claude-crap 0.1.2

package/plugin/hooks/post-tool-use.mjs

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+// @ts-check
+/**
+ * claude-crap :: PostToolUse hook — retrospective verifier.
+ *
+ * This hook runs immediately AFTER a Write / Edit / MultiEdit / NotebookEdit
+ * call has mutated a file on disk. Its job is to inspect the artifact the
+ * agent just produced and surface anything that the PreToolUse gatekeeper
+ * could not catch without the finished file:
+ *
+ *   - Missing test harness for a production source file
+ *     (Golden Rule enforcement from CLAUDE.md).
+ *   - Crude "silenced warning" signatures (`eslint-disable`, `// @ts-ignore`,
+ *     `# nosec`, `# type: ignore`). These often hide real issues.
+ *   - TODO / FIXME / XXX markers in newly committed code.
+ *
+ * PostToolUse is **non-blocking** by design: every finding is emitted on
+ * stderr as a warning and the tool call is allowed to proceed. The agent
+ * is expected to read the warnings and remediate on its next turn, and
+ * the Stop quality gate will block the task close if any violation
+ * persists all the way to the end.
+ *
+ * The hook is intentionally cheap: only the artifact's path and raw
+ * bytes are examined. Deep SAST / CRAP / TDR analysis is deferred to the
+ * Stop hook which calls the MCP server.
+ *
+ * @module hooks/post-tool-use
+ */
+
+import { promises as fs } from "node:fs";
+import { resolve } from "node:path";
+
+import { ExitCodes, readStdinJson, runHook, warnNonBlocking } from "./lib/hook-io.mjs";
+import { findTestFile, isTestFile } from "./lib/test-harness.mjs";
+
+const WORKSPACE_ROOT = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+
+/**
+ * Source extensions we care about for the test-harness rule. Files
+ * outside this list (README, YAML, JSON, etc.) are skipped silently.
+ */
+const PRODUCTION_SOURCE_EXTENSIONS = new Set([
+  ".ts",
+  ".tsx",
+  ".mts",
+  ".cts",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".py",
+  ".java",
+  ".cs",
+]);
+
+/**
+ * Inline suppression patterns. Each entry is a regex we look for in the
+ * just-written file. When matched, the hook emits a warning naming the
+ * suppression and asking the agent to remove it.
+ */
+const SUPPRESSION_PATTERNS = [
+  { id: "SUPP-ESLINT-DISABLE", re: /\beslint-disable(?:-next-line)?\b/, tool: "ESLint" },
+  { id: "SUPP-TS-IGNORE", re: /@ts-ignore/, tool: "TypeScript" },
+  { id: "SUPP-TS-EXPECT-ERROR", re: /@ts-expect-error/, tool: "TypeScript" },
+  { id: "SUPP-NOSEC", re: /#\s*nosec/, tool: "Bandit" },
+  { id: "SUPP-TYPE-IGNORE", re: /#\s*type:\s*ignore/, tool: "mypy / pyright" },
+];
+
+const TODO_MARKER_REGEX = /\b(TODO|FIXME|XXX|HACK)\b/;
+
+/**
+ * @typedef {Object} HookInput
+ * @property {string} [session_id]
+ * @property {string} [hook_event_name]
+ * @property {string} tool_name
+ * @property {Record<string, unknown>} tool_input
+ * @property {Record<string, unknown>} [tool_response]
+ */
+
+/**
+ * Validate the minimum structural shape of a PostToolUse payload. Throws
+ * with a descriptive error when the payload is unrecognizable — the
+ * caller's fail-open harness will degrade gracefully.
+ *
+ * @param {unknown} payload
+ * @returns {HookInput}
+ */
+function validate(payload) {
+  if (!payload || typeof payload !== "object") throw new Error("payload is not an object");
+  const p = /** @type {Record<string, unknown>} */ (payload);
+  if (typeof p.tool_name !== "string") throw new Error("payload.tool_name missing");
+  if (!p.tool_input || typeof p.tool_input !== "object") throw new Error("payload.tool_input missing");
+  return /** @type {HookInput} */ (p);
+}
+
+/**
+ * Extract the target file path from the tool input, if any. Returns
+ * `null` when the tool does not operate on a single file (e.g. Bash).
+ *
+ * @param {HookInput} input
+ * @returns {string | null}
+ */
+function extractTargetFile(input) {
+  const fp = input.tool_input.file_path;
+  if (typeof fp === "string") return fp;
+  const np = input.tool_input.notebook_path;
+  if (typeof np === "string") return np;
+  return null;
+}
+
+/**
+ * Is this extension one of the production source languages we guard?
+ *
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function isProductionSource(filePath) {
+  for (const ext of PRODUCTION_SOURCE_EXTENSIONS) {
+    if (filePath.endsWith(ext)) return true;
+  }
+  return false;
+}
+
+/**
+ * Rule: production source files must have an accompanying test file.
+ *
+ * Fires a `SONAR-TEST-MISSING` warning when none of the conventional
+ * test locations exists. Does not block — the Stop gate enforces the
+ * strict verdict.
+ *
+ * @param {string} filePath   Absolute path to the artifact just written.
+ * @param {string} toolName   Name of the tool that wrote it (for logging).
+ */
+async function checkTestHarness(filePath, toolName) {
+  if (isTestFile(filePath)) return;
+  if (!isProductionSource(filePath)) return;
+
+  const resolution = await findTestFile(WORKSPACE_ROOT, filePath);
+  if (resolution.testFile) return;
+
+  warnNonBlocking({
+    title: "PostToolUse",
+    ruleId: "SONAR-TEST-MISSING",
+    tool: toolName,
+    reason:
+      `No test file was found for '${filePath}'. ` +
+      `The Golden Rule in CLAUDE.md requires a test harness to accompany every production source file. ` +
+      `Corrective action: before the Stop quality gate runs, create a test next to the file or under the ` +
+      `mirror tree at 'tests/' with a name such as '${resolution.candidates[0]}'.`,
+  });
+}
+
+/**
+ * Rule: inline suppression markers are forbidden.
+ *
+ * Reads the just-written file and scans for common linter / type-checker
+ * suppression annotations. When found, emits a warning naming the tool
+ * whose output was being silenced.
+ *
+ * @param {string} filePath
+ * @param {string} toolName
+ */
+async function checkSuppressionMarkers(filePath, toolName) {
+  let content;
+  try {
+    content = await fs.readFile(filePath, "utf8");
+  } catch {
+    // File not readable (unusual: PostToolUse runs after a successful write).
+    return;
+  }
+
+  for (const suppression of SUPPRESSION_PATTERNS) {
+    if (!suppression.re.test(content)) continue;
+    warnNonBlocking({
+      title: "PostToolUse",
+      ruleId: `SONAR-${suppression.id}`,
+      tool: toolName,
+      reason:
+        `Found a suppression marker (${suppression.id}) that silences ${suppression.tool}. ` +
+        `CLAUDE.md forbids silencing findings — fix the underlying issue instead. ` +
+        `Corrective action: remove the suppression and address the warning it was hiding. If the warning ` +
+        `is truly a false positive, add an entry to the tool's configuration file with a clear rationale.`,
+    });
+  }
+}
+
+/**
+ * Rule: freshly committed TODO/FIXME markers are tracked.
+ *
+ * Not every TODO is a defect, but TODOs that slip into committed code
+ * are a leading indicator of technical debt. We emit a single aggregated
+ * warning per file rather than one per line.
+ *
+ * @param {string} filePath
+ * @param {string} toolName
+ */
+async function checkTodoMarkers(filePath, toolName) {
+  let content;
+  try {
+    content = await fs.readFile(filePath, "utf8");
+  } catch {
+    return;
+  }
+  const lines = content.split(/\r?\n/);
+  /** @type {number[]} */
+  const hits = [];
+  lines.forEach((line, idx) => {
+    if (TODO_MARKER_REGEX.test(line)) hits.push(idx + 1);
+  });
+  if (hits.length === 0) return;
+
+  warnNonBlocking({
+    title: "PostToolUse",
+    ruleId: "SONAR-TODO-MARKER",
+    tool: toolName,
+    reason:
+      `Found ${hits.length} TODO/FIXME/HACK marker(s) in '${filePath}' at line(s) ${hits.slice(0, 5).join(", ")}` +
+      `${hits.length > 5 ? ", ..." : ""}. ` +
+      `These are tracked by the TDR engine as debt. Either resolve them now or open a linked ticket and ` +
+      `reference it in the comment so the Stop gate can audit the backlog.`,
+  });
+}
+
+async function main() {
+  const payload = await readStdinJson();
+  const input = validate(payload);
+  const filePath = extractTargetFile(input);
+  if (!filePath) {
+    // Tool did not write a file (e.g. Bash). Nothing to verify.
+    process.exit(ExitCodes.ALLOW);
+  }
+
+  const absolute = resolve(WORKSPACE_ROOT, filePath);
+  await checkTestHarness(absolute, input.tool_name);
+  await checkSuppressionMarkers(absolute, input.tool_name);
+  await checkTodoMarkers(absolute, input.tool_name);
+
+  // PostToolUse never blocks — always allow. Warnings already wrote to stderr.
+  process.stdout.write(
+    JSON.stringify({ status: "verified", tool: input.tool_name, file: filePath }) + "\n",
+  );
+  process.exit(ExitCodes.ALLOW);
+}
+
+runHook("PostToolUse", main);

package/plugin/hooks/pre-tool-use.mjs

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+// @ts-check
+/**
+ * claude-crap :: PreToolUse hook — prophylactic gatekeeper.
+ *
+ * Contract with Claude Code (see https://code.claude.com/docs/en/hooks):
+ *
+ *   stdin  : JSON payload `{ session_id, tool_name, tool_input, ... }`
+ *   stdout : Free-form informational output. Never interpreted by Claude.
+ *   stderr : Corrective message injected into the agent's context when
+ *            the hook exits with code 2.
+ *   exit 0 : Allow the tool call.
+ *   exit 2 : ABORT the tool call. Claude Code forwards stderr to the LLM.
+ *   exit N : Non-zero, non-2 exit. Treated by Claude Code as "allow"
+ *            (fail-open). claude-crap uses this code only for LOW-RISK
+ *            tools when the hook itself errors; HIGH-RISK tools always
+ *            fall back to exit 2 (fail-closed) — see the allowlist below.
+ *
+ * Deterministic design principles:
+ *
+ *   - Zero network I/O.
+ *   - Zero filesystem I/O beyond reading stdin and writing stderr.
+ *   - Target latency: under 200 ms in the common case.
+ *   - All rules live in `./lib/gatekeeper-rules.mjs` so they can be tested
+ *     in isolation without spinning up Claude Code.
+ *
+ * Fail-open vs fail-closed (F-A06-01):
+ *
+ *   The CLAUDE.md contract states that "none of your proposals bypass
+ *   those filters." A fully fail-open gatekeeper would break that
+ *   contract the instant any rule throws an exception or any payload
+ *   fails to parse. But a fully fail-closed gatekeeper would deadlock
+ *   the user whenever Claude Code sends an unusual payload, which is
+ *   also unacceptable.
+ *
+ *   The compromise is an allowlist of HIGH-risk tool names: Write,
+ *   Edit, MultiEdit, NotebookEdit, Bash. For those tools, ANY failure
+ *   to evaluate the rules (parse error, rule throw, validator throw)
+ *   exits 2 with a structured corrective message. For every other
+ *   tool, the legacy fail-open behavior is preserved.
+ *
+ *   When the stdin payload is unparseable we still try to recover the
+ *   tool name via a best-effort regex so the fail-closed check can
+ *   trigger even in the degraded path.
+ *
+ * What this hook does NOT do:
+ *
+ *   Deep SAST, CRAP computation, tree-sitter AST parsing, coverage lookup
+ *   and SARIF aggregation all live in PostToolUse (retrospective) or Stop
+ *   (final quality gate). Those stages call the MCP server. The PreToolUse
+ *   hook is intentionally a cheap synchronous speed bump.
+ *
+ * @module hooks/pre-tool-use
+ */
+
+import { runAllRules } from "./lib/gatekeeper-rules.mjs";
+
+/** Allow the tool call to proceed. */
+const EXIT_ALLOW = 0;
+/** Block the tool call and inject `stderr` into the agent's context. */
+const EXIT_BLOCK = 2;
+/** Internal hook failure (fail-open for LOW-risk tools only). */
+const EXIT_INTERNAL_ERROR = 1;
+
+/**
+ * Tool names for which the gatekeeper MUST fail closed when it cannot
+ * evaluate the payload. These are exactly the tools that can mutate the
+ * workspace or execute a shell, so bypassing the gatekeeper for them
+ * would violate the CLAUDE.md Golden Rule.
+ */
+const HIGH_RISK_TOOLS = Object.freeze(
+  new Set(["Write", "Edit", "MultiEdit", "NotebookEdit", "Bash"]),
+);
+
+/**
+ * Best-effort regex used to recover `tool_name` from stdin that does not
+ * parse as JSON. The regex is intentionally lenient: it just looks for
+ * the first `"tool_name": "<something>"` substring anywhere in the raw
+ * input. When nothing matches we return `null` and the caller treats
+ * the tool as unknown (which means fail-open).
+ */
+const TOOL_NAME_EXTRACT_RE = /"tool_name"\s*:\s*"([^"]+)"/;
+
+/**
+ * Read the full stdin stream as a raw UTF-8 string. Kept separate from
+ * JSON parsing so the caller can attempt a best-effort `tool_name`
+ * extraction on malformed input.
+ *
+ * @returns {Promise<string>} The stdin contents, trimmed of surrounding whitespace.
+ */
+async function readStdinRaw() {
+  /** @type {Buffer[]} */
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(/** @type {Buffer} */ (chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8").trim();
+}
+
+/**
+ * Parse a raw stdin string as JSON, rethrowing with a friendly message.
+ *
+ * @param {string} raw Raw stdin contents.
+ * @returns {object}   The parsed JSON payload.
+ * @throws  When the string is empty or not valid JSON.
+ */
+function parseStdinJson(raw) {
+  if (!raw) {
+    throw new Error("stdin was empty — claude-crap PreToolUse expected a hook JSON payload");
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`stdin is not valid JSON: ${/** @type {Error} */ (err).message}`);
+  }
+}
+
+/**
+ * Validate that the payload has the minimum shape of a Claude Code hook
+ * and narrow its type for downstream consumers. Throws when the payload
+ * is unrecognizable — the caller handles the fail-closed / fail-open
+ * decision.
+ *
+ * @param {unknown} payload Raw parsed JSON from stdin.
+ * @returns {import("./lib/gatekeeper-rules.mjs").HookInput}
+ * @throws  When required fields are missing or the wrong type.
+ */
+function validateHookPayload(payload) {
+  if (!payload || typeof payload !== "object") {
+    throw new Error("payload is not an object");
+  }
+  const p = /** @type {Record<string, unknown>} */ (payload);
+  if (typeof p.tool_name !== "string") {
+    throw new Error("payload.tool_name is missing or not a string");
+  }
+  if (!p.tool_input || typeof p.tool_input !== "object") {
+    throw new Error("payload.tool_input is missing or not an object");
+  }
+  return /** @type {import("./lib/gatekeeper-rules.mjs").HookInput} */ (p);
+}
+
+/**
+ * Best-effort extractor for `tool_name` from unparseable stdin. Used as
+ * a last resort when the gatekeeper needs to decide between fail-open
+ * and fail-closed but the payload never made it through `JSON.parse`.
+ *
+ * @param {string} raw Raw stdin contents.
+ * @returns {string | null} The extracted tool name, or `null`.
+ */
+function extractToolNameFromRaw(raw) {
+  if (!raw) return null;
+  const match = TOOL_NAME_EXTRACT_RE.exec(raw);
+  return match && typeof match[1] === "string" ? match[1] : null;
+}
+
+/**
+ * `true` when the given tool name is in the high-risk allowlist and
+ * therefore must fail closed on any internal hook error.
+ *
+ * @param {string | null | undefined} toolName
+ * @returns {boolean}
+ */
+function isHighRiskTool(toolName) {
+  return typeof toolName === "string" && HIGH_RISK_TOOLS.has(toolName);
+}
+
+/**
+ * Render the fail-closed corrective message. Claude Code injects this
+ * text into the agent's context when the hook exits with code 2, so it
+ * must be imperative and actionable.
+ *
+ * @param {Object} opts
+ * @param {string} opts.toolName   Recovered tool name (e.g. `"Write"`).
+ * @param {string} opts.phase      Which phase failed — `"parse"` or `"evaluate"`.
+ * @param {string} opts.detail     Short technical description of the failure.
+ * @returns {string}               Multi-line box ready to write to stderr.
+ */
+function renderFailClosedMessage({ toolName, phase, detail }) {
+  return [
+    "╭─ claude-crap :: PreToolUse BLOCKED (fail-closed) ───────────────",
+    "│ rule : SONAR-GATEKEEPER-FAILCLOSED",
+    `│ tool : ${toolName}`,
+    `│ phase: ${phase}`,
+    "│",
+    "│ The gatekeeper could not evaluate this call and the tool is in",
+    "│ the high-risk allowlist (Write, Edit, MultiEdit, NotebookEdit,",
+    "│ Bash). Per CLAUDE.md, enforcement must not be bypassed by a hook",
+    "│ failure for tools that mutate files or run a shell.",
+    "│",
+    "│ Corrective action: fix the gatekeeper bug surfaced by the detail",
+    "│ line below, then retry. If you cannot fix it, ask the user to",
+    "│ invoke a non-mutating tool (Read, Glob, Grep) to inspect the",
+    "│ situation instead.",
+    "│",
+    `│ detail: ${detail}`,
+    "╰──────────────────────────────────────────────────────────────────",
+  ].join("\n");
+}
+
+/**
+ * Handle a hook internal error uniformly. Decides between fail-closed
+ * (exit 2, for high-risk tools) and fail-open (exit 1, for everything
+ * else), writes the appropriate message to stderr, and exits. Never
+ * returns.
+ *
+ * @param {Object} opts
+ * @param {string | null} opts.toolName   Best-effort recovered tool name.
+ * @param {string}        opts.phase      `"parse"` or `"evaluate"`.
+ * @param {string}        opts.detail     Short technical reason.
+ * @returns {never}
+ */
+function exitOnInternalError({ toolName, phase, detail }) {
+  if (isHighRiskTool(toolName)) {
+    process.stderr.write(
+      renderFailClosedMessage({
+        toolName: /** @type {string} */ (toolName),
+        phase,
+        detail,
+      }) + "\n",
+    );
+    process.exit(EXIT_BLOCK);
+  }
+  process.stderr.write(
+    `[claude-crap] PreToolUse: ${phase} failure (${detail}). ` +
+      `Tool '${toolName ?? "<unknown>"}' is not in the high-risk allowlist; ` +
+      `falling back to permissive mode (fail-open).\n`,
+  );
+  process.exit(EXIT_INTERNAL_ERROR);
+}
+
+/**
+ * Entrypoint. Reads the hook payload, runs every rule, and exits with
+ * the appropriate code. Any unexpected failure is routed through
+ * `exitOnInternalError`, which fails closed for high-risk tools.
+ */
+async function main() {
+  /** @type {string} */
+  let raw = "";
+  /** @type {import("./lib/gatekeeper-rules.mjs").HookInput | null} */
+  let input = null;
+
+  try {
+    raw = await readStdinRaw();
+    const parsed = parseStdinJson(raw);
+    input = validateHookPayload(parsed);
+  } catch (err) {
+    const recoveredTool = extractToolNameFromRaw(raw);
+    exitOnInternalError({
+      toolName: recoveredTool,
+      phase: "parse",
+      detail: /** @type {Error} */ (err).message,
+    });
+    return; // unreachable, but keeps the type checker happy
+  }
+
+  try {
+    const verdict = runAllRules(input);
+    if (verdict && verdict.blocked) {
+      // Structured message for the LLM. Claude Code injects stderr into
+      // the agent's context whenever a hook exits with code 2, so this
+      // text effectively becomes a prompt. Keep it imperative and actionable.
+      const message = [
+        "╭─ claude-crap :: PreToolUse BLOCKED ────────────────────────────",
+        `│ rule : ${verdict.ruleId}`,
+        `│ tool : ${input.tool_name}`,
+        "│",
+        `│ ${verdict.reason}`,
+        "╰──────────────────────────────────────────────────────────────────",
+      ].join("\n");
+      process.stderr.write(`${message}\n`);
+      process.exit(EXIT_BLOCK);
+      return;
+    }
+
+    // Silent pass-through. We still emit a single JSON line on stdout so
+    // that the hooks transcript can be audited after the fact.
+    process.stdout.write(
+      JSON.stringify({ status: "allow", tool: input.tool_name, rules_evaluated: 4 }) + "\n",
+    );
+    process.exit(EXIT_ALLOW);
+  } catch (err) {
+    exitOnInternalError({
+      toolName: input.tool_name,
+      phase: "evaluate",
+      detail: /** @type {Error} */ (err).message,
+    });
+  }
+}
+
+main();

package/plugin/hooks/session-start.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// @ts-check
+/**
+ * claude-crap :: SessionStart hook — baseline context seeder.
+ *
+ * Runs once when Claude Code starts a new interactive session with this
+ * plugin active. Its purpose is to fix the agent's opening mental model
+ * without paying for it in tokens later: the hook writes a short,
+ * structured briefing on stdout so Claude Code can inject it into the
+ * session's system context.
+ *
+ * The briefing contains:
+ *
+ *   - A reminder of the Golden Rule and the hook contract.
+ *   - The current configured thresholds (CRAP, TDR rating, LOC cost).
+ *   - Baseline metrics pulled from the last consolidated SARIF report.
+ *
+ * Exit semantics:
+ *
+ *   - Exit 0 → briefing written to stdout, Claude Code appends it to
+ *              the session context.
+ *   - Any other exit → fail-open; the session starts with no briefing.
+ *
+ * The hook never blocks, never reads the filesystem beyond the SARIF
+ * report, and never calls the MCP server — it must complete in under
+ * 10 seconds per the `hooks.json` timeout budget.
+ *
+ * @module hooks/session-start
+ */
+
+import { ExitCodes, runHook } from "./lib/hook-io.mjs";
+import { evaluateQualityGate, loadQualityGateConfig } from "./lib/quality-gate.mjs";
+
+/**
+ * Render the opening briefing as Markdown. The text lands in the
+ * agent's system context, so it must be compact and imperative.
+ *
+ * @param {import("./lib/quality-gate.mjs").QualityGateConfig} config
+ * @param {import("./lib/quality-gate.mjs").GateVerdict}       verdict
+ * @returns {string}
+ */
+function renderBriefing(config, verdict) {
+  const { summary } = verdict;
+  return [
+    "## claude-crap session briefing",
+    "",
+    "This session is running under the claude-crap plugin. You are bound by:",
+    "",
+    "- **Golden Rule** — do not write functional code until a characterization test",
+    "  pins the current behavior.",
+    "- **Hook contract** — PreToolUse can abort with exit 2, PostToolUse emits",
+    "  warnings, Stop / SubagentStop enforce the quality gate.",
+    "- **Deterministic engines** — anchor decisions in the claude-crap MCP tools",
+    "  (`compute_crap`, `compute_tdr`, `analyze_file_ast`, `ingest_sarif`,",
+    "  `require_test_harness`) rather than in speculative reasoning.",
+    "",
+    "### Current policy",
+    "",
+    `- CRAP threshold: **${config.crapThreshold}** (block on any function above it)`,
+    `- Maintainability ceiling: **${config.tdrMaxRating}** (worse ratings halt the Stop gate)`,
+    `- Cost per LOC: **${config.minutesPerLoc}** minutes (used as the TDR denominator)`,
+    "",
+    "### Baseline workspace metrics",
+    "",
+    `- Workspace LOC: **${summary.physicalLoc}**`,
+    `- Total findings: **${summary.totalFindings}** ` +
+      `(error: ${summary.errorFindings}, warning: ${summary.warningFindings}, note: ${summary.noteFindings})`,
+    `- Remediation debt: **${summary.remediationMinutes} min**`,
+    `- TDR: **${summary.tdrPercent}%** → rating **${summary.tdrRating}**`,
+    summary.toolsSeen.length > 0
+      ? `- Scanners already ingested: ${summary.toolsSeen.join(", ")}`
+      : "- Scanners already ingested: <none>",
+    "",
+    verdict.passed
+      ? "The baseline currently passes the quality gate. Keep it that way."
+      : `⚠️ Baseline would FAIL the Stop gate (${verdict.failures.length} policy violation(s)). ` +
+        "Your first priority should be remediating existing findings before introducing new code.",
+  ].join("\n");
+}
+
+async function main() {
+  const config = loadQualityGateConfig();
+  let verdict;
+  try {
+    verdict = await evaluateQualityGate(config);
+  } catch (err) {
+    // If we cannot produce a verdict (e.g. MCP server not built yet),
+    // fail open: write a stripped briefing so the session still starts.
+    process.stderr.write(
+      `[claude-crap] SessionStart: could not evaluate baseline: ${/** @type {Error} */ (err).message}\n`,
+    );
+    process.stdout.write(
+      [
+        "## claude-crap session briefing",
+        "",
+        "claude-crap is active but the baseline quality gate could not run.",
+        "Run `cd src/mcp-server && npm run build` to enable deterministic metrics.",
+        "The Golden Rule still applies: no functional code without a prior test.",
+      ].join("\n") + "\n",
+    );
+    process.exit(ExitCodes.ALLOW);
+    return;
+  }
+
+  process.stdout.write(renderBriefing(config, verdict) + "\n");
+  process.exit(ExitCodes.ALLOW);
+}
+
+runHook("SessionStart", main);