@nurix/etna 0.19.43 → 0.19.44

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": "0140c843638d",
     "harnesses": {
         "apollo": {
             "plugin": "apollo",

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.2",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
@@ -14,5 +14,5 @@
     "docs/history/backlog.md",
     "docs/memory/main.md"
   ],
-  "digest": "e971ef9a4d8f"
+  "digest": "3c2fc6ad2e82"
 }

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.10",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
   "seeds": [],
-  "digest": "b48a9de4fe22"
+  "digest": "552c88cf99bf"
 }