@nurix/etna 0.20.36 → 0.20.38

package/data/harnesses/code/skills/documentation/references/instruction-style.md

@@ -1,4 +1,4 @@
-# Instruction-File Style
+# Instruction-file style
 
 The shared style for every file an agent obeys — a `CLAUDE.md`, a rule, an agent definition, skill prose. Prose style only: frontmatter is metadata, not style. Docs-tree documents follow the skill's templates and [`style-guide.md`](style-guide.md) instead.
 
@@ -6,11 +6,11 @@ The shared style for every file an agent obeys — a `CLAUDE.md`, a rule, an age
 
 An instruction file is paid for whenever it loads, scaled by its load class: `CLAUDE.md` and unscoped rules load on **every turn of every session** — the most expensive prose in a repo per word; a `paths:`-scoped rule loads on those same terms from its first matching file read on; an agent definition loads per dispatch, a skill per invocation. The bar is not "is this true?" but **"must this be in front of the agent whenever this file loads?"** Measure weight in tokens, not lines; trim biggest-first on every edit.
 
-**Rewriting, the test is armor vs. narration.** A reason clause either blocks a move an agent would otherwise make — the failure is counter-intuitive, the wrong fix looks correct, or the rule reads as arbitrary tidiness and gets "improved away" — or it explains the self-evident. Ask of each: *does the forbidden move look correct to an agent mid-task?* Keep the first kind, cut the second. **A constraint may lose its explanation; it may never lose its existence** — compression is fewer words for the same constraints, so a passage that cannot shrink without dropping one stays long.
+**On a rewrite, the test is armor vs. narration.** A reason clause either blocks a move an agent would otherwise make — the failure is counter-intuitive, the wrong fix looks correct, or the rule reads as arbitrary tidiness and gets "improved away" — or it explains the self-evident. Ask of each: *does the forbidden move look correct to an agent mid-task?* Keep the first kind, cut the second. **A constraint may lose its explanation; it may never lose its existence** — compression is fewer words for the same constraints, so a passage that cannot shrink without dropping one stays long.
 
 ## Coherence
 
-A rewrite is not only a trim — read the file as one artifact and fix what disagrees or is missing:
+A rewrite is not only a trim. Read the file as one artifact and fix what disagrees or is missing:
 
 - **Two statements of one fact agree, or become one.** A defaults block vs. the worked example beside it, a table row vs. a bullet — reconcile against the code the rule governs and keep one canonical statement; a silent disagreement is worse than either version alone, because each reader picks a different one.
 - **Every cross-reference resolves** — the cited `§`, sibling file, or command exists and still says what the citation claims. Section numbers are a public surface other files cite: append, never reshuffle.

package/data/harnesses/code/skills/documentation/references/source-comments.md

@@ -2,17 +2,17 @@
 
 Load when: writing or sweeping source-file comments, or cutting a comment whose claim belongs in a document. Not needed to write a document.
 
-**In `docs/`, never in the file's comments** — and this skill is the half of that rule that makes it safe. A source file carries a repo-relative path header of two or three present-tense sentences and one third-person sentence above each non-obvious function; the shape is the harness's `CLAUDE.md` § File Structure, which is canonical and is not restated here. That header's `docs/…` path is also the file's edge into the knowledge graph: the header pointer names the document that speaks for the file, which is how ownership is computed ([`frontmatter.md`](frontmatter.md)). What lands **here** is everything that shape displaces: design rationale, the alternatives weighed, the measurement behind a constant, the reason an obvious-looking change is wrong.
+**In `docs/`, never in the file's comments** — and this skill is the half of that rule that makes it safe. A source file carries a repo-relative path header of two or three present-tense sentences and one third-person sentence above each non-obvious function; the canonical shape is the harness's `CLAUDE.md` § File Structure. That header's `docs/…` path is also the file's edge into the knowledge graph: the header pointer names the document that speaks for the file, which is how ownership is computed ([`frontmatter.md`](frontmatter.md)). What lands **here** is everything that shape displaces: design rationale, the alternatives weighed, the measurement behind a constant, the reason an obvious-looking change is wrong.
 
 **Cutting a comment is a move, not a deletion.** A claim taken out of a source file is owed one of two things before the cut is done, and the choice is per claim, not per file:
 
 | The claim is | What it earns |
 | --- | --- |
 | Worth keeping, and its doc does not state it | A section in the **owning feature doc** (the ownership index resolves which), carrying the claim and the argument for why the codebase is worse without it — never the comment's wording, which was written for a reader holding the code |
-| Already stated in its doc | Nothing — but you **open that doc and find the sentence** before saying so. An assumed duplicate is how a claim is lost |
+| Already stated in its doc | Nothing, once you **open that doc and find the sentence**. An assumed duplicate is how a claim is lost |
 | History, a ticket or decision-record reference, a dated note, a divider, or narration of code that no longer exists | Nothing, and no record. A record lives in `docs/history/`; these are not claims about the present |
 
-**Count what you cut, and prove the cut was only comments.** A comment sweep states comment lines before and after per file, so a drop nobody accounted for is visible as a number rather than as a feeling. [`scripts/comment-strip.mjs`](../scripts/comment-strip.mjs) turns that from a claim into a check: it strips comments from both revisions — honouring strings, template and character literals, regex literals, raw strings and JSX comment braces — and diffs what is left, so a sweep that quietly changed executable code cannot pass as a cleanup. `comment-strip.mjs --rev <before> --to <after> <paths…>` exits 0 for "no executable code changed" and 1 naming the file and the first diverging line. Run it over any pass that touches more than a handful of files; a sweep without it is an assertion.
+**Count what you cut, and prove the cut was only comments.** A comment sweep states comment lines before and after per file, so an unaccounted drop shows as a number. [`scripts/comment-strip.mjs`](../scripts/comment-strip.mjs) turns that from a claim into a check: it strips comments from both revisions — honouring strings, template and character literals, regex literals, raw strings and JSX comment braces — and diffs what is left, so a sweep that quietly changed executable code cannot pass as a cleanup. `comment-strip.mjs --rev <before> --to <after> <paths…>` exits 0 for "no executable code changed" and 1 naming the file and the first diverging line. Run it over any pass that touches more than a handful of files; a sweep without it is an assertion.
 
 **The mechanical half of the shape is checked, not remembered.** [`scripts/source-lint.mjs`](../scripts/source-lint.mjs) `--changed` reports a header that names another path or none, a change whose added lines are over a quarter comments, and the four shapes the convention deletes outright — narration, ALL-CAPS emphasis, an over-long header, a comment block that has become a document. Block-severity findings must be fixed; the escape hatch is a `source-lint-disable: <id>` comment with the reason in a second comment beside it, and the only finding that legitimately takes one is a booby trap. The harness detector raises a bookkeeping row for the same condition, so an unfixed breach outlives the session that wrote it.
 

