@nurix/etna 0.20.35 → 0.20.37

package/data/harnesses/code/skills/issue-bridge/references/trackers/linear.md

@@ -1,20 +1,23 @@
 # Linear — connector pack
 
-Access options in preference order. Probe each in order; use the first that answers. Research of record: `discussions/code-analysis-tools/research-tracker-connectors/03-linear.md` (2026-08-19).
+Access options in preference order. Probe each in order; use the first that answers.
 
 ## Option 1 — the official Linear MCP server
 
 Probe: a `linear`/`linear-server` entry in `.mcp.json` / Linear MCP tools visible in-session.
-Setup: `claude mcp add --transport http linear-server https://mcp.linear.app/mcp`, then `/mcp` for OAuth 2.1. A **read-only endpoint exists**: `https://mcp.linear.app/mcp/readonly` — prefer it for triage-only sessions. Direct bearer also works (`Authorization: Bearer <token>` — OAuth token or a Linear personal API key; a Read-only API key gives enforced read-only).
-**Tool names are unpublished by Linear** — introspect the live tool list before planning calls; expect find/create/update tools over issues, projects, comments.
+Setup: `claude mcp add --transport http linear-server https://mcp.linear.app/mcp`, then `/mcp` for OAuth 2.1. A **read-only endpoint exists**: `https://mcp.linear.app/mcp/readonly` — prefer it for triage-only sessions. Direct bearer also works (`Authorization: Bearer <token>` — an OAuth token or a Linear personal API key; a Read-only API key enforces read-only).
+**Linear publishes no tool names** — introspect the live tool list before planning calls; expect find/create/update tools over issues, projects, comments.
 
 ## Option 2 — community MCP servers
 
-`tacticlaunch/mcp-linear` (146★, MIT — the exhaustive option, 150+ `linear_*` tools, TOOLS.md published) or `prime-radiant-inc/streamlinear` (89★, MIT — the token-efficient option: one dispatch tool `action: search|get|update|comment|create|graphql|help`, ~500 schema tokens; auth `LINEAR_API_TOKEN`).
+| Server | Shape | Pick when |
+| --- | --- | --- |
+| `tacticlaunch/mcp-linear` (146★, MIT) | 150+ `linear_*` tools, TOOLS.md published | You need exhaustive coverage |
+| `prime-radiant-inc/streamlinear` (89★, MIT) | One dispatch tool, `action: search\|get\|update\|comment\|create\|graphql\|help`, ~500 schema tokens; auth `LINEAR_API_TOKEN` | You want token efficiency |
 
 ## Option 3 — CLI
 
