@oneie/claude 0.6.0 → 0.7.0

package/skills/typedb/examples/python-patterns.py

@@ -1,6 +1,13 @@
 """
-TypeDB 3.x Python Driver Patterns
-Complete examples for TypeDB Python SDK
+TypeDB Python Driver Patterns — upstream reference only.
+
+NOTHING IN THIS MONOREPO USES THE PYTHON DRIVER. There is no `typedb-driver`
+dependency anywhere. The real Python path is `backup/scripts/typedb/dump.py`
+and `replay.py`, which speak the `/v1/` HTTP API through `urllib`, and the
+TypeScript path is `one.ie/web/src/lib/substrate.ts` -> `api/src/index.ts`.
+Keep this file for reading upstream docs; do not model new code on it.
+
+Server: TypeDB 3.12.1 (prod and local, since 2026-07-29).
 """
 
 import os
@@ -34,7 +41,7 @@ def connect_cloud():
     credentials = Credentials("admin", os.environ["TYPEDB_PASSWORD"])
     options = DriverOptions(is_tls_enabled=True)
     return TypeDB.driver(
-        "https://cluster.cloud.typedb.com:80",
+        "https://flsiu1-0.cluster.typedb.com:1729",  # port 1729, never :80
         credentials,
         options
     )
@@ -581,7 +588,7 @@ def main():
     options = DriverOptions(is_tls_enabled=True)
 
     with TypeDB.driver(
-        "https://cluster.cloud.typedb.com:80",
+        "https://flsiu1-0.cluster.typedb.com:1729",  # port 1729, never :80
         credentials,
         options
     ) as driver:

package/skills/typedb/examples/query-patterns.tql

@@ -1,5 +1,9 @@
-# TypeQL 3.0 Query Patterns
-# Common patterns for TypeDB 3.x queries
+# TypeQL Query Patterns — TypeDB 3.12.1 (prod + local, 2026-07-29)
+# Generic teaching schema (user/friendship/employment), NOT the ONE substrate.
+# For real substrate queries use schema/*.tql — see SKILL.md 'In-repo'.
+# Syntax notes: no if/then/else expression; `return first <literal>` is a
+# TQL0 error (bind a `let` first); stream returns are `-> { type }`, never
+# `-> { $v: type }`; iterate a stream with `let $x in f(...)`.
 
 # ============================================================================
 # SCHEMA DEFINITION PATTERNS
@@ -407,7 +411,8 @@ select $friend, $age;
 with
     fun is_adult($u: user) -> boolean:
         match $u has age $a; $a >= 18;
-        return first true;
+        let $ok = true;    # `return first true` is a TQL0 syntax error
+        return first $ok;
 match
     $u isa user;
     let $adult = is_adult($u);

package/skills/typedb/examples/schema-patterns.tql

@@ -1,5 +1,7 @@
-# TypeQL 3.0 Schema Patterns
-# Common schema design patterns for TypeDB 3.x
+# TypeQL Schema Patterns — TypeDB 3.12.1 (prod + local, 2026-07-29)
+# Generic teaching schema, NOT the ONE substrate. schema/one.tql is canon.
+# UNVERIFIED on 3.12.1 anywhere in this repo: struct, value string[], @index,
+# @cascade, @subkey — zero occurrences in schema/*.tql and in the live dump.
 
 # ============================================================================
 # BASIC ENTITY PATTERNS

package/skills/typedb/reference/migration-2x-3x.md

@@ -1,6 +1,24 @@
 # TypeDB 2.x to 3.x Migration Reference
 