package/data/harnesses/code/skills/documentation/references/style-guide.md

@@ -1,9 +1,9 @@
 <!-- doc-lint-disable: date-in-truth-doc, history-narration, stale-tripwire, progress-marker, temporal-hedge, predecessor-frame, status-glyph -->
 <!-- reason: the style authority quotes the forbidden constructions verbatim in its ❌ columns; each match is an example of what not to write. -->
 
-# Documentation Style Guide
+# Documentation style guide
 
-This guide states how a document is written: every file under `docs/` and every README the `documentation` skill authors or edits. Two neighbouring authorities answer the questions beside it. [`instruction-style.md`](instruction-style.md) governs the files an agent obeys (`CLAUDE.md`, rules, agents, skill prose), which are paid for on every load and written lean; each template in [`templates/`](../templates/Readme.md) governs its genre's sections and fields. The first two sections of this guide are enough to write a correct document; the sections after them are the detail each principle unfolds into, and a reader who stops early holds a coarse picture that is still true.
+This guide states how a document is written: every file under `docs/` and every README the `documentation` skill authors or edits. Two neighbouring authorities answer the questions beside it: [`instruction-style.md`](instruction-style.md) governs the files an agent obeys (`CLAUDE.md`, rules, agents, skill prose), which are paid for on every load and written lean, and each template in [`templates/`](../templates/Readme.md) governs its genre's sections and fields. The first two sections are enough to write a correct document; the sections after them are the detail each principle unfolds into, so a reader who stops early holds a coarse picture that is true.
 
 ## The model
 
@@ -75,7 +75,7 @@ The test (principle 3) decides what a sentence may say. These survive it:
 
 Unbuilt work has one home per kind. Decided design the code does not do yet is an `UNBUILT` block where the design is stated; a shortfall in what is built (a promise the code does not keep, a case it mishandles) is one bullet under Gaps; the work that would close either is a backlog row, and the document never tracks that work's progress.
 
-The authority split (principle 4) is stated once, where agents enter the docs (the root instruction file or `docs/README.md`), so a reader who finds the code and the document disagreeing knows which way to resolve it. A doctrine document restates it in its model where its readers would otherwise not know; a feature, package or system document never does, because its opening is fixed to its goal.
+The authority split (principle 4) is stated once, where agents enter the docs (the root instruction file or `docs/README.md`), so a reader who finds the code and the document disagreeing knows which way to resolve it. A doctrine document restates it in its opening, as the authority sentence (`templates/doctrine.md`), where its readers would otherwise not know; a feature, package or system document never does, because its opening is fixed to its goal.
 
 ### Diagrams and length by layer
 
@@ -131,7 +131,7 @@ A feature, package or system document is scanned more than read (principle 6). I
 | System | Opening paragraph (the machine defined) · Scope · Flow · Decisions · Promises · Gaps · For the agent |
 | Package | Identity line · Goal line · Scope · Ownership · Usage · Decisions · Promises · Gaps · For the agent |
 
-Nothing else. "Why it exists" is retired; its content is Scope or Decisions. Mechanism sections (Architecture, Key Functions, State, Files, Schema, Routes, Wire, and their kin) are the graph's, and `doc-lint` blocks them as `mechanism-section`. The templates say when each section is required and how long each genre runs.
+Nothing else. A "Why it exists" section has no place; its content is Scope or Decisions. Mechanism sections (Architecture, Key Functions, State, Files, Schema, Routes, Wire, and their kin) are the graph's, and `doc-lint` blocks them as `mechanism-section`. The templates say when each section is required and how long each genre runs.
 
 ### The body
 
@@ -269,7 +269,7 @@ flowchart LR
 
 ## Reference documents
 
-A reference document is the deepest genre: signatures, shapes and variables are its content, so the stability test does not apply to it (§ The genres). These rules bind only there, and in a procedure's appendix; an owning document names a symbol nowhere but its footer, and then only as a seam.
+A reference document is the deepest genre: signatures, shapes and variables are its content, so the stability test does not apply to it (§ The genres). These rules bind only there, and in a procedure's appendix; an owning document names a symbol only as a seam (§ Owning documents — the body and the footer).
 
 ### Function signatures
 

package/data/harnesses/code/skills/documentation/references/untemplated.md

@@ -1,28 +1,28 @@
-# Writing an Untemplated Document
+# Writing an untemplated document
 
 Load when: no template in [`templates/`](../templates/Readme.md) matches the document being written — a design note, a comparison, an investigation writeup, an index, a reference sheet, anything the Routing table sends to "no template matches".
 
 A template is a pre-made set of shape decisions. With no template, make the same decisions explicitly, in this order.
 
-## 1. Decide the nature — truth or record
+## 1. Decide the nature — truth, record or queue
 
-Every document is exactly one (`SKILL.md` § The three natures). Ask: *when reality changes, is this file rewritten, frozen, or does it lose a row?*
+Every document is exactly one of the three (`SKILL.md` § The three natures). Ask: *when reality changes, is this file rewritten, frozen, or does it lose a row?*
 
-- Rewritten in place → **truth document**. Topic-named (`kebab-case.md`), lives outside `docs/history/`, present tense throughout — the iron rule in `SKILL.md` § The three natures.
-- A list of open work whose rows are added and deleted → **queue**. A fixed name, one row per item; extend an existing queue before inventing one.
+- Rewritten in place → **truth document**. Topic-named (`kebab-case.md`), lives outside `docs/history/`, present tense throughout.
 - Frozen → **record**. Date-named (`YYYY-MM-DD-slug.md`), lives in `docs/history/` — inside an existing subfolder where it fits (an investigation or research writeup → `history/research/{topic}/`); a genuinely new category of record needs a `docs/structure.md` folder-rule row in the same change, never an invented folder.
+- Loses a row when work is resolved → **queue**. A fixed name, one row per item; extend an existing queue before inventing one.
 
 When a draft wants to be both — the current state *and* the story of getting there — split it: the state becomes a truth document, the story becomes a record that links to it. Never mix the natures in one body.
 
 ## 2. Place and name it
 
 - `docs/structure.md` is the placement authority — match the document's topic to its folder map before inventing a location.
-- **One canonical home per topic.** If a document on the topic already exists, extend it; a second document on the same topic is drift waiting to happen. Link, don't copy.
+- **One canonical home per topic.** If a document on the topic already exists, extend it; a second document on the same topic is drift. Link, don't copy.
 - A new topic *folder* gets a `Readme.md` landing page that describes what the folder holds and how its files are named, never a row per file (`type: folder-index`).
 
 ## 3. Shape it
 
