@nurix/etna 0.19.29 → 0.19.31

package/bin/etna.js

@@ -242,6 +242,49 @@ function pruneOrphanedComponents(targetDir, priorOwned, newOwned) {
     return removed;
 }
 
+// Every file inside dir, as paths relative to dir.
+function listFilesRecursive(dir, prefix = '') {
+    const out = [];
+    if (!existsSync(dir)) return out;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) out.push(...listFilesRecursive(join(dir, entry.name), rel));
+        else out.push(rel);
+    }
+    return out;
+}
+
+// Remove directories left empty by a prune, depth-first.
+function removeEmptyDirs(dir) {
+    if (!existsSync(dir)) return;
+    for (const entry of readdirSync(dir, { withFileTypes: true }))
+        if (entry.isDirectory()) removeEmptyDirs(join(dir, entry.name));
+    if (readdirSync(dir).length === 0) rmSync(dir, { recursive: true, force: true });
+}
+
+// Remove files inside an installed component that this bundle no longer ships. copyHarnessSubdir
+// merges, so a component that SURVIVES an upgrade while shedding a file keeps the stale copy
+// forever — that is how a retired reference file goes on being read as live doctrine. Scoped to
+// components the bundle still ships (a project's own components are never in that set, so they
+// are never touched), and needs no prior manifest, so one refresh clears orphans left by any
+// earlier version. Whole components that disappear are pruneOrphanedComponents' job.
+function pruneStaleComponentFiles(bundledSubdir, projectSubdir) {
+    const removed = [];
+    if (!existsSync(bundledSubdir)) return removed;
+    for (const entry of readdirSync(bundledSubdir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        const shipped = new Set(listFilesRecursive(join(bundledSubdir, entry.name)));
+        const installedDir = join(projectSubdir, entry.name);
+        for (const rel of listFilesRecursive(installedDir)) {
+            if (shipped.has(rel)) continue;
+            rmSync(join(installedDir, rel), { force: true });
+            removed.push(`${entry.name}/${rel}`);
+        }
+        removeEmptyDirs(installedDir);
+    }
+    return removed;
+}
+
 // True if an event's matcher-group already carries a hook with this command string.
 function groupHasCommand(group, command) {
     return (group.hooks || []).some((h) => h.command === command);
@@ -395,6 +438,16 @@ async function installHarness(harnessName, harnesses) {
     const newOwned = bundledOwned(bundledHarnessDir);
     for (const r of pruneOrphanedComponents(targetDir, priorOwned, newOwned)) notices.push(`removed ${r}`);
 
+    // Then prune stale files INSIDE components the bundle still ships — the case the
+    // name-level diff above cannot see, since the component itself is still present.
+    for (const sub of PRUNABLE_SUBDIRS) {
+        const stale = pruneStaleComponentFiles(
+            join(bundledHarnessDir, sub),
+            join(targetDir, '.claude', sub),
+        );
+        for (const r of stale) notices.push(`removed stale ${sub.replace(/s$/, '')} file ${r}`);
+    }
+
     // Dual-runtime: derive the repo's Codex artifacts (AGENTS.md, .agents/skills/,
     // .codex/agents/, .codex/hooks.json) from the just-installed Claude tree + bundle, so the
     // same project works under Codex too. Pure-derived — no MCP, no settings/config.toml

package/data/harness-index.json

@@ -1,5 +1,5 @@
 {
-    "fingerprint": "d66fabc6887f",
+    "fingerprint": "db921503525c",
     "harnesses": {
         "code": {
             "plugin": "code",

package/data/harnesses/code/.prettierignore

@@ -8,8 +8,19 @@ pnpm-lock.yaml
 package-lock.json
 yarn.lock
 
-# Harness-managed agent/skill definitions (installed under .claude/)
+# Harness-managed — the installer overwrites all of these, so formatting them is churn
+# that comes straight back on the next `npx @nurix/etna`.
 .claude
+.codex
+.agents
+CLAUDE.md
+AGENTS.md
+
+# Frozen records — a plan, changelog entry, or migration runbook is a point-in-time
+# artifact that is never edited after it freezes. Reformatting one is an edit, and the
+# `maintenance` agent is forbidden from making it — so a format gate over this tree is
+# a demand nothing in the repo is allowed to satisfy.
+docs/history
 
 # Source catalogs — authored markdown; prettier collapses template/example blocks
 skills

package/data/harnesses/code/agents/maintenance.md

@@ -27,7 +27,9 @@ Decide the mode once, up front, from the version marker — then run.
 2. Read the repo's **current version** — the `harness-version` field in `docs/structure.md` frontmatter (a semver).
    - **Absent** ⇒ the repo is unharnessed ⇒ **baseline mode** (reconcile from nothing), then audit.
    - **Behind on major** ⇒ **baseline mode** (reconcile across the gap), then audit.
-   - **Behind on minor/patch** ⇒ **probe before deciding.** Run the Step B2 detection pass read-only: if any old-shape artifact in the fold table is present, **or** the target tree is missing a folder the current shape mandates, the shape *did* change ⇒ **baseline mode**. Only when the probe finds nothing ⇒ re-stamp the version (no reshape), then audit.
+   - **Behind on minor/patch** ⇒ **probe before deciding.** Run the Step B2 detection pass read-only: if any old-shape artifact in the fold table is present, **or** any **scaffolded file** in the target tree is missing (`docs/README.md`, `docs/structure.md`, `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/index.md`), the shape *did* change ⇒ **baseline mode**. Only when the probe finds nothing ⇒ re-stamp the version (no reshape), then audit.
+
+   > **Never probe on a missing folder.** Git does not track empty directories, so an unused folder is absent on every clone — reading that as drift puts the repo in baseline mode *forever* and contradicts this agent's own idempotency guarantee. Only the five scaffolded files above are shape signals; every folder in the target tree is created on first use.
    - **Equal to installed** ⇒ **audit only** (the default spine).
 
 > **The version digit is a hint; the fold table is the authority.** A shape change ships in a minor whenever the capability behind it is additive — `docs/history/ledger/` dissolving into `docs/history/changelog/` arrived in a minor, as did `docs/history/migrations/`. Never conclude "minor ⇒ nothing to reshape" without running the probe: that reading silently strands dissolved-shape artifacts in the repo forever.
@@ -113,7 +115,7 @@ For unowned code paths:
 
 ### Step 6: Report & update tracking
 
-1. Update `docs/structure.md` Health Log with today's date and summary.
+1. Update `docs/structure.md` Health Log with today's date and summary — **append to the end**, never date-sorted into the middle. Rows are positional: one may say "the row above is…", and an inserted row silently breaks that reference.
 2. Update `docs/memory/maintenance.md` with last review date, stale docs fixed, unowned paths, backlog items created.
 3. Report findings: stale docs, broken ownership, unowned code, architecture drift, backlog health.
 
@@ -127,27 +129,31 @@ Baseline mode converges the repo's `docs/` to the **installed** harness shape, t
 
 ```
 docs/
-├── README.md              # Documentation root — quick links, section index
-├── structure.md           # Authority map + frontmatter `harness-version` (you own this field)
+├── README.md            ✱ # Documentation root — quick links, section index
+├── structure.md         ✱ # Authority map + frontmatter `harness-version` (you own this field)
 ├── architecture/          # Cross-module design + steering layer
 │   │                      #   domain-model, glossary, non-goals, references, open-questions
 │   └── decisions/         # Architecture Decisions (ADs — one per subject, updated in place; journey in each AD's Decision Changelog)
 ├── features/              # Feature specs — the only first-class doc unit (flat; ownership in each doc's `owns:` frontmatter)
 │   └── {group}/           #   browse-only subfolder for grouping; NEVER a module; may carry a Readme.md
 ├── operations/            # Setup, development, deployment, CI/CD
-├── research/              # Optional — in-progress brainstorm sessions ({topic}-brainstorm/; legacy -brainstorming/) + standing research; Readme.md is the index
-│   └── {topic}-brainstorm/     #   created by the `brainstorm` skill; NOT scaffolded empty; moves to history/brainstorms/ on a passed harvest
+├── research/              # In-progress brainstorm sessions ({topic}-brainstorm/; legacy -brainstorming/) + standing research; Readme.md is the index
+│   └── {topic}-brainstorm/     #   created by the `brainstorm` skill; moves to history/brainstorms/ on a passed harvest
 ├── history/
-│   ├── CHANGELOG.md       # Master changelog index
-│   ├── changelog/         # Individual entries (YYYY-MM-DD-{three-words}.md; written at commit time, NOT scaffolded empty)
+│   ├── CHANGELOG.md     ✱ # Master changelog index
+│   ├── changelog/         # Individual entries (YYYY-MM-DD-{three-words}.md; written at commit time)
 │   ├── plans/             # Implementation plans (Status field required)
-│   ├── migrations/        # One-shot migration/upgrade runbooks (YYYY-MM-DD-{slug}.md; outcome-stamped then frozen; NOT scaffolded empty)
+│   ├── migrations/        # One-shot migration/upgrade runbooks (YYYY-MM-DD-{slug}.md; outcome-stamped then frozen)
 │   ├── brainstorms/       # Harvested brainstorm sessions ({topic}/) — user decides kept (committed) or deleted; Readme.md is the index
-│   └── backlog.md         # Tracked work items by priority (P0-P3)
-├── memory/                # index.md, main.md, {agent}.md — project knowledge + per-agent strategy memory
-└── tests/                 # Behavioral test checklists ({feature}.md, step → **Assert**), derived at plan Completion via the `documentation` skill; author-maintained, present only when test docs exist
+│   ├── research/          # Deep-research records ({topic}/ — README.md synthesis + findings.md + sources.md); frozen, cited, owns no code
+│   └── backlog.md       ✱ # Tracked work items by priority (P0-P3)
+├── memory/
+│   └── index.md         ✱ #   plus main.md, {agent}.md — project knowledge + per-agent strategy memory
+└── tests/                 # Behavioral test checklists ({feature}.md, step → **Assert**), derived at plan Completion via the `documentation` skill; author-maintained
 ```
 
+**✱ marks the five scaffolded files — the only paths a baseline creates, and the only shape signals.** Every **folder** in this tree is created on first use and is simply absent until it holds a file; git cannot track an empty directory, so a missing folder is never evidence of drift and is never scaffolded to satisfy the shape. Record its role in `docs/structure.md` instead.
+
 There is **no `docs/routing.md`**, **no `docs/modules/{m}/`**, **no `docs/pillars/`**, **no `docs/boundaries/`**. Code ownership lives in feature `owns:` frontmatter; a module is a `module:` label, not a folder; boundaries are diagnosed from source; brainstorm records live in `docs/research/` (active) and `docs/history/brainstorms/` (harvested).
 
 > Brainstorm records are **author-created, never scaffolded** — the `brainstorm` skill writes an active session at `docs/research/{topic}-brainstorm/` (legacy folders carry the older `-brainstorming/` suffix; treat both as canonical) and moves it to `docs/history/brainstorms/{topic}/` on a **passed harvest** — the move is the completion marker, and the moved folder's fate is the **user's decision: delete or commit**. Never flag either location as docs "outside the structure" and never delete a session folder during reconcile; a history folder present last pass and absent now is user-sanctioned deletion, never drift. Each folder carries a `Readme.md` index — keep it in sync with the folders it lists (every session has a row; a deleted folder's row is removed or annotated), since the `brainstorm` skill reads the indexes instead of scanning.
@@ -173,7 +179,8 @@ This is what makes baseline more than a fresh scaffold. Detect old-shape artifac
 | `docs/history/ledger/YYYY-MM.md` (the Refinement Ledger, now merged into the changelog) | split each `### ` block into its own `docs/history/changelog/YYYY-MM-DD-{three-words}.md` entry — content preserved **verbatim**, heading promoted to `#`, three words naming the work; append one row per entry to `docs/history/CHANGELOG.md`; delete the `docs/history/ledger/` folder. Records are moved, never rewritten |
 | `docs/operations/guardrails.md` | fold durable contract notes into `docs/architecture/` |
 | `docs/architecture/overview.md` | split into `domain-model.md` / `glossary.md` / `non-goals.md` / `references.md` / `open-questions.md` |
-| a legacy `docs/brainstorm/{topic}/`, or a root `brainstorm/`/`brainstorming/` folder | move each **active** record to `docs/research/{topic}-brainstorm/` and each **harvested** one to `docs/history/brainstorms/{topic}/` (dropping the suffix); create/refresh both `Readme.md` indexes; delete the emptied folder |
+| `docs/architecture/adr/` (legacy folder name), or `ADR-NNN-*.md` records anywhere under `docs/architecture/` | **rename to the AD genre.** The folder becomes `docs/architecture/decisions/`; each record file `ADR-NNN-{slug}.md` becomes `AD-NNN-{slug}.md`, keeping its number and slug. Inside each record, update the retired vocabulary — "ADR", "Architecture Decision Record", and any supersession framing ("once accepted, an ADR is never edited; a later ADR supersedes it") — to the AD model: one AD per subject, **updated in place**, its journey confined to a `Decision Changelog` tail. A record's **reasoning is never rewritten** by a reconcile; only its genre vocabulary, its own title/id, and paths it cites. The folder's `Readme.md` is an **index, not a record** — reframe its genre description while preserving authored content such as a candidate-decision list verbatim. Repoint live references **inside `docs/`**, including one AD citing another; leave frozen records' links as point-in-time. A live reference **outside** your write scope — most often the root `README.md`, which you never overwrite — cannot be repointed: record it as a backlog item naming the file and line rather than leaving the residue silent |
+| a legacy `docs/brainstorm/{topic}/`, a singular `docs/history/brainstorm/`, or a root `brainstorm/`/`brainstorming/` folder | move each **active** record to `docs/research/{topic}-brainstorm/` and each **harvested** one to `docs/history/brainstorms/{topic}/` (dropping the suffix); create/refresh both `Readme.md` indexes; delete the emptied folder |
 | no `harness-version` in `structure.md` | stamp it (Step B4) |
 
 ### Step B3 — Present the reconcile plan, then execute

package/data/harnesses/code/codex/agents/maintenance.toml

@@ -25,7 +25,9 @@ Decide the mode once, up front, from the version marker — then run.
 2. Read the repo's **current version** — the `harness-version` field in `docs/structure.md` frontmatter (a semver).
    - **Absent** ⇒ the repo is unharnessed ⇒ **baseline mode** (reconcile from nothing), then audit.
    - **Behind on major** ⇒ **baseline mode** (reconcile across the gap), then audit.
-   - **Behind on minor/patch** ⇒ **probe before deciding.** Run the Step B2 detection pass read-only: if any old-shape artifact in the fold table is present, **or** the target tree is missing a folder the current shape mandates, the shape *did* change ⇒ **baseline mode**. Only when the probe finds nothing ⇒ re-stamp the version (no reshape), then audit.
+   - **Behind on minor/patch** ⇒ **probe before deciding.** Run the Step B2 detection pass read-only: if any old-shape artifact in the fold table is present, **or** any **scaffolded file** in the target tree is missing (`docs/README.md`, `docs/structure.md`, `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/index.md`), the shape *did* change ⇒ **baseline mode**. Only when the probe finds nothing ⇒ re-stamp the version (no reshape), then audit.
+
+   > **Never probe on a missing folder.** Git does not track empty directories, so an unused folder is absent on every clone — reading that as drift puts the repo in baseline mode *forever* and contradicts this agent's own idempotency guarantee. Only the five scaffolded files above are shape signals; every folder in the target tree is created on first use.
    - **Equal to installed** ⇒ **audit only** (the default spine).
 
 > **The version digit is a hint; the fold table is the authority.** A shape change ships in a minor whenever the capability behind it is additive — `docs/history/ledger/` dissolving into `docs/history/changelog/` arrived in a minor, as did `docs/history/migrations/`. Never conclude "minor ⇒ nothing to reshape" without running the probe: that reading silently strands dissolved-shape artifacts in the repo forever.
@@ -111,7 +113,7 @@ For unowned code paths:
 
 ### Step 6: Report & update tracking
 
-1. Update `docs/structure.md` Health Log with today's date and summary.
+1. Update `docs/structure.md` Health Log with today's date and summary — **append to the end**, never date-sorted into the middle. Rows are positional: one may say "the row above is…", and an inserted row silently breaks that reference.
 2. Update `docs/memory/maintenance.md` with last review date, stale docs fixed, unowned paths, backlog items created.
 3. Report findings: stale docs, broken ownership, unowned code, architecture drift, backlog health.
 
@@ -125,27 +127,31 @@ Baseline mode converges the repo's `docs/` to the **installed** harness shape, t
 
 ```
 docs/
-├── README.md              # Documentation root — quick links, section index
-├── structure.md           # Authority map + frontmatter `harness-version` (you own this field)
+├── README.md            ✱ # Documentation root — quick links, section index
+├── structure.md         ✱ # Authority map + frontmatter `harness-version` (you own this field)
 ├── architecture/          # Cross-module design + steering layer
 │   │                      #   domain-model, glossary, non-goals, references, open-questions
 │   └── decisions/         # Architecture Decisions (ADs — one per subject, updated in place; journey in each AD's Decision Changelog)
 ├── features/              # Feature specs — the only first-class doc unit (flat; ownership in each doc's `owns:` frontmatter)
 │   └── {group}/           #   browse-only subfolder for grouping; NEVER a module; may carry a Readme.md
 ├── operations/            # Setup, development, deployment, CI/CD
-├── research/              # Optional — in-progress brainstorm sessions ({topic}-brainstorm/; legacy -brainstorming/) + standing research; Readme.md is the index
-│   └── {topic}-brainstorm/     #   created by the `brainstorm` skill; NOT scaffolded empty; moves to history/brainstorms/ on a passed harvest
+├── research/              # In-progress brainstorm sessions ({topic}-brainstorm/; legacy -brainstorming/) + standing research; Readme.md is the index
+│   └── {topic}-brainstorm/     #   created by the `brainstorm` skill; moves to history/brainstorms/ on a passed harvest
 ├── history/
-│   ├── CHANGELOG.md       # Master changelog index
-│   ├── changelog/         # Individual entries (YYYY-MM-DD-{three-words}.md; written at commit time, NOT scaffolded empty)
+│   ├── CHANGELOG.md     ✱ # Master changelog index
+│   ├── changelog/         # Individual entries (YYYY-MM-DD-{three-words}.md; written at commit time)
 │   ├── plans/             # Implementation plans (Status field required)
-│   ├── migrations/        # One-shot migration/upgrade runbooks (YYYY-MM-DD-{slug}.md; outcome-stamped then frozen; NOT scaffolded empty)
+│   ├── migrations/        # One-shot migration/upgrade runbooks (YYYY-MM-DD-{slug}.md; outcome-stamped then frozen)
 │   ├── brainstorms/       # Harvested brainstorm sessions ({topic}/) — user decides kept (committed) or deleted; Readme.md is the index
-│   └── backlog.md         # Tracked work items by priority (P0-P3)
-├── memory/                # index.md, main.md, {agent}.md — project knowledge + per-agent strategy memory
-└── tests/                 # Behavioral test checklists ({feature}.md, step → **Assert**), derived at plan Completion via the `documentation` skill; author-maintained, present only when test docs exist
+│   ├── research/          # Deep-research records ({topic}/ — README.md synthesis + findings.md + sources.md); frozen, cited, owns no code
+│   └── backlog.md       ✱ # Tracked work items by priority (P0-P3)
+├── memory/
+│   └── index.md         ✱ #   plus main.md, {agent}.md — project knowledge + per-agent strategy memory
+└── tests/                 # Behavioral test checklists ({feature}.md, step → **Assert**), derived at plan Completion via the `documentation` skill; author-maintained
 ```
 
+**✱ marks the five scaffolded files — the only paths a baseline creates, and the only shape signals.** Every **folder** in this tree is created on first use and is simply absent until it holds a file; git cannot track an empty directory, so a missing folder is never evidence of drift and is never scaffolded to satisfy the shape. Record its role in `docs/structure.md` instead.
+
 There is **no `docs/routing.md`**, **no `docs/modules/{m}/`**, **no `docs/pillars/`**, **no `docs/boundaries/`**. Code ownership lives in feature `owns:` frontmatter; a module is a `module:` label, not a folder; boundaries are diagnosed from source; brainstorm records live in `docs/research/` (active) and `docs/history/brainstorms/` (harvested).
 
 > Brainstorm records are **author-created, never scaffolded** — the `brainstorm` skill writes an active session at `docs/research/{topic}-brainstorm/` (legacy folders carry the older `-brainstorming/` suffix; treat both as canonical) and moves it to `docs/history/brainstorms/{topic}/` on a **passed harvest** — the move is the completion marker, and the moved folder's fate is the **user's decision: delete or commit**. Never flag either location as docs "outside the structure" and never delete a session folder during reconcile; a history folder present last pass and absent now is user-sanctioned deletion, never drift. Each folder carries a `Readme.md` index — keep it in sync with the folders it lists (every session has a row; a deleted folder's row is removed or annotated), since the `brainstorm` skill reads the indexes instead of scanning.
@@ -171,7 +177,8 @@ This is what makes baseline more than a fresh scaffold. Detect old-shape artifac
 | `docs/history/ledger/YYYY-MM.md` (the Refinement Ledger, now merged into the changelog) | split each `### ` block into its own `docs/history/changelog/YYYY-MM-DD-{three-words}.md` entry — content preserved **verbatim**, heading promoted to `#`, three words naming the work; append one row per entry to `docs/history/CHANGELOG.md`; delete the `docs/history/ledger/` folder. Records are moved, never rewritten |
 | `docs/operations/guardrails.md` | fold durable contract notes into `docs/architecture/` |
 | `docs/architecture/overview.md` | split into `domain-model.md` / `glossary.md` / `non-goals.md` / `references.md` / `open-questions.md` |
-| a legacy `docs/brainstorm/{topic}/`, or a root `brainstorm/`/`brainstorming/` folder | move each **active** record to `docs/research/{topic}-brainstorm/` and each **harvested** one to `docs/history/brainstorms/{topic}/` (dropping the suffix); create/refresh both `Readme.md` indexes; delete the emptied folder |
+| `docs/architecture/adr/` (legacy folder name), or `ADR-NNN-*.md` records anywhere under `docs/architecture/` | **rename to the AD genre.** The folder becomes `docs/architecture/decisions/`; each record file `ADR-NNN-{slug}.md` becomes `AD-NNN-{slug}.md`, keeping its number and slug. Inside each record, update the retired vocabulary — "ADR", "Architecture Decision Record", and any supersession framing ("once accepted, an ADR is never edited; a later ADR supersedes it") — to the AD model: one AD per subject, **updated in place**, its journey confined to a `Decision Changelog` tail. A record's **reasoning is never rewritten** by a reconcile; only its genre vocabulary, its own title/id, and paths it cites. The folder's `Readme.md` is an **index, not a record** — reframe its genre description while preserving authored content such as a candidate-decision list verbatim. Repoint live references **inside `docs/`**, including one AD citing another; leave frozen records' links as point-in-time. A live reference **outside** your write scope — most often the root `README.md`, which you never overwrite — cannot be repointed: record it as a backlog item naming the file and line rather than leaving the residue silent |
+| a legacy `docs/brainstorm/{topic}/`, a singular `docs/history/brainstorm/`, or a root `brainstorm/`/`brainstorming/` folder | move each **active** record to `docs/research/{topic}-brainstorm/` and each **harvested** one to `docs/history/brainstorms/{topic}/` (dropping the suffix); create/refresh both `Readme.md` indexes; delete the emptied folder |
 | no `harness-version` in `structure.md` | stamp it (Step B4) |
 
 ### Step B3 — Present the reconcile plan, then execute

package/data/harnesses/code/harness.json

@@ -1,11 +1,11 @@
 {
   "harness": "code",
   "name": "code",
-  "version": "3.4.2",
+  "version": "3.5.0",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
-  "digest": "94097b6f4ba1"
+  "digest": "7281074d495c"
 }

package/data/harnesses/code/skills/boundary/SKILL.md

@@ -17,7 +17,7 @@ Three layers tell you what to look for; the code tells you what exists.
 
 - **The mechanisms** — [`references/mechanisms.md`](references/mechanisms.md) defines the seven failure mechanisms every boundary instantiates (rendezvous-string, serialized-shape, generated-artifact, dual-authority, config-elsewhere, trust-invariant, lifecycle-protocol), each with its trace strategy, universal safe-change pattern, and severity heuristic, plus the two stack-independent domain contracts (entity-model, tenancy). Load it on every check.
 - **The technology packs** — [`references/index.md`](references/index.md) routes to the packs under `references/packs/` by the signals in the touched code. Each pack carries the non-derivable payload for one technology area: exact detect patterns, expensive-to-learn gotchas, and safe-change sequences. Load **only the packs the touch list exhibits**; a technology no pack covers is still in scope — diagnose it from its mechanism.
-- **Repo doctrine** — `.claude/rules/`, `docs/architecture/` (including `adr/`), and any contracts package name the repo's bespoke contracts (a documented response envelope, a schema-parity rule, an entity model). A documented contract is a real side of a boundary: a plan that contradicts one is a finding **even when no code consumer exists yet** — this is how greenfield plans, whose modules have no code to trace, still get checked.
+- **Repo doctrine** — `.claude/rules/`, `docs/architecture/` (including `decisions/`), and any contracts package name the repo's bespoke contracts (a documented response envelope, a schema-parity rule, an entity model). A documented contract is a real side of a boundary: a plan that contradicts one is a finding **even when no code consumer exists yet** — this is how greenfield plans, whose modules have no code to trace, still get checked.
 
 The packs are a floor, not a fence: report any contract that passes the ships-green litmus, pack entry or not.
 

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

@@ -2,7 +2,7 @@
 // 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 { readFileSync, existsSync, statSync, readdirSync } from 'node:fs';
 import { execSync } from 'node:child_process';
 
 const RULES = [
@@ -10,10 +10,14 @@ const RULES = [
   { 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' },
-  // docs/tests/ behavioral checklists use `- [ ]` as test-step notation (step → **Assert**), not progress tracking — exempt that one folder from this rule; every other truth doc still bans checkboxes.
-  { id: 'status-glyph', severity: 'warn', scope: 'truth', exempt: /(^|\/)docs\/tests\//, 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' },
+  // "previously-fetched" is a hyphenated adjective naming a thing, not a predecessor design — don't fire on it.
+  { 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' },
+  // docs/tests/ behavioral checklists use `- [ ]` as test-step notation (step → **Assert**) and docs/operations/
+  // procedures use it for operator verification steps — neither is progress tracking. Every other truth doc still bans checkboxes.
+  { id: 'status-glyph', severity: 'warn', scope: 'truth', exempt: /(^|\/)docs\/(tests|operations)\//, pattern: /(^|\s)(✅|⏳|- \[[ x]\])/u, message: 'status glyph / checklist in a truth doc — tracking belongs in a record' },
+  // Truth docs are supposed to cite records, and record filenames are dated — so a date inside a link
+  // target or a code span is a path, not narration. Strip those before matching.
+  { id: 'date-in-truth-doc', severity: 'warn', scope: 'truth', strip: /\[[^\]]*\]\([^)]*\)|`[^`]*`/g, 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).
@@ -74,13 +78,16 @@ function lintFile(path, findings) {
     if (rule.scope !== scope || disabled.has(rule.id)) continue;
     if (rule.exempt && rule.exempt.test(path)) continue;
     for (const { n, line } of lines) {
-      if (!rule.pattern.test(line)) continue;
+      const subject = rule.strip ? line.replace(rule.strip, '') : line;
+      if (!rule.pattern.test(subject)) 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)) {
+  // 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);
+  if (scope === 'truth' && !isFolderIndex && /(^|\/)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` });
@@ -106,7 +113,21 @@ 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); }
+// Expand any directory argument into the .md files beneath it, so `doc-lint.mjs docs/` works.
+function expandDirs(paths) {
+  const out = [];
+  for (const p of paths) {
+    if (!existsSync(p)) { out.push(p); continue; }
+    if (!statSync(p).isDirectory()) { out.push(p); continue; }
+    for (const e of readdirSync(p, { withFileTypes: true })) {
+      if (e.name === 'node_modules' || e.name.startsWith('.')) continue;
+      out.push(...expandDirs([`${p.replace(/\/$/, '')}/${e.name}`]));
+    }
+  }
+  return out;
+}
+files = expandDirs(files).filter((f) => f.endsWith('.md'));
+if (!files.length) { console.error('usage: node doc-lint.mjs <file.md | dir ...> | --changed'); process.exit(2); }
 
 const findings = [];
 files.forEach((f) => lintFile(f, findings));

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

@@ -2,6 +2,8 @@
 
 Truth document. Use for: the entry point for all documentation in a repo. Created during baseline audit.
 
+**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.
+
 ```
 # {Project Name} Documentation
 

package/data/harnesses/discover/.prettierignore

@@ -8,8 +8,19 @@ pnpm-lock.yaml
 package-lock.json
 yarn.lock
 
-# Harness-managed agent/skill definitions (installed under .claude/)
+# Harness-managed — the installer overwrites all of these, so formatting them is churn
+# that comes straight back on the next `npx @nurix/etna`.
 .claude
+.codex
+.agents
+CLAUDE.md
+AGENTS.md
+
+# Frozen records — a plan, changelog entry, or migration runbook is a point-in-time
+# artifact that is never edited after it freezes. Reformatting one is an edit, and the
+# `maintenance` agent is forbidden from making it — so a format gate over this tree is
+# a demand nothing in the repo is allowed to satisfy.
+docs/history
 
 # Source catalogs — authored markdown; prettier collapses template/example blocks
 skills

package/data/harnesses/discover/harness.json

@@ -8,5 +8,5 @@
     ".vscode/settings.json",
     "tooling-recommendations.md"
   ],
-  "digest": "43b78e58bf42"
+  "digest": "48356bdb7940"
 }

package/data/harnesses/discussion/.prettierignore

@@ -8,8 +8,19 @@ pnpm-lock.yaml
 package-lock.json
 yarn.lock
 
-# Harness-managed agent/skill definitions (installed under .claude/)
+# Harness-managed — the installer overwrites all of these, so formatting them is churn
+# that comes straight back on the next `npx @nurix/etna`.
 .claude
+.codex
+.agents
+CLAUDE.md
+AGENTS.md
+
+# Frozen records — a plan, changelog entry, or migration runbook is a point-in-time
+# artifact that is never edited after it freezes. Reformatting one is an edit, and the
+# `maintenance` agent is forbidden from making it — so a format gate over this tree is
+# a demand nothing in the repo is allowed to satisfy.
+docs/history
 
 # Source catalogs — authored markdown; prettier collapses template/example blocks
 skills

package/data/harnesses/discussion/harness.json

@@ -1,11 +1,11 @@
 {
   "harness": "discussion",
   "name": "discussion",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
-  "digest": "3f0234327768"
+  "digest": "74ab29c65c8f"
 }

package/data/harnesses/etna/.prettierignore

@@ -8,8 +8,19 @@ pnpm-lock.yaml
 package-lock.json
 yarn.lock
 
-# Harness-managed agent/skill definitions (installed under .claude/)
+# Harness-managed — the installer overwrites all of these, so formatting them is churn
+# that comes straight back on the next `npx @nurix/etna`.
 .claude
+.codex
+.agents
+CLAUDE.md
+AGENTS.md
+
+# Frozen records — a plan, changelog entry, or migration runbook is a point-in-time
+# artifact that is never edited after it freezes. Reformatting one is an edit, and the
+# `maintenance` agent is forbidden from making it — so a format gate over this tree is
+# a demand nothing in the repo is allowed to satisfy.
+docs/history
 
 # Source catalogs — authored markdown; prettier collapses template/example blocks
 skills

package/data/harnesses/etna/CLAUDE.md

@@ -44,7 +44,7 @@ etna authors the components it also runs and ships, so **three copies of every c
 | --- | --- | --- |
 | **Source** (canonical) | the shared catalogs — `skills/`, `agents/`, `rules/`, plus `harness/*/` (each harness — its `readme.md` manifest, `CLAUDE.md` policy, and owned trees in one folder) | Edit here. Etna is the source of truth. |
 | **Dogfood** | `.claude/skills/`, `.claude/agents/`, `.claude/rules/`, `.claude/hooks/` (git-tracked) | The subset the `etna` harness installs on itself — the copy this repo actually runs this session. |
-| **Shipped bundle** | `packages/cli/data/harnesses/*/` (git-tracked build artifact, regenerated by `packages/cli/scripts/build-data.js`) | Generated — never hand-edit. |
+| **Shipped bundle** | `packages/cli/data/harnesses/*/` (generated by `packages/cli/scripts/build-data.js`; gitignored except each harness `CLAUDE.md`, and rebuilt by `prepack` on every publish) | Generated — never hand-edit. |
 
 - **Keep source and dogfood in sync.** When a dogfooded component's source changes, mirror the edit into its `.claude/` copy in the same change — otherwise the skill this session runs diverges from the authored one.
 - **A component edit ships.** On push to `dev`, CI fingerprints the payload, patch-bumps, and publishes to the marketplace and `@nurix/etna` npm — reaching every consumer repo. Weigh catalog edits with that blast radius in mind. The pipeline authority is **[`docs/architecture/distribution.md`](docs/architecture/distribution.md)** — link, don't restate.

package/data/harnesses/etna/agents/maintenance.md

@@ -27,7 +27,9 @@ Decide the mode once, up front, from the version marker — then run.
 2. Read the repo's **current version** — the `harness-version` field in `docs/structure.md` frontmatter (a semver).
    - **Absent** ⇒ the repo is unharnessed ⇒ **baseline mode** (reconcile from nothing), then audit.
    - **Behind on major** ⇒ **baseline mode** (reconcile across the gap), then audit.
-   - **Behind on minor/patch** ⇒ **probe before deciding.** Run the Step B2 detection pass read-only: if any old-shape artifact in the fold table is present, **or** the target tree is missing a folder the current shape mandates, the shape *did* change ⇒ **baseline mode**. Only when the probe finds nothing ⇒ re-stamp the version (no reshape), then audit.
+   - **Behind on minor/patch** ⇒ **probe before deciding.** Run the Step B2 detection pass read-only: if any old-shape artifact in the fold table is present, **or** any **scaffolded file** in the target tree is missing (`docs/README.md`, `docs/structure.md`, `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/index.md`), the shape *did* change ⇒ **baseline mode**. Only when the probe finds nothing ⇒ re-stamp the version (no reshape), then audit.
+
+   > **Never probe on a missing folder.** Git does not track empty directories, so an unused folder is absent on every clone — reading that as drift puts the repo in baseline mode *forever* and contradicts this agent's own idempotency guarantee. Only the five scaffolded files above are shape signals; every folder in the target tree is created on first use.
    - **Equal to installed** ⇒ **audit only** (the default spine).
 
 > **The version digit is a hint; the fold table is the authority.** A shape change ships in a minor whenever the capability behind it is additive — `docs/history/ledger/` dissolving into `docs/history/changelog/` arrived in a minor, as did `docs/history/migrations/`. Never conclude "minor ⇒ nothing to reshape" without running the probe: that reading silently strands dissolved-shape artifacts in the repo forever.
@@ -113,7 +115,7 @@ For unowned code paths:
 
 ### Step 6: Report & update tracking
 
-1. Update `docs/structure.md` Health Log with today's date and summary.
+1. Update `docs/structure.md` Health Log with today's date and summary — **append to the end**, never date-sorted into the middle. Rows are positional: one may say "the row above is…", and an inserted row silently breaks that reference.
 2. Update `docs/memory/maintenance.md` with last review date, stale docs fixed, unowned paths, backlog items created.
 3. Report findings: stale docs, broken ownership, unowned code, architecture drift, backlog health.
 
@@ -127,27 +129,31 @@ Baseline mode converges the repo's `docs/` to the **installed** harness shape, t
 
 ```
 docs/
-├── README.md              # Documentation root — quick links, section index
-├── structure.md           # Authority map + frontmatter `harness-version` (you own this field)
+├── README.md            ✱ # Documentation root — quick links, section index
+├── structure.md         ✱ # Authority map + frontmatter `harness-version` (you own this field)
 ├── architecture/          # Cross-module design + steering layer
 │   │                      #   domain-model, glossary, non-goals, references, open-questions
 │   └── decisions/         # Architecture Decisions (ADs — one per subject, updated in place; journey in each AD's Decision Changelog)
 ├── features/              # Feature specs — the only first-class doc unit (flat; ownership in each doc's `owns:` frontmatter)
 │   └── {group}/           #   browse-only subfolder for grouping; NEVER a module; may carry a Readme.md
 ├── operations/            # Setup, development, deployment, CI/CD
-├── research/              # Optional — in-progress brainstorm sessions ({topic}-brainstorm/; legacy -brainstorming/) + standing research; Readme.md is the index
-│   └── {topic}-brainstorm/     #   created by the `brainstorm` skill; NOT scaffolded empty; moves to history/brainstorms/ on a passed harvest
+├── research/              # In-progress brainstorm sessions ({topic}-brainstorm/; legacy -brainstorming/) + standing research; Readme.md is the index
+│   └── {topic}-brainstorm/     #   created by the `brainstorm` skill; moves to history/brainstorms/ on a passed harvest
 ├── history/
-│   ├── CHANGELOG.md       # Master changelog index
-│   ├── changelog/         # Individual entries (YYYY-MM-DD-{three-words}.md; written at commit time, NOT scaffolded empty)
+│   ├── CHANGELOG.md     ✱ # Master changelog index
+│   ├── changelog/         # Individual entries (YYYY-MM-DD-{three-words}.md; written at commit time)
 │   ├── plans/             # Implementation plans (Status field required)
-│   ├── migrations/        # One-shot migration/upgrade runbooks (YYYY-MM-DD-{slug}.md; outcome-stamped then frozen; NOT scaffolded empty)
+│   ├── migrations/        # One-shot migration/upgrade runbooks (YYYY-MM-DD-{slug}.md; outcome-stamped then frozen)
 │   ├── brainstorms/       # Harvested brainstorm sessions ({topic}/) — user decides kept (committed) or deleted; Readme.md is the index
-│   └── backlog.md         # Tracked work items by priority (P0-P3)
-├── memory/                # index.md, main.md, {agent}.md — project knowledge + per-agent strategy memory
-└── tests/                 # Behavioral test checklists ({feature}.md, step → **Assert**), derived at plan Completion via the `documentation` skill; author-maintained, present only when test docs exist
+│   ├── research/          # Deep-research records ({topic}/ — README.md synthesis + findings.md + sources.md); frozen, cited, owns no code
+│   └── backlog.md       ✱ # Tracked work items by priority (P0-P3)
+├── memory/
+│   └── index.md         ✱ #   plus main.md, {agent}.md — project knowledge + per-agent strategy memory
+└── tests/                 # Behavioral test checklists ({feature}.md, step → **Assert**), derived at plan Completion via the `documentation` skill; author-maintained
 ```
 
+**✱ marks the five scaffolded files — the only paths a baseline creates, and the only shape signals.** Every **folder** in this tree is created on first use and is simply absent until it holds a file; git cannot track an empty directory, so a missing folder is never evidence of drift and is never scaffolded to satisfy the shape. Record its role in `docs/structure.md` instead.
+
 There is **no `docs/routing.md`**, **no `docs/modules/{m}/`**, **no `docs/pillars/`**, **no `docs/boundaries/`**. Code ownership lives in feature `owns:` frontmatter; a module is a `module:` label, not a folder; boundaries are diagnosed from source; brainstorm records live in `docs/research/` (active) and `docs/history/brainstorms/` (harvested).
 
 > Brainstorm records are **author-created, never scaffolded** — the `brainstorm` skill writes an active session at `docs/research/{topic}-brainstorm/` (legacy folders carry the older `-brainstorming/` suffix; treat both as canonical) and moves it to `docs/history/brainstorms/{topic}/` on a **passed harvest** — the move is the completion marker, and the moved folder's fate is the **user's decision: delete or commit**. Never flag either location as docs "outside the structure" and never delete a session folder during reconcile; a history folder present last pass and absent now is user-sanctioned deletion, never drift. Each folder carries a `Readme.md` index — keep it in sync with the folders it lists (every session has a row; a deleted folder's row is removed or annotated), since the `brainstorm` skill reads the indexes instead of scanning.
@@ -173,7 +179,8 @@ This is what makes baseline more than a fresh scaffold. Detect old-shape artifac
 | `docs/history/ledger/YYYY-MM.md` (the Refinement Ledger, now merged into the changelog) | split each `### ` block into its own `docs/history/changelog/YYYY-MM-DD-{three-words}.md` entry — content preserved **verbatim**, heading promoted to `#`, three words naming the work; append one row per entry to `docs/history/CHANGELOG.md`; delete the `docs/history/ledger/` folder. Records are moved, never rewritten |
 | `docs/operations/guardrails.md` | fold durable contract notes into `docs/architecture/` |
 | `docs/architecture/overview.md` | split into `domain-model.md` / `glossary.md` / `non-goals.md` / `references.md` / `open-questions.md` |
-| a legacy `docs/brainstorm/{topic}/`, or a root `brainstorm/`/`brainstorming/` folder | move each **active** record to `docs/research/{topic}-brainstorm/` and each **harvested** one to `docs/history/brainstorms/{topic}/` (dropping the suffix); create/refresh both `Readme.md` indexes; delete the emptied folder |
+| `docs/architecture/adr/` (legacy folder name), or `ADR-NNN-*.md` records anywhere under `docs/architecture/` | **rename to the AD genre.** The folder becomes `docs/architecture/decisions/`; each record file `ADR-NNN-{slug}.md` becomes `AD-NNN-{slug}.md`, keeping its number and slug. Inside each record, update the retired vocabulary — "ADR", "Architecture Decision Record", and any supersession framing ("once accepted, an ADR is never edited; a later ADR supersedes it") — to the AD model: one AD per subject, **updated in place**, its journey confined to a `Decision Changelog` tail. A record's **reasoning is never rewritten** by a reconcile; only its genre vocabulary, its own title/id, and paths it cites. The folder's `Readme.md` is an **index, not a record** — reframe its genre description while preserving authored content such as a candidate-decision list verbatim. Repoint live references **inside `docs/`**, including one AD citing another; leave frozen records' links as point-in-time. A live reference **outside** your write scope — most often the root `README.md`, which you never overwrite — cannot be repointed: record it as a backlog item naming the file and line rather than leaving the residue silent |
+| a legacy `docs/brainstorm/{topic}/`, a singular `docs/history/brainstorm/`, or a root `brainstorm/`/`brainstorming/` folder | move each **active** record to `docs/research/{topic}-brainstorm/` and each **harvested** one to `docs/history/brainstorms/{topic}/` (dropping the suffix); create/refresh both `Readme.md` indexes; delete the emptied folder |
 | no `harness-version` in `structure.md` | stamp it (Step B4) |
 
 ### Step B3 — Present the reconcile plan, then execute

package/data/harnesses/etna/codex/agents/maintenance.toml

@@ -25,7 +25,9 @@ Decide the mode once, up front, from the version marker — then run.
 2. Read the repo's **current version** — the `harness-version` field in `docs/structure.md` frontmatter (a semver).
    - **Absent** ⇒ the repo is unharnessed ⇒ **baseline mode** (reconcile from nothing), then audit.
    - **Behind on major** ⇒ **baseline mode** (reconcile across the gap), then audit.
-   - **Behind on minor/patch** ⇒ **probe before deciding.** Run the Step B2 detection pass read-only: if any old-shape artifact in the fold table is present, **or** the target tree is missing a folder the current shape mandates, the shape *did* change ⇒ **baseline mode**. Only when the probe finds nothing ⇒ re-stamp the version (no reshape), then audit.
+   - **Behind on minor/patch** ⇒ **probe before deciding.** Run the Step B2 detection pass read-only: if any old-shape artifact in the fold table is present, **or** any **scaffolded file** in the target tree is missing (`docs/README.md`, `docs/structure.md`, `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/index.md`), the shape *did* change ⇒ **baseline mode**. Only when the probe finds nothing ⇒ re-stamp the version (no reshape), then audit.
+
+   > **Never probe on a missing folder.** Git does not track empty directories, so an unused folder is absent on every clone — reading that as drift puts the repo in baseline mode *forever* and contradicts this agent's own idempotency guarantee. Only the five scaffolded files above are shape signals; every folder in the target tree is created on first use.
    - **Equal to installed** ⇒ **audit only** (the default spine).
 
 > **The version digit is a hint; the fold table is the authority.** A shape change ships in a minor whenever the capability behind it is additive — `docs/history/ledger/` dissolving into `docs/history/changelog/` arrived in a minor, as did `docs/history/migrations/`. Never conclude "minor ⇒ nothing to reshape" without running the probe: that reading silently strands dissolved-shape artifacts in the repo forever.
@@ -111,7 +113,7 @@ For unowned code paths:
 
 ### Step 6: Report & update tracking
 
-1. Update `docs/structure.md` Health Log with today's date and summary.
+1. Update `docs/structure.md` Health Log with today's date and summary — **append to the end**, never date-sorted into the middle. Rows are positional: one may say "the row above is…", and an inserted row silently breaks that reference.
 2. Update `docs/memory/maintenance.md` with last review date, stale docs fixed, unowned paths, backlog items created.
 3. Report findings: stale docs, broken ownership, unowned code, architecture drift, backlog health.
 
@@ -125,27 +127,31 @@ Baseline mode converges the repo's `docs/` to the **installed** harness shape, t
 
 ```
 docs/
-├── README.md              # Documentation root — quick links, section index
-├── structure.md           # Authority map + frontmatter `harness-version` (you own this field)
+├── README.md            ✱ # Documentation root — quick links, section index
+├── structure.md         ✱ # Authority map + frontmatter `harness-version` (you own this field)
 ├── architecture/          # Cross-module design + steering layer
 │   │                      #   domain-model, glossary, non-goals, references, open-questions
 │   └── decisions/         # Architecture Decisions (ADs — one per subject, updated in place; journey in each AD's Decision Changelog)
 ├── features/              # Feature specs — the only first-class doc unit (flat; ownership in each doc's `owns:` frontmatter)
 │   └── {group}/           #   browse-only subfolder for grouping; NEVER a module; may carry a Readme.md
 ├── operations/            # Setup, development, deployment, CI/CD
-├── research/              # Optional — in-progress brainstorm sessions ({topic}-brainstorm/; legacy -brainstorming/) + standing research; Readme.md is the index
-│   └── {topic}-brainstorm/     #   created by the `brainstorm` skill; NOT scaffolded empty; moves to history/brainstorms/ on a passed harvest
+├── research/              # In-progress brainstorm sessions ({topic}-brainstorm/; legacy -brainstorming/) + standing research; Readme.md is the index
+│   └── {topic}-brainstorm/     #   created by the `brainstorm` skill; moves to history/brainstorms/ on a passed harvest
 ├── history/
-│   ├── CHANGELOG.md       # Master changelog index
-│   ├── changelog/         # Individual entries (YYYY-MM-DD-{three-words}.md; written at commit time, NOT scaffolded empty)
+│   ├── CHANGELOG.md     ✱ # Master changelog index
+│   ├── changelog/         # Individual entries (YYYY-MM-DD-{three-words}.md; written at commit time)
 │   ├── plans/             # Implementation plans (Status field required)
-│   ├── migrations/        # One-shot migration/upgrade runbooks (YYYY-MM-DD-{slug}.md; outcome-stamped then frozen; NOT scaffolded empty)
+│   ├── migrations/        # One-shot migration/upgrade runbooks (YYYY-MM-DD-{slug}.md; outcome-stamped then frozen)
 │   ├── brainstorms/       # Harvested brainstorm sessions ({topic}/) — user decides kept (committed) or deleted; Readme.md is the index
-│   └── backlog.md         # Tracked work items by priority (P0-P3)
-├── memory/                # index.md, main.md, {agent}.md — project knowledge + per-agent strategy memory
-└── tests/                 # Behavioral test checklists ({feature}.md, step → **Assert**), derived at plan Completion via the `documentation` skill; author-maintained, present only when test docs exist
+│   ├── research/          # Deep-research records ({topic}/ — README.md synthesis + findings.md + sources.md); frozen, cited, owns no code
+│   └── backlog.md       ✱ # Tracked work items by priority (P0-P3)
+├── memory/
+│   └── index.md         ✱ #   plus main.md, {agent}.md — project knowledge + per-agent strategy memory
+└── tests/                 # Behavioral test checklists ({feature}.md, step → **Assert**), derived at plan Completion via the `documentation` skill; author-maintained
 ```
 
+**✱ marks the five scaffolded files — the only paths a baseline creates, and the only shape signals.** Every **folder** in this tree is created on first use and is simply absent until it holds a file; git cannot track an empty directory, so a missing folder is never evidence of drift and is never scaffolded to satisfy the shape. Record its role in `docs/structure.md` instead.
+
 There is **no `docs/routing.md`**, **no `docs/modules/{m}/`**, **no `docs/pillars/`**, **no `docs/boundaries/`**. Code ownership lives in feature `owns:` frontmatter; a module is a `module:` label, not a folder; boundaries are diagnosed from source; brainstorm records live in `docs/research/` (active) and `docs/history/brainstorms/` (harvested).
 
 > Brainstorm records are **author-created, never scaffolded** — the `brainstorm` skill writes an active session at `docs/research/{topic}-brainstorm/` (legacy folders carry the older `-brainstorming/` suffix; treat both as canonical) and moves it to `docs/history/brainstorms/{topic}/` on a **passed harvest** — the move is the completion marker, and the moved folder's fate is the **user's decision: delete or commit**. Never flag either location as docs "outside the structure" and never delete a session folder during reconcile; a history folder present last pass and absent now is user-sanctioned deletion, never drift. Each folder carries a `Readme.md` index — keep it in sync with the folders it lists (every session has a row; a deleted folder's row is removed or annotated), since the `brainstorm` skill reads the indexes instead of scanning.
@@ -171,7 +177,8 @@ This is what makes baseline more than a fresh scaffold. Detect old-shape artifac
 | `docs/history/ledger/YYYY-MM.md` (the Refinement Ledger, now merged into the changelog) | split each `### ` block into its own `docs/history/changelog/YYYY-MM-DD-{three-words}.md` entry — content preserved **verbatim**, heading promoted to `#`, three words naming the work; append one row per entry to `docs/history/CHANGELOG.md`; delete the `docs/history/ledger/` folder. Records are moved, never rewritten |
 | `docs/operations/guardrails.md` | fold durable contract notes into `docs/architecture/` |
 | `docs/architecture/overview.md` | split into `domain-model.md` / `glossary.md` / `non-goals.md` / `references.md` / `open-questions.md` |
-| a legacy `docs/brainstorm/{topic}/`, or a root `brainstorm/`/`brainstorming/` folder | move each **active** record to `docs/research/{topic}-brainstorm/` and each **harvested** one to `docs/history/brainstorms/{topic}/` (dropping the suffix); create/refresh both `Readme.md` indexes; delete the emptied folder |
+| `docs/architecture/adr/` (legacy folder name), or `ADR-NNN-*.md` records anywhere under `docs/architecture/` | **rename to the AD genre.** The folder becomes `docs/architecture/decisions/`; each record file `ADR-NNN-{slug}.md` becomes `AD-NNN-{slug}.md`, keeping its number and slug. Inside each record, update the retired vocabulary — "ADR", "Architecture Decision Record", and any supersession framing ("once accepted, an ADR is never edited; a later ADR supersedes it") — to the AD model: one AD per subject, **updated in place**, its journey confined to a `Decision Changelog` tail. A record's **reasoning is never rewritten** by a reconcile; only its genre vocabulary, its own title/id, and paths it cites. The folder's `Readme.md` is an **index, not a record** — reframe its genre description while preserving authored content such as a candidate-decision list verbatim. Repoint live references **inside `docs/`**, including one AD citing another; leave frozen records' links as point-in-time. A live reference **outside** your write scope — most often the root `README.md`, which you never overwrite — cannot be repointed: record it as a backlog item naming the file and line rather than leaving the residue silent |
+| a legacy `docs/brainstorm/{topic}/`, a singular `docs/history/brainstorm/`, or a root `brainstorm/`/`brainstorming/` folder | move each **active** record to `docs/research/{topic}-brainstorm/` and each **harvested** one to `docs/history/brainstorms/{topic}/` (dropping the suffix); create/refresh both `Readme.md` indexes; delete the emptied folder |
 | no `harness-version` in `structure.md` | stamp it (Step B4) |
 
 ### Step B3 — Present the reconcile plan, then execute

package/data/harnesses/etna/harness.json

@@ -1,11 +1,11 @@
 {
   "harness": "etna",
   "name": "etna",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
-  "digest": "a515403fea70"
+  "digest": "b1de16d6988e"
 }

package/data/harnesses/etna/skills/boundary/SKILL.md

@@ -17,7 +17,7 @@ Three layers tell you what to look for; the code tells you what exists.
 
 - **The mechanisms** — [`references/mechanisms.md`](references/mechanisms.md) defines the seven failure mechanisms every boundary instantiates (rendezvous-string, serialized-shape, generated-artifact, dual-authority, config-elsewhere, trust-invariant, lifecycle-protocol), each with its trace strategy, universal safe-change pattern, and severity heuristic, plus the two stack-independent domain contracts (entity-model, tenancy). Load it on every check.
 - **The technology packs** — [`references/index.md`](references/index.md) routes to the packs under `references/packs/` by the signals in the touched code. Each pack carries the non-derivable payload for one technology area: exact detect patterns, expensive-to-learn gotchas, and safe-change sequences. Load **only the packs the touch list exhibits**; a technology no pack covers is still in scope — diagnose it from its mechanism.
-- **Repo doctrine** — `.claude/rules/`, `docs/architecture/` (including `adr/`), and any contracts package name the repo's bespoke contracts (a documented response envelope, a schema-parity rule, an entity model). A documented contract is a real side of a boundary: a plan that contradicts one is a finding **even when no code consumer exists yet** — this is how greenfield plans, whose modules have no code to trace, still get checked.
+- **Repo doctrine** — `.claude/rules/`, `docs/architecture/` (including `decisions/`), and any contracts package name the repo's bespoke contracts (a documented response envelope, a schema-parity rule, an entity model). A documented contract is a real side of a boundary: a plan that contradicts one is a finding **even when no code consumer exists yet** — this is how greenfield plans, whose modules have no code to trace, still get checked.
 
 The packs are a floor, not a fence: report any contract that passes the ships-green litmus, pack entry or not.
 

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

@@ -2,7 +2,7 @@
 // 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 { readFileSync, existsSync, statSync, readdirSync } from 'node:fs';
 import { execSync } from 'node:child_process';
 
 const RULES = [
@@ -10,10 +10,14 @@ const RULES = [
   { 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' },
-  // docs/tests/ behavioral checklists use `- [ ]` as test-step notation (step → **Assert**), not progress tracking — exempt that one folder from this rule; every other truth doc still bans checkboxes.
-  { id: 'status-glyph', severity: 'warn', scope: 'truth', exempt: /(^|\/)docs\/tests\//, 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' },
+  // "previously-fetched" is a hyphenated adjective naming a thing, not a predecessor design — don't fire on it.
+  { 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' },
+  // docs/tests/ behavioral checklists use `- [ ]` as test-step notation (step → **Assert**) and docs/operations/
+  // procedures use it for operator verification steps — neither is progress tracking. Every other truth doc still bans checkboxes.
+  { id: 'status-glyph', severity: 'warn', scope: 'truth', exempt: /(^|\/)docs\/(tests|operations)\//, pattern: /(^|\s)(✅|⏳|- \[[ x]\])/u, message: 'status glyph / checklist in a truth doc — tracking belongs in a record' },
+  // Truth docs are supposed to cite records, and record filenames are dated — so a date inside a link
+  // target or a code span is a path, not narration. Strip those before matching.
+  { id: 'date-in-truth-doc', severity: 'warn', scope: 'truth', strip: /\[[^\]]*\]\([^)]*\)|`[^`]*`/g, 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).
@@ -74,13 +78,16 @@ function lintFile(path, findings) {
     if (rule.scope !== scope || disabled.has(rule.id)) continue;
     if (rule.exempt && rule.exempt.test(path)) continue;
     for (const { n, line } of lines) {
-      if (!rule.pattern.test(line)) continue;
+      const subject = rule.strip ? line.replace(rule.strip, '') : line;
+      if (!rule.pattern.test(subject)) 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)) {
+  // 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);
+  if (scope === 'truth' && !isFolderIndex && /(^|\/)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` });
@@ -106,7 +113,21 @@ 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); }
+// Expand any directory argument into the .md files beneath it, so `doc-lint.mjs docs/` works.
+function expandDirs(paths) {
+  const out = [];
+  for (const p of paths) {
+    if (!existsSync(p)) { out.push(p); continue; }
+    if (!statSync(p).isDirectory()) { out.push(p); continue; }
+    for (const e of readdirSync(p, { withFileTypes: true })) {
+      if (e.name === 'node_modules' || e.name.startsWith('.')) continue;
+      out.push(...expandDirs([`${p.replace(/\/$/, '')}/${e.name}`]));
+    }
+  }
+  return out;
+}
+files = expandDirs(files).filter((f) => f.endsWith('.md'));
+if (!files.length) { console.error('usage: node doc-lint.mjs <file.md | dir ...> | --changed'); process.exit(2); }
 
 const findings = [];
 files.forEach((f) => lintFile(f, findings));

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

@@ -2,6 +2,8 @@
 
 Truth document. Use for: the entry point for all documentation in a repo. Created during baseline audit.
 
+**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.
+
 ```
 # {Project Name} Documentation
 

package/data/harnesses/hr/.prettierignore

@@ -8,8 +8,19 @@ pnpm-lock.yaml
 package-lock.json
 yarn.lock
 
-# Harness-managed agent/skill definitions (installed under .claude/)
+# Harness-managed — the installer overwrites all of these, so formatting them is churn
+# that comes straight back on the next `npx @nurix/etna`.
 .claude
+.codex
+.agents
+CLAUDE.md
+AGENTS.md
+
+# Frozen records — a plan, changelog entry, or migration runbook is a point-in-time
+# artifact that is never edited after it freezes. Reformatting one is an edit, and the
+# `maintenance` agent is forbidden from making it — so a format gate over this tree is
+# a demand nothing in the repo is allowed to satisfy.
+docs/history
 
 # Source catalogs — authored markdown; prettier collapses template/example blocks
 skills

package/data/harnesses/hr/harness.json

@@ -7,5 +7,5 @@
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
-  "digest": "b9e1f9989578"
+  "digest": "2cd2d7347c4f"
 }

package/data/harnesses/kb-agi/.prettierignore

@@ -8,8 +8,19 @@ pnpm-lock.yaml
 package-lock.json
 yarn.lock
 
-# Harness-managed agent/skill definitions (installed under .claude/)
+# Harness-managed — the installer overwrites all of these, so formatting them is churn
+# that comes straight back on the next `npx @nurix/etna`.
 .claude
+.codex
+.agents
+CLAUDE.md
+AGENTS.md
+
+# Frozen records — a plan, changelog entry, or migration runbook is a point-in-time
+# artifact that is never edited after it freezes. Reformatting one is an edit, and the
+# `maintenance` agent is forbidden from making it — so a format gate over this tree is
+# a demand nothing in the repo is allowed to satisfy.
+docs/history
 
 # Source catalogs — authored markdown; prettier collapses template/example blocks
 skills

package/data/harnesses/kb-agi/harness.json

@@ -7,5 +7,5 @@
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
-  "digest": "d2b1e92990e9"
+  "digest": "d0b9322bb685"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nurix/etna",
-    "version": "0.19.29",
+    "version": "0.19.31",
     "description": "Bootstrap a project with a Nurix harness — copies the harness's CLAUDE.md, skills, agents, rules, and hooks directly into the project from a bundled payload (no marketplace fetch, no network).",
     "type": "module",
     "bin": {