-> Complete guide for migrating from TypeDB 2.x to 3.x
+> Complete guide for migrating from TypeDB 2.x to 3.x.
+>
+> **Why this file still earns its place, and how to read it.** Nobody here is
+> migrating a 2.x database — this repo has always been 3.x, and prod + local
+> both run **3.12.1**. Its value is as the **rule→fun translation guide** and
+> the *"why does this old snippet not work"* lookup: 2.x TypeQL is all over
+> the public internet, older blog posts, and LLM training data, so the failure
+> mode it prevents is real and recurring. `SKILL.md` used to point at
+> `packages/typedb-inference-patterns/` for that translation; **that directory
+> does not exist**, which leaves this file as the only place it lives.
+>
+> Read the "2.x" blocks as *things you will encounter and must reject*, never
+> as things to run. The rule→fun section here is the mechanical table; the
+> worked, live-verified examples are in `SKILL.md` § *Inference Rules
+> (Emergence Patterns)*.
+>
+> Two corrections to apply as you read: `return first true` and any
+> `if … then … else` expression are **rejected on 3.12.1** — bind a `let`
+> first. See `SKILL.md`'s VERIFIED table.
 
 ---
 

package/skills/typedb/reference/python-driver.md

@@ -1,6 +1,22 @@
 # TypeDB Python Driver Reference
 
-> Complete Python driver patterns for TypeDB 3.x
+> Complete Python driver patterns for TypeDB 3.x.
+>
+> **Nothing in this monorepo uses the Python driver.** There is no
+> `typedb-driver` dependency in any `package.json`, `requirements.txt` or
+> `pyproject.toml`. Both real access paths speak the **`/v1/` HTTP API**:
+> `one.ie/web/src/lib/substrate.ts` → `api/src/index.ts` (TypeScript), and
+> `backup/scripts/typedb/{dump,replay}.py` (Python via `urllib`). Load this file
+> when reading upstream TypeDB documentation or evaluating the driver — not as a
+> model for new code here.
+>
+> Server is **3.12.1** (prod and local, since 2026-07-29). The driver API
+> surface below is transcribed from upstream docs and has **not** been
+> exercised against 3.12.1 from this repo. Where it disagrees with
+> `SKILL.md`'s VERIFIED table, the VERIFIED table wins — it was probed live.
+>
+> Ports: this repo's prod endpoint is `:1729`, local is `:8000`. Ignore the
+> `:80` in upstream connection snippets.
 
 ---
 

