@nurix/etna 0.19.66 → 0.19.68

package/bin/etna.js

@@ -232,7 +232,16 @@ async function main(args) {
   await sleep(2000);
   boot.stop('Ready');
 
-  const harnessName = await resolveHarnessName(name, harnesses);
+  // Transition alias: the `apollo` harness merged into `code` (the code harness is pre-baked —
+  // it ships the docs scaffold as seeds and auto-baselines on first contact). Scripts and docs
+  // that pin the old name keep working through the alias; it retires after one window.
+  let requested = name;
+  if (requested === 'apollo' && !harnesses.apollo) {
+    p.log.info('`apollo` merged into `code` — installing `code` (the pre-baked harness).');
+    requested = 'code';
+  }
+
+  const harnessName = await resolveHarnessName(requested, harnesses);
   if (!harnessName) return; // user cancelled the interactive pick
 
   await installHarness(harnessName, harnesses);

package/data/harness-index.json

@@ -1,10 +1,6 @@
 {
-    "fingerprint": "774efa3ae2da",
+    "fingerprint": "d5b676c55c3a",
     "harnesses": {
-        "apollo": {
-            "plugin": "apollo",
-            "description": "the pre-baked `code` harness, built for Apollo Studio exports"
-        },
         "code": {
             "plugin": "code",
             "description": "the foundation every Nurix project starts with"

package/data/harnesses/code/CLAUDE.md

@@ -6,6 +6,8 @@ How AI coding agents — any vendor, any runtime — work on this project. Rules
 
 ## Maintenance
 
+**Baseline first**: if `docs/structure.md` lacks a `harness-version` frontmatter marker, or it is behind the `version` in `.claude/harness.json`, dispatch the `maintenance` agent **as a sub-agent** before taking up the user's first ask — baseline is bulky mechanical work, and dispatching it keeps this context clean for the ask. Tell the user what it will do; on a repo with existing docs or `.bkp` files, name what the fold will touch. No dispatch mechanism ⇒ run it inline.
+
 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.
 
 ---

package/data/harnesses/code/agents/maintenance.md

@@ -51,7 +51,7 @@ The ownership source of truth is the **union of every feature doc's `owns:` fron
 ### Step 1: Build the ownership map
 
 1. Read `docs/structure.md` for the authority map.
-2. Glob `docs/features/**/*.md`; for each, parse the frontmatter `owns:` globs and `module:` label.
+2. Glob `docs/features/**/*.md`, ignoring `*.bkp.*` files (installer backups awaiting the fold); for each, parse the frontmatter `owns:` globs and `module:` label.
 3. Build a map: glob → owning doc + module. Narrower glob wins on overlap. **This IS the source of truth.**
 
 **Architecture-first fallback.** If no feature doc carries `owns:` yet (a fresh-baseline repo can carry thousands of LOC and zero feature docs), drive this pass's ownership/drift surface off `docs/architecture/**` file-references instead — they become the **primary** ownership map for Steps 2–5. The `owns:` map becomes primary the moment any feature doc declares ownership — this is a fallback, not a replacement.
@@ -149,6 +149,7 @@ docs/
 │   ├── 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
+│   ├── sessions/          # Per-session gate logs (YYYY-MM-DD-{sid}.md) — machinery-written records, never drained, never edited down; created by the first gate event, 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)
@@ -186,6 +187,8 @@ This is what makes baseline more than a fresh scaffold. Detect old-shape artifac
 | `docs/architecture/overview.md` | split into `domain-model.md` / `glossary.md` / `non-goals.md` / `references.md` / `open-questions.md` |
 | `docs/architecture/adr/` (legacy folder name), or `ADR-NNN-*.md` records anywhere under `docs/architecture/` | **rename to the AD genre.** The folder becomes `docs/architecture/decisions/`; each record file `ADR-NNN-{slug}.md` becomes `AD-NNN-{slug}.md`, keeping its number and slug. Inside each record, update the retired vocabulary — "ADR", "Architecture Decision Record", and any supersession framing ("once accepted, an ADR is never edited; a later ADR supersedes it") — to the AD model: one AD per subject, **updated in place**, its journey confined to a `Decision Changelog` tail. A record's **reasoning is never rewritten** by a reconcile; only its genre vocabulary, its own title/id, and paths it cites. The folder's `Readme.md` is an **index, not a record** — reframe its genre description while preserving authored content such as a candidate-decision list verbatim. Repoint live references **inside `docs/`**, including one AD citing another; leave frozen records' links as point-in-time. A live reference **outside** your write scope — most often the root `README.md`, which you never overwrite — cannot be repointed: record it as a backlog item naming the file and line rather than leaving the residue silent |
 | a legacy `docs/brainstorm/{topic}/`, a singular `docs/history/brainstorm/`, or a root `brainstorm/`/`brainstorming/` folder | move each **active** record to `docs/research/{topic}-brainstorm/` and each **harvested** one to `docs/history/brainstorms/{topic}/` (dropping the suffix); create/refresh both `Readme.md` indexes; delete the emptied folder |
+| `*.bkp.*` files under `docs/` (the installer's first-contact backups of the project's pre-existing files) | **fold the content, then delete the backup.** Classify each backup's content by nature and land it in the current shape — a backed-up changelog's rows into `docs/history/CHANGELOG.md` and per-entry files, a backed-up structure/readme's real claims into the scaffolded truth doc, a backed-up feature doc's content merged into its sibling (or adopted whole if the sibling is a pristine seed). Content is folded, never discarded silently; what cannot be classified goes to the backlog with the backup kept. When the fold lands, delete the `.bkp` file |
+| `*.bkp.*` files at the repo root or in config (`CLAUDE.bkp.md`, `.prettierrc.bkp.json`, …) | **never merge these.** Top-level config is harness-owned by design; list each one to the user as their call, and leave the file in place |
 | no `harness-version` in `structure.md` | stamp it (Step B4) |
 
 ### Step B3 — Present the reconcile plan, then execute

package/data/harnesses/code/harness.json

@@ -1,14 +1,19 @@
 {
   "harness": "code",
   "name": "code",
-  "version": "3.7.3",
+  "version": "3.8.2",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
   "seeds": [
+    "docs/README.md",
+    "docs/structure.md",
+    "docs/history/CHANGELOG.md",
+    "docs/history/backlog.md",
+    "docs/memory/main.md",
     ".mcp.json"
   ],
-  "digest": "5e3c8dcf55ff"
+  "digest": "2dcea7420200"
 }

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

@@ -30,6 +30,8 @@ import {
   stateDir,
   recordTouched,
 } from "./lib/state.mjs";
+import { frozenStatus } from "./lib/frozen.mjs";
+import { approvedPackages } from "./lib/approved.mjs";
 
 const today = () => new Date().toISOString().slice(0, 10);
 
@@ -360,6 +362,68 @@ function detectRenames(projectDir, command, meta, rows) {
   }
 }
 
+// Working-tree paths git sees as changed or untracked — the outcome detector's ground truth.
+// Fails open: no git, or a git error, reads as an empty list.
+function dirtyPaths(projectDir) {
+  const res = spawnSync("git", ["status", "--porcelain"], { cwd: projectDir, encoding: "utf8", timeout: 5000 });
+  if (res.status !== 0) return [];
+  return (res.stdout || "")
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => {
+      const p = line.slice(3);
+      return p.includes(" -> ") ? p.split(" -> ")[1] : p; // a rename reports both sides; the new path is the live one
+    })
+    .map((p) => p.replace(/^"|"$/g, ""));
+}
+
+// OUTCOME RECOMPUTATION — the gates deny wrong actions, but an action can be routed around by
+// any tool that writes bytes (a manifest written by a script, a frozen record touched by sed).
+// State cannot be routed around: recompute the two outcomes the gates guard and raise what
+// changed as rows. Dedupe against the queue so a retry loop raises one row, not ten.
+function detectOutcomes(projectDir, meta, rows) {
+  const existing = readQueue(projectDir);
+  const raised = (needle) => existing.some((r) => r.body.includes(needle)) || rows.some((r) => r.includes(needle));
+  for (const rel of dirtyPaths(projectDir)) {
+    if (rel.includes("node_modules/") || rel.includes(".bkp.")) continue;
+    if (path.posix.basename(rel) === "package.json") {
+      const approved = approvedPackages(projectDir);
+      if (approved.size === 0) continue; // no table installed — nothing to enforce
+      let manifest;
+      try {
+        manifest = JSON.parse(readSafe(path.join(projectDir, rel)));
+      } catch (e) {
+        continue;
+      }
+      const names = [...Object.keys(manifest.dependencies || {}), ...Object.keys(manifest.devDependencies || {})];
+      for (const name of names) {
+        if (approved.has(name) || raised(`\`${name}\` (package-off-catalog`)) continue;
+        rows.push(
+          formatAutoRow({
+            ...meta,
+            kind: "package-off-catalog",
+            description: `${rel} declares \`${name}\` (package-off-catalog), absent from the approved table`,
+            action: "remove the dependency, or add it to .claude/hooks/approved-packages.md by explicit user decision",
+          })
+        );
+      }
+    }
+    if (rel.startsWith("docs/history/")) {
+      const frozen = frozenStatus(projectDir, rel);
+      if (frozen.frozen && !raised(`${rel} is a frozen record`)) {
+        rows.push(
+          formatAutoRow({
+            ...meta,
+            kind: "frozen-record-edited",
+            description: `${rel} is a frozen record and carries uncommitted modifications (${frozen.reason})`,
+            action: "revert the edit — a correction is a new dated entry that links back",
+          })
+        );
+      }
+    }
+  }
+}
+
 function postToolUse(projectDir, payload) {
   const meta = {
     date: today(),
@@ -371,11 +435,16 @@ function postToolUse(projectDir, payload) {
   const rows = [];
   if (payload.tool_name === "Bash") {
     detectRenames(projectDir, input.command, meta, rows);
+    detectOutcomes(projectDir, meta, rows);
   } else {
     const rel = relIfInside(projectDir, input.file_path || input.notebook_path);
     if (rel) detectorForFile(projectDir, rel, meta, rows);
     // Editing a feature doc's frontmatter can orphan globs the same way a rename can.
     if (rel && rel.startsWith("docs/features/")) detectRenames(projectDir, "git mv", meta, rows);
+    // A manifest or history file written by a non-Bash tool is the same evasion surface.
+    if (rel && (path.posix.basename(rel) === "package.json" || rel.startsWith("docs/history/"))) {
+      detectOutcomes(projectDir, meta, rows);
+    }
   }
   appendRows(projectDir, rows);
 }

package/data/harnesses/code/hooks/compliance.mjs

@@ -13,6 +13,7 @@ import { readQueue, countRows, askedThisSession, recordAsked } from "./lib/state
 import { frozenStatus } from "./lib/frozen.mjs";
 import { undischargedRows } from "./lib/ledger.mjs";
 import { appendEvent, unresolvedDenials, sessionLogPath } from "./lib/session-log.mjs";
+import { approvedPackages } from "./lib/approved.mjs";
 
 function readSafe(file) {
   try {
@@ -192,6 +193,7 @@ function stagedExempt(files) {
       HARNESS_FILES.includes(f) ||
       f.startsWith("docs/history/changelog/") ||
       f.startsWith("docs/history/sessions/") ||
+      f.includes(".bkp.") ||
       f === "docs/history/CHANGELOG.md"
   );
 }
@@ -239,20 +241,6 @@ function commitGate(projectDir, sessionId) {
   return null;
 }
 
-// Package names approved in .claude/hooks/approved-packages.md (plus testing.md frameworks and general.md).
-function approvedPackages(projectDir) {
-  const names = new Set();
-  const sources = [
-    path.join(projectDir, ".claude", "hooks", "approved-packages.md"),
-    path.join(projectDir, ".claude", "rules", "general.md"),
-    path.join(projectDir, ".claude", "rules", "testing.md"),
-  ];
-  for (const src of sources) {
-    const text = readSafe(src);
-    for (const m of text.matchAll(/`(@?[a-z0-9][\w./-]*)`/g)) names.add(m[1]);
-  }
-  return names;
-}
 
 // A token must parse as an npm package spec — name or @scope/name, optional @range tail —
 // before it may be judged against the table. Everything else on an install line (redirections

package/data/harnesses/code/hooks/lib/approved.mjs

@@ -0,0 +1,30 @@
+// harness/code/hooks/lib/approved.mjs — the approved-package set, one reader shared by the
+// PreToolUse install gate (compliance) and the PostToolUse outcome detector (awareness), so
+// "blocked at install" and "flagged in the manifest" can never disagree about the table.
+
+import fs from "node:fs";
+import path from "node:path";
+
+function readSafe(file) {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch (e) {
+    return "";
+  }
+}
+
+// Package names approved in .claude/hooks/approved-packages.md (plus testing.md frameworks and
+// general.md). Empty set ⇒ no rules installed ⇒ nothing to enforce.
+export function approvedPackages(projectDir) {
+  const names = new Set();
+  const sources = [
+    path.join(projectDir, ".claude", "hooks", "approved-packages.md"),
+    path.join(projectDir, ".claude", "rules", "general.md"),
+    path.join(projectDir, ".claude", "rules", "testing.md"),
+  ];
+  for (const src of sources) {
+    const text = readSafe(src);
+    for (const m of text.matchAll(/`(@?[a-z0-9][\w./-]*)`/g)) names.add(m[1]);
+  }
+  return names;
+}

package/data/harnesses/code/hooks/lib/frozen.mjs

@@ -29,6 +29,9 @@ function readSafe(projectDir, filePath) {
 
 // The predicate. Returns { frozen: boolean, reason?: string }.
 export function frozenStatus(projectDir, filePath) {
+  // *.bkp.* siblings are install-time backups, not records — the maintenance fold edits and
+  // deletes them, which a frozen verdict would forbid.
+  if (relPosix(projectDir, filePath).includes(".bkp.")) return { frozen: false };
   const rel = relPosix(projectDir, filePath);
   if (rel.startsWith("docs/history/changelog/") && rel.endsWith(".md")) {
     if (isCommitted(projectDir, rel)) {

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

@@ -117,7 +117,9 @@ export function asList(v) {
 // Shape: { doc (repo-relative, /-separated), owns[], module, keywords[], status }.
 export function scanFeatureDocs(projectDir) {
   const featuresDir = path.join(projectDir, "docs", "features");
-  const files = listMarkdown(featuresDir);
+  // *.bkp.* files are install-time backups awaiting the maintenance fold — a backed-up feature
+  // doc still carries owns: frontmatter, and scanning it would double-own every path it names.
+  const files = listMarkdown(featuresDir).filter((f) => !f.includes(".bkp."));
   const docs = [];
   for (const file of files) {
     let text;

package/data/harnesses/code/skills/documentation/references/frontmatter.md

@@ -12,7 +12,7 @@ When creating or updating a feature doc, derive its **`owns:` frontmatter** —
 
 ## How to derive the frontmatter
 
-A feature doc's ownership frontmatter is `owns:` (required), `module:` (optional), `keywords:` (required), and `status:` (required). An optional `last-reviewed:` date (stamped whenever the doc is substantively reviewed or updated) gives the `maintenance` agent a staleness signal to rank its audits by — it is tooling metadata, never narrated in the body. `type:` (required — the genre, enum = the template names) and `rev:` (generator-written generation stamp) are the same class: external tooling reads them, sessions **preserve them on edits** and never narrate or inject them. The `maintenance` agent stamps `type:` on docs that predate the key.
+A feature doc's ownership frontmatter is `owns:` (required), `module:` (optional), `keywords:` (required), and `status:` (required). An optional `last-reviewed:` date (stamped whenever the doc is substantively reviewed or updated) gives the `maintenance` agent a staleness signal to rank its audits by — it is tooling metadata, never narrated in the body. `type:` (required — the genre, enum = the template names) and `rev:` (generator-written generation stamp) are the same class: external tooling reads them, sessions **preserve them on edits** and never narrate or inject them. The `maintenance` agent stamps `type:` on docs that predate the key. `slug:` completes the set on generated docs: the identity key, minted once at creation and never re-derived from a display name — in the repo the filename is the slug, and the `maintenance` agent re-aligns the two when they diverge.
 
 **1. `owns:`** (the path scope)
 

package/data/harnesses/code/skills/documentation/scripts/doc-lint.mjs

@@ -23,7 +23,7 @@ const RULES = [
 // Sections inside a truth doc where dated history is sanctioned (the two bridges).
 const BRIDGE_HEADINGS = /^#{1,4}\s+(decision changelog|health log)\b/i;
 // Instruction files and generated trees are a different genre — out of this linter's scope.
-const SKIP = /(^|\/)(\.claude|node_modules|skills|rules|agents|harness|packages\/[^/]+\/data)\/|(^|\/)(CLAUDE|AGENTS)\.md$/;
+const SKIP = /(^|\/)(\.claude|node_modules|skills|rules|agents|harness|packages\/[^/]+\/data)\/|(^|\/)(CLAUDE|AGENTS)\.md$|\.bkp\./;
 const RECORD = /(^|\/)docs\/(history|research|memory)\//;
 
 // Classify a path: skipped genre, record, or truth.

package/data/harnesses/code/skills/documentation/templates/Readme.md

@@ -30,6 +30,8 @@ One file per template. Every template is either a **truth document** (states cur
 | Backlog | [backlog.md](backlog.md) | Record (append-only) |
 | Memory (main agent) | [memory-main.md](memory-main.md) | Record (append-only ledger) |
 
+**The `type:` enum lives here.** A doc's `type:` frontmatter takes its value from this table — one genre per template (`feature`, `architecture-decision`, `non-goals`, …). External generators consume this list rather than defining their own; a type this table does not name defaults to `docs/architecture/` placement and is never added to the protected-files list.
+
 **Baseline scaffolds** — files that must exist after every baseline; the `maintenance` agent (baseline mode) creates any that are missing: [docs-readme.md](docs-readme.md), [structure.md](structure.md), [changelog-index.md](changelog-index.md), [backlog.md](backlog.md), [memory-main.md](memory-main.md), and [root-readme.md](root-readme.md) (never overwriting an existing root README).
 
 **Ownership.** A feature doc is the canonical reference for the code paths in its **`owns:` frontmatter** — the only ownership key. To find what a doc owns, read its `owns:` globs; to find the doc for a path, match the path against the injected ownership index (the union of every feature's `owns:` globs), narrower glob wins. See [`../references/frontmatter.md`](../references/frontmatter.md) for turning code into `owns:` globs.

package/data/harnesses/code/skills/documentation/templates/structure.md

@@ -31,6 +31,7 @@ Each topic has one canonical location. Read from here, not from plans or changel
 | Historical plans | `docs/history/plans/` | YYYY-MM-DD-name.md |
 | Change records | `docs/history/changelog/` | `YYYY-MM-DD-{three-words}.md` — one per unit of work, written at commit time |
 | Migration runbooks | `docs/history/migrations/` | YYYY-MM-DD-name.md |
+| Session gate logs | `docs/history/sessions/` | `YYYY-MM-DD-{sid}.md` — machinery-written; denials and their resolutions, appended, never edited down |
 | Deep-research artifacts | `docs/history/research/{topic}/` | README.md + findings.md + sources.md |
 | Brainstorm design records | `docs/research/{topic}-brainstorm/` (active; legacy `-brainstorming/`) → `docs/history/brainstorms/{topic}/` (harvested; user deletes or commits) | thesis.md + forks.md + ledger.md + state.md |
 | Backlog | `docs/history/` | backlog.md |

package/data/harnesses/delivery/agents/maintenance.md

@@ -51,7 +51,7 @@ The ownership source of truth is the **union of every feature doc's `owns:` fron
 ### Step 1: Build the ownership map
 
 1. Read `docs/structure.md` for the authority map.
-2. Glob `docs/features/**/*.md`; for each, parse the frontmatter `owns:` globs and `module:` label.
+2. Glob `docs/features/**/*.md`, ignoring `*.bkp.*` files (installer backups awaiting the fold); for each, parse the frontmatter `owns:` globs and `module:` label.
 3. Build a map: glob → owning doc + module. Narrower glob wins on overlap. **This IS the source of truth.**
 
 **Architecture-first fallback.** If no feature doc carries `owns:` yet (a fresh-baseline repo can carry thousands of LOC and zero feature docs), drive this pass's ownership/drift surface off `docs/architecture/**` file-references instead — they become the **primary** ownership map for Steps 2–5. The `owns:` map becomes primary the moment any feature doc declares ownership — this is a fallback, not a replacement.
@@ -149,6 +149,7 @@ docs/
 │   ├── 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
+│   ├── sessions/          # Per-session gate logs (YYYY-MM-DD-{sid}.md) — machinery-written records, never drained, never edited down; created by the first gate event, 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)
@@ -186,6 +187,8 @@ This is what makes baseline more than a fresh scaffold. Detect old-shape artifac
 | `docs/architecture/overview.md` | split into `domain-model.md` / `glossary.md` / `non-goals.md` / `references.md` / `open-questions.md` |
 | `docs/architecture/adr/` (legacy folder name), or `ADR-NNN-*.md` records anywhere under `docs/architecture/` | **rename to the AD genre.** The folder becomes `docs/architecture/decisions/`; each record file `ADR-NNN-{slug}.md` becomes `AD-NNN-{slug}.md`, keeping its number and slug. Inside each record, update the retired vocabulary — "ADR", "Architecture Decision Record", and any supersession framing ("once accepted, an ADR is never edited; a later ADR supersedes it") — to the AD model: one AD per subject, **updated in place**, its journey confined to a `Decision Changelog` tail. A record's **reasoning is never rewritten** by a reconcile; only its genre vocabulary, its own title/id, and paths it cites. The folder's `Readme.md` is an **index, not a record** — reframe its genre description while preserving authored content such as a candidate-decision list verbatim. Repoint live references **inside `docs/`**, including one AD citing another; leave frozen records' links as point-in-time. A live reference **outside** your write scope — most often the root `README.md`, which you never overwrite — cannot be repointed: record it as a backlog item naming the file and line rather than leaving the residue silent |
 | a legacy `docs/brainstorm/{topic}/`, a singular `docs/history/brainstorm/`, or a root `brainstorm/`/`brainstorming/` folder | move each **active** record to `docs/research/{topic}-brainstorm/` and each **harvested** one to `docs/history/brainstorms/{topic}/` (dropping the suffix); create/refresh both `Readme.md` indexes; delete the emptied folder |
+| `*.bkp.*` files under `docs/` (the installer's first-contact backups of the project's pre-existing files) | **fold the content, then delete the backup.** Classify each backup's content by nature and land it in the current shape — a backed-up changelog's rows into `docs/history/CHANGELOG.md` and per-entry files, a backed-up structure/readme's real claims into the scaffolded truth doc, a backed-up feature doc's content merged into its sibling (or adopted whole if the sibling is a pristine seed). Content is folded, never discarded silently; what cannot be classified goes to the backlog with the backup kept. When the fold lands, delete the `.bkp` file |
+| `*.bkp.*` files at the repo root or in config (`CLAUDE.bkp.md`, `.prettierrc.bkp.json`, …) | **never merge these.** Top-level config is harness-owned by design; list each one to the user as their call, and leave the file in place |
 | no `harness-version` in `structure.md` | stamp it (Step B4) |
 
 ### Step B3 — Present the reconcile plan, then execute

package/data/harnesses/delivery/harness.json

@@ -1,12 +1,12 @@
 {
   "harness": "delivery",
   "name": "delivery",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
   "seeds": [],
-  "digest": "5384fce602a8"
+  "digest": "5f761b31c27a"
 }

package/data/harnesses/delivery/skills/documentation/references/frontmatter.md

@@ -12,7 +12,7 @@ When creating or updating a feature doc, derive its **`owns:` frontmatter** —
 
 ## How to derive the frontmatter
 
-A feature doc's ownership frontmatter is `owns:` (required), `module:` (optional), `keywords:` (required), and `status:` (required). An optional `last-reviewed:` date (stamped whenever the doc is substantively reviewed or updated) gives the `maintenance` agent a staleness signal to rank its audits by — it is tooling metadata, never narrated in the body. `type:` (required — the genre, enum = the template names) and `rev:` (generator-written generation stamp) are the same class: external tooling reads them, sessions **preserve them on edits** and never narrate or inject them. The `maintenance` agent stamps `type:` on docs that predate the key.
+A feature doc's ownership frontmatter is `owns:` (required), `module:` (optional), `keywords:` (required), and `status:` (required). An optional `last-reviewed:` date (stamped whenever the doc is substantively reviewed or updated) gives the `maintenance` agent a staleness signal to rank its audits by — it is tooling metadata, never narrated in the body. `type:` (required — the genre, enum = the template names) and `rev:` (generator-written generation stamp) are the same class: external tooling reads them, sessions **preserve them on edits** and never narrate or inject them. The `maintenance` agent stamps `type:` on docs that predate the key. `slug:` completes the set on generated docs: the identity key, minted once at creation and never re-derived from a display name — in the repo the filename is the slug, and the `maintenance` agent re-aligns the two when they diverge.
 
 **1. `owns:`** (the path scope)
 

package/data/harnesses/delivery/skills/documentation/scripts/doc-lint.mjs

@@ -23,7 +23,7 @@ const RULES = [
 // Sections inside a truth doc where dated history is sanctioned (the two bridges).
 const BRIDGE_HEADINGS = /^#{1,4}\s+(decision changelog|health log)\b/i;
 // Instruction files and generated trees are a different genre — out of this linter's scope.
-const SKIP = /(^|\/)(\.claude|node_modules|skills|rules|agents|harness|packages\/[^/]+\/data)\/|(^|\/)(CLAUDE|AGENTS)\.md$/;
+const SKIP = /(^|\/)(\.claude|node_modules|skills|rules|agents|harness|packages\/[^/]+\/data)\/|(^|\/)(CLAUDE|AGENTS)\.md$|\.bkp\./;
 const RECORD = /(^|\/)docs\/(history|research|memory)\//;
 
 // Classify a path: skipped genre, record, or truth.

package/data/harnesses/delivery/skills/documentation/templates/Readme.md

@@ -30,6 +30,8 @@ One file per template. Every template is either a **truth document** (states cur
 | Backlog | [backlog.md](backlog.md) | Record (append-only) |
 | Memory (main agent) | [memory-main.md](memory-main.md) | Record (append-only ledger) |
 
+**The `type:` enum lives here.** A doc's `type:` frontmatter takes its value from this table — one genre per template (`feature`, `architecture-decision`, `non-goals`, …). External generators consume this list rather than defining their own; a type this table does not name defaults to `docs/architecture/` placement and is never added to the protected-files list.
+
 **Baseline scaffolds** — files that must exist after every baseline; the `maintenance` agent (baseline mode) creates any that are missing: [docs-readme.md](docs-readme.md), [structure.md](structure.md), [changelog-index.md](changelog-index.md), [backlog.md](backlog.md), [memory-main.md](memory-main.md), and [root-readme.md](root-readme.md) (never overwriting an existing root README).
 
 **Ownership.** A feature doc is the canonical reference for the code paths in its **`owns:` frontmatter** — the only ownership key. To find what a doc owns, read its `owns:` globs; to find the doc for a path, match the path against the injected ownership index (the union of every feature's `owns:` globs), narrower glob wins. See [`../references/frontmatter.md`](../references/frontmatter.md) for turning code into `owns:` globs.

package/data/harnesses/delivery/skills/documentation/templates/structure.md

@@ -31,6 +31,7 @@ Each topic has one canonical location. Read from here, not from plans or changel
 | Historical plans | `docs/history/plans/` | YYYY-MM-DD-name.md |
 | Change records | `docs/history/changelog/` | `YYYY-MM-DD-{three-words}.md` — one per unit of work, written at commit time |
 | Migration runbooks | `docs/history/migrations/` | YYYY-MM-DD-name.md |
+| Session gate logs | `docs/history/sessions/` | `YYYY-MM-DD-{sid}.md` — machinery-written; denials and their resolutions, appended, never edited down |
 | Deep-research artifacts | `docs/history/research/{topic}/` | README.md + findings.md + sources.md |
 | Brainstorm design records | `docs/research/{topic}-brainstorm/` (active; legacy `-brainstorming/`) → `docs/history/brainstorms/{topic}/` (harvested; user deletes or commits) | thesis.md + forks.md + ledger.md + state.md |
 | Backlog | `docs/history/` | backlog.md |

package/data/harnesses/etna/agents/maintenance.md

@@ -51,7 +51,7 @@ The ownership source of truth is the **union of every feature doc's `owns:` fron
 ### Step 1: Build the ownership map
 
 1. Read `docs/structure.md` for the authority map.
-2. Glob `docs/features/**/*.md`; for each, parse the frontmatter `owns:` globs and `module:` label.
+2. Glob `docs/features/**/*.md`, ignoring `*.bkp.*` files (installer backups awaiting the fold); for each, parse the frontmatter `owns:` globs and `module:` label.
 3. Build a map: glob → owning doc + module. Narrower glob wins on overlap. **This IS the source of truth.**
 
 **Architecture-first fallback.** If no feature doc carries `owns:` yet (a fresh-baseline repo can carry thousands of LOC and zero feature docs), drive this pass's ownership/drift surface off `docs/architecture/**` file-references instead — they become the **primary** ownership map for Steps 2–5. The `owns:` map becomes primary the moment any feature doc declares ownership — this is a fallback, not a replacement.
@@ -149,6 +149,7 @@ docs/
 │   ├── 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
+│   ├── sessions/          # Per-session gate logs (YYYY-MM-DD-{sid}.md) — machinery-written records, never drained, never edited down; created by the first gate event, 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)
@@ -186,6 +187,8 @@ This is what makes baseline more than a fresh scaffold. Detect old-shape artifac
 | `docs/architecture/overview.md` | split into `domain-model.md` / `glossary.md` / `non-goals.md` / `references.md` / `open-questions.md` |
 | `docs/architecture/adr/` (legacy folder name), or `ADR-NNN-*.md` records anywhere under `docs/architecture/` | **rename to the AD genre.** The folder becomes `docs/architecture/decisions/`; each record file `ADR-NNN-{slug}.md` becomes `AD-NNN-{slug}.md`, keeping its number and slug. Inside each record, update the retired vocabulary — "ADR", "Architecture Decision Record", and any supersession framing ("once accepted, an ADR is never edited; a later ADR supersedes it") — to the AD model: one AD per subject, **updated in place**, its journey confined to a `Decision Changelog` tail. A record's **reasoning is never rewritten** by a reconcile; only its genre vocabulary, its own title/id, and paths it cites. The folder's `Readme.md` is an **index, not a record** — reframe its genre description while preserving authored content such as a candidate-decision list verbatim. Repoint live references **inside `docs/`**, including one AD citing another; leave frozen records' links as point-in-time. A live reference **outside** your write scope — most often the root `README.md`, which you never overwrite — cannot be repointed: record it as a backlog item naming the file and line rather than leaving the residue silent |
 | a legacy `docs/brainstorm/{topic}/`, a singular `docs/history/brainstorm/`, or a root `brainstorm/`/`brainstorming/` folder | move each **active** record to `docs/research/{topic}-brainstorm/` and each **harvested** one to `docs/history/brainstorms/{topic}/` (dropping the suffix); create/refresh both `Readme.md` indexes; delete the emptied folder |
+| `*.bkp.*` files under `docs/` (the installer's first-contact backups of the project's pre-existing files) | **fold the content, then delete the backup.** Classify each backup's content by nature and land it in the current shape — a backed-up changelog's rows into `docs/history/CHANGELOG.md` and per-entry files, a backed-up structure/readme's real claims into the scaffolded truth doc, a backed-up feature doc's content merged into its sibling (or adopted whole if the sibling is a pristine seed). Content is folded, never discarded silently; what cannot be classified goes to the backlog with the backup kept. When the fold lands, delete the `.bkp` file |
+| `*.bkp.*` files at the repo root or in config (`CLAUDE.bkp.md`, `.prettierrc.bkp.json`, …) | **never merge these.** Top-level config is harness-owned by design; list each one to the user as their call, and leave the file in place |
 | no `harness-version` in `structure.md` | stamp it (Step B4) |
 
 ### Step B3 — Present the reconcile plan, then execute

package/data/harnesses/etna/harness.json

@@ -1,12 +1,12 @@
 {
   "harness": "etna",
   "name": "etna",
-  "version": "1.4.3",
+  "version": "1.4.5",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
     ".vscode/settings.json"
   ],
   "seeds": [],
-  "digest": "1c440d72ea9f"
+  "digest": "e0669fcb3dcf"
 }

package/data/harnesses/etna/skills/documentation/references/frontmatter.md

@@ -12,7 +12,7 @@ When creating or updating a feature doc, derive its **`owns:` frontmatter** —
 
 ## How to derive the frontmatter
 
-A feature doc's ownership frontmatter is `owns:` (required), `module:` (optional), `keywords:` (required), and `status:` (required). An optional `last-reviewed:` date (stamped whenever the doc is substantively reviewed or updated) gives the `maintenance` agent a staleness signal to rank its audits by — it is tooling metadata, never narrated in the body. `type:` (required — the genre, enum = the template names) and `rev:` (generator-written generation stamp) are the same class: external tooling reads them, sessions **preserve them on edits** and never narrate or inject them. The `maintenance` agent stamps `type:` on docs that predate the key.
+A feature doc's ownership frontmatter is `owns:` (required), `module:` (optional), `keywords:` (required), and `status:` (required). An optional `last-reviewed:` date (stamped whenever the doc is substantively reviewed or updated) gives the `maintenance` agent a staleness signal to rank its audits by — it is tooling metadata, never narrated in the body. `type:` (required — the genre, enum = the template names) and `rev:` (generator-written generation stamp) are the same class: external tooling reads them, sessions **preserve them on edits** and never narrate or inject them. The `maintenance` agent stamps `type:` on docs that predate the key. `slug:` completes the set on generated docs: the identity key, minted once at creation and never re-derived from a display name — in the repo the filename is the slug, and the `maintenance` agent re-aligns the two when they diverge.
 
 **1. `owns:`** (the path scope)
 

package/data/harnesses/etna/skills/documentation/scripts/doc-lint.mjs

@@ -23,7 +23,7 @@ const RULES = [
 // Sections inside a truth doc where dated history is sanctioned (the two bridges).
 const BRIDGE_HEADINGS = /^#{1,4}\s+(decision changelog|health log)\b/i;
 // Instruction files and generated trees are a different genre — out of this linter's scope.
-const SKIP = /(^|\/)(\.claude|node_modules|skills|rules|agents|harness|packages\/[^/]+\/data)\/|(^|\/)(CLAUDE|AGENTS)\.md$/;
+const SKIP = /(^|\/)(\.claude|node_modules|skills|rules|agents|harness|packages\/[^/]+\/data)\/|(^|\/)(CLAUDE|AGENTS)\.md$|\.bkp\./;
 const RECORD = /(^|\/)docs\/(history|research|memory)\//;
 
 // Classify a path: skipped genre, record, or truth.

package/data/harnesses/etna/skills/documentation/templates/Readme.md

@@ -30,6 +30,8 @@ One file per template. Every template is either a **truth document** (states cur
 | Backlog | [backlog.md](backlog.md) | Record (append-only) |
 | Memory (main agent) | [memory-main.md](memory-main.md) | Record (append-only ledger) |
 
+**The `type:` enum lives here.** A doc's `type:` frontmatter takes its value from this table — one genre per template (`feature`, `architecture-decision`, `non-goals`, …). External generators consume this list rather than defining their own; a type this table does not name defaults to `docs/architecture/` placement and is never added to the protected-files list.
+
 **Baseline scaffolds** — files that must exist after every baseline; the `maintenance` agent (baseline mode) creates any that are missing: [docs-readme.md](docs-readme.md), [structure.md](structure.md), [changelog-index.md](changelog-index.md), [backlog.md](backlog.md), [memory-main.md](memory-main.md), and [root-readme.md](root-readme.md) (never overwriting an existing root README).
 
 **Ownership.** A feature doc is the canonical reference for the code paths in its **`owns:` frontmatter** — the only ownership key. To find what a doc owns, read its `owns:` globs; to find the doc for a path, match the path against the injected ownership index (the union of every feature's `owns:` globs), narrower glob wins. See [`../references/frontmatter.md`](../references/frontmatter.md) for turning code into `owns:` globs.

package/data/harnesses/etna/skills/documentation/templates/structure.md

@@ -31,6 +31,7 @@ Each topic has one canonical location. Read from here, not from plans or changel
 | Historical plans | `docs/history/plans/` | YYYY-MM-DD-name.md |
 | Change records | `docs/history/changelog/` | `YYYY-MM-DD-{three-words}.md` — one per unit of work, written at commit time |
 | Migration runbooks | `docs/history/migrations/` | YYYY-MM-DD-name.md |
+| Session gate logs | `docs/history/sessions/` | `YYYY-MM-DD-{sid}.md` — machinery-written; denials and their resolutions, appended, never edited down |
 | Deep-research artifacts | `docs/history/research/{topic}/` | README.md + findings.md + sources.md |
 | Brainstorm design records | `docs/research/{topic}-brainstorm/` (active; legacy `-brainstorming/`) → `docs/history/brainstorms/{topic}/` (harvested; user deletes or commits) | thesis.md + forks.md + ledger.md + state.md |
 | Backlog | `docs/history/` | backlog.md |