@nurix/etna 0.19.68 → 0.19.70

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

@@ -5,35 +5,33 @@ developer_instructions = '''
 
 # 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
 
@@ -49,7 +47,7 @@ The ownership source of truth is the **union of every feature doc's `owns:` fron
 ### Step 1: Build the ownership map
 
 1. Read `docs/structure.md` for the authority map.
-2. Glob `docs/features/**/*.md`; for each, parse the frontmatter `owns:` globs and `module:` label.
+2. Glob `docs/features/**/*.md`, ignoring `*.bkp.*` files (installer backups awaiting the fold); for each, parse the frontmatter `owns:` globs and `module:` label.
 3. Build a map: glob → owning doc + module. Narrower glob wins on overlap. **This IS the source of truth.**
 
 **Architecture-first fallback.** If no feature doc carries `owns:` yet (a fresh-baseline repo can carry thousands of LOC and zero feature docs), drive this pass's ownership/drift surface off `docs/architecture/**` file-references instead — they become the **primary** ownership map for Steps 2–5. The `owns:` map becomes primary the moment any feature doc declares ownership — this is a fallback, not a replacement.
@@ -60,6 +58,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`). 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):
 
@@ -67,16 +66,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**.
@@ -94,34 +91,31 @@ 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.
 
+> **Never regenerate `.claude/state/drift-report.md` by running the awareness hook when the bookkeeping queue is what you are measuring.** `driftBanner()` calls `resolveRows()`, which *mutates* the queue as a side effect of reporting on it — so the act of refreshing the report changes the thing the report describes. Read the existing report, or recompute the facts directly from `deadGlobs()` / `scanFeatureDocs()`.
+
 ### 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.
-2. Update `docs/memory/maintenance.md` with last review date, stale docs fixed, unowned paths, backlog items created.
+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` 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)
 
@@ -135,6 +129,7 @@ docs/
 ├── features/              # Feature specs — the only first-class doc unit (flat; ownership in each doc's `owns:` frontmatter)
 │   └── {group}/           #   browse-only subfolder for grouping; NEVER a module; may carry a Readme.md
 ├── operations/            # Setup, development, deployment, CI/CD
+│   └── bookkeeping.md     #   the shared doc-sync work queue (hook-appended, bookkeeper-drained, walled at commit) — author-created, never scaffolded; treat rows as live work, never as drift
 ├── research/              # In-progress brainstorm sessions ({topic}-brainstorm/; legacy -brainstorming/) + standing research; Readme.md is the index
 │   └── {topic}-brainstorm/     #   created by the `brainstorm` skill; moves to history/brainstorms/ on a passed harvest
 ├── history/
@@ -142,6 +137,8 @@ docs/
 │   ├── changelog/         # Individual entries (YYYY-MM-DD-{three-words}.md; written at commit time)
 │   ├── plans/             # Implementation plans (Status field required)
 │   ├── migrations/        # One-shot migration/upgrade runbooks (YYYY-MM-DD-{slug}.md; outcome-stamped then frozen)
+│   ├── journal.md         # Append-only mid-execution knowledge capture (one line per fact; resolves by landing in its owning doc) — author-created, never scaffolded
+│   ├── sessions/          # Per-session gate logs (YYYY-MM-DD-{sid}.md) — machinery-written records, never drained, never edited down; created by the first gate event, never scaffolded
 │   ├── brainstorms/       # Harvested brainstorm sessions ({topic}/) — user decides kept (committed) or deleted; Readme.md is the index
 │   ├── research/          # Deep-research records ({topic}/ — README.md synthesis + findings.md + sources.md); frozen, cited, owns no code
 │   └── backlog.md       ✱ # Tracked work items by priority (P0-P3)
@@ -154,7 +151,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
 
@@ -164,7 +161,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) |
 | --- | --- |
@@ -179,6 +176,8 @@ This is what makes baseline more than a fresh scaffold. Detect old-shape artifac
 | `docs/architecture/overview.md` | split into `domain-model.md` / `glossary.md` / `non-goals.md` / `references.md` / `open-questions.md` |
 | `docs/architecture/adr/` (legacy folder name), or `ADR-NNN-*.md` records anywhere under `docs/architecture/` | **rename to the AD genre.** The folder becomes `docs/architecture/decisions/`; each record file `ADR-NNN-{slug}.md` becomes `AD-NNN-{slug}.md`, keeping its number and slug. Inside each record, update the retired vocabulary — "ADR", "Architecture Decision Record", and any supersession framing ("once accepted, an ADR is never edited; a later ADR supersedes it") — to the AD model: one AD per subject, **updated in place**, its journey confined to a `Decision Changelog` tail. A record's **reasoning is never rewritten** by a reconcile; only its genre vocabulary, its own title/id, and paths it cites. The folder's `Readme.md` is an **index, not a record** — reframe its genre description while preserving authored content such as a candidate-decision list verbatim. Repoint live references **inside `docs/`**, including one AD citing another; leave frozen records' links as point-in-time. A live reference **outside** your write scope — most often the root `README.md`, which you never overwrite — cannot be repointed: record it as a backlog item naming the file and line rather than leaving the residue silent |
 | a legacy `docs/brainstorm/{topic}/`, a singular `docs/history/brainstorm/`, or a root `brainstorm/`/`brainstorming/` folder | move each **active** record to `docs/research/{topic}-brainstorm/` and each **harvested** one to `docs/history/brainstorms/{topic}/` (dropping the suffix); create/refresh both `Readme.md` indexes; delete the emptied folder |
+| `*.bkp.*` files under `docs/` (the installer's first-contact backups of the project's pre-existing files) | **fold the content, then delete the backup.** Classify each backup's content by nature and land it in the current shape — a backed-up changelog's rows into `docs/history/CHANGELOG.md` and per-entry files, a backed-up structure/readme's real claims into the scaffolded truth doc, a backed-up feature doc's content merged into its sibling (or adopted whole if the sibling is a pristine seed). Content is folded, never discarded silently; what cannot be classified goes to the backlog with the backup kept. When the fold lands, delete the `.bkp` file |
+| `*.bkp.*` files at the repo root or in config (`CLAUDE.bkp.md`, `.prettierrc.bkp.json`, …) | **never merge these.** Top-level config is harness-owned by design; list each one to the user as their call, and leave the file in place |
 | no `harness-version` in `structure.md` | stamp it (Step B4) |
 
 ### Step B3 — Present the reconcile plan, then execute
@@ -187,9 +186,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
 
@@ -202,7 +199,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.
 
 ---
 
@@ -214,8 +213,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.
@@ -224,5 +224,13 @@ 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/code/codex/agents/performance-review.toml

@@ -5,14 +5,14 @@ developer_instructions = '''
 
 # 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.
 
 ---
 
