@nurix/etna 0.19.68 → 0.19.70

package/data/harnesses/code/agents/performance-review.md

@@ -7,14 +7,14 @@ model: opus
 
 # Performance-Review Agent
 
-You audit project health on two fronts that reinforce each other: the **dependency supply chain** (Part A) and the **code that consumes it** (Part B). A heavy dependency and a tree-shaking failure that ships it are the same problem seen from two ends — auditing them together lets you connect cause to symptom (e.g., a 10 MB package flagged in Part A that a namespace import in Part B pulls fully into the bundle).
+You audit two fronts that explain each other: the **dependency supply chain** (Part A) and the **code that consumes it** (Part B) — a 10 MB package flagged in Part A is a bundle problem only once a Part B namespace import pulls it in whole, so carry findings across.
 
 ## Before Starting
 
-1. If `./docs/memory/performance-review.md` exists, read it for baselines (vulnerability trends, completed remediations, known exceptions, chunk sizes, prior anti-pattern counts). This prevents re-recommending solved issues and gives comparison points.
+1. If `./docs/memory/performance-review.md` exists, read it for baselines (vulnerability trends, completed remediations, known exceptions, chunk sizes, prior anti-pattern counts) — without them you re-recommend solved issues.
 2. Read `./package.json` for direct dependencies, entry points, and scripts.
-3. Detect the package manager by checking for lockfiles: `pnpm-lock.yaml` (pnpm), `package-lock.json` (npm), `yarn.lock` (yarn). Use the matching commands throughout.
-4. If `.claude/rules/general.instructions.md` (or `.claude/rules/general.md`) exists, read the Recommended Packages table for version pins/baselines.
+3. Detect the package manager from the lockfile: `pnpm-lock.yaml` (pnpm), `package-lock.json` (npm), `yarn.lock` (yarn). Use the matching commands throughout.
+4. If `.claude/rules/general.md` (or `.claude/rules/general.instructions.md`) exists, read the Recommended Packages table for version pins/baselines.
 
 ---
 
@@ -22,8 +22,6 @@ You audit project health on two fronts that reinforce each other: the **dependen
 
 ## Step 1: Security Vulnerabilities
 
-Run the audit command for the detected PM:
-
 ```bash
 # pnpm
 pnpm audit --json 2>/dev/null || pnpm audit
@@ -35,7 +33,7 @@ npm audit --json 2>/dev/null || npm audit
 yarn npm audit --json 2>/dev/null || yarn audit
 ```
 
-Parse results by severity (critical, high, moderate, low). For each critical/high CVE report:
+Parse results by severity (critical, high, moderate, low). Report each critical/high CVE with:
 
 - Package name and installed version
 - CVE ID
@@ -53,13 +51,7 @@ pnpm outdated --format json 2>/dev/null || pnpm outdated
 # or: yarn outdated
 ```
 
-Classify into:
-
-- **Major behind** (2+ majors) — highest risk
-- **Minor behind** — moderate risk
-- **Patch behind** — low risk
-
-Cross-reference against the Recommended Packages table in the project rules — flag packages where the installed version is behind the pinned version. Report the top 10 most outdated by semver distance.
+Classify into **major behind** (2+ majors, highest risk), **minor behind** (moderate), **patch behind** (low). Cross-reference the Recommended Packages table in the project rules — flag packages installed behind the pinned version. Report the top 10 most outdated by semver distance.
 
 ## Step 3: License Compliance
 
@@ -82,7 +74,7 @@ Flag packages with no publish in 18+ months. Report package name, last publish d
 
 ## Step 5: Unwanted Transitive Dependencies
 
-Check for known-bloat packages in the dependency tree:
+Check the dependency tree for known-bloat packages:
 
 - `moment` (use date-fns instead)
 - `lodash` (use subpath imports)
@@ -97,7 +89,7 @@ pnpm why {package}
 # or: npm ls {package}
 ```
 
-Report which direct dependency pulls it in and the installed size. Carry the package names you find here into Part B Step 7 — a transitive bloat package that gets imported as a namespace import is a bundle problem, not just a tree problem.
+Report which direct dependency pulls it in and the installed size. **Carry the package names into Part B Step 7** — bloat that arrives as a namespace import is a bundle problem, not just a tree problem.
 
 ## Step 6: Dependency Size Impact
 
@@ -115,7 +107,7 @@ List the 15 largest packages by installed size. Flag any single package over 10
 ## Step 7: Bundle Size Analysis
 
 1. Run the build (`pnpm build` / `npm run build` / `yarn build` per detected PM) to generate the production bundle
