@oneie/claude 0.4.0 → 0.5.0

package/README.md

@@ -1,9 +1,5 @@
 # @oneie/claude
 
-> "Every other AI coding tool stops at 'here's some code.' That's the easy 20%. The other 80% — the spec nobody wrote, the test nobody added, the doc that's already a lie, the proof that it actually works — is where software goes to die. We built a machine that does the whole 80%, and only commits to the trunk once it's proven."
->
-> — Anthony O'Connell, Founder of ONE
-
 One command. One substrate. Install this plugin and Claude Code gains two things: a complete build workflow that takes an idea to proven, shipped software — and direct access to the ONE substrate, the backend that makes any application composable by agents.
 
 ```
@@ -35,10 +31,10 @@ That's it. The `/do` workflow is available immediately. The substrate tools acti
 One command walks the entire build lifecycle. You confirm the goal once. Everything below it is owned by the workflow.
 
 ```
-IDEA → GOAL → FRAME → SURVEY → SPEC → PLAN → BUILD → TEST → VERIFY → PROVE → TEACH → SHIP → LEARN
+IDEA → AIM → PROMISE → SURVEY → [INVESTIGATE] → DESIGN → PLAN → BUILD → TEST → VERIFY → PROVE → TEACH → SHIP → LEARN
 ```
 
-The workflow is a spine of artifacts on disk. A phase whose artifact already exists is skipped. Point `/do` at a blank idea and it runs every phase. Point it at code that's missing tests and point it runs only those.
+The workflow is a spine of artifacts on disk. A phase whose artifact is already **true** — it both *exists* and *reconciles* with its canon (`true ≡ exists ∧ reconciles`) — is skipped. Missing → write it. Stale → rewrite it. True → skip. Point `/do` at a blank idea and it makes every artifact true. Point it at code that's missing tests and docs and it backfills only those.
 
 A cheap probe at the start sizes the work:
 
@@ -55,14 +51,14 @@ You never pick the tier. The probe does, and it defaults down when unsure.
 
 1. The agreed goal is actually met (goal-fit gate)
 2. Every shippable deliverable has a test asserting it
-3. No regression — tests green, zero new type errors
-4. Proven live and matches the promise
-5. Docs in sync — no stale names, no dead links
-6. Full coverage — no orphan tasks
+3. No regression — coherence ratchet held, `must_not_break` preserved
+4. Proven live, reachable, matches the promise
+5. Surfaces wired into navigation, not orphaned
+6. Docs in sync — no stale name, no dead link
 7. Rubric clears the bar
 8. Loop closed — recorded result, written learning
 
-A typo clears 1, 2, 3, 8. A feature clears all eight.
+A typo clears 1, 3, 7, 8. A feature clears all eight.
 
 ### The ONE substrate — 14 operations via MCP
 
@@ -73,19 +69,18 @@ Every application is composed from the same fourteen operations:
 ```ts
 // A merchant publishes a product
 await c.signal('world:create-thing', {
-  content: { name: 'Midnight Linen Jacket', type: 'product', price: 295 }
+  name: 'Midnight Linen Jacket', type: 'product', price: 295
 })
 
-// A buyer completes a purchase — marks the path, settles payment
-await c.mark('buyer→merchant:order', {
-  weight: 295.00, currency: 'USDC', fit: 1, form: 1
-})
+// A buyer completes a purchase — settle the payment, then mark the path that converted
+await c.payWeight('buyer', 'merchant', 'order', 295.00)   // USDC settled
+await c.mark('buyer→merchant:order')                      // strengthen what worked
 
 // The substrate asks: what should we surface next?
-const next = await c.select('product', { exploration: 0.15 })
+const { target } = await c.select('product')
 ```
 
-Three calls. A commerce platform. The substrate records what converted, strengthens those paths, and starts surfacing better results automatically.
+Four calls. A commerce platform. The substrate records what converted, strengthens those paths, and starts surfacing better results automatically.
 
 **MCP tools available after `/setup`:**
 
@@ -142,7 +137,7 @@ When `/do` reaches the `code` phase it runs four waves:
 
 **W3 — Edit** — spawns one Sonnet agent per file, all in a single message. Pre-validates every anchor. Soft-resumes if interrupted.
 
-**W4 — Verify** — bash first, zero tokens: `bun run verify`, the goal gate, the doc-sync gate, the ratchet (`delta_tsc ≤ 0`). Rubric only if the bash gates pass.
+**W4 — Verify** — bash first, zero tokens: `bun run verify`, the goal gate, then `reconciles` — one predicate over seven canons (`substrate · dictionary · authority · sdk · design · navigation · types`) that subsumes the old reconcile, compress, promise-check, and doc-sync gates — and the ratchet (`delta_tsc ≤ 0`). Rubric only if the bash gates pass.
 
 ```
 composite = 0.35·goal-fit + 0.20·security + 0.20·stability + 0.15·simplicity + 0.10·speed
