@oneie/claude 0.5.0 → 0.7.0

package/templates/template-todo.md

@@ -2,25 +2,57 @@
 title: {Human-readable title}
 slug: {kebab-slug}
 type: plan
-tier: simple               # trivial | simple | complex  — /do reads this before W0
+tier: feature              # PATCH | FIX | FEATURE | SCHEMA — the SPINE tier. /do reads this
+                           # before W0 to prune the spine (do.md § "The pruned spine by tier").
+                           # This is the vocabulary do-tier.sh emits; case-insensitive here.
+classifier: complex        # trivial | simple | complex — the BUILD classifier (how much
+                           # machinery W0-W4 runs INSIDE a cycle). A SEPARATE AXIS from tier:.
+                           # Conflating the two is the recorded root cause of 157 plans
+                           # carrying `tier: complex` — a BUILD classifier in a field /do
+                           # resolves the spine from. Spine tier answers "which stops run";
+                           # classifier answers "how heavy is each cycle". Set both.
 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.
+                           # If the plan ships anything user-visible, this command MUST include a page-load proof —
+                           # e.g. `bash .claude/scripts/do-prove.sh --route /x && <other checks>`. grep/tsc alone
+                           # can pass while the page 500s or the code is dead.
 outcome_asserts: ""        # ONE sentence — what passing the outcome command proves (human-readable).
 
 deliverables:              # Concrete artifacts that ship. Every entry maps to a cycle. If it isn't here, it doesn't ship.
-  # - {route|component|cli-verb|api|migration|doc}: {path} — {what the user sees / can do}
-  # Example:
-  # - route: /chat/memory — user can read & edit company memory inline
-  # - api:   POST /api/memory/upsert — agent writes memory facts
-  # - cli:   one memory add — operator writes memory facts from terminal
+  # LAW — user-visible feature ⇒ must include a route/component row whose accept loads the page (do-prove.sh --route /path)
+  # QUOTE EVERY VALUE. The value is prose, and prose contains `:`, backticks, `{`, `#` and
+  # `—` — every one of which is YAML syntax. An unquoted entry parses as a nested mapping
+  # or dies outright, and nothing warns you: /do survives today only because do-rank.py
+  # hand-rolls a regex parser instead of using YAML. 101 of 292 filled *-todo.md files in
+  # this repo already fail to parse. factory-check.sh templates asserts that count never
+  # RISES — it is a ratchet, not a cleanup.
+  # - {route|component|cli-verb|api|migration|doc}: "{path} — {what the user sees / can do}"
+  # Example (note: every value quoted, colons and backticks safe inside):
+  # - route: "/chat/memory — user can read & edit company memory inline"
+  # - api:   "POST /api/memory/upsert — agent writes memory facts"
+  # - cli:   "one memory add — operator writes memory facts from terminal"
 
 ux_before: ""              # ONE sentence — what the user does TODAY (the current journey, friction included).
 ux_after: ""               # ONE sentence — what the user does AFTER this plan ships (the new journey).
@@ -34,17 +66,34 @@ 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.
   # The next batch fires the moment the previous batch's W4 closes.
   # Empty list → /do auto-derives from the cycle-level arrows below.
-  - [C1]                   # batch 1: foundation
+  #
+  # DOCS GO IN BATCH 1, NOT LAST. `.claude/rules/documentation.md` is explicit:
+  # the doc set is authored at the DOCS stop, BEFORE any code, and the tests are
+  # drawn from it. Scheduling `<slug>-docs.md` as the final cycle inverts that —
+  # the code decides what the doc says, and the acceptance oracle ends up written
+  # by the thing it is supposed to judge. Author the docs in batch 1; keep a
+  # separate, narrower closing cycle that RECONCILES them to what shipped. Two
+  # different jobs: one writes the oracle, the other closes drift.
+  #
+  # An arrow into the docs cycle is almost always imaginary — a doc cycle reads
+  # the promise, not another cycle's output. Same test as every other arrow:
+  # name the file the later cycle reads that the earlier one writes, or delete
+  # the edge. "We'll know more after C4" is W2 learning, not a file dependency.
+  - [C1]                   # batch 1: foundation + the doc set (the spec)
   - [C2, C3, C4]           # batch 2: independent siblings (concurrent)
   - [C5]                   # batch 3: composes C1-C4
   - [C6]                   # batch 4: polish across all
@@ -55,6 +104,7 @@ shared_recon:              # files /do reads ONCE at plan start (W0.5), shared b
 # ─────────────────────────────────────────────────────────────────────
 
 source_of_truth:           # ≤5 files — W2 auto-loads; only files that actually exist
+                           # any plan with a cycle whose surface ≠ none MUST list text/<slug>-ui.md here
   - docs/relevant-spec.md
   - src/relevant/file.ts
 existing_primitives:       # the components/libs this plan composes — NEVER reimplement these
@@ -126,81 +176,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 |
+- `.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
 
-## Category — what each tag family carries
+**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.
 
-| 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 |
-
-**The naming law:** `template-<suffix>.md` fills to `<slug>-<suffix>.md`. Six templates, one per spine stop that writes an artifact:
-- `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 — the one exception: agents live in `.claude/agents/`, not `text/`)
-- `template-tests.md` → `<slug>-tests.md` or `tests/e2e/<cycle>.test.ts` (TEST)
-- `template-teach.md` → `<slug>-doc.md` (TEACH)
-
-## 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 guidance |
-| 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)
 
