@oneie/claude 0.4.0 → 0.6.0

package/commands/do.md

@@ -1,19 +1,23 @@
-# /do — idea to shipped (v2, lifecycle-first)
+# /do — the autonomous build engine (v2, lifecycle-first)
 
-**One command.** Type `/do "<an idea>"` and it walks the whole build lifecycle from wherever the idea is: it agrees a goal, then walks the artifact spine — **making each artifact true** — writing whatever is missing, skipping whatever exists. Point it at a bare idea and it writes everything. Point it at code with no tests or docs and it backfills just those.
+**ONE builds itself through this loop.** Type `/do "<an idea>"` and it walks the whole build lifecycle — agreeing a goal, walking the artifact spine, **making each artifact true**. Every cycle writes `mark`/`warn`/`signal("cost:cycle")` back into the substrate. The world grows smarter with each run; the loop and the substrate are the same system.
 
 For each artifact on the spine: `true(artifact) ≡ exists(artifact) ∧ reconciles(artifact, canon)`. Missing → write. Stale → rewrite. True → skip.
 
 The human owns one thing: the goal sentence. `/do` owns everything below it.
 
-> Narrative for humans: `text/do.md`. Per-stage template/skill/agent routing: `text/templates-plan.md`. This file is what `/do` executes.
+> Narrative for humans: `text/do.md`. Per-stage template/skill/agent routing: `text/templates-plan.md`. Surface layers detail: `text/surfaces-layers.md`. Skill invocation contract: `text/skill-invocation.md`. Full-stack composition example: `text/sdk-mcp-cli-schema-design-integration.md`. This file is what `/do` executes.
 
 ---
 
-## Two principles, underneath every phase
+## Principles, underneath every phase
+
+**Docs-first — the doc is the spec *and* the oracle.** Write the documentation set (and the tests drawn from it) **before** building, not after. A doc written in the reader's language is a sharper spec than a plan written in the builder's — so it produces a sharper plan and sharper tests. The same docs are then the **acceptance oracle**: at the end, PROVE validates the shipped thing against the docs, and the tests assert the observable claims the docs make. Docs are written *first* and made *true last* — if BUILD can't make a documented claim true, either the code is wrong (fix it) or the doc was wrong (correct it), but every doc ends true. This replaces the old seed-then-refine draft: the first write is the real spec, not a sketch; the last touch is validation, not authorship.
 
 **Progressive disclosure.** Each phase loads only what it needs. Recon reads the last few turns + the most relevant files, never the whole history. A reference doc loads only when the work touches it. Skills are invoked, not inlined. Widen context only on a miss.
 
+**Skills are first-class.** W2 declares which skills apply to each file. W3 invokes them before editing to get domain guidance (patterns, examples, gotchas, best practices). If a skill is missing or stale (>30 days), W3 creates/updates it automatically via `/skill-creator`. Every edit is guided by live expertise — no guessing on patterns.
+
 **Parallel agents at the right model · effort.** Reach for the cheapest tool that can answer, then run as many as the work allows in one message. Two dials:
 
 ```
@@ -21,9 +25,32 @@ bash    none              bit-equal checks, greps, schema validation, test exit
 Haiku   low | medium      recon (low) · binary judgment / rubric (medium)
 Sonnet  low | medium      mechanical edit (low) · genuine restructure / prose (medium)
 Opus    high | xhigh      architecture (high) · substrate / schema reconciliation (xhigh)
+Fable   high · ×1         apex judgment — verdicts that compound across ≥3 cycles or the
+                          whole substrate (audit severity, cut lines, wire-vs-kill, canon).
+                          Never sweeps, never edits: Haiku extracts → Sonnet condenses into
+                          a context pack → Fable reads the pack, returns verdicts/diff specs.
+                          Escalation from Opus, never the default — with TWO standing
+                          exceptions: (1) SCHEMA-tier W2 (do-tier.sh emits w2_model=fable;
+                          substrate verdicts compound across every future cycle — and the
+                          classifier counts D1 .sql migrations and on-chain contract
+                          sources (.move/.sol, tests excluded) as SCHEMA, since applied
+                          migrations are append-only and deployed contracts can't be
+                          patched) and
+                          (2) the W4 UI Taste gate (one Fable verdict per UI-heavy cycle —
+                          keep/refine/reject, never sweeps/edits).
 ```
 
-Fan-out: independent agents in ONE message, capped by the plan's `parallel_budget`. Recon + verify fan wide (Haiku × N). Edits run one-per-file (Sonnet × N). Only W2 stays single — understanding is not delegable, but it runs as a **spawned single Opus `w2-decide` agent**, not inline. The conductor/session model runs Sonnet; W2 stays Opus·high. W2 is in the spawn list (W1·**W2**·W3·W4-rubric); the "never delegated → run inline" constraint is replaced by "stays single — one Opus agent, never fanned."
+> **✅ FABLE AVAILABLE (restored 2026-07-04).** `FABLE_AVAILABLE=on` is set in
+> `.claude/settings.json`'s `env` block, so Fable-pinned/Fable-mandatory cycles
+> (including SCHEMA-tier W2 and `do-tier.sh w2_model=fable`) spawn on **Fable·high**
+> as designed. `hook:fable-fallback` is the backstop: if Fable access is ever
+> revoked again, unset `FABLE_AVAILABLE` and every `model: "fable"` spawn falls
+> back to Opus automatically. New plans should set `parallel_budget.fable: 1`
+> and mark apex-judgment cycles `[Fable — mandatory]` per the rule above.
+
+Fan-out: independent agents in ONE message, capped by the plan's `parallel_budget`. Recon + verify fan wide (Haiku × N). Edits run one-per-file (Sonnet × N). Only W2 stays single — understanding is not delegable, but it runs as a **spawned single Opus `w2-decide` agent** (model-override to **Fable** when the cycle is marked Fable-mandatory in the plan), not inline. The conductor/session model runs Sonnet; W2 stays Opus·high (or Fable·high when pinned). W2 is in the spawn list (W1·**W2**·W3·W4-rubric); the "never delegated → run inline" constraint is replaced by "stays single — one apex agent, never fanned."
+
+> **Two execution paths (effort & parallelism).** The **Agent tool has no `effort` param** — so this default Agent-spawn path controls *model* per wave but not *effort* (the `· high/· low` columns are intent the conductor approximates, not an enforced knob). For **true per-wave effort** + managed parallel fan-out + worktree isolation, use **Path 2: the Workflow engine** (`.claude/workflows/do-engine.js`) — the interactive session runs `Workflow({name:"do-engine", args:{slug}})`; each wave's `agent({model, effort})` is explicit (W1 haiku·low · W2 opus·high · W3 sonnet·low · W4 haiku·medium), cycles in a batch run in parallel, and the plan worktree is the shared edit surface. Path 1 (`do-auto.sh`, shell `--auto`) stays the proven fire-and-forget loop and now passes the conductor's session `--effort`. **Both paths report identically** (shipped 2026-07-04, workflow-bridge C1): do-engine emits `world:do-event` at cycle open (`type:aim`) + close (`type:learn` with `{shape, model, composite}`) via a shell-quoted, fire-and-forget haiku curl — a Path 2 run lands in the inbox Build space and teaches the shape→model router exactly like Path 1. Architecture + when-to-use each: `text/do-engine-plan.md`. The wider seam (routing fan-out stages to workflows automatically, do-engine as a priced skill): `text/workflow-bridge-plan.md` — seed table + gates designed; the auto-routing default lands as its C6, not yet wired here.
 
 ### The coherence ratchet
 
@@ -47,12 +74,12 @@ Comprehensive and fast are not in tension: the **tier decides which gates run**,
 | Lever | Fires at | Saves by |
 |---|---|---|
 | Tier prune | Step 1 | PATCH walks `code` only; a gate never runs above the phases it guards |
-| Tool ladder | every decision | bash → Haiku → Sonnet → Opus; stop at the first that decides |
+| Tool ladder | every decision | bash → Haiku → Sonnet → Opus → Fable; stop at the first that decides |
 | **Context reset** | cycle boundary | multi-cycle plans run each cycle in a fresh subprocess (`do-auto.sh`) — prior-cycle chatter (~15–25k/cycle) never accumulates; ~90–150k saved on a 6-cycle plan |
 | **TRIVIAL fast-path** | BUILD | **0 agent spawns** — read ≤3 files inline, edit, bash verify, inline rubric, 1 learnings line |
 | Recon cache | W1 | `do-recon-cache.sh check` — sha-keyed local store, <14d → **0 tokens**, skip all spawns (saves ~12k/recon) |
