@nurix/etna 0.19.65 → 0.19.67

package/bin/etna.js

@@ -232,7 +232,16 @@ async function main(args) {
   await sleep(2000);
   boot.stop('Ready');
 
-  const harnessName = await resolveHarnessName(name, harnesses);
+  // Transition alias: the `apollo` harness merged into `code` (the code harness is pre-baked —
+  // it ships the docs scaffold as seeds and auto-baselines on first contact). Scripts and docs
+  // that pin the old name keep working through the alias; it retires after one window.
+  let requested = name;
+  if (requested === 'apollo' && !harnesses.apollo) {
+    p.log.info('`apollo` merged into `code` — installing `code` (the pre-baked harness).');
+    requested = 'code';
+  }
+
+  const harnessName = await resolveHarnessName(requested, harnesses);
   if (!harnessName) return; // user cancelled the interactive pick
 
   await installHarness(harnessName, harnesses);

package/data/harness-index.json

@@ -1,10 +1,6 @@
 {
-    "fingerprint": "b0d947332bf0",
+    "fingerprint": "546f4bccb873",
     "harnesses": {
-        "apollo": {
-            "plugin": "apollo",
-            "description": "the pre-baked `code` harness, built for Apollo Studio exports"
-        },
         "code": {
             "plugin": "code",
             "description": "the foundation every Nurix project starts with"

package/data/harnesses/code/CLAUDE.md

@@ -6,6 +6,8 @@ How AI coding agents — any vendor, any runtime — work on this project. Rules
 
 ## Maintenance
 
+**Baseline first**: if `docs/structure.md` lacks a `harness-version` frontmatter marker, or it is behind the `version` in `.claude/harness.json`, dispatch the `maintenance` agent **as a sub-agent** before taking up the user's first ask — baseline is bulky mechanical work, and dispatching it keeps this context clean for the ask. Tell the user what it will do; on a repo with existing docs or `.bkp` files, name what the fold will touch. No dispatch mechanism ⇒ run it inline.
+
 Invoke the `maintenance` agent when a mechanical condition holds: `docs/structure.md` is missing (the repo isn't reconciled — baseline first), the `harness-version` marker is behind the installed version, a doc contradicts code being touched, or source paths are unowned — not on prose that merely looks stale. Structural reconciliation is never done by hand — the agent auto-selects its mode (baseline when the marker is missing or behind, coherence audit otherwise) and hands back; if it returns a follow-up (typically the module proposal), re-invoke it to finish. Single-glob or single-line doc corrections are done inline, per § Documentation. Each component's internals live in the component, not here.
 
 ---
@@ -50,7 +52,7 @@ These four mechanisms work in tandem to keep the repo self-updating and to preve
 
 ### Ownership — route before editing
 
-Which doc is canonical for which code paths is the **feature doc's own frontmatter**. A feature doc (flat in `docs/features/`) carries `owns:` (code-path globs — the only ownership key), `module:` (a bounded-context label, omitted when cross-cutting), `keywords:` (discovery), and `status:`. Code → doc ownership is the union of every feature doc's `owns:` globs, surfaced as the generated ownership index at session start. A module is tied to code by the `owns:` globs of the docs carrying its `module:` label — not a folder, not a separate map. Architecture docs describe cross-cutting patterns and own no files; operations docs describe procedures.
+Which doc is canonical for which code paths is the **feature doc's own frontmatter**. A feature doc (flat in `docs/features/`) carries `owns:` (code-path globs — the only ownership key), `module:` (a bounded-context label, omitted when cross-cutting), `keywords:` (discovery), and `status:`. Code → doc ownership is the union of every feature doc's `owns:` globs, surfaced as the generated ownership index at session start. A module is tied to code by the `owns:` globs of the docs carrying its `module:` label — not a folder, not a separate map. Architecture docs describe cross-cutting patterns and own no files; operations docs describe procedures. Every doc carries `type:` — its genre, stamped by document generators or at authoring, read by tooling (UI grouping, protected-file mapping); the `maintenance` agent stamps it where missing. Like `last-reviewed:`, it is tooling metadata: preserve it on edits, never inject or narrate it.
 
 Before modifying code in an unfamiliar area:
 

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

@@ -51,7 +51,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.
@@ -62,6 +62,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.
 
 For each code symbol or path a doc explicitly **names** (function/export/route/type):
 
@@ -185,6 +186,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

package/data/harnesses/code/harness.json

@@ -1,14 +1,19 @@
 {
   "harness": "code",
   "name": "code",
-  "version": "3.7.1",
+  "version": "3.8.1",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
   "seeds": [
+    "docs/README.md",
+    "docs/structure.md",
+    "docs/history/CHANGELOG.md",
+    "docs/history/backlog.md",
+    "docs/memory/main.md",
     ".mcp.json"
   ],
-  "digest": "105461e25748"
+  "digest": "f120a269e99c"
 }

package/data/harnesses/code/hooks/check-completion-integrity.mjs

@@ -7,6 +7,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { frontmatter, field } from "./lib/ownership.mjs";
+import { undischargedRows } from "./lib/ledger.mjs";
 
 const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
 const plansDir = path.join(projectDir, "docs", "history", "plans");
@@ -41,6 +42,13 @@ for (const file of plans) {
     const unchecked = (text.match(/^- \[ \]/gm) || []).length;
     if (unchecked > 0) fail(`${file} is Complete with ${unchecked} unchecked Done Criteria box(es)`);
 
+    // The ledger is discharged per row, in the file — a Done Criteria checkbox asserting "every
+    // row discharged" is exactly the checkbox-nothing-reads failure the doc ledger existed to fix.
+    const rows = undischargedRows(text);
+    if (rows.length > 0) {
+      fail(`${file} is Complete with ${rows.length} Test Obligations row(s) missing a discharge outcome (#${rows.join(", #")})`);
+    }
+
     // EVERY Spec line, not the first. A plan may implement against several feature docs, and a
     // single-match parse silently exempts all but one — the same singular assumption the Doc
     // Obligations ledger exists to break, reintroduced here where nothing would surface it.

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

@@ -11,6 +11,8 @@ import { spawnSync } from "node:child_process";
 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";
 
 function readSafe(file) {
   try {
@@ -38,6 +40,23 @@ function decision(permissionDecision, reason) {
   };
 }
 
+// A deny is also an event in the session gate log — the record that makes going silent after a
+// block impossible. The log is a dated per-session record (never drained; bookkeeping stays a
+// queue); the Stop and commit walls block on `denied` lines with no later `resolved` pair.
+function deny(projectDir, sessionId, gate, target, reason) {
+  appendEvent(projectDir, sessionId, "denied", gate, target);
+  return decision("deny", reason);
+}
+
+// The mechanical half of resolution: when the once-denied operation later succeeds through the
+// gate, machinery writes `retried-ok` itself — the session hand-writes only the judgment claims
+// (`waived → {ref}`, `disclosed → {entry}`).
+function autoResolve(projectDir, sessionId, gate, target) {
+  if (unresolvedDenials(projectDir, sessionId).includes(`${gate} · ${target}`)) {
+    appendEvent(projectDir, sessionId, "resolved", gate, target, "retried-ok");
+  }
+}
+
 // ---------------------------------------------------------------------------
 // PreToolUse — file gates
 // ---------------------------------------------------------------------------
@@ -83,40 +102,54 @@ function openGatedPlans(projectDir) {
 
 const SOURCE_LIKE = /\.(m?[jt]sx?|py|rs|go|rb|java|kt|swift|c|h|cpp|hpp|cs|sh|sql|vue|svelte)$/;
 
-function fileGate(projectDir, rel, toolName) {
+function fileGate(projectDir, rel, toolName, sessionId) {
   const frozen = frozenStatus(projectDir, rel);
   if (frozen.frozen) {
-    return decision(
-      "deny",
+    return deny(
+      projectDir,
+      sessionId,
+      "frozen-record",
+      rel,
       `BLOCKED — frozen record. \`${rel}\` is committed history and is never edited (${frozen.reason}). A correction is a new dated entry that links back.`
     );
   }
 
   if (protectedPaths(projectDir).includes(rel)) {
-    return decision("deny", `BLOCKED — protected file. \`${rel}\` is on the protected list.`);
+    return deny(projectDir, sessionId, "protected-file", rel, `BLOCKED — protected file. \`${rel}\` is on the protected list.`);
   }
 
   const inDocs = rel.startsWith("docs/") || rel.startsWith(".claude/") || rel.endsWith(".md");
   if (!inDocs && SOURCE_LIKE.test(rel)) {
     for (const plan of openGatedPlans(projectDir)) {
       if (/Boundary:\s*pending/i.test(plan.gates)) {
-        return decision(
-          "deny",
+        return deny(
+          projectDir,
+          sessionId,
+          "plan-gate",
+          plan.file,
           `BLOCKED — plan gate. \`${plan.file}\` is open but its Gates line reads 'Boundary: pending'. Run the \`boundary\` skill and record its verdict in the plan before implementation edits.`
         );
       }
       if (!plan.hasLedger) {
-        return decision(
-          "deny",
+        return deny(
+          projectDir,
+          sessionId,
+          "plan-gate",
+          plan.file,
           `BLOCKED — plan gate. \`${plan.file}\` has no \`## Test Obligations\` section. Run the \`testing\` skill (plan-gate mode); its ledger is what the verification gate discharges.`
         );
       }
       if (!plan.hasDocLedger) {
-        return decision(
-          "deny",
+        return deny(
+          projectDir,
+          sessionId,
+          "plan-gate",
+          plan.file,
           `BLOCKED — plan gate. \`${plan.file}\` has no \`## Doc Obligations\` section. Resolve the Proposed Changes paths against the ownership index and fill the table yourself — it is a lookup, not a skill run. "None" is a valid row when the plan touches only unowned paths.`
         );
       }
+      // The gates pass now — a plan-gate denial recorded earlier is a successful retry.
+      autoResolve(projectDir, sessionId, "plan-gate", plan.file);
     }
   }
 
@@ -158,30 +191,52 @@ function stagedExempt(files) {
       HARNESS_PREFIXES.some((p) => f.startsWith(p)) ||
       HARNESS_FILES.includes(f) ||
       f.startsWith("docs/history/changelog/") ||
+      f.startsWith("docs/history/sessions/") ||
+      f.includes(".bkp.") ||
       f === "docs/history/CHANGELOG.md"
   );
 }
 
-function commitGate(projectDir) {
+function commitGate(projectDir, sessionId) {
   const staged = (git(projectDir, ["diff", "--cached", "--name-only"]) || "")
     .split("\n")
     .map((s) => s.trim())
     .filter(Boolean);
   if (staged.length > 0 && !stagedExempt(staged)) {
     if (!staged.some((f) => f.startsWith("docs/history/changelog/"))) {
-      return decision(
-        "deny",
+      return deny(
+        projectDir,
+        sessionId,
+        "changelog",
+        "git commit",
         "BLOCKED — changelog. This commit stages no `docs/history/changelog/` entry. Every non-exempt commit carries its entry inside it (exempt: release/bot, harness installs and bumps, lockfile-only, pure renames, changelog housekeeping — state which if claiming one, then stage accordingly or re-run)."
       );
     }
   }
   const counts = countRows(readQueue(projectDir));
   if (counts.unresolved > 0) {
+    return deny(
+      projectDir,
+      sessionId,
+      "bookkeeping",
+      "git commit",
+      `BLOCKED — bookkeeping. ${counts.unresolved} unresolved row(s) in docs/operations/bookkeeping.md. Dispatch the bookkeeper, resolve, or convert to \`waived:\` with a reason and expiry.`
+    );
+  }
+
+  // This session's own open denials wall the commit too — a commit is the arc's end as much as a
+  // stop is, and an undisclosed failure must not ride out inside one.
+  const open = unresolvedDenials(projectDir, sessionId).filter((pair) => !pair.startsWith("changelog ·") && !pair.startsWith("bookkeeping ·"));
+  if (open.length > 0) {
     return decision(
       "deny",
-      `BLOCKED — bookkeeping. ${counts.unresolved} unresolved row(s) in docs/operations/bookkeeping.md. Dispatch the bookkeeper, resolve, or convert to \`waived:\` with a reason and expiry.`
+      `BLOCKED — session gate log. ${open.length} denial(s) this session have no resolved line (${open.join("; ")}). Append \`resolved\` to the session log — retried-ok happens automatically on a successful retry; otherwise \`waived → {ref}\` or \`disclosed → {changelog entry}\`. Never delete log lines.`
     );
   }
+
+  // All commit gates pass — a changelog/bookkeeping denial recorded earlier is a successful retry.
+  autoResolve(projectDir, sessionId, "changelog", "git commit");
+  autoResolve(projectDir, sessionId, "bookkeeping", "git commit");
   return null;
 }
 
@@ -200,22 +255,40 @@ function approvedPackages(projectDir) {
   return names;
 }
 
-function packageGate(projectDir, command) {
-  const m = new RegExp(String.raw`(?:^|&&|;|\|)\s*(?:sudo\s+)?(?:pnpm|npm|yarn|bun)\s+(?:add|install|i)\s+(.+)`).exec(command);
+// A token must parse as an npm package spec — name or @scope/name, optional @range tail —
+// before it may be judged against the table. Everything else on an install line (redirections
+// like 2>&1, chained commands, flags, paths, URLs) is shell, not a package. A non-candidate is
+// skipped, never blocked: a miss is caught downstream by the lockfile, while a false deny
+// teaches the session the gate is noise exactly where the gate matters most.
+const PKG_SPEC = /^(@[a-z0-9~-][\w.-]*\/)?[a-z0-9~-][\w.-]*(@[\w.^~*<>=|x-]+)?$/;
+
+function packageGate(projectDir, command, sessionId) {
+  const m = new RegExp(
+    String.raw`(?:^|&&|;|\|)\s*(?:sudo\s+)?(?:pnpm|npm|yarn|bun)\s+(?:add|install|i)(?=\s|$)([^&;|]*)`
+  ).exec(command);
   if (!m) return null;
   const approved = approvedPackages(projectDir);
   if (approved.size === 0) return null; // no rules file installed — nothing to enforce
-  const args = m[1].split(/\s+/).filter((a) => a && !a.startsWith("-"));
+  const args = (m[1] || "")
+    .split(/\s+/)
+    .filter((a) => a && !a.startsWith("-") && PKG_SPEC.test(a));
   for (const arg of args) {
     const pkg = arg.startsWith("@") ? arg.split("@").slice(0, 2).join("@") : arg.split("@")[0];
-    if (!pkg || pkg === "." || pkg.includes("/") && !pkg.startsWith("@")) continue;
     if (!approved.has(pkg)) {
-      return decision(
-        "deny",
+      return deny(
+        projectDir,
+        sessionId,
+        "package-table",
+        pkg,
         `BLOCKED — package table. \`${pkg}\` is not in the approved table (.claude/hooks/approved-packages.md; test packages: .claude/rules/testing.md). The table changes only by explicit user decision.`
       );
     }
   }
+  // Every named package is approved — a package-table denial for one of them is a successful retry.
+  for (const arg of args) {
+    const pkg = arg.startsWith("@") ? arg.split("@").slice(0, 2).join("@") : arg.split("@")[0];
+    autoResolve(projectDir, sessionId, "package-table", pkg);
+  }
   return null;
 }
 
@@ -252,7 +325,7 @@ function bashGate(projectDir, command, sessionId) {
   if (!command) return null;
 
   if (statement(String.raw`git\s+commit\b`).test(command)) {
-    return commitGate(projectDir);
+    return commitGate(projectDir, sessionId);
   }
 
   // `git branch <name>` creates; flag-led forms (--show-current, --list, -d, -vv) query or manage
@@ -277,7 +350,7 @@ function bashGate(projectDir, command, sessionId) {
     );
   }
 
-  return packageGate(projectDir, command);
+  return packageGate(projectDir, command, sessionId);
 }
 
 // ---------------------------------------------------------------------------
@@ -397,13 +470,44 @@ function stopGate(projectDir, payload) {
     };
   }
 
+  // Open gate denials wall the stop: silence after a block is the one ending the log exists to
+  // make impossible. Resolution appends to the log — retried-ok is machinery-written on a
+  // successful retry; waived/disclosed are the session's hand-written, auditable claims.
+  const openDenials = unresolvedDenials(projectDir, payload.session_id);
+  if (openDenials.length > 0) {
+    const rel = path.relative(projectDir, sessionLogPath(projectDir, payload.session_id));
+    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.",
+    };
+  }
+
   // An undischarged Doc Obligations ledger is not walled here — the detector raises it as a
   // `needs-session:` row, which the queue wall above already blocks on, and which outlives this
   // stop through the commit gate and CI. A second wall keyed to one checkbox would add a special
   // case beside a general rule that already covers it.
-  const undocumented = plansCompletedThisSession(projectDir, payload.session_id).filter(
-    (rel) => !planHasChangelogEntry(projectDir, rel)
-  );
+  const completed = plansCompletedThisSession(projectDir, payload.session_id);
+
+  // The Test Obligations ledger IS walled per row: the Outcome cell lives in the plan file, so the
+  // only way past this block is reading the file — a context-held copy of the ledger is exactly
+  // how rows get missed. (Tables without an Outcome column are legacy and pass; see lib/ledger.)
+  for (const rel of completed) {
+    const rows = undischargedRows(readSafe(path.join(projectDir, rel)));
+    if (rows.length > 0) {
+      return {
+        decision: "block",
+        reason:
+          `Plan \`${rel}\` is Status: Complete with ${rows.length} Test Obligations row(s) missing a discharge outcome (#${rows.join(", #")}). ` +
+          "Re-read the ledger from the plan file and discharge every row at the verification gate — satisfied, owes nothing (reason), or blocked → backlog — before completing.",
+      };
+    }
+  }
+
+  const undocumented = completed.filter((rel) => !planHasChangelogEntry(projectDir, rel));
   if (undocumented.length > 0) {
     return {
       decision: "block",
@@ -434,7 +538,7 @@ function main() {
       out = bashGate(commandRoot(projectDir, payload, input.command), input.command, payload.session_id);
     } else {
       const rel = relIfInside(projectDir, input.file_path || input.notebook_path);
-      if (rel) out = fileGate(projectDir, rel, payload.tool_name);
+      if (rel) out = fileGate(projectDir, rel, payload.tool_name, payload.session_id);
     }
   } else if (event === "Stop") {
     out = stopGate(projectDir, payload);
@@ -451,7 +555,15 @@ function main() {
 try {
   main();
 } catch (e) {
-  // Fail open: a broken gate must never become an outage.
+  // Fail open: a broken gate must never become an outage. But a gate that crashes silently is a
+  // gate nobody knows stopped guarding — leave a trace where the next SessionStart can find it.
+  try {
+    const dir = path.join(process.env.CLAUDE_PROJECT_DIR || process.cwd(), ".claude", "state");
+    fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(path.join(dir, "hook-failures.log"), `${new Date().toISOString()} compliance.mjs ${e?.message || e}\n`);
+  } catch (e2) {
+    /* truly nowhere to write — fail open stays absolute */
+  }
 } finally {
   process.exit(0);
 }

package/data/harnesses/code/hooks/lib/frozen.mjs

@@ -29,6 +29,9 @@ function readSafe(projectDir, filePath) {
 
 // The predicate. Returns { frozen: boolean, reason?: string }.
 export function frozenStatus(projectDir, filePath) {
+  // *.bkp.* siblings are install-time backups, not records — the maintenance fold edits and
+  // deletes them, which a frozen verdict would forbid.
+  if (relPosix(projectDir, filePath).includes(".bkp.")) return { frozen: false };
   const rel = relPosix(projectDir, filePath);
   if (rel.startsWith("docs/history/changelog/") && rel.endsWith(".md")) {
     if (isCommitted(projectDir, rel)) {

package/data/harnesses/code/hooks/lib/ledger.mjs

@@ -0,0 +1,31 @@
+// harness/code/hooks/lib/ledger.mjs — the Test Obligations table, read the way the walls read it.
+// A row is discharged when its Outcome cell states one of the gate's three outcomes. The plan file
+// is the checked truth — a discharge held only in conversation memory does not exist, which is what
+// forces the gate to re-read the ledger from disk. Tables without an Outcome column predate the
+// contract and are out of scope: the same legacy tolerance the Gates: line gets, so an upgrade
+// cannot brick a plan already Complete.
+
+const OUTCOME = /^(satisfied|owes nothing|blocked)\b/i;
+
+// Row numbers (the `#` column) of every ledger row whose Outcome cell is empty or off-vocabulary.
+export function undischargedRows(planText) {
+  const start = (planText || "").search(/^##\s+Test Obligations\b/m);
+  if (start === -1) return [];
+  const body = [];
+  for (const line of planText.slice(start).split("\n").slice(1)) {
+    if (/^##\s/.test(line)) break; // next section
+    body.push(line);
+  }
+  const rows = body.filter((line) => /^\s*\|/.test(line));
+  if (rows.length < 3) return []; // header + divider + at least one data row
+  const header = rows[0].split("|").map((cell) => cell.trim().toLowerCase());
+  const col = header.indexOf("outcome");
+  if (col === -1) return []; // legacy table — predates the Outcome contract
+  const out = [];
+  for (const line of rows.slice(2)) {
+    const cells = line.split("|").map((cell) => cell.trim());
+    if (!/^\d+$/.test(cells[1] || "")) continue;
+    if (!OUTCOME.test(cells[col] || "")) out.push(cells[1]);
+  }
+  return out;
+}

package/data/harnesses/code/hooks/lib/ownership.mjs

@@ -117,7 +117,9 @@ export function asList(v) {
 // Shape: { doc (repo-relative, /-separated), owns[], module, keywords[], status }.
 export function scanFeatureDocs(projectDir) {
   const featuresDir = path.join(projectDir, "docs", "features");
-  const files = listMarkdown(featuresDir);
+  // *.bkp.* files are install-time backups awaiting the maintenance fold — a backed-up feature
+  // doc still carries owns: frontmatter, and scanning it would double-own every path it names.
+  const files = listMarkdown(featuresDir).filter((f) => !f.includes(".bkp."));
   const docs = [];
   for (const file of files) {
     let text;

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

@@ -0,0 +1,75 @@
+// harness/code/hooks/lib/session-log.mjs — the per-session gate log: a dated record, never drained.
+// Bookkeeping is a queue whose success state is empty; this file is the opposite genre — the
+// session's operational story, kept like memory. Machinery appends `denied` and `hook-crash`
+// events; the session appends `resolved` lines. The walls read PAIRS: a `denied` with no later
+// `resolved` for the same gate·target is an open failure, and silence about it is what the Stop
+// and commit walls refuse. Every line survives forever — the row's afterlife is the failure
+// stream later intelligence reads, so resolution appends rather than deletes.
+
+import fs from "node:fs";
+import path from "node:path";
+
+const DIR = ["docs", "history", "sessions"];
+
+function sid8(sessionId) {
+  return String(sessionId || "unknown").replace(/[^a-zA-Z0-9-]/g, "").slice(0, 8) || "unknown";
+}
+
+export function sessionLogPath(projectDir, sessionId) {
+  const dir = path.join(projectDir, ...DIR);
+  const suffix = `-${sid8(sessionId)}.md`;
+  try {
+    const existing = fs.readdirSync(dir).find((f) => f.endsWith(suffix));
+    if (existing) return path.join(dir, existing);
+  } catch (e) {
+    /* dir absent — first event creates it */
+  }
+  const date = new Date().toISOString().slice(0, 10);
+  return path.join(dir, `${date}${suffix}`);
+}
+
+// Append one event line, creating the file (with its header) on first write. Best-effort by
+// design: a log append must never become an outage, so failures return false and are the
+// caller's cue to fall back to .claude/state/hook-failures.log.
+export function appendEvent(projectDir, sessionId, kind, gate, target, detail = "") {
+  try {
+    const file = sessionLogPath(projectDir, sessionId);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    if (!fs.existsSync(file)) {
+      fs.writeFileSync(
+        file,
+        `# Session gate log · sid=${sessionId || "unknown"}\n\n` +
+          "Machinery-written record (a dated record, never edited down — resolutions append). " +
+          "Every `denied` line needs a later `resolved` line for the same gate · target — " +
+          "`retried-ok`, `waived → {ref}`, or `disclosed → {changelog entry}` — before the " +
+          "session ends or commits.\n\n"
+      );
+    }
+    const ts = new Date().toISOString().slice(11, 19);
+    const tail = detail ? ` · ${detail}` : "";
+    fs.appendFileSync(file, `- ${ts} ${kind} · ${gate} · ${target}${tail}\n`);
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+// Open failures: gate·target pairs denied with no later `resolved` line. Multiple denials of one
+// pair are one open failure (the retry count stays in the story; the wall asks one question).
+export function unresolvedDenials(projectDir, sessionId) {
+  let text = "";
+  try {
+    text = fs.readFileSync(sessionLogPath(projectDir, sessionId), "utf8");
+  } catch (e) {
+    return [];
+  }
+  const open = new Map();
+  for (const line of text.split("\n")) {
+    const m = /^- \S+ (denied|resolved) · ([^·]+) · ([^·\n]+?)(?: · |$)/.exec(line);
+    if (!m) continue;
+    const key = `${m[2].trim()} · ${m[3].trim()}`;
+    if (m[1] === "denied") open.set(key, true);
+    else open.delete(key);
+  }
+  return [...open.keys()];
+}

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

@@ -12,6 +12,8 @@ Every unit of work leaves one record — `docs/history/changelog/YYYY-MM-DD-{thr
 
 An entry is owed only by work that changes promised behavior or takes a design decision; mechanical and cosmetic commits — a typo, a copy tweak, a config value, a log line — take only their `docs/history/CHANGELOG.md` row, no entry file. The failure fields (`Ask:`, `Skills:`, `Pin:`) are required only when non-none.
 
+Route the lesson by who pays for losing it: product context — what changed and why — belongs in the entry; anything the **next session would re-pay** — a library's API drifted from what the model expects, a validator's quirk, a tooling workaround — goes to `docs/memory/main.md` as well, because a changelog is read by people tracing history and memory is read by every session before it repeats the mistake.
+
 ## Lifecycle
 
 Draft (created before its commit exists) → complete (missing fields filled from the diff and the session) → frozen the moment it rides in a commit. **Immutability begins at commit, not at creation** — a draft is meant to be edited, which is what lets a completed plan record its context before anything is committed; a committed entry is history, and a correction is a new entry linking back, **never** an edit.

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

@@ -73,6 +73,7 @@ The two guarantees are complementary and both break on mixing: a reader holding
 | Testing strategy | [`templates/testing-strategy.md`](templates/testing-strategy.md) |
 | Behavioral checklist for one feature (`docs/tests/{feature}.md`) | [`templates/behavioral-checklist.md`](templates/behavioral-checklist.md) — the verification gate's driving script, and the source its suite tests are drawn from |
 | Recurring procedure/setup | [`templates/operations-procedure.md`](templates/operations-procedure.md) |
+| Cold-start build order (implementation map) | [`templates/implementation-map.md`](templates/implementation-map.md) — authored by the executing session at build start, updated in place as waves complete |
 | Capture mid-execution knowledge (`docs/history/journal.md`) | [`templates/journal.md`](templates/journal.md) (record — append-only; a row resolves by landing in its owning doc) |
 | Bookkeeping work queue (`docs/operations/bookkeeping.md`) | [`templates/bookkeeping.md`](templates/bookkeeping.md) — machine-read row grammar; appended by hooks and sessions, drained by the `bookkeeper` agent, walled at Stop and commit |
 | One-shot migration/upgrade | [`templates/migration-runbook.md`](templates/migration-runbook.md) (record) |

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

@@ -12,7 +12,7 @@ When creating or updating a feature doc, derive its **`owns:` frontmatter** —
 
 ## How to derive the frontmatter
 
-A feature doc's ownership frontmatter is `owns:` (required), `module:` (optional), `keywords:` (required), and `status:` (required). An optional `last-reviewed:` date (stamped whenever the doc is substantively reviewed or updated) gives the `maintenance` agent a staleness signal to rank its audits by — it is tooling metadata, never narrated in the body.
+A feature doc's ownership frontmatter is `owns:` (required), `module:` (optional), `keywords:` (required), and `status:` (required). An optional `last-reviewed:` date (stamped whenever the doc is substantively reviewed or updated) gives the `maintenance` agent a staleness signal to rank its audits by — it is tooling metadata, never narrated in the body. `type:` (required — the genre, enum = the template names) and `rev:` (generator-written generation stamp) are the same class: external tooling reads them, sessions **preserve them on edits** and never narrate or inject them. The `maintenance` agent stamps `type:` on docs that predate the key.
 
 **1. `owns:`** (the path scope)
 

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

@@ -23,7 +23,7 @@ const RULES = [
 // Sections inside a truth doc where dated history is sanctioned (the two bridges).
 const BRIDGE_HEADINGS = /^#{1,4}\s+(decision changelog|health log)\b/i;
 // Instruction files and generated trees are a different genre — out of this linter's scope.
-const SKIP = /(^|\/)(\.claude|node_modules|skills|rules|agents|harness|packages\/[^/]+\/data)\/|(^|\/)(CLAUDE|AGENTS)\.md$/;
+const SKIP = /(^|\/)(\.claude|node_modules|skills|rules|agents|harness|packages\/[^/]+\/data)\/|(^|\/)(CLAUDE|AGENTS)\.md$|\.bkp\./;
 const RECORD = /(^|\/)docs\/(history|research|memory)\//;
 
 // Classify a path: skipped genre, record, or truth.
@@ -89,7 +89,7 @@ function lintFile(path, findings) {
   const isFolderIndex = /(^|\/)(readme)\.md$/i.test(path);
   if (scope === 'truth' && !isFolderIndex && /(^|\/)docs\/features\/[^/]+\.md$/.test(path)) {
     const fm = text.startsWith('---') ? text.slice(0, text.indexOf('\n---', 3)) : '';
-    for (const key of ['owns:', 'keywords:', 'status:'])
+    for (const key of ['owns:', 'keywords:', 'status:', 'type:'])
       if (!fm.includes(key)) findings.push({ path, n: 1, severity: 'block', id: 'feature-frontmatter', message: `feature doc missing \`${key}\` frontmatter` });
   }
 }

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

@@ -16,6 +16,7 @@ One file per template. Every template is either a **truth document** (states cur
 | Testing strategy | [testing-strategy.md](testing-strategy.md) | Truth |
 | Behavioral checklist | [behavioral-checklist.md](behavioral-checklist.md) | Truth |
 | Operations procedure | [operations-procedure.md](operations-procedure.md) | Truth |
+| Implementation map | [implementation-map.md](implementation-map.md) | Truth |
 | Bookkeeping ledger | [bookkeeping.md](bookkeeping.md) | Truth (work queue) |
 | Protected files | [protected-files.md](protected-files.md) | Truth |
 | Project root README | [root-readme.md](root-readme.md) | Truth |

package/data/harnesses/code/skills/documentation/templates/behavioral-checklist.md

@@ -16,6 +16,7 @@ Required: **Conventions**, at least one numbered behavior section, **Failure Rep
 - **Prefer exact literals** — the real prompt text, the real button label, the real count. A vague assertion passes a broken product.
 - **Assert persistence separately from display.** "It appeared on screen" and "it was written" are two claims; a surface that streams unsaved content satisfies the first while failing the second.
 - **State each section's trace.** `Pinned:` names the suite test that now guards it, or says `driven only` **with the reason** — an unmarked section is indistinguishable from an unexamined one.
+- **State each section's `AC:` keys.** Where the repo carries a keyed acceptance-criteria source, each section names the keys it proves, so the chain from criterion to checklist to suite test survives the last hop; the gate reports coverage and backlogs uncovered keys. `none — not AC-mapped` is the honest line where no keyed source exists.
 - **A known-failing assertion stays written as the contract.** A checklist states what the feature promises; the *run* records the failure and the backlog carries the defect. Never soften an assertion to make a run go green.
 
 ```
@@ -44,6 +45,7 @@ Each step is an action; each **Assert** is the observable it must produce.
 - [ ] **Assert**: {the persistence claim, where the behavior writes something}
 
 > Pinned: `{tests/path/to/file.test.ts}` — or `driven only — {why no durable test is bought}`
+> AC: {the acceptance-criteria keys this section proves} — or `none — not AC-mapped`
 
 ### 2. {The next behavior}