@nurix/etna 0.19.43 → 0.19.45

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

@@ -0,0 +1,223 @@
+// harness/code/hooks/lib/ownership.mjs — frontmatter scan + owns:-glob resolution, shared by the
+// hook entrypoints (awareness, compliance) and the CI checks so gates and pipeline cannot disagree.
+// Everything here is read-only over docs/features/ and the source tree; no network, no deps.
+
+import fs from "node:fs";
+import path from "node:path";
+
+// Read all of stdin synchronously; returns "" if nothing is piped.
+export function readStdin() {
+  try {
+    return fs.readFileSync(0, "utf8");
+  } catch (e) {
+    return "";
+  }
+}
+
+// Resolve the project root: CLAUDE_PROJECT_DIR env, else payload cwd, else process cwd.
+export function resolveProjectDir(payload) {
+  return process.env.CLAUDE_PROJECT_DIR || (payload && payload.cwd) || process.cwd();
+}
+
+// Recursively collect every .md file under dir (returns [] if the dir is absent).
+export function listMarkdown(dir) {
+  const out = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (e) {
+    return out;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...listMarkdown(full));
+    else if (entry.isFile() && entry.name.endsWith(".md")) out.push(full);
+  }
+  return out;
+}
+
+// Pull the leading `--- … ---` frontmatter block; "" if the file has none.
+export function frontmatter(text) {
+  const m = /^?---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  return m ? m[1] : "";
+}
+
+// Trim surrounding whitespace, then strip one layer of matching quotes.
+export function unquote(s) {
+  return String(s).trim().replace(/^["']|["']$/g, "").trim();
+}
+
+// One YAML list/array item → clean value: a quoted item ends at its closing quote
+// (anything after — trailing comments — drops); an unquoted item ends at ` #`.
+export function cleanItem(s) {
+  const t = String(s).trim();
+  const q = t[0];
+  if (q === '"' || q === "'") {
+    const end = t.indexOf(q, 1);
+    if (end > 0) return t.slice(1, end).trim();
+  }
+  const hash = t.search(/\s#/);
+  return unquote(hash >= 0 ? t.slice(0, hash) : t);
+}
+
+// `[a, b] # comment` → items; content ends at the closing bracket, not the line end.
+function parseInlineArray(raw) {
+  const end = raw.indexOf("]");
+  const body = (end >= 0 ? raw.slice(0, end) : raw).replace(/^\[/, "");
+  return body.split(",").map((s) => cleanItem(s)).filter(Boolean);
+}
+
+// Read one frontmatter key: scalar (`k: v`), inline array (`k: [a, b]`), or a following `- item` block.
+// Returns a string for scalars, an array for lists, or undefined when the key is absent.
+export function field(block, key) {
+  const lines = block.split(/\r?\n/);
+  const head = new RegExp(`^${key}\\s*:\\s*(.*)$`);
+  for (let i = 0; i < lines.length; i++) {
+    const m = head.exec(lines[i]);
+    if (!m) continue;
+    const raw = m[1].trim();
+    if (raw === "") {
+      // A bare key may continue as an indented inline array on the next line, or a `- item` block.
+      const next = (lines[i + 1] || "").trim();
+      if (next.startsWith("[")) {
+        return parseInlineArray(next);
+      }
+      const items = [];
+      for (let j = i + 1; j < lines.length; j++) {
+        const li = /^\s*-\s+(.*)$/.exec(lines[j]);
+        if (!li) break;
+        items.push(cleanItem(li[1]));
+      }
+      return items;
+    }
+    if (raw.startsWith("[")) {
+      return parseInlineArray(raw);
+    }
+    return unquote(raw);
+  }
+  return undefined;
+}
+
+// Coerce a field that may be scalar/array/undefined into a clean string array.
+export function asList(v) {
+  if (v == null) return [];
+  return (Array.isArray(v) ? v : [v]).map((s) => String(s).trim()).filter(Boolean);
+}
+
+// Scan docs/features/**/*.md and return one entry per feature doc that declares owns:.
+// Shape: { doc (repo-relative, /-separated), owns[], module, keywords[], status }.
+export function scanFeatureDocs(projectDir) {
+  const featuresDir = path.join(projectDir, "docs", "features");
+  const files = listMarkdown(featuresDir);
+  const docs = [];
+  for (const file of files) {
+    let text;
+    try {
+      text = fs.readFileSync(file, "utf8");
+    } catch (e) {
+      continue;
+    }
+    const block = frontmatter(text);
+    if (!block) continue;
+    const owns = asList(field(block, "owns"));
+    if (owns.length === 0) continue;
+    docs.push({
+      doc: path.relative(projectDir, file).split(path.sep).join("/"),
+      owns,
+      module: (field(block, "module") || "—").toString(),
+      keywords: asList(field(block, "keywords")),
+      status: (field(block, "status") || "active").toString().toLowerCase(),
+    });
+  }
+  return docs;
+}
+
+// Build the ownership index text from every feature doc's frontmatter.
+export function buildIndex(projectDir) {
+  const docs = scanFeatureDocs(projectDir);
+  const lines = [];
+  let deprecated = 0;
+  for (const entry of docs) {
+    if (entry.status === "deprecated") {
+      deprecated += 1;
+      continue; // keep deprecated docs out of the routing lines
+    }
+    const kw = entry.keywords.length ? `[${entry.keywords.join(", ")}]` : "[]";
+    for (const glob of entry.owns) {
+      lines.push(`${glob} → ${entry.doc} · ${entry.module} · ${kw} · ${entry.status}`);
+    }
+  }
+  if (lines.length === 0) return "";
+  lines.sort();
+  const header =
+    "# Ownership index (generated) — code-path glob → owning feature doc · module · keywords · status\n" +
+    "# Match the file or topic you're about to touch, then read the owning doc before changing it.\n";
+  const footer = deprecated > 0 ? `\n# (${deprecated} deprecated feature doc(s) omitted)` : "";
+  return header + lines.join("\n") + footer;
+}
+
+// Compile one owns:-style glob (`**` any depth, `*` within a segment) to a RegExp
+// over /-separated repo-relative paths. `a/**` also matches `a` itself.
+export function globToRegExp(glob) {
+  const g = glob.replace(/\\/g, "/").replace(/\/+$/, "");
+  const escaped = g.replace(/[\\^$.|?+()[\]{}]/g, "\\$&");
+  const re = escaped
+    .replace(/\/\*\*$/, "\0TAIL\0") // `x/**` → x plus optionally anything below it
+    .replace(/\*\*\//g, "\0LEAD\0") // `**/x` → any (possibly empty) directory prefix
+    .replace(/\*\*/g, "\0ANY\0")
+    .replace(/\*/g, "[^/]*")
+    .replace(/\0TAIL\0/g, "(?:/.*)?")
+    .replace(/\0LEAD\0/g, "(?:.*/)?")
+    .replace(/\0ANY\0/g, ".*");
+  return new RegExp(`^${re}$`);
+}
+
+// Feature docs owning the given repo-relative path (deprecated docs excluded).
+export function owningDocs(projectDir, relPath) {
+  const rel = relPath.split(path.sep).join("/");
+  const out = [];
+  for (const entry of scanFeatureDocs(projectDir)) {
+    if (entry.status === "deprecated") continue;
+    if (entry.owns.some((g) => globToRegExp(g).test(rel))) out.push(entry);
+  }
+  return out;
+}
+
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", ".claude", ".codex"]);
+
+// Walk the repo once and return every tracked-ish file path (repo-relative, /-separated).
+// Used to detect dead globs; heavy dirs are skipped, depth is bounded by the tree itself.
+export function listRepoFiles(projectDir) {
+  const out = [];
+  function walk(dir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (e) {
+      return;
+    }
+    for (const entry of entries) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile()) out.push(path.relative(projectDir, full).split(path.sep).join("/"));
+    }
+  }
+  walk(projectDir);
+  return out;
+}
+
+// Globs across all feature docs that match zero files on disk.
+// Returns [{ glob, doc }]; pass a precomputed file list to amortize the walk.
+export function deadGlobs(projectDir, repoFiles) {
+  const files = repoFiles || listRepoFiles(projectDir);
+  const dead = [];
+  for (const entry of scanFeatureDocs(projectDir)) {
+    if (entry.status === "deprecated") continue;
+    for (const glob of entry.owns) {
+      const re = globToRegExp(glob);
+      if (!files.some((f) => re.test(f))) dead.push({ glob, doc: entry.doc });
+    }
+  }
+  return dead;
+}

package/data/harnesses/apollo/hooks/lib/state.mjs

@@ -0,0 +1,156 @@
+// harness/code/hooks/lib/state.mjs — the bookkeeping queue (docs/operations/bookkeeping.md) and the
+// machine-local state dir (.claude/state/). The row grammar is the contract between the awareness
+// detector (writer), the bookkeeper agent (drain), the compliance gates (walls), and CI (backstop):
+//   - auto: {YYYY-MM-DD} · {finding-kind} · {description} → {action} | sid={session_id} tp={transcript_path} ts={ISO}
+//   - note: {YYYY-MM-DD} · {area} · {context} → lands-in: {owning doc | backlog | memory} | sid=… tp=… ts=…
+//   - needs-session: {YYYY-MM-DD} · {what could not be grounded} → main session resolves | refs={ts}
+//   - waived: {YYYY-MM-DD} · {what is deferred} · reason: {why} → expires={YYYY-MM-DD}
+// Unresolved = auto + note + needs-session. waived: rows are resolved history until expires= passes.
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const QUEUE_PATH = ["docs", "operations", "bookkeeping.md"];
+
+export const QUEUE_HEADER = `# Bookkeeping
+
+The shared work queue keeping documentation and code in sync — rows are appended mechanically (auto:) and by working sessions (note:), drained by the bookkeeper agent, and walled at commit: a commit is possible only when every row is resolved or waived. Row grammar and lifecycle: the behavioral-hooks feature doc. A \`waived:\` row carries \`expires=\` and is PR-reviewable history.
+`;
+
+export function queueFile(projectDir) {
+  return path.join(projectDir, ...QUEUE_PATH);
+}
+
+const ROW_RE = /^-\s+(auto|note|needs-session|waived):\s+(.*)$/;
+
+// Parse the queue text into rows: { kind, date, body, raw }. Non-row lines are ignored.
+export function parseQueue(text) {
+  const rows = [];
+  for (const line of String(text || "").split(/\r?\n/)) {
+    const m = ROW_RE.exec(line.trim());
+    if (!m) continue;
+    const body = m[2].trim();
+    const date = (/^(\d{4}-\d{2}-\d{2})/.exec(body) || [])[1] || "";
+    rows.push({ kind: m[1], date, body, raw: line });
+  }
+  return rows;
+}
+
+export function readQueue(projectDir) {
+  try {
+    return parseQueue(fs.readFileSync(queueFile(projectDir), "utf8"));
+  } catch (e) {
+    return [];
+  }
+}
+
+// Counts by kind; `unresolved` is the number the walls act on.
+export function countRows(rows) {
+  const c = { auto: 0, note: 0, needsSession: 0, waived: 0 };
+  for (const row of rows) {
+    if (row.kind === "auto") c.auto += 1;
+    else if (row.kind === "note") c.note += 1;
+    else if (row.kind === "needs-session") c.needsSession += 1;
+    else if (row.kind === "waived") c.waived += 1;
+  }
+  c.unresolved = c.auto + c.note + c.needsSession;
+  return c;
+}
+
+// Format one auto: row per the grammar; sid/tp/ts come from the hook payload.
+export function formatAutoRow({ date, kind, description, action, sessionId, transcriptPath, ts }) {
+  return `- auto: ${date} · ${kind} · ${description} → ${action} | sid=${sessionId || "-"} tp=${transcriptPath || "-"} ts=${ts || "-"}`;
+}
+
+// Append rows to the queue, creating the file with its genre header when absent.
+// Dedupes on the row text before the `| sid=` tail, so a re-fired detector never stacks duplicates.
+export function appendRows(projectDir, rowLines) {
+  if (!rowLines || rowLines.length === 0) return 0;
+  const file = queueFile(projectDir);
+  let text = "";
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch (e) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    text = QUEUE_HEADER + "\n";
+  }
+  const key = (line) => line.split("| sid=")[0].trim();
+  const existing = new Set(parseQueue(text).map((r) => key(r.raw)));
+  const fresh = rowLines.filter((line) => !existing.has(key(line)));
+  if (fresh.length === 0) return 0;
+  if (!text.endsWith("\n")) text += "\n";
+  fs.writeFileSync(file, text + fresh.join("\n") + "\n");
+  return fresh.length;
+}
+
+// Delete queue rows matching the predicate (used by the detector to auto-resolve
+// rows whose finding the session has since addressed). Returns the count removed.
+export function resolveRows(projectDir, predicate) {
+  const file = queueFile(projectDir);
+  let text;
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch (e) {
+    return 0;
+  }
+  let removed = 0;
+  const kept = text.split(/\r?\n/).filter((line) => {
+    const m = ROW_RE.exec(line.trim());
+    if (!m) return true;
+    const row = { kind: m[1], body: m[2].trim(), raw: line };
+    if (predicate(row)) {
+      removed += 1;
+      return false;
+    }
+    return true;
+  });
+  if (removed > 0) fs.writeFileSync(file, kept.join("\n"));
+  return removed;
+}
+
+// Unexpired waived rows for a finding kind (the dead-glob allowlist CI honors).
+// A waived row covers a glob when its body names it verbatim.
+export function unexpiredWaivers(rows, kind, today) {
+  return rows.filter((row) => {
+    if (row.kind !== "waived") return false;
+    if (kind && !row.body.includes(kind)) return false;
+    const expires = (/expires=(\d{4}-\d{2}-\d{2})/.exec(row.body) || [])[1];
+    if (!expires) return false;
+    return expires >= today;
+  });
+}
+
+// Ensure .claude/state/ exists and is self-ignoring (a `*` .gitignore inside it),
+// so consumers never see machine-local state as untracked noise. Returns the dir.
+export function stateDir(projectDir) {
+  const dir = path.join(projectDir, ".claude", "state");
+  fs.mkdirSync(dir, { recursive: true });
+  const ignore = path.join(dir, ".gitignore");
+  if (!fs.existsSync(ignore)) fs.writeFileSync(ignore, "*\n");
+  return dir;
+}
+
+// Session-scoped ask memory: an `ask` gate fires once per (session, class); after the user has
+// answered it once, repeats in the same session pass silently (the runtime's own permission
+// prompts still apply). Records live in .claude/state/asked.tsv — machine-local, self-ignored.
+export function askedThisSession(projectDir, sessionId, key) {
+  if (!sessionId) return false;
+  try {
+    const text = fs.readFileSync(path.join(projectDir, ".claude", "state", "asked.tsv"), "utf8");
+    return text.split("\n").includes(`${sessionId}\t${key}`);
+  } catch (e) {
+    return false;
+  }
+}
+
+export function recordAsked(projectDir, sessionId, key) {
+  if (!sessionId) return;
+  fs.appendFileSync(path.join(stateDir(projectDir), "asked.tsv"), `${sessionId}\t${key}\n`);
+}
+
+// Append one tab-separated line to .claude/state/touched.tsv (file → owning doc map for the session).
+export function recordTouched(projectDir, relPath, docs) {
+  const dir = stateDir(projectDir);
+  const line = `${new Date().toISOString()}\t${relPath}\t${docs.join(",") || "-"}\n`;
+  fs.appendFileSync(path.join(dir, "touched.tsv"), line);
+}

package/data/harnesses/apollo/skills/boundary/SKILL.md

@@ -61,9 +61,11 @@ The packs are a floor, not a fence: report any contract that passes the ships-gr
 
    **BLOCK** = any CRITICAL. HIGH findings yield **PASS WITH AMENDMENTS** — fold the amendments into the plan before coding. Order amendments sequencing-first: many violations dissolve by reordering steps (expand-then-contract, migrate-before-code) rather than changing what ships — prefer that fix, drawn from the entry's safe-change sequence.
 
+6. **Record the verdict in the plan's `Gates:` line.** Rewrite only your own segment, to exactly `Boundary: passed YYYY-MM-DD` (PASS, or PASS WITH AMENDMENTS once the amendments are folded) or `Boundary: blocked YYYY-MM-DD` (BLOCK). The compliance hook greps these exact forms — implementation edits stay blocked while the segment reads `pending`. A plan with no `Gates:` line predates the format; add the line rather than skipping the write-back.
+
 ## Rules
 
-- **Read-only.** You never edit the plan, the code, or any doc. The user folds your amendments into the plan.
+- **Read-only, one exception.** You never edit the plan's content, the code, or any doc — the user folds your amendments into the plan. The single write you own is the plan's `Gates:` line (step 6), your segment only.
 - **Verify in source.** Never flag from plan text alone — read both sides of every finding and cite them: code as `file:line`, doctrine as the doc path.
 - **No other side, no violation.** An intersection with no traced consumer and no doctrine behind it isn't a violation — it's a **new edge**: report it in its own section with the hardening its mechanism prescribes (version the cache key now, make the enum append-only now), so the fragile edge is born safe.
 - **A clean report is valid.** Zero violations means say so — the coverage table is the evidence it was checked, not skipped. Don't pad findings.

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

@@ -73,6 +73,8 @@ 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) |
+| 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) |
 | Add to protected files | [`templates/protected-files.md`](templates/protected-files.md) |
 | Create/update root README | [`templates/root-readme.md`](templates/root-readme.md) |

