@oneie/claude 0.8.0 → 0.10.0

package/skills/planning/SKILL.md

@@ -0,0 +1,256 @@
+---
+name: planning
+description: Turn a whole task board into a plan, and the plan into moved rows — tasks:board to see everything, tasks:bulk to act on it. Use whenever an agent has a goal and needs to know what already exists, what is ready, what is blocked and who owns it, or needs to file a plan tree, route unowned work, sweep a stale tag, or find the rows that became claimable when something closed. Triggers — "plan this", "what should I work on", "see the whole board", "what is ready", "what is blocked", "file the plan", "break this down into tasks", "route the unassigned work", "clean up these tasks", "how many tasks are there really".
+---
+
+# planning — the board is the plan
+
+**Purpose:** one loop. **See it all → decide → shape → act → close.** Every step is a
+receiver, none is a convention you can improvise, and the whole board is ONE request.
+
+**A page of tasks is not the board.** Measured 2026-09-13 and written into the contract
+(`packages/sdk/src/receivers.ts:2113-2118`): an agent asked for the board, hit a 200-row page,
+paged by six tags, found 353 more rows **by name only**, and never learned the real total.
+`tasks:board` exists so that cannot happen again — and so you can reason about 2,000 tasks
+while reading 0 of them.
+
+**Use the CLI first.** `one tasks board|bulk|set` (`packages/cli/src/tasks.ts`) is the fast door —
+it walks the pages, chunks writes at 25, and previews filter writes unless `--apply`. Pipe `--json`
+to a file and filter it with `node -e`/`jq`; never read 2,000 rows through the context window.
+
+    node packages/cli/dist/src/index.js tasks board --workspace one --tree --summary          # 1 — see it all
+    node packages/cli/dist/src/index.js tasks board --workspace one --tree --all --limit 2000 --include notes --json > board.json
+    node packages/cli/dist/src/index.js tasks set --workspace one --where-tag <t> --set-status dissolved --comment "why"   # preview
+    node packages/cli/dist/src/index.js tasks bulk --file plan.json --apply                   # file a whole plan tree
+    node packages/cli/dist/src/index.js tasks brief --workspace one --tree                     # one screen + next five moves
+    node packages/cli/dist/src/index.js tasks plan <goal-tid|tag> --workspace one --tree       # waves + critical path (hops)
+    node packages/cli/dist/src/index.js tasks plan <goal> --emit dispatch --out wave.json     # hand-off for factory-executor / tasks:launch
+    node packages/cli/dist/src/index.js tasks sequence <tid> <tid> <tid>                      # chain in order; preview unless --apply
+
+`brief`, `board` and `plan` default to `--kind work`: rows tagged `approval` are parked workflow
+runs, left out of the counts and COUNTED as excluded. Close one with `tasks_approve` /
+`workflow:stop`, never by status — `set --apply` refuses a match that holds one unless `--kind all`.
+`plan` reads a blocker's state from the server's `openBlockers`, never raw `blockedBy`: a closed
+blocker is satisfied, an open one outside the goal is `waits outside plan` and never dispatched.
+Dispatch hints ride in notes as labelled lines — `model:` `effort:` `touches:` `accept:` — and rows
+in one wave that share a `touches:` path are serialised. Promise + plan: `text/tasks-cli.md`.
+
+The raw HTTP door and the MCP tools below are the same receivers; use them only without a shell.
+If `tasks` is an unknown command the CLI `dist/` is stale — rebuild sdk then cli.
+
+Every door: `POST https://one.ie/api/ask/<receiver>`, `Authorization: Bearer $GATEWAY_API_KEY`
+(from `one.ie/web/.dev.vars`, **not `.env`**), body wrapped in `{"data":{…}}` or you get
+`envelope_missing`. Via MCP, `tasks_board` / `tasks_bulk` take the same fields.
+
+---
+
+## 1 — SEE IT ALL (always first, before any row read)
+
+```json
+{"data":{"workspace":"one","view":"summary","scope":"tree"}}
+```
+
+`view:"summary"` returns counts and sets and **no rows** — the cheapest way to see a 2,000-row
+board. `scope:"tree"` is this group **and every descendant** (the CEO / agency lens); default is
+`own`. Read the rows only once the summary told you which rows to ask for.
+
+**Four honesty fields. Read all four before you plan.**
+
+| Field | Means | Your next move |
+|---|---|---|
+| `total` | rows matching the filters **before paging**. Exact — *unless* `truncated.rows` is present, then it is a **floor** | quote it as the count, or as "at least N" |
+| `nextCursor` | present **iff** more rows match. Absent = you have them all | page until it is absent; never stop early and call it the board |
+| `truncated` | absent = nothing was cut. `.rows` = snapshot hit its budget · `.edges` = a row may read unblocked or orphaned when it is not · `.tags` = returned rows may be missing tags | **say so in your report** before planning on it |
+| `asOf` | ISO time the snapshot was built; rows are at most this stale | it is a KV memo, not a live read. `fresh:true` asks for a rebuild and is honoured **at most once per memo window** |
+
+**`summary` counts are over ALL matched rows; its id lists are a SAMPLE.**
+`summarizeBoard` counts every matched row (`one.ie/web/src/lib/tasks/board.ts:531`), but
+`readyIds` / `blockedIds` are the **top 50 by priority** (`board.ts:559-560`) and `byTag` is the
+**top 100 tags by count** (`board.ts:553`). A board with `ready: 300` hands you 50 ids — take the
+count from `summary`, take the rows from a filtered `view:"rows"` call with `nextCursor`.
+
+**Row width.** Compact rows already carry `tid,name,status,priority,tags,assignee,workspace,
+parent,blockedBy,openBlockers,ready,dueAt` — and `blockedBy`/`openBlockers` appear only when the
+row actually has blockers (`one.ie/web/src/lib/resolvers/task-board.ts:170`). Widen with
+`include: ["notes","graph","dates","thread"]`; `notes` is **clipped to 2000 chars per row**
+(`task-board.ts:182`) — read a whole goal one task at a time.
+
+---
+
+## 2 — DECIDE what to do
+
+Shipped in `summary` today (all computed in RAM over the matched set, no TypeDB):
+
+- **`ready`** — open **and** every blocker closed; a blocker not on the board counts as open, so
+  readiness is never reported on a guess (`board.ts:463-469`). The set a director can start now.
+- **`blocked`** — status `blocked`, or active with at least one open blocker.
+- **`unassigned`** · **`overdue`** — work with no owner, work past its date.
+- **`orphans`** — no parent, unreachable from any plan's containment walk.
+- **`noNotes`** — no prose goal: the rows a puller **cannot act on**. Not work, a title.
+
+**The unblockable row is the highest-value row on any board.** Status `blocked`, every blocker
+now closed — claimable in fact, invisible in practice, because `ready` requires
+`status === 'open'` (`board.ts:465`) and **nothing promotes it automatically**. Derive it today:
+ask `{"status":"blocked"}`, keep rows whose `openBlockers` is `0` or absent, then flip them with
+`tasks:bulk edits` (recipe D).
+
+**Designed, not built** — `summary.decisions` (`unrouted` · `unblocked` · `stalePicked` ·
+`deadlocked`) is **R10** of `text/tasks-inbox-plan.md` §6 and is not in the zod. So are
+`changedSince` (R9), `include:["route"]` + `summary.routes` (R11), and the CEO digest (R12).
+Zod **strips undeclared keys**, so sending one of those fields does not error — it silently
+degrades to a full cold read. Do not write payloads against them.
+
+---
+
+## 3 — SHAPE the work: chain before you fan out
+
+`tasks:claim` is **blocker-gated**, and the edges you write are what that gate reads. An
+unchained board hands every agent every row at once and nothing knows what comes first.
+
+**One call files a whole plan tree.** `tasks:bulk` `creates` (max 25) with `ref` handles:
+
+```json
+{"data":{"workspace":"one","creates":[
+  {"ref":"plan","title":"Launch the pricing page","notes":"Done when /pricing is live and converts"},
+  {"ref":"copy","title":"Write pricing copy","parent":"plan","notes":"Three tiers, no jargon"},
+  {"title":"Ship pricing page","parent":"plan","blockedBy":["copy"],"notes":"Deploy after copy lands"}]}}
+```
+
+**Ref rules — earlier-only.** A ref must be created **earlier in the same `creates` array** and
+its own create must have succeeded. A forward ref, a self ref, or a ref whose create failed is
+`unknown_ref`, and **nothing is written for that row** — a typo never reaches the substrate as a
+lookup (`one.ie/web/src/lib/resolvers/tasks.ts:2245-2252`). The receipt maps `ref → tid` in
+`created`.
+
+`tasks:subtask` does the same job **one row at a time** (row, notes, tags, containment edge and
+every `blockedBy` in one pipeline) and `tasks:depend` orders rows that already exist. **Never file
+a child with `tasks:create`** — it lands claimable, with no parent and no ordering.
+
+**The claim gate is wider than the board's `ready` flag.** `blockersResolved` requires every
+`blocks` blocker **AND every `containment` child** to be done|verified (`tasks.ts:614-619`,
+called by claim at `tasks.ts:963`), while the board's `isReady` reads `blockedBy` only
+(`board.ts:465-469`). So **a parent whose children are still open reads `ready:true` and
+`tasks:claim` refuses it `blocked`.** That is the design working — a plan root is unclaimable
+until its leaves close. Claim leaves, not roots.
+
+---
+
+## 4 — ACT
+
+**`where`+`set` is a DRY RUN by default.** `dryRun` is true unless you say `false` in so many
+words (`tasks.ts:2276-2278`). Read `matchedIds`, satisfy yourself they are the rows you meant,
+then resend the identical call with `"dryRun":false`.
+
+- The 25-row budget is **shared**: `where` pages at `MAX_BULK − (creates+edits)`
+  (`tasks.ts:2525`), and a `where`+`set` sent alongside a full 25 rows errors `too_many`
+  (`tasks.ts:2527`). Follow `nextCursor` to continue.
+- On a truncated snapshot the envelope adds a `detail` saying **`matched` is a floor, not a
+  total** (`tasks.ts:2577-2578`). Quote it that way.
+- **Put a `comment` on every change**, saying why — it lands in the task's inbox thread where the
+  humans already read. Side effect: **a comment heartbeats a `picked` lease**
+  (`tasks.ts:1943-1946`), so commenting on stale `picked` rows fights `tasks:reap`.
+- **`ok` is the CALL's outcome, never the rows'** (`tasks.ts:2687-2693`). Read
+  `applied` / `failed` / `notAttempted` — a row never attempted says so by name. And `created`
+  means **the row exists**, not that its later priority/dueAt/edge writes applied; that row's
+  receipt in `results` can still be `ok:false` (`tasks.ts:2682-2684`).
+- **Delegate in place** with `tasks:reassign` — never by filing a second task. Under a shared
+  gateway key a claim lands as the workspace, so follow `tasks:claim` with
+  `tasks:reassign {assignee:"<your slug>"}` or the ledger cannot say who took the row.
+- **`tasks:announce` returns `matched`, and matched is NOT delivered** — it is `actors.length`
+  from the fan-out (`one.ie/web/src/lib/resolvers/subscriptions.ts:1245` — the cite was
+  `:990`, which is a `lane = 'explore'` branch, not a `matched` line at all; `:928` is
+  `world:announce`'s). Quote it as reach.
+
+Claim · delegate · chat · chain as a *meeting* is the `meeting` skill and
+`.claude/agents/ceo.md § The four verbs`. Go there; don't restate it here.
+
+---
+
+## 5 — CLOSE THE LOOP
+
+The three locked rules, applied to a board turn:
+
+1. **Every signal closes** with `mark`, `warn` or `dissolve` — `tasks:bulk` marks on `applied`
+   and warns on `failed` (`tasks.ts:2679-2680`); your *report* closes too.
+2. **Structural time.** Tasks → waves → cycles. Never days, hours or weeks.
+3. **Deterministic numbers, from the RECEIPT.** `applied` / `failed` / `notAttempted` are
+   authoritative. **Do not re-read the board to verify your own write** — it is a KV memo stamped
+   `asOf` and `fresh:true` is rate-limited, so it can answer with rows that predate your edit.
+
+---
+
+## The five mistakes
+
+1. **Reading a page as the board** — six tag pages, 353 rows by name, no total. `view:"summary"` first, every time.
+2. **Quoting `matched` as delivered** — `tasks:announce` reports reach, not action.
+3. **Planning on a truncated board without saying so** — an unmentioned `truncated` turns a floor into a total.
+4. **A bulk `ok:true` that hid failed rows** — `ok` is the call; rows live in `applied`/`failed`/`notAttempted`.
+5. **Filing a child with `tasks:create`** — claimable, no parent, no ordering. Use `creates` or `tasks:subtask`.
+
+---
+
+## Recipes (valid against the zod)
+
+**A — Plan a feature.** One call, whole tree, ordering included.
+
+```json
+{"data":{"workspace":"one","creates":[
+ {"ref":"root","title":"Ship voice in chat","notes":"Done when a user can talk to a page and hear a reply","tags":["voice"],"priority":70},
+ {"ref":"api","title":"Wire the TTS receiver","parent":"root","notes":"Receiver + contract + test"},
+ {"title":"Voice bubble UI","parent":"root","blockedBy":["api"],"notes":"Push-to-talk and hands-free"}]}}
+```
+
+**B — Route unowned ready work.** Dry run, read `matchedIds`, then apply.
+
+```json
+{"data":{"workspace":"one","where":{"status":"open","ready":true,"assignee":"","tags":["launch"]},
+ "set":{"assignee":"cmo","comment":"Routing unowned ready launch work to marketing"},"dryRun":true}}
+```
+Then the same body with `"dryRun":false`. Follow `nextCursor` until absent; read `applied`.
+
+**C — Sweep a stale tag.** See it first, then dissolve with a reason.
+
+```json
+{"data":{"workspace":"one","tags":["q3-experiment"],"status":"active","view":"both","limit":100}}
+```
+```json
+{"data":{"workspace":"one","where":{"tags":["q3-experiment"],"status":"active"},
+ "set":{"status":"dissolved","comment":"Superseded by the Q4 plan — dissolved, not done"},"dryRun":false}}
+```
+A `picked` row in that sweep gets its lease heartbeat by the comment; reap it with `tasks:reap`
+rather than commenting it back to life.
+
+**D — Find what is unblockable.** The highest-value rows nobody knows are claimable.
+
+```json
+{"data":{"workspace":"one","scope":"tree","status":"blocked","limit":200}}
+```
+`openBlockers` is already on the compact row — no `include` needed. Keep rows whose
+`openBlockers` is `0` or absent, then promote them by name:
+```json
+{"data":{"workspace":"one","edits":[
+ {"tid":"task:<24hex>","status":"open","comment":"Every blocker closed — open and claimable"}]}}
+```
+
+**E — The CEO's turn, in its SHIPPED form.** Three calls.
+
+```json
+{"data":{"workspace":"one","scope":"tree","view":"summary"}}
+```
+```json
+{"data":{"workspace":"one","where":{"status":"open","ready":true,"assignee":"","scope":"tree"},
+ "set":{"assignee":"cto","comment":"Unowned and ready — routing to engineering"},"dryRun":true}}
+```
+…then the same call with `"dryRun":false`. **Designed, not built:** §6's faster turn
+(`changedSince` watermark, `include:["route"]`, `summary.routes` ranked by who staked the tags)
+is R9/R11/R12 of `text/tasks-inbox-plan.md` — until those ship, the CEO routes from its keyword
+table and its own judgment, and unstaked work stays the CEO's call.
+
+---
+
+## See also
+
+`packages/sdk/src/receivers.ts` — the contract; its `describe()` text is the spec, never invent a
+field · `.claude/skills/meeting/SKILL.md` — the room where rows move ·
+`.claude/agents/ceo.md § Seeing the whole board` · `text/tasks-inbox-plan.md` §5-§6 — the decided
+doctrine and the unbuilt rungs.

package/skills/shadcn/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: shadcn
-description: shadcn/ui primitives in `one.ie/web` under the ONE 6-token design system. Covers the `src/components/ui/` inventory, why shadcn's own `-foreground` names survive the `--color-*: initial` palette wipe via the Layout.astro aliases, adding a primitive with the CLI, and Button/Badge/Card/Dialog variants. Use when adding or editing a `src/components/ui/` primitive, when a shadcn component renders transparent or invisible after the wipe, or when picking between a token utility and an alias.
+description: "shadcn/ui primitives in `one.ie/web` under the ONE 6-token design system. Covers the `src/components/ui/` inventory, why shadcn's own `-foreground` names survive the `--color-*: initial` palette wipe via the Layout.astro aliases, adding a primitive with the CLI, and Button/Badge/Card/Dialog variants. Use when adding or editing a `src/components/ui/` primitive, when a shadcn component renders transparent or invisible after the wipe, or when picking between a token utility and an alias."
 user-invocable: true
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 ---

package/skills/typedb/SKILL.md

@@ -129,6 +129,13 @@ anything but `read`. `GET /v1/databases/one/schema` dumps the live schema —
 the fastest way to answer "is this fun actually deployed?". `GET /v1/version`
 returns the running build.
 
+**A timeout arrives as HTTP 500, not 408 or 503.** The body carries
+`"The operation was aborted due to timeout"` — and that string was absent from
+`RETRYABLE` in `one.ie/web/src/lib/substrate.ts` until 2026-09-14, so every timed-out
+read failed hard on the first try. Reads now retry it; **writes deliberately do
+not** — a write that timed out may already have committed, so retrying it is a
+duplicate, not a recovery. Classify by the message, never by the status code.
+
 The Python driver (`TypeDB.driver(...)`, `driver.transaction(...)`) is covered in
 the *Python Driver* section for reading upstream docs. **No code in this repo
 uses it** — there is no `typedb-driver` dependency in any `package.json` or

package/skills/voice/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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".
+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
@@ -33,7 +33,7 @@ Everything else — observe don't assert, specific numbers or none, short senten
 
 ## 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.**
+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 `apps/ants/docs/book/manuscript/` — 96,540 words of directory, 93,032 of them the 25 chapters the section below measures. **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.
 
@@ -51,22 +51,110 @@ If it performs urgency, expertise, contrarianism, or aspiration — rewrite it.
 
 ---
 
+## What the corpus actually does — measured
+
+`text/voice-and-tone.md` says what the voice must never do. The 25 chapters of
+*100 Million Years Ahead* show what it does. Measured 2026-09-09 over
+`apps/ants/docs/book/manuscript/*.md` — 93,032 words, 6,163 sentences, 1,441
+paragraphs. Re-measure any time with `bash .claude/skills/voice/corpus-check.sh --corpus`.
+
+| Signature | Measured | What it means for a draft |
+|---|---|---|
+| **"I"** | **0** in 93,032 words | Absolute, not a preference. One occurrence is a defect. |
+| **Contractions** (`n't`) | **5** in the whole book | Effectively never. Write *does not*, *is not*, *will not*. The spec never states this; the corpus is unanimous. |
+| **`###` headings inside a chapter** | **0**, across all 25 | Confirmed absolute. |
+| **Horizontal rules** (`---`) | **median 5 per chapter**, up to 10 | The derived guide's "once or twice" is **wrong**. The scene break is a primary structural tool, not a rarity. |
+| **One-sentence paragraphs** | **371 of 1,441 — 25.7%** | One paragraph in four is a single sentence. That is the rhythm, not an occasional flourish. |
+| **Sentence length** | median **12** words · mean 15.1 · p10 **4** · p90 30 · max 82 | Wide range on purpose; 22.2% of sentences are 6 words or fewer. A draft of uniform 20-word sentences is not this voice. |
+| **Final sentence of a chapter** | median **10** words; three chapters end in 3 | Land short. *"The soil will."* · *"In the substrate."* · *"The architecture, running."* |
+| **"the reader"** vs **"you"** | 134 vs 113 — and **50 of the 113 sit in the epilogue alone** | The standing device is third-person *"the reader."* Direct *you* is held back and spent at the end, where the book turns to face the reader. |
+| **Digits** | 5.8 per 10k words | Numbers are rare and therefore load-bearing. A number earns its place or is cut. |
+| **Hedges** | *on the order of* ×12 · *roughly* ×23 · *approximately* ×3 | Precise when the evidence is sharp, *on the order of* when it is not. Never a fake decimal. |
+| **Em dashes** | 89.6 per 10k | Book register uses them freely. The "3 or fewer" rule is **commercial only** — do not carry it across. |
+| **Question marks** | 5.3 per 10k — 49 in the whole book | A rhetorical question is a rationed move. Two chapters end on one. |
+
+---
+
+## The three sentence shapes
+
+These are the shapes the corpus reaches for. They are not decoration. They are how an
+observation gets made without being asserted.
+
+**1. The negative-definition fragment.** A statement, then a fragment that names the
+obvious alternative and refuses it. The most characteristic sentence in the book.
+
+> *"This is the thing to look at. Not the ant."*
+> *"This is where the colony's memory lives. Not in any ant."*
+> *"The colony regulates the queen. Not the other way around."*
+> *"That eighth one ran in fifteen years what the desert ran in a hundred million. Not because it was better designed."*
+
+The fragment is deliberate. It does the work an em dash and a subordinate clause would
+do, and it lands harder because it stops.
+
+**2. "It is not X. It is Y."** Two flat copulas. The first clears the ground, the second
+puts the thing down. No connective, no *rather*, no *instead*.
+
+> *"It is not chemistry. It is not soil."*
+> *"It is not a stored recipe retrieved on cue. It is constructed for the case in front of it."*
+> *"It was not built as a substrate for collective intelligence. It was built to record grain shipments and tax debts."*
+
+**3. The copula-forward declarative.** *It is* appears 683 times — 73.5 per 10k. The
+voice states what a thing is and then stops, rather than explaining that it is about to
+state it. This is what "confidence without assertion" looks like structurally.
+
+**And one shape to avoid:** the interpretive paragraph after a clear observation. The
+corpus makes the observation and leaves a blank line. The reader is given room to feel
+the implication before the next paragraph arrives.
+
+---
+
+## Openings and closings
+
+**Every one of the 25 chapters opens on a concrete particular.** Never on an argument,
+never on a thesis, never on a summary of what the chapter will do.
+
+They open on: a temperature on dirt · a nine-month-old on a kitchen floor · dawn in the
+Chihuahuan Desert · a corridor a centimetre wide · a freshly emerged ant · a stretch of
+high desert near Rodeo · *"She is the largest animal in the nest, and she is doing the
+least."* · a man opening a coffee shop · a person selling four hundred shares · Vienna,
+1847 · a scrape on a knee · one and a half kilograms of tissue · the year 1300 · 2008 ·
+*"The desert is still there."*
+
+Three reliable opening moves: **a place and a temperature**; **a date, a person, an
+action**; **a flat short sentence holding a contradiction** ("largest… doing the least").
+Pick one and begin. Do not announce.
+
+**The closings are short, and they return.** Median 10 words. The dominant move is a
+recontextualised return to the chapter's own opening image — chapter 22 opens *"The
+desert is still there"* and closes *"The architecture, running."* Two chapters close on a
+question. Several close on a fragment that lands on one noun and nothing else.
+
+Never close on a summary. Never close on an implication the reader can draw alone.
+
+---
 ## 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.
+- [ ] **No contractions.** *does not*, not *doesn't*. Five in 92,894 words of corpus.
+- [ ] **No `###` subheadings** — zero across 25 chapters. But **use the horizontal rule**: median 5 scene breaks per chapter, up to 10.
+- [ ] **"The reader", not "you"** — 134 to 116, and 50 of the *you*s are in the epilogue. Direct address is saved for the end.
+- [ ] **One paragraph in four is a single sentence** (25.7% measured). Vary sentence length hard: median 12 words, but 22.2% are ≤6.
+- [ ] **Specific numbers, or honest hedging** (*on the order of*, *roughly*). Never false specificity. Digits appear only 5.8 times per 10k words — each one is load-bearing.
 - [ ] **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.
+- [ ] **Opens on a concrete particular** — a place and a temperature, a date and a person and an action, or a short flat sentence holding a contradiction. Never on the thesis.
+- [ ] **Closes short** — median 10 words — often a recontextualised return to the opening image. Never a summary.
+- [ ] **Reaches for the three shapes** — the negative-definition fragment, "It is not X. It is Y.", the copula-forward declarative.
+- [ ] **Leaves the observation alone.** No interpretive paragraph after a clear one.
 - [ ] **Passes both the "your mum" and the "Demis Hassabis" test.**
 - [ ] **The emotion is recognition, not awe.** No "this changes everything."
+- [ ] **Run `bash .claude/skills/voice/corpus-check.sh <draft.md>`** — it counts the mechanical half against the corpus and cannot judge the rest.
 
 ## Commercial-register checklist
 
-- [ ] **Em dashes: 3 or fewer.** Count them.
+- [ ] **Em dashes: 3 or fewer.** Count them. (Book register is the opposite — 89.6 per 10k. Do not carry this rule across.)
 - [ ] **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.

package/skills/voice/corpus-check.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# corpus-check.sh — measure book-register prose against the corpus that defines it.
+#
+#   bash .claude/skills/voice/corpus-check.sh --corpus        re-derive the SKILL.md table
+#   bash .claude/skills/voice/corpus-check.sh <draft.md> ...  check a draft
+#   bash .claude/skills/voice/corpus-check.sh --self-test     prove the checker goes RED
+#
+# It counts the MECHANICAL half of the voice only: the things a machine can see.
+# It cannot tell whether a sentence observes or asserts, and it never claims to.
+# A green run is a draft that has not broken a countable rule. It is not a good draft.
+#
+# manifest: monorepo-only   (the corpus lives in the sibling repo apps/ants)
+set -o pipefail
+
+CORPUS="${VOICE_CORPUS:-/Users/toc/Server/apps/ants/docs/book/manuscript}"
+
+measure() {  # measure <label> <file...>
+  python3 - "$@" <<'PY'
+import re,sys,statistics
+label=sys.argv[1]; files=sys.argv[2:]
+txt=[]
+for f in files:
+    try: t=open(f, encoding="utf-8").read()
+    except OSError as e: print(f"  cannot read {f}: {e}"); continue
+    txt.append(t)
+raw="\n".join(txt)
+raw=re.sub(r'\A---\n.*?\n---\n','',raw,flags=re.S)      # YAML frontmatter is metadata, not prose
+body="\n".join(l for l in raw.split("\n") if not l.startswith("#"))
+words=len(body.split())
+if not words: print("  EMPTY — nothing to measure"); sys.exit(2)
+sents=[s.strip() for s in re.split(r'(?<=[.!?])\s+',body) if len(s.strip())>1]
+wl=[len(s.split()) for s in sents]
+paras=[p.strip() for p in body.split("\n\n") if p.strip() and p.strip()!="---"]
+psent=[len(re.split(r'(?<=[.!?])\s+',p)) for p in paras]
+per10k=lambda n: 10000*n/words
+CONTRACTION=r"n[\u2019']t\b"
+c=lambda pat: len(re.findall(pat,body))
+craw=lambda pat: len(re.findall(pat,raw))   # headings live only in raw
+one=sum(1 for x in psent if x==1)
+short=sum(1 for x in wl if x<=6)
+last=re.split(r'(?<=[.!?])\s+',paras[-1].replace("\n"," "))[-1] if paras else ""
+print(f"  {label}: {words} words · {len(sents)} sentences · {len(paras)} paragraphs")
+print(f"    I                    {c(r'(?<![A-Za-z])I[ ,.]'):6d}        target 0")
+print(f"    contractions n\'t     {c(CONTRACTION):6d}        target ~0 (corpus 0.5/10k)")
+print(f"    ### headings         {craw(r'(?m)^#{3,}'):6d}        target 0")
+sb=[len(re.findall(r'(?m)^---\s*$',t)) for t in txt]
+print(f"    --- scene breaks     {sum(sb):6d}  median {statistics.median(sb) if sb else 0:.0f}/file   corpus median 5")
+print(f"    1-sentence paras     {one:6d}  {100*one/len(paras):5.1f}%   corpus 25.7%")
+print(f"    sentences <=6 words  {short:6d}  {100*short/len(sents):5.1f}%   corpus 22.4%")
+print(f"    sentence median      {statistics.median(wl):6.0f} words    corpus 12 (mean {statistics.mean(wl):.1f}, corpus 15.1)")
+print(f"    'the reader'         {c(r'(?i)\bthe reader\b'):6d}")
+print(f"    'you'                {c(r'(?i)\byou\b'):6d}        corpus favours 'the reader'")
+print(f"    digits    per10k     {per10k(c(r'\b\d')):6.1f}        corpus 5.8")
+print(f"    em dash   per10k     {per10k(c(chr(8212))):6.1f}        corpus 89.8")
+print(f"    final sentence       {len(last.split()):6d} words    corpus median 10")
+if last: print(f"      > {last[:100]}")
+PY
+}
+
+case "${1:-}" in
+  --corpus)
+    if [ ! -d "$CORPUS" ]; then
+      echo "corpus not found: $CORPUS"
+      echo "It lives in the sibling repo apps/ants and does not ship. Set VOICE_CORPUS to point at it."
+      exit 4          # unavailable — NOT a pass
+    fi
+    measure "corpus" "$CORPUS"/[0-9][0-9]-*.md ;;
+
+  --self-test)
+    d=$(mktemp -d); trap 'rm -rf "$d"' EXIT
+    printf '### A heading\n\nI think this is fine. It doesn'"'"'t matter.\n\nYou will see that you agree, you really will.\n' > "$d/bad.md"
+    out=$(measure "red-proof" "$d/bad.md")
+    echo "$out"
+    fail=0
+    echo "$out" | grep -qE '^ +I +[1-9]'            || { echo "RED PROOF FAILED: 'I' not counted"; fail=1; }
+    echo "$out" | grep -qE "contractions n't +[1-9]" || { echo "RED PROOF FAILED: contraction not counted"; fail=1; }
+    echo "$out" | grep -qE '### headings +[1-9]'     || { echo "RED PROOF FAILED: heading not counted"; fail=1; }
+    [ $fail -eq 0 ] && echo "SELF-TEST ok — the checker sees all three violations" || exit 1 ;;
+
+  ""|-h|--help)
+    sed -n '2,14p' "$0" | sed 's/^# \{0,1\}//' ;;
+
+  *)
+    measure "draft" "$@"
+    echo
+    echo "  Counted, not judged. The uncountable half is the checklist in SKILL.md." ;;
+esac

