@oneie/claude 0.4.0 → 0.6.0

package/templates/template-todo.md

@@ -5,11 +5,25 @@ type: plan
 tier: simple               # trivial | simple | complex  — /do reads this before W0
 mode: construction         # discovery | construction | evolution | maintenance
 tags: []                   # drives pheromone routing + W2 context triggers
+priority: 0                # 0 none · 1 should · 2 important · 3 critical — human override; do-rank.py reads it
+depends_on: []             # [other-slug, …] — plans that must be DONE before this is READY; powers do-rank.py's blocked/ready buckets + do-fleet conflict ordering
 
 # ─── GOAL CONTRACT (the only thing that matters) ─────────────────────
+# PROMISE FAN-OUT: this file is spawned by the promise's derives.todo
+# at PLAN (text/<slug>.md is the promise). `outcome:` MUST be the
+# promise's `proof:` VERBATIM — and that proof is the && -join of the
+# promise's deliverables: schedule (the agency SOW), so the outcome
+# inherits its exhaustiveness — one observable, named once at PROMISE,
+# never restated. Cycles may be seeded by world: presence-check gaps
+# (missing agent → a template-agent.md cycle · missing skill →
+# /skill-creator · missing workflow/lifecycle stage → a cycle here).
+# Reconciles upward to the promise.
 # Both fields are load-bearing. /do reads them at plan start, every W2
 # verifies its cycle moves outcome closer, every W4 re-runs the outcome
 # command. Plan does not close until outcome exits 0.
+# ARMED CHECK: at PLAN close the outcome command MUST exit non-zero —
+# red before green. If it already passes, the goal is met (build nothing)
+# or the outcome is too weak to gate anything (rewrite it first).
 
 goal: ""                   # ONE sentence — what becomes true that wasn't before. Not "ship X" but "user can do Y" or "system enforces Z".
 outcome: ""                # ONE bash command — exits 0 = goal achieved. Re-runs after every batch's W4. The kill-switch.
@@ -34,11 +48,15 @@ ux_delta: ""               # ONE sentence — the specific improvement (fewer cl
 # without re-asking. Defaults below are conservative — raise per plan.
 
 parallel_budget:           # how many of each model can run simultaneously
-  # Two dials per agent: MODEL (haiku/sonnet/opus/bash) AND EFFORT (none/low/medium/high/xhigh).
+  # Two dials per agent: MODEL (haiku/sonnet/opus/fable/bash) AND EFFORT (none/low/medium/high/xhigh).
   # Pick the cheapest model that can decide, then the lowest effort that holds. See text/templates-plan.md.
   haiku:   20              # recon (low) + verify rubric (medium) agents
   sonnet:  10              # W3 edit agents — one per file, parallel (low mechanical / medium genuine edit)
   opus:    2               # W2 architectural decisions (high) / substrate reconciliation (xhigh) — rarely > 1
+  fable:   1               # ✅ FABLE AVAILABLE (restored 2026-07-04) — apex judgment ONLY: W2 escalation for
+                           # verdicts compounding across ≥3 cycles (audit severity, cut lines, wire-vs-kill,
+                           # canon); mark those cycles "[Fable — mandatory]". Backstop: hook:fable-fallback
+                           # forces every fable spawn back to Opus if FABLE_AVAILABLE is ever unset again.
 
 batches:                   # plan-level cycle DAG, flattened into batches.
   # Cycles inside the same batch run their waves IN PARALLEL.
@@ -126,79 +144,28 @@ Mirror this table into `deliverables:` frontmatter. Every row is owned by exactl
 
 ---
 
-## Canon reference (the 7 sources of truth)
+## Doctrine (pointed at, never copied)
 
-Every artifact reconciles against the canons that apply to its category. Running `do-reconcile.sh <canon>` on a file exits 0 when it reconciles.
+The static rules — canon table, category table, naming law, compose-first taxonomy, anti-pattern reject list, testing tool ladder, live-verification block, checkbox tick rules — live in exactly two places:
 
