claude-crap 0.1.2

package/plugin/bundle/tdr-engine.mjs

@@ -0,0 +1,50 @@
+// Generated by scripts/bundle-plugin.mjs — DO NOT EDIT
+
+// src/metrics/tdr.ts
+var RATING_ORDER = ["A", "B", "C", "D", "E"];
+function ratingToRank(rating) {
+  return RATING_ORDER.indexOf(rating);
+}
+function ratingIsWorseThan(actual, limit) {
+  return ratingToRank(actual) > ratingToRank(limit);
+}
+function classifyTdr(percent) {
+  if (!Number.isFinite(percent) || percent < 0) {
+    throw new Error(`[tdr] percent is invalid: ${percent}`);
+  }
+  if (percent <= 5) return "A";
+  if (percent <= 10) return "B";
+  if (percent <= 20) return "C";
+  if (percent <= 50) return "D";
+  return "E";
+}
+function computeTdr(input) {
+  if (input.totalLinesOfCode <= 0) {
+    throw new Error(`[tdr] totalLinesOfCode must be > 0, got ${input.totalLinesOfCode}`);
+  }
+  if (input.minutesPerLoc <= 0) {
+    throw new Error(`[tdr] minutesPerLoc must be > 0, got ${input.minutesPerLoc}`);
+  }
+  if (input.remediationMinutes < 0) {
+    throw new Error(`[tdr] remediationMinutes must be \u2265 0, got ${input.remediationMinutes}`);
+  }
+  const developmentCostMinutes = input.minutesPerLoc * input.totalLinesOfCode;
+  const ratio = input.remediationMinutes / developmentCostMinutes;
+  const percent = ratio * 100;
+  const rating = classifyTdr(percent);
+  return {
+    ratio: Number(ratio.toFixed(6)),
+    percent: Number(percent.toFixed(4)),
+    rating,
+    remediationMinutes: input.remediationMinutes,
+    totalLinesOfCode: input.totalLinesOfCode,
+    developmentCostMinutes
+  };
+}
+export {
+  classifyTdr,
+  computeTdr,
+  ratingIsWorseThan,
+  ratingToRank
+};
+//# sourceMappingURL=tdr-engine.mjs.map