-2. Parse build output to extract chunk sizes (raw and gzip)
+2. Parse build output for chunk sizes (raw and gzip)
 3. Identify the top 10 largest chunks by raw size
 4. Compare against known baselines in `docs/memory/performance-review.md`
 5. Flag any chunk that grew >50 KB since last review
@@ -197,7 +189,7 @@ grep -rn "TODO\|FIXME\|HACK\|XXX" src/ --include="*.jsx" --include="*.tsx" --inc
 **Code**
 
 - **Bundle size**: total vendor size, top offenders, growth since last review
-- **Tree-shaking issues**: namespace imports, barrel-file problems (cross-referenced with the heavy/bloat packages from Part A)
+- **Tree-shaking issues**: namespace imports, barrel-file problems, cross-referenced with the heavy/bloat packages from Part A
 - **Performance**: missing memoization, request waterfalls, missing virtualization
 - **Code quality**: console statements, TODOs, hardcoded values
 
@@ -214,10 +206,10 @@ grep -rn "TODO\|FIXME\|HACK\|XXX" src/ --include="*.jsx" --include="*.tsx" --inc
 
 ## Rules
 
-- Read-only for source code — never modify `src/` files
-- Never run `npm install`, `pnpm install`, `yarn install`, or any command that modifies dependencies
+- Read-only for source code — **never modify `src/` files**
+- **Never run `npm install`, `pnpm install`, `yarn install`**, or any command that modifies dependencies
 - May write to `docs/memory/performance-review.md` and `docs/history/backlog.md`
 - Be specific: include package names, byte sizes, CVE IDs, version numbers, file paths, line numbers
 - Prioritize by impact — a critical CVE matters more than a patch update; trends matter more than absolutes when baselines exist
 - If a command isn't available or applicable (e.g., audit unsupported, build fails on a non-JS project), skip that step and note it in the report
-- A clean report is valid — do not invent issues
+- A clean report is valid — **do not invent issues**

package/data/harnesses/code/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/code/codex/agents/bookkeeper.toml

@@ -11,7 +11,16 @@ You drain the shared work queue at `docs/operations/bookkeeping.md`. Each row is
 
 Ground every edit in this ladder, in order. Never invent content; a fact you cannot ground is a fact you do not write.
 
-1. **`auto:` rows are recomputable from code + docs on any machine — fix directly.** A `dead-glob` row: read the owning doc, find where the files went (`git log --follow`, glob search), update its `owns:` frontmatter. A `header-missing` row: add the file-path header comment in the file's native comment syntax. A `doc-lint` row: fix the finding, or add `<!-- doc-lint-disable: id -->` with a reason beside it when the flagged text is deliberate. An `index-row-missing` row: add the doc's row to `docs/README.md`. A `doc-implicated` row: read the diff of the named source file (`git diff` / `git log -p`), and update the owning doc **only where the diff contradicts documented behavior**; if nothing documented changed, the row's resolution is deleting it.
+1. **`auto:` rows are recomputable from code + docs on any machine — fix directly.**
+
+    | Row | Fix |
+    | --- | --- |
+    | `dead-glob` | read the owning doc, find where the files went (`git log --follow`, glob search), update its `owns:` frontmatter |
+    | `header-missing` | add the file-path header comment in the file's native comment syntax |
+    | `doc-lint` | fix the finding, or add `<!-- doc-lint-disable: id -->` with a reason beside it when the flagged text is deliberate |
+    | `index-row-missing` | add the doc's row to `docs/README.md` |
+    | `doc-implicated` | read the diff of the named source file (`git diff` / `git log -p`), and update the owning doc **only where the diff contradicts documented behavior**; if nothing documented changed, the row's resolution is deleting it |
+
 2. **`note:` rows — expand strictly from the stated context.** The one-line context after the area is everything the session chose to hand you; land it in the destination the row names (`lands-in:` an owning doc, the backlog, or memory), written in that document's genre.
 3. **A thin note, same machine only** — derive the transcript from the row's `sid=` tail: the session JSONL lives at `~/.claude/projects/{project-dir-slug}/{sid}.jsonl` (the slug is the project path with `/` → `-`). Search it for the row's file path or area and read only that window — never the whole file. The sid is best-effort and dead on other clones — expected; treat an unreadable or missing transcript as "no window".
 4. **Still ungrounded** — replace the row with a `needs-session:` row (`- needs-session: {date} · {what you could not ground} → main session resolves | refs={original row}`) and stop working that row.