package/templates/template-agent.md

@@ -6,7 +6,7 @@
 name: {kebab-name}
 description: {One sentence — what this agent does and when to spawn it}
 tools: {comma-separated tool list}
-model: {haiku | sonnet | opus}
+model: {haiku | sonnet | opus}   # OPTIONAL — omit to inherit the default
 effort: {none | low | medium | high | xhigh}
 skills: {comma-separated skill list}
 subscribes: [{tag}, {tag}]  # the agent's stake — these tags route matching
@@ -39,6 +39,12 @@ You are the {name} agent. {One sentence role statement.}
 
 **Default:** pick the cheapest model that can answer. Stop at the first that decides.
 
+**`model:` is optional — omit it unless you are OVERRIDING.** It is `z.string().optional()` in the schema (`one.ie/web/src/lib/agent-schema.ts:236`), and an absent value resolves by the walk this whole estate resolves by — **agent → group → ancestor → platform** (`resolveModel`, `packages/sdk/src/billing.ts:179`) — ending at `DEFAULT_MODEL` = `x-ai/grok-4.5` (`billing.ts:138`), filled for `one.ie/ai/agents` by **channels** (`context.ts:592` → `personas.one`, `channels/src/personas.ts:61`) and for the separate `one.ie/web/ai/agents` tree by the web loaders (`agent-loader.ts:64`, `agents.ts:91`) — two trees, one `web/` apart, so check which glob covers your file before citing a loader. Declaring the default buys nothing and hides the walk, so write the line only when the answer differs from it.
+
+**The `kind: agent` genus has its own spec — `text/agents-spec.md`** — the field table across the six readers, the required set (`name` · `kind: agent` · a non-empty body), and the shapes the runtime cannot read; `oneie agent validate <path>` enforces it. This template is the other genus and is not validated by it.
+
+**Which spelling depends on which genus you are writing, and they are not interchangeable.** This template is the **Claude Code** shape (root-level `one.ie/ai/agents/<name>.md`, with `tools:`/`effort:`/scalar `skills:`) — it is spawned through the Agent tool, which accepts only the bare aliases `opus | sonnet | haiku | fable`, so those are what belongs above. A **`kind: agent`** file under `one.ie/ai/agents/<name>/agent.md` is the other genus and takes a full **OpenRouter id** instead — and OpenRouter versions ids with **dots**: `anthropic/claude-sonnet-4.5`, never `anthropic/claude-sonnet-4-5`. Nothing normalises between them (no `normalizeModel`/`MODEL_ALIAS` exists in web, sdk or channels), so a wrong-genus or hyphenated value fails silently at `gateway()` rather than at parse. Measured 2026-09-17: 78 of 105 `kind: agent` files carried an id `/api/openrouter-models` does not serve. Verify before you write one — `curl -s localhost:4321/api/openrouter-models | jq -r '.models[].id'`.
+
 ## The Three Locked Rules
 
 1. **Closed loop** — every output closes with a result, warn, or dissolve. No silent returns.

