Foundation Task Ledger (FTL)

Version: 3.0 Last Updated: 2025-12-27

Purpose

The Foundation Task Ledger (FTL) is the canonical intake and tracking system for all foundation work:

Ideas — Captured concepts, not yet evaluated
Proposals — Formally proposed changes or additions
Tasks — Approved work items
Decisions — Outcomes (accepted, rejected, deferred)

This ledger ensures:

No idea is lost or implicit
Progress is reviewable
Scope is explicit
Conversations are not the source of truth

Entry Lifecycle

Idea → Proposed → Under Review → Accepted/Rejected/Deferred → Complete

Status	Meaning
Idea	Captured, not yet evaluated
Proposed	Formally proposed, awaiting review
Under Review	Active evaluation in progress
Accepted	Approved for implementation
Rejected	Decision: will not implement (with rationale)
Deferred	Decision: not now, revisit later
In Progress	Actively being worked
Blocked	Awaiting decision or dependency
Complete	Acceptance criteria satisfied or decision documented

Entry Template

New entries should follow this structure:

### FTL-XXX: [Title]

- **Status:** [Idea/Proposed/Under Review/Accepted/Rejected/Deferred/In Progress/Complete]
- **Category:** [Task/Proposal/Decision/Amendment]
- **Priority:** [P1/P2/P3 or None]
- **Created:** [Date]
- **Completed:** [Date or N/A]

**Problem/Context:**
[What issue or opportunity does this address?]

**Proposal/Solution:**
[What is being proposed or decided?]

**Rationale:**
[Why this approach?]

**Acceptance Criteria:** (if applicable)
- [ ] Criterion 1
- [ ] Criterion 2

**Artifact:** [Link to resulting document, or N/A]

**Decision:** (if status is Rejected/Deferred/Complete)
[Final decision and reasoning]

Entry Workflow

Capture — Add entry with status: Idea
Evaluate — Human reviews, updates to Proposed or Rejected
Review — Discussion/analysis, status: Under Review
Decide — Human decides: Accepted, Rejected, or Deferred
Implement — If Accepted, create iteration and work
Close — Update status to Complete with artifact link or decision rationale

Key Constraint: Only human authority can transition entries past Idea status.

Open Entries

FTL-014: Trivial Work Exemption

Status: Complete (Accepted)
Accepted: 2025-12-26
Category: Amendment
Priority: P2
Created: 2025-12-26

Problem/Context: Binary choice exists between full iteration ceremony and deviation violation. Minor changes (sitemap, config tweaks) trigger same overhead as major spec work. This has caused 2 logged deviations on 2025-12-26.

Proposal/Solution: Define “trivial work” category exempt from iteration ceremony.

Exemption Criteria (ALL must be true):

Human explicitly approves exemption BEFORE work begins
No new content pages (specs, docs)
No spec changes
Configuration/tooling only
< 5 files modified

Tracking:

Log to maintenance.log (not deviations.log)
Format: [DATE] APPROVED-TRIVIAL | description | human approval note

Key Constraint: Human must say “approved trivial” or equivalent BEFORE work. Agent cannot self-classify as trivial.

Rationale: Reduces friction for legitimate minor work while preserving iteration discipline for substantive changes. Human approval gate prevents abuse.

Acceptance Criteria:

Criteria documented in workflow_contract.md
maintenance.log format defined
DIDP updated (or amendment documented)

Artifact: Workflow Contract v3.1 Section 13.5

Decision: Accepted by human authority on 2025-12-26. Trivial work exemption is now active.

Research Track (Deferred)

FTL-032: WSP v0.1 Formal Protocol Specification

Status: Deferred
Category: Research/PhD
Created: 2025-12-27 (migrated from tasks.md)

Context: Wormhole Skill Protocol formal specification for cross-network AI skill exchange.

Rationale: Research-track item, not immediate foundation work.

FTL-033: WSP Threat Model (Byzantine Adversaries)

Status: Deferred
Category: Research/PhD
Created: 2025-12-27 (migrated from tasks.md)

Context: Security analysis for WSP against Byzantine adversaries.

FTL-034: WAP Protocol Specification

Status: Deferred
Category: Research/PhD
Created: 2025-12-27 (migrated from tasks.md)

Context: Wormhole AI Protocol formal specification.

FTL-035: Skill Semantic Descriptor (SSD) Schema

Status: Deferred
Category: Research/PhD
Created: 2025-12-27 (migrated from tasks.md)

Context: Machine-readable skill description format (input domain, output invariants, failure modes, resource envelope).

FTL-036: Competence Attack Threat Model

Status: Deferred
Category: Research/PhD
Created: 2025-12-27 (migrated from tasks.md)

Context: Byzantine competence adversary model — novel research contribution.

FTL-037: Jellylabs Research Canon Framework (JLP-XXX)

Status: Deferred
Category: Research/PhD
Created: 2025-12-27 (migrated from tasks.md)

Context: Publication series framework: JLP-001 (WSP), JLP-002 (SSD), JLP-003 (Competence Attestation), JLP-004 (Economics).

FTL-047: DIDP Knowledge System

Status: Complete
Category: Task
Priority: P2
Created: 2025-12-27
Completed: 2025-12-28

Problem/Context: The DIDP skill currently lives in ~/.claude/skills/didp/ (global) but needs to be project-level for:

Portability (future jellyfish package)
Version control with project
No global dependency

Additionally, detecting spec changes requires manual checking. Need automated hash-based change detection.

Proposal/Solution: Build project-level knowledge system at .jellylabs.ai/didp/knowledge/:

