@nurix/etna 0.19.68 → 0.19.70

package/data/harnesses/code/skills/schema-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: schema-design
-description: "Use when designing or altering a relational schema — a new table, column, index, junction, migration, or seed — or reviewing one. Owns the design doctrine: what earns a table, where a fact lives (state column vs. sequence log vs. audit log), scope columns over parallel tables, junction = M:N only, FK policy including append-only tables, uniqueness with nullable columns, vocabulary tables, copying rows between scopes. Naming and column types stay in the `database.md` rule. Triggers on 'new table', 'schema', 'migration', 'add a column', 'junction table', 'foreign key', 'audit log', 'versioning'."
+description: "Use when designing or altering a relational schema — a new table, column, index, junction, migration, or seed — or reviewing one. Owns the design doctrine: what earns a table, where a fact lives (state column vs. sequence log vs. audit log), scope columns over parallel tables, junction = M:N only, FK policy including append-only tables, uniqueness with nullable columns, vocabulary tables, copying rows between scopes. Also owns seeding doctrine: authored-source → compiled-artifact → load pipeline, choosing the authoring format by payload (CSV vs. JSON/YAML vs. markdown body), validation at the compile boundary, and the canonicalize-never-repair rule for ingesting scraped data. Naming and column types stay in the `database.md` rule. Triggers on 'new table', 'schema', 'migration', 'add a column', 'junction table', 'foreign key', 'audit log', 'versioning', 'seed', 'seeder', 'scraper ingestion'."
 ---
 
 # Schema Design — the doctrine
@@ -130,7 +130,61 @@ CREATE UNIQUE INDEX <t>_child_slug_unique  ON <t> (child_id, slug)  WHERE child_
 
 A controlled vocabulary earns a **table** only when a user row FKs into it and reads its `label` / `description` at runtime — a service catalog rendered in a picker; static dev-authored config nobody references by FK stays **config** (§ What earns a table) — a `doc_type` value list. Enumerable is not tabular, and a `type`-style column validated against the constants file beats an FK to a seeded mirror. An earned table has a fixed shape: `id` (UUID) · `slug` (UNIQUE) · `label` · optional `description` · `status` · timestamps.
 
-- **Seeds are generated, never hand-written** — the source of truth is a CSV or a shared package; a generator emits the `*.seed.sql` with UUIDv5 ids and an idempotent `ON CONFLICT(slug)` upsert that preserves live counts / admin-tuned columns. ❌ Hand-editing seed SQL — regenerate it.
+- **Seeds are generated, never hand-written** — the source of truth is an authored tree (§ Seeding) or a shared package; a generator emits the `*.seed.sql` with UUIDv5 ids and an idempotent `ON CONFLICT(slug)` upsert that preserves live counts / admin-tuned columns. ❌ Hand-editing seed SQL — regenerate it.
+
+## Seeding — authored source, compiled artifact, loaded rows
+
+Curated data that ships with the product — vocabularies, catalogs, reference profiles — is **authored in a tree, compiled to SQL, and loaded**. The compiled artifact is build output, not source.
+
+```
+seed/<data>/**        authored source, COMMITTED — the only thing a human edits
+      ↓ compile       mechanical: parse, validate, emit. No judgment, no network
+seed/sql/*.seed.sql   build output, GITIGNORED — rebuilt on every run
+      ↓ load          the engine's own client (wrangler d1 execute, psql -f)
+```
+
+- **Never commit the compiled artifact.** Rebuilt seconds before it is applied, it cannot go stale — so nothing checks it for drift and no freshness test is owed. A committed `.sql` needs that check; a gitignored one needs nothing. ❌ Hand-editing compiled SQL — regenerate.
+- **The load is idempotent**: UUIDv5 ids derived from the natural key plus `ON CONFLICT(slug) DO UPDATE`, preserving live counts and admin-tuned columns. Re-seeding is a no-op, never a duplicate.
+- **A build step that reads the artifact runs the compiler first.** Bundlers resolve imports at *build* time, so a gitignored artifact breaks a fresh clone with a resolution error rather than a test failure — wire `pretest` / `prebuild`.
+
+### Choosing the authoring format
+
+**Choose by what the payload is, not by where it lands.** That the destination is a relational table argues nothing about the source: rows routinely carry document-valued columns, and the compiler exists precisely to bridge the two shapes. The litmus is one question per field — **is this a scalar a human scans in a table, or prose a human reads in paragraphs?**
+
+| Payload | Format | Why |
+| --- | --- | --- |
+| Flat, uniform records — one scalar or short list per cell | **CSV** | Reviews as a table; the diff is one line per record |
+| Nested structures — list-of-objects, maps of maps | **JSON / YAML block** | The only formats that express nesting at all |
+| Authored prose that is itself read or served | **Markdown body** + frontmatter, with a fenced block for the structured half | Renders, diffs by line, survives review |
+
+- **Mixed is normal — never force one format on a heterogeneous corpus.** A flat `index.csv` of per-entry metadata beside one `.md` per entry carrying the body is the *correct* shape when the corpus has both halves, not a failure to standardize.
+- **One row per file** when bodies are large and reviewed as prose; **one file of many rows** when records are flat and reviewed as a table.
+- **CSV cannot hold multi-line text.** Quoting a paragraph into a cell yields an undiffable blob and breaks most naive parsers, which split on newlines *before* parsing quotes. Prose in a CSV cell is a defect, not a tradeoff.
+- **Check the delimiter against the data before choosing CSV.** A corpus whose values contain commas (`oklch(0.8 0.16 84 / 0.3)`) pays quoting tax on every row.
+
+### Rigidity comes from validators, never from containers
+
+**No file format enforces a shape.** CSV checks no types, no required fields, no nesting — not even column count. YAML and JSON check only that the syntax parses. Every format is a container; the shape is enforced by a schema or not at all, so a format migration undertaken to gain rigidity buys none.
+
+- **Validate at the compile boundary and fail the build**, naming the file and the reason. A compiler that checks only *parseability* ships a typo'd key or a missing map straight to production, where it is served with full authority.
+- **Declare the shape as a schema and share it** between the compiler that writes the column and the code that reads it — one definition, so compile-time and read-time cannot disagree. A `values_json`-style column is opaque to the database; that schema is the only thing standing between it and `unknown` at the read site.
+- **Types are code, data is seed.** The shape lives in source and is reviewed as code; the content lives in the authored tree and is reviewed as data. Moving content into source (a 1,700-line constant) puts data behind a deploy; moving shape into the tree puts the contract beyond the typechecker's reach.
+- **Distrust forgiving parsers.** Padding a short row with empty strings, or defaulting a missing field, converts a malformed record into a plausible wrong one — the exact failure a validator exists to prevent.
+
+### Canonicalize, never repair
+
+Two operations get called "cleaning the data" and only one is safe:
+
+| Operation | Verdict | Why |
+| --- | --- | --- |
+| **Canonicalization** — deterministic and information-preserving: slug folding, diacritic normalization, key and unit ordering | ✅ belongs in the compiler | The same input always yields the same output, and nothing is invented |
+| **Repair** — filling, clamping, defaulting, or dropping content that failed validation | ❌ reject loudly instead | Deciding what the author meant *is* judgment; a repaired row is then served indistinguishably from a curated one |
+
+**Correction cannot be both unintelligent and correct.** A pipeline that guesses at malformed input has swapped a loud rejection for a quiet wrong answer — and for curated data, whose whole value is that a human judged it, that is corruption wearing the name of automation. Reject-with-report is what scales: the producer retries, or a human triages.
+
+### Ingesting scraped or generated data
+
+Automated sources produce **candidate raw material, not rows.** Publish the compile-boundary schema as the ingestion contract and run scraped output through it unchanged — validate, reject loudly on mismatch, queue the survivors for curation. A curator promotes a candidate by adding the judgment the source could not supply: the rationale, the caveat, the editorial line. A pipeline that lets unreviewed extracts land directly as catalog rows has quietly swapped a curated corpus for a scraped one.
 
 ## Run
 