package/skills/voice/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: voice
+description: Write in Anthony O'Connell's voice. Use whenever prose will go out under Anthony's or ONE's name and must sound like him, not like a generic assistant — books, essays, whitepapers, manifestos, blog posts, landing-page and marketing copy, founder updates, social posts, newsletters, client emails, playbook chapters, README and doc prose, or any rewrite where the note is "this doesn't sound like me". Its first job is picking the register: book/essay (patient, observational, no visible author, never sells) or commercial (first person, receipts, product names, sells). Invoke AFTER `writer` (craft) and alongside `product-marketing.md` (product context). Triggers — "write this in my voice", "in Anthony's voice/tone", "make it sound like me", "this reads like AI", "too corporate", "sounds generic", "write the book/chapter/essay/whitepaper", "write the blog post/landing page", "rewrite this properly".
+---
+
+# voice — Anthony O'Connell's register
+
+He writes in two registers. **Picking the right one is this skill's main job**, and getting it wrong is the most expensive mistake available — the two contradict each other on narrator, on selling, and on whether jokes exist.
+
+---
+
+## Step 1 — pick the register
+
+| Writing this | Register | Read |
+|---|---|---|
+| book · book chapter · essay · whitepaper · manifesto · long-form thought | **Book** | `text/voice-and-tone.md` — **complete, stop there** |
+| landing page · blog post · promise (`text/<slug>.md`) · client email · social · newsletter · playbook chapter · doc prose | **Commercial** | `text/writing-style-guide.md` Parts 1, 3–8 + `.claude/product-marketing.md` |
+| unsure | **Ask one question:** does it sell anything, and does it have a narrator? Both no → book. Either yes → commercial. |
+
+The registers differ on five load-bearing points. Do not blend them:
+
+| | Book | Commercial |
+|---|---|---|
+| "I" / "we" | **never** — no visible author | yes |
+| Sells | **never** | yes, that's the job |
+| Product / company names | **never** | yes |
+| Code, file paths | **never** | yes, and always real |
+| Headings inside a piece | **never** | yes |
+
+Everything else — observe don't assert, specific numbers or none, short sentences, one-sentence paragraphs, never lecture, never apologise, never overreach, recognition not awe — holds in both. Those universals are Part 1 of the style guide.
+
+---
+
+## Step 2 — the sources, in order of authority
+
+1. **`text/voice-and-tone.md`** — the specification. **Authored by Anthony.** Vendored from `apps/ants/docs/book/files/01-voice-and-tone.md`; edit the original, re-vendor here. Demonstrated across 96,540 words in `apps/ants/docs/book/manuscript/`. **Senior to everything else. Where anything disagrees with it, it wins.**
+2. **`text/writing-style-guide.md`** — derived. Splits universal from book-only, and documents the commercial register the spec doesn't cover.
+3. **`.claude/product-marketing.md`** — product context: offer, audience, thesis, the measured-numbers table. Commercial only.
+
+Read the whole of the relevant source when the piece is long-form, when it's the first piece in a new format, or when the user's note is about voice. For a short piece in a format you've already done this session, the checklists below are enough.
+
+---
+
+## The sentence test (both registers)
+
+> *Would a careful, slightly amused, very patient person, who is in no hurry to convince anyone of anything but who has noticed something important, write this sentence?*
+
+If it performs urgency, expertise, contrarianism, or aspiration — rewrite it.
+
+**He does not joke.** *"It is amused, but never sarcastic … The voice does not joke."* There is dry pleasure at a pattern recurring where nobody expected it. There is no comedy, no snark, no bit. If a draft is being funny, it is not being him.
+
+---
+
+## Book-register checklist
+
+- [ ] **Opens on a scene** — a place, a person, a moment, a number. Never on an argument.
+- [ ] **No "I", no editorial "we", no visible author.** The camera is there; the camera is not the subject.
+- [ ] **Observes; does not assert.** "The intelligence was not in any of the ants," not "intelligence is a property of substrates."
+- [ ] **Sells nothing.** Names no company, product, or technology. Quotes no code.
+- [ ] **No subheadings.** A horizontal rule may mark a shift in scene or scale, once or twice.
+- [ ] **Specific numbers, or honest hedging** (*on the order of*, *approximately*). Never false specificity.
+- [ ] **Never defines a technical term** — makes its meaning land through use.
+- [ ] **Closes on a short concrete sentence** the reader carries, often a recontextualised return to the opening.
+- [ ] **Passes both the "your mum" and the "Demis Hassabis" test.**
+- [ ] **The emotion is recognition, not awe.** No "this changes everything."
+
+## Commercial-register checklist
+
+- [ ] **Em dashes: 3 or fewer.** Count them.
+- [ ] **Every quality adjective replaced by a number** — or the claim cut, or the gap stated.
+- [ ] **No fabricated proof.** Every metric, quote, logo, benchmark, file path real or marked unproven.
+- [ ] **Speed claims carry a measured number** from `product-marketing.md`'s table.
+- [ ] **Opens with a scene or an orthodoxy, not the thesis.**
+- [ ] **Closes on a verdict with its shadow** — name what's still broken. No "In conclusion."
+- [ ] **No hedging, no throat-clearing.** (Honest uncertainty stated precisely is not hedging.)
+- [ ] **Snark aimed at systems, never people.**
+- [ ] **Substrate jargon stripped** from customer-facing copy — no `signal`, `mark`, `warn`, `path`, `substrate`. Customer's words instead.
+- [ ] **Pub test** — read the cleverest sentence aloud. If you'd wince, cut it.
+- [ ] **Status claims are true** — built means built, armed-red means armed-red.
+
+---
+
+## The five commercial moves
+
+| Move | Example |
+|---|---|
+| **"X, not Y"** | "The threat model is a table, not a promise." |
+| **The physics reframe** | "This is not a buyer problem. It is a physics problem." |
+| **The uncomfortable truth** | "Here's the part nobody in marketing wants to say out loud …" |
+| **Receipts, not adjectives** | "11 interactions, 55 to 65 seconds, plus DNS wait." |
+| **The unpaid-debt close** | end on what's still broken, unresolved |
+
+The uncomfortable-truth move is not contrarianism and not a hot take — the spec forbids performing either. It works because it is a conclusion reached reluctantly and reported flatly.
+
+---
+
+## The stack
+
+```
+1. writer                    craft    — draft, cut, structure, polish
+2. voice  (this skill)       register — pick one, then apply it
+3. product-marketing.md      context  — offer, audience, measured numbers (commercial only)
+4. docs                      taxonomy — only for text/*.md doc types
+```
+
+`writer` decides whether the sentence works. `voice` decides whether it's his. When they disagree, `voice` wins.
+
+---
+
+## Don't
+
+- **Don't blend the registers.** A book chapter that names a product, or a landing page with no narrator, is the failure this skill exists to prevent.
+- **Don't make him funny.** His own spec rules it out. Warmth is not comedy.
+- **Don't invoke this instead of `writer`** — invoke it after. Craft first, register second.
+- **Don't apply it to internal specs, TypeQL, migrations, or commit messages.** Those have their own registers and this one makes them worse.
+- **Don't edit `text/voice-and-tone.md`.** It's a vendored copy. Edit `apps/ants/docs/book/files/01-voice-and-tone.md` and re-vendor.
+- **Don't invent biography.** If a beat wants lived experience that isn't on record, use a corpus example or mark it constructed.