-- **Open with the goal.** The first line under the H1 states what the document is for and who reads it — a reader (or agent) landing here cold decides in one sentence whether to keep reading.
+- **Open with the goal.** The first line under the H1 states what the document is for and who reads it, so a reader landing cold decides in one sentence whether to keep reading.
 - **Headings are noun phrases** — no verb, no tense, no person (`references/style-guide.md` § Labels).
 - **Headings are retrieval keys.** Sections get pulled out of context by search and agents; qualify generic headings with the topic (`## Merge rules — data sync`, not `## Rules`) so each stands alone.
 - **Tables for enumerable facts, prose for judgment.** One row per item; anything needing a *because* lives in prose around the table, never inside a cell.
@@ -38,4 +38,4 @@ When a draft wants to be both — the current state *and* the story of getting t
 
 **Stage 1 — context gathering.** Read what already exists on the topic, then draft the structure from §1–3 with sensible defaults for audience, purpose and format. Ask only the questions whose answer the repository cannot give and a default would get wrong (usually one to three), each with your recommended answer, in one message.
 
-**Stage 2 — draft.** Show the structure with the questions, then draft the whole document on the answers or the defaults. The user indicates changes — learn their style from their edits; don't silently rewrite them.
+**Stage 2 — draft.** Show the structure with the questions, then draft the whole document on the answers or the defaults. Learn the user's style from the changes they make, and **never** silently rewrite their edits.

package/data/harnesses/code/skills/documentation/scripts/doc-lint.mjs

@@ -234,8 +234,9 @@ function lintFile(path, findings) {
       findings.push({ path, n: 1, severity: 'block', id: 'record-type-in-truth-location', message: `\`type: ${declared}\` is a record genre declared in a truth location — move the file to \`docs/history/\` if it is a record, or give it its location's genre` });
   }
 
-  // A folder index (Readme.md/README.md) is a browse page, not a feature doc — it owns no code.
-  const isFolderIndex = /(^|\/)(readme)\.md$/i.test(path);
+  // A folder index (Readme.md/README.md) is a browse page that owns no code; a Readme declaring an owning genre is
+  // that folder's landing document and is graded as its genre instead.
+  const isFolderIndex = /(^|\/)(readme)\.md$/i.test(path) && !['feature', 'package', 'system'].includes(declaredType(text));
 
   // An index names folders, never files (SKILL.md § Indexes and descriptions). A link from a folder index or
   // the authority map to an individual document is a row that must be edited on every add, rename

package/data/harnesses/code/skills/documentation/templates/Readme.md

@@ -61,7 +61,7 @@ Every fact about a genre lives in one row of the table below: its template, its
 
 ## Ownership
 
-Three genres speak for code — **feature**, **package**, **system** — and a **UX** document speaks for a surface's components where none of them does (`ux-behavior.md`). A document names the objects it designs in `objects:`; a source file names the document that speaks for it in its path header. The harness's ownership scan reads one edge today, the transitional `owns:` region glob on each owning document (`packages/{name}/**` on a package, a machine's subtrees on a system, a feature's own directory on a feature), and the narrower glob wins. The header pointer is written now so the scan can switch to it and the object closure without a second pass over the code (`references/frontmatter.md`).
+Three genres speak for code — **feature**, **package**, **system** — and a **UX** document speaks for a surface's components where none of them does (`ux-behavior.md`). A document names the objects it designs in `objects:`; a source file names the document that speaks for it in its path header. The harness's ownership scan reads one edge, the transitional `owns:` region glob on each owning document (`packages/{name}/**` on a package, a machine's subtrees on a system, a feature's own directory on a feature), and the narrower glob wins. The header pointer is written alongside it so the scan can switch to it and the object closure without a second pass over the code (`references/frontmatter.md`).
 
 ## Baseline scaffolds
 

package/data/harnesses/code/skills/documentation/templates/acceptance-criteria.md

@@ -1,4 +1,4 @@
-# Acceptance Criteria
+# Acceptance criteria
 
 Truth document. Use for: the promises one capability must keep, stated as machine-parseable claims. Lives in `docs/acceptance/`, one `kebab-case.md` per capability. Written at specification time — before implementation — and read by verification surfaces, which parse each `AC-n` line as a claim to grade the built product against.
 

package/data/harnesses/code/skills/documentation/templates/api-reference.md

@@ -1,4 +1,4 @@
-# API Reference (docs/architecture/api.md)
+# API reference (docs/architecture/api.md)
 
 Truth document. Use for: the consolidated catalog of the system's HTTP surface — every live route in one place. This is the **reference document** for the API surface: a route's shape lives here or in the generated spec, never in a feature doc, which states what the route promises and leaves its shape to this catalog. If the repo generates an OpenAPI spec, this doc points at it and carries only what the spec can't (auth model, conventions, ownership links).
 

package/data/harnesses/code/skills/documentation/templates/architecture-decision.md

@@ -24,7 +24,7 @@ Don't write an AD for:
 
 `Proposed` → `Accepted` → `Deprecated`
 
-Frontmatter `status:` is the single lifecycle source of truth. An AD stays `Accepted` for as long as its subject is live — revisions rewrite the body and never change the status, and there is **no `Superseded` state**: supersession is an edit plus a changelog entry, not a new document. Set `Deprecated` only when the subject itself is retired (the component is gone, the contract no longer exists); state where the replacement lives, if any.
+Frontmatter `status:` is the single lifecycle source of truth; **never** also write "Status: Accepted" in the body. An AD stays `Accepted` for as long as its subject is live — revisions rewrite the body and never change the status, and there is **no `Superseded` state**: supersession is an edit plus a changelog entry, not a new document. Set `Deprecated` only when the subject itself is retired (the component is gone, the contract no longer exists); state where the replacement lives, if any.
 
 ### Naming
 
@@ -110,12 +110,8 @@ reviewers: [] # optional
 
 ### Rules
 
-- **One subject per AD; all its revisions stay inside it.** Two genuinely different subjects means two ADs — a revision of an existing subject never does.
-- **The body is always the current truth.** Rewrite affected sections on every revision; never leave a superseded choice narrated in the body — the Decision Changelog carries the journey, with each entry naming the old choice and the trigger.
-- Decision-first. The first paragraph after the heading is the answer; readers should not need to scroll.
 - **Consequences lists positives, negatives, AND risks.** Pros-only Consequences is the genre's classic failure — one AD's honest resulting context is the input context for the next.
 - **Options Considered keeps every genuinely rejected alternative with the real reason.** Informed rejections are the most expensive knowledge to lose; a rejection made with strong prior art in view says so explicitly.
 - **Keep it short — one to two pages.** Long decision docs don't get updated. How-it-works detail belongs in the owning feature doc; execution in a plan. Link, don't embed.