hash-site.ts - Generate SHA-256 manifest of all src/content/**/*.md on build
index-specs.ts - Extract normative rules (MUST/SHOULD/MAY) from specs
doctor.ts - Analyze CLAUDE.md for anti-patterns, with agent handoff for deep evaluation
Versioned history - Keep snapshots in knowledge/history/ with cleanup agent hook

Rationale:

Hash manifest enables quick change detection (compare siteHash)
Static rule extraction keeps scripts simple, agent handles quality eval
Project-level means no global config changes without human approval
Prepares for jellyfish package extraction

Acceptance Criteria:

.jellylabs.ai/didp/scripts/ contains hash-site.ts, index-specs.ts, doctor.ts
.jellylabs.ai/didp/knowledge/ contains index.json, rules.json
package.json has postbuild hook for hash-site.ts
/didp-eval command created for agent evaluation handoff
Global CLAUDE.md changes require human approval (no auto-modify)
Documentation added to methodology.md

Artifact: Methodology Guide - Knowledge System

Backlog (Ideas)

FTL-038: Formal Approval Workflow Documentation

Status: Complete
Category: Quality Management
Created: 2025-12-27 (migrated from tasks.md)
Completed: 2025-12-28

Context: Define review/approval processes for documentation tiers. Assign roles: author, technical reviewer, governance reviewer, approver.

Solution: Created comprehensive approval workflow guide at /docs/guides/approval-workflow covering:

Role definitions (Author, Technical Reviewer, Governance Reviewer, Approver)
Tier-based workflows with timelines
Review checklists for technical and governance reviews
Approval record format
Dispute resolution process
Review metrics

Artifact: site/src/content/docs/guides/approval-workflow.md

FTL-039: Cross-Reference Validation Automation

Status: Complete
Category: Quality Management
Created: 2025-12-27 (migrated from tasks.md)
Completed: 2025-12-28

Context: Script to validate internal markdown links, check protocol version references, verify hierarchy consistency, detect orphaned documents.

Solution: Created .jellylabs.ai/didp/scripts/check-links.ts - validates internal markdown links, reports broken links, optional orphan detection with --orphans flag.

Initial Run Results: Found 33 broken links mostly due to URL path vs. file path differences (/specs/ URLs vs specs/ content directory). These are not true broken links - Astro routes them correctly at runtime.

Artifact: .jellylabs.ai/didp/scripts/check-links.ts

FTL-040: Periodic Review Schedule

Status: Complete
Category: Quality Management
Created: 2025-12-27 (migrated from tasks.md)
Completed: 2025-12-28

Context: Tier 1 specs: Annual review. Tier 2 governance: Semi-annual. Tier 3 docs: Quarterly.

Solution: Created review schedule guide at /docs/guides/review-schedule covering:

Review cadence by tier (Annual/Semi-annual/Quarterly)
Review checklists for each tier
Calendar for 2025-2026
Non-scheduled review triggers
Frontmatter tracking fields
Automation support

Artifact: site/src/content/docs/guides/review-schedule.md

FTL-041: Documentation Quality Metrics Dashboard

Status: Complete
Category: Quality Management
Created: 2025-12-27 (migrated from tasks.md)
Completed: 2025-12-28

Context: KPI tracking for cross-reference validation, PSP conformance, PPP URL compliance, living doc timestamps.

Solution: Created quality metrics reference page at /docs/reference/quality-metrics covering:

Documentation health (links, freshness, completeness)
Process health (FTL status, iteration metrics, review compliance)
Automation coverage (hooks, scripts)
Quality gates and quick commands

Artifact: site/src/content/docs/reference/quality-metrics.md

FTL-042: Post-Implementation Verification Process

Status: Idea
Category: Quality Management
Created: 2025-12-27 (migrated from tasks.md)

Context: Add Section 9 to PSP proposal template for verification criteria checklist.

FTL-043: JellyFish JSON Schemas

Status: Complete
Category: Schemas
Created: 2025-12-27 (migrated from tasks.md)
Completed: 2025-12-28

Context: Create tentacle.schema.json, gnosis.schema.json, lock.schema.json for programmatic validation.

Artifacts:

https://jellylabs.ai/schemas/tentacle.schema.json
https://jellylabs.ai/schemas/gnosis.schema.json
https://jellylabs.ai/schemas/lock.schema.json
Updated /docs/reference/json-schemas with published status

FTL-044: Publish iteration_state.schema.json

Status: Complete
Category: Schemas
Created: 2025-12-27 (migrated from tasks.md)
Completed: 2025-12-28

Context: Publish schema and bootstrap prompts for external DIDP adoption.

Artifacts:

Schema: https://jellylabs.ai/schemas/iteration_state.schema.json
Bootstrap prompt: https://jellylabs.ai/prompts/didp-bootstrap.txt
Minimal prompt: https://jellylabs.ai/prompts/didp-bootstrap-minimal.txt

FTL-045: v2 Roadmap Documentation

Status: Complete
Category: Documentation
Created: 2025-12-27 (migrated from tasks.md)
Completed: 2025-12-28

Context: Document evolution path for DIDP v2, PPP v2, PSP v2.

Solution: Updated /docs/roadmap with Future Versions section covering DIDP v4, PSP v2, and PPP v2 planned features.

Artifact: site/src/content/docs/roadmap.md

FTL-046: 7-Phase Publication Framework Document

Status: Complete
Category: Documentation
Created: 2025-12-27 (migrated from tasks.md)
Completed: 2025-12-28

Context: Freeze, Declare Intent, License, Publish, Name, Invite Scrutiny, Separate Spec.

