@nurix/etna 0.19.19 → 0.19.21

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

@@ -11,10 +11,16 @@ Writing rules for clear, maintainable documentation.
 ```markdown
 ### `functionName(param1, param2, options)`
 
-**Goal:** One-line purpose **Input:**
+**Goal:** One-line purpose
+
+**Input:**
 
 - `param1` (type) - Description
-- `param2` (type, optional) - Description **Output:** `{ field1, field2 }` **Side Effects:** State updates, API calls, etc.
+- `param2` (type, optional) - Description
+
+**Output:** `{ field1, field2 }`
+
+**Side Effects:** State updates, API calls, etc.
 ```
 
 ### Parameter Rules
@@ -62,34 +68,33 @@ Always specify:
 ```json
 {
   "activeField": "value"
-  // "deprecated": null  // UNUSED: Remove in v3
+  // "deprecated": null  // UNUSED: dead key; kept so old persisted state rehydrates
 }
 ```
-````
 
 **Storage:** localStorage key `state_key`
 
 **Backend:**
 
-```sql
-model Table {
-  id   String @id
-  data Json
-  // old String?  // UNUSED: Legacy
-}
+```ts
+export const table = pgTable('table', {
+  id: text('id').primaryKey(),
+  data: jsonb('data'),
+  // old: text('old'),  // UNUSED: dead column; nothing reads it
+});
 ```
-
 ````
 
 ### Mark Unused Keys
 
-Always comment deprecated/unused fields:
+Always comment deprecated/unused fields. The annotation states why the field is dead _now_ — never where it went, what replaced it, or when it will be removed (no "Remove in v3", no "Migrated to newField"; that is history narration, § The Two Natures below):
+
 ```json
 {
   "active": [],
-  // "legacy": {}  // UNUSED: Migrated to newField
+  // "legacy": {}  // UNUSED: dead key; kept for rehydrate compatibility
 }
-````
+```
 
 ---
 
@@ -102,6 +107,8 @@ Always comment deprecated/unused fields:
 - Component interactions
 - Process flows
 
+**Docs only.** Diagrams belong in documents read on demand (feature docs, ADs, operations). Instruction files — `CLAUDE.md`, rules, agent definitions, `SKILL.md` prose — never carry them: they load on every turn or every invocation, and a table or a sentence carries the same information at a fraction of the tokens.
+
 ### Pattern
 
 ```