package/skills/writer/SKILL.md

@@ -25,6 +25,22 @@ Every piece of writing — long or short — goes through this loop:
 
 If time is short, skip steps 5 and 6 and ship. Steps 1–4 are non-negotiable.
 
+**Writing under Anthony's or ONE's name?** Invoke the `voice` skill. It picks
+between his two registers — the book register
+([`text/voice-and-tone.md`](../../../text/voice-and-tone.md), his own writing
+specification) and the commercial register
+([`text/writing-style-guide.md`](../../../text/writing-style-guide.md)).
+
+**Order depends on the register.** For commercial work, run this loop first, then
+`voice`. For **book** work, invoke `voice` first and use this skill only for
+sentence-level polish — step 3 above ("aim to halve the word count") and step 4
+("move the strongest point to the top") are wrong for that register, which is
+paced to walk at the reader's pace and never leads with its thesis. Applying
+them to a chapter turns it into a landing page.
+
+This skill decides whether the sentence works; `voice` decides whether it's *his*.
+When they disagree, `voice` wins.
+
 ---
 
 ## Step 0: Audience, medium, goal
@@ -307,30 +323,31 @@ But: when in doubt, shorter. Almost no one ever wishes a piece of writing were l
 
 ## Project-specific voice
 
-Two voice documents layer on top of this skill. Read both before writing anything here.
+Voice documents layer on top of this skill. **Which ones you read is the `voice`
+skill's decision, not this one's** — it picks the register first, and the book
+register reads `text/voice-and-tone.md` and stops there. Don't preload all of
+them.
 
-**Personal essays, blog posts, tech pieces, opinion writing:**
-[`text/writing-style-guide.md`](../../../../text/writing-style-guide.md) — Anthony's
-personal writing style. Dry, sardonic, technically grounded. The sensibility
-(does this tool serve the work, or has it started serving itself?), the
-typography fingerprint (trailing ` …`, the em-dash ration, scare-quotes,
-capitalized Concepts), the sentence rhythm (punch / carrier / escalating list),
-and the recurring beats (received-wisdom turn, forensic descent, two-camps
-dismissal). This is the default voice for any personal piece. Apply it always.
+**Commercial register — blog posts, landing pages, client email, social, docs prose:**
+[`text/writing-style-guide.md`](../../../text/writing-style-guide.md) — the
+derived guide. The sensibility (does this tool serve the work, or has it started
+serving itself?), the typography fingerprint (trailing ` …`, the em-dash ration,
+scare-quotes, capitalized Concepts), the sentence rhythm (punch / carrier /
+escalating list), and the recurring beats (received-wisdom turn, forensic
+descent, two-camps dismissal).
 
 **Marketing, product, and landing-page copy:**
 [`/.claude/product-marketing.md`](../../product-marketing.md) — ONE's brand voice.
 Audience (CEOs + engineers), the speed/ease/simplicity thesis, banned vocabulary,