package/plugin/bundle/tdr-engine.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/metrics/tdr.ts"],
+  "sourcesContent": ["/**\n * Technical Debt Ratio (TDR) \u2014 deterministic computation and rating.\n *\n * The Technical Debt Ratio expresses how expensive it would be to remediate\n * all known issues in a scope, relative to how much it would have cost to\n * write the code in the first place. Formally (see docs/quality-gate.md):\n *\n *     TDR = remediationCost / (costPerLine \u00D7 totalLinesOfCode)\n *\n * Where the remediation cost is the sum (in minutes) of every linter /\n * scanner / mutator finding's individual estimated effort, and the per-line\n * cost is assumed to be a constant `minutesPerLoc` (industry default: 30\n * minutes per line of code, including design, writing and review).\n *\n * The resulting ratio is converted to a percentage and mapped to a letter\n * grade A..E. The thresholds are strict and non-negotiable:\n *\n *   | Rating | TDR %        | Meaning                                   |\n *   |--------|--------------|-------------------------------------------|\n *   | A      | 0..5%        | Excellent \u2014 remediation cost is noise     |\n *   | B      | >5..10%      | Low risk                                  |\n *   | C      | >10..20%     | Moderate, watch closely                   |\n *   | D      | >20..50%     | Critical, remediation plan required       |\n *   | E      | >50%         | Unmaintainable \u2014 halt feature work        |\n *\n * Rating E always halts the workflow at the Stop quality gate, regardless\n * of the configured `TDR_MAX_RATING` tolerance.\n *\n * @module metrics/tdr\n */\n\nimport type { MaintainabilityRating } from \"../config.js\";\n\n/**\n * Inputs required to compute a Technical Debt Ratio over any scope\n * (project, module, or file).\n */\nexport interface TdrInput {\n  /** Sum of all finding remediation estimates, in minutes. Must be \u2265 0. */\n  readonly remediationMinutes: number;\n  /** Total lines of code in the scope. Must be > 0 (division denominator). */\n  readonly totalLinesOfCode: number;\n  /** Assumed development cost per LOC, in minutes. Must be > 0. */\n  readonly minutesPerLoc: number;\n}\n\n/**\n * Result of a TDR computation with both the raw ratio and the letter grade.\n */\nexport interface TdrResult {\n  /** Raw ratio (remediation / development), rounded to 6 decimals. */\n  readonly ratio: number;\n  /** Same ratio expressed as a percentage, rounded to 4 decimals. */\n  readonly percent: number;\n  /** Letter grade derived from `percent` via {@link classifyTdr}. */\n  readonly rating: MaintainabilityRating;\n  /** Remediation input, echoed for traceability. */\n  readonly remediationMinutes: number;\n  /** LOC input, echoed for traceability. */\n  readonly totalLinesOfCode: number;\n  /** Computed `minutesPerLoc \u00D7 totalLinesOfCode`, useful for the dashboard. */\n  readonly developmentCostMinutes: number;\n}\n\n/** Canonical ordering used by {@link ratingToRank}. */\nconst RATING_ORDER: ReadonlyArray<MaintainabilityRating> = [\"A\", \"B\", \"C\", \"D\", \"E\"];\n\n/**\n * Convert a letter rating to its numeric rank (A=0, E=4). Useful when\n * comparing two ratings without relying on lexical order.\n *\n * @param rating The rating letter.\n * @returns      Its rank in `[0, 4]`.\n */\nexport function ratingToRank(rating: MaintainabilityRating): number {\n  return RATING_ORDER.indexOf(rating);\n}\n\n/**\n * Return `true` when `actual` is strictly worse than `limit`, false otherwise.\n * Used by the Stop quality gate to decide whether to block task completion.\n *\n * @param actual Rating currently achieved by the project.\n * @param limit  Maximum tolerated rating (worst allowed).\n * @returns      `true` if `actual` should trigger a block.\n *\n * @example\n * ratingIsWorseThan(\"D\", \"C\") // \u2192 true\n * ratingIsWorseThan(\"B\", \"C\") // \u2192 false\n * ratingIsWorseThan(\"C\", \"C\") // \u2192 false (equal, not worse)\n */\nexport function ratingIsWorseThan(\n  actual: MaintainabilityRating,\n  limit: MaintainabilityRating,\n): boolean {\n  return ratingToRank(actual) > ratingToRank(limit);\n}\n\n/**\n * Map a TDR percentage to its letter rating. The boundaries are inclusive\n * on the upper end (5% is still an A, 10% is still a B, etc.).\n *\n * @param percent TDR expressed as a percentage. Must be \u2265 0.\n * @returns       Letter rating A..E.\n * @throws        When `percent` is negative or not finite.\n */\nexport function classifyTdr(percent: number): MaintainabilityRating {\n  if (!Number.isFinite(percent) || percent < 0) {\n    throw new Error(`[tdr] percent is invalid: ${percent}`);\n  }\n  if (percent <= 5) return \"A\";\n  if (percent <= 10) return \"B\";\n  if (percent <= 20) return \"C\";\n  if (percent <= 50) return \"D\";\n  return \"E\";\n}\n\n/**\n * Compute the Technical Debt Ratio for a scope and return the full result.\n * This function is pure and deterministic.\n *\n * @param input Remediation minutes, total LOC and the cost-per-line assumption.\n * @returns     A {@link TdrResult} ready to be serialized to SARIF properties.\n * @throws      When any numeric input is out of range.\n *\n * @example\n * // 240 minutes of remediation across 500 LOC at 30 min/LOC\n * computeTdr({ remediationMinutes: 240, totalLinesOfCode: 500, minutesPerLoc: 30 })\n * // \u2192 { ratio: 0.016, percent: 1.6, rating: \"A\", ... }\n */\nexport function computeTdr(input: TdrInput): TdrResult {\n  if (input.totalLinesOfCode <= 0) {\n    throw new Error(`[tdr] totalLinesOfCode must be > 0, got ${input.totalLinesOfCode}`);\n  }\n  if (input.minutesPerLoc <= 0) {\n    throw new Error(`[tdr] minutesPerLoc must be > 0, got ${input.minutesPerLoc}`);\n  }\n  if (input.remediationMinutes < 0) {\n    throw new Error(`[tdr] remediationMinutes must be \u2265 0, got ${input.remediationMinutes}`);\n  }\n\n  const developmentCostMinutes = input.minutesPerLoc * input.totalLinesOfCode;\n  const ratio = input.remediationMinutes / developmentCostMinutes;\n  const percent = ratio * 100;\n  const rating = classifyTdr(percent);\n\n  return {\n    ratio: Number(ratio.toFixed(6)),\n    percent: Number(percent.toFixed(4)),\n    rating,\n    remediationMinutes: input.remediationMinutes,\n    totalLinesOfCode: input.totalLinesOfCode,\n    developmentCostMinutes,\n  };\n}\n"],
+  "mappings": ";;;AAiEA,IAAM,eAAqD,CAAC,KAAK,KAAK,KAAK,KAAK,GAAG;AAS5E,SAAS,aAAa,QAAuC;AAClE,SAAO,aAAa,QAAQ,MAAM;AACpC;AAeO,SAAS,kBACd,QACA,OACS;AACT,SAAO,aAAa,MAAM,IAAI,aAAa,KAAK;AAClD;AAUO,SAAS,YAAY,SAAwC;AAClE,MAAI,CAAC,OAAO,SAAS,OAAO,KAAK,UAAU,GAAG;AAC5C,UAAM,IAAI,MAAM,6BAA6B,OAAO,EAAE;AAAA,EACxD;AACA,MAAI,WAAW,EAAG,QAAO;AACzB,MAAI,WAAW,GAAI,QAAO;AAC1B,MAAI,WAAW,GAAI,QAAO;AAC1B,MAAI,WAAW,GAAI,QAAO;AAC1B,SAAO;AACT;AAeO,SAAS,WAAW,OAA4B;AACrD,MAAI,MAAM,oBAAoB,GAAG;AAC/B,UAAM,IAAI,MAAM,2CAA2C,MAAM,gBAAgB,EAAE;AAAA,EACrF;AACA,MAAI,MAAM,iBAAiB,GAAG;AAC5B,UAAM,IAAI,MAAM,wCAAwC,MAAM,aAAa,EAAE;AAAA,EAC/E;AACA,MAAI,MAAM,qBAAqB,GAAG;AAChC,UAAM,IAAI,MAAM,kDAA6C,MAAM,kBAAkB,EAAE;AAAA,EACzF;AAEA,QAAM,yBAAyB,MAAM,gBAAgB,MAAM;AAC3D,QAAM,QAAQ,MAAM,qBAAqB;AACzC,QAAM,UAAU,QAAQ;AACxB,QAAM,SAAS,YAAY,OAAO;AAElC,SAAO;AAAA,IACL,OAAO,OAAO,MAAM,QAAQ,CAAC,CAAC;AAAA,IAC9B,SAAS,OAAO,QAAQ,QAAQ,CAAC,CAAC;AAAA,IAClC;AAAA,IACA,oBAAoB,MAAM;AAAA,IAC1B,kBAAkB,MAAM;AAAA,IACxB;AAAA,EACF;AACF;",
+  "names": []
+}

