@veda-hq/pariksha 0.5.19 → 0.6.4

package/README.md

@@ -4,8 +4,8 @@
 test-quality ratchets. Part of [Veda](https://github.com/veda-hq/veda).
 
 ```sh
-npx @veda-hq/pariksha@0.5.19 <check> [flags]
-npx @veda-hq/pariksha@0.5.19 --version
+npx @veda-hq/pariksha@0.6.4 <check> [flags]
+npx @veda-hq/pariksha@0.6.4 --version
 ```
 
 Every check exits 0 when the repository passes, 1 when it refuses something
@@ -72,19 +72,32 @@ step's `if:`, or any `${{ … }}` in the job, outside quoted literals. Text in
 a `run:` script and an action input named `if` are not reads. A non-gating
 job (a change detector) need not be gated, but must be declared once read.
 
+The same command refuses a workflow that holds a gate and can also be
+dispatched (`workflow_dispatch` in `on:`, as one event, in a list or as a
+key), one line per gate under its own id, `dispatch-on-gate-workflow`. A
+dispatch run from a branch with an open pull request posts every job's check
+on the head commit, the gate among them as skipped, and that replaces the
+pull request run's success: a merge queue requiring the gate reads it as
+failed and dequeues the pull request. Ad-hoc runs belong in a separate
+workflow with no gate-named job.
+
 ```json
-{ "id": "CI-001", "workflowsDir": ".github/workflows", "gateName": "gate$", "nonGating": ["detect-changes"] }
+{ "id": "CI-001", "workflowsDir": ".github/workflows", "gateName": "gate$", "nonGating": ["detect-changes"], "dispatchAllowed": [] }
 ```
 
 - `id` (default `aggregate-gate-needs`) names the check in its messages: a
-  project's rule id, say.
+  project's rule id, say. The dispatch refusal keeps its own id.
 - `workflowsDir` (default `.github/workflows`, relative to the root).
 - `gateName` (default `gate$`) is a regex, matched case-insensitively.
 - `nonGating` (default none) lists job ids that gate nothing.
+- `dispatchAllowed` (default none) lists workflow file names (`release.yml`)
+  that may be dispatched beside a gate: one no merge queue requires, such as
+  an approval gate in a release workflow.
 
 A workflow that does not parse is reported as a gap, never passed. No
 workflow to read exits 1 (`no workflow files found — the lookup failed`),
-as the original did; a bad config exits 2.
+as the original did; a bad config exits 2. The clean line is unchanged: it
+prints only when both refusals find nothing.
 
 ## `authority-citations`
 
@@ -931,6 +944,47 @@ refuse is not passed: it is printed as a selector not version-checked.
 line to stdout; a missing input file is a failure (exit 1), a bad config or
 an unreadable `package.json` exits 2.
 
+## `python-floor`
+
+```sh
+pariksha python-floor --python <interpreter> --floor-file <path> [--exclude <regex>] [--selector <path>] [--root <dir>]
+```
+
+Every tracked Python source runs on the Python the repository declares. The
+floor drifts unseen: CI runners ship a new Python, and a PEP 604 union or a
+fresh stdlib import reads as ordinary code until it fails on an older
+interpreter, inside whatever was running it. Sources are `*.py` files, and
+heredocs and single-quoted `python3 -c '...'` payloads in `*.sh` files and
+under `.husky/`, read from the index (the commit being made, not the working
+tree). Each is refused for:
+
+1. syntax the floor cannot parse (`ast` with `feature_version` at the floor);
+2. a stdlib module added after the floor, or removed at or before it;
+3. on a floor below 3.10, a PEP 604 `X | Y` that is evaluated.
+
+A source it cannot read (an unknown encoding, a symlink, conflict stages) is
+refused, never skipped.
+
+- `--python` names the interpreter, at or above the floor; pariksha never
+  chooses or bundles one. Below the floor it refuses to judge (exit 2).
+- `--floor-file` is the file, relative to the root and tracked, holding one
+  `MAJOR.MINOR` (`#` comments allowed).
+- `--exclude` (default none) is a Python regular expression matched from the
+  start of each path; what it matches is not checked. One that does not
+  compile exits 2.
+- `--selector` (default none) names what picks an interpreter at or above
+  the floor in this repository, for the message given when `--python` is
+  below it.
+
+The check is a stdlib-only script shipped in the package
+(`python/python-floor.py`), run as `<interpreter> python/python-floor.py`;
+its stdout (the clean line), stderr (findings) and exit code are passed
+through unchanged. An interpreter that cannot be started, or that is stopped
+by a signal, exits 2. Two input errors exit 1, as the script always has: a
+floor file that is not in the index, not a regular file there, or not one
+`MAJOR.MINOR` (one line on stderr), and a `--root` outside a git repository
+(a Python traceback).
+
 ## `required-settings`
 
 ```sh
@@ -989,6 +1043,38 @@ Parsing those is the job of a command guard such as kavach's `git_safety`.
 project's settings and then also skips the user's own `defaultMode`, so it
 belongs in user settings only.
 
+## `schema-roots`
+
+```sh
+pariksha schema-roots [--files-from <file>|-] [--root <dir>] [<file>...]
+```
+
+The Anthropic API refuses a tool's `input_schema`, or a structured output's
+schema, with `allOf`, `anyOf` or `oneOf` at its root, answering 400:
+"input_schema does not support oneOf, allOf, or anyOf at the top level". The
+request fails before the first tool call, so an agent built on that schema
+dies at its start every time. This reads the JSON files it is given and refuses each such
+schema:
+
+- the value under `input_schema`, `inputSchema`, `output_schema`,
+  `outputSchema` or `json_schema`, and the `schema` inside a `json_schema`,
+  at any depth, in objects and arrays (a request's `tools` list, say);
+- the `schema` of an object whose `type` is `json_schema`, a structured
+  output format;
+- the root of a file named `*.schema.json`.
+
+A combinator below a schema's root is allowed, and a schema found is not read
+further: a property inside it named `input_schema` is a property. Each
+finding goes to stderr as `<file>: <json path>: top-level <keyword>`, with
+the fix: express the condition in code after the call returns.
+
+The files are the ones named on the command line and the ones `--files-from`
+lists, one path per line (a file, or `-` for stdin); relative paths are read
+from the root. Only `.json` files are read, so a list of changed files can
+hold others; YAML is not read. No file to read passes. The first `.json`
+file that cannot be read or is not plain JSON (one with comments, say) exits
+2, naming it, and no finding is printed; so does a list that cannot be read.
+
 ## `shell-gates`
 
 ```sh

package/dist/aggregate-gate-needs.js

@@ -15,20 +15,32 @@
 // `${{ … }}` in the job. Not read: text in a `run:` script, quoted literals in
 // an expression, and an action input that happens to be called `if`. A
 // workflow that does not parse is reported, never read as having no gaps.
+//
+// The same workflows are also refused a `workflow_dispatch` trigger beside a
+// gate (dispatch-on-gate-workflow): a dispatch run from a branch with an open
+// pull request posts every job's check on the head commit, the gate among
+// them as skipped, and that replaces the pull request run's success. A merge
+// queue requiring the gate then reads it as failed and dequeues the pull
+// request. `dispatchAllowed` names the workflows (by file name) where that
+// cannot happen, for a project with no merge queue on the gate.
 import { readdirSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 import { load as parseYaml } from 'js-yaml';
 export const DEFAULT_GATE_CONFIG = {
     workflowsDir: '.github/workflows',
     gateName: /gate$/i,
     nonGating: new Set(),
     id: 'aggregate-gate-needs',
+    dispatchAllowed: new Set(),
 };
+/** What the messages call the dispatch refusal: its own rule, not the project's needs rule. */
+export const DISPATCH_ID = 'dispatch-on-gate-workflow';
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 /**
  * `{ "id"?: "<label>", "workflowsDir"?: "<dir>", "gateName"?: "<regex>",
- * "nonGating"?: ["<job id>", …] }`; `gateName` matches case-insensitively.
- * Absent keys take the defaults; anything else throws.
+ * "nonGating"?: ["<job id>", …], "dispatchAllowed"?: ["<file name>", …] }`;
+ * `gateName` matches case-insensitively. Absent keys take the defaults;
+ * anything else throws.
  */
 export const parseGateConfig = (text) => {
     let raw;
@@ -40,7 +52,7 @@ export const parseGateConfig = (text) => {
     }
     if (!isRecord(raw))
         throw new Error('the config must be a JSON object');
-    const unknown = Object.keys(raw).find((k) => !['id', 'workflowsDir', 'gateName', 'nonGating'].includes(k));
+    const unknown = Object.keys(raw).find((k) => !['id', 'workflowsDir', 'gateName', 'nonGating', 'dispatchAllowed'].includes(k));
     if (unknown !== undefined)
         throw new Error(`unknown key "${unknown}"`);
     const text_ = (key, fallback) => {
@@ -60,10 +72,15 @@ export const parseGateConfig = (text) => {
     catch (e) {
         throw new Error(`"gateName" is not a regex: ${e.message}`);
     }
-    const nonGating = 'nonGating' in raw ? raw['nonGating'] : [];
-    if (!Array.isArray(nonGating) || nonGating.some((j) => typeof j !== 'string' || j === ''))
-        throw new Error('"nonGating" must be a list of job ids');
-    return { id, workflowsDir, gateName, nonGating: new Set(nonGating) };
+    const names = (key, what) => {
+        const value = key in raw ? raw[key] : [];
+        if (!Array.isArray(value) || value.some((j) => typeof j !== 'string' || j === ''))
+            throw new Error(`"${key}" must be a list of ${what}`);
+        return new Set(value);
+    };
+    const nonGating = names('nonGating', 'job ids');
+    const dispatchAllowed = names('dispatchAllowed', 'workflow file names');
+    return { id, workflowsDir, gateName, nonGating, dispatchAllowed };
 };
 /** The `.yml` and `.yaml` files in the workflows folder, as root-relative paths; none when it cannot be read. */
 export const workflowFiles = (root, dir) => {
@@ -107,23 +124,31 @@ export const consumedNeeds = (job) => {
     return [...ids];
 };
 const asArray = (needs) => (needs === undefined ? [] : Array.isArray(needs) ? needs : [needs]);
+/** The workflow at `relative`, or undefined when it does not parse; a scalar or null document is no job map, read as empty. */
+const readWorkflow = (root, relative) => {
+    let parsed;
+    try {
+        parsed = parseYaml(readFileSync(join(root, relative), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    return typeof parsed === 'object' && parsed !== null ? parsed : {};
+};
+/** The ids of the workflow's gates: jobs whose `name:` (or id), or id, matches `gateName`. */
+const gatesOf = (jobs, config) => Object.keys(jobs).filter((id) => config.gateName.test(jobs[id]?.name ?? id) || config.gateName.test(id));
 /** Each gate, in each of `files` (root-relative), whose `needs:` leaves out a job it gates or reads. */
 export const findGateGaps = (root, files, config) => {
     const gaps = [];
     for (const relative of files) {
-        let document;
-        try {
-            // A workflow that parses to a scalar or null is no job map: read as empty.
-            const parsed = parseYaml(readFileSync(join(root, relative), 'utf8'));
-            document = typeof parsed === 'object' && parsed !== null ? parsed : {};
-        }
-        catch {
+        const document = readWorkflow(root, relative);
+        if (document === undefined) {
             gaps.push({ workflow: relative, gate: '(unparseable)', missing: ['<file did not parse>'] });
             continue;
         }
         const jobs = document.jobs ?? {};
         const jobIds = Object.keys(jobs);
-        const gateIds = jobIds.filter((id) => config.gateName.test(jobs[id]?.name ?? id) || config.gateName.test(id));
+        const gateIds = gatesOf(jobs, config);
         for (const gateId of gateIds) {
             const declared = new Set(asArray(jobs[gateId]?.needs));
             const missing = jobIds.filter((id) => id !== gateId && !gateIds.includes(id) && !config.nonGating.has(id) && !declared.has(id));
@@ -135,19 +160,53 @@ export const findGateGaps = (root, files, config) => {
     }
     return gaps;
 };
-/** The verdict on the workflows under `root`, worded as the original check worded it. */
+/** Whether the workflow's `on:` (one event, a list, or a map) holds `workflow_dispatch`; a map's value is usually null. */
+export const hasDispatch = (on) => {
+    if (typeof on === 'string')
+        return on === 'workflow_dispatch';
+    if (Array.isArray(on))
+        return on.includes('workflow_dispatch');
+    return isRecord(on) && Object.hasOwn(on, 'workflow_dispatch');
+};
+/**
+ * Each gate, in each of `files` (root-relative), whose workflow can also be
+ * dispatched, outside `dispatchAllowed`. A workflow that does not parse is
+ * left to findGateGaps, which reports it.
+ */
+export const findDispatchedGates = (root, files, config) => {
+    const found = [];
+    for (const relative of files) {
+        if (config.dispatchAllowed.has(basename(relative)))
+            continue;
+        const document = readWorkflow(root, relative);
+        if (document === undefined || !hasDispatch(document.on))
+            continue;
+        for (const gate of gatesOf(document.jobs ?? {}, config))
+            found.push({ workflow: relative, gate });
+    }
+    return found;
+};
+/** The refusal of one dispatched gate, one line. */
+export const dispatchMessage = (found) => `❌ ${DISPATCH_ID}: ${found.workflow}: workflow_dispatch on the workflow holding the required gate ${found.gate}. ` +
+    "A dispatch run posts the gate as skipped on the PR's head commit, which a merge queue reads as failed and dequeues the PR. " +
+    'Move ad-hoc runs to a separate workflow with no gate-named job.';
+/** The verdict on the workflows under `root`: the needs gaps worded as the original check worded them, then each dispatched gate. */
 export const checkGates = (root, config) => {
     const files = workflowFiles(root, config.workflowsDir);
     if (files.length === 0)
         return { ok: false, out: [], err: [`❌ ${config.id}: no workflow files found — the lookup failed`] };
     const gaps = findGateGaps(root, files, config);
-    if (gaps.length === 0)
+    const dispatched = findDispatchedGates(root, files, config).map(dispatchMessage);
+    if (gaps.length === 0 && dispatched.length === 0)
         return { ok: true, out: [`✅ ${config.id}: every aggregate gate depends on all its jobs (${files.length} workflow(s))`], err: [] };
-    const err = [`\n❌ ${config.id}: ${gaps.length} aggregate gate(s) with an incomplete needs list\n`];
-    for (const gap of gaps)
-        err.push(` ${gap.workflow} → job "${gap.gate}"`, `   not depended on: ${gap.missing.join(', ')}\n`);
-    err.push('The merge queue checks only the gate. A job absent from its `needs:` cannot\n' +
-        'block a merge however it fails — and a failure upstream turns into a SKIP\n' +
-        'downstream, which the gate then accepts.\n');
-    return { ok: false, out: [], err };
+    const err = [];
+    if (gaps.length > 0) {
+        err.push(`\n❌ ${config.id}: ${gaps.length} aggregate gate(s) with an incomplete needs list\n`);
+        for (const gap of gaps)
+            err.push(` ${gap.workflow} → job "${gap.gate}"`, `   not depended on: ${gap.missing.join(', ')}\n`);
+        err.push('The merge queue checks only the gate. A job absent from its `needs:` cannot\n' +
+            'block a merge however it fails — and a failure upstream turns into a SKIP\n' +
+            'downstream, which the gate then accepts.\n');
+    }
+    return { ok: false, out: [], err: [...err, ...dispatched] };
 };

package/dist/cli.js

@@ -31,6 +31,8 @@ import { emptyRoots, growthSince, readBaseline, wholeId } from "./registry-ratch
 import { checkClaims, formatOutcome, loadEslint, parseConfig as parseClaimsConfig } from "./enforcement-claims.js";
 import { parseConfig as parseDuplicateConfig, runDuplicateTests } from "./duplicate-tests.js";
 import { DEFAULT_RUNS, npxVitest, parseConfig as parseFlakyConfig, parseRuns, runFlakyTests } from "./flaky-tests.js";
+import { inheritRunner, runPythonFloor } from "./python-floor.js";
+import { checkSchemaRoots, jsonFiles, readDocuments } from "./schema-roots.js";
 export const DENY_FILE = '.veda/deny.sha256';
 const USAGE = [
     'usage: pariksha authority-citations [--mode staged|tree] [--authority <a,b>] [--issue-prefix <A,B>] [--adr-dir <dir>] [--root <dir>]',
@@ -51,7 +53,9 @@ const USAGE = [
     '       pariksha masked-exit-codes [--config <file>] [--staged] [--root <dir>]',
     '       pariksha non-synced-resources [--config <file>] [--files-from <file>|-] [--root <dir>]',
     '       pariksha pnpm-settings [--config <file>] [--root <dir>]',
+    '       pariksha python-floor --python <interpreter> --floor-file <path> [--exclude <regex>] [--selector <path>] [--root <dir>]',
     '       pariksha required-settings --require <file> [--settings <file>] [--root <dir>]',
+    '       pariksha schema-roots [--files-from <file>|-] [--root <dir>] [<file>...]',
     '       pariksha shell-gates [--config <file>] [--staged | --all | --base <ref> | --files-from <file>|-] [--only <checks>] [--root <dir>]',
     '       pariksha hash <word>',
     '       pariksha --version',
@@ -769,6 +773,72 @@ const flakyTests = (f, io) => {
     }
     return runFlakyTests(selected.config, runs, selected.mode, root, selected.files, io.vitest ?? npxVitest, io.out);
 };
+/** python-floor: the packaged script under the `--python` the caller names, its output and exit code passed through. */
+const pythonFloor = (f, io) => {
+    const python = f.get('--python');
+    const floorFile = f.get('--floor-file');
+    if (python === undefined || floorFile === undefined) {
+        io.err(USAGE);
+        return 2;
+    }
+    const root = f.get('--root');
+    const exclude = f.get('--exclude');
+    const selector = f.get('--selector');
+    const options = {
+        python,
+        floorFile,
+        ...(root === undefined ? {} : { root }),
+        ...(exclude === undefined ? {} : { exclude }),
+        ...(selector === undefined ? {} : { selector }),
+    };
+    return runPythonFloor(options, io.python ?? inheritRunner, io.err);
+};
+/** `rest` split into its `--name value` pairs and the bare words around them, the files a command names. */
+export const splitFiles = (rest) => {
+    const flagArgs = [];
+    const files = [];
+    for (let i = 0; i < rest.length; i += 1) {
+        const word = rest[i];
+        if (!word.startsWith('--')) {
+            files.push(word);
+            continue;
+        }
+        flagArgs.push(...rest.slice(i, i + 2));
+        i += 1;
+    }
+    return { flagArgs, files };
+};
+/**
+ * schema-roots: the `.json` files named on the command line and in the
+ * `--files-from` list, relative ones read from the root; other files are
+ * not read, and none at all is a pass. The first file that cannot be read or
+ * parsed exits 2, naming it, with no finding printed.
+ */
+const schemaRoots = (rest, io) => {
+    const P = 'pariksha schema-roots:';
+    const { flagArgs, files: named } = splitFiles(rest);
+    const f = flags(flagArgs, ['--files-from', '--root']);
+    if (!f) {
+        io.err(USAGE);
+        return 2;
+    }
+    const root = resolve(f.get('--root') ?? '.');
+    const from = f.get('--files-from');
+    let documents;
+    try {
+        const listed = [...named, ...(from === undefined ? [] : entries(listFrom(from, io)))];
+        const files = [...new Set(jsonFiles(listed).map((p) => relative(root, resolve(root, p))))];
+        documents = readDocuments(files, (file) => readFileSync(resolve(root, file), 'utf8'));
+    }
+    catch (e) {
+        io.err(`${P} ${e.message}; nothing was checked, so this is not a pass`);
+        return 2;
+    }
+    const result = checkSchemaRoots(documents);
+    result.out.forEach(io.out);
+    result.err.forEach(io.err);
+    return result.ok ? 0 : 1;
+};
 const COMMANDS = {
     'codec-registry': { allowed: ['--config', '--base', '--root'], switches: ['--no-base'], run: codecRegistry },
     'coverage-exemptions': { allowed: ['--config', '--package', '--root'], run: coverageExemptions },
@@ -777,6 +847,7 @@ const COMMANDS = {
     'aggregate-gate-needs': { allowed: ['--config', '--root'], run: aggregateGateNeeds },
     'non-synced-resources': { allowed: ['--config', '--files-from', '--root'], run: nonSyncedResources },
     'pnpm-settings': { allowed: ['--config', '--root'], run: pnpmSettings },
+    'python-floor': { allowed: ['--python', '--floor-file', '--exclude', '--selector', '--root'], run: pythonFloor },
     'authority-citations': { allowed: ['--mode', '--authority', '--issue-prefix', '--adr-dir', '--root'], run: authorityCitations },
     boundary: { allowed: ['--root', '--deny'], run: boundary },
     'coverage-by-type': { allowed: ['--config', '--files-from', '--root'], run: coverageByType },
@@ -802,6 +873,9 @@ export const run = (args, io, version = ownVersion(), env = process.env) => {
         io.out(hash(rest[0]));
         return 0;
     }
+    // The one check that takes files as bare words, so not through `flags`.
+    if (command === 'schema-roots')
+        return schemaRoots(rest, io);
     const spec = command !== undefined && Object.hasOwn(COMMANDS, command) ? COMMANDS[command] : undefined;
     const f = spec && flags(rest, spec.allowed, spec.switches);
     if (!spec || !f) {

package/dist/python-floor.js

@@ -0,0 +1,32 @@
+// python-floor: every tracked Python source runs on the interpreter a repository
+// declares. The check is python/python-floor.py, run under the interpreter the
+// caller names; pariksha never chooses or bundles a Python, and passes the
+// script's stdout, stderr and exit code through unchanged.
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+/** The packaged script: beside src/ in the repository, beside dist/ in the npm package. */
+export const SCRIPT = join(import.meta.dirname, '..', 'python', 'python-floor.py');
+export const inheritRunner = (python, args) => spawnSync(python, args, { stdio: 'inherit' });
+/** The script's arguments: each option only when given, so its own defaults hold. */
+export const scriptArgs = (options) => [
+    SCRIPT,
+    '--floor-file',
+    options.floorFile,
+    ...(options.root === undefined ? [] : ['--root', options.root]),
+    ...(options.exclude === undefined ? [] : ['--exclude', options.exclude]),
+    ...(options.selector === undefined ? [] : ['--selector', options.selector]),
+];
+/** The script's exit code; 2, with a reason on `err`, when it could not run or did not exit. */
+export const runPythonFloor = (options, runner, err) => {
+    const P = 'pariksha python-floor:';
+    const result = runner(options.python, scriptArgs(options));
+    if (result.error !== undefined) {
+        err(`${P} cannot run ${options.python}: ${result.error.message}; nothing was checked, so this is not a pass`);
+        return 2;
+    }
+    if (result.status === null) {
+        err(`${P} ${options.python} was stopped by ${String(result.signal)}; nothing was checked, so this is not a pass`);
+        return 2;
+    }
+    return result.status;
+};

package/dist/schema-roots.js

@@ -0,0 +1,92 @@
+// schema-roots: no tool or output schema with a combinator at its root.
+//
+// The Anthropic API refuses a tool's `input_schema`, or a structured output's
+// schema, whose root holds `allOf`, `anyOf` or `oneOf` (a 400, "input_schema
+// does not support oneOf, allOf, or anyOf at the top level"). The request
+// fails before the model's first tool call, so an agent built on that schema
+// dies at its start, every time, with nothing wrong in its own code. This
+// reads JSON documents and refuses each such schema it finds:
+//
+// - the value under `input_schema`, `inputSchema`, `output_schema`,
+//   `outputSchema` or `json_schema`, and the `schema` inside a `json_schema`;
+// - the `schema` of an object whose `type` is `json_schema` (a structured
+//   output format: `{ "type": "json_schema", "schema": {…} }`);
+// - the root of a file named `*.schema.json`.
+//
+// A schema found is not read further: a combinator below its root is allowed,
+// and a property inside it that happens to be called `input_schema` is a
+// property, not a tool.
+import { basename } from 'node:path';
+export const COMBINATORS = ['allOf', 'anyOf', 'oneOf'];
+/** The keys whose value is a tool's or an output's schema. */
+export const SCHEMA_KEYS = ['input_schema', 'inputSchema', 'output_schema', 'outputSchema', 'json_schema'];
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** `path` one step further: `[0]`, `.name`, or `["a key"]` for a key that is no identifier. */
+const step = (path, key) => typeof key === 'number' ? `${path}[${key}]` : /^[A-Za-z_$][\w$]*$/.test(key) ? `${path}.${key}` : `${path}[${JSON.stringify(key)}]`;
+/** Each tool or output schema in `document`, the JSON of `file`, whose root holds a combinator. */
+export const findRootCombinators = (file, document) => {
+    const found = [];
+    const atRoot = (schema, path) => {
+        if (!isRecord(schema))
+            return;
+        for (const keyword of COMBINATORS)
+            if (Object.hasOwn(schema, keyword))
+                found.push({ file, path, keyword });
+    };
+    const walk = (value, path) => {
+        if (Array.isArray(value)) {
+            value.forEach((item, i) => walk(item, step(path, i)));
+            return;
+        }
+        if (!isRecord(value))
+            return;
+        const format = value['type'] === 'json_schema' && isRecord(value['schema']);
+        for (const [key, child] of Object.entries(value)) {
+            const at = step(path, key);
+            if (format && key === 'schema')
+                atRoot(child, at);
+            else if (SCHEMA_KEYS.includes(key)) {
+                atRoot(child, at);
+                if (key === 'json_schema' && isRecord(child))
+                    atRoot(child['schema'], step(at, 'schema'));
+            }
+            else
+                walk(child, at);
+        }
+    };
+    if (basename(file).endsWith('.schema.json'))
+        atRoot(document, '$');
+    else
+        walk(document, '$');
+    return found;
+};
+/** The refusal of one schema, one line. */
+export const rootMessage = (found) => `pariksha schema-roots: ${found.file}: ${found.path}: top-level ${found.keyword}. ` +
+    'The API rejects tool and output schemas with oneOf, allOf or anyOf at the root; express the condition in code after the call returns.';
+/** The JSON files among `paths`: the ones this check reads. */
+export const jsonFiles = (paths) => paths.filter((p) => /\.json$/i.test(p));
+/** A file's text as JSON, a leading byte-order mark dropped; throws `not JSON: …`. */
+export const parseJson = (text) => {
+    try {
+        return JSON.parse(text.startsWith('') ? text.slice(1) : text);
+    }
+    catch (e) {
+        throw new Error(`not JSON: ${e.message}`);
+    }
+};
+/** Each of `files`, read by `read` and parsed; throws on the first that cannot be, naming it. */
+export const readDocuments = (files, read) => files.map((file) => {
+    try {
+        return { file, json: parseJson(read(file)) };
+    }
+    catch (e) {
+        throw new Error(`${file}: ${e.message}`);
+    }
+});
+/** The verdict on `documents`, each a file's path and its parsed JSON. */
+export const checkSchemaRoots = (documents) => {
+    const found = documents.flatMap((d) => findRootCombinators(d.file, d.json));
+    if (found.length > 0)
+        return { ok: false, out: [], err: found.map(rootMessage) };
+    return { ok: true, out: [`pariksha schema-roots: ${documents.length} JSON file(s), no tool or output schema with oneOf, allOf or anyOf at its root`], err: [] };
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@veda-hq/pariksha",
-  "version": "0.5.19",
-  "description": "Repository checks: doc drift, rule enforcement, test-quality ratchets. Checks: absolute-paths, aggregate-gate-needs, authority-citations, boundary, codec-registry, coverage-by-type, coverage-exemptions, doc-budgets, doc-references, duplicate-tests, enforcement-claims, env-gate-switches, export-deletions, fault-injection-registry, flaky-tests, masked-exit-codes, non-synced-resources, pnpm-settings, required-settings, shell-gates. Also markdownlint rules for Markdown that renders mangled: @veda-hq/pariksha/markdownlint.",
+  "version": "0.6.4",
+  "description": "Repository checks: doc drift, rule enforcement, test-quality ratchets. Checks: absolute-paths, aggregate-gate-needs, authority-citations, boundary, codec-registry, coverage-by-type, coverage-exemptions, doc-budgets, doc-references, duplicate-tests, enforcement-claims, env-gate-switches, export-deletions, fault-injection-registry, flaky-tests, masked-exit-codes, non-synced-resources, pnpm-settings, python-floor, required-settings, schema-roots, shell-gates. Also markdownlint rules for Markdown that renders mangled: @veda-hq/pariksha/markdownlint.",
   "keywords": [
     "repository checks",
     "lint",
@@ -36,6 +36,7 @@
   },
   "files": [
     "dist",
+    "python",
     "baselines",
     "NOTICE"
   ],

package/python/python-floor.py

@@ -0,0 +1,631 @@
+#!/usr/bin/env python3
+"""Every tracked Python source must run on the interpreter this repo declares.
+
+WHY THIS EXISTS
+---------------
+The floor in the ``--floor-file`` is only worth declaring if something
+notices when code drifts above it. The drift is invisible in CI — Ubuntu
+runners ship a new Python — and invisible in review, because a PEP 604 union or
+a fresh stdlib import looks like ordinary modern Python. It surfaces on a
+developer's Mac, from inside a validator, as a message about something else:
+
+  * ``scripts/run-validation.sh`` grew ``-> bytes | None`` annotations. Before
+    3.10 those are evaluated at ``def`` time, so a clean ``git merge`` died with
+    ``TypeError: unsupported operand type(s) for |`` — which the Codex isolation
+    validator re-reported as "policy history gate rejected authorized
+    activation", i.e. as a trust-chain violation.
+  * ``validate-codex-workflow-ports.py`` grew ``import tomllib`` (3.11+), which
+    fails as ``ModuleNotFoundError`` with no hint that a Python version is the
+    cause.
+
+Three checks, all measured against the declared floor rather than a constant,
+so lowering the floor re-arms the ones that are currently inert:
+
+  1. syntax — parsed with ``ast``'s ``feature_version`` set to the floor;
+  2. stdlib — modules added after the floor, or removed at or before it;
+  3. runtime PEP 604 — ``X | Y`` that is *evaluated*, which is every use before
+     3.10 except an annotation guarded by ``from __future__ import annotations``.
+
+Usage: python-floor.py --floor-file PATH [--exclude REGEX] [--selector PATH] [--root DIR] [--floor 3.11]
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import io
+import re
+import subprocess
+import tokenize
+import sys
+from pathlib import Path
+
+
+# The floor file, relative to the root: --floor-file, set by main().
+FLOOR_FILE = Path()
+
+# Top-level stdlib modules and the version that introduced them. Only entries
+# at or after 3.9 matter: anything older predates every floor worth declaring.
+# An import of a module absent from this table is assumed to be old enough,
+# which is the safe default — a false negative here costs a portability bug,
+# while a false positive would block a legitimate import.
+ADDED_IN = {
+    "graphlib": (3, 9),
+    "zoneinfo": (3, 9),
+    "tomllib": (3, 11),
+    "annotationlib": (3, 14),
+    "compression": (3, 14),
+}
+
+# Modules removed by a given version, so raising the floor catches code that
+# still imports them. PEP 594 took most of these out in 3.12.
+REMOVED_IN = {
+    "asynchat": (3, 12),
+    "asyncore": (3, 12),
+    "distutils": (3, 12),
+    "imp": (3, 12),
+    "smtpd": (3, 12),
+    "aifc": (3, 13),
+    "cgi": (3, 13),
+    "cgitb": (3, 13),
+    "telnetlib": (3, 13),
+}
+
+# A heredoc that feeds Python: the command word on the line is a python
+# interpreter. Matching on the command rather than the tag keeps a
+# `cat <<PYTHON_NOTES` out of the scan and keeps `python3 - <<EOF` in it.
+HEREDOC = re.compile(
+    r"\bpython3?(?:\.\d+)?\b[^\n<]*<<(-)?\s*(['\"]?)([A-Za-z_][A-Za-z0-9_]*)\2\s*$"
+)
+
+# `python3 -c '...'` with a single-quoted payload, which may span lines. Double
+# quotes are skipped deliberately: the shell interpolates them, so the bytes in
+# the file are not the bytes Python sees.
+INLINE = re.compile(r"\bpython3?(?:\.\d+)?\b[^\n]*?\s-c\s+'")
+
+
+class Finding:
+    def __init__(self, where: str, line: int, rule: str, detail: str, remedy: str) -> None:
+        self.where = where
+        self.line = line
+        self.rule = rule
+        self.detail = detail
+        self.remedy = remedy
+
+    def render(self) -> str:
+        return (
+            f"  {self.where}:{self.line}\n"
+            f"      {self.rule}: {self.detail}\n"
+            f"      fix: {self.remedy}"
+        )
+
+
+class Source:
+    """One unit of Python: a file, a heredoc body, or a `-c` payload."""
+
+    def __init__(self, where: str, first_line: int, text: str) -> None:
+        self.where = where
+        self.first_line = first_line
+        self.text = text
+
+    def at(self, node_line: int) -> int:
+        return self.first_line + node_line - 1
+
+
+class Entry:
+    """One index entry: what a commit made now would record at ``path``."""
+
+    def __init__(self, mode: str, oid: str, stage: str, path: str) -> None:
+        self.mode = mode
+        self.oid = oid
+        self.stage = stage
+        self.path = path
+
+
+# Index modes that are not a regular file's bytes: a symlink's blob is its
+# target path, and a gitlink names a commit in another repository.
+SYMLINK_MODE = "120000"
+GITLINK_MODE = "160000"
+REGULAR_MODES = {"100644", "100755"}
+
+
+def index_entries(root: Path) -> list[Entry]:
+    """The index, not the working tree, because this gate runs at pre-commit.
+
+    Reading files from disk judged something other than the commit: a tracked
+    file deleted with the deletion unstaged was refused as unreadable although
+    the commit keeps it unchanged, and a broken staged file passed as long as
+    the copy on disk had been repaired without staging the repair.
+    """
+    out = subprocess.run(
+        ["git", "-C", str(root), "ls-files", "--stage", "-z"],
+        capture_output=True,
+        check=True,
+    ).stdout.decode()
+    entries: list[Entry] = []
+    for record in out.split("\0"):
+        if not record:
+            continue
+        meta, path = record.split("\t", 1)
+        mode, oid, stage = meta.split(" ")
+        entries.append(Entry(mode, oid, stage, path))
+    return entries
+
+
+def read_blobs(root: Path, oids: list[str]) -> dict[str, bytes | None]:
+    """Blob bytes by object id, from one `git cat-file --batch`; None if missing."""
+    stdout = subprocess.run(
+        ["git", "-C", str(root), "cat-file", "--batch"],
+        input="".join(f"{oid}\n" for oid in oids).encode(),
+        capture_output=True,
+        check=True,
+    ).stdout
+    blobs: dict[str, bytes | None] = {}
+    offset = 0
+    for oid in oids:
+        end = stdout.index(b"\n", offset)
+        header = stdout[offset:end].decode().split(" ")
+        offset = end + 1
+        if len(header) != 3:
+            # `<oid> missing`: no content follows the header.
+            blobs[oid] = None
+            continue
+        size = int(header[2])
+        blobs[oid] = stdout[offset : offset + size]
+        offset += size + 1
+    return blobs
+
+
+def decode(data: bytes, encoding: str) -> str:
+    # TextIOWrapper, as tokenize.open and Path.read_text use, so newline
+    # translation matches what reading the file from disk produced.
+    return io.TextIOWrapper(io.BytesIO(data), encoding=encoding).read()
+
+
+def read_floor(root: Path, entries: list[Entry]) -> tuple[int, int]:
+    staged = [
+        entry
+        for entry in entries
+        if entry.path == FLOOR_FILE.as_posix() and entry.stage == "0"
+    ]
+    if not staged:
+        raise SystemExit(f"{FLOOR_FILE} is not in the index, so there is no declared floor")
+    # A symlink's blob is its target path, which could itself read as a version.
+    if staged[0].mode not in REGULAR_MODES:
+        raise SystemExit(f"{FLOOR_FILE} must be a regular file in the index")
+    blob = read_blobs(root, [staged[0].oid])[staged[0].oid]
+    if blob is None:
+        raise SystemExit(f"{FLOOR_FILE} is staged but its object is missing")
+    raw = decode(blob, "utf-8")
+    stripped = [
+        line.split("#", 1)[0].strip() for line in raw.splitlines()
+    ]
+    values = [line for line in stripped if line]
+    if len(values) != 1:
+        raise SystemExit(
+            f"{FLOOR_FILE} must hold exactly one version, found {len(values)}"
+        )
+    parts = values[0].split(".")
+    if len(parts) != 2 or not all(part.isdigit() for part in parts):
+        raise SystemExit(f"{FLOOR_FILE} must hold MAJOR.MINOR, found {values[0]!r}")
+    return (int(parts[0]), int(parts[1]))
+
+
+# Paths nothing executes, no check reads and no edit may touch, matched from
+# the start of the path: --exclude, set by main(); None excludes nothing.
+FROZEN: re.Pattern[str] | None = None
+
+
+def is_candidate(path: str) -> bool:
+    if FROZEN is not None and FROZEN.match(path):
+        return False
+    return path.endswith(".py") or path.endswith(".sh") or path.startswith(".husky/")
+
+
+def collect(root: Path, entries: list[Entry]) -> tuple[list[Source], list[Finding]]:
+    """Every Python source a hook, validator or agent tool can execute.
+
+    Each source is its STAGED blob, so the gate judges the commit being made.
+    Unreadable sources are REPORTED, never skipped. A guard that quietly drops a
+    file it cannot decode passes while that file holds anything at all, which is
+    the failure mode this whole script exists to prevent.
+    """
+    sources: list[Source] = []
+    failures: list[Finding] = []
+    unmerged: set[str] = set()
+    regular: list[Entry] = []
+    for entry in entries:
+        if not is_candidate(entry.path) or entry.mode == GITLINK_MODE:
+            continue
+        if entry.stage != "0":
+            if entry.path not in unmerged:
+                unmerged.add(entry.path)
+                failures.append(
+                    unreadable(
+                        entry.path,
+                        "unmerged: the index holds conflict stages",
+                        "resolve the conflict and stage the result",
+                    )
+                )
+            continue
+        if entry.mode == SYMLINK_MODE:
+            failures.append(
+                unreadable(
+                    entry.path,
+                    "a symlink: the gate reads staged blobs and does not follow links",
+                    "track the file itself rather than a link to it",
+                )
+            )
+            continue
+        regular.append(entry)
+
+    blobs = read_blobs(root, [entry.oid for entry in regular])
+    for entry in regular:
+        path = entry.path
+        blob = blobs[entry.oid]
+        if blob is None:
+            failures.append(unreadable(path, f"staged object {entry.oid} is missing"))
+            continue
+        if path.endswith(".py"):
+            try:
+                # detect_encoding honours the PEP 263 coding declaration and a
+                # BOM, as tokenize.open does, so a validly-encoded non-UTF-8
+                # source is CHECKED rather than skipped.
+                encoding, _ = tokenize.detect_encoding(io.BytesIO(blob).readline)
+                text = decode(blob, encoding)
+            except (SyntaxError, UnicodeDecodeError, ValueError) as error:
+                failures.append(unreadable(path, f"{type(error).__name__}: {error}"))
+                continue
+            sources.append(Source(path, 1, text))
+            continue
+        try:
+            text = decode(blob, "utf-8")
+        except UnicodeDecodeError as error:
+            failures.append(unreadable(path, f"{type(error).__name__}: {error}"))
+            continue
+        sources.extend(embedded(path, text))
+    return sources, failures
+
+
+def unreadable(
+    path: str,
+    detail: str,
+    remedy: str = "give the file a decodable encoding (a PEP 263 declaration for "
+    "Python), or untrack it",
+) -> Finding:
+    return Finding(
+        path,
+        1,
+        "unreadable",
+        detail,
+        f"{remedy} — this gate will not skip a source it cannot read",
+    )
+
+
+def embedded(path: str, text: str) -> list[Source]:
+    lines = text.splitlines()
+    found: list[Source] = []
+    index = 0
+    while index < len(lines):
+        line = lines[index]
+        heredoc = HEREDOC.search(line)
+        if heredoc is not None:
+            dash, tag = heredoc.group(1), heredoc.group(3)
+            start = index + 1
+            end = start
+            while end < len(lines) and lines[end].strip() != tag:
+                end += 1
+            body = lines[start:end]
+            # `<<-` tells the shell to strip leading TABS from every body line
+            # (and from the terminator, which `.strip()` above already covers).
+            # Python never sees them, so neither may this — otherwise a
+            # tab-indented heredoc reads as an IndentationError and is reported
+            # as syntax the floor cannot parse.
+            if dash:
+                body = [entry.lstrip("\t") for entry in body]
+            found.append(
+                Source(f"{path} <<{tag}", start + 1, "\n".join(body))
+            )
+            index = end + 1
+            continue
+        inline = INLINE.search(line)
+        if inline is not None:
+            body, end = inline_payload(lines, index, inline.end())
+            found.append(Source(f"{path} python -c", index + 1, body))
+            index = end + 1
+            continue
+        index += 1
+    return found
+
+
+def inline_payload(lines: list[str], index: int, offset: int) -> tuple[str, int]:
+    """Text between the opening quote at ``offset`` and the next single quote."""
+    first = lines[index][offset:]
+    if "'" in first:
+        return first[: first.index("'")], index
+    collected = [first]
+    cursor = index + 1
+    while cursor < len(lines):
+        if "'" in lines[cursor]:
+            collected.append(lines[cursor][: lines[cursor].index("'")])
+            return "\n".join(collected), cursor
+        collected.append(lines[cursor])
+        cursor += 1
+    return "\n".join(collected), cursor - 1
+
+
+def has_future_annotations(tree: ast.Module) -> bool:
+    return any(
+        isinstance(node, ast.ImportFrom)
+        and node.module == "__future__"
+        and any(alias.name == "annotations" for alias in node.names)
+        for node in tree.body
+    )
+
+
+def annotation_nodes(tree: ast.Module) -> set[int]:
+    """id() of every expression that sits in an annotation position."""
+    marked: set[int] = set()
+    for node in ast.walk(tree):
+        found: list[ast.expr] = []
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            arguments = node.args
+            for arg in (
+                arguments.posonlyargs
+                + arguments.args
+                + arguments.kwonlyargs
+                + [arguments.vararg, arguments.kwarg]
+            ):
+                if arg is not None and arg.annotation is not None:
+                    found.append(arg.annotation)
+            if node.returns is not None:
+                found.append(node.returns)
+        elif isinstance(node, ast.AnnAssign):
+            found.append(node.annotation)
+        for expression in found:
+            for descendant in ast.walk(expression):
+                marked.add(id(descendant))
+    return marked
+
+
+def check_stdlib(source: Source, tree: ast.Module, floor: tuple[int, int]) -> list[Finding]:
+    findings: list[Finding] = []
+    for node in ast.walk(tree):
+        names: list[str] = []
+        if isinstance(node, ast.Import):
+            names = [alias.name for alias in node.names]
+        elif isinstance(node, ast.ImportFrom) and node.level == 0 and node.module:
+            names = [node.module]
+        for name in names:
+            top = name.split(".")[0]
+            added = ADDED_IN.get(top)
+            if added is not None and added > floor:
+                findings.append(
+                    Finding(
+                        source.where,
+                        source.at(node.lineno),
+                        "stdlib-too-new",
+                        f"{top} was added in Python {added[0]}.{added[1]}, "
+                        f"above the declared floor {floor[0]}.{floor[1]}",
+                        f"raise {FLOOR_FILE.as_posix()}, or use a module the floor has "
+                        "(no __future__ import can supply a missing module)",
+                    )
+                )
+            removed = REMOVED_IN.get(top)
+            if removed is not None and removed <= floor:
+                findings.append(
+                    Finding(
+                        source.where,
+                        source.at(node.lineno),
+                        "stdlib-removed",
+                        f"{top} was removed in Python {removed[0]}.{removed[1]}, "
+                        f"at or below the declared floor {floor[0]}.{floor[1]}",
+                        "use the replacement module named in that release's changelog",
+                    )
+                )
+    return findings
+
+
+def type_expression_nodes(tree: ast.Module) -> set[int]:
+    """id() of expressions that are unambiguously types rather than values.
+
+    `|` is overloaded: set union, dict merge and `os.O_RDONLY | os.O_NOFOLLOW`
+    all use it and all predate PEP 604. Flagging every BitOr would bury the real
+    finding under false positives from this repo's own hooks, so only positions
+    where `|` cannot mean anything but a type union are considered.
+    """
+    marked: set[int] = set()
+
+    def mark(expression: ast.expr) -> None:
+        for descendant in ast.walk(expression):
+            marked.add(id(descendant))
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Call):
+            callee = node.func
+            name = callee.attr if isinstance(callee, ast.Attribute) else getattr(callee, "id", "")
+            # cast(T, value); isinstance(x, T); issubclass(C, T)
+            if name == "cast" and node.args:
+                mark(node.args[0])
+            elif name in {"isinstance", "issubclass"} and len(node.args) > 1:
+                mark(node.args[1])
+    return marked
+
+
+def is_optional_shorthand(node: ast.BinOp) -> bool:
+    """`X | None`, which can never be set union or integer bitwise-or."""
+    return any(
+        isinstance(side, ast.Constant) and side.value is None
+        for side in (node.left, node.right)
+    )
+
+
+def check_runtime_unions(
+    source: Source, tree: ast.Module, floor: tuple[int, int]
+) -> list[Finding]:
+    """PEP 604 unions that are evaluated, on a floor that cannot evaluate them.
+
+    Inert at 3.10 and above, and deliberately so: it is the check that makes the
+    floor file mean something if anyone lowers it.
+
+    Conservative outside annotations. A bare alias of two names — `IntOrStr =
+    int | str` — is indistinguishable from a set union without type knowledge
+    and is not reported; `int | None` is, because `None` has no `__or__`.
+    """
+    if floor >= (3, 10):
+        return []
+    deferred = has_future_annotations(tree)
+    in_annotation = annotation_nodes(tree)
+    in_type_position = type_expression_nodes(tree)
+    findings: list[Finding] = []
+    for node in ast.walk(tree):
+        if not (isinstance(node, ast.BinOp) and isinstance(node.op, ast.BitOr)):
+            continue
+        annotated = id(node) in in_annotation
+        if annotated:
+            if deferred:
+                continue
+            detail = (
+                "X | Y in an annotation is evaluated at definition time without "
+                "`from __future__ import annotations`"
+            )
+        elif id(node) in in_type_position or is_optional_shorthand(node):
+            detail = "X | Y in a type position outside an annotation is always evaluated"
+        else:
+            continue
+        findings.append(
+            Finding(
+                source.where,
+                source.at(node.lineno),
+                "runtime-pep604",
+                f"{detail}; PEP 604 unions need Python 3.10, floor is "
+                f"{floor[0]}.{floor[1]}",
+                "add `from __future__ import annotations` (annotations only), or "
+                "write Optional[X] / Union[X, Y]",
+            )
+        )
+    return findings
+
+
+def check(source: Source, floor: tuple[int, int]) -> list[Finding]:
+    try:
+        tree = ast.parse(source.text, feature_version=floor)
+    except SyntaxError as error:
+        return [
+            Finding(
+                source.where,
+                source.at(error.lineno or 1),
+                "syntax-too-new",
+                f"{error.msg} — not valid Python {floor[0]}.{floor[1]}",
+                f"rewrite for the declared floor, or raise {FLOOR_FILE.as_posix()}",
+            )
+        ]
+    except ValueError as error:
+        return [
+            Finding(source.where, source.first_line, "unparseable", str(error), "check the source")
+        ]
+    return check_stdlib(source, tree, floor) + check_runtime_unions(source, tree, floor)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--root", default=".")
+    parser.add_argument(
+        "--floor-file",
+        required=True,
+        help="the file declaring MAJOR.MINOR, relative to --root",
+    )
+    parser.add_argument(
+        "--exclude",
+        help="a regular expression matched from the start of each path; matches are not checked",
+    )
+    parser.add_argument(
+        "--selector",
+        help="what picks an interpreter at or above the floor, named when this one is below it",
+    )
+    parser.add_argument(
+        "--floor",
+        help="override MAJOR.MINOR for testing; defaults to the --floor-file",
+    )
+    args = parser.parse_args()
+    global FLOOR_FILE, FROZEN
+    FLOOR_FILE = Path(args.floor_file)
+    if args.exclude is not None:
+        try:
+            FROZEN = re.compile(args.exclude)
+        except re.error as error:
+            parser.error(f"--exclude is not a regular expression: {error}")
+    root = Path(args.root).resolve()
+    entries = index_entries(root)
+
+    if args.floor is None:
+        floor = read_floor(root, entries)
+    else:
+        parts = args.floor.split(".")
+        floor = (int(parts[0]), int(parts[1]))
+
+    # `feature_version` cannot describe a grammar newer than the running
+    # interpreter, so a stale Python would silently under-report. The hook
+    # selects an interpreter at or above the floor before calling this.
+    if sys.version_info[:2] < floor:
+        print(
+            f"❌ validate-hook-python-floor: running on Python "
+            f"{sys.version_info[0]}.{sys.version_info[1]}, which is below the "
+            f"declared floor {floor[0]}.{floor[1]}, so it cannot judge the floor.\n"
+            f"   Run it under a newer interpreter"
+            + (
+                ""
+                if args.selector is None
+                else f" (the hook does this for you via {args.selector})"
+            )
+            + ".",
+            file=sys.stderr,
+        )
+        return 2
+
+    sources, unreadable_findings = collect(root, entries)
+    if not sources and not unreadable_findings:
+        print(
+            "❌ validate-hook-python-floor: found no Python to check, which means "
+            "the scan is broken rather than the repo clean.",
+            file=sys.stderr,
+        )
+        return 2
+
+    # A nested union (`a | b | c`) is several BinOp nodes on one line, and a
+    # line is the unit a developer fixes — so report each line once.
+    seen: set[tuple[str, int, str]] = set()
+    findings: list[Finding] = list(unreadable_findings)
+    for source in sources:
+        for finding in check(source, floor):
+            key = (finding.where, finding.line, finding.rule)
+            if key in seen:
+                continue
+            seen.add(key)
+            findings.append(finding)
+
+    if findings:
+        print(
+            f"❌ Python that cannot run on the declared floor "
+            f"{floor[0]}.{floor[1]} ({FLOOR_FILE.as_posix()}):\n",
+            file=sys.stderr,
+        )
+        for finding in findings:
+            print(finding.render(), file=sys.stderr)
+        print(
+            f"\n{len(findings)} finding(s) across {len(sources)} Python source(s). "
+            "These fail on a stock macOS interpreter, usually reported by whatever "
+            "validator was running rather than as a version problem.",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(
+        f"✅ {len(sources)} Python source(s) run on Python "
+        f"{floor[0]}.{floor[1]} ({FLOOR_FILE.as_posix()})"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())