@poetic-ai/poetic 1.42.0

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

@@ -0,0 +1,777 @@
+#!/usr/bin/env node
+/**
+ * Poetic 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 Poetic, no npm, and no network.
+ *
+ * Runs four check families over the diff between a base ref and HEAD:
+ *   1. baseline-anti-inflation: ratchet baseline JSONs under baselines/ may
+ *      only shrink. Any per-key count increase, new key, or a surviving count
+ *      retyped away from number fails. A baseline file that is new at the base
+ *      ref is skipped (introducing a ratchet is a gate-critical human merge).
+ *   2. secret-scan: added diff lines matched against provider key formats plus
+ *      config.json extraSecretPatterns.
+ *   3. artifact-paths: changed paths matched against generated deny defaults
+ *      plus config.json extraDenyPaths / extraArtifactPatterns.
+ *   4. guard-integrity: any changed path under this guard directory (check.mjs,
+ *      config.json, baselines) is a gate-critical finding. Matching is
+ *      case-INSENSITIVE (a case-variant path like .poetic/Guard/x collides with
+ *      the guard dir on case-insensitive filesystems). EXEMPTION: a plain
+ *      'M' modification of a baselines/*.json file that is a pure shrink/removal
+ *      (verified via merge-base vs HEAD with the built-in count comparison, and
+ *      only while baseline-anti-inflation is on) is NOT a guard-integrity
+ *      finding and does NOT untrust branch config — routine ratchet-downs merge
+ *      without a human. Deletions, renames, new keys, inflation, retypes, and
+ *      unparseable baselines are never exempt.
+ *
+ * Exit codes:
+ *   0  clean.
+ *   1  hard failure (baseline inflation, secret, artifact path). 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,
+ * 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, mkdirSync, 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 = [
+  'baselineAntiInflation',
+  'secretScan',
+  'artifactPaths',
+  'guardIntegrity',
+];
+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: poetic 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: poetic init --guardrails --reinstall-guard\n'
+  );
+  process.exit(1);
+}
+
+// The guard directory is normally where this script lives. POETIC_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 POETIC_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.POETIC_GUARD_DIR
+    ? process.env.POETIC_GUARD_DIR
+    : dirname(fileURLToPath(import.meta.url))
+);
+
+// Baked-in provider key formats. Fixture/test values must not match these.
+const SECRET_PATTERNS = [
+  { rule: 'openai-key', source: 'sk-[a-zA-Z0-9]{48}' },
+  { rule: 'openai-project-key', source: 'sk-proj-[A-Za-z0-9_-]{20,}' },
+  { rule: 'openai-service-account-key', source: 'sk-svcacct-[a-zA-Z0-9_-]{20,}' },
+  { rule: 'openai-admin-key', source: 'sk-admin-[a-zA-Z0-9_-]{20,}' },
+  { rule: 'anthropic-key', source: 'sk-ant-[a-zA-Z0-9_-]{20,}' },
+  { rule: 'openrouter-key', source: 'sk-or-v1-[a-zA-Z0-9]{20,}' },
+  { rule: 'xai-key', source: 'xai-[a-zA-Z0-9]{20,}' },
+  { rule: 'google-key', source: 'AIzaSy[a-zA-Z0-9_-]{20,}' },
+  { rule: 'slack-token', source: 'xox[baprs]-[a-zA-Z0-9-]{10,}' },
+  { rule: 'github-token', source: 'gh[pousr]_[a-zA-Z0-9]{36,}' },
+  { rule: 'github-pat', source: 'github_pat_[a-zA-Z0-9_]{22,}' },
+];
+
+/** 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 (.poetic/Guard/x, .Poetic/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; the shrink-only baseline
+ * exemption stays case-EXACT (fail closed: a case-variant baseline path is a
+ * guard finding, never an exemption).
+ */
+function isUnderGuardNamespace(filePath, guardDirPrefix) {
+  return filePath.toLowerCase().startsWith(guardDirPrefix.toLowerCase());
+}
+
+/**
+ * Escape a baseline object key (or array item) for use in a flattened path.
+ * The separators '.' and '|' plus the escape character itself are escaped so
+ * distinct JSON structures can never flatten to colliding paths — without
+ * this, base {"a.b": 5} vs head {"a": {"b": 2}, "a.b": 9} would collide and
+ * the decoy could mask a count increase (baseline keys are commonly file
+ * paths, which contain dots).
+ */
+function escapeBaselineKey(key) {
+  return key.replace(/[\\.|]/g, (ch) => `\\${ch}`);
+}
+
+// Flattened paths are rooted at '$' so the root value itself has a path
+// distinct from every child (an empty-string key yields '$.', not '$').
+const BASELINE_ROOT_PATH = '$';
+
+/**
+ * Flattens a baseline JSON value into countable entries.
+ * - number leaf -> { "<path>": n }
+ * - string array leaf -> { "<path>|<item>": 1 } (identity sets)
+ * - other scalars are ignored (generatedAt, regex sources, scan roots).
+ */
+function flattenBaselineCounts(value, path = BASELINE_ROOT_PATH, out = {}) {
+  if (typeof value === 'number') {
+    out[path] = value;
+    return out;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      if (typeof item === 'string') {
+        out[`${path}|${escapeBaselineKey(item)}`] = 1;
+      }
+    }
+    return out;
+  }
+  if (value && typeof value === 'object') {
+    for (const [key, child] of Object.entries(value)) {
+      flattenBaselineCounts(child, `${path}.${escapeBaselineKey(key)}`, out);
+    }
+  }
+  return out;
+}
+
+/**
+ * Records the JSON type of every path (leaves AND containers). Combined with
+ * the generalized type comparison in compareBaselineCounts, this makes any
+ * base-vs-head type change at a surviving path a violation, so a count cannot
+ * be silently retyped away — not to a scalar (5 -> "999"), not to a container
+ * (5 -> {} or {note:"x"}, which flattens to no counts and would otherwise
+ * read as a clean removal), and not via container swaps (["x"] -> {note:"x"},
+ * or replacing the whole file's object with an array/scalar).
+ */
+function collectLeafTypes(value, path = BASELINE_ROOT_PATH, out = {}) {
+  if (value === null || typeof value !== 'object') {
+    // typeof null is 'object'; record it distinctly so null cannot alias an
+    // object container in the type comparison.
+    out[path] = value === null ? 'null' : typeof value;
+    return out;
+  }
+  if (Array.isArray(value)) {
+    out[path] = 'array';
+    return out;
+  }
+  out[path] = 'object';
+  for (const [key, child] of Object.entries(value)) {
+    collectLeafTypes(child, `${path}.${escapeBaselineKey(key)}`, out);
+  }
+  return out;
+}
+
+/** Returns violation objects (rule/message/fix) for a single baseline file. */
+function compareBaselineCounts(baseCounts, headCounts, baseTypes, headTypes) {
+  const violations = [];
+  for (const [key, headValue] of Object.entries(headCounts)) {
+    const baseValue = baseCounts[key];
+    if (baseValue === undefined) {
+      violations.push({
+        rule: 'new-baseline-key',
+        message: `new baseline key: ${key} (${headValue})`,
+        fix: 'Remove the new baseline key, or land it as a gate-critical human merge.',
+      });
+    } else if (headValue > baseValue) {
+      violations.push({
+        rule: 'count-increase',
+        message: `baseline count increased: ${key} (${baseValue} -> ${headValue})`,
+        fix: 'Reduce the count to at most the base value; baselines only shrink.',
+      });
+    }
+  }
+  // Generalized retype rule: any path present at BOTH base and head whose JSON
+  // type changed is a violation. Removals (head type undefined) stay legal —
+  // that is the shrink direction. This closes container swaps that carry no
+  // counts on either side (array -> object, object -> scalar, root retypes).
+  for (const [key, baseType] of Object.entries(baseTypes)) {
+    const headType = headTypes[key];
+    if (headType !== undefined && headType !== baseType) {
+      violations.push({
+        rule: 'count-retype',
+        message: `baseline value retyped (must keep its type): ${key} (${baseType} -> ${headType})`,
+        fix: 'Keep baseline value types stable; land schema changes as a gate-critical human merge.',
+      });
+    }
+  }
+  return violations;
+}
+
+/**
+ * Shrink-only baseline exemption for guard-integrity.
+ *
+ * Security-critical: this decides whether a changed guard-dir file skips the
+ * guard-integrity finding AND keeps branch config trusted. It runs inside the
+ * FIRST check block, before any consumer-config regex compiles, so it must use
+ * ONLY git show + JSON.parse + the built-in count helpers — it must never
+ * compile or evaluate anything derived from config.json (a branch could plant a
+ * ReDoS payload there).
+ *
+ * A file qualifies ONLY if ALL hold:
+ *   (a) it is under baselinesDir and ends with .json;
+ *   (b) its git status is a plain 'M' (parseNameStatusZ marks rename sources as
+ *       'D' and destinations as R/C — neither is 'M', so renames never qualify;
+ *       deletions are 'D', also never eligible);
+ *   (c) MANIFEST.checks.baselineAntiInflation is true (no validator otherwise);
+ *   (d) both merge-base and HEAD content parse as JSON;
+ *   (e) compareBaselineCounts over the flattened counts returns ZERO violations
+ *       (pure shrink/removal — no new key, no count increase, no retype).
+ * Any failure => not exempt (falls through to the normal guard-integrity path).
+ */
+function isShrinkOnlyBaselineChange(entry, mergeBase, baselinesDir) {
+  if (entry.status !== 'M') return false;
+  if (!(entry.path.startsWith(baselinesDir) && entry.path.endsWith('.json'))) return false;
+  if (!MANIFEST.checks.baselineAntiInflation) return false;
+  const baseContent = git(['show', `${mergeBase}:${entry.path}`], { allowFailure: true });
+  const headContent = git(['show', `HEAD:${entry.path}`], { allowFailure: true });
+  if (baseContent === null || headContent === null) return false;
+  let baseJson;
+  let headJson;
+  try {
+    baseJson = JSON.parse(baseContent);
+    headJson = JSON.parse(headContent);
+  } catch {
+    return false;
+  }
+  const violations = compareBaselineCounts(
+    flattenBaselineCounts(baseJson),
+    flattenBaselineCounts(headJson),
+    collectLeafTypes(baseJson),
+    collectLeafTypes(headJson)
+  );
+  return violations.length === 0;
+}
+
+// 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: POETIC_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,
+    updateBaseline: false,
+    listChecks: false,
+    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 === '--update-baseline') {
+      parsed.updateBaseline = true;
+    } else if (arg === '--list-checks') {
+      parsed.listChecks = true;
+    } 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.POETIC_GUARD_BASE_REF) {
+    return process.env.POETIC_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 }));
+}
+
+function compileSecretMatchers(config) {
+  const matchers = SECRET_PATTERNS.map((entry) => ({
+    rule: entry.rule,
+    regex: new RegExp(entry.source),
+  }));
+  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;
+}
+
+/**
+ * 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.
+  const globs = [
+    ...(Array.isArray(MANIFEST.defaultDenyPaths) ? MANIFEST.defaultDenyPaths : []),
+    ...(Array.isArray(config.extraDenyPaths) ? config.extraDenyPaths : []),
+  ];
+  const matchers = globs.map((source) => ({ source, regex: globToRegex(source) }));
+  for (const source of Array.isArray(config.extraArtifactPatterns)
+    ? config.extraArtifactPatterns
+    : []) {
+    matchers.push({ source, regex: new RegExp(source) });
+  }
+  return matchers;
+}
+
+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);
+  }
+
+  if (args.updateBaseline) {
+    if (isCI()) {
+      process.stderr.write('Error: refusing --update-baseline in CI.\n');
+      process.exit(1);
+    }
+    mkdirSync(join(SCRIPT_DIR, 'baselines'), { recursive: true });
+    process.stdout.write(
+      'Info: --update-baseline is dormant. No count-producing scanners exist yet, so\n' +
+        'baselines/ stays empty and anti-inflation has nothing to compare. The engine is\n' +
+        'present but inert until stack scanners are wired in a later phase.\n'
+    );
+    process.exit(0);
+  }
+
+  const config = loadConfig();
+  const emitFailure = (rule, message, fix) => {
+    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: 'git', 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 POETIC_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 POETIC_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))}/`;
+  const baselinesDir = `${normalizePath(relative(repoRoot, join(SCRIPT_DIR, 'baselines')))}/`;
+
+  // Deletions (D) are included: deleting a guard file or baseline is a change
+  // the guard-integrity check must see (a deleted baseline would otherwise
+  // bypass anti-inflation entirely). 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);
+  //   anti-inflation:  a deleted baseline is guard-integrity's finding.
+  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 4 (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.
+  // Shrink-only baseline exemption: a plain 'M' baselines/*.json that is a pure
+  // shrink/removal is a routine ratchet-down, not gate-machinery tampering. It
+  // skips the guard-integrity finding and keeps branch config trusted. The
+  // check uses only git show + JSON.parse + built-in helpers (no config regex),
+  // preserving the ordering property that no branch-owned pattern executes
+  // before the guard verdict.
+  const guardChanged = [];
+  if (MANIFEST.checks.guardIntegrity) {
+    for (const entry of changedEntries) {
+      if (!isUnderGuardNamespace(entry.path, guardDir)) {
+        continue;
+      }
+      // The shrink exemption requires the EXACT tracked case: a case-variant
+      // baseline path is namespace pollution, not a ratchet-down.
+      if (
+        entry.path.startsWith(guardDir) &&
+        isShrinkOnlyBaselineChange(entry, mergeBase, baselinesDir)
+      ) {
+        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 poetic 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'
+    );
+  }
+
+  // Check 1: baseline anti-inflation.
+  if (MANIFEST.checks.baselineAntiInflation) {
+    const baselineFiles = presentFiles.filter(
+      (file) => file.startsWith(baselinesDir) && file.endsWith('.json')
+    );
+    for (const file of baselineFiles) {
+      const baseContent = git(['show', `${mergeBase}:${file}`], { allowFailure: true });
+      if (baseContent === null) {
+        // New baseline at base: introducing a ratchet is gate-critical elsewhere.
+        continue;
+      }
+      let baseJson;
+      let headJson;
+      try {
+        baseJson = JSON.parse(baseContent);
+        headJson = JSON.parse(git(['show', `HEAD:${file}`], { allowFailure: true }) ?? 'null');
+      } catch {
+        addFinding(
+          'baseline-anti-inflation',
+          'unparseable-baseline',
+          file,
+          'baseline JSON is not parseable',
+          'Restore valid JSON for the baseline file.'
+        );
+        continue;
+      }
+      const violations = compareBaselineCounts(
+        flattenBaselineCounts(baseJson),
+        flattenBaselineCounts(headJson),
+        collectLeafTypes(baseJson),
+        collectLeafTypes(headJson)
+      );
+      for (const violation of violations) {
+        addFinding('baseline-anti-inflation', violation.rule, file, violation.message, violation.fix);
+      }
+    }
+  }
+
+  // Check 2: secrets in added lines.
+  if (MANIFEST.checks.secretScan) {
+    const matchers = compileSecretMatchers(effectiveConfig);
+    for (const file of presentFiles) {
+      // Pathspec is repo-root-relative; git runs from SCRIPT_DIR, so anchor
+      // at the repo root with (top) and add (literal) so filenames containing
+      // glob metacharacters ([, *, ?) are addressed literally. allowFailure
+      // is NOT used here: a diff failure for a known-changed path must fail
+      // the gate loudly, never read as an empty (secret-free) diff.
+      const diff = git(['diff', mergeBase, 'HEAD', '--', `:(top,literal)${file}`]);
+      for (const rawLine of diff.split('\n')) {
+        if (!rawLine.startsWith('+') || rawLine.startsWith('+++')) {
+          continue;
+        }
+        // Strip the diff marker so anchored consumer patterns (^MYCO_) match
+        // content at the start of an added line.
+        const line = rawLine.slice(1);
+        for (const matcher of matchers) {
+          if (matcher.regex.test(line)) {
+            addFinding(
+              'secret-scan',
+              matcher.rule,
+              file,
+              `potential secret in an added line (${matcher.rule})`,
+              'Remove the credential and rotate it; never commit secrets.'
+            );
+          }
+        }
+      }
+    }
+  }
+
+  // Check 3: artifact paths.
+  if (MANIFEST.checks.artifactPaths) {
+    const matchers = compileArtifactMatchers(effectiveConfig);
+    // Deletions skipped: removing a committed artifact is cleanup, not a
+    // violation.
+    for (const file of presentFiles) {
+      for (const matcher of matchers) {
+        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.'
+          );
+        }
+      }
+    }
+  }
+
+  // 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.POETIC_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 (POETIC_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);
+}