-headline patterns, and the data rule. Layers on top of the personal voice for
+headline patterns, and the data rule. Layers on top of the style guide for
 anything that ships as ONE copy.
 
 ---
 
 ## Reference files
 
-- `text/writing-style-guide.md` — **Always read.** Anthony's personal writing voice: sensibility, typography fingerprint, sentence rhythm, recurring beats, vocabulary bank, anti-patterns, worked examples.
+- `text/writing-style-guide.md` — the commercial register: sensibility, typography fingerprint, sentence rhythm, recurring beats, vocabulary bank, anti-patterns, worked examples. Read it when `voice` picks commercial; for the book register `voice` sends you to `text/voice-and-tone.md` instead.
 - `references/anti-patterns.md` — A longer catalogue of clichés, AI-prose tells, and corporate jargon to avoid, with replacements. Read this when editing marketing or corporate copy where the user wants to sound less like a press release.
-- `references/voice-matching.md` — How to read a writer's voice from sample text and match it. Read this when ghostwriting or editing on someone else's behalf.
 - `references/structures.md` — Concrete templates for common pieces (essay openings, founder updates, landing page sections, cold emails). Read this when the user asks for a format you want to handle well.
 - `references/copy-frameworks.md` — The canon: ten headline frameworks (JTBD, PAS, BAB, outcome+timeframe, hard-thing-without-pain, plain truth, numbered nouns, category-for-audience, Dunford positioning, attributed quote) with when-to-use, examples, traps; the specificity and sensory rules; the seven biases (anchoring, loss aversion, social proof, authority, reciprocity, scarcity, decoy) and which frameworks recruit which. Read this when writing or rewriting landing pages, pricing pages, hero sections, or any headline that has to convert.
 

package/templates/template-feature.md

@@ -81,6 +81,22 @@ proof: ""                  # THE ACCEPTANCE TEST — derived, not authored: the
                            # 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).
+                           #
+                           # THREE EXIT CODES, NOT TWO. A check that can only say ok/failed will
+                           # report an outage as a broken promise:
+                           #   0  ok         — the thing is built and behaves
+                           #   1  RED        — the thing is genuinely missing or wrong
+                           #   3  CANNOT RUN — the check could not reach its evidence (cluster
+                           #                   down, no creds, network gone). NOT a red.
+                           # Exit 3 must be distinguishable, because red and cannot-run send a
+                           # human to opposite places: red means fix the build, cannot run means
+                           # fix the environment. A board that paints cannot-run as failure will
+                           # send someone to re-scope a correct migration. Make each accept:
+                           # exit 3 when its evidence is unreachable, and say WHY in one line.
+                           # And when the armed check goes red, confirm it is red for the RIGHT
+                           # reason — a proof that false-fails on a dialect artifact or a missing
+                           # binary gates nothing (recorded: a bare `node --check` that could
+                           # never pass, so the kill-switch was decorative).
 
 derives:                   # the artifacts this promise spawns. /do backfills each down the spine
                            # instead of re-deciding at DESIGN. true = spawn · false = skip.
@@ -91,11 +107,20 @@ derives:                   # the artifacts this promise spawns. /do backfills ea
   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)
+                           # (mirror the engine's {"surface":"none","reason":…} escape). When true, this
+                           # promise's proof: MUST invoke `bash .claude/scripts/do-ui-gate.sh <slug>` —
+                           # do-promise-lint.sh's ui-coupling check enforces it, so a UI-bearing promise
+                           # can't settle without its ```ui fence rows (text/template-ui.md) actually
+                           # being gate-checked.
   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
+  walk:      false         # text/<slug>-humans.md + text/<slug>-agents.md — the deterministic verification
+                           # walk (do-walk.sh); DEFAULT true whenever ui: is true or any route ships —
+                           # one stop per deliverables: row, agents-mode asserts reuse the accept: checks
+  lifecycle: false         # text/<slug>-lifecycle.md — the end-to-end journey for both audiences;
+                           # set true when world: names lifecycle stages, workflow steps, or ≥2 surfaces
 
 rubric:                    # THE QUALITY CONTRACT — W4 scores every cycle against these
                            # floors; the composite gates the cycle (≥ 0.65 AND goal-fit