-| W1 prefix cache | W1 miss | `w1-recon.ts` caches the ~5,400-token rules+agent prefix across Haiku calls (~4,900 saved/repeat) |
-| W4 rubric cache | W4 | `w4-rubric.ts` caches the ~10,900-token rubric+spec block across 6 Haiku calls — 1 write + 5 reads (~46k saved/run) |
+| W1 prefix cache | W1 miss | `w1-recon.ts` caches the ~5,400-token rules+agent prefix across Haiku calls (~4,900 saved/repeat). Needs `ANTHROPIC_API_KEY` — `do-auto.sh` lifts it from `one.ie/web/.env`; absent → uncached agent-spawn fallback |
+| W4 rubric cache | W4 | `w4-rubric.ts` caches the ~10,900-token rubric+spec block across 6 Haiku calls — 1 write + 5 reads (~46k saved/run). Same key requirement as W1 |
 | Verify-only-changed | W3→W4 | dependency cone from `git diff`; full verify only at cycle close |
 | Cross-cycle pre-warm | W4 close | one fire-and-forget Haiku pre-reads the next cycle's W1 targets |
 | Recon cap | W1 | 400-word receipt; high-signal slices → `.w2-spec.json`, not the raw dump |
@@ -87,18 +114,82 @@ C2·C3·C4 are siblings → their W1/W2 run concurrently and their W3a edits mer
 
 ---
 
+## Substrate signals — the loop feeds the world
+
+Every phase emits a `signal("world:do-event", payload)` into the substrate. Actors (human or agent) who follow the relevant tags receive it in their inbox at `/u/[slug]/in`. The receiver is the world; the router fans to followers; `mark()` closes the loop. Full routing spec: `text/routing.md`. Schema: `schema/do.tql`.
+
+| Phase | Signal | Tags emitted |
+|-------|--------|-------------|
+| **AIM** | `{ type:"aim", slug, tier, goal }` | `do:aim` · `do:cycle` · `tier:<tier>` · `slug:<slug>` |
+| **W1 recon** | `{ type:"wave", slug, cycle, wave:"W1" }` | `do:wave` · `do:build` · `slug:<slug>` |
+| **W2 decide** | `{ type:"wave", slug, cycle, wave:"W2" }` | `do:wave` · `do:build` · `slug:<slug>` |
+| **W3 edit** | `{ type:"wave", slug, cycle, wave:"W3" }` | `do:wave` · `do:build` · `slug:<slug>` |
+| **W4 verify** | `{ type:"verify", slug, cycle, composite, axis }` | `do:verify` · `do:cycle` · `slug:<slug>` · `s:<axis>` |
+| **LEARN/close** | `{ type:"learn", slug, tier, cycle, composite, deliverable, axis }` | `do:learn` · `do:cycle` · `tier:<tier>` · `slug:<slug>` · `s:<axis>` |
+| **HALT** | `{ type:"halt", slug, cycle, reason }` | `do:halt` · `slug:<slug>` |
+
+`axis` is the subset of the five axes a cycle measurably advanced — **Security · Stability · Speed · Structure · Integration** (the W4 rubric: `rubric-security`, `rubric-stability`, `rubric-speed`, `rubric-simplicity` = Structure, and `rubric-integration` = wired-not-orphaned). A cycle that raised the security score emits `s:security`; one that wired an orphaned surface emits `s:integration`; an agent following `s:security` watches that axis compound. The number is the rubric score, not a vibe.
+
+```bash
+# emitted by BOTH paths — do-auto.sh (Path 1) and do-engine.js emitDoEvent()
+# (Path 2, cycle open/close) — at each phase boundary (signal has no tag attribute —
+# tags ride in the payload and the receiver matches them at fan-out)
+signal("world:do-event", JSON.stringify({
+  type: "learn", slug: SLUG, tier: TIER, cycle: N, composite: C, deliverable: D,
+  axis: ["security","structure"],
+  tags: ["do:learn","do:cycle","tier:"+TIER.toLowerCase(),"slug:"+SLUG,"s:security","s:structure"]
+}))
+```
+
+The receiver is **`world:do-event` in `one.ie/web/src/lib/world-receivers.ts` `HANDLERS`** (a receiver, not a new route). It (1) gates to a trusted internal sender and scopes D1 to `ctx.ownerSlug` (IDOR); (2) finds every actor whose follow-paths match the payload tags **exactly**; (3) writes a D1 `thread` + `entity_tags` `["do-event","lifecycle:do:<stage>"]` so it renders in the inbox Build space; (4) `mark`s the `shape → model` path so the model router learns; (5) `mark`s each delivery (closed loop); (6) broadcasts `inbox:refresh` on the `inbox:{slug}` SSE topic. Actors subscribe with `sdk.follow("do:learn")` / `sdk.follow("slug:<slug>")` / `sdk.follow("s:security")`.
+
+---
+
 ## Step 0 — Classify the input
 
 | Input | Treat as | Entry |
 |---|---|---|
 | bare text (`"add usage billing"`) | **IDEA** (default) | walk the spine from the top |
-| `<slug>` or a `text/*.md` path | existing work | resolve its slug; ≥2 incomplete cycles → auto context-isolated loop, else walk from the first gap inline |
+| `<slug>` or a `text/*.md` path | existing work | resolve its slug; **always builds in a worktree** — ≥2 incomplete cycles → auto context-isolated loop, else walk the spine in-session inside a `--setup-only` worktree |
+| `--here` | run inline on the **current tree** — skip the worktree, for a trivial in-session edit you'll commit yourself | BUILD engine |
 | `--wave N` | force one wave of a todo | BUILD engine |
 | `--next-cycle` | *(internal)* run one batch then exit — the loop's recursion guard, set by `do-auto.sh`; never typed by a human | BUILD engine |
 | `--auto` | *(legacy alias)* same as a bare multi-cycle `/do <slug>` — the loop is automatic now | BUILD engine, trust-aware |
+| `--autonomous` | *(set by the orchestrator)* resolve gates without a human — see **Autonomous gate resolution** below | BUILD engine, headless |
 
 Derive the **slug** from the idea: kebab-case, 2–4 words (`"add usage billing"` → `usage-billing`). Every artifact on the spine is keyed by this slug.
 
+### Orchestrator verbs — `/do` across MANY plans
+
+If the **first word** after `/do` is one of these reserved verbs, it routes to the cross-plan orchestrator: run the mapped script via Bash, show its output verbatim, don't editorialize. Anything else is an idea/slug (above). None of these merge to `main` — they stop at the merge gate.
+
+| Type | Does | Runs |
+|---|---|---|
+| `/do next` | show the ranked priority queue (what to build next) | `.claude/scripts/do-rank.py` |
+| `/do audit` | classify every plan's kill-switch — armed/green/broken/prod | `.claude/scripts/do-killswitch-audit.py --run` |
+| `/do loop [N]` | **preview** — what the loop WOULD build (dry-run, N iters, default 3) | `.claude/scripts/do-orchestrate.sh --iters ${N:-3}` |
+| `/do auto [N]` | **build hands-off** — top N eligible+armed plans → branches, stop at merge | `DO_CONDUCTOR_TIMEOUT=900 .claude/scripts/do-orchestrate.sh --autonomous --go --iters ${N:-1}` |
+| `/do fleet [N]` | build N file-disjoint plans in parallel worktrees (default 2) | `.claude/scripts/do-fleet.sh --max ${N:-2} --go` |
+| `/do accept <slug>` | record a merge you landed (earns trust toward auto-merge) | `.claude/scripts/do-accept.sh <slug> accept` |
+| `/do reject <slug>` | record a branch you abandoned | `.claude/scripts/do-accept.sh <slug> reject` |
+| `/do prove` | prove the anti-fabrication gate (4/4) | `.claude/scripts/do-orchestrate.sh --prove-gate` |
+| `/do rubric [pkg]` | score security · stability · simplicity · integration · speed; writes W0 baseline the loop reads | `python3 .claude/scripts/do-rubric.py ${pkg:-"--all"}` |
+
+`/do auto` builds **nothing** when no plan is hermetic ∧ genuine-armed ∧ no-open-judgment — that's correct (it refuses unsafe work with a receipt). Give it fuel: a `tier: fix` plan with a LOCAL `outcome:` (see `text/orchestrator-how-to.md` §8). Full runbook: `text/orchestrator-how-to.md`.
+
+### Autonomous gate resolution (`--autonomous` / `DO_AUTONOMOUS=1`)
+
+Headless, the four asking-gates **must not call `AskUserQuestion`** — there is no human to answer, so it wedges. Resolve each by rule (the orchestrator only feeds *eligible* plans, so these rarely fire). Logic + tests: `one.ie/web/src/lib/do-autonomous.ts`; design: `text/do-autonomous-plan.md`.
+
+| Gate | Autonomous action |
+|---|---|
+| **AIM** (goal+tier) | **Resolve** from frontmatter `goal:`/`tier:` — the plan is authored, the human already answered. No question. |
+| **W3 anchor-miss** | **Re-plan once** — re-run W2 recon against current code to regenerate anchors, then retry. Miss again → **park**. |
+| **CLARIFY** | **Park** — emit `signal("world:do-event",{type:"park",reason:"needs-clarification"})`, tag `do:parked`, stop the cycle. Never guess. |
+| **PROMISE** (missing) | **Park** the same way — a missing promise is a missing spec. |
+
+**The rule:** auto-resolution ≠ auto-approval. Resolve what's encoded or safely derivable; **park** genuine judgment (a parked plan lands in the inbox for a human). The anti-fabrication gate (real ∧ ungamed ∧ kill-switch green) still runs on every autonomous cycle, and **merge stays human** until merge-trust is earned (L4, `autonomyLevel`). Never auto-merge from `--autonomous` alone.
+
 ---
 
 ## Step 1 — Goal + tier (the one human gate)