-`@schpet/linear-cli` (binary `linear`, 911★, actively maintained; Linear's own npm CLIs are abandoned — do not use `@linear/cli`). Probe: `linear --version`. Install: `brew install schpet/tap/linear`. Branch-aware issue detection, list/start/create, PR text generation.
+`@schpet/linear-cli` (binary `linear`, 911★, actively maintained). **Never `@linear/cli`** — Linear's own npm CLIs are abandoned. Probe: `linear --version`. Install: `brew install schpet/tap/linear`. Branch-aware issue detection, list/start/create, PR text generation.
 
 ## Option 4 — GraphQL fallback
 
@@ -23,15 +26,17 @@ Endpoint `https://api.linear.app/graphql`. **Auth header for a personal API key
 - Search: `{ issues(first: 25, filter: {title: {contains: "…"}}) { edges { node { id identifier title } } pageInfo { hasNextPage endCursor } } }` (Relay cursors; also `issueSearch`/`searchIssues`)
 - Create (approval-gated): `mutation { issueCreate(input: {title: "…", teamId: "<uuid>", description: "…", labelIds: […]}) { success issue { id identifier url } } }`
 - Comment (approval-gated): `mutation { commentCreate(input: {issueId: "<uuid>", body: "…"}) { success comment { id } } }`
-Rate limits: API key 2,500 req/hr + complexity budget (single request cap 10,000 points — keep `first:` small on nested connections); watch `X-RateLimit-*`/`X-Complexity` headers.
+
+Rate limits: API key 2,500 req/hr plus a complexity budget (single request cap 10,000 points — keep `first:` small on nested connections); watch the `X-RateLimit-*` / `X-Complexity` headers.
 
 ## Composing for Linear — including Linear's own agent rules
 
-Linear publishes **Agent Interaction Guidelines** (linear.app/developers/aig); this pack adopts the two that bind writers even outside formal Agent Sessions:
+Linear's **Agent Interaction Guidelines** (linear.app/developers/aig) carry two rules that bind a writer even outside formal Agent Sessions:
 - **You are a `delegate`, never an `assignee`** — humans keep ownership of issues you touch.
-- **Never move work to a terminal state** — done/canceled transitions belong to humans (the same rule the linear-use community plugin hard-codes). Starting work maps to the team's lowest-position "started" state, and only when instructed.
-Body is native markdown. Pick team and project explicitly — never guess a team. Priority conservatively (default: none). Cycles and estimates stay human.
+- **Never move work to a terminal state** — done/canceled transitions belong to humans. Starting work maps to the team's lowest-position "started" state, and only when instructed.
+
+Body is native markdown. Pick team and project explicitly — **never** guess a team. Set priority conservatively (default: none). Cycles and estimates stay human.
 
-## Ecosystem notes (2026-08-19)
+## Ecosystem notes
 
-The strongest community skill (`wrsmith108/linear-claude-skill`, 121★) itself recommends the official MCP server — aligned with this pack's ordering. No official Anthropic Linear skill exists.
+No official Anthropic Linear skill exists. The strongest community skill (`wrsmith108/linear-claude-skill`, 121★) itself recommends the official MCP server, matching this pack's Option 1.

package/data/harnesses/code/skills/nustack-graph/SKILL.md

@@ -6,59 +6,68 @@ description: Query the code graph before reading source. An LLM-first codebase i
 
 # nustack graph — the index-first method
 
-**If the tool is absent** (`nustack --version` fails): do not stall. Read `.claude/state/decisions.tsv` for `tool.nustack`.
+## When the tool is absent
 
-- **`declined`** — fall back to the cold method (grep, targeted reads, `git log`) **silently**. Do not mention the tool, do not re-offer. The user has answered.
-- **undecided** (no file, no key, or anything unrecognised) — fall back to the cold method *and* make the offer **once**: this repository would answer "where is / who calls / what changed / who owns" from an index instead of a grep sweep. `npx @nurix/nustack graph overview` runs it without installing anything; `npm install -g @nurix/nustack` puts it on `PATH`. **Ask, never act** — a global npm install modifies the machine, and indexing writes to `~/.codegraph`. Record the answer with `recordDecision` either way, so the question is asked at most once per repo per machine.
-- **`accepted` but the binary is gone** — treat as undecided; a failed or removed install is not a standing yes.
-
-**A failed install is `absent`, not an error to retry.** Global installs fail on machines without permission; say so once, fall back, and move on. `npx @nurix/nustack` needs no install at all and is the shorter ladder when one command is all you want.
+If `nustack --version` fails, do not stall: read `tool.nustack` in `.claude/state/decisions.tsv` and fall back to the cold method — grep, targeted reads, `git log`.
 
-**An explicit invocation overrides a stored decline.** If the user asks for this skill by name, honour it and re-offer — "stop asking" must never become "never usable".
+- **`declined`** — fall back **silently**. Never mention the tool or re-offer it.
+- **Undecided** (no file, no key, or an unrecognised value) — fall back *and* offer the tool **once**: this repository could answer "where is / who calls / what changed / who owns" from an index instead of a grep sweep. `npx @nurix/nustack graph overview` runs it with no install; `npm install -g @nurix/nustack` puts it on `PATH`. **Ask, never act** — a global install modifies the machine and indexing writes to `~/.codegraph`. Record the answer with `recordDecision` either way, so the question is asked at most once per repo per machine.
+- **`accepted` but the binary is gone** — treat as undecided; a failed or removed install is not a standing yes.
 
-**A repository that has never been indexed** answers with the tool saying so rather than with a wrong answer. That is the tool degrading correctly, not a failure: `nustack graph index` builds it, under the same ask-first rule.
+**A failed install means absent — never retry it.** Global installs fail on machines without permission: say so once, fall back, move on. `npx` is the shorter ladder when one command is all you want.
 
-**Freshness is not your problem.** `nustack graph` re-indexes a stale store before it answers, so a query after a commit reports the new HEAD without anyone running an index first. Pass `--no-refresh` when you deliberately want the index as it stands — answering from a known-old index is a choice you can make, never one you make by accident. This is the one thing that changed when the code graph moved behind `nustack`: there is no staleness ritual left to perform.
+**An explicit invocation overrides a stored decline.** When the user asks for this skill by name, honour it and re-offer — "stop asking" must never become "never usable".
 
 Everything below assumes the tool is present.
 
-`nustack graph` defaults to the git root of the working directory — inside this repository, no flags are needed; `--repo <pathOrId>` asks about another one. Every answer states its own confidence per section (`CERTAIN` / `INFERRED` / `UNRESOLVED`), announces anything the token budget dropped, and says what an empty section means. Trust those labels.
+## What every answer carries
+
+- **Scope** — the git root of the working directory; no flags needed inside this repository. `--repo <pathOrId>` asks about another one.
+- **Confidence** — each section is labelled `CERTAIN`, `INFERRED` or `UNRESOLVED`; the answer announces anything the token budget dropped and says what an empty section means. Trust those labels.
+- **Freshness** — `nustack graph` re-indexes a stale store before it answers, so never run `index` to make a query correct. `--no-refresh` answers from the index as it stands — a deliberate choice, never an accidental one.
+- **A never-indexed repository** — the tool says so instead of answering wrongly. `nustack graph index` builds it, under the same ask-first rule as the install.
 
 ## The method order
 
 Localize through the index **before** opening any file, in this order; then read only the files it points at.
 
-1. **`nustack graph find <fragment>`** — symbols and file paths by name fragment. The entry point when you only have issue vocabulary. Symbol names only — it will never match string literals, dict keys, or SQL fragments (grep for those, without shame).
-2. **`nustack graph where-defined <symbol>`** / **`nustack graph outline <file>`** — pin the definition; map a big file. `outline` turns a 100+ declaration file into a navigable, line-numbered list — use it instead of reading god files blind. On a large file add `--budget 0` (see traps).
-3. **`nustack graph who-calls <symbol>`** / **`nustack graph impact <target>`** — callers, and blast radius (static reach + historical co-change reach, reported separately on purpose: they disagree, and the disagreement is information).
-4. **`nustack graph churn --days N --path <dir>`** · **`coupling --path <file>`** · **`owners <path>`** · **`tests-covering <file>`** — the history layer: what's hot, what changes together (including *hidden coupling* — co-change with no static reference, the one fact reading code cannot reveal), who knows this area and how recently, which test file historically guards this file.
+1. **`nustack graph find <fragment>`** — symbols and file paths by name fragment; the entry point when you have only the issue's vocabulary. It matches symbol names only — never string literals, dict keys, or SQL fragments; grep for those.
+2. **`nustack graph where-defined <symbol>`** / **`nustack graph outline <file>`** — pin the definition; map a big file. Use `outline` instead of reading a 100+ declaration file blind: it returns a navigable, line-numbered list. The default token budget truncates a large file's outline — pass `--limit N` (which lifts the budget) or `--budget 0`; an explicit `--budget` wins over `--limit`.
+3. **`nustack graph who-calls <symbol>`** / **`nustack graph impact <target>`** — callers, and blast radius. `impact` reports static reach and historical co-change reach separately; never merge them — where they disagree, the disagreement is the finding. `who-calls` also tabulates the keyword arguments each call site passes, so "which call sites omit this option" is one query.
+4. **`nustack graph churn --days N --path <dir>`** · **`coupling --path <file>`** · **`owners <path>`** · **`tests-covering <file>`** — the history layer: what is hot, what changes together, who knows this area and how recently, which test file historically guards this file. `coupling` surfaces *hidden coupling* — co-change with no static reference, which no amount of reading reveals.
 5. **`nustack graph god-objects --minSymbols 30`** / **`hotspots`** / **`overview`** — repo-scale orientation and risk.
 
-Then read, with `sed -n` ranges at the lines the index gave you. The index does discovery; reading does diagnosis. Add `--json` when a wrapper needs structure — the answer arrives inside the CLI's machine envelope, `{ nustackJsonVersion, command, ok, data }`.
+Then read with `sed -n` ranges at the lines the index gave you — the index does discovery, reading does diagnosis. Add `--json` when a wrapper needs structure; the answer arrives in the CLI's envelope, `{ nustackJsonVersion, command, ok, data }`.
 
-There is also **`nustack graph blame <file> [--line N]`** — the commits behind a file or one specific line, answered by git at query time; **`nustack graph refs <name>`** — the data-reference layer: where a name is used as a dict/object key, attribute/field, import, or type annotation, with read/write direction, and a cross-language flag when the same name spans Python and TypeScript files (this answers "who reads `x_axis_sort`" / "who writes `chart.query_context`" in one call — the questions that used to need grep); and **`nustack graph drift`** — near-duplicate function bodies crossed with co-change history: similar code whose files never change together is an unfinished refactor waiting to disagree. `who-calls` additionally tabulates which keyword arguments each call site passes, so "which call sites omit this option" is one query.
+| Other verb | Answers |
+| --- | --- |
+| `nustack graph blame <file> [--line N]` | The commits behind a file or one line, from git at query time |
+| `nustack graph refs <name>` | The data-reference layer: where a name is used as a dict/object key, attribute/field, import, or type annotation, with read/write direction and a cross-language flag when the name spans Python and TypeScript — "who reads `x_axis_sort`" / "who writes `chart.query_context`" in one call |
+| `nustack graph drift` | Near-duplicate function bodies crossed with co-change history — similar code whose files never change together is an unfinished refactor waiting to disagree |
+| `nustack graph status` | What the index holds — indexed HEAD, file and symbol counts, staleness. Reach for it when an answer surprises you |
+| `nustack graph index [--commits N]` | An explicit rebuild |
 
-**`nustack graph status`** reports what the index holds for this repository — indexed HEAD, file and symbol counts, whether it is stale — and **`nustack graph index [--commits N]`** rebuilds it explicitly. Reach for `status` when an answer surprises you and you want to know what it was computed from; you should never need `index` to make a query correct.
+## The boundary — what the index cannot answer
 
-## The boundary — what the index cannot answer (fall back immediately, don't retry)
+Fall back to reading immediately for these; never retry the index.
 
-- **Free-text string literals** (SQL templates, prose, format strings) — grep. Identifier-shaped keys and fields ARE indexed (`refs <name>`); anything longer or with spaces is not.
-- **Framework reflection** (Marshmallow `@post_load`, signal handlers, `appbuilder.add_api(Cls)` registration) — invisible to call edges. Bare decorator *application* (`@has_access_api`) IS indexed as a reference; what the decorator does and when it runs is not.
+- **Free-text string literals** (SQL templates, prose, format strings) — grep. Identifier-shaped keys and fields **are** indexed (`refs <name>`); anything longer or containing spaces is not.
+- **Framework reflection** (Marshmallow `@post_load`, signal handlers, `appbuilder.add_api(Cls)` registration) — invisible to call edges. A bare decorator *application* (`@has_access_api`) **is** indexed as a reference; what the decorator does and when it runs is not.
 - **Data flow and mechanism** ("does this value reach that function", "what order do these run in") — always reading work.
 
-Indexed symbol forms include statement declarations, `const X = () => {}`, named function expressions inside wrapper calls (`typedMemo(function DataTable() {})`), TS/JS class fields, and Python class-body fields (`is_dttm = Column(...)`); nested members render as `Parent › member` in `outline`.
+Indexed symbol forms: statement declarations, `const X = () => {}`, named function expressions inside wrapper calls (`typedMemo(function DataTable() {})`), TS/JS class fields, and Python class-body fields (`is_dttm = Column(...)`). `outline` renders nested members as `Parent › member`.
 
-## Traps (each cost a prior agent real time)
+## Traps
 
 - **Bare-name collision.** Call references match by name, not resolved binding. When a name has several definitions, `who-calls` lists every candidate and says so in its subject line — read that section before trusting the call sites, and pass `--scope <path-fragment>` (also on `find`, `where-defined`, `impact`) to narrow to a package.
-- **`nustack graph functions` lists the graph's own verbs**, not the repository's functions. For repo functions use `find`. An explicit `--limit` lifts the default token budget, so a full `outline` needs no `--budget 0` incantation (an explicit `--budget` still wins).
-- **Churn windows.** `churn --days 180` returning nothing does not mean quiet history — widen the window. Directory-scope churn ranks by raw commit count and buries small-but-critical files; for specific files use `owners`/`coupling` per file.
+- **`nustack graph functions` lists the graph's own verbs**, not the repository's functions. For repository functions use `find`.
+- **Churn windows.** An empty `churn --days 180` does not mean quiet history — widen the window. Directory-scope churn ranks by raw commit count and buries small-but-critical files; for specific files use `owners` / `coupling` per file.
 - **`tests-covering` is co-change evidence, not executed coverage** — it names the right test file to open; it cannot say the specific scenario is tested.
-- **Coupling on a busy file has a noise tail** — partners at <15% shared commits are usually PR-cohabitation, not real coupling. Verify a partner with a read before adding it to a touch-list.
-- **The history layer sees one window, and the refresh keeps resetting it to 5000 commits.** `churn`, `owners`, `coupling`, `blame` and `tests-covering` answer over the ingested commits, and an index — the automatic one included — takes the most recent 5000 unless `index --commits N` says otherwise. On a deeper repository those answers are true of the window, not of the repository, and the next refresh silently narrows a wider window back. Say "over the last N commits" when you report them, and re-ask for the depth you need.
-- **`owners` is authorship weight, not a file-touch tally** — an author is counted once per commit touching the path, however many of the path's files that commit changed. Do not transcribe its numbers as "files changed".
-- **The first query after a long gap pays for the re-index.** Absorption is not free: on a large repository the refresh takes tens of seconds before the answer appears. That is one wait, not a per-query cost — and `--no-refresh` skips it when you would rather have the old answer now.
+- **Coupling on a busy file has a noise tail** — partners below 15% shared commits are usually PR cohabitation, not real coupling. Verify a partner with a read before adding it to a touch-list.
+- **The history layer sees one window, and every refresh resets it to 5000 commits.** `churn`, `owners`, `coupling`, `blame` and `tests-covering` answer over the ingested commits; an index, the automatic one included, takes the most recent 5000 unless `index --commits N` says otherwise. On a deeper repository those answers are true of the window, not the repository, and the next refresh silently narrows a wider window back. Always report them as "over the last N commits", and re-ask for the depth you need.
+- **`owners` is authorship weight, not a file-touch tally** — an author counts once per commit touching the path, however many of its files that commit changed. Never transcribe its numbers as "files changed".
+- **The first query after a long gap pays for the re-index** — tens of seconds on a large repository before the answer appears. That is one wait, not a per-query cost; `--no-refresh` skips it when the old answer will do.
 
 ## Division of truth in this repository
 
-`docs/` is the source of truth for **intent** — what a feature is for, its invariants, decisions, vocabulary. The code graph is the source of truth for **facts** — where things are, who calls what, what changed together, who owns what. Never copy live facts (caller counts, churn numbers) into docs as if permanent; never ask the index for intent.
+`docs/` is the source of truth for **intent** — what a feature is for, its invariants, decisions, vocabulary. The code graph is the source of truth for **facts** — where things are, who calls what, what changed together, who owns what. **Never** copy live facts (caller counts, churn numbers) into docs as if permanent; never ask the index for intent.

package/data/harnesses/code/skills/polygraph/references/dispatch.md

@@ -4,7 +4,7 @@ Load when: composing a context pack, dispatching any role, packeting rows, recov
 
 ## The run folder
 
-`.claude/state/polygraph/{YYYY-MM-DD-slug}/` — machine-local, never tracked, deleted when the run closes:
+`.claude/state/polygraph/{YYYY-MM-DD-slug}/` is machine-local, never tracked, and deleted when the run closes:
 
 ```
 partials/{doc}.psv      one per finder — its whole output, no header
@@ -16,22 +16,22 @@ apply-{doc}.psv         id|outcome|note
 packs/{doc}.md          the context pack each finder and applier reads
 ```
 
-Work items pass through files, never through a dispatch call's arguments — a resumed agent may not carry arguments, and one that dies on a missing argument dies before it reads anything.
+**Work items pass through files, never through a dispatch call's arguments** — a resumed agent may not carry its arguments, and one that dies on a missing argument dies before it reads anything.
 
 ## The context pack — the agent's whole reading list
 
-One page per target document, written by you before the first dispatch. A brief that sends an agent to the charter, the backlog, the ownership index, or the findings file hands it a 500 KB read to extract 2 KB of fact — and hands the same read to every other agent in the wave. The pack carries the 2 KB:
+Write one page per target document before the first dispatch. **Never point an agent at the charter, the backlog, the ownership index, or the findings file** — that hands it a 500 KB read to extract 2 KB of fact, and hands the same read to every other agent in the wave. The pack carries the 2 KB:
 
 | Section | Content |
 | --- | --- |
-| Target | the doc path; for a plan target, the plan path and the Proposed Changes paths that intersect this doc's `owns:` |
-| Code | the doc's `owns:` globs, resolved to the files that exist today |
+| Target | the doc path; for a plan target, the plan path and the Proposed Changes paths that intersect the files this doc speaks for |
+| Code | the files the doc speaks for — the source files whose headers name it, and its `owns:` globs resolved to the files that exist |
 | Precedent | the quotations from guardrails, accepted decisions, and doctrine that **name** a subject this doc covers — the naming words only, with `path:line` |
 | Already tracked | backlog and register rows that name a subject this doc covers, as `path:line` |
 | Rulings | owner answers that bind this subject, verbatim |
 | Read budget | the two clauses below, verbatim |
 
-The two clauses every pack carries:
+Every pack carries these two clauses:
 
 > Tree state: re-check every citation against today's tree before acting; a claim that fails to reproduce dies as *did not reproduce* — never becomes an edit. READ-ONLY everywhere except your one output file.
 
@@ -51,30 +51,43 @@ Where the runtime has no such agent installed, dispatch an independent subagent
 
 ## Packets — one doc, one applier
 
-Routing is judgment, so you compose packets by hand; `audit.mjs` asserts the one mechanical invariant: **no document appears in two packets** — appliers run in parallel, and two agents in one file silently lose each other's edits.
+Compose packets by hand; routing is judgment. `audit.mjs` asserts the one mechanical invariant: **no document appears in two packets** — appliers run in parallel, and two agents in one file silently lose each other's edits.
 
-**Packet by the doc the fix belongs in, not the doc a row's evidence cites.** A row's citations say where the *evidence* lives; the fix usually belongs elsewhere, and a bounced row's `needs-cross-doc` note says exactly where. A row with no derivable doc goes to the owner — never into a packet "to see what the agent makes of it".
+- **Packet by the doc the fix belongs in, never the doc a row's evidence cites.** Citations say where the evidence lives; the fix usually belongs elsewhere, and a bounced row's `needs-cross-doc` note names where.
+- **A row with no derivable doc goes to the owner** — never into a packet "to see what the agent makes of it".
 
-By verdict: QUESTION and `depends_on` rows → the owner, inline. CONTESTED → you, with both sets of evidence. RESIDUE, and any row whose subject is a source file — a stale comment included — → the register. Everything else → the owning doc's packet.
+| Rows | Destination |
+| --- | --- |
+| QUESTION, and any row with `depends_on` set | the owner, in your report |
+| CONTESTED | you, with both sets of evidence |
+| RESIDUE, and any row whose subject is a source file — a stale comment included | the register |
+| everything else | the owning doc's packet |
 
 ## Verification — budgeted by what it caught
 
-- **The applier re-check is the law.** In the proving run it killed more false positives than every other mechanism combined.
-- **Blind re-derivation is discretionary.** Send a row *you* doubt — claim and subject only. As a mandatory stage it refuted nothing: finders' self-doubt is conservative, and the errors live in the confident pile, which is where your own read of the evidence looks. Disagreement makes the row CONTESTED; a verification never overwrites a verdict.
+- **The applier re-check is the law** — it kills more false positives than every other mechanism combined.
+- **Blind re-derivation is discretionary.** Send only a row *you* doubt, with claim and subject only. As a mandatory stage it refutes nothing: finders' self-doubt is conservative, and the errors sit in the confident pile, which is where your own read of the evidence looks. Disagreement makes the row CONTESTED; a verification never overwrites a verdict.
 
 ## Fold-back
 
-After each applier returns, its outcomes become row state by your own edit, then `audit.mjs` checks the arithmetic:
+After each applier returns, turn its outcomes into row state by your own edit, then run `audit.mjs` to check the arithmetic.
+
+| Outcome | Row state |
+| --- | --- |
+| `applied` · `registered` · `exempt-frozen` | `resolved`, the resolution stamped with how |
+| `refuted-on-apply` | `resolved`, resolution `did not reproduce` — a legitimate death; its count is the quality signal you report |
+| `needs-cross-doc` · `blocked-on-question` · `skipped` | stays open — repacket, or hold for the answer |
 
-- `applied` · `registered` · `exempt-frozen` → `resolved`, the resolution stamped with how.
-- `refuted-on-apply` → `resolved`, resolution `did not reproduce`. A legitimate death; its count is the quality signal you report.
-- `needs-cross-doc` · `blocked-on-question` · `skipped` → stays open — repacket, or hold for the answer.
-- COHERENT rows close when recorded; they carry no work.
+COHERENT rows close when recorded; they carry no work.
 
 ## Recovery
 
-**The file on disk is the recovery unit, never the wave.** A dead agent costs its remainder; read what landed and relaunch only that. A finder that returns **partial** at its turn cap is resumed once from its partial — a second partial is accepted as that doc's sweep and named as such in the report. Every dispatch names its output file and a time bound; an agent past its bound with no file is dead — relaunch it, never wait on it, and never let one runaway agent hold the run. Gates — lint, links, ownership — run in your own seat.
+**The file on disk is the recovery unit, never the wave.** A dead agent costs only its remainder: read what landed and relaunch that.
+
+- **Partial at the turn cap:** resume the finder once from its partial; a second partial is accepted as that doc's sweep and named as such in the report.
+- **Time bound:** every dispatch names its output file and a time bound. An agent past its bound with no file is dead — relaunch it, never wait on it, and never let one runaway agent hold the run.
+- **Gates** — lint, links, ownership — run in your own seat.
 
 ## Price
 
-State before dispatching, whenever a run exceeds ten documents or an owner directive names a tier: the per-doc cost at the pinned tier, the wave count under the concurrency ceiling, and the total; for a stronger tier, the multiplier and both totals. The directive and the estimate go in the changelog entry.
+**Before dispatching, state the price whenever a run exceeds ten documents or an owner directive names a tier:** the per-doc cost at the pinned tier, the wave count under the concurrency ceiling, and the total; for a stronger tier, the multiplier and both totals. The directive and the estimate go in the changelog entry.

package/data/harnesses/code/skills/polygraph/references/rows.md

@@ -35,23 +35,28 @@ id|subject|claim|evidence|counter_evidence|verdict|confidence|depends_on|status|
 | `UNBUILT` | a documented design with no code behind it — decided-unbuilt (the repo's marker convention), abandoned, or a document that should die; only the owner distinguishes the last two, so suspecting either makes the row a QUESTION | the marker |
 | `RESIDUE` | code a standing decision condemns by name — running, even load-bearing, and still retiring | a register row, never a doc edit |
 | `CONTESTED` | the evidence conflicts — a verifier and a finder disagree, or a claim has no code to arbitrate and a sibling document says otherwise | the primary judges with both sets of evidence in hand |
-| `QUESTION` | only the owner can resolve it — intent, not evidence, is what is missing | asked inline, answered in the same pass |
+| `QUESTION` | only the owner can resolve it — intent, not evidence, is what is missing | returned to the owner in full in the report; the answer arrives as a further dispatch |
 
 A disposition is the verdict's default; where the primary overrides it, the resolution says so. **A verification never overwrites a verdict** — disagreement makes the row CONTESTED.
 
 ## The residue guard
 
-Before an UNDOCUMENTED row becomes a doc edit, its subject is tested against the precedent pack — the one place the audit can silently undo the repo's own decisions. The test is **naming**: a precedent matches only when it names the subject — the file, table, route, command, or surface by the product's own name for it — and the row quotes the naming words into `evidence`. A precedent describing a *resembling* thing is not a match; shared adjectives ("legacy", "old export lane") are not a match; a misread pronoun is not a match. Unsure → QUESTION, never a silent RESIDUE.
+Test an UNDOCUMENTED row's subject against the precedent pack before it becomes a doc edit — this is the one place the audit can silently undo the repo's own decisions.
 
-The asymmetry runs both ways. A missed match resurfaces: the register is owner-read, and an UNDOCUMENTED row that should have been RESIDUE is caught when the owner reads the doc it produced. A false match does not: it retires code the product still ships and withholds its documentation — worse than the disease. When in doubt, ask.
+- **The test is naming.** A precedent matches only when it names the subject — the file, table, route, command, or surface, by the product's own name for it — and the row quotes the naming words into `evidence`.
+- **No match:** a precedent describing a *resembling* thing; shared adjectives ("legacy", "old export lane"); a misread pronoun.
+- **Unsure → QUESTION, never a silent RESIDUE.** The errors are not symmetric: a missed match resurfaces when the owner reads the doc it produced, but a false match retires code the product still ships and withholds its documentation.
 
 ## Frozen records and code
 
 - **Frozen records are exempt** — a completed plan, a changelog entry, an archived document resolves `exempt-frozen`; its claims were true when frozen and the tree does not correct history.
-- **The audit never edits code.** A code-side finding — a bug, a stale source comment, the unbuilt, residue — exits as a register row for the planning workflow, however small the edit and however directly it is asked for. **Markdown is not source**: every document read may be edited under the applier discipline, package and root READMEs included; the line is doc versus code, not proximity to `src/`.
+- **The audit never edits code.** A code-side finding — a bug, a stale source comment, the unbuilt, residue — exits as a register row for the planning workflow, however small the edit and however directly it is asked for.
+- **Markdown is not source.** Every document read may be edited under the applier discipline, package and root READMEs included; the line is doc versus code, not proximity to `src/`.
 
 ## A document's right to exist
 
-A wholly stale document passes a sentence-by-sentence audit one true sentence at a time, so a finder that reads a document whose subject is gone, whose authority another doc has absorbed, or whose content belongs inside a sibling emits **one QUESTION row proposing deletion or merge**, carrying the inbound-reference count (who links here, which index rows list it, which ownership globs it claims). Deletion is owner-approved, always. An approved deletion removes the file, repoints every inbound reference to the surviving authority, and leaves **no redirect stub** — an annotation, a banner, or a status flag left in the reading path is not a source of truth however carefully the surviving sentences are hedged. A document whose subject survives but whose content is wrong is MISDESCRIBED, not a deletion candidate.
+A wholly stale document passes a sentence-by-sentence audit one true sentence at a time. So a finder reading a document whose subject is gone, whose authority another doc has absorbed, or whose content belongs inside a sibling emits **one QUESTION row proposing deletion or merge**, carrying the inbound-reference count: who links here, which index rows list it, which ownership globs it claims.
 
-**Abandonment has no marker.** A design decided against is not owed: its claims come **out** of every marker that carried them rather than being reworded inside one, and the document survives as the record of a decision not to build, its status saying so. The tell that this went wrong: a reader finishes the paragraph still expecting the feature.
+- **Deletion is owner-approved, always.** An approved deletion removes the file, repoints every inbound reference to the surviving authority, and leaves **no redirect stub** — an annotation, banner, or status flag left in the reading path is not a source of truth, however carefully the surviving sentences are hedged.
+- **A surviving subject with wrong content** is MISDESCRIBED, never a deletion candidate.
+- **Abandonment has no marker.** A design decided against is not owed: its claims come **out** of every marker that carried them rather than being reworded inside one, and the document survives as the record of a decision not to build, its status saying so. The tell that this went wrong: a reader finishes the paragraph still expecting the feature.

package/data/harnesses/code/skills/schema-design/SKILL.md

@@ -5,13 +5,13 @@ description: "Use when designing or altering a relational schema — a new table
 
 # Schema Design — the doctrine
 
-You decide **what earns a table and where a fact lives** — for every Nurix relational schema, engine-agnostic (written for SQLite / Cloudflare D1 + Drizzle; a Postgres project keeps the same names and semantics with native types). Naming, the `id`/`slug`/`label` vocabulary, and column types are the `database.md` rule and are never restated here — this skill owns the design arguments consulted at schema-change time.
+You decide **what earns a table and where a fact lives** for every Nurix relational schema — written for SQLite / Cloudflare D1 + Drizzle; a Postgres project keeps the same names and semantics with native types. Naming, the `id`/`slug`/`label` vocabulary, and column types are the `database.md` rule; this skill never restates them.
 
-Apply the sections below to the change in hand; when reviewing, report violations with the section that names them.
+Apply the sections below to the change in hand; when reviewing, report each violation with the section that names it.
 
 ## What earns a table
 
-A table is the most expensive home for data — a migration to change its shape, a join to read, a mirror to keep in sync. Default to **not** a table — a concept earns one only with at least one property in the left column.
+A table costs a migration to reshape, a join to read, a mirror to keep in sync. Default to **not** a table — a concept earns one **only** with at least one property in the left column.
 
 | A table is earned by…                                                      | Lacking all of these, the data belongs in…              |
 | -------------------------------------------------------------------------- | ------------------------------------------------------- |
@@ -27,15 +27,14 @@ A table is the most expensive home for data — a migration to change its shape,
 
 Each right-column route is one test: process state — would a product feature break if this vanished the instant the request finished?; derived output — exactly recomputable from other rows + code?; un-addressed detail — is the row ever `SELECT`ed / `JOIN`ed / FK'd alone?; another system's record — does a specialized service (chat, telemetry, object store) already own it?
 
-- **Static vocabulary or a fixed graph → config, not a table** — HTTP status labels, a fixed onboarding funnel. Surface it in code as a constant/type; reifying it into tables plus a seed makes the file and the tables a two-copy sync problem. The refined boundary is § Vocabulary / lookup tables.
-- **History → one immutable log + a mutable head.** Never shatter versioning into per-entity `*_revisions` / `*_revision_sections` tables — snapshot the coherent set into one append-only versions table; current state is a projection of the newest entry. A table that is just "old rows of another table" collapses into the snapshot.
+- **Static vocabulary or a fixed graph → config, not a table** — HTTP status labels, a fixed onboarding funnel. Surface it in code as a constant or type; reifying it into tables plus a seed makes the file and the tables a two-copy sync problem. The refined boundary is § Vocabulary / lookup tables.
+- **History → one immutable log + a mutable head.** **Never** shatter versioning into per-entity `*_revisions` / `*_revision_sections` tables — snapshot the coherent set into one append-only versions table; current state is a projection of the newest entry. A table that is just "old rows of another table" collapses into the snapshot.
 - **A surviving table names the invariant it buys** — content-addressed immutable rows buy reproducibility, a monotonic sequence buys ordering/sync, an atomic write boundary buys multi-row atomicity. Drop the requirement and the table drops with it.
-
-Table count tracks **requirements, not domain richness** — a rich domain is not entitled to a table per noun.
+- **Table count tracks requirements, not domain richness** — a rich domain is not entitled to a table per noun.
 
 ## State, rules, and history
 
-**One fact has one home, chosen by what kind of fact it is.** Confusing these produces the most common redundant table in a schema — a queue whose rows restate state the entity already carries.
+**One fact has one home, chosen by what kind of fact it is.**
 
 | The fact | Home | Example |
 | --- | --- | --- |
@@ -45,7 +44,7 @@ Table count tracks **requirements, not domain richness** — a rich domain is no
 | What a consumer must **replay in order** | the **sequence log** | an `app_events` row keyed `(app_id, sequence)` |
 
 - **State becomes a column the moment anything selects on it.** `WHERE state = 'blocked'` takes an index; `WHERE json_extract(metadata, '$.state') = 'blocked'` scans the table and is invisible to every schema check. JSON keeps only what § What earns a table leaves it — detail nothing addresses alone.
-- **A pending-work table mirroring row state is the anti-pattern** — `*_actions`, `*_inbox`, `*_flags`. The tell: resolving one of its rows also updates the entity, so two rows answer one question and are free to disagree. The *open question* is a column beside the state (at most one per row ⇒ a column, § A junction spells many-to-many); the *answer given* is an audit-log row.
+- **A pending-work table mirroring row state is the anti-pattern** — `*_actions`, `*_inbox`, `*_flags`; it is the most common redundant table in a schema. The tell: resolving one of its rows also updates the entity, so two rows answer one question and are free to disagree. The *open question* is a column beside the state (at most one per row ⇒ a column, § A junction spells many-to-many); the *answer given* is an audit-log row.
 - **Legal transitions live in code, never as rows** — a `status_transitions` table is a state machine the database cannot enforce and the code must re-implement anyway to use.
 
 **The two logs are not substitutes**, and no one table serves both:
@@ -58,36 +57,36 @@ Table count tracks **requirements, not domain richness** — a rich domain is no
 | Records | only what **happened** | **attempts too** — `denied`, `failure` |
 | Read by | cursors replaying forward | investigations, at any age |
 
-The bottom two rows are why neither can hold the other's rows: an event at a scope with no entity has no sequence to take, and a refused attempt in a replay stream would have consumers apply something that never happened.
+The Scope and Records rows are why neither can hold the other's rows: an event at a scope with no entity has no sequence to take, and a refused attempt in a replay stream would have consumers apply something that never happened.
 
 ### The audit log's own shape
 
-**An audit log outlives every row it names, so it stores what it needs to stay readable without them.** Both consequences are missing from most first drafts:
+**An audit log outlives every row it names, so it stores what it needs to stay readable without them.**
 
-- **Denormalize the display at write time** — `actor_label`, `target_label` beside `actor_id` / `target_id`. Ids alone leave the log intact but unreadable once the person or record is deleted, which is the one thing it exists to survive.
+- **Denormalize the display at write time** — `actor_label`, `target_label` beside `actor_id` / `target_id`. Ids alone leave the log intact but unreadable once the person or record is deleted.
 - **Record the attempt, not the success** — `outcome` (`success | failure | denied`) plus a `reason`. Refused sign-ins and permission denials are most of what anyone opens an audit log for; without the column they cannot be written at all.
 - **Keep the columns product-neutral** — `actor_*` · `action` · `outcome` · `target_*` · `scope_path` · `channel` · `source_ip` · `correlation_id` · `changes_json` serve any domain. Per-level tenancy columns tie the log to today's model; a materialized `scope_path` (`workspace:abc/app:def`) makes "everything under this tenant" one prefix scan and survives a new level appearing — at the price of enforcing the hierarchy in code rather than a `CHECK`.
 
 ## Scope, not parallel tables
 
-One entity that exists at several scopes is **one table with a nullable scope column** — never one table per scope, and never one table shared across entity families.
+One entity that exists at several scopes is **one table with a nullable scope column** — **never** one table per scope, and **never** one table shared across entity families.
 
 - **A table shared by several families carries the union of their columns** — one `settings` table for users, apps, and workspaces. Almost nothing can be `NOT NULL`, the payload lands in JSON beyond every constraint, index, and FK, and a new family widens a table other features already depend on. One table per family.
 - **Two tables declared to have "the same columns" are two schemas maintained by hand** — the drift is silent, surfacing as an incomplete copy, never as an error. Collapse them and discriminate by column.
 - **The scope column is the discriminator** (`app_id IS NULL` = parent scope, set = child scope). Copying a scope is then `INSERT … SELECT` over one table with one column rewritten, so source and target cannot disagree about shape.
-- **A nullable owner column is how a row exists before its owner does** — a pending enrolment or unclaimed record is creatable before the owner is known, which is what lets a `pending_*` / `*_requests` table collapse into the real one.
-- **A reserved row can own the shipped defaults.** A fixed-id "system" parent makes the defaults and a tenant's copy the same kind of row, through the same code. It must then be excluded from every tenant-scoped query — state that invariant where the id is defined.
+- **A nullable owner column lets a row exist before its owner does** — a pending enrolment or unclaimed record is creatable before the owner is known, which collapses a `pending_*` / `*_requests` table into the real one.
+- **A reserved row can own the shipped defaults.** A fixed-id "system" parent makes the defaults and a tenant's copy the same kind of row, through the same code. It **must** then be excluded from every tenant-scoped query — state that invariant where the id is defined.
 
 ## Copying rows between scopes
 
-- **A copied junction row is already correct with no remapping** — its endpoints are `slug` references (§ Keys & the shared vocabulary), and a slug means the same thing in every scope. Rewriting ids through a source→copy map is the most error-prone step in a multi-level copy, and a partial failure leaves wiring pointed into another scope rather than raising.
+- **A copied junction row is already correct with no remapping** — its endpoints are `slug` references (the `database.md` rule § Keys & the shared vocabulary), and a slug means the same thing in every scope. Rewriting ids through a source→copy map is the most error-prone step in a multi-level copy, and a partial failure leaves wiring pointed into another scope rather than raising.
 - **Provenance is a soft reference — no FK.** `source_id` must outlive its referent; an FK would either block the source's deletion or erase the lineage.
 - **Store the source's version at copy time** — `version` + `source_version` make "is an upgrade available" a comparison of two stored values, not a content diff.
-- **A copy is a row, never a live read.** Nothing at the child scope reads the parent's row at runtime; propagation happens only through an explicit re-copy, so a local edit is never silently overwritten.
+- **A copy is a row, never a live read.** Nothing at the child scope reads the parent's row at runtime; propagation happens **only** through an explicit re-copy, so a local edit is never silently overwritten.
 
 ## A junction spells many-to-many — nothing else
 
-**A `_map` table is the schema's notation for M:N. Using it for 1:M is a category error** — the junction's own uniqueness admits many parents per child, so the "one parent" rule stops being enforced the moment it is written this way. Cardinality decides between the only two shapes:
+**A `_map` table is the schema's notation for M:N. Using it for 1:M is a category error** — the junction's own uniqueness admits many parents per child, so the "one parent" rule is unenforced from the moment it is written. Cardinality decides between the only two shapes:
 
 | Relationship | Shape |
 | --- | --- |
@@ -95,7 +94,7 @@ One entity that exists at several scopes is **one table with a nullable scope co
 | **M:N** — both sides have many | a **`<a>_<b>_map` junction** with a composite unique |
 
 - **The test is one question about the child**: can this row ever belong to two parents at once? No ⇒ column. A junction "in case it becomes M:N later" ships the unenforced model today to buy a migration you may never run.
-- **A junction for a 1:M also** makes the association a row that can go missing independently of the child — a child can exist correctly while its wiring does not — and forces a join onto the most common read in the system.
+- **A 1:M junction also** makes the association a row that can go missing independently of the child — the child exists correctly while its wiring does not — and forces a join onto the most common read in the system.
 - **A junction carrying only its two endpoints and timestamps is the tell** — a real M:N junction usually earns its own columns (a role, an order, a status); one that never does is a 1:M waiting to be collapsed into a column.
 - **Collapsing deletes a copy step** — the association travels inside the row it belongs to: no second pass to remap, no copy landing with its wiring half-applied.
 - **A pair already recorded elsewhere needs no table at all.** If an append-only log stores `(parent, child)` on every write, the association table is `SELECT DISTINCT` over that log — a cache free to disagree with the log it derives from (§ What earns a table).
@@ -107,13 +106,13 @@ One entity that exists at several scopes is **one table with a nullable scope co
 | Action | Why it fails on an append-only table |
 | --- | --- |
 | `SET NULL` | It is an **UPDATE**. An append-only trigger aborts it, so the parent's deletion fails — with an error naming the trigger, not the constraint. |
-| `CASCADE` | Deletes history to delete a person. The log exists precisely to outlive its subjects. |
-| `NO ACTION` | Makes anyone who ever appeared in the log undeletable — the hub defect above. |
+| `CASCADE` | Deletes history to delete a person. The log exists to outlive its subjects. |
+| `NO ACTION` | Makes anyone who ever appeared in the log undeletable — the hub-table defect of the `database.md` rule § Keys & the shared vocabulary. |
 
 - **`SET NULL` is the trap** — it reads like a safe relaxation of `NO ACTION` and passes review as one.
-- **Record the actor as a plain column** — the same soft-reference treatment provenance gets (`source_id`, `thread_id`). The log keeps naming who acted after the account is gone, which is what an audit trail is for.
-- **`CASCADE` from the append-only side's own parent is still fine** — a cascade is a DELETE, so a `BEFORE UPDATE` trigger never sees it: an App's log dying with the App is legitimate, distinct from erasing a log to delete a person.
-- **State the exemption where it exists.** A catalog whose rows must not disappear under a referencing row (a service definition, a vocabulary) keeps `NO ACTION` deliberately — that guarantee is worth one line saying so.
+- **Record the actor as a plain column** — the same soft-reference treatment provenance gets (`source_id`, `thread_id`), so the log keeps naming who acted after the account is gone.
+- **`CASCADE` from the append-only side's own parent is fine** — a cascade is a DELETE, so a `BEFORE UPDATE` trigger never sees it: an App's log dying with the App is legitimate, distinct from erasing a log to delete a person.
+- **State the exemption where it exists.** A catalog whose rows must not disappear under a referencing row (a service definition, a vocabulary) keeps `NO ACTION` deliberately — one line saying so.
 
 ## Uniqueness with a nullable column
 
@@ -128,28 +127,27 @@ CREATE UNIQUE INDEX <t>_child_slug_unique  ON <t> (child_id, slug)  WHERE child_
 
 ## Vocabulary / lookup tables
 
-A controlled vocabulary earns a **table** only when a user row FKs into it and reads its `label` / `description` at runtime — a service catalog rendered in a picker; static dev-authored config nobody references by FK stays **config** (§ What earns a table) — a `doc_type` value list. Enumerable is not tabular, and a `type`-style column validated against the constants file beats an FK to a seeded mirror. An earned table has a fixed shape: `id` (UUID) · `slug` (UNIQUE) · `label` · optional `description` · `status` · timestamps.
+A controlled vocabulary earns a **table** **only** when a user row FKs into it and reads its `label` / `description` at runtime — a service catalog rendered in a picker. Static dev-authored config nobody references by FK stays **config** (§ What earns a table) — a `doc_type` value list. Enumerable is not tabular: a `type`-style column validated against the constants file beats an FK to a seeded mirror. An earned table has a fixed shape: `id` (UUID) · `slug` (UNIQUE) · `label` · optional `description` · `status` · timestamps.
 
-- **Seeds are generated, never hand-written** — the source of truth is an authored tree (§ Seeding) or a shared package; a generator emits the `*.seed.sql` with UUIDv5 ids and an idempotent `ON CONFLICT(slug)` upsert that preserves live counts / admin-tuned columns. ❌ Hand-editing seed SQL — regenerate it.
+- **Seeds are generated, never hand-written** — the source of truth is an authored tree or a shared package, compiled and loaded per § Seeding.
 
 ## Seeding — authored source, compiled artifact, loaded rows
 
 Curated data that ships with the product — vocabularies, catalogs, reference profiles — is **authored in a tree, compiled to SQL, and loaded**. The compiled artifact is build output, not source.
 
-```
-seed/<data>/**        authored source, COMMITTED — the only thing a human edits
-      ↓ compile       mechanical: parse, validate, emit. No judgment, no network
-seed/sql/*.seed.sql   build output, GITIGNORED — rebuilt on every run
-      ↓ load          the engine's own client (wrangler d1 execute, psql -f)
-```
+| Stage | Where | Rule |
+| --- | --- | --- |
+| Author | `seed/<data>/**` | committed — the only thing a human edits |
+| Compile | emits `seed/sql/*.seed.sql` | mechanical — parse, validate, emit; no judgment, no network. Output is gitignored and rebuilt on every run |
+| Load | the engine's own client — `wrangler d1 execute`, `psql -f` | idempotent |
 
-- **Never commit the compiled artifact.** Rebuilt seconds before it is applied, it cannot go stale — so nothing checks it for drift and no freshness test is owed. A committed `.sql` needs that check; a gitignored one needs nothing. ❌ Hand-editing compiled SQL — regenerate.
+- **Never commit the compiled artifact.** Rebuilt seconds before it is applied, it cannot go stale, so it owes no drift check and no freshness test; a committed `.sql` would owe both. **Never hand-edit seed SQL** — regenerate it.
 - **The load is idempotent**: UUIDv5 ids derived from the natural key plus `ON CONFLICT(slug) DO UPDATE`, preserving live counts and admin-tuned columns. Re-seeding is a no-op, never a duplicate.
-- **A build step that reads the artifact runs the compiler first.** Bundlers resolve imports at *build* time, so a gitignored artifact breaks a fresh clone with a resolution error rather than a test failure — wire `pretest` / `prebuild`.
+- **A build step that reads the artifact runs the compiler first** — wire `pretest` / `prebuild`. Bundlers resolve imports at *build* time, so a gitignored artifact breaks a fresh clone with a resolution error rather than a test failure.
 
 ### Choosing the authoring format
 
-**Choose by what the payload is, not by where it lands.** That the destination is a relational table argues nothing about the source: rows routinely carry document-valued columns, and the compiler exists precisely to bridge the two shapes. The litmus is one question per field — **is this a scalar a human scans in a table, or prose a human reads in paragraphs?**
+**Choose by what the payload is, not by where it lands.** A relational destination argues nothing about the source: rows routinely carry document-valued columns, and the compiler exists to bridge the two shapes. The litmus is one question per field — **is this a scalar a human scans in a table, or prose a human reads in paragraphs?**
 
 | Payload | Format | Why |
 | --- | --- | --- |
@@ -164,7 +162,7 @@ seed/sql/*.seed.sql   build output, GITIGNORED — rebuilt on every run
 
 ### Rigidity comes from validators, never from containers
 
-**No file format enforces a shape.** CSV checks no types, no required fields, no nesting — not even column count. YAML and JSON check only that the syntax parses. Every format is a container; the shape is enforced by a schema or not at all, so a format migration undertaken to gain rigidity buys none.
+**No file format enforces a shape.** CSV checks no types, no required fields, no nesting — not even column count; YAML and JSON check only that the syntax parses. The shape is enforced by a schema or not at all, so a format migration undertaken to gain rigidity buys none.
 
 - **Validate at the compile boundary and fail the build**, naming the file and the reason. A compiler that checks only *parseability* ships a typo'd key or a missing map straight to production, where it is served with full authority.
 - **Declare the shape as a schema and share it** between the compiler that writes the column and the code that reads it — one definition, so compile-time and read-time cannot disagree. A `values_json`-style column is opaque to the database; that schema is the only thing standing between it and `unknown` at the read site.
@@ -173,24 +171,24 @@ seed/sql/*.seed.sql   build output, GITIGNORED — rebuilt on every run
 
 ### Canonicalize, never repair
 
-Two operations get called "cleaning the data" and only one is safe:
+Two operations get called "cleaning the data"; only one is safe:
 
 | Operation | Verdict | Why |
 | --- | --- | --- |
 | **Canonicalization** — deterministic and information-preserving: slug folding, diacritic normalization, key and unit ordering | ✅ belongs in the compiler | The same input always yields the same output, and nothing is invented |
 | **Repair** — filling, clamping, defaulting, or dropping content that failed validation | ❌ reject loudly instead | Deciding what the author meant *is* judgment; a repaired row is then served indistinguishably from a curated one |
 
-**Correction cannot be both unintelligent and correct.** A pipeline that guesses at malformed input has swapped a loud rejection for a quiet wrong answer — and for curated data, whose whole value is that a human judged it, that is corruption wearing the name of automation. Reject-with-report is what scales: the producer retries, or a human triages.
+**Never guess at malformed input** — a guessing pipeline swaps a loud rejection for a quiet wrong answer, and for curated data, whose whole value is that a human judged it, that is corruption. Reject with a report: the producer retries, or a human triages.
 
 ### Ingesting scraped or generated data
 
-Automated sources produce **candidate raw material, not rows.** Publish the compile-boundary schema as the ingestion contract and run scraped output through it unchanged — validate, reject loudly on mismatch, queue the survivors for curation. A curator promotes a candidate by adding the judgment the source could not supply: the rationale, the caveat, the editorial line. A pipeline that lets unreviewed extracts land directly as catalog rows has quietly swapped a curated corpus for a scraped one.
+Automated sources produce **candidate raw material, not rows.** Publish the compile-boundary schema as the ingestion contract and run scraped output through it unchanged — validate, reject loudly on mismatch, queue the survivors for curation. A curator promotes a candidate by adding the judgment the source could not supply: the rationale, the caveat, the editorial line. **Never** let an unreviewed extract land directly as a catalog row — that swaps a curated corpus for a scraped one.
 
 ## Run
 
 1. **Route every new fact through § What earns a table** — default to *not* a table; name the left-column property that earns one, or the right-column home it takes instead.
 2. **Classify every fact by § State, rules, and history** — now-state → entity column; rules → code; what-was-done → audit log; replayable → sequence log.
-3. **Check cardinality before any junction** (§ A junction spells many-to-many) and every FK's `ON DELETE` (§ Keys, § Append-only).
-4. **Prove uniqueness claims by inserting the forbidden duplicate** — a schema review cannot tell a firing index from a silent one by reading.
+3. **Check cardinality before any junction** (§ A junction spells many-to-many) and every FK's `ON DELETE` — hub edges per the `database.md` rule § Keys & the shared vocabulary, append-only edges per § Foreign keys into and out of append-only tables.
+4. **Prove every uniqueness claim by inserting the forbidden duplicate** (§ Uniqueness with a nullable column).
 5. **For a seed pipeline, walk § Seeding** — format chosen by payload rather than by destination, shape enforced by a schema at the compile boundary, artifact gitignored, correction limited to canonicalization.
 6. **Report as a findings list** — one line per violation: the section, the table/column, the fix.