@nurix/etna 0.20.36 → 0.20.38

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

@@ -1,12 +1,12 @@
 # Jira — 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/02-jira.md` (2026-08-19).
+Access options in preference order. Probe each in order; use the first that answers.
 
 ## Option 1 — the official Atlassian Remote MCP Server (Cloud only)
 
 Probe: an `atlassian` entry in `.mcp.json` / Atlassian MCP tools visible in-session.
 Setup: `claude mcp add --transport http atlassian https://mcp.atlassian.com/v1/mcp/authv2`, then `/mcp` in-session for the OAuth 2.1 flow. **Cloud only — no Data Center.** Rate limits: 500–1,000 calls/hr by plan.
-**Tool names are unpublished by Atlassian** — introspect the live tool list from your session (ToolSearch / the MCP tool listing) before planning calls; expect find/create/update/comment/transition capabilities per Atlassian's own examples.
+**Atlassian publishes no tool names** — introspect the live tool list from your session (ToolSearch / the MCP tool listing) before planning calls; expect find/create/update/comment/transition capabilities per Atlassian's own examples.
 
 ## Option 2 — community MCP: `sooperset/mcp-atlassian` (Cloud + Server/DC)
 
@@ -16,7 +16,7 @@ Confirmed tool names: `jira_get_issue` · `jira_search` (JQL) · `jira_create_is
 
 ## Option 3 — CLIs
 
-**acli** (Atlassian-official). Probe: `acli --version` + an authenticated site. **Namespace is `workitem`, not `issue`.**
+**acli** (Atlassian-official). Probe: `acli --version` + an authenticated site. **The namespace is `workitem`, not `issue`.**
 `acli jira workitem view KEY-1 --json` · `workitem search --jql "..." --json [--paginate]` · `workitem create --summary --project --type` · `workitem comment create --key KEY-1 --body "..."`.
 
 **jira-cli** (ankitpokhrel, 5.9k★, MIT). Probe: `jira me`. Setup: `jira init` (Cloud: email + `JIRA_API_TOKEN`; DC: PAT + `JIRA_AUTH_TYPE=bearer`).
@@ -26,15 +26,18 @@ Confirmed tool names: `jira_get_issue` · `jira_search` (JQL) · `jira_create_is
 
 Basic auth `email:API_token`. Base `https://<domain>.atlassian.net/rest/api/3/`.
 - Read: `GET /rest/api/3/issue/{KEY}`
-- **JQL search: `GET /rest/api/3/search/jql`** — the old `/rest/api/3/search` is deprecated and being removed; do not use it.
+- **JQL search: `GET /rest/api/3/search/jql`** — **never** `/rest/api/3/search`, which Atlassian has deprecated for removal.
 - Create: `POST /rest/api/3/issue` — **`description` must be ADF** (`{"type":"doc","version":1,"content":[…]}`).
 - Comment: `POST /rest/api/3/issue/{KEY}/comment` — body must be ADF.
-- **ADF inconvenient → v2**: `/rest/api/2/issue` + `/rest/api/2/issue/{KEY}/comment` take plain-string bodies; v2 JQL endpoint is `/rest/api/2/search`.
+- **ADF inconvenient → v2**: `/rest/api/2/issue` + `/rest/api/2/issue/{KEY}/comment` take plain-string bodies; the v2 JQL endpoint is `/rest/api/2/search`.
 
 ## Composing for Jira
 
-Map to the project's real issue types (`Bug`/`Story`/`Task` — list them, don't assume). Set `components` from the owning doc's `module:` where components exist. Atlassian renamed "issue" → "work item" in UI/acli — expect both vocabularies. Leave estimates, sprints, and epic links to humans unless instructed.
+- Map to the project's real issue types (`Bug`/`Story`/`Task`) — list them; never assume.
+- Set `components` from the owning doc's `module:` where components exist.
+- Atlassian's UI and `acli` say "work item" where the API says "issue" — expect both vocabularies.
+- Leave estimates, sprints, and epic links to humans unless instructed.
 
-## Ecosystem notes (2026-08-19)
+## Ecosystem notes
 
-No official Anthropic Jira skill. Community skills exist at small adoption (JIRA-Assistant-Skills 42★, two atlassian-skills repos, an acli wrapper) — nothing to defer to; this pack is self-sufficient.
+No official Anthropic Jira skill exists, and the community skills (JIRA-Assistant-Skills 42★, two atlassian-skills repos, an acli wrapper) are small-adoption — this pack defers to none of them.

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.