@@ -153,6 +148,21 @@ A cycle that runs zero LLM calls is a good cycle.
 
 ---
 
+## Templates
+
+Each spine stop that writes an artifact has a template — copied, never written from scratch, under the naming law `template-<suffix>.md → <slug>-<suffix>.md`. One proof observable is named once at PROMISE and referenced (never restated) all the way to TEACH.
+
+| Template | Stop | Writes |
+|----------|------|--------|
+| `template-feature.md` | PROMISE | `<slug>.md` — the promise + the one proof observable PROVE checks |
+| `template-plan.md` | DESIGN | `<slug>-plan.md` — design, pre-mortem, 7-canon reconcile gate |
+| `template-todo.md` | PLAN | `<slug>-todo.md` — cycles, parallel budget, DAG, testing policy |
+| `template-agent.md` | BUILD | `.claude/agents/<name>.md` — agent contract + one filled example |
+| `template-tests.md` | TEST | the cycle's demo gate — assert the destination, red before green |
+| `template-teach.md` | TEACH | `<slug>-doc.md` — the journey doc for humans *and* agents |
+
+---
+
 ## Agents as builders
 
 Agents are actors. They have the same fourteen operations as any other actor — the same API key, the same signal grammar, the same read surfaces. A human developer and an AI agent calling `signal` land in the same substrate. Same paths. Same pheromone.

package/agents/w4-verify.md

@@ -64,7 +64,7 @@ The rubric is not a verdict; it is a map forward.
 
 1. Run `bun run verify` (biome + tsc + vitest). Capture exit code and counts. If the command fails because `bun` isn't available, fall back to `npm run verify`.
 2. If biome/tsc/vitest fail on files touched in W3 → route failure back to W3 (the parent handles the W3.5 reloop; you emit `w4:verify:fail` with the failure list). Max 3 loops per cycle.