@@ -115,9 +206,13 @@ The pruned spine by tier:
 
 ```
 PATCH     AIM → BUILD → VERIFY                                                                          (edit + W4 verify gate; 0 spawns)
-FIX       AIM → SURVEY → [INVESTIGATE] → BUILD → TEST → PROVE → LEARN
-FEATURE   AIM → PROMISE → SURVEY → DESIGN ▸clarify → PLAN ▸analyze → BUILD → TEST → VERIFY → PROVE → TEACH → SHIP → LEARN
+FIX       AIM → SURVEY → [INVESTIGATE] → DOCS → BUILD → TEST → PROVE → LEARN
+FEATURE   AIM → PROMISE → SURVEY → DESIGN ▸clarify → DOCS → PLAN ▸analyze → TEST → BUILD → VERIFY → PROVE → TEACH → SHIP → LEARN
 SCHEMA    = FEATURE + Substrate reconcile at max
+
+  ▸ Docs-first order: DOCS (the full doc set = the spec) is written right after DESIGN; TEST (from those docs)
+    is written before BUILD; BUILD makes docs+tests true; PROVE validates the shipped thing against the docs;
+    TEACH is now reconcile-not-author (correct any doc↔reality drift so every doc ends true).
 ```
 
 `INVESTIGATE` rides any tier when the work touches code we didn't just write — it's the "understand before you change" step, not a separate tier.
@@ -131,26 +226,53 @@ For each **enabled** stop (per the pruned spine), in order: check if its artifac
 | Stop | Presence check | Missing → write with | Owner · model · effort |
 |---|---|---|---|
 | **AIM** | goal + tier confirmed | `AskUserQuestion` (one) | — |
-| **PROMISE** | `test -f text/<slug>.md` | `writer` skill + `text/template-feature.md` | sonnet · medium |
+| **PROMISE** | `test -f text/<slug>.md && .claude/scripts/do-promise-lint.sh <slug>` | `writer` skill + `text/template-feature.md` | sonnet · medium |
 | **SURVEY** | `do-survey.sh` (4 surfaces) | reuse verdict (expose / extend / build / drop) → the gap list, not the whole idea, feeds the design | `w1-recon`, `Explore` · haiku · low |
 | **INVESTIGATE** *(fix / legacy only)* | code we didn't just write | forensic recon → root cause (not symptom) + blast radius + the `must_not_break` line | `w1-recon` · haiku→sonnet · medium |
 | **DESIGN** | `test -f text/<slug>-plan.md` | Opus + `text/template-plan.md` (designs the gap list; pre-mortem + decisions live in the template), then `do-reconcile.sh substrate` + `do-reconcile.sh dictionary` | opus · high |
 | ↳ *CLARIFY* | plan has `## Clarifications` (FEATURE/SCHEMA) | ≤5 `AskUserQuestion`, written back into the plan | opus · high |
-| **PLAN** | `test -f text/<slug>-todo.md` | `/create todo` + `text/template-todo.md` | sonnet · medium |
+| ↳ *SPEC docs* | `-features.md` if scope is multi-capability; `-ui.md` if the feature ships a user-visible surface | `docs` skill picks the types → `text/template-features.md` / `text/template-ui.md` (conditional — see Doc artifacts below) | sonnet · medium |
+| **DOCS** | doc set exists ∧ reconciles | the **full** doc set, written as the spec — `docs` skill picks the types, `writer` drafts: always `-docs.md`; + `-tutorial`/`-how-to`/`-reference`/`-agents-docs` per condition. Written in the reader's language *before* code — this is the acceptance spec PROVE validates against. Not a draft: the real thing | sonnet · medium |
+| **PLAN** | `test -f text/<slug>-todo.md` | `/create todo` + `text/template-todo.md` — cycles + deliverables derived from the docs (each cycle ships a documented observable) | sonnet · medium |
 | ↳ *ANALYZE* | — | `do-analyze.sh text/<slug>-todo.md` — CRITICAL exit 1 blocks BUILD | bash · none |
-| **BUILD** | survey verdict = `build` (≥70% match → `expose`/`extend` instead) | the BUILD engine (Step 3) | sonnet · low–medium |
-| **TEST** | test file in the repo folder | test-first, one assertion per deliverable | sonnet · low |
+| **TEST** | test file in the repo folder | test-first **from the docs** — one assertion per documented observable; the docs' claims become the executable acceptance tests *before* code exists | sonnet · low |
+| **BUILD** | survey verdict = `build` (≥70% match → `expose`/`extend` instead) | the BUILD engine (Step 3) — make the docs + tests true | sonnet · low–medium |
 | **VERIFY** | rubric + ratchet pass | `do-reconcile.sh <canon>` per category + rubric composite ≥ 0.65 | haiku · medium |
-| **PROVE** | proof artifact captured | `do-prove.sh` (browser / curl / contract / sync) + `accessibility`; the shipped thing checked against `text/<slug>.md`. A multi-cycle plan already built on its own `do/<slug>` branch (worktree isolation — see context isolation below); PROVE is the gate that branch must clear before a human merges it to trunk | sonnet · low |
-| **TEACH** | feature doc + runbook exist | `tutorial` + `writer` — written against the *proven* behavior | sonnet · medium |
+| **PROVE** | proof artifact captured | `do-prove.sh` (browser / curl / contract / sync) + `accessibility`; the shipped thing checked against **the docs** — `text/<slug>-docs.md` (every documented observable) + `text/<slug>.md` (the promise). The docs are the oracle. A multi-cycle plan already built on its own `do/<slug>` branch (worktree isolation — see context isolation below); PROVE is the gate that branch must clear before a human merges it to trunk | sonnet · low |
+| **TEACH** | docs reconcile with shipped reality | **reconcile, not author** — the docs were written first at DOCS; now correct any doc↔reality drift so every doc ends *true* (fix the doc where reality justifiably diverged, or loop BUILD where the code missed the spec). `docs` skill + `writer` | sonnet · medium |
 | **SHIP** | changelog / README row | `/release` + adoption signal | sonnet · low |
 | **LEARN** | learnings entry written | close: learnings + cost signal + trust write | — |
 
-**Proof before docs.** PROVE can fail and loop back to BUILD; docs written first would describe behavior that isn't final. Document what's proven, then ship.
+**Docs are written first, validated last.** `text/<slug>-docs.md` (and the conditional doc set) is the **spec** — authored at DOCS, *before* BUILD, in the reader's language, so the plan and tests are drawn from a sharp description of intended behavior. It is not a draft: it is what the build must make true. At TEACH / plan close the same doc is **validated, not re-authored** — PROVE checks the shipped thing against it, and any drift is reconciled (fix the doc where reality justifiably diverged, or loop BUILD where the code fell short). Every doc ends true. *(This supersedes the old seed-at-PLAN / refine-at-TEACH pattern: the first write is the real spec, the last touch is validation.)*
+
+**Doc artifacts — all ten templates, each gated.** Every doc type in `text/docs.md` has a template (`text/templates.md` is the map). The **promise's `derives:` manifest** (`text/<slug>.md` frontmatter) declares which of these the feature spawns; the `docs` skill (`.claude/skills/docs/SKILL.md`) confirms the choice at DESIGN/DOCS — neither forces all ten. **Three are spine (automatic); seven are conditional (write only if the promise's `derives:` set them true, else skip).** All are written *before* BUILD. Copy the template, never write from scratch.
+
+| Doc | Template | Stop | Write when (else skip) |
+|---|---|---|---|
+| `<slug>.md` | `template-feature.md` | PROMISE | **spine** — FEATURE/SCHEMA (PATCH/FIX skip) |
+| `<slug>-plan.md` | `template-plan.md` | DESIGN | **spine** — FEATURE/SCHEMA |
+| `<slug>-features.md` | `template-features.md` | DESIGN | scope spans ≥3 capabilities, or a non-goal boundary must be pinned |
+| `<slug>-ui.md` | `template-ui.md` | DESIGN | the feature ships ≥1 user-visible surface (component/page) |
+| `<slug>-docs.md` | `template-teach.md` | **DOCS** (spec) → TEACH (validate) | **spine** — FEATURE/SCHEMA |
+| `<slug>-tutorial.md` | `template-tutorial.md` | **DOCS** | there's a first-success worth its own page |
+| `<slug>-how-to.md` | `template-how-to.md` | **DOCS** | ≥2 distinct recurring tasks users will repeat |
+| `<slug>-reference.md` | `template-reference.md` | **DOCS** | the spec (signals/fields/limits) is too detailed for `-docs.md` |
+| `<slug>-agents-docs.md` | `template-agents-docs.md` | **DOCS** | agents call this feature's receivers/signals |
+| *(build)* `tests/<slug>.test.ts` | `template-tests.md` | **TEST** (pre-BUILD) | **spine** — one assertion per documented observable |
+
+The split rule: `-docs.md` stays the single complete guide until it would balloon; when it does, the `docs` skill pulls the first-run into `-tutorial.md`, recurring tasks into `-how-to.md`, and the exhaustive spec into `-reference.md`, leaving `-docs.md` as explanation that links out. W4 doc-sync verifies whichever files the `docs` skill chose to write — a chosen doc that's missing or stale (or untrue against the shipped behavior) fails the gate.
 
 The two `↳` rows are **gates, not artifacts**: CLARIFY edits the plan in place (FEATURE/SCHEMA only); ANALYZE is read-only and blocks only on CRITICAL. Each real stop closes by leaving **one durable artifact on disk** — that artifact is the skip-check next time.
 
