commandmate 0.29.1 → 0.29.2

package/dist/lib/verification/verify-config.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Loader and validator for `.commandmate/verify.yaml`.
+ *
+ * Canonical spec: docs/design/verification-config.md
+ * Phase 0 reference implementation: .claude/skills/cmate-verify/scripts/verify-run.sh
+ *
+ * Server-only: reads from disk, so import this from API routes / CLI only.
+ */
+export interface VerifyGate {
+    id: string;
+    command: string;
+    timeoutSec: number;
+    /**
+     * Name of a machine-wide lock this gate must hold while it runs (Issue #1771).
+     *
+     * Declares "only one of these may run on this machine at a time", which a
+     * gate owning a fixed port, database or emulator needs and which command and
+     * timeout cannot express. Two parallel worktrees running such a gate at once
+     * make the second fail on the resource, and `GATE e2e FAIL exit=1` reads
+     * exactly like the change being broken.
+     *
+     * Optional rather than `string | null`: contracts store their gate list as
+     * JSON in `tasks.contract_json` and are read back with `JSON.parse`, never
+     * re-validated, so every row written before this field existed simply has no
+     * key — and `undefined` is the honest reading of that.
+     */
+    mutex?: string;
+    /**
+     * Re-run this gate once, in the same tree, when its command exits non-zero
+     * (Issue #1772). `1` opts in; `0` (the default) is the behaviour every gate
+     * had before this field existed.
+     *
+     * Only 0 and 1 are accepted. A gate allowed three or four attempts stops
+     * being a gate: enough re-runs turn any red into a green, and the value of
+     * this field is precisely that it cannot. One retry answers the one question
+     * worth asking — "does this reproduce in the same tree?" — and nothing more.
+     *
+     * Optional for the same reason {@link VerifyGate.mutex} is: contracts store
+     * their gate list as JSON in `tasks.contract_json` and read it back with
+     * `JSON.parse` without re-validating, so a row written before this field
+     * existed simply has no key.
+     */
+    retryOnFail?: number;
+    /**
+     * Whether a FLAKY outcome — failed, then passed on the retry — counts as a
+     * pass (Issue #1772). Default false: the gate does not get weaker by opting
+     * into a retry, it only gets a name for what happened.
+     *
+     * Declared per gate rather than per repository because it is a statement
+     * about *this* gate's failure mode. `unit` failing on a random UUID that
+     * happens to contain a forbidden substring is noise; `e2e` failing once and
+     * passing once is usually a real race in the product. An `options`-level flag
+     * would force those two into one answer, and would also be declarable for
+     * gates that never opted into a retry, where it can never fire.
+     *
+     * `true` without `retryOnFail: 1` is a config error rather than a no-op: no
+     * retry means no FLAKY, so the declaration could never take effect.
+     */
+    flakyIsPass?: boolean;
+}
+export interface VerifyOptions {
+    /** null when unset; the caller resolves the repository default branch. */
+    baseRef: string | null;
+    skipInPrimaryCheckout: boolean;
+    maxLogTailBytes: number;
+    /**
+     * Whether `work-evidence` demands a COMMIT rather than any change at all
+     * (Issue #1628, D-4). Default false — the gate's job has always been "is
+     * there work here to verify", and a dirty tree answers that.
+     *
+     * Turn it on in a repository whose delegations end in a commit (the task
+     * contract preamble tells agents "未 commit の作業は未完了とみなされる", and
+     * without this the gate happily passes `commits=0 uncommitted=1`, so
+     * `RESULT passed` proved nothing about the commit). Repository-wide by
+     * design: it is a property of how the repository is worked, not of one run.
+     */
+    requireCommit: boolean;
+    /**
+     * Whether the built-in `env-clean` gate judges this repository's runs
+     * (Issue #1740). Default false — every contract written before the gate
+     * existed must keep its verdict, and a gate that starts failing runs the day
+     * it lands is a gate that gets switched off again.
+     *
+     * Turning it on has a second effect: baselines are only recorded (at task
+     * creation) while it is on, because a snapshot of the machine is a side effect
+     * and the off state must have none. A run without a baseline reports UNKNOWN,
+     * never a pass.
+     */
+    requireEnvClean: boolean;
+}
+export interface VerifyConfig {
+    version: 1;
+    gates: VerifyGate[];
+    options: VerifyOptions;
+}
+/**
+ * Built-in gate that answers "is there any work here to verify?".
+ *
+ * Declared here rather than in the runner so modules that only reason *about*
+ * gate selection (task contracts) can name it without importing the engine.
+ */
+export declare const WORK_EVIDENCE_GATE_ID = "work-evidence";
+/**
+ * Built-in gate that reconciles the changed files against the contract's
+ * `scope.allow` / `scope.deny` (#1546). Declared alongside work-evidence for the
+ * same reason: `lib/tasks/contract-message.ts` has to name it while resolving a
+ * contract's gate list, and must not pull the engine in to do so.
+ */
+export declare const SCOPE_GATE_ID = "scope";
+/**
+ * Built-in gate that reconciles the *machine* against the snapshot taken when
+ * the task was created (#1740): listening CommandMate servers, `mcbd-*` tmux
+ * sessions, `$HOME` and `~/.commandmate`. `scope` answers what a delegation
+ * changed inside the repository; this answers what it changed outside one.
+ */
+export declare const ENV_CLEAN_GATE_ID = "env-clean";
+/** Gate IDs reserved for built-in gates; using one in `gates` is a config error. */
+export declare const RESERVED_GATE_IDS: readonly ["work-evidence", "scope", "env-clean"];
+export declare const VERIFY_CONFIG_RELATIVE_PATH = ".commandmate/verify.yaml";
+/**
+ * Gate ids a default full run executes, in the order the runner records them
+ * (Issue #2061).
+ *
+ * The Verification pane needs a denominator while a run is in flight — gate
+ * rows are created as each gate starts, so "3 gates recorded" is progress, not
+ * a total. Declared here rather than in the pane because the composition is the
+ * runner's: `work-evidence`, then `scope`, then `env-clean` only when a
+ * declaration switched it on, then verify.yaml's own gates in file order.
+ *
+ * A *default* run, which is what the pane's "run verification" button starts.
+ * A run narrowed with `--gates` / `gateIds` executes a subset of this.
+ *
+ * @param contractGates gate definitions the worktree's execution contract
+ *        carries (#1791). They run after verify.yaml's, exactly as
+ *        `declaredGates()` orders them, and leaving them out understated both
+ *        the pane's progress denominator and — since #2063 made the list
+ *        selectable — which gates an operator is allowed to re-run: a run whose
+ *        only failure was a contract gate offered nothing to re-run at all.
+ */
+export declare function defaultPlannedGateIds(config: VerifyConfig, contractGates?: readonly VerifyGate[]): string[];
+export declare const DEFAULT_TIMEOUT_SEC = 600;
+export declare const DEFAULT_MAX_LOG_TAIL_BYTES = 8192;
+/**
+ * Shape a gate id may take, wherever a gate is declared.
+ *
+ * Exported because the task contract declares gates too (#1791) and names them
+ * in `verify.gates`. A second copy of this expression would let the two
+ * declaration sites drift into accepting different ids, and a contract gate the
+ * runner refuses to resolve is a completion criterion nothing can evaluate.
+ */
+export declare const GATE_ID_PATTERN: RegExp;
+/**
+ * Shape a `mutex` name may take (Issue #1771).
+ *
+ * Wider than {@link GATE_ID_PATTERN} because a mutex names a *resource*, not a
+ * gate: two repositories that both bind port 60303 should be able to agree on
+ * `port.60303` and be serialized against each other. Narrow enough that the
+ * name is safe as a path segment — no separator, no whitespace, nothing a shell
+ * re-interprets — because both runners turn it into
+ * `~/.commandmate/locks/<name>.lock`.
+ */
+export declare const GATE_MUTEX_PATTERN: RegExp;
+/** Keeps the lock directory name inside every filesystem's limit. */
+export declare const MAX_GATE_MUTEX_LENGTH = 64;
+/**
+ * Largest `retryOnFail` a gate may declare (Issue #1772).
+ *
+ * Deliberately 1, and deliberately a named constant rather than a literal in
+ * one `if`: the ceiling is the feature. A gate that may re-run until it passes
+ * reports the machine's luck, not the work.
+ */
+export declare const MAX_RETRY_ON_FAIL = 1;
+export declare class VerifyConfigError extends Error {
+    readonly issues: string[];
+    constructor(issues: string[]);
+}
+/**
+ * Validate a list of `{ id, command, timeoutSec }` entries.
+ *
+ * Shared with the task contract's `verify.gateDefinitions` (#1791), which
+ * declares gates in the same shape and must be held to the same constraints —
+ * id pattern, reserved ids, duplicates, integer timeout in range. Calling this
+ * is what makes "the same constraints" a fact rather than a comment: a contract
+ * gate accepted here is one the runner can execute and the report can name.
+ *
+ * Deliberately does *not* decide whether the list may be absent or empty. That
+ * is the caller's rule: verify.yaml requires at least one gate, a contract that
+ * declares none is the normal case.
+ *
+ * @param at path prefix for issue messages (`gates`, `verify.gateDefinitions`)
+ * @returns the accepted entries; an entry that produced an issue is dropped so
+ *          the result never carries a value that failed validation
+ */
+export declare function validateGateEntries(value: unknown, at: string, issues: string[]): VerifyGate[];
+/**
+ * Read and validate `<repoPath>/.commandmate/verify.yaml`.
+ *
+ * @returns the validated config, or null when the file does not exist
+ * @throws VerifyConfigError with every violation collected in `issues`
+ */
+export declare function loadVerifyConfig(repoPath: string): VerifyConfig | null;
+//# sourceMappingURL=verify-config.d.ts.map