package/templates/template-tests.md

@@ -40,6 +40,10 @@ Rules (from do.md testing policy):
 - ≤1 test file per cycle
 - Goal-based: assert shipped outcome, not implementation detail
 - Vitest-first; add requires_playwright: true in todo frontmatter if browser needed
+- UI states: if the cycle has a text/<slug>-ui.md, EVERY row of its component-states
+  table gets a render test (vitest + @testing-library — empty/loading/error/populated),
+  and the todo outcome includes `do-prove.sh --route <path>` per route in the -ui.md's
+  Proof section. A table row with no test is a build gap.
 - N-variant split-test → winner mark(), losers warn(0.5)
 - One import per test file (avoid cross-cycle coupling)
 -->

package/templates/template-todo.md

@@ -2,7 +2,15 @@
 title: {Human-readable title}
 slug: {kebab-slug}
 type: plan
-tier: simple               # trivial | simple | complex  — /do reads this before W0
+tier: feature              # PATCH | FIX | FEATURE | SCHEMA — the SPINE tier. /do reads this
+                           # before W0 to prune the spine (do.md § "The pruned spine by tier").
+                           # This is the vocabulary do-tier.sh emits; case-insensitive here.
+classifier: complex        # trivial | simple | complex — the BUILD classifier (how much
+                           # machinery W0-W4 runs INSIDE a cycle). A SEPARATE AXIS from tier:.
+                           # Conflating the two is the recorded root cause of 157 plans
+                           # carrying `tier: complex` — a BUILD classifier in a field /do
+                           # resolves the spine from. Spine tier answers "which stops run";
+                           # classifier answers "how heavy is each cycle". Set both.
 mode: construction         # discovery | construction | evolution | maintenance
 tags: []                   # drives pheromone routing + W2 context triggers
 priority: 0                # 0 none · 1 should · 2 important · 3 critical — human override; do-rank.py reads it
@@ -27,14 +35,24 @@ depends_on: []             # [other-slug, …] — plans that must be DONE befor
 
 goal: ""                   # ONE sentence — what becomes true that wasn't before. Not "ship X" but "user can do Y" or "system enforces Z".
 outcome: ""                # ONE bash command — exits 0 = goal achieved. Re-runs after every batch's W4. The kill-switch.
+                           # If the plan ships anything user-visible, this command MUST include a page-load proof —
+                           # e.g. `bash .claude/scripts/do-prove.sh --route /x && <other checks>`. grep/tsc alone
+                           # can pass while the page 500s or the code is dead.
 outcome_asserts: ""        # ONE sentence — what passing the outcome command proves (human-readable).
 
 deliverables:              # Concrete artifacts that ship. Every entry maps to a cycle. If it isn't here, it doesn't ship.
-  # - {route|component|cli-verb|api|migration|doc}: {path} — {what the user sees / can do}
-  # Example:
-  # - route: /chat/memory — user can read & edit company memory inline
-  # - api:   POST /api/memory/upsert — agent writes memory facts
-  # - cli:   one memory add — operator writes memory facts from terminal
+  # LAW — user-visible feature ⇒ must include a route/component row whose accept loads the page (do-prove.sh --route /path)
+  # QUOTE EVERY VALUE. The value is prose, and prose contains `:`, backticks, `{`, `#` and
+  # `—` — every one of which is YAML syntax. An unquoted entry parses as a nested mapping
+  # or dies outright, and nothing warns you: /do survives today only because do-rank.py
+  # hand-rolls a regex parser instead of using YAML. 101 of 292 filled *-todo.md files in
+  # this repo already fail to parse. factory-check.sh templates asserts that count never
+  # RISES — it is a ratchet, not a cleanup.
+  # - {route|component|cli-verb|api|migration|doc}: "{path} — {what the user sees / can do}"
+  # Example (note: every value quoted, colons and backticks safe inside):
+  # - route: "/chat/memory — user can read & edit company memory inline"
+  # - api:   "POST /api/memory/upsert — agent writes memory facts"
+  # - cli:   "one memory add — operator writes memory facts from terminal"
 
 ux_before: ""              # ONE sentence — what the user does TODAY (the current journey, friction included).
 ux_after: ""               # ONE sentence — what the user does AFTER this plan ships (the new journey).