Solution: Created comprehensive publication framework guide at /docs/guides/publication-framework covering all 7 phases with detailed checklists and examples.

Artifact: site/src/content/docs/guides/publication-framework.md

FTL-048: SQLite Knowledge Cache

Status: Complete
Category: Task
Created: 2025-12-27
Completed: 2025-12-28

Context: Add SQLite cache.db for fast rule queries when rule count exceeds threshold (~500+ rules). Currently using JSON which is sufficient for current scale, but may need optimization for larger rule sets.

Solution: Created cache-rules.ts script that:

Builds SQLite database from rules.json
Creates indexes for type, category, source queries
Implements FTS5 full-text search on statements
Provides CLI interface for queries (--query, --type, --category, --stats)
Auto-refreshes cache when source hash changes

Artifact: .jellylabs.ai/didp/scripts/cache-rules.ts, .jellylabs.ai/didp/knowledge/cache.db

FTL-049: Knowledge History Cleanup Agent

Status: Complete
Category: Task
Created: 2025-12-27
Completed: 2025-12-28

Context: Hook cleanup agent when .jellylabs.ai/didp/knowledge/history/ directory exceeds size threshold (e.g., 50 snapshots or 10MB). Would prune oldest snapshots while preserving milestones.

Solution: Created cleanup-history.ts script that:

Prunes old snapshots when count exceeds threshold (default 50)
Respects size threshold (default 10MB)
Always preserves last 10 snapshots
Always preserves milestone snapshots (where siteHash changed)
Supports --dry-run for safe testing
Configurable via --max-count and --max-size flags

Artifact: .jellylabs.ai/didp/scripts/cleanup-history.ts

FTL-050: DIDP Knowledge System Public Release

Status: Idea
Category: Task
Created: 2025-12-28

Context: Package the DIDP knowledge system (hash-site.ts, index-specs.ts, doctor.ts) as public tooling for external DIDP adopters.

Scope:

Extract scripts to standalone npm/bun package (@jellylabs/didp-tools or similar)
Make content directory configurable (not hardcoded to src/content/)
Add CLI interface (didp hash, didp index, didp doctor)
Add init command to scaffold knowledge directory structure
Document installation and usage for external projects
Consider integration with jellyfish package (FTL-043 dependency)

Prerequisite: FTL-047 (Complete), real-world validation in jellylabs.ai project

FTL-051: Skill Dependency Checker

Status: Complete
Category: Tooling
Created: 2025-12-27
Completed: 2025-12-28

Context: Skills like d2-diagrams require external binaries (e.g., d2). Upon jellyfish/tentacle install, the system should check for required dependencies and prompt user to install missing ones.

Solution: Created check-skill-deps.ts script that:

Scans SKILL.md files for bash code blocks containing commands
Parses tentacle.yaml for explicit dependencies field
Checks 70+ known binaries with install hints (brew, npm, curl commands)
Searches common non-PATH locations (~/.bun/bin, ~/.cargo/bin, /opt/homebrew/bin)
Reports missing dependencies with install instructions
Supports --skill filter and --path override

Artifact: .jellylabs.ai/didp/scripts/check-skill-deps.ts

FTL-052: Doctor.ts Documentation Verification Flag

Status: Complete
Category: Tooling
Created: 2025-12-28
Completed: 2025-12-28

Context: Extend doctor.ts with --docs flag to verify documentation compliance per workflow_contract.md Section 14.

Scope:

Add --docs flag to .jellylabs.ai/didp/scripts/doctor.ts
Check that methodology.md covers new public features
Check that FTL status matches iteration state
Check that CLAUDE.md (local) reflects new commands/capabilities
Report missing documentation as errors (blocking) or warnings

Prerequisite: FTL-047 (Complete), Section 14 in workflow_contract.md

Artifact: .jellylabs.ai/didp/scripts/doctor.ts (v1.1.0)

FTL-054: Deferred Decisions Tracking

Status: Complete
Category: Amendment
Created: 2025-12-28
Completed: 2025-12-28

Problem/Context: Decisions and discussions that don’t immediately result in action get lost between sessions. Example: “project cleanup” was discussed with nerds but never implemented or tracked.

Solution (Simplified): Instead of new schema, use existing FTL system:

Agent MUST create FTL Idea immediately when discussion produces actionable insight
Agent provides feedback: “Idea triggered…” → “Saved as FTL-XXX”
Session startup surfaces recent FTL Ideas

Scope (Implemented):

Section 15: Agent Transparency (global feedback rule for all hooks)
Section 16: Deferred Decision Capture (FTL Idea creation)

Rationale: Prevents valuable decisions from being lost to context compaction. Ensures continuity across sessions.

Artifact: Workflow Contract Sections 15-16

FTL-056: Session Transcript Archiving

Status: Complete
Category: Task
Created: 2025-12-28
Completed: 2025-12-28

Context: Claude Code stores full session transcripts as JSONL in ~/.claude/projects/{project}/. Could archive these with completed iterations for full history.

Discovery:

Path: ~/.claude/projects/-Users-dust--local-dev-jellylabs/*.jsonl
Format: JSONL with user/assistant messages, tool calls, timestamps
Agent sessions: agent-*.jsonl

Solution: Created archive-session.ts script that:

Lists all sessions with message counts and sizes (--list)
Archives sessions to .jellylabs.ai/didp/archive/sessions/{iteration_id}/
Creates manifest.json linking session files to iteration
Supports export for specific iterations (--export ITER-ID)

Artifact: .jellylabs.ai/didp/scripts/archive-session.ts, .jellylabs.ai/didp/archive/sessions/

FTL-055: Project Structure Cleanup

Status: Complete
Category: Task
Priority: P2
Created: 2025-12-28
Completed: 2025-12-28

Context: Discussed with nerds but never implemented. Root directory has clutter, archive organization is inconsistent, handoffs are scattered.

Changes Made:

Removed: @_shared, build.ninja, Makefile, deploy.sh, DONT_TOUCH.md, DEPLOY.md
Moved: plans/ → .claude/plans/, prompts/ → .jellylabs.ai/didp/prompts/
Consolidated: docs/ → src/content/docs/ and archive/docs/
Merged: _shared/ → assets/
Archived: 10 handoffs from Dec 24-26 to .claude/archive/handoffs/
Captured: 8 FTL Ideas from DONT_TOUCH.md (FTL-058 to FTL-065)
Documented: Standard project layout in .claude/CLAUDE.md

Acceptance Criteria:

No loose files at root except standard project files
Single canonical location for each file type
DONT_TOUCH.md ideas captured as FTL entries
Project structure documented

Artifact: .claude/CLAUDE.md (Repository Structure section)

FTL-057: Site Search via Pagefind

Status: Complete
Category: Task
Created: 2025-12-28
Completed: 2025-12-28

Context: Discussed adding search to jellylabs.ai but never implemented. Pagefind is the recommended Astro plugin for static site search.

Scope:

Install pagefind directly
Add search component to site header/nav
Index specs and docs content
Configure search UI styling (dark theme)

Implementation:

Added pagefind dependency to site/package.json
Created Search.astro component with dark theme styling
Integrated into HomeLayout, DocLayout, SpecLayout
Added to standalone docs/index.astro page
Pagefind runs as postbuild step, indexes 56 pages / 3161 words

Reference: https://pagefind.app/ (Astro integration)

Artifact: site/src/components/Search.astro, iteration ITER-2025-12-28-G

FTL-058: Agent Sandbox Enforcement

Status: Complete
Category: Security
Created: 2025-12-28
Completed: 2025-12-28

Context: Captured from DONT_TOUCH.md during FTL-055 cleanup.

Requirements:

Prevent agents from leaving project root by default
Automatic hooks that prevent leaving project pwd, git repo
Prevent visiting known bad websites (registered where?)

Implementation:

Hook script: ~/.claude/hooks/project-sandbox.fish
Registered in: ~/.claude/settings.json for Bash, Read, Write, Edit, Glob, Grep tools
Project root detection: Uses git root or pwd
Allowed escapes: ~/.claude, /tmp, /var/folders, ~/.local/share, /usr/bin, /usr/local/bin, /opt/homebrew
Blocked sensitive paths: /etc/passwd, /etc/shadow, ~/.ssh/id_*, ~/.gnupg, ~/.aws/credentials, ~/.config/gh/hosts.yml
Violations logged to: ~/.claude/state/violations.log

Note: Website blocking deferred - would require URL interception which is beyond current hook scope.

Artifact: ~/.claude/hooks/project-sandbox.fish

FTL-059: Pre-Discussion Context Loading

Status: Complete
Category: Workflow
Created: 2025-12-28
Completed: 2025-12-28

Context: Captured from DONT_TOUCH.md during FTL-055 cleanup.

Requirement: Enforce agent reads docs/decisions/roadmap/specs before discussing topics.

Solution: Created context-loading.ts user-prompt-submit hook that:

Scans user prompt for topic keywords (didp, psp, ppp, roadmap, ftl, etc.)
Suggests relevant context files for the agent to read
Provides <context-reminder> tags with file paths

Artifact: ~/.claude/hooks/context-loading.ts

FTL-060: Documentation Single Source of Truth

Status: Complete
Category: Documentation
Created: 2025-12-28
Completed: 2025-12-28

Context: Captured from DONT_TOUCH.md during FTL-055 cleanup.

Problem: “documentation is a huge issue, files everywhere hard to enforce single source of truth”

Note: Partially addressed by FTL-055 (project cleanup) and FTL-047 (knowledge system).

Solution: Created SSOT guide at /docs/guides/documentation-ssot covering:

Canonical location matrix for all document types
SSOT rules (one location, edit at source, no duplication, reference don’t copy, archive don’t delete)
Detection and prevention strategies
Migration guide for fixing fragmentation
Authority hierarchy reference
Maintenance checklists

Artifact: site/src/content/docs/guides/documentation-ssot.md

FTL-061: Automatic Violation Trigger and Review

Status: Complete
Category: Compliance
Created: 2025-12-28
Completed: 2025-12-28

Context: Captured from DONT_TOUCH.md during FTL-055 cleanup.

Requirement: Automatic violation detection with review workflow.

Implementation:

Violations logged to: ~/.claude/state/violations.log
Log format: [timestamp] TYPE: description (context)
Types: BLOCKED rm/delete, BLOCKED sandbox escape, BLOCKED sensitive path
Review command: /violations - displays formatted log with summary
Summary script: ~/.claude/scripts/violation-summary.fish - session-end statistics
Archive support: /violations clear archives and resets log

Artifacts:

~/.claude/commands/violations.md
~/.claude/scripts/violation-summary.fish
~/.claude/hooks/violation-alert.fish

FTL-062: Phase Progress Visualization

Status: Complete
Category: UX
Created: 2025-12-28
Completed: 2025-12-28

Context: Captured from DONT_TOUCH.md during FTL-055 cleanup.

Requirement: At the end of each phase, show iteration progress (stage graph), suggest next steps.

Solution: Created show-progress.ts script that renders visual phase progress with:

Box-drawing progress bar showing all phases
Current phase highlighted with Unicode blocks
Scope, blockers, and next steps from iteration state
JSON output mode for programmatic use (--json flag)

Artifact: .jellylabs.ai/didp/scripts/show-progress.ts

FTL-063: Git-Push Deploy Strategy

Status: Complete
Category: DevOps
Created: 2025-12-28
Completed: 2025-12-28

Context: Captured from DONT_TOUCH.md during FTL-055 cleanup.

Requirement: Configure Cloudflare to use git push to deploy strategy (currently manual wrangler deploy).

Solution: Created .github/workflows/deploy.yml - GitHub Actions workflow that triggers on push to master, builds the site, and deploys to Cloudflare Pages using wrangler-action.

Note: Requires CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID secrets in GitHub repo settings.

Artifact: .github/workflows/deploy.yml

FTL-064: Enforce Changelog Writes

Status: Complete
Category: Compliance
Created: 2025-12-28
Completed: 2025-12-28

Context: Captured from DONT_TOUCH.md during FTL-055 cleanup.

Requirement: Enforce changelog writes as part of phase exit criteria.

Solution: Created Stop hook that checks for content changes without corresponding changelog entry.

Artifact: ~/.claude/hooks/enforce-changelog.ts

FTL-065: Enforce Handoff Creation

Status: Complete
Category: Compliance
Created: 2025-12-28
Completed: 2025-12-28

Context: Captured from DONT_TOUCH.md during FTL-055 cleanup.

Requirement: Enforce handoff creation at session end.

Solution: Created Stop hook that detects significant work sessions (>5 files modified, DIDP active) and reminds to create handoff document.

Artifact: ~/.claude/hooks/enforce-handoff.ts

FTL-066: Destructive Command Prevention Hook

Status: Complete
Category: Security
Created: 2025-12-28
Completed: 2025-12-28

Context: Agent used rm to delete files during FTL-055 cleanup instead of archiving. Need a hook that blocks destructive commands.

Scope:

Create Claude Code hook that intercepts bash commands
Block rm, dd, and other destructive commands
Suggest archive alternative: mv <file> archive/
Allow override with explicit confirmation if absolutely necessary

Implementation:

Hook script: ~/.claude/hooks/no-destructive-commands.fish
Registered in: ~/.claude/settings.json under hooks.PreToolUse
Matcher: Bash (intercepts all bash tool invocations)
Blocked patterns: rm, dd, shred, unlink
Exit code 2 blocks execution, displays guidance message
Violations logged to: ~/.claude/state/violations.log

Artifact: ~/.claude/hooks/no-destructive-commands.fish

FTL-053: Rich D2 Graphics for JellyLabs Site

Status: Complete
Category: Documentation
Created: 2025-12-27
Completed: 2025-12-28

Context: The jellylabs.ai website would benefit from rich visual diagrams throughout. Use the d2-diagrams skill to create consistent, dark-themed graphics that explain protocols and concepts.

Scope:

FTL entry lifecycle diagram
DIDP phase model (planning → complete flow)
Protocol hierarchy (PSP → DIDP → PPP authority chain)
JAS architecture (jellyfish anatomy diagram)
Site architecture (Astro + content collections + Cloudflare)
Tentacle package structure
Governance flow (proposal → acceptance → publication)

Artifacts (all in site/public/diagrams/):

ftl-lifecycle.d2 + .svg
didp-phases.d2 + .svg
protocol-hierarchy.d2 + .svg
jas-architecture.d2 + .svg
site-architecture.d2 + .svg
tentacle-structure.d2 + .svg
governance-flow.d2 + .svg
Embed in relevant spec/doc pages

Completed Entries

Foundation Phase (2025-12-24)

FTL-001 through FTL-013 (all Complete)

FTL-001: Formalize human authority fallback

Status: Complete
Completed: 2025-12-24
Artifact: Human Authority and Judgment
Acceptance basis: All criteria satisfied; non-normative positioning preserved

FTL-002: Document accepted failure modes

Status: Complete
Completed: 2025-12-24
Artifact: Accepted Failure Modes
Acceptance basis: Failure modes listed; no false promises; placed in docs

FTL-003: Define sunset / exit principles

Status: Complete
Completed: 2025-12-24
Artifact: Sunset and Exit Principles
Acceptance basis: Explicit principle documented; deprecated/frozen/retired distinguished

FTL-004: Add reader responsibility contract

Status: Complete
Completed: 2025-12-24
Artifact: Reader Responsibility
Acceptance basis: Clear contract; avoids legal overreach

FTL-005: Create system overview diagram

Status: Complete
Completed: 2025-12-24
Artifact: System Overview
Acceptance basis: Single diagram; simple and readable; authority flow clear

FTL-006: Finalize PSP v1 acceptance

Status: Complete
Completed: 2025-12-24
Artifact: PSP v1 (status: Accepted)
Acceptance basis: PSP exercised repeatedly and correctly across proposal creation, acceptance logic, task gating, and governance closure.

FTL-007: Create proposal index page

Status: Complete
Completed: 2025-12-24
Artifact: Proposal Index
Acceptance basis: Index created; PSP-001 listed; status shown

FTL-008: Add Living Documentation notice

Status: Complete
Completed: 2025-12-24
Artifact: Notices added to index pages
Acceptance basis: Notices reference PSP-001; non-promotional language

FTL-009: Establish docs changelog discipline

Status: Complete
Completed: 2025-12-24
Artifact: Changelog
Acceptance basis: Changelog exists; format defined; first entries added

FTL-010: Evaluate and formalize Conductor Pattern

Status: Complete (Decision: Do Not Formalize)
Completed: 2025-12-24
Decision: Not elevated to protocol; permitted as execution pattern under human authority
Rationale: Formalizing execution patterns prematurely risks over-constraining work.

FTL-011: Define AI-assisted planning and ideation boundaries

Status: Complete (Covered by Existing Artifacts)
Completed: 2025-12-24
Decision: No standalone document required
Coverage: Human Authority Fallback, Accepted Failure Modes, Reader Contract, AMC

FTL-012: Define safety boundaries and failure containment

Status: Complete
Completed: 2025-12-24
Artifact: AMC, Patterns and Risks

FTL-013: Evaluate need and scope for security threat analysis

Status: Complete (Deferred by Design)
Completed: 2025-12-24
Decision: No immediate security spec required; revisit only if threat model changes
Related: PSP-002 remains on radar

tasks.md Migration (2025-12-27)

FTL-015 through FTL-031 (migrated from tasks.md)

FTL-015: PSP v1

Status: Complete
Completed: 2025-12-24
Artifact: PSP v1
Note: Migrated from tasks.md; already tracked as FTL-006 acceptance

FTL-016: Foundation Charter v1

Status: Complete
Completed: 2025-12-24
Artifact: Foundation Charter

FTL-017: Authoritative Material Classification

Status: Complete
Completed: 2025-12-24
Artifact: AMC
Note: Related to FTL-012

FTL-018: Patterns & Risk Prioritization

Status: Complete
Completed: 2025-12-24
Artifact: Patterns and Risks
Note: Related to FTL-012

FTL-019: Human Authority Fallback

Status: Complete
Completed: 2025-12-24
Artifact: Human Authority
Note: Same as FTL-001

FTL-020: Accepted Failure Modes

Status: Complete
Completed: 2025-12-24
Artifact: Accepted Failures
Note: Same as FTL-002

FTL-021: Sunset & Exit Principles

Status: Complete
Completed: 2025-12-24
Artifact: Sunset Principles
Note: Same as FTL-003

FTL-022: Reader Responsibility Contract

Status: Complete
Completed: 2025-12-24
Artifact: Reader Contract
Note: Same as FTL-004

FTL-023: Naming & Attribution Convention

Status: Complete
Completed: 2025-12-25
Artifact: Naming and Attribution

FTL-024: System Overview Diagram

Status: Complete
Completed: 2025-12-24
Artifact: System Overview
Note: Same as FTL-005

FTL-025: INTENT.md

Status: Complete
Completed: 2025-12-25
Artifact: Intent

FTL-026: Institutional Independence

Status: Complete
Completed: 2025-12-25
Artifact: Institutional Independence

FTL-027: JAS v0.1.0

Status: Complete
Completed: 2025-12-26
Artifact: JAS v0.1

FTL-028: Tentacle Spec v4

Status: Complete
Completed: 2025-12-26
Artifact: Tentacle v4

FTL-029: Distillation Pipeline / Methodology

Status: Complete
Completed: 2025-12-25
Artifact: Methodology

FTL-030: JELLY-TENTACLE v5.0.0

Status: Complete (Rejected)
Completed: 2025-12-26
Decision: JAS extracted instead; v5 direction not taken. The jellyfish biological metaphor was foundational ontology, not decoration — led to architectural split.
Artifact: Tentacle v5 Direction

FTL-031: Foundation Asset Registry (FAR)

Status: Complete (Rejected)
Completed: 2025-12-26
Decision: Redundant. File system + frontmatter + git already serves the purpose. Maintenance burden not justified.
Artifact: FAR Closure

Changelog

Date	Entry	Change
2025-12-27	FTL	v3.0: Migrated tasks.md to FTL, removed legacy backlog
2025-12-27	FTL-015–031	Migrated completed/rejected items from tasks.md
2025-12-27	FTL-032–046	Migrated open items (deferred + ideas) from tasks.md
2025-12-26	FTL	v2.0: Added lifecycle states, entry template, workflow, reopened ledger
2025-12-26	FTL-014	Created: Trivial Work Exemption proposal
2025-12-26	FTL-014	Accepted by human authority
2025-12-24	FTL-001–013	All completed, ledger closed (v1.0)

Task Completion Checklist

Before closing any FTL item:

Acceptance criteria fully satisfied (or decision documented)
Resulting artifact exists in repo (or N/A with rationale)
No TODO markers remain in published text
Cross-links added (if applicable)
Changelog entry added
Ledger status updated to Complete

Proposal → Task → Artifact Mapping

Idea (FTL)
     ↓ human approval
Proposal (FTL or PSP)
     ↓ authorizes
Tasks (FTL / Iteration)
     ↓ produce
Artifacts (Docs / Specs)

Future work enters via this ledger. Use the entry template above.

FTL-067: Enforce CLAUDE.md and README.md Updates at Iteration End

Status: Complete
Category: Compliance
Created: 2025-12-28
Completed: 2025-12-28

Context: Documentation often falls out of sync with code. CLAUDE.md and README.md should be reviewed and updated as part of iteration completion.

Requirement: Add exit criteria check that CLAUDE.md and README.md are updated if iteration changes affect documented structure, workflows, or capabilities.

Solution: Created Stop hook that detects new commands, hooks, skills, or directory structure changes and recommends documentation updates if CLAUDE.md/README.md weren’t modified.

Artifact: ~/.claude/hooks/enforce-docs-update.ts

FTL-068: Reconcile Gnosis System with DIDP

Status: Deferred
Category: Architecture
Created: 2025-12-28

Context: The Gnosis system (persistent memory across sessions) conflicts with DIDP’s source of truth hierarchy where iteration_state.yaml is the highest authority. Currently removed from CLAUDE.md (GLOBAL) pending resolution.

Problem: Gnosis creates a parallel source of truth that may contradict DIDP state. Need to either integrate Gnosis under DIDP authority or deprecate it entirely.

Options:

Deprecate Gnosis - rely solely on DIDP iteration state
Make Gnosis subordinate to DIDP - only for non-iteration knowledge
Merge concepts - Gnosis becomes part of iteration state schema

Deferred Reason: Requires architectural decision from human authority. This affects the fundamental knowledge management strategy.

FTL-069: Sentinel System for Crash Recovery

Status: Complete
Category: Infrastructure
Created: 2025-12-28
Completed: 2025-12-28

Context: Sentinel files track active plan execution for crash recovery. Currently removed from CLAUDE.md (GLOBAL) pending review of integration with DIDP crash recovery mechanisms.

Concept: Create sentinel file when plan starts, delete on clean completion. Orphaned sentinels indicate crashed sessions that need recovery.

Solution: Created plan-sentinel.ts script that:

Creates sentinel with PID, plan path, project path, iteration ID
Detects orphaned sentinels (PID no longer alive)
Provides CLI commands: create, delete, check, list, heartbeat
Stores sentinels in ~/.claude/state/sessions/
Returns exit code 1 when orphans detected (for hook integration)

Artifact: ~/.claude/hooks/plan-sentinel.ts

FTL-070: Split Specs and Docs at Maturity

Status: Idea
Category: Architecture
Created: 2025-12-28

Context: Architectural debt from foundation phase. Currently single site with dual routes (/specs/* and /docs/*). At maturity, should split into separate repositories.

Trigger Conditions:

Multiple external contributors to documentation
Documentation update velocity exceeds spec updates 10:1
Need for separate governance/approval workflows
Community confusion about normative vs explanatory content

Action When Triggered:

Create jellylabs-ai/docs repo
Migrate /docs/* content
Configure docs.jellylabs.ai subdomain
Keep specs.jellylabs.ai for normative content only

Reference: Originally documented in TODO.md (now archived)

FTL-071: Decision Documentation Architecture

Status: Complete
Category: Architecture
Priority: P2
Created: 2025-12-28
Completed: 2025-12-28

Problem/Context: Three places for decisions: decision-log.md, decisions/*.md, FTL entries. No single source of truth.

Resolution:

Migrated DL-001 to DL-008 into FTL (FTL-072 to FTL-079)
Archived decision-log.md → archive/docs/
Archived decisions/ → archive/docs/decisions/
FTL is now the single source of truth for decisions

Architectural Decisions (Migrated from decision-log.md)

FTL-072: Single Site with Dual Routes (DL-001)

Status: Complete (Decision)
Category: Architecture
Created: 2025-12-23
Completed: 2025-12-23

Decision: Implement specs and docs as dual routes (/specs/* and /docs/*) within a single Astro site, with mandatory split at maturity.

Options Considered:

Option A: Single site, dual routes (lower overhead, faster iteration)
Option B: Separate sites immediately (clean separation, more friction)

Rationale: Option A chosen — early-stage velocity matters more than architectural purity. Can migrate to Option B when triggers occur.

Consequences: Architectural debt accepted with explicit payoff timeline. See FTL-070 for split triggers.

FTL-073: Astro for Static Site Generation (DL-002)

Status: Complete (Decision)
Category: Architecture
Created: 2025-12-21
Completed: 2025-12-21

Decision: Use Astro as the static site generator for JellyLabs.ai.

Rationale: Content-focused, excellent markdown support, component islands, works with Bun.

FTL-074: Bun as Package Manager and Runtime (DL-003)

Status: Complete (Decision)
Category: Architecture
Created: 2025-12-21
Completed: 2025-12-21

Decision: Use Bun instead of npm/yarn/pnpm.

Rationale: Faster install/execution, built-in TypeScript, aligns with modern tooling.

FTL-075: Major Version in URL Path (DL-004)

Status: Complete (Decision)
Category: Architecture
Created: 2025-12-21
Completed: 2025-12-21

Decision: Include major version in URL path: /specs/<name>/v<major>

Rationale: Path-based versions are most cacheable, clear indication of version in URL, follows common API patterns.

FTL-076: Immutable Published Specifications (DL-005)

Status: Complete (Decision)
Category: Architecture
Created: 2025-12-21
Completed: 2025-12-21

Decision: Once a specification version is published, its content MUST NOT change (except errata).

Rationale: Enables reliable citations, prevents silent breaking changes, matches RFC/W3C practices.

FTL-077: YAML for Iteration State (DL-006)

Status: Complete (Decision)
Category: Architecture
Created: 2025-12-21
Completed: 2025-12-21

Decision: Use YAML for iteration_state.yaml instead of JSON or TOML.

Rationale: Supports comments (important for handoff notes), more human-readable, well-supported.

FTL-078: Phase-Based Development Model (DL-007)

Status: Complete (Decision)
Category: Architecture
Created: 2025-12-21
Completed: 2025-12-21

Decision: Implement strict phase-based development with defined transitions.

Rationale: Phases create checkpoints for session recovery, explicit transitions prevent scope creep, artifacts override conversational memory.

FTL-079: PSP Scope Evolution (DL-008)

Status: Complete (Decision)
Category: Architecture
Created: 2025-12-24
Completed: 2025-12-24

Decision: PSP v1 evolved from “Protocol Specification Protocol” to “Proposal Specification Protocol”, with protocol structure specification moved to PPP-BOOTSTRAP v1 prompt.

Rationale: Governance and structure are distinct concerns. PSP focuses on proposal governance, PPP-BOOTSTRAP defines protocol structure template.

Consequences: Naming clarified, gap filled with PPP-BOOTSTRAP prompt, grandfathering for existing protocols.

FTL-080: Rename GitHub Repo from specs to jellylabs

Status: Deferred
Category: Infrastructure
Created: 2025-12-28

Context: Local directory is jellylabs but GitHub repo is jellylabs-ai/specs. Should align to jellylabs-ai/jellylabs for consistency.

Scope:

Rename GitHub repo from specs to jellylabs
Update git remote in local clone
Update CLAUDE.md (LOCAL) repository URL reference
Update any CI/CD or Cloudflare Pages connections

Deferred Reason: Requires human oversight for GitHub operations. GitHub provides automatic redirects from old to new repo name, but Cloudflare Pages and any external references need manual update.

Checklist for when this is actioned:

Rename repo on GitHub: Settings → Rename
Update local remote: git remote set-url origin [email protected]:jellylabs-ai/jellylabs.git
Update .claude/CLAUDE.md repository URL
Update Cloudflare Pages project (if git-connected)
Update .github/workflows/deploy.yml if needed
Test git push/pull after rename

FTL-081: Security Review - ~/.claude in ALLOWED_ESCAPES

Status: Complete
Category: Security
Priority: P2
Created: 2025-12-28
Completed: 2025-12-28

Context: The project sandbox hook (~/.claude/hooks/project-sandbox.ts) includes ~/.claude in ALLOWED_ESCAPES, allowing agents to write to this directory without triggering a violation.

Security Concern: An agent can modify:

~/.claude/hooks/ - Add/modify hooks that run on every tool use
~/.claude/settings.json - Change permissions, disable hooks
~/.claude/skills/ - Modify skill behavior
~/.claude/commands/ - Alter slash command definitions

This could allow an agent to disable its own guardrails or inject malicious hooks.

Options:

Remove ~/.claude from ALLOWED_ESCAPES entirely (require human approval for all changes)
Whitelist specific subdirectories only (e.g., allow ~/.claude/state/ but not ~/.claude/hooks/)
Add a secondary confirmation hook for ~/.claude/ writes
Keep current behavior but log all ~/.claude/ modifications to audit log

Review Finding: The current implementation already uses Option 2 (whitelisting). The project-sandbox.ts hook:

Has a CLAUDE_WHITELIST of allowed subdirectories
Only allows writes to: __dump__, agents, archive, backups, commands, docs, handoffs, hooks, output-style, plans, plugins, scripts, skills, state
Blocks any subdirectory not in the whitelist
Allows root-level files (like CLAUDE.md) but not new directories

Risk Assessment:

⚠️ Hooks directory is writable - but mitigated by:
- claude-config-changelog.ts logs all changes
- skill-validation.ts validates skill changes
- hook-version-control.ts (FTL-083) audits hook changes
✅ Sensitive files outside .claude/ are blocked
✅ Unknown subdirectories are blocked

Decision: Current security model is acceptable. Mitigation via audit logging is sufficient. No changes required.

Artifact: Security review documented in this entry

FTL-082: Global Install Only Works via npm

Status: Complete
Category: Tooling
Created: 2025-12-28
Completed: 2025-12-28

Context: Global installation (e.g., for CLI tools or packages meant to be installed globally) only works via npm, not bun or other package managers.

Problem: Despite using Bun as the project runtime (FTL-074), global package installation may have compatibility issues or limitations compared to npm’s global install mechanism.

Investigation Findings:

Bun is installed at ~/.bun/bin/bun (v1.3.4)
npm is installed at ~/.local/opt/homebrew/bin/npm (v11.6.2)
Bun global packages: ~/.bun/install/global/ (only playwright)
npm global packages: ~/.local/opt/homebrew/lib/ (linear-cli, wrangler)

Root Cause: ~/.bun/bin is not in PATH for subprocess execution, causing shebang #!/usr/bin/env bun to fail. This is why all DIDP scripts use explicit path: #!/usr/bin/env -S /Users/dust/.bun/bin/bun

Resolution Options:

Add ~/.bun/bin to PATH in shell config (fish: fish_add_path ~/.bun/bin)
Continue using explicit bun path in shebangs (current approach)
Use npm for global CLI distribution, bun for project development

Decision: Current approach (explicit path shebangs) is acceptable for internal tooling. For public distribution (FTL-050), use npm since it has broader PATH support.

Artifact: Investigation documented in this entry

FTL-083: Hook Version Control Enforcement

Status: Complete
Category: Tooling
Priority: P3
Created: 2025-12-28
Completed: 2025-12-28

Context: Hooks are created in ~/.claude/hooks/ (global) but should be backed up to version control for preservation and reproducibility.

Problem: When new hooks are created, there’s no automatic mechanism to ensure they’re copied to .jellylabs.ai/hooks/ for version control. This creates risk of losing hook implementations if the global directory is lost.

Solution: Created hook-version-control.ts PostToolUse hook that:

Detects writes to ~/.claude/hooks/*.ts or ~/.claude/hooks/*.sh
Logs all hook modifications to ~/.claude/state/hook-audit.log
Emits <agent-directive> with copy instructions to project hooks directory
Checks if project has .jellylabs.ai/ for DIDP-aware suggestions

Artifact: ~/.claude/hooks/hook-version-control.ts