@@ -20,8 +20,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
@@ -33,7 +31,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
@@ -51,13 +49,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
 
@@ -80,7 +72,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)
@@ -95,7 +87,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
 
@@ -113,7 +105,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
@@ -195,7 +187,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
 
@@ -212,11 +204,11 @@ 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/codex/agents/retro.toml

@@ -5,7 +5,7 @@ developer_instructions = '''
 
 # 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/harness.json

@@ -1,7 +1,7 @@
 {
   "harness": "code",
   "name": "code",
-  "version": "3.8.2",
+  "version": "3.8.4",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
@@ -15,5 +15,5 @@
     "docs/memory/main.md",
     ".mcp.json"
   ],
-  "digest": "2dcea7420200"
+  "digest": "cfd0df4274c4"
 }

package/data/harnesses/code/hooks/awareness.mjs

@@ -186,6 +186,13 @@ function driftBanner(projectDir) {
 }
 
 function sessionStart(projectDir) {
+  // Stamp the session's start so gitless repos still have a "modified since" horizon for the
+  // outcome detector's fallback scan (dirtyPaths). Overwritten per session; best-effort.
+  try {
+    fs.writeFileSync(path.join(stateDir(projectDir), "session-started"), new Date().toISOString() + "\n");
+  } catch (e) {
+    /* the stamp is a convenience for the fallback; git repos never need it */
+  }
   const lines = [];
   const pm = detectPackageManager(projectDir);
   if (pm) lines.push(`Package manager: ${pm}`);
@@ -366,7 +373,7 @@ function detectRenames(projectDir, command, meta, rows) {
 // Fails open: no git, or a git error, reads as an empty list.
 function dirtyPaths(projectDir) {
   const res = spawnSync("git", ["status", "--porcelain"], { cwd: projectDir, encoding: "utf8", timeout: 5000 });
-  if (res.status !== 0) return [];
+  if (res.status !== 0) return mtimeFallbackPaths(projectDir);
   return (res.stdout || "")
     .split("\n")
     .filter(Boolean)
@@ -377,6 +384,44 @@ function dirtyPaths(projectDir) {
     .map((p) => p.replace(/^"|"$/g, ""));
 }
 
+// No git ⇒ no porcelain, and the outcome detector went blind (a real run edited a frozen plan
+// via `sed -i` in a gitless repo, unseen). Fall back to "modified since this session started":
+// the SessionStart stamp bounds the scan, and the scan covers exactly the two surfaces the
+// detector reads — package manifests and docs/history records. No stamp ⇒ empty, as before.
+function mtimeFallbackPaths(projectDir) {
+  let since = 0;
+  try {
+    since = fs.statSync(path.join(stateDir(projectDir), "session-started")).mtimeMs;
+  } catch (e) {
+    return [];
+  }
+  const out = [];
+  const walk = (dirRel, depth, wanted) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(path.join(projectDir, dirRel), { withFileTypes: true });
+    } catch (e) {
+      return;
+    }
+    for (const en of entries) {
+      if (en.name === "node_modules" || en.name.startsWith(".")) continue;
+      const rel = dirRel ? `${dirRel}/${en.name}` : en.name;
+      if (en.isDirectory()) {
+        if (depth > 0) walk(rel, depth - 1, wanted);
+      } else if (wanted(en.name)) {
+        try {
+          if (fs.statSync(path.join(projectDir, rel)).mtimeMs >= since) out.push(rel);
+        } catch (e) {
+          /* raced away — not dirty */
+        }
+      }
+    }
+  };
+  walk("", 3, (name) => name === "package.json");
+  walk("docs/history", 4, (name) => name.endsWith(".md"));
+  return out;
+}
+
 // OUTCOME RECOMPUTATION — the gates deny wrong actions, but an action can be routed around by
 // any tool that writes bytes (a manifest written by a script, a frozen record touched by sed).
 // State cannot be routed around: recompute the two outcomes the gates guard and raise what

package/data/harnesses/code/hooks/compliance.mjs

@@ -12,7 +12,7 @@ import { readStdin, resolveProjectDir, frontmatter } from "./lib/ownership.mjs";
 import { readQueue, countRows, askedThisSession, recordAsked } from "./lib/state.mjs";
 import { frozenStatus } from "./lib/frozen.mjs";
 import { undischargedRows } from "./lib/ledger.mjs";
-import { appendEvent, unresolvedDenials, sessionLogPath } from "./lib/session-log.mjs";
+import { appendEvent, unresolvedDenials, sessionLogPath, malformedEventLines } from "./lib/session-log.mjs";
 import { approvedPackages } from "./lib/approved.mjs";
 
 function readSafe(file) {
@@ -337,9 +337,61 @@ function bashGate(projectDir, command, sessionId) {
     );
   }
 
+  const shellWrite = bashWriteScreen(projectDir, command, sessionId);
+  if (shellWrite) return shellWrite;
+
   return packageGate(projectDir, command, sessionId);
 }
 
+// A file write arriving by shell hits the same wall the Edit tool does. Only tokens in a
+// WRITING position count — redirect targets, `tee`/`mv`/`cp` destinations, and any path on an
+// in-place editor line (`sed -i`, `perl -i`) — so reading a frozen record into a pipe stays
+// legal. A token that isn't an existing repo path falls through frozenStatus/protected as a
+// no-op, which keeps sed expressions and flags harmless without shell-parsing them.
+function bashWriteTargets(command) {
+  const targets = [];
+  let m;
+  const redirect = />{1,2}\s*([^\s;|&<>]+)/g;
+  while ((m = redirect.exec(command))) targets.push(m[1]);
+  const tee = /\btee\s+(?:-\S+\s+)*([^\s;|&<>]+)/g;
+  while ((m = tee.exec(command))) targets.push(m[1]);
+  const moveCopy = /\b(?:mv|cp)\s+(?:-\S+\s+)*\S+\s+([^\s;|&<>]+)/g;
+  while ((m = moveCopy.exec(command))) targets.push(m[1]);
+  if (/\b(?:sed|perl)\s+(?:-\S*\s+)*-\S*i/.test(command) || /\bsed\s+--in-place\b/.test(command)) {
+    for (const t of command.split(/[\s"']+/)) {
+      if (t && !t.startsWith("-") && /[/.]/.test(t)) targets.push(t);
+    }
+  }
+  return targets;
+}
+
+function bashWriteScreen(projectDir, command, sessionId) {
+  for (const target of bashWriteTargets(command)) {
+    const rel = relIfInside(projectDir, target);
+    if (!rel) continue;
+    const frozen = frozenStatus(projectDir, rel);
+    if (frozen.frozen) {
+      return deny(
+        projectDir,
+        sessionId,
+        "frozen-record",
+        rel,
+        `BLOCKED — frozen record. \`${rel}\` is committed history and is never edited (${frozen.reason}) — a shell write is still a write. A correction is a new dated entry that links back.`
+      );
+    }
+    if (protectedPaths(projectDir).includes(rel)) {
+      return deny(
+        projectDir,
+        sessionId,
+        "protected-file",
+        rel,
+        `BLOCKED — protected file. \`${rel}\` is on the protected list — a shell write is still a write.`
+      );
+    }
+  }
+  return null;
+}
+
 // ---------------------------------------------------------------------------
 // Stop
 // ---------------------------------------------------------------------------
@@ -463,13 +515,21 @@ function stopGate(projectDir, payload) {
   const openDenials = unresolvedDenials(projectDir, payload.session_id);
   if (openDenials.length > 0) {
     const rel = path.relative(projectDir, sessionLogPath(projectDir, payload.session_id));
+    // A resolution that doesn't parse reads to the session as "my resolution didn't count"
+    // with no explanation — name the offending lines and the grammar instead of staying mute.
+    const bad = malformedEventLines(projectDir, payload.session_id);
+    const badNote =
+      bad.length > 0
+        ? ` NOTE: ${bad.length} line(s) look like events but don't parse — the grammar is \`- HH:MM:SS denied|resolved · gate · target[ · detail]\` (a resolved line missing its timestamp is invisible to the wall): ${bad.join(" | ")}.`
+        : "";
     return {
       decision: "block",
       reason:
         `${openDenials.length} gate denial(s) this session have no resolved line in ${rel}: ${openDenials.join("; ")}. ` +
         "For each, either retry the operation properly (a success appends `retried-ok` automatically), convert it to a waiver and append " +
         "`resolved · {gate} · {target} · waived → {ref}`, or record the failure honestly in the changelog entry and append " +
-        "`resolved · {gate} · {target} · disclosed → {entry file}`. Never delete log lines — the log is a record, not a queue.",
+        "`resolved · {gate} · {target} · disclosed → {entry file}`. Never delete log lines — the log is a record, not a queue." +
+        badNote,
     };
   }
 

package/data/harnesses/code/hooks/lib/session-log.mjs

@@ -73,3 +73,23 @@ export function unresolvedDenials(projectDir, sessionId) {
   }
   return [...open.keys()];
 }
+
+// Lines that LOOK like events but don't parse — a resolution missing its timestamp token, a
+// hand-typed variant of the grammar. The pair-matcher above skips them silently, which reads
+// to the session as "my resolution didn't count" with no explanation (a real session burned
+// its tail debugging exactly this). The walls surface these loudly instead.
+export function malformedEventLines(projectDir, sessionId) {
+  let text = "";
+  try {
+    text = fs.readFileSync(sessionLogPath(projectDir, sessionId), "utf8");
+  } catch (e) {
+    return [];
+  }
+  const bad = [];
+  for (const line of text.split("\n")) {
+    if (!/^- .*\b(denied|resolved)\b\s*·/.test(line)) continue;
+    if (/^- \S+ (denied|resolved) · ([^·]+) · ([^·\n]+?)(?: · |$)/.test(line)) continue;
+    bad.push(line.trim());
+  }
+  return bad;
+}

package/data/harnesses/code/rules/testing.md

@@ -55,7 +55,7 @@ Test packages install at `latest` — outside the approved-packages pin set. Fak
 - **Wire the canonical command.** `"test"` in `package.json` runs the whole unit suite (`vitest run`); e2e under `"test:e2e"`. A repo where `pnpm test` / `npm test` doesn't run the suite is misconfigured — fix the wiring, **never** route around it.
 - **Unit and E2E trees stay separate.** Vitest/Jest suites in `tests/`; Playwright/Maestro suites in `e2e/` with their own config — **never** mixed into the unit runner's glob.
 - **No test doubles for what you own.** Prefer real instances — in-memory SQLite for drizzle, the actual Express app via `supertest` — over mocks; mock **only** true externals (network via `msw`, time via the runner's fake timers).
-- **Determinism.** No real network, no real time, no shared mutable state between tests; every test **must** pass alone and in any order.
+- **Determinism.** No real network, no real time, no shared mutable state between tests; every test **must** pass alone, in any order, **and from a cold shell** — never against a hand-started dev server (Workers: `@cloudflare/vitest-pool-workers`; Express: `supertest` against the app instance).
 
 ## Discipline
 

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

@@ -15,7 +15,7 @@ The **`Gates:`** line is machine-read: the compliance hook greps exactly the for
 **Gates:** Boundary: pending · Test-plan: pending · Docs: pending
 **Spec:** [docs/features/{feature}.md](../../features/{feature}.md)   <!-- one line per feature doc this plan implements against; a plan spanning three features names three -->
 **Started:** YYYY-MM-DD
-**Completed:** YYYY-MM-DD   <!-- fill when status flips to Complete -->
+**Completed:** YYYY-MM-DD   <!-- fill in the SAME edit that flips Status to Complete: the flip freezes the file instantly, so a date left for a second edit is unreachable (the frozen-record gate rightly blocks it) -->
 
 ## Background