-- No section numbering (`§5.1.1`). Use markdown headings only — inserting a section shouldn't renumber everything.
-- Frontmatter `status` is the single source of truth for lifecycle. Don't also write "Status: Accepted" in the body.
-- The Decision Changelog is append-only, newest first. Typo and formatting fixes don't get entries.
+- **No section numbering** (`§5.1.1`); markdown headings only, so inserting a section renumbers nothing.
+- **The Decision Changelog is append-only, newest first**, one entry per revision naming the old choice and the trigger. Typo and formatting fixes get no entry.

package/data/harnesses/code/skills/documentation/templates/behavioral-checklist.md

@@ -1,4 +1,4 @@
-# Behavioral Checklist (docs/tests/{feature}.md)
+# Behavioral checklist (docs/tests/{feature}.md)
 
 Truth document. Use for: **how to verify one feature's promised behavior by driving the real product** — the browser, the CLI binary, HTTP against the running service. One file per feature, named for the feature doc that owns the code (`docs/features/auth.md` → `docs/tests/auth.md`).
 

package/data/harnesses/code/skills/documentation/templates/changelog-entry.md

@@ -1,4 +1,4 @@
-# Changelog Entry
+# Changelog entry
 
 Record. Use for: the per-unit-of-work journal of what changed and how it was refined — one file per entry under `docs/history/changelog/YYYY-MM-DD-{three-words}.md`, written by whoever does the work and frozen inside the commit it describes. The three words name the work, not the commit. Trigger and lifecycle policy: the `changelog` rule; distillation is the `retro` agent.
 

package/data/harnesses/code/skills/documentation/templates/changelog-index.md

@@ -22,7 +22,7 @@ description: "How {Project Name}'s changelog works: one entry per unit of work u
 ## Owed entries
 
 - **Plan completion:** a draft entry, written when the plan reaches `Status: Complete`.