package/templates/template-feature.md

@@ -155,6 +155,15 @@ world:                     # the runtime the kept promise puts into the world
   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"
+  code:                    # the CODE the tag's family owns — every value a path relative to
+                           # the repo root, presence-checked EXACTLY like agents: a declared
+                           # path that does not exist → a cycle in the todo; present → skip.
+                           # Gate: `bash .claude/scripts/do-world-check.sh <slug>`.
+    ts:      []            # ["one.ie/web/src/lib/{slug}/tasks.ts"] — libs, resolvers, receivers
+    astro:   []            # ["one.ie/web/src/pages/{slug}.astro"]  — pages the tag ships
+    tql:     []            # ["schema/{slug}.tql"]                  — the tag asked as a query
+    panel:   []            # ["one.ie/web/src/components/{Slug}Panel.tsx"] — what a view mounts
+    command: []            # [".claude/commands/{slug}.md"]         — the operator's door
   tasks:
     tags: ["slug:{slug}"]  # the todo enters the world as a tagged weighted signal
   tracking:

package/templates/template-todo.md

@@ -16,6 +16,35 @@ tags: []                   # drives pheromone routing + W2 context triggers
 priority: 0                # 0 none · 1 should · 2 important · 3 critical — human override; do-rank.py reads it
 depends_on: []             # [other-slug, …] — plans that must be DONE before this is READY; powers do-rank.py's blocked/ready buckets + do-fleet conflict ordering
 
