kataster 0.0.0-stage → 0.2.0

package/.claude/hooks/path-rules.ts

@@ -0,0 +1,66 @@
+/**
+ * Path-scoped rules (`.claude/rules/*.md`) for harnesses without native support.
+ *
+ * Claude Code reads `.claude/rules/` itself and scopes each rule by its `paths:` frontmatter. OpenCode has no
+ * path-scoped rules, so `.opencode/plugins/kataster` calls this script whenever a file is read or written and
+ * attaches the matching rules to the session as keyed instruction entries. One source of truth, two harnesses.
+ *
+ *   echo '{"paths":["libs/shared/src/index.ts"],"cwd":"/repo"}' | node .claude/hooks/path-rules.ts
+ *
+ * Output: `{"rules":[{"key":"<slug>","value":"<rule body>"}]}` – empty when nothing matches. This hook never
+ * blocks; a broken rule must not stop a tool call.
+ */
+import { readFileSync } from "node:fs";
+import { isAbsolute, relative, sep } from "node:path";
+import { globToRegExp, validateRules } from "../lib/architecture.ts";
+import { ROOT } from "../lib/repo.ts";
+
+interface Entry {
+  key: string;
+  value: string;
+}
+
+let data: Record<string, unknown>;
+try {
+  data = JSON.parse(readFileSync(0, "utf8"));
+} catch {
+  process.exit(0);
+}
+
+const root = typeof data.cwd === "string" && data.cwd ? data.cwd : ROOT;
+const raw = Array.isArray(data.paths)
+  ? data.paths
+  : data.tool_input && typeof data.tool_input === "object" && typeof (data.tool_input as Record<string, unknown>).file_path === "string"
+    ? [(data.tool_input as Record<string, unknown>).file_path]
+    : [];
+
+const files = raw
+  .filter((p): p is string => typeof p === "string" && p.length > 0)
+  .map((p) => toRepoPath(root, p))
+  .filter((p): p is string => p !== undefined);
+if (!files.length) fail();
+
+const { rules } = validateRules(root);
+const matched: Entry[] = [];
+for (const rule of rules) {
+  if (!rule.paths.some((glob) => files.some((file) => globToRegExp(glob).test(file)))) continue;
+  const key = rule.path.replace(/^\.claude\/rules\//, "").replace(/\.md$/, "").replaceAll("/", "-");
+  const scope = `Applies to ${rule.paths.map((p) => `\`${p}\``).join(", ")}.`;
+  matched.push({ key, value: `${scope}\n\n${rule.body}` });
+}
+
+process.stdout.write(JSON.stringify({ rules: matched }));
+process.exit(0);
+
+/** Repository-relative POSIX path, or undefined when the file is outside the repository. */
+function toRepoPath(root: string, path: string): string | undefined {
+  const rel = isAbsolute(path) ? relative(root, path) : path;
+  const posix = rel.split(sep).join("/").replace(/^\.\//, "");
+  if (!posix || posix.startsWith("../") || posix === ".." || isAbsolute(posix)) return undefined;
+  return posix;
+}
+
+function fail(): never {
+  process.stdout.write(JSON.stringify({ rules: [] }));
+  process.exit(0);
+}

package/.claude/hooks/project-check.ts

@@ -0,0 +1,108 @@
+/**
+ * Project-check dispatcher – one hook, project-owned checks.
+ *
+ *   docs/engineering/checks.yaml lists checks with a `phase` (edit | stop | ci), optional `paths` globs,
+ *   a timeout and an optional `advisory` flag. This script runs the checks for the phase:
+ *
+ *     edit  – after Write/Edit (PostToolUse); only checks whose `paths` match the changed file
+ *     stop  – full set; called by the stop gate and by `verify.ts`
+ *
+ * It is wired into both harnesses once (Claude settings, OpenCode plugin). Adding a check never touches the
+ * hook wiring; adding an arbitrary hook per package is deliberately not supported.
+ */
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { loadChecks, matchesAny, relPath, type Phase } from "../lib/architecture.ts";
+import { ROOT } from "../lib/repo.ts";
+
+const args = process.argv.slice(2);
+const phaseArg = args[args.indexOf("--phase") + 1];
+const phase: Phase = phaseArg === "stop" || phaseArg === "ci" ? phaseArg : "edit";
+const changedIndex = args.indexOf("--changed");
+const changedArg = changedIndex === -1 ? undefined : args[changedIndex + 1];
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function tail(text: string, lines = 40): string {
+  return text.trim().split("\n").slice(-lines).join("\n");
+}
+
+let changed = changedArg && !changedArg.startsWith("--") ? changedArg : process.env.CHANGED_FILE;
+
+if (phase === "edit" && !changed && !process.stdin.isTTY) {
+  // The hook payload carries the changed file; a stop/CI run has none.
+  try {
+    const raw = readFileSync(0, "utf8").trim();
+    if (raw) {
+      const data = JSON.parse(raw) as { cwd?: string; tool_input?: { file_path?: unknown } };
+      const fp = data.tool_input?.file_path;
+      if (typeof fp === "string" && fp) changed = isAbsolute(fp) ? fp : join(data.cwd ?? ROOT, fp);
+    }
+  } catch {
+    // no stdin or malformed payload – there is nothing to scope an edit check to
+  }
+}
+
+if (changed) changed = relPath(ROOT, changed);
+
+try {
+  const config = loadChecks(ROOT);
+  const checks = config?.checks ?? [];
+  if (!checks.length) process.exit(0);
+  if (phase === "edit" && !changed) process.exit(0);
+
+  const failures: string[] = [];
+  const notes: string[] = [];
+
+  for (const check of checks) {
+    if (check.phase !== phase) continue;
+    // `paths` scopes the edit-time check. Stop/CI runs the full set.
+    if (phase === "edit" && check.paths.length) {
+      if (!changed) continue;
+      if (!matchesAny(changed, check.paths)) continue;
+    }
+
+    const command = check.command.replaceAll("{changed}", changed ? shellQuote(changed) : "");
+    const result = spawnSync(command, {
+      cwd: ROOT,
+      shell: true,
+      encoding: "utf8",
+      timeout: check.timeout * 1000,
+      env: { ...process.env, CHANGED_FILE: changed ?? "", KATASTER_PHASE: phase },
+    });
+    const ok = result.status === 0;
+    if (ok) continue;
+
+    const timedOut = result.error && "code" in result.error && result.error.code === "ETIMEDOUT";
+    const detail = timedOut
+      ? `timed out after ${check.timeout}s`
+      : tail(`${result.stdout ?? ""}${result.stderr ?? ""}`) || `exit ${result.status ?? "?"}`;
+    const block = `── ${check.name} ──\n${detail}`;
+    if (check.advisory) notes.push(block);
+    else failures.push(block);
+  }
+
+  if (failures.length) {
+    process.stderr.write(
+      `Project checks failed – fix before continuing:\n\n${failures.join("\n\n")}\n\n` +
+        "A brownfield violation that already existed belongs in the baseline (boundary-check --update-baseline), not in a red hook.\n",
+    );
+    process.exit(2);
+  }
+
+  if (notes.length) {
+    console.log(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: phase === "edit" ? "PostToolUse" : "Stop",
+        additionalContext: `Project checks (advisory):\n\n${notes.join("\n\n")}`,
+      },
+    }));
+  }
+  process.exit(0);
+} catch (error) {
+  process.stderr.write(`Project check configuration is broken:\n${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(2);
+}