-| Canon | Lives in | Reconcile test |
-|---|---|---|
-| **Substrate** | `schema/one.tql` | extends the model, never forks; no new dim/verb; no dead name |
-| **Dictionary** | `text/dictionary-plan.md` | no synonym, no dead name |
-| **Authority** | `schema/roles.tql` | walk-up resolves it; no ad-hoc role equality check |
-| **SDK** | `@oneie/sdk` receivers | joins a receiver; never redefines a verb method |
-| **Design** | shadcn/ui + tokens | composes existing; promise terms appear in shipped artifact |
-| **Navigation** | `lib/menu.ts` · `data/in-types.ts` | registered in the right manifest + ≥1 inbound link |
-| **Types** | `tsc` | tsc delta ≤ 0 — no new errors |
-
-## Category — what each tag family carries
-
-| Category | Tags | Reconciles with | Done when |
-|---|---|---|---|
-| **PROMISE** | copy · benefit · journey | voice contract + personas | concrete enough to prove; voice consistent |
-| **DATA** | schema · types · migration | Substrate + Dictionary + Types | schema extended, types flow from it, delta_tsc ≤ 0 |
-| **SURFACE** | ui · page · nav · component | Design + Navigation | composed from real primitives; **registered + linked**; every state (empty/loading/error/edge) built |
-| **GATEWAY** | api · route · worker · channel | SDK + Authority | joins a receiver + route family; guarded by walk-up |
-| **PROOF** | test · e2e · a11y | goal / outcome | asserts the destination, not the path; exits 0 |
-| **TEACH** | doc · runbook · tutorial | Dictionary (names + links) | no stale name, no dead link |
+- `.claude/commands/do.md` — the engine: waves, gates, ratchet, parallelism, arrow test
+- `text/templates-plan.md` § Todo doctrine — taxonomy, anti-patterns, testing ladder, live verification
 
-**The naming law:** `template-<suffix>.md` fills to `<slug>-<suffix>.md`. Four templates, four phases:
-- `template-feature.md` → `<slug>.md` (PROMISE)
-- `template-plan.md` → `<slug>-plan.md` (DESIGN)
-- `template-todo.md` → `<slug>-todo.md` (PLAN)
-- `template-agent.md` → `.claude/agents/<name>.md` (BUILD)
+**Do not copy those tables into this file when filling it.** A todo instance carries only what is plan-specific. Copied doctrine = three-way drift + tokens paid at every W2 read in every fresh cycle subprocess.
 
-## Reuse contract (read before drafting any cycle)
+## Reuse contract (the one fill-in: compose-or-construct)
 
 **Power through simplicity.** The smallest amount of new code that closes the
-loop wins. Every cycle in this plan must answer the **compose-or-construct**
-question before W3 spawns any agent.
-
-### The compose-or-construct test
-
-For every new file a cycle proposes, W2 must record one line:
+loop wins. For every new file a cycle proposes, W2 must record one line:
 
 > **`{file}`** — no existing primitive covers `{specific behaviour}`. Closest
 > match: `{path}` does `{what}` but lacks `{gap}`. Composition would require
 > `{≥N hacks}` and lose `{what}`.
 
 If you can't fill that in, **delete the new file from the W3 list** and slot
-the behaviour into the closest existing primitive instead.
-
-### Compose-first taxonomy
-
-Before drafting any cycle, walk these registries top-to-bottom. The first
-match wins; only fall through to "new file" if every layer fails.
-
-| Layer | Where to look | Default verdict |
-|---|---|---|
-| 1. **Domain composition** | the surface's own folder (`web/src/components/{surface}/`) | extend the file that already renders this surface |
-| 2. **Cross-surface composition** | sibling component folders (`chat/`, `crm/`, `cards/`, `in/`, `settings/`) | import + slot — do not copy |
-| 3. **Design primitives** | `web/src/components/ai-elements/`, `web/src/components/ui/` | compose the primitive into a parent; never reimplement |
-| 4. **Library primitives** | `@/lib/`, `@/engine/`, existing hooks | reuse the helper; do not parallel-write |
-| 5. **Skill / rule packs** | `.claude/skills/`, `.claude/rules/` | invoke the existing skill; do not inline its knowledge |
-| 6. **New file** | only if 1-5 all fail | requires the W2 justification line above |
-
-**Anti-patterns rejected on sight:**
-
-- ❌ New `<Composer>` / `<Toolbar>` / `<Picker>` tree when `PromptInput*` already covers it
-- ❌ New `<ThreadView>` / `<MessageBubble>` when `Conversation` + `Message` + `MessageList` cover it
-- ❌ New `<Modal>` / `<Drawer>` / `<Sheet>` when `Drawer.tsx` is in `ui/`
-- ❌ Inline `<svg>` when `lucide-react` + `<Icon>` + `<IconBadge>` exist
-- ❌ Bespoke `<textarea>` when `PromptInputTextarea` is one import away
-- ❌ A new test file per component when one test file per surface is the norm
-- ❌ Re-implementing a debounce / fetch / SSE helper that already lives in `@/lib/`
-
-If your plan trips any of these, rewrite the cycle to compose instead.
+the behaviour into the closest existing primitive instead. Walk the
+compose-first taxonomy (`text/templates-plan.md` § Todo doctrine) top-to-bottom
+first; the anti-pattern list there rejects on sight.
 
 ### Reuse audit (mandatory W4 line item — every cycle, no exceptions)
 
