@dogfood-lab/verify 1.6.0 → 1.8.0

package/README.md

@@ -62,6 +62,28 @@ import { validateSchema } from '@dogfood-lab/verify/validators/schema.js';
 import { validateProvenance } from '@dogfood-lab/verify/validators/provenance.js';
 ```
 
+## CLI (`dogfood-verify`)
+
+The package ships a `dogfood-verify` bin with two verbs.
+
+**Verify** a submission (local dry-run / explain — never writes):
+
+```bash
+dogfood-verify --file submission.json --explain   # human verdict, reasons classified by who-fixes-it
+dogfood-verify --file submission.json --json       # machine-readable
+# exit: 0 accepted · 1 rejected · 2 operator error
+```
+
+**Lint** a policy file (VERIFY-F3, author-time — no submission needed):
+
+```bash
+dogfood-verify lint policies/repos/<org>/<repo>.yaml        # or global-policy.yaml
+dogfood-verify lint policies/global-policy.yaml --json      # for CI
+# exit: 0 clean or warnings-only · 1 errors · 2 operator error
+```
+
+`lint` runs the structural schema gate **plus** the data-independent predicate checks (`unknown_field`, `max_depth`, `node_budget`) over every `when` predicate, and emits an **advisory** warning on the `[]` footgun (a negative operator over a `[]` path fails open) with the fail-closed `not(any(...))` rewrite as a suggestion — never auto-applied, never a hard error. It is the `opa check` analogue. It **cannot** statically catch a `type_mismatch` or a fan-out overrun (both are data-dependent) and says so. Full contract + coverage boundary: [`docs/policy-lint.md`](https://github.com/dogfood-lab/testing-os/blob/main/docs/policy-lint.md).
+
 ## Submission envelope
 
 The full envelope shape is defined by `@dogfood-lab/schemas` (`dogfood-record-submission.schema.json`). Minimum required fields:
@@ -92,7 +114,8 @@ Discrimination happens by **class**, surfaced by `parseRejectionReason` (below).
 | Prefix | Source | Meaning |
 |---|---|---|
 | `schema:` | `validators/schema.js` | JSON Schema check on the submission/record envelope failed. The rest of the string carries the AJV path + message. |
-| `policy:` | `validators/policy.js` | Per-repo policy gate failed (forbidden tags, missing required fields, surface evidence/CI requirements, etc.). |
+| `policy:` | `validators/policy.js` | Per-repo policy gate failed (forbidden tags, missing required fields, surface evidence/CI requirements, or a declarative `when`/`custom_rules` predicate matched — see the [policy DSL](https://dogfood-lab.github.io/testing-os/handbook/policy-dsl/)). |
+| `policy-config:` | `validators/policy.js` | **VERIFY-F1.** A REPO custom-rule predicate hit an eval-time semantic fault the schema could not catch — an unknown leading field, a numeric operator against a non-number, or a depth/width/fan-out budget. The repo authored the bad rule, so the fix is the submitter's. (A malformed GLOBAL predicate is `VALIDATOR_FAULT_POLICY:` operational instead — see below.) |
 | `steps[<id>]:` | `validators/steps.js` | Step-level contract check failed on a specific step id (gate accumulation, ordering, evidence shape). |
 | `provenance:` | `validators/provenance.js` | The run was genuinely **absent / not confirmable** — a 404 from the provider API, or the run head did not match the submitted commit/repo. The submitter's payload points at a run that does not exist or does not bind. (Operational provider faults — 429/5xx/401/403 — are NOT this class; see `provenance-fault:` below.) |
 | `repo:` | `index.js` cross-field guard | `submission.repo` does not match the owner/repo encoded in `source.run_url` (anti-forgery guard). Emitted as `repo:mismatch: …`. |
@@ -105,7 +128,7 @@ Discrimination happens by **class**, surfaced by `parseRejectionReason` (below).
 | Prefix | Source | Meaning |
 |---|---|---|
 | `VALIDATOR_FAULT_SCHEMA:` | `runValidator('schema', …)` catch | Internal exception inside the schema validator. The rest of the string carries the thrown `.message`. |
-| `VALIDATOR_FAULT_POLICY:` | `runValidator('policy', …)` catch | Internal exception inside the policy validator. |
+| `VALIDATOR_FAULT_POLICY:` | `runValidator('policy', …)` catch | Internal exception inside the policy validator — including a **GLOBAL** declarative-rule predicate fault (VERIFY-F1): a broken `policies/global-policy.yaml` is an ops incident (the studio's own config), so its predicate fault throws here rather than bouncing to the submitter. The repo-authored counterpart is `policy-config:` submission-bad. |
 | `VALIDATOR_FAULT_STEPS:` | `runValidator('steps', …)` catch | Internal exception inside the steps validator. |
 | `VALIDATOR_FAULT_CONTRACT_SCHEMA_VERSION:` | `runValidator('contract_schema_version', …)` catch | The version gate was called with an unknown contract key (a programmer error at the call site, not a submission fault). |
 | `submission-malformed:` | `index.js` null/non-object early-return | The submission itself was `null` or not an object — a malfunctioning **dispatcher** sent garbage, not a submitter who authored a bad-but-shaped payload. Page ops / inspect the dispatch pipeline; do NOT bounce it to a submitter. |

package/cli-lint.js

@@ -0,0 +1,209 @@
+/**
+ * cli-lint.js (VERIFY-F3) — the `dogfood-verify lint <policy-file>` subcommand.
+ *
+ * A SEPARATE parse/render path from the verify CLI (cli.js): it takes a policy YAML
+ * (not a submission JSON) and reports static lint findings, so it does not share the
+ * verify arg parser or output. cli.js's `main` dispatcher routes the `lint` verb here
+ * and leaves the verify `run` path untouched. The exit contract mirrors that path:
+ *
+ *   0 — clean, or warnings-only (footgun advisories never block).
+ *   1 — one or more errors (schema-invalid, a static predicate fault, or unparseable YAML).
+ *   2 — operator error (file missing/unreadable, or a malformed invocation).
+ *
+ * YAML that fails to parse is exit 1 (a lint FINDING about the policy the author must fix —
+ * surfacing "line 4: bad indentation" is the lint's job), not exit 2. A file that does not
+ * exist is exit 2 (the author pointed at the wrong path). See docs/policy-lint.md.
+ */
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import yaml from 'js-yaml';
+
+import { lintPolicy, COVERAGE_NOTE } from './validators/lint-policy.js';
+
+/** Operator-error sentinel → exit 2 (distinct from a lint finding, which is exit 1). */
+class LintOperatorError extends Error {
+  constructor(message, hint) {
+    super(message);
+    this.name = 'LintOperatorError';
+    this.hint = hint;
+  }
+}
+
+const LINT_USAGE = `dogfood-verify lint — author-time static check for a policy file
+
+USAGE:
+  dogfood-verify lint <policy-file> [--json]
+
+WHAT IT CHECKS (no submission needed):
+  - structural validity against policy.schema.json
+  - every predicate's known leading field, combinator depth, and node budget
+  - an ADVISORY warning on the [] footgun (a negative op over a [] path fails open)
+
+It CANNOT statically catch a type_mismatch or a fanout_budget overrun — those depend
+on submission data. Run \`dogfood-verify --file <submission> --explain\` for that.
+
+OPTIONS:
+  --json        Machine-readable result for CI.
+  -h, --help    Show this help.
+
+EXIT CODES:
+  0  clean or warnings-only     1  errors found     2  operator error (bad flags / IO)`;
+
+/**
+ * Parse the lint argv (everything AFTER the `lint` verb). Accepts exactly one positional
+ * policy-file path plus optional `--json` / `--help`. Throws LintOperatorError (→ exit 2)
+ * on any malformed invocation.
+ *
+ * @param {string[]} argv
+ * @returns {{ help: boolean, file: string|null, json: boolean }}
+ */
+export function parseLintArgs(argv) {
+  let file = null;
+  let json = false;
+  let help = false;
+
+  for (const arg of argv) {
+    if (arg === '-h' || arg === '--help') { help = true; continue; }
+    if (arg === '--json') { json = true; continue; }
+    if (arg.startsWith('-')) {
+      throw new LintOperatorError(`unknown argument: ${arg}`, 'run `dogfood-verify lint --help` for usage');
+    }
+    if (file !== null) {
+      throw new LintOperatorError('more than one policy file given', 'lint one file at a time');
+    }
+    file = arg;
+  }
+
+  if (help) return { help: true, file: null, json: false };
+  if (file === null) {
+    throw new LintOperatorError('no policy file provided', 'dogfood-verify lint <policy-file>');
+  }
+  return { help: false, file, json };
+}
+
+/**
+ * Classify a policy file by its path so the report can name the origin (which decides the
+ * runtime fault class: global → operational, repo → submission-bad). Mirrors the
+ * `policies/global-policy.yaml` vs `policies/repos/<org>/<repo>.yaml` layout.
+ */
+export function originForPath(p) {
+  const norm = String(p).replace(/\\/g, '/');
+  if (/\/policies\/repos\//.test(norm)) return 'repo';
+  if (/(^|\/)global-policy\.yaml$/.test(norm)) return 'global';
+  return 'unknown';
+}
+
+/** Render the human (default) view of a lint result — verdict-first, ERROR before WARNING. */
+export function renderLintText(result, file) {
+  const lines = [];
+  const verdict = !result.ok ? 'ERRORS' : (result.warnings.length ? 'CLEAN (advisory warnings)' : 'CLEAN');
+  lines.push(`VERDICT: ${verdict}`);
+  lines.push('');
+  lines.push(`  file:   ${file}`);
+  lines.push(`  origin: ${result.origin}`);
+
+  if (result.errors.length) {
+    lines.push('');
+    lines.push(`ERRORS (${result.errors.length}):`);
+    for (const e of result.errors) {
+      const field = e.field ? ` — field "${e.field}"` : '';
+      lines.push(`  - [${e.label} ${e.code}] ${e.location}${field}`);
+      lines.push(`      ${e.message}`);
+    }
+  }
+
+  if (result.warnings.length) {
+    lines.push('');
+    lines.push(`WARNINGS (${result.warnings.length}) — advisory; the author confirms intent, nothing is auto-applied:`);
+    for (const w of result.warnings) {
+      lines.push(`  - [${w.label} ${w.code}] ${w.location} — field "${w.field}"`);
+      lines.push(`      ${w.message}`);
+      lines.push(`      ${w.suggestion}`);
+    }
+  }
+
+  if (result.ok && !result.warnings.length) {
+    lines.push('');
+    lines.push('No findings. The policy passes static lint.');
+  }
+
+  lines.push('');
+  lines.push(`note: ${result.coverageNote}`);
+  return lines.join('\n');
+}
+
+/** Build the machine-readable (--json) result. */
+export function buildLintJson(result, file) {
+  return {
+    file,
+    origin: result.origin,
+    ok: result.ok,
+    errors: result.errors,
+    warnings: result.warnings,
+    coverageNote: result.coverageNote,
+  };
+}
+
+/**
+ * Run the lint subcommand. Returns the exit code (does not call process.exit) so it is
+ * unit-testable with an injected stdout/stderr sink.
+ *
+ * @param {string[]} argv - args AFTER the `lint` verb
+ * @param {{ stdout?: (s: string) => void, stderr?: (s: string) => void }} [io]
+ * @returns {Promise<number>}
+ */
+export async function runLint(argv, io = {}) {
+  const out = io.stdout ?? ((s) => process.stdout.write(s + '\n'));
+  const err = io.stderr ?? ((s) => process.stderr.write(s + '\n'));
+
+  let opts;
+  try {
+    opts = parseLintArgs(argv);
+  } catch (e) {
+    err(`ERROR: ${e.message}`);
+    if (e.hint) err(`  hint: ${e.hint}`);
+    return 2;
+  }
+
+  if (opts.help) {
+    out(LINT_USAGE);
+    return 0;
+  }
+
+  const path = resolve(opts.file);
+  let raw;
+  try {
+    raw = readFileSync(path, 'utf-8');
+  } catch (e) {
+    err(`ERROR: could not read policy file: ${path} — ${e.message}`);
+    err('  hint: check the path exists and is readable');
+    return 2;
+  }
+
+  let doc;
+  try {
+    doc = yaml.load(raw);
+  } catch (e) {
+    // A YAML parse failure is a lint finding about the policy (exit 1), not an operator error.
+    const where = e && e.mark ? ` at line ${e.mark.line + 1}, column ${e.mark.column + 1}` : '';
+    const result = {
+      ok: false,
+      origin: originForPath(path),
+      errors: [{
+        label: 'policy-schema:',
+        code: 'yaml_parse',
+        location: '/',
+        message: `policy YAML failed to parse${where} — ${e.message}`,
+      }],
+      warnings: [],
+      coverageNote: COVERAGE_NOTE,
+    };
+    out(opts.json ? JSON.stringify(buildLintJson(result, path)) : renderLintText(result, path));
+    return 1;
+  }
+
+  const result = lintPolicy(doc, { origin: originForPath(path) });
+  out(opts.json ? JSON.stringify(buildLintJson(result, path)) : renderLintText(result, path));
+  return result.ok ? 0 : 1;
+}

package/cli.js

@@ -39,6 +39,7 @@ import yaml from 'js-yaml';
 
 import { verify, parseRejectionReason } from './index.js';
 import { stubProvenance, provenanceForProvider } from './validators/provenance.js';
+import { runLint } from './cli-lint.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -440,8 +441,27 @@ export async function run(argv, io = {}) {
   return record.verification?.status === 'accepted' ? 0 : 1;
 }
 
