@oneie/claude 0.4.0 → 0.6.0

package/templates/template-feature.md

@@ -1,12 +1,150 @@
 <!--
-TEMPLATE — FEATURE PROMISE. Copy to text/<slug>.md, fill, delete this comment.
-Owner: writer skill. This is the PROMISE phase of /do.
-One file = the marketing copy + the promise that PROVE later checks.
+TEMPLATE — THE PROMISE. Copy to text/<slug>.md, fill, delete this comment.
+Owner: writer skill. This is the PROMISE phase of /do — the FIRST file and the
+GENESIS of the feature. Everything else (-plan, -todo, -docs, tests, code) is
+derived from this file and must reconcile UPWARD to it.
+
+  text/<slug>.md          ← THE PROMISE (this file) — root canon + oracle
+    ├─ text/<slug>-plan.md    (HOW / DESIGN)
+    ├─ text/<slug>-todo.md    (cycles / PLAN — its `outcome:` = this file's `proof:`)
+    ├─ text/<slug>-docs.md    (the full spec — elaborates this promise; the acceptance oracle)
+    └─ tests/<slug>.test.ts   (one assertion per documented observable)
+
+The prose is the marketing copy. The frontmatter is the contract — read it the
+way an engineering agency reads the statement of work it signs with a client:
+`deliverables:` is the exhaustive schedule of what will be delivered, each line
+with its own acceptance check; `proof:` is the acceptance test — the && -join
+of every acceptance check, one command that settles the whole contract;
+`derives:` is the manifest of artifacts this promise spawns (each true key →
+its template, filled at its /do stop by a parallel agent); and `world:` is the
+manifest of runtime the kept promise puts into the substrate — lifecycle,
+workflow, agents, skills, tasks, tracking, routing, views. NO GAPS BY LAW:
+not on the schedule = not promised (write it in "Out of scope") · on the
+schedule = ships or the promise settles broken · acceptance is indivisible
+(all lines together, no partial credit). do-promise-lint.sh enforces the
+schedule ⇄ proof law with zero LLM calls. /do presence-checks world: entries like artifacts: missing
+agent → template-agent.md cycle, missing skill → /skill-creator, missing
+workflow/lifecycle stage → a cycle in the todo, missing view/route → a cycle
+in the todo. "The first file creates the rest" is these blocks, made
+mechanical. The covenant every maker signs into: text/promises.md.
+
+A promise that also settles ON-CHAIN (generated Move contract + terms_hash
+ratchet) uses the SAME template: uncomment the contract: block below and
+follow its comment. Worked example: text/playbook.md.
 -->
 ---
 title: {Human-readable title}
 slug: {kebab-slug}
-type: feature
+type: feature              # this file IS the promise — the genesis contract for the slug
+
+# ─── THE CONTRACT (machine-read by /do) ──────────────────────────────
+# A promise is a contract of what will be made — the statement of work
+# an engineering agency signs with a client. The schedule of
+# deliverables is EXHAUSTIVE, every line carries its own acceptance
+# check, and the one proof is all of them joined. PROMISE writes the
+# terms first; every downstream stop reconciles to them; PROVE settles
+# the contract by re-running `proof`. No gaps: not listed = not
+# promised · listed = ships or the promise settles broken.
+
+deliverables:              # THE SCHEDULE — what will be delivered, enumerated like an
+                           # agency SOW. Exhaustive by law: an item not on this list is
+                           # NOT promised (name it under "Out of scope" in the body); an
+                           # item on this list ships or the WHOLE promise settles broken.
+                           # Acceptance is indivisible — every line together, no partial
+                           # credit, nothing between the lines. 3–9 items is typical;
+                           # if you can't enumerate the delivery, you're not ready to
+                           # promise. Linted: do-promise-lint.sh <slug>.
+                           # PAGE-PROOF LAW: any user-visible item needs a route/component
+                           # row whose accept: loads the page — e.g.
+                           # `bash .claude/scripts/do-prove.sh --route /x` — enforced by
+                           # do-promise-lint.sh (grep/tsc alone can pass while the page 500s).
+  - item: "{one concrete thing the client receives — a route, a component, a doc, a wire}"
+    accept: "{bash — exits 0 ONLY when this item is delivered AND wired, not merely present}"
+  # - item: "{next deliverable}"
+  #   accept: "{its own check}"
+
+assumes: []                # CLIENT-SIDE DEPENDENCIES — what must already be true for the
+                           # schedule to be deliverable, one bash check per line. GREEN AT
+                           # PROMISE (the inverse of proof): a failing assumption means the
+                           # contract can't be signed yet; one that goes false mid-build
+                           # forces a renegotiation (a NEW promise), never a silent gap.
+
+proof: ""                  # THE ACCEPTANCE TEST — derived, not authored: the && -join of
+                           # every deliverable's accept:, verbatim, in schedule order:
+                           #   proof = accept₁ && accept₂ && … && acceptₙ
+                           # ONE command settles the contract (do-promise-settle.sh runs
+                           # exactly this); the schedule above makes it exhaustive BY
+                           # CONSTRUCTION — an accept: missing from the proof, or an item
+                           # with no accept:, fails do-promise-lint.sh. It still BECOMES
+                           # the todo's `outcome:`, the TEST assertion, and the PROVE
+                           # oracle — named once, here, never restated loosely.
+                           # RED BEFORE GREEN: at PROMISE this must EXIT NON-ZERO (the thing isn't
+                           # built yet). It goes green only at PROVE. Green at PROMISE = already
+                           # shipped (skip) or too weak to gate (rewrite it).
+
+derives:                   # the artifacts this promise spawns. /do backfills each down the spine
+                           # instead of re-deciding at DESIGN. true = spawn · false = skip.
+  plan:      true          # text/<slug>-plan.md      — HOW (DESIGN)   — spine, always
+  todo:      true          # text/<slug>-todo.md      — cycles (PLAN)  — spine, always
+  docs:      true          # text/<slug>-docs.md      — spec + oracle (DOCS) — spine, always
+  tests:     true          # tests/<slug>.test.ts     — one assert / observable (TEST) — spine, always
+  features:  false         # text/<slug>-features.md  — WHAT — set true if scope spans ≥3 capabilities
+  ui:        false         # text/<slug>-ui.md        — screens/states — DEFAULT true whenever world: names views,
+                           # lifecycle stages, inbox spaces, or any route; false only with a stated reason
+                           # (mirror the engine's {"surface":"none","reason":…} escape)
+  tutorial:  false         # text/<slug>-tutorial.md  — set true if there's a first-success worth its own page
+  how-to:    false         # text/<slug>-how-to.md    — set true if ≥2 recurring tasks users repeat
+  reference: false         # text/<slug>-reference.md — set true if the spec is too detailed for -docs.md
+  agents:    false         # text/<slug>-agents-docs.md — set true if agents call this feature's receivers
+
+rubric:                    # THE QUALITY CONTRACT — W4 scores every cycle against these
+                           # floors; the composite gates the cycle (≥ 0.65 AND goal-fit
+                           # ≥ 0.50) and becomes the mark() amount on this promise's path —
+                           # quality compounds, not completion.
+  security:    0.65        # secrets never land, authority walk intact, IDOR-guarded
+  stability:   0.65        # ratchet held — tsc delta ≤ 0, tests green, must_not_break preserved
+  simplicity:  0.65        # net-new primitives ≤ 0 — compose 3 existing before adding 1
+  speed:       0.65        # cheapest tool that decides; token ceiling respected; lean diff
+  integration: 0.65        # wired, never orphaned — nav/SDK/MCP/CLI/docs synced; scored
+                           # deterministically from .w2-surface-checklist.json + do-reconcile.sh
+
+# ── ON-CHAIN (optional) — uncomment to mint + settle this promise on Sui:
+# fill the block, run `bun pay/tools/promise-chain.ts mint <slug>` at PROMISE;
+# /close's do-promise-settle.sh then drives both settles.
+# Deep-dive: text/do-promise.md. ──
+# contract:
+#   object:      Promise     # generated: schema/sui.tql `promise` → substrate.move — never hand-written
+#   disposition: shared      # @sui:shared — maker + world both settle (owned = solo fast path · frozen = immutable once kept)
+#   terms_hash:  "sha256(text/<slug>.md @ PROMISE)"  # the prose frozen at genesis — PROVE checks against THIS hash
+#   settle:      proof       # PROVE runs `proof`: exit 0 → settle_promise(kept=true, k), strength += k (mark);
+#                            # non-zero → kept=false, resistance += k (warn). assert!(state < 3) = the on-chain ratchet.
+#                            # The off-chain `proof:` above IS the settlement condition — one source.
+#   object_id:   ""          # on-chain handle — written back by the mint
+#   maker:       ""          # Sui address that promised — filled at mint
+#   oracle:      ""          # Sui address that attests — distinct from maker; set PROMISE_ORACLE=0x… before
+#                            # minting or the tool refuses (exit 5); --self-oracle for fixtures/local only
+
+world:                     # the runtime the kept promise puts into the world —
+                           # /do presence-checks each entry and backfills the gaps
+  lifecycle: []            # "{stage} → {stage}: the move + the signal that records it"
+  workflow:  []            # "{kind}: …" — kinds (LOCKED): trigger·tool·skill·agent·condition·human·delay·sell
+  agents:    []            # { name, subscribes: [tags] } — the tags are the stake (routing + inbox Space)
+  skills:    []            # "{skill}: what it lets an agent do"
+  tasks:
+    tags: ["slug:{slug}"]  # the todo enters the world as a tagged weighted signal
+  tracking:
+    marks: []              # signals that prove it works — strengthen the path
+    warns: []              # signals that prove it doesn't — add resistance
+  routing:   []            # "{from}→{to}: what a high strength here routes next"
+  views:     []            # "{view-kind}: what this promise shows there" — where the
+                           # kept promise becomes VISIBLE. Kinds from the view registry
+                           # (one.ie/web/src/lib/views/registry.ts), reached by the
+                           # order-free traversal (lib/navigation.ts resolvePath — any
+                           # {dept, view} permutation lands on the same cell). Presence-
+                           # checked like every entry above: view kind or route missing
+                           # → a cycle in the todo; present → skip. Worked example:
+                           # text/view-coverage.md.
+# ─────────────────────────────────────────────────────────────────────
 ---
 
 # {Title}
@@ -21,7 +159,24 @@ type: feature
 {One sentence — the delta. "Before: {friction}. After: {flow}."}
 
 ## The promise (PROVE checks this)
-{One paragraph — concrete enough to prove. What the user sees, clicks, or gets back. Specific nouns. No hedging.}
+{One paragraph — concrete enough to prove. What the user sees, clicks, or gets back. Specific nouns. No hedging. The schedule below is the whole delivery; the exclusions after it are the whole "no".}
+
+## The deliverables (the schedule of work)
+
+{Read this like the statement of work an agency signs. One row per `deliverables:` line — the same items, in the client's words. Anything not in this table is not promised.}
+
+| # | Deliverable | Accepted when |
+|---|---|---|
+| 1 | {the thing delivered} | {its `accept:` check, in words} |
+
+**Completeness clause:** this schedule is exhaustive and acceptance is indivisible — every line delivered and green together, or the promise settles broken. No partial credit, no "mostly done", nothing between the lines.
+
+## Out of scope (excluded, in writing)
+
+{Enumerate the adjacent things this promise deliberately does NOT deliver — every line a client might otherwise assume in. One line each: "Not this: {thing} — {where it lives instead, if anywhere}." An ambiguity that isn't on the schedule and isn't listed here is a drafting bug in the promise.}
+
+## The proof (the acceptance test the whole spine points at)
+{The `proof:` command in words — the && -join of every deliverable's acceptance check. True only if every line of the schedule shipped. 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

@@ -1,8 +1,12 @@
+status: ACTIVE
+
 <!--
 TEMPLATE — DESIGN PHASE. Copy to text/<slug>-plan.md, fill, delete this comment.
 Owner: Opus · high (the decider — never delegated). Skills: typedb, signal where the
 substrate is touched. This is the DESIGN phase of /do (see text/do-refined.md).
 Runs AFTER PROMISE (text/<slug>.md) and SURVEY, BEFORE the plan (text/<slug>-todo.md).
+Spawned by the promise's derives.plan at DESIGN — it designs the promise's gap
+list (only the gap gets designed) and reconciles upward to text/<slug>.md.
 -->
 
 ---
@@ -12,20 +16,29 @@ type: plan
 tier: {trivial | simple | complex}
 source_of_truth:
   - text/{feature}.md          # the promise this design must keep
-  - text/dictionary-plan.md        # canonical names — reconcile against this
+  - text/dictionary.md        # canonical names — reconcile against this
   - schema/one.tql             # only if the substrate is touched
 ---
 
 # {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)
 
 {expose | extend | build | drop} — {what already exists, what the real gap is. Only the gap gets designed.}
 
+## Evidence (verified, dated)
+
+Every claim this design makes about existing code carries `file:line` proof, verified on the day of writing — never recalled from memory or a previous plan. A claim without a citation is a guess; a stale citation is worse than none. State what was checked and what it showed:
+
+| Claim | Status | Evidence |
+|---|---|---|
+| {what the design assumes exists / is absent} | ✅ shipped / ❌ gap | `{path}:{line}` — {one clause of what's there} |
+
 ## Design
 
 ### Data shape
@@ -40,10 +53,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)
+
+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.
 
-- [ ] Names exist in `dictionary.md` (no dead names)
-- [ ] No new dimension / verb / type — or one-sentence justification: {…}
+- [ ] **dictionary** — names exist in `text/dictionary.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
+<!-- Spawned by the promise's derives.docs — authored at DOCS as the spec, validated at TEACH after PROVE passes, so every claim below ends proven, never planned. Reconciles upward to the promise (text/{{slug}}.md) — 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 readers 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}}-docs.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,36 @@
 ---
 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.
+> Spawned by the promise's derives.tests at TEST — before code.
+> One `expect()` per documented observable — **assert the destination, not the path.**
+> The FIRST assertion is the promise's `proof:` restated as code — nothing new
+> (if `proof:` needs a live surface, note here that PROVE's oracle asserts it).
+> 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')
   })
 })
 ```