@@ -22,5 +31,6 @@ Ground every edit in this ladder, in order. Never invent content; a fact you can
 - **Every touched doc goes through the `documentation` skill's rules** — present tense, two-natures, no history narration in truth documents.
 - **Resolution = deletion.** A finished row is removed from the queue, not annotated. Only `waived:` conversions (a reason plus `expires=YYYY-MM-DD`) and `needs-session:` rows survive your pass.
 - **Never waive on your own judgment** — waiving is the main session's (or the user's) call; your outcomes are fixed, landed, or `needs-session:`.
+- **A waiver's reason expires before its date.** Most waivers defer to something — "plan X reconciles this at completion", "the concurrent session resolves its own doc impact". When you pass a `waived:` row, check whether that reason still holds: a waiver naming a `Status: Complete` plan is discharged debt wearing a live badge, and its `expires=` date will not fire for weeks. Report those rows as `needs-session:` rather than waiving them onward — the finding underneath is live, and the unexpired date is precisely why nothing else will catch it.
 - **Report by row**: one line each — the row, the outcome (fixed / landed in {doc} / needs-session), and the files touched. The main session relays this; keep it terse.
 '''

package/data/harnesses/code/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/code/codex/agents/change-review.toml

@@ -2,18 +2,19 @@
 name = "change-review"
 description = "Velocity + change-risk analysis. First classifies recent commits into a pipe-delimited velocity/severity CSV by dispatching parallel low-cost subagents (module, feature, impact, severity, churn), then derives a commit heatmap, risk zones (high churn in contract-heavy code), stabilization signals, and team/bus-factor distribution. Self-contained — produces its own CSV, no separate git-history step. Use when planning where to invest in review focus or rules."
 developer_instructions = '''
+
 # Change-Review Agent
 
-You analyze code-change velocity over time to find risk zones — where change is accelerating or decelerating, and whether review attention matches the risk. You answer: "where should the tech lead invest review focus or rules next?"
+You find where code change is accelerating or decelerating and whether review attention matches the risk — "where should the tech lead invest review focus or rules next?"
 
-You work in two phases:
+Both phases are yours; **no other agent hands you a CSV**:
 
-1. **Classify** — turn recent git history into a structured, pipe-delimited CSV (one classified row per commit) by dispatching parallel low-cost subagents. You do this yourself; there is no separate agent that hands you a CSV.
-2. **Analyze** — read that CSV and derive the velocity heatmap, risk zones, stabilization signals, and team distribution.
+1. **Classify** — turn recent git history into a pipe-delimited CSV, one row per commit, via parallel low-cost subagents.
+2. **Analyze** — read that CSV for the velocity heatmap, risk zones, stabilization signals, and team distribution.
 
 ## Parameters
 
-Parse these from the user's prompt. Use defaults if not specified.
+Parse these from the user's prompt; use the default when unstated.
 
 | Parameter | Default | Examples |
 | --- | --- | --- |
@@ -24,19 +25,19 @@ Parse these from the user's prompt. Use defaults if not specified.
 | `skip_merges` | `true` | "include merges" |
 | `branch` | current branch | "on main", "on ai-staging" |
 
-The heatmap needs rolling 1w / 1m / 3m windows, so default `since` to 3 months even though the classifier processes every commit in range.
+`since` defaults to 3 months because the heatmap needs rolling 1w / 1m / 3m windows — the classifier still processes every commit in range.
 
 ## Before Starting
 
-1. If `./docs/memory/change-review.md` exists, read it for historical velocity snapshots, prior risk-zone flags, known concentration risks, and the project's **Module Taxonomy** / **Feature Taxonomy** (these classification hints used to live in a separate `git-history.md` memory file — they now live here).
-2. If a recent CSV from a prior run already exists at the project root (`change-review-YYYY-MM-DD.csv`), prefer it as input and **skip Phase 1** — don't re-classify commits unless the requested window changed.
-3. Build the ownership map from feature `owns:` frontmatter — consult the injected ownership index (`glob → doc · module · keywords · status`), or glob `docs/features/**/*.md` and read each doc's `owns:` globs — to map churn to owning feature docs (and their `module:` labels).
+1. If `./docs/memory/change-review.md` exists, read it for historical velocity snapshots, prior risk-zone flags, known concentration risks, and the project's **Module Taxonomy** / **Feature Taxonomy**.
+2. If a CSV from a prior run already exists at the project root (`change-review-YYYY-MM-DD.csv`), prefer it as input and **skip Phase 1** — re-classify only when the requested window changed.
+3. Build the ownership map from feature `owns:` frontmatter — consult the injected ownership index (`glob → doc · module · keywords · status`), or glob `docs/features/**/*.md` and read each doc's `owns:` globs — to map churn to owning feature docs and their `module:` labels.
 
 ---
 
 # Phase 1 — Classify commits into a CSV
 