-**PROMISE first (for FEATURE/SCHEMA).** The promise (`text/<slug>.md`) is what PROVE later checks the shipped feature against. If you can't state what the user gets, halt — the idea isn't ready to build. PATCH/FIX have no promise to keep, so they skip it.
+**PROMISE first — the genesis contract (for FEATURE/SCHEMA).** The promise (`text/<slug>.md`) is the **first file and the genesis of the feature**: a contract of what will be made — read like the statement of work an engineering agency signs with a client. Everything below it on the spine — `-plan`, `-todo`, `-docs`, tests, code — is **derived from it and reconciles upward to it**. Four frontmatter fields make this mechanical (`text/template-feature.md`):
+- **`deliverables:`** — the **schedule of work**, enumerated and exhaustive: every item the client receives, each with its own `accept:` check. Not on the schedule = not promised (it goes in the promise's "Out of scope" section, in writing); on the schedule = ships or the whole promise settles broken. Acceptance is indivisible — no partial credit. `assumes:` alongside it lists client-side dependencies, each green at the making (a failing assumption means the contract can't be signed yet).
+- **`proof:`** — the acceptance test that settles the contract: **derived, not authored** — the `&&`-join of every deliverable's `accept:`, verbatim, so the one observable is exhaustive *by construction*. It *becomes* the todo's `outcome:`, the TEST assertion, and the PROVE oracle — named once here, never restated loosely. The schedule ⇄ proof law is enforced by `.claude/scripts/do-promise-lint.sh <slug>` (zero LLM — the PROMISE gate): every `accept:` must appear inside `proof:`, every item must carry an `accept:`, every assumption must hold; `--red` additionally requires the proof RED at PROMISE. Promises predating the schedule (no `deliverables:` block) pass grandfathered.
+- **`derives:`** — the manifest of which artifacts this promise spawns. `/do` reads it to know which conditional stops to backfill (instead of re-deciding at DESIGN); the tier prune still applies on top.
+- **`world:`** — the manifest of runtime the kept promise puts into the substrate: lifecycle moves (+ the signal that records each), workflow steps (the locked kinds), agents (+ their `subscribes:` tags), skills, task tags, tracking marks/warns, routing paths. At DESIGN/PLAN, `/do` presence-checks every entry the same way it checks an artifact — **missing agent → a `template-agent.md` cycle (+ `subscriptions:register` for its tags) · missing skill → `/skill-creator` · missing workflow/lifecycle stage → a cycle in the todo · present → skip**. PROVE reads `tracking.marks` as production observables alongside the docs; the `routing:` paths are where cycle composites and run-time outcomes land, so the ranker routes the next wave toward what worked. The fan-out builds exactly what the promise names — nothing more.
+
+**Contract-backed promises mint on-chain.** When the promise carries an uncommented `contract:` block (`text/template-feature.md`'s optional on-chain block), PROMISE also runs `bun pay/tools/promise-chain.ts mint <slug>` — it submits the generated `create_promise` with `terms_hash = sha256(text/<slug>.md)` and writes `object_id` + `maker` back into the frontmatter. Unarmed (no signer) → clean exit 2, the promise stays off-chain-only until minted. At close, `do-promise-settle.sh` settles **both halves** from the one proof exit code.
+
+The promise is the **genesis + root oracle**; it **composes with** docs-first, it does not replace it — `text/<slug>-docs.md` (authored at DOCS) is the derived, detailed oracle that *elaborates* the promise, and PROVE checks the shipped thing against **both**. Everything reconciles upward: a doc claim that contradicts the promise is a bug in the doc. If you can't state what the user gets, halt — the idea isn't ready to build. PATCH/FIX have no promise to keep, so they skip it. Design + Sui sketch: `text/promise-plan.md`.
 
 **Before BUILD — EQUIP (skill-check).** Infer skills from the task tags → `ls .claude/skills/{name}/` → **ready** (proceed) / **stale** (warn, proceed) / **missing** (offer to add). Block only if a required skill is missing.
 
@@ -168,9 +290,9 @@ The two `↳` rows are **gates, not artifacts**: CLARIFY edits the plan in place
 
 Forward-only — a `[x]` is never un-ticked except by `/do --wave N --redo`. If an action has no checkbox, it isn't tracked, and untracked work is the loudest smell. Full granularity table in `text/template-todo.md`.
 
-After the spine: **LEARN / close** — write one `learnings.md` entry (slug, tier, composite, deliverable, proof line), emit `signal("cost:cycle", {tokens, model, composite})`, delete `.w3-receipts.json`, write `.do-trust.json {level, consecutive, composite}`, and append `.w4-improvements.json` (an open item recurring in 3+ consecutive cycles = systemic gap → emit `substrate:systemic-gap`; next W1 reads it as a mandatory recon target).
+After the spine: **LEARN / close** — validate `text/<slug>-docs.md` against the shipped behavior (the doc was authored at DOCS as the spec; close is where every documented observable is confirmed true and any drift reconciled — no plan closes with a doc that lies about what shipped); write one `learnings.md` entry (slug, tier, composite, deliverable, proof line), emit `signal("cost:cycle", {tokens, model, composite})` and `signal("world:do-event", { type:"learn", slug, tier, cycle, composite, deliverable, tags:["do:learn","do:cycle","tier:"+tier,"slug:"+slug] })`, delete `.w3-receipts.json`, write `.do-trust.json {level, consecutive, composite}` (in a worktree loop, `do-auto.sh` syncs trust + improvements back to the main tree every iteration — state never strands), and append `.w4-improvements.json` (an open item recurring in 3+ consecutive cycles = systemic gap → emit `substrate:systemic-gap`; next W1 reads it as a mandatory recon target).
 
-**Plan-outcome kill-switch (zero LLM).** Re-run the plan's `outcome:` command every cycle close. Exit 0 → the goal is met: remaining cycles enter justify-or-drop (default drop), `--auto` halts. Over the tier ceiling → `warn` + justify. Weak rubric 3× → halt, the *plan* is wrong, not the code. Goal-drift (outcome fails 3× with green rubrics) → force a re-plan.
+**Plan-outcome kill-switch (zero LLM).** The switch must be **armed before it can fire**: at PLAN close (before the first BUILD cycle), run the `outcome:` command once and require a **non-zero exit**. Exit 0 at plan start means either the goal is already met (close the plan, build nothing) or the outcome is too weak to gate anything (rewrite it before any cycle runs) — red before green, at plan level. Then re-run the command every cycle close. Exit 0 → the goal is met: remaining cycles enter justify-or-drop (default drop), `--auto` halts. Over the tier ceiling → `warn` + justify. Weak rubric 3× → halt, the *plan* is wrong, not the code. Goal-drift (outcome fails 3× with green rubrics) → force a re-plan.
 
 **One command, complexity-sized.** `/do <anything>` is the only thing a human types — an idea, a slug, or a `text/<slug>-todo.md` path. The tier sizes the work and the spine prunes itself: a typo is edited and verified inline (one cycle, no loop); a feature writes its promise, plan, todo, tests, and docs and then runs every cycle. The human never picks the mode, never types a flag, never runs a second command.
 
@@ -178,14 +300,26 @@ After the spine: **LEARN / close** — write one `learnings.md` entry (slug, tie
 
 ```bash
 # /do runs this itself — the user never types it
-bun .claude/scripts/do-auto.sh <slug>
+bash .claude/scripts/do-auto.sh <slug>   # it's a bash script — `bun` parses it as JS and dies on `case ... )`
 ```
 
 `do-auto.sh` loops: each iteration spawns a clean `/do <slug> --next-cycle` that runs exactly one batch (W1→W4), ticks its boxes, writes state, and exits. Because each cycle starts from near-zero context, prior-cycle recon/edit/verify chatter never accumulates. The main session just kicks off the loop and reports the close.
 
-**Worktree isolation comes free with the loop.** The loop's existence *is* the trigger — `do-auto.sh` only runs for multi-cycle plans, which is exactly the FEATURE/SCHEMA work that must not land half-built on trunk. So before the first cycle it cuts a worktree `.do-worktrees/<slug>` on branch `do/<slug>` (reusing it on resume), syncs the plan's spine artifacts into it, and runs **every cycle inside it** — each cycle's edits and box-ticks commit to that branch. Trunk never moves while the loop runs; a halt (trust `cautious` / stall / max-cycles) leaves a clean, inspectable WIP branch, and re-running `/do <slug>` resumes in the same worktree. On plan-complete the loop **reports** the merge (`git merge --no-ff do/<slug>`) rather than running it — landing to trunk is a human decision (commit only when asked), and PROVE is the gate that branch cleared to earn the merge. PATCH/FIX never reach the loop, so they run inline with no worktree.
+**The multi-cycle loop builds in a worktree** (and so does every other `/do` — see the next section). For a multi-cycle plan — the FEATURE/SCHEMA work that must not land half-built on trunk — before the first cycle `do-auto.sh` cuts a worktree `.do-worktrees/<slug>` on branch `do/<slug>` (reusing it on resume), links deps, syncs the plan's spine artifacts into it, and runs **every cycle inside it** — each cycle's edits and box-ticks commit to that branch. Trunk never moves while the loop runs; a halt (trust `cautious` / stall / max-cycles) leaves a clean, inspectable WIP branch, and re-running `/do <slug>` resumes in the same worktree. On plan-complete the loop **reports** the merge (`git merge --no-ff do/<slug>`) rather than running it, and first writes a **zero-LLM merge digest** (`.do-digest.md` — cycles closed, diffstat vs trunk, gate verdict `trust·composite`, open items carried, cycle commits) so the human lands an *informed* merge, not a blind one: context isolation deliberately discarded each cycle's reasoning to stay cheap, so the digest is the only record left to read before an irreversible merge. Landing to trunk is a human decision (commit only when asked), and PROVE is the gate that branch cleared to earn the merge.
+
+**Every `/do` builds in a worktree — the default, no exceptions.** Worktree isolation is now *decoupled* from the subprocess loop: trunk never moves while any `/do` runs, regardless of tier. Two shapes, one outcome:
+
+- **Multi-cycle** (≥2 incomplete cycles) → the `do-auto.sh` loop above: a fresh subprocess per cycle, inside the worktree. (Context isolation + worktree isolation.)
+- **Single-cycle · PATCH · FIX** → there's nothing to context-isolate, so **no subprocess** — but it still gets a worktree. After PLAN (once `text/<slug>-todo.md` exists), the conductor runs:
+  ```bash
+  WT=$(bash .claude/scripts/do-auto.sh <slug> --setup-only)   # cuts/reuses .do-worktrees/<slug> on do/<slug>, links deps, prints the path
+  cd "$WT"
+  ```
+  then runs the spine **inline, in-session** with the worktree as the edit surface (Edit/Write target `$WT/...`), commits each step to `do/<slug>`, and on close writes `.do-digest.md` and **reports the merge** — exactly like the loop. The build happens in front of you; only trunk-landing waits.
 
-A **single** incomplete cycle (or a PATCH/FIX) runs inline — there's nothing to isolate from, and spawning a subprocess would cost more than it saves.
+**Escape hatch — `/do <x> --here`** runs inline on the **current tree** (the old no-worktree behavior) for a genuinely trivial in-session edit you'll commit yourself. The only way to skip the worktree.
+
+The close is uniform across all tiers: a branch `do/<slug>`, a digest, and one copy-pasteable land line — `git merge --no-ff do/<slug> && bash .claude/scripts/do-auto.sh --gc`.
 
 **`--next-cycle` is internal.** It means "run one batch, tick boxes, exit — do **not** loop." Only `do-auto.sh` passes it; it is the recursion guard that keeps a fresh `/do` from re-entering the loop. A human never types it.
 
@@ -224,7 +358,7 @@ echo "$RESOLVED" | jq -se 'all(.doc_only)' >/dev/null \
 TSC=$(bunx tsc --noEmit 2>&1 | grep -c "error TS" || echo 0)   # write .w0-baseline.json {tscErrors, loc, tests}
 ```
 
-**W1 — Recon.** Read `.w4-improvements.json` open items first — they're mandatory recon targets.
+**W1 — Recon.** Read `.w4-improvements.json` open items first — they're mandatory recon targets. Then consume the improvements queue: `grep -i "<slug-or-touched-paths>" .claude/improvements.queue.md | head -5` — matching proposals become recon targets too, and W4 deletes any line this cycle resolves (the queue shrinks or the loop is hoarding).
 
 **Cache check (zero tokens):**
 ```bash
@@ -238,14 +372,42 @@ bun .claude/scripts/w1-recon.ts --targets "$FILES" --mode RECON
 ```
 Script exits 2 if `ANTHROPIC_API_KEY` is absent → fall back to spawning `w1-recon` agent (Haiku · low) for ALL files in ONE message. Either path: skip `relevance_score < 0.4`; all-filtered → halt and broaden (zero-findings guard). Receipt capped at 400 words; persist high-signal slices into `.w2-spec.json`. *(The `w1-recon` agent carries the two-track existing-code + primitive-inventory contract.)*
 
-**W2 — Decide (spawned single Opus `w2-decide` agent — Opus · high).** W2 is NOT run inline; the conductor spawns one `w2-decide` agent at Opus·high and waits for its result. Understanding is not delegable; it stays single, never fanned — but pinning it to the conductor process is not required. The conductor/session model runs Sonnet; W2 stays Opus. W2 writes the goal/deliverable/UX gate (3 sentences) first. Then: reconcile names against `dictionary.md`; run the **compress check** before any new primitive (name 3 existing primitives that compose it → `compose` removes it from the diff, `new` needs a one-line justification + same-diff doc edit). The pre-mortem + trade-offs were already captured at the DESIGN stop (`template-plan.md`) — carry the failure modes forward as test cases, don't redo them. Classify each W1 finding Act / Keep / Defer. Output diff specs + write `.w2-spec.json` (+ `.w2-doc-plan.json` if a doc trigger fires). Pin the **Interface Contract** (shared names, CLI signatures, decisions that multiple downstream tasks reference — pins let them run parallel, not serial). Emit the maximal-width batch DAG (arrow test applied: arrows exist only where one cycle reads a file another writes). *(The `w2-decide` agent carries the compose-target table — which canonical doc to check per primitive type — plus context-triggers for surgical doc injection.)*
+**W2 — Decide (spawned single `w2-decide` agent — Opus · high; Fable · high when the cycle is Fable-pinned).** W2 is NOT run inline; the conductor spawns one `w2-decide` agent at Opus·high (model-override `fable` if the plan marks this cycle Fable-mandatory) and waits for its result. Understanding is not delegable; it stays single, never fanned — but pinning it to the conductor process is not required. The conductor/session model runs Sonnet; W2 stays Opus. W2 writes the goal/deliverable/UX gate (3 sentences) first. Then: reconcile names against `dictionary.md`; run the **compress check** before any new primitive (name 3 existing primitives that compose it → `compose` removes it from the diff, `new` needs a one-line justification + same-diff doc edit). The pre-mortem + trade-offs were already captured at the DESIGN stop (`template-plan.md`) — carry the failure modes forward as test cases, don't redo them. Classify each W1 finding Act / Keep / Defer. Output diff specs + write `.w2-spec.json` (+ `.w2-doc-plan.json` if a doc trigger fires). **Output surface checklist:** for each route/page/component being added, fill `.w2-surface-checklist.json` with: which nav parent it links under, what inbound links to add + from which pages, which SDK/MCP/CLI exports are needed, all UI states. If a surface is being added but nav_entry/inbound_links are null, W4 will fail — they are not optional. Pin the **Interface Contract** (shared names, CLI signatures, decisions that multiple downstream tasks reference — pins let them run parallel, not serial). Emit the maximal-width batch DAG (arrow test applied: arrows exist only where one cycle reads a file another writes). *(The `w2-decide` agent carries the compose-target table — which canonical doc to check per primitive type — plus context-triggers for surgical doc injection.)*
 
-**W3 — Edit (Sonnet × N parallel).** Soft-resume first: if `.w3-receipts.json` has fewer receipts than `.w2-spec.json` diff specs, a prior W3 was interrupted — skip W0–W2 and resume from the first unapplied spec. Pre-validate every anchor with `grep -qF` in parallel. No file overlap → spawn all `w3-edit` agents in ONE message (W3a). Overlap → W3a (independent) then W3b (same-file, sequential). Append a receipt per edit; anchor miss twice → halt, ask user. Build every UI state (empty / loading / error / edge), not just the happy path. Surfaces are built in category order: `schema → types → receiver/SDK → API route → component → page → route registered → nav entry → inbound links → states`.
+**W3 — Edit (Sonnet × N parallel).** Soft-resume first: if `.w3-receipts.json` has fewer receipts than `.w2-spec.json` diff specs, a prior W3 was interrupted — skip W0–W2 and resume from the first unapplied spec. Pre-validate every anchor with `grep -qF` in parallel. No file overlap → spawn all `w3-edit` agents in ONE message (W3a). Overlap → W3a (independent) then W3b (same-file, sequential). Append a receipt per edit; anchor miss twice → halt, ask user. **Surface build order (mandatory, every cycle):** `schema → types → receiver/SDK → API route → MCP tool → CLI verb → component → page → route registration → navigation → inbound links → doc updates → UI states` (full-stack composition example: `text/sdk-mcp-cli-schema-design-integration.md`). MCP/CLI layers run only when `.w2-surface-checklist.json` declares `mcp_tool`/`cli_verb` — agent-facing or operator-facing capabilities, not every UI tweak. **Docs are parallel to code** — do not wait for W3a to complete; doc edits spawn in the same W3a message as code edits. **Navigation is mandatory** — if `.w2-surface-checklist.json` declares `nav_entry`, W3 must wire it (add route to nav system + create link from specified parent page); if omitted from checklist, W4 will fail. Same for inbound links. UI states (empty / loading / error / edge) rendered inline with page/component; not separate edits.
 
 **W4 — Verify (bash first, zero tokens).**
 ```bash
 ( cd $folder && bun run verify )            # biome + tsc + vitest
 $(cycle.demo.command)                       # the goal gate — exit 0 = pass
+# OBJECTIVE SECURITY GATE (zero-LLM, before the rubric) — a scored security score
+# can miss a leaked key or a known-vuln dep, so this is the deterministic backstop.
+# Guarded `if` forms: absence of the tool / of a dep change must NOT invert the exit.
+if command -v gitleaks >/dev/null; then gitleaks detect --no-git --source . --redact -q || exit 1; fi   # secret-scan
+if git diff HEAD --name-only | grep -qE '(bun\.lock|package\.json)$'; then bun audit --audit-level moderate || exit 1; fi  # dep audit (only when deps moved)
+# do-auto.sh runs the same _secret_gate before every per-cycle commit — the secret never lands on the branch.
+
+# SURFACE LAYER VERIFICATION (the missing piece)
+if [ -f .w2-surface-checklist.json ]; then
+  jq -r '.surfaces[] | select(.nav_entry) | .nav_entry' .w2-surface-checklist.json | while read -r route; do
+    grep -q "path:.*$route" src/lib/navigation.ts || exit 1  # route registered
+  done
+  jq -r '.surfaces[] | select(.inbound_links) | .inbound_links[]' .w2-surface-checklist.json | while read -r entry; do
+    page=$(echo "$entry" | cut -d: -f1)
+    text=$(echo "$entry" | cut -d: -f2)
+    grep -q "$text" "src/pages/$page.astro" || exit 1  # link added
+  done
+  # Verify SDK/MCP/CLI exports if declared
+  jq -r '.surfaces[] | select(.sdk_export) | .sdk_export' .w2-surface-checklist.json | while read -r export; do
+    grep -q "export.*from.*$export" packages/sdk/src/index.ts || exit 1
+  done
+  jq -r '.surfaces[] | select(.mcp_tool) | .mcp_tool' .w2-surface-checklist.json | while read -r tool; do
+    grep -rq "$tool" packages/mcp/src/tools/index.ts || exit 1    # tool registered
+  done
+  jq -r '.surfaces[] | select(.cli_verb) | .cli_verb' .w2-surface-checklist.json | while read -r verb; do
+    grep -rq "$verb" packages/cli/src/commands/index.ts || exit 1 # verb registered
+  done
+fi
 # RECONCILES gate: per-category reconcile calls
 do-reconcile.sh types                       # tsc delta ≤ 0
 do-reconcile.sh dictionary                  # no dead name, no new synonym
@@ -253,7 +415,13 @@ do-reconcile.sh substrate   <file>          # DATA tasks — schema extended, no
 do-reconcile.sh sdk         <file>          # GATEWAY tasks — joins a receiver
 do-reconcile.sh navigation  <surface>       # SURFACE tasks — registered + ≥1 inbound link
 do-reconcile.sh design      <file>          # SURFACE tasks — composes shadcn/tokens
-do-reconcile.sh authority   <file>          # GATEWAY tasks — walk-up resolves, no ad-hoc
+do-reconcile.sh authority   <file>          # GATEWAY tasks — walk-up resolves, no ad-hoc role bypass, no slug/workspace-from-request without authorizeWorkspace() (IDOR)
+# PROMISE CHECK (verify shipped feature matches text/<slug>.md promise)
+if [ -f "text/$(cycle.slug).md" ]; then
+  # Cycle demo must prove the observable from text/<slug>.md exists
+  # Example: if promise says "user can edit memory in sidebar", demo must navigate to sidebar + verify edit control
+  do-prove.sh $(cycle.slug) || exit 1
+fi
 # TEACH tasks: do-reconcile.sh dictionary + do-reconcile.sh types on doc files
 DELTA_TSC=$((TSC_NOW - TSC_BASELINE))       # hard gate: ≤ 0, no new type errors ever
 ```
@@ -263,12 +431,15 @@ bun .claude/scripts/w4-rubric.ts --files "$(git diff HEAD --name-only | tr '\n'
 ```
 Script exits 2 if key absent → fall back to spawning 6 Haiku agents · medium. Either path runs alongside `pr-review-toolkit` (code-reviewer, silent-failure-hunter, type-design-analyzer) + `find-bugs` + `accessibility` on UI):
 ```
-composite = 0.35·goal-fit + 0.20·security + 0.20·stability + 0.15·simplicity + 0.10·speed
+composite = 0.30·goal-fit + 0.18·security + 0.18·stability + 0.12·simplicity + 0.12·integration + 0.10·speed
 gate: composite ≥ 0.65  AND  goal-fit ≥ 0.50 (hard)  AND  no adversarial > 0.5  AND  delta_tsc ≤ 0
 ```