@@ -216,27 +213,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
 
@@ -260,25 +237,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
 
@@ -290,24 +255,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
@@ -340,7 +287,7 @@ Pin shared names, CLI signatures, and design decisions **here**, before drawing
 | 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 · plan · todo · agent · tests · teach` (six, one per artifact-writing stop) |
-| 8 | W2 delegation | W2 = spawned single Opus agent; conductor stays Sonnet |
+| 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.
 
@@ -397,7 +344,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.
@@ -459,33 +406,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-surface-checklist.json` is **mandatory every cycle** — not just cycles that add routes. Either it lists the surface layers (routes, components, nav, inbound links, states) or it explicitly declares `{"surface": "none", "reason": "<why this cycle ships nothing user-visible>"}`. A missing file = W2 incomplete. For every new route/page/component the entry looks like:
+
+```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)
 
@@ -548,6 +517,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)
@@ -563,6 +533,8 @@ Plan close
 
 **UX delta:** {ONE sentence — what the user can do after this cycle that they couldn't before. "Operator now sees company memory in the chat sidebar." If "no user-visible change," say so explicitly — internal-only cycles must justify why they ship before a user-visible one.}
 
+**Surface:** {`/route` | `component:<Name>` | `none({reason})` — the user-visible surface this cycle ships; W2 copies this verbatim into `.w2-surface-checklist.json` (none requires the reason)}
+
 **Cycle outcome:** {verifiable — bash command / test name / API shape / Lighthouse score}
 
 ✓ valid: "`bun run verify` passes AND `GET /api/foo` returns `{id, name}`"
@@ -578,6 +550,17 @@ demo:
   budget:  "<2s wall · <80 LOC test"
 ```
 
+**Wave tracking** (mandatory — `do-auto.sh`'s `_sync_status` scans THIS `## C<n>` section for
+`- [ ] W` lines to auto-derive the Status kanban's header tick; the kanban's own nested
+`- [ ] W1 recon` lines are a summary view, not what the script reads. Omitting this block
+means the section never has an open `- [ ] W` line, so `_sync_status` false-ticks the cycle
+complete on the very first pass, before any work happens — verified failure, `live-edit` C1–C6,
+2026-07-23. One line per wave, updated to `[x]` as each completes):
+- [ ] W1 recon — {one line: what was found}
+- [ ] W2 decide — {one line: what was decided}
+- [ ] W3 edit — {one line: what landed}
+- [ ] W4 verify — {one line: what passed}
+
 ### W1 — Recon  [Haiku · parallel · merged across batch]
 
 /do spawns recon agents for ALL files in this batch's W1 list in a **single message**, deduped against `shared_recon:` cache. List only cycle-specific files that exist now (shared files are already cached at plan start).
@@ -598,7 +581,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.
 
@@ -612,6 +595,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`) — MANDATORY every cycle: for every new route/page/component document nav parent, inbound links + source pages, SDK/MCP/CLI exports, UI states — or write an explicit `{"surface": "none", "reason": "…"}`
 
 **Compose-or-construct verdict (mandatory — top of W2, before any other decision):**
 
@@ -639,16 +623,47 @@ 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.
+
+**UI cycles (surface ≠ none):** name `text/<slug>-ui.md` as source_of_truth and load the `shadcn` / `puck` / `frontend-design` skills before editing; W4 then verifies each component-state row of the -ui.md renders, `do-prove.sh --route` passes, and light+dark screenshots are attached to the cycle close note.
+
+**Surface build order (every cycle, in this order — driven by the mandatory `.w2-surface-checklist.json`; a cycle with `{"surface": "none"}` skips 5–8 but still files the checklist):**
+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]
 
@@ -660,6 +675,24 @@ 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)
+  - [ ] Page-load proof (surface ≠ none): `bash .claude/scripts/do-prove.sh --route {route}` exits 0 + each component-state row of `text/<slug>-ui.md` renders + light+dark screenshots attached to the close note
+- [ ] **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.
@@ -681,13 +714,20 @@ Report: `delta_tsc=±N  delta_loc=±N  compress_orphans=N  new_files=N  primitiv
 **Goal delta:** {one sentence}
 **Deliverable:** {one row from `deliverables:` table}
 **UX delta:** {one sentence — or "internal-only, justified by X"}
+**Surface:** {`/route` | `component:<Name>` | `none({reason})` — W2 copies into `.w2-surface-checklist.json`}
 **Cycle outcome:** {verifiable}
 
+**Wave tracking** (mandatory — see C1's note above for why):
+- [ ] W1 recon — {one line}
+- [ ] W2 decide — {one line}
+- [ ] W3 edit — {one line}
+- [ ] W4 verify — {one line}
+
 ### W1 — Recon  [Haiku · parallel]
 
 - `{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}
 
@@ -716,8 +756,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}
-- `text/dictionary-plan.md` — canonical names (always)
-- `text/rubrics-plan.md` — scoring bands (always)
+- `text/dictionary.md` — canonical names (always)
+- `text/rubrics.md` — scoring bands (always)
 
 ---
 
@@ -779,5 +819,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: `"text/dsl-plan.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