@@ -168,6 +175,8 @@ function extract(json) {
 
 ❌ Bad: Full 50-line implementation
 
+(Worked example: [`examples.md`](examples.md) Example 1.)
+
 ---
 
 ## Writing Style
@@ -191,7 +200,7 @@ Prose is valuable for context that contracts can't capture:
 | Non-obvious behavior | "The hook always fetches fresh data. There is no caching or version checking." |
 | Design rationale | "Why parallel fetches? Each entity type is independent, reducing load time." |
 | Edge cases | "If created then deleted before save, it's removed from `added[]` without adding to `removed[]`." |
-| Current limitations | "This hook is not currently integrated into the main flow." |
+| Limitations, stated as facts | "`useAppInit` is standalone — nothing in the mount path calls it." |
 | Usage context | "Used to show 'Unsaved' badge, warn before navigation, enable save buttons." |
 
 ### When to Avoid Prose
@@ -224,7 +233,7 @@ Use for structured info:
 
 Every document is a **truth document** (states current absolutes, updated in place) or a **record** (dated account of activity, frozen or append-only) — see `SKILL.md` § The Two Natures. The tense rules follow directly:
 
-**Truth documents describe the present, not the past.** Everything outside `docs/history/` states what the system _is_ and how it works _today_. It must not narrate how it got there. The journey — the dates, the migrations — lives **only** in records (`docs/history/`: changelog, plans, migrations). Two sanctioned exceptions: `docs/memory/` is the agent's own dated ledger, and an AD's **Decision Changelog** tail carries that decision's dated revision history (the AD body stays current-truth-only — head is truth, tail is provenance).
+**Truth documents describe the present, not the past.** Everything outside `docs/history/` states what the system _is_ and how it works _today_. It must not narrate how it got there. The journey — the dates, the migrations — lives **only** in records (`docs/history/`: changelog, plans, migrations). Three sanctioned exceptions: `docs/memory/` is the agent's own dated ledger; an AD's **Decision Changelog** tail carries that decision's dated revision history; and `docs/structure.md`'s **Health Log** tail carries the maintenance agent's tooling-stamped audit rows. In both tail bridges the body stays current-truth-only — head is truth, tail is provenance.
 
 **Records are never edited to match the present.** A frozen plan stays wrong-in-hindsight; a changelog entry describes what shipped as it shipped. A scope change gets a new dated record that links back.
 
@@ -236,16 +245,31 @@ Strip this language from truth documents:
 | "Built 2026-06-14; shipped + verified 2026-06-13." | "`agentSessionWorkflow` runs an outer turn loop over `runAgentLoop`." |
 | "The legacy worker was deleted in the 2026-06-14 fold." | "One worker interprets `WorkflowDefinition`." |
 | "ex-`@nurix/mcp-runtime`, M9 Phase C; was X, now Y." | "MCP client runtime, wired into `agentTriggerWorkflow`." |
+| "Build Sequence phases 0–4 are complete." | Nothing — progress lives in the plan/backlog record; the doc describes what exists |
+| "There is no standalone `skills/components/` — treat any reference to it as stale." | Nothing — delete or repoint the stale references; state only the present design |
 | "Read first: `docs/history/plans/2026-…-fold.md`" (routing) | "Read first: `docs/architecture/<current-truth-doc>.md`" |
 
 Rules:
 
-- **No dates in truth documents** for when something shipped, was verified, folded, or was removed. A bare status marker (`✅ shipped`, `⏳ pending`) is fine; the _date_ it shipped is not.
+- **No dates and no progress narration in truth documents.** Nothing about _when_ something shipped, was verified, folded, or was removed — and no completion markers either: no "phases 0–4 are complete", no per-item `✅ shipped` / `⏳ pending`. Progress tracking is a **record's** job (the plan, the backlog); a truth document describes what exists, as if it had always been so.
+- **No stale-reference tripwires.** Never write "X is gone — treat references to X as stale"; that is a redirect doc compressed into one sentence. Delete or repoint every stale reference instead (same rule as the **No redirect docs** rule in `SKILL.md` § The Two Natures) and state only the present fact.
+- **No version or phase framing.** A bare `v1`/`v2` as a label, "Phase 1/2", "the old X", "supersedes the earlier" — there is one design; describe it without its predecessors. (A version naming an external present-tense fact stays: a schema literal like `design-tokens/v2`, a dependency pin like `@0.14.0`.)
+- **Temporal hedges are progress markers in prose.** "currently", "not yet", "still", "for now" smuggle a ⏳ into a truth document — state the fact without the hedge ("the hook is standalone; nothing in the mount path calls it") and let the backlog record carry the intention.
+- **A published artifact's own version surface is external fact.** Release notes and upgrade guides for a shipped package may use version framing (`v1 → v2`) — that is the artifact's public contract, not the doc narrating its own past. They live beside the artifact or under `docs/operations/`, never in `docs/features/` or `docs/architecture/`.
 - **Cite the AD for the _why_, never the _when_.** `Provenance: AD-002` is good (it points to the decision rationale). "Decided in AD-002 and shipped 2026-06-13" is not.
-- **Routing/index docs point only to truth documents.** A row whose only "read first" target is a historical plan or changelog is a redirect-for-history — repoint it to the current truth doc, or drop the row.
+- **Routing/index docs point only to truth documents as a topic's authority.** A row whose "read first" target for a topic is a historical plan or changelog is a redirect-for-history — repoint it to the current truth doc, or drop the row. (An index _of the records themselves_ — a History section listing `plans/`, `changelog/` — is sanctioned: that indexes records, it doesn't route a topic.)
 - **When a doc changes because the system changed, the change-story goes in `docs/history/` (a changelog entry), and the truth document simply becomes correct in present tense.** Never leave the diff narrated in place.
 - **A decision that moves is an edit, not a new document.** Rewrite the AD's affected sections to the new truth and append the revision to its Decision Changelog — never mint a parallel doc and never leave the old choice narrated in the body.
 
+Worked example of the strip-and-relocate move: [`examples.md`](examples.md) Example 6.
+
+---
+
+## Mechanics
+
+- Inline-code every identifier, filename, command, and config key.
+- Bullet rules take the form "**bold assertion** — explanation."
+
 ---
 
 ## Structure
@@ -309,7 +333,8 @@ Always end with:
 | Parameters | Type + purpose                  |
 | Returns    | Type + shape                    |
 | State      | Persistence points only         |
