@nurix/etna 0.19.43 → 0.19.45

package/data/harnesses/apollo/hooks/check-ownership.mjs

@@ -0,0 +1,22 @@
+// harness/code/hooks/check-ownership.mjs — CI backstop: every owns: glob must match at least one
+// file, unless an unexpired `waived:` dead-glob row in docs/operations/bookkeeping.md covers it
+// (the waiver names the glob verbatim). Exit 1 on any unwaived dead glob.
+
+import { deadGlobs } from "./lib/ownership.mjs";
+import { readQueue, unexpiredWaivers } from "./lib/state.mjs";
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const today = new Date().toISOString().slice(0, 10);
+
+const dead = deadGlobs(projectDir);
+const waivers = unexpiredWaivers(readQueue(projectDir), "dead-glob", today);
+const unwaived = dead.filter((d) => !waivers.some((w) => w.body.includes(d.glob)));
+
+if (unwaived.length === 0) {
+  console.log(`check-ownership: OK (${dead.length} dead glob(s), all waived or none)`);
+  process.exit(0);
+}
+console.error(`check-ownership: ${unwaived.length} unwaived dead owns: glob(s):`);
+for (const d of unwaived) console.error(`  ${d.glob} → ${d.doc}`);
+console.error("Fix the owning doc's owns: frontmatter, or add a `waived:` dead-glob row with reason + expires=.");
+process.exit(1);

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

