@nurix/etna 0.13.0 → 0.15.1

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

@@ -3,7 +3,7 @@ name: maintenance
 description: Docs-vs-code coherence audit. Detects and fixes docs drifting from code — stale docs, broken ownership, routing table drift, unowned source paths. Run weekly or after major changes. Contract violations (code drifting from docs) are handled by the `boundary` skill (`init` mode); pre-implementation impact checks by its `check` mode.
 tools: Read, Glob, Grep, Edit, Write, Bash
 model: inherit
-plugins: [nurix-harness]
+plugins: [code]
 ---
 
 # Maintenance Agent
@@ -23,21 +23,40 @@ Out of scope (handled by the `boundary` skill):
 ## Step 1: Build Ownership Map
 
 1. Read `docs/structure.md` for the authority map
-2. Glob `docs/features/**/*.md` and extract YAML frontmatter (`owns`, `touches`, `depends_on`)
+2. Glob `docs/{features,modules/*/features}/**/*.md` and extract YAML frontmatter (`owns`, `touches`, `depends_on`)
 3. Build a map: glob pattern → owning doc
 
+**Boundary-first fallback.** If that glob yields **no `owns` frontmatter at all** (a real possibility — a boundary-first repo can carry thousands of LOC, a populated `docs/boundaries/`, and zero feature docs) **but `docs/boundaries/**` exists**, drive this pass's ownership/drift surface off the boundaries instead: each boundary's `Bounds`/`Shape` referents (the modules/paths it names) plus `docs/architecture/**` file-references become the **primary** ownership map for Steps 2–5. Feature-`owns` stays primary the moment any appears — this is a fallback, not a replacement. Don't re-mechanize the named-referent / path checks here; Step 2 already resolves boundary referents and Step 5 already greps architecture paths — this clause just promotes them to primary when feature-owns is empty. **Exempt the pre-code markers:** a referent a boundary marks `planned`/`point*`/`transcribe*` is intentionally not-yet-landed — never flag it absent (that is the greenfield contract, not drift); only a referent whose target *has* landed fires, via Step 2's planned-landed / transcribe-landed checks.
+
 ## Step 2: Validate Ownership
 
 For each doc with `owns` frontmatter:
 - Verify the glob patterns match existing files
 - Report deleted paths, empty globs, orphaned ownership
 
+For each code symbol or path a doc explicitly **names** (function/export/route/type):
+- Verify it resolves in the code, independent of git-churn — Step 3's churn gate is blind to churn-free false claims
+- Flag unresolved named referents as drift, phrased as a question (e.g. `docs/x.md:NN names fn() — no static definition found; confirm it is not generated/re-exported before treating as stale`)
+- On codegen/reflection/DI/barrel stacks where static resolution is unreliable, skip — yielding nothing is correct
+
+Also resolve **`point`-mode boundary pointers** in `docs/boundaries/**/*.md` — a boundary whose `Bounds`/`Shape` carries a `file:line` pointer (e.g. `self-locating in lib/db.js:14`):
+- Verify the named path still exists; a rename (e.g. `lib/db.js`→`lib/store.js`) leaves a stale pointer that **distill② can never repair — boundary docs are write-protected** — so this pass is where it surfaces, as a question
+- If the boundary carries a literal **`planned`** marker (or "pointer lands at implementation") on a named target **and that target now resolves to real code**, the pointer has gone stale the other way — the code landed but the doc still says planned. Raise it as a question (e.g. `db-schema.md is marked planned but packages/api/src/db/schema.ts now exists — confirm and convert the pointer to file:line`). A barrel/re-export at the named path counts as landed.
+- Same skip rule on unreliable-resolution stacks
+
+Also handle **`transcribe`-mode boundaries** — a boundary whose `Shape` transcribes a contract (an event/wire/config shape copied from doctrine) **until** the owning module lands, typically with a checklist line like *"replace this transcription when X lands"*:
+- If **X now exists**, the transcribed shape can have silently diverged from the real one — and a transcription names fields, so the divergence is field-level, not path-level (e.g. an event transcribed as `{ entity, event_kind, … }` against a landed module that uses `eventKind`). Raise it as a question that the transcribed shape be reconciled against the real one — or handed to a proposed `boundary init` run for that file (e.g. `outbox-events.md transcribes event_kind but the landed outbox module uses eventKind — confirm the transcription should be reconciled to the real shape`). Question-phrased, never asserted; never rewrite the boundary doc yourself (write-protected).
+
+Also check **`env-var-contract` boundaries** — a boundary whose job is to assert the env contract (typically *"every variable the code reads appears in `.env.example`"*). The named-referent check above covers code symbols and paths but not env vars, which live in a separate canonical file:
+- Extract the `UPPER_SNAKE` tokens the boundary names in its `Shape` (allow a trailing `*` glob, e.g. `MASTER_KEK*` matching `MASTER_KEK`, `MASTER_KEK_ID`). Grep each against the declared canonical `.env`/`.env.example` (the boundary names which file is canonical).
+- Raise any absence as a question (e.g. `env-vars.md names MASTER_KEK* but no MASTER_KEK* appears in .env.example — confirm the contract still holds`). Same skip rule when the canonical file isn't declared or doesn't exist.
+
 ## Step 3: Detect Doc Drift
 
 Run `git log --since="2 weeks ago" --name-only --pretty=format:"%h %s"` to find changed source files.
 
 For each changed file:
-- Match against `owns` patterns → identify the owning doc
+- Match against `owns` patterns from every feature doc — flat and module-local alike (`docs/{features,modules/*/features}/**/*.md`) → identify the owning doc
 - If no owner exists → flag as unowned
 - If owner exists → compare last modified dates (`git log -1 --format="%ci" -- <path>`), flag docs where code changed more recently (14-day threshold)
 
@@ -46,16 +65,18 @@ For each changed file:
 If `./docs/routing.md` exists:
 
 1. For each row, verify the file pattern matches existing files and referenced docs/agents exist
-2. Check for new top-level `src/` directories not covered by any routing entry
+2. Check for new top-level source directories (the repo's actual source roots — derive them, never assume `src/`) not covered by any routing entry
 3. Fix drift directly, or backlog if unclear
 
 Also flag **unowned paths** — top-level source directories with no owning feature doc (no `owns` glob covers them).
 
+Also catch a **stale greenfield self-label.** If `routing.md` (or `structure.md`) asserts the repo is greenfield — *"Greenfield. No source code or feature docs exist yet"* or similar — **but a real source tree exists** (the derived source roots from this step's item 2 above, or Step 5's Unowned-code derivation, are non-empty, e.g. a populated `packages/` of real workspaces), the self-label has gone stale: the scaffold filled in but the doc still announces an empty repo. Raise it as a question (e.g. `routing.md says "No source code exists yet" but packages/ holds 5 workspaces — confirm the greenfield label should be retired`).
+
 ## Step 5: Check Architecture & Backlog
 
 **Architecture drift:** Grep `docs/architecture/` for file path references. Verify referenced paths still exist. Remove or update stale references.
 
-**Unowned code:** Compare all `src/` top-level directories against the union of all `owns` patterns. Report directories with no feature doc ownership.
+**Unowned code:** Compare the repo's actual top-level source directories (derive them — the top-level dirs that contain code, or the roots named across `owns` globs in `structure.md` / feature frontmatter; do not assume `src/`) against the union of all `owns` patterns from both flat and module-local feature docs (`docs/{features,modules/*/features}/**/*.md`). Report directories with no feature doc ownership.
 
 **Backlog health:** Read `docs/history/backlog.md`. Report items older than 30 days. Count pending by priority.
 
@@ -66,13 +87,29 @@ For each stale doc:
 - If drift is ambiguous (major refactor, unclear intent) → backlog it
 
 For unowned code paths:
-- Append: `- **[P2]** No feature doc owns \`src/{module}/\` — discovered by maintenance`
+- Append: `- **[P2]** No feature doc owns \`{dir}/\` — discovered by maintenance` (`{dir}` = the actual unowned source directory)
+
+**Declined realignment:** When you propose a realignment and the user **declines or does not act**, never drop the finding and never block. Append it to `docs/history/backlog.md` as `- **[P0–P3]** <finding> — discovered by maintenance`, with priority = the finding's own severity **on the same P0–P3 scale as code items** — never a segregated "compliance" section, never auto-relegated to the lowest tier. Record once: dedupe against existing entries; if already present, leave it. (This is the decline branch — it pairs with dispatching a remediation sub-agent on a yes.)
 
 ## Step 7: Report & Update Tracking
 
 1. Update `docs/structure.md` Health Log with today's date and summary
 2. Update `docs/memory/maintenance.md` with last review date, stale docs fixed, unowned paths, backlog items created
 3. Report findings: stale docs, broken ownership, unowned code, architecture drift, backlog health
+4. **Ledger-distillation threshold.** Count undigested ledger entries — `docs/memory/ledger/**/*.md` entries newer than the high-water mark in `docs/memory/facts/.digest-state.md` (absent state-file ⇒ every entry counts). If the count is **≥20**, add one line to the report **proposing** a `distiller` `facts` run — propose only, never auto-run, no cron. If the user declines or ignores it, do nothing: the count keeps growing and the proposal reappears next pass — that recurrence *is* the dedupe, so never backlog it.
+5. **Docs-distillation threshold.** Per target doc, count undigested fact-cards (`invalid_from: null`, the doc's path not in their `digested_into:`) that **touch** it by the structural intersection in `skills/distiller/references/docs-mode.md` Resolution 1 (provenance∩`owns` strong, entities∩declared-ownership supporting — qmd-independent). If **≥10** map to **one** doc, add one line to the report **proposing** a `distiller docs --doc <path>` run on that doc — propose only, never auto-run, no cron. Declined or ignored ⇒ the count keeps growing and the proposal reappears next pass; that recurrence *is* the dedupe, so never backlog the proposal.
+
+## Step 8: Refresh Index (Optional)
+
+If the `qmd` binary is available (`command -v qmd`), re-run `qmd embed -c <collection>` once per `{repo}-*` collection (`{repo}` = the repo's directory name; `qmd collection list` shows the set harness-manager registered — skip any absent) so the local docs index reflects the files this pass touched. Scope every run with `-c` — the qmd index is global (`~/.cache/qmd/` holds every repo's collections), so a bare `qmd embed` would re-embed unrelated repos' collections. If `qmd` is absent, skip silently — it's never required.
+
+## Step 9: Check Anchor Drift (Optional)
+
+If `qmd` is absent (`command -v qmd` finds nothing), **skip this whole step silently** — it's never required.
+
+This catches **doc-area drift** — the subject the doc abstracts moving or vanishing from the indexed corpus. It does **not** catch a pure code rename that leaves the doc's prose unchanged: the anchor query semantically matches the doc's own text, so the result set doesn't shift. Code-symbol drift is Step 2's named-referent check, not this one — the two are complementary, not redundant.
+
+Glob `docs/{features,modules/*/features}/**/*.md`, `docs/boundaries/**/*.md`, `docs/architecture/**/*.md`, and `docs/operations/**/*.md` for docs carrying `anchors:` frontmatter. For each anchor query on such a doc, resolve it with `qmd query --format json -c <collection> "<query>"` — repeat `-c` per relevant `{repo}-*` collection (no comma lists; the collection set is what `qmd collection list` shows). If a query resolves to **nothing**, or to a result set that has **radically shifted** away from the area the doc describes, raise it as a drift finding **phrased as a question** — e.g. `docs/x.md anchors "<query>" — resolves to nothing; confirm the area moved before treating the doc as stale` — and ask the user. On **yes**, dispatch the remediation sub-agent (the same yes-branch as Step 6). On **decline or no action**, append it to `docs/history/backlog.md` at the finding's own P0–P3 severity per the **Declined realignment** branch in Step 6 — same scale, deduped, never a gate.
 
 ---
 

package/data/harnesses/code/agents/performance-review.md

@@ -3,7 +3,7 @@ name: performance-review
 description: Combined dependency + code health audit. Part A audits the dependency supply chain — security CVEs, outdated packages, license compliance, abandoned packages, unwanted transitive dependencies, install size. Part B audits code-level health — bundle size, tree-shaking issues, performance anti-patterns, code-quality flags. Run weekly or before releases. Merges the former `dep-health` and `review` agents so the package tree and the code that uses it are audited together.
 tools: Read, Glob, Grep, Bash
 model: inherit
-plugins: [nurix-harness]
+plugins: [code]
 ---
 
 # Performance-Review Agent

package/data/harnesses/code/agents/spec-mode.md

@@ -5,7 +5,7 @@ tools: Read, Glob, Grep, WebSearch, WebFetch
 model: inherit
 skills:
   - documentation
-plugins: [nurix-harness]
+plugins: [code]
 ---
 
 # Spec Mode Agent
@@ -19,7 +19,7 @@ You do NOT write the spec — you return structured research that the main agent
 First, understand the documentation landscape:
 
 1. Read `./docs/README.md` to understand the documentation structure
-2. Read `./docs/features/README.md` to see existing feature specs and where the new spec fits
+2. If `./docs/features/README.md` exists, read it to see existing feature specs and where the new spec fits; otherwise glob the feature docs directly
 3. If `./docs/memory/spec-mode.md` exists, read it for feature doc inventory, ownership conflict zones, and lessons from previous research
 4. Read 1-2 existing specs in `./docs/features/` to calibrate format and depth
 5. Glob `./docs/{features,modules/*/features}/**/*.md` and read YAML frontmatter (`owns`, `touches`, `depends_on`) from each to build the ownership map.

package/data/harnesses/code/harness.json

@@ -0,0 +1,6 @@
+{
+  "name": "code",
+  "version": "0.15.1",
+  "epoch": 12,
+  "digest": "1bdfd15cf1e5"
+}

package/data/harnesses/code/hooks/hooks.json

@@ -0,0 +1,41 @@
+{
+  "hooks": {
+    "SessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-stop.js\"",
+            "async": true
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/post-tool-failure.js\"",
+            "async": true
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "if": "Bash(git commit *)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/post-commit.js\"",
+            "async": true
+          }
+        ]
+      }
+    ]
+  }
+}