package/data/harnesses/apollo/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 |
+| 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 |
 | docs/README.md (doc index) | [docs-readme.md](docs-readme.md) | Truth |
@@ -23,6 +24,7 @@ One file per template. Every template is either a **truth document** (states cur
 | Plan | [plan.md](plan.md) | Record |
 | Changelog entry | [changelog-entry.md](changelog-entry.md) | Record |
 | Migration runbook | [migration-runbook.md](migration-runbook.md) | Record |
+| Journal | [journal.md](journal.md) | Record (append-only) |
 | CHANGELOG master index | [changelog-index.md](changelog-index.md) | Record index (append-only) |
 | Backlog | [backlog.md](backlog.md) | Record (append-only) |
 | Memory (main agent) | [memory-main.md](memory-main.md) | Record (append-only ledger) |

package/data/harnesses/apollo/skills/documentation/templates/bookkeeping.md

@@ -0,0 +1,18 @@
+# Bookkeeping ledger (docs/operations/bookkeeping.md)
+
+Truth document with an unusual lifecycle: a **work queue**, not an archive. Rows are appended mechanically by the awareness hook (`auto:`) and deliberately by working sessions (`note:`), drained by the `bookkeeper` agent, and walled at Stop and commit — a commit is possible only when every row is resolved (deleted) or converted to `waived:`. What survives in git — `waived:` and `needs-session:` rows — is exactly what a PR reviewer should see.
+
+The row grammar is machine-read by the hooks and CI; keep it exact. A `waived:` row's `expires=` date is enforced: CI honors the waiver until the date, then fails. `waived:` rows whose finding kind is `dead-glob` double as the dead-glob allowlist.
+
+```
+# Bookkeeping
+
+The shared work queue keeping documentation and code in sync — rows are appended mechanically (auto:) and by working sessions (note:), drained by the bookkeeper agent, and walled at commit: a commit is possible only when every row is resolved or waived. Row grammar and lifecycle: the behavioral-hooks feature doc. A `waived:` row carries `expires=` and is PR-reviewable history.
+
+- auto: YYYY-MM-DD · {finding-kind} · {description} → {action} | sid={session_id} tp={transcript_path} ts={ISO}
+- note: YYYY-MM-DD · {area} · {one-line context only the session holds} → lands-in: {owning doc | backlog | memory} | sid=… tp=… ts=…
+- needs-session: YYYY-MM-DD · {what the bookkeeper could not ground} → main session resolves | refs={original row ts}
+- waived: YYYY-MM-DD · {what is deferred} · reason: {why} → expires=YYYY-MM-DD
+```
+
+Finding kinds for `auto:`: `dead-glob` · `doc-implicated` · `doc-lint` · `header-missing` · `index-row-missing` · `boundary-scan-suggested` · `doc-placement`.

package/data/harnesses/apollo/skills/documentation/templates/journal.md

@@ -0,0 +1,13 @@
+# Journal (docs/history/journal.md)
+
+Record — append-only. Use for: durable mid-execution knowledge — a fact discovered while building that some owning doc will eventually carry, captured the moment it exists so it survives the session. A row is resolved by landing in its owning doc: the row is deleted and the changelog entry cites it. The file stays short by construction; a journal that only grows is a queue nobody drains.
+
+One line per fact. Never narrative, never progress notes (progress lives in the plan), never user preferences (those go to the runtime's memory store).
+
+```
+# Journal
+
+Append-only capture of mid-execution knowledge — one line per fact, written the moment it exists, resolved by landing in its owning doc (delete the row, cite it in the changelog entry). Format: `YYYY-MM-DD · <area> · <one-line fact> → lands-in: <owning doc | backlog | memory>`
+
+- YYYY-MM-DD · {area} · {one-line fact} → lands-in: {owning doc | backlog | memory}
+```

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

@@ -4,10 +4,13 @@ Record. Use for: every implementation plan. Plans are created here directly with
 
 The `boundary` skill parses the **Proposed Changes** sections to check boundary impact before execution, and the `test-plan` skill writes a **Test Obligations** section into the plan at the same gate. Keep that structure stable — section headings and bullet shape are load-bearing for the parsers, and the Test Obligations table is the ledger the verification gate discharges before the plan may reach `Status: Complete`.
 
+The **`Gates:`** line is machine-read: the compliance hook greps exactly the forms below, and implementation edits are blocked while a segment reads `pending`. Each gate skill rewrites only its own segment when it runs — `boundary` to `Boundary: passed YYYY-MM-DD` or `Boundary: blocked YYYY-MM-DD`; `test-plan` to `Test-plan: written YYYY-MM-DD (N rows)`. Never hand-edit the line to skip a gate.
+
 ```
 # {Feature Name}
 
 **Status:** Draft | In Progress | Complete | Abandoned
+**Gates:** Boundary: pending · Test-plan: pending
 **Spec:** [docs/features/{feature}.md](../../features/{feature}.md)
 **Started:** YYYY-MM-DD
 **Completed:** YYYY-MM-DD   <!-- fill when status flips to Complete -->

package/data/harnesses/apollo/skills/test-plan/SKILL.md

@@ -73,6 +73,8 @@ An e2e obligation (a scenario in the project's e2e tree per `testing.md`) is ear
 
    A behavior with no obligation is stated too, with the reason (compiler-guarded, covered by an existing test) — an empty cell reads as "not yet analyzed"; an explicit "none — compiler-guarded" reads as "checked."
 
+6. **Record the write in the plan's `Gates:` line.** Rewrite only your own segment, to exactly `Test-plan: written YYYY-MM-DD (N rows)` where N is the ledger's row count. The compliance hook greps this exact form. A plan with no `Gates:` line predates the format; add the line rather than skipping the write-back.
+
 ## Rules
 
 - **Manifest only.** You write the Test Obligations section into the plan and a chat summary. You write **no** test files and **no** `docs/tests/` checklist — those are verification-gate-time and Completion-time, owned by others.

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

@@ -1,12 +1,12 @@
 {
   "harness": "code",
   "name": "code",
-  "version": "3.5.9",
+  "version": "3.5.11",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
   "seeds": [],
-  "digest": "b48a9de4fe22"
+  "digest": "132494301fd0"
 }