package/.claude/hooks/protect-files.ts

@@ -0,0 +1,55 @@
+/**
+ * PreToolUse hook (Write|Edit|MultiEdit): protects files that must not be edited by hand.
+ *
+ * - Generated files (BACKLOG.md, event-storming.md) → blocked; they are rendered by hooks and scripts.
+ * - Accepted ADRs are never edited, only superseded: the only change allowed is
+ *   `status: accepted` → `status: superseded by ADR-NNNN`.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { rel, ROOT } from "../lib/discovery.ts";
+
+const GENERATED = new Set(["docs/stories/BACKLOG.md", "docs/domain/event-storming.md"]);
+
+let data: Record<string, any>;
+try {
+  data = JSON.parse(readFileSync(0, "utf8"));
+} catch {
+  process.exit(0);
+}
+const ti = data.tool_input ?? {};
+const fp: unknown = ti.file_path;
+if (typeof fp !== "string" || !fp) process.exit(0);
+const path = isAbsolute(fp) ? fp : join(data.cwd || ROOT, fp);
+const r = rel(path);
+
+function block(msg: string): never {
+  process.stderr.write(`Blocked: ${msg}\n`);
+  process.exit(2);
+}
+
+if (GENERATED.has(r)) block(`'${r}' is generated – change its sources (story files, events.yaml) instead.`);
+
+if (/^docs\/adr\/\d{4}-.*\.md$/.test(r) && existsSync(path)) {
+  const old = readFileSync(path, "utf8");
+  if (!/^status:\s*accepted\s*$/m.test(old)) process.exit(0);
+
+  let next: string;
+  if (data.tool_name === "Write") {
+    next = String(ti.content ?? "");
+  } else {
+    const edits: { old_string: string; new_string: string; replace_all?: boolean }[] =
+      data.tool_name === "MultiEdit" ? ti.edits ?? [] : [ti];
+    next = old;
+    for (const e of edits) next = e.replace_all ? next.split(e.old_string).join(e.new_string) : next.replace(e.old_string, e.new_string);
+  }
+  const withoutStatus = (t: string) => t.replace(/^status:.*$/m, "");
+  const newStatus = /^status:\s*(.*?)\s*$/m.exec(next)?.[1] ?? "";
+  if (withoutStatus(next) !== withoutStatus(old) || !/^superseded by ADR-\d{4}$/.test(newStatus)) {
+    block(
+      `'${r}' is an accepted ADR. Accepted ADRs are never edited – write a new ADR (status: proposed) and, ` +
+        "once the user accepts it, only change this one's status to 'superseded by ADR-NNNN'.",
+    );
+  }
+}
+process.exit(0);

package/.claude/hooks/session-start.ts

@@ -0,0 +1,213 @@
+/**
+ * SessionStart hook: what a fresh checkout is still missing (only what is missing),
+ * and where the work stands – branch, stories in progress, the next story, the last verify result.
+ *
+ * Everything project-specific comes from `.claude/project.json`; this file contains no project knowledge.
+ * The setup checks run before anything is imported from .claude/lib, so they still work when the
+ * tooling dependencies are not installed yet.
+ */
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const root = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+
+type Profile = {
+  name?: string;
+  kind?: "greenfield" | "brownfield";
+  languages?: { artifacts?: string; ui?: string };
+  commands?: { install?: string };
+  review?: { preview?: string; pullRequest?: string };
+  setup?: { envFile?: string; envHint?: string };
+  backlog?: {
+    provider?: "local" | "github" | "jira";
+    jira?: { project?: string; mcpServer?: string };
+    github?: { repo?: string };
+  };
+};
+
+function profile(): Profile {
+  try {
+    return JSON.parse(readFileSync(join(root, ".claude", "project.json"), "utf8")) as Profile;
+  } catch {
+    return {};
+  }
+}
+
+/** Runs a command with stderr folded into stdout; `ok` is the exit status. */
+function sh(command: string): { ok: boolean; out: string } {
+  try {
+    return { ok: true, out: execSync(`${command} 2>&1`, { cwd: root, encoding: "utf8", timeout: 5000 }).trim() };
+  } catch (e) {
+    const err = e as { stdout?: string };
+    return { ok: false, out: (err.stdout ?? "").trim() };
+  }
+}
+
+type McpApproval = {
+  mcpServers?: Record<string, unknown>;
+  enableAllProjectMcpServers?: boolean;
+  enabledMcpjsonServers?: string[];
+  disabledMcpjsonServers?: string[];
+};
+
+/** A JSON settings file, or nothing when it is missing, unreadable or too large to bother. */
+function readJson(path: string): Record<string, unknown> | undefined {
+  try {
+    if (statSync(path).size > 50_000_000) return undefined;
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Is the preview MCP server from .mcp.json approved for this project? The approval can live in the project's
+ * entry of ~/.claude.json or in any settings file (user, project, local – the "approve" dialog writes
+ * .claude/settings.local.json). undefined = can't tell.
+ */
+function mcpApproved(server: string): boolean | undefined {
+  const global = readJson(join(homedir(), ".claude.json"));
+  const sources: McpApproval[] = [
+    (global?.projects as Record<string, McpApproval> | undefined)?.[root],
+    readJson(join(homedir(), ".claude/settings.json")),
+    readJson(join(root, ".claude", "settings.json")),
+    readJson(join(root, ".claude", "settings.local.json")),
+  ].filter((source): source is McpApproval => source !== undefined);
+  if (sources.length === 0) return undefined;
+  if (sources.some((source) => source.disabledMcpjsonServers?.includes(server))) return false;
+  return sources.some(
+    (source) =>
+      Boolean(source.mcpServers?.[server]) ||
+      source.enableAllProjectMcpServers === true ||
+      source.enabledMcpjsonServers?.includes(server),
+  );
+}
+
+/** Is an MCP server with this name configured anywhere the harness reads? */
+function mcpConfigured(server: string): boolean {
+  for (const file of [".mcp.json", ".claude/settings.json", ".claude/settings.local.json", ".opencode/opencode.jsonc", ".opencode/opencode.json"]) {
+    const path = join(root, file);
+    try {
+      if (existsSync(path) && readFileSync(path, "utf8").includes(server)) return true;
+    } catch {
+      // an unreadable config never blocks a session start
+    }
+  }
+  return false;
+}
+
+function setupHints(p: Profile): string[] {
+  const hints: string[] = [];
+
+  if (!existsSync(join(root, ".claude/node_modules/yaml")))
+    hints.push("- Tooling dependencies are missing – the validators and scripts won't run: `npm install --prefix .claude`");
+
+  const install = p.commands?.install;
+  if (install && existsSync(join(root, "package.json")) && !existsSync(join(root, "node_modules")))
+    hints.push(`- The application's dependencies are missing: \`${install}\``);
+
+  if (p.review?.pullRequest === "gh") {
+    if (!sh("command -v gh").ok) {
+      hints.push("- GitHub CLI (`gh`) not installed – /implement can't open the pull request itself, it falls back to the compare URL from `git push`: https://cli.github.com");
+    } else {
+      const auth = sh("gh auth status");
+      if (!auth.ok) hints.push("- `gh` is not authenticated – no pull requests from here: `gh auth login` (needs the `repo` scope)");
+      else if (!/Token scopes:.*'repo'/.test(auth.out)) hints.push("- The `gh` token has no `repo` scope – creating pull requests will fail: `gh auth refresh -s repo`");
+    }
+  }
+
+  const backlog = p.backlog?.provider ?? "local";
+  if (backlog === "github" && p.review?.pullRequest !== "gh") {
+    if (!sh("command -v gh").ok)
+      hints.push("- Backlog provider is `github`, but the GitHub CLI (`gh`) is missing – the mirror cannot sync: https://cli.github.com");
+    else if (!sh("gh auth status").ok)
+      hints.push("- Backlog provider is `github`, but `gh` is not authenticated – `gh auth login` (needs the `repo` scope).");
+  }
+  if (backlog === "jira") {
+    const project = p.backlog?.jira?.project ?? "";
+    const server = p.backlog?.jira?.mcpServer ?? "mcp-atlassian";
+    if (!project) hints.push("- Backlog provider is `jira`, but `backlog.jira.project` is empty in `.claude/project.json`.");
+    if (!mcpConfigured(server))
+      hints.push(
+        `- Backlog provider is \`jira\`, but no \`${server}\` MCP server is configured in this project. ` +
+          "Add it in your harness (see the `backlog` skill), otherwise no story can be read from or written to Jira.",
+      );
+  }
+
+  if (p.review?.preview === "vercel" && existsSync(join(root, ".mcp.json")) && mcpApproved("vercel") === false)
+    hints.push(
+      "- Vercel MCP (`vercel` in .mcp.json) is not enabled yet: approve the project server, then authenticate it. " +
+        "It gives preview deployment status and build/runtime logs for the acceptance step; without it, ask the user for the preview URL.",
+    );
+
+  if (p.setup?.envFile && !existsSync(join(root, p.setup.envFile)))
+    hints.push(`- No ${p.setup.envFile} – ${p.setup.envHint ?? "the app may not start"}`);
+
+  if (!existsSync(join(root, "CONTEXT.md")))
+    hints.push(
+      `- Discovery has not started: no CONTEXT.md. Run \`${p.kind === "brownfield" ? "/adopt" : "/bootstrap"}\` to build the domain model with the user.`,
+    );
+
+  if (p.kind === "brownfield" && !existsSync(join(root, "docs", "architecture", "repo-map.json")))
+    hints.push(
+      "- No repository map yet: `/adopt` maps the repository first, then adopts one slice at a time (one domain plus at most one shared library).",
+    );
+
+  return hints;
+}
+
+const p = profile();
+const name = p.name ?? "this project";
+const lines: string[] = [];
+
+try {
+  const hints = setupHints(p);
+  if (hints.length > 0) lines.push(`${name} – setup (tell the user, don't fix it silently):`, ...hints, "");
+} catch {
+  // a broken check never blocks a session start
+}
+
+try {
+  const { rel, storyId, loadStories } = await import("../lib/discovery.ts");
+  const { git, nextStory, readVerifyState } = await import("../lib/engineering.ts");
+
+  lines.push(`${name} – engineering status:`);
+  const branch = git("rev-parse", "--abbrev-ref", "HEAD");
+  const dirty = (git("status", "--porcelain") ?? "") !== "";
+  lines.push(`- Branch: ${branch ?? "?"}${dirty ? " (uncommitted changes)" : ""}`);
+
+  const provider = p.backlog?.provider ?? "local";
+  if (provider !== "local") {
+    const stories = loadStories().parsed;
+    const unlinked = stories.filter((story) => {
+      const ext = story.meta.external as { provider?: unknown; key?: unknown } | undefined;
+      return !ext || ext.provider !== provider || typeof ext.key !== "string" || !ext.key;
+    }).length;
+    const target = provider === "jira" ? `Jira (${p.backlog?.jira?.project || "project not configured"})` : "GitHub Issues";
+    lines.push(
+      `- Backlog: ${target} – ${stories.length - unlinked} of ${stories.length} stories linked` +
+        (unlinked ? `; ${unlinked} need /backlog-sync` : ""),
+    );
+  }
+
+  const { inProgress, next } = nextStory();
+  for (const s of inProgress) lines.push(`- In progress: ${storyId(s)} – ${s.meta.title} (${rel(s.path)})`);
+  if (next) lines.push(`- Next ready story: ${storyId(next)} – ${next.meta.title} (start with /implement)`);
+  if (!inProgress.length && !next && !existsSync(join(root, "docs", "stories")))
+    lines.push("- No backlog yet – discovery comes first (/bootstrap or /adopt).");
+
+  const v = readVerifyState();
+  if (v) {
+    const head = git("rev-parse", "--short", "HEAD");
+    const stale = v.commit !== head || v.dirty ? " – older than the current code" : "";
+    const failed = v.steps.filter((s) => !s.ok).map((s) => s.name);
+    lines.push(`- Last verify: ${v.ok ? "green" : `RED (${failed.join(", ")})`} at ${v.at} on ${v.branch}@${v.commit}${stale}`);
+  }
+} catch {
+  // never block a session start
+}
+
+if (lines.length > 0) console.log(lines.join("\n"));
+process.exit(0);

package/.claude/hooks/stop-gate.ts

@@ -0,0 +1,56 @@
+/**
+ * Stop hook: quick gate before Claude finishes a turn in which application code changed.
+ *
+ * Runs the type check and the tests related to the changed files (Vitest). If they fail, Claude is sent back
+ * once to fix them (exit 2); `stop_hook_active` prevents a loop – the second time it only reports.
+ * The full gate is `node .claude/skills/implement/scripts/verify.ts`.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ROOT } from "../lib/discovery.ts";
+import { appBin, git, isCode } from "../lib/engineering.ts";
+
+let data: Record<string, any>;
+try {
+  data = JSON.parse(readFileSync(0, "utf8"));
+} catch {
+  process.exit(0);
+}
+if (data.stop_hook_active) process.exit(0);
+
+const changed = (git("status", "--porcelain", "--untracked-files=all") ?? "")
+  .split("\n")
+  .map((l) => l.slice(3).trim().replace(/^.* -> /, ""))
+  .filter((f) => f && !f.startsWith(".claude/") && !f.startsWith("docs/") && isCode(f) && existsSync(join(ROOT, f)));
+if (!changed.length) process.exit(0);
+
+const failures: string[] = [];
+const tail = (s: string) => s.trim().split("\n").slice(-40).join("\n");
+
+const tsc = appBin("tsc");
+if (tsc && existsSync(join(ROOT, "tsconfig.json"))) {
+  const r = spawnSync(tsc, ["--noEmit", "-p", "."], { cwd: ROOT, encoding: "utf8", timeout: 240_000 });
+  if (r.status !== 0) failures.push(`Type check failed:\n${tail(r.stdout + r.stderr)}`);
+}
+const vitest = appBin("vitest");
+if (vitest) {
+  const r = spawnSync(vitest, ["related", "--run", "--passWithNoTests", ...changed], { cwd: ROOT, encoding: "utf8", timeout: 300_000 });
+  if (r.status !== 0) failures.push(`Tests related to the changed files failed:\n${tail(r.stdout + r.stderr)}`);
+}
+
+// Project-owned checks from docs/engineering/checks.yaml (boundaries, architecture tests, …).
+const project = spawnSync(process.execPath, [join(ROOT, ".claude", "hooks", "project-check.ts"), "--phase", "stop"], {
+  cwd: ROOT,
+  encoding: "utf8",
+  timeout: 120_000,
+});
+if (project.status !== 0) {
+  failures.push(`Project checks failed:\n${tail(`${project.stdout ?? ""}${project.stderr ?? ""}`)}`);
+}
+
+if (failures.length) {
+  process.stderr.write(`Quick gate is red – fix before finishing (or say explicitly why it is red on purpose, e.g. a failing test in the red step):\n\n${failures.join("\n\n")}\n`);
+  process.exit(2);
+}
+process.exit(0);

package/.claude/hooks/validate-docs.ts

@@ -0,0 +1,58 @@
+/**
+ * PostToolUse hook: validates discovery artifacts right after every write.
+ *
+ * - docs/domain/events.yaml → schema + references; on success event-storming.md and BACKLOG.md are re-rendered
+ * - docs/stories/*.md       → validation of the changed story (lenient on dependencies) and of its status change
+ *                             since the last commit (engineering workflow); on success BACKLOG.md is re-rendered
+ * Exit 2 + stderr = Claude gets the errors back and has to fix them.
+ */
+import { readFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import * as d from "../lib/discovery.ts";
+import * as e from "../lib/engineering.ts";
+
+let data: d.Obj;
+try {
+  data = JSON.parse(readFileSync(0, "utf8"));
+} catch {
+  process.exit(0);
+}
+
+const fp: unknown = data.tool_input?.file_path;
+if (typeof fp !== "string" || !fp) process.exit(0);
+const path = isAbsolute(fp) ? fp : join(data.cwd || d.ROOT, fp);
+const rel = d.rel(path);
+
+const report = new d.Report();
+if (rel === "docs/domain/events.yaml") {
+  const model = d.validateEvents(report);
+  if (report.ok && model !== null) {
+    d.writeEventStormingMd(model);
+    d.writeBacklogMd();
+  }
+} else if (d.storyFiles().some((f) => d.realPath(f) === d.realPath(path))) {
+  const stories = d.validateStories(report, path, true);
+  // Status workflow: compared with the last commit, the new status must be reachable and its preconditions met
+  const story = [...stories.values()].find((s) => d.realPath(s.path) === d.realPath(path));
+  const from = story ? e.headStatus(story) : null;
+  if (story && from !== null) {
+    for (const msg of e.transitionErrors(story, from, String(story.meta.status), stories)) report.error(rel, msg);
+  }
+  if (report.ok) d.writeBacklogMd();
+} else {
+  process.exit(0);
+}
+
+if (!report.ok) {
+  process.stderr.write(`Validation of ${rel} failed – please fix:\n${report.lines().join("\n")}\n`);
+  process.exit(2);
+}
+if (report.warnings.length) {
+  // Return warnings as context without blocking
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PostToolUse",
+      additionalContext: "Validation OK, notes:\n" + report.warnings.join("\n"),
+    },
+  }));
+}