@@ -214,27 +181,7 @@ Every W4 includes these greps; the cycle does not close if any fail:
 
 **The rule.** Every cycle has **one demo gate**: a bash command that exits 0 = pass. The command runs zero LLM tokens. If the command can't decide the cycle, it's the wrong command.
 
-### Goal-based, not implementation-based
-
-| Bad (implementation) | Good (goal) |
-|---|---|
-| `expect(getByText('Mark')).toHaveClass('bg-primary')` | `await run('mark', e); expect(getStrength(edge)).toBe(1)` |
-| "the button is visible and styled correctly" | "the action deposits pheromone on the edge" |
-| asserts the path | asserts the destination |
-
-A test that breaks when the styling changes is testing the wrong thing.
-
-### Vitest-first; Playwright only when justified
-
-| Test type | Use for | Time | Tokens (fail debug) | Default |
-|---|---|---|---|---|
-| **Vitest pure** | classifier, dispatcher, hooks, parsers | <100ms | ~200 | **default** |
-| **Vitest + msw** | API contract, fetch dispatch, SSE protocol | <500ms | ~400 | **default for network** |
-| **Vitest + @testing-library/react** | component render given prop, role-gated visibility | <1s | ~500 | **default for UI** |
-| **Lighthouse CLI** (Vitest wrapper) | perf budgets only | 30s | ~600 | when cycle ships perf |
-| **Playwright** | visual regression · real multi-context SSE · pixel-drag | 5-30s | 2k-10k | only if cycle declares `requires_playwright: true` in frontmatter |
-
-**Default to the cheapest tool that can express the goal.** A Playwright test where Vitest + msw would suffice is a token-waste and a flake risk.
+Assert the destination, not the path. Tool selection (Vitest-first ladder, Playwright only with `requires_playwright: true`) and the live-verification block for deploy-surface cycles: `text/templates-plan.md` § Todo doctrine.
 
 ### One demo gate per cycle
 
@@ -258,25 +205,13 @@ W4's "cycle demo passes" line resolves to `$(command) && echo pass`. The test fi
 
 If a cycle needs more than 150 LOC of test, it's actually two cycles.
 
-### Model × effort × wave × token math
+### Test file location — avoid the `generated/**` permission trap
 
-Two dials, set per agent. **Model** = cheapest that can decide. **Effort** = lowest that holds.
-Full per-stage routing in `text/templates-plan.md`.
+`.claude/settings.json` denies both `Read` and `Edit` on `**/generated/**` for the conductor and every spawned agent. A cycle that plans its demo test into `tests/unit/generated/<slug>.test.ts` will pass W2 planning and then dissolve mid-W3 when the edit is blocked. Default new tests to a sibling path — `tests/unit/<feature>.test.ts` — unless the plan is deliberately extending an existing file already inside `generated/` from before this deny was added.
 
-```
-W1 recon      bash · none      cache check       0 tokens on hit (saves ~12k vs live call); 14-day TTL
-              Haiku · low      SDK on miss       ~5,400-token prefix cached; saves ~4,900/call vs no-cache (40%)
-              (inline)         ≤5 files          no agent spawn — read inline
-W2 decide     Opus · high      architectural     Opus · xhigh if substrate/schema
-              Sonnet · medium  mechanical         inline if trivial
-W3 edit       Sonnet · low     mechanical edit   × N parallel, single message
-              Sonnet · medium  genuine restructure
-W4 verify     bash · none      `bun vitest run`  0 LLM tokens
-              Haiku · medium   × 6 rubric        SDK: ~10,900-token block cached; saves ~46k tokens/run (70%)
-demo gate     bash · none      test exit code    0 tokens
-```
+### Model × effort routing
 
