@monte3l/groundwork 0.0.0

package/templates/core/.claude/hooks/guard-double-background.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse guard (Bash): block a command that combines `run_in_background:
+ * true` with a shell-level detach construct (`nohup`, `disown`, or a trailing
+ * `&`) in the same call.
+ *
+ * The two mechanisms both try to survive process/session churn, but stacking
+ * them produces a false "completed" report instead of a working one: the
+ * harness's own background-job tracking loses track of a process it never
+ * actually owns (the shell already detached it), so a poll against the
+ * harness-tracked job reports done while the real work is either still
+ * running unobserved or was silently killed along with the polling wrapper.
+ * Pick exactly one detachment mechanism per call: `run_in_background: true`
+ * alone (the harness tracks it), or a plain foreground command wrapped in
+ * `nohup <cmd> > <log> 2>&1 & disown` with the polling done separately
+ * against the raw PID (`kill -0 $PID`) -- never both on the same invocation.
+ *
+ * Fail-open on everything ambiguous: a malformed payload, a missing/
+ * non-boolean `run_in_background`, or a command with no detach construct all
+ * exit 0. This is a DENYLIST of the three known detach constructs, not a
+ * strict parse of the shell grammar -- extend `hasShellDetach` as new gaps
+ * are found rather than reaching for a real shell parser.
+ */
+import process from "node:process";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Does `command` contain a shell-level detach construct: `nohup`, `disown`,
+ * or a trailing background `&`?
+ *
+ * Both checks are anchored to avoid matching ordinary argument text, not
+ * just shell operators:
+ *
+ * - `nohup`/`disown` only count in COMMAND POSITION -- the start of the
+ *   whole string, or right after a command separator (`;`, `&`, `|`, `(`).
+ *   An unanchored `\bnohup\b` would also fire on `grep -n nohup file.txt`
+ *   (searching FOR the word) -- matching argument text, not an invocation.
+ * - the bare `&` check excludes `&&` (logical AND), both fd-duplication
+ *   redirect spellings -- `2>&1` (a `&` immediately preceded by `>`) and
+ *   `&>`/`&>>` (bash's combined-redirect shorthand for `> file 2>&1`) -- and
+ *   requires the `&` to sit at a command boundary (end-of-command or
+ *   followed by whitespace), so an embedded query-string `&`
+ *   (`...100&page=2`) isn't misread as backgrounding.
+ *
+ * @param {string} command
+ * @returns {boolean}
+ */
+export function hasShellDetach(command) {
+  if (/(?:^|[;&|(])\s*(?:nohup|disown)\b/.test(command)) return true;
+  return /(?<![&>])&(?![&>\S])/.test(command);
+}
+
+/**
+ * Pure decision function -- exported for unit testing. Every ambiguous or
+ * non-applicable input returns `false` (allow), and only one confirmed
+ * verdict returns `true` (block).
+ *
+ * @param {string} command
+ * @param {unknown} runInBackground raw `tool_input.run_in_background` value
+ * @returns {boolean} true = block, false = allow
+ */
+export function shouldBlockDoubleBackground(command, runInBackground) {
+  if (runInBackground !== true) return false;
+  if (typeof command !== "string" || command.length === 0) return false;
+  return hasShellDetach(command);
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+// Deliberately inlined in every hook rather than shared: caps.ts counts
+// .claude/hooks/*.mjs files against a hard limit, so a helper module would
+// cost a hook slot. `import.meta.url` is symlink-resolved but `process.argv[1]`
+// is not, so comparing them directly is false under any symlinked path and the
+// guard body would never run -- exit 0, i.e. fail open.
+function isEntryPoint() {
+  try {
+    return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+}
+
+// Only run when invoked directly, not when imported for testing.
+if (isEntryPoint()) {
+  const raw = await readStdin();
+  let input;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    process.exit(0);
+  }
+
+  const command = input.tool_input?.command;
+  const runInBackground = input.tool_input?.run_in_background;
+
+  if (!shouldBlockDoubleBackground(command, runInBackground)) process.exit(0);
+
+  process.stderr.write(`\
+[guard-double-background] Blocked: this command combines \`run_in_background:
+true\` with a shell-level detach construct (\`nohup\`, \`disown\`, or a
+trailing \`&\`). Stacking both risks a false "completed" report -- the
+harness loses track of a process the shell already detached. Pick exactly one:
+  - \`run_in_background: true\` alone, polled via TaskOutput/Monitor, or
+  - a foreground \`nohup <cmd> > <log> 2>&1 & disown\`, polled separately
+    against the raw PID (\`kill -0 $PID\`) -- with run_in_background left false.
+`);
+  process.exit(2);
+}

package/templates/core/.claude/hooks/guard-git-push-signed.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse guard (Bash): block a `git push` issued through the agent's Bash
+ * tool when any outgoing commit is unsigned or has an invalid signature.
+ *
+ * This is the FIRST Bash-matcher hook in the baseline -- every other
+ * PreToolUse hook inspects `tool_input.file_path`; this one inspects
+ * `tool_input.command`.
+ *
+ * Opt-in, not always-on: `signingEnabled()` (bin/lib/signed-range.mjs) checks
+ * whether THIS machine's git is configured to sign commits at all
+ * (`commit.gpgsign`). A project whose author hasn't set up commit signing
+ * gets no enforcement here -- the alternative (enforcing by default) would
+ * hard-block every push on a machine with no GPG/SSH signing key configured,
+ * which is not a safe default for a freshly bootstrapped project. Turn
+ * signing on (`git config commit.gpgsign true`) and this guard turns on with
+ * it, no other configuration step.
+ *
+ * Fail-open by design (matching every sibling hook): a malformed payload, a
+ * non-push command, signing not enabled, or a git failure all exit 0. The
+ * literal-signature verdict is the only thing that blocks (exit 2). Pair
+ * this with your remote's own "require signed commits" branch-protection
+ * setting for the authoritative, unbypassable layer -- this hook is only the
+ * earlier, local catch.
+ */
+import process from "node:process";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import {
+  parseGitPush,
+  outgoingCommits,
+  unsignedCommits,
+  signingEnabled,
+} from "../../bin/lib/signed-range.mjs";
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+// Deliberately inlined in every hook rather than shared: caps.ts counts
+// .claude/hooks/*.mjs files against a hard limit, so a helper module would
+// cost a hook slot. `import.meta.url` is symlink-resolved but `process.argv[1]`
+// is not, so comparing them directly is false under any symlinked path and the
+// guard body would never run -- exit 0, i.e. fail open.
+function isEntryPoint() {
+  try {
+    return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+}
+
+// Only run when invoked directly, not when imported for testing.
+if (isEntryPoint()) {
+  const raw = await readStdin();
+  let input;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    process.exit(0);
+  }
+
+  const command = input.tool_input?.command;
+  const { isPush, dryRun } = parseGitPush(
+    typeof command === "string" ? command : "",
+  );
+  if (!isPush || dryRun) process.exit(0);
+  if (!signingEnabled()) process.exit(0);
+
+  let bad;
+  try {
+    bad = unsignedCommits(outgoingCommits());
+  } catch {
+    process.exit(0); // cannot determine range -> defer to remote branch protection
+  }
+  if (bad.length === 0) process.exit(0);
+
+  process.stderr.write(`\
+[guard-git-push-signed] Blocked: refusing to push unsigned/unverified commits.
+${bad.map(({ sha, code }) => `  - ${sha.slice(0, 12)} (%G? = ${code})`).join("\n")}
+
+commit.gpgsign is enabled on this machine, so every commit pushed to the
+remote must carry a valid signature. Re-sign the range, e.g.:
+  git rebase --exec 'git commit --amend --no-edit -S' origin/main
+Then retry the push.
+`);
+  process.exit(2);
+}

package/templates/core/.claude/hooks/guard-hub-src-writes.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse guard (Write|Edit): blocks hub-authored writes into guarded
+ * source and test paths on ANY branch.
+ *
+ * Problem: `guard-branch-isolation.mjs` only fires while `HEAD` is `main`.
+ * On a feature branch nothing else stops the hub itself from writing
+ * directly into a guarded path instead of dispatching the write to a writer
+ * spoke, as CLAUDE.md's Agent Operating Model requires.
+ *
+ * The seam: the PreToolUse payload carries a top-level `agent_type` field
+ * when the tool call fires inside a subagent context. The field is absent
+ * (or empty) for hub-level calls, and contains the subagent's name for
+ * spoke calls.
+ *
+ * The decision: block when BOTH conditions hold:
+ *   (a) the target path is a guarded source/test path, AND
+ *   (b) `agent_type` is NOT the name of an authorised writer spoke
+ *       (`code-implementer` or `test-author`, per WRITER_SPOKES in
+ *        bin/lib/agent-roster.mjs).
+ *
+ * Hub calls (absent/empty agent_type) and non-writer subagents are treated
+ * identically -- both are blocked from guarded paths. Writer spokes are
+ * allowed through. All other paths are allowed through unconditionally.
+ *
+ * Fail-open: an unparseable payload or missing file_path exits 0 so a
+ * malformed hook input never wedges the session.
+ */
+import process from "node:process";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { isProtectedPath } from "../../bin/lib/protected-paths.mjs";
+import { WRITER_SPOKES } from "../../bin/lib/agent-roster.mjs";
+
+/**
+ * Pure decision function -- exported for unit testing.
+ *
+ * @param {string | undefined} filePath  The file_path from the tool_input payload.
+ * @param {unknown} agentType            The top-level agent_type from the payload.
+ * @returns {boolean} true = block, false = allow.
+ */
+export function shouldBlockHubSrcWrite(filePath, agentType) {
+  if (!filePath || typeof filePath !== "string") return false;
+  if (!isProtectedPath(filePath)) return false;
+  if (
+    typeof agentType === "string" &&
+    agentType.length > 0 &&
+    WRITER_SPOKES.has(agentType)
+  ) {
+    return false;
+  }
+  return true;
+}
+
+// Deliberately inlined in every hook rather than shared: caps.ts counts
+// .claude/hooks/*.mjs files against a hard limit, so a helper module would
+// cost a hook slot. `import.meta.url` is symlink-resolved but `process.argv[1]`
+// is not, so comparing them directly is false under any symlinked path and the
+// guard body would never run -- exit 0, i.e. fail open.
+function isEntryPoint() {
+  try {
+    return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+}
+
+// Only run when invoked directly, not when imported for testing.
+if (isEntryPoint()) {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  let input;
+  try {
+    input = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch {
+    process.exit(0);
+  }
+  const filePath = input.tool_input?.file_path ?? "";
+  const agentType = input.agent_type;
+  if (!shouldBlockHubSrcWrite(filePath, agentType)) process.exit(0);
+  process.stderr.write(
+    "guard-hub-src-writes: Hub-authored write to a guarded path detected.\n" +
+      `  Path: ${filePath}\n` +
+      "  Dispatch the write to 'code-implementer' (src/**) or 'test-author' (tests/**) instead.\n" +
+      "  See: CLAUDE.md's Agent Operating Model.\n",
+  );
+  process.exit(2);
+}

package/templates/core/.claude/hooks/guard-js-extension.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse guard (Write|Edit): blocks writing a relative import that is
+ * missing the `.js` extension.
+ *
+ * This is the #1 documented ESM gotcha -- a relative import without `.js`
+ * type-checks but fails to resolve at runtime in Node. Path-scoped rules
+ * inject on Read, not reliably at Write, so this runs as a hook.
+ *
+ * Blocks by exiting 2 with a message on stderr (Claude Code convention).
+ */
+import process from "node:process";
+
+const ALLOWED = [".js", ".mjs", ".cjs", ".json", ".node"];
+
+/** Extract the content being written from the tool input. */
+function contentToCheck(input) {
+  const ti = input.tool_input ?? {};
+  // Write -> content; Edit -> new_string (the text being introduced).
+  return [ti.content, ti.new_string].filter((s) => typeof s === "string");
+}
+
+/** Find relative import/export specifiers missing an allowed extension. */
+function offendingSpecifiers(source) {
+  const offenders = [];
+  // Matches: from "./x", from '../y', import("./z"), require("./w")
+  const re = /\b(?:from|import|require)\s*\(?\s*["'](\.\.?\/[^"']*)["']/g;
+  let m;
+  while ((m = re.exec(source)) !== null) {
+    const spec = m[1];
+    const hasAllowed = ALLOWED.some((ext) => spec.endsWith(ext));
+    if (!hasAllowed) offenders.push(spec);
+  }
+  return offenders;
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+const raw = await readStdin();
+let input;
+try {
+  input = JSON.parse(raw);
+} catch {
+  process.exit(0); // Not our concern; let the call through.
+}
+
+const filePath = input.tool_input?.file_path ?? "";
+if (!/\.(ts|tsx|mts|cts)$/.test(filePath)) process.exit(0);
+
+const offenders = contentToCheck(input).flatMap(offendingSpecifiers);
+if (offenders.length > 0) {
+  const unique = [...new Set(offenders)];
+  process.stderr.write(
+    `Blocked: relative import(s) missing the required \`.js\` extension ` +
+      `(ESM + NodeNext will fail to resolve at runtime):\n` +
+      unique.map((s) => `  - "${s}"  ->  "${s}.js"`).join("\n") +
+      `\nAdd the \`.js\` extension to every relative import.\n`,
+  );
+  process.exit(2);
+}
+
+process.exit(0);

package/templates/core/.claude/hooks/guard-no-commonjs.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse guard (Write|Edit): blocks CommonJS constructs in TypeScript
+ * source. This project is ESM only ("type": "module"); `require`,
+ * `module.exports`, `exports.`, `__dirname`, and `__filename` are forbidden.
+ *
+ * Blocks by exiting 2 with a message on stderr.
+ */
+import process from "node:process";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const PATTERNS = [
+  { re: /\brequire\s*\(/, label: "require(...)" },
+  { re: /\bmodule\.exports\b/, label: "module.exports" },
+  // A bare \b also fires inside kebab-case filenames like
+  // "check-doc-exports.mjs" (hyphen -> letter is a word-boundary
+  // transition). Excluding a preceding identifier char or hyphen keeps real
+  // `exports.foo = ...` assignments blocked while letting mentions of any
+  // "*-exports.<ext>" bin script through.
+  { re: /(?<![\w-])exports\.[A-Za-z_$]/, label: "exports.<name>" },
+  { re: /\b__dirname\b/, label: "__dirname" },
+  { re: /\b__filename\b/, label: "__filename" },
+];
+
+const SOURCE_EXT_RE = /\.(ts|tsx|mts|cts|js|mjs)$/;
+
+/**
+ * True when `filePath` is TS/JS source this guard should inspect -- not a
+ * config file, doc, or a file under this hook's own directory.
+ *
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function isGuardedFilePath(filePath) {
+  if (!SOURCE_EXT_RE.test(filePath)) return false;
+  // Normalize separators first: Windows paths use "\", and a literal "/"
+  // check silently never matches there, leaving this hook unable to exempt
+  // its own directory on that platform.
+  if (filePath.replace(/\\/g, "/").includes("/.claude/hooks/")) return false;
+  return true;
+}
+
+/**
+ * Scan `content` for forbidden CommonJS constructs. Returns a human-readable
+ * label per match (empty array when clean).
+ *
+ * @param {string} content
+ * @returns {string[]}
+ */
+export function findCommonJsHits(content) {
+  return PATTERNS.filter((p) => p.re.test(content)).map((p) => p.label);
+}
+
+function contentToCheck(input) {
+  const ti = input.tool_input ?? {};
+  return [ti.content, ti.new_string].filter((s) => typeof s === "string");
+}
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+// Deliberately inlined in every hook rather than shared: caps.ts counts
+// .claude/hooks/*.mjs files against a hard limit, so a helper module would
+// cost a hook slot. `import.meta.url` is symlink-resolved but `process.argv[1]`
+// is not, so comparing them directly is false under any symlinked path and the
+// guard body would never run -- exit 0, i.e. fail open.
+function isEntryPoint() {
+  try {
+    return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+}
+
+// Main execution -- only run when invoked directly, not when imported for testing.
+if (isEntryPoint()) {
+  const raw = await readStdin();
+  let input;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    process.exit(0);
+  }
+
+  const filePath = input.tool_input?.file_path ?? "";
+  if (!isGuardedFilePath(filePath)) process.exit(0);
+
+  const source = contentToCheck(input).join("\n");
+  const hits = findCommonJsHits(source);
+  if (hits.length > 0) {
+    process.stderr.write(
+      `Blocked: CommonJS construct(s) found (this project is ESM only):\n` +
+        hits.map((h) => `  - ${h}`).join("\n") +
+        `\nUse ESM equivalents: import/export, import.meta.url, ` +
+        `fileURLToPath(import.meta.url).\n`,
+    );
+    process.exit(2);
+  }
+
+  process.exit(0);
+}

package/templates/core/.claude/hooks/guard-protected-paths.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse guard (Write|Edit): protects tool-owned artifacts.
+ *
+ *  - `dist/**` is tsc output and must never be hand-edited.
+ *  - `coverage/**` is the vitest v8 coverage report and must never be
+ *    hand-edited.
+ *
+ * Add another generated-output directory to PROTECTED_DIR_NAMES below if
+ * this project introduces one (e.g. a bundler's own output dir).
+ *
+ * Blocks by exiting 2 with a message on stderr.
+ */
+import process from "node:process";
+
+const PROTECTED_DIR_NAMES = ["dist", "coverage"];
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+const raw = await readStdin();
+let input;
+try {
+  input = JSON.parse(raw);
+} catch {
+  process.exit(0);
+}
+
+const filePath = input.tool_input?.file_path ?? "";
+
+const hit = PROTECTED_DIR_NAMES.find((name) =>
+  new RegExp(`(^|/)${name}/`).test(filePath),
+);
+if (hit) {
+  process.stderr.write(
+    `Blocked: \`${hit}/\` is generated output and must never be ` +
+      `hand-edited. Change the source and rebuild/retest instead.\n`,
+  );
+  process.exit(2);
+}
+
+process.exit(0);

package/templates/core/.claude/hooks/guard-secret-writes.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse blocking (Write|Edit): refuse to write a real secret to disk.
+ *
+ * CLAUDE.md's Security section requires that no secret or token ever land in
+ * source, tests, or fixtures. A CI secret-scanning step is the backstop;
+ * this hook is the earlier, write-time block so a credential never reaches
+ * the working tree -- where it would linger in git reflog/objects even
+ * after a fix.
+ *
+ * Two independent triggers, both hard-block (exit 2):
+ *   1. Path: a dotenv file (`.env`, `.env.local`, ...) -- these are
+ *      gitignored secret stores and should never be authored by the agent.
+ *      Template variants (`.env.example`/`.sample`/`.template`/`.dist`) are
+ *      allowed.
+ *   2. Content: a known secret-key assignment carrying a *real* value, or a
+ *      recognised high-entropy token/private-key literal. References and
+ *      placeholders (`${{ secrets.X }}`, `process.env.X`, `<your-token>`, ...)
+ *      are NOT flagged -- the point is to catch values, not names.
+ *
+ * Detection is deliberately conservative: prefix-anchored token shapes and
+ * placeholder exclusion keep false positives off legitimate config/docs
+ * (e.g. `GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}` in a workflow).
+ */
+import process from "node:process";
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+/**
+ * Env-var-name prefixes/exact names whose assigned *value* is a secret we
+ * must never persist. Project-specific keys can be appended here.
+ */
+export const SECRET_KEYS = [
+  "NPM_TOKEN",
+  "GITHUB_TOKEN",
+  "GH_TOKEN",
+  "AWS_SECRET_ACCESS_KEY",
+  "AWS_ACCESS_KEY_ID",
+  "AWS_SESSION_TOKEN",
+];
+
+// High-signal literal shapes -- a match is almost certainly a real credential.
+const TOKEN_LITERALS = [
+  /\bghp_[A-Za-z0-9]{36}\b/, // GitHub personal access token
+  /\bgithub_pat_[A-Za-z0-9_]{22,}\b/, // GitHub fine-grained PAT
+  /\bnpm_[A-Za-z0-9]{36}\b/, // npm automation token
+  /\bAKIA[0-9A-Z]{16}\b/, // AWS access key id
+  /-----BEGIN (?:RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----/, // PEM private key
+];
+
+/**
+ * A value is a placeholder/reference, not a real secret, when it defers to an
+ * env var or CI secret, or is an obvious dummy. Such values must not be flagged.
+ *
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isPlaceholderValue(value) {
+  const v = value.trim().replace(/^["']|["']$/g, "");
+  if (v.length === 0) return true;
+  if (/\$\{|\$\(|process\.env|secrets\.|env\./.test(v)) return true; // reference
+  if (/^<.*>$/.test(v)) return true; // <your-token>
+  if (
+    /(example|placeholder|changeme|your[-_]|xxx+|dummy|fake|redacted)/i.test(v)
+  )
+    return true;
+  // Too short / low-entropy to be a real token.
+  return v.length < 16;
+}
+
+/**
+ * True when the basename is a real dotenv file (not a committed template).
+ *
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function isEnvFilePath(filePath) {
+  const base = path.basename(filePath);
+  if (!/^\.env(\.|$)/.test(base)) return false;
+  return !/\.(example|sample|template|dist)$/.test(base);
+}
+
+/**
+ * Scan `content` for secret-key assignments carrying a real value or for a
+ * recognised token/private-key literal. Returns a human-readable reason per
+ * match (empty array when clean).
+ *
+ * @param {string} content
+ * @returns {string[]}
+ */
+export function findSecrets(content) {
+  const hits = [];
+
+  for (const key of SECRET_KEYS) {
+    // KEY = value  or  KEY: value  (env/yaml/json-ish), value runs to EOL.
+    const re = new RegExp(`\\b${key}\\b\\s*[:=]\\s*(.+)`, "g");
+    for (const m of content.matchAll(re)) {
+      if (!isPlaceholderValue(m[1]))
+        hits.push(`${key} assigned a literal value`);
+    }
+  }
+
+  for (const re of TOKEN_LITERALS) {
+    if (re.test(content))
+      hits.push(`recognised token/key literal (${re.source})`);
+  }
+
+  return hits;
+}
+
+/**
+ * Combined verdict for a write. Returns the block reasons (empty when allowed).
+ *
+ * @param {string} filePath
+ * @param {string} content
+ * @returns {string[]}
+ */
+export function isSecretWrite(filePath, content) {
+  const reasons = [];
+  if (isEnvFilePath(filePath)) {
+    reasons.push(`writing a dotenv secret file (${path.basename(filePath)})`);
+  }
+  reasons.push(...findSecrets(content ?? ""));
+  return reasons;
+}
+
+// Deliberately inlined in every hook rather than shared: caps.ts counts
+// .claude/hooks/*.mjs files against a hard limit, so a helper module would
+// cost a hook slot. `import.meta.url` is symlink-resolved but `process.argv[1]`
+// is not, so comparing them directly is false under any symlinked path and the
+// guard body would never run -- exit 0, i.e. fail open.
+function isEntryPoint() {
+  try {
+    return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+}
+
+// Main execution -- only run when invoked directly, not when imported for testing.
+if (isEntryPoint()) {
+  const raw = await readStdin();
+  let input;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    process.exit(0);
+  }
+
+  const filePath = input.tool_input?.file_path ?? "";
+  if (typeof filePath !== "string" || filePath.length === 0) process.exit(0);
+
+  // Content by field presence (Write -> content, Edit -> new_string), matching
+  // the sibling-hook convention so the guard stays live if tool_name is absent.
+  const ti = input.tool_input ?? {};
+  const content =
+    typeof ti.content === "string"
+      ? ti.content
+      : typeof ti.new_string === "string"
+        ? ti.new_string
+        : "";
+
+  const reasons = isSecretWrite(filePath, content);
+  if (reasons.length === 0) process.exit(0);
+
+  process.stderr.write(`\
+[guard-secret-writes] Blocked write to ${filePath}:
+${reasons.map((r) => `  - ${r}`).join("\n")}
+
+Secrets and tokens must never be written to the working tree -- they persist in
+git objects/reflog even after removal. Use a CI secret or an env var reference
+instead of a literal value, and keep real dotenv files out of the repo (.env*
+is gitignored; author .env.example with placeholders).
+`);
+  process.exit(2);
+}