+**Integration is scored deterministically** — from `.w2-surface-checklist.json` (nav entry registered · inbound links present · SDK/MCP/CLI exports wired) + the `do-reconcile.sh sdk|navigation|docs` results: fraction of declared surfaces verified. Pass it to the rubric as `w4-rubric.ts --integration=0.NN`; only when no checklist exists does the LLM score it from the diff. The surface hard gates above still block independently — the score makes the axis *compound* (mark amount, `s:integration` signal), the gates make it *mandatory*.
+**Taste gate (UI-heavy cycles only).** When a cycle's deliverable is primarily a component/page, the design canon checks composition (shadcn/tokens) but not whether the result is *good*. Spawn one Fable verdict — fed the screenshot/render + the surface checklist, returning keep / refine / reject with one sentence why. Counts toward the simplicity score; reject → W3.5. Skipped for internal-only or non-UI cycles.
+
 Verify scope is the **dependency cone** of `git diff` (full verify only at cycle close — speed). Then compress sweep (ts-prune + noUnusedLocals → delete orphans/dead code), write `.w4-improvements.json`, and fire one pre-warm Haiku at the next cycle's W1 targets. Verify or demo failure on touched files → W3.5 (one Sonnet per dirty file), max 3 W4 loops then halt.
 
-**Testing policy** (full detail in `text/template-todo.md`): Vitest-first; Playwright only when the cycle declares `requires_playwright: true`; one goal-based `expect()` per deliverable (assert the destination, not the path); ≤1 test file per cycle; a cycle needing >5 tasks splits unless `mode: lean`; N-variant split-test → winner `mark()`, losers `warn(0.5)`.
+**Testing policy** (full detail in `text/templates-plan.md` § Todo doctrine): Vitest-first; Playwright only when the cycle declares `requires_playwright: true`; one goal-based `expect()` per deliverable (assert the destination, not the path); ≤1 test file per cycle; a cycle needing >5 tasks splits unless `mode: lean`; N-variant split-test → winner `mark()`, losers `warn(0.5)`.
 
 ---
 