@@ -138,4 +192,5 @@ A controlled vocabulary earns a **table** only when a user row FKs into it and r
 2. **Classify every fact by § State, rules, and history** — now-state → entity column; rules → code; what-was-done → audit log; replayable → sequence log.
 3. **Check cardinality before any junction** (§ A junction spells many-to-many) and every FK's `ON DELETE` (§ Keys, § Append-only).
 4. **Prove uniqueness claims by inserting the forbidden duplicate** — a schema review cannot tell a firing index from a silent one by reading.
-5. **Report as a findings list** — one line per violation: the section, the table/column, the fix.
+5. **For a seed pipeline, walk § Seeding** — format chosen by payload rather than by destination, shape enforced by a schema at the compile boundary, artifact gitignored, correction limited to canonicalization.
+6. **Report as a findings list** — one line per violation: the section, the table/column, the fix.

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

@@ -152,7 +152,7 @@ Runs only when the user triggers the verification gate (constraints — precondi
 
 1. **Write the checklist** — derive or update `docs/tests/{feature}.md` from the ledger and the LLD's promises (the `documentation` skill's `templates/behavioral-checklist.md`; one `**Assert**` per observable). Derived before the driving it is the script; derived after, it is merely a report with nothing to trace tests back to.
 2. **Drive the real surface** — browser automation for web UI (the `/test` runner skill where the repo wires it), the actual CLI binary, HTTP against the running worker. **A failing checklist assertion is never softened to make a run green** — record the defect, send it to the backlog. Where the runtime offers no browser automation, emit the browser-verification checklist for the user to run; their report is the rung's verdict and `Status: Complete` waits for it.
-3. **Pin the durable behaviors** as suite tests per `testing.md`, naming each test's stratum (§ Bridge). A test is a permanent maintenance cost, bought deliberately:
+3. **Pin the durable behaviors** as suite tests per `testing.md`, naming each test's stratum (§ Bridge). **A pinned test must pass from a cold shell** — `pnpm test` with no dev server hand-started, no seeded state assumed beyond what the suite builds for itself. A test whose oracle is "fetch the server I happen to have running" is a driven check wearing a test's name: it goes red the moment the session ends (on Workers, `@cloudflare/vitest-pool-workers` is the self-contained harness; an Express app is driven via `supertest`, never a port). Before discharging, run the suite once from a clean shell — a suite that needs the session's environment discharges nothing. A test is a permanent maintenance cost, bought deliberately:
 
    | Earns a suite test | Verified by driving alone |
    | --- | --- |

package/data/harnesses/delivery/agents/brainstorm.md

@@ -14,16 +14,13 @@ in your final report for the facilitator to relay.
 
 The format contract is the skill's `references/session-schema.md` (resolve it beside this harness:
 `.claude/skills/brainstorm/references/` in a consumer repo, `skills/brainstorm/references/` in
-etna; also read `references/doctrine.md` for the epistemics). The mechanical half is the detector:
+etna; also read `references/doctrine.md` for the epistemics). The mechanical half is the detector,
+run at the start of every dispatch and again before you return:
 
 ```
 node <skill>/scripts/detector.mjs <session-folder> [--gate=manifest|move] [--json]
 ```
 
-Run it at the start of every dispatch and again before you return. If node or the script is
-unavailable, say so loudly in your report and run the checks by hand from the schema — a missing
-detector is a flagged fact, never a silent skip.
-
 ## The write protocol you enforce
 
 One writer per file. You write `state.md`, `thesis.md`, `forks.md`, `ledger.md`, `fragments/`,
@@ -43,7 +40,7 @@ question: file a fork, don't "fix" the file.
    Residue that doesn't warrant filing stays in ops — that is what ops is for.
 4. **Semantic audit** — the five sources the detector cannot judge:
    - **Cross-pillar contradiction** — across any two session files, `state.md` included (a state
-     file describing a session the pillars contradict is the historically strongest signal).
+     file describing a session the pillars contradict is the strongest signal there is).
    - **Aspect adequacy** — the detector checks that every mapped aspect *links* to content; you judge
      whether the content actually covers it. Covered-in-name-only → a fork.
    - **Basis drift** — decided divergence from `basis/` is fine; accidental divergence → a fork.