+/**
+ * Top-level dispatcher. The bin has two verbs:
+ *   - `dogfood-verify lint <policy-file>` → the author-time policy lint (VERIFY-F3, cli-lint.js).
+ *   - `dogfood-verify <flags>`            → the verify dry-run/explain (the original `run` path).
+ *
+ * Dispatching on `argv[0] === 'lint'` is a purely additive change: that token previously hit the
+ * verify parser's default arm and threw `unknown argument: lint`. The verify path is unchanged.
+ *
+ * @param {string[]} argv - process.argv.slice(2)
+ * @param {object} [io] - injected stdout/stderr/repoRoot for testing
+ * @returns {Promise<number>} exit code
+ */
+export async function main(argv, io = {}) {
+  if (argv[0] === 'lint') {
+    return runLint(argv.slice(1), io);
+  }
+  return run(argv, io);
+}
+
 // --- CLI entrypoint ---
 const isMain = process.argv[1] && resolve(process.argv[1]) === resolve(__dirname, 'cli.js');
 if (isMain) {
-  run(process.argv.slice(2)).then((code) => process.exit(code));
+  main(process.argv.slice(2)).then((code) => process.exit(code));
 }

package/index.js

@@ -265,6 +265,11 @@ export async function verify(submission, options) {
       if (policyRun.ok) {
         policyValid = policyRun.result.valid;
         reasons.push(...policyRun.result.errors.map(e => `policy: ${e}`));
+        // VERIFY-F1: a malformed REPO custom-rule predicate is a distinct
+        // `policy-config:` rejection (submission-bad — the repo authored the bad
+        // rule). A malformed GLOBAL predicate never reaches here; it throws and
+        // surfaces as VALIDATOR_FAULT_POLICY (operational) via the else branch.
+        reasons.push(...(policyRun.result.configErrors || []).map(e => `policy-config: ${e}`));
         warnings.push(...(policyRun.result.warnings || []).map(w => `policy: ${w}`));
       } else {
         reasons.push(policyRun.faultReason);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogfood-lab/verify",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "type": "module",
   "description": "Central verifier for testing-os. Validates submissions against schema and policy, produces persisted records.",
   "main": "index.js",
@@ -10,6 +10,7 @@
   "exports": {
     ".": "./index.js",
     "./cli.js": "./cli.js",
+    "./cli-lint.js": "./cli-lint.js",
     "./parse-rejection.js": "./parse-rejection.js",
     "./validators/*": "./validators/*",
     "./validators/*.js": "./validators/*.js"
@@ -21,6 +22,7 @@
   "files": [
     "index.js",
     "cli.js",
+    "cli-lint.js",
     "parse-rejection.js",
     "validators/",
     "README.md",

package/parse-rejection.js

@@ -23,7 +23,9 @@
  *
  * The prefix vocabulary below is enumerated from the ACTUAL emitters — it is
  * NOT invented:
- *   - verify/index.js:                schema:, policy:, steps[<id>]:,
+ *   - verify/index.js:                schema:, policy:, policy-config: (VERIFY-F1,
+ *                                     repo custom-rule predicate fault → submission-bad),
+ *                                     steps[<id>]:,
  *                                     provenance: (run absent → submission-bad),
  *                                     provenance-fault: (provider 429/5xx/401/403
  *                                       → operational), repo:,
@@ -62,6 +64,13 @@
 const LITERAL_PREFIXES = [
   // submission-bad
   { match: 'schema:', prefix: 'schema:', class: 'submission-bad' },
+  // VERIFY-F1: a malformed REPO custom-rule predicate (eval-time semantic fault the
+  // schema could not catch). submission-bad — the repo authored the bad policy YAML,
+  // so the fix belongs to the submitter, not studio ops. Ordered BEFORE `policy:`
+  // to keep the most-specific-first invariant (the tokens don't overlap — `policy:`
+  // ends at the colon, `policy-config:` continues with `-config:` — but the order is
+  // explicit). A malformed GLOBAL predicate is operational (VALIDATOR_FAULT_POLICY).
+  { match: 'policy-config:', prefix: 'policy-config:', class: 'submission-bad' },
   { match: 'policy:', prefix: 'policy:', class: 'submission-bad' },
   // operational — a provider-side provenance FAULT (429/5xx/401/403). The
   // adapter THROWS these (verify-A-002); index.js catches the throw and emits

package/validators/lint-policy.js

@@ -0,0 +1,120 @@
+/**
+ * Policy lint (VERIFY-F3)
+ *
+ * `lintPolicy(policyDoc, { origin })` is the author-time check behind the
+ * `dogfood-verify lint` verb: it validates a whole policy file WITHOUT a submission,
+ * batch-reporting every fault. It is the `opa check` analogue named (as a deferred
+ * companion) in docs/policy-dsl.md and specified in docs/policy-lint.md.
+ *
+ * Three passes, mirroring the runtime's own layering:
+ *   1. Structural gate — `validatePayload('policy', …)` against policy.schema.json (the same
+ *      gate loadGlobalPolicy / loadRepoPolicy run). Catches unknown op, malformed/banned field,
+ *      mixed node, value-arity, custom_rules-under-defaults, additionalProperties.
+ *   2. Static predicate walk — the data-independent semantic faults the schema cannot express:
+ *      unknown leading field, combinator over-depth, node budget (via predicate.js#lintPredicate).
+ *   3. `[]`-footgun advisory — a deterministic warning (never an error) on a negative op over a
+ *      `[]` path (via predicate.js#findEmptyArrayFootguns).
+ *
+ * Coverage boundary (the VERIFY-F2 over-claim lesson): `type_mismatch` and `fanout_budget` are
+ * DATA-DEPENDENT and cannot be caught statically. `coverageNote` says so — a clean lint is "no
+ * static fault and no footgun," NOT "this policy can never produce a policy-config: rejection."
+ */
+
+import { validatePayload } from '@dogfood-lab/schemas';
+import { lintPredicate, findEmptyArrayFootguns } from './predicate.js';
+
+/** Stated in every lint result so a clean verdict is never read as full coverage. */
+export const COVERAGE_NOTE =
+  'Static lint only — it cannot catch a `type_mismatch` (a numeric op over a non-number field) ' +
+  'or a `fanout_budget` overrun; both depend on submission data. Run ' +
+  '`dogfood-verify --file <submission> --explain` to exercise the data-dependent path.';
+
+/**
+ * Lint a parsed policy document.
+ *
+ * @param {unknown} policyDoc - The parsed policy YAML/JSON (any value; a non-object is reported
+ *   by the schema gate).
+ * @param {{ origin?: 'global'|'repo'|'unknown' }} [opts] - The policy's origin, used only for
+ *   reporting (the caller derives it from the file path).
+ * @returns {{
+ *   ok: boolean, origin: string, coverageNote: string,
+ *   errors: { label: string, code: string, location: string, field?: string, message: string }[],
+ *   warnings: { label: string, code: string, location: string, field: string, suggestion: string, message: string }[]
+ * }} `ok` is true iff there are no errors; warnings (footguns) never affect `ok`.
+ */
+export function lintPolicy(policyDoc, { origin = 'unknown' } = {}) {
+  const errors = [];
+  const warnings = [];
+
+  // 1. Structural schema gate.
+  const schema = validatePayload('policy', policyDoc);
+  for (const e of schema.errors) {
+    errors.push({
+      label: 'policy-schema:',
+      code: e.keyword || 'schema',
+      location: e.path || '/',
+      message: e.message || 'schema violation',
+    });
+  }
+
+  // 2 + 3. Static predicate walk + footgun advisory over every `when` location. Defensive: a
+  // schema-invalid doc may have malformed predicates; the walkers tolerate non-objects.
+  for (const { when, scope, location } of collectPredicates(policyDoc)) {
+    for (const f of lintPredicate(when, scope)) {
+      errors.push({ label: 'policy-config:', code: f.code, location, field: f.field, message: f.message });
+    }
+    for (const g of findEmptyArrayFootguns(when)) {
+      warnings.push({
+        label: 'policy-footgun:',
+        code: 'footgun-empty-array',
+        location,
+        field: g.field,
+        suggestion: g.suggestion,
+        message:
+          `negative operator "${g.op}" over the array path "${g.field}" fails OPEN on an empty or ` +
+          `absent array — the rule silently does not fire when there are no elements`,
+      });
+    }
+  }
+
+  return { ok: errors.length === 0, origin, errors, warnings, coverageNote: COVERAGE_NOTE };
+}
+
+/**
+ * Enumerate every `when` predicate in a policy with its evaluation scope and an operator-readable
+ * location. Walks the SAME two locations the runtime evaluates (validators/policy.js):
+ *   - `global_rules[].when` at scope `rule.scope || 'submission'`
+ *   - `surfaces.<surface>.custom_rules[].when` at scope `scenario_result`
+ * `custom_rules` under `defaults` is schema-forbidden, so it is not walked here — the structural
+ * gate already reports it if present (matching the runtime, which never evaluates it).
+ */
+function* collectPredicates(policyDoc) {
+  if (policyDoc === null || typeof policyDoc !== 'object') return;
+
+  const globalRules = Array.isArray(policyDoc.global_rules) ? policyDoc.global_rules : [];
+  for (let i = 0; i < globalRules.length; i++) {
+    const rule = globalRules[i];
+    if (rule && typeof rule === 'object' && rule.when != null) {
+      yield {
+        when: rule.when,
+        scope: rule.scope || 'submission',
+        location: `global_rules[${i}]${rule.id ? ` (${rule.id})` : ''}`,
+      };
+    }
+  }
+
+  const surfaces = policyDoc.surfaces && typeof policyDoc.surfaces === 'object' ? policyDoc.surfaces : {};
+  for (const [surface, sp] of Object.entries(surfaces)) {
+    const customRules = sp && Array.isArray(sp.custom_rules) ? sp.custom_rules : [];
+    for (let i = 0; i < customRules.length; i++) {
+      const rule = customRules[i];
+      if (rule && typeof rule === 'object' && rule.when != null) {
+        yield {
+          when: rule.when,
+          scope: 'scenario_result',
+          location: `surfaces.${surface}.custom_rules[${i}]${rule.id ? ` (${rule.id})` : ''}`,
+        };
+      }
+    }
+  }
+}

package/validators/policy.js

@@ -5,6 +5,8 @@
  * Global rules are non-overridable. Repo policies add surface-specific requirements.
  */
 
+import { evaluatePredicate, buildReason, PredicateError } from './predicate.js';
+
 function deepMerge(target, source) {
   const result = { ...target };
   for (const key of Object.keys(source)) {
@@ -44,7 +46,6 @@ function deepMerge(target, source) {
 const KNOWN_REJECT_RULE_IDS = new Set([
   // handled by the switch in validatePolicy
   'scenario-minimum',
-  'attested-if-human',
   'blocked-needs-reason',
   // enforced by other validators or by verify() itself (default-arm no-op is correct)
   'schema-valid',
@@ -54,6 +55,34 @@ const KNOWN_REJECT_RULE_IDS = new Set([
   'no-verdict-upgrade',
 ]);
 
+// VERIFY-F1: `attested-if-human` is intentionally NOT in the set above. It used to
+// be a switch arm; it is now enforced DECLARATIVELY (it carries a `when` predicate
+// in policies/global-policy.yaml and flows through the engine). If it ever appears
+// WITHOUT a `when` — a misconfigured migration — it falls to the default arm and is
+// NOT in KNOWN_REJECT_RULE_IDS, so it surfaces the "no enforcement" diagnostic
+// (fail-closed) instead of silently doing nothing.
+
+/**
+ * VERIFY-F1: evaluate a declarative rule's `when` predicate against each root and
+ * return one reason string (`[id] body`) per match. Throws {@link PredicateError}
+ * on a semantic fault; the caller decides whether that is operational (global rule)
+ * or submission-bad (repo custom rule).
+ */
+function collectMatches(rule, roots, scope) {
+  const reasons = [];
+  for (const root of roots) {
+    if (evaluatePredicate(rule.when, root, scope)) reasons.push(buildReason(rule, root));
+  }
+  return reasons;
+}
+
+/** Route matched reasons by severity. reject -> errors, warn -> warnings, info -> logged-only. */
+function routeReasons(rule, reasons, errors, warnings) {
+  if (rule.severity === 'reject') errors.push(...reasons);
+  else if (rule.severity === 'warn') warnings.push(...reasons);
+  // info: intentionally non-surfacing
+}
+
 /**
  * Resolve the effective surface policy for a given product surface.
  * Repo policy overrides global defaults per surface.
@@ -80,7 +109,10 @@ function resolveSurfacePolicy(surface, globalPolicy, repoPolicy) {
  * @param {object} options
  * @param {object} options.globalPolicy
  * @param {object|null} options.repoPolicy
- * @returns {{ valid: boolean, errors: string[], warnings: string[] }}
+ * @returns {{ valid: boolean, errors: string[], warnings: string[], configErrors: string[] }}
+ *   `configErrors` (VERIFY-F1) are eval-time repo custom-rule predicate faults; the
+ *   caller emits them with a `policy-config:` prefix (submission-bad). A non-empty
+ *   `configErrors` makes `valid` false.
  */
 export function validatePolicy(submission, { globalPolicy, repoPolicy }) {
   const errors = [];
@@ -88,12 +120,36 @@ export function validatePolicy(submission, { globalPolicy, repoPolicy }) {
   // instead of being silently dropped. A populated warnings[] never affects
   // `valid` — the caller (index.js) routes it to verification.warnings.
   const warnings = [];
+  // VERIFY-F1: a malformed REPO custom-rule predicate (an eval-time semantic fault
+  // the schema could not catch — unknown leading field, numeric op vs non-number,
+  // over-depth) is a `policy-config:` submission-bad reason recorded here (the repo
+  // authored the bad rule; do NOT page studio ops). A non-empty configErrors flips
+  // `valid` false (fail-closed). The caller prefixes these `policy-config: `, not
+  // `policy: `. Global-rule predicate faults are NOT collected here — they throw
+  // (-> VALIDATOR_FAULT_POLICY, operational).
+  const configErrors = [];
 
   // --- Global rules (non-overridable) ---
 
   const globalRules = globalPolicy.global_rules || [];
 
   for (const rule of globalRules) {
+    // VERIFY-F1: a rule carrying a `when` predicate is enforced DECLARATIVELY by
+    // the engine; a rule WITHOUT `when` falls to the legacy severity handling +
+    // id switch below (the seven built-ins that stay code-enforced). A GLOBAL-rule
+    // predicate fault is allowed to THROW (-> VALIDATOR_FAULT_POLICY, operational):
+    // a broken global policy is an operator/ops incident, mirroring loadGlobalPolicy's
+    // fail-loud schema gate. scope 'scenario_result' evaluates per element in array
+    // order (one reason per offending element); 'submission' (default) evaluates once.
+    if (rule.when) {
+      const scope = rule.scope || 'submission';
+      const roots = scope === 'scenario_result'
+        ? (submission.scenario_results || [])
+        : [submission];
+      routeReasons(rule, collectMatches(rule, roots, scope), errors, warnings);
+      continue;
+    }
+
     // VERIFY-F4: a global warn-rule is accepted-with-warning; an info-rule logs
     // only. Neither may reject. Mirrors the PROACT-VERIFY-002 discipline of not
     // dropping operator-authored rules on the floor: a declared rule that the
@@ -115,15 +171,10 @@ export function validatePolicy(submission, { globalPolicy, repoPolicy }) {
         }
         break;
 
-      case 'attested-if-human':
-        for (const sr of submission.scenario_results || []) {
-          if ((sr.execution_mode === 'human' || sr.execution_mode === 'mixed') && !sr.attested_by) {
-            errors.push(
-              `[${rule.id}] scenario "${sr.scenario_id}": execution_mode is "${sr.execution_mode}" but attested_by is missing`
-            );
-          }
-        }
-        break;
+      // VERIFY-F1: the `attested-if-human` switch arm was removed in v1.7.0. The rule
+      // is now enforced declaratively via a `when` predicate (see the `if (rule.when)`
+      // branch above and policies/global-policy.yaml). The differential-equivalence
+      // gate proves the declarative form is byte-identical to this removed arm.
 
       case 'blocked-needs-reason':
         for (const sr of submission.scenario_results || []) {
@@ -215,6 +266,22 @@ export function validatePolicy(submission, { globalPolicy, repoPolicy }) {
         }
       }
     }
+
+    // VERIFY-F1: declarative custom rules for this surface, evaluated per
+    // scenario_result. Additive-only (reject/warn/info, no accept verb) so a repo
+    // can never weaken a global gate. A predicate fault here is a `policy-config:`
+    // submission-bad reason (the repo authored the bad rule), NOT an ops page.
+    for (const customRule of surfacePolicy.custom_rules || []) {
+      try {
+        routeReasons(customRule, collectMatches(customRule, [sr], 'scenario_result'), errors, warnings);
+      } catch (err) {
+        if (err instanceof PredicateError) {
+          configErrors.push(`rule "${customRule.id}": ${err.message}`);
+          continue;
+        }
+        throw err;
+      }
+    }
   }
 
   const uniqueSurfaces = [...new Set((submission.scenario_results || []).map(sr => sr.product_surface))];
@@ -256,5 +323,10 @@ export function validatePolicy(submission, { globalPolicy, repoPolicy }) {
     }
   }
 
-  return { valid: errors.length === 0, errors, warnings };
+  return {
+    valid: errors.length === 0 && configErrors.length === 0,
+    errors,
+    warnings,
+    configErrors,
+  };
 }

package/validators/predicate.js

@@ -0,0 +1,449 @@
+/**
+ * Predicate engine (VERIFY-F1)
+ *
+ * A bounded, NO-EVAL interpreter for the declarative policy DSL. Operators author
+ * rules as structured predicates in their YAML policy file (field-selector +
+ * operator + value, composed with all/any/not/implies); this module evaluates
+ * them. There is no `eval`, `Function`, `vm`, dynamic import, or template-string
+ * execution anywhere in the path — the evaluator is a pure tree-walk. That is the
+ * whole safety thesis (see docs/policy-dsl.md).
+ *
+ * The schema (`policy.schema.json`, recursive `predicate` $def) is the FIRST gate:
+ * unknown operators, malformed nodes, banned path segments, and arity errors are
+ * rejected at policy-LOAD time by `validatePayload('policy', …)` and inherit the
+ * existing origin-based classification (global policy → throws/operational; repo
+ * policy → `__torn`/submission-bad). This module is the SECOND gate: the residual
+ * SEMANTIC faults the schema cannot express — an unknown leading field, a numeric
+ * operator against a non-number, or a predicate nested past the depth cap — surface
+ * as a {@link PredicateError} that the caller (policy.js) turns into a
+ * `policy-config:` reason, classified by predicate origin. A predicate is never
+ * silently skipped and never throws uncaught (fail-closed; Saltzer & Schroeder 1975).
+ */
+
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+
+/** Combinator nesting cap. A predicate nested deeper is a `max_depth` fault. */
+export const PREDICATE_MAX_DEPTH = 5;
+
+/**
+ * Total-work budgets (VERIFY-F1 Phase 3 hardening — the depth cap bounds NESTING
+ * but not WIDTH or array fan-out). The engine runs synchronously inside the ingest
+ * pipeline, so an unbounded tree-walk would block the event loop. Both budgets are
+ * generous relative to any real policy (a hand-authored rule is a handful of nodes
+ * over a handful of elements) and exist only to refuse a pathological / hostile
+ * predicate as a classified `policy-config:` fault rather than letting it spin.
+ */
+export const PREDICATE_MAX_NODES = 10_000;       // visited predicate nodes per evaluation
+export const PREDICATE_MAX_FRONTIER = 500_000;   // selected values from a `[]` fan-out
+
+/** Field-path segments that must never be traversed (prototype-pollution guard). */
+const POISON_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
+
+/** The closed operator set. Mirrors the `op` enum in policy.schema.json. */
+const OPERATORS = new Set([
+  'equals', 'not_equals', 'in', 'not_in', 'contains', 'not_contains',
+  'exists', 'not_exists', 'gt', 'gte', 'lt', 'lte',
+]);
+
+/**
+ * A structured predicate fault (compile- or eval-time). The `code` is a stable
+ * machine token; the message is operator-actionable (names the rule + the exact
+ * problem). The caller maps this to a `policy-config:` rejection reason, classified
+ * by the predicate's origin (global → operational, repo → submission-bad).
+ */
+export class PredicateError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'PredicateError';
+    this.code = code;
+  }
+}
+
+/**
+ * Known leading-field sets per scope, derived from the submission schema so the
+ * allowlist never drifts from the contract (CLAUDE.md rule #5: schemas via
+ * createRequire). Only the LEADING path segment is validated — a deeper typo just
+ * resolves to `undefined` (no match), but a wrong leading field is an operator
+ * error worth a diagnostic.
+ */
+const KNOWN_FIELDS = (() => {
+  const require = createRequire(import.meta.url);
+  const schemaPath = require.resolve('@dogfood-lab/schemas/json/dogfood-record-submission.schema.json');
+  const schema = JSON.parse(readFileSync(schemaPath, 'utf-8'));
+  const submission = new Set(Object.keys(schema.properties || {}));
+  const srProps = schema.properties?.scenario_results?.items?.properties || {};
+  const scenario_result = new Set(Object.keys(srProps));
+  return { submission, scenario_result };
+})();
+
+/** Split a dotted field path into segments, normalizing the `[]` array marker. */
+function splitPath(field) {
+  // 'scenario_results[].tags' -> ['scenario_results', '[]', 'tags']
+  const segments = [];
+  for (const raw of String(field).split('.')) {
+    const m = raw.match(/^([A-Za-z_][A-Za-z0-9_]*)(\[\])?$/);
+    if (!m) throw new PredicateError('bad_field', `field path segment "${raw}" is malformed`);
+    segments.push(m[1]);
+    if (m[2]) segments.push('[]');
+  }
+  return segments;
+}
+
+/** Read one own-property segment without ever touching the prototype chain. */
+function safeGet(value, segment) {
+  if (POISON_SEGMENTS.has(segment)) {
+    // Defense in depth — the schema `pattern` already bans these, but the
+    // evaluator never trusts the schema alone for a security-critical read.
+    throw new PredicateError('banned_segment', `field path segment "${segment}" is forbidden`);
+  }
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  return Object.hasOwn(value, segment) ? value[segment] : undefined;
+}
+
+/**
+ * Resolve a field path to the list of values it selects. A path with no `[]`
+ * yields exactly one value (possibly `undefined`, preserving "field absent" so
+ * `not_exists` works). Each `[]` segment expands the current frontier across the
+ * elements of the arrays at that position. The only iteration in the whole DSL.
+ */
+function resolvePath(root, segments) {
+  let frontier = [root];
+  for (const seg of segments) {
+    if (seg === '[]') {
+      const next = [];
+      for (const v of frontier) {
+        if (!Array.isArray(v)) continue;
+        // Explicit element loop, NOT `next.push(...v)` — the spread form blows the
+        // call stack on a large array (RangeError) before any budget check fires.
+        for (const el of v) {
+          if (next.length >= PREDICATE_MAX_FRONTIER) {
+            throw new PredicateError(
+              'fanout_budget',
+              `field path selection exceeds the limit of ${PREDICATE_MAX_FRONTIER} elements`
+            );
+          }
+          next.push(el);
+        }
+      }
+      frontier = next;
+    } else {
+      frontier = frontier.map(v => safeGet(v, seg));
+    }
+  }
+  return frontier;
+}
+
+/**
+ * Decide whether a field's LEADING segment is unknown for a scope, returning the
+ * fault rather than throwing it. Factored out so the eval path ({@link checkLeadingField},
+ * fail-on-first) and the lint path ({@link lintPredicate}, batch-collect) share one
+ * source of truth — a divergence between author-time and runtime diagnostics is
+ * impossible by construction. Data-INDEPENDENT (the known-field set is derived from
+ * the schema), so it is exactly the kind of check the lint can run without a submission.
+ */
+function leadingFieldFault(field, scope) {
+  const leading = String(field).split('.')[0].replace('[]', '');
+  const known = KNOWN_FIELDS[scope];
+  if (known && !known.has(leading)) {
+    return new PredicateError(
+      'unknown_field',
+      `field "${field}" references unknown leading field "${leading}" (known ${scope} fields: ${[...known].join(', ')})`
+    );
+  }
+  return null;
+}
+
+/** Validate the leading field segment against the scope's known-field set (eval path: throws). */
+function checkLeadingField(field, scope) {
+  const fault = leadingFieldFault(field, scope);
+  if (fault) throw fault;
+}
+
+/** Apply one operator to a single resolved value + comparand. */
+function applyOp(op, value, comparand) {
+  switch (op) {
+    case 'equals': return value === comparand;
+    case 'not_equals': return value !== comparand;
+    case 'in': return Array.isArray(comparand) && comparand.includes(value);
+    case 'not_in': return Array.isArray(comparand) && !comparand.includes(value);
+    case 'contains':
+      if (Array.isArray(value)) return value.includes(comparand);
+      if (typeof value === 'string') return value.includes(comparand);
+      return false;
+    case 'not_contains':
+      // not_contains is the negation of contains, so a missing/non-collection
+      // field genuinely "does not contain" the value (matches the v1.6.0
+      // required_tags semantics — a tagless scenario fails required_tags).
+      return !applyOp('contains', value, comparand);
+    case 'exists': return Boolean(value);
+    case 'not_exists': return !value;
+    case 'gt': case 'gte': case 'lt': case 'lte': {
+      if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new PredicateError(
+          'type_mismatch',
+          `operator "${op}" requires a numeric field value but got ${describe(value)}`
+        );
+      }
+      if (op === 'gt') return value > comparand;
+      if (op === 'gte') return value >= comparand;
+      if (op === 'lt') return value < comparand;
+      return value <= comparand;
+    }
+    default:
+      // Unreachable when the schema gate ran (op is enum-constrained), but the
+      // evaluator fails closed rather than trusting the schema.
+      throw new PredicateError('unknown_op', `unknown operator "${op}"`);
+  }
+}
+
+function describe(value) {
+  if (value === undefined) return 'undefined (field absent)';
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'an array';
+  return `${typeof value} (${JSON.stringify(value)})`;
+}
+
+function isCombinator(node) {
+  return node != null && typeof node === 'object' &&
+    (Array.isArray(node.all) || Array.isArray(node.any) || node.not != null || Array.isArray(node.implies));
+}
+
+/** Evaluate a leaf `{field, op, value?}` against a root, with "any element" semantics. */
+function evalLeaf(node, root, scope) {
+  if (!OPERATORS.has(node.op)) {
+    throw new PredicateError('unknown_op', `unknown operator "${node.op}"`);
+  }
+  checkLeadingField(node.field, scope);
+  const values = resolvePath(root, splitPath(node.field));
+  // The predicate is true when ANY selected value satisfies the operator. For a
+  // scalar (no `[]`) path this is just that single value; for an empty `[]`
+  // selection there is nothing to match, so the leaf is false.
+  for (const v of values) {
+    if (applyOp(node.op, v, node.value)) return true;
+  }
+  return false;
+}
+
+/**
+ * Evaluate a predicate node against a root object (the whole submission for
+ * `submission` scope, or a single scenario_result for `scenario_result` scope).
+ *
+ * @param {object} node - The predicate tree.
+ * @param {object} root - The data to evaluate against.
+ * @param {'submission'|'scenario_result'} scope - Field-resolution scope.
+ * @returns {boolean} True when the (violation) predicate matches.
+ * @throws {PredicateError} On a semantic fault (unknown field, type mismatch, depth, budget).
+ */
+export function evaluatePredicate(node, root, scope) {
+  // The budget is per-evaluation (one call over one root). It bounds the WIDTH a
+  // single predicate can consume, complementing the per-node depth cap.
+  return evalNode(node, root, scope, 1, { nodes: 0 });
+}
+
+function evalNode(node, root, scope, depth, budget) {
+  if (++budget.nodes > PREDICATE_MAX_NODES) {
+    throw new PredicateError(
+      'node_budget',
+      `predicate exceeds the evaluation budget of ${PREDICATE_MAX_NODES} nodes`
+    );
+  }
+  if (isCombinator(node)) {
+    if (depth > PREDICATE_MAX_DEPTH) {
+      throw new PredicateError(
+        'max_depth',
+        `predicate nests deeper than the limit of ${PREDICATE_MAX_DEPTH} combinator levels`
+      );
+    }
+    if (Array.isArray(node.all)) return node.all.every(c => evalNode(c, root, scope, depth + 1, budget));
+    if (Array.isArray(node.any)) return node.any.some(c => evalNode(c, root, scope, depth + 1, budget));
+    if (node.not != null) return !evalNode(node.not, root, scope, depth + 1, budget);
+    // implies: [antecedent, consequent] is the VIOLATION all(antecedent, not(consequent))
+    // — it matches the inputs that BREAK the implication antecedent => consequent.
+    const [antecedent, consequent] = node.implies;
+    return evalNode(antecedent, root, scope, depth + 1, budget)
+      && !evalNode(consequent, root, scope, depth + 1, budget);
+  }
+  return evalLeaf(node, root, scope);
+}
+
+/**
+ * Interpolate a `reason_template`'s `{slot}` placeholders from a root object.
+ * Slots are read via the same prototype-safe accessor as the field selector and
+ * interpolated RAW (no escaping) — the differential-equivalence oracle wraps
+ * values in literal quotes, and any escaping would diverge byte-for-byte. A slot
+ * that resolves to nothing renders empty.
+ */
+function renderTemplate(template, root) {
+  return String(template).replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, slot) => {
+    // A poison slot is rendered empty — never traversed, never thrown. The own-
+    // property read avoids the prototype chain entirely (no inherited values leak).
+    if (POISON_SEGMENTS.has(slot)) return '';
+    const present = root !== null && typeof root === 'object' && Object.hasOwn(root, slot);
+    const v = present ? root[slot] : undefined;
+    return v === undefined || v === null ? '' : String(v);
+  });
+}
+
+/**
+ * Build the full reason string for a matched rule: `[<id>] <body>`, where the
+ * body is the rendered `reason_template` or, absent that, the rule's
+ * `description`. The `policy:` prefix is NOT added here — verify/index.js prepends
+ * it to every policy error.
+ *
+ * @param {object} rule - The policy rule ({ id, description?, reason_template? }).
+ * @param {object} root - The matched element (scenario_result) or submission.
+ * @returns {string}
+ */
+export function buildReason(rule, root) {
+  const body = rule.reason_template != null
+    ? renderTemplate(rule.reason_template, root)
+    : (rule.description ?? '');
+  return `[${rule.id}] ${body}`;
+}
+
+/* ───────────────────────── Static analysis (VERIFY-F3 policy-lint) ─────────────────────────
+ *
+ * The two functions below analyze a predicate AST WITHOUT a submission. They are the reusable
+ * leaf the `policy-lint` verb (and any future eager-validation path) builds on. Co-located here,
+ * not in a separate module, so they reuse this file's private engine internals (KNOWN_FIELDS via
+ * leadingFieldFault, isCombinator, the depth/node-budget constants) without exporting the guts —
+ * predicate.js owns *everything about a predicate node*: eval AND static analysis.
+ *
+ * Coverage boundary (the VERIFY-F2 over-claim lesson — see docs/policy-lint.md):
+ *   - DATA-INDEPENDENT, caught here: unknown leading field, combinator over-depth, node budget.
+ *   - STRUCTURAL (unknown op, banned/malformed segment, arity): caught earlier by the schema gate
+ *     (`validatePayload('policy', …)`), so lintPredicate does not re-report them.
+ *   - DATA-DEPENDENT, NOT catchable statically: `type_mismatch` (a numeric op over a non-number)
+ *     and `fanout_budget` (a `[]` selection size) — both need a real submission. The lint says so.
+ */
+
+/** A static lint finding: a machine `code` (mirrors {@link PredicateError} codes) + an operator message. */
+
+/**
+ * Statically lint a predicate tree against one scope, batch-collecting the data-independent
+ * semantic faults the schema cannot express. Unlike {@link evaluatePredicate} this NEVER throws —
+ * a lint reports every fault rather than failing on the first — and it is DEFENSIVE: a malformed
+ * node (already flagged by the schema gate) is skipped, not crashed on. The walk mirrors the
+ * evaluator's own depth + node accounting (same constants), so a lint verdict agrees with what the
+ * engine would do at eval time, and the walk is itself bounded (it cannot become a DoS on a
+ * pathological policy file).
+ *
+ * @param {unknown} node - The predicate tree (any value; non-objects are skipped).
+ * @param {'submission'|'scenario_result'} scope - Field-resolution scope.
+ * @returns {{ code: string, field?: string, message: string }[]}
+ */
+export function lintPredicate(node, scope) {
+  const findings = [];
+  walkLint(node, scope, 1, { nodes: 0, depthReported: false, budgetReported: false }, findings);
+  return findings;
+}
+
+function walkLint(node, scope, depth, state, findings) {
+  if (state.budgetReported) return;
+  if (++state.nodes > PREDICATE_MAX_NODES) {
+    if (!state.budgetReported) {
+      state.budgetReported = true;
+      findings.push({
+        code: 'node_budget',
+        message: `predicate exceeds the evaluation budget of ${PREDICATE_MAX_NODES} nodes`,
+      });
+    }
+    return;
+  }
+  if (node === null || typeof node !== 'object') return;
+
+  if (isCombinator(node)) {
+    if (depth > PREDICATE_MAX_DEPTH) {
+      // Mirror the evaluator, which throws when a combinator is reached past the cap; report once
+      // and stop descending this branch (siblings are still walked — batch reporting).
+      if (!state.depthReported) {
+        state.depthReported = true;
+        findings.push({
+          code: 'max_depth',
+          message: `predicate nests deeper than the limit of ${PREDICATE_MAX_DEPTH} combinator levels`,
+        });
+      }
+      return;
+    }
+    const children =
+      Array.isArray(node.all) ? node.all :
+      Array.isArray(node.any) ? node.any :
+      node.not != null ? [node.not] :
+      Array.isArray(node.implies) ? node.implies : [];
+    for (const child of children) walkLint(child, scope, depth + 1, state, findings);
+    return;
+  }
+
+  // Leaf: the only data-independent semantic check is the unknown leading field. The op set and
+  // path shape are schema-gated; a numeric-op type mismatch is data-dependent (not checkable here).
+  if (typeof node.field === 'string') {
+    const fault = leadingFieldFault(node.field, scope);
+    if (fault) findings.push({ code: fault.code, field: node.field, message: fault.message });
+  }
+}
+
+/** Negative operators that fail OPEN over an empty/absent `[]` selection (the footgun). */
+const NEGATIVE_OPS = new Set(['not_equals', 'not_in', 'not_contains', 'not_exists']);
+
+/** The positive counterpart used in the fail-closed `not(any(...))` rewrite suggestion. */
+const POSITIVE_OF = { not_equals: 'equals', not_in: 'in', not_contains: 'contains', not_exists: 'exists' };
+
+/** Build the deterministic, AST-derived fail-closed rewrite suggestion for a footgun leaf. */
+function footgunSuggestion(field, op) {
+  const pos = POSITIVE_OF[op] || 'contains';
+  const valuePart = pos === 'exists' ? ' ' : ', value: … ';
+  return `if you meant "reject when no element satisfies it", use the fail-closed idiom ` +
+    `{ not: { any: [ { field: "${field}", op: ${pos}${valuePart}} ] } }`;
+}
+
+/**
+ * Find `[]`-footgun leaves: a NEGATIVE operator over a `[]` field path, which fails OPEN on an
+ * empty/absent array (existential vacuous truth — see docs/policy-lint.md). ADVISORY only: there
+ * are legitimate existential-negatives, so the caller surfaces these as warnings the author
+ * confirms, never as hard errors, and never auto-applies the rewrite.
+ *
+ * Suppression by negation PARITY, not a bare "is there a `not` above me" flag. A leaf inverted an
+ * EVEN number of times (0, 2, …) still fails open and is flagged; an ODD number of inversions makes
+ * it fail CLOSED, so it is suppressed. Two sources of inversion are counted: a `not` combinator,
+ * and the CONSEQUENT (second element) of an `implies` (since `implies:[A,C]` desugars to the
+ * violation `all(A, not(C))`). This refinement came from the VERIFY-F3 cross-family adversarial
+ * jury (deepseek-v4-pro / glm-5.2 / minimax-m3, 2026-06-30), which converged on two real defects in
+ * the original boolean rule: `not(not(X))` over `[]` fails open but was suppressed (false negative),
+ * and a negative-op consequent of `implies` fails closed but was flagged (false positive). Parity
+ * fixes both. Scope stays NEGATIVE-ops-only and ADVISORY (the jury's "flag every op" and "make it a
+ * hard error" suggestions were rejected — the former floods noise on the normal `contains` idiom,
+ * the latter blocks legitimate existential-negatives). False positives remain acceptable by design;
+ * a false negative (a silent production fail-open) is the expensive failure, so it errs toward warning.
+ *
+ * @param {unknown} node - The predicate tree.
+ * @returns {{ field: string, op: string, suggestion: string }[]}
+ */
+export function findEmptyArrayFootguns(node) {
+  const guns = [];
+  walkFootgun(node, false, { nodes: 0 }, guns);
+  return guns;
+}
+
+function walkFootgun(node, inverted, state, guns) {
+  if (node === null || typeof node !== 'object') return;
+  if (++state.nodes > PREDICATE_MAX_NODES) return; // bounded; lintPredicate reports node_budget
+
+  if (isCombinator(node)) {
+    if (Array.isArray(node.all)) { for (const c of node.all) walkFootgun(c, inverted, state, guns); return; }
+    if (Array.isArray(node.any)) { for (const c of node.any) walkFootgun(c, inverted, state, guns); return; }
+    if (node.not != null) { walkFootgun(node.not, !inverted, state, guns); return; }
+    if (Array.isArray(node.implies)) {
+      // implies:[A, C] === all(A, not(C)) — only the consequent (index 1) flips parity.
+      node.implies.forEach((c, i) => walkFootgun(c, i === 1 ? !inverted : inverted, state, guns));
+      return;
+    }
+    return;
+  }
+
+  if (!inverted &&
+      typeof node.op === 'string' && NEGATIVE_OPS.has(node.op) &&
+      typeof node.field === 'string' && node.field.includes('[]')) {
+    guns.push({ field: node.field, op: node.op, suggestion: footgunSuggestion(node.field, node.op) });
+  }
+}