@dogfood-lab/verify 1.9.0 → 1.11.0

package/README.md

@@ -109,21 +109,23 @@ The verifier emits rejection-reason strings under stable prefixes, each mapping
 
 Discrimination happens by **class**, surfaced by `parseRejectionReason` (below). Every prefix maps to one of four classes: **submission-bad** (the submitter fixes the payload), **operational** (the verifier/tooling faulted), **ingest** (an ingest-side load fault), or **unknown** (unrecognized prefix).
 
+**Retryable** (F-f8952a50, wave 10) is a SEPARATE, narrower per-prefix flag, orthogonal to `class`: may a same-`run_id` resubmission whose ONLY prior rejection carries this prefix still reach an acceptance, once corrected? `packages/ingest/persist.js`'s duplicate guard (`isDuplicate` → `isRetryableRejection`) reads this flag — never `class` or `prefix` directly — to decide whether a stale `_rejected` record blocks a same-`run_id` retry that is now headed to acceptance. Every `operational` / `ingest` / `unknown` prefix is `retryable: false` (an ops fault or an unrecognized signal is never the submitter's to retry past). Within `submission-bad`, the taxonomy splits further — **shape/addressing** prefixes ("we could not even read/place/shape your submission") are retryable; **content-verdict** prefixes ("we read your submission and rendered a verdict against its own reported content") are not, so a submitter cannot launder a genuinely-bad run into an accepted one by resubmitting different self-reported content under the same `run_id`. The table below marks each `submission-bad` prefix's retryable value explicitly.
+
 **Submission-bad** — `class: 'submission-bad'` (the submitter's payload failed a validator gate; fix the submission and resubmit):
 
-| 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, 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: …`. |
-| `submission-contains-verifier-field:` | `index.js` | The submission carried a verifier-owned field (`policy_version`, `verification`, or an object `overall_verdict`) it must not author. |
-| `CONTRACT_SCHEMA_TOO_NEW:` | `validators/schema-version.js` | The submission's `schema_version` declares a MAJOR **above** what this build supports (see `SUPPORTED_SCHEMA_VERSIONS` in `@dogfood-lab/schemas`). This build cannot understand a future contract — **the operator must upgrade testing-os**, but the routing class stays submission-bad (the payload as-shipped cannot be accepted by THIS build). |
-| `CONTRACT_SCHEMA_TOO_OLD:` | `validators/schema-version.js` | The submission's `schema_version` declares a MAJOR **below** the supported floor. **The submitter must re-emit** against the current contract. A patch/minor delta inside the supported major range is NOT rejected. |
-
-**Operational** — `class: 'operational'` (the validator itself threw an internal error; investigate the verifier, do NOT bounce to the submitter):
+| Prefix | Retryable | Source | Meaning |
+|---|---|---|---|
+| `schema:` | Yes — shape | `validators/schema.js` | JSON Schema check on the submission/record envelope failed. The rest of the string carries the AJV path + message. |
+| `policy:` | **No — content verdict** | `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/)). Judges the run's OWN reported content (tags, evidence, scenario results); consuming the run_id is the deliberate anti-gaming behavior. |
+| `policy-config:` | Yes — shape | `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 (config), not the run's content, so the fix belongs to the submitter and is retryable. (A malformed GLOBAL predicate is `VALIDATOR_FAULT_POLICY:` operational instead — see below.) |
+| `steps[<id>]:` | Yes — shape | `validators/steps.js` | Step-level contract check failed on a specific step id (gate accumulation, ordering, evidence shape — a completeness/structure mismatch, not a verdict on whether the steps passed). |
+| `provenance:` | **No — content verdict** | `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 provider could not confirm THIS specific run happened as claimed; resubmitting different self-reported content under the same run_id to "become confirmable" is exactly the laundering the anti-gaming doctrine blocks. (Operational provider faults — 429/5xx/401/403 — are NOT this class; see `provenance-fault:` below.) |
+| `repo:` | Yes — shape | `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: …`. Pure identity/addressing — the run happened, only the repo/run_url pairing was mis-stated. |
+| `submission-contains-verifier-field:` | Yes — shape | `index.js` | The submission carried a verifier-owned field (`policy_version`, `verification`, or an object `overall_verdict`) it must not author. |
+| `CONTRACT_SCHEMA_TOO_OLD:` | Yes — shape | `validators/schema-version.js` | The submission's `schema_version` declares a MAJOR **below** the supported floor. **The submitter must re-emit** against the current contract. A patch/minor delta inside the supported major range is NOT rejected. (NOT symmetric with `CONTRACT_SCHEMA_TOO_NEW:` below — see that row for why.) |
+| `unsafe-record-path:` | Yes — shape | `packages/ingest/run.js`, `writeRecord()` catch | The record passed schema validation but `computeRecordPath()`'s traversal guard (`isUnsafeSegment`, stricter than the schema's `repo` pattern — e.g. `../etc`) still refused to place it on disk. The submitter's own `repo` string is the problem; nothing is persisted (there is no safe path to write to). |
+
+**Operational** — `class: 'operational'`, always `retryable: false` (the validator itself threw an internal error; investigate the verifier, do NOT bounce to the submitter):
 
 | Prefix | Source | Meaning |
 |---|---|---|