@@ -277,15 +448,19 @@ Verify scope is the **dependency cone** of `git diff` (full verify only at cycle
 | # | Done means | Gate |
 |---|---|---|
 | 1 | The agreed goal is met | RUBRIC goal-fit |
-| 2 | Every shippable deliverable has a test asserting it | ANALYZE + TEST |
+| 2 | Docs written first (the spec) + a test per documented observable | DOCS + TEST (both pre-BUILD) |
 | 3 | No regression — ratchet held, `must_not_break` preserved | RECONCILES |
-| 4 | Proven live, reachable, matches the promise | PROVE |
-| 5 | Surfaces wired into navigation, not orphaned | RECONCILES (Navigation) |
-| 6 | Docs in sync — no stale name, no dead link | RECONCILES (Docs) |
-| 7 | Rubric clears the bar | RUBRIC |
-| 8 | Loop closed — result + learning recorded | LEARN |
-
-PATCH clears {1, 3, 7, 8}. FEATURE clears all eight. Same bar, scaled to the work.
+| 4 | Proven live, reachable, **every documented observable is true** + matches the promise | PROVE (docs as oracle + `.w2-surface-checklist.json`) |
+| 5 | **Routes registered in navigation + nav links wired** | W3 (navigation layer) + W4 (checklist verify) |
+| 6 | **Inbound links added from related pages** | W3 (inbound links layer) + W4 (checklist verify) |
+| 7 | **SDK/MCP/CLI exports completed** | W3 (SDK layer) + W4 (checklist verify) |
+| 8 | **All UI states rendered** (empty, loading, error, edit) | W3 (states layer) + W4 (checklist verify) |
+| 9 | Docs true — no stale name, no dead link, no claim the shipped thing doesn't honor | DOCS (authored) + W4 (docs reconcile vs shipped) |
+| 10 | Surfaces wired into navigation, not orphaned | W4 (RECONCILES Navigation) |
+| 11 | Rubric clears the bar | RUBRIC |
+| 12 | Loop closed — result + learning recorded | LEARN |
+
+PATCH clears {1, 3, 11, 12}. FIX clears {1, 2, 3, 4, 11, 12}. FEATURE clears all twelve. Same bar, scaled to the work.
 
 ---
 
@@ -295,8 +470,14 @@ PATCH clears {1, 3, 7, 8}. FEATURE clears all eight. Same bar, scaled to the wor
 - **Default to parallel.** Spawn W1, **W2**, W3, and W4-rubric agents — across cycles in a batch, not just within one. W2 is in the spawn list; the conductor runs Sonnet. An arrow exists only when you can name the file one cycle writes and the next reads; reject every imaginary blocker.
 - **Tick the moment it lands.** Flip `[ ]`→`[x]` as each agent/check settles — never batch at the end. The file is the progress bar.
 - **PROMISE before code (FEATURE/SCHEMA)** — no feature ships without a stated promise. PATCH/FIX skip PROMISE by design.
+- **Docs-first, validated last.** The doc set (`text/<slug>-docs.md` + conditional types) is authored at **DOCS, before BUILD**, as the real spec — never as a sketch. Tests are written from those docs at **TEST, before BUILD**. PROVE validates the shipped thing against the docs; close reconciles any drift so every doc ends true. No plan closes with a doc that lies about what shipped.
+- **W2 outputs surface checklist.** Every new route/page/component must have nav_entry, inbound_links, and ui_states declared before W3 runs. Missing any = W4 fails. This is what `.w2-surface-checklist.json` is for — no surprises in W3.
+- **W3 builds surfaces in order.** Code → docs → navigation → inbound links → UI states. All in W3a (parallel), not W3b. Docs are parallel to code, navigation is mandatory (not optional). If checklist says nav_entry, W3 wires it.
+- **W4 verifies surface layers.** No route is orphaned. Every nav_entry is wired. Every inbound link created. Every UI state rendered. Every SDK/MCP/CLI export done. Every doc updated. These are hard gates, not aspirational.
+- **Security findings sweep the whole cycle, not one file.** When a security gap (IDOR, SSRF, auth bypass, injection) is found or fixed, extract the pattern and grep it across the entire cycle diff — every sibling instance is fixed in the same wave, or the cycle does not close. `do-reconcile.sh authority` enforces the IDOR case deterministically per GATEWAY file (slug/workspace-from-request must use `authorizeWorkspace()`). A finding patched in one file but shipped in a sibling created the same cycle is an open vulnerability.
 - **Closed loop** — every cycle ends in `mark`/`warn`, never a silent return.
 - **Cheapest tool that decides wins** — a phase that needs no LLM call is the best kind.
+- **Arm the kill-switch.** The plan `outcome:` command must exit non-zero at PLAN close, before the first cycle. An outcome that passes before the work starts gates nothing.
 - **W4 max 3 loops**, then halt and report.
 - **One command.** A human types `/do <anything>` and nothing else. Complexity sizing, spine pruning, and (for multi-cycle plans) the context-isolated loop are all automatic — never a flag, never a second command.
 - **Every cycle gets a fresh context.** A multi-cycle `/do` runs each cycle in a clean subprocess via the internal loop. Prior-cycle conversation is noise; the todo checkboxes are the only state that carries forward.
@@ -306,16 +487,18 @@ PATCH clears {1, 3, 7, 8}. FEATURE clears all eight. Same bar, scaled to the wor
 
 ## Available to /do — the toolbox
 
-**Scripts** (`.claude/scripts/`): `do-auto.sh` (*internal* — the context-isolated, worktree-isolated loop `/do` drives for multi-cycle plans; builds on branch `do/<slug>`, merges to trunk only on a human's say-so) · `do-tier.sh` (tier + pruned spine + classifier + ceiling) · `do-folder.sh` (folder-aware verify/build) · `do-survey.sh` (reuse verdict) · `do-reconcile.sh <canon>` (**one predicate over 7 canons** — `substrate|dictionary|authority|sdk|design|navigation|types` — subsumes the old RECONCILE, COMPRESS, PROMISE-CHECK, DOC-SYNC gates; `navigation` branch enforces surface reachability; `--self-test` drives fixtures) · `do-analyze.sh` (deliverable↔cycle coverage gate) · `do-prove.sh` (surface-detect proof — pure PROVE, promise-check moved into `do-reconcile.sh design`) · `do-smoke.sh` (deterministic outcome — drives ≥1 fixture per canon branch + orphan/reachable nav fixtures) · `w1-recon.ts` (prompt-cached recon) · `w4-rubric.ts` (cached parallel rubric).
+**Scripts** (`.claude/scripts/`): `do-auto.sh` (*internal* — the context-isolated, worktree-isolated loop `/do` drives for multi-cycle plans; builds on branch `do/<slug>`, merges to trunk only on a human's say-so; writes a zero-LLM merge digest (`.do-digest.md`) at plan-complete so the human merges informed, not blind; conductor pinned `--model sonnet`; syncs trust/improvements back to main tree every iteration; `--gc` sweeps merged worktrees; **`--setup-only` cuts+links the worktree and prints its path then exits — the seam the inline single-cycle/PATCH/FIX path uses to build in a worktree without the subprocess loop**) · `do-tier.sh` (tier + pruned spine + classifier + ceiling) · `do-folder.sh` (folder-aware verify/build) · `do-survey.sh` (reuse verdict) · `do-reconcile.sh <canon>` (**one predicate over 7 canons** — `substrate|dictionary|authority|sdk|design|navigation|types` — subsumes the old RECONCILE, COMPRESS, PROMISE-CHECK, DOC-SYNC gates; `navigation` branch enforces surface reachability; `--self-test` drives fixtures) · `do-analyze.sh` (deliverable↔cycle coverage gate) · `do-prove.sh` (surface-detect proof — pure PROVE, promise-check moved into `do-reconcile.sh design`) · `do-promise-settle.sh <slug> [--composite 0.NN]` (zero-LLM promise settle at close — re-runs the promise's `proof:`; kept → `mark` on `promise:<slug>→proof` + `world:announce`, broken → `warn`, no observable → dissolved; `--self-test` drives kept/broken/dissolved fixtures; thesis `text/marketplace.md`) · `do-smoke.sh` (deterministic outcome — drives ≥1 fixture per canon branch + orphan/reachable nav fixtures) · `w1-recon.ts` (prompt-cached recon) · `w4-rubric.ts` (cached parallel rubric).
 
-**Templates**: `text/template-feature.md` (promise/PROMISE) · `text/template-plan.md` (design + pre-mortem + decisions/DESIGN) · `text/template-todo.md` (plan + parallel budget + testing policy/PLAN) · `text/template-agent.md` (agent definition/BUILD).
+**Templates**: `text/template-feature.md` (promise/PROMISE — uncomment its `contract:` block for a contract-backed promise that mints on-chain, worked example `text/playbook.md`) · `text/template-plan.md` (design + pre-mortem + decisions/DESIGN) · `text/template-todo.md` (plan + parallel budget + testing policy/PLAN) · `text/template-agent.md` (agent definition/BUILD).
 
 **Agents**: `w1-recon` · `w2-decide` (spawned single Opus; carries the full W2 contract — compress check, Interface Contract pin, maximal batch DAG) · `w3-edit` · `w4-verify` · `Explore` · `Plan` · `pr-review-toolkit:*` (code-reviewer, silent-failure-hunter, type-design-analyzer, pr-test-analyzer, code-simplifier) · `find-bugs`.
 
-**Skills** (per-stage routing in `text/templates-plan.md`): PROMISE → `writer`, `copywriting` · DESIGN → `typedb`, `signal` · BUILD → `astro`, `react19`, `shadcn`, `ai-ui`, `ai-sdk`, `reactflow`, `hono`, `cloudflare`, `wrangler`, `durable-objects` · TEST → `vitest`, `playwright-best-practices`, `webapp-testing` · VERIFY → `accessibility`, `find-bugs`, `perf`, `typecheck` · TEACH → `tutorial`, `writer`.
+**Skills** (per-stage routing in `text/templates-plan.md`): PROMISE → `docs`, `writer`, `copywriting` · DESIGN → `docs`, `typedb`, `signal`, `frontend-design` (if UI) · BUILD → `astro`, `react19`, `shadcn`, `ai-ui`, `ai-sdk`, `sdk`, `mcp`, `cli`, `reactflow`, `hono`, `cloudflare`, `wrangler`, `durable-objects` · TEST → `vitest`, `playwright-best-practices`, `webapp-testing` · VERIFY → `accessibility`, `find-bugs`, `perf`, `typecheck` · TEACH → `docs`, `writer`.
+
+**Skill-per-layer routing (W3 surface build order):** schema → `typedb` · types → `sdk` · API route → `ai-sdk` · receiver/SDK → `sdk` · MCP tool → `mcp` · CLI verb → `cli` · component/page → `react19` + `shadcn` · docs → `writer`. W3 loads the layer's skill before editing; missing/stale (>30d) → `/skill-creator` first (contract: `text/skill-invocation.md`).
 
 **State files** (write-once, read-by-path — compaction-proof): `.w0-baseline.json` · `.w2-spec.json` · `.w2-doc-plan.json` · `.w3-receipts.json` · `.do-trust.json` · `.w4-improvements.json`.
 
 ---
 
-*`/do` is `select()` made human-readable: idea in, shipped-and-proven feature out. Each artifact is made true — exists and agrees with its canon. The path remembers every execution.*
+*`/do` is `select()` made executable: idea in, proven feature out — each completed cycle marks what worked, warns what didn't, and writes the result back into the substrate. The world builds itself.*

package/commands/kill.md

@@ -1,35 +1,65 @@
 # /kill — Reset dev environment
 
-Stop all Astro dev servers (ports 4321–4329) and wrangler (8787), clear node + astro + vite + wrangler caches, run `bun install`, then `bun run dev`.
+Stop all Astro dev servers (ports 4321–4329) and all CF/wrangler ports (8787–8799), clear node + astro + vite caches, run `bun install`, then `bun run dev`.
 
 Use when HMR is broken, Vite re-optimization desyncs deps (duplicate React `useContext` is null, `createRoot` not exported with two `?v=hash` URLs), ghost ports refuse to release, or the user says "kill", "nuke", "reset dev", or "full clean rebuild".
 
 Scope is `one.ie/web/` only.
 
+## ⛔ NEVER DELETE — local database lives here
+
+**`.wrangler/` must NEVER be deleted.** It contains the local database:
+
+| Path | Contains |
+|------|----------|
+| `.wrangler/state/v3/d1/` | Local D1 SQLite databases |
+| `.wrangler/state/v3/kv/` | Local KV store |
+| `.wrangler/state/v3/r2/` | Local R2 buckets |
+| `.wrangler/state/v3/do/` | Durable Object storage |
+| `.wrangler/state/v3/workflows/` | Workflow state |
+
+Deleting `.wrangler/` wipes all local data. There is no undo. Do not include it in any `rm` command, ever — not even in a "full nuke".
+
 ## What it does (in order)
 
-1. **Kill** any process bound to ports 4321–4329 (Astro) and 8787 (wrangler), plus lingering `astro dev` / `wrangler dev` / `vite` / `workerd` processes
-2. **Clear** caches only — `.astro`, `node_modules/.vite`, `node_modules/.astro`, `dist` (preserves `node_modules` + `bun.lock` so install is fast; preserves `.wrangler/state` to keep local KV/D1/R2/DO data)
+1. **Kill** any process bound to ports 4321–4329 (Astro) and 8787–8799 (wrangler/CF Workers), plus lingering `astro dev` / `wrangler dev` / `vite` / `workerd` / `miniflare` processes
+2. **Clear** caches only — `.astro`, `node_modules/.vite`, `node_modules/.astro`, `dist` — nothing else
 3. **Reinstall** via `bun install`
-4. **Start** `bun run dev`
+4. **Start all three servers** in background:
+   - `bun run dev` — Astro on 4321
+   - `bun run dev:gateway:bg` — local gateway
+   - `bun run dev:wrangler` — CF Worker on 8787 (requires build; slow ~30s)
 
 ## One-shot command
 
-Run this exactly:
+Run the kill + reinstall first, then start all three servers. Each server starts in background (`run_in_background: true`).
 
+**Step 1 — kill + reinstall:**
 ```bash
 cd /Users/toc/Server/one-ie/one.ie/web && \
-  (lsof -ti:4321,4322,4323,4324,4325,4326,4327,4328,4329,8787 2>/dev/null | xargs kill -9 2>/dev/null; \
+  (lsof -ti:4321,4322,4323,4324,4325,4326,4327,4328,4329,8787,8788,8789,8790,8791,8792,8793,8794,8795,8796,8797,8798,8799 2>/dev/null | xargs kill -9 2>/dev/null; \
    pkill -f "astro dev" 2>/dev/null; \
    pkill -f "wrangler dev" 2>/dev/null; \
    pkill -f "vite" 2>/dev/null; \
-   pkill -f "workerd" 2>/dev/null; true) && \
+   pkill -f "workerd" 2>/dev/null; \
+   pkill -f "miniflare" 2>/dev/null; true) && \
   rm -rf .astro node_modules/.vite node_modules/.astro dist && \
-  bun install && \
-  bun run dev
+  bun install
+```
+
+**Step 2 — start all servers (each as a separate background Bash call):**
+```bash
+# Astro
+cd /Users/toc/Server/one-ie/one.ie/web && bun run dev
+
+# Gateway
+cd /Users/toc/Server/one-ie/one.ie/web && bun run dev:gateway
+
+# CF Worker (requires build — starts slower)
+cd /Users/toc/Server/one-ie/one.ie/web && bun run dev:wrangler
 ```
 
-Start the final `bun run dev` in the background (`run_in_background: true`) so you can monitor logs and confirm the server is up on 4321.
+Confirm Astro is up on 4321, gateway is up, and wrangler is up on 8787 by checking logs.
 
 ## When NOT to use
 
@@ -42,4 +72,4 @@ Start the final `bun run dev` in the background (`run_in_background: true`) so y
 
 1. `rm -rf node_modules/.vite .astro && bun run dev` — clears Vite + Astro cache only (~3s)
 2. **This command** — kills servers + clears caches + reinstall (~30s)
-3. Full nuke: `rm -rf node_modules bun.lock .astro dist && bun install && bun run dev` (~90s) — only if dependency tree itself is suspect
+3. Full nuke: `rm -rf node_modules bun.lock .astro dist && bun install && bun run dev` (~90s) — only if dependency tree itself is suspect. **Never include `.wrangler/`.**

package/commands/notify.md

@@ -0,0 +1,24 @@
+# /notify — send yourself a Telegram message via onedotbot
+
+Send a message to your personal Telegram from Claude Code.
+
+## Usage
+
+```
+/notify <message>
+```
+
+## How to invoke
+
+```bash
+.claude/scripts/notify.sh "<message>"
+```
+
+## Examples
+
+```bash
+.claude/scripts/notify.sh "deploy done — channels worker is live"
+.claude/scripts/notify.sh "tests passing, ready to review"
+```
+
+Sends to your Telegram (tg-631201930) via the channels worker. Uses `CHANNELS_URL` env var or the deployed worker at `channels.oneie.workers.dev`.