package/dist/lib/verification/verify-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-config.d.ts","sourceRoot":"","sources":["../../../src/lib/verification/verify-config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,qBAAqB,EAAE,OAAO,CAAC;IAC/B,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;OAUG;IACH,aAAa,EAAE,OAAO,CAAC;IACvB;;;;;;;;;;OAUG;IACH,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,CAAC,CAAC;IACX,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,OAAO,EAAE,aAAa,CAAC;CACxB;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,kBAAkB,CAAC;AAErD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,UAAU,CAAC;AAErC;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAE7C,oFAAoF;AACpF,eAAO,MAAM,iBAAiB,kDAIpB,CAAC;AAEX,eAAO,MAAM,2BAA2B,6BAA6B,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,YAAY,EACpB,aAAa,GAAE,SAAS,UAAU,EAAO,GACxC,MAAM,EAAE,CAWV;AAED,eAAO,MAAM,mBAAmB,MAAM,CAAC;AACvC,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAM/C;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,QAA8B,CAAC;AAE3D;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,QAAsB,CAAC;AAEtD,qEAAqE;AACrE,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAYnC,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;gBAEd,MAAM,EAAE,MAAM,EAAE;CAK7B;AA6CD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE,CAe9F;AA2OD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAYtE"}

package/dist/lib/verification/verify-config.js

