@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/templates/guard-kit/check.mjs.template

@@ -0,0 +1,932 @@
+#!/usr/bin/env node
+/**
+ * Build guardrail kit gate (kit version {{KIT_VERSION}}).
+ *
+ * Self-contained, vendored gate script. Zero npm dependencies: only node:
+ * builtins are imported. Requires Node >= 24 (ESM, modern fs). Runs at gate
+ * time with no Build, no npm, and no network.
+ *
+ * Runs three check families over the diff between a base ref and HEAD. With
+ * --staged it runs only the built-in secret scan over the staged index. With
+ * --message <file> (`-` reads stdin) it runs only the attribution text rules
+ * over one commit message against this checkout's policy.json, the same rules
+ * the range scan applies to each commit message (for a commit-msg hook):
+ *   1. secret-scan: added diff lines matched against the built-in credential
+ *      catalog (supported provider CLI keys plus the AWS, GCP, and GitHub paths
+ *      they authenticate through) plus config.json extraSecretPatterns.
+ *   2. artifact-paths: changed paths matched against generated deny defaults
+ *      plus config.json extraDenyPaths / extraArtifactPatterns. config.json
+ *      allowPaths exempts matching paths from the DEFAULT denies only (a repo
+ *      that commits dist/ on purpose), never from the extras it added itself.
+ *   3. guard-integrity: any changed path under this guard directory (check.mjs,
+ *      config.json, policy.json, checks.lock) is a gate-critical finding.
+ *      Matching is case-INSENSITIVE (a case-variant path like .build-project/Guard/x
+ *      collides with the guard dir on case-insensitive filesystems).
+ *   4. attribution: when the BASE ref's committed policy.json says `human-only`
+ *      (a PR cannot relax it by editing its own copy), every non-merge commit
+ *      in the range (author, committer, message) and the pull-request body
+ *      (BUILD_GUARD_PR_BODY_FILE, else GITHUB_EVENT_PATH) must carry no AI
+ *      attribution. Structural rules: any Co-authored-by trailer and any
+ *      `[bot]` author/committer outside policy.botAllow are findings.
+ *      Catalog rules: the vendored provider identities, trailer keys, and
+ *      bylines. Under `allow` the family is a no-op. policy.json is generated
+ *      and hash-tracked (see build guard sync); missing or malformed fails
+ *      closed.
+ *
+ * Exit codes:
+ *   0  clean.
+ *   1  hard failure (secret, artifact path, attribution). Blocks merge.
+ *   2  only guard-integrity findings (gate machinery changed) with no hard
+ *      failure. Softer than 1: merge automation treats this as
+ *      require-human-merge rather than block. A hard finding always dominates,
+ *      so exit 1 wins when both are present.
+ *
+ * Config (this-dir config.json, all keys optional): baseRef, extraDenyPaths,
+ * allowPaths, extraSecretPatterns, extraArtifactPatterns. Config tunes policy VALUES only;
+ * it cannot enable or disable a check. Check on/off lives in the generated
+ * manifest below and is not consumer-editable.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { basename, dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const MANIFEST = {{GENERATED_MANIFEST}};
+
+// Fail CLOSED on a malformed manifest. Every check family gates on
+// MANIFEST.checks.<key>; if the renderer and this template ever disagree on
+// the manifest shape, a missing key must abort the run — never silently skip
+// a check (a skipped check reads as a pass to merge automation).
+const REQUIRED_CHECK_KEYS = [
+  'secretScan',
+  'artifactPaths',
+  'guardIntegrity',
+  'attribution',
+];
+for (const key of REQUIRED_CHECK_KEYS) {
+  if (typeof MANIFEST?.checks?.[key] !== 'boolean') {
+    process.stderr.write(
+      `Error: guard manifest is malformed (checks.${key} missing). ` +
+        'The generated gate is unusable; re-run: build init --guardrails --reinstall-guard\n'
+    );
+    process.exit(1);
+  }
+}
+if (!Array.isArray(MANIFEST.defaultDenyPaths)) {
+  process.stderr.write(
+    'Error: guard manifest is malformed (defaultDenyPaths missing). ' +
+      'Re-run: build init --guardrails --reinstall-guard\n'
+  );
+  process.exit(1);
+}
+
+// The guard directory is normally where this script lives. BUILD_GUARD_DIR
+// overrides it for the trusted-base invocation pattern: CI extracts the BASE
+// branch's copy of check.mjs to a temp path and runs that copy against the
+// PR checkout (a PR-owned script could otherwise strip its own
+// guard-integrity check before it runs). See the generated CI guidance.
+/**
+ * Resolve symlinks so path comparisons against git output are stable (macOS:
+ * /var/... vs /private/var/...). Tolerates a missing path by realpathing the
+ * nearest existing ancestor and re-appending the missing tail — needed when a
+ * PR deletes the guard dir and BUILD_GUARD_DIR points at the gap.
+ */
+function realpathBestEffort(target) {
+  let head = target;
+  let tail = '';
+  for (;;) {
+    try {
+      const real = realpathSync(head);
+      return tail ? join(real, tail) : real;
+    } catch {
+      const parent = dirname(head);
+      if (parent === head) return target;
+      tail = tail ? join(basename(head), tail) : basename(head);
+      head = parent;
+    }
+  }
+}
+
+const SCRIPT_DIR = realpathBestEffort(
+  process.env.BUILD_GUARD_DIR
+    ? process.env.BUILD_GUARD_DIR
+    : dirname(fileURLToPath(import.meta.url))
+);
+
+// Generated from src/core/guard-kit/secret-patterns.ts. Local staged checks
+// and hosted commit-range checks execute this same vendored inventory.
+const SECRET_PATTERNS = {{SECRET_PATTERNS}};
+
+/** Normalize any git path to forward slashes before matching. */
+function normalizePath(value) {
+  return value.replace(/\\/g, '/');
+}
+
+/**
+ * Case-insensitive prefix test for the guard NAMESPACE. Guard-integrity must
+ * catch case-variant paths (.build-project/Guard/x, .Build/guard/y): on a
+ * case-sensitive CI runner those are distinct paths, but when the merged
+ * branch is later checked out on a case-insensitive filesystem (macOS,
+ * Windows) they materialize INSIDE the real guard directory. Detection is
+ * deliberately broader than the exact tracked case.
+ */
+function isUnderGuardNamespace(filePath, guardDirPrefix) {
+  return filePath.toLowerCase().startsWith(guardDirPrefix.toLowerCase());
+}
+
+// Git cwd: prefer the guard dir when it exists (normal case), else fall back
+// to the process cwd. The fallback matters for the trusted-base pattern when
+// a PR DELETES the entire guard directory: BUILD_GUARD_DIR then points at a
+// missing path, and spawning git from it would crash with a generic error
+// instead of reaching the guard-integrity verdict (exit 2).
+const GIT_CWD = existsSync(SCRIPT_DIR) ? SCRIPT_DIR : process.cwd();
+
+function git(args, options = {}) {
+  try {
+    return execFileSync('git', args, {
+      cwd: GIT_CWD,
+      encoding: 'utf8',
+      maxBuffer: 64 * 1024 * 1024,
+    });
+  } catch (error) {
+    if (options.allowFailure) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+function isCI() {
+  const value = process.env.CI;
+  return Boolean(value) && value !== '0' && value.toLowerCase() !== 'false';
+}
+
+function loadConfig() {
+  const configPath = join(SCRIPT_DIR, 'config.json');
+  if (!existsSync(configPath)) {
+    return {};
+  }
+  let raw;
+  try {
+    raw = readFileSync(configPath, 'utf8');
+  } catch (error) {
+    throw new Error(`cannot read config.json at ${configPath}: ${error.message}`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`unparseable config.json at ${configPath}: ${error.message}`);
+  }
+}
+
+function parseArgs(argv) {
+  const parsed = {
+    formatJson: false,
+    listChecks: false,
+    staged: false,
+    message: null,
+    base: null,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--format') {
+      parsed.formatJson = argv[++i] === 'json';
+    } else if (arg === '--format=json') {
+      parsed.formatJson = true;
+    } else if (arg === '--list-checks') {
+      parsed.listChecks = true;
+    } else if (arg === '--staged') {
+      parsed.staged = true;
+    } else if (arg === '--message') {
+      parsed.message = argv[++i] ?? null;
+    } else if (arg === '--base') {
+      parsed.base = argv[++i] ?? null;
+    } else if (arg.startsWith('--base=')) {
+      parsed.base = arg.slice('--base='.length);
+    }
+  }
+  return parsed;
+}
+
+function resolveBaseRef(config, cliBase) {
+  if (cliBase) {
+    return cliBase;
+  }
+  if (process.env.BUILD_GUARD_BASE_REF) {
+    return process.env.BUILD_GUARD_BASE_REF;
+  }
+  const githubBase = (process.env.GITHUB_BASE_REF ?? '').trim();
+  if (githubBase) {
+    return `origin/${githubBase}`;
+  }
+  // config.json is BRANCH-OWNED, so it must never choose the base in CI: a
+  // PR could set baseRef to HEAD, empty the diff, and disable every check.
+  // Locally it is a convenience only (local runs are feedback, CI is the
+  // enforcement point). In CI the base comes from env/flags/origin/HEAD or
+  // the run fails closed.
+  if (config.baseRef && !isCI()) {
+    return config.baseRef;
+  }
+  const originHead = git(['symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD'], {
+    allowFailure: true,
+  });
+  if (originHead) {
+    return originHead.trim().replace(/^refs\/remotes\//, '');
+  }
+  return null;
+}
+
+/** Parse `git diff --name-status -z` into a de-duplicated changed-path list. */
+function parseNameStatusZ(raw) {
+  const tokens = raw.split('\0');
+  const entries = new Map();
+  const add = (path, status) => {
+    if (path && !entries.has(normalizePath(path))) {
+      entries.set(normalizePath(path), status);
+    }
+  };
+  let i = 0;
+  while (i < tokens.length) {
+    const status = tokens[i];
+    if (!status) {
+      i++;
+      continue;
+    }
+    if (/^[RC]\d*$/.test(status)) {
+      // Rename/copy: the source path effectively left (deleted) and the
+      // destination arrived.
+      add(tokens[i + 1], 'D');
+      add(tokens[i + 2], status[0]);
+      i += 3;
+    } else {
+      add(tokens[i + 1], status[0]);
+      i += 2;
+    }
+  }
+  return [...entries].map(([path, status]) => ({ path, status }));
+}
+
+/**
+ * Validate the parsed policy shape strictly. Returns an error string or null.
+ * A malformed catalog field must never degrade to "no rule" (fail closed).
+ */
+function validatePolicyShape(parsed) {
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return 'policy is not a JSON object';
+  }
+  if (parsed.attribution !== 'allow' && parsed.attribution !== 'human-only') {
+    return 'attribution must be "allow" or "human-only"';
+  }
+  const isStringList = (value) =>
+    Array.isArray(value) && value.every((entry) => typeof entry === 'string' && entry.length > 0);
+  if (parsed.botAllow !== undefined && !isStringList(parsed.botAllow)) {
+    return 'botAllow must be an array of non-empty strings';
+  }
+  if (!parsed.catalog || typeof parsed.catalog !== 'object' || Array.isArray(parsed.catalog)) {
+    return 'catalog must be an object';
+  }
+  for (const key of ['identities', 'trailerKeys', 'bylines', 'bylineRegexSources']) {
+    if (parsed.catalog[key] !== undefined && !isStringList(parsed.catalog[key])) {
+      return `catalog.${key} must be an array of non-empty strings`;
+    }
+  }
+  return null;
+}
+
+/**
+ * Load the attribution policy from its TRUSTED source. The base ref's committed
+ * policy.json governs: a pull request cannot relax the rule for itself by
+ * editing the file, whichever guard dir BUILD_GUARD_DIR points at. When the
+ * base ref has no policy.json (the kit there predates 0.5.0):
+ *   - guard files unchanged in this diff -> the guard-dir copy equals the base
+ *     copy, so it is read; a 0.5.0 gate with no policy at all is a partial kit
+ *     and fails closed;
+ *   - guard files changed -> the branch copy is untrusted; attribution is not
+ *     evaluated (returned policy null) and guard-integrity already forces a
+ *     human merge (exit 2).
+ * Returns { policy } (policy may be null with `skipped` set) or { error }.
+ */
+function loadPolicy(baseRef, guardDirRel, trustBranchConfig) {
+  // A null baseRef (--message mode) reads this checkout's policy.json directly.
+  let raw =
+    baseRef === null
+      ? null
+      : git(['show', `${baseRef}:${guardDirRel}policy.json`], { allowFailure: true });
+  let origin = `${baseRef}:${guardDirRel}policy.json`;
+  if (raw === null) {
+    if (!trustBranchConfig) {
+      return {
+        policy: null,
+        skipped: `base ref ${baseRef} has no policy.json and guard files changed in this diff; attribution not evaluated (guard-integrity requires a human merge).`,
+      };
+    }
+    const policyPath = join(SCRIPT_DIR, 'policy.json');
+    if (!existsSync(policyPath)) {
+      return {
+        error: `policy.json missing at ${policyPath}${baseRef === null ? '' : ` and absent at ${baseRef}`}`,
+      };
+    }
+    try {
+      raw = readFileSync(policyPath, 'utf8');
+    } catch (error) {
+      return { error: `policy.json unreadable at ${policyPath}: ${error.message}` };
+    }
+    origin = policyPath;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    return { error: `policy.json at ${origin} is not valid JSON: ${error.message}` };
+  }
+  const shapeError = validatePolicyShape(parsed);
+  if (shapeError) {
+    return { error: `policy.json at ${origin} is malformed (${shapeError})` };
+  }
+  const lower = (values) => (values ?? []).map((value) => value.toLowerCase());
+  const catalog = parsed.catalog;
+  try {
+    return {
+      policy: {
+        attribution: parsed.attribution,
+        botAllow: lower(parsed.botAllow),
+        identities: lower(catalog.identities),
+        trailerKeys: lower(catalog.trailerKeys),
+        bylines: lower(catalog.bylines),
+        bylineRegexes: (catalog.bylineRegexSources ?? []).map((source) => new RegExp(source, 'i')),
+      },
+    };
+  } catch (error) {
+    return { error: `policy.json at ${origin} has an invalid catalog regex: ${error.message}` };
+  }
+}
+
+const ATTRIBUTION_FIX =
+  'Under git.attribution=human-only, remove the AI attribution (amend or rebase the commit, edit the PR body) and run build guard sync so the agent CLIs stop adding it.';
+
+/**
+ * Bot login for a git identity, lower-cased, or null. Recognises the
+ * `<login>[bot]` display name and the GitHub bot address
+ * `<id>+<login>[bot]@users.noreply.github.com`.
+ */
+function botLogin(name, email) {
+  const trimmedName = (name || '').trim();
+  if (/\[bot\]$/i.test(trimmedName)) {
+    return trimmedName.toLowerCase();
+  }
+  const match = /^(?:\d+\+)?([^@]+\[bot\])@users\.noreply\.github\.com$/i.exec((email || '').trim());
+  return match ? match[1].toLowerCase() : null;
+}
+
+/** Scan free text (a commit body or PR body) for attribution signatures. */
+function scanAttributionText(policy, text, file, addFinding) {
+  const lowerText = text.toLowerCase();
+  for (const rawLine of text.split('\n')) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    const lowerLine = line.toLowerCase();
+    const coauthor = /^co-authored-by:\s*(.*)$/i.exec(line);
+    if (coauthor) {
+      addFinding('attribution', 'co-authored-by', file, `Co-authored-by trailer present (${coauthor[1].trim()})`, ATTRIBUTION_FIX);
+      continue;
+    }
+    for (const key of policy.trailerKeys) {
+      if (lowerLine.startsWith(`${key}:`)) {
+        addFinding('attribution', 'agent-trailer', file, `agent trailer present (${line})`, ATTRIBUTION_FIX);
+      }
+    }
+    for (const regex of policy.bylineRegexes) {
+      if (regex.test(line)) {
+        addFinding('attribution', 'agent-byline', file, `agent byline present (${line})`, ATTRIBUTION_FIX);
+      }
+    }
+  }
+  for (const byline of policy.bylines) {
+    if (lowerText.includes(byline)) {
+      addFinding('attribution', 'agent-byline', file, `agent byline present (${byline})`, ATTRIBUTION_FIX);
+    }
+  }
+  for (const identity of policy.identities) {
+    if (lowerText.includes(identity)) {
+      addFinding('attribution', 'agent-identity', file, `agent identity present (${identity})`, ATTRIBUTION_FIX);
+    }
+  }
+}
+
+/**
+ * Scan every non-merge commit in mergeBase..HEAD: identities and message.
+ * Fields and records are NUL-separated: git refuses NUL bytes in commit
+ * messages and identities, so no message content can forge a boundary (a
+ * printable separator such as U+001E could). Each record is exactly six
+ * fields; the hex object id (SHA-1 or SHA-256) guards alignment.
+ */
+function scanAttributionCommits(policy, mergeBase, addFinding) {
+  const raw =
+    git([
+      'log',
+      '-z',
+      '--no-merges',
+      '--format=%H%x00%an%x00%ae%x00%cn%x00%ce%x00%B',
+      `${mergeBase}..HEAD`,
+    ]) ?? '';
+  const tokens = raw.split('\u0000');
+  for (let index = 0; index + 5 < tokens.length; index += 6) {
+    const [sha, authorName, authorEmail, committerName, committerEmail, body] = tokens.slice(
+      index,
+      index + 6
+    );
+    // SHA-1 (40) or SHA-256 (64) object ids.
+    if (!/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/.test(sha)) {
+      throw new Error(`unexpected git log record alignment at token ${index}`);
+    }
+    const file = `commit ${sha.slice(0, 12)}`;
+    for (const [role, name, email] of [
+      ['author', authorName, authorEmail],
+      ['committer', committerName, committerEmail],
+    ]) {
+      const lowerEmail = (email || '').trim().toLowerCase();
+      if (policy.identities.includes(lowerEmail)) {
+        addFinding('attribution', 'agent-identity', file, `${role} ${lowerEmail} is an AI agent identity`, ATTRIBUTION_FIX);
+      }
+      const bot = botLogin(name, email);
+      if (bot && !policy.botAllow.includes(bot)) {
+        addFinding('attribution', 'bot-identity', file, `${role} ${bot} is a bot identity not in policy.botAllow`, ATTRIBUTION_FIX);
+      }
+    }
+    scanAttributionText(policy, body, file, addFinding);
+  }
+}
+
+/**
+ * Pull-request body for the hosted run: BUILD_GUARD_PR_BODY_FILE (any CI), else
+ * the GitHub event payload. Null when neither is available (local runs, merge
+ * queues); the PR event re-runs on `edited`, so body enforcement lives there.
+ */
+function loadPullRequestBody() {
+  const bodyFile = process.env.BUILD_GUARD_PR_BODY_FILE;
+  if (bodyFile && existsSync(bodyFile)) {
+    return readFileSync(bodyFile, 'utf8');
+  }
+  const eventPath = process.env.GITHUB_EVENT_PATH;
+  if (eventPath && existsSync(eventPath)) {
+    try {
+      const event = JSON.parse(readFileSync(eventPath, 'utf8'));
+      const body = event?.pull_request?.body;
+      if (typeof body === 'string') return body;
+    } catch {
+      // A malformed event payload only means no body is available.
+    }
+  }
+  return null;
+}
+
+function compileSecretMatchers(config) {
+  const matchers = SECRET_PATTERNS.map((entry) => ({
+    rule: entry.rule,
+    regex: new RegExp(entry.source, entry.caseInsensitive ? 'i' : ''),
+  }));
+  const extra = Array.isArray(config.extraSecretPatterns) ? config.extraSecretPatterns : [];
+  for (const source of extra) {
+    matchers.push({ rule: `config-secret:${source}`, regex: new RegExp(source) });
+  }
+  return matchers;
+}
+
+function scanAddedLines(diff, matchers, addFinding) {
+  let currentFile = '';
+  let inFileHeader = false;
+  let sawSourceHeader = false;
+  for (const rawLine of diff.split('\n')) {
+    if (rawLine.startsWith('diff --git ')) {
+      currentFile = '';
+      inFileHeader = true;
+      sawSourceHeader = false;
+      continue;
+    }
+    if (inFileHeader && rawLine.startsWith('--- ')) {
+      sawSourceHeader = true;
+      continue;
+    }
+    if (inFileHeader && sawSourceHeader && rawLine.startsWith('+++ ')) {
+      const next = rawLine.slice(4);
+      currentFile =
+        next === '/dev/null' ? '' : normalizePath(next.startsWith('b/') ? next.slice(2) : next);
+      sawSourceHeader = false;
+      continue;
+    }
+    if (rawLine.startsWith('@@ ')) {
+      inFileHeader = false;
+      sawSourceHeader = false;
+      continue;
+    }
+    if (!currentFile || !rawLine.startsWith('+')) {
+      continue;
+    }
+    const line = rawLine.slice(1);
+    for (const matcher of matchers) {
+      matcher.regex.lastIndex = 0;
+      if (matcher.regex.test(line)) {
+        addFinding(
+          'secret-scan',
+          matcher.rule,
+          currentFile,
+          `potential secret in an added line (${matcher.rule})`,
+          'Remove the credential and rotate it; never commit secrets.'
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Restricted glob matcher for deny PATHS: `*` matches within a path segment,
+ * `**` matches across segments. Deliberately tiny — no npm glob library at
+ * gate time.
+ */
+function globToRegex(pattern) {
+  // `**/` matches zero or more whole directories (so `**/*.log` matches a
+  // root-level `debug.log`); a bare `**` matches anything including slashes.
+  const parts = pattern.split(/\*\*\//);
+  const segment = (part) =>
+    part
+      .split('**')
+      .map((piece) =>
+        piece
+          .split('*')
+          .map((literal) => literal.replace(/[.+^${}()|[\]\\?]/g, '\\$&'))
+          .join('[^/]*')
+      )
+      .join('.*');
+  const source = parts.map(segment).join('(?:[^/]+/)*');
+  return new RegExp(`^${source}$`);
+}
+
+function compileArtifactMatchers(config) {
+  // defaultDenyPaths and extraDenyPaths are GLOBS (path patterns);
+  // extraArtifactPatterns are raw regex sources for advanced consumers.
+  // `origin` records whether a matcher came from the generated defaults or the
+  // consumer's own extras: allowPaths may exempt a path from a DEFAULT deny
+  // (a repo that commits dist/ on purpose) but never from an extra the
+  // consumer added itself.
+  const matchers = [];
+  for (const source of Array.isArray(MANIFEST.defaultDenyPaths) ? MANIFEST.defaultDenyPaths : []) {
+    matchers.push({ source, regex: globToRegex(source), origin: 'default' });
+  }
+  for (const source of Array.isArray(config.extraDenyPaths) ? config.extraDenyPaths : []) {
+    matchers.push({ source, regex: globToRegex(source), origin: 'extra' });
+  }
+  for (const source of Array.isArray(config.extraArtifactPatterns)
+    ? config.extraArtifactPatterns
+    : []) {
+    matchers.push({ source, regex: new RegExp(source), origin: 'extra' });
+  }
+  return matchers;
+}
+
+function compileAllowMatchers(config) {
+  const globs = Array.isArray(config.allowPaths) ? config.allowPaths : [];
+  return globs
+    .filter((source) => typeof source === 'string' && source.length > 0)
+    .map((source) => ({ source, regex: globToRegex(source) }));
+}
+
+function renderHuman(baseRef, findings, changedCount) {
+  const lines = [];
+  for (const finding of findings) {
+    const label = finding.check === 'guard-integrity' ? 'Warning' : 'Error';
+    lines.push(`${label}: [${finding.check}] ${finding.file}: ${finding.message}`);
+    if (finding.fix) {
+      lines.push(`  fix: ${finding.fix}`);
+    }
+  }
+  if (findings.length === 0) {
+    lines.push(`OK: guard checks passed (${changedCount} changed file(s) vs ${baseRef}).`);
+  }
+  return lines.join('\n');
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.listChecks) {
+    process.stdout.write(`${JSON.stringify(MANIFEST, null, 2)}\n`);
+    process.exit(0);
+  }
+
+  const config = loadConfig();
+  if (args.staged) {
+    const findings = [];
+    const addFinding = (check, rule, file, message, fix) => {
+      findings.push({ check, rule, file, message, fix });
+    };
+    if (MANIFEST.checks.secretScan) {
+      const stagedDiff = git([
+        'diff',
+        '--cached',
+        '--no-ext-diff',
+        '--no-color',
+        '--src-prefix=a/',
+        '--dst-prefix=b/',
+        '--unified=0',
+        '--diff-filter=ACMR',
+      ]);
+      // Staged checks use only the generated catalog. Branch-owned custom
+      // regexes are reserved for the hosted path, where guard changes make
+      // config untrusted before regex compilation.
+      scanAddedLines(stagedDiff, compileSecretMatchers({}), addFinding);
+    }
+    const deduped = [...new Map(findings.map((finding) => [
+      `${finding.check}\u0000${finding.rule}\u0000${finding.file}`,
+      finding,
+    ])).values()];
+    if (args.formatJson) {
+      process.stdout.write(
+        `${JSON.stringify({ baseRef: 'staged-index', mergeBase: null, findings: deduped }, null, 2)}\n`
+      );
+    } else if (deduped.length === 0) {
+      process.stdout.write('OK: guard staged secret scan passed.\n');
+    } else {
+      process.stderr.write(`${renderHuman('staged index', deduped, 0)}\n`);
+    }
+    process.exit(deduped.length === 0 ? 0 : 1);
+  }
+
+  if (args.message !== null) {
+    const findings = [];
+    const addFinding = (check, rule, file, message, fix) => {
+      findings.push({ check, rule, file, message, fix });
+    };
+    if (MANIFEST.checks.attribution) {
+      const loaded = loadPolicy(null, '', true);
+      if (loaded.error) {
+        addFinding(
+          'attribution',
+          'policy-unusable',
+          'policy.json',
+          `guard policy is unusable (${loaded.error}).`,
+          'Re-run: build init --guardrails --reinstall-guard, then build guard sync, and commit .build-project/guard/.'
+        );
+      } else if (loaded.policy.attribution === 'human-only') {
+        const text = readFileSync(args.message === '-' ? 0 : args.message, 'utf8');
+        scanAttributionText(loaded.policy, text, 'commit message', addFinding);
+      }
+    }
+    const deduped = [...new Map(findings.map((finding) => [
+      `${finding.check}\u0000${finding.rule}\u0000${finding.file}`,
+      finding,
+    ])).values()];
+    if (args.formatJson) {
+      process.stdout.write(
+        `${JSON.stringify({ baseRef: 'commit-message', mergeBase: null, findings: deduped }, null, 2)}\n`
+      );
+    } else if (deduped.length === 0) {
+      process.stdout.write('OK: guard commit message check passed.\n');
+    } else {
+      process.stderr.write(`${renderHuman('commit message', deduped, 0)}\n`);
+    }
+    process.exit(deduped.length === 0 ? 0 : 1);
+  }
+
+  const emitFailure = (rule, message, fix, check = 'git') => {
+    process.stderr.write(`Error: ${message}\n`);
+    process.stderr.write(`  fix: ${fix}\n`);
+    if (args.formatJson) {
+      process.stdout.write(
+        `${JSON.stringify(
+          { baseRef: null, mergeBase: null, findings: [{ check, rule, file: '', message, fix }] },
+          null,
+          2
+        )}\n`
+      );
+    }
+    process.exit(1);
+  };
+
+  const baseRef = resolveBaseRef(config, args.base);
+  if (!baseRef) {
+    emitFailure(
+      'base-resolution',
+      'cannot determine a base ref (fail closed).',
+      'Pass --base <ref>, set BUILD_GUARD_BASE_REF, set config.json baseRef, or ensure origin/HEAD resolves.'
+    );
+  }
+
+  if (git(['rev-parse', '--verify', '--quiet', baseRef], { allowFailure: true }) === null) {
+    emitFailure(
+      'base-resolution',
+      `cannot resolve base ref '${baseRef}' (fail closed).`,
+      `Fetch the base branch (git fetch origin) or set BUILD_GUARD_BASE_REF / config.json baseRef to a resolvable ref.`
+    );
+  }
+
+  const mergeBaseRaw = git(['merge-base', baseRef, 'HEAD'], { allowFailure: true });
+  const mergeBase = mergeBaseRaw ? mergeBaseRaw.trim() : '';
+  if (!mergeBase) {
+    emitFailure(
+      'shallow-clone',
+      `no merge base between '${baseRef}' and HEAD (likely a shallow clone).`,
+      'Use fetch-depth: 0 in your CI checkout, or run git fetch --unshallow, then retry.'
+    );
+  }
+
+  const repoRoot = normalizePath(git(['rev-parse', '--show-toplevel']).trim());
+  const guardDir = `${normalizePath(relative(repoRoot, SCRIPT_DIR))}/`;
+
+  // Deletions (D) are included: deleting a guard file is a change the
+  // guard-integrity check must see. Per-check policy on deletions:
+  //   guard-integrity: sees them (that is the point);
+  //   artifact-paths:  skips them (removing a committed artifact is cleanup);
+  //   secret-scan:     skips naturally (deleted files add no lines).
+  const changedEntries = parseNameStatusZ(
+    git(['diff', '--name-status', '-z', '-M', '--diff-filter=ACDMRT', mergeBase, 'HEAD']) ?? ''
+  );
+  const changedFiles = changedEntries.map((entry) => entry.path);
+  const presentFiles = changedEntries
+    .filter((entry) => entry.status !== 'D')
+    .map((entry) => entry.path);
+
+  const findings = [];
+  const addFinding = (check, rule, file, message, fix) => {
+    findings.push({ check, rule, file, message, fix });
+  };
+
+  // Check 3 (guard integrity) runs FIRST, before any consumer-config-derived
+  // matcher executes: config.json is branch-owned, so a PR could plant a
+  // pathological regex (ReDoS) in extraSecretPatterns to hang or hard-fail
+  // the run before the guard-change verdict is reached. When guard files
+  // changed, the branch config is untrusted — content checks still run, but
+  // with BUILT-IN matchers only.
+  const guardChanged = [];
+  if (MANIFEST.checks.guardIntegrity) {
+    for (const entry of changedEntries) {
+      if (!isUnderGuardNamespace(entry.path, guardDir)) {
+        continue;
+      }
+      guardChanged.push(entry.path);
+      const caseVariant = !entry.path.startsWith(guardDir);
+      addFinding(
+        'guard-integrity',
+        caseVariant ? 'guard-namespace-case-variant' : 'guard-change',
+        entry.path,
+        caseVariant
+          ? 'case-variant path collides with the guard directory namespace'
+          : 'gate machinery changed under the guard directory',
+        caseVariant
+          ? 'Remove the path; on case-insensitive filesystems it materializes inside the guard directory.'
+          : 'Land guard changes via build init --guardrails, or require a human merge.'
+      );
+    }
+  }
+  const trustBranchConfig = guardChanged.length === 0;
+  const effectiveConfig = trustBranchConfig ? config : {};
+  if (!trustBranchConfig) {
+    process.stderr.write(
+      'Info: guard files changed in this diff; consumer config.json is untrusted for this run (built-in checks only).\n'
+    );
+  }
+
+  // Attribution policy from its trusted source (the base ref's copy; see
+  // loadPolicy). Unusable policy fails closed; absent-at-base with guard
+  // changes is skipped because guard-integrity already forces a human merge.
+  let policy = null;
+  if (MANIFEST.checks.attribution) {
+    const loaded = loadPolicy(baseRef, guardDir, trustBranchConfig);
+    if (loaded.error) {
+      emitFailure(
+        'policy-unusable',
+        `guard policy is unusable (${loaded.error}).`,
+        'Re-run: build init --guardrails --reinstall-guard, then build guard sync, and commit .build-project/guard/.',
+        'attribution'
+      );
+    }
+    policy = loaded.policy;
+    if (loaded.skipped && !args.formatJson) {
+      process.stderr.write(`Info: ${loaded.skipped}\n`);
+    }
+  }
+
+  // Check 1: secrets in every commit addition in the PR range. Scanning the
+  // commit history, rather than only the endpoint diff, catches credentials
+  // that were committed and removed before the branch reached its final tree.
+  if (MANIFEST.checks.secretScan) {
+    const matchers = compileSecretMatchers(effectiveConfig);
+    const historyDiff = git([
+      'log',
+      '--format=',
+      '--no-ext-diff',
+      '--no-color',
+      '--no-merges',
+      '--src-prefix=a/',
+      '--dst-prefix=b/',
+      '-p',
+      `${mergeBase}..HEAD`,
+    ]);
+    scanAddedLines(historyDiff, matchers, addFinding);
+    const endpointDiff = git([
+      'diff',
+      '--no-ext-diff',
+      '--no-color',
+      '--src-prefix=a/',
+      '--dst-prefix=b/',
+      mergeBase,
+      'HEAD',
+    ]);
+    scanAddedLines(endpointDiff, matchers, addFinding);
+  }
+
+  // Check 2: artifact paths.
+  if (MANIFEST.checks.artifactPaths) {
+    const matchers = compileArtifactMatchers(effectiveConfig);
+    const allowMatchers = compileAllowMatchers(effectiveConfig);
+    // Deletions skipped: removing a committed artifact is cleanup, not a
+    // violation.
+    for (const file of presentFiles) {
+      const allowed = allowMatchers.some((matcher) => matcher.regex.test(file));
+      for (const matcher of matchers) {
+        if (allowed && matcher.origin === 'default') {
+          continue;
+        }
+        if (matcher.regex.test(file)) {
+          addFinding(
+            'artifact-paths',
+            `deny:${matcher.source}`,
+            file,
+            'artifact/generated path must not be committed',
+            'Remove the path from the commit and add it to .gitignore.'
+          );
+        }
+      }
+    }
+  }
+
+  // Check 4: attribution (human-only only). Uses the trusted policy loaded
+  // from the guard dir, never branch config, so a PR cannot relax it.
+  if (MANIFEST.checks.attribution && policy && policy.attribution === 'human-only') {
+    scanAttributionCommits(policy, mergeBase, addFinding);
+    const prBody = loadPullRequestBody();
+    if (prBody !== null) {
+      scanAttributionText(policy, prBody, 'pull-request-body', addFinding);
+    }
+  }
+
+  // De-duplicate findings by (check, rule, file).
+  const seen = new Set();
+  let deduped = [];
+  for (const finding of findings) {
+    const key = `${finding.check}\u0000${finding.rule}\u0000${finding.file}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    deduped.push(finding);
+  }
+
+  // Guard self-change escape hatch: honored only outside CI.
+  const allowSelfChange = process.env.BUILD_GUARD_ALLOW_SELF_CHANGE === '1' && !isCI();
+  let selfChangeSuppressed = false;
+  if (allowSelfChange) {
+    const before = deduped.length;
+    deduped = deduped.filter((finding) => finding.check !== 'guard-integrity');
+    selfChangeSuppressed = deduped.length !== before;
+  }
+
+  const guardFindings = deduped.filter((finding) => finding.check === 'guard-integrity');
+  const hardFindings = deduped.filter((finding) => finding.check !== 'guard-integrity');
+
+  let exitCode = 0;
+  if (hardFindings.length > 0) {
+    exitCode = 1;
+  } else if (guardFindings.length > 0) {
+    exitCode = 2;
+  }
+
+  if (args.formatJson) {
+    process.stdout.write(`${JSON.stringify({ baseRef, mergeBase, findings: deduped }, null, 2)}\n`);
+    process.exit(exitCode);
+  }
+
+  if (selfChangeSuppressed) {
+    process.stderr.write('Info: guard self-change allowed (BUILD_GUARD_ALLOW_SELF_CHANGE=1, not CI).\n');
+  }
+  const rendered = renderHuman(baseRef, deduped, changedFiles.length);
+  const stream = exitCode === 0 ? process.stdout : process.stderr;
+  stream.write(`${rendered}\n`);
+  if (exitCode === 2) {
+    stream.write('Guard machinery changed: this requires a human merge (exit 2).\n');
+  }
+  process.exit(exitCode);
+}
+
+// This module is an EXECUTABLE gate, not a library: it runs main() (which calls
+// process.exit) at import time. Do not export or import its helpers — any
+// import would execute the gate. Tests exercise it via subprocess execution
+// (see tests/unit/guard-kit/check-script.test.ts), never by importing.
+try {
+  main();
+} catch (error) {
+  process.stderr.write(
+    `Error: guard check failed - ${error instanceof Error ? error.message : String(error)}\n`
+  );
+  process.exit(1);
+}