-- **Commit:** every non-exempt commit carries its entry inside it (the `changelog` rule lists the exemptions).
+- **Commit:** every non-exempt commit carries its entry inside it (the closed exemption list is the `documentation` skill's `templates/changelog-entry.md`).
 
 ## Reading the changelog
 

package/data/harnesses/code/skills/documentation/templates/docs-readme.md

@@ -1,8 +1,8 @@
-# docs/README.md (Documentation Root)
+# docs/README.md (documentation root)
 
-Truth document. Use for: the entry point for all documentation in a repo. Created during baseline audit.
+Truth document. Use for: the entry point for all documentation in a repo, created by the `maintenance` agent's baseline.
 
-**This file describes directories, never files.** Each section names one folder under `docs/` and says what the folder holds, who reads it and how its files are named — a description of the directory, not of its contents. No per-file rows, no file tree, no `├──` block: the tree is `structure.md`'s, as the authority on placement, and `ls` is the roster. A row per file forces an index edit on every file added, renamed or retired, and the index's own history then records roster churn instead of what the index said. Each section below names a folder and says what the folder holds and how its files are named; the only files an index may name are the mandated scaffolds and the root instruction files, listed in `SKILL.md` § The three natures. The repo-root `README.md` routes the team and agents in by intent; this file describes the folders of the docs tree — each links the other once and neither restates the other. Naming a file without a link is the same row: no filename, no record ID (`AD-010`), no per-record table. Each file's own `description:` frontmatter is its account, read with `grep -m1 '^description:' <folder>/*.md`. `doc-lint` blocks a folder index that links an individual document (`index-lists-files`), names one (`index-names-records`) or draws a tree (`index-file-tree`).
+**This file describes directories, never files.** Each section names one folder under `docs/` and says what the folder holds, who reads it and how its files are named. No per-file rows, no file tree, no `├──` block: the tree is `structure.md`'s, as the authority on placement, and `ls` is the roster. A row per file forces an index edit on every file added, renamed or retired, so the index's history records roster churn instead of what the index said. Naming a file without a link is the same row: no filename, no record ID (`AD-010`), no per-record table. The only files an index may name are the mandated scaffolds and the root instruction files (`SKILL.md` § Indexes and descriptions). Each file's own `description:` frontmatter is its account, read with `grep -m1 '^description:' <folder>/*.md`. `doc-lint` blocks a folder index that links an individual document (`index-lists-files`), names one (`index-names-records`) or draws a tree (`index-file-tree`). The repo-root `README.md` routes the team and agents in by intent and this file describes the folders of the docs tree; each links the other once and neither restates the other.
 
 **Link only what exists.** Every row below is a placeholder — drop any whose target the repo does not have. Most `history/` and `architecture/` folders are created on first use, so linking them unconditionally ships a docs index with dead links on day one. An index is a browse page: a link that resolves to nothing is worse than an absent row.
 

package/data/harnesses/code/skills/documentation/templates/doctrine.md

@@ -1,4 +1,4 @@
-# Doctrine Documentation (docs/architecture/common/{concern}.md)
+# Doctrine documentation (docs/architecture/common/{concern}.md)
 
 Truth document. Use for **one concern the platform handles everywhere**: authentication, authorization, storage, the API protocol, credentials, telemetry. One file per concern, named for the concern. A doctrine document speaks for no code: no source header names it, and it carries no `owns:`. The surfaces bound by it are the documents that design or touch the objects it governs, computed through those objects, and each names it in its Scope.
 

package/data/harnesses/code/skills/documentation/templates/domain-model.md

@@ -1,4 +1,4 @@
-# Domain Model (docs/architecture/domain-model.md)
+# Domain model (docs/architecture/domain-model.md)
 
 Truth document. Use for: the entities the system is about — what they are, how they relate, and who owns their state. The vocabulary here must match the glossary and the code; when they disagree, fix the disagreement, don't document around it.
 

package/data/harnesses/code/skills/documentation/templates/environment-registry.md

@@ -1,4 +1,4 @@
-# Environment Registry (docs/operations/environment.md)
+# Environment registry (docs/operations/environment.md)
 
 Truth document. Use for: the config surface — every variable the code reads, in one table. `.env.example` mirrors this doc's variable list.
 

package/data/harnesses/code/skills/documentation/templates/feature.md

@@ -1,4 +1,4 @@
-# Feature Documentation (docs/features/{feature}.md)
+# Feature documentation (docs/features/{feature}.md)
 
 Truth document. Use for every feature in `docs/features/`: something a person points at, such as an address, a command family or a named control. One file per feature, cut by the objects it designs, never by the code's routers, tables, plans or packages. The file persists from design (`status: draft`) to live reference (`status: active`).
 
@@ -8,9 +8,9 @@ Truth document. Use for every feature in `docs/features/`: something a person po
 - **Each bullet is a bold label, then one or two third-person sentences** saying what happens: "**Organization user:** user lands in their existing organization", never "you land…".
 - **Flows carry the journey; Decisions carry the reasons; Promises run deepest.**
 
-The frontmatter names the objects the feature designs; which files it speaks for is never listed in the body. The ownership scan reads its transitional `owns:` region glob today, and each owned source file's header names this document for when the scan switches (`references/frontmatter.md`). Every computable fact (columns, vocabularies, foreign keys, writers, routes, guards, files) is the code graph's (`docs/architecture/systems/knowledge-layer.md`), and a hand-typed copy is the defect this genre removes. Code is named only where a person types or sees it (a page, a command, a flag, an environment variable) or at a cross-cutting seam the graph would not lead a reader to.
+The frontmatter names the objects the feature designs; which files it speaks for is never listed in the body. The ownership scan reads its transitional `owns:` region glob, and each owned source file's header names this document, ready for when the scan switches (`references/frontmatter.md`). Every computable fact (columns, vocabularies, foreign keys, writers, routes, guards, files) is the code graph's (`docs/architecture/systems/knowledge-layer.md`), and a hand-typed copy is the defect this genre removes. Code is named only where a person types or sees it (a page, a command, a flag, an environment variable) or at a cross-cutting seam the graph would not lead a reader to.
 
-**A feature document runs deepest toward its end.** Scope and Flows are the model and the journey. **Promises** goes as deep as the behaviour does: every state the surface can be in, every edge case, what a refusal tells the person, and the exact wording wherever the wording itself is promised. That depth is earned because a person or a test checks it and the code cannot state it as intent. It still stops before mechanism. A promise reads "a removed membership shows a panel, not a redirect", never which route answers it.
+**A feature document runs deepest toward its end.** Scope and Flows are the model and the journey. **Promises** goes as deep as the behaviour does: every state the surface can be in, every edge case, what a refusal tells the person, and the exact wording wherever the wording itself is promised. That depth is earned because a person or a test checks it and the code cannot state it as intent. It stops before mechanism. A promise reads "a removed membership shows a panel, not a redirect", never which route answers it.
 
 **Sections:**
 

package/data/harnesses/code/skills/documentation/templates/handover.md

@@ -2,7 +2,7 @@
 
 Record. Use for: the account an **unattended or multi-session build** leaves the person who owns it — written by the orchestrating session as its last act, before the owner's first decision, read in one sitting. It is a **decision queue, an undo manual and a resume file**, in that order: is it done · what must I decide today · what escaped the repository and how do I undo it · can I see it working · what was decided for me and how do I overturn it · what is red and whose it is. Everything below the divider is for the next session, not the owner. It is not a pull-request description (which argues for a diff), not a changelog entry (which carries refinement context) and not a plan (which is frozen). It is mutable while `status: open` — a successor that re-proves a state line corrects it in place and appends one Timeline row — and **freezes when the owner has acted on § 1 (`status: accepted`)**; a correction after that is a new dated hand-over linking back. Raw artefacts (plans, hand-offs, notes) live in a same-named folder beside it.
 
-Required: **Verdict**, **Owner decisions due**, **Live-world ledger** (even when empty), **Ten-minute walkthrough**, **Rulings on the owner's behalf**, **Red board**, **What was built**, **Proof**, **State**, **Open loops**, **Artefacts & mandate**. Optional: Left alone, Discoveries, Debt, Cost, Timeline.
+Required: **Verdict**, **Owner decisions due**, **Live-world ledger** (even when empty), **Ten-minute walkthrough**, **Rulings on the owner's behalf**, **Red board**, **What was built**, **Proof**, **State**, **Open loops**, **Artefacts & mandate**. Optional: Untouched scope, Discoveries, Deferrable debt, Cost, Timeline.
 
 **Reading order is act → verify → understand.** Owner half, ~20 minutes: Verdict (1) · § 1 (2) · § 2 (2) · § 3 (10, at the product) · § 4 (3) · § 5–6 (2). Successor half, read when the job arrives: § 8–14 (~10).
 
@@ -168,7 +168,7 @@ Present tense; every row true of `as_of_commit`, and every row re-provable by it
 - **§ 8 Proof.** **An unproven claim is an empty cell, never a sentence** — prose has no empty cell to scan for. `Independent?` reads `no` whenever one agent authored both the code and its pin, or found, fixed and pinned the same defect, and names who. Ledger counts are parsed from the plan, never quoted from an agent's summary, so `blocked` cannot hide inside "discharged". Every `G-n` names the command that would close it.
 - **§ 9 State.** Present tense; a claim that cannot be re-proved by its `Re-prove` command does not belong here — it moves to § 15 as a dated event. Volatile things (`/tmp`, pid files, ports, tokens, browser connections) declare a lifetime and the command that makes them durable.
 - **§ 10–12.** A loop is a runnable command or a named question, never a noun phrase and never "investigate"; one needing a person's judgment states the question and the default in force. A discovery is a present-tense fact with a guard — "Workers Builds does not fire on a `dev` merge", not "we found that it didn't"; `none — {what would hold it}` is an honest guard that feeds the backlog. Debt names where it now lives, so this file can be deleted without losing it.
-- **§ 13–14.** Every uninstrumented number reads `unmeasured — {what would have measured it}`; a blank reports a cheaper run than the one that happened. **State whether the run's own corpus is version-controlled** — an untracked corpus is one `rm -rf` from being three PR descriptions, and archiving it is a § 1 row.
+- **§ 13–14.** Every uninstrumented number reads `unmeasured — {what would measure it}`; a blank reports a cheaper run than the one that happened. **State whether the run's own corpus is version-controlled** — an untracked corpus is one `rm -rf` from being three PR descriptions, and archiving it is a § 1 row.
 - **Ids are stable and run-global** — `D-`, `G-`, `L-`, `X-`, `T-` — so a PR comment or a successor cites a row instead of re-describing it. A withdrawn row keeps its id and states what disproved it.
 - **Evidence is an address that outlives the run** — `path:line`, a 7-char sha, a PR number, a URL, or a command. A branch name is not a pointer; a `/tmp` log is not evidence — copy it into the record folder first.
 - **Blanket claims are banned.** "All suites green", "every ledger discharged", "nothing was deployed" carry a count and the sha they are true of, or they become a `G-n` row.

package/data/harnesses/code/skills/documentation/templates/implementation-map.md

@@ -1,4 +1,4 @@
-# Implementation Map (docs/operations/implementation-map.md)
+# Implementation map (docs/operations/implementation-map.md)
 
 Truth document. Use for: **the cold-start execution contract of a project being built from its documented design** — one per repo, at `docs/operations/implementation-map.md`. It is authored by the **executing session at build start**, never generated at design time: build order is derived from the repo's actual feature docs and their stated dependencies, and a design-time prediction of it goes stale the day reality disagrees. It lives in operations because it says *how to proceed*, not *what is true of the design*.
 

package/data/harnesses/code/skills/documentation/templates/migration-runbook.md

@@ -1,4 +1,4 @@
-# Migration Runbook (docs/history/migrations/YYYY-MM-DD-{slug}.md)
+# Migration runbook (docs/history/migrations/YYYY-MM-DD-{slug}.md)
 
 Record. Use for: a **one-shot** migration, upgrade, or data operation — authored before execution, executed once, then outcome-stamped and frozen. Supporting scripts live beside it in a same-named folder when needed (`YYYY-MM-DD-{slug}/`).
 

package/data/harnesses/code/skills/documentation/templates/non-goals.md

@@ -1,4 +1,4 @@
-# Non-Goals (docs/architecture/non-goals.md)
+# Non-goals (docs/architecture/non-goals.md)
 
 Truth document. Use for: what the system deliberately does **not** do. A non-goal is a decision, not an omission — each entry carries the why and what would reopen it. Readers (and agents) use this to stop re-proposing settled exclusions.
 

package/data/harnesses/code/skills/documentation/templates/operations-procedure.md

@@ -1,8 +1,8 @@
-# Operations Procedure (docs/operations/{procedure}.md)
+# Operations procedure (docs/operations/{procedure}.md)
 
 Truth document. Use for: any **recurring** procedure — development, deployment, maintenance. The one-time first run (prerequisites, install, env files, first commands, the stack) is not one of these: it has its own template and a fixed name, `templates/setup.md` → `docs/operations/setup.md`, one per repo. A procedure is consulted mid-task, not read: exact commands, copy-paste runnable, no narrative. Updated in place whenever the workflow changes.
 
-A **one-shot** procedure (a migration, an upgrade, an incident response executed once) is not an operations doc — it is a **Migration Runbook** (record, below). The test: will someone run this again next month? Yes → operations. No → runbook.
+A **one-shot** procedure (a migration, an upgrade, an incident response executed once) is not an operations doc — it is a **migration runbook** (record, `templates/migration-runbook.md`). The test: will someone run this again next month? Yes → operations. No → runbook.
 
 Required: **Goal**, **Steps**, **Verification**. Optional: Preconditions, Troubleshooting, Rollback — include only when they carry real content.
 

package/data/harnesses/code/skills/documentation/templates/package.md

@@ -1,4 +1,4 @@
-# Package Documentation (docs/architecture/packages/{package}.md)
+# Package documentation (docs/architecture/packages/{package}.md)
 
 Truth document. Use for: **one workspace package** — one unit of distribution: a manifest, a build, a binary, a bundle, a Worker. One file per package, named for its folder.
 

package/data/harnesses/code/skills/documentation/templates/protected-files.md

@@ -1,4 +1,4 @@
-# Protected Files
+# Protected files
 
 Truth document. Use for: documenting critical files that need approval before modification.
 

package/data/harnesses/code/skills/documentation/templates/root-readme.md

@@ -1,4 +1,4 @@
-# Project Root README (/README.md)
+# Project root README (/README.md)
 
 Truth document. Use for: the repository root `/README.md`. It opens outward — what the product does, for whom, and where it runs, in a user's terms — then turns inward for the team and coding agents: what state the repo is in, how it works, what its parts are and what must not break, then routes every other question into `docs/`. The outward part comes first because it is what a stranger reads; the inward part is longer because it is what the team uses. **It hosts nothing it can link to.** It is distinct from `docs/README.md`, which describes the folders of the docs tree, and from `CLAUDE.md` / `AGENTS.md`, the standing rules an agent loads. It points at both and restates neither.
 

package/data/harnesses/code/skills/documentation/templates/security-overview.md

@@ -1,4 +1,4 @@
-# Security Overview (docs/architecture/security.md)
+# Security overview (docs/architecture/security.md)
 
 Truth document. Use for: the single place the system's security posture is stated — assets, trust boundaries, controls, and accepted risks. Controls link to the code that implements them; this doc asserts, the code proves.
 

package/data/harnesses/code/skills/documentation/templates/system-overview.md

@@ -1,4 +1,4 @@
-# System Overview (docs/architecture/system-design.md)
+# System overview (docs/architecture/system-design.md)
 
 Truth document. Use for: the bird's-eye view — what the system is, its subsystems, and how they connect. The first doc a new reader opens after the README; austere and short (two screens max). Depth lives in feature docs — this doc maps, it doesn't explain.
 

package/data/harnesses/code/skills/documentation/templates/system.md

@@ -1,4 +1,4 @@
-# System Documentation (docs/architecture/systems/{system}.md)
+# System documentation (docs/architecture/systems/{system}.md)
 
 Truth document. Use for: **one machine that spans packages**, which a person cannot point at — the walk, the egress, the ingest, the settlement, a gate, a sweep, a door an agent calls. One file per machine, named for the machine. A thing a person navigates to is a feature document, even when it owns tables; a unit of distribution is a package document.
 

package/data/harnesses/code/skills/documentation/templates/testing-strategy.md

@@ -1,4 +1,4 @@
-# Testing Strategy (docs/architecture/common/testing.md)
+# Testing strategy (docs/architecture/common/testing.md)
 
 Truth document. Use for: the repo's test posture — what is tested at which level, how to run it, and what is deliberately untested. The framework choices come from the harness testing rule; this doc records how *this repo* applies them.
 

package/data/harnesses/code/skills/documentation/templates/ux-behavior.md

@@ -1,4 +1,4 @@
-# UX Behavior — template
+# UX behavior (docs/features/{surface}-ux.md)
 
 **Truth document.** States what a person sees and can do on a surface, and what the surface promises never to do. Present tense, like every truth document.
 
@@ -26,9 +26,7 @@ owns:                             # transitional, only when this document speaks
 | One surface's — a panel, an editor, a dialog | `docs/features/{surface}-ux.md`; its component files' headers name it |
 | Cross-cutting — routing, information architecture, the state vocabulary every surface obeys, presentation of streams | `docs/architecture/` — owns no code, like every architecture doc |
 
-**Ownership: a component file names one document in its header.** A surface's components are frequently already spoken for — by the page's feature document, by the feature behind one panel — and a file's header names exactly one document. Where the header already names the feature document, this document is named in that feature document's **See also** line under For the agent instead, phrased as *different promises over the same files*, and the object closure links the two through the objects both name. Where no document speaks for the component yet, its header names this one.
-
-That matters because a doc nothing implicates is a doc that rots, and a surface rewritten under an unimplicated document is the failure this genre exists to prevent. The See also line is the weaker of the two bindings; prefer the header pointer wherever no document speaks for the component yet.
+**Ownership: a component file names one document in its header.** A surface's components are frequently already spoken for — by the page's feature document, by the feature behind one panel — and a file's header names exactly one document. Where the header already names the feature document, this document is named in that feature document's **See also** line under For the agent instead, phrased as *different promises over the same files*, and the object closure links the two through the objects both name. Where no document speaks for the component, its header names this one; prefer that header pointer, because the See also line is the weaker binding. A document nothing implicates rots, and a surface rewritten under an unimplicated document is the failure this genre exists to prevent.
 
 ---
 
@@ -67,7 +65,7 @@ What moves the surface between states, and who causes each move — the person,
 
 ## Optional sections
 
-**Copy** — the exact words, where the wording is load-bearing (a refusal, an irreversible confirmation). **Density and rhythm** — where a surface deliberately differs from the design system's default. **Open questions** — decisions deliberately not yet made, so an implementer knows what to ask rather than guessing.
+**Copy** — the exact words, where the wording is load-bearing (a refusal, an irreversible confirmation). **Density and rhythm** — where a surface deliberately differs from the design system's default. **Open questions** — decisions deliberately left open, so an implementer knows what to ask rather than guessing.
 
 ## Rules
 

package/data/harnesses/code/skills/issue-bridge/SKILL.md

@@ -5,7 +5,7 @@ description: The bridge between a traditional issue tracker (GitHub Issues, Jira
 
 # issue-bridge — the tracker bridge method
 
-**If no connector is reachable** (no MCP server, no CLI, no API credentials — the pack for your tracker lists the probes): do not stall — accept pasted issue text, name the fields you are missing (labels, comments, linked items), and run triage on what you have. Degraded output is acceptable; silent degradation is not.
+> **No connector reachable** (no MCP server, no CLI, no API credentials — the pack for your tracker lists the probes): never stall. Accept pasted issue text, name the fields you are missing (labels, comments, linked items), and triage what you have, announced.
 
 You bridge two systems of record. Neither is asked to change:
 
@@ -15,41 +15,76 @@ You bridge two systems of record. Neither is asked to change:
 
 ## Connectors
 
-Tracker access is **this skill's own knowledge**, not a harness-declared tool. It was briefly modelled as a "connector" sub-kind of the tools class; that was wrong, and the probes are the proof — the tools class means one deterministic, versioned executable, while a tracker is an MCP entry *or* one of several unrelated CLIs *or* an env var, varying per repo and per team. So the access method lives in `references/trackers/<tracker>.md`, probed in preference order at the moment of use. It is **credentialed and side-effectful**, which is why every tracker write is approval-gated. Each tracker's pack under [`references/trackers/`](references/trackers/) lists its access options in preference order (MCP server → CLI → raw API), the probe for each, auth setup, and the exact calls for read / search / create / comment. Read the pack for your tracker before the first tracker call. More than one tracker in play → one pack each; the method below is identical across all of them.
+Tracker access is this skill's own knowledge, never a harness-declared tool: a tracker is reached through an MCP entry, one of several unrelated CLIs, or an env var, varying per repo and per team, so you probe for it at the moment of use. Each tracker's pack under [`references/trackers/`](references/trackers/) lists its access options in preference order — an MCP server, a CLI, the raw API, in the order that pack sets — with the probe for each, auth setup, and the exact calls for read / search / create / comment.
+
+- **Always read the pack for your tracker before the first tracker call.**
+- More than one tracker in play → one pack each; the method below is identical across all of them.
 
 ## Tool tier
 
-Read the `nustack` status from the session context (`Tool:` line). **Present-fresh** → localize every question through `nustack graph` (`find`, `where-defined`, `who-calls`, `refs`, `impact`, `blame`, `tests-covering`) before reading source. **Present-stale** → use it, note the gap. **Absent** → Glob/Grep/read, announced. Never run an index step first — the family re-indexes a stale store before it answers. One carve-out: **syntax-level detail — decorator lists and their order, full function bodies, statement sequence — is not in the index's query surface**; go straight to source for that class, whatever the tier. Decorator *application* is indexed as a reference, attributed to the decorated declaration; what the decorator does is not.
+Read the `nustack` status from the session context (`Tool:` line):
+
+| Tier | Do |
+| --- | --- |
+| **Present-fresh** | Localize every question through `nustack graph` (`find`, `where-defined`, `who-calls`, `refs`, `impact`, `blame`, `tests-covering`) before reading source |
+| **Present-stale** | Use it; note the gap |
+| **Absent** | Glob/Grep/read, announced |
+
+- **Never run an index step first** — the family re-indexes a stale store before it answers.
+- **Syntax-level detail goes straight to source, whatever the tier** — decorator lists and their order, full function bodies, statement sequence are not in the index's query surface. Decorator *application* is indexed as a reference, attributed to the decorated declaration; what the decorator does is not.
 
 ## Mode selection
 
-**Triage** when given issue references, a tracker query, or pasted issue text. **File** when given a harness finding to externalize — a backlog row, a drift or bookkeeping finding, an audit or critic result, a changelog discovery. Ambiguous → ask one question, don't guess.
+**Triage** when given issue references, a tracker query, or pasted issue text. **File** when given a harness finding to externalize — a backlog row, a drift or bookkeeping finding, an audit or critic result, a changelog discovery. Ambiguous → ask one question; never guess.
 
 ## Triage — tracker item in, dossier out
 
 1. **Fetch** through the connector (per the pack). No access → pasted-text mode, missing fields named.
-2. **Classify.** Bug / feature request / question / docs-gap. Questions get owning-doc pointers and a direct answer, not a dossier.
+2. **Classify.** Bug / feature request / question / docs-gap. A question gets owning-doc pointers and a direct answer, not a dossier.
 3. **Route.** Match the issue's vocabulary against the ownership index and feature docs' `keywords:`. Read the owning doc(s) **fully** — intent and invariants first, code second. No owning doc → say so; the absence is itself a finding.
-4. **Localize.** Names from the issue go through `nustack graph`; every location claim carries `file:line`.
-5. **Diagnose.** Root-cause hypothesis, confidence-graded — `certain` / `inferred` / `unresolved` — and never present inferred as certain. Blast radius via `impact`/`coupling`; test surface via `tests-covering`.
-6. **Dedup.** Search the tracker for siblings and priors (per the pack); check `nustack graph drift` for the same-bug-in-a-clone class.
+4. **Localize.** Run names from the issue through `nustack graph` (per § Tool tier); every location claim carries `file:line`.
+5. **Diagnose.** Write a root-cause hypothesis graded `certain` / `inferred` / `unresolved` — **never** present inferred as certain. Blast radius via `impact` / `coupling`; test surface via `tests-covering`.
+6. **Dedup.** Search the tracker for siblings and priors (per the pack); check `nustack graph drift` for the same bug in a clone.
 7. **Write the dossier** to `docs/operations/triage/YYYY-MM-DD-<tracker>-<id>-<slug>.md` and return the verdict summary.
-8. **Posting back** (comment, label, assign, transition) is **approval-gated per run**: show exactly what would be posted, post only on an explicit yes in this session. A standing repo ruling (e.g. "never post to this upstream") overrides any approval.
+8. **Post back** (comment, label, assign, transition) only under § Boundaries' approval gate: show exactly what would be posted, post only on an explicit yes in this session.
 
 ## The dossier
 
-Frontmatter: `type: triage`, `tracker`, `date`, `confidence`, and the subject key — `issue: {id: <n>, url: <url>}` with a **numeric** id for a tracker item, `issue: {id: local:<record-id>}` for a locally-authored record, `pr: {id: <n>}` when the dossier resolves a pull request. This shape is machine-read: the NuStack desktop's Issues panel joins dossiers to tracker rows on exactly this key, so a quoted number, a missing id, or a renamed key leaves the dossier orphaned — written but never surfaced beside its issue. Sections, in order: **Verdict** (1–3 sentences) · Classification · Owning docs (paths) · Root cause (cited, graded) · Blast radius · Suggested fix plan (feeds the plan → PR loop; you never implement) · Test surface · Duplicates & related · **Prior-thread corrections** (claims already on the tracker thread — bot answers, maintainer comments — that your evidence shows to be wrong, each with the citation that refutes it) · Open questions. A dossier is a dated working artifact — it never claims `owns:` globs and never masquerades as a feature doc.
+A dossier is a dated working artifact — it **never** claims `owns:` globs and never masquerades as a feature doc.
+
+**Frontmatter:** `type: triage`, `tracker`, `date`, `confidence`, and the subject key:
+
+| Subject | Key |
+| --- | --- |
+| A tracker item | `issue: {id: <n>, url: <url>}` — the id **numeric** |
+| A locally-authored record | `issue: {id: local:<record-id>}` |
+| A pull request the dossier resolves | `pr: {id: <n>}` |
+
+**This key is machine-read:** the NuStack desktop's Issues panel joins dossiers to tracker rows on exactly this key, so a quoted number, a missing id, or a renamed key leaves the dossier orphaned — written but never surfaced beside its issue.
+
+**Sections, in order:**
+
+1. **Verdict** — 1–3 sentences.
+2. Classification
+3. Owning docs — paths.
+4. Root cause — cited, graded.
+5. Blast radius
+6. Suggested fix plan — feeds the plan → PR loop; you never implement.
+7. Test surface
+8. Duplicates & related
+9. **Prior-thread corrections** — claims already on the tracker thread (bot answers, maintainer comments) that your evidence shows to be wrong, each with the citation that refutes it.
+10. Open questions
 
 ## File — harness finding in, tracker issue out
 
 1. **Verify first.** Reproduce the finding against source before externalizing it. A claim that doesn't reproduce is reported back, never filed.
-2. **Compose tracker-idiomatic** (per the pack): imperative title; body: one plain-language context paragraph (no harness jargon), evidence (`file:line`, commit hashes), expected vs actual, acceptance criteria; link the owning feature doc by path.
-3. **Show the draft(s).** Create only on explicit approval, through the connector. Batch discipline: many findings → one draft list, one approval, then individual creation; report every created ID.
+2. **Compose tracker-idiomatic** (per the pack): imperative title; body of one plain-language context paragraph (no harness jargon), evidence (`file:line`, commit hashes), expected vs actual, acceptance criteria; link the owning feature doc by path.
+3. **Show the draft(s).** Create only on explicit approval, through the connector. Many findings → one draft list, one approval, then individual creation; report every created ID.
 4. **Close the loop.** Write the created issue's ID/URL back into the originating row — a backlog row gains the link, a bookkeeping row resolves.
 
 ## Boundaries
 
-- Never edit source code. The dossier ends at the fix *plan*; implementation belongs to the plan → verification → PR loop.
-- Nothing is created, edited, or commented in the tracker without explicit approval in the current run.
-- Repo writes are `docs/operations/triage/**` plus the loop-closing edits to `docs/history/backlog.md` / `docs/operations/bookkeeping.md`. Nothing else.
-- Announce degraded modes; never silently downgrade evidence quality.
+- **Never edit source code.** The dossier ends at the fix *plan*; implementation belongs to the plan → verification → PR loop.
+- **Nothing is created, edited, or commented in the tracker without explicit approval in the current run.** A standing repo ruling (e.g. "never post to this upstream") overrides any approval.
+- **Repo writes are only** `docs/operations/triage/**` plus the loop-closing edits to `docs/history/backlog.md` / `docs/operations/bookkeeping.md`.
+- **Announce every degraded mode** — degraded output is acceptable; silently downgraded evidence quality is not.

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

@@ -1,6 +1,6 @@
 # GitHub — 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/01-github.md` (2026-08-19).
+Access options in preference order. Probe each in order; use the first that answers.
 
 ## Option 1 — the `gh` CLI (default)
 
@@ -26,12 +26,12 @@ Headers: `Authorization: Bearer <PAT>` · `Accept: application/vnd.github+json`.
 - Read: `GET https://api.github.com/repos/OWNER/REPO/issues/N`
 - Search: `GET https://api.github.com/search/issues?q=<query>` (q ≤256 chars, ≤5 boolean ops, ~10 req/min)
 - Create: `POST /repos/OWNER/REPO/issues` `{"title","body","labels":[]}` · Comment: `POST .../issues/N/comments` `{"body"}`
-- Labels: POST appends, PUT replaces — never PUT unless replacement is the stated intent.
+- Labels: POST appends, PUT replaces — **never** PUT unless replacement is the stated intent.
 
 ## Composing for GitHub
 
-Markdown body, native. Reference related issues/PRs by bare `#number` so GitHub auto-links. Labels from the owning doc's `module:` where the repo's label taxonomy allows — **read `gh label list` first; never invent labels** (real taxonomies differ: apache/superset uses `#bug:*`, not `bug`).
+Markdown body, native. Reference related issues/PRs by bare `#number` so GitHub auto-links. Labels come from the owning doc's `module:` where the repo's label taxonomy allows — **read `gh label list` first; never invent labels** (real taxonomies differ: apache/superset uses `#bug:*`, not `bug`).
 
-## Ecosystem notes (2026-08-19)
+## Ecosystem notes
 
-No incumbent GitHub-issues skill/plugin exists in anthropics/skills, the official plugin marketplace, or awesome-claude-code — this pack has no upstream to defer to. The reverse direction exists as `anthropics/claude-code-action` (@claude mentions inside issues trigger CI sessions); do not confuse the two.
+`anthropics/claude-code-action` runs the reverse direction — an @claude mention inside an issue triggers a CI session. Never confuse it with this pack.