@@ -131,13 +133,14 @@ Discrimination happens by **class**, surfaced by `parseRejectionReason` (below).
 | `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). |
+| `CONTRACT_SCHEMA_TOO_NEW:` | `validators/schema-version.js` | **F-be0deacd (wave 20).** The submission's `schema_version` declares a MAJOR **above** what this build supports (see `SUPPORTED_SCHEMA_VERSIONS` in `@dogfood-lab/schemas`) — THIS BUILD is behind a schema major its own submitters have already adopted. No resubmission, corrected or not, can ever satisfy a `major > maxMajor` comparison until testing-os itself ships an upgrade — **the operator must upgrade testing-os**. Page ops; do NOT bounce it back to the submitter. Unlike every other row in this table, `validators/schema-version.js` RETURNS this as an ordinary rejection string rather than throwing, so (unlike the `VALIDATOR_FAULT_*`/`provenance-fault:`/`scenario-fetch-fault:` rows) it genuinely persists to `records/_rejected/` and is reachable by `packages/ingest/persist.js`'s `isRetryableRejection()` — **F-51780da9 (wave 22):** rather than trusting the frozen `retryable: false` this prefix's own classification carries, `isRetryableRejection()` re-derives retryability for this ONE prefix against the CURRENT build's `SUPPORTED_SCHEMA_VERSIONS` ceiling, so a stale TOO_NEW rejection unblocks once the operator upgrades testing-os past the declared major. Distinct from the submission-bad `CONTRACT_SCHEMA_TOO_OLD:` above — the two prefixes are asymmetric despite the shared emitter. |
 | `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. |
 | `provenance-fault:` | `index.js` provenance catch | The provenance adapter THREW an operational error confirming the run — a provider **429 rate-limit, 5xx outage, or 401/403 token** fault (`validators/provenance.js` throws these on purpose for non-404 responses). The submitter's payload is fine; the verifier could not reach a verdict. Page ops / retry; do NOT bounce it to a submitter. Distinct from the submission-bad `provenance:` (genuine absence/404). |
 | `scenario-fetch-fault:` | `packages/ingest/load-context.js` | The scenario fetcher THREW after exhausting its retry budget (**5xx/429 outage, transport reject**) or hit a **401/403 credential** fault loading a scenario definition. The submission may be perfectly good — the fetch infrastructure faulted. The ingest CLI lets this propagate (exit 2, nothing persisted); a true missing file is the ingest-class `scenario-load: … (reason: not_found)` instead. |
 
 Any future `VALIDATOR_FAULT_<NEW>:` prefix is classified `operational` by family — `parseRejectionReason` matches the `VALIDATOR_FAULT_` head, so a new validator class needs no parser edit. The `submission-malformed:` prefix is matched literally (it is not part of the `VALIDATOR_FAULT_` family).
 
-**Ingest** — `class: 'ingest'` (an ingest-side load fault, not a verifier gate):
+**Ingest** — `class: 'ingest'`, always `retryable: false` (an ingest-side load fault, not a verifier gate):
 
 | Prefix | Source | Meaning |
 |---|---|---|
@@ -145,13 +148,13 @@ Any future `VALIDATOR_FAULT_<NEW>:` prefix is classified `operational` by family
 
 ### Operator hygiene
 
