@nurix/etna 0.19.43 → 0.19.44

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

@@ -1,12 +1,12 @@
 {
   "harness": "delivery",
   "name": "delivery",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
   "seeds": [],
-  "digest": "ee08c0d0162a"
+  "digest": "dd6fdce1e2aa"
 }

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

@@ -1,12 +1,12 @@
 {
   "harness": "etna",
   "name": "etna",
-  "version": "1.3.8",
+  "version": "1.3.9",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
   "seeds": [],
-  "digest": "91acf558021c"
+  "digest": "12d918b0c33e"
 }

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

@@ -1,6 +1,6 @@
 {
     "name": "@nurix/etna",
-    "version": "0.19.43",
+    "version": "0.19.44",
     "description": "Bootstrap a project with a Nurix harness — copies the harness's CLAUDE.md, skills, agents, rules, and hooks directly into the project from a bundled payload (no marketplace fetch, no network).",
     "type": "module",
     "bin": {
@@ -41,5 +41,5 @@
         "agent",
         "plugin"
     ],
-    "etnaFingerprint": "4d6e06e37895"
+    "etnaFingerprint": "0140c843638d"
 }