@@ -0,0 +1,429 @@
+"use strict";
+/**
+ * Loader and validator for `.commandmate/verify.yaml`.
+ *
+ * Canonical spec: docs/design/verification-config.md
+ * Phase 0 reference implementation: .claude/skills/cmate-verify/scripts/verify-run.sh
+ *
+ * Server-only: reads from disk, so import this from API routes / CLI only.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VerifyConfigError = exports.MAX_RETRY_ON_FAIL = exports.MAX_GATE_MUTEX_LENGTH = exports.GATE_MUTEX_PATTERN = exports.GATE_ID_PATTERN = exports.DEFAULT_MAX_LOG_TAIL_BYTES = exports.DEFAULT_TIMEOUT_SEC = exports.VERIFY_CONFIG_RELATIVE_PATH = exports.RESERVED_GATE_IDS = exports.ENV_CLEAN_GATE_ID = exports.SCOPE_GATE_ID = exports.WORK_EVIDENCE_GATE_ID = void 0;
+exports.defaultPlannedGateIds = defaultPlannedGateIds;
+exports.validateGateEntries = validateGateEntries;
+exports.loadVerifyConfig = loadVerifyConfig;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const yaml_1 = require("yaml");
+/**
+ * Built-in gate that answers "is there any work here to verify?".
+ *
+ * Declared here rather than in the runner so modules that only reason *about*
+ * gate selection (task contracts) can name it without importing the engine.
+ */
+exports.WORK_EVIDENCE_GATE_ID = 'work-evidence';
+/**
+ * Built-in gate that reconciles the changed files against the contract's
+ * `scope.allow` / `scope.deny` (#1546). Declared alongside work-evidence for the
+ * same reason: `lib/tasks/contract-message.ts` has to name it while resolving a
+ * contract's gate list, and must not pull the engine in to do so.
+ */
+exports.SCOPE_GATE_ID = 'scope';
+/**
+ * Built-in gate that reconciles the *machine* against the snapshot taken when
+ * the task was created (#1740): listening CommandMate servers, `mcbd-*` tmux
+ * sessions, `$HOME` and `~/.commandmate`. `scope` answers what a delegation
+ * changed inside the repository; this answers what it changed outside one.
+ */
+exports.ENV_CLEAN_GATE_ID = 'env-clean';
+/** Gate IDs reserved for built-in gates; using one in `gates` is a config error. */
+exports.RESERVED_GATE_IDS = [
+    exports.WORK_EVIDENCE_GATE_ID,
+    exports.SCOPE_GATE_ID,
+    exports.ENV_CLEAN_GATE_ID,
+];
+exports.VERIFY_CONFIG_RELATIVE_PATH = '.commandmate/verify.yaml';
+/**
+ * Gate ids a default full run executes, in the order the runner records them
+ * (Issue #2061).
+ *
+ * The Verification pane needs a denominator while a run is in flight — gate
+ * rows are created as each gate starts, so "3 gates recorded" is progress, not
+ * a total. Declared here rather than in the pane because the composition is the
+ * runner's: `work-evidence`, then `scope`, then `env-clean` only when a
+ * declaration switched it on, then verify.yaml's own gates in file order.
+ *
+ * A *default* run, which is what the pane's "run verification" button starts.
+ * A run narrowed with `--gates` / `gateIds` executes a subset of this.
+ *
+ * @param contractGates gate definitions the worktree's execution contract
+ *        carries (#1791). They run after verify.yaml's, exactly as
+ *        `declaredGates()` orders them, and leaving them out understated both
+ *        the pane's progress denominator and — since #2063 made the list
+ *        selectable — which gates an operator is allowed to re-run: a run whose
+ *        only failure was a contract gate offered nothing to re-run at all.
+ */
+function defaultPlannedGateIds(config, contractGates = []) {
+    return [
+        exports.WORK_EVIDENCE_GATE_ID,
+        exports.SCOPE_GATE_ID,
+        ...(config.options.requireEnvClean ? [exports.ENV_CLEAN_GATE_ID] : []),
+        ...config.gates.map((gate) => gate.id),
+        // A contract gate whose id collides with verify.yaml is refused at send
+        // (#1791) and the runner refuses it again, so no de-duplication is needed
+        // here; a duplicate id would be a bug worth seeing rather than hiding.
+        ...contractGates.map((gate) => gate.id),
+    ];
+}
+exports.DEFAULT_TIMEOUT_SEC = 600;
+exports.DEFAULT_MAX_LOG_TAIL_BYTES = 8192;
+const MIN_TIMEOUT_SEC = 1;
+const MAX_TIMEOUT_SEC = 7200;
+const MAX_LOG_TAIL_BYTES = 1048576;
+/**
+ * Shape a gate id may take, wherever a gate is declared.
+ *
+ * Exported because the task contract declares gates too (#1791) and names them
+ * in `verify.gates`. A second copy of this expression would let the two
+ * declaration sites drift into accepting different ids, and a contract gate the
+ * runner refuses to resolve is a completion criterion nothing can evaluate.
+ */
+exports.GATE_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/;
+/**
+ * Shape a `mutex` name may take (Issue #1771).
+ *
+ * Wider than {@link GATE_ID_PATTERN} because a mutex names a *resource*, not a
+ * gate: two repositories that both bind port 60303 should be able to agree on
+ * `port.60303` and be serialized against each other. Narrow enough that the
+ * name is safe as a path segment — no separator, no whitespace, nothing a shell
+ * re-interprets — because both runners turn it into
+ * `~/.commandmate/locks/<name>.lock`.
+ */
+exports.GATE_MUTEX_PATTERN = /^[A-Za-z0-9_.-]+$/;
+/** Keeps the lock directory name inside every filesystem's limit. */
+exports.MAX_GATE_MUTEX_LENGTH = 64;
+/**
+ * Largest `retryOnFail` a gate may declare (Issue #1772).
+ *
+ * Deliberately 1, and deliberately a named constant rather than a literal in
+ * one `if`: the ceiling is the feature. A gate that may re-run until it passes
+ * reports the machine's luck, not the work.
+ */
+exports.MAX_RETRY_ON_FAIL = 1;
+const TOP_LEVEL_KEYS = ['version', 'gates', 'options'];
+const GATE_KEYS = ['id', 'command', 'timeoutSec', 'mutex', 'retryOnFail', 'flakyIsPass'];
+const OPTION_KEYS = [
+    'baseRef',
+    'skipInPrimaryCheckout',
+    'maxLogTailBytes',
+    'requireCommit',
+    'requireEnvClean',
+];
+class VerifyConfigError extends Error {
+    issues;
+    constructor(issues) {
+        super(`invalid verify config:\n${issues.map((issue) => `  - ${issue}`).join('\n')}`);
+        this.name = 'VerifyConfigError';
+        this.issues = issues;
+    }
+}
+exports.VerifyConfigError = VerifyConfigError;
+function isMapping(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * The bash reference parser strips outer quotes before comparing, so `timeoutSec: "900"`
+ * means 900 there. Accept the same spelling, but only an exact decimal literal.
+ */
+function asInteger(value) {
+    if (typeof value === 'number')
+        return Number.isInteger(value) ? value : null;
+    if (typeof value === 'string' && /^-?\d+$/.test(value))
+        return Number(value);
+    return null;
+}
+function asBoolean(value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    return null;
+}
+function describe(value) {
+    if (value === undefined)
+        return 'nothing';
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return 'a list';
+    if (typeof value === 'object')
+        return 'a mapping';
+    return String(value);
+}
+function collectUnknownKeys(mapping, allowed, at, issues) {
+    for (const key of Object.keys(mapping)) {
+        if (!allowed.includes(key)) {
+            issues.push(`${at}: unknown key "${key}" (v1 is a closed set)`);
+        }
+    }
+}
+/**
+ * Validate a list of `{ id, command, timeoutSec }` entries.
+ *
+ * Shared with the task contract's `verify.gateDefinitions` (#1791), which
+ * declares gates in the same shape and must be held to the same constraints —
+ * id pattern, reserved ids, duplicates, integer timeout in range. Calling this
+ * is what makes "the same constraints" a fact rather than a comment: a contract
+ * gate accepted here is one the runner can execute and the report can name.
+ *
+ * Deliberately does *not* decide whether the list may be absent or empty. That
+ * is the caller's rule: verify.yaml requires at least one gate, a contract that
+ * declares none is the normal case.
+ *
+ * @param at path prefix for issue messages (`gates`, `verify.gateDefinitions`)
+ * @returns the accepted entries; an entry that produced an issue is dropped so
+ *          the result never carries a value that failed validation
+ */
+function validateGateEntries(value, at, issues) {
+    if (!Array.isArray(value)) {
+        issues.push(`${at}: must be a list (got ${describe(value)})`);
+        return [];
+    }
+    const gates = [];
+    const seenIds = new Set();
+    value.forEach((entry, index) => {
+        const entryAt = `${at}[${index}]`;
+        validateGateEntry(entry, entryAt, seenIds, gates, issues);
+    });
+    return gates;
+}
+/** One gate entry; accepted entries are appended to `gates`. */
+function validateGateEntry(entry, at, seenIds, gates, issues) {
+    const issuesBefore = issues.length;
+    if (!isMapping(entry)) {
+        issues.push(`${at}: must be a mapping (got ${describe(entry)})`);
+        return;
+    }
+    collectUnknownKeys(entry, GATE_KEYS, at, issues);
+    if (typeof entry.id !== 'string' || entry.id === '') {
+        issues.push(`${at}.id: required, must be a non-empty string (got ${describe(entry.id)})`);
+    }
+    else if (!exports.GATE_ID_PATTERN.test(entry.id)) {
+        issues.push(`${at}.id: "${entry.id}" must match ${exports.GATE_ID_PATTERN.source}`);
+    }
+    else if (exports.RESERVED_GATE_IDS.includes(entry.id)) {
+        issues.push(`${at}.id: "${entry.id}" is reserved for a built-in gate`);
+    }
+    else if (seenIds.has(entry.id)) {
+        issues.push(`${at}.id: duplicate gate id "${entry.id}"`);
+    }
+    else {
+        seenIds.add(entry.id);
+    }
+    if (typeof entry.command !== 'string' || entry.command.trim() === '') {
+        issues.push(`${at}.command: required, must be a non-empty string (got ${describe(entry.command)})`);
+    }
+    let timeoutSec = exports.DEFAULT_TIMEOUT_SEC;
+    if (entry.timeoutSec !== undefined) {
+        const parsed = asInteger(entry.timeoutSec);
+        if (parsed === null) {
+            issues.push(`${at}.timeoutSec: must be an integer (got ${describe(entry.timeoutSec)})`);
+        }
+        else if (parsed < MIN_TIMEOUT_SEC || parsed > MAX_TIMEOUT_SEC) {
+            issues.push(`${at}.timeoutSec: must be ${MIN_TIMEOUT_SEC}..${MAX_TIMEOUT_SEC} (got ${parsed})`);
+        }
+        else {
+            timeoutSec = parsed;
+        }
+    }
+    let mutex;
+    if (entry.mutex !== undefined) {
+        if (typeof entry.mutex !== 'string' || entry.mutex === '') {
+            issues.push(`${at}.mutex: must be a non-empty string (got ${describe(entry.mutex)})`);
+        }
+        else if (entry.mutex.length > exports.MAX_GATE_MUTEX_LENGTH) {
+            issues.push(`${at}.mutex: must be at most ${exports.MAX_GATE_MUTEX_LENGTH} characters (got ${entry.mutex.length})`);
+        }
+        else if (!exports.GATE_MUTEX_PATTERN.test(entry.mutex)) {
+            issues.push(`${at}.mutex: "${entry.mutex}" must match ${exports.GATE_MUTEX_PATTERN.source}`);
+        }
+        else {
+            mutex = entry.mutex;
+        }
+    }
+    let retryOnFail;
+    if (entry.retryOnFail !== undefined) {
+        const parsed = asInteger(entry.retryOnFail);
+        if (parsed === null) {
+            issues.push(`${at}.retryOnFail: must be an integer (got ${describe(entry.retryOnFail)})`);
+        }
+        else if (parsed < 0 || parsed > exports.MAX_RETRY_ON_FAIL) {
+            // Not "at most N": the range is the contract. See MAX_RETRY_ON_FAIL.
+            issues.push(`${at}.retryOnFail: must be 0 or ${exports.MAX_RETRY_ON_FAIL} (got ${parsed})`);
+        }
+        else {
+            retryOnFail = parsed;
+        }
+    }
+    let flakyIsPass;
+    if (entry.flakyIsPass !== undefined) {
+        const parsed = asBoolean(entry.flakyIsPass);
+        if (parsed === null) {
+            issues.push(`${at}.flakyIsPass: must be true or false (got ${describe(entry.flakyIsPass)})`);
+        }
+        else if (parsed && retryOnFail !== exports.MAX_RETRY_ON_FAIL) {
+            // A knob that can never fire is a config bug, not a preference: without a
+            // retry the gate has no FLAKY outcome for this to reclassify, so the
+            // declaration reads as "flakes are tolerated here" while changing nothing.
+            issues.push(`${at}.flakyIsPass: true requires retryOnFail: ${exports.MAX_RETRY_ON_FAIL} ` +
+                '(without a retry a gate can never be FLAKY)');
+        }
+        else {
+            flakyIsPass = parsed;
+        }
+    }
+    if (issues.length === issuesBefore) {
+        const gate = {
+            id: entry.id,
+            command: entry.command,
+            timeoutSec,
+        };
+        // Only set when declared: an explicit `mutex: undefined` would serialize
+        // into a contract's stored JSON as a key, and "declared without a value"
+        // is not a state this field has. The same holds for the #1772 pair, whose
+        // absence has to keep meaning "this gate runs exactly once".
+        if (mutex !== undefined)
+            gate.mutex = mutex;
+        if (retryOnFail !== undefined)
+            gate.retryOnFail = retryOnFail;
+        if (flakyIsPass !== undefined)
+            gate.flakyIsPass = flakyIsPass;
+        gates.push(gate);
+    }
+}
+function validateGates(value, issues) {
+    if (value === undefined || value === null) {
+        issues.push('gates: required, at least one gate must be defined');
+        return [];
+    }
+    if (Array.isArray(value) && value.length === 0) {
+        issues.push('gates: at least one gate must be defined');
+        return [];
+    }
+    return validateGateEntries(value, 'gates', issues);
+}
+function validateOptions(value, issues) {
+    const options = {
+        baseRef: null,
+        skipInPrimaryCheckout: true,
+        maxLogTailBytes: exports.DEFAULT_MAX_LOG_TAIL_BYTES,
+        requireCommit: false,
+        requireEnvClean: false,
+    };
+    // A childless `options:` key parses as null and means "all defaults".
+    if (value === undefined || value === null)
+        return options;
+    if (!isMapping(value)) {
+        issues.push(`options: must be a mapping (got ${describe(value)})`);
+        return options;
+    }
+    collectUnknownKeys(value, OPTION_KEYS, 'options', issues);
+    if (value.baseRef !== undefined) {
+        if (typeof value.baseRef !== 'string' || value.baseRef.trim() === '') {
+            issues.push(`options.baseRef: must be a non-empty string (got ${describe(value.baseRef)})`);
+        }
+        else {
+            options.baseRef = value.baseRef;
+        }
+    }
+    if (value.skipInPrimaryCheckout !== undefined) {
+        const parsed = asBoolean(value.skipInPrimaryCheckout);
+        if (parsed === null) {
+            issues.push(`options.skipInPrimaryCheckout: must be true or false (got ${describe(value.skipInPrimaryCheckout)})`);
+        }
+        else {
+            options.skipInPrimaryCheckout = parsed;
+        }
+    }
+    if (value.requireCommit !== undefined) {
+        const parsed = asBoolean(value.requireCommit);
+        if (parsed === null) {
+            issues.push(`options.requireCommit: must be true or false (got ${describe(value.requireCommit)})`);
+        }
+        else {
+            options.requireCommit = parsed;
+        }
+    }
+    if (value.requireEnvClean !== undefined) {
+        const parsed = asBoolean(value.requireEnvClean);
+        if (parsed === null) {
+            issues.push(`options.requireEnvClean: must be true or false (got ${describe(value.requireEnvClean)})`);
+        }
+        else {
+            options.requireEnvClean = parsed;
+        }
+    }
+    if (value.maxLogTailBytes !== undefined) {
+        const parsed = asInteger(value.maxLogTailBytes);
+        if (parsed === null) {
+            issues.push(`options.maxLogTailBytes: must be an integer (got ${describe(value.maxLogTailBytes)})`);
+        }
+        else if (parsed < 0 || parsed > MAX_LOG_TAIL_BYTES) {
+            issues.push(`options.maxLogTailBytes: must be 0..${MAX_LOG_TAIL_BYTES} (got ${parsed})`);
+        }
+        else {
+            options.maxLogTailBytes = parsed;
+        }
+    }
+    return options;
+}
+function parseVerifyConfig(raw, configPath) {
+    let document;
+    try {
+        document = (0, yaml_1.parse)(raw);
+    }
+    catch (error) {
+        throw new VerifyConfigError([`${configPath}: YAML parse error: ${error.message}`]);
+    }
+    if (!isMapping(document)) {
+        throw new VerifyConfigError([
+            `${configPath}: expected a YAML mapping at the top level (got ${describe(document)})`,
+        ]);
+    }
+    const issues = [];
+    collectUnknownKeys(document, TOP_LEVEL_KEYS, 'top level', issues);
+    if (!('version' in document)) {
+        issues.push('version: required, v1 configs must declare "version: 1"');
+    }
+    else if (asInteger(document.version) !== 1) {
+        issues.push(`version: must be 1 (got ${describe(document.version)})`);
+    }
+    const gates = validateGates(document.gates, issues);
+    const options = validateOptions(document.options, issues);
+    if (issues.length > 0)
+        throw new VerifyConfigError(issues);
+    return { version: 1, gates, options };
+}
+/**
+ * Read and validate `<repoPath>/.commandmate/verify.yaml`.
+ *
+ * @returns the validated config, or null when the file does not exist
+ * @throws VerifyConfigError with every violation collected in `issues`
+ */
+function loadVerifyConfig(repoPath) {
+    const configPath = (0, path_1.join)(repoPath, exports.VERIFY_CONFIG_RELATIVE_PATH);
+    let raw;
+    try {
+        raw = (0, fs_1.readFileSync)(configPath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw new VerifyConfigError([`${configPath}: ${error.message}`]);
+    }
+    return parseVerifyConfig(raw, configPath);
+}