package/plugin/hooks/hooks.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://code.claude.com/schemas/hooks.json",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/pre-tool-use.mjs",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/post-tool-use.mjs",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/stop-quality-gate.mjs",
+            "timeout": 120
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/stop-quality-gate.mjs",
+            "timeout": 120
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/session-start.mjs",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugin/hooks/lib/crap-config.mjs

@@ -0,0 +1,152 @@
+// @ts-check
+/**
+ * Workspace-level sonar configuration loader (JS twin).
+ *
+ * This is the hook-side copy of `src/crap-config.ts`. Hooks live
+ * outside the TypeScript `rootDir` and cannot import the compiled
+ * `dist/` engine at the top of the module graph (the hook needs to
+ * work even when `dist/` is stale or missing), so we keep a
+ * zero-dependency JS twin that implements the same algorithm.
+ *
+ * See `src/crap-config.ts` for the full rationale. The two copies
+ * are validated against the same behavior table in
+ * `src/tests/crap-config.test.ts` and in
+ * `src/tests/stop-quality-gate-strictness.test.ts`.
+ *
+ * Resolution order (most specific wins):
+ *
+ *   1. `CLAUDE_CRAP_STRICTNESS` environment variable
+ *   2. `.claude-crap.json` at the workspace root
+ *   3. Hardcoded default `"strict"`
+ *
+ * @module hooks/lib/crap-config
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * @typedef {"strict" | "warn" | "advisory"} Strictness
+ */
+
+/**
+ * Exhaustive list of valid strictness values. Keep in sync with the
+ * TypeScript twin at `src/crap-config.ts`.
+ */
+export const STRICTNESS_VALUES = Object.freeze(["strict", "warn", "advisory"]);
+
+/**
+ * Default strictness when neither the env var nor the file provides
+ * a value. `"strict"` preserves the hard-failing Stop gate as the
+ * out-of-the-box experience.
+ *
+ * @type {Strictness}
+ */
+export const DEFAULT_STRICTNESS = "strict";
+
+/**
+ * Error thrown by {@link loadCrapConfig} when the configuration is
+ * rejected. Hook callers catch this and fall back to the default so
+ * a busted config file never deadlocks the user.
+ */
+export class CrapConfigError extends Error {
+  /** @param {string} message */
+  constructor(message) {
+    super(message);
+    this.name = "CrapConfigError";
+  }
+}
+
+/**
+ * Resolve the effective sonar configuration for a given workspace.
+ * Pure function except for the one synchronous file read on
+ * `<workspaceRoot>/.claude-crap.json` and the single env lookup.
+ *
+ * @param {{ workspaceRoot: string }} options
+ * @returns {{ strictness: Strictness, strictnessSource: "env" | "file" | "default" }}
+ * @throws  {CrapConfigError} on any invalid input.
+ */
+export function loadCrapConfig(options) {
+  const envRaw = process.env["CLAUDE_CRAP_STRICTNESS"];
+  if (typeof envRaw === "string" && envRaw.trim() !== "") {
+    const normalized = envRaw.trim().toLowerCase();
+    if (!isStrictness(normalized)) {
+      throw new CrapConfigError(
+        `[crap-config] CLAUDE_CRAP_STRICTNESS="${envRaw}" is not a valid strictness. ` +
+          `Expected one of: ${STRICTNESS_VALUES.join(", ")}.`,
+      );
+    }
+    return { strictness: normalized, strictnessSource: "env" };
+  }
+
+  const fromFile = readFromFile(options.workspaceRoot);
+  if (fromFile) return { strictness: fromFile, strictnessSource: "file" };
+
+  return { strictness: DEFAULT_STRICTNESS, strictnessSource: "default" };
+}
+
+/**
+ * Attempt to read and validate `.claude-crap.json` at the workspace
+ * root. Returns `null` when the file is missing (the common case for
+ * fresh installs). Throws {@link CrapConfigError} on malformed JSON,
+ * a non-object root, a wrong-type `strictness` field, or an unknown
+ * enum value — so the caller cannot silently drop into the default
+ * on a typo.
+ *
+ * @param {string} workspaceRoot
+ * @returns {Strictness | null}
+ */
+function readFromFile(workspaceRoot) {
+  const filePath = join(workspaceRoot, ".claude-crap.json");
+  let raw;
+  try {
+    raw = readFileSync(filePath, "utf8");
+  } catch (err) {
+    const error = /** @type {NodeJS.ErrnoException} */ (err);
+    if (error.code === "ENOENT") return null;
+    throw new CrapConfigError(
+      `[crap-config] Failed to read ${filePath}: ${error.message}`,
+    );
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new CrapConfigError(
+      `[crap-config] ${filePath} is not valid JSON: ${/** @type {Error} */ (err).message}`,
+    );
+  }
+
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new CrapConfigError(
+      `[crap-config] ${filePath} must be a JSON object at the top level`,
+    );
+  }
+  if (!("strictness" in parsed)) return null;
+
+  const value = parsed.strictness;
+  if (typeof value !== "string") {
+    throw new CrapConfigError(
+      `[crap-config] ${filePath}: 'strictness' must be a string, got ${typeof value}`,
+    );
+  }
+  const normalized = value.trim().toLowerCase();
+  if (!isStrictness(normalized)) {
+    throw new CrapConfigError(
+      `[crap-config] ${filePath}: 'strictness' is "${value}"; ` +
+        `expected one of ${STRICTNESS_VALUES.join(", ")}.`,
+    );
+  }
+  return /** @type {Strictness} */ (normalized);
+}
+
+/**
+ * Runtime type guard for the Strictness union.
+ *
+ * @param {string} value
+ * @returns {value is Strictness}
+ */
+function isStrictness(value) {
+  return STRICTNESS_VALUES.includes(value);
+}