@@ -0,0 +1,353 @@
+// harness/code/hooks/compliance.mjs — the gate-always-waivable hook module.
+// PreToolUse (Edit|Write|MultiEdit|Bash): deny what is never legitimate (frozen records, protected
+// files, plan-gate skips, changelog-less commits, off-catalog packages), ask where intent matters
+// (branches, live commands, test files mid-plan, off-map doc paths). Stop: block an arc that tries
+// to end with unresolved bookkeeping or an unrecorded plan completion. Every gate fails open — a
+// crash or unreadable repo allows the action; enforcement is never allowed to become an outage.
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { readStdin, resolveProjectDir, frontmatter } from "./lib/ownership.mjs";
+import { readQueue, countRows, askedThisSession, recordAsked } from "./lib/state.mjs";
+import { frozenStatus } from "./lib/frozen.mjs";
+
+function readSafe(file) {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch (e) {
+    return "";
+  }
+}
+
+function relIfInside(projectDir, filePath) {
+  if (!filePath) return null;
+  const rel = path.relative(projectDir, path.resolve(projectDir, filePath));
+  if (rel.startsWith("..") || path.isAbsolute(rel)) return null;
+  return rel.split(path.sep).join("/");
+}
+
+function git(projectDir, args) {
+  const res = spawnSync("git", args, { cwd: projectDir, encoding: "utf8", timeout: 5000 });
+  return res.status === 0 ? (res.stdout || "").trim() : null;
+}
+
+function decision(permissionDecision, reason) {
+  return {
+    hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision, permissionDecisionReason: reason },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// PreToolUse — file gates
+// ---------------------------------------------------------------------------
+
+function protectedPaths(projectDir) {
+  const listFile = path.join(projectDir, "docs", "operations", "protected-files.md");
+  const paths = ["AGENTS.md", "docs/operations/protected-files.md"];
+  const text = readSafe(listFile);
+  for (const m of text.matchAll(/`([^`\n]+)`/g)) {
+    const candidate = m[1].trim();
+    if (candidate && !candidate.includes(" ")) paths.push(candidate.replace(/^\.\//, ""));
+  }
+  return paths;
+}
+
+// Open plans in the new format only (a `Gates:` line present). Plans without one are
+// legacy and pass every plan gate — otherwise every open plan bricks on harness upgrade.
+function openGatedPlans(projectDir) {
+  const dir = path.join(projectDir, "docs", "history", "plans");
+  let entries;
+  try {
+    entries = fs.readdirSync(dir).filter((f) => f.endsWith(".md"));
+  } catch (e) {
+    return [];
+  }
+  const plans = [];
+  for (const file of entries) {
+    const text = readSafe(path.join(dir, file));
+    const status = (/^\*\*Status:\*\*\s*(.+)$/m.exec(text) || [])[1]?.trim();
+    if (!status || /Complete|Abandoned/.test(status)) continue;
+    const gates = (/^\*\*Gates:\*\*\s*(.+)$/m.exec(text) || [])[1]?.trim();
+    if (!gates) continue; // legacy tolerance
+    plans.push({ file, status, gates, hasLedger: /^##\s+Test Obligations\b/m.test(text) });
+  }
+  return plans;
+}
+
+const TEST_FILE_RE = /(^|\/)tests?\/|\.test\.|\.spec\./;
+const SOURCE_LIKE = /\.(m?[jt]sx?|py|rs|go|rb|java|kt|swift|c|h|cpp|hpp|cs|sh|sql|vue|svelte)$/;
+
+function fileGate(projectDir, rel, toolName) {
+  const frozen = frozenStatus(projectDir, rel);
+  if (frozen.frozen) {
+    return decision(
+      "deny",
+      `BLOCKED — frozen record. \`${rel}\` is committed history and is never edited (${frozen.reason}). A correction is a new dated entry that links back.`
+    );
+  }
+
+  if (protectedPaths(projectDir).includes(rel)) {
+    return decision("deny", `BLOCKED — protected file. \`${rel}\` is on the protected list.`);
+  }
+
+  const inDocs = rel.startsWith("docs/") || rel.startsWith(".claude/") || rel.endsWith(".md");
+  if (!inDocs && SOURCE_LIKE.test(rel)) {
+    for (const plan of openGatedPlans(projectDir)) {
+      if (/Boundary:\s*pending/i.test(plan.gates)) {
+        return decision(
+          "deny",
+          `BLOCKED — plan gate. \`${plan.file}\` is open but its Gates line reads 'Boundary: pending'. Run the \`boundary\` skill and record its verdict in the plan before implementation edits.`
+        );
+      }
+      if (!plan.hasLedger) {
+        return decision(
+          "deny",
+          `BLOCKED — plan gate. \`${plan.file}\` has no \`## Test Obligations\` section. Run the \`test-plan\` skill; its ledger is what the verification gate discharges.`
+        );
+      }
+    }
+  }
+
+  if (toolName === "Write" && TEST_FILE_RE.test(rel)) {
+    const midPlan = openGatedPlans(projectDir).some((p) => /In Progress/i.test(p.status));
+    if (midPlan) {
+      return decision(
+        "ask",
+        "Create a test file mid-plan? Plan builds defer tests to the verification gate — proceed only if this is a bug-fix regression test (fails before the fix, passes after)."
+      );
+    }
+  }
+
+  // Doc placement is never an interruption: an off-map docs/ folder is detected silently by
+  // the awareness module (a `doc-placement` auto: row) and resolved by the bookkeeper.
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// PreToolUse — Bash gates
+// ---------------------------------------------------------------------------
+
+const LOCKFILES = /^(pnpm-lock\.yaml|package-lock\.json|yarn\.lock|bun\.lockb?|Cargo\.lock)$/;
+
+// Exempt per the changelog rule's closed list, judged mechanically: lockfile-only,
+// harness-file-only (.claude/, AGENTS.md, CLAUDE.md), or changelog housekeeping.
+function stagedExempt(files) {
+  return files.every(
+    (f) =>
+      LOCKFILES.test(path.basename(f)) ||
+      f.startsWith(".claude/") ||
+      f === "AGENTS.md" ||
+      f === "CLAUDE.md" ||
+      f.startsWith("docs/history/changelog/") ||
+      f === "docs/history/CHANGELOG.md"
+  );
+}
+
+function commitGate(projectDir) {
+  const staged = (git(projectDir, ["diff", "--cached", "--name-only"]) || "")
+    .split("\n")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  if (staged.length > 0 && !stagedExempt(staged)) {
+    if (!staged.some((f) => f.startsWith("docs/history/changelog/"))) {
+      return decision(
+        "deny",
+        "BLOCKED — changelog. This commit stages no `docs/history/changelog/` entry. Every non-exempt commit carries its entry inside it (exempt: release/bot, lockfile-only, pure renames, changelog housekeeping — state which if claiming one, then stage accordingly or re-run)."
+      );
+    }
+  }
+  const counts = countRows(readQueue(projectDir));
+  if (counts.unresolved > 0) {
+    return decision(
+      "deny",
+      `BLOCKED — bookkeeping. ${counts.unresolved} unresolved row(s) in docs/operations/bookkeeping.md. Dispatch the bookkeeper, resolve, or convert to \`waived:\` with a reason and expiry.`
+    );
+  }
+  return null;
+}
+
+// Package names approved anywhere in the rules (general.md table + testing.md's frameworks).
+function approvedPackages(projectDir) {
+  const names = new Set();
+  for (const rule of ["general.md", "testing.md"]) {
+    const text = readSafe(path.join(projectDir, ".claude", "rules", rule));
+    for (const m of text.matchAll(/`(@?[a-z0-9][\w./-]*)`/g)) names.add(m[1]);
+  }
+  return names;
+}
+
+function packageGate(projectDir, command) {
+  const m = new RegExp(String.raw`(?:^|&&|;|\|)\s*(?:sudo\s+)?(?:pnpm|npm|yarn|bun)\s+(?:add|install|i)\s+(.+)`).exec(command);
+  if (!m) return null;
+  const approved = approvedPackages(projectDir);
+  if (approved.size === 0) return null; // no rules file installed — nothing to enforce
+  const args = m[1].split(/\s+/).filter((a) => a && !a.startsWith("-"));
+  for (const arg of args) {
+    const pkg = arg.startsWith("@") ? arg.split("@").slice(0, 2).join("@") : arg.split("@")[0];
+    if (!pkg || pkg === "." || pkg.includes("/") && !pkg.startsWith("@")) continue;
+    if (!approved.has(pkg)) {
+      return decision(
+        "deny",
+        `BLOCKED — package table. \`${pkg}\` is not in the approved table (.claude/rules/general.md; test packages: .claude/rules/testing.md). The table changes only by explicit user decision.`
+      );
+    }
+  }
+  return null;
+}
+
+// The repo a Bash command acts on: an explicit `cd <dir>` in the command wins, then the
+// payload's cwd, then the session's home project — a session may operate across repos
+// (forge + consumer), and gating a commit against the wrong repo blocks or passes falsely.
+function commandRoot(projectDir, payload, command) {
+  const cdMatch = /(?:^|&&|;)\s*cd\s+"?([^"\s;&]+)"?/.exec(command || "");
+  for (const candidate of [cdMatch && cdMatch[1], payload.cwd]) {
+    if (!candidate || !path.isAbsolute(candidate)) continue;
+    try {
+      if (fs.statSync(candidate).isDirectory()) return candidate;
+    } catch (e) {
+      /* fall through */
+    }
+  }
+  return projectDir;
+}
+
+// An ask class fires once per session: the first occurrence asks, later ones pass silently —
+// the user has already exercised judgment on this class this session.
+function askOnce(projectDir, sessionId, key, message) {
+  if (askedThisSession(projectDir, sessionId, key)) return null;
+  recordAsked(projectDir, sessionId, key);
+  return decision("ask", message);
+}
+
+// Command matchers anchor at statement boundaries (start, &&, ;, |) so quoted text — an
+// echoed payload, a commit message naming a command — can never trigger a gate.
+const AT_STATEMENT = String.raw`(?:^|&&|;|\|)\s*(?:sudo\s+)?(?:npx\s+(?:--yes\s+)?)?`;
+const statement = (body) => new RegExp(AT_STATEMENT + body);
+
+function bashGate(projectDir, command, sessionId) {
+  if (!command) return null;
+
+  if (statement(String.raw`git\s+commit\b`).test(command)) {
+    return commitGate(projectDir);
+  }
+
+  if (statement(String.raw`git\s+(checkout\s+-b|switch\s+-c|branch\s+\S+|worktree\s+add)\b`).test(command)) {
+    return askOnce(
+      projectDir,
+      sessionId,
+      "branch-worktree",
+      "Create a branch/worktree? Policy allows this only when you asked for a PR or branch."
+    );
+  }
+
+  if (
+    statement(String.raw`wrangler(?:@\S+)?\b.*(\bd1\s+execute\b.*--remote|\bsecret\s+(put|bulk)\b|\bdeploy\b)`).test(command) &&
+    !/--dry-run\b|--local\b/.test(command)
+  ) {
+    return askOnce(
+      projectDir,
+      sessionId,
+      "live-command",
+      "Run this live-system command (deploy / remote DB / secrets)? If it's a one-shot migration, its runbook should exist in docs/history/migrations/ first. Asked once per session."
+    );
+  }
+
+  return packageGate(projectDir, command);
+}
+
+// ---------------------------------------------------------------------------
+// Stop
+// ---------------------------------------------------------------------------
+
+// True when the transcript's recent tail shows a bookkeeper dispatch this turn — best-effort:
+// absent or unreadable transcript reads as "not dispatched".
+function bookkeeperDispatched(transcriptPath) {
+  const text = readSafe(transcriptPath || "");
+  if (!text) return false;
+  const tail = text.slice(-200000);
+  return /bookkeeper/i.test(tail) && /"(Task|Agent)"/.test(tail);
+}
+
+// Plans this session flipped to Complete: Status is Complete AND the file appears in this
+// machine's touched.tsv (written by the awareness detector as edits happen).
+function plansCompletedThisSession(projectDir) {
+  const touched = readSafe(path.join(projectDir, ".claude", "state", "touched.tsv"));
+  const touchedPlans = new Set(
+    touched
+      .split("\n")
+      .map((line) => line.split("\t")[1])
+      .filter((p) => p && p.startsWith("docs/history/plans/"))
+  );
+  const out = [];
+  for (const rel of touchedPlans) {
+    const text = readSafe(path.join(projectDir, rel));
+    if (/^\*\*Status:\*\*\s*Complete\b/m.test(text)) out.push(rel);
+  }
+  return out;
+}
+
+function stopGate(projectDir, payload) {
+  if (payload.stop_hook_active) return null; // the runtime's infinite-loop guard — never re-block
+
+  const counts = countRows(readQueue(projectDir));
+  if (counts.unresolved > 0 && !bookkeeperDispatched(payload.transcript_path)) {
+    return {
+      decision: "block",
+      reason:
+        `${counts.unresolved} unresolved bookkeeping rows (${counts.auto} auto, ${counts.note} note, ${counts.needsSession} needs-session) in docs/operations/bookkeeping.md. ` +
+        "Dispatch the `bookkeeper` agent to drain them, resolve them now, or convert to `waived:` rows with reason + expiry. " +
+        "If implementation of the open plan is complete, also report it and offer the verification gate — never run it unbidden.",
+    };
+  }
+
+  const completed = plansCompletedThisSession(projectDir);
+  if (completed.length > 0) {
+    const drafts = git(projectDir, ["status", "--porcelain", "--", "docs/history/changelog/"]) || "";
+    if (!drafts.trim()) {
+      return {
+        decision: "block",
+        reason: `Plan \`${completed[0]}\` reached Status: Complete this session with no changelog entry drafted. Write the draft now (documentation skill → templates/changelog-entry.md) — the Ask quotes, rejected iterations, and skill verdicts that fill it exist only in this session and die with it.`,
+      };
+    }
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+
+function main() {
+  const raw = readStdin();
+  let payload = {};
+  try {
+    payload = raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    payload = {};
+  }
+  const projectDir = resolveProjectDir(payload);
+  const event = payload.hook_event_name;
+
+  let out = null;
+  if (event === "PreToolUse") {
+    const input = payload.tool_input || {};
+    if (payload.tool_name === "Bash") {
+      out = bashGate(commandRoot(projectDir, payload, input.command), input.command, payload.session_id);
+    } else {
+      const rel = relIfInside(projectDir, input.file_path || input.notebook_path);
+      if (rel) out = fileGate(projectDir, rel, payload.tool_name);
+    }
+  } else if (event === "Stop") {
+    out = stopGate(projectDir, payload);
+  }
+
+  if (out) process.stdout.write(JSON.stringify(out));
+}
+
+try {
+  main();
+} catch (e) {
+  // Fail open: a broken gate must never become an outage.
+} finally {
+  process.exit(0);
+}

package/data/harnesses/apollo/hooks/hooks.json

@@ -1,16 +1,22 @@
 {
+  "permissions": {
+    "allow": [
+      "Edit(docs/**)",
+      "Write(docs/**)"
+    ]
+  },
   "hooks": {
     "SessionStart": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/generate-ownership-index.mjs\"",
-            "timeout": 10
-          }
-        ]
-      }
+      { "matcher": "", "hooks": [ { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/awareness.mjs\"", "timeout": 10 } ] }
+    ],
+    "PostToolUse": [
+      { "matcher": "Edit|Write|MultiEdit|Bash", "hooks": [ { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/awareness.mjs\"", "timeout": 10 } ] }
+    ],
+    "PreToolUse": [
+      { "matcher": "Edit|Write|MultiEdit|Bash", "hooks": [ { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/compliance.mjs\"", "timeout": 10 } ] }
+    ],
+    "Stop": [
+      { "matcher": "", "hooks": [ { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/compliance.mjs\"", "timeout": 15 } ] }
     ]
   }
 }

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

