@nurix/etna 0.20.35 → 0.20.37

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

@@ -1,11 +1,16 @@
-# 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.
 
-```
+```markdown
+---
+type: non-goals
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
+---
+
 # Non-Goals
 
 Things this system deliberately does not do. Each is a decision — don't re-propose one without new information of the kind its "revisit if" names.
 
-- **{Non-goal}** — {why it's excluded}. Revisit if: {the trigger that would reopen it}.
+- **{Non-goal}:** {why it's excluded}. Revisit if: {the trigger that would reopen it}.
 ```

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

@@ -1,14 +1,19 @@
-# 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.
 
 If a procedure is a deterministic command list run frequently, script it and have the doc point at the script — a doc should carry judgment (when, why, what to check), not replace automation.
 
-```
+```markdown
+---
+type: operations
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
+---
+
 # {Procedure Name}
 
 **Goal:** What this procedure accomplishes, one line.

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.
 
@@ -6,7 +6,7 @@ Truth document. Use for: **one workspace package** — one unit of distribution:
 
 **A package document's deepest layer is its public contract** (`references/style-guide.md` § Shape — the model first, the detail after): the commands and flags a person types, the exports another package imports, what is installed and where. For a CLI the flags *are* the promise, so they belong in Usage. It stops before internal layout, build steps and which file holds what.
 
-**A package document is the residual owner of its own tree.** Every file in the package whose header names no narrower document is its to speak for, so it loses to every system or feature document a header names. Until the ownership scan switches to header pointers, its transitional `owns:` is the whole package glob. The one enumerable fact it declares is the ownership table: which subtrees other documents speak for.
+**A package document is the residual owner of its own tree.** Every file in the package whose header names no narrower document is its to speak for, so it loses to every system or feature document a header names. Until the ownership scan switches to header pointers, its transitional `owns:` is the whole package glob. Which subtrees narrower documents speak for is computed from their headers, never tabled here.
 
 **Sharp, bulleted, labelled with noun phrases** (`references/style-guide.md` § Labels). Every section after the goal line is bullets under a noun-phrase heading, each bullet a bold noun-phrase label followed by one or two sentences.
 
@@ -15,7 +15,7 @@ Truth document. Use for: **one workspace package** — one unit of distribution:
 | Section | When |
 | --- | --- |
 | `Scope` | required. Why the package is its own unit, who consumes it, and what it deliberately does not hold |
-| `Ownership` | required, as one line or a table |
+| `Ownership` | required, as one line |
 | `Usage` | required |
 | `Decisions` | once any choice was made that the code cannot explain |
 | `Promises` | required |
@@ -49,11 +49,7 @@ owns: ["packages/{name}/**"]                     # transitional — the residual
 
 ## Ownership
 
-This document is the residual owner of `packages/{name}/**`. Claimed at higher specificity:
-
-| Subtree | Stated and owned by |
-| --- | --- |
-| `src/{machine}/**` | [{system}](../systems/{system}.md) |
+This document is the residual owner of `packages/{name}/**`; a subtree whose files' headers name a system or feature document is that document's.
 
 ## Usage
 
@@ -77,7 +73,7 @@ This document is the residual owner of `packages/{name}/**`. Claimed at higher s
 - **Commands and exports:** {…} — the public contract
 - **Code root:** `packages/{name}/`
 - **Seams:** {…} by name
-- **Checklist:** `tests/{package}.md`
+- **Checklist:** `docs/tests/{package}.md`
 - **See also:** {neighbour}: {why}
 
 No file lists or symbol rosters — those are the graph's.

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

@@ -8,7 +8,7 @@ The `boundary` skill parses the **Proposed Changes** sections to check boundary
 
 **Doc Obligations is the one ledger the plan's author writes.** Deriving tests from behavior is judgment, which is why `testing` owns that section and it is marked never-hand-author; resolving Proposed Changes' file paths to the feature docs that own them is a **lookup** against the ownership index already injected at session start. Different work, different rule — fill it yourself, while the touch list is fresh.
 
-The **`Gates:`** line carries two machine-read segments. The compliance hook greps **`Boundary:`** — implementation edits inside the plan's scope are blocked while it reads `Boundary: pending`; the `boundary` skill rewrites it to `Boundary: passed YYYY-MM-DD` or `Boundary: blocked YYYY-MM-DD`. The other two plan gates are enforced by **section presence**: a plan with no `## Test Obligations` or no `## Doc Obligations` section blocks the same edits — the sections are the artifacts, and the gate derives from them, not from a claim about them. A **`Polygraph:`** segment appears only when the user has the `polygraph` agent audit the plan's documents — it appends `Polygraph: passed YYYY-MM-DD (N docs · N claims · N corrected · N registered)`, or `Polygraph: pending` while an owner question is open. It is a trace for readers, never an obligation: a plan carries none by default, no hook or CI check reads it, and it is never hand-written. Never hand-edit the line to skip a gate.
+The **`Gates:`** line carries one machine-read segment. The compliance hook greps **`Boundary:`** and blocks implementation edits inside the plan's scope until it reads `passed`: `Boundary: pending` has no verdict yet and `Boundary: blocked` is a verdict against coding, so both wall. The `boundary` skill rewrites it to `Boundary: passed YYYY-MM-DD` or `Boundary: blocked YYYY-MM-DD`; a blocked plan folds the amendments and re-runs the skill. The other two plan gates are enforced by **section presence**: a plan with no `## Test Obligations` or no `## Doc Obligations` section blocks the same edits — the sections are the artifacts, and the gate derives from them, not from a claim about them. A **`Polygraph:`** segment appears only when the user has the `polygraph` agent audit the plan's documents — it appends `Polygraph: passed YYYY-MM-DD (N docs · N claims · N corrected · N registered)`, or `Polygraph: pending` while an owner question is open. It is a trace for readers, never an obligation: a plan carries none by default, no hook or CI check reads it, and it is never hand-written. Never hand-edit the line to skip a gate.
 
 ```
 # {Feature Name}
@@ -51,12 +51,11 @@ Why this work is happening *now*. Link to the spec for *what* we're building; th
 ## Doc Obligations
 
 <!-- One row per feature doc whose `owns:` globs intersect the Proposed Changes above — resolve
-     them against the injected ownership index. Hand-authored: this is a lookup, not research.
-     Amendable while the plan is open; discharged at Completion. -->
+     them against the injected ownership index. Hand-authored: this is a lookup, not research. Amendable while the plan is open; discharged at Completion. -->
 
-| Doc | Claim that changes | `owns:` still accurate? | Outcome |
+| Doc | Claim that changes | Still the owning doc? | Outcome |
 | --- | --- | --- | --- |
-| `docs/features/{feature}.md` | what it says today that this plan makes false | yes / no — new paths to add | written empty; discharged at Completion — **updated** / **owes nothing** (with the reason) / **blocked** (→ backlog) |
+| `docs/features/{feature}.md` | what it says today that this plan makes false | yes / no — the document the changed files' headers should name | written empty; discharged at Completion — **updated** / **owes nothing** (with the reason) / **blocked** (→ backlog) |
 
 **"None" is valid** — a plan touching only unowned paths owes no doc update, and says so explicitly. It is not a free pass: `boundary` builds its own touch list from the same Proposed Changes and reports docs this table missed.
 
@@ -69,12 +68,7 @@ Why this work is happening *now*. Link to the spec for *what* we're building; th
 ## Test Obligations
 
 <!-- Written by the `testing` skill (plan-gate mode) at the plan gate (after `boundary`). One row per
-     promised behavior: layer · target file · oracle · fixtures · an empty Outcome cell the
-     verification gate fills (satisfied / owes nothing / blocked → backlog). Amendable while the
-     plan is open. Do not hand-author. NEVER put a pipe in a ledger cell, escaped or not — the
-     compliance hook splits rows on `|` at a fixed column index with no unescaping, so a
-     markdown-legal `\|` shifts every later cell and the wall blocks a row that is in fact
-     discharged. Write "`install` or `update`", not "`install \| update`". -->
+     promised behavior: layer · target file · oracle · fixtures · an empty Outcome cell the verification gate fills (satisfied / owes nothing / blocked → backlog). Amendable while the plan is open. Do not hand-author. A literal pipe in a cell is written `\|`; an unescaped one adds a column and shifts every later cell. Prefer "`install` or `update`" to escaping. -->
 
 ## Open Questions
 

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

@@ -1,10 +1,15 @@
-# Protected Files
+# Protected files
 
 Truth document. Use for: documenting critical files that need approval before modification.
 
 This doc answers *what is protected and why breaking it hurts* — nothing more. Don't duplicate function-level detail here (signatures, inputs/outputs): it drifts from both the code and the owning feature doc. The owning feature doc is the canonical reference for how the code works; link to it.
 
-```
+```markdown
+---
+type: protected-files
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
+---
+
 # Protected Files
 
 Critical files requiring 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.
 
@@ -13,7 +13,7 @@ Sections come in this order; 1 to 3 are the outward-facing first screen, 4 onwar
 5. **State.** Optional: a one-line blockquote, present only while something repo-wide is true that a newcomer must know (frozen, mid-migration, mid-breaking-change on `dev`). It links the plan or runbook that owns the change. Say here which units publish and where, if any do.
 6. **The main path.** Three to six short paragraphs, or numbered stages, along the main request or data path: who arrives, what is built, where state lives, how the result leaves. Name a technology only where it explains a stage. End with a link to the system overview.
 7. **Repository map.** A sentence on how the tree is organised, then one table row per top-level unit (package, app, service), giving its path, what it is in one line, and its owning doc; the top folders that are not packages get a sentence each. This replaces the tree.
-8. **Rules that bite.** Optional. At most five one-line invariants, public/internal boundaries, never-edit paths (generated, protected) or non-goals, each linked to the doc that argues it.
+8. **Load-bearing rules.** Optional. At most five one-line invariants, public/internal boundaries, never-edit paths (generated, protected) or non-goals, each linked to the doc that argues it.
 9. **Destinations.** An intent-to-destination table. Its last row is the one for agents.
 10. **Everyday commands.** Optional. At most four commands run on every change, ending at the gate a push must pass. First-run commands are never here.
 
@@ -31,11 +31,11 @@ Sections come in this order; 1 to 3 are the outward-facing first screen, 4 onwar
 
 ### Writing rules
 
-- **Budget: between 60 and 140 non-blank lines, the outward part under a third of it.** Prose is welcome — The main path and Rules that bite read better as paragraphs than as rows — but past the ceiling a section is hosting content that belongs in a doc. Move it and leave the link.
+- **Budget: between 60 and 140 non-blank lines, the outward part under a third of it.** Prose is welcome — The main path and Load-bearing rules read better as paragraphs than as rows — but past the ceiling a section is hosting content that belongs in a doc. Move it and leave the link.
 - **Every section is either a fact the reader acts on or a link.** If a section needs a paragraph, it needs a doc.
 - **One H1, then H2 sections, in plain Markdown.** Sentence-case headings, no emoji, no HTML layout, and no `#` comment lines inside code blocks (they parse as H1s).
 - **Relative links into the repo only.** Never an absolute repo URL. Never an external site as the home of a canonical doc.
-- **Link folders and mandated scaffolds, never rosters.** The allowed targets are folders, `docs/README.md`, `docs/structure.md`, `docs/operations/setup.md`, `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `CLAUDE.md` and the owning docs in the Map. A procedure is named only where a Destinations row needs it. Every heading and table header is a noun phrase (`../references/style-guide.md` § Labels). Never list individual feature docs: the ownership index finds them.
+- **Link folders and mandated scaffolds, never rosters.** The allowed targets are folders, `docs/README.md`, `docs/structure.md`, `docs/operations/setup.md`, `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `CLAUDE.md`, `AGENTS.md` and the owning docs in the Map. A procedure is named only where a Destinations row needs it. Every heading and table header is a noun phrase (`../references/style-guide.md` § Labels). Never list individual feature docs: the ownership index finds them.
 - **No tree.** The Map stops at top-level units and never lists files. Mark paths that look primary but are not, for example "`legacy/`: reference only, never edited".
 - **The Map is a coarse view of the ownership index, not a rival to it.** The Owning doc column names the doc the index resolves for that path. When the two disagree the index wins, and the Map row is fixed in the same change.
 - **No version numbers and no dates.** Name the file that pins a version (`.nvmrc`, `packageManager`, `rust-toolchain.toml`). Write in the present tense, with no "coming soon" and no "as of".
@@ -90,7 +90,7 @@ The rest of this page is for the team and for coding agents working in this repo
 
 {One sentence each for the top folders that are not packages — `registry/`, `scripts/`, `docs/` — with their owning doc.} Where every doc lives: [docs/structure.md](docs/structure.md).
 
-## Rules that bite
+## Load-bearing rules
 
 {One sentence saying these are stated here and argued in the documents they point at.}
 

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

@@ -1,10 +1,15 @@
-# 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.
 
 Required: **Trust boundaries**, **Controls**. Optional: Assets, Accepted risks.
 
-```
+```markdown
+---
+type: security-overview
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
+---
+
 # Security Overview
 
 ## Assets
@@ -13,7 +18,7 @@ Required: **Trust boundaries**, **Controls**. Optional: Assets, Accepted risks.
 
 ## Trust boundaries
 
-- {Boundary} — {what crosses it, and what checks the crossing} 
+- **{Boundary}:** {what crosses it, and what checks the crossing} 
 
 ## Controls
 
@@ -23,5 +28,5 @@ Required: **Trust boundaries**, **Controls**. Optional: Assets, Accepted risks.
 
 ## Accepted risks
 
-- {Risk knowingly carried} — accepted because {reason}; owner: {who}. Revisit if: {trigger}.
+- **{Risk knowingly carried}:** accepted because {reason}; owner: {who}. Revisit if: {trigger}.
 ```

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

@@ -4,7 +4,7 @@ Truth document, operations genre (`type: operations`). Use for: **the one-time p
 
 It is distinct from `local-development.md`, the daily loop: watch modes, resetting state, per-package traps, the inner test cycle. Setup runs once per machine. Local development runs every session. Setup ends by handing off to it, and neither copies the other. Deploying is `deployment.md`.
 
-Required: **Goal**, **Stack**, **Prerequisites**, **Install**, **First run**, **Verify**. Optional, included only with real content: the audience fork, **Before cloning**, **Environment files**, **Local services**, **Reset**, **Common failures**.
+Required: **Goal**, **Stack**, **Prerequisites**, **Installation**, **First run**, **Verification**. Optional, included only with real content: the audience fork, **Before cloning**, **Environment files**, **Local services**, **Reset**, **Common failures**.
 
 ### Writing rules
 
@@ -32,7 +32,7 @@ description: "{at most 300 characters: what this document settles and where its
 
 **Goal:** take a fresh machine from clone to a verified first run of {what runs: e.g. "the product Worker on :{port} and the web shell on :{port}, signed in as the dev fixture"}. Done once per machine; the daily loop is [`local-development.md`]({local-development}.md).
 
-{Optional audience fork: "Only running {the CLI / one package}? Stop after Install and see [`{procedure}`]({path})."}
+{Optional audience fork: "Only running {the CLI / one package}? Stop after Installation and see [`{procedure}`]({path})."}
 
 ## Stack
 
@@ -59,7 +59,7 @@ Why these were chosen: [{system overview}](../architecture/{overview}.md).
 
 - **{Trap}:** {what a fresh clone hits and the one command that clears it, e.g. `git lfs install`, `git submodule update --init`}.
 
-## Install
+## Installation
 
 \`\`\`bash
 git clone {url} && cd {repo}
@@ -103,7 +103,7 @@ The contract is [`{example file or typed Env}`](../../{path}). Read it before co
 
 4. Open `{http://localhost:port}` and {sign in as `{seeded user}` / reach `{first screen}`}.
 
-## Verify
+## Verification
 
 - `{curl -fsS http://localhost:{port}/{health}}` returns `200` {and `{body}`}.
 - `{doctor or status command}` reports {expected}. ← keep whichever exists
@@ -130,9 +130,9 @@ The baseline scaffolds `docs/operations/setup.md` when it is missing and the rep
 
 - **Stack:** from the workspace manifests, one row per layer.
 - **Prerequisites:** from the pinning files.
-- **Install and First run:** from the root README's getting-started block (if one exists) and the root scripts.
+- **Installation and First run:** from the root README's getting-started block (if one exists) and the root scripts.
 - **Environment files:** from every `*.example` / `.dev.vars.example` in the workspace.
-- **Verify:** from a health route, a doctor command or the test script.
+- **Verification:** from a health route, a doctor command or the test script.
 
 It leaves Common failures empty until a failure is root-caused, and it drops every section it cannot fill concretely.
 

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

@@ -1,13 +1,18 @@
-# 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.
 
-Required: **What this is**, **Subsystem map**. Optional: Key flows, Where the truth lives.
+Required: **Purpose**, **Subsystem map**. Optional: Key flows, Sources of truth.
+
+```markdown
+---
+type: system-overview
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
+---
 
-```
 # System Overview
 
-## What this is
+## Purpose
 
 {Two or three sentences: what the system does, for whom, in what environment it runs.}
 
@@ -18,13 +23,13 @@ Required: **What this is**, **Subsystem map**. Optional: Key flows, Where the tr
 └──────────┘     └──────────┘     └──────────┘
 {One box per subsystem; label the arrows with the contract that crosses them.}
 
-- **{Subsystem}** — one line: what it owns. → [owning doc](../features/{feature}.md)
+- **{Subsystem}:** what it owns, in one line. → [owning doc](../features/{feature}.md)
 
 ## Key flows
 
-{At most two or three ASCII flow diagrams for the flows everything else hangs off — request lifecycle, auth, the core domain operation.}
+{At most two or three mermaid flow diagrams, at role level, for the flows everything else hangs off: request lifecycle, auth, the core domain operation.}
 
-## Where the truth lives
+## Sources of truth
 
 | Area | Canonical doc |
 | ---- | ------------- |

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.
 
@@ -69,7 +69,7 @@ owns:                                            # transitional — region globs
 - **Objects:** {…}
 - **Code roots:** {…} — directories, one per package the machine spans
 - **Seams:** {…} by name
-- **Checklist:** `tests/{system}.md`
+- **Checklist:** `docs/tests/{system}.md`
 - **See also:** {neighbour}: {why}
 
 No tables, routes or symbol rosters — those are the graph's.

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

@@ -1,10 +1,15 @@
-# Testing Strategy (docs/tests/strategy.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.
 
-Required: **Levels**, **Running**. Optional: Deliberately untested, Adding a test.
+Required: **Levels**, **Commands**. Optional: Deliberately untested, New tests.
+
+```markdown
+---
+type: testing-strategy
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
+---
 
-```
 # Testing Strategy
 
 ## Levels
@@ -14,7 +19,7 @@ Required: **Levels**, **Running**. Optional: Deliberately untested, Adding a tes
 | Unit / integration | {runner} | `tests/` | {what} |
 | E2E | {runner} | `e2e/` | {what} |
 
-## Running
+## Commands
 
 - `{pm} test` — the whole unit suite (CI gate)
 - `{pm} run test:e2e` — {when to run}
@@ -23,7 +28,7 @@ Required: **Levels**, **Running**. Optional: Deliberately untested, Adding a tes
 
 - {Area} — {why, and what verifies it instead (typecheck, boot check, manual journey)}
 
-## Adding a test
+## New tests
 
 1. {Where the file goes, what it's named, where fixtures live}
 ```

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

@@ -1,9 +1,20 @@
-# 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.
 
 **`type: ux`**, plus `status:` and `objects:` — the objects the surface presents (`references/frontmatter.md`). The doctrine it answers to (the state vocabulary, the routing doctrine, the information architecture) is named in its Purpose for people and computed through shared objects for tooling.
 
+```yaml
+---
+type: ux
+description: "{at most 300 characters: what this document settles and where its boundary sits}"
+status: active                    # draft until the surface it decides is built
+objects: [workspace, run]         # the objects the surface presents
+owns:                             # transitional, only when this document speaks for the surface's components (references/frontmatter.md)
+  - packages/{pkg}/src/{surface}/**
+---
+```
+
 **Why this genre exists.** A feature doc (LLD) states what a feature is, how its data flows, and which contracts it honours — all of which stay plausibly true through a rewrite of the surface. Nothing else in the repo states what a person *observes*. So a change to the wire lands, the interface absorbs it, and the absorption reads as maintenance: no test fails, no lint fires, no document is contradicted. This document is the thing a silent change contradicts.
 
 **Not a test plan.** `docs/tests/{feature}.md` records that behavior was driven and holds `Pinned:` traces; this document *decides* the behavior it later verifies. Written after the code, it is a transcript. Write it first.
@@ -15,9 +26,7 @@
 | 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 **coordinated edits** row 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 coordinated-edit row 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.
 
 ---
 
@@ -56,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.

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.