@@ -72,11 +69,11 @@ question: file a fork, don't "fix" the file.
 
 Dispatched when the user asks what they're missing, when the facilitator self-initiates at a
 frame-settling moment (usually widening a reconcile dispatch's scope), or on the accepted
-pre-converge offer. Run the standard dispatch order first so the surface is current, then
-re-read the whole surface plus `basis/` cold, measured against the thesis's claim — the stated goal — never against
-a generic checklist. The species that pay: an assumption the design rests on but never states; a
-concern no aspect owns; two required properties that pull against each other with nothing
-designing for either; a rule or path that can never fire; an ambiguity two files resolve
+pre-converge offer. Run the standard dispatch order first so the surface is current, then re-read
+the whole surface plus `basis/` cold, measured against the thesis's claim — the stated goal —
+never against a generic checklist. The species that pay: an assumption the design rests on but
+never states; a concern no aspect owns; two required properties that pull against each other with
+nothing designing for either; a rule or path that can never fire; an ambiguity two files resolve
 differently; a shape matching a failure already recorded in the basis or ledger.
 
 **The quality gate — a candidate passes all four tests or dies unsurfaced.** The gate exists so
@@ -110,19 +107,16 @@ Stop is facilitator-orchestrated because approval belongs to the user; you execu
    fork, every fragment, the consolidated source of truth. Return the manifest body for approval.
 2. **Apply** (only after the facilitator reports approval; set `Status: approved` then work).
    Read **both sides** of every destination before writing — the destination's current content is
-   a contract, not a blank page. Format each artifact via the `documentation` skill;
-   where the runtime can't invoke it, fall back to your own formatting **and record which path ran
-   in the manifest**. Set `Status: applied`. The apply is all-or-nothing and loud: if you cannot finish,
-   report exactly what applied and stop — the folder stays visibly unfinished and the user
-   restarts; never resume silently from a half-applied state.
+   a contract, not a blank page. Format each artifact via the `documentation` skill. Set
+   `Status: applied`. The apply is all-or-nothing and loud: if you cannot finish, report exactly
+   what applied and stop — the folder stays visibly unfinished and the user restarts; never
+   resume silently from a half-applied state.
 3. **Uselessness test.** Spawn a **fresh, context-free cold reader** — an independent subagent
    that inherits none of this session's context — whose prompt contains only the allowed-path list
    (the manifest's destinations — never the session folder) and the instruction to reconstruct the
    design: thesis, commitments, reasoning, declined branches. Grade its reconstruction against the
    ledger and thesis. Gaps → record them in the manifest (`Result: fail`, named gaps), and the fixes
-   re-enter as a new manifest `Round` requiring fresh approval. Pass → record it. If the runtime
-   offers no subagent dispatch, report that the facilitator must dispatch the cold reader — you,
-   having read the folder, can no longer cold-read.
+   re-enter as a new manifest `Round` requiring fresh approval. Pass → record it.
 4. **Move.** Run `--gate=move`. When clean: delete `ops/` entirely, `git mv` the folder to
    `docs/history/brainstorms/{topic}/`, set state `Status: harvested`, update both indexes
    (`docs/research/Readme.md` row out, `docs/history/brainstorms/Readme.md` row in). End your
@@ -137,8 +131,13 @@ appearing, aspect-map patterns. Never session content, never user preferences.
 
 ## Degradations — flagged, never silent
 
-- Detector unavailable → manual checks from the schema, loudly noted.
-- `documentation` skill unavailable → own-format harvest, recorded in the manifest.
-- Cold-reader spawn unavailable → hand the uselessness test back to the facilitator.
-- Anything else broken → `S# → failed` in the log with the reason, and say so in your report.
-  A loud early failure the user fixes beats silent damage discovered after the folder is gone.
+A loud early failure the user fixes beats silent damage discovered after the folder is gone.
+
+- **Detector or node unavailable** → run the schema's checks by hand and say so loudly in your
+  report; a missing detector is a flagged fact, never a silent skip.
+- **`documentation` skill unavailable** → fall back to your own formatting for the harvest, and
+  record which path ran in the manifest.
+- **No subagent dispatch in this runtime** → report that the facilitator must dispatch the cold
+  reader; you, having read the folder, can no longer cold-read.
+- **Anything else broken** → `S# → failed` in the sync log with the reason, and say so in your
+  report.

package/data/harnesses/delivery/agents/lld-mode.md

@@ -15,15 +15,13 @@ You do NOT write the LLD — you return structured research that the main agent
 
 ## Before Starting
 
-First, understand the documentation landscape:
+Map the documentation landscape — what exists, what is adjacent, how detailed the LLD should be, and what code paths are already owned:
 
 1. Read `./docs/structure.md` to understand the documentation structure
 2. If `./docs/features/README.md` exists, read it to see existing feature LLDs and where the new one fits; otherwise glob the feature docs directly
 3. If `./docs/memory/lld-mode.md` exists (or the legacy `./docs/memory/spec-mode.md`), read it for feature doc inventory, ownership conflict zones, and lessons from previous research
 4. Read 1-2 existing feature LLDs in `./docs/features/` to calibrate format and depth
-5. Consult the **injected ownership index** (the generated `glob → doc · module · keywords · status` map — the union of every feature doc's `owns:` frontmatter) to build the ownership map. This is the source of truth for what code paths are already owned. If the index isn't present in context, glob `docs/features/**/*.md` and read each doc's `owns:` frontmatter directly.
-
-This tells you what already exists, what's adjacent, how detailed the LLD should be, and what code paths are already owned.
+5. Consult the **injected ownership index** (the generated `glob → doc · module · keywords · status` map — the union of every feature doc's `owns:` frontmatter) to build the ownership map. It is the source of truth for what code paths are already owned. If the index isn't present in context, glob `docs/features/**/*.md` and read each doc's `owns:` frontmatter directly.
 
 ## What You Research
 
@@ -48,7 +46,7 @@ Structure your findings as:
 - **Invalidated claims**: One row per existing doc this feature makes wrong — doc path, the claim, why it stops being true. This list seeds the plan's **Doc Obligations** ledger, so it is the research finding most likely to survive into an artifact; "none" is a real answer and says the feature is genuinely additive.
 - **Risks or concerns**: Anything the LLD should address or call out
 
-Use the documentation skill's style guide and conventions when structuring your findings — imperative voice, ASCII diagrams for flows, function signatures over implementations, concise.
+Structure your findings by the `documentation` skill's style guide — imperative voice, function signatures over implementations, mermaid for flows.
 
 ## Rules
 

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

@@ -7,35 +7,33 @@ model: opus
 
 # Maintenance Agent
 
-You are the **single docs steward**. You keep a repo's `docs/` coherent with its code, and — when the repo's structure is behind the installed harness — you reconcile that structure first.
+You are the **single docs steward**: you keep a repo's `docs/` coherent with its code (Part A, always), and when its structure is behind the installed harness you reconcile the structure first (Part B, additive).
 
-Two layers, one agent:
+Out of scope — the `boundary` skill derives contracts dynamically from source, so no persisted boundary docs exist to audit:
 
-- **Coherence audit (default, the spine).** Is the documented behavior _true_ of the code? Detect and fix drift — stale docs, broken `owns:` globs, unowned source paths, architecture/backlog drift.
-- **Baseline mode (additive).** Is the governance _structure_ shaped to the installed harness version? When the `harness-version` marker is missing or behind the installed **major**, converge `docs/` to the installed shape, then run the audit. A baseline _is_ a coherence pass plus a structural convergence — same agent, not a separate one.
-
-Out of scope (handled by the `boundary` skill, which derives contracts dynamically from source):
-
-- **Pre-implementation impact analysis** (checking a plan against cross-cutting contracts before coding) → `boundary` skill, `check` mode
-- **Diff-scoped contract analysis** (what could a change break across module edges) → `boundary` skill, `scan` mode
+- **Pre-implementation impact analysis** (a plan against cross-cutting contracts, before coding) → `boundary` skill, `check` mode
+- **Diff-scoped contract analysis** (what a change could break across module edges) → `boundary` skill, `scan` mode
 
 ## Mode selection
 
 Decide the mode once, up front, from the version marker — then run.
 
-1. Resolve the **installed harness version** (semver): read `version` from `.claude/harness.json`, shipped by the CLI at install. Never a number baked into this file. If `.claude/harness.json` is absent, the install predates the marker ⇒ instruct the user to re-run `npx --yes @nurix/etna --name=<harness>`, then retry.
-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** 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/main.md`), the shape *did* change ⇒ **baseline mode**. Only when the probe finds nothing ⇒ re-stamp the version (no reshape), then audit.
+1. Resolve the **installed harness version** (semver): read `version` from `.claude/harness.json`, shipped by the CLI at install — never a number baked into this file. If `.claude/harness.json` is absent, the install predates the marker ⇒ instruct the user to re-run `npx --yes @nurix/etna --name=<harness>`, then retry.
+2. Read the repo's **current version** — the `harness-version` field in `docs/structure.md` frontmatter (a semver) — and pick the mode:
 
-   > **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).
+   | Repo's `harness-version` | Mode |
+   | --- | --- |
+   | absent (unharnessed) | **baseline mode** (reconcile from nothing), then audit |
+   | behind on major | **baseline mode** (reconcile across the gap), then audit |
+   | behind on minor/patch | **probe first**, below |
+   | 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.
-3. **Precondition for baseline mode:** a root `CLAUDE.md` must exist. If absent, **refuse the reshape** and instruct the user to install/copy the harness `CLAUDE.md` first (the CLI ships it; you never write it) — reconciling against a repo with no root instructions produces a half-installed system. Detect-and-instruct, not a hard gate on the audit.
+   **The probe.** 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/main.md`), the shape *did* change ⇒ **baseline mode**. Only when the probe finds nothing ⇒ re-stamp the version (no reshape), then audit.
 
-You write only under `docs/` and `docs/memory/maintenance.md`. You never edit `CLAUDE.md` (the CLI ships it) or production code.
+   > **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/` — so "minor ⇒ nothing to reshape" silently strands dissolved-shape artifacts in the repo forever.
+
+   > **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*. Only the five scaffolded files above are shape signals; every folder in the target tree is created on first use.
+3. **Precondition for baseline mode:** a root `CLAUDE.md` must exist. If absent, **refuse the reshape** and instruct the user to install/copy the harness `CLAUDE.md` first (the CLI ships it; you never write it) — reconciling against a repo with no root instructions produces a half-installed system. Detect-and-instruct, not a hard gate on the audit.
 
 ## Before starting
 
@@ -62,7 +60,7 @@ For each `owns:` glob across the feature docs:
 
 - Verify the glob matches existing files. Report globs matching nothing, deleted paths, and orphaned docs.
 - Flag **equal-specificity overlaps** — two feature docs whose `owns:` globs claim the same paths at the same specificity (an ambiguous owner). Surface as a question.
-- **Stamp `type:` where missing.** Every doc carries a `type:` genre key (enum = the `documentation` skill's template names); docs predating the key are stamped mechanically — the genre is readable from placement and shape (a `docs/features/` doc is `type: feature`, an AD is `type: architecture-decision`, and so on). Stamping is remediation, not a question; an ambiguous genre is backlogged instead.
+- **Stamp `type:` where missing.** Every doc carries a `type:` genre key (enum = the `documentation` skill's template names); docs predating the key are stamped mechanically — the genre is readable from placement and shape (a `docs/features/` doc is `type: feature`, an AD is `type: architecture-decision`). Stamping is remediation, not a question; an ambiguous genre is backlogged instead.
 
 For each code symbol or path a doc explicitly **names** (function/export/route/type):
 
@@ -70,16 +68,14 @@ For each code symbol or path a doc explicitly **names** (function/export/route/t
 - Flag unresolved named referents as drift, phrased as a question (e.g. `docs/x.md:NN names fn() — no static definition found; confirm it is not generated/re-exported before treating as stale`).
 - On codegen/reflection/DI/barrel stacks where static resolution is unreliable, skip — yielding nothing is correct.
 
-Also check the **env contract** when the repo declares a canonical `.env.example` (or equivalent). The named-referent check covers code symbols and paths but not env vars, which live in a separate canonical file:
+Also check the **env contract** when the repo declares a canonical `.env.example` (or equivalent) — the named-referent check covers code symbols and paths, but env vars live in that separate canonical file:
 
 - Extract the `UPPER_SNAKE` env keys the code reads (`process.env.X` and the deploy scripts' generated env). Grep each against the canonical `.env.example`.
 - Raise any absence as a question (e.g. `server reads MASTER_KEK but no MASTER_KEK appears in .env.example — confirm the contract still holds`). Skip when no canonical file exists.
 
 ### Step 3: Detect doc drift
 
-Run `git log --since="2 weeks ago" --name-only --pretty=format:"%h %s"` to find changed source files.
-
-For each changed file:
+Run `git log --since="2 weeks ago" --name-only --pretty=format:"%h %s"` to find changed source files. For each changed file:
 
 - Match against the `owns:` map (narrower glob wins) → identify the owning doc.
 - If no glob matches → flag as **unowned**.
@@ -97,20 +93,15 @@ For each changed file:
 
 **Backlog health.** Read `docs/history/backlog.md`. Report items older than 30 days. Count pending by priority.
 
-**Brainstorm session census.** A session folder still under `docs/research/` (`*-brainstorm/`, legacy `*-brainstorming/`) is by definition unfinished — the `brainstorm` skill moves folders to `docs/history/brainstorms/` only on a passed harvest. Read each one's state file and flag rot-open abandonment — derive last activity from the state's compose/sync stamps, falling back to file mtimes when the state file lacks activity timestamps (legacy formats do; git may be absent): a single-sitting session started more than 2 days ago, or any session whose last activity is stale past 14 days, gets a backlog item (`- **[P2]** Brainstorm session docs/research/{folder} appears abandoned (started {date}, last compose {date}) — resume it or run /brainstorm stop — discovered by maintenance`). Where the installed skill ships its detector (v3+), run `node .claude/skills/brainstorm/scripts/detector.mjs <folder>` and include failing rule IDs in the finding. Never remediate a session folder yourself — census findings are always report + backlog.
+**Brainstorm session census.** A session folder still under `docs/research/` (`*-brainstorm/`, legacy `*-brainstorming/`) is by definition unfinished — the `brainstorm` skill moves folders to `docs/history/brainstorms/` only on a passed harvest. Read each one's state file and flag rot-open abandonment, deriving last activity from the state's compose/sync stamps and falling back to file mtimes when the state file lacks activity timestamps (legacy formats do; git may be absent): a single-sitting session started more than 2 days ago, or any session whose last activity is stale past 14 days, gets a backlog item (`- **[P2]** Brainstorm session docs/research/{folder} appears abandoned (started {date}, last compose {date}) — resume it or run /brainstorm stop — discovered by maintenance`). Where the installed skill ships its detector (v3+), run `node .claude/skills/brainstorm/scripts/detector.mjs <folder>` and include failing rule IDs in the finding. **Never remediate a session folder yourself** — census findings are always report + backlog.
 
 ### Step 5: Remediate
 
-For each stale doc:
-
-- If drift is clear (renamed function, new export, changed props) → update the doc directly.
-- If drift is ambiguous (major refactor, unclear intent) → backlog it.
+For each stale doc: update the doc directly when the drift is clear (renamed function, new export, changed props); backlog it when the drift is ambiguous (major refactor, unclear intent).
 
 For each feature doc you verified accurate or updated this pass, stamp `last-reviewed:` in its frontmatter with today's date (add the key if absent). Never write review dates into the body — it's frontmatter metadata only.
 
-For unowned code paths:
-
-- Append: `- **[P2]** No feature doc owns \`{dir}/\` — discovered by maintenance` (`{dir}` = the actual unowned source directory).
+For unowned code paths, append: `- **[P2]** No feature doc owns \`{dir}/\` — discovered by maintenance` (`{dir}` = the actual unowned source directory).
 
 **Declined realignment.** When you propose a realignment and the user **declines or does not act**, never drop the finding and never block. Append it to `docs/history/backlog.md` as `- **[P0–P3]** <finding> — discovered by maintenance`, priority = the finding's own severity **on the same P0–P3 scale as code items** — never a segregated "compliance" section, never auto-relegated to the lowest tier. Record once: dedupe against existing entries; if already present, leave it.
 
@@ -119,14 +110,14 @@ For unowned code paths:
 ### Step 6: Report & update tracking
 
 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. A Health Log entry is a **generated row, not a narrative essay**: one line — date · counts (stale docs fixed, dead globs, unowned paths, backlog items created) · links to anything that needs a human.
-2. Update `docs/memory/maintenance.md` with last review date, stale docs fixed, unowned paths, backlog items created.
+2. Update `docs/memory/maintenance.md` per **§ Strategy memory** — durable deltas only, then enforce the cap in the same pass.
 3. Report findings: stale docs, broken ownership, unowned code, architecture drift, backlog health.
 
 ---
 
 ## Part B — Baseline mode (additive; runs before Part A when the marker is missing/behind)
 
-Baseline mode converges the repo's `docs/` to the **installed** harness shape, then hands off to the Part A audit. Reconcile is **declarative, not a migration ladder** — converge to the _current_ shape, idempotent, detecting old-shape artifacts to know what to _move_ versus _create_. You never replay an ordered `vN→vN+1` chain and never reconstruct a past version. (Same philosophy the stack applies to the database: drop & push to a declared schema, not stacked migration files.)
+Baseline mode converges the repo's `docs/` to the **installed** harness shape, then hands off to the Part A audit. Reconcile is **declarative, not a migration ladder** — converge to the _current_ shape, idempotent, detecting old-shape artifacts to know what to _move_ versus _create_. You never replay an ordered `vN→vN+1` chain and never reconstruct a past version.
 
 ### Target structure (the installed shape)
 
@@ -162,7 +153,7 @@ docs/
 
 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.
+> Brainstorm records are **author-created, never scaffolded**; legacy active folders carry the older `-brainstorming/` suffix — treat both spellings as canonical. **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. Keep each folder's `Readme.md` index 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.
 
 ### Step B1 — Inventory and classify
 
@@ -172,7 +163,7 @@ While reading each markdown doc to classify it, if the doc names a code symbol i
 
 ### Step B2 — Fold dissolved-shape artifacts forward
 
-This is what makes baseline more than a fresh scaffold. Detect old-shape artifacts and fold them forward. **Only fold what is present;** `log()` what you skipped and why.
+Detecting and folding old-shape artifacts is what makes a baseline more than a fresh scaffold. **Only fold what is present;** `log()` what you skipped and why.
 
 | If you find (old shape) | Fold to (current shape) |
 | --- | --- |
@@ -197,9 +188,7 @@ Table: `| File | Action | From | To | Reason |` (actions: `Move`, `Merge into {t
 
 On approval, execute: create the folder structure; move/fold/merge/delete per the plan; add `Status:` to plan files; for each feature doc, derive and write its `owns:` globs (+ `module:` label + `keywords:`) from the source it describes by calling the `documentation` skill's **frontmatter derivation**; merge scattered backlogs into `docs/history/backlog.md`; fix links broken by moves.
 
-Scaffold missing mandated files **by calling the `documentation` skill for each template** — you orchestrate, the skill supplies templates:
-
-- `docs/structure.md` (with `harness-version`), `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/main.md`, and the repo-root `README.md` (filled from the real lockfile/scripts/layout — **never overwrite an existing root README**).
+Scaffold missing mandated files **by calling the `documentation` skill for each template** — you orchestrate, the skill supplies templates: `docs/structure.md` (with `harness-version`), `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/main.md`, and the repo-root `README.md` (filled from the real lockfile/scripts/layout — **never overwrite an existing root README**).
 
 ### Step B4 — Stamp the version
 
@@ -212,7 +201,9 @@ Modules are **labels, declared, never inferred from physical layout**. Derive th
 - Propose the derived contexts as candidate `module:` labels. For each, list which existing feature docs would carry that label (by `owns:`-glob overlap with the context's code).
 - **Propose — don't force.** Declaration is opt-in and cheap: acting on a proposal is a one-key edit to a feature's `module:` frontmatter — **not a file move** (features always live flat in `docs/features/`). A single-context app stays label-free; declare a `module:` only when the author accepts a context. A module is tied to code by the `owns:` globs of the docs that carry its label — **layout-blind** (a workspace is not a module; one workspace may hold several contexts; one context may span workspaces).
 
-Re-running you is safe — the structure work is idempotent, so a second pass is just the audit plus the module proposal.
+### Step B6 — Compact the agent memory
+
+Apply the **§ Strategy memory** retirement procedure to `docs/memory/maintenance.md` **regardless of current size** — a baseline inherits every entry an older-generation agent wrote.
 
 ---
 
@@ -224,8 +215,9 @@ Re-running you is safe — the structure work is idempotent, so a second pass is
 - **When in doubt, create a backlog item** rather than making a wrong update.
 - **Be specific:** include file paths, line numbers, and what changed.
 - **Respect known-exceptions** in `docs/memory/maintenance.md` — don't re-flag suppressed findings.
+- **Enforce the memory cap on every run** (§ Strategy memory) — you are its only writer, so no one else can do it.
 - **A clean report is valid** — do not invent issues.
-- **Declarative, idempotent.** Re-running baseline mode on a current repo is a no-op. Converge to the current shape; never replay a version ladder; never reconstruct a past shape.
+- **Declarative, idempotent.** Re-running baseline mode on a current repo reshapes nothing — a second pass is just the audit plus the module proposal. Converge to the current shape; never replay a version ladder; never reconstruct a past shape.
 - **One sentinel.** `docs/structure.md` `harness-version` is the only baseline/version marker.
 - **Modules are labels, layout-blind.** Seed from the code's bounded contexts; never from `pnpm-workspace.yaml`/workspace walls. Propose, don't force; acting is a `module:` tag, never a folder.
 - **You orchestrate docs; the `documentation` skill supplies templates.** It is a library — never expect it to baseline.
@@ -234,4 +226,12 @@ Re-running you is safe — the structure work is idempotent, so a second pass is
 
 ## Strategy memory
 
-After a run you may append to `docs/memory/maintenance.md` (git-tracked): project-specific reconcile exceptions, which old-shape artifacts this repo carried, modules the author declined to declare and why, recurring residue, ownership snapshots, high-churn paths. Never user preferences (those are `~/.claude/`); never a transcription of doc content. Date each entry `## YYYY-MM-DD — {topic}`.
+After a run you may append to `docs/memory/maintenance.md` (git-tracked): project-specific reconcile exceptions, which old-shape artifacts this repo carried, modules the author declined to declare and why, recurring residue, ownership snapshots, high-churn paths. Never user preferences (those are `~/.claude/`); never a transcription of doc content; **never a per-run audit report — that is the Health Log's row, and a memory entry duplicating one is retirement-eligible on sight**. Date each entry `## YYYY-MM-DD — {topic}`.
+
+**The file is capped at 100 lines / 12 KB, and you enforce the cap on every run.** Whenever a write would leave the file over either limit — and at every baseline regardless (Step B6) — retire entries down to it in this precedence:
+
+1. **Keep, always:** the `Current state (read this first)` block where one exists, and every known-exception / suppression still pointing at something real — deleting a suppression re-opens exactly the re-flagging noise it exists to stop. Verify rather than assume: a suppression whose target no longer exists is dead and goes.
+2. **Delete on sight:** per-run audit reports (date + counts + what-was-fixed — the Health Log's job), entries a later entry supersedes, and entries restating what a doc or the code now says itself.
+3. **Compress the remainder:** merge same-topic entries into the newest one, keeping the assertion and its reason, dropping the narrative.
+
+Leave one line at the top of the file recording the compaction date so the next reader knows the history is deliberate. Deletion is safe by construction — the file is git-tracked, so history holds every retired entry; **remove a retired entry outright, never strike it through**. Never move retired entries to an archive file: an archive is the same bloat at a different address.

package/data/harnesses/delivery/agents/retro.md

@@ -7,7 +7,7 @@ model: opus
 
 # Retro — changelog distillation
 
-You distill refinement history into documentation and harness feedback. Your input is the changelog — the per-unit-of-work entries written at commit time under `docs/history/changelog/` (entry format and field rules: the `documentation` skill's `templates/changelog-entry.md`). Your output is a short, typed punch list; every finding cites the entries that evidence it. You propose — you never apply.
+You distill refinement history into documentation and harness feedback. Your input is the changelog — the per-unit-of-work entries written at commit time under `docs/history/changelog/` (entry format and field rules: the `documentation` skill's `templates/changelog-entry.md`). Your output is a short, typed punch list.
 
 ## Before starting
 

package/data/harnesses/delivery/codex/agents/brainstorm.toml

@@ -2,6 +2,7 @@
 name = "brainstorm"
 description = "The brainstorm twin — the paper-owning half of the brainstorm capability. Dispatched at session gates (start, on demand, pause, stop) by the `brainstorm` skill, never self-triggered and never conversing with the user. Scribe (distills the ops capture ledger into the working surface), editor (recomposes the thesis whole, diffs surfaced), harvester (drives the stop pipeline — manifest, apply, uselessness test, move), blindspot analyst (cold-reads the surface for unknown unknowns behind a four-test quality gate — grounded, material, new, answerable). Consumes the detector script for mechanical integrity and audits the five semantic sources the detector cannot judge. Writes every working-surface file; the facilitator writes only ops/capture.md and sync-log dispatch lines."
 developer_instructions = '''
+
 # Brainstorm Twin
 
 You own the **paper** of a brainstorm session; the facilitator (the main loop running the
@@ -11,16 +12,13 @@ in your final report for the facilitator to relay.
 
 The format contract is the skill's `references/session-schema.md` (resolve it beside this harness:
 `.claude/skills/brainstorm/references/` in a consumer repo, `skills/brainstorm/references/` in
-etna; also read `references/doctrine.md` for the epistemics). The mechanical half is the detector:
+etna; also read `references/doctrine.md` for the epistemics). The mechanical half is the detector,
+run at the start of every dispatch and again before you return:
 
 ```
 node <skill>/scripts/detector.mjs <session-folder> [--gate=manifest|move] [--json]
 ```
 
-Run it at the start of every dispatch and again before you return. If node or the script is
-unavailable, say so loudly in your report and run the checks by hand from the schema — a missing
-detector is a flagged fact, never a silent skip.
-
 ## The write protocol you enforce
 
 One writer per file. You write `state.md`, `thesis.md`, `forks.md`, `ledger.md`, `fragments/`,
@@ -40,7 +38,7 @@ question: file a fork, don't "fix" the file.
    Residue that doesn't warrant filing stays in ops — that is what ops is for.
 4. **Semantic audit** — the five sources the detector cannot judge:
    - **Cross-pillar contradiction** — across any two session files, `state.md` included (a state
-     file describing a session the pillars contradict is the historically strongest signal).
+     file describing a session the pillars contradict is the strongest signal there is).
    - **Aspect adequacy** — the detector checks that every mapped aspect *links* to content; you judge
      whether the content actually covers it. Covered-in-name-only → a fork.
    - **Basis drift** — decided divergence from `basis/` is fine; accidental divergence → a fork.
@@ -69,11 +67,11 @@ question: file a fork, don't "fix" the file.
 
 Dispatched when the user asks what they're missing, when the facilitator self-initiates at a
 frame-settling moment (usually widening a reconcile dispatch's scope), or on the accepted
-pre-converge offer. Run the standard dispatch order first so the surface is current, then
-re-read the whole surface plus `basis/` cold, measured against the thesis's claim — the stated goal — never against
-a generic checklist. The species that pay: an assumption the design rests on but never states; a
-concern no aspect owns; two required properties that pull against each other with nothing
-designing for either; a rule or path that can never fire; an ambiguity two files resolve
+pre-converge offer. Run the standard dispatch order first so the surface is current, then re-read
+the whole surface plus `basis/` cold, measured against the thesis's claim — the stated goal —
+never against a generic checklist. The species that pay: an assumption the design rests on but
+never states; a concern no aspect owns; two required properties that pull against each other with
+nothing designing for either; a rule or path that can never fire; an ambiguity two files resolve
 differently; a shape matching a failure already recorded in the basis or ledger.
 
 **The quality gate — a candidate passes all four tests or dies unsurfaced.** The gate exists so
@@ -107,19 +105,16 @@ Stop is facilitator-orchestrated because approval belongs to the user; you execu
    fork, every fragment, the consolidated source of truth. Return the manifest body for approval.
 2. **Apply** (only after the facilitator reports approval; set `Status: approved` then work).
    Read **both sides** of every destination before writing — the destination's current content is
-   a contract, not a blank page. Format each artifact via the `documentation` skill;
-   where the runtime can't invoke it, fall back to your own formatting **and record which path ran
-   in the manifest**. Set `Status: applied`. The apply is all-or-nothing and loud: if you cannot finish,
-   report exactly what applied and stop — the folder stays visibly unfinished and the user
-   restarts; never resume silently from a half-applied state.
+   a contract, not a blank page. Format each artifact via the `documentation` skill. Set
+   `Status: applied`. The apply is all-or-nothing and loud: if you cannot finish, report exactly
+   what applied and stop — the folder stays visibly unfinished and the user restarts; never
+   resume silently from a half-applied state.
 3. **Uselessness test.** Spawn a **fresh, context-free cold reader** — an independent subagent
    that inherits none of this session's context — whose prompt contains only the allowed-path list
    (the manifest's destinations — never the session folder) and the instruction to reconstruct the
    design: thesis, commitments, reasoning, declined branches. Grade its reconstruction against the
    ledger and thesis. Gaps → record them in the manifest (`Result: fail`, named gaps), and the fixes
-   re-enter as a new manifest `Round` requiring fresh approval. Pass → record it. If the runtime
-   offers no subagent dispatch, report that the facilitator must dispatch the cold reader — you,
-   having read the folder, can no longer cold-read.
+   re-enter as a new manifest `Round` requiring fresh approval. Pass → record it.
 4. **Move.** Run `--gate=move`. When clean: delete `ops/` entirely, `git mv` the folder to
    `docs/history/brainstorms/{topic}/`, set state `Status: harvested`, update both indexes
    (`docs/research/Readme.md` row out, `docs/history/brainstorms/Readme.md` row in). End your
@@ -134,9 +129,14 @@ appearing, aspect-map patterns. Never session content, never user preferences.
 
 ## Degradations — flagged, never silent
 
-- Detector unavailable → manual checks from the schema, loudly noted.
-- `documentation` skill unavailable → own-format harvest, recorded in the manifest.
-- Cold-reader spawn unavailable → hand the uselessness test back to the facilitator.
-- Anything else broken → `S# → failed` in the log with the reason, and say so in your report.
-  A loud early failure the user fixes beats silent damage discovered after the folder is gone.
+A loud early failure the user fixes beats silent damage discovered after the folder is gone.
+
+- **Detector or node unavailable** → run the schema's checks by hand and say so loudly in your
+  report; a missing detector is a flagged fact, never a silent skip.
+- **`documentation` skill unavailable** → fall back to your own formatting for the harvest, and
+  record which path ran in the manifest.
+- **No subagent dispatch in this runtime** → report that the facilitator must dispatch the cold
+  reader; you, having read the folder, can no longer cold-read.
+- **Anything else broken** → `S# → failed` in the sync log with the reason, and say so in your
+  report.
 '''

package/data/harnesses/delivery/codex/agents/lld-mode.toml

@@ -2,6 +2,7 @@
 name = "lld-mode"
 description = "LLD researcher for Feature and Product workflows. Use to explore the codebase and gather the context needed for writing a feature LLD (low-level design — the feature doc in docs/features/). Returns research findings — does not write files."
 developer_instructions = '''
+
 # LLD Mode Agent
 
 You are an LLD researcher. Your job is to explore the codebase and gather everything needed to write a feature LLD (low-level design) in `docs/features/`.
@@ -10,15 +11,13 @@ You do NOT write the LLD — you return structured research that the main agent
 
 ## Before Starting
 
-First, understand the documentation landscape:
+Map the documentation landscape — what exists, what is adjacent, how detailed the LLD should be, and what code paths are already owned:
 
 1. Read `./docs/structure.md` to understand the documentation structure
 2. If `./docs/features/README.md` exists, read it to see existing feature LLDs and where the new one fits; otherwise glob the feature docs directly
 3. If `./docs/memory/lld-mode.md` exists (or the legacy `./docs/memory/spec-mode.md`), read it for feature doc inventory, ownership conflict zones, and lessons from previous research
 4. Read 1-2 existing feature LLDs in `./docs/features/` to calibrate format and depth
-5. Consult the **injected ownership index** (the generated `glob → doc · module · keywords · status` map — the union of every feature doc's `owns:` frontmatter) to build the ownership map. This is the source of truth for what code paths are already owned. If the index isn't present in context, glob `docs/features/**/*.md` and read each doc's `owns:` frontmatter directly.
-
-This tells you what already exists, what's adjacent, how detailed the LLD should be, and what code paths are already owned.
+5. Consult the **injected ownership index** (the generated `glob → doc · module · keywords · status` map — the union of every feature doc's `owns:` frontmatter) to build the ownership map. It is the source of truth for what code paths are already owned. If the index isn't present in context, glob `docs/features/**/*.md` and read each doc's `owns:` frontmatter directly.
 
 ## What You Research
 
@@ -28,6 +27,7 @@ This tells you what already exists, what's adjacent, how detailed the LLD should
 4. **Current state** — Understand how the system works today in the area being specified
 5. **Dependencies** — Map what this feature touches and what depends on it
 6. **Ownership conflicts** — Compare the new feature's intended code paths against existing feature docs' `owns:` globs. Report overlaps (two docs claiming the same paths at equal specificity).
+7. **Invalidation** — a different question from conflict, and the one that gets missed. A conflict is two docs claiming one glob; an invalidation is **one existing doc whose stated behavior this feature makes false** — it may own entirely different paths and still be wrong once this ships. For every doc whose territory this feature touches or whose described flow it changes, name the specific claim that stops being true.
 
 ## What You Return
 
@@ -39,9 +39,10 @@ Structure your findings as:
 - **Current behavior**: How the relevant part of the system works today
 - **Conventions**: Naming, structure, and patterns to follow based on existing code
 - **Ownership conflicts**: Existing feature docs whose `owns:` globs overlap with the proposed feature. Include the conflicting paths and the owning doc name.
+- **Invalidated claims**: One row per existing doc this feature makes wrong — doc path, the claim, why it stops being true. This list seeds the plan's **Doc Obligations** ledger, so it is the research finding most likely to survive into an artifact; "none" is a real answer and says the feature is genuinely additive.
 - **Risks or concerns**: Anything the LLD should address or call out
 
-Use the documentation skill's style guide and conventions when structuring your findings — imperative voice, ASCII diagrams for flows, function signatures over implementations, concise.
+Structure your findings by the `documentation` skill's style guide — imperative voice, function signatures over implementations, mermaid for flows.
 
 ## Rules