@juzser/blacksmith 0.1.0

package/factory/orchestrator/dist/policy.js

@@ -0,0 +1,1308 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import picomatch from 'picomatch';
+import { parse as parseYaml } from 'yaml';
+import { SmithError } from './errors.js';
+import { runGit } from './git.js';
+import { GUARDRAILS_POLICY_PATH, REPO_ROOT } from './paths.js';
+/**
+ * Blacksmith's guard hook, moved off bash-and-regex-in-a-shell-script and
+ * onto data (factory/policies/guardrails.yml) plus tested TypeScript
+ * (here). `.claude/hooks/guard.sh` used to hold both: the rule content
+ * (branch names, allowed roots, the message an agent sees) tangled together
+ * with the matcher that decided whether a given command tripped it, and
+ * neither half had a test. This module is the matcher half — every function
+ * below is a direct, behaviour-preserving port of one piece of guard.sh, and
+ * each one is exercised in test/policy.test.ts. Two things bash could not do
+ * well are fixed in the port, not added to it: path normalization for the
+ * `rm -rf` rule uses `path.resolve`/`path.relative` instead of shelling out
+ * to `realpath -m` (which does not exist on every platform this runs on),
+ * and that same normalization is `path.sep`-aware rather than bash's
+ * `/`-only `case` glob — see `normalizeRemovalPath`.
+ *
+ * `smith policy check` and `smith policy hook` (cli.ts) are the two CLI
+ * callers, both routed through `hookDecision.ts`; `.claude/hooks/guard.sh`
+ * execs `dist/policyHook.js`, an entry point over that same decision whose
+ * import graph is only what deciding needs.
+ */
+export class PolicyError extends SmithError {
+}
+/**
+ * The six rules guard.sh has always enforced, plus the three the judge
+ * sandbox adds. `parseGuardrailPolicy` rejects a guardrails.yml missing any
+ * of these outright, rather than silently loading a policy with fewer rules
+ * than the file that shipped it — a guard-hook rule that fails to load is
+ * not "off by default", it is a hole. The judge rules are required on the
+ * same terms even though they fire only under a lease: a policy file that
+ * cannot name them is a policy file that would run judges unguarded and
+ * report nothing wrong. `role-write-scope` is required for the mirror of
+ * that reason: it is the mechanism that keeps a tester out of the code it is
+ * grading, and a policy that cannot name it either blocks the tester
+ * entirely or lets it mark its own homework.
+ */
+const REQUIRED_RULE_IDS = [
+    'push-to-protected',
+    'force-push',
+    'merge-into-protected',
+    'deploy-command',
+    'history-rewrite-on-protected',
+    'unbounded-rm',
+    'judge-network',
+    'judge-write',
+    'judge-sandbox-escape',
+    'role-write-scope',
+];
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((v) => typeof v === 'string');
+}
+function requireStringArray(value, key) {
+    if (!isStringArray(value)) {
+        throw new PolicyError('policy.invalid-document', `guardrails.yml is missing ${key} (a string list).`, { key });
+    }
+    return value;
+}
+/**
+ * `deploy_commands` and `judge_sandbox.network_subcommands` are the same
+ * shape — a command word plus the subcommands that make it matter — so they
+ * parse through one function rather than two copies that drift.
+ */
+function parseCommandSpecs(raw, key) {
+    if (!Array.isArray(raw)) {
+        throw new PolicyError('policy.invalid-document', `guardrails.yml is missing ${key} (a list).`, {
+            key,
+        });
+    }
+    return raw.map((entry, index) => {
+        const e = entry;
+        if (typeof e.command !== 'string' || !isStringArray(e.subcommands)) {
+            throw new PolicyError('policy.invalid-document', `guardrails.yml ${key}[${index}] needs a string "command" and a string-list "subcommands".`, { key, index });
+        }
+        return { command: e.command, subcommands: e.subcommands };
+    });
+}
+/** Fold one `rules:` list into the shared id-keyed map. Used for the top-level list and the judge_sandbox one. */
+function collectRules(raw, into, key) {
+    if (!Array.isArray(raw)) {
+        throw new PolicyError('policy.invalid-document', `guardrails.yml is missing ${key} (a list).`, {
+            key,
+        });
+    }
+    for (const entry of raw) {
+        const r = entry;
+        if (typeof r.id !== 'string' ||
+            typeof r.severity !== 'string' ||
+            typeof r.reason !== 'string') {
+            throw new PolicyError('policy.invalid-document', `guardrails.yml has a rule in ${key} missing a string id/severity/reason.`, { key, rule: entry });
+        }
+        into.set(r.id, {
+            id: r.id,
+            severity: r.severity,
+            reason: r.reason,
+            reasonOnCurrentBranch: typeof r.reason_on_current_branch === 'string' ? r.reason_on_current_branch : null,
+        });
+    }
+}
+/**
+ * Parse guardrails.yml. Throws `PolicyError` on anything short of the full
+ * shape — a guard-hook policy file with a typo'd key must fail loudly, not
+ * load as a policy with an empty `rules` map that denies nothing.
+ */
+/**
+ * `role_write_scopes.scopes` — one entry per role that writes under a lease.
+ *
+ * A role declared here must not also be a judge role: the two rule sets are
+ * selected by role, so an overlap is a question with no answer, and guessing
+ * one silently is exactly the kind of quiet mis-enforcement this whole
+ * module exists to end.
+ */
+function parseRoleWriteScopes(raw, judgeRoles) {
+    if (!Array.isArray(raw)) {
+        throw new PolicyError('policy.invalid-document', 'guardrails.yml is missing role_write_scopes.scopes (a list of role scopes).');
+    }
+    const scopes = [];
+    for (const [index, entry] of raw.entries()) {
+        const key = `role_write_scopes.scopes[${index}]`;
+        if (typeof entry !== 'object' || entry === null) {
+            throw new PolicyError('policy.invalid-document', `guardrails.yml ${key} is not a mapping.`);
+        }
+        const item = entry;
+        const role = item.role;
+        if (typeof role !== 'string' || role === '') {
+            throw new PolicyError('policy.invalid-document', `guardrails.yml ${key} is missing role.`);
+        }
+        if (judgeRoles.includes(role)) {
+            throw new PolicyError('policy.invalid-document', `guardrails.yml declares "${role}" as both a judge role and a write-scoped role; a role gets one rule set, not two.`, { role });
+        }
+        if (scopes.some((s) => s.role === role)) {
+            throw new PolicyError('policy.invalid-document', `guardrails.yml declares role "${role}" twice under role_write_scopes.scopes.`, { role });
+        }
+        const writeGlobs = requireStringArray(item.write_globs, `${key}.write_globs`);
+        if (writeGlobs.length === 0) {
+            throw new PolicyError('policy.invalid-document', `guardrails.yml ${key}.write_globs is empty; a scope that permits nothing blocks the role instead of bounding it.`, { role });
+        }
+        scopes.push({
+            role,
+            writeGlobs,
+            refusedCommands: requireStringArray(item.refused_commands, `${key}.refused_commands`),
+            refusedGitSubcommands: requireStringArray(item.refused_git_subcommands, `${key}.refused_git_subcommands`),
+        });
+    }
+    return scopes;
+}
+/** What `catch_up_remotes` means when guardrails.yml does not say — the strict reading. */
+const DEFAULT_CATCH_UP_REMOTES = ['origin'];
+export function parseGuardrailPolicy(yamlText) {
+    const doc = (parseYaml(yamlText) ?? {});
+    const names = doc.protected_branches?.names;
+    if (!isStringArray(names)) {
+        throw new PolicyError('policy.invalid-document', 'guardrails.yml is missing protected_branches.names (a string list).');
+    }
+    const patterns = doc.protected_branches?.patterns;
+    if (!isStringArray(patterns)) {
+        throw new PolicyError('policy.invalid-document', 'guardrails.yml is missing protected_branches.patterns (a string list).');
+    }
+    // The one optional key in this file. Every other field throws when it is
+    // missing, because a policy that silently loses a rule is worse than one
+    // that refuses to load — but this key only ever *narrows* rule 3, and a
+    // guardrails.yml written before it existed should keep working. Absent
+    // means the strict reading, not the permissive one.
+    const catchUpRemotes = doc.catch_up_remotes ?? DEFAULT_CATCH_UP_REMOTES;
+    if (!isStringArray(catchUpRemotes)) {
+        throw new PolicyError('policy.invalid-document', 'guardrails.yml has a catch_up_remotes that is not a string list.');
+    }
+    const allowedRoots = doc.destructive_removal?.allowed_roots;
+    if (!isStringArray(allowedRoots)) {
+        throw new PolicyError('policy.invalid-document', 'guardrails.yml is missing destructive_removal.allowed_roots (a string list).');
+    }
+    const deployCommands = parseCommandSpecs(doc.deploy_commands, 'deploy_commands');
+    const rawSandbox = doc.judge_sandbox;
+    if (rawSandbox === undefined || rawSandbox === null) {
+        throw new PolicyError('policy.invalid-document', 'guardrails.yml is missing judge_sandbox (the judge sandbox rule data).');
+    }
+    const judgeSandbox = {
+        roles: requireStringArray(rawSandbox.roles, 'judge_sandbox.roles'),
+        writeRoots: requireStringArray(rawSandbox.write_roots, 'judge_sandbox.write_roots'),
+        networkCommands: requireStringArray(rawSandbox.network_commands, 'judge_sandbox.network_commands'),
+        networkSubcommands: parseCommandSpecs(rawSandbox.network_subcommands, 'judge_sandbox.network_subcommands'),
+        targetWriteCommands: requireStringArray(rawSandbox.target_write_commands, 'judge_sandbox.target_write_commands'),
+        refusedWriteCommands: requireStringArray(rawSandbox.refused_write_commands, 'judge_sandbox.refused_write_commands'),
+        gitWriteSubcommands: requireStringArray(rawSandbox.git_write_subcommands, 'judge_sandbox.git_write_subcommands'),
+    };
+    const rawScopes = doc.role_write_scopes;
+    if (rawScopes === undefined || rawScopes === null) {
+        throw new PolicyError('policy.invalid-document', 'guardrails.yml is missing role_write_scopes (the per-role write bounds).');
+    }
+    const roleWriteScopes = parseRoleWriteScopes(rawScopes.scopes, judgeSandbox.roles);
+    const rules = new Map();
+    collectRules(doc.rules, rules, 'rules');
+    collectRules(rawSandbox.rules, rules, 'judge_sandbox.rules');
+    collectRules(rawScopes.rules, rules, 'role_write_scopes.rules');
+    for (const requiredId of REQUIRED_RULE_IDS) {
+        if (!rules.has(requiredId)) {
+            throw new PolicyError('policy.invalid-document', `guardrails.yml is missing required rule "${requiredId}".`, { rule: requiredId });
+        }
+    }
+    return {
+        protectedBranchNames: names,
+        protectedBranchPatterns: patterns,
+        catchUpRemotes,
+        allowedRemovalRoots: allowedRoots,
+        deployCommands,
+        judgeSandbox,
+        roleWriteScopes,
+        rules,
+    };
+}
+/**
+ * Every role `smith sandbox open --role` accepts — the judge roles plus the
+ * write-scoped ones. A role outside this list is a typo or an attempt to
+ * pick a rule set by naming one that does not exist; sandbox.ts refuses it
+ * at lease time so the mistake surfaces there rather than as silently
+ * stricter enforcement three commands later.
+ */
+export function sandboxRoles(policy = loadGuardrailPolicy()) {
+    return [...policy.judgeSandbox.roles, ...policy.roleWriteScopes.map((s) => s.role)];
+}
+export function loadGuardrailPolicy(filePath = GUARDRAILS_POLICY_PATH) {
+    return parseGuardrailPolicy(readFileSync(filePath, 'utf8'));
+}
+// ---------------------------------------------------------------------------
+// bash-equivalent matchers — one function per guard.sh helper, same name in
+// spirit, same behaviour. See guard.sh's own comments for the trade-offs
+// repeated here; they are not re-argued twice.
+// ---------------------------------------------------------------------------
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Chain-aware subcommand detector, ported from guard.sh's `is_git_subcmd`.
+ * Global flags (including value-taking ones like `-C <path>`) sit between
+ * `git` and the subcommand, so this does not try to match position — it
+ * requires `git` and the subcommand word to appear in the same chain segment
+ * (no `;`, `&`, `|` between them). This is intentionally loose (same
+ * trade-off as the `rm -rf` detector below): it can over-match a subcommand
+ * word appearing elsewhere in the same segment (e.g. a commit message), but
+ * it never under-matches on global-flag placement, which is the
+ * security-relevant direction for a deny gate.
+ *
+ * The one place it is deliberately tight is the hyphen. `\b` treats `-` as a
+ * boundary, so a bare `\bmerge\b` matches `git merge-base` — a read-only
+ * plumbing command that cannot merge anything, and one this repo's own tooling
+ * runs constantly. Every hyphenated `<subcommand>-*` in git is a separate
+ * command from `<subcommand>`, so requiring the word to be neither preceded
+ * nor followed by a hyphen costs no coverage on `push`, `merge` or `rebase`
+ * and removes a class of false deny that teaches operators to route around
+ * the gate.
+ */
+function isGitSubcommand(command, subcommand) {
+    return new RegExp(`\\bgit\\b[^;&|]*${bareWord(subcommand)}`, 'i').test(command);
+}
+/** `subcommand` as a whole word, excluding a hyphenated neighbour — see `isGitSubcommand`. */
+function bareWord(word) {
+    return `(?<!-)\\b${word}\\b(?!-)`;
+}
+/**
+ * EVERY chain segment containing `git ... <word>`, used to inspect the
+ * destination ref precisely instead of loose substring matching. Ported from
+ * guard.sh's `git_segment_for`, with the same deliberate behaviour change
+ * `checkUnboundedRm` makes below: bash returned the *first* matching segment
+ * and stopped, so `git push origin feat/x; git push origin main` was read as
+ * a push to `feat/x`, allowed, and the second half never looked at. A chain
+ * is one tool call and every command in it runs, so every command in it gets
+ * inspected.
+ */
+function gitSegmentsFor(command, word) {
+    const re = new RegExp(`\\bgit\\b.*${bareWord(word)}`, 'i');
+    return splitChainSegments(command).filter((s) => re.test(s));
+}
+/**
+ * The refs a `git push` names: every token after the `push` word that is not a
+ * flag, quotes stripped, so `isProtectedRef` can read a destination precisely
+ * rather than by a substring match that would false-block `git push origin
+ * fix-main-config`.
+ *
+ * Replaces guard.sh's `last_token`, which this file ported and which read the
+ * destination as the segment's *last* whitespace-separated token. That is the
+ * ref only when the segment ends at the push, and a segment ends at the push
+ * only when nothing follows it — no redirect, no comment, no closing `)` of a
+ * substitution. `git push origin main > /dev/null` handed the rule
+ * `/dev/null`, and the most ordinary way to write a quiet push turned the gate
+ * off. Reading every operand instead needs no guess about which one is the
+ * destination: if any of them is a protected ref, the push is refused.
+ *
+ * Flags are dropped rather than paired with their values, so a flag that takes
+ * one (`git push --repo main ...`) leaves that value in the list. That
+ * over-refuses on a value spelled exactly `main`, which is the direction this
+ * file errs in everywhere else.
+ */
+function pushOperands(segment) {
+    return gitOperands(segment, 'push');
+}
+/**
+ * The same read, for any subcommand: every token after the subcommand word
+ * that is not a flag, quotes stripped. `pushOperands` is this function under
+ * the name rule 1 reads it by, and rule 3 reads a catch-up's source with it.
+ * One parser, because a second copy of a rule's reading is a copy that drifts
+ * out of step with the first.
+ */
+function gitOperands(segment, word) {
+    return gitTokens(segment, word)
+        .filter((t) => !t.startsWith('-'))
+        .map((t) => t.replace(/^["']/, '').replace(/["']$/, ''));
+}
+/**
+ * Every token after the subcommand word, flags included and quotes intact.
+ * Rule 3's exception needs to see the flags, not only the operands: a flag it
+ * does not recognise is a command doing something the exception has not
+ * proved.
+ */
+function gitTokens(segment, word) {
+    const match = new RegExp(`${bareWord(word)}(.*)$`, 'i').exec(segment);
+    if (!match)
+        return [];
+    return (match[1] ?? '')
+        .trim()
+        .split(/\s+/)
+        .filter((t) => t !== '');
+}
+/**
+ * Ported from guard.sh's `is_main_or_master_ref` `case` statement, but
+ * data-driven off `policy.protectedBranchNames` instead of the two names
+ * bash had hardcoded — same behaviour today (names is `[main, master]`),
+ * but a rename doesn't need a second code change to take effect.
+ */
+function isProtectedRef(ref, policy) {
+    return policy.protectedBranchNames.some((name) => ref === name || ref.endsWith(`:${name}`) || ref.endsWith(`:refs/heads/${name}`));
+}
+function isProtectedBranchName(branch, policy) {
+    return policy.protectedBranchNames.includes(branch);
+}
+/**
+ * Rule 5's protected-branch test: main/master by name, or a shared
+ * `smith/<epic>/integration` branch by pattern (task branches
+ * `smith/<epic>/<task-id>` are exempt — rebase/amend there is the sanctioned
+ * pre-merge-queue flow, worktree.yml). Ported from guard.sh's inline
+ * `^smith/[^/]+/integration$|^(main|master)$`, generalized to whatever
+ * `protected_branches.patterns` says instead of one hardcoded shape.
+ */
+function isProtectedForHistoryRewrite(branch, policy) {
+    if (isProtectedBranchName(branch, policy))
+        return true;
+    return policy.protectedBranchPatterns.some((pattern) => picomatch(pattern)(branch));
+}
+/**
+ * `replaceAll`, not `replace`: a template author writing `{branch}` twice
+ * should get the branch twice, not the branch and then a literal `{branch}`
+ * in the operator's face. Every message in guardrails.yml used it once, so
+ * this changes no text today and stops the second use being a trap.
+ */
+function renderBranch(template, branch) {
+    return template.replaceAll('{branch}', branch);
+}
+/**
+ * Tools whose `command` string this policy inspects. Only `Bash` is in scope
+ * today, but that is a fact about which tools *have* a shell command to
+ * inspect, not a hardcoded branch in `evaluateCommand` — a second Bash-like
+ * tool added later is a one-line change here, not new control flow.
+ */
+const INSPECTED_TOOLS = ['Bash'];
+/**
+ * Tools whose `file_path` this policy inspects — the write path that does
+ * not go through a shell. Nothing here has a command to match, so only the
+ * lease rules can fire on them; the base six are all about shell commands
+ * and no-op on an empty one.
+ */
+const INSPECTED_FILE_TOOLS = ['Write', 'Edit', 'MultiEdit', 'NotebookEdit'];
+function requireRule(policy, id) {
+    const rule = policy.rules.get(id);
+    if (!rule) {
+        // Unreachable once a policy has passed parseGuardrailPolicy (which
+        // requires every id in REQUIRED_RULE_IDS) — this is a defensive
+        // safety-net, not a real code path.
+        throw new PolicyError('policy.missing-rule', `guardrails.yml has no rule "${id}".`, {
+            rule: id,
+        });
+    }
+    return rule;
+}
+function violation(rule, reason = rule.reason) {
+    return { ruleId: rule.id, severity: rule.severity, reason };
+}
+/**
+ * Blank the payload of git's message flags before the six rules below scan a
+ * command for refs and command words.
+ *
+ * A commit or merge message is git's own free-text field: its words are prose,
+ * never a ref and never a command. Scanning them anyway is how a commit whose
+ * message *described a rule* came to be refused for breaking it — five of the
+ * six rules could be tripped by a sentence alone, with no push, merge, deploy
+ * or removal anywhere in the command. That is the false deny this file already
+ * names twice as the one worth engineering against (see `isGitSubcommand`'s
+ * hyphen carve-out and `stripQuotedSpans`): the kind that teaches an agent to
+ * route around the gate rather than trust it.
+ *
+ * Deliberately narrower than `stripQuotedSpans`, which blanks every quoted
+ * span. Only a message payload goes, so a quoted *ref* is still read: `git
+ * push origin "main"` is still a push to main and `wrangler "deploy"` is still
+ * a deploy. Hiding a real target in here would mean passing it where git reads
+ * prose, which costs the target its meaning — so the blanking buys no way past
+ * any rule.
+ *
+ * That last sentence holds only for a payload the shell hands over as it
+ * stands, which is why `shellExpandsPayload` below gets to veto the blanking.
+ *
+ * Narrow in four more ways, each one a place where `-m` is not prose:
+ *
+ * - **Only where git spends `-m` on a message**, named subcommand by
+ *   subcommand. `git rebase -m <upstream>` spells `--merge` and `git revert -m
+ *   <parent-number>` picks a mainline, so their argument is a ref or a number
+ *   that later scans must still see; `mkdir -m 755 <dir>` and `gh pr merge -m
+ *   <branch>` are not git at all. A subcommand missing from this list is only
+ *   scanned as it is today — the failure is a false deny, which is the
+ *   direction this file errs in on purpose.
+ * - **Segment by segment**, so `git commit -m "…" && git push origin main`
+ *   blanks the message and still reads the push.
+ * - **Only where the shell hands the payload over untouched** — see
+ *   `shellExpandsPayload`. A payload the shell expands first is not the
+ *   message, it is a command that has already run.
+ *
+ * It is deliberately *not* narrow about how `-m` was spelled. Git takes the
+ * message from `-m x`, `-m=x`, `-mx` and `-amx` alike, so a scanner that only
+ * knows the spaced form calls the other three prose-that-wasn't-exempted and
+ * denies a commit for the words in its message. `git commit -am "…"` is the
+ * common one, and it was denied. The letters before the `m` are matched as a
+ * cluster and the `m` must end it, which is git's own rule: in `-am` the value
+ * follows, in `-ma` the value *is* `a`.
+ *
+ * The double-quoted form counts an escaped quote as part of the payload, since
+ * a shell does. Stopping at the `\"` in `-m "he said \" then ran it"` left the
+ * tail exposed and the commit denied for it. Single quotes are left exact:
+ * inside them a backslash is a backslash, so `'[^']*'` is already right and
+ * teaching it about escapes would be teaching it a falsehood.
+ *
+ * The value is blanked rather than deleted, so token boundaries survive for
+ * the scans that read the last token of a segment.
+ */
+const MESSAGE_FLAG_RE = /(^|\s)(-[a-zA-Z]*m|--message)(=|\s+|)("(?:\\.|[^"\\])*"|'[^']*'|\S+)/g;
+/** The git subcommands whose `-m`/`--message` takes free text, and nothing else. */
+const MESSAGE_SUBCOMMANDS = ['commit', 'merge', 'tag', 'stash', 'notes'];
+/**
+ * Does the payload open and close with this quote character?
+ *
+ * First and last character only. That is enough for the payloads
+ * `MESSAGE_FLAG_RE` hands over and no more: it cannot tell a true pair from
+ * one whose closing quote is a backslash-escaped literal, and it does not try.
+ * Being wrong there costs a false deny, never a false allow, which is the
+ * direction this file errs in everywhere else too.
+ */
+function isQuotedWith(payload, quote) {
+    return payload.length >= 2 && payload.startsWith(quote) && payload.endsWith(quote);
+}
+/**
+ * Every opener that forks a command and substitutes a path to its stream. The
+ * first two are bash's and zsh's alike; `=(` is zsh's own, and zsh is the shell
+ * behind the agent's Bash tool, so it is the one most likely to be typed here.
+ */
+const PROCESS_SUBSTITUTIONS = ['<(', '>(', '=('];
+/**
+ * True when the shell runs part of this payload *before* handing the rest
+ * over — the one case where blanking a payload hides a command rather than
+ * prose.
+ *
+ * A message payload holding a command substitution does not *describe* that
+ * command, it runs it: bash expands `$( )` inside double quotes before git is
+ * executed at all, so the substituted command happens and its *output* is what
+ * finally becomes the message. Blanking such a payload deleted the only real
+ * command on the line and left the rules reading the part that was genuinely
+ * prose. Backticks are the same expansion in an older spelling, and an
+ * unquoted payload is expanded too.
+ *
+ * Process substitution is a third spelling and runs a command just as eagerly.
+ * `git commit -m <(wrangler deploy)` forks the deploy, hands git the path
+ * `/dev/fd/63`, and the deploy has already happened by the time git has a
+ * message to read. What was blanked there is one whitespace-delimited token —
+ * `<(wrangler`, the binary — leaving ` deploy)` behind, so rule 4 went looking
+ * for a binary that had been deleted out from under it. Rules 1, 2, 3 and 5
+ * came through the same deletion intact for the unremarkable reason that what
+ * each of them keys on — a ref, a `--force` flag, a `merge`/`rebase`
+ * subcommand — happened not to be the token that got eaten. That is a fact
+ * about this payload's word order, not a property any of them hold.
+ *
+ * All three openers are listed in `PROCESS_SUBSTITUTIONS`, because which ones
+ * exist is a fact about the shell that will run the command, not about bash.
+ * The agent's shell here is zsh, which has bash's `<( )` and `>( )` and one
+ * more of its own: `=(cmd)` runs cmd, writes its output to a temp file and
+ * substitutes *that* path. It is the spelling most likely to be reached on
+ * this machine and the one a bash-only reading of the problem misses.
+ *
+ * Quoting decides both kinds, and not along the same line, so the two are
+ * asked separately. Single quotes are every shell's own: no expansion of any
+ * kind happens inside them, so the payload is exactly the text it looks like.
+ * Double quotes are narrower — a command substitution still happens inside
+ * them, a process substitution does not — so `"$( )"` is a command while
+ * `"<( )"`, `">( )"` and `"=( )"` are the prose they appear to be. Asking
+ * "will the shell run this" with the shell's own rule is what keeps the answer
+ * from being a guess layered on top of it.
+ *
+ * Two deliberate imprecisions, both erring toward reading more rather than
+ * less, which is the direction the six rules are safe in:
+ *
+ * - `${VAR}` is left alone. A parameter expansion substitutes a value and runs
+ *   no command, so it is prose with a hole in it.
+ * - An escaped `\$(` inside double quotes is a literal `$(` to the shell, and
+ *   is read here as live anyway. The cost is a false deny on a message that
+ *   both escapes a substitution and spells out a guarded command, and the fix
+ *   for it is the single quotes that were already the clearer way to write it.
+ *
+ * Reading a payload is not refusing it. Whatever the expansion contains is
+ * judged by the same six rules as any other command, so a message that
+ * substitutes `date` stays allowed: `date` is nobody's guarded command.
+ */
+function shellExpandsPayload(payload) {
+    // Single-quoted: literal to every shell, so nothing in it can run.
+    if (isQuotedWith(payload, "'"))
+        return false;
+    // Command substitution, which double quotes do not suppress.
+    if (payload.includes('$(') || payload.includes('`'))
+        return true;
+    // Process substitution, which they do.
+    if (isQuotedWith(payload, '"'))
+        return false;
+    return PROCESS_SUBSTITUTIONS.some((opener) => payload.includes(opener));
+}
+function stripMessageFlagValues(command) {
+    // Split keeping the separators, so the segments can be rejoined untouched.
+    return command
+        .split(/([;&|])/)
+        .map((segment) => MESSAGE_SUBCOMMANDS.some((sub) => isGitSubcommand(segment, sub))
+        ? segment.replace(MESSAGE_FLAG_RE, (match, lead, flag, sep, payload) => shellExpandsPayload(payload) ? match : `${lead}${flag}${sep}""`)
+        : segment)
+        .join('');
+}
+/**
+ * `smith policy check --command '<cmd>'` is how anyone asks what these rules
+ * say about a command *without running it*. `guardrails.md` leads with it, and
+ * the six rules refused it: the hook scans the whole Bash string, so asking
+ * about a force push read as a force push and asking about a protected push
+ * read as a protected push. Every command worth asking about was a command you
+ * could not ask about. A gate whose own dry run is unreachable does not teach
+ * caution, it teaches an agent to find out by doing.
+ *
+ * The exemption rests on one fact and no other: `policy check` parses,
+ * evaluates and prints. It has no path that executes what it was handed — see
+ * its handler in cli.ts. That is a narrower claim than "quoted text is data",
+ * and it is the reason this cannot be widened to any other flag or binary.
+ *
+ * Narrow in four ways, each closing a way the exemption could be borrowed:
+ *
+ * - **Quoted payloads only, and only the quoting that leaves them inert.**
+ *   `--command "$(…)"` is expanded by the shell before this binary is reached,
+ *   so the command in it really runs and the question is not hypothetical.
+ *   That is a fact about the payload, not about which quote surrounds it:
+ *   double quotes stop a *process* substitution and not a *command* one, so
+ *   the same predicate that rules on a message payload rules here —
+ *   `shellExpandsPayload`. Keying on the single quote instead was a stand-in
+ *   for that predicate, and it refused `--command "<(…)"`, which runs nothing:
+ *   an over-refusal on the one command whose whole job is answering without
+ *   running.
+ * - **Segment by segment**, so a real command chained after the question is
+ *   read as itself. Whatever shares the segment is read too: the payload is
+ *   blanked, not the segment.
+ * - **On the `policy check` subcommand pair, not on a binary name.** The
+ *   caller's spelling is `smith`, a package-manager script, or the built entry
+ *   point directly, and a public repo cannot assume which — or that an
+ *   installation has not aliased it. Keying on the pair also keeps `--command`
+ *   from meaning anything here when some other tool spells it.
+ * - **An unquoted payload is left alone**, since where it ends is the caller's
+ *   shell's business rather than this scanner's. Over-refusing is the
+ *   direction this file errs in on purpose, and the fix is the quoting the
+ *   docs already show.
+ */
+const POLICY_CHECK_RE = /(^|\s)policy\s+check(\s|$)/;
+/** Only `--command` carries a command; `--file` carries a path and `--sandbox` a role name. */
+const POLICY_CHECK_PAYLOAD_RE = /(^|\s)(--command)(=|\s+)('[^']*'|"(?:\\.|[^"\\])*")/g;
+function stripPolicyCheckPayloads(command) {
+    // Split keeping the separators, so the segments can be rejoined untouched.
+    return command
+        .split(/([;&|])/)
+        .map((segment) => POLICY_CHECK_RE.test(segment)
+        ? segment.replace(POLICY_CHECK_PAYLOAD_RE, (match, lead, flag, sep, payload) => shellExpandsPayload(payload) ? match : `${lead}${flag}${sep}''`)
+        : segment)
+        .join('');
+}
+/**
+ * `git stash push` writes to the stash. It reaches no remote, so nothing about
+ * it is a push to a protected branch — but the word is right there, and the
+ * loose `isGitSubcommand` read that this file wants everywhere else found it.
+ *
+ * Matched as the adjacent pair only, never as "a segment mentioning stash", so
+ * `git push origin stash` is still read as the push it is. Filtering happens
+ * per segment after the chain is split, so the second half of `git stash push
+ * && git push` is untouched by this and still denied.
+ */
+const STASH_PUSH_RE = /\bgit\b[^;&|]*\bstash\s+push\b/i;
+/** Rule 1: push to main/master — destination ref, checked precisely; or a bare push while already on a protected branch. */
+function checkPushToProtected(command, branch, policy) {
+    if (!isGitSubcommand(command, 'push'))
+        return null;
+    const rule = requireRule(policy, 'push-to-protected');
+    const pushSegments = gitSegmentsFor(command, 'push').filter((s) => !STASH_PUSH_RE.test(s));
+    if (pushSegments.some((segment) => pushOperands(segment).some((ref) => isProtectedRef(ref, policy)))) {
+        return violation(rule);
+    }
+    if (isProtectedBranchName(branch, policy) &&
+        pushSegments.some((segment) => /push(\s+(origin|upstream))?\s*$/.test(segment))) {
+        return violation(rule, renderBranch(rule.reasonOnCurrentBranch ?? rule.reason, branch));
+    }
+    return null;
+}
+/** Rule 2: force push (`--force` / `--force-with-lease` / `-f`). Case-sensitive, same as guard.sh (its `grep -Eq` has no `-i`). */
+const FORCE_PUSH_RE = /(--force(-with-lease)?\b|(^|\s)-[a-zA-Z]*f[a-zA-Z]*(\s|$))/;
+function checkForcePush(command, policy) {
+    if (!isGitSubcommand(command, 'push'))
+        return null;
+    if (!FORCE_PUSH_RE.test(command))
+        return null;
+    return violation(requireRule(policy, 'force-push'));
+}
+/** Rule 3: `git merge` or `git pull` while standing on a protected branch — the only place a merge can land. */
+function checkMergeIntoProtected(command, branch, policy) {
+    // A merge has exactly one destination and it is never on the command line:
+    // it is wherever HEAD is. Every ref you name is a source. So the only
+    // question this rule can answer honestly is which branch you are standing
+    // on. Reading an operand as the destination refused the routine
+    // `git merge <base>` that refreshes a stale side branch — the opposite act.
+    //
+    // `git pull` is `git fetch` followed by that same merge, and it lands in the
+    // same place, so it is the same rule. `bareWord` keeps `git merge-base`,
+    // `git merge-tree` and `git pull-request` out: hyphenated names are
+    // different commands, and the plumbing ones cannot merge anything.
+    if (!isGitSubcommand(command, 'merge') && !isGitSubcommand(command, 'pull'))
+        return null;
+    // Names only, deliberately, not `protected_branches.patterns`: landing task
+    // branches on `smith/<epic>/integration` is the merge queue's whole job.
+    if (!isProtectedBranchName(branch, policy))
+        return null;
+    // One exception, and it is the one act of merging that lands nothing:
+    // fast-forwarding this branch to its own copy on a remote. No commit is
+    // created and no work arrives that was not already published, so refusing
+    // it protected nothing and cost the operator the ordinary refresh of a
+    // local `main` — the only way to do it was outside the gate entirely.
+    //
+    // Judged per segment, because every command in a chain runs: an allowed
+    // catch-up in front of `&& git merge feature-y` buys the merge nothing.
+    const segments = catchUpSegments(command);
+    if (segments.length > 0 &&
+        segments.every((segment) => isUpstreamCatchUp(segment, branch, policy))) {
+        return null;
+    }
+    const rule = requireRule(policy, 'merge-into-protected');
+    return violation(rule, renderBranch(rule.reasonOnCurrentBranch ?? rule.reason, branch));
+}
+/**
+ * The only flag rule 3's exception knows how to read. Everything else — even
+ * something harmless — falls back to the deny, because the exception's claim
+ * is that the command lands nothing, and a flag it has never seen is a claim
+ * it cannot make. `--no-ff` is the reason this is an allowlist and not a
+ * `--ff-only` presence test: `git pull --ff-only origin main --no-ff` has the
+ * exception's exact spelling in it and still writes a merge commit, since the
+ * later flag wins.
+ */
+const CATCH_UP_FLAGS = ['--ff-only'];
+/** `git merge` / `git pull` and nothing in between — no `git -c ...`, no env prefix, no wrapper. */
+const CATCH_UP_SHAPE_RE = /^git\s+(merge|pull)(?:\s|$)/;
+/**
+ * Is this segment a fast-forward of the branch you are standing on to its own
+ * copy on a remote?
+ *
+ * The rule reads what the command line says, so the exception does too, and it
+ * allows a segment only where the text itself proves every part: the command
+ * is a plain `git merge`/`git pull` with nothing spliced in front of the
+ * subcommand; its only flag is `--ff-only`; its source names *this* branch on
+ * a remote the policy lists; and there is no other operand, since a second
+ * source is a second thing landing. Anything the exception has not read is a
+ * denial, not a shrug — that is the difference between a proof and a guess.
+ *
+ * What it deliberately leaves out is a bare `git pull --ff-only`, whose source
+ * is `branch.<name>.merge` in a config file this rule cannot read. It is
+ * almost always the same catch-up, and "almost always" is the reasoning rule 3
+ * was just corrected out of — the operator gets a spelling that is true on its
+ * face instead.
+ *
+ * And what it cannot prove even so: a remote is a name here, and `git remote
+ * set-url origin <anywhere>` makes that name point wherever it likes. The
+ * allowlist buys the operator a name they control, not a URL this gate has
+ * verified — see docs/standards/guardrails.md.
+ */
+function isUpstreamCatchUp(segment, branch, policy) {
+    const subcommand = CATCH_UP_SHAPE_RE.exec(segment.trim())?.[1];
+    if (!subcommand)
+        return false;
+    const tokens = gitTokens(segment, subcommand);
+    const flags = tokens.filter((t) => t.startsWith('-'));
+    if (!flags.includes('--ff-only'))
+        return false;
+    if (flags.some((flag) => !CATCH_UP_FLAGS.includes(flag)))
+        return false;
+    const operands = tokens
+        .filter((t) => !t.startsWith('-'))
+        .map((t) => t.replace(/^["']/, '').replace(/["']$/, ''));
+    if (subcommand === 'pull') {
+        // `git pull <remote> <branch>`: the source is two operands, spelled apart.
+        return operands.length === 2 && isCatchUpRemote(operands[0], policy) && operands[1] === branch;
+    }
+    // `git merge <remote>/<branch>`: the same source, spelled as one ref. A bare
+    // `main` is not it — that is a local ref that merely shares the name.
+    if (operands.length !== 1)
+        return false;
+    const [remote, ...rest] = (operands[0] ?? '').split('/');
+    return isCatchUpRemote(remote, policy) && rest.join('/') === branch;
+}
+function isCatchUpRemote(token, policy) {
+    return token !== undefined && policy.catchUpRemotes.includes(token);
+}
+/** Rule 4: deploy/publish commands (`deploy_commands` in guardrails.yml — wrangler deploy/publish, pages publish today). */
+function checkDeployCommand(command, policy) {
+    const rule = requireRule(policy, 'deploy-command');
+    for (const spec of policy.deployCommands) {
+        const subcommandAlt = spec.subcommands.map(escapeRegExp).join('|');
+        const re = new RegExp(`\\b${escapeRegExp(spec.command)}\\b.*\\b(${subcommandAlt})\\b`, 'i');
+        if (re.test(command)) {
+            return violation(rule);
+        }
+    }
+    return null;
+}
+/** Rule 5: history rewrite (rebase / commit --amend / filter-branch|filter-repo) on a protected branch. */
+function checkHistoryRewriteOnProtected(command, branch, policy) {
+    if (!isProtectedForHistoryRewrite(branch, policy))
+        return null;
+    const rewrites = isGitSubcommand(command, 'rebase') ||
+        /\bcommit\b.*--amend\b/i.test(command) ||
+        /\bfilter-(branch|repo)\b/i.test(command);
+    if (!rewrites)
+        return null;
+    const rule = requireRule(policy, 'history-rewrite-on-protected');
+    return violation(rule, renderBranch(rule.reason, branch));
+}
+/** Rule 6 detection, half one: is `rm` invoked as a command in this segment? Looser than "first token", so `sudo rm …` still matches; stricter than a bare substring, so the `rm` inside `charm`/`confirm` is not this rule's business. */
+const RM_INVOKE_RE = /(^|[;&|]|\s)rm\s+/;
+/** A bundled short-flag token (`-rf`, `-Rvf`) as opposed to a long flag (`--force`) or a path. */
+const RM_SHORT_FLAG_RE = /^-[a-zA-Z]+$/;
+/**
+ * Rule 6 detection, half two: does this `rm` carry both recursive and force?
+ *
+ * Read across the invocation's flag tokens rather than out of a single one,
+ * because the spellings that mean the same removal are one case, not four:
+ * bundled (`-rf`), split (`-r -f`), long (`--recursive --force`), and mixed
+ * (`--recursive -f`). The predecessor of this function matched the flags as a
+ * literal run directly after `rm`, which read `-rf` and `-fr` and nothing
+ * else — so `rm -Rf src` and `rm -r -f src` were recursive-force removals the
+ * gate did not see. `-R` counts: it is POSIX's own recursive spelling and
+ * does exactly what `-r` does.
+ *
+ * `-i` is still ignored, matching guard.sh — an interactive prompt is not a
+ * bound the factory can hold an agent to.
+ */
+function hasRecursiveForce(tokens) {
+    let recursive = false;
+    let force = false;
+    for (const token of tokens) {
+        if (token === '--recursive')
+            recursive = true;
+        else if (token === '--force')
+            force = true;
+        else if (RM_SHORT_FLAG_RE.test(token)) {
+            if (token.includes('r') || token.includes('R'))
+                recursive = true;
+            if (token.includes('f'))
+                force = true;
+        }
+    }
+    return recursive && force;
+}
+/**
+ * The characters that separate one command in a chain from the next. `;&|`
+ * are the three guard.sh knew, and for a long time this file knew no others
+ * — which left the rules that read a segment's *operands* (rule 1's
+ * destination ref, rule 6's paths) reading whatever the next piece of shell
+ * syntax put in front of them:
+ * - `(` `)` open and close a substitution or subshell — `echo $(git push
+ *   origin main)` is a real push in a real tool call, and the `)` stuck to
+ *   the ref made it `main)`, which is nothing's name.
+ * - A backtick is the older spelling of the same thing.
+ * - `#` starts a comment; everything after it is not a command at all.
+ * - A newline separates two commands exactly as `;` does. A multi-line Bash
+ *   payload is one tool call, and every line in it runs.
+ * - `{` `}` group commands.
+ *
+ * Splitting stays naive about quoting, the same trade-off guard.sh made: a
+ * separator inside a quoted string splits anyway. That direction over-refuses,
+ * which is the one this file chooses everywhere.
+ */
+const COMMAND_SEPARATOR_CHARS = ';&|\\n(){}#`';
+/**
+ * `>` `<` start a redirection, whose target is a file the command writes,
+ * never one of its operands. This is the one that mattered: `git push
+ * origin main > /dev/null` is not an evasion, it is how a quiet push is
+ * written, and it was allowed.
+ *
+ * They are kept apart from the separators above because cutting a command
+ * here does not separate two commands, it *truncates* one — and the two
+ * cuts differ on whether that is safe. A rule that refuses on what it sees
+ * refuses more when it sees less, so every deny rule may cut here freely.
+ * `checkMergeIntoProtected`'s exception *allows* on what it sees, and text
+ * it never read is a claim it must not make: see `stripRedirections`.
+ */
+const REDIRECTION_CHARS = '<>';
+/** Every character that ends the command a segment is about — what the deny rules split on. */
+const SEPARATOR_CHARS = `${COMMAND_SEPARATOR_CHARS}${REDIRECTION_CHARS}`;
+/**
+ * Every separated segment of a command, so a chain can be inspected one
+ * invocation at a time — and so a rule reading a segment's operands is looking
+ * at that command's operands and nothing else.
+ */
+function splitChainSegments(command) {
+    return command.split(new RegExp(`[${SEPARATOR_CHARS}]`));
+}
+/**
+ * A redirection, with its target: an optional file descriptor or `&`, one of
+ * the redirection operators, and then either a descriptor to duplicate
+ * (`2>&1`, `<&-`) or a word to redirect to, glued or spaced (`>/dev/null`,
+ * `> out`). The target stops at a separator so that `>out; git merge x` gives
+ * back the `;` it was written with.
+ *
+ * Longest operators first: `>>` before `>`, `<<<` before `<<` before `<`.
+ */
+const REDIRECTION_RE = new RegExp(`(?:&|\\d*)(?:>>|>|<<<|<<-?|<>|<)(?:&\\d*-?|\\s*[^\\s${COMMAND_SEPARATOR_CHARS}${REDIRECTION_CHARS}]*)`, 'g');
+/**
+ * The command with its plumbing taken out — `git pull --ff-only origin main
+ * 2>&1 | tail` becomes `git pull --ff-only origin main   | tail`.
+ *
+ * Removing redirections *before* splitting is the point, and the order is what
+ * makes it correct: the `&` in `2>&1` belongs to the redirection, and only a
+ * reader that has already recognised it can tell it from the `&&` that really
+ * does start a second command.
+ *
+ * This is the exception's reading and nothing else's. Every deny rule keeps
+ * splitting on `<` and `>`, where truncating a command is the safe direction.
+ */
+function stripRedirections(command) {
+    return command.replace(REDIRECTION_RE, ' ');
+}
+/**
+ * The `git merge`/`git pull` commands in a chain, read for rule 3's exception:
+ * plumbing removed, then split on the characters that actually separate two
+ * commands.
+ *
+ * `gitSegmentsFor` is the same read for every rule that denies, and it would
+ * hand this one a lie: `git pull --ff-only origin main >/dev/null --no-ff`
+ * splits at the `>` into a segment that ends at `main`, which is exactly the
+ * catch-up the exception allows — while the command git actually runs has
+ * `--no-ff` on it and writes a merge commit.
+ */
+function catchUpSegments(command) {
+    const re = new RegExp(`\\bgit\\b.*(?:${bareWord('merge')}|${bareWord('pull')})`, 'i');
+    return stripRedirections(command)
+        .split(new RegExp(`[${COMMAND_SEPARATOR_CHARS}]`))
+        .filter((s) => re.test(s));
+}
+/** The `rm <args>` run up to the next separator, ported from guard.sh's `grep -Eo 'rm[[:space:]]+[^;&|]*'` and widened with it. Applied per chain segment (see `checkUnboundedRm`), so "up to the next separator" and "to the end of the string" mean the same thing by the time this runs — the negated class is belt and braces, kept in step with the split so the two can never disagree about where a command ends. */
+const RM_ARGS_RE = new RegExp(`rm\\s+([^${SEPARATOR_CHARS}]*)`);
+function extractRmArgs(segment) {
+    const match = RM_ARGS_RE.exec(segment);
+    if (!match)
+        return [];
+    return (match[1] ?? '')
+        .trim()
+        .split(/\s+/)
+        .filter((t) => t !== '');
+}
+/**
+ * Normalize an `rm` argument to a repo-root-relative path — the portable
+ * replacement for guard.sh's `normalize_path`, which shelled out to
+ * `realpath -m` when present and fell back to the raw string otherwise (no
+ * `realpath` on a stock Windows install, which is one of the three named
+ * reasons the guard hook needed WSL2). `path.resolve` needs no external
+ * binary, and `path.relative` is `path.sep`-aware — unlike bash's `case
+ * "$p" in "$REPO_ROOT"/*) … esac`, which only ever recognised `/` — so this
+ * is also the fix for guard.sh's Windows-path-separator gap, not just its
+ * missing-binary one.
+ */
+function normalizeRemovalPath(token, repoRoot) {
+    if (repoRoot === null) {
+        // No repo root to make this relative to (guard.sh: `git rev-parse
+        // --show-toplevel` failed, so `REPO_ROOT` was `''` and the `-n
+        // "$REPO_ROOT"` guard skipped the prefix strip entirely). Absolutize
+        // instead of returning the token as-is, so a bare relative token like
+        // `workspaces` can never coincidentally read as an allowed root — the
+        // same fail-closed behaviour bash got for free from comparing an
+        // un-prefix-stripped absolute path against a bare `workspaces/*` glob.
+        return path.resolve(token);
+    }
+    const absolute = path.resolve(repoRoot, token);
+    const relative = path.relative(repoRoot, absolute);
+    return relative === '' ? '.' : relative;
+}
+function isAllowedRemovalPath(normalizedPath, policy) {
+    const first = normalizedPath.split(path.sep)[0];
+    // `path.relative` produces a leading `..` segment when the path climbs
+    // above repoRoot, and an empty leading segment for an absolute path
+    // (posix `/x` splits to `['', 'x']`) — neither is an allowed root name.
+    return (first !== undefined &&
+        first !== '' &&
+        first !== '..' &&
+        policy.allowedRemovalRoots.includes(first));
+}
+/**
+ * Rule 6: a recursive-force `rm` outside `allowed_roots`, however the two
+ * flags are spelled (see `hasRecursiveForce`).
+ *
+ * Checks every chain segment independently, not just the first `rm` in the
+ * whole command. guard.sh's own `grep -Eo 'rm[[:space:]]+[^;&|]*'` — and this
+ * function, until this fix — stopped at the first match in the *whole*
+ * command string, so `rm -rf workspaces/a; rm -rf src/important` read
+ * `workspaces/a` (allowed), decided the command was fine, and never looked
+ * at `src/important` at all. That is a deliberate behaviour change from a
+ * straight port: closing a chained-command bypass that guard.sh always had,
+ * not carrying it forward with new spelling.
+ */
+function checkUnboundedRm(command, repoRoot, policy) {
+    const outOfBounds = splitChainSegments(command).some((segment) => {
+        if (!RM_INVOKE_RE.test(segment))
+            return false;
+        const args = extractRmArgs(segment);
+        if (!hasRecursiveForce(args))
+            return false;
+        return args.some((tok) => {
+            if (tok.startsWith('-'))
+                return false;
+            return !isAllowedRemovalPath(normalizeRemovalPath(tok, repoRoot), policy);
+        });
+    });
+    if (!outOfBounds)
+        return null;
+    return violation(requireRule(policy, 'unbounded-rm'));
+}
+// ---------------------------------------------------------------------------
+// judge sandbox — rules that apply only while a lease is open (sandbox.ts)
+// ---------------------------------------------------------------------------
+/**
+ * Does `segment` invoke `word` as a command?
+ *
+ * Looser than "first token" (so `xargs curl …` and `sudo rm …` still match)
+ * but stricter than the bare `\b<word>\b` the git matchers use, because
+ * these lists contain two-letter words: `\bnc\b` matches inside `src/nc/`,
+ * and a judge running `grep -r x src/nc/` being told it has no network
+ * access is the kind of false refusal that gets a guard switched off.
+ * Requiring whitespace or a chain separator on the left, and whitespace or
+ * end-of-segment on the right, keeps path components out while keeping every
+ * real invocation in.
+ */
+function hasCommandWord(segment, word) {
+    return new RegExp(`(^|[;&|(]|\\s)${escapeRegExp(word)}(\\s|$)`, 'i').test(segment);
+}
+/** `<command> … <one of subcommands>` within a single chain segment. */
+function hasCommandSubcommand(segment, spec) {
+    if (!hasCommandWord(segment, spec.command))
+        return false;
+    return spec.subcommands.some((sub) => new RegExp(`\\b${escapeRegExp(sub)}\\b`, 'i').test(segment));
+}
+/**
+ * Remove heredoc bodies before looking for redirections.
+ *
+ * A judge's one legitimate write is its verdict, and the way an agent with
+ * no `Write` tool produces a JSON file is `cat > state/results/x.json
+ * <<'JSON' … JSON`. The body of that heredoc is prose the judge wrote, and
+ * prose contains `>`. Without this, a finding that says "expected > 0"
+ * parses as a redirection to a file named `0`, which is not under a write
+ * root, and the judge is refused permission to file its own report. Strips
+ * from the line introducing the delimiter to the line that closes it, or to
+ * the end when it is never closed.
+ */
+function stripHeredocBodies(command) {
+    const lines = command.split('\n');
+    const kept = [];
+    let delimiter = null;
+    for (const line of lines) {
+        if (delimiter !== null) {
+            if (line.trim() === delimiter)
+                delimiter = null;
+            continue;
+        }
+        kept.push(line);
+        const match = /<<-?\s*(?:'([^']+)'|"([^"]+)"|([A-Za-z_][A-Za-z0-9_]*))/.exec(line);
+        if (match)
+            delimiter = match[1] ?? match[2] ?? match[3] ?? null;
+    }
+    return kept.join('\n');
+}
+/**
+ * Targets of `>`/`>>` redirections. `2>&1` and friends are excluded by the
+ * `(?!&)` lookahead — a duplicated file descriptor is not a path.
+ */
+const REDIRECT_TARGET_RE = />>?\s*(?!&)([^\s;&|<>]+)/g;
+function redirectTargets(command) {
+    const targets = [];
+    for (const match of stripHeredocBodies(command).matchAll(REDIRECT_TARGET_RE)) {
+        const token = (match[1] ?? '').replace(/^["']/, '').replace(/["']$/, '');
+        if (token !== '')
+            targets.push(token);
+    }
+    return targets;
+}
+/** Non-flag arguments following `word` in `segment`, i.e. the paths a `mkdir`/`tee`/`touch` will write. */
+function argumentsAfter(segment, word) {
+    const tokens = segment.trim().split(/\s+/);
+    const index = tokens.findIndex((t) => t.toLowerCase() === word.toLowerCase());
+    if (index === -1)
+        return [];
+    return tokens
+        .slice(index + 1)
+        .filter((t) => t !== '' && !t.startsWith('-'))
+        .map((t) => t.replace(/^["']/, '').replace(/["']$/, ''));
+}
+/**
+ * Is a repo-root-relative path inside one of `write_roots`?
+ *
+ * Segment-wise rather than string-prefix, so `state/results-of-mine` does
+ * not read as inside `state/results`. Equality counts (`mkdir -p
+ * state/results` is a judge preparing to write its verdict), and anything
+ * that climbed above the repo root — `path.relative` renders that with a
+ * leading `..`, and an absolute path with a leading empty segment — does
+ * not.
+ */
+function isUnderWriteRoot(normalizedPath, roots) {
+    const parts = normalizedPath.split(path.sep);
+    if (parts[0] === undefined || parts[0] === '' || parts[0] === '..')
+        return false;
+    return roots.some((root) => {
+        const rootParts = root.split('/').filter((p) => p !== '');
+        return parts.length >= rootParts.length && rootParts.every((p, i) => parts[i] === p);
+    });
+}
+/**
+ * A probe segment appended to a path to ask "would anything *inside* this
+ * directory be in scope?" — see `isWithinWriteScope`.
+ */
+const SCOPE_PROBE = '__scope_probe__';
+/** Repo-root-relative, posix-separated — the shape `write_globs` are written in. */
+function toRepoRelativePosix(token, repoRoot) {
+    return normalizeRemovalPath(token, repoRoot).split(path.sep).join('/');
+}
+/**
+ * Is a repo-root-relative path inside a role's write scope?
+ *
+ * Globs rather than `write_roots`' path prefixes, because a tester's scope is
+ * not a directory: a double-star test-file pattern is a shape, and the files
+ * it names sit beside the implementation they cover.
+ *
+ * A directory counts as in scope when something inside it would be, which is
+ * what the probe asks: `mkdir -p factory/orchestrator/test/fixtures` is a
+ * tester preparing to write fixtures, and refusing it would be a false deny
+ * — the kind that teaches an agent to route around the gate rather than
+ * trust it. A path that climbed above the repo root (`path.relative` renders
+ * that with a leading `..`, an absolute path with a leading empty segment)
+ * is never in scope, whatever the globs say.
+ */
+function isWithinWriteScope(normalizedPath, globs) {
+    const first = normalizedPath.split('/')[0];
+    if (first === undefined || first === '' || first === '..' || normalizedPath === '.')
+        return false;
+    const isMatch = picomatch([...globs], { dot: true });
+    return isMatch(normalizedPath) || isMatch(`${normalizedPath}/${SCOPE_PROBE}`);
+}
+/** `{role}` and `{write_roots}` in a judge rule's reason, same placeholder convention as `{branch}`. */
+function renderSandboxReason(template, lease, policy) {
+    return template
+        .replace('{role}', lease.role)
+        .replace('{write_roots}', policy.judgeSandbox.writeRoots.join(' or '));
+}
+function sandboxViolation(policy, id, lease) {
+    const rule = requireRule(policy, id);
+    return violation(rule, renderSandboxReason(rule.reason, lease, policy));
+}
+/** Judge rule 1: no outbound access — network clients, remote git, package installs. */
+function checkJudgeNetwork(command, lease, policy) {
+    const { networkCommands, networkSubcommands } = policy.judgeSandbox;
+    const reaches = splitChainSegments(command).some((segment) => networkCommands.some((word) => hasCommandWord(segment, word)) ||
+        networkSubcommands.some((spec) => hasCommandSubcommand(segment, spec)));
+    return reaches ? sandboxViolation(policy, 'judge-network', lease) : null;
+}
+/**
+ * Judge rule 2: the only write a judge may make is a redirection into a
+ * write root.
+ *
+ * Four shapes, deliberately not unified. A file tool names its target
+ * outright, so it is checked directly (judges hold no `Edit`/`Write` today,
+ * but the rule answers for the role, not for the tool it reached for). A redirection has one readable
+ * target, so it is checked against the allowlist. `mkdir`/`tee`/`touch` take
+ * nothing but targets, so every non-flag argument is checked. Everything
+ * else that writes is refused outright rather than path-checked, because
+ * deciding which token of `cp a b` is the target — or of `install -m 644 a b
+ * c` — is more machinery than the zero legitimate cases justify.
+ */
+function checkJudgeWrite(command, filePath, lease, repoRoot, policy) {
+    const { writeRoots, targetWriteCommands, refusedWriteCommands, gitWriteSubcommands } = policy.judgeSandbox;
+    const outOfBounds = (token) => !isUnderWriteRoot(normalizeRemovalPath(token, repoRoot), writeRoots);
+    if (filePath !== null && filePath !== '' && outOfBounds(filePath)) {
+        return sandboxViolation(policy, 'judge-write', lease);
+    }
+    if (redirectTargets(command).some(outOfBounds)) {
+        return sandboxViolation(policy, 'judge-write', lease);
+    }
+    const stripped = stripHeredocBodies(command);
+    const writes = splitChainSegments(stripped).some((segment) => {
+        if (refusedWriteCommands.some((word) => hasCommandWord(segment, word)))
+            return true;
+        if (/\bsed\b[^;&|]*\s-i(\.[^\s]*)?(\s|$)/i.test(segment))
+            return true;
+        if (hasCommandWord(segment, 'git') &&
+            gitWriteSubcommands.some((sub) => new RegExp(`\\b${escapeRegExp(sub)}\\b`, 'i').test(segment))) {
+            return true;
+        }
+        return targetWriteCommands.some((word) => hasCommandWord(segment, word) && argumentsAfter(segment, word).some(outOfBounds));
+    });
+    return writes ? sandboxViolation(policy, 'judge-write', lease) : null;
+}
+/**
+ * Blank out quoted spans before scanning a segment for command words.
+ *
+ * Only the write-scope rule needs this *blanket* form — the six base rules
+ * take the narrower `stripMessageFlagValues` above, which spares a quoted ref.
+ * The write-scope rule needs the wider net because the role it governs
+ * commits: `git commit -m "test: cover the restore path"` is a tester doing
+ * exactly what its output contract asks, and refusing it because the message
+ * says "restore" is the same class of false deny as refusing `git merge-base`
+ * — the kind that teaches an agent to route around the gate rather than
+ * trust it. A quoted span is an argument, never a command word.
+ *
+ * Replaced rather than deleted, so token boundaries survive. Targets keep
+ * being read off the unstripped segment, since `tee "state/results/x"` is a
+ * write whose target happens to be quoted.
+ */
+function stripQuotedSpans(segment) {
+    return segment.replace(/"[^"]*"|'[^']*'/g, '""');
+}
+/** `{role}` and `{write_globs}` in the role-write-scope rule's reason. */
+function scopeViolation(policy, lease, scope) {
+    const rule = requireRule(policy, 'role-write-scope');
+    return violation(rule, rule.reason.replace('{role}', lease.role).replace('{write_globs}', scope.writeGlobs.join(', ')));
+}
+/**
+ * Role rule: a write-scoped role writes inside its globs and nowhere else.
+ *
+ * The shapes mirror `checkJudgeWrite`, with two differences that follow from
+ * the role actually being allowed to write. `rm` is path-checked rather than
+ * refused, because deleting a stale test is ordinary tester work and its
+ * arguments are all targets. `git add`/`commit` stay allowed, because the
+ * tester's output contract *requires* a commit on the task branch — only the
+ * git subcommands that change tracked content without passing a path check
+ * (`apply`, `checkout`, `reset`, …) are refused, since those would put the
+ * implementation back under the tester's control by the back door.
+ *
+ * `sed -i` and the verbs in `refused_commands` are refused outright for the
+ * same reason the judge refuses them: deciding which token of `cp a b` is
+ * the target is more machinery than the legitimate cases justify, and here
+ * the role has `Edit` and `Write`, which *are* path-checked, as the better
+ * route to the same edit.
+ *
+ * The known limit is the judge sandbox's, unchanged: this reads command
+ * text, not intent. A write smuggled through an interpreter is invisible to
+ * it, which is why `smith worktree fingerprint`/`verify` stays behind it.
+ */
+function checkRoleWriteScope(command, filePath, lease, repoRoot, policy, scope) {
+    const outOfScope = (token) => !isWithinWriteScope(toRepoRelativePosix(token, repoRoot), scope.writeGlobs);
+    if (filePath !== null && filePath !== '' && outOfScope(filePath)) {
+        return scopeViolation(policy, lease, scope);
+    }
+    if (redirectTargets(command).some(outOfScope)) {
+        return scopeViolation(policy, lease, scope);
+    }
+    // Which verbs take nothing but targets is a fact about the verbs, not
+    // about the role, so the judge sandbox's list is reused rather than
+    // restated once per scope. `rm` joins them here only.
+    const targetVerbs = [...policy.judgeSandbox.targetWriteCommands, 'rm'];
+    const stripped = stripHeredocBodies(command);
+    const writes = splitChainSegments(stripped).some((segment) => {
+        const words = stripQuotedSpans(segment);
+        if (scope.refusedCommands.some((word) => hasCommandWord(words, word)))
+            return true;
+        if (/\bsed\b[^;&|]*\s-i(\.[^\s]*)?(\s|$)/i.test(words))
+            return true;
+        if (scope.refusedGitSubcommands.some((sub) => isGitSubcommand(words, sub)))
+            return true;
+        return targetVerbs.some((word) => hasCommandWord(segment, word) && argumentsAfter(segment, word).some(outOfScope));
+    });
+    return writes ? scopeViolation(policy, lease, scope) : null;
+}
+/**
+ * Judge rule 3: a judge does not touch its own lease.
+ *
+ * Without this the sandbox would be one `smith sandbox close` away from
+ * being off, and `rm state/sandboxes/<hash>.json` is a removal under
+ * `state/`, which the `unbounded-rm` rule above explicitly permits. The
+ * refusal is unconditional on the lease directory rather than scoped to
+ * *this* lease: reading another judge's lease is no more a judge's business
+ * than deleting its own.
+ */
+function checkJudgeSandboxEscape(command, lease, policy) {
+    const escapes = splitChainSegments(command).some((segment) => {
+        if (/state[\\/]sandboxes/i.test(segment))
+            return true;
+        if (!/\bsandbox\b/i.test(segment))
+            return false;
+        return (hasCommandWord(segment, 'smith') ||
+            hasCommandWord(segment, 'node') ||
+            /\bcli\.js\b/i.test(segment));
+    });
+    return escapes ? sandboxViolation(policy, 'judge-sandbox-escape', lease) : null;
+}
+/**
+ * The guard hook's decision for one tool call: every guardrails.yml rule
+ * that fires, not just the first (an agent — or an operator reading the
+ * denial — should see every reason at once, the same way `smith check` does
+ * for gate failures). Only tools in `INSPECTED_TOOLS` (a shell command) or
+ * `INSPECTED_FILE_TOOLS` (a target path) are evaluated; every other tool
+ * call, an empty command and an absent path all allow trivially.
+ */
+export function evaluateCommand(context, policy = loadGuardrailPolicy()) {
+    const inspectsCommand = INSPECTED_TOOLS.includes(context.toolName);
+    const inspectsPath = INSPECTED_FILE_TOOLS.includes(context.toolName);
+    const filePath = inspectsPath ? (context.filePath ?? null) : null;
+    if (!inspectsCommand && !inspectsPath)
+        return { allowed: true, violations: [] };
+    if (inspectsCommand && context.command.trim() === '') {
+        return { allowed: true, violations: [] };
+    }
+    if (inspectsPath && (filePath === null || filePath.trim() === '')) {
+        return { allowed: true, violations: [] };
+    }
+    const { command, branch, repoRoot } = context;
+    // The six base rules look for refs and command words, so they read the
+    // command with its message payloads blanked — see `stripMessageFlagValues` —
+    // and with the payload of a `policy check` question blanked too, since
+    // asking what a rule says is not doing the thing it says no to.
+    // The lease rules below keep the raw string: they read *targets* off the
+    // command, and `-m` is not always prose down there (`mkdir -m 755 <dir>`
+    // spends it on a mode), so blanking it could put an empty token where a
+    // path belongs.
+    // Outermost quoting wins, so the question is blanked before the message
+    // payloads inside it are looked at: `policy check --command 'git commit -m
+    // "…"'` is one inert span, not a commit with a message.
+    const scanned = stripMessageFlagValues(stripPolicyCheckPayloads(command));
+    const checks = [
+        () => checkPushToProtected(scanned, branch, policy),
+        () => checkForcePush(scanned, policy),
+        () => checkMergeIntoProtected(scanned, branch, policy),
+        () => checkDeployCommand(scanned, policy),
+        () => checkHistoryRewriteOnProtected(scanned, branch, policy),
+        () => checkUnboundedRm(scanned, repoRoot, policy),
+    ];
+    // The judge rules are additive: a judge is bound by everything an ordinary
+    // session is bound by, and by these on top. They are appended rather than
+    // substituted so there is no arrangement of leases under which a command
+    // is checked by fewer rules than it would have been with no lease at all.
+    const lease = context.sandbox ?? null;
+    if (lease !== null) {
+        // One rule set per lease, selected by role. A role with no declared
+        // write scope gets the judge rules — that covers the six judge roles
+        // and, deliberately, anything unrecognised: `--role coder` is either a
+        // typo or an attempt to pick a rule set, and the strictest set is the
+        // safe answer to both. sandbox.ts refuses the unknown role outright at
+        // lease time; this is the second line, for a lease file written by hand.
+        const scope = policy.roleWriteScopes.find((s) => s.role === lease.role) ?? null;
+        if (scope === null) {
+            checks.push(() => checkJudgeNetwork(command, lease, policy), () => checkJudgeWrite(command, filePath, lease, repoRoot, policy));
+        }
+        else {
+            checks.push(() => checkRoleWriteScope(command, filePath, lease, repoRoot, policy, scope));
+        }
+        // Not role-dependent: a lease a leaseholder can lift is not a lease,
+        // whichever rule set the role draws the rest of its bounds from.
+        checks.push(() => checkJudgeSandboxEscape(command, lease, policy));
+    }
+    const violations = checks.map((check) => check()).filter((v) => v !== null);
+    return { allowed: violations.length === 0, violations };
+}
+// ---------------------------------------------------------------------------
+// git-derived context — used by `smith policy check` when --branch is not given
+// ---------------------------------------------------------------------------
+/** `git rev-parse --abbrev-ref HEAD`, or `''` outside a git repo / on a fresh repo with no commits — mirrors guard.sh's `current_branch()`. */
+export function detectCurrentBranch(cwd = REPO_ROOT) {
+    try {
+        return runGit(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
+    }
+    catch {
+        return '';
+    }
+}
+/** `git rev-parse --show-toplevel`, or `null` outside a git repo — mirrors guard.sh's inline `REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || printf '')"`. */
+export function detectRepoRoot(cwd = REPO_ROOT) {
+    try {
+        return runGit(cwd, ['rev-parse', '--show-toplevel']);
+    }
+    catch {
+        return null;
+    }
+}