-Every check that can be a bash command is a bash command. Tests are bash commands. **The cycle closes when the test exits 0** — no LLM judges the outcome. Progressive disclosure applies at every wave: a Haiku gets the last few turns and top paths, never the full history; a context doc loads only when a `context_triggers:` pattern matches.
+Model = cheapest that can decide; effort = lowest that holds. The full per-wave ladder and cache math live in `text/templates-plan.md` (registry) and `.claude/commands/do.md` (engine). Every check that can be a bash command is a bash command; **the cycle closes when the test exits 0** — no LLM judges the outcome.
 
 ### Autonomy gates
 
@@ -288,24 +223,6 @@ Cycle closes autonomously when:
 
 Any one fails → cycle stops, root cause filed, **no user prompt unless trust=cautious or W4 loops > 3**.
 
-### Live verification (cycles that touch deploy surfaces)
-
-Cycles that modify `web/src/middleware.ts`, `web/astro.config.mjs`, `wrangler.toml`,
-`web/src/pages/api/**`, or any `.tql`/D1 migration are required to add a post-deploy
-HTTP check to W4. Local `bun run verify` is necessary but **not sufficient** — D1
-schema drift and CF adapter changes only surface against the deployed runtime.
-
-```bash
-# W4 step for deploy-surface cycles (zero LLM tokens):
-for path in / /chat /agents; do
-  code=$(curl -s -o /dev/null -w "%{http_code}" "https://<deploy-url>$path?_t=$(date +%s)")
-  [ "$code" = "200" ] || [ "$code" = "302" ] || { echo "FAIL: $path → $code"; exit 1; }
-done
-```
-
-The cache buster (`?_t=...`) is mandatory — Astro's Layout sets long-cache headers
-on error responses too, so a stale 500 can mask a successful redeploy for up to 24h.
-
 ---
 
 ## Parallel execution plan
@@ -337,8 +254,8 @@ Pin shared names, CLI signatures, and design decisions **here**, before drawing
 | 4 | Self-test protocol | `do-reconcile.sh navigation --self-test` exits 0 |
 | 5 | Agent invocation strings | `do-reconcile.sh <canon> <file>` per category |
 | 6 | Shadow → live rename map | `do2-reconcile.sh → do-reconcile.sh` |
-| 7 | Template names | `template-feature.md · template-plan.md · template-todo.md · template-agent.md` |
-| 8 | W2 delegation | W2 = spawned single Opus agent; conductor stays Sonnet |
+| 7 | Template names | `template-feature · plan · todo · agent · tests · teach` (six, one per artifact-writing stop) |
+| 8 | W2 delegation | W2 = spawned single Opus agent (Fable when the cycle is Fable-pinned); conductor stays Sonnet |
 
 **Contract test:** could every cycle's W2 fill in its diff specs right now, without waiting for another cycle? If yes → contract complete. If no → pin the missing decision before drawing any arrow.
 
@@ -395,7 +312,7 @@ Mirrors `batches:` frontmatter. Each batch fires the moment the previous batch's
 
 - **Shared W0:** never re-run. Baseline captured in batch 0; W4 diffs against the same `.w0-baseline.json` for every cycle.
 - **W1 (recon):** every cycle's W1 file list is union'd, deduped against `shared_recon:`, and the remaining unique files are read in ONE message of `min(unique_files, parallel_budget.haiku)` agents.