-| Diagrams   | ASCII for all flows             |
+| Diagrams   | ASCII for all flows — docs only, never instruction files |
 | Code       | Under 15 lines, contracts only  |
 | Voice      | Imperative/active               |
+| Mechanics  | Inline-code identifiers; bold-assertion bullets |
 | Length     | Concise, one line when possible |

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

@@ -0,0 +1,38 @@
+# 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
+
+Every document is exactly one (`SKILL.md` § The Two Natures). Ask: *when reality changes, is this file rewritten, or is it frozen?*
+
+- Rewritten in place → **truth document**. Topic-named (`kebab-case.md`), lives outside `docs/history/`, present tense throughout — the iron rule in `SKILL.md` § Present tense, always.
+- Frozen or append-only → **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.
+
+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.
+- A new topic *folder* gets a `Readme.md` landing page that introduces and indexes it.
+
+## 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.
+- **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.
+- **Every section earns its place.** No empty stubs — omit what has nothing real to say; write an explicit "None" only where the absence itself is information.
+- **Cite sources and link neighbours.** If the document mentions a concept another document owns, link it; if it draws on code, name the files.
+
+## 4. Write it in the house style
+
+`references/style-guide.md` carries the rules: present tense with no history narration, progress markers, or stale-reference tripwires (§ The Two Natures); imperative/active voice; code examples under 15 lines showing contracts, not implementations; ASCII diagrams in docs only; inline-code every identifier, filename, command, and config key.
+
+## 5. With a human in the loop — the co-authoring workflow
+
+**Stage 1 — context gathering.** Ask: audience? purpose? existing format to match? Have the user dump all the context they hold, then ask 5–10 clarifying questions before proposing anything.
+
+**Stage 2 — structure & draft.** Propose the section structure from §1–3 above, then draft section by section. The user indicates changes — learn their style from their edits; don't silently rewrite them.

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