-Discriminate by **class**, not by hand-rolled `.startsWith()` chains. `parseRejectionReason(reason)` returns `{ class, prefix, detail }`:
+Discriminate by **class**, not by hand-rolled `.startsWith()` chains. `parseRejectionReason(reason)` returns `{ class, prefix, detail, retryable }`:
 
 ```js
 import { parseRejectionReason } from '@dogfood-lab/verify';
 
 for (const r of result.rejection_reasons) {
-  const { class: cls, prefix, detail } =
+  const { class: cls, prefix, detail, retryable } =
     parseRejectionReason(r);
   switch (cls) {
     case 'operational':

package/cli-lint.js

@@ -1,5 +1,5 @@
 /**
- * cli-lint.js (VERIFY-F3) — the `dogfood-verify lint <file>` subcommand.
+ * cli-lint.js (VERIFY-F3 + F-49940082) — the `dogfood-verify lint <file>` subcommand.
  *
  * A SEPARATE parse/render path from the verify CLI (cli.js): it takes a policy YAML or
  * (with --scenario) a scenario YAML — not a submission JSON — and reports static lint
@@ -9,7 +9,8 @@
  *
  *   0 — clean, or warnings-only (footgun advisories never block).
  *   1 — one or more errors (schema-invalid, a static fault, or unparseable YAML).
- *   2 — operator error (file missing/unreadable, or a malformed invocation).
+ *   2 — operator error (file missing/unreadable, a malformed invocation, or a batch
+ *       whose positionals resolved to zero lintable files).
  *
  * YAML that fails to parse is exit 1 (a lint FINDING about the file the author must fix —
  * surfacing "line 4: bad indentation" is the lint's job), not exit 2. A file that does not
@@ -19,11 +20,21 @@
  *   - default (policy):  lintPolicy(doc, { origin })      → origin global|repo|unknown
  *   - --scenario:        lintScenario(doc, { file })      → origin 'scenario'
  * Both return the same { ok, origin, errors, warnings, coverageNote } shape, so
- * renderLintText / buildLintJson are reused unchanged.
+ * renderLintText / buildLintJson are reused unchanged, single-file or batch.
+ *
+ * Directory-or-multi-path mode (F-49940082): one or more positionals are accepted. A
+ * positional that is a directory is walked recursively for YAML files (extension match,
+ * mirroring the discovery semantics of scripts/lint-policies.test.mjs's own policyFiles()
+ * walker — see walkYamlFiles below). A positional that is a file is linted directly, no
+ * extension filter (an explicit path is trusted as authored intent; the extension filter
+ * only exists to skip non-policy noise during an unattended directory walk). The exact
+ * single-positional-file invocation shape is untouched: it still runs through the very
+ * same statements it always has, so its output is byte-identical to before this mode
+ * existed — see the "legacy single-file path" branch in runLint.
  */
 
-import { readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve, join } from 'node:path';
 import yaml from 'js-yaml';
 
 import { lintPolicy, COVERAGE_NOTE } from './validators/lint-policy.js';
@@ -40,11 +51,23 @@ class LintOperatorError extends Error {
 
 const LINT_USAGE = `dogfood-verify lint — author-time static check for a policy or scenario file
 
-USAGE:
+Usage:
   dogfood-verify lint <policy-file> [--json]
+  dogfood-verify lint <path> [<path> ...] [--json]
   dogfood-verify lint --scenario <scenario-file> [--json]
+  dogfood-verify lint --scenario <path> [<path> ...] [--json]
+
+Directory-or-multi-path mode:
+  Give more than one positional, or point at a directory, and every path is linted as
+  a batch. A directory positional is walked recursively for *.yaml and *.yml files; a
+  file positional is linted directly regardless of extension. Results print one block
+  per file (same format as single-file mode) followed by a batch summary — files
+  linted / clean / with-errors / with-warnings. The batch exit code is 1 if any file
+  has an error, 0 if every file is clean or warnings-only — the single-file contract,
+  extended across the set. A directory (or set of directories) with nothing to lint is
+  an operator error (exit 2), never a silent pass.
 
-WHAT IT CHECKS — policy mode (default, no submission needed):
+What it checks — policy mode (default, 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)
@@ -52,7 +75,7 @@ WHAT IT CHECKS — policy mode (default, no submission needed):
   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.
 