package/plugin/hooks/lib/gatekeeper-rules.mjs

@@ -0,0 +1,257 @@
+// @ts-check
+/**
+ * Deterministic prophylactic rules for the claude-crap PreToolUse gatekeeper.
+ *
+ * Each rule is a pure function (input → verdict). Rules never perform I/O:
+ * rules that would need a deep analysis instead trigger an MCP tool call
+ * from a later hook (PostToolUse or Stop). The PreToolUse hook itself must
+ * respond within Claude Code's 15-second timeout window — anything that
+ * could block for longer than a few hundred milliseconds belongs elsewhere.
+ *
+ * Each rule returns a verdict of the shape:
+ *
+ *   { blocked: boolean, ruleId: string, reason: string }
+ *
+ * When `blocked === true`, the hook will exit with code 2 and write the
+ * `reason` text to stderr. Claude Code forwards stderr from a blocking
+ * hook straight into the agent's context window, so the reason text is
+ * effectively a prompt to the LLM — it must be imperative and corrective.
+ *
+ * All reason strings are in English because they are injected into the
+ * agent's context and the plugin is distributed publicly.
+ *
+ * @module hooks/lib/gatekeeper-rules
+ */
+
+/**
+ * Minimal shape of the JSON payload Claude Code sends on stdin to a hook.
+ * See https://code.claude.com/docs/en/hooks for the full spec.
+ *
+ * @typedef {Object} HookInput
+ * @property {string} [session_id]        - Current session identifier.
+ * @property {string} [transcript_path]   - Path to the conversation transcript.
+ * @property {string} [hook_event_name]   - "PreToolUse" for this hook.
+ * @property {string} tool_name           - Name of the tool about to be invoked.
+ * @property {Record<string, unknown>} tool_input - Raw arguments proposed by the LLM.
+ */
+
+/**
+ * Verdict returned by each rule. Rules that do not trigger return `null`
+ * instead of a verdict — the runner uses that signal to short-circuit.
+ *
+ * @typedef {Object} Verdict
+ * @property {boolean} blocked - `true` if the hook should abort the tool call.
+ * @property {string}  ruleId  - Stable identifier for this rule (SONAR-XXX-NNN).
+ * @property {string}  reason  - Imperative, corrective message for the LLM.
+ */
+
+/**
+ * Default blocklist regex for sensitive paths. This is replaced at runtime
+ * by whatever the user configured via `CLAUDE_PLUGIN_OPTION_BLOCKED_PATH_PATTERNS`.
+ */
+const DEFAULT_BLOCKED_PATH_REGEX =
+  /(^|\/)(\.git|\.env|\.env\..*|node_modules|\.venv|secrets?|credentials?|id_rsa|\.ssh)(\/|$)/i;
+
+/**
+ * Heuristic signatures of secrets that should never be committed to source.
+ * This list is intentionally conservative — the gatekeeper is a speed bump,
+ * not a replacement for a real secret scanner. Deeper detection runs in
+ * PostToolUse via the MCP `ingest_sarif` tool.
+ */
+const HARDCODED_SECRET_PATTERNS = [
+  { id: "SEC-AWS", re: /AKIA[0-9A-Z]{16}/ },
+  { id: "SEC-PRIVKEY", re: /-----BEGIN (RSA |OPENSSH |EC |DSA |PGP )?PRIVATE KEY-----/ },
+  { id: "SEC-SLACKTOKEN", re: /xox[baprs]-[0-9A-Za-z-]{10,}/ },
+  { id: "SEC-GHTOKEN", re: /gh[pousr]_[A-Za-z0-9]{36,}/ },
+  { id: "SEC-JWT", re: /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/ },
+];
+
+/**
+ * Destructive shell patterns. These commands can silently destroy work,
+ * overwrite published git history, or execute remote code without review.
+ * The gatekeeper refuses them outright — if the user really needs to run
+ * one of these, they should do it from their own terminal.
+ */
+const DESTRUCTIVE_BASH_PATTERNS = [
+  { id: "BASH-RMROOT", re: /\brm\s+(-[frR]+\s+|--force\s+|--recursive\s+).*(\s|^)\/($|\s)/ },
+  { id: "BASH-RMHOME", re: /\brm\s+-[frR]+\s+.*\$HOME\b/ },
+  { id: "BASH-DD", re: /\bdd\s+.*of=\/dev\/(sd|nvme|disk)/ },
+  { id: "BASH-GITFORCE", re: /\bgit\s+push\s+.*--force(?!-with-lease)/ },
+  { id: "BASH-GITRESET", re: /\bgit\s+reset\s+--hard\s+origin/ },
+  { id: "BASH-CURLSUDO", re: /\bcurl\s+[^|]*\|\s*(sudo\s+)?(bash|sh|zsh|fish)/ },
+];
+
+/**
+ * Compile the user-configured blocked-path regex. Falls back to the default
+ * pattern if the configured value is missing or malformed — we never let a
+ * broken regex disable the gatekeeper entirely.
+ *
+ * @param {string | undefined} value Raw regex source from the environment.
+ * @returns {RegExp}                 A compiled, case-insensitive regex.
+ */
+function compileBlockedPathRegex(value) {
+  if (!value) return DEFAULT_BLOCKED_PATH_REGEX;
+  try {
+    return new RegExp(value, "i");
+  } catch {
+    return DEFAULT_BLOCKED_PATH_REGEX;
+  }
+}
+
+/**
+ * Rule 1 — blocked destination path.
+ *
+ * Fires when the LLM tries to Write, Edit or NotebookEdit any file that
+ * matches the blocklist regex. This is the first line of defense against
+ * accidental edits to `.env`, `.git`, `node_modules`, SSH keys, etc.
+ *
+ * @param {HookInput} input Parsed hook payload.
+ * @returns {Verdict | null} A blocking verdict, or `null` to pass.
+ */
+export function checkBlockedPath(input) {
+  const filePath =
+    typeof input.tool_input.file_path === "string"
+      ? input.tool_input.file_path
+      : typeof input.tool_input.notebook_path === "string"
+        ? input.tool_input.notebook_path
+        : undefined;
+  if (!filePath) return null;
+
+  const regex = compileBlockedPathRegex(process.env.CLAUDE_PLUGIN_OPTION_BLOCKED_PATH_PATTERNS);
+  if (regex.test(filePath)) {
+    return {
+      blocked: true,
+      ruleId: "SONAR-PATH-001",
+      reason:
+        `Path '${filePath}' matches BLOCKED_PATH_PATTERNS. ` +
+        `claude-crap refuses to write or edit sensitive paths such as secrets, .git, node_modules, or .env files. ` +
+        `Corrective action: pick a file outside those directories. If this change is legitimate, ` +
+        `ask the user to relax CLAUDE_PLUGIN_OPTION_BLOCKED_PATH_PATTERNS before retrying.`,
+    };
+  }
+  return null;
+}
+
+/**
+ * Rule 2 — hardcoded secrets in proposed content.
+ *
+ * Scans `content` (Write), `new_string` (Edit) and every element of
+ * `edits[]` (MultiEdit) for well-known secret signatures. Does NOT run
+ * full entropy analysis — that is the job of a secret scanner plugged in
+ * via PostToolUse / `ingest_sarif`.
+ *
+ * @param {HookInput} input Parsed hook payload.
+ * @returns {Verdict | null} A blocking verdict, or `null` to pass.
+ */
+export function checkHardcodedSecrets(input) {
+  const candidates = [];
+  if (typeof input.tool_input.content === "string") {
+    candidates.push(input.tool_input.content);
+  }
+  if (typeof input.tool_input.new_string === "string") {
+    candidates.push(input.tool_input.new_string);
+  }
+  if (Array.isArray(input.tool_input.edits)) {
+    for (const edit of input.tool_input.edits) {
+      if (edit && typeof edit === "object" && typeof (/** @type {any} */ (edit).new_string) === "string") {
+        candidates.push(/** @type {any} */ (edit).new_string);
+      }
+    }
+  }
+  if (candidates.length === 0) return null;
+
+  for (const text of candidates) {
+    for (const pat of HARDCODED_SECRET_PATTERNS) {
+      if (pat.re.test(text)) {
+        return {
+          blocked: true,
+          ruleId: `SONAR-SEC-${pat.id}`,
+          reason:
+            `A likely hardcoded secret (${pat.id}) was detected in the proposed content. ` +
+            `Per the Golden Rule in CLAUDE.md, credentials must never be embedded in source code. ` +
+            `Corrective action: move the value to an environment variable or a managed secret; ` +
+            `do not commit tokens, private keys, or JWTs to the source tree under any circumstance.`,
+        };
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Rule 3 — destructive Bash commands.
+ *
+ * Only fires when `tool_name === "Bash"`. Refuses commands that can
+ * recursively delete the workspace, overwrite published git history,
+ * write raw bytes to a block device, or pipe a remote script into a shell.
+ *
+ * @param {HookInput} input Parsed hook payload.
+ * @returns {Verdict | null} A blocking verdict, or `null` to pass.
+ */
+export function checkDestructiveBash(input) {
+  if (input.tool_name !== "Bash") return null;
+  const command =
+    typeof input.tool_input.command === "string" ? input.tool_input.command : undefined;
+  if (!command) return null;
+
+  for (const pat of DESTRUCTIVE_BASH_PATTERNS) {
+    if (pat.re.test(command)) {
+      return {
+        blocked: true,
+        ruleId: `SONAR-BASH-${pat.id}`,
+        reason:
+          `The proposed Bash command matched the destructive pattern ${pat.id}: '${command}'. ` +
+          `claude-crap blocks operations that can wipe the project tree, rewrite published git history, ` +
+          `or execute remote code without review. ` +
+          `Corrective action: if this operation is truly intended, ask the user to confirm and run it ` +
+          `manually from their own terminal instead of through the agent.`,
+      };
+    }
+  }
+  return null;
+}
+
+/**
+ * Rule 4 — test harness presence (no-op in PreToolUse by design).
+ *
+ * The CLAUDE.md Golden Rule forbids writing functional code before a
+ * test safety net exists. Enforcing that strictly requires reading
+ * the workspace to check for an accompanying test file, which is too
+ * slow for the 15 s PreToolUse budget. The full check therefore runs
+ * in PostToolUse via the MCP `require_test_harness` tool — this rule
+ * stays in the pipeline purely as the registered slot for rule ID
+ * `SONAR-TEST-001`, so the rule count the hook reports on stdout
+ * stays stable and downstream consumers can correlate the slot with
+ * its PostToolUse counterpart.
+ *
+ * @param {HookInput} _input Parsed hook payload (unused; always returns null).
+ * @returns {Verdict | null} Always `null`; enforcement happens in PostToolUse.
+ */
+export function checkTestHarnessPresence(_input) {
+  return null;
+}
+
+/**
+ * Run every rule in order, cheapest first, and return the first blocking
+ * verdict found. Returns `null` when the proposed action passes every rule.
+ *
+ * Ordering matters: path checks are nearly free, destructive-bash checks
+ * run a handful of regexes, and secret checks iterate a longer pattern
+ * list. Keeping cheap rules first minimizes the common-case latency.
+ *
+ * @param {HookInput} input Parsed hook payload.
+ * @returns {Verdict | null} First blocking verdict, or `null` to pass.
+ */
+export function runAllRules(input) {
+  const rules = [
+    checkBlockedPath,
+    checkDestructiveBash,
+    checkHardcodedSecrets,
+    checkTestHarnessPresence,
+  ];
+  for (const rule of rules) {
+    const verdict = rule(input);
+    if (verdict && verdict.blocked) return verdict;
+  }
+  return null;
+}