vouchington-tooling 0.4.0 → 0.4.2

package/README.md

@@ -19,6 +19,10 @@ vouchington runner-port-policy --file ./policy.json
 vouchington runner-port-policy --reserved 2200
 vouchington with-host-lock --name expensive-build --timeout-seconds 60 -- make build
 vouchington gha-runtime-audit --pr-workflow CI --push-workflow '/^Main CI \\(.+\\)$/'
+vouchington require-up-to-date --remote origin --branch main
+vouchington gitleaks-directory-scan --config .gitleaks.toml
+vouchington ast-grep-examples --rules ast-grep-tests --config sgconfig.yml
+vouchington gha-workspace-policy
 vouchington gha-output name
 vouchington gha-needs-results
 vouchington download-with-diagnostics <url> <destination>
@@ -79,6 +83,14 @@ download`), and extracts each selected name into its own directory. Ordinary abs
 `availability=unavailable`. Artifact listing retries up to three times with bounded backoff;
 exhausted transport errors, invalid names, and cancellation remain hard failures.
 
+`require-up-to-date` fetches the requested remote branch and fails unless its fetched tip is an
+ancestor of `HEAD`. `gitleaks-directory-scan` builds and scans isolated staged-index and current
+nonignored-working-tree mirrors with an explicit config; `--directory` selects the repository root.
+`ast-grep-examples` runs native `ast-grep test`, then validates each scoped rule's `files:` and
+`ignores:` examples with project `languageGlobs` replay from its root `--config`.
+`gha-workspace-policy` checks tracked workflow and composite-action files in the current repository;
+pass `--root`, `--workflow-directory`, or `--action-directory` for consumer-owned layouts.
+
 `retrospective-transcript` discovers Codex and Claude transcripts by default. It also reads a
 Claude-compatible transcript when `CURSOR_SESSION_ID` is set, and Grok's `updates.jsonl` session
 layout when `GROK_SESSION_ID` is set. Use `--grok-sessions-dir` to point discovery at a nondefault
@@ -177,6 +189,9 @@ import { rateLimitDelay } from 'vouchington-tooling/gha-rate-limit'
 import { parseCheckpoint } from 'vouchington-tooling/gha-pr-checkpoint'
 import { checkWorkspaceGatesPolicy } from 'vouchington-tooling/workspace-gates'
 import { checkGhaWorkspacePolicy } from 'vouchington-tooling/gha-workspace-policy'
+import { requireUpToDate } from 'vouchington-tooling/require-up-to-date'
+import { runGitleaksDirectoryScan } from 'vouchington-tooling/gitleaks-directory-scan'
+import { runAstGrepExamples } from 'vouchington-tooling/ast-grep-examples'
 import { validateNugetUpdate } from 'vouchington-tooling/nuget-central-version'
 import { normalizeSwiftSource } from 'vouchington-tooling/swift-semantic-equal'
 import { parseUniqueSwiftBinaryTargetChecksum } from 'vouchington-tooling/swift-source-offset'

package/dist/ast-grep-examples/index.d.mts

@@ -0,0 +1,15 @@
+interface AstGrepResult {
+    status: number | null;
+    stdout?: string;
+    stderr?: string;
+}
+export type AstGrepExamplesExecutor = (args: readonly string[], cwd: string) => AstGrepResult;
+export interface AstGrepExamplesOptions {
+    readonly rules: string;
+    readonly config: string;
+    readonly executable?: string;
+    readonly execute?: AstGrepExamplesExecutor;
+}
+export declare function astGrepExamplesArguments(options: AstGrepExamplesOptions): string[];
+export declare function runAstGrepExamples(options: AstGrepExamplesOptions): number;
+export {};

package/dist/ast-grep-examples/index.mjs

@@ -0,0 +1,138 @@
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import picomatch from 'picomatch';
+import { parse as yamlLoad, stringify as yamlDump } from 'yaml';
+export function astGrepExamplesArguments(options) {
+    return [
+        'test',
+        '--test-dir',
+        needPath(options.rules, '--rules'),
+        '--config',
+        needPath(options.config, '--config'),
+    ];
+}
+function needPath(value, option) {
+    if (!value)
+        throw new Error(`${option} requires a path`);
+    return value;
+}
+function eligible(rule, file) {
+    const path = file.replace(/\\/g, '/').replace(/^\.\//, '');
+    return ((!rule.files?.length || picomatch(rule.files)(path)) &&
+        !(rule.ignores?.length && picomatch(rule.ignores)(path)));
+}
+function loadRules(directory) {
+    return fs.readdirSync(directory, { recursive: true })
+        .filter((file) => /\.ya?ml$/u.test(file))
+        .toSorted()
+        .map((file) => {
+        const ruleFile = join(directory, file);
+        return { ruleFile, rule: yamlLoad(fs.readFileSync(ruleFile, 'utf8')) };
+    });
+}
+function assertExample(rule, example) {
+    if (!example.code || !example.file)
+        throw new Error(`${rule.id}: examples require non-empty code and file`);
+    safeRelativePath(example.file, `${rule.id}: example.file`);
+}
+function safeRelativePath(value, label) {
+    if (value.includes('\0') ||
+        isAbsolute(value) ||
+        value
+            .replace(/\\/g, '/')
+            .split('/')
+            .some((component) => component === '..'))
+        throw new Error(`${label} must stay within the temporary rule directory`);
+    return value;
+}
+function defaultExecute(executable) {
+    return (args, cwd) => {
+        const result = spawnSync(executable, args, { cwd, encoding: 'utf8' });
+        if (result.error)
+            throw new Error(`ast-grep failed to spawn: ${result.error.message}`);
+        return result;
+    };
+}
+function writeNativeTests(rules, testDir, semanticDir) {
+    for (const { rule } of rules) {
+        if (!/^[A-Za-z0-9_.-]+$/u.test(rule.id))
+            throw new Error('rule id must be a filesystem-safe name');
+        const { examples } = rule;
+        const invalid = [
+            ...new Set(examples.filter((example) => !example.isValid).map((example) => example.code)),
+        ];
+        const valid = [
+            ...new Set(examples
+                .filter((example) => example.isValid && eligible(rule, example.file) && !invalid.includes(example.code))
+                .map((example) => example.code)),
+        ];
+        fs.writeFileSync(join(testDir, `${rule.id}.yml`), yamlDump({ id: rule.id, valid, invalid }));
+        const { examples: _examples, files: _files, ignores: _ignores, ...semanticRule } = rule;
+        fs.writeFileSync(join(semanticDir, `${rule.id}.yml`), yamlDump(semanticRule));
+    }
+}
+function scanScopedRule(loaded, root, languageGlobs, execute) {
+    const { invalid, rule } = loaded;
+    const expected = new Map();
+    for (const example of rule.examples) {
+        assertExample(rule, example);
+        const file = example.file.replace(/\\/g, '/').replace(/^\.\//, '');
+        expected.set(file, eligible(rule, file));
+        const path = join(root, file);
+        fs.mkdirSync(dirname(path), { recursive: true });
+        fs.writeFileSync(path, invalid);
+    }
+    fs.copyFileSync(loaded.ruleFile, join(root, 'rule.yml'));
+    fs.writeFileSync(join(root, 'sgconfig.yml'), yamlDump({ languageGlobs }));
+    const result = execute(['scan', '--rule', 'rule.yml', '--config', 'sgconfig.yml', '--json', '--no-ignore', '--hidden'], root);
+    if (result.status === null || result.status > 1)
+        throw new Error(`ast-grep scan failed (exit ${result.status ?? 'signal'}): ${result.stderr ?? ''}`);
+    const found = new Set(result.stdout?.trim()
+        ? JSON.parse(result.stdout).map((f) => f.file.replace(/\\/g, '/').replace(/^\.\//, ''))
+        : []);
+    for (const [file, shouldFind] of expected)
+        if (found.has(file) !== shouldFind)
+            throw new Error(`${rule.id}: expected ${file} ${shouldFind ? 'to produce' : 'not to produce'} a finding`);
+}
+export function runAstGrepExamples(options) {
+    const rulesDirectory = resolve(needPath(options.rules, '--rules'));
+    const config = resolve(needPath(options.config, '--config'));
+    const languageGlobs = yamlLoad(fs.readFileSync(config, 'utf8')).languageGlobs;
+    if (!languageGlobs)
+        throw new Error(`${config}: missing languageGlobs`);
+    const rules = loadRules(rulesDirectory).map((loaded) => {
+        const { rule } = loaded;
+        const examples = rule.examples ?? [];
+        for (const example of examples)
+            assertExample(rule, example);
+        const invalid = examples.find((example) => !example.isValid);
+        if (!examples.some((example) => example.isValid) || invalid === undefined)
+            throw new Error(`${rule.id}: examples require valid and invalid cases`);
+        return { ...loaded, rule: { ...rule, examples }, invalid: invalid.code };
+    });
+    const execute = options.execute ?? defaultExecute(options.executable ?? 'ast-grep');
+    const root = fs.mkdtempSync(join(tmpdir(), 'ast-grep-examples-'));
+    try {
+        const tests = join(root, 'native-tests');
+        const semantic = join(root, 'semantic-rules');
+        fs.mkdirSync(tests);
+        fs.mkdirSync(semantic);
+        writeNativeTests(rules, tests, semantic);
+        const nativeConfig = join(root, 'sgconfig.yml');
+        fs.writeFileSync(nativeConfig, yamlDump({ ruleDirs: [semantic] }));
+        const native = execute(['test', '--config', nativeConfig, '--test-dir', tests, '--skip-snapshot-tests'], process.cwd());
+        if (native.status !== 0)
+            throw new Error(`${native.stdout ?? ''}\n${native.stderr ?? ''}`);
+        for (const loaded of rules.filter(({ rule }) => rule.files?.length || rule.ignores?.length)) {
+            const scopedRoot = join(root, 'path-scans', loaded.rule.id);
+            fs.mkdirSync(scopedRoot, { recursive: true });
+            scanScopedRule(loaded, scopedRoot, languageGlobs, execute);
+        }
+        return 0;
+    }
+    finally {
+        fs.rmSync(root, { force: true, recursive: true });
+    }
+}

package/dist/cli/commands/ast-grep-examples.d.mts

@@ -0,0 +1,4 @@
+export declare function runAstGrepExamplesCommand(options: {
+    rules: string;
+    config: string;
+}): number;

package/dist/cli/commands/ast-grep-examples.mjs

@@ -0,0 +1,10 @@
+import { runAstGrepExamples } from '../../ast-grep-examples/index.mjs';
+export function runAstGrepExamplesCommand(options) {
+    try {
+        return runAstGrepExamples(options);
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}

package/dist/cli/commands/gha-workspace-policy.d.mts

@@ -0,0 +1,12 @@
+import { checkGhaWorkspacePolicy, type GhaWorkspacePolicyOptions } from '../../gha-workspace-policy/index.mts';
+import { type SharedContext } from '../../shared-context/index.mts';
+export interface GhaWorkspacePolicyCliOptions extends GhaWorkspacePolicyOptions {
+    readonly root?: string;
+}
+interface Dependencies {
+    readonly buildContext?: (root: string) => Promise<SharedContext>;
+    readonly check?: typeof checkGhaWorkspacePolicy;
+    readonly stderr?: NodeJS.WritableStream;
+}
+export declare function runGhaWorkspacePolicy(options: GhaWorkspacePolicyCliOptions, dependencies?: Dependencies): Promise<number>;
+export {};

package/dist/cli/commands/gha-workspace-policy.mjs

@@ -0,0 +1,18 @@
+import { checkGhaWorkspacePolicy, } from '../../gha-workspace-policy/index.mjs';
+import { buildSharedContext } from '../../shared-context/index.mjs';
+export async function runGhaWorkspacePolicy(options, dependencies = {}) {
+    const context = await (dependencies.buildContext ?? buildSharedContext)(options.root ?? process.cwd());
+    const result = await (dependencies.check ?? checkGhaWorkspacePolicy)(context, {
+        ...(options.workflowDirectories === undefined
+            ? {}
+            : { workflowDirectories: options.workflowDirectories }),
+        ...(options.actionDirectories === undefined
+            ? {}
+            : { actionDirectories: options.actionDirectories }),
+    });
+    if (result.errors.length === 0)
+        return 0;
+    const stderr = dependencies.stderr ?? process.stderr;
+    stderr.write(`${result.errors.join('\n')}\n`);
+    return 1;
+}

package/dist/cli/commands/require-up-to-date.d.mts

@@ -0,0 +1,4 @@
+export declare function runRequireUpToDate(options: {
+    remote: string;
+    branch: string;
+}): number;

package/dist/cli/commands/require-up-to-date.mjs

@@ -0,0 +1,11 @@
+import { requireUpToDate } from '../../require-up-to-date/index.mjs';
+export function runRequireUpToDate(options) {
+    try {
+        requireUpToDate(options);
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}

package/dist/cli/index.mjs

@@ -21,6 +21,9 @@ import { runLinkSkill } from './commands/link-skill.mjs';
 import { runRetrospectiveFactsCommand } from './commands/retrospective-facts.mjs';
 import { runAgentBlackboardCommand } from './commands/agent-blackboard.mjs';
 import { runWithHostLock } from './commands/with-host-lock.mjs';
+import { runRequireUpToDate } from './commands/require-up-to-date.mjs';
+import { runAstGrepExamplesCommand } from './commands/ast-grep-examples.mjs';
+import { runGhaWorkspacePolicy } from './commands/gha-workspace-policy.mjs';
 import { parseCli } from './parse.mjs';
 import { packageScriptPath } from './script-path.mjs';
 import { printUsage } from './usage.mjs';
@@ -119,6 +122,18 @@ export function runCli(argv = process.argv) {
             return runRetrospectiveFactsCommand(parsed.args);
         case 'agent-blackboard':
             return runAgentBlackboardCommand(parsed.args);
+        case 'require-up-to-date':
+            return runRequireUpToDate(parsed);
+        case 'gitleaks-directory-scan':
+            return runScript('bash', packageScriptPath('scripts/gitleaks-directory-scan.sh'), [
+                '--config',
+                parsed.config,
+                ...(parsed.directory === undefined ? [] : ['--root', parsed.directory]),
+            ]);
+        case 'ast-grep-examples':
+            return runAstGrepExamplesCommand(parsed);
+        case 'gha-workspace-policy':
+            return runGhaWorkspacePolicy(parsed);
     }
 }
 function readInstalledVersion() {

package/dist/cli/parse-options.d.mts

@@ -0,0 +1,8 @@
+import type { ParsedCli } from './parse.mts';
+export declare function parseLinkSkill(args: readonly string[]): ParsedCli;
+export declare function parseRunnerPortPolicy(args: readonly string[]): ParsedCli;
+export declare function parseHttpOrigin(args: readonly string[]): ParsedCli;
+export declare function parseRequireUpToDate(args: readonly string[]): ParsedCli;
+export declare function parseGitleaksDirectoryScan(args: readonly string[]): ParsedCli;
+export declare function parseAstGrepExamples(args: readonly string[]): ParsedCli;
+export declare function parseGhaWorkspacePolicy(args: readonly string[]): ParsedCli;

package/dist/cli/parse-options.mjs

@@ -0,0 +1,142 @@
+export function parseLinkSkill(args) {
+    const [name, ...flags] = args;
+    if (name === undefined || name.startsWith('-'))
+        return { kind: 'error', message: 'link-skill requires a skill name' };
+    const options = parseOptions(flags, ['source-root', 'target-root'], 'link-skill', 'path');
+    if ('kind' in options)
+        return options;
+    const sourceRoot = options.values['source-root'];
+    const targetRoot = options.values['target-root'];
+    if (sourceRoot === undefined || targetRoot === undefined) {
+        return { kind: 'error', message: 'link-skill requires --source-root and --target-root' };
+    }
+    return {
+        kind: 'link-skill',
+        name,
+        sourceRoot,
+        targetRoot,
+    };
+}
+export function parseRunnerPortPolicy(args) {
+    const options = parseOptions(args, ['file', 'reserved'], 'runner-port-policy', (flag) => flag === '--reserved' ? 'port' : 'path');
+    if ('kind' in options)
+        return options;
+    const file = options.values.file;
+    const reservedValue = options.values.reserved;
+    const reserved = reservedValue === undefined ? undefined : Number(reservedValue);
+    if (reservedValue !== undefined && !Number.isInteger(reserved)) {
+        return { kind: 'error', message: '--reserved must be an integer' };
+    }
+    return {
+        kind: 'runner-port-policy',
+        ...(file === undefined ? {} : { file }),
+        ...(reserved === undefined ? {} : { reserved }),
+    };
+}
+export function parseHttpOrigin(args) {
+    let field = 'origin';
+    const values = [];
+    let index = 0;
+    while (index < args.length) {
+        const flag = args[index];
+        index += 1;
+        if (flag === '--help' || flag === '-h')
+            return { kind: 'help' };
+        if (flag === '--field') {
+            const value = args[index];
+            if (value === undefined)
+                return { kind: 'error', message: '--field requires a name' };
+            field = value;
+            index += 1;
+            continue;
+        }
+        if (flag === '--') {
+            values.push(...args.slice(index));
+            break;
+        }
+        if (flag.startsWith('-'))
+            return { kind: 'error', message: `unknown http-origin option: ${flag}` };
+        values.push(flag);
+    }
+    if (values.length > 1)
+        return { kind: 'error', message: 'http-origin accepts at most one value' };
+    return { kind: 'http-origin', field, value: values[0] ?? '' };
+}
+export function parseRequireUpToDate(args) {
+    const options = parseOptions(args, ['remote', 'branch'], 'require-up-to-date', 'name');
+    if ('kind' in options)
+        return options;
+    const remote = options.values.remote;
+    const branch = options.values.branch;
+    if (remote === undefined)
+        return { kind: 'error', message: '--remote requires a name' };
+    if (branch === undefined)
+        return { kind: 'error', message: '--branch requires a name' };
+    return { kind: 'require-up-to-date', remote, branch };
+}
+export function parseGitleaksDirectoryScan(args) {
+    const options = parseOptions(args, ['config', 'directory'], 'gitleaks-directory-scan', 'path');
+    if ('kind' in options)
+        return options;
+    const config = options.values.config;
+    const directory = options.values.directory;
+    if (config === undefined)
+        return { kind: 'error', message: '--config requires a path' };
+    return {
+        kind: 'gitleaks-directory-scan',
+        config,
+        ...(directory === undefined ? {} : { directory }),
+    };
+}
+export function parseAstGrepExamples(args) {
+    const options = parseOptions(args, ['rules', 'config'], 'ast-grep-examples', 'path');
+    if ('kind' in options)
+        return options;
+    const rules = options.values.rules;
+    const config = options.values.config;
+    if (rules === undefined)
+        return { kind: 'error', message: '--rules requires a path' };
+    if (config === undefined)
+        return { kind: 'error', message: '--config requires a path' };
+    return { kind: 'ast-grep-examples', rules, config };
+}
+export function parseGhaWorkspacePolicy(args) {
+    const options = parseOptions(args, ['root', 'workflow-directory', 'action-directory'], 'gha-workspace-policy', 'path');
+    if ('kind' in options)
+        return options;
+    const root = options.values.root;
+    return {
+        kind: 'gha-workspace-policy',
+        ...(root === undefined ? {} : { root }),
+        ...(options.workflowDirectories.length === 0
+            ? {}
+            : { workflowDirectories: options.workflowDirectories }),
+        ...(options.actionDirectories.length === 0
+            ? {}
+            : { actionDirectories: options.actionDirectories }),
+    };
+}
+function parseOptions(args, allowed, command, missingValue) {
+    const result = { values: {}, workflowDirectories: [], actionDirectories: [] };
+    for (let index = 0; index < args.length; index += 1) {
+        const flag = args[index];
+        if (flag === '--help' || flag === '-h')
+            return { kind: 'help' };
+        if (!flag.startsWith('--') || !allowed.includes(flag.slice(2))) {
+            return { kind: 'error', message: `unknown ${command} option: ${flag}` };
+        }
+        const value = args[index + 1];
+        if (value === undefined) {
+            const noun = typeof missingValue === 'string' ? missingValue : missingValue(flag);
+            return { kind: 'error', message: `${flag} requires a ${noun}` };
+        }
+        if (flag === '--workflow-directory')
+            result.workflowDirectories.push(value);
+        else if (flag === '--action-directory')
+            result.actionDirectories.push(value);
+        else
+            result.values[flag.slice(2)] = value;
+        index += 1;
+    }
+    return result;
+}

package/dist/cli/parse.d.mts

@@ -60,6 +60,23 @@ export type ParsedCli = {
 } | {
     kind: 'agent-blackboard';
     args: string[];
+} | {
+    kind: 'require-up-to-date';
+    remote: string;
+    branch: string;
+} | {
+    kind: 'gitleaks-directory-scan';
+    config: string;
+    directory?: string;
+} | {
+    kind: 'ast-grep-examples';
+    rules: string;
+    config: string;
+} | {
+    kind: 'gha-workspace-policy';
+    root?: string;
+    workflowDirectories?: string[];
+    actionDirectories?: string[];
 } | ParsedGhaRuntimeAudit | ParsedGhaArtifactsCleanup;
 export type ScriptCommand = 'gha-output' | 'gha-needs-results' | 'download-with-diagnostics' | 'download-optional-run-artifacts' | 'host-pressure-diagnostics' | 'allocate-browser-safe-ports' | 'diagnose-port-collision' | 'prepare-trivy-db' | 'check-cache-size' | 'make-shard-matrix' | 'load-runner-env' | 'clean-workspace' | 'install-github-release' | 'run-with-timeout' | 'lint-links' | 'materialize-pr-context' | 'wait-for-apt-locks' | 'install-playwright-chromium-arm64' | 'ghcr-package-retention' | 'harness-admission-lane' | 'harness-assert-gates';
 export declare function parseCli(argv: readonly string[]): ParsedCli;

package/dist/cli/parse.mjs

@@ -1,5 +1,6 @@
 import { parseGhaArtifactsCleanup, } from './parse-gha-artifacts-cleanup.mjs';
 import { parseGhaRuntimeAudit } from './parse-gha-runtime-audit.mjs';
+import { parseAstGrepExamples, parseGhaWorkspacePolicy, parseGitleaksDirectoryScan, parseHttpOrigin, parseLinkSkill, parseRequireUpToDate, parseRunnerPortPolicy, } from './parse-options.mjs';
 const SCRIPT_COMMANDS = new Set([
     'gha-output',
     'gha-needs-results',
@@ -62,6 +63,14 @@ export function parseCli(argv) {
         return { kind: 'retrospective-facts', args: rest };
     if (command === 'agent-blackboard')
         return { kind: 'agent-blackboard', args: rest };
+    if (command === 'require-up-to-date')
+        return parseRequireUpToDate(rest);
+    if (command === 'gitleaks-directory-scan')
+        return parseGitleaksDirectoryScan(rest);
+    if (command === 'ast-grep-examples')
+        return parseAstGrepExamples(rest);
+    if (command === 'gha-workspace-policy')
+        return parseGhaWorkspacePolicy(rest);
     if (command === 'gha-artifacts-cleanup')
         return parseGhaArtifactsCleanup(rest);
     if (command !== undefined && SCRIPT_COMMANDS.has(command)) {
@@ -69,89 +78,3 @@ export function parseCli(argv) {
     }
     return { kind: 'error', message: `unknown command: ${command}` };
 }
-function parseLinkSkill(args) {
-    const [name, ...flags] = args;
-    if (name === undefined || name.startsWith('-'))
-        return { kind: 'error', message: 'link-skill requires a skill name' };
-    let sourceRoot;
-    let targetRoot;
-    for (let index = 0; index < flags.length; index += 1) {
-        const flag = flags[index];
-        const value = flags[index + 1];
-        if (flag !== '--source-root' && flag !== '--target-root')
-            return { kind: 'error', message: `unknown link-skill option: ${flag}` };
-        if (value === undefined)
-            return { kind: 'error', message: `${flag} requires a path` };
-        if (flag === '--source-root')
-            sourceRoot = value;
-        else
-            targetRoot = value;
-        index += 1;
-    }
-    if (sourceRoot === undefined || targetRoot === undefined)
-        return { kind: 'error', message: 'link-skill requires --source-root and --target-root' };
-    return { kind: 'link-skill', name, sourceRoot, targetRoot };
-}
-function parseRunnerPortPolicy(args) {
-    let file;
-    let reserved;
-    for (let index = 0; index < args.length; index += 1) {
-        const flag = args[index];
-        if (flag === '--file') {
-            const value = args[index + 1];
-            if (value === undefined)
-                return { kind: 'error', message: '--file requires a path' };
-            file = value;
-            index += 1;
-            continue;
-        }
-        if (flag === '--reserved') {
-            const value = args[index + 1];
-            if (value === undefined)
-                return { kind: 'error', message: '--reserved requires a port' };
-            const port = Number(value);
-            if (!Number.isInteger(port))
-                return { kind: 'error', message: '--reserved must be an integer' };
-            reserved = port;
-            index += 1;
-            continue;
-        }
-        if (flag === '--help' || flag === '-h')
-            return { kind: 'help' };
-        return { kind: 'error', message: `unknown runner-port-policy option: ${flag}` };
-    }
-    return {
-        kind: 'runner-port-policy',
-        ...(file === undefined ? {} : { file }),
-        ...(reserved === undefined ? {} : { reserved }),
-    };
-}
-function parseHttpOrigin(args) {
-    let field = 'origin';
-    const values = [];
-    let index = 0;
-    while (index < args.length) {
-        const flag = args[index];
-        index += 1;
-        if (flag === '--help' || flag === '-h')
-            return { kind: 'help' };
-        if (flag === '--field') {
-            const value = args[index];
-            if (value === undefined)
-                return { kind: 'error', message: '--field requires a name' };
-            field = value;
-            index += 1;
-            continue;
-        }
-        if (flag === '--') {
-            values.push(...args.slice(index));
-            break;
-        }
-        if (flag.startsWith('-'))
-            return { kind: 'error', message: `unknown http-origin option: ${flag}` };
-        values.push(flag);
-    }
-    if (values.length > 1)
-        return { kind: 'error', message: 'http-origin accepts at most one value' };
-    return { kind: 'http-origin', field, value: values[0] ?? '' };
-}

package/dist/cli/usage.d.mts

@@ -1,2 +1,2 @@
-export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n  runner-port-policy   Print or validate a runner port policy\n  with-host-lock       Run a command under a host-wide lock\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  gha-output                    Write a collision-safe multiline GITHUB_OUTPUT record\n  gha-needs-results             Fail if required GitHub Actions job results failed\n  download-with-diagnostics     Download a URL and report HTTP status on failure\n  download-optional-run-artifacts  Download optional artifacts from the current run\n  host-pressure-diagnostics     Print a bounded host memory/OOM/PSI snapshot\n  allocate-browser-safe-ports   Allocate Fetch-safe localhost ports\n  diagnose-port-collision       Capture bounded localhost port diagnostics\n  prepare-trivy-db              Download the Trivy vulnerability database\n  gha-artifacts-cleanup         Delete classified GitHub Actions artifacts\n  http-origin                   Validate an optional HTTP(S) origin\n  vitest-blob-manifest          Stamp a vitest-blob-manifest:v1 identity file\n  vitest-report-attempt         Write or read a Vitest report-attempt marker\n  prepare-vitest-reports        Validate and select Vitest report JSON files\n  pnpm-install                  Install a pnpm workspace with retry and release-age fail-fast\n  check-cache-size              Measure a path and decide whether to save a GHA cache\n  make-shard-matrix             Emit a [1..N] GitHub Actions shard matrix\n  load-runner-env               Overlay a runner env file onto GITHUB_ENV with injection guards\n  clean-workspace               Reset a persistent-runner workspace with a fork-PR trust gate\n  install-github-release        Download a checksum-verified GitHub Release binary\n  run-with-timeout              Run a command with GNU timeout or a Perl fallback\n  lint-links                    Two-pass lychee: internal links fail, external warn\n  materialize-pr-context        Dump PR title/body/files/diff/comments and #N crawl\n  wait-for-apt-locks            Wait until apt/dpkg lock files are free\n  install-playwright-chromium-arm64  Install Playwright Chromium from browsers.json\n  ghcr-package-retention        Delete old GHCR package versions past KEEP_MIN\n  harness-admission-lane        Compute a GITHUB_RUN_ID admission lane for fleet fan-out\n  harness-assert-gates          Fail if any named HARNESS_*_ENABLED gate is enabled\n  nuget-central-version         Validate a Directory.Packages.props PackageVersion delta\n  swift-semantic-equal          Compare Swift sources ignoring comments and whitespace\n  post-review                   Post one COMMENT review from a staged payload file\n  stage-review-payload          Validate a review payload file into a staging directory\n  retrospective-transcript      Format facts from Claude-compatible, Codex, or Grok transcripts\n  link-skill                    Link one packaged skill into an explicit consumer directory\n  retrospective-facts           Gather immutable facts for a retrospective\n  agent-blackboard              Probe and journal an Agent Blackboard deployment\n\nOptions:\n  -h, --help       Show this help\n  -v, --version    Print the package version\n\nrunner-port-policy\n  (no args)              Print the shipped policy as JSON\n  --file <path>          Validate and print a policy file\n  --reserved <port>      Print true if the port is reserved\n\nwith-host-lock\n  --name <family>\n  [--slots <n>]\n  --timeout-seconds <n>\n  [--command-timeout-seconds <n>]\n  [--failure-diagnostics <absolute-script>]\n  [--on-acquire-timeout fail|run-unlocked]\n  -- <command> [args...]\n\ngha-runtime-audit\n  [--repository owner/name]   Default GITHUB_REPOSITORY\n  [--branch main]\n  --pr-workflow <name|/regex/>     Repeatable\n  --push-workflow <name|/regex/>   Repeatable\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\ndownload-optional-run-artifacts (--name <name> | --pattern <pattern>) --dir <directory>\nhost-pressure-diagnostics\nallocate-browser-safe-ports [count] [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\nvitest-report-attempt <write DIRECTORY SUITE|read ROOT>\nprepare-vitest-reports [primary-directory] [fallback-directory] [output-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--expected-sha256 SHA256] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention <url-encoded-package>...\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nswift-semantic-equal <base> <head> <file.swift>\npost-review\nstage-review-payload optional|required <source> <destination>\nretrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]\nlink-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir>  Link a packaged or repository-local skill\nretrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]\nagent-blackboard probe\nagent-blackboard journal append --session-id UUID --agent NAME --version VERSION --file PATH [--parent-session-id UUID] [--timestamp ISO8601]\nagent-blackboard journal entries --session-id UUID\nagent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{\"sessions\":N,\"entries\":N,\"records\":N,\"bytes\":N}'\nagent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]\n";
+export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n  runner-port-policy   Print or validate a runner port policy\n  with-host-lock       Run a command under a host-wide lock\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  require-up-to-date            Require HEAD to include a fetched remote branch\n  gitleaks-directory-scan       Scan a directory with Gitleaks\n  ast-grep-examples             Run AST-grep rule examples\n  gha-workspace-policy          Check GitHub Actions workspace safety policy\n  gha-output                    Write a collision-safe multiline GITHUB_OUTPUT record\n  gha-needs-results             Fail if required GitHub Actions job results failed\n  download-with-diagnostics     Download a URL and report HTTP status on failure\n  download-optional-run-artifacts  Download optional artifacts from the current run\n  host-pressure-diagnostics     Print a bounded host memory/OOM/PSI snapshot\n  allocate-browser-safe-ports   Allocate Fetch-safe localhost ports\n  diagnose-port-collision       Capture bounded localhost port diagnostics\n  prepare-trivy-db              Download the Trivy vulnerability database\n  gha-artifacts-cleanup         Delete classified GitHub Actions artifacts\n  http-origin                   Validate an optional HTTP(S) origin\n  vitest-blob-manifest          Stamp a vitest-blob-manifest:v1 identity file\n  vitest-report-attempt         Write or read a Vitest report-attempt marker\n  prepare-vitest-reports        Validate and select Vitest report JSON files\n  pnpm-install                  Install a pnpm workspace with retry and release-age fail-fast\n  check-cache-size              Measure a path and decide whether to save a GHA cache\n  make-shard-matrix             Emit a [1..N] GitHub Actions shard matrix\n  load-runner-env               Overlay a runner env file onto GITHUB_ENV with injection guards\n  clean-workspace               Reset a persistent-runner workspace with a fork-PR trust gate\n  install-github-release        Download a checksum-verified GitHub Release binary\n  run-with-timeout              Run a command with GNU timeout or a Perl fallback\n  lint-links                    Two-pass lychee: internal links fail, external warn\n  materialize-pr-context        Dump PR title/body/files/diff/comments and #N crawl\n  wait-for-apt-locks            Wait until apt/dpkg lock files are free\n  install-playwright-chromium-arm64  Install Playwright Chromium from browsers.json\n  ghcr-package-retention        Delete old GHCR package versions past KEEP_MIN\n  harness-admission-lane        Compute a GITHUB_RUN_ID admission lane for fleet fan-out\n  harness-assert-gates          Fail if any named HARNESS_*_ENABLED gate is enabled\n  nuget-central-version         Validate a Directory.Packages.props PackageVersion delta\n  swift-semantic-equal          Compare Swift sources ignoring comments and whitespace\n  post-review                   Post one COMMENT review from a staged payload file\n  stage-review-payload          Validate a review payload file into a staging directory\n  retrospective-transcript      Format facts from Claude-compatible, Codex, or Grok transcripts\n  link-skill                    Link one packaged skill into an explicit consumer directory\n  retrospective-facts           Gather immutable facts for a retrospective\n  agent-blackboard              Probe and journal an Agent Blackboard deployment\n\nOptions:\n  -h, --help       Show this help\n  -v, --version    Print the package version\n\nrunner-port-policy\n  (no args)              Print the shipped policy as JSON\n  --file <path>          Validate and print a policy file\n  --reserved <port>      Print true if the port is reserved\n\nwith-host-lock\n  --name <family>\n  [--slots <n>]\n  --timeout-seconds <n>\n  [--command-timeout-seconds <n>]\n  [--failure-diagnostics <absolute-script>]\n  [--on-acquire-timeout fail|run-unlocked]\n  -- <command> [args...]\n\ngha-runtime-audit\n  [--repository owner/name]   Default GITHUB_REPOSITORY\n  [--branch main]\n  --pr-workflow <name|/regex/>     Repeatable\n  --push-workflow <name|/regex/>   Repeatable\n\nrequire-up-to-date --remote <name> --branch <name>\ngitleaks-directory-scan --config <path> [--directory <path>]\nast-grep-examples --rules <directory> --config <path>\ngha-workspace-policy [--root <directory>] [--workflow-directory <directory>] [--action-directory <directory>]\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\ndownload-optional-run-artifacts (--name <name> | --pattern <pattern>) --dir <directory>\nhost-pressure-diagnostics\nallocate-browser-safe-ports [count] [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\nvitest-report-attempt <write DIRECTORY SUITE|read ROOT>\nprepare-vitest-reports [primary-directory] [fallback-directory] [output-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--expected-sha256 SHA256] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention <url-encoded-package>...\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nswift-semantic-equal <base> <head> <file.swift>\npost-review\nstage-review-payload optional|required <source> <destination>\nretrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]\nlink-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir>  Link a packaged or repository-local skill\nretrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]\nagent-blackboard probe\nagent-blackboard journal append --session-id UUID --agent NAME --version VERSION --file PATH [--parent-session-id UUID] [--timestamp ISO8601]\nagent-blackboard journal entries --session-id UUID\nagent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{\"sessions\":N,\"entries\":N,\"records\":N,\"bytes\":N}'\nagent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]\n";
 export declare function printUsage(stream?: NodeJS.WritableStream): void;

package/dist/cli/usage.mjs

@@ -4,6 +4,10 @@ Commands:
   runner-port-policy   Print or validate a runner port policy
   with-host-lock       Run a command under a host-wide lock
   gha-runtime-audit             Audit successful GitHub Actions job runtimes
+  require-up-to-date            Require HEAD to include a fetched remote branch
+  gitleaks-directory-scan       Scan a directory with Gitleaks
+  ast-grep-examples             Run AST-grep rule examples
+  gha-workspace-policy          Check GitHub Actions workspace safety policy
   gha-output                    Write a collision-safe multiline GITHUB_OUTPUT record
   gha-needs-results             Fail if required GitHub Actions job results failed
   download-with-diagnostics     Download a URL and report HTTP status on failure
@@ -64,6 +68,11 @@ gha-runtime-audit
   --pr-workflow <name|/regex/>     Repeatable
   --push-workflow <name|/regex/>   Repeatable
 
+require-up-to-date --remote <name> --branch <name>
+gitleaks-directory-scan --config <path> [--directory <path>]
+ast-grep-examples --rules <directory> --config <path>
+gha-workspace-policy [--root <directory>] [--workflow-directory <directory>] [--action-directory <directory>]
+
 gha-output <name>
 gha-needs-results [label]
 download-with-diagnostics <url> <destination> [-- curl-args...]

package/dist/gitleaks-directory-scan/index.d.mts

@@ -0,0 +1,8 @@
+export type DirectoryScanExecutor = (executable: string, args: readonly string[]) => Promise<number>;
+export interface GitleaksDirectoryScanOptions {
+    readonly config: string;
+    readonly directory?: string;
+    readonly execute?: DirectoryScanExecutor;
+}
+export declare function gitleaksDirectoryScanArguments(options: GitleaksDirectoryScanOptions): string[];
+export declare function runGitleaksDirectoryScan(options: GitleaksDirectoryScanOptions): Promise<number>;

package/dist/gitleaks-directory-scan/index.mjs

@@ -0,0 +1,30 @@
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+function requirePath(value, option) {
+    if (!value)
+        throw new Error(`${option} requires a path`);
+    return value;
+}
+export function gitleaksDirectoryScanArguments(options) {
+    return [
+        '--config',
+        requirePath(options.config, '--config'),
+        ...(options.directory === undefined
+            ? []
+            : ['--root', requirePath(options.directory, '--directory')]),
+    ];
+}
+function defaultExecute(executable, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(executable, args, { stdio: 'inherit' });
+        child.once('error', reject);
+        child.once('close', (code) => resolve(code ?? 1));
+    });
+}
+export function runGitleaksDirectoryScan(options) {
+    const script = fileURLToPath(new URL('../../scripts/gitleaks-directory-scan.sh', import.meta.url));
+    return (options.execute ?? defaultExecute)('bash', [
+        script,
+        ...gitleaksDirectoryScanArguments(options),
+    ]);
+}

package/dist/index.d.mts

@@ -17,6 +17,12 @@ export { auditCiJobRuntime, parseWorkflowNameMatch } from './gha-runtime-audit/i
 export type { GhApiExecutor, RuntimeAuditOptions, RuntimeAuditResult, RuntimeAuditWorkflowFilter, RuntimeJobResult, RuntimeSample, } from './gha-runtime-audit/index.mts';
 export { checkGhaWorkspacePolicy } from './gha-workspace-policy/index.mts';
 export type { GhaWorkspacePolicyOptions } from './gha-workspace-policy/index.mts';
+export { requireUpToDate } from './require-up-to-date/index.mts';
+export type { GitExecutor, RequireUpToDateOptions } from './require-up-to-date/index.mts';
+export { gitleaksDirectoryScanArguments, runGitleaksDirectoryScan, } from './gitleaks-directory-scan/index.mts';
+export type { DirectoryScanExecutor, GitleaksDirectoryScanOptions, } from './gitleaks-directory-scan/index.mts';
+export { astGrepExamplesArguments, runAstGrepExamples } from './ast-grep-examples/index.mts';
+export type { AstGrepExamplesExecutor, AstGrepExamplesOptions } from './ast-grep-examples/index.mts';
 export { createVitestBlobManifest, createVitestReportAttempt, inspectVitestBlobBundle, parseVitestBlobManifest, parseVitestReportAttempt, readVitestReportAttempts, serializeVitestBlobManifest, serializeVitestReportAttempt, VITEST_BLOB_MANIFEST_FILENAME, VITEST_BLOB_MANIFEST_VERSION, VITEST_REPORT_ATTEMPT_PREFIX, VITEST_REPORT_ATTEMPT_VERSION, vitestBlobBundlePaths, writeVitestBlobManifest, writeVitestReportAttempt, } from './vitest-blob-manifest/index.mts';
 export type { InspectedVitestBlobBundle, VitestBlobIdentity, VitestBlobManifest, VitestReportAttempt, VitestReportAttemptIdentity, } from './vitest-blob-manifest/index.mts';
 export { prepareVitestReports } from './vitest-blob-manifest/reports.mts';

package/dist/index.mjs

@@ -9,6 +9,9 @@ export { extractAlterTableAddColumnLocations, extractCreateIndexMetadata, extrac
 export { dollarQuoteEnd, lineOf, maskSqlQuotedText, readDollarQuoteDelimiter, readStringLiteral, splitSqlStatements, sqlFragments, stripSqlComments, } from './sql-scanner/index.mjs';
 export { auditCiJobRuntime, parseWorkflowNameMatch } from './gha-runtime-audit/index.mjs';
 export { checkGhaWorkspacePolicy } from './gha-workspace-policy/index.mjs';
+export { requireUpToDate } from './require-up-to-date/index.mjs';
+export { gitleaksDirectoryScanArguments, runGitleaksDirectoryScan, } from './gitleaks-directory-scan/index.mjs';
+export { astGrepExamplesArguments, runAstGrepExamples } from './ast-grep-examples/index.mjs';
 export { createVitestBlobManifest, createVitestReportAttempt, inspectVitestBlobBundle, parseVitestBlobManifest, parseVitestReportAttempt, readVitestReportAttempts, serializeVitestBlobManifest, serializeVitestReportAttempt, VITEST_BLOB_MANIFEST_FILENAME, VITEST_BLOB_MANIFEST_VERSION, VITEST_REPORT_ATTEMPT_PREFIX, VITEST_REPORT_ATTEMPT_VERSION, vitestBlobBundlePaths, writeVitestBlobManifest, writeVitestReportAttempt, } from './vitest-blob-manifest/index.mjs';
 export { prepareVitestReports } from './vitest-blob-manifest/reports.mjs';
 export { findWorkspaceLinkMismatches, formatReleaseAgeFailure, INSTALL_TERMINATION_FAILED, isReleaseAgeViolation, parseInstallOptions, parseReleaseAgeViolations, runInstallLifecycle, } from './pnpm-install/index.mjs';

package/dist/pnpm-install/native-health.d.mts

@@ -1,6 +1,8 @@
 export type NativeFamily = 'elf' | 'macho' | 'pe';
 export declare function nativeFamilyFromMagic(buffer: Buffer): NativeFamily | undefined;
 export declare function expectedNativeFamily(platform?: NodeJS.Platform): NativeFamily | undefined;
-export declare function mismatchedNativeBinaries(root?: string, platform?: NodeJS.Platform): Promise<string[]>;
+declare function packageExcludesPlatform(owner: string, platform: string): Promise<boolean>;
+export declare function mismatchedNativeBinaries(root?: string, platform?: NodeJS.Platform, readPackageExclusion?: typeof packageExcludesPlatform): Promise<string[]>;
 export declare function nativeBinariesMatchRuntime(root?: string, platform?: NodeJS.Platform): Promise<boolean>;
 export declare function repairedNativeBinariesMatchRuntime(paths: string[], platform?: NodeJS.Platform): Promise<boolean>;
+export {};

package/dist/pnpm-install/native-health.mjs

@@ -1,4 +1,4 @@
-import { glob, open, stat } from 'node:fs/promises';
+import { glob, open, readFile, stat } from 'node:fs/promises';
 import path from 'node:path';
 const ELF = Buffer.from([0x7f, 0x45, 0x4c, 0x46]);
 const PE = Buffer.from([0x4d, 0x5a]);
@@ -58,7 +58,38 @@ async function searchRoot(nodeModules) {
         return nodeModules;
     }
 }
-export async function mismatchedNativeBinaries(root = process.cwd(), platform = process.platform) {
+function excludesPlatform(os, platform) {
+    const values = typeof os === 'string' ? [os] : Array.isArray(os) ? os : undefined;
+    if (values === undefined || !values.every((value) => typeof value === 'string'))
+        return false;
+    if (values.length === 1 && values[0] === 'any')
+        return false;
+    if (values.includes(`!${platform}`))
+        return true;
+    return values.some((value) => !value.startsWith('!')) && !values.includes(platform);
+}
+function packageRoot(pathname, searchRoot) {
+    const segments = path.relative(searchRoot, pathname).split(path.sep);
+    const nodeModules = segments.lastIndexOf('node_modules');
+    const packageStart = nodeModules === -1 ? 0 : nodeModules + 1;
+    const name = segments[packageStart];
+    if (name === undefined || name === '.bin')
+        return undefined;
+    const packageLength = name.startsWith('@') ? 2 : 1;
+    if (segments.length <= packageStart + packageLength)
+        return undefined;
+    return path.join(searchRoot, ...segments.slice(0, packageStart + packageLength));
+}
+async function packageExcludesPlatform(owner, platform) {
+    try {
+        const manifest = JSON.parse(await readFile(path.join(owner, 'package.json'), 'utf8'));
+        return excludesPlatform(manifest.os, platform);
+    }
+    catch {
+        return false;
+    }
+}
+export async function mismatchedNativeBinaries(root = process.cwd(), platform = process.platform, readPackageExclusion = packageExcludesPlatform) {
     const expected = expectedNativeFamily(platform);
     if (expected === undefined)
         return [];
@@ -72,17 +103,28 @@ export async function mismatchedNativeBinaries(root = process.cwd(), platform =
         return [];
     }
     const cwd = await searchRoot(nodeModules);
+    const pattern = cwd === nodeModules ? ['**/*.{node,bin}', '.bin/*.{node,bin}'] : '**/*.{node,bin}';
     const mismatches = [];
-    for await (const relative of glob('**/*.{node,bin}', { cwd })) {
+    for await (const relative of glob(pattern, { cwd })) {
         const pathname = path.join(cwd, relative);
         const magic = await readMagic(pathname);
         if (magic === undefined)
             continue;
         const family = nativeFamilyFromMagic(magic);
-        if (family !== undefined && family !== expected)
-            mismatches.push(pathname);
+        if (family !== undefined && family !== expected) {
+            mismatches.push({ owner: packageRoot(pathname, cwd), pathname });
+        }
     }
-    return mismatches;
+    const owners = [
+        ...new Set(mismatches.flatMap(({ owner }) => (owner === undefined ? [] : [owner]))),
+    ];
+    const exclusions = new Map(await Promise.all(owners.map(async (owner) => [
+        owner,
+        await readPackageExclusion(owner, platform),
+    ])));
+    return mismatches
+        .filter(({ owner }) => owner === undefined || !exclusions.get(owner))
+        .map(({ pathname }) => pathname);
 }
 export async function nativeBinariesMatchRuntime(root = process.cwd(), platform = process.platform) {
     return (await mismatchedNativeBinaries(root, platform)).length === 0;

package/dist/require-up-to-date/index.d.mts

@@ -0,0 +1,8 @@
+export type GitExecutor = (args: readonly string[], cwd?: string) => number;
+export interface RequireUpToDateOptions {
+    readonly remote: string;
+    readonly branch: string;
+    readonly cwd?: string;
+    readonly execute?: GitExecutor;
+}
+export declare function requireUpToDate(options: RequireUpToDateOptions): void;

package/dist/require-up-to-date/index.mjs

@@ -0,0 +1,31 @@
+import { execFileSync } from 'node:child_process';
+function defaultExecute(args, cwd) {
+    try {
+        execFileSync('git', args, { cwd, stdio: 'inherit' });
+        return 0;
+    }
+    catch (error) {
+        const status = error.status;
+        if (typeof status === 'number')
+            return status;
+        throw error;
+    }
+}
+function validateName(value, option) {
+    if (!value || value.startsWith('-') || /\s/u.test(value)) {
+        throw new Error(`${option} must be a non-option Git name`);
+    }
+}
+export function requireUpToDate(options) {
+    validateName(options.remote, '--remote');
+    validateName(options.branch, '--branch');
+    const execute = options.execute ?? defaultExecute;
+    const fetchStatus = execute(['fetch', '--quiet', options.remote, options.branch], options.cwd);
+    if (fetchStatus !== 0)
+        throw new Error(`git fetch failed with exit code ${fetchStatus}`);
+    const ancestryStatus = execute(['merge-base', '--is-ancestor', 'FETCH_HEAD', 'HEAD'], options.cwd);
+    if (ancestryStatus === 1)
+        throw new Error(`Current HEAD is not up to date with ${options.remote}/${options.branch}`);
+    if (ancestryStatus !== 0)
+        throw new Error(`git merge-base failed with exit code ${ancestryStatus}`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -81,6 +81,21 @@
       "import": "./dist/gha-workspace-policy/index.mjs",
       "default": "./dist/gha-workspace-policy/index.mjs"
     },
+    "./require-up-to-date": {
+      "types": "./dist/require-up-to-date/index.d.mts",
+      "import": "./dist/require-up-to-date/index.mjs",
+      "default": "./dist/require-up-to-date/index.mjs"
+    },
+    "./gitleaks-directory-scan": {
+      "types": "./dist/gitleaks-directory-scan/index.d.mts",
+      "import": "./dist/gitleaks-directory-scan/index.mjs",
+      "default": "./dist/gitleaks-directory-scan/index.mjs"
+    },
+    "./ast-grep-examples": {
+      "types": "./dist/ast-grep-examples/index.d.mts",
+      "import": "./dist/ast-grep-examples/index.mjs",
+      "default": "./dist/ast-grep-examples/index.mjs"
+    },
     "./vitest-blob-manifest": {
       "types": "./dist/vitest-blob-manifest/index.d.mts",
       "import": "./dist/vitest-blob-manifest/index.mjs",

package/scripts/gha/diagnose-port-collision.sh

@@ -208,8 +208,12 @@ done
 {
   echo "# Docker diagnostics (best effort)"
   if command -v docker >/dev/null 2>&1; then
-    run_bounded 10 docker version --format 'server={{.Server.Version}}' 2>&1 || true
-    docker_ps_output=$(run_bounded 10 docker ps --no-trunc --format 'container={{.ID}} names={{.Names}} ports={{.Ports}}' 2>&1 || true)
+    docker_probe_timeout_seconds=${VOUCHINGTON_DOCKER_DIAGNOSTIC_TIMEOUT_SECONDS:-10}
+    case "$docker_probe_timeout_seconds" in
+      ''|*[!0-9]*|0) docker_probe_timeout_seconds=10 ;;
+    esac
+    run_bounded "$docker_probe_timeout_seconds" docker version --format 'server={{.Server.Version}}' 2>&1 || true
+    docker_ps_output=$(run_bounded "$docker_probe_timeout_seconds" docker ps --no-trunc --format 'container={{.ID}} names={{.Names}} ports={{.Ports}}' 2>&1 || true)
     for port in "${valid_ports[@]}"; do
       echo "published_port=$port"
       printf '%s\n' "$docker_ps_output" | awk -v port="$port" '/^probe=/ || $0 ~ "(^|[^0-9])" port "->"' || true

package/scripts/gitleaks-directory-scan.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+set -euo pipefail
+CDPATH=''
+
+config_path=''
+repo_root=$(pwd -P)
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --config) config_path=${2:?--config requires a path}; shift 2 ;;
+    --root) repo_root=${2:?--root requires a path}; shift 2 ;;
+    *) echo "unknown gitleaks-directory-scan option: $1" >&2; exit 2 ;;
+  esac
+done
+for command_name in git gitleaks tar; do
+  command -v "$command_name" >/dev/null 2>&1 || {
+    echo "$command_name is required but was not found on PATH" >&2; exit 127;
+  }
+done
+[ -n "$config_path" ] || { echo '--config requires a path' >&2; exit 2; }
+case "$config_path" in /*|*'..'*|*'//'*) echo '--config must be a repository-relative path' >&2; exit 2 ;; esac
+repo_root=$(cd -- "$repo_root" && pwd -P)
+[ -f "$repo_root/$config_path" ] || {
+  echo "required Gitleaks config is missing: $repo_root/$config_path" >&2; exit 1;
+}
+scratch_dir=$(mktemp -d "${TMPDIR:-/tmp}/gitleaks-directory.XXXXXX")
+cleanup() { [ -n "${scratch_dir:-}" ] && rm -rf -- "$scratch_dir"; }
+trap cleanup EXIT
+trap 'exit 129' HUP
+trap 'exit 130' INT
+trap 'exit 143' TERM
+index_dir="$scratch_dir/index"
+working_dir="$scratch_dir/working"
+mkdir -p "$index_dir" "$working_dir"
+git -C "$repo_root" checkout-index --all --prefix="$index_dir/"
+index_config_path="$index_dir/$config_path"
+[ -f "$index_config_path" ] || {
+  echo "required staged Gitleaks config is missing: $config_path" >&2; exit 1;
+}
+git -C "$repo_root" ls-files --cached --others --exclude-standard -z |
+  while IFS= read -r -d '' candidate_path; do
+    if [ -e "$repo_root/$candidate_path" ] || [ -L "$repo_root/$candidate_path" ]; then
+      printf '%s\0' "$candidate_path"
+    fi
+  done |
+  tar -C "$repo_root" --null -T - -cf - |
+  tar -C "$working_dir" -xf -
+scan_directory() ( cd -- "$1"; gitleaks dir --config "$2" --redact=100 .; )
+scan_directory "$index_dir" "$index_config_path"
+scan_directory "$working_dir" "$working_dir/$config_path"

package/skills/dotnet-test-authoring/SKILL.md

@@ -14,3 +14,8 @@ Consumer wrappers own solution layout, test frameworks, native dependencies, and
 
 Keep portable library tests separate from rendered application tests; batch compatible native targets
 in one selection pass so a shared build validates the same source set.
+
+Before finishing an assertion, name a concrete defect in the code under test that would make it fail;
+an `Assert.True(true)` or a re-implemented computation compared against itself passes for every input
+and proves nothing, so treat [tautological tests](../test-authoring/references/tautological-tests.md)
+as a defect even when coverage looks satisfied.

package/skills/manifest.json

@@ -4,7 +4,7 @@
     {
       "name": "agent-workflow",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.6.2",
+      "pluginVersion": "0.6.3",
       "path": "agent-workflow/SKILL.md"
     },
     {
@@ -17,13 +17,13 @@
     {
       "name": "blackboard",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.6.2",
+      "pluginVersion": "0.6.3",
       "path": "blackboard/SKILL.md"
     },
     {
       "name": "dependabot",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.6.2",
+      "pluginVersion": "0.6.3",
       "path": "dependabot/SKILL.md",
       "prerequisites": ["github-actions-checklist"]
     },
@@ -36,26 +36,26 @@
     {
       "name": "git-commit-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.6.2",
+      "pluginVersion": "0.6.3",
       "path": "git-commit-checklist/SKILL.md"
     },
     {
       "name": "github-actions-authoring",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.6.2",
+      "pluginVersion": "0.6.3",
       "path": "github-actions-authoring/SKILL.md",
       "prerequisites": ["github-actions-checklist"]
     },
     {
       "name": "github-actions-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.6.2",
+      "pluginVersion": "0.6.3",
       "path": "github-actions-checklist/SKILL.md"
     },
     {
       "name": "github-issue",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.6.2",
+      "pluginVersion": "0.6.3",
       "path": "github-issue/SKILL.md"
     },
     {
@@ -68,25 +68,25 @@
     {
       "name": "npm-publishing",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.6.2",
+      "pluginVersion": "0.6.3",
       "path": "npm-publishing/SKILL.md"
     },
     {
       "name": "organize-github-issues",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.6.2",
+      "pluginVersion": "0.6.3",
       "path": "organize-github-issues/SKILL.md"
     },
     {
       "name": "package-json-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.6.2",
+      "pluginVersion": "0.6.3",
       "path": "package-json-checklist/SKILL.md"
     },
     {
       "name": "planning",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.6.2",
+      "pluginVersion": "0.6.3",
       "path": "planning/SKILL.md"
     },
     {
@@ -110,43 +110,43 @@
     {
       "name": "pr-description",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.6.2",
+      "pluginVersion": "0.6.3",
       "path": "pr-description/SKILL.md"
     },
     {
       "name": "retrospective",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.6.2",
+      "pluginVersion": "0.6.3",
       "path": "retrospective/SKILL.md"
     },
     {
       "name": "retrospective-distill",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.6.2",
+      "pluginVersion": "0.6.3",
       "path": "retrospective-distill/SKILL.md"
     },
     {
       "name": "review-ci-logs",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.6.2",
+      "pluginVersion": "0.6.3",
       "path": "review-ci-logs/SKILL.md"
     },
     {
       "name": "review-github-issue-taxonomy",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.6.2",
+      "pluginVersion": "0.6.3",
       "path": "review-github-issue-taxonomy/SKILL.md"
     },
     {
       "name": "revisit-followups",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.6.2",
+      "pluginVersion": "0.6.3",
       "path": "revisit-followups/SKILL.md"
     },
     {
       "name": "static-analysis-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.6.2",
+      "pluginVersion": "0.6.3",
       "path": "static-analysis-checklist/SKILL.md"
     },
     {

package/skills/playwright-authoring/SKILL.md

@@ -13,3 +13,6 @@ failure. Prefer browser coverage for real browser interactions rather than dupli
 Consumer wrappers own environments, credentials, personas, fixtures, and suite commands.
 
 Read [browser reliability](references/browser-reliability.md) for locator, waiting, state, and network rules.
+
+Read [tautological tests](../test-authoring/references/tautological-tests.md) before finishing any
+assertion that is not obviously falsifiable by a defect in the flow under test.

package/skills/retrospective/SKILL.md

@@ -17,5 +17,10 @@ Read the local `AGENTS.md`, `CLAUDE.md`, and journal guidance first.
 4. Save through the repository's required durable mechanism and report the record identifier plus
    any follow-up decisions.
 
+Use raw evidence only for local verification. Save only bounded structured facts or redacted summaries
+in a durable retrospective; never embed unredacted logs, command output, environment dumps, provider
+payloads, or transcript content there.
+
 Do not prescribe transcript access, retention, a report schema, a journal provider, or issue
-filing policy. Consumer wrappers add those local contracts.
+filing policy. Consumer wrappers add those local contracts without weakening this minimization
+boundary.

package/skills/storybook-authoring/SKILL.md

@@ -13,3 +13,6 @@ end-to-end setup or production data handling.
 Consumer wrappers own Storybook configuration, exclusions, visual baselines, and commands.
 
 Read [component coverage](references/component-coverage.md) for direct stories and browser isolation.
+
+Read [tautological tests](../test-authoring/references/tautological-tests.md) before finishing any
+interaction assertion that is not obviously falsifiable by a defect in the component under test.

package/skills/swift-test-authoring/SKILL.md

@@ -13,3 +13,6 @@ fixtures small enough to make failures readable.
 Consumer wrappers own test targets, coverage thresholds, view-inspection libraries, and fixture APIs.
 
 Read [network test doubles](references/network-test-doubles.md) for cancellation and shared-state safety.
+
+Read [tautological tests](../test-authoring/references/tautological-tests.md) before finishing any
+assertion that is not obviously falsifiable by a defect in the code under test.

package/skills/test-authoring/SKILL.md

@@ -15,3 +15,6 @@ A consumer wrapper owns those choices.
 
 Read [core practice](references/core-practice.md) for the shared boundary, completion, and evidence
 rules before choosing a runner-specific approach.
+
+Read [tautological tests](references/tautological-tests.md) before finishing any test whose
+assertion is not obviously falsifiable by a defect in the code under test.

package/skills/test-authoring/references/core-practice.md

@@ -7,4 +7,5 @@ failure paths, authorization, and security-relevant validation rather than priva
 Start with a failing test when the behavior is testable. Finish only when the production path, its
 public contract, documentation, and generated artifacts move together. Do not leave placeholders or
 test-only production branches. For every acceptance criterion, retain evidence from a focused test,
-review, or explicitly justified manual check.
+review, or explicitly justified manual check — evidence only counts if it is falsifiable, so confirm
+the assertion is not [tautological](tautological-tests.md) before treating it as coverage.

package/skills/test-authoring/references/tautological-tests.md

@@ -0,0 +1,46 @@
+# Tautological tests
+
+A test is tautological when no defect in the code under test could make its assertion fail. Before
+trusting an assertion, name a concrete defect it would catch; if none exists, the assertion proves
+nothing regardless of how many lines it exercises. A test name is part of the assertion: `it('returns
+200')` that never reads the status is itself the defect, since reviewers trust the name and skim the
+body instead of checking that it matches what is asserted.
+
+Watch for these shapes, most consequential first. A forced-value tautology transforms the result
+before asserting on the transformed constant, as in `expect(x.then(() => undefined))
+.resolves.toBeUndefined()`: the `.then` still depends on `x` fulfilling rather than rejecting, but
+every fulfillment value collapses to the same `undefined`, so the assertion no longer depends on what
+the code actually returned — ask whether the assertion still depends on the code's output, not merely
+on whether it threw; a test named after the data it claims to return is asserting nothing about that
+data. A literal tautology asserts a literal against itself, `expect(true).toBe(true)`, with
+equivalents in other runners (`XCTAssertTrue(true)`, `Assert.True(true)`). A self-comparison,
+`expect(x).toBe(x)`, and a literal echo that asserts on a value the test itself just wrote fail the
+same way: the input and the expectation are the same value with no code path in between. A mock echo
+asserts that a mock returns what it was configured to return, exercising the mock's configuration
+rather than the code under test. A re-implementation recomputes the production algorithm inside the
+test and compares the two computations, so a bug shared by both cancels out invisibly. A vacuous
+range or shape check — `expect(x.length).toBeGreaterThanOrEqual(0)`, or a `toBeDefined()`/`typeof`
+check on a static import or a value the test just constructed — holds for every possible output. A
+no-assert test awaits a call and asserts nothing afterward: it fails if the call throws, but nothing
+distinguishes a correct return value from an incorrect one, and an `expect-expect` lint rule will
+flag the missing assertion regardless.
+
+Coverage pressure is the usual root cause: a line must be covered and no assertion is obvious. Before
+reaching for a weak assertion, check whether the code takes a null- or error-swallowing path for the
+case under test — a repository-lookup helper that returns `null` instead of throwing for a not-found
+condition, for example — and assert the exact expected outcome for the case under test, such as
+`.toBeNull()` for the not-found path or a definite non-null shape for the found path, rather than a
+looser definedness check that would still pass if a regression collapsed the two. Otherwise assert
+the shape of the returned payload. Only when neither is available, fall back to an assertion that
+depends on nothing but successful completion, such as `await expect(run())
+.resolves.not.toBeInstanceOf(Error)`, paired with a test name that says "resolves" rather than
+"succeeds" or "returns 200" — a legitimately weak assertion, honestly labeled as weak. Satisfying a
+coverage percentage while asserting nothing is never acceptable; a 403 executes the same lines as a
+200, and coverage tooling cannot tell them apart.
+
+Delete a tautological test if removing it does not reduce coverage; if it does, that test was the sole
+owner of that coverage and must be strengthened in place, not deleted, since a steady coverage number
+is not evidence the remaining tests check anything real. Consumer repositories may enforce the
+mechanical shapes above with ast-grep rules and an `expect-expect` lint rule; this document is the
+judgment layer for shapes those tools cannot express, such as a definedness check that needs dataflow
+analysis, a mock echo, or a re-implementation — tooling and this guidance should agree, not diverge.