-- **W2 (decide):** ONE Opus call per cycle (can't merge — each cycle is its own architectural decision). These N Opus calls fire in parallel in ONE message (subject to `parallel_budget.opus`).
+- **W2 (decide):** ONE apex call per cycle (can't merge — each cycle is its own architectural decision). These N calls fire in parallel in ONE message (subject to `parallel_budget.opus`). A Fable-pinned cycle's W2 runs as the single `parallel_budget.fable` slot — if two Fable-pinned cycles land in one batch, the second queues (or downgrades to Opus only if the plan explicitly allows it); Sonnet pre-builds each Fable call's context pack from the batch's W1 facts before the spawn.
 - **W3a (edit):** ALL independent edits from ALL cycles in the batch merge into ONE Sonnet spawn message. If C2 has 8 edits and C3 has 6 edits and C4 has 4 edits, that's 18 Sonnet agents in one message (subject to `parallel_budget.sonnet`).
 - **W3b (edit, dependent):** runs the moment its W3a counterpart settles, regardless of which cycle it belongs to.
 - **Demo gates:** all cycles' `demo.command` test files run in ONE `vitest run` invocation: `bun vitest run tests/e2e/c2.test.ts tests/e2e/c3.test.ts tests/e2e/c4.test.ts`. Single bash, zero LLM tokens, one ratchet check.
@@ -457,33 +374,55 @@ Reject any of these as reasons to add an arrow or move cycles to later batches:
 
 ---
 
-## Checkbox auto-tick contract
+## Surface checklist contract (W2 output)
+
+W2 must fill in `.w2-surface-checklist.json` for every new route/page/component:
+
+```json
+{
+  "surfaces": [
+    {
+      "name": "memory",
+      "routes": ["/u/[slug]/chat/memory"],
+      "components": ["MemoryCard", "MemoryEditor"],
+      "nav_entry": {
+        "parent_page": "src/pages/u/[slug]/chat/index.astro",
+        "parent_section": "Chat sidebar",
+        "link_text": "Memory",
+        "link_target": "/u/[slug]/chat/memory"
+      },
+      "inbound_links": [
+        {
+          "from_page": "src/pages/u/[slug]/chat/index.astro",
+          "anchor_text": "View memory"
+        },
+        {
+          "from_page": "src/pages/u/[slug]/settings/index.astro",
+          "anchor_text": "Manage memory"
+        }
+      ],
+      "sdk_export": "packages/sdk/src/types/memory.ts",
+      "mcp_tool": null,
+      "cli_verb": null,
+      "ui_states": ["empty (no memory yet)", "loading (fetching memory)", "error (fetch failed)", "edit (user editing memory)"]
+    }
+  ]
+}
+```
 
-Every actionable item in this plan is a checkbox. `/do` ticks them **the
-moment the action finishes** — never at the end of the run, never on
-"I'll do it next time." This is how a user reading the file mid-run can
-tell at a glance what's done.
+**Every surface must have:**
+- `nav_entry` (required if route is user-visible; null if internal-only)
+- `inbound_links` (required if user-visible; at least one link from a related page)
+- `sdk_export` (required if cycle adds new public types; null if only internal changes)
+- `ui_states` (required if component rendered; describe each state the component can be in)
 
-### The rule
+W4 will verify every entry above. Missing fields = W4 fails.
 
-| When | Action | Who marks it |
-|------|--------|--------------|
-| A W1 recon agent returns findings for a file | `- [ ] {file}` → `- [x] {file}` | `/do` after the agent settles |
-| A W2 decision item resolves (verdict filed, slot map populated, diff spec output) | item → `[x]` | `/do` inline |
-| A W3 edit agent reports success on a file | `- [ ] {file}` → `- [x] {file}` | `/do` after the agent settles |
-| A W4 check passes (`bun run verify`, demo command, rubric, doc-sync) | item → `[x]` | `/do` after the bash exits 0 |
-| A wave's items are all `[x]` | the wave header (`W1 recon`, `W2 decide`, etc.) → `[x]` | `/do` derives |
-| A cycle's four waves are all `[x]` | the cycle header (`C1 — name`) → `[x]` | `/do` derives |
-| A batch's cycles are all `[x]` | the batch header (`Batch 2`) → `[x]` | `/do` derives |
-| All batches `[x]` + plan rubric ≥ 0.65 | `Plan close` items → `[x]` | `/do` derives |
+---
 
-### What this means in practice
+## Checkbox contract
 
-- **No silent progress.** Every Bash exit and every agent return triggers a checkbox edit. The file IS the progress bar.
-- **Mid-run readability.** A user can `cat dashboard-todo.md` while `/do --auto` is running and see exactly where the wave fan-out is.
-- **Forward-only.** A `[x]` is never un-ticked except by an explicit `/do --wave N --redo`.
-- **Derivation, not duplication.** When `/do` sees all four waves of C2 are `[x]`, it ticks the `C2 —` header. The user doesn't tick anything manually unless they're overriding.
-- **Auto-advance.** When a batch closes, the next batch's blocker chain unblocks and its cycles flip from `state: blocked` to `state: ready`. `/do --auto` fires the next batch's W1 immediately — no prompt.
+Every actionable item is a checkbox; `/do` flips it the moment the action settles. The full tick table and invariants live in `.claude/commands/do.md` § Step 2 — the file IS the progress bar, forward-only, headers derived. What stays here is the instance-shaped granularity:
 
 ### Granularity (one checkbox per atomic action)
 
@@ -546,6 +485,7 @@ Plan close
   - [ ] **Every row in `deliverables:` table is shipped and reachable** (route returns 2xx, component renders, CLI verb runs, api responds)
   - [ ] **ux_after journey is walkable end-to-end** — record the screenshot / log / CLI session that proves it
   - [ ] Justify-or-drop review on any cycles unstarted after outcome passed
+  - [ ] **`text/<slug>-docs.md` is true** — authored first at DOCS (the spec); every documented observable now proven against the shipped thing, any drift reconciled (no plan closes with a doc that lies)
   - [ ] Final compress sweep
   - [ ] Final docs/improvements.md append
   - [ ] Plan rubric ≥ 0.65 across all cycles (goal-fit weight 0.35)
@@ -596,7 +536,7 @@ Recon agents return the **public API** (exported names + key prop signatures)
 of every primitive they find. W2 cannot decide compose-vs-construct without
 this — make it explicit, not implicit.
 
-### W2 — Decide  [Opus if complex · Sonnet if simple · inline if trivial]
+### W2 — Decide  [Fable if verdict compounds plan-wide · Opus if complex · Sonnet if simple · inline if trivial]
 
 /do resolves these from W1 findings. Write the real questions now — W2 answers them.
 
@@ -610,6 +550,7 @@ Every item below is a checkbox; `/do` ticks each as it resolves.
 - [ ] **Architectural questions** answered
 - [ ] **Diff specs output** for every W3 target
 - [ ] **Doc-plan** filed (`.w2-doc-plan.json`) if any trigger applies (new primitive · rename · public surface · directory contract)
+- [ ] **Surface checklist** (`.w2-surface-checklist.json`) — for every new route/page/component, document: nav parent, inbound links + source pages, SDK/MCP/CLI exports, UI states
 
 **Compose-or-construct verdict (mandatory — top of W2, before any other decision):**
 
@@ -637,16 +578,45 @@ separately. Default to "compose"; "new" is the exception, not the default.
 
 ### W3 — Edit  [Sonnet · parallel]
 
-W2 fills in the anchors. Mark which edits are independent vs dependent.
+W2 fills in the anchors AND the surface checklist. Mark which edits are independent vs dependent.
+
+**Surface build order (every cycle, in this order):**
+1. Schema (migration if needed)
+2. Types (TypeScript interfaces)
+3. Receiver/SDK (if new public method)
+4. API route (if new endpoint)
+5. Component (React/Astro component)
+6. Page (Astro page that uses component)
+7. **Navigation (route registered in nav system + parent link)**
+8. **Inbound links (links from related pages)**
+9. **Docs (dictionary updates, feature doc sections, plan updates)**
+10. **UI states (empty, loading, error, edge cases)**
 
 **W3a — independent (spawned in one message):**
-- [ ] `src/pages/api/chat.ts` — {what changes}
-- [ ] `text/chat-plan.md` — {doc update parallel to code change}
+- [ ] `migrations/0042_{feature}.sql` — {schema changes, if any}
+- [ ] `src/types/{feature}.ts` — {type definitions}
+- [ ] `src/pages/api/{feature}.ts` — {new endpoint, if any}
+- [ ] `src/components/{surface}/{Feature}.tsx` — {React component}
+- [ ] `src/pages/u/[slug]/{feature}/index.astro` — {Astro page}
+- [ ] `src/lib/navigation.ts` — {add route + link to parent nav section}
+- [ ] `src/pages/u/[slug]/{related-page}.astro` — {add inbound link to new feature}
+- [ ] `text/dictionary.md` — {add new terms + type definitions}
+- [ ] `text/{feature}-plan.md` — {add new section documenting the feature}
+- [ ] `packages/sdk/src/index.ts` — {export new types, if any}
+- [ ] `packages/sdk/src/client.ts` — {add new public method, if any}
+- [ ] `packages/mcp/src/tools/{feature}.ts` — {add MCP tool, if agent-facing}
+
+**UI states (inline with component, not separate edits):**
+- Empty state component (when no data exists)
+- Loading state (skeleton / spinner)
+- Error state (with fix link)
+- Edit mode (if applicable)
 
 **W3b — dependent (single message, after W3a completes):**
-- [ ] `src/lib/agents.ts` — {depends on W3a output in chat.ts}
+- [ ] `src/lib/index.ts` — {add exports from new modules W3a created}
+- [ ] `src/components/{surface}/index.ts` — {export new component if W3a created it}
 
-If all edits are independent, leave W3b empty — empty W3b = one fewer round-trip.
+If all edits are independent, leave W3b empty — empty W3b = one fewer round-trip. **Docs and navigation are NEVER W3b** — they are always in W3a.
 
 ### W4 — Verify  [Haiku×6 SDK-cached if complex · inline composite if simple/trivial]
 
@@ -658,6 +628,23 @@ If all edits are independent, leave W3b empty — empty W3b = one fewer round-tr
   - [ ] No reimplementation: greps from W2 anti-patterns table return zero hits in this cycle's new files
   - [ ] `wc -l {new files}` total ≤ W2-declared LOC budget
   - [ ] `delta_loc_net` matches or beats W2 target (negative preferred when this cycle replaces a bespoke widget)
+- [ ] **Surface layer verification** (hard gate — from `.w2-surface-checklist.json`):
+  - [ ] Route registered in navigation system (grep `path: ".*{route}"` in `src/lib/navigation.ts`)
+  - [ ] Nav entry created (parent link exists in parent page + sidebar)
+  - [ ] Inbound links wired (each link in checklist appears in source pages)
+  - [ ] SDK exports completed (new types in `packages/sdk/src/index.ts`)
+  - [ ] MCP tool defined (if agent-facing; in `packages/mcp/src/tools/`)
+  - [ ] CLI verb added (if operator-facing; in `packages/cli/src/commands/`)
+  - [ ] All UI states rendered (empty, loading, error, edit modes exist in component)
+- [ ] **Docs synchronized** (hard gate):
+  - [ ] New terms added to `text/dictionary.md`
+  - [ ] Feature doc section exists (`text/{feature}-plan.md` or appended to existing)
+  - [ ] No broken links (`markdown-link-check text/**/*.md`)
+  - [ ] No dead names from W3 edits (`grep -r "{old-name}" text/ | grep -v "^text/learnings.md"` returns nothing)
+- [ ] **Promise check** (hard gate — cycle's observable matches `text/{feature}.md`):
+  - [ ] Feature promise in `text/{feature}.md` states what the user gets
+  - [ ] Cycle's demo proves that promise is live (observable in UI, API, or CLI)
+  - [ ] Screenshot / curl output / CLI session pasted into cycle close note
 - [ ] **Deliverable shipped** — the `Deliverable:` row is live: route returns 2xx, component renders, CLI verb runs, api responds. Verified by bash, not vibes.
 - [ ] **UX delta observable** — record the after-state proof (curl output, screenshot path, log line) and paste it into the cycle close note.
 - [ ] **Plan outcome re-check** — `$(plan.outcome)` exit code recorded; if 0, trigger justify-or-drop on remaining cycles.
@@ -685,7 +672,7 @@ Report: `delta_tsc=±N  delta_loc=±N  compress_orphans=N  new_files=N  primitiv
 
 - `{file}` — {what to find}
 
-### W2 — Decide  [Opus if complex · Sonnet if simple · inline if trivial]
+### W2 — Decide  [Fable if verdict compounds plan-wide · Opus if complex · Sonnet if simple · inline if trivial]
 
 - {question}
 
@@ -714,8 +701,8 @@ Report: `delta_tsc=±N  delta_loc=±N  compress_orphans=N  new_files=N  primitiv
 - `text/template-feature.md` — the PROMISE template (PROMISE phase)
 - `docs/relevant-spec.md` — {why relevant to this plan}
 - `src/relevant/file.ts` — {why relevant}
-- `one/dictionary.md` — canonical names (always)
-- `one/rubrics.md` — scoring bands (always)
+- `text/dictionary.md` — canonical names (always)
+- `text/rubrics.md` — scoring bands (always)
 
 ---
 
@@ -777,5 +764,5 @@ nothing in this codebase is built on bare ground.
 
 **context_triggers:**
 - Pattern is matched against W1 findings (file paths + excerpts) — regex, case-insensitive
-- Inject only the *section* you need: `"one/signals.md § Six Verbs"` not the whole file
+- Inject only the *section* you need: `"text/dsl.md § Six Verbs"` not the whole file
 - If you don't know which patterns will fire, leave empty — do.md's built-in triggers still apply

package/commands/claw.md

@@ -1,135 +0,0 @@
-# /claw
-
-**Skills:** `/sui` (agent wallet derivation via `addressFor(uid)`) · `/cloudflare` (Worker deploy + secrets) · `/signal` (webhook channel routing, `ui:*` + `hook:*`)
-
-Add a NanoClaw (edge worker with LLM + substrate tools) to any agent.
-
-## Usage
-
-```
-/claw <agent-id>              Deploy claw for an agent from agents/*.md
-/claw <agent-id> --token T    Deploy with Telegram bot token
-/claw --list                  List available agents
-/claw --dry-run <agent-id>    Show config without deploying
-```
-
-## What is a Claw?
-
-A **NanoClaw** is a Cloudflare Worker that gives any agent:
-- LLM access (via OpenRouter — any model)
-- Substrate tools (signal, discover, remember, recall, highways, mark, warn)
-- Channel adapters (Telegram, Discord, Web)
-- Queue for async processing
-
-## Steps
-
-### 1. Check if agent exists
-
-First, verify the agent exists in `agents/` directory:
-
-```bash
-ls agents/*.md agents/**/*.md
-```
-
-If the agent doesn't exist, create one first:
-```bash
-cat > agents/<name>.md << 'EOF'
----
-name: <name>
-model: anthropic/claude-haiku-4-5
----
-
-Your system prompt here.
-EOF
-```
-
-### 2. Generate claw config
-
-Use the API to generate the config:
-
-```bash
-curl -X POST http://localhost:4321/api/claw \
-  -H "Content-Type: application/json" \
-  -d '{"agentId": "<agent-id>"}'
-```
-
-This returns:
-- `persona` — the agent's name, model, system prompt
-- `wranglerConfig` — ready-to-use wrangler.toml
-- `personaEntry` — code to add to personas.ts
-- `deployCommands` — step-by-step deploy instructions
-- `quickDeploy` — one-liner to deploy
-
-### 3. Deploy the claw
-
-**Option A: Quick deploy (recommended)**
-
-```bash
-bun run scripts/setup-agents.ts --name <name> --agent <agent-id>
-```
-
-Add `--token <telegram-token>` if you want a Telegram bot.
-
-**Option B: Manual deploy**
-
-1. Add persona to `agents/src/personas.ts`
-2. Create `agents/wrangler.<name>.toml`
-3. Deploy:
-   ```bash
-   cd agents
-   wrangler deploy --config wrangler.<name>.toml
-   wrangler secret put OPENROUTER_API_KEY --config wrangler.<name>.toml
-   ```
-4. Register Telegram webhook (optional):
-   ```bash
-   curl "https://api.telegram.org/bot<TOKEN>/setWebhook?url=https://<name>-claw.oneie.workers.dev/webhook/telegram"
-   ```
-
-### 4. Test the claw
-
-```bash
-# Web message
-curl -X POST https://<name>-claw.oneie.workers.dev/message \
-  -H "Content-Type: application/json" \
-  -d '{"group": "test", "text": "Hello!"}'
-
-# Health check
-curl https://<name>-claw.oneie.workers.dev/health
-```
-
-## Available Tools
-
-Every claw has access to these substrate tools:
-
-| Tool | What it does |
-|------|-------------|
-| `signal` | Emit a signal to another agent or skill |
-| `discover` | Find agents by tag or capability |
-| `remember` | Store an insight in TypeDB |
-| `recall` | Retrieve learned patterns |
-| `highways` | Get proven paths (highest pheromone) |
-| `mark` | Strengthen a path (positive feedback) |
-| `warn` | Weaken a path (negative feedback) |
-
-## Examples
-
-```bash
-# Deploy claw for the tutor agent
-/claw tutor
-
-# Deploy with Telegram bot
-/claw tutor --token 1234567890:ABC...
-
-# Deploy for a marketing agent
-/claw marketing/creative
-
-# Just show config
-/claw tutor --dry-run
-```
-
-## See Also
-
-- `scripts/setup-agents.ts` — Full deploy script
-- `agents/src/personas.ts` — Persona definitions
-- `agents/src/lib/tools.ts` — Substrate tool implementations
-- `/api/claw` — Config generation API