@nurix/etna 0.19.66 → 0.19.68

package/lib/install/materialize.mjs

@@ -24,7 +24,6 @@ import {
   readFileSync,
   writeFileSync,
   renameSync,
-  cpSync,
   readdirSync,
   lstatSync,
   rmSync,
@@ -50,23 +49,25 @@ export function isSymlink(path) {
   }
 }
 
-// Move <path> to <path>.bak.<timestamp> if it exists. Returns the backup path, or null.
-function backupIfExists(path) {
-  if (!existsSync(path) && !isSymlink(path)) return null;
-  const ts = new Date().toISOString().replace(/[:.]/g, '-');
-  const backup = `${path}.bak.${ts}`;
-  renameSync(path, backup);
-  return backup;
+// The .bkp path for a colliding file: the marker goes BEFORE the final extension
+// (CHANGELOG.md → CHANGELOG.bkp.md, .prettierrc.json → .prettierrc.bkp.json), so one glob —
+// `*.bkp.*` — matches every backup, and every harness scanner ignores exactly that glob. A file
+// with no extension appends `.bkp`.
+export function bkpPathFor(path) {
+  const slash = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'));
+  const dot = path.lastIndexOf('.');
+  if (dot <= slash + 1) return `${path}.bkp`; // no extension, or a leading-dot name like `.env`
+  return `${path.slice(0, dot)}.bkp${path.slice(dot)}`;
 }
 
-// Copy a directory to <path>.bak.<timestamp>, leaving the original in place. Returns the
-// backup path, or null. Used for .claude/, which is refreshed in place (not overwritten
-// wholesale), so the live tree must survive for the in-place update — snapshot, don't move.
-function snapshotDirIfExists(path) {
-  if (!existsSync(path)) return null;
-  const ts = new Date().toISOString().replace(/[:.]/g, '-');
-  const backup = `${path}.bak.${ts}`;
-  cpSync(path, backup, { recursive: true });
+// Move a colliding FOREIGN file aside as its .bkp sibling. First backup wins: if the .bkp
+// already exists (a re-run before any baseline folded it), the older backup is the more
+// original and is kept; the collision file is simply overwritten by the install.
+function bkpRename(path) {
+  if (!existsSync(path) && !isSymlink(path)) return null;
+  const backup = bkpPathFor(path);
+  if (existsSync(backup) || isSymlink(backup)) return null;
+  renameSync(path, backup);
   return backup;
 }
 
@@ -300,43 +301,17 @@ export function materializeHarness({ bundledHarnessDir, targetDir, pluginName, p
   // the marker that holds it is one of the files about to be overwritten.
   const priorOwned = readInstalledOwned(targetDir);
 
-  // The safety net, for the two artifacts a refresh overwrites outright. A git repo recovers them
-  // from history, so we only say so; without git there is no net, so we take a copy and warn. The
-  // .claude/ tree is SNAPSHOTTED rather than moved — it is refreshed in place, so the live tree has
-  // to survive for the writes below.
-  for (const [rel, kind] of [
-    ['CLAUDE.md', 'file'],
-    ['AGENTS.md', 'file'],
-  ]) {
-    const dest = join(targetDir, rel);
-    if (!existsSync(dest) && !isSymlink(dest)) continue;
-    if (projectHasGit) {
-      notices.push(
-        `Overwrote existing ${rel} (tracked by git — \`git checkout ${rel}\` to restore).`,
-      );
-    } else {
-      warnings.push(
-        `No .git here, so no version-control safety net — backed up existing ${rel} → ${backupIfExists(dest)}`,
-      );
-    }
-    void kind;
-  }
-  for (const rel of ['.claude', ...CODEX_REBUILT_DIRS]) {
-    const dest = join(targetDir, rel);
-    if (!existsSync(dest)) continue;
-    if (projectHasGit) {
-      notices.push(
-        `Refreshed existing ${rel}/ in place (tracked by git — \`git checkout ${rel}\` to restore).`,
-      );
-    } else {
-      const backup = snapshotDirIfExists(dest);
-      if (backup) {
-        warnings.push(
-          `No .git here, so no version-control safety net — snapshotted existing ${rel}/ → ${backup}`,
-        );
-      }
-    }
-  }
+  // FIRST CONTACT vs REFRESH is the entire backup question, and the marker decides it. On a
+  // refresh, every colliding file at a harness path is the harness's own previous version —
+  // overwritten in place, git or no git; backing up our own stale copies would bury every upgrade
+  // in .bkp noise. On first contact, a colliding file is the USER'S — it is moved aside as its
+  // .bkp sibling, ours installs, and the maintenance baseline folds docs-side .bkp content into
+  // the reconciled tree (top-level config .bkp files are never merged — they are listed and left
+  // to the human). Git is not the distinction: history protects bytes, but the .bkp file is what
+  // makes the fold duty visible to the next session. The harness is deliberately unapologetic
+  // about its own process; the backup is how it stays honest about yours.
+  const firstContact = !existsSync(join(targetDir, '.claude', 'harness.json'));
+  void projectHasGit; // kept for caller compatibility; the .bkp rule does not branch on it
 
   // The Codex mirrors are rebuilt wholesale, not merged: they are byte projections of the Claude
   // tree, so a file left behind from a prior version is a skill Codex still sees after the harness
@@ -346,13 +321,18 @@ export function materializeHarness({ bundledHarnessDir, targetDir, pluginName, p
 
   let written = 0;
   let seeded = 0;
+  const backedUp = [];
   for (const file of files) {
     const dest = join(targetDir, file.path);
-    // A seed is one-time scaffolding: once the path exists it is the project's living copy, and a
-    // refresh must not touch it. This is also the rule that lets an Apollo export carry an App's
-    // own `docs/history/backlog.md` instead of the harness's.
+    // A seed is one-time scaffolding: once installed, the path is the project's living copy and a
+    // refresh never touches it. On FIRST contact a pre-existing file at a seed path is the user's
+    // — it moves aside as .bkp and the pristine seed installs, so the baseline has both to fold.
     if (file.policy === 'seed') {
-      if (existsSync(dest)) continue;
+      if (existsSync(dest)) {
+        if (!firstContact) continue;
+        const backup = bkpRename(dest);
+        if (backup) backedUp.push(file.path);
+      }
       mkdirSync(dirname(dest), { recursive: true });
       writeFileSync(dest, file.content);
       seeded += 1;
@@ -362,12 +342,26 @@ export function materializeHarness({ bundledHarnessDir, targetDir, pluginName, p
     // permissions. The plan's copy is what a FRESH install would hold; against an existing file the
     // authority is mergeHooks below, which is additive and idempotent.
     if (file.policy === 'merge') continue;
+    if (firstContact && (existsSync(dest) || isSymlink(dest))) {
+      const backup = bkpRename(dest);
+      if (backup) backedUp.push(file.path);
+    }
     mkdirSync(dirname(dest), { recursive: true });
     writeFileSync(dest, file.content);
     written += 1;
   }
   installed.push(`${written} harness file(s) → ./ and .claude/`);
   if (seeded > 0) installed.push(`${seeded} seed file(s) → ./ (only where absent)`);
+  if (backedUp.length > 0) {
+    warnings.push(
+      `${backedUp.length} pre-existing file(s) moved aside as .bkp siblings (${backedUp.join(', ')}). ` +
+        'The maintenance baseline folds docs-side .bkp content into the reconciled tree and deletes the .bkp; ' +
+        'top-level config .bkp files are never merged — review those yourself.',
+    );
+  }
+  if (!firstContact) {
+    notices.push('Refresh: harness-owned files updated in place; seeds and .bkp files untouched.');
+  }
 
   // Prune components a prior harness version owned but this bundle no longer ships (e.g. a retired
   // agent). Only prior-owned names are eligible, so the project's own files survive.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nurix/etna",
-    "version": "0.19.66",
+    "version": "0.19.68",
     "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": {
@@ -42,5 +42,5 @@
         "agent",
         "plugin"
     ],
-    "etnaFingerprint": "774efa3ae2da"
+    "etnaFingerprint": "d5b676c55c3a"
 }

package/data/harnesses/apollo/.mcp.json

@@ -1,8 +0,0 @@
-{
-    "mcpServers": {
-        "design": {
-            "type": "http",
-            "url": "https://apollo.nustack.tech/design/mcp"
-        }
-    }
-}

package/data/harnesses/apollo/.prettierignore

@@ -1,29 +0,0 @@
-# Dependencies & build output
-node_modules
-dist
-build
-
-# Lockfiles
-pnpm-lock.yaml
-package-lock.json
-yarn.lock
-
-# Harness-managed — the installer overwrites all of these, so formatting them is churn
-# that comes straight back on the next `npx @nurix/etna`.
-.claude
-.codex
-.agents
-CLAUDE.md
-AGENTS.md
-
-# Frozen records — a plan, changelog entry, or migration runbook is a point-in-time
-# artifact that is never edited after it freezes. Reformatting one is an edit, and the
-# `maintenance` agent is forbidden from making it — so a format gate over this tree is
-# a demand nothing in the repo is allowed to satisfy.
-docs/history
-
-# Source catalogs — authored markdown; prettier collapses template/example blocks
-skills
-rules
-agents
-harness

package/data/harnesses/apollo/.prettierrc.json

@@ -1,3 +0,0 @@
-{
-  "proseWrap": "never"
-}

package/data/harnesses/apollo/.vscode/settings.json

@@ -1,19 +0,0 @@
-{
-  // Markdown: Prettier unwraps prose to one logical line per paragraph
-  // (see .prettierrc → proseWrap:never) on save; the editor soft-wraps for
-  // reading, so no hard line breaks get baked into the source.
-  "[markdown]": {
-    "editor.defaultFormatter": "esbenp.prettier-vscode",
-    "editor.formatOnSave": true,
-    "editor.wordWrap": "on"
-  },
-  // Hide harness-authoring scaffolding from the file explorer
-  "files.exclude": {
-    ".claude": true,
-    ".vscode": true,
-    ".agents": true,
-    ".codex": true,
-    "**/node_modules": true,
-    "**/apollo.service.json": true
-  }
-}

package/data/harnesses/apollo/CLAUDE.md

@@ -1,162 +0,0 @@
-# Agent Instructions
-
-How AI coding agents — any vendor, any runtime — work on this project. Rules are runtime-neutral: a rule that depends on a capability (sub-agent dispatch, browser tools, context injection, slash commands) applies only if the runtime has it, and states its fallback. Rules marked **[override]** deliberately replace a runtime default — in a conflict, the rule here wins.
-
----
-
-## Maintenance
-
-**Baseline first**: if `docs/structure.md` lacks a `harness-version` frontmatter marker, or it is behind the `version` in `.claude/harness.json`, invoke the `maintenance` agent before taking up the user's first ask — tell the user, let the agent run, then proceed.
-
-Invoke the `maintenance` agent when a mechanical condition holds: `docs/structure.md` is missing (the repo isn't reconciled — baseline first), the `harness-version` marker is behind the installed version, a doc contradicts code being touched, or source paths are unowned — not on prose that merely looks stale. Structural reconciliation is never done by hand — the agent auto-selects its mode (baseline when the marker is missing or behind, coherence audit otherwise) and hands back; if it returns a follow-up (typically the module proposal), re-invoke it to finish. Single-glob or single-line doc corrections are done inline, per § Documentation. Each component's internals live in the component, not here.
-
----
-
-## Getting Started
-
-- Consult **[`docs/structure.md`](docs/structure.md)** when adding or moving a doc — it is the authority on placement
-- Read **[`docs/memory/`](docs/memory/)** for agent memory files (one per agent)
-- Prefer `docs/` over `README.md` — docs/ is canonical for agents; check the README only when docs/ lacks a setup detail
-- Check **[`package.json`](package.json)** for available scripts. Detect the package manager from the lockfile — see `.claude/rules/general.md`; don't hardcode one.
-
----
-
-## Workflows
-
-Three peer modes, then a verification gate and a Completion step — enter wherever the user's thinking already is. Each mode is implemented by an agent + skill; the behavioural detail lives in those files, not here.
-
-| Mode | Enter when | Implemented by | Exits to |
-| --- | --- | --- | --- |
-| **Brainstorming** | explicit ask (`/brainstorm start`); or offer a session — never auto-enter — when the user brings a large piece of work (name what makes it big) or an utterance contradicts a recorded pillar (name the principle) | `brainstorm` agent + skill | LLD, Plan, or close + harvest |
-| **LLD** (low-level design) | new feature work | `lld-mode` agent + `documentation` skill | Plan |
-| **Plan** | an LLD is approved | `documentation` skill → `docs/history/plans/YYYY-MM-DD-{slug}.md` | Verification gate → Completion |
-
-> Brainstorm entry needs a **basis** — a reference document or a one-shot brain dump; drip-sized asks (a bug fix, one button) are too small and get redirected. A **pillar** is a recorded strategic principle from a past brainstorm: in-progress sessions live under `docs/research/`, harvested ones under `docs/history/brainstorms/`, harvested doctrine under `docs/architecture/`. The LLD is the feature doc itself — `docs/features/{feature}.md`, design intent first, extended in place at Completion.
-
-> **The lightweight lane:** a change touching one module, no cross-module contract surface, and under about a day's work skips the modes above entirely — the ad-hoc regime of `.claude/rules/testing.md` applies: make the change, pay its test immediately if it alters promised behavior, cover it with a changelog row.
-
-**On Plan Completion:**
-
-1. **The verification gate passes first** — user-triggered: when implementation completes, report it and offer the gate; never run it unbidden. It requires the plan's Test Obligations ledger to exist (proof the plan gates ran) and discharges every row, driving the real surface before pinning tests — `.claude/rules/testing.md`. A plan with outstanding obligations stays open, whatever the code does.
-2. Freeze the plan — `Status: Complete`, fill the Completed date. The file is now frozen.
-3. **Discharge the plan's Doc Obligations ledger — every row, into exactly one outcome**: **updated** (the doc now states what the code does), **owes nothing** (with the reason), or **blocked** (→ a backlog item, so the debt outlives the frozen plan). For each row's doc: flip `status: active` if it was `draft`, extend it in place with the how-it-works sections, and confirm its `owns:` globs against the actual code. A plan spanning three features discharges three rows — the ledger, not memory, says how many.
-4. Record the gate's results in the changelog entry, and confirm every section of `docs/tests/{feature}.md` carries its `Pinned:` trace — the checklist itself is authored at the gate (step 1), not written up afterwards.
-
-**On Brainstorm Close** (when a session ends, not when a plan completes): close + harvest is the skill's `stop` procedure — converge, a user-approved harvest manifest, apply, then a uselessness test; conclusions disperse by scope (architecture docs, decision records, backlog), the record moves from `docs/research/{topic}-brainstorm/` to `docs/history/brainstorms/{topic}/`, and the user decides whether the moved folder is deleted or committed.
-
----
-
-## Ownership, Boundaries, Verification & Documentation
-
-These four mechanisms work in tandem to keep the repo self-updating and to prevent half-finished changes: **ownership** routes an edit to the canonical doc before the code is touched, the **boundary** check reads both sides of every contract a change participates in so one side never ships alone, **verification** proves the change works in the product before it is called done, and **documentation** updates close the loop so the next session inherits the truth. Skipping any leg breaks the others.
-
-### Ownership — route before editing
-
-Which doc is canonical for which code paths is the **feature doc's own frontmatter**. A feature doc (flat in `docs/features/`) carries `owns:` (code-path globs — the only ownership key), `module:` (a bounded-context label, omitted when cross-cutting), `keywords:` (discovery), and `status:`. Code → doc ownership is the union of every feature doc's `owns:` globs, surfaced as the generated ownership index at session start. A module is tied to code by the `owns:` globs of the docs carrying its `module:` label — not a folder, not a separate map. Architecture docs describe cross-cutting patterns and own no files; operations docs describe procedures. Every doc carries `type:` — its genre, stamped by document generators or at authoring, read by tooling (UI grouping, protected-file mapping); the `maintenance` agent stamps it where missing. Like `last-reviewed:`, it is tooling metadata: preserve it on edits, never inject or narrate it.
-
-Before modifying code in an unfamiliar area:
-
-1. Consult the **injected ownership index** (`glob → doc · module · keywords · status`). Match the path or topic to the owning feature doc and read it before changes. (No index in context ⇒ either the repo isn't reconciled — see Maintenance — or the runtime doesn't inject it — see Runtime Notes.)
-2. If a `docs/memory/` file exists for the domain, read it for domain knowledge and failure modes.
-
-The `lld-mode` agent checks for ownership conflicts during LLD research — feature docs whose `owns:` globs overlap at equal specificity. Resolve them in the LLD before proceeding.
-
-### Boundaries — check while changing
-
-Boundaries are **diagnosed, not documented** — the `boundary` skill derives them fresh from source on every run (the definition and mechanism catalog live in the skill), so nothing is persisted that could go stale.
-
-**Invoke the `boundary` skill after a plan is approved and before its first implementation step.** It parses the plan's Proposed Changes, reads the touched source, traces the consumers on the other side, and reports severity-ranked violations with suggested amendments and a pass/block verdict — in chat, read-only. Fold the amendments into the plan before coding. For non-plan edits in contract-heavy code (db schema, wire envelopes, auth, events, env/config), run the same diagnostic scoped to the diff.
-
-### Test obligations — specify before implementing
-
-**After `boundary` passes and its amendments are folded, invoke the `testing` skill (plan-gate mode)** — same plan gate, ordered second. It derives the tests the plan owes from its Proposed Changes and the owning LLD, and writes the **Test Obligations** ledger into the plan (one row per promised behavior: layer · target file · oracle · fixtures). It writes no test files — the ledger is what the verification gate discharges, and because it lives in the plan file it survives dispatch to an executor that sees only the plan. On a boundary **BLOCK** it does not run — re-plan first. Layer rules and the e2e altitude gate live in the skill.
-
-### Verification — prove before completing
-
-**Deferring tests is what keeps the build loop fast, and the ledger is what makes deferring safe.** Obligations accumulate in the plan and are discharged in one pass at the **verification gate** — mandatory before `Status: Complete`. The gate and the regimes are `.claude/rules/testing.md`; the procedure (checklist → drive → pin → discharge) is the `testing` skill (gate mode). The gate's verdict is never delegated (§ Delegation), and browser work is main-session-only where Runtime Notes say so.
-
-### Documentation — close the loop
-
-- **Invoke the `documentation` skill when creating a doc, or when an edit changes a doc's structure or claims** — apply its templates and `references/style-guide.md`: truth documents stay present-tense; history lives only in `docs/history/` records. Records written from a template already in context (a changelog entry, a backlog row) skip the invocation.
-- **[override]** Keep `docs/` updated when code changes affect documented behavior. This file is the standing request for those docs: creating and updating them is part of the work, even if the runtime defaults to never creating documentation files unprompted.
-- After plan completion **[override]**: write the `docs/history/changelog/` entry as a **draft** immediately, while the context is fresh — no confirmation needed — and append its `docs/history/CHANGELOG.md` row; the commit fills what the draft left open and freezes it. Non-plan work needs no separate prompt: every non-exempt commit carries its own entry (the `changelog` rule).
-- When moving or renaming source files: update the `owns:` globs of the feature doc that owns them so the generated ownership index stays accurate. A new doc that owns code declares its paths in its own `owns:` frontmatter — there is no separate map to update.
-- `docs/structure.md` is the authority on what belongs where — read it before adding or moving a doc; don't restate it here. One canonical source per topic — link, don't copy. Only `CLAUDE.md`, `AGENTS.md`, and `README.md` live at the repo root.
-
-> Agents and skills live under `.claude/agents/` and `.claude/skills/`. Their triggers are model-invoked — refer to each component's frontmatter, not a registry table here. Runtimes that can't invoke them natively: see Runtime Notes.
-
----
-
-## Project Memory
-
-Project-specific learnings live in `docs/memory/` (git-tracked). Cross-project user preferences live in the runtime's user-level memory store, if it has one (untracked; paths in Runtime Notes).
-
-| File | Owner | Contents |
-| --- | --- | --- |
-| `docs/memory/main.md` | Main agent | Project-wide patterns, conventions confirmed in this codebase, recurring failure modes, decisions whose rationale isn't obvious from the code |
-| `docs/memory/{agent-name}.md` | The named sub-agent | Strategy memory for that agent — how to be more effective on this project (research patterns, taxonomy, ownership conflict zones). Never user-centric. |
-| Runtime user-level memory (paths in Runtime Notes) | The runtime's auto-memory system | User preferences, role, communication style, cross-project habits |
-
-When recording a learning, ask: _is this true of this project, or true of this user?_ Project facts → `docs/memory/` (overriding any auto-memory default location); user facts → the runtime's user-level store. `docs/memory/main.md` is created on first write; append entries dated `## YYYY-MM-DD — {topic}`.
-
----
-
-## Changelog
-
-The working session is the last holder of the refinement context that produced a change — asks, iterations, rejections, discoveries; the changelog captures it, and the `retro` agent distills it on demand into doc, skill, and pin feedback. When an entry is owed, its lifecycle, its granularity, and the migration-runbook genre are the `changelog` rule; format and required fields are the `documentation` skill's `templates/changelog-entry.md`. A plan reaching `Status: Complete` writes its entry as a **draft** immediately, while the context is fresh; **immutability begins at commit, not creation** — a committed entry is never edited, a correction is a new entry that links back.
-
----
-
-## Out-of-Scope Discovery
-
-When a plan's implementation surfaces work that is important but outside the plan's scope and is not being done now (a pre-existing bug being fixed on the spot is the bug-fix regime — the `testing` rule — not a backlog item):
-
-- Append it to `docs/history/backlog.md` under the appropriate priority (P0-P3)
-- Format: `- **[P1]** Description — discovered by [plan-name or agent-name]`
-- Do NOT ask permission. Just append and mention it in the reply.
-
----
-
-## Delegation
-
-The single policy for sub-agent dispatch — when to fan out, at what tier, and how far to trust the result. Component-internal dispatch mechanics (the foreman loop, the brainstorm twin, batch classification) stay in their components and defer here for anything this section covers. No dispatch mechanism ⇒ inline.
-
-- **Delegate to keep bulk out of the main context.** Wide file reads, sweeps, broad research, audits, fixture prep — work whose raw tool output the main session doesn't need — defaults to a sub-agent: output a sub-agent reads dies with it, while output read inline is re-read and re-billed on every later turn. The hand-off is self-contained (the sub-agent sees none of the conversation), so it must still cost less than the work; run independent delegations in parallel.
-- **Small or judgment work stays inline.** A task finishable in a handful of tool calls is faster done than briefed. **Never delegate judgment by reflex** — a second opinion is for a high-stakes call or an explicit request.
-- **A delegated result is a report, not verifiable ground truth** — verify load-bearing results directly.
-- **Tiers**: mechanical fan-out → the cheapest capable tier; judgment-heavy delegation → the session's standard tier; the strongest tier **only** on explicit user request. The session itself defaults to the standard tier, entering the strongest only by explicit user switch. Model names live in Runtime Notes.
-- **An explicit user directive about tier, cost, or delegation overrides this section.**
-
----
-
-## Guardrails & Defaults
-
-Defaults — ❌ prohibitions hold unless the user explicitly asks otherwise; ✅ and ⚠️ items are standing policy:
-
-- ✅ **Verification — batched at a gate, not continuous.** Only a plan defers tests; bug fixes and ad-hoc changes that alter promised behavior pay theirs immediately. The gate, regimes, frameworks, and placement are `.claude/rules/testing.md`; the procedure is the `testing` skill (gate mode) — the repo's existing runner and layout always win.
-- ❌ **Dependencies** – Never upgrade pinned packages without asking; security patches and test-tooling installs at `latest` (`testing.md`) are exempt.
-- ❌ **Compatibility** – Never maintain backward compatibility unless specified.
-- ❌ **Branches & Worktrees [override]** – Never self-create git branches or worktrees; commit straight to the checked-out branch. This replaces any built-in "branch first on the default branch" default. Exception: when the user asks for a pull request, create the branch the PR requires before committing its changes.
-- ❌ **Protected Files** – Once per session, if `docs/operations/protected-files.md` exists, read it and never modify any path it lists; never modify `AGENTS.md` (harness-regenerated) or `protected-files.md` itself.
-- ✅ **Browser Automation** – If the runtime provides browser automation, use it freely; no need to ask first. If it doesn't — or the executing agent can't hold the browser connection (see Runtime Notes) — return a browser-verification checklist (URLs, actions, expected outcomes) for the orchestrating session or the user to run.
-- ✅ **Bookkeeping** — hooks silently append doc-debt rows to `docs/operations/bookkeeping.md`; the commit hook blocks while unresolved rows remain — dispatch the `bookkeeper` agent to drain the queue. The queue is a queue, never an archive: a drained row is **deleted**, so a fully drained file holds no rows at all.
-- ✅ **Cleanup removes the cause, not the record of it.** When the user asks for something to be deleted or cleaned up, the ask is for the underlying condition to be gone. Deleting the record while the condition survives is worse than doing nothing — it destroys the only evidence the debt exists. The order is fixed: **read what the record is masking** (a `waived:` row, an `UNBUILT:` marker, a `status:` flag, a lint suppression — each asserts something is fine; check whether that is still true), **fix the condition**, **then delete the record**. Reversing it backfires concretely: a deleted waiver's finding is re-appended by the detector as an `auto:` row, which *fails* the commit wall the `waived:` row passed.
-- ✅ **Delegation** — when to fan out, tiers, and trust are § Delegation.
-- ⚠️ **Plans** – Plans are created directly in `docs/history/plans/` (see Workflows). Once `Status: Complete` or `Status: Abandoned`, the file is frozen — never edited. Abandoning a plan whose code was committed first converts its undischarged Test Obligations into backlog items (the `testing` rule). If scope changes after completion, write a new dated plan that links back to the old one.
-- ⚠️ **Tool Issues** – If any CLI tool, shell alias, or MCP tool behaves unexpectedly (syntax errors, silent failures, wrong defaults), report the exact tool name, command, and error to the user so they can fix or remove the underlying library.
-
----
-
-## File Structure
-
-- Add a file-path header comment at the top of each source file, in the file's native comment syntax — `// src/modules/example.js - Module for handling user authentication`. Place it below any shebang line; skip formats with no comment syntax (JSON, lockfiles) and generated files.
-- Add a 1-line description above each function whose purpose isn't fully evident from its name and signature: `// Extract JWT token from request based on endpoint type`. A comment that restates the name is noise. No inline comments that restate obvious code; no commented-out code — if a block needs a comment to be understandable, refactor for clarity instead.
-
----
-
-## Runtime Notes
-
-Everything above is runtime-neutral. This section is the only place runtime- or vendor-specific facts may live; re-audit it whenever a runtime ships new models or tools. Lint: nothing outside this section may name a model, a vendor product, or a runtime-built-in tool — exempt are repo-relative `.claude/**` component paths (shipped in this repo, readable by any runtime) and protocol names (e.g. MCP).
-
-- **Claude Code**: sub-agent dispatch is the Agent tool; sub-agents can run skills and spawn their own sub-agents (probe-verified; re-verify on runtime updates), but cannot reliably hold the browser connection (the "can't hold the browser connection" condition the Browser Automation guardrail refers to) — browser work is Chrome CDP ("Claude in Chrome"), main session only. The user-level memory store is `~/.claude/` (auto-memory under `~/.claude/projects/...`). The ownership index and skill/agent descriptions are injected at session start; skills are invoked as slash commands (e.g. `/brainstorm start`). Dispatch tiers (§ Delegation): the standard tier is Opus-class and is the session default; mechanical fan-out runs on the cheapest capable tier (Sonnet-class); the strongest tier (Fable-class) only on explicit user switch or request — pick by capability at dispatch, since model names go stale.
-- **Runtimes without native component support** (AGENTS.md readers, etc.): read `.claude/agents/<name>.md` and each skill's `.claude/skills/<name>/SKILL.md` (plus its `references/`) and follow them inline; derive the ownership index by scanning `docs/features/` frontmatter.

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

@@ -1,28 +0,0 @@
----
-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, deletes each row it drains. 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: sonnet
----
-
-# 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** — derive the transcript from the row's `sid=` tail: the session JSONL lives at `~/.claude/projects/{project-dir-slug}/{sid}.jsonl` (the slug is the project path with `/` → `-`). Search it for the row's file path or area and read only that window — never the whole file. The sid 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 row}`) 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:`.
-- **A waiver's reason expires before its date.** Most waivers defer to something — "plan X reconciles this at completion", "the concurrent session resolves its own doc impact". When you pass a `waived:` row, check whether that reason still holds: a waiver naming a `Status: Complete` plan is discharged debt wearing a live badge, and its `expires=` date will not fire for weeks. Report those rows as `needs-session:` rather than waiving them onward — the finding underneath is live, and the unexpired date is precisely why nothing else will catch it.
-- **Report by row**: one line each — the row, the outcome (fixed / landed in {doc} / needs-session), and the files touched. The main session relays this; keep it terse.

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

@@ -1,144 +0,0 @@
----
-name: brainstorm
-description: The brainstorm twin — the paper-owning half of the brainstorm capability. Dispatched at session gates (start, on demand, pause, stop) by the `brainstorm` skill, never self-triggered and never conversing with the user. Scribe (distills the ops capture ledger into the working surface), editor (recomposes the thesis whole, diffs surfaced), harvester (drives the stop pipeline — manifest, apply, uselessness test, move), blindspot analyst (cold-reads the surface for unknown unknowns behind a four-test quality gate — grounded, material, new, answerable). Consumes the detector script for mechanical integrity and audits the five semantic sources the detector cannot judge. Writes every working-surface file; the facilitator writes only ops/capture.md and sync-log dispatch lines.
-tools: Read, Glob, Grep, Write, Edit, Bash, Task, Skill
-model: opus
----
-
-# Brainstorm Twin
-
-You own the **paper** of a brainstorm session; the facilitator (the main loop running the
-`brainstorm` skill) owns the conversation. You are dispatched at gates with a session-folder path,
-a gate name, and a scope. You never talk to the user — anything needing their judgment goes back
-in your final report for the facilitator to relay.
-
-The format contract is the skill's `references/session-schema.md` (resolve it beside this harness:
-`.claude/skills/brainstorm/references/` in a consumer repo, `skills/brainstorm/references/` in
-etna; also read `references/doctrine.md` for the epistemics). The mechanical half is the detector:
-
-```
-node <skill>/scripts/detector.mjs <session-folder> [--gate=manifest|move] [--json]
-```
-
-Run it at the start of every dispatch and again before you return. If node or the script is
-unavailable, say so loudly in your report and run the checks by hand from the schema — a missing
-detector is a flagged fact, never a silent skip.
-
-## The write protocol you enforce
-
-One writer per file. You write `state.md`, `thesis.md`, `forks.md`, `ledger.md`, `fragments/`,
-manifest, and your own sync-log **result** lines. You never write `ops/capture.md` (the
-facilitator's) or sync-log dispatch lines. The user may hand-edit anything: before rewriting any
-file, read its current state in full and treat content you did not write as **first-class user
-signal — fold it forward, never clobber it**. A hand-edit that contradicts the ledger is a design
-question: file a fork, don't "fix" the file.
-
-## Every dispatch, in order
-
-1. **Detector first** — `--gate=session`. Fix what is yours to fix (scribe-calls, below); report
-   what isn't.
-2. **Read the whole surface** plus every `ops/capture.md` entry since the last reconciled sync.
-3. **Scribe pass** — distill new capture into the surface, per the doctrine's epistemic rules
-   (distilled never verbatim; examples as examples; no naked pointers; both sides captured).
-   Residue that doesn't warrant filing stays in ops — that is what ops is for.
-4. **Semantic audit** — the five sources the detector cannot judge:
-   - **Cross-pillar contradiction** — across any two session files, `state.md` included (a state
-     file describing a session the pillars contradict is the historically strongest signal).
-   - **Aspect adequacy** — the detector checks that every mapped aspect *links* to content; you judge
-     whether the content actually covers it. Covered-in-name-only → a fork.
-   - **Basis drift** — decided divergence from `basis/` is fine; accidental divergence → a fork.
-   - **Tech conflicts** — anything violating the tech fragment (or the repo's `.claude/rules/`)
-     without a recorded deviation → a fork.
-   - **Self-containment** — read as the stranger you are (you were dispatched context-free; use
-     that): undefined terms, naked pointers, enumerations cited but never printed.
-5. **The scribe-call / design-call line** — an edit whose resolution doesn't change the design
-   (wording, bookkeeping, printing an enumeration, glossing a term) you apply directly and list.
-   An edit whose resolution changes the idea becomes a fork (`Raised by: twin (S#)` — cite your
-   own sync id). Never route a design question through a direct edit.
-6. **Editor pass** — recompose `thesis.md` whole (claim → argument → what changed), stamp
-   `Current as of:`, mirror the stamp into state.md `Last compose`, update the posture line.
-   Filing an insight must never push the session away from coherent: orphan evidence is a
-   scribe-note in your report, never a fork; free-floating insight may feed a thesis aspect.
-7. **Close the log** — append your result line to `ops/sync-log.md`:
-   `S# → reconciled | <ISO datetime> | N edits · M new forks · K open · untouched: <aspects>`
-   (or `S# → failed | <ts> | <reason>` — never omit the line; an unlogged dispatch reads as a
-   fabricated one). The one-line report is also the last line of your reply, plus anything the
-   facilitator must relay (design questions raised, what the recompose changed). When several
-   audit sources fire at once, rank integrity findings (attribution without evidence, files
-   contradicting the state) above coverage and staleness — a record that lies about its own
-   process is worse than one that merely stalled.
-
-## The blindspot pass (gate: on demand, scope: blindspot)
-
-Dispatched when the user asks what they're missing, when the facilitator self-initiates at a
-frame-settling moment (usually widening a reconcile dispatch's scope), or on the accepted
-pre-converge offer. Run the standard dispatch order first so the surface is current, then
-re-read the whole surface plus `basis/` cold, measured against the thesis's claim — the stated goal — never against
-a generic checklist. The species that pay: an assumption the design rests on but never states; a
-concern no aspect owns; two required properties that pull against each other with nothing
-designing for either; a rule or path that can never fire; an ambiguity two files resolve
-differently; a shape matching a failure already recorded in the basis or ledger.
-
-**The quality gate — a candidate passes all four tests or dies unsurfaced.** The gate exists so
-the user never over-replies to noise:
-
-1. **Grounded** — it cites the specific surface or basis content that creates it. Raisable
-   against any project of this type without reading this folder → generic → dead.
-2. **Material** — some plausible answer changes the thesis, a commitment, or the aspect map.
-   Every answer leaves the design unchanged → dead.
-3. **New** — not a restatement of an open fork, a ledger decision or Declined line, or an
-   explicit park.
-4. **Answerable** — resolvable by a decision or a named investigation, not "think harder
-   about X".
-
-File each survivor as a fork (`Raised by: twin (S#)`, body opening `Blindspot:`) with a close
-condition — at most five per pass, ranked by materiality; fewer survivors means surface fewer,
-never pad. End your report with the survivors in relay shape (finding → why it's material here,
-citing the creating content → what answering it would change) plus the kill line — e.g.
-"killed 6: 4 generic, 1 restates F3, 1 immaterial" — so gate discipline stays auditable; the
-facilitator's capture persists it. A killed candidate re-raised unchanged in a later pass stays
-dead; new surface content that changes its gate verdict reopens it.
-
-## The stop pipeline (gate: stop — multiple dispatches)
-
-Stop is facilitator-orchestrated because approval belongs to the user; you execute each leg:
-
-1. **Converge support + manifest build.** Final scribe/audit/compose as above, then run
-   `--gate=manifest`. While it fails (open forks, uncovered aspects, stale compose), report what
-   blocks — you do not build a manifest over a failing gate. When clean, write `ops/manifest.md`
-   (`Status: proposed`): route by scope per the skill's `references/harvest.md` — every parked
-   fork, every fragment, the consolidated source of truth. Return the manifest body for approval.
-2. **Apply** (only after the facilitator reports approval; set `Status: approved` then work).
-   Read **both sides** of every destination before writing — the destination's current content is
-   a contract, not a blank page. Format each artifact via the `documentation` skill;
-   where the runtime can't invoke it, fall back to your own formatting **and record which path ran
-   in the manifest**. Set `Status: applied`. The apply is all-or-nothing and loud: if you cannot finish,
-   report exactly what applied and stop — the folder stays visibly unfinished and the user
-   restarts; never resume silently from a half-applied state.
-3. **Uselessness test.** Spawn a **fresh, context-free cold reader** — an independent subagent
-   that inherits none of this session's context — whose prompt contains only the allowed-path list
-   (the manifest's destinations — never the session folder) and the instruction to reconstruct the
-   design: thesis, commitments, reasoning, declined branches. Grade its reconstruction against the
-   ledger and thesis. Gaps → record them in the manifest (`Result: fail`, named gaps), and the fixes
-   re-enter as a new manifest `Round` requiring fresh approval. Pass → record it. If the runtime
-   offers no subagent dispatch, report that the facilitator must dispatch the cold reader — you,
-   having read the folder, can no longer cold-read.
-4. **Move.** Run `--gate=move`. When clean: delete `ops/` entirely, `git mv` the folder to
-   `docs/history/brainstorms/{topic}/`, set state `Status: harvested`, update both indexes
-   (`docs/research/Readme.md` row out, `docs/history/brainstorms/Readme.md` row in). End your
-   report with the offer the facilitator relays: **delete the moved folder, or commit it** — the
-   user decides; the design assumes deletion.
-
-## Strategy memory
-
-`docs/memory/brainstorm.md` (create on first write, entries dated `## YYYY-MM-DD — {topic}`):
-how to facilitate *this repo* better — recurring audit findings, harvest destinations that keep
-appearing, aspect-map patterns. Never session content, never user preferences.
-
-## Degradations — flagged, never silent
-
-- Detector unavailable → manual checks from the schema, loudly noted.
-- `documentation` skill unavailable → own-format harvest, recorded in the manifest.
-- Cold-reader spawn unavailable → hand the uselessness test back to the facilitator.
-- Anything else broken → `S# → failed` in the log with the reason, and say so in your report.
-  A loud early failure the user fixes beats silent damage discovered after the folder is gone.