@@ -0,0 +1,58 @@
+// harness/code/hooks/lib/frozen.mjs — the frozen-record predicate, shared by the compliance gate
+// and CI. Frozen: a committed docs/history/changelog/ entry, a plan whose Status is Complete or
+// Abandoned, an outcome-stamped migration runbook. Immutability begins at commit for changelog
+// entries (a draft in the working tree is meant to be edited), at the status flip for plans, and
+// at the Executed stamp for runbooks. Every check fails open: no git, unreadable file ⇒ not frozen.
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+function relPosix(projectDir, filePath) {
+  return path.relative(projectDir, path.resolve(projectDir, filePath)).split(path.sep).join("/");
+}
+
+// True when git tracks the file at HEAD (i.e. it has been committed at least once).
+export function isCommitted(projectDir, filePath) {
+  const rel = relPosix(projectDir, filePath);
+  const res = spawnSync("git", ["cat-file", "-e", `HEAD:${rel}`], { cwd: projectDir, stdio: "ignore" });
+  return res.status === 0;
+}
+
+function readSafe(projectDir, filePath) {
+  try {
+    return fs.readFileSync(path.resolve(projectDir, filePath), "utf8");
+  } catch (e) {
+    return "";
+  }
+}
+
+// The predicate. Returns { frozen: boolean, reason?: string }.
+export function frozenStatus(projectDir, filePath) {
+  const rel = relPosix(projectDir, filePath);
+  if (rel.startsWith("docs/history/changelog/") && rel.endsWith(".md")) {
+    if (isCommitted(projectDir, rel)) {
+      return { frozen: true, reason: "committed changelog entry — immutability begins at commit" };
+    }
+    return { frozen: false };
+  }
+  if (rel.startsWith("docs/history/plans/") && rel.endsWith(".md")) {
+    const text = readSafe(projectDir, rel);
+    if (/^\*\*Status:\*\*\s*(Complete|Abandoned)\b/m.test(text)) {
+      return { frozen: true, reason: "plan with Status: Complete or Abandoned" };
+    }
+    return { frozen: false };
+  }
+  if (rel.startsWith("docs/history/migrations/") && rel.endsWith(".md")) {
+    const text = readSafe(projectDir, rel);
+    if (/^\*\*Executed:\*\*\s*\d{4}-\d{2}-\d{2}/m.test(text)) {
+      return { frozen: true, reason: "outcome-stamped migration runbook" };
+    }
+    return { frozen: false };
+  }
+  return { frozen: false };
+}
+
+export function isFrozen(projectDir, filePath) {
+  return frozenStatus(projectDir, filePath).frozen;
+}