package/data/harnesses/code/hooks/lib/redact.js

@@ -0,0 +1,37 @@
+// harness/code/hooks/lib/redact.js — shared privacy filter: redacts secret shapes before ledger append.
+
+"use strict";
+
+// Patterns ordered most-specific first; each replaces a match with [redacted:{kind}].
+const RULES = [
+  // PEM private/public key blocks (multiline).
+  { kind: "pem", re: /-----BEGIN[\s\S]*?-----END[^-]*-----/g },
+  // OpenAI / Anthropic-style keys (sk-..., sk-ant-...).
+  { kind: "api-key", re: /\bsk-(?:ant-)?[A-Za-z0-9_-]{8,}\b/g },
+  // AWS access key IDs.
+  { kind: "aws-key", re: /\bAKIA[0-9A-Z]{16}\b/g },
+  // Bearer tokens in Authorization context.
+  { kind: "bearer", re: /\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/gi },
+  // password= / passwd= / secret= / token= / api_key= style assignments (= or :).
+  {
+    kind: "credential",
+    re: /\b(?:password|passwd|pwd|secret|token|api[_-]?key|access[_-]?key|client[_-]?secret)\b\s*[:=]\s*["']?[^\s"'&)\]},;[]{3,}/gi,
+  },
+  // Generic long hex/base64 token ONLY in a key-value credential context.
+  {
+    kind: "credential",
+    re: /\b(?:key|auth|cred|credential|signature|sig)\b\s*[:=]\s*["']?[A-Za-z0-9+/=_-]{32,}/gi,
+  },
+];
+
+// Redact secret shapes in arbitrary text; returns a string with placeholders.
+function redact(text) {
+  if (text == null) return "";
+  let out = String(text);
+  for (const rule of RULES) {
+    out = out.replace(rule.re, `[redacted:${rule.kind}]`);
+  }
+  return out;
+}
+
+module.exports = { redact };

package/data/harnesses/code/hooks/post-commit.js

@@ -0,0 +1,136 @@
+// harness/code/hooks/post-commit.js — PostToolUse(Bash git commit) hook: append one decision entry with commit hash + message.
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+const { redact } = require("./lib/redact.js");
+
+// Read all of stdin synchronously; returns "" if nothing is piped.
+function readStdin() {
+  try {
+    return fs.readFileSync(0, "utf8");
+  } catch (e) {
+    return "";
+  }
+}
+
+// Resolve the project root: CLAUDE_PROJECT_DIR env, else payload cwd, else process cwd.
+function resolveProjectDir(payload) {
+  return process.env.CLAUDE_PROJECT_DIR || (payload && payload.cwd) || process.cwd();
+}
+
+// Run a git command in projectDir; returns trimmed stdout or fallback on any error.
+function git(projectDir, args, fallback) {
+  try {
+    return execFileSync("git", ["-C", projectDir, ...args], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim() || fallback;
+  } catch (e) {
+    return fallback;
+  }
+}
+
+// Slug a raw actor name into kebab-case ASCII.
+function slugActor(name) {
+  return String(name || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+// Determine the actor: git user.name (slugged) → $USER → "agent".
+function resolveActor(projectDir) {
+  const fromGit = slugActor(git(projectDir, ["config", "user.name"], ""));
+  if (fromGit) return fromGit;
+  const fromEnv = slugActor(process.env.USER || "");
+  if (fromEnv) return fromEnv;
+  return "agent";
+}
+
+// Truncate a single line to n chars with an ellipsis marker.
+function truncate(text, n) {
+  const clean = String(text || "").replace(/\s+/g, " ").trim();
+  return clean.length > n ? clean.slice(0, n) + "…" : clean;
+}
+
+// Compute the ledger day-file path for a given actor and date.
+function ledgerPath(projectDir, date, actor) {
+  const dir = path.join(projectDir, "docs", "memory", "ledger");
+  return { dir, file: path.join(dir, `${date}--${actor}.md`) };
+}
+
+// Build the day-file header block.
+function header(date, actor) {
+  return `# Ledger — ${date} — ${actor}\nAppend-only event ledger. Raw input to distillation — see docs/memory/.\n`;
+}
+
+// Pull the bash command string from a PostToolUse payload.
+function commandFromPayload(payload) {
+  return (payload && payload.tool_input && payload.tool_input.command) || "";
+}
+
+// True only for an actual `git commit` invocation (start of command or after ;, &&, ||, |) —
+// never for commands that merely mention the words (greps, echoes, heredoc prose).
+function isGitCommitInvocation(command) {
+  return /(^\s*|[;&|]\s*)git\s+(?:-[^\s]+\s+|-C\s+\S+\s+|\S+=\S+\s+)*commit\b/.test(command);
+}
+
+// Main: if the tool was a git commit, append one decision entry with the new commit hash + subject.
+function main() {
+  const raw = readStdin();
+  let payload = {};
+  try {
+    payload = raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    payload = {};
+  }
+
+  if (!isGitCommitInvocation(commandFromPayload(payload))) return;
+  if (payload.tool_response && payload.tool_response.is_error === true) return;
+
+  const projectDir = resolveProjectDir(payload);
+  const actor = resolveActor(projectDir);
+  const repo = path.basename(projectDir);
+  const branch = git(projectDir, ["rev-parse", "--abbrev-ref", "HEAD"], "-");
+
+  const headLine = git(projectDir, ["log", "-1", "--format=%h%x20%s"], "");
+  if (!headLine) return;
+  const spaceIdx = headLine.indexOf(" ");
+  const hash = spaceIdx > 0 ? headLine.slice(0, spaceIdx) : headLine;
+  const subject = spaceIdx > 0 ? headLine.slice(spaceIdx + 1) : "";
+
+  const now = new Date();
+  const pad = (n) => String(n).padStart(2, "0");
+  const date = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+  const hhmm = `${pad(now.getHours())}:${pad(now.getMinutes())}`;
+
+  const lines = [
+    `## ${hhmm} · ${actor} · ${repo}@${branch}`,
+    `- type: decision`,
+    `- what: committed — ${truncate(redact(subject), 200) || "(no subject)"}`,
+    `- refs: commit ${redact(hash)}${payload.session_id ? ` · session ${redact(payload.session_id)}` : ""}`,
+  ];
+
+  const { dir, file } = ledgerPath(projectDir, date, actor);
+  const exists = fs.existsSync(file);
+  // Dedupe: the same commit hash is never logged twice in one day-file.
+  if (exists && fs.readFileSync(file, "utf8").includes(`commit ${hash}`)) return;
+  fs.mkdirSync(dir, { recursive: true });
+  const block = (exists ? "\n" : header(date, actor) + "\n") + lines.join("\n") + "\n";
+  fs.appendFileSync(file, block, "utf8");
+}
+
+try {
+  main();
+} catch (e) {
+  try {
+    process.stderr.write(`post-commit hook: ${e && e.message ? e.message : e}\n`);
+  } catch (e2) {
+    // Nothing more we can do.
+  }
+} finally {
+  process.exit(0);
+}

package/data/harnesses/code/hooks/post-tool-failure.js

@@ -0,0 +1,136 @@
+// harness/code/hooks/post-tool-failure.js — PostToolUseFailure hook: append one high-surprisal failure entry.
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+const { redact } = require("./lib/redact.js");
+
+// Read all of stdin synchronously; returns "" if nothing is piped.
+function readStdin() {
+  try {
+    return fs.readFileSync(0, "utf8");
+  } catch (e) {
+    return "";
+  }
+}
+
+// Resolve the project root: CLAUDE_PROJECT_DIR env, else payload cwd, else process cwd.
+function resolveProjectDir(payload) {
+  return process.env.CLAUDE_PROJECT_DIR || (payload && payload.cwd) || process.cwd();
+}
+
+// Run a git command in projectDir; returns trimmed stdout or fallback on any error.
+function git(projectDir, args, fallback) {
+  try {
+    return execFileSync("git", ["-C", projectDir, ...args], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim() || fallback;
+  } catch (e) {
+    return fallback;
+  }
+}
+
+// Slug a raw actor name into kebab-case ASCII.
+function slugActor(name) {
+  return String(name || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+// Determine the actor: git user.name (slugged) → $USER → "agent".
+function resolveActor(projectDir) {
+  const fromGit = slugActor(git(projectDir, ["config", "user.name"], ""));
+  if (fromGit) return fromGit;
+  const fromEnv = slugActor(process.env.USER || "");
+  if (fromEnv) return fromEnv;
+  return "agent";
+}
+
+// Truncate a single line to n chars with an ellipsis marker.
+function truncate(text, n) {
+  const clean = String(text || "").replace(/\s+/g, " ").trim();
+  return clean.length > n ? clean.slice(0, n) + "…" : clean;
+}
+
+// Compute the ledger day-file path for a given actor and date.
+function ledgerPath(projectDir, date, actor) {
+  const dir = path.join(projectDir, "docs", "memory", "ledger");
+  return { dir, file: path.join(dir, `${date}--${actor}.md`) };
+}
+
+// Build the day-file header block.
+function header(date, actor) {
+  return `# Ledger — ${date} — ${actor}\nAppend-only event ledger. Raw input to distillation — see docs/memory/.\n`;
+}
+
+// Take the first non-empty line of an error string.
+function firstLine(text) {
+  const lines = String(text || "").split("\n");
+  for (const line of lines) {
+    if (line.trim()) return line.trim();
+  }
+  return "";
+}
+
+// Main: append one failure entry describing the tool and its error, never blocking.
+function main() {
+  const raw = readStdin();
+  let payload = {};
+  try {
+    payload = raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    payload = {};
+  }
+
+  const errorText = payload.error || (payload.error_details && payload.error_details.message) || "";
+  if (!errorText && !payload.tool_name) return;
+
+  const projectDir = resolveProjectDir(payload);
+  const actor = resolveActor(projectDir);
+  const repo = path.basename(projectDir);
+  const branch = git(projectDir, ["rev-parse", "--abbrev-ref", "HEAD"], "-");
+
+  const now = new Date();
+  const pad = (n) => String(n).padStart(2, "0");
+  const date = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+  const hhmm = `${pad(now.getHours())}:${pad(now.getMinutes())}`;
+
+  const tool = payload.tool_name || "unknown-tool";
+  const detail = truncate(redact(firstLine(errorText)), 200) || "(no error message)";
+  const command =
+    payload.tool_input && payload.tool_input.command
+      ? ` · cmd: ${truncate(redact(payload.tool_input.command), 100)}`
+      : "";
+
+  const lines = [
+    `## ${hhmm} · ${actor} · ${repo}@${branch}`,
+    `- type: failure`,
+    `- what: ${redact(tool)} failed — ${detail}${command}`,
+  ];
+  const refs = [];
+  if (payload.session_id) refs.push(`session ${payload.session_id}`);
+  if (payload.tool_use_id) refs.push(`tool ${payload.tool_use_id}`);
+  if (refs.length) lines.push(`- refs: ${redact(refs.join(" · "))}`);
+
+  const { dir, file } = ledgerPath(projectDir, date, actor);
+  const exists = fs.existsSync(file);
+  fs.mkdirSync(dir, { recursive: true });
+  const block = (exists ? "\n" : header(date, actor) + "\n") + lines.join("\n") + "\n";
+  fs.appendFileSync(file, block, "utf8");
+}
+
+try {
+  main();
+} catch (e) {
+  try {
+    process.stderr.write(`post-tool-failure hook: ${e && e.message ? e.message : e}\n`);
+  } catch (e2) {
+    // Nothing more we can do.
+  }
+} finally {
+  process.exit(0);
+}