@@ -62,7 +80,20 @@ batches:                   # plan-level cycle DAG, flattened into batches.
   # Cycles inside the same batch run their waves IN PARALLEL.
   # The next batch fires the moment the previous batch's W4 closes.
   # Empty list → /do auto-derives from the cycle-level arrows below.
-  - [C1]                   # batch 1: foundation
+  #
+  # DOCS GO IN BATCH 1, NOT LAST. `.claude/rules/documentation.md` is explicit:
+  # the doc set is authored at the DOCS stop, BEFORE any code, and the tests are
+  # drawn from it. Scheduling `<slug>-docs.md` as the final cycle inverts that —
+  # the code decides what the doc says, and the acceptance oracle ends up written
+  # by the thing it is supposed to judge. Author the docs in batch 1; keep a
+  # separate, narrower closing cycle that RECONCILES them to what shipped. Two
+  # different jobs: one writes the oracle, the other closes drift.
+  #
+  # An arrow into the docs cycle is almost always imaginary — a doc cycle reads
+  # the promise, not another cycle's output. Same test as every other arrow:
+  # name the file the later cycle reads that the earlier one writes, or delete
+  # the edge. "We'll know more after C4" is W2 learning, not a file dependency.
+  - [C1]                   # batch 1: foundation + the doc set (the spec)
   - [C2, C3, C4]           # batch 2: independent siblings (concurrent)
   - [C5]                   # batch 3: composes C1-C4
   - [C6]                   # batch 4: polish across all
@@ -73,6 +104,7 @@ shared_recon:              # files /do reads ONCE at plan start (W0.5), shared b
 # ─────────────────────────────────────────────────────────────────────
 
 source_of_truth:           # ≤5 files — W2 auto-loads; only files that actually exist
+                           # any plan with a cycle whose surface ≠ none MUST list text/<slug>-ui.md here
   - docs/relevant-spec.md
   - src/relevant/file.ts
 existing_primitives:       # the components/libs this plan composes — NEVER reimplement these
@@ -376,7 +408,7 @@ Reject any of these as reasons to add an arrow or move cycles to later batches:
 
 ## Surface checklist contract (W2 output)
 
-W2 must fill in `.w2-surface-checklist.json` for every new route/page/component:
+`.w2-surface-checklist.json` is **mandatory every cycle** — not just cycles that add routes. Either it lists the surface layers (routes, components, nav, inbound links, states) or it explicitly declares `{"surface": "none", "reason": "<why this cycle ships nothing user-visible>"}`. A missing file = W2 incomplete. For every new route/page/component the entry looks like:
 
 ```json
 {
@@ -501,6 +533,8 @@ Plan close
 
 **UX delta:** {ONE sentence — what the user can do after this cycle that they couldn't before. "Operator now sees company memory in the chat sidebar." If "no user-visible change," say so explicitly — internal-only cycles must justify why they ship before a user-visible one.}
 
+**Surface:** {`/route` | `component:<Name>` | `none({reason})` — the user-visible surface this cycle ships; W2 copies this verbatim into `.w2-surface-checklist.json` (none requires the reason)}
+
 **Cycle outcome:** {verifiable — bash command / test name / API shape / Lighthouse score}
 
 ✓ valid: "`bun run verify` passes AND `GET /api/foo` returns `{id, name}`"
@@ -516,6 +550,17 @@ demo:
   budget:  "<2s wall · <80 LOC test"
 ```
 