+# ─── BOARD CONTRACT (the plan and the board are ONE graph) ───────────
+# A plan's cycles and the board's rows are the same work in two renderings.
+# Until this block existed they were two graphs that drifted: `batches:` held
+# the ordering in markdown, D1 held it in `blocks` edges, and nothing joined
+# them — so a head reading the board could claim C5 while C1 was still open.
+#
+# THE JOIN IS NOT DECORATION. `tasks:claim` is BLOCKER-GATED and reads the very
+# `blocks` edge `tasks:depend` writes. So a plan whose batch DAG is mirrored onto
+# the board CANNOT be claimed out of order — the gate enforces the plan. A plan
+# that is not mirrored hands every agent every cycle at once, and the fan-out is
+# a race. Chain before you fan out.
+#
+# ONE GRAPH, TWO RENDERINGS:
+#   batches: [[C1],[C2,C3],[C4]]   ==   C2.blockedBy=[C1] · C3.blockedBy=[C1] · C4.blockedBy=[C2,C3]
+# If the two ever disagree, the BOARD is truth (the gate reads it) and the
+# batches list is stale — `do-plan-json.sh` emits both so the drift is visible.
+
+anchor: ""                 # task:<24hex> — the board row this plan answers to. The parent every
+                           # cycle row hangs off. Empty = the plan is not on the board and no
+                           # agent can find it: file the anchor FIRST, then write the plan.
+board_workspace: one       # where the rows live. Platform work lives in `one`; a client plan
+                           # lives in that client's slug.
+cycle_rows: []             # [{cycle: C1, tid: "task:…"}, …] — WRITTEN BY `do-board.sh <slug>`,
+                           # never by hand: it mints each row with tasks:subtask (parent = anchor,
+                           # blockedBy = the batch predecessors, tags slug:<slug>-c<n> + plan:<slug>)
+                           # and this list is the ONLY record of a cycle's tid — the cycle frames
+                           # below do not repeat it. `do-board.sh <slug> --status` reads it back.
+# ─────────────────────────────────────────────────────────────────────
+
 # ─── GOAL CONTRACT (the only thing that matters) ─────────────────────
 # PROMISE FAN-OUT: this file is spawned by the promise's derives.todo
 # at PLAN (text/<slug>.md is the promise). `outcome:` MUST be the