-2.5. **Contract gate** — for any verb touched in W3 (`signal`, `mark`, `warn`, `fade`, `follow`, `harden`), read `text/contracts-plan.md` and verify the diff against the verb's pre/post/inv. Until a property-test suite exists, this is a manual check; emit `contracts: reviewed` or `contracts: violated <verb> <clause>` in receipts. A violation is **non-bypassable** — cycle does not close regardless of rubric. If no verb touched → `contracts: n/a`.
+2.5. **Contract gate** — for any verb touched in W3 (`signal`, `mark`, `warn`, `fade`, `follow`, `harden`), read `text/contracts.md` and verify the diff against the verb's pre/post/inv. Until a property-test suite exists, this is a manual check; emit `contracts: reviewed` or `contracts: violated <verb> <clause>` in receipts. A violation is **non-bypassable** — cycle does not close regardless of rubric. If no verb touched → `contracts: n/a`.
 
 3. **Reconcile per canon** — run after deterministic checks pass, before rubric scoring.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneie/claude",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "ONE Claude Code plugin — /do lifecycle, W1-W4 BUILD engine, ONE substrate via MCP, signals, and rules",
   "files": [
     ".claude-plugin",

package/rules/engine.md

@@ -1,11 +1,14 @@
 ---
 paths:
-  - "agents/src/**/*.ts"
+  - "packages/sdk/src/**/*.ts"
+  - "channels/src/**/*.ts"
+  - "one.ie/web/src/lib/pheromone.ts"
+  - "one.ie/web/src/workers/**/*.ts"
 ---
 
 # Engine Rules
 
-Apply to `src/engine/*.ts`
+Apply to substrate code — the SDK verbs, the pheromone world, and every worker that consumes them.
 
 ---
 
@@ -16,17 +19,20 @@ These three rules compound. Breaking any one breaks the flywheel.
 ### Rule 1 — Closed Loop
 
 **Every signal closes its loop.** `mark()` on result, `warn()` on failure,
-`dissolve` on missing unit/capability. No silent returns. No orphan signals.
+`dissolve` on missing receiver. No silent returns. No orphan signals.
 
 ```typescript
-const { result, timeout, dissolved } = await net.ask({ receiver: next })
-if (result)        net.mark(edge, chainDepth)  // success → path strengthens
-else if (timeout)  /* neutral — not the agent's fault */
-else if (dissolved) net.warn(edge, 0.5)         // mild — path doesn't exist
-else               net.warn(edge, 1)            // failure — agent produced nothing
+// ask() resolves to one of 4 outcomes (packages/sdk/src/types.ts — Outcome<T>)
+const outcome = await one.ask(receiver, data)
+switch (outcome.kind) {
+  case "result":    await one.mark(edge); break        // success → path strengthens
+  case "timeout":   /* neutral — not the agent's fault */ break
+  case "dissolved": await one.warn(edge, 0.5); break   // mild — receiver doesn't exist
+  case "failure":   await one.warn(edge, 1); break     // failure — produced nothing
+}
 ```
 
-Why: pheromone is the only thing that compounds. A handler that returns
+Why: path strength is the only thing that compounds. A handler that returns
 silently leaks learning. Width (parallelism) only compounds if every
 parallel branch deposits a mark or warn on the path it used.
 
@@ -36,10 +42,10 @@ parallel branch deposits a mark or warn on the path it used.
 or any wall-clock unit.
 
 ```
-task    = atomic unit of work (one .on() handler, one file edit)
+task    = atomic unit of work (one receiver handler, one file edit)
 wave    = phase within a cycle (W1 recon → W2 decide → W3 edit → W4 verify)
 cycle   = full W0-W4 sandwich, exits at rubric >= 0.65
-path    = what remembers across cycles (pheromone strength / resistance)
+path    = what remembers across cycles (strength / resistance)
 ```
 
 Why: the substrate measures **width** by tasks-per-wave, **depth** by
@@ -52,7 +58,7 @@ from outside the substrate.
 
 **Every loop reports verified numbers, not vibes.** Tests passed/total.
 Build time in ms. Deploy time per service. Health check latency. Rubric
-dimension scores. These are the deterministic signals that calibrate pheromone.
+dimension scores. These are the deterministic signals that calibrate path strength.
 
 ```typescript
 // Every loop ends like this — not "done", but "done with receipts"
@@ -60,8 +66,8 @@ dimension scores. These are the deterministic signals that calibrate pheromone.
   passed: 320,
   failed: 0,
   buildMs: 22995,
-  deployMs: { gateway: 13705, sync: 8249, nanoclaw: 9163, pages: 17391 },
-  health: { gateway: 292, sync: 270, nanoclaw: 270 },
+  deployMs: { web: 13705, sync: 8249, channels: 9163, api: 17391 },
+  health: { web: 292, sync: 270, channels: 270 },
   // /do code rubric — security/stability/simplicity/speed, gate ≥ 0.65
   rubric: { security: 0.92, stability: 0.85, simplicity: 0.90, speed: 0.80 }
 }
@@ -73,153 +79,48 @@ it's learning. A loop that can't report deterministic results can't
 sandwich applied to every automation skill.
 
 **Where it shows up:**
-- `/work` — reports task count, tests passed, time spent
-- `/wave` — reports dissolved/marked/warned agent counts per wave
+- `/do` — W4 reports tests passed/total, reconcile canons, rubric scores
+- `/close` — reports rubric score (security + stability + simplicity + speed, composite ≥ 0.65) + learnings entry
 - `/sync` — reports tasks synced, hash-delta, KV writes
 - `/deploy` — reports W0 results, build ms, per-service deploy ms, health
-- `/done` — reports rubric score (security + stability + simplicity + speed, composite ≥ 0.65)
-- growth tick — reports per-loop timings (L1-L7 lastAtMs, nextAtMs)
 
 If you can't measure it, you can't route around it.
 
 ---
 
-## The Substrate
-
-```
-~90 lines.  Zero returns.  Two fields.  Queue.
-
-{ receiver, data }
-
-That's all that flows.
-The runtime moves signals. TypeDB remembers.
-```
-
----
-
-## Two Layers
-
-```
-NERVOUS SYSTEM (runtime)         BRAIN (TypeDB)
-signals, strength, resistance, queue     paths, units, skills, knowledge
-loops L1-L3 (ms to minutes)      loops L4-L7 (hours to weeks)
-```
-
-The runtime handles what moves. TypeDB handles what remains.
-
----
-
-## Tasks = Handlers, Dependencies = Continuations
-
-```typescript
-// Tasks are .on() handlers on units
-// Dependencies are .then() continuations
-const bob = net.add('bob')
-  .on('schema', async (data, emit) => buildSchema(data))
-  .then('schema', r => ({ receiver: 'bob:api', data: r }))
-  .on('api', async (data, emit) => buildAPI(data))
-  .then('api', r => ({ receiver: 'bob:test', data: r }))
-
-// No task entities. No dependency relations. No trail relations.
-// Pheromone accumulates on paths automatically.
-```
-
----
-
-## Agent Self-Improvement
-
-Units have `model`, `system-prompt`, `generation`.
-The substrate measures performance. When it's bad enough, the agent evolves.
-
-```typescript
-// TypeDB detects
-needs_evolution(unit) → success-rate < 0.50, sample-count >= 20
-
-// Agent responds
-unit.system-prompt = rewrite(old-prompt, failures)
-unit.generation++
-```
-
-Two layers of learning:
-- **Substrate** — pheromone on paths. World gets smarter.
-- **Agent** — prompt/model evolution. Individual gets smarter.
-
----
-
 ## Signal
 
 ```typescript
 type Signal = {
-  receiver: string      // "unit" or "unit:task"
-  data?: unknown        // { tags?, weight?, content? } by convention
+  receiver: string      // "family" or "family:action"
+  data?: unknown        // typed per receiver via RECEIVERS catalog
 }
 ```
 
-The universal primitive. `data` is untyped — convention shapes it:
-`tags` (routing/classification), `weight` (pheromone deposit), `content` (payload).
+The universal primitive — `{ receiver, data }` is frozen. Capability contracts
+live in the receiver registry (`@oneie/sdk/receivers`); the schema is truth for data.
 
 ---
 
-## Unit
-
-```typescript
-unit(id, route?)
-  .on(name, fn)           // define task (handler)
-  .then(name, template)   // define continuation (dependency)
-  .role(name, task, ctx)  // context-bound task
-  .has(name)              // introspection
-  .list()                 // introspection
-  .id                     // identity
-```
-
-### Task Signature
+## World (the pheromone primitives)
 
-```typescript
-(data, send, ctx) => result
-
-data   // the data
-send   // (signal) => void — fan out
-ctx    // { from: string, self: string }
-```
-
----
-
-## World
+Shipped surface — `createWorld()` in `one.ie/web/src/lib/pheromone.ts`
+(vendored in-RAM for DO bundles; mirrors the SDK verb semantics):
 
 ```typescript
-world()
-  .add(id)                // create unit (auto-drains queued signals)
-  .remove(id)             // remove unit (trails remain, fade naturally)
-  .signal(signal, from?)  // route signal, mark pheromone
-  .enqueue(signal)        // queue for later processing
-  .drain()                // shift from queue, signal it
-  .pending()              // queue length
-  .mark(edge, strength?)  // strengthen path
-  .warn(edge, strength?)  // weaken path
-  .sense(edge)            // read strength
-  .danger(edge)           // read resistance
-  .follow(type)           // best path (deterministic)
-  .select(type?)          // best path (probabilistic, ant-like)
-  .fade(rate?)            // decay all paths (resistance 2x faster)
-  .highways(limit?)       // top weighted paths
-  .has(id)                // introspection
-  .list()                 // introspection
-  .get(id)                // direct access
+world.mark(edge, w?)        // strengthen path
+world.warn(edge, w?)        // weaken path (resistance)
+world.sense(edge)           // read strength
+world.follow(from)          // best path (deterministic)
+world.select(from)          // best path (probabilistic, ant-like)
+world.highways(prefix?, n?) // top weighted paths
+world.fade(rate?)           // decay all paths (resistance 2x faster)
+world.serialize()           // snapshot for KV
+world.restore(snapshot)     // rehydrate
 ```
 
----
-
-## Persist
-
-```typescript
-persist()                           // extends world with TypeDB
-  .actor(id, kind?, opts?)          // add + persist
-  .flow(from, to)                   // mark/warn wrapper
-  .open(n?)                         // top paths as {from, to, strength}
-  .blocked()                        // toxic paths
-  .know()                           // promote highways to knowledge
-  .recall(match?)                   // query knowledge from TypeDB
-```
+Over HTTP the same verbs are `SubstrateClient` methods (`packages/sdk/src/client.ts`).
+`harden` is exposed via `signal("learning:know")`.
 
 ---
 
@@ -228,70 +129,25 @@ persist()                           // extends world with TypeDB
 Positive flow only. Silence is valid.
 
 ```typescript
-// GOOD
-task?.(data, emit, ctx).then(result =>
-  next[name] && route?.(next[name](result), receiver)
-)
+// GOOD — missing handler? Signal dissolves. World continues.
+handler?.(data, send, ctx)
 
 // BAD
-if (!task) return reject(...)
+if (!handler) return reject(...)
 if (!target) throw new Error(...)
 ```
 
-Missing handler? Signal dissolves. Group continues.
-
----
-
-## The Tick
-
-```typescript
-const next = net.select()              // follow pheromone
-next && net.signal({ receiver: next }) // execute
-net.drain()                            // process queue
-net.fade(0.05)                         // decay
-// evolve every 10min, know every hour
-```
-
----
-
-## Signal Flow
-
-```
-signal(sig, from='entry')
-  → unit(sig, from)
-    → task(data, send, {from, self})
-      → send(sig)  // fan out
-        → signal(sig, from=self)
-          → mark(edge)  // path remembers
-      → .then(task)  // continuation fires
-        → signal(next)  // chain continues
-```
-
-Concurrency safe. No global state.
-
----
-
-## Multi-Machine Collaboration
-
-```
-Machine A                           Machine B
-┌──────────┐                        ┌──────────┐
-│  router   │──signal──→ TypeDB ←──signal──│  router   │
-│          │←─paths───→       ←──paths──│          │
-└──────────┘                        └──────────┘
-```
-
-Each machine runs one router process. TypeDB is shared.
-Pheromone builds across machines. The substrate learns end-to-end paths.
+A dissolved signal still closes its loop — the *caller* sees `kind: "dissolved"`
+and warns the edge (Rule 1). Dissolve is an outcome, not an exception.
 
 ---
 
-*Signal. Mark. Warn. Follow. Fade. Highway. Queue. Evolve. Know.*
+*The 6 verbs: signal · mark · warn · fade · follow · harden.*
 
 ---
 
 ## Verb Contracts
 
-Each of the 6 verbs has a **pre / post / invariant** contract. Spec lives in `text/contracts-plan.md` — loaded only when editing a verb implementation, not every session.
+Each of the 6 verbs has a **pre / post / invariant** contract. Spec lives in `text/contracts.md` — loaded only when editing a verb implementation, not every session.
 
-New verb? You need: contract block in `text/contracts-plan.md`, row in `one-ie/CLAUDE.md` § The 6 verbs, contract gate in `.claude/agents/w4-verify.md` step 2.5. If you can't write the contract, you can't ship the verb.
+New verb? You need: contract block in `text/contracts.md`, row in `one-ie/CLAUDE.md` § The 6 verbs, contract gate in `.claude/agents/w4-verify.md` step 2.5. If you can't write the contract, you can't ship the verb.

package/scripts/w4-rubric.ts

@@ -31,7 +31,7 @@ const DIMS = [
   { key: "goal-fit",    weight: 0.35, instruction: "Score goal-fit: does the diff advance the plan outcome? Read Goal/deliverable from the spec. 0 = no movement, 1 = fully delivers." },
   // These are grep-pattern strings sent to the LLM for it to search — not code being executed.
   { key: "security",    weight: 0.20, instruction: "Score security: check for hardcoded secrets, calls to eval, dangerouslySetInnerHTML, missing Zod at API boundaries, wildcard CORS, TypeQL string concat. 1 = all greps return 0." },
-  { key: "stability",   weight: 0.20, instruction: "Score stability: check new `any`, @ts-ignore without comment, silent returns, retired names (knowledge|connections|people|node|scent|alarm|trail|colony). 1 = all zero." },
+  { key: "stability",   weight: 0.20, instruction: "Score stability: check new `any`, @ts-ignore without comment, silent returns, retired names (knowledge|connections|people|node|scent|trail|colony|pheromone). 1 = all zero." },
   { key: "simplicity",  weight: 0.15, instruction: "Score simplicity: focused single-purpose files, functions under 20 lines, no backwards-compat shims or WHAT comments. 1 = tight, no ceremony." },
   { key: "speed",       weight: 0.10, instruction: "Score speed: does the diff increase bundle size or build time? Any new client:load where client:idle suffices? 1 = no regressions." },
   { key: "adversarial", weight: 0,    instruction: "Adversarial check: is there any finding that should block this cycle? If yes, name it briefly. If nothing blocks, return null for 'finding'." },

package/templates/template-agent.md

@@ -15,6 +15,8 @@ You are the {name} agent. {One sentence role statement.}
 
 **Output:** {format of the result — structured, bounded, cited}
 
+**Escalate, don't guess.** Ambiguous or under-specified input → return a `needs: {what}` receipt and stop. Never assume a missing value.
+
 ## Model · Effort dial
 
 | Model | Effort | Use when |
@@ -45,6 +47,17 @@ You are the {name} agent. {One sentence role statement.}
 
 {json signal receiver and shape}
 
+## Example (one filled pass — the shape to copy)
+
+**Input:** `{ targets: ["src/lib/foo.ts", "src/lib/bar.ts"], mode: "RECON" }`
+
+**Output:**
+```json
+{ "receiver": "recon:done", "files": 2,
+  "findings": [{ "file": "src/lib/foo.ts", "exports": ["fooClient"], "relevance": 0.8 }],
+  "receipt": "2 files · 1 high-signal · bar.ts filtered (relevance 0.3)" }
+```
+
 ## Out of scope
 
 - {what this agent never does}

package/templates/template-feature.md

@@ -22,6 +22,10 @@ type: feature
 
 ## The promise (PROVE checks this)
 {One paragraph — concrete enough to prove. What the user sees, clicks, or gets back. Specific nouns. No hedging.}
+{One line — and what it deliberately does NOT do, so scope can't creep: "Not this: {the adjacent thing we leave out}."}
+
+## The proof (the one observable the whole spine points at)
+{ONE checkable thing that is true only if the promise is kept — a screen that renders, a command that exits 0, a response shape. Name it once here; DESIGN's pre-mortem tests, the todo's `outcome:` command, the TEST assertion, and TEACH's "verify it's working" all reference THIS — never a loose restatement.}
 
 ## Tone
 {Voice contract keywords for this surface — 3-5 words that capture the feel. These come from .claude/product-marketing.md.}

package/templates/template-plan.md

@@ -18,9 +18,10 @@ source_of_truth:
 
 # {Title}
 
-## The promise (from FRAME)
+## The promise (from PROMISE)
 
 {One line, copied from text/<feature>.md — the design exists to keep this promise.}
+{The one proof observable, copied from the promise — every decision below is measured against keeping it true.}
 
 ## Reuse verdict (from SURVEY)
 
@@ -40,10 +41,14 @@ source_of_truth:
 ### UI
 {Which existing components / pages / navigation this composes. Empty / loading / error / edge states named here, not deferred to BUILD.}
 
-## Substrate reconciliation (gate — zero new core concepts without justification)
+## Reconciliation (gate — reconcile against every canon this design touches)
 
-- [ ] Names exist in `dictionary.md` (no dead names)
-- [ ] No new dimension / verb / type — or one-sentence justification: {…}
+The 7 canons: `substrate · dictionary · authority · sdk · design · navigation · types`. Tick only those this design touches; each becomes a `do-reconcile.sh <canon>` gate at W4.
+
+- [ ] **dictionary** — names exist in `text/dictionary-plan.md`; no dead name, no synonym
+- [ ] **substrate** — extends `schema/one.tql`, never forks; no new dimension/verb (or one-sentence justification: {…})
+- [ ] **navigation** — every new surface names its manifest entry + ≥1 inbound link *here*, not deferred to BUILD
+- [ ] **authority** — access resolves by the walk-up; no ad-hoc role-equality check
 - [ ] No locked-rule break (6 dims, 6 verbs, 3 rules)
 
 ## Pre-mortem (assume it shipped and failed — why?)

package/templates/template-teach.md

@@ -2,33 +2,74 @@
 slug: {{slug}}
 written: {{YYYY-MM-DD}}
 proven: true
+audience: humans + agents
 promise: text/{{slug}}.md
 ---
 
 # {{Feature Name}}
 
-> Written after PROVE passes. Describes behavior that exists, not behavior that is planned.
-> The promise (`text/{{slug}}.md`) is what this doc must match.
+> {{One line — the promise kept, in the reader's own words. This is the hook. Make them want the next sentence.}}
 
-## What it does
+<!-- Written AFTER PROVE passes. Every claim below is proven behavior, never planned. The promise (text/{{slug}}.md) is the spec this doc must match. -->
 
-{{1–3 sentences. What the user/operator gets. Every claim here must be in the proven behavior.}}
+## Why this exists
 
-## How to use it
+{{2–4 sentences. The world *before* this feature — the friction, the wait, the thing that was hard or impossible. Name the pain the reader already feels, so everything after lands as relief. Plain English, no jargon. Earn the reader before you teach them.}}
 
-{{The golden path. Step-by-step. Present tense. Tested commands only.}}
+## What you get
+
+{{1–3 sentences. The capability in the reader's words — what they can do now that they couldn't before. This is the "after" to the "Why this exists" "before." One clean promise, no list of features.}}
+
+## The mental model
+
+{{The one idea that makes everything else obvious. One short paragraph — or the small diagram below. Hold this shape in your head and every step clicks. Great docs hand you the model first; weak docs make you reverse-engineer it from the steps. Use an analogy only if it is exact.}}
+
+```
+{{optional — a 3–6 line shape: the thing, what goes in, what comes out}}
+```
+
+## Your first win (60 seconds)
+
+The shortest path to a working result. Copy, paste, watch it work — then you'll trust the rest.
 
 ```bash
-# Example — copy-pasteable, verified to work
+# Copy-pasteable. Verified to work. The fastest route to a green result.
+{{the one command — or 2–3 lines — that produce a visible win}}
 ```
 
+You'll see {{the exact observable result: the line of output, the screen, the file that appears}}. That is the whole thing working. Everything below is depth, not prerequisite.
+
+## The walkthrough
+
+The full path, one step at a time. Each step says what you do, what you'll see, and why it matters — so you are never typing on faith.
+
+### 1. {{Step name — start with a verb}}
+
+{{What this step does and why, in 1–2 sentences.}}
+
+```bash
+{{command}}
+```
+
+{{What you see, and how you know it worked. Show the expected output — don't make the reader guess.}}
+
+### 2. {{Step name}}
+
+{{Repeat. Number every step. Show the result after each. Call out the one place people slip — inline, right before they would hit it, not in a footnote.}}
+
+### 3. {{Step name}}
+
+{{The final step lands the reader exactly at the goal from "What you get." Close the loop out loud: "You now have {{the outcome}}."}}
+
 ## Reference
 
-| Concept | Where |
-|---------|-------|
-| {{name}} | {{`file:line` or section link}} |
-| Script | `.claude/scripts/{{relevant-script}}.sh` |
-| Template | `text/template-{{template}}.md` |
+Everything you'll look up later, scannable at a glance. **Agents: this is the contract** — exact names, paths, signatures, no prose required.
+
+| Thing | What it is | Where |
+|---|---|---|
+| {{name}} | {{one line}} | {{`file:line` or link}} |
+| {{command / flag}} | {{what it does}} | {{usage}} |
+| Script | {{what it runs}} | `.claude/scripts/{{script}}.sh` |
 
 ---
 
@@ -36,24 +77,48 @@ promise: text/{{slug}}.md
 
 ### Verify it's working
 
+The proof command from PROVE, reusable as a health check. Green here means the feature is live.
+
 ```bash
-# The proof command from the PROVE step — still valid as a health check
+{{the proof command}}
+# Expected: {{the exact passing output}}
 ```
 
-### Common issues
+### When something breaks
 
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| {{symptom}} | {{cause}} | {{fix}} |
+| You see | It means | Do this |
+|---|---|---|
+| {{symptom}} | {{cause}} | {{the exact fix — a command, not advice}} |
 
 ### Rollback
 
-{{What to undo if this needs to be reverted. Specific commands, not vague guidance.}}
+{{The exact way back. Specific commands, in order. The reader is stressed when they reach this section — be precise, be calm, be complete. Leave nothing to infer.}}
+
+## Where to go next
+
+{{1–3 pointers: the adjacent feature, the deeper doc, the thing this unlocks. Leave the reader knowing which door to open next.}}
 
 <!--
-TEACH stop rules (from do.md):
-- Write AFTER PROVE passes (proven: true in frontmatter marks this)
-- Match the promise: every user-facing claim must appear in text/{{slug}}.md
-- Doc + runbook in one file; presence check is: test -f text/{{slug}}-doc.md
-- do-reconcile.sh dictionary on this file before committing (no dead names)
+TEACH template — the doc that brings humans AND agents on a journey.
+
+VOICE — friendly · authoritative · clear · succinct · complete:
+- Talk to one reader. "You", never "the user." Warm, never chatty.
+- Authoritative = you have done this and it works. Show, don't hedge. No "should probably", no "might."
+- Succinct = every sentence earns its place. Cut adverbs. Depth through brevity — see .claude/product-marketing.md.
+- Complete = no step assumed, no command untested, no output unshown. A reader holding ONLY this doc can succeed.
+- Plain English. A CEO and an engineer read the same words. Banned-jargon list lives in .claude/product-marketing.md.
+
+THE JOURNEY — why → what → model → first win → walkthrough → reference → runbook → next:
+- Motivation before mechanics. The reader must WANT it before they learn it.
+- Model before steps. Give the shape; the steps then click into it.
+- A win before the depth. One fast success buys patience for everything after.
+- Every command copy-pasteable and verified. Every step shows its expected output.
+- Two audiences, one doc: humans read the prose top-to-bottom for the journey; agents jump to Reference + Runbook for the contract. Serve both — narrative for the journey, tables for the lookup. Never make a human scan a table for motivation, or an agent read prose for a path.
+
+STOP RULES (from do.md):
+- Write AFTER PROVE passes (proven: true in frontmatter). Proven behavior only — never planned.
+- Match the promise: every user-facing claim appears in text/{{slug}}.md.
+- Doc + runbook in one file. Presence check: test -f text/{{slug}}-doc.md.
+- Run do-reconcile.sh dictionary on this file before committing (no dead names, no new synonyms).
+- Draft with the `tutorial` skill, tighten with the `writer` skill.
 -->

package/templates/template-tests.md

@@ -1,34 +1,34 @@
 ---
 slug: {{slug}}
-surface: {{frontend|api|backend|substrate}}
 cycle: {{C1}}
 folder: {{one.ie/web|packages/sdk|channels}}
+demo:                                  # this file IS the cycle's demo gate — the todo references it by this command
+  command: "bun vitest run {{folder}}/tests/e2e/{{cycle}}.test.ts"
+  asserts: "{{the promise's one proof observable — what passing means}}"
+  budget:  "<2s wall · ≤80 LOC"
 deliverables:
   - {{D1 — what it asserts}}
 ---
 
 # Tests — {{slug}} · {{cycle}}
 
-> One `expect()` per deliverable — assert the destination, not the path.
-> Run: `bun run verify` in `{{folder}}/`
-> Written first (before W3 edits land), verified at W4.
+> One `expect()` per deliverable — **assert the destination, not the path.**
+> The assertion is the promise's proof observable restated as code — nothing new.
+> Write it FIRST: it must **fail before W3 lands (red), pass after (green).**
+> Run: `bun run verify` in `{{folder}}/`.
 
 ## {{D1 — user-facing outcome}}
 
 ```typescript
 import { describe, it, expect } from 'vitest'
-// import { {{thing}} } from '{{path}}'
+// import { {{thing}} } from '{{path}}'   // one import per file — no cross-cycle coupling
 
 describe('{{slug}} · {{deliverable}}', () => {
-  it('{{outcome a user would care about}}', async () => {
-    // arrange
-    // const input = ...
-
-    // act
-    // const result = await ...
-
-    // assert
-    // expect(result).toBe(...)
+  it('{{the outcome a user cares about}}', async () => {
+    const result = await {{run the real thing}}
+    expect(result).toBe({{the destination}})
+    // ✓ destination:  expect(getStrength(edge)).toBe(1)
+    // ✗ not the path: expect(button).toHaveClass('bg-primary')
   })
 })
 ```

package/templates/template-todo.md

@@ -151,11 +151,13 @@ Every artifact reconciles against the canons that apply to its category. Running
 | **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`. Four templates, four phases:
+**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)
+- `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)
 
@@ -185,7 +187,7 @@ match wins; only fall through to "new file" if every layer fails.
 | 2. **Cross-surface composition** | sibling component folders (`chat/`, `crm/`, `cards/`, `in/`, `settings/`) | import + slot — do not copy |
 | 3. **Design primitives** | `web/src/components/ai-elements/`, `web/src/components/ui/` | compose the primitive into a parent; never reimplement |
 | 4. **Library primitives** | `@/lib/`, `@/engine/`, existing hooks | reuse the helper; do not parallel-write |
-| 5. **Skill / rule packs** | `.claude/skills/`, `.claude/rules/` | invoke the existing skill; do not inline its knowledge |
+| 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:**
@@ -337,7 +339,7 @@ Pin shared names, CLI signatures, and design decisions **here**, before drawing
 | 4 | Self-test protocol | `do-reconcile.sh navigation --self-test` exits 0 |
 | 5 | Agent invocation strings | `do-reconcile.sh <canon> <file>` per category |
 | 6 | Shadow → live rename map | `do2-reconcile.sh → do-reconcile.sh` |
-| 7 | Template names | `template-feature.md · template-plan.md · template-todo.md · template-agent.md` |
+| 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 |
 
 **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.
@@ -714,8 +716,8 @@ Report: `delta_tsc=±N  delta_loc=±N  compress_orphans=N  new_files=N  primitiv
 - `text/template-feature.md` — the PROMISE template (PROMISE phase)
 - `docs/relevant-spec.md` — {why relevant to this plan}
 - `src/relevant/file.ts` — {why relevant}
-- `one/dictionary.md` — canonical names (always)
-- `one/rubrics.md` — scoring bands (always)
+- `text/dictionary-plan.md` — canonical names (always)
+- `text/rubrics-plan.md` — scoring bands (always)
 
 ---
 
@@ -777,5 +779,5 @@ nothing in this codebase is built on bare ground.
 
 **context_triggers:**
 - Pattern is matched against W1 findings (file paths + excerpts) — regex, case-insensitive
-- Inject only the *section* you need: `"one/signals.md § Six Verbs"` not the whole file
+- Inject only the *section* you need: `"text/dsl-plan.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