+**Wave tracking** (mandatory — `do-auto.sh`'s `_sync_status` scans THIS `## C<n>` section for
+`- [ ] W` lines to auto-derive the Status kanban's header tick; the kanban's own nested
+`- [ ] W1 recon` lines are a summary view, not what the script reads. Omitting this block
+means the section never has an open `- [ ] W` line, so `_sync_status` false-ticks the cycle
+complete on the very first pass, before any work happens — verified failure, `live-edit` C1–C6,
+2026-07-23. One line per wave, updated to `[x]` as each completes):
+- [ ] W1 recon — {one line: what was found}
+- [ ] W2 decide — {one line: what was decided}
+- [ ] W3 edit — {one line: what landed}
+- [ ] W4 verify — {one line: what passed}
+
 ### W1 — Recon  [Haiku · parallel · merged across batch]
 
 /do spawns recon agents for ALL files in this batch's W1 list in a **single message**, deduped against `shared_recon:` cache. List only cycle-specific files that exist now (shared files are already cached at plan start).
@@ -550,7 +595,7 @@ Every item below is a checkbox; `/do` ticks each as it resolves.
 - [ ] **Architectural questions** answered
 - [ ] **Diff specs output** for every W3 target
 - [ ] **Doc-plan** filed (`.w2-doc-plan.json`) if any trigger applies (new primitive · rename · public surface · directory contract)
-- [ ] **Surface checklist** (`.w2-surface-checklist.json`) — for every new route/page/component, document: nav parent, inbound links + source pages, SDK/MCP/CLI exports, UI states
+- [ ] **Surface checklist** (`.w2-surface-checklist.json`) — MANDATORY every cycle: for every new route/page/component document nav parent, inbound links + source pages, SDK/MCP/CLI exports, UI states — or write an explicit `{"surface": "none", "reason": "…"}`
 
 **Compose-or-construct verdict (mandatory — top of W2, before any other decision):**
 
@@ -580,7 +625,9 @@ separately. Default to "compose"; "new" is the exception, not the default.
 
 W2 fills in the anchors AND the surface checklist. Mark which edits are independent vs dependent.
 
-**Surface build order (every cycle, in this order):**
+**UI cycles (surface ≠ none):** name `text/<slug>-ui.md` as source_of_truth and load the `shadcn` / `puck` / `frontend-design` skills before editing; W4 then verifies each component-state row of the -ui.md renders, `do-prove.sh --route` passes, and light+dark screenshots are attached to the cycle close note.
+
+**Surface build order (every cycle, in this order — driven by the mandatory `.w2-surface-checklist.json`; a cycle with `{"surface": "none"}` skips 5–8 but still files the checklist):**
 1. Schema (migration if needed)
 2. Types (TypeScript interfaces)
 3. Receiver/SDK (if new public method)
@@ -636,6 +683,7 @@ If all edits are independent, leave W3b empty — empty W3b = one fewer round-tr
   - [ ] MCP tool defined (if agent-facing; in `packages/mcp/src/tools/`)
   - [ ] CLI verb added (if operator-facing; in `packages/cli/src/commands/`)
   - [ ] All UI states rendered (empty, loading, error, edit modes exist in component)
+  - [ ] Page-load proof (surface ≠ none): `bash .claude/scripts/do-prove.sh --route {route}` exits 0 + each component-state row of `text/<slug>-ui.md` renders + light+dark screenshots attached to the close note
 - [ ] **Docs synchronized** (hard gate):
   - [ ] New terms added to `text/dictionary.md`
   - [ ] Feature doc section exists (`text/{feature}-plan.md` or appended to existing)
@@ -666,8 +714,15 @@ Report: `delta_tsc=±N  delta_loc=±N  compress_orphans=N  new_files=N  primitiv
 **Goal delta:** {one sentence}
 **Deliverable:** {one row from `deliverables:` table}
 **UX delta:** {one sentence — or "internal-only, justified by X"}
+**Surface:** {`/route` | `component:<Name>` | `none({reason})` — W2 copies into `.w2-surface-checklist.json`}
 **Cycle outcome:** {verifiable}
 
+**Wave tracking** (mandatory — see C1's note above for why):
+- [ ] W1 recon — {one line}
+- [ ] W2 decide — {one line}
+- [ ] W3 edit — {one line}
+- [ ] W4 verify — {one line}
+
 ### W1 — Recon  [Haiku · parallel]
 
 - `{file}` — {what to find}