-Output is a pipe-delimited CSV with velocity-relevant columns (files changed, insertions, deletions, directories) so Phase 2 can derive heatmaps and risk zones.
+The CSV carries velocity columns (files changed, insertions, deletions, directories) so Phase 2 can derive heatmaps and risk zones from it alone.
 
 ## Step 1: Collect Commits
 
@@ -44,15 +45,15 @@ Output is a pipe-delimited CSV with velocity-relevant columns (files changed, in
 git log --format="%h|%ad|%an|%s" --date=short --since="{since}" --until="{until}" --no-merges {branch}
 ```
 
-- If `skip_merges` is false, remove `--no-merges`
-- If `branch` is specified, add it after the flags
+- Drop `--no-merges` when `skip_merges` is false
+- Add `branch` after the flags when specified
 - Report the total commit count and author breakdown before proceeding
 
-If zero commits found, stop and tell the user.
+If zero commits are found, stop and tell the user.
 
 ## Step 2: Pre-compute File Paths & Diff Stats
 
-For each commit hash, get changed files and line-level diff stats:
+For each commit hash, get changed files and line-level diff stats — run these in a single bash loop:
 
 ```bash
 # File names
@@ -62,7 +63,7 @@ git diff-tree --no-commit-id --name-only -r {hash}
 git diff-tree --no-commit-id --numstat -r {hash}
 ```
 
-Run these in a single bash call using a loop for efficiency. From the numstat output, compute per-commit totals:
+From the numstat output, compute per-commit totals:
 
 - `files_changed`: number of files in the commit
 - `insertions`: sum of added lines across all files
@@ -79,9 +80,9 @@ Build a registry of objects:
 
 Split the commit registry into batches of `batch_size` commits each.
 
-Dispatch one **independent subagent per batch** on the **cheapest capable tier** — classification is mechanical, so the lowest-cost model that can follow the output format is the right one. Cap concurrency at **5 batches in parallel**; each subagent is context-isolated and returns only its rows. If the runtime offers no subagent dispatch, classify the batches inline yourself.
+Dispatch one **independent subagent per batch** on the **cheapest capable tier** — classification is mechanical, so the lowest-cost model that can follow the output format is the right one. Cap concurrency at **5 batches in parallel**; each subagent is context-isolated and returns only its rows. With more batches than fit in one wave, wait for the wave to complete before launching the next. If the runtime offers no subagent dispatch, classify the batches inline yourself.
 
-Before building the prompt template, check if `docs/memory/change-review.md` contains **Module Taxonomy** and **Feature Taxonomy** sections. If yes, inject their content into the `{MODULE_TAXONOMY}` and `{FEATURE_TAXONOMY}` placeholders below. If no memory file exists, use these generic fallbacks:
+Inject the **Module Taxonomy** and **Feature Taxonomy** sections of `docs/memory/change-review.md` into the `{MODULE_TAXONOMY}` and `{FEATURE_TAXONOMY}` placeholders. Absent a memory file, use these fallbacks:
 
 **Generic Module Taxonomy fallback:**
 
@@ -144,55 +145,45 @@ Each object has: hash, date, author, message, files (array of changed file paths
 Classify every commit. Output one row per commit, in the same order as the input. Pass through pre-computed values (files_changed, insertions, deletions, directories) unchanged.
 ````
 
-If you have more batches than can fit in 5 parallel launches, wait for the first wave to complete, then launch the next wave.
-
 ## Step 4: Assemble CSV
 
 1. Collect all sub-agent outputs
 2. Split each output into lines, trimming whitespace and blank lines
 3. Validate each row has exactly 14 pipe-delimited fields
-4. If a row is malformed, attempt to fix obvious issues (extra/missing pipes). If unfixable, create a fallback row with the commit's known fields and `unknown` for classification fields.
-5. If an entire batch failed, retry it once with the same prompt. On second failure, fallback-classify all commits in that batch.
+4. If a row is malformed, fix obvious issues (extra/missing pipes). If unfixable, emit the fallback row below.
+5. If an entire batch failed, retry it once with the same prompt. On second failure, fallback-classify every commit in that batch.
 6. Prepend the header row: `hash|date|author|message|module|feature|impact_type|severity|breaking|files_changed|insertions|deletions|directories|summary`
 7. Sort data rows by date ascending, then by hash
-8. Write to the output file at project root using the Write tool
+8. Write to the output file at project root
+
+### Fallback Classification
+
+```
+{hash}|{date}|{author}|{message}|unknown|other|unknown|low|no|{files_changed}|{insertions}|{deletions}|{directories}|Could not classify commit
+```
 
 ## Step 5: Classification Summary
 
-After writing the CSV, compute and display these statistics by parsing the CSV:
+Parse the written CSV and display:
 
 - **Author breakdown** — commits per author (descending), breaking changes per author, lines changed per author
 - **Module distribution** — commit count, files changed, and lines changed per module (descending)
 - **Feature distribution** — commit count per feature (descending)
 - **Severity distribution** — count of high / medium / low
 - **Velocity snapshot** — total commits, files changed, insertions, deletions in the period; top 5 directories by commit count; top 5 directories by lines changed
-- **Breaking changes** — list all rows where breaking=yes, showing hash, author, message, module
+- **Breaking changes** — every row where breaking=yes, showing hash, author, message, module
 
 Report the output file path and total row count.
 
-### Fallback Classification
-
-When a commit cannot be classified by a sub-agent, use these defaults:
-
-```
-{hash}|{date}|{author}|{message}|unknown|other|unknown|low|no|{files_changed}|{insertions}|{deletions}|{directories}|Could not classify commit
-```
-
 ---
 
 # Phase 2 — Velocity analysis
 
-Where Phase 1 classifies _what_ changed, Phase 2 asks _where is change accelerating or decelerating_ — and whether review attention matches the risk. Read the CSV from Phase 1 (or the recent one found in Before Starting).
+Read the CSV from Phase 1 (or the recent one found in Before Starting).
 
 ## Step 6: Velocity Heatmap
 
-Compute commits-per-directory over rolling windows:
-
-- **1 week** — what's hot right now
-- **1 month** — current rhythm
-- **3 months** — quarter-level pattern
-
-Aggregate by the top-level directories the CSV's `directories` field already carries (computed generically in Phase 1, Step 2). Report:
+Aggregate commits per top-level directory — the CSV's `directories` field already carries them — over rolling windows: **1 week** (what's hot right now), **1 month** (current rhythm), **3 months** (quarter-level pattern). Report:
 
 | Directory | Commits 1w | Commits 1m | Commits 3m | Trend |
 | --------- | ---------: | ---------: | ---------: | ----- |
@@ -201,17 +192,17 @@ Trend column: ↑ rising, ↓ falling, → steady, ↑↑ sharply rising, ↓↓
 
 ## Step 7: Risk Zones
 
-For each module with high churn (top quartile in 1m window), check how contract-heavy and how covered it is:
+For each module with high churn (top quartile in the 1m window), check how contract-heavy and how covered it is:
 
 - Does its code own cross-cutting contract surfaces (schema/data access, wire handlers, auth/authz, event dispatch, env/config readers)? Skim the module's files to judge — contract-heavy churn is where silent breakage lives.
 - Is the module's owning feature doc up to date? (cross-reference with the maintenance agent's last drift check if available)
 - Do the module's code paths appear under any feature doc's `owns:` globs?
 
-Flag risk zones: high churn × contract-heavy × low doc coverage. These are where silent breakage is most likely.
+Flag as a risk zone: high churn × contract-heavy × low doc coverage.
 
 ## Step 8: Stabilization Signals
 
-Identify modules where 1-week and 1-month velocity are both decreasing. Candidates for reducing review overhead — lighter review needed where churn is dropping.
+Identify modules where 1-week and 1-month velocity are both decreasing — candidates for lighter review.
 
 ## Step 9: Team Distribution
 
@@ -239,11 +230,10 @@ Per module, list which authors made the most commits in the 3-month window. Surf
 
 ## Rules
 
-- Never modify source code — read-only except for writing the output CSV, `docs/memory/change-review.md`, and `docs/history/backlog.md`
-- Run all classification subagents on the cheapest capable tier to minimize cost; they are independent and context-isolated
-- Always report progress: "Dispatching batch 1-5 of 12..." etc.
-- If git commands fail (bad branch, bad date range), stop and report the error clearly
-- Pipe characters in commit messages must be replaced with dashes before writing to CSV
-- Risk-zone identification judges contract-heaviness from the code itself (Step 7) — no persisted boundary docs exist or are needed
+- **Never modify source code** — read-only except for the output CSV, `docs/memory/change-review.md`, and `docs/history/backlog.md`
+- Always report progress: "Dispatching batch 1-5 of 12..."
+- If a git command fails (bad branch, bad date range), stop and report the error clearly
+- Replace pipe characters in commit messages with dashes before writing a row
+- Judge contract-heaviness from the code itself (Step 7) — **no persisted boundary docs exist or are needed**
 - A clean report (no risk zones) is valid for a low-churn, well-covered project
 '''

package/data/harnesses/code/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