@@ -0,0 +1,117 @@
+// skills/documentation/scripts/doc-lint.mjs - mechanical checks over markdown docs (tense narration, dates, stubs, redirects)
+// Usage: node doc-lint.mjs <file.md ...> | node doc-lint.mjs --changed   (git-changed + untracked .md)
+// Exit 1 when any block-severity finding survives. Escape hatch: <!-- doc-lint-disable: id[, id] --> (file-wide, or on the offending line).
+
+import { readFileSync, existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+
+const RULES = [
+  { id: 'stale-tripwire', severity: 'block', scope: 'truth', pattern: /treat (any )?[\w`./-]+ ?(references? )?as stale|superseded (by|the)|\bused to (be|target|live|hold)\b/i, message: 'stale-reference tripwire / supersession talk — fix the references, state the present fact' },
+  { id: 'history-narration', severity: 'block', scope: 'truth', pattern: /\bno longer\b|\bwas (renamed|removed|extracted|folded|migrated|replaced)\b|\bmoved (to|from|into) [\w`./-]+ \(?20\d{2}/i, message: 'history narration — the journey belongs in a dated record' },
+  { id: 'progress-marker', severity: 'block', scope: 'truth', pattern: /\bphases?\s+\d[^.\n]{0,40}\b(complete|done)\b|\b(build|implementation) (is )?(\d+%|partially) (complete|done)\b/i, message: 'progress marker — progress lives in the plan/backlog record' },
+  { id: 'temporal-hedge', severity: 'warn', scope: 'truth', pattern: /\bnot yet\b|\bfor now\b|\bcurrently\b|\bstill (unsupported|missing|pending|unimplemented|in progress)\b/i, message: 'temporal hedge — state the fact without "currently / not yet / for now"' },
+  { id: 'predecessor-frame', severity: 'warn', scope: 'truth', pattern: /\bpreviously\b|\bthe old \w+\b|\blegacy \w+ (was|is)\b/i, message: 'predecessor framing — describe the one current design' },
+  { id: 'status-glyph', severity: 'warn', scope: 'truth', pattern: /(^|\s)(✅|⏳|- \[[ x]\])/u, message: 'status glyph / checklist in a truth doc — tracking belongs in a record' },
+  { id: 'date-in-truth-doc', severity: 'warn', scope: 'truth', pattern: /\b20\d{2}-\d{2}-\d{2}\b/, message: 'date in a truth doc — only the AD Decision Changelog and structure.md Health Log tails carry dates' },
+];
+
+// Sections inside a truth doc where dated history is sanctioned (the two bridges).
+const BRIDGE_HEADINGS = /^#{1,4}\s+(decision changelog|health log)\b/i;
+// Instruction files and generated trees are a different genre — out of this linter's scope.
+const SKIP = /(^|\/)(\.claude|node_modules|skills|rules|agents|harness|packages\/[^/]+\/data)\/|(^|\/)(CLAUDE|AGENTS)\.md$/;
+const RECORD = /(^|\/)docs\/(history|research|memory)\//;
+
+// Classify a path: skipped genre, record, or truth.
+function scopeOf(path) {
+  if (SKIP.test(path)) return 'skip';
+  return RECORD.test(path) ? 'record' : 'truth';
+}
+
+// Yield prose lines only: frontmatter, fenced code blocks, and bridge sections drop out.
+function proseLines(text) {
+  const lines = text.split('\n');
+  const out = [];
+  let inFence = false;
+  let inFrontmatter = lines[0] === '---';
+  let inBridge = false;
+  let bridgeLevel = 0;
+  for (let i = inFrontmatter ? 1 : 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (inFrontmatter) { if (line === '---') inFrontmatter = false; continue; }
+    if (/^\s*(```|~~~|````)/.test(line)) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    const heading = line.match(/^(#{1,4})\s/);
+    if (heading) {
+      if (inBridge && heading[1].length <= bridgeLevel) inBridge = false;
+      if (BRIDGE_HEADINGS.test(line)) { inBridge = true; bridgeLevel = heading[1].length; }
+    }
+    if (!inBridge) out.push({ n: i + 1, line });
+  }
+  return out;
+}
+
+// Collect file-wide disabled rule ids from <!-- doc-lint-disable: a, b --> comments.
+function fileDisables(text) {
+  const ids = new Set();
+  for (const m of text.matchAll(/<!--\s*doc-lint-disable:\s*([\w-,\s]+?)\s*-->/g))
+    m[1].split(',').forEach((id) => ids.add(id.trim()));
+  return ids;
+}
+
+function lintFile(path, findings) {
+  const scope = scopeOf(path);
+  if (scope === 'skip' || !existsSync(path)) return;
+  const text = readFileSync(path, 'utf8');
+  const disabled = fileDisables(text);
+  const lines = proseLines(text);
+
+  const nonEmpty = text.split('\n').filter((l) => l.trim()).length;
+  if (scope === 'truth' && nonEmpty <= 10 && /\b(moved to|relocated to|see [\w`./-]+ instead)\b/i.test(text) && !disabled.has('redirect-doc'))
+    findings.push({ path, n: 1, severity: 'block', id: 'redirect-doc', message: 'redirect stub — delete the file and repoint every inbound link' });
+
+  for (const rule of RULES) {
+    if (rule.scope !== scope || disabled.has(rule.id)) continue;
+    for (const { n, line } of lines) {
+      if (!rule.pattern.test(line)) continue;
+      if (line.includes(`doc-lint-disable: ${rule.id}`) || new RegExp(`doc-lint-disable:[^>]*\\b${rule.id}\\b`).test(line)) continue;
+      findings.push({ path, n, severity: rule.severity, id: rule.id, message: rule.message, excerpt: line.trim().slice(0, 90) });
+    }
+  }
+
+  if (scope === 'truth' && /(^|\/)docs\/features\/[^/]+\.md$/.test(path)) {
+    const fm = text.startsWith('---') ? text.slice(0, text.indexOf('\n---', 3)) : '';
+    for (const key of ['owns:', 'keywords:', 'status:'])
+      if (!fm.includes(key)) findings.push({ path, n: 1, severity: 'block', id: 'feature-frontmatter', message: `feature doc missing \`${key}\` frontmatter` });
+  }
+}
+
+// A changed plan whose committed version is already frozen must not be edited.
+function checkFrozenEdits(paths, findings) {
+  for (const path of paths) {
+    if (!/(^|\/)docs\/history\/(plans|changelog|migrations)\//.test(path)) continue;
+    try {
+      const head = execSync(`git show HEAD:"${path}"`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] });
+      if (/(^|\/)plans\//.test(path) && !/Status:\s*(Complete|Abandoned)/i.test(head)) continue;
+      findings.push({ path, n: 1, severity: 'block', id: 'frozen-record-edit', message: 'frozen record modified — records are never edited; write a new dated record that links back' });
+    } catch { /* new file — creating a record is fine */ }
+  }
+}
+
+const args = process.argv.slice(2);
+let files = args.filter((a) => a !== '--changed');
+const changedMode = args.includes('--changed');
+if (changedMode) {
+  const out = execSync('git diff --name-only HEAD -- "*.md"; git ls-files --others --exclude-standard -- "*.md"', { encoding: 'utf8', shell: '/bin/bash' });
+  files = [...new Set([...files, ...out.split('\n').filter(Boolean)])];
+}
+if (!files.length) { console.error('usage: node doc-lint.mjs <file.md ...> | --changed'); process.exit(2); }
+
+const findings = [];
+files.forEach((f) => lintFile(f, findings));
+if (changedMode) checkFrozenEdits(files.filter((f) => existsSync(f)), findings);
+
+for (const f of findings.sort((a, b) => (a.severity === b.severity ? 0 : a.severity === 'block' ? -1 : 1)))
+  console.log(`${f.path}:${f.n} [${f.severity}] ${f.id} — ${f.message}${f.excerpt ? `: "${f.excerpt}"` : ''}`);
+const blocks = findings.filter((f) => f.severity === 'block').length;
+console.log(`\n${findings.length} finding(s), ${blocks} blocking, ${files.length} file(s) checked.`);
+process.exit(blocks ? 1 : 0);

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

@@ -0,0 +1,31 @@
+# Documentation Templates
+
+One file per template. Every template is either a **truth document** (states current absolutes, updated in place) or a **record** (dated account of activity, frozen or append-only) — the split is defined in `SKILL.md` § The Two Natures, and each template names its nature in its opening line.
+
+| Template | File | Nature |
+| --- | --- | --- |
+| Feature (LLD) | [feature.md](feature.md) | Truth |
+| Architecture Decision (AD) | [architecture-decision.md](architecture-decision.md) | Truth (Decision Changelog tail sanctioned) |
+| System overview | [system-overview.md](system-overview.md) | Truth |
+| Domain model | [domain-model.md](domain-model.md) | Truth |
+| Glossary | [glossary.md](glossary.md) | Truth |
+| Non-goals | [non-goals.md](non-goals.md) | Truth |
+| API reference | [api-reference.md](api-reference.md) | Truth |
+| Environment registry | [environment-registry.md](environment-registry.md) | Truth |
+| Security overview | [security-overview.md](security-overview.md) | Truth |
+| Testing strategy | [testing-strategy.md](testing-strategy.md) | Truth |
+| Operations procedure | [operations-procedure.md](operations-procedure.md) | Truth |
+| Protected files | [protected-files.md](protected-files.md) | Truth |
+| Project root README | [root-readme.md](root-readme.md) | Truth |
+| docs/README.md (doc index) | [docs-readme.md](docs-readme.md) | Truth |
+| docs/structure.md (authority map) | [structure.md](structure.md) | Truth (Health Log tail sanctioned) |
+| Plan | [plan.md](plan.md) | Record |
+| Changelog entry | [changelog-entry.md](changelog-entry.md) | Record |
+| Migration runbook | [migration-runbook.md](migration-runbook.md) | Record |
+| CHANGELOG master index | [changelog-index.md](changelog-index.md) | Record index (append-only) |
+| Backlog | [backlog.md](backlog.md) | Record (append-only) |
+| Memory (main agent) | [memory-main.md](memory-main.md) | Record (append-only ledger) |
+
+**Baseline scaffolds** — files that must exist after every baseline; the `maintenance` agent (baseline mode) creates any that are missing: [docs-readme.md](docs-readme.md), [structure.md](structure.md), [changelog-index.md](changelog-index.md), [backlog.md](backlog.md), [memory-main.md](memory-main.md), and [root-readme.md](root-readme.md) (never overwriting an existing root README).
+
+**Ownership.** A feature doc is the canonical reference for the code paths in its **`owns:` frontmatter** — the only ownership key. To find what a doc owns, read its `owns:` globs; to find the doc for a path, match the path against the injected ownership index (the union of every feature's `owns:` globs), narrower glob wins. See [`../references/frontmatter.md`](../references/frontmatter.md) for turning code into `owns:` globs.

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

@@ -0,0 +1,20 @@
+# 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 **index**: request/response shapes stay in the owning feature docs; this doc answers "what exists and where is it documented." 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).
+
+Required: **Conventions**, the **route tables**. One row per live route; a route that isn't here doesn't exist.
+
+```
+# API Reference
+
+## Conventions
+
+- Base path: `/api/v{N}` · Auth: {scheme} · Envelope: `{ "status": 1, "message": "...", "data": {...} }`
+- Errors: `{ "status": 0, "message": "...", "data": null }` · Codes: 200/201/400/401/403/404/500
+
+## {Resource group}
+
+| Method | Path | Purpose | Auth | Owning doc |
+| ------ | ---- | ------- | ---- | ---------- |
+| GET | `/api/foo` | {one line} | {role} | [feature](../features/{feature}.md) |
+```

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

@@ -0,0 +1,121 @@
+# Architecture Decision (AD)
+
+Truth document — with the one sanctioned dated tail. Use for: the standing decision on one architectural **subject** — a system shape, a contract, a substrate choice. Lives in `docs/architecture/decisions/`. The body always states the current decision and its current reasoning. When the decision moves, rewrite the affected sections to what is now true, bump `last-updated`, and append the revision to the **Decision Changelog** — the journey lives in that tail, never in the body. Head is truth; tail is provenance.
+
+### One subject per AD
+
+The unit is the subject, not the individual call. "The persistence layer", "auth", "the design-skill architecture" are subjects; every decision, reversal, and re-decision on a subject lands in that subject's one AD, however many times it moves. Write a second AD only when a genuinely separate subject emerges — never to record a revision of an existing one.
+
+### When to write an AD
+
+Write an AD when **all three** apply:
+
+1. The decision is architectural — affects system shape, contracts, or substrate choice, not internal implementation
+2. Alternatives were genuinely considered and rejected
+3. Future maintainers will ask "why is it this way?"
+
+Don't write an AD for:
+
+- Standing principles or style preferences (those are stances, not decisions — put them in `docs/architecture/`)
+- Routine implementation choices with no rejected alternatives
+- Anything you'd be happy reversing without ceremony
+
+### Lifecycle
+
+`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.
+
+### Naming
+
+`AD-NNN-short-title.md` — three-digit zero-padded number, kebab-case subject. Numbers are assigned sequentially across the project and never reused.
+
+### Structure
+
+Three sections are required: **Decision**, **Context**, **Consequences** — plus the **Decision Changelog** once the AD has been revised at least once. Everything else is optional — include only when warranted. Decision-first: readers should see the answer in the first paragraph.
+
+### Template
+
+```markdown
+---
+title: "AD-NNN: Short title in sentence case"
+status: Accepted # Proposed | Accepted | Deprecated
+created: YYYY-MM-DD
+last-updated: YYYY-MM-DD # bump on every revision
+decision-owner: Name
+reviewers: [] # optional
+tags: [ad]
+---
+
+# AD-NNN: Short Title
+
+## Decision
+
+[One paragraph, active voice. "We will…" Lead with the answer — the current answer, whatever the journey was.]
+
+## Context
+
+[The forces in play. What is the problem? Why does it need a decision? Technical, political, social, and project-local pressures — stated as present-tense forces, not as a history of the subject.]
+
+## Consequences
+
+**Positive:**
+
+- [What becomes easier]
+
+**Negative:**
+
+- [What becomes harder, what we accept reluctantly]
+
+**Risks:**
+
+- [Second-order effects you can already see, with mitigations if known]
+
+<!-- Optional sections below. Include only when warranted by the decision's weight. -->
+
+## Decision Drivers
+
+[Hard non-negotiables vs. strong levers. Include when alternatives exist and the criteria aren't self-evident from Context.]
+
+## Options Considered
+
+| Option       | Pros | Cons | Outcome               |
+| ------------ | ---- | ---- | --------------------- |
+| **Option A** | …    | …    | **CHOSEN**            |
+| Option B     | …    | …    | Eliminated — [reason] |
+
+## Deep Comparison
+
+[Honest framing of the strongest alternative(s). Include when the table doesn't make the reasoning obvious. State the *real* reason each was rejected — not a strawman.]
+
+## Architecture in Detail
+
+[Diagrams, code shape, layer responsibilities. Include when the decision implies non-trivial structure that readers need to understand alongside the *why*. Execution belongs in a plan doc (`docs/history/plans/`) — link to it, don't embed an implementation plan here.]
+
+## Open Questions
+
+1. **[Question]** — _Default_: [stated default until resolved].
+
+## References
+
+- [External link or cross-reference]
+
+## Decision Changelog
+
+<!-- The provenance tail — append-only, newest first. One entry per revision: what changed, the trigger, the previous choice, and the plan that implemented it. Added on the first revision; the initial acceptance is the last entry. -->
+
+- YYYY-MM-DD — [What changed] because [trigger]. Implemented by [plan link]. (Previously: [old choice].)
+- YYYY-MM-DD — Initial decision accepted. Implemented by [plan link].
+```
+
+### 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.

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

@@ -0,0 +1,33 @@
+# Scaffold: docs/history/backlog.md
+
+Baseline scaffold — created if missing (the `maintenance` agent's baseline calls this). Target file: `docs/history/backlog.md`.
+
+```
+# Backlog
+
+Tracked work items, technical debt, and planned improvements. Append new items under the appropriate priority.
+
+---
+
+## Format
+
+- **[P0]** Description — discovered by [plan-name or agent-name]
+
+---
+
+## P0 — Critical
+
+{items here}
+
+## P1 — High
+
+{items here}
+
+## P2 — Medium
+
+{items here}
+
+## P3 — Low
+
+{items here}
+```

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

@@ -0,0 +1,62 @@
+# Changelog
+
+Record. Use for: recording code changes with function-level detail. Entries are frozen once written — they describe the change as it shipped, and are never edited to match later reality.
+
+Change categories follow the Keep a Changelog vocabulary — **Added / Changed / Deprecated / Removed / Fixed / Security** — the same six the master `CHANGELOG.md` scaffold instructs. Include only the categories that apply; all six share the same bullet shape (function/file, then detail lines).
+
+```
+# YYYY-MM-DD - [Title]
+
+## Summary
+
+Brief description of what changed and why.
+
+## Changes
+
+### Added
+- `newFunction(params)` in `path/to/file.js`
+  - Purpose: What it does
+  - Used by: Where it's called
+
+### Changed
+- `existingFunction()` in `path/to/file.js`
+  - Changed: What's different
+  - Reason: Why it changed
+  - Migration: What callers must do
+
+### Removed
+- `oldFunction()` from `path/to/file.js`
+  - Replaced by: `newFunction()`
+
+### Fixed
+- `buggyFunction()` in `path/to/file.js`
+  - Bug: What was wrong, when it manifested
+  - Fix: What changed
+
+(Deprecated / Security follow the same shape.)
+
+## Breaking Changes
+
+⚠️ **[Change description]**
+- Old: Previous behavior
+- New: Current behavior
+- Impact: What breaks
+- Migration: How to fix
+
+## Migration Steps
+
+Numbered instructions for whoever applies the change — not a tracked task list (the entry is frozen once written):
+
+1. {Step}
+2. {Step}
+
+## Verified
+
+- What was exercised end-to-end and the observed result — real runs, real fixtures, measured timings
+- A future agent diagnosing a regression starts from this evidence
+
+## Files Changed
+
+- `src/path/file1.js` - Core changes
+- `src/path/file2.js` - Supporting updates
+```

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

@@ -0,0 +1,41 @@
+# Scaffold: docs/history/CHANGELOG.md
+
+Baseline scaffold — created if missing (the `maintenance` agent's baseline calls this). Target file: `docs/history/CHANGELOG.md`.
+
+```
+# Changelog
+
+All notable changes to {Project Name} will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+---
+
+## [Unreleased]
+
+{entries added here as work proceeds; promoting them under a release heading is the one sanctioned edit to this index — the dated entry files themselves stay frozen}
+
+---
+
+## Links
+
+- [Setup Guide](../operations/setup.md)
+- [Architecture](../architecture/)
+
+---
+
+## How to Update This Changelog
+
+1. Create a dated change file in `docs/history/changelog/`:
+   `docs/history/changelog/YYYY-MM-DD-feature-name.md`
+
+2. Update this CHANGELOG.md with a high-level summary linking to the detail file
+
+3. Follow Keep a Changelog categories:
+   - **Added** for new features
+   - **Changed** for changes in existing functionality
+   - **Deprecated** for soon-to-be removed features
+   - **Removed** for now removed features
+   - **Fixed** for bug fixes
+   - **Security** for security improvements
+```