shapeup-sdlc 1.6.2

package/hooks/lib/decision.mjs

@@ -0,0 +1,183 @@
+// runHook — give `allow` a receipt.
+//
+// WHY THIS FILE EXISTS (reproduced by executing the shipped hooks, not theorized).
+//
+// Every enforcement tool's FAILURE signature was identical to its SUCCESS signature. Fed malformed
+// input, every gate in this repo answered the same way:
+//
+//     $ echo 'NOT JSON AT ALL {{{' | node hooks/<gate>.mjs
+//     gate-l2            exit=0   stdout_len=0
+//     gate-zerowork      exit=0   stdout_len=0
+//     sandbox-guard      exit=0   stdout_len=0
+//     safety-spine       exit=0   stdout_len=0
+//     gate-deadline      exit=0   stdout_len=0
+//     gate-intake        exit=0   stdout_len=0
+//     validate-envelope  exit=0   stdout_len=0
+//
+// exit 0 + silence = allow. But that is ALSO what "inspected the board and deferred" looks like,
+// and what "no rule matched" looks like, and what a thrown exception looks like, and what F-16
+// looked like — a hook whose entire body silently never ran. Four states, one signature. No test,
+// orchestrator or auditor could tell them apart, which is how 26 enforcement points sat inert
+// behind 610 green checks while every one of them reported success.
+//
+// FAIL-OPEN IS RETAINED, DELIBERATELY. `gate-l2.mjs` argues for it correctly in its own header: a
+// gate that breaks legitimate or standalone runs just gets disabled, and a disabled gate enforces
+// nothing. The defect was never the direction. It is that `allow` carried NO EVIDENCE.
+//
+// THE PREDICATE IS ALREADY INVENTED IN THIS REPO. `tests/structural/11-is-main.mjs` calls its
+// helper `spoke()` — did the script produce output? That is exactly the right question. It existed
+// only in the test harness, applied to entry points. This promotes it to runtime and applies it to
+// hooks, which closes F-16's whole CLASS rather than its instance:
+//
+//     inspected-and-permitted · no-rule-matched · threw · never ran
+//
+// all four become distinguishable facts in `.shapeup-sdlc/decisions.jsonl`.
+//
+// TIER: LOCAL, and checkout-wide rather than per-slug — hooks fire outside any run, so there is
+// frequently no `<slug>` to file under. Pure run-trace; the durable cross-machine record is the
+// committed metrics shard, which `stats --hooks` aggregates into.
+//
+// THE RECEIPT IS BEST-EFFORT BY DESIGN. An unwritable `decisions.jsonl` must never turn into a
+// failed tool call: a receipt that can break a run would get the whole layer disabled, which is
+// the exact outcome this file exists to prevent. Every write here is inside a try/catch.
+
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+/**
+ * Where the receipts land.
+ *
+ * `SHAPEUP_DECISIONS_PATH` redirects the ledger. It exists because this project's OWN test suite
+ * executes the real hooks, and without a redirect every `npm test` appended ~21 rows to the
+ * developer's live `decisions.jsonl` — which would then be read back by `stats --hooks` as if
+ * they were evaluations from a real run. A measurement instrument that its own test suite
+ * contaminates is not an instrument.
+ *
+ * @param {string} [cwd] - Project root; defaults to the process cwd.
+ * @returns {string} The ledger path — `SHAPEUP_DECISIONS_PATH` when set, else
+ *   `<cwd>/.shapeup-sdlc/decisions.jsonl`.
+ */
+export function decisionsPath(cwd) {
+  return process.env.SHAPEUP_DECISIONS_PATH || join(cwd || process.cwd(), ".shapeup-sdlc", "decisions.jsonl");
+}
+
+/**
+ * Append one decision row. Never throws.
+ * @param {object} row - The decision record (see {@link runHook} for the shape).
+ * @param {string} [cwd] - Project root.
+ * @returns {boolean} True when the row reached disk.
+ */
+export function record(row, cwd) {
+  try {
+    const path = decisionsPath(cwd);
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, JSON.stringify(row) + "\n");
+    return true;
+  } catch { return false; }
+}
+
+/**
+ * Read the raw hook payload from stdin. Hooks that need it before deciding can call this;
+ * {@link runHook} does not read stdin itself, so a hook keeps control of its own parsing.
+ * @returns {Promise<string>} The stdin text, or "" when stdin is closed or errors.
+ */
+export function readStdin() {
+  return new Promise((res) => {
+    let d = "";
+    process.stdin.on("data", (c) => (d += c));
+    process.stdin.on("end", () => res(d));
+    process.stdin.on("error", () => res(""));
+  });
+}
+
+/**
+ * The sentinel `settle()` throws so a hook can leave from anywhere without a `process.exit` of
+ * its own. `runHook` unwraps it back into an ordinary decision.
+ */
+export class HookDecision extends Error {
+  /**
+   * @param {object} decision - The decision record (see {@link runHook}).
+   */
+  constructor(decision) {
+    super(decision.verdict);
+    this.name = "HookDecision";
+    this.decision = decision;
+  }
+}
+
+/**
+ * Settle the hook from anywhere in its body — the shape a `defer()` / `deny()` helper wraps.
+ *
+ * Hooks are written as a straight-line sequence of "is this even my business?" tests, each of
+ * which used to call `process.exit(0)` directly. Throwing instead of exiting means every one of
+ * those early outs still passes through the receipt.
+ *
+ * @param {object} decision - The decision record (see {@link runHook}).
+ * @returns {never} Never returns — always throws {@link HookDecision}.
+ */
+export function settle(decision) {
+  throw new HookDecision(decision);
+}
+
+/**
+ * The single exit path for every hook.
+ *
+ * A hook's body becomes a function that RETURNS a decision instead of calling `process.exit`
+ * itself. `runHook` records that decision and then exits — so there is exactly one place a hook
+ * can leave, and no route out of one that skips the receipt.
+ *
+ * The decision shape:
+ *   {
+ *     verdict: "allow" | "warn" | "deny" | "block" | "error",
+ *                                                      // "error" is still fail-open, now recorded;
+ *                                                      // "warn" permits but says so — see below
+ *     reason:  string,                                 // why, in one line
+ *     rule?:   string,                                 // which rule fired, when one did
+ *     event?:  string, tool?: string, subject?: string,// what was being judged
+ *     payload?: object,                                // the JSON the host reads
+ *     emit?:   boolean,                                // print `payload` even on an allow
+ *     cwd?:    string,                                 // where to file the receipt
+ *   }
+ *
+ * A body that returns nothing is recorded as `{verdict:"allow", reason:"no rule matched"}` — the
+ * commonest case, and previously the one indistinguishable from never having run.
+ *
+ * @param {string} name - The hook's name, as it appears in `hooks.json`.
+ * @param {function(): (object|Promise<object|undefined>|undefined)} fn - The hook body.
+ * @returns {Promise<never>} Does not return — always exits 0, per the fail-open contract.
+ */
+export async function runHook(name, fn) {
+  let d;
+  try {
+    d = (await fn()) ?? { verdict: "allow", reason: "no rule matched" };
+  } catch (e) {
+    if (e instanceof HookDecision) d = e.decision;
+    // Still fail-open — but now the throw is a FACT on disk instead of the same silence as a
+    // clean allow. This is the state that used to be completely unobservable.
+    else d = { verdict: "error", reason: String(e?.message ?? e) };
+  }
+  record({
+    at: new Date().toISOString(),
+    hook: name,
+    pid: process.pid,
+    event: d.event ?? null,
+    tool: d.tool ?? null,
+    subject: d.subject ?? null,
+    verdict: d.verdict ?? "allow",
+    reason: d.reason ?? null,
+    rule: d.rule ?? null,
+  }, d.cwd);
+  // Deny/block/warn payloads are emitted by definition. `emit: true` covers the hooks whose whole
+  // job is to SAY something on an allow — session-rehydrate's additionalContext, for instance — so
+  // a permitting hook can still write to stdout without pretending to be a denial.
+  //
+  // WHY `warn` IS ITS OWN VERDICT (ADR-0001). An advisory gate permits the call, so the obvious
+  // encoding is `verdict: "allow"`. That would make "permitted because the rule was satisfied"
+  // byte-identical to "permitted DESPITE the rule being broken" — the exact indistinguishability
+  // this file exists to eliminate, reintroduced one level up. A gate that downgrades from deny to
+  // advisory must stay countable, or `stats --hooks` silently loses the measurement.
+  if (d.payload && (d.verdict === "deny" || d.verdict === "block" || d.verdict === "warn" || d.emit)) {
+    process.stdout.write(JSON.stringify(d.payload));
+  }
+  process.exit(0);
+}