-WHAT IT CHECKS — --scenario mode (no submission needed):
+What it checks — --scenario mode (no submission needed):
   - structural validity against scenario.schema.json
   - every success_criteria.required_steps entry references a declared steps[].id
   - step ids are unique
@@ -63,27 +86,33 @@ WHAT IT CHECKS — --scenario mode (no submission needed):
   It CANNOT verify that a real submission's step_results satisfy required_steps, nor
   that the receiver can fetch the file at the attested commit — run a real ingest.
 
-OPTIONS:
-  --scenario    Lint the file as a scenario definition (default: policy).
-  --json        Machine-readable result for CI.
+Options:
+  --scenario    Lint the file(s) as scenario definitions (default: policy).
+  --json        Machine-readable result for CI. A single-file invocation emits one
+                result object, unchanged. Multi-path/directory mode emits
+                { mode: "batch", ok, summary, files: [ <one result object per file> ] }.
   -h, --help    Show this help.
 
-EXIT CODES:
-  0  clean or warnings-only     1  errors found     2  operator error (bad flags / IO)`;
+Exit codes:
+  0  clean or warnings-only     1  errors found     2  operator error (bad flags / IO / nothing to lint)`;
 
 /**
- * Parse the lint argv (everything AFTER the `lint` verb). Accepts exactly one positional
- * file path plus optional `--scenario` / `--json` / `--help`. Throws LintOperatorError
- * (→ exit 2) on any malformed invocation.
+ * Parse the lint argv (everything AFTER the `lint` verb). Accepts one or more positional
+ * paths (files and/or directories) plus optional `--scenario` / `--json` / `--help`.
+ * Throws LintOperatorError (→ exit 2) on any malformed invocation.
  *
  * `--scenario` is a boolean MODE flag (default: policy mode). It selects which linter runs
- * over the one positional file; it never consumes the path itself.
+ * over every positional; it never consumes a path itself.
+ *
+ * Whether a given invocation is "single-file" (legacy, byte-identical output) or "batch"
+ * (F-49940082) is NOT decided here — this just collects positionals. runLint makes that
+ * call once it knows whether the sole positional is a directory.
  *
  * @param {string[]} argv
- * @returns {{ help: boolean, file: string|null, json: boolean, scenario: boolean }}
+ * @returns {{ help: boolean, paths: string[], json: boolean, scenario: boolean }}
  */
 export function parseLintArgs(argv) {
-  let file = null;
+  const paths = [];
   let json = false;
   let help = false;
   let scenario = false;
@@ -95,18 +124,15 @@ export function parseLintArgs(argv) {
     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 file given', 'lint one file at a time');
-    }
-    file = arg;
+    paths.push(arg);
   }
 
-  if (help) return { help: true, file: null, json: false, scenario: false };
-  if (file === null) {
-    const usage = scenario ? 'dogfood-verify lint --scenario <scenario-file>' : 'dogfood-verify lint <policy-file>';
-    throw new LintOperatorError(`no ${scenario ? 'scenario' : 'policy'} file provided`, usage);
+  if (help) return { help: true, paths: [], json: false, scenario: false };
+  if (paths.length === 0) {
+    const usage = scenario ? 'dogfood-verify lint --scenario <scenario-file|dir> [...]' : 'dogfood-verify lint <policy-file|dir> [...]';
+    throw new LintOperatorError(`no ${scenario ? 'scenario' : 'policy'} file or directory provided`, usage);
   }
-  return { help: false, file, json, scenario };
+  return { help: false, paths, json, scenario };
 }
 
 /**
@@ -121,6 +147,35 @@ export function originForPath(p) {
   return 'unknown';
 }
 
+/**
+ * Recursively collect every YAML file (extension .yaml or .yml) under `dir`, depth-first.
+ * This is the F-49940082 directory-walk primitive for batch mode, deliberately mirroring
+ * policyFiles() in scripts/lint-policies.test.mjs — the CI gate that has quietly re-walked
+ * `policies/` on its own since VERIFY-F3 rather than exercising this CLI (that gap is the
+ * whole reason F-49940082 exists). Same two rules, on purpose: no skip-list (a hidden
+ * directory or a stray `node_modules` is walked like any other — the intended input here is
+ * an author-controlled tree such as `policies/`, not an arbitrary large directory), and
+ * symlinks are followed (`statSync`, not `lstatSync`).
+ *
+ * One deliberate divergence: this returns results in this function's own recursion order,
+ * which the caller (runLint) sorts across every discovered file from every positional —
+ * policyFiles() returns readdirSync's raw per-directory order because its only consumer is
+ * a test that aggregates failures into an unordered list; a human-facing CLI report reads
+ * better, and diffs better across runs, sorted.
+ *
+ * @param {string} dir - an already-resolved, existing directory path
+ * @returns {string[]} absolute file paths, unsorted (caller sorts across the full batch)
+ */
+export function walkYamlFiles(dir) {
+  const out = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) out.push(...walkYamlFiles(full));
+    else if (entry.endsWith('.yaml') || entry.endsWith('.yml')) out.push(full);
+  }
+  return out;
+}
+
 /** Render the human (default) view of a lint result — verdict-first, ERROR before WARNING. */
 export function renderLintText(result, file) {
   const lines = [];
@@ -172,42 +227,51 @@ export function buildLintJson(result, file) {
   };
 }
 
