@nurix/etna 0.19.43 → 0.19.45

package/bin/etna.js

@@ -162,16 +162,32 @@ function migrateFromPluginInstall(targetDir, pluginName) {
 // Hook scripts shipped by earlier harness versions (the legacy memory-ledger tier) and since retired.
 // mergeHooks is additive, so an upgrade must explicitly remove both the stale settings.json
 // entries pointing at these and the leftover script files they reference.
-const RETIRED_HOOKS = ['session-stop.js', 'post-tool-failure.js', 'post-commit.js'];
+const RETIRED_HOOKS = [
+    'session-stop.js',
+    'post-tool-failure.js',
+    'post-commit.js',
+    'generate-ownership-index.mjs', // folded into awareness.mjs — unretired, the index would inject twice
+];
 
 // Remove settings.json hook entries and .claude/hooks/ files for retired hook scripts.
-function retireOldHooks(targetDir) {
+// Bundle-aware: a name on the retired list is skipped while THIS bundle still ships it —
+// several harnesses share the list, and they retire the same script at different versions.
+function retireOldHooks(targetDir, bundledHarnessDir) {
     const removed = [];
+    const bundledHooksDir = join(bundledHarnessDir, 'hooks');
+    const stillShipped = new Set(
+        existsSync(bundledHooksDir)
+            ? readdirSync(bundledHooksDir, { withFileTypes: true })
+                  .filter((e) => e.isFile())
+                  .map((e) => e.name)
+            : [],
+    );
+    const retired = RETIRED_HOOKS.filter((name) => !stillShipped.has(name));
     const settingsPath = join(targetDir, '.claude', 'settings.json');
     if (existsSync(settingsPath)) {
         const settings = readJson(settingsPath);
         const isRetired = (h) =>
-            RETIRED_HOOKS.some((name) => (h.command || '').includes(`/hooks/${name}`));
+            retired.some((name) => (h.command || '').includes(`/hooks/${name}`));
         let pruned = 0;
         for (const [event, groups] of Object.entries(settings.hooks || {})) {
             for (const group of groups) {
@@ -187,7 +203,7 @@ function retireOldHooks(targetDir) {
             removed.push(`${pruned} retired hook entr${pruned === 1 ? 'y' : 'ies'} in settings.json`);
         }
     }
-    for (const name of RETIRED_HOOKS) {
+    for (const name of retired) {
         const file = join(targetDir, '.claude', 'hooks', name);
         if (existsSync(file)) {
             rmSync(file, { force: true });
@@ -296,11 +312,22 @@ function groupHasCommand(group, command) {
 // already exists there; a new matcher creates a new group. Returns count of hooks added.
 function mergeHooks(targetDir, bundledHooksJson) {
     if (!existsSync(bundledHooksJson)) return 0;
-    const incoming = readJson(bundledHooksJson).hooks || {};
+    const bundled = readJson(bundledHooksJson);
+    const incoming = bundled.hooks || {};
     const settingsPath = join(targetDir, '.claude', 'settings.json');
     const settings = readJson(settingsPath);
     settings.hooks = settings.hooks || {};
     let added = 0;
+    // Harness-shipped permission defaults (e.g. Edit/Write on docs/** flow without prompts —
+    // the deny hooks still hard-block frozen/protected paths underneath). Additive, idempotent.
+    for (const rule of bundled.permissions?.allow || []) {
+        settings.permissions = settings.permissions || {};
+        const allowList = (settings.permissions.allow = settings.permissions.allow || []);
+        if (!allowList.includes(rule)) {
+            allowList.push(rule);
+            added += 1;
+        }
+    }
     for (const [event, groups] of Object.entries(incoming)) {
         const existingGroups = (settings.hooks[event] = settings.hooks[event] || []);
         for (const group of groups) {
@@ -504,7 +531,7 @@ async function installHarness(harnessName, harnesses) {
 
     // Retire hooks earlier harness versions shipped before merging, so the additive merge
     // never resurrects an entry pointing at a script this bundle no longer carries.
-    for (const r of retireOldHooks(targetDir)) notices.push(`removed ${r}`);
+    for (const r of retireOldHooks(targetDir, bundledHarnessDir)) notices.push(`removed ${r}`);
 
     // Merge the bundle's hooks.json into the project's settings.json (idempotent).
     const added = mergeHooks(targetDir, join(bundledHarnessDir, 'hooks', 'hooks.json'));

package/data/harness-index.json

@@ -1,5 +1,5 @@
 {
-    "fingerprint": "4d6e06e37895",
+    "fingerprint": "8a30d3130f63",
     "harnesses": {
         "apollo": {
             "plugin": "apollo",

package/data/harnesses/apollo/agents/bookkeeper.md

@@ -0,0 +1,27 @@
+---
+name: bookkeeper
+description: Drains docs/operations/bookkeeping.md — performs mechanical fixes (owns: globs, header comments, doc-lint findings, index rows), expands note: rows into doc edits, marks rows resolved. Dispatched by the main session at turn end or commit time; never self-triggers. Triggers on "drain the bookkeeping queue", "dispatch the bookkeeper", "/bookkeeper".
+tools: Read, Glob, Grep, Edit, Write, Bash, Skill
+model: inherit
+---
+
+# Bookkeeper Agent
+
+You drain the shared work queue at `docs/operations/bookkeeping.md`. Each row is one finding; your job is to resolve it — by doing the work it names — and delete the row. You are the asynchronous half of the harness's enforcement loop: the detector appends rows silently, you drain them, and the Stop/commit walls hold until the queue is clean or waived.
+
+## Source-of-truth order — the repo first, the transcript last
+
+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.
+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** — read a timestamp-anchored window of the transcript JSONL at the row's `tp=` path around its `ts=` stamp (never the whole file). The stamp 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 ts}`) and stop working that row.
+
+## Rules
+
+- **Never edit frozen records** — committed changelog entries, `Status: Complete|Abandoned` plans, outcome-stamped runbooks. A finding that seems to require one gets a `needs-session:` row instead.
+- **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:`.
+- **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/apollo/agents/maintenance.md

@@ -115,7 +115,7 @@ For unowned code paths:
 
 ### Step 6: Report & update tracking
 
-1. Update `docs/structure.md` Health Log with today's date and summary — **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.
+1. Update `docs/structure.md` Health Log with today's date and summary — **append to the end**, never date-sorted into the middle. Rows are positional: one may say "the row above is…", and an inserted row silently breaks that reference. A Health Log entry is a **generated row, not a narrative essay**: one line — date · counts (stale docs fixed, dead globs, unowned paths, backlog items created) · links to anything that needs a human.
 2. Update `docs/memory/maintenance.md` with last review date, stale docs fixed, unowned paths, backlog items created.
 3. Report findings: stale docs, broken ownership, unowned code, architecture drift, backlog health.
 
@@ -137,6 +137,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/
@@ -144,6 +145,7 @@ 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
 │   ├── 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)

package/data/harnesses/apollo/harness.json

@@ -1,7 +1,7 @@
 {
   "harness": "apollo",
   "name": "apollo",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
@@ -14,5 +14,5 @@
     "docs/history/backlog.md",
     "docs/memory/main.md"
   ],
-  "digest": "e971ef9a4d8f"
+  "digest": "544ba9e97120"
 }

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

@@ -0,0 +1,370 @@
+// harness/code/hooks/awareness.mjs — the inform-never-block hook module.
+// SessionStart: inject the session context block, the ownership index, and a budget-capped drift
+// banner (full report → .claude/state/drift-report.md). PostToolUse (Edit|Write|MultiEdit|Bash):
+// the silent detector — record file→doc touches, append machine-recomputable findings as auto:
+// rows to docs/operations/bookkeeping.md. Never narrates into the session, never blocks, exits 0
+// on every path: everything here is a convenience, absent on any failure.
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import {
+  readStdin,
+  resolveProjectDir,
+  buildIndex,
+  scanFeatureDocs,
+  owningDocs,
+  listRepoFiles,
+  deadGlobs,
+  globToRegExp,
+  frontmatter,
+} from "./lib/ownership.mjs";
+import {
+  readQueue,
+  countRows,
+  formatAutoRow,
+  appendRows,
+  resolveRows,
+  unexpiredWaivers,
+  stateDir,
+  recordTouched,
+} from "./lib/state.mjs";
+
+const today = () => new Date().toISOString().slice(0, 10);
+
+function readSafe(file) {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch (e) {
+    return "";
+  }
+}
+
+function readJsonSafe(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (e) {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// SessionStart
+// ---------------------------------------------------------------------------
+
+function detectPackageManager(projectDir) {
+  const lockfiles = [
+    ["pnpm-lock.yaml", "pnpm"],
+    ["package-lock.json", "npm"],
+    ["yarn.lock", "yarn"],
+    ["bun.lockb", "bun"],
+    ["bun.lock", "bun"],
+  ];
+  for (const [file, manager] of lockfiles) {
+    if (fs.existsSync(path.join(projectDir, file))) return `${manager} (${file} found)`;
+  }
+  return null;
+}
+
+function harnessLine(projectDir) {
+  const marker = readJsonSafe(path.join(projectDir, ".claude", "harness.json"));
+  if (!marker || !marker.version) return null;
+  const structure = readSafe(path.join(projectDir, "docs", "structure.md"));
+  const stamped = (/harness-version:\s*([\w.-]+)/.exec(frontmatter(structure) || structure) || [])[1];
+  const state =
+    stamped === marker.version
+      ? "reconciled"
+      : stamped
+        ? `stamped ${stamped} — behind: run maintenance`
+        : "unstamped — run maintenance";
+  return `Harness: installed ${marker.version} · docs/structure.md ${state}`;
+}
+
+function memoryLine(projectDir) {
+  const dir = path.join(projectDir, "docs", "memory");
+  let entries;
+  try {
+    entries = fs.readdirSync(dir).filter((f) => f.endsWith(".md"));
+  } catch (e) {
+    return null;
+  }
+  return entries.length ? `Memory: ${entries.map((f) => `docs/memory/${f}`).join(", ")}` : null;
+}
+
+function openPlanLines(projectDir) {
+  const dir = path.join(projectDir, "docs", "history", "plans");
+  let entries;
+  try {
+    entries = fs.readdirSync(dir).filter((f) => f.endsWith(".md"));
+  } catch (e) {
+    return [];
+  }
+  const lines = [];
+  for (const file of entries) {
+    const text = readSafe(path.join(dir, file));
+    const status = (/^\*\*Status:\*\*\s*(.+)$/m.exec(text) || [])[1]?.trim();
+    if (!status || /Complete|Abandoned/.test(status)) continue;
+    const gates = (/^\*\*Gates:\*\*\s*(.+)$/m.exec(text) || [])[1]?.trim();
+    const ledgerRows = (text.match(/^\|\s*\d+\s*\|/gm) || []).length;
+    const parts = [`Open plan: ${file} (${status}`];
+    if (gates) parts.push(` · Gates: ${gates}`);
+    if (ledgerRows) parts.push(` · ledger: ${ledgerRows} rows`);
+    lines.push(parts.join("") + ")");
+  }
+  return lines;
+}
+
+// Compute drift facts once; write the full report, return the one-line banner.
+function driftBanner(projectDir) {
+  const repoFiles = listRepoFiles(projectDir);
+  const dead = deadGlobs(projectDir, repoFiles);
+  const queueRows = readQueue(projectDir);
+  const counts = countRows(queueRows);
+  const waivers = unexpiredWaivers(queueRows, "dead-glob", today());
+  const unwaivedDead = dead.filter((d) => !waivers.some((w) => w.body.includes(d.glob)));
+
+  // Docs older than the code they own (doc mtime < newest owned-file mtime).
+  const staleDocs = [];
+  for (const entry of scanFeatureDocs(projectDir)) {
+    let docTime;
+    try {
+      docTime = fs.statSync(path.join(projectDir, entry.doc)).mtimeMs;
+    } catch (e) {
+      continue;
+    }
+    const res = entry.owns.map((g) => globToRegExp(g));
+    let newest = 0;
+    for (const file of repoFiles) {
+      if (!res.some((re) => re.test(file))) continue;
+      try {
+        newest = Math.max(newest, fs.statSync(path.join(projectDir, file)).mtimeMs);
+      } catch (e) {
+        /* deleted between walk and stat */
+      }
+    }
+    if (newest > docTime) staleDocs.push(entry.doc);
+  }
+
+  const report = [
+    `# Drift report — generated ${new Date().toISOString()}`,
+    "",
+    `## Dead owns: globs (${dead.length}, ${dead.length - unwaivedDead.length} waived)`,
+    ...dead.map((d) => `- ${d.glob} → ${d.doc}${unwaivedDead.includes(d) ? "" : " (waived)"}`),
+    "",
+    `## Docs older than owned code (${staleDocs.length})`,
+    ...staleDocs.map((d) => `- ${d}`),
+    "",
+    `## Bookkeeping queue (${counts.unresolved} unresolved: ${counts.auto} auto · ${counts.note} note · ${counts.needsSession} needs-session · ${counts.waived} waived)`,
+  ].join("\n");
+  try {
+    fs.writeFileSync(path.join(stateDir(projectDir), "drift-report.md"), report + "\n");
+  } catch (e) {
+    /* report is a convenience */
+  }
+
+  if (dead.length === 0 && staleDocs.length === 0 && counts.unresolved === 0) return null;
+  const waivedNote = dead.length
+    ? unwaivedDead.length === 0
+      ? " (all waived)"
+      : ` (${unwaivedDead.length} UNWAIVED)`
+    : "";
+  return (
+    `Drift: ${dead.length} dead owns: glob(s)${waivedNote} · ${staleDocs.length} doc(s) older than owned code · ` +
+    `bookkeeping: ${counts.unresolved} unresolved row(s) — full report: .claude/state/drift-report.md`
+  );
+}
+
+function sessionStart(projectDir) {
+  const lines = [];
+  const pm = detectPackageManager(projectDir);
+  if (pm) lines.push(`Package manager: ${pm}`);
+  const harness = harnessLine(projectDir);
+  if (harness) lines.push(harness);
+  const memory = memoryLine(projectDir);
+  if (memory) lines.push(memory);
+  lines.push(...openPlanLines(projectDir).slice(0, 4));
+  try {
+    const drift = driftBanner(projectDir);
+    if (drift) lines.push(drift);
+  } catch (e) {
+    /* the banner is optional; the index below still injects */
+  }
+  const block = lines.length
+    ? "# Session context (generated — a convenience, never a gate)\n" + lines.slice(0, 10).join("\n")
+    : "";
+  const index = buildIndex(projectDir);
+  const context = [block, index].filter(Boolean).join("\n\n");
+  if (!context) return;
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: context },
+    })
+  );
+}
+
+// ---------------------------------------------------------------------------
+// PostToolUse — the silent detector
+// ---------------------------------------------------------------------------
+
+const SOURCE_EXT = /\.(m?[jt]sx?|py|rs|go|rb|java|kt|swift|c|h|cpp|hpp|cs|sh|sql|css|scss|vue|svelte)$/;
+
+function relIfInside(projectDir, filePath) {
+  if (!filePath) return null;
+  const rel = path.relative(projectDir, path.resolve(projectDir, filePath));
+  if (rel.startsWith("..") || path.isAbsolute(rel)) return null;
+  return rel.split(path.sep).join("/");
+}
+
+// Spawn the installed doc-lint over one file; returns finding lines (empty when absent/clean).
+function docLint(projectDir, rel) {
+  const script = path.join(projectDir, ".claude", "skills", "documentation", "scripts", "doc-lint.mjs");
+  if (!fs.existsSync(script)) return [];
+  const res = spawnSync("node", [script, rel], { cwd: projectDir, encoding: "utf8", timeout: 5000 });
+  const out = `${res.stdout || ""}`;
+  return out.split("\n").filter((line) => /:\d+ \[(block|warn)\]/.test(line));
+}
+
+// True when a source file's first lines carry its repo-relative path (the header-comment rule).
+function hasHeaderComment(projectDir, rel) {
+  const head = readSafe(path.join(projectDir, rel)).split("\n").slice(0, 5).join("\n");
+  return head.includes(rel) || head.includes(path.basename(rel));
+}
+
+function detectorForFile(projectDir, rel, meta, rows) {
+  const owners = owningDocs(projectDir, rel);
+  recordTouched(projectDir, rel, owners.map((o) => o.doc));
+
+  if (rel.endsWith(".md")) {
+    // An edited doc resolves any doc-implicated row that pointed at it.
+    resolveRows(projectDir, (row) => row.kind === "auto" && row.body.includes("doc-implicated") && row.body.includes(rel));
+    if (rel.startsWith("docs/")) {
+      const findings = docLint(projectDir, rel);
+      if (findings.length) {
+        rows.push(
+          formatAutoRow({
+            ...meta,
+            kind: "doc-lint",
+            description: `${rel} has ${findings.length} doc-lint finding(s)`,
+            action: `fix or doc-lint-disable with reason`,
+          })
+        );
+      }
+    }
+    const segment = rel.split("/")[1];
+    if (rel.startsWith("docs/") && segment && !segment.endsWith(".md")) {
+      const structure = readSafe(path.join(projectDir, "docs", "structure.md"));
+      if (structure && !structure.includes(`${segment}/`) && !structure.includes(`docs/${segment}`)) {
+        rows.push(
+          formatAutoRow({
+            ...meta,
+            kind: "doc-placement",
+            description: `${rel} sits in a folder absent from docs/structure.md's authority map`,
+            action: "move the doc per the add-a-doc table, or record the new folder in structure.md",
+          })
+        );
+      }
+    }
+    if (rel.startsWith("docs/features/") && !readSafe(path.join(projectDir, "docs", "README.md")).includes(path.basename(rel))) {
+      rows.push(
+        formatAutoRow({
+          ...meta,
+          kind: "index-row-missing",
+          description: `${rel} is not linked from docs/README.md`,
+          action: "add its row to the Features index",
+        })
+      );
+    }
+    return;
+  }
+
+  if (SOURCE_EXT.test(rel)) {
+    if (!hasHeaderComment(projectDir, rel)) {
+      rows.push(
+        formatAutoRow({
+          ...meta,
+          kind: "header-missing",
+          description: `${rel} lacks its file-path header comment`,
+          action: "add the header comment",
+        })
+      );
+    }
+    for (const owner of owners) {
+      rows.push(
+        formatAutoRow({
+          ...meta,
+          kind: "doc-implicated",
+          description: `${rel} changed; owning doc ${owner.doc} may need an update (doc-implicated: ${owner.doc})`,
+          action: "update the doc or delete this row if no documented behavior changed",
+        })
+      );
+    }
+    if (/(schema|init\.sql|migration|auth|webhook|\benv\b|wrangler)/i.test(rel)) {
+      rows.push(
+        formatAutoRow({
+          ...meta,
+          kind: "boundary-scan-suggested",
+          description: `${rel} is contract-heavy`,
+          action: "run the boundary skill scoped to the diff",
+        })
+      );
+    }
+  }
+}
+
+function detectRenames(projectDir, command, meta, rows) {
+  if (!/\bgit mv\b|\bmv\b/.test(command || "")) return;
+  for (const { glob, doc } of deadGlobs(projectDir)) {
+    rows.push(
+      formatAutoRow({
+        ...meta,
+        kind: "dead-glob",
+        description: `owns: glob \`${glob}\` in ${doc} matches no files`,
+        action: `update the doc's owns: frontmatter`,
+      })
+    );
+  }
+}
+
+function postToolUse(projectDir, payload) {
+  const meta = {
+    date: today(),
+    sessionId: payload.session_id,
+    transcriptPath: payload.transcript_path,
+    ts: new Date().toISOString(),
+  };
+  const input = payload.tool_input || {};
+  const rows = [];
+  if (payload.tool_name === "Bash") {
+    detectRenames(projectDir, input.command, meta, rows);
+  } else {
+    const rel = relIfInside(projectDir, input.file_path || input.notebook_path);
+    if (rel) detectorForFile(projectDir, rel, meta, rows);
+    // Editing a feature doc's frontmatter can orphan globs the same way a rename can.
+    if (rel && rel.startsWith("docs/features/")) detectRenames(projectDir, "git mv", meta, rows);
+  }
+  appendRows(projectDir, rows);
+}
+
+// ---------------------------------------------------------------------------
+
+function main() {
+  const raw = readStdin();
+  let payload = {};
+  try {
+    payload = raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    payload = {};
+  }
+  const projectDir = resolveProjectDir(payload);
+  const event = payload.hook_event_name || "SessionStart";
+  if (event === "PostToolUse") postToolUse(projectDir, payload);
+  else sessionStart(projectDir);
+}
+
+try {
+  main();
+} catch (e) {
+  // Inform-only module: on any failure, inject nothing, write nothing, never block.
+} finally {
+  process.exit(0);
+}

package/data/harnesses/apollo/hooks/check-bookkeeping-clean.mjs

@@ -0,0 +1,19 @@
+// harness/code/hooks/check-bookkeeping-clean.mjs — CI backstop: no unresolved bookkeeping rows
+// (auto:/note:/needs-session:) may reach the remote. waived: rows pass — they are the recorded,
+// PR-reviewable exceptions. Exit 1 when unresolved rows exist.
+
+import { readQueue, countRows } from "./lib/state.mjs";
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const counts = countRows(readQueue(projectDir));
+
+if (counts.unresolved === 0) {
+  console.log(`check-bookkeeping-clean: OK (${counts.waived} waived row(s))`);
+  process.exit(0);
+}
+console.error(
+  `check-bookkeeping-clean: ${counts.unresolved} unresolved row(s) in docs/operations/bookkeeping.md ` +
+    `(${counts.auto} auto, ${counts.note} note, ${counts.needsSession} needs-session). ` +
+    "Drain them (bookkeeper agent), resolve them, or convert to waived: with reason + expires=."
+);
+process.exit(1);

package/data/harnesses/apollo/hooks/check-changelog-presence.mjs

@@ -0,0 +1,48 @@
+// harness/code/hooks/check-changelog-presence.mjs — CI backstop: the commit under test (HEAD)
+// carries a docs/history/changelog/ entry unless it is exempt by the changelog rule's closed list,
+// judged mechanically: lockfile-only, harness-file-only, pure renames, changelog housekeeping,
+// or a bot author. Exit 1 when a non-exempt HEAD stages no entry.
+
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+function git(args) {
+  const res = spawnSync("git", args, { cwd: projectDir, encoding: "utf8" });
+  return res.status === 0 ? (res.stdout || "").trim() : null;
+}
+
+const nameStatus = git(["diff-tree", "--root", "--no-commit-id", "--name-status", "-r", "HEAD"]) || "";
+const entries = nameStatus
+  .split("\n")
+  .filter(Boolean)
+  .map((line) => {
+    const [status, ...files] = line.split("\t");
+    return { status, file: files[files.length - 1] };
+  });
+
+const LOCKFILES = /^(pnpm-lock\.yaml|package-lock\.json|yarn\.lock|bun\.lockb?|Cargo\.lock)$/;
+const exemptFile = (f) =>
+  LOCKFILES.test(path.basename(f)) ||
+  f.startsWith(".claude/") ||
+  f === "AGENTS.md" ||
+  f === "CLAUDE.md" ||
+  f.startsWith("docs/history/changelog/") ||
+  f === "docs/history/CHANGELOG.md";
+
+const author = git(["log", "-1", "--format=%an <%ae>"]) || "";
+const isBot = /\[bot\]|actions@github\.com/i.test(author);
+const allRenames = entries.length > 0 && entries.every((e) => e.status.startsWith("R"));
+const allExempt = entries.length === 0 || entries.every((e) => exemptFile(e.file));
+const hasEntry = entries.some((e) => e.file.startsWith("docs/history/changelog/") && e.file.endsWith(".md"));
+
+if (isBot || allRenames || allExempt || hasEntry) {
+  console.log("check-changelog-presence: OK");
+  process.exit(0);
+}
+console.error(
+  "check-changelog-presence: HEAD is a non-exempt commit carrying no docs/history/changelog/ entry. " +
+    "Every non-exempt commit ships its entry inside it (exempt: release/bot, lockfile-only, pure renames, changelog housekeeping)."
+);
+process.exit(1);

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

@@ -0,0 +1,68 @@
+// harness/code/hooks/check-completion-integrity.mjs — CI backstop for plan completion. Scope:
+// plans in the Gates: format only (legacy plans predate the contract and are history). A Complete
+// plan must show a fully discharged surface: no unchecked Done Criteria boxes, the Spec'd LLD
+// flipped active, and the behavioral checklist present. An Abandoned plan must reference the
+// backlog (undischarged obligations outlive the frozen file there). Exit 1 on any violation.
+
+import fs from "node:fs";
+import path from "node:path";
+import { frontmatter, field } from "./lib/ownership.mjs";
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const plansDir = path.join(projectDir, "docs", "history", "plans");
+
+function readSafe(file) {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch (e) {
+    return "";
+  }
+}
+
+let failures = 0;
+const fail = (msg) => {
+  failures += 1;
+  console.error(`check-completion-integrity: ${msg}`);
+};
+
+let plans = [];
+try {
+  plans = fs.readdirSync(plansDir).filter((f) => f.endsWith(".md"));
+} catch (e) {
+  plans = [];
+}
+
+for (const file of plans) {
+  const text = readSafe(path.join(plansDir, file));
+  if (!/^\*\*Gates:\*\*/m.test(text)) continue; // legacy plan — out of contract
+  const status = (/^\*\*Status:\*\*\s*(\S+)/m.exec(text) || [])[1];
+
+  if (status === "Complete") {
+    const unchecked = (text.match(/^- \[ \]/gm) || []).length;
+    if (unchecked > 0) fail(`${file} is Complete with ${unchecked} unchecked Done Criteria box(es)`);
+
+    const spec = (/^\*\*Spec:\*\*\s*\[[^\]]*\]\(([^)]+)\)/m.exec(text) || [])[1];
+    if (spec) {
+      const specPath = path.resolve(plansDir, spec);
+      const specText = readSafe(specPath);
+      const specStatus = (field(frontmatter(specText), "status") || "").toString();
+      if (specText && specStatus !== "active") {
+        fail(`${file} is Complete but its Spec LLD is status: ${specStatus || "unknown"} (expected active)`);
+      }
+      const feature = path.basename(specPath, ".md");
+      if (!fs.existsSync(path.join(projectDir, "docs", "tests", `${feature}.md`))) {
+        fail(`${file} is Complete but docs/tests/${feature}.md (the behavioral checklist) is missing`);
+      }
+    }
+  }
+
+  if (status === "Abandoned" && !/backlog/i.test(text)) {
+    fail(`${file} is Abandoned without referencing the backlog — undischarged obligations must outlive the frozen plan`);
+  }
+}
+
+if (failures === 0) {
+  console.log("check-completion-integrity: OK");
+  process.exit(0);
+}
+process.exit(1);