package/hooks/safety-spine.mjs

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+// Safety spine — PreToolUse hook (v1.2, absorb-audit P1).
+//
+// The three older hooks guard the PIPELINE (gate order, envelopes, substrates); this one
+// guards the MACHINE and the git remote — the substrate everything else sits on. It denies
+// the small set of provably destructive operations no harness round (and no standalone
+// session) ever legitimately needs:
+//   • destructive-fs   — rm -rf on /, ~, $HOME, .., bare * / ., 1-segment absolute paths;
+//                        git clean -f with -d/-x and no pathspec
+//   • git-destructive  — push --force (--force-with-lease stays allowed), explicit push to
+//                        main/master, git reset --hard (the harness's own rule: stash, never
+//                        hard-discard — see task-executor round protocol)
+//   • sql-destructive  — DROP TABLE/DATABASE/SCHEMA, TRUNCATE
+//   • secret-read      — reader commands (and the Read tool) on .env/*.pem/*.key/ssh keys/
+//                        cloud credentials
+//   • self-protect     — any write/move/delete touching .shapeup/safety-overrides.json:
+//                        the model must never widen its own safety envelope (same principle
+//                        as sandbox-guard's active-scope pointer rule)
+//
+// Deliberately conservative, mirrors gate-l2/sandbox-guard: fail-OPEN on unparseable input
+// or an unmatched command (precision over reach — a spine that broke `rm -rf ./build` would
+// just get disabled), fail-CLOSED the moment a rule provably matches.
+//
+// Escape hatch: .shapeup/safety-overrides.json (schema: domain.schema.json#/$defs/
+// SafetyOverrides) — human-authored, per-project, auditable. A malformed overrides file is
+// treated as ABSENT: the override channel fails closed so a parse error can never disable
+// the spine. Every exercised override is logged as a SAFETY-OVERRIDE pathology row —
+// overrides stay visible, propose-never-dispose.
+//
+// Contract: PreToolUse stdin JSON { tool_name, tool_input:{ command | file_path | edits[] }, cwd }.
+// Deny via { hookSpecificOutput: { hookEventName, permissionDecision:"deny", permissionDecisionReason } }.
+
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, join, basename } from "node:path";
+import { globToRegExp, logPathology } from "./sandbox-guard.mjs";
+import { isMain } from "../skills/tech-lead/scripts/lib/is-main.mjs";
+import { LOCAL, safetyOverrides, metricsShard } from "../skills/tech-lead/scripts/lib/paths.mjs";
+
+import { runHook, readStdin, settle } from "./lib/decision.mjs";
+
+// --- overrides ---------------------------------------------------------------
+
+export function loadOverrides(cwd) {
+  const p = safetyOverrides(cwd);
+  if (!existsSync(p)) return null;
+  try {
+    const o = JSON.parse(readFileSync(p, "utf8"));
+    // Fail closed: anything that isn't a well-formed v1 overrides object is ignored.
+    if (o?.schema_version !== 1) return null;
+    return {
+      allow_commands: Array.isArray(o.allow_commands) ? o.allow_commands : [],
+      allow_secret_paths: Array.isArray(o.allow_secret_paths) ? o.allow_secret_paths : [],
+      note: typeof o.note === "string" ? o.note : "",
+    };
+  } catch {
+    return null;
+  }
+}
+
+function commandOverridden(cmd, overrides) {
+  return (overrides?.allow_commands || []).some((src) => {
+    try { return new RegExp(src).test(cmd); } catch { return false; }
+  });
+}
+
+// --- secret paths --------------------------------------------------------------
+
+const SECRET_PATTERNS = [
+  /(^|[\\/])\.env(\.[^\\/]+)?$/i, // .env, .env.local, … (example/sample excluded below)
+  /\.pem$/i,
+  /\.key$/i,
+  /(^|[\\/])id_(rsa|ed25519|ecdsa|dsa)$/i, // private keys only — id_rsa.pub is public
+  /(^|[\\/])\.ssh[\\/]/,
+  /(^|[\\/])\.aws[\\/]credentials$/,
+  /(^|[\\/])credentials\.(json|ya?ml)$/i,
+];
+const SECRET_EXEMPT = /\.(example|sample|template|dist)$/i;
+
+export function isSecretPath(path, overrides) {
+  if (!path || typeof path !== "string") return false;
+  const clean = path.replace(/^['"]|['"]$/g, "");
+  if (SECRET_EXEMPT.test(clean)) return false;
+  if (!SECRET_PATTERNS.some((re) => re.test(clean))) return false;
+  if ((overrides?.allow_secret_paths || []).some((g) => globToRegExp(g).test(clean.replace(/^\.\//, "")))) return false;
+  return true;
+}
+
+// --- Bash command classification ------------------------------------------------
+
+const READER_CMDS = new Set([
+  "cat", "head", "tail", "less", "more", "strings", "grep", "rg", "awk", "sed", "cut", "base64", "xxd", "od",
+]);
+
+function tokens(segment) {
+  return segment.trim().split(/\s+/).filter(Boolean)
+    .map((t) => t.replace(/^['"]|['"]$/g, ""));
+}
+
+/** Strip leading env assignments and privilege/no-op wrappers to find the real command. */
+function commandTokens(segment) {
+  const ts = tokens(segment);
+  let i = 0;
+  while (i < ts.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(ts[i]) || ["sudo", "command", "env", "nohup", "time"].includes(ts[i]))) i++;
+  return ts.slice(i);
+}
+
+function isDangerousRmTarget(t) {
+  if (["/", "/*", "~", "~/", "$HOME", "${HOME}", "..", "../", "*", "."].includes(t)) return true;
+  // 1-segment absolute path: /usr, /etc, /Volumes … (multi-segment absolutes stay allowed)
+  if (t.startsWith("/") && t.replace(/\/+$/, "").split("/").filter(Boolean).length === 1) return true;
+  return false;
+}
+
+function classifySegment(segment, overrides) {
+  const ts = commandTokens(segment);
+  if (ts.length === 0) return null;
+  const cmd = basename(ts[0]);
+
+  // destructive-fs: rm with recursive+force on a provably dangerous target
+  if (cmd === "rm") {
+    const flags = ts.slice(1).filter((t) => t.startsWith("-"));
+    const recursive = flags.some((f) => f === "--recursive" || /^-[a-zA-Z]*[rR]/.test(f));
+    const force = flags.some((f) => f === "--force" || (/^-[a-zA-Z]*f/.test(f) && !f.startsWith("--")));
+    if (recursive && force) {
+      const target = ts.slice(1).filter((t) => !t.startsWith("-")).find(isDangerousRmTarget);
+      if (target) {
+        return { category: "destructive-fs", reason: `\`rm -rf ${target}\` targets a path whose loss is unrecoverable (${target}). Delete a specific project sub-path instead (relative, multi-segment targets like ./build are allowed).` };
+      }
+    }
+  }
+
+  // destructive-fs: git clean -f with -d/-x and no pathspec (wipes the whole untracked tree)
+  if (cmd === "git" && ts[1] === "clean") {
+    const rest = ts.slice(2);
+    const flags = rest.filter((t) => t.startsWith("-"));
+    const paths = rest.filter((t) => !t.startsWith("-"));
+    const force = flags.some((f) => /^-[a-zA-Z]*f/.test(f) || f === "--force");
+    const wide = flags.some((f) => /^-[a-zA-Z]*[dxX]/.test(f));
+    if (force && wide && paths.length === 0) {
+      return { category: "destructive-fs", reason: "`git clean -f` with -d/-x and no pathspec wipes every untracked file in the tree — including gitignored run-state. Name an explicit pathspec." };
+    }
+  }
+
+  if (cmd === "git") {
+    // git-destructive: force push / push to main
+    if (ts[1] === "push") {
+      const rest = ts.slice(2);
+      if (rest.some((t) => (t === "--force" || t === "-f") )) {
+        return { category: "git-destructive", reason: "`git push --force` rewrites remote history. Use --force-with-lease if a forced update is genuinely intended (it is allowed)." };
+      }
+      const nonFlags = rest.filter((t) => !t.startsWith("-"));
+      const ref = nonFlags[1] || "";
+      if (nonFlags.length >= 2 && (/^(main|master)$/.test(ref) || /:(main|master)$/.test(ref))) {
+        return { category: "git-destructive", reason: `\`git push ${nonFlags[0]} ${ref}\` pushes directly to the default branch. Push the working branch and open a PR (plain \`git push\` of the current branch is allowed).` };
+      }
+    }
+    // git-destructive: hard reset
+    if (ts[1] === "reset" && ts.includes("--hard")) {
+      return { category: "git-destructive", reason: "`git reset --hard` discards uncommitted work irrecoverably. The harness's own round protocol is `git stash push -u` — stash, never hard-discard (`git reset --soft` is allowed)." };
+    }
+  }
+
+  // sql-destructive
+  if (/\b(DROP\s+(TABLE|DATABASE|SCHEMA)|TRUNCATE(\s+TABLE)?)\b/i.test(segment)) {
+    return { category: "sql-destructive", reason: "The command contains a destructive SQL statement (DROP/TRUNCATE). Run schema-destroying SQL yourself, outside the session." };
+  }
+
+  // secret-read: a reader command whose argument is a secret path
+  if (READER_CMDS.has(cmd)) {
+    const secret = ts.slice(1).filter((t) => !t.startsWith("-")).find((t) => isSecretPath(t, overrides));
+    if (secret) {
+      return { category: "secret-read", reason: `\`${cmd} ${secret}\` reads a secret file. Secrets must not enter the conversation; if this is a false positive, add the path to ${LOCAL}/safety-overrides.json (allow_secret_paths).` };
+    }
+  }
+
+  // self-protect: any write/move/delete naming the overrides file
+  if (segment.includes("safety-overrides.json")) {
+    const writer =
+      /(^|[^>])>>?(?!&)/.test(segment) || // redirection (>, >>) — but not >&2
+      /\btee\b/.test(segment) ||
+      /\bsed\s+-[a-zA-Z]*i/.test(segment) ||
+      ["rm", "mv", "cp", "truncate"].includes(cmd);
+    if (writer) {
+      return { category: "self-protect", reason: `The safety-overrides file is human-authored only — the session must never widen (or remove) its own safety envelope. Ask the PO to edit ${LOCAL}/safety-overrides.json.` };
+    }
+  }
+
+  return null;
+}
+
+/** Classify a full Bash command (raw string + each &&/;/|/newline segment).
+ *  Returns { deny, category, reason } — deny:false means the spine has nothing to say. */
+export function classifyCommand(command, overrides) {
+  if (!command || typeof command !== "string") return { deny: false };
+  for (const segment of command.split(/\s*(?:\|\||&&|;|\||\n)\s*/).filter(Boolean)) {
+    const hit = classifySegment(segment, overrides);
+    if (hit) return { deny: true, ...hit };
+  }
+  return { deny: false };
+}
+
+// --- hook entry ------------------------------------------------------------------
+
+const HOOK_TOOLS = new Set(["Bash", "Read", "Write", "Edit", "MultiEdit"]);
+
+function extractPaths(toolInput) {
+  const paths = [];
+  if (toolInput?.file_path) paths.push(toolInput.file_path);
+  if (Array.isArray(toolInput?.edits)) {
+    for (const e of toolInput.edits) if (e?.file_path) paths.push(e.file_path);
+  }
+  return paths;
+}
+
+async function main() {
+  await runHook("safety-spine", async () => {
+  const raw = await readStdin();
+  let p;
+  /** Fail-open, with the reason on the record (hooks/lib/decision.mjs). */
+  const defer = (reason, rule) => settle({
+    verdict: "allow", event: "PreToolUse", tool: p?.tool_name ?? null, cwd: p?.cwd, reason, rule,
+  });
+  try { p = JSON.parse(raw || "{}"); }
+  catch (e) { settle({ verdict: "error", event: "PreToolUse", reason: `unparseable payload: ${e.message}` }); }
+
+  if (!HOOK_TOOLS.has(p.tool_name)) defer(`${p.tool_name ?? "no tool_name"} is not a guarded tool — out of scope`);
+
+  const cwd = p.cwd || process.cwd();
+  const overrides = loadOverrides(cwd);
+  const metricsPath = metricsShard(cwd);
+
+  const deny = (category, reason, detail) => {
+    logPathology(metricsPath, {
+      schema_version: 1,
+      at: new Date().toISOString(),
+      kind: "pathology",
+      pathology: "SAFETY",
+      category,
+      tool: p.tool_name,
+      ...detail,
+    });
+    settle({
+      verdict: "deny", event: "PreToolUse", tool: p.tool_name, cwd, rule: category,
+      subject: detail?.path ?? detail?.command ?? null, reason,
+      payload: {
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          permissionDecision: "deny",
+          permissionDecisionReason: `Safety spine (${category}) — ${reason}`,
+        },
+      },
+    });
+  };
+
+  if (p.tool_name === "Bash") {
+    const command = p.tool_input?.command || "";
+    const verdict = classifyCommand(command, overrides);
+    if (!verdict.deny) defer("command matched no destructive rule — inspected and permitted", "bash-clean");
+    if (commandOverridden(command, overrides)) {
+      // Exercised override: allowed, but never invisible.
+      logPathology(metricsPath, {
+        schema_version: 1,
+        at: new Date().toISOString(),
+        kind: "pathology",
+        pathology: "SAFETY-OVERRIDE",
+        category: verdict.category,
+        tool: "Bash",
+        command: command.slice(0, 200),
+        note: overrides?.note || "",
+      });
+      defer(`${verdict.category} allowed by a human-authored override — permitted, never invisible`, "override");
+    }
+    deny(verdict.category, verdict.reason, { command: command.slice(0, 200) });
+  }
+
+  if (p.tool_name === "Read") {
+    const path = p.tool_input?.file_path || "";
+    if (isSecretPath(path, overrides)) {
+      deny("secret-read", `Read(${path}) targets a secret file. Secrets must not enter the conversation; if this is a false positive, add the path to ${LOCAL}/safety-overrides.json (allow_secret_paths).`, { path });
+    }
+    defer("read target is not a secret path — inspected and permitted", "read-clean");
+  }
+
+  // Write | Edit | MultiEdit — only the self-protect rule; substrates stay sandbox-guard's job.
+  const overridesAbs = resolve(safetyOverrides(cwd));
+  const hit = extractPaths(p.tool_input).find((raw) => resolve(cwd, raw) === overridesAbs);
+  if (hit) {
+    deny("self-protect", `The safety-overrides file is human-authored only — the session must never widen (or remove) its own safety envelope. Ask the PO to edit ${LOCAL}/safety-overrides.json.`, { path: hit });
+  }
+  defer("write does not touch the safety envelope — inspected and permitted", "write-clean");
+  });
+}
+
+if (isMain(import.meta.url)) {
+  main();
+}

package/hooks/sandbox-guard.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+// Sandbox guard — PreToolUse hook (design spec v1.1 §4.5/Blueprint E, PA3 countermeasure).
+//
+// Blocks Edit/Write/MultiEdit calls that touch a file outside the active scope's
+// `allowed_file_substrate` (+ declared `shared_substrate`). Turns "generator only edits its
+// own scope" from prose into a precondition the model cannot talk past — the same pattern as
+// hooks/gate-l2.mjs for GATE L2.
+//
+// Design (deliberately conservative, mirrors gate-l2.mjs):
+//   • Fail-OPEN whenever there is nothing to enforce: no active-scope pointer (not running
+//     inside a scoped harness round), pointer names a scope contract that doesn't exist or is
+//     unparsable, or the tool call carries no resolvable file path. A guard that breaks
+//     legitimate non-harness edits would just get disabled.
+//   • Fail-CLOSED the moment an active scope IS declared and the target path matches none of
+//     its globs — deny, naming the substrate so the model can self-correct.
+//   • Run-trace carve-out — writes under the ACTIVE feature's LOCAL gitignored root
+//     (`.shapeup/<slug>/`) are always allowed: that root is harness bookkeeping the doer
+//     is REQUIRED to write (task-executor P3 status/AC ticks + tasks/_index.md, run-state,
+//     execution logs, the P3.7 discovery ledger). Substrate globs whitelist product code and
+//     never list the run-trace, so without the carve-out every scoped round strands its own
+//     board (island-escape shipped 16/20 task files stale this way). Deliberately narrow:
+//     only the active slug's root — `.shapeup/active-scope` (this guard's own pointer)
+//     and other features' roots remain subject to the substrate whitelist.
+//   • Every denial is also appended to the metrics pathology log (telemetry, not just defense).
+//
+// Contract: PreToolUse stdin JSON { tool_name, tool_input:{file_path | edits[].file_path}, cwd }.
+// Deny via { hookSpecificOutput: { hookEventName, permissionDecision:"deny", permissionDecisionReason } }.
+
+import { readFileSync, existsSync, appendFileSync, mkdirSync } from "node:fs";
+import { resolve, join, relative, dirname, sep } from "node:path";
+import { isMain } from "../skills/tech-lead/scripts/lib/is-main.mjs";
+import { LOCAL, activeScope, scopeContract, metricsShard } from "../skills/tech-lead/scripts/lib/paths.mjs";
+import { readContract, SCOPE_CONTRACT } from "../skills/tech-lead/scripts/lib/contract-md.mjs";
+import { runHook, readStdin, settle } from "./lib/decision.mjs";
+
+// --- tiny glob matcher: supports *, **, ? — enough for substrate globs, zero dependencies ---
+export function globToRegExp(glob) {
+  let re = "";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === "*") {
+      if (glob[i + 1] === "*") {
+        re += ".*";
+        i++;
+        if (glob[i + 1] === "/") i++;
+      } else {
+        re += "[^/]*";
+      }
+    } else if (c === "?") {
+      re += "[^/]";
+    } else if (".+^${}()|[]\\".includes(c)) {
+      re += "\\" + c;
+    } else {
+      re += c;
+    }
+  }
+  return new RegExp(`^${re}$`);
+}
+
+export function matchesAny(relPath, globs) {
+  return (globs || []).some((g) => globToRegExp(g).test(relPath));
+}
+
+function readJSON(p) {
+  try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; }
+}
+
+function extractPaths(toolInput) {
+  const paths = [];
+  if (toolInput?.file_path) paths.push(toolInput.file_path);
+  if (Array.isArray(toolInput?.edits)) {
+    for (const e of toolInput.edits) if (e?.file_path) paths.push(e.file_path);
+  }
+  return paths;
+}
+
+export function logPathology(metricsPath, event) {
+  try {
+    mkdirSync(dirname(metricsPath), { recursive: true });
+    appendFileSync(metricsPath, JSON.stringify(event) + "\n");
+  } catch { /* telemetry is best-effort; never block on a logging failure */ }
+}
+
+async function main() {
+  await runHook("sandbox-guard", async () => {
+  const raw = await readStdin();
+  let p;
+  /** Fail-open, with the reason on the record (hooks/lib/decision.mjs). */
+  const defer = (reason, rule) => settle({
+    verdict: "allow", event: "PreToolUse", tool: p?.tool_name ?? null, cwd: p?.cwd, reason, rule,
+  });
+  try { p = JSON.parse(raw || "{}"); }
+  catch (e) { settle({ verdict: "error", event: "PreToolUse", reason: `unparseable payload: ${e.message}` }); }
+
+  if (!["Edit", "Write", "MultiEdit"].includes(p.tool_name)) {
+    defer(`${p.tool_name ?? "no tool_name"} is not a write tool — out of scope`);
+  }
+
+  const cwd = p.cwd || process.cwd();
+  const activeScopePath = activeScope(cwd);
+  // no harness round in progress → don't enforce
+  if (!existsSync(activeScopePath)) defer("no active-scope pointer — no harness round in progress", "no-round");
+
+  const active = readJSON(activeScopePath);
+  if (!active?.slug || !active?.scope_id) defer("active-scope pointer is unreadable or incomplete", "bad-pointer");
+
+  // Markdown first, legacy JSON second (ADR-0001) — a project mid-migration must stay sandboxed.
+  let found = null;
+  try { found = readContract(scopeContract(cwd, active.slug, active.scope_id), SCOPE_CONTRACT); }
+  catch (e) { defer(`scope contract is unparseable (${e.message})`, "bad-contract"); }
+  // pointer stale / contract not committed yet → don't break the run
+  if (!found) defer(`no contract for ${active.scope_id} — pointer stale or not committed yet`, "no-contract");
+  const contract = found.contract;
+  if (!contract) defer("scope contract is unparseable", "bad-contract");
+
+  const allowed = [...(contract.allowed_file_substrate || []), ...(contract.shared_substrate || [])];
+  // no whitelist declared → nothing to enforce
+  if (allowed.length === 0) defer(`scope ${active.scope_id} declares no write whitelist`, "no-whitelist");
+
+  const targetPaths = extractPaths(p.tool_input);
+  if (targetPaths.length === 0) defer("no writable path in the tool input", "no-target");
+
+  const metricsPath = metricsShard(cwd);
+  // Run-trace carve-out (see header): the active feature's LOCAL root only. The prefix ends
+  // with a separator so a sibling `<local>/<slug>-other/` can't ride along, and the active-scope
+  // pointer sits outside it by construction.
+  const runTracePrefix = join(LOCAL, active.slug) + sep;
+  const violations = [];
+  for (const raw of targetPaths) {
+    const abs = resolve(cwd, raw);
+    const rel = relative(cwd, abs);
+    if (rel.startsWith(runTracePrefix)) continue;
+    if (!matchesAny(rel, allowed)) violations.push(rel);
+  }
+
+  // Inside the substrate — the "inspected and permitted" row. Previously byte-identical to
+  // "this hook never ran", which is how 26 enforcement points sat inert behind 610 green checks.
+  if (violations.length === 0) {
+    defer(`${targetPaths.length} path(s) inside scope ${active.scope_id} substrate — permitted`, "in-substrate");
+  }
+
+  logPathology(metricsPath, {
+    schema_version: 1,
+    at: new Date().toISOString(),
+    kind: "pathology",
+    pathology: "PA3",
+    scope_id: active.scope_id,
+    slug: active.slug,
+    blocked_paths: violations,
+  });
+
+  return {
+    verdict: "deny", event: "PreToolUse", tool: p.tool_name, subject: active.scope_id, cwd,
+    rule: "outside-substrate",
+    reason: `${violations.length} write(s) outside the scope substrate: ${violations.join(", ")}`,
+    payload: {
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason:
+          `Sandbox guard (PA3) — scope "${active.scope_id}" may only write ${JSON.stringify(allowed)}. ` +
+          `Blocked: ${violations.join(", ")}. If this write legitimately crosses scopes, add the path to ` +
+          `the contract's shared_substrate (via ba --remap) rather than editing outside the substrate.`,
+      },
+    },
+  };
+  });
+}
+
+if (isMain(import.meta.url)) {
+  main();
+}