+/** Render the batch summary footer printed after every per-file block in
+ *  directory-or-multi-path mode (F-49940082). */
+export function renderBatchSummary(summary) {
+  const { total, clean, withErrors, withWarnings } = summary;
+  return [
+    '-'.repeat(60),
+    `BATCH SUMMARY: ${total} file(s) linted -- ${clean} clean, ${withWarnings} with warnings, ${withErrors} with errors`,
+  ].join('\n');
+}
+
 /**
- * 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>}
+ * Build the machine-readable (--json) result for batch mode (F-49940082). Each entry in
+ * `files` has the exact shape buildLintJson produces for a single file, so a consumer
+ * written against the single-file --json shape only needs to index into `.files[i]`
+ * instead of the top-level object. There is no pre-existing batch JSON consumer to match
+ * instead: scripts/lint-policies.test.mjs (the only other batch-shaped lint caller in this
+ * repo) bypasses the CLI's JSON output entirely and calls lintPolicy() directly — that
+ * bypass is F-49940082's own subject, not a shape for this to imitate.
  */
-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;
-  }
+export function buildBatchLintJson(files, summary) {
+  return {
+    mode: 'batch',
+    ok: summary.withErrors === 0,
+    summary,
+    files,
+  };
+}
 
-  const path = resolve(opts.file);
-  const kind = opts.scenario ? 'scenario' : 'policy';
-  let raw;
-  try {
-    raw = readFileSync(path, 'utf-8');
-  } catch (e) {
-    err(`ERROR: could not read ${kind} file: ${path} — ${e.message}`);
-    err('  hint: check the path exists and is readable');
-    return 2;
-  }
+/**
+ * Read, parse, and lint ONE file — the primitive shared by the legacy single-file path
+ * and batch mode (F-49940082). Deliberately does not catch a read failure: the two
+ * callers give it different severity. The legacy path treats "the one named file cannot
+ * be read" as an operator mistake (exit 2, and it aborts — there is nothing else to try).
+ * Batch mode treats "one file among several cannot be read" as a per-file finding folded
+ * into the batch (see unreadableResult) so one bad path does not hide the results for
+ * every other path given alongside it. A YAML parse failure, by contrast, IS handled
+ * here and returned as an ok:false result — that has always been a lint finding, not an
+ * operator error, in both modes.
+ *
+ * @param {string} path - an already-resolved file path
+ * @param {{ scenario: boolean }} opts
+ * @returns {{ ok: boolean, origin: string, errors: object[], warnings: object[], coverageNote: string }}
+ */
+function lintOneFile(path, opts) {
+  const raw = readFileSync(path, 'utf-8');
 
   let doc;
   try {
@@ -217,7 +281,7 @@ export async function runLint(argv, io = {}) {
     // Mirrors the policy path exactly, only differing in the origin/label/coverageNote so the
     // scenario report reads as a scenario report.
     const where = e && e.mark ? ` at line ${e.mark.line + 1}, column ${e.mark.column + 1}` : '';
-    const result = opts.scenario
+    return opts.scenario
       ? {
           ok: false,
           origin: 'scenario',
@@ -242,13 +306,164 @@ export async function runLint(argv, io = {}) {
           warnings: [],
           coverageNote: COVERAGE_NOTE,
         };
-    out(opts.json ? JSON.stringify(buildLintJson(result, path)) : renderLintText(result, path));
-    return 1;
   }
 
-  const result = opts.scenario
+  return opts.scenario
     ? lintScenario(doc, { file: path })
     : lintPolicy(doc, { origin: originForPath(path) });
-  out(opts.json ? JSON.stringify(buildLintJson(result, path)) : renderLintText(result, path));
-  return result.ok ? 0 : 1;
+}
+
+/**
+ * Build a lint-result-shaped entry for a batch-mode path that could not be read at all
+ * (missing, a permission fault, or any other readFileSync failure). `detail` is the real
+ * underlying Error#message from that failed read — not a guessed ENOENT string — so the
+ * report matches what the OS actually said, the same way the legacy single-file operator
+ * error always has.
+ *
+ * @param {string} path
+ * @param {{ scenario: boolean }} opts
+ * @param {string} detail - e.message from the failed readFileSync
+ */
+function unreadableResult(path, opts, detail) {
+  const kind = opts.scenario ? 'scenario' : 'policy';
+  const message = `could not read ${kind} file: ${path} — ${detail}`;
+  return opts.scenario
+    ? {
+        ok: false,
+        origin: 'scenario',
+        errors: [{ label: 'scenario-schema:', code: 'path_unreadable', location: '/', message }],
+        warnings: [],
+        coverageNote: SCENARIO_COVERAGE_NOTE,
+      }
+    : {
+        ok: false,
+        origin: originForPath(path),
+        errors: [{ label: 'policy-schema:', code: 'path_unreadable', location: '/', message }],
+        warnings: [],
+        coverageNote: COVERAGE_NOTE,
+      };
+}
+
+/**
+ * stat a path without throwing. `null` means "does not exist, or could not be stat'd for
+ * any other reason" — the caller never needs to know which, because either way the path
+ * is not a confirmed directory, so it is handled as a candidate file, and any real fault
+ * (missing, permission, ...) surfaces through the normal readFileSync path with its own
+ * accurate message instead of a guess made here.
+ */
+function safeStat(path) {
+  try {
+    return statSync(path);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Run the lint subcommand. Returns the exit code (does not call process.exit) so it is
+ * unit-testable with an injected stdout/stderr sink.
+ *
+ * Routing (F-49940082): a single positional that does not resolve to an existing
+ * directory takes the legacy single-file path below, unchanged in every statement and
+ * every error message from before directory-or-multi-path mode existed. Anything else —
+ * two or more positionals, or the sole positional resolving to a directory — is batch
+ * mode: every positional is either walked (if a directory) or linted directly (if a
+ * file), results are aggregated, and a batch summary is printed after the per-file
+ * blocks. See the module docstring for the discovery-semantics parity statement against
+ * scripts/lint-policies.test.mjs's policyFiles().
+ *
+ * @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 resolvedPaths = opts.paths.map((p) => resolve(p));
+  const soleStat = resolvedPaths.length === 1 ? safeStat(resolvedPaths[0]) : null;
+  const isBatch = resolvedPaths.length > 1 || (soleStat !== null && soleStat.isDirectory());
+
+  if (!isBatch) {
+    // ── legacy single-file path — byte-identical to pre-F-49940082 behavior. Same
+    // statements, same order, same error text; only factored through lintOneFile so
+    // batch mode below can share it instead of duplicating the read/parse/lint sequence. ──
+    const path = resolvedPaths[0];
+    const kind = opts.scenario ? 'scenario' : 'policy';
+    let result;
+    try {
+      result = lintOneFile(path, opts);
+    } catch (e) {
+      err(`ERROR: could not read ${kind} file: ${path} — ${e.message}`);
+      err('  hint: check the path exists and is readable');
+      return 2;
+    }
+    out(opts.json ? JSON.stringify(buildLintJson(result, path)) : renderLintText(result, path));
+    return result.ok ? 0 : 1;
+  }
+
+  // ── batch mode (F-49940082): directory-or-multi-path ──
+  const kind = opts.scenario ? 'scenario' : 'policy';
+  const discovered = new Set();
+  for (const p of resolvedPaths) {
+    const st = safeStat(p);
+    if (st !== null && st.isDirectory()) {
+      for (const f of walkYamlFiles(p)) discovered.add(f);
+    } else {
+      // Not a confirmed directory: a file, a missing path, or anything else safeStat
+      // could not classify. Hand it to lintOneFile as a candidate — a genuinely missing
+      // or unreadable path surfaces its real OS error there, not a guess made here.
+      discovered.add(p);
+    }
+  }
+  const files = [...discovered].sort((a, b) => a.localeCompare(b));
+
+  if (files.length === 0) {
+    // Every positional was a confirmed directory and none contributed a file to lint.
+    // A lint that finds nothing and exits 0 is a vacuous pass — fail loud instead of
+    // silently doing nothing (swarms/CLAUDE.md: "a gate that can't go red is theater").
+    err(`ERROR: no ${kind} files found under: ${resolvedPaths.join(', ')}`);
+    err('  hint: an empty directory, or one with no yaml files, has nothing to lint');
+    return 2;
+  }
+
+  const summary = { total: files.length, clean: 0, withErrors: 0, withWarnings: 0 };
+  const textBlocks = [];
+  const jsonFiles = [];
+
+  for (const path of files) {
+    let result;
+    try {
+      result = lintOneFile(path, opts);
+    } catch (e) {
+      result = unreadableResult(path, opts, e.message);
+    }
+
+    if (result.errors.length) summary.withErrors++;
+    else if (result.warnings.length) summary.withWarnings++;
+    else summary.clean++;
+
+    if (opts.json) jsonFiles.push(buildLintJson(result, path));
+    else textBlocks.push(renderLintText(result, path));
+  }
+
+  out(opts.json
+    ? JSON.stringify(buildBatchLintJson(jsonFiles, summary))
+    : `${textBlocks.join('\n\n')}\n\n${renderBatchSummary(summary)}`);
+
+  return summary.withErrors > 0 ? 1 : 0;
 }

package/cli.js

@@ -67,6 +67,21 @@ class OperatorError extends Error {
   }
 }
 
+/**
+ * V2-CONTRACT-004: appended to EVERY --explain rendering (accepted and
+ * rejected alike) so a preview verdict can never be read as covering the
+ * required_steps gate, which only production ingest enforces (it fetches the
+ * scenario definitions this preview does not have).
+ *
+ * Declared ahead of USAGE and interpolated directly into its own "Not checked
+ * in preview" section below (F-e0c3fa21 — that section used to restate the
+ * header as its own redundant lowercase lead-in, worded slightly differently
+ * than this constant) so --help and --explain describe the identical gap
+ * from one shared string and can never drift apart again.
+ */
+const PREVIEW_GAP_NOTE =
+  'Not checked in preview: required_steps (needs scenario definitions — enforced only by real ingest).';
+
 const USAGE = `verify — local dry-run / explain for dogfood submissions
 
 Usage:
@@ -92,8 +107,7 @@ Provenance (default: stub):
 
   -h, --help           Show this help.
 
-Not checked in preview:
-  not checked in preview: required_steps (needs scenario definitions).
+${PREVIEW_GAP_NOTE}
   Scenario definitions live in the source repo; only a real ingest fetches
   them and enforces success_criteria.required_steps.
 
@@ -362,15 +376,6 @@ function resolveProvenance(provenanceMode, submission) {
  * the routing decision parseRejectionReason() makes; this maps it to operator
  * language so the consumer knows WHOSE problem each reason is.
  */
-/**
- * V2-CONTRACT-004: appended to EVERY --explain rendering (accepted and
- * rejected alike) so a preview verdict can never be read as covering the
- * required_steps gate, which only production ingest enforces (it fetches the
- * scenario definitions this preview does not have).
- */
-const PREVIEW_GAP_NOTE =
-  'Not checked in preview: required_steps (needs scenario definitions — enforced only by real ingest).';
-
 const CLASS_LABEL = {
   'submission-bad': 'SUBMISSION  — fix your payload and resubmit',
   'operational': 'OPERATIONAL — verifier/tooling fault; page ops, do not bounce to submitter',