commandmate 0.22.2 → 0.23.0

package/dist/server/src/lib/verification/scope-gate.js

@@ -0,0 +1,402 @@
+"use strict";
+/**
+ * Built-in `scope` gate: reconcile what actually changed in the worktree against
+ * the contract's `scope.allow` / `scope.deny` (Issue #1546, Phase 2-2).
+ *
+ * Canonical spec: docs/design/task-contract.md §2.2
+ *
+ * A parallel worker that edits a shared config file, or quietly rewrites a
+ * module another worker owns, produces a green run and a broken integration.
+ * The contract already declares which paths the task may touch; this gate is
+ * what makes that declaration something other than a comment.
+ *
+ * Promoted from `.claude/skills/orchestrate-monitor/scripts/verify-scope.sh`.
+ * That script is a *grep* guard over one file rather than a diff-versus-glob
+ * check, so what carries over is not its logic but the two ways it false-reported
+ * (both recorded in feedback_orchestrate_monitor_started_guard):
+ *
+ *   1. It matched a forbidden pattern that appeared only in explanatory prose.
+ *      The analogue here is judging text instead of paths, so nothing in this
+ *      module ever greps content: the file set comes from git plumbing, and the
+ *      verdict comes from matching whole paths.
+ *   2. Its `grep -c ... || echo 0` idiom emitted a two-line "0\n0" that the
+ *      caller read as a count. The analogue is git output that parses into
+ *      phantom entries, so every git call here is `-z`: the human formats quote
+ *      and arrow-join paths, and splitting those on whitespace invents files
+ *      that do not exist.
+ *
+ * Server-only: spawns git and is called from the verification engine.
+ *
+ * @module lib/verification/scope-gate
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCOPE_SKIP_NOT_REQUIRED = exports.SCOPE_SKIP_NO_CONTRACT = exports.ScopeMatcher = exports.CONTRACT_DIR_PREFIX = exports.ALWAYS_ALLOWED_PREFIX = exports.SCOPE_ALLOW_GUIDANCE = exports.MAX_REPORTED_VIOLATIONS = void 0;
+exports.isContractPath = isContractPath;
+exports.parsePorcelainEntries = parsePorcelainEntries;
+exports.collectChangedPaths = collectChangedPaths;
+exports.scopeSkipDetachedContract = scopeSkipDetachedContract;
+exports.evaluateScope = evaluateScope;
+const child_process_1 = require("child_process");
+/**
+ * Violations listed in `log_tail` before the rest are summarised as a count.
+ *
+ * A worker that ran in the wrong directory can put thousands of paths out of
+ * scope, and log_tail is stored per gate in SQLite.
+ */
+exports.MAX_REPORTED_VIOLATIONS = 100;
+/**
+ * Actionable coda appended to every scope failure report (#1683).
+ *
+ * The violating paths alone say *what* failed but not what to do about it —
+ * #1678 B-2 is a worker structurally unable to pass because a lockfile was
+ * missing from the issue's target-file list, and nothing in the output said so.
+ * The wording answers both directions a violation can resolve: widen the
+ * declared scope when the diff is intended, revert when it is not. Re-sending
+ * is named because scope is judged from the contract's send-time snapshot, so
+ * editing the YAML in place changes nothing.
+ */
+exports.SCOPE_ALLOW_GUIDANCE = "To allow this diff, add the paths above to the contract's scope.allow (the " +
+    "issue's target-file list) and re-send the task (`send --contract`) — scope " +
+    'is judged from the send-time snapshot, so editing the contract file alone ' +
+    'changes nothing. A path matching deny: is a deliberate prohibition; revert ' +
+    'it instead.';
+/**
+ * Paths that are in scope no matter what the contract says.
+ *
+ * The contract file lives here, so a contract whose own `allow` list forgot to
+ * mention `.commandmate/` would fail the moment it was committed — the scope
+ * declaration would make its own storage a violation. The exemption covers the
+ * `allow` requirement only; an explicit `deny` still applies, because a deny is
+ * a deliberate prohibition and silently ignoring one is worse than the accident
+ * this exemption prevents.
+ */
+exports.ALWAYS_ALLOWED_PREFIX = '.commandmate/';
+/**
+ * Execution contracts, dropped from both gates' change sets entirely (#1580).
+ *
+ * An orchestrator writes `.commandmate/tasks/<task>.yaml` into a worktree and
+ * sends immediately, without committing it. Counting that file as change makes
+ * an agent that did nothing indistinguishable from one that did something:
+ * work-evidence sees a dirty tree and passes, and the run that should have been
+ * `not_started` collects a row of green gates instead.
+ *
+ * Dropping it is tamper-safe because the contract is snapshotted into
+ * `tasks.contract_json` at send time (src/lib/db/tasks-db.ts), so editing the
+ * file afterwards cannot change what the run is judged against.
+ * `.commandmate/verify.yaml` has no such snapshot — the gates are re-read from
+ * the file on every run — so it stays in the change set, where a contract's
+ * explicit `deny` can still catch an agent weakening its own gates.
+ */
+exports.CONTRACT_DIR_PREFIX = '.commandmate/tasks/';
+/** Whether git reported a path that {@link CONTRACT_DIR_PREFIX} excludes. */
+function isContractPath(path) {
+    return path.startsWith(exports.CONTRACT_DIR_PREFIX);
+}
+// =============================================================================
+// Glob matching
+// =============================================================================
+/**
+ * Translate a scope glob into an anchored regular expression.
+ *
+ * Deliberately a small, documented subset rather than a glob library. The
+ * semantics are fixed in docs/design/task-contract.md §2.2:
+ *
+ * - `**` as a whole path segment crosses directory boundaries, including zero of
+ *   them: `a/**` matches `a/b` and `a/b/c`, `**\/*.ts` matches `x.ts`.
+ * - `*` and `?` never cross `/`. Leading dots are ordinary characters, so
+ *   `.github/**` and `*.md` behave the way they read.
+ * - `{a,b}` is alternation, nestable. Unbalanced braces are literal, as in a
+ *   shell — `src/{a` is a path with a brace in it, not a syntax error.
+ * - `[` and `]` are **literal**. This repository routes through
+ *   `src/app/proxy/[...path]/`, and treating those as character classes would
+ *   make the pattern that names them match nothing at all — a silent no-match is
+ *   the failure mode this gate exists to avoid.
+ * - A pattern that matches a directory also matches everything beneath it, so
+ *   `src/lib`, `src/lib/` and `src/lib/**` all mean the same thing. Without this
+ *   rule, `allow: ["src/lib/verification"]` — the way people write a directory —
+ *   would put every file inside it out of scope.
+ */
+function globToRegExp(rawPattern) {
+    // A trailing slash carries no information once the rule above applies.
+    const pattern = rawPattern.replace(/\/+$/, '');
+    const bracesBalanced = hasBalancedBraces(pattern);
+    let source = '';
+    let depth = 0;
+    let i = 0;
+    while (i < pattern.length) {
+        const char = pattern[i];
+        if (char === '*') {
+            let end = i;
+            while (pattern[end] === '*')
+                end += 1;
+            const isGlobstar = end - i > 1;
+            const atSegmentStart = i === 0 || pattern[i - 1] === '/';
+            if (isGlobstar && atSegmentStart && pattern[end] === '/') {
+                // Consume the following slash too: `a/**/b` has to match `a/b`.
+                source += '(?:[^/]*/)*';
+                i = end + 1;
+                continue;
+            }
+            if (isGlobstar && atSegmentStart && end === pattern.length) {
+                source += '.*';
+                i = end;
+                continue;
+            }
+            // `**` that is not a whole segment (`a**b`) cannot mean "cross
+            // directories" without also matching `a/x/b`, which the pattern does not
+            // say. Collapse it to a single-segment wildcard.
+            source += '[^/]*';
+            i = end;
+            continue;
+        }
+        if (char === '?') {
+            source += '[^/]';
+            i += 1;
+            continue;
+        }
+        if (bracesBalanced && char === '{') {
+            depth += 1;
+            source += '(?:';
+            i += 1;
+            continue;
+        }
+        if (bracesBalanced && char === '}' && depth > 0) {
+            depth -= 1;
+            source += ')';
+            i += 1;
+            continue;
+        }
+        if (bracesBalanced && char === ',' && depth > 0) {
+            source += '|';
+            i += 1;
+            continue;
+        }
+        source += char.replace(/[.*+?^${}()|[\]\\]/, '\\$&');
+        i += 1;
+    }
+    return new RegExp(`^${source}(?:/.*)?$`);
+}
+function hasBalancedBraces(pattern) {
+    let depth = 0;
+    for (const char of pattern) {
+        if (char === '{')
+            depth += 1;
+        else if (char === '}') {
+            depth -= 1;
+            if (depth < 0)
+                return false;
+        }
+    }
+    return depth === 0;
+}
+/**
+ * A scope declaration compiled once per run.
+ *
+ * Compiling per pattern per file would rebuild the same regexes for every one of
+ * potentially thousands of changed paths.
+ */
+class ScopeMatcher {
+    contractPath;
+    allow;
+    deny;
+    /**
+     * @param contractPath the contract's own path, exempted alongside
+     *        {@link ALWAYS_ALLOWED_PREFIX} for contracts kept outside `.commandmate/`
+     */
+    constructor(scope, contractPath = null) {
+        this.contractPath = contractPath;
+        this.allow = scope.allow.map(globToRegExp);
+        this.deny = scope.deny.map(globToRegExp);
+    }
+    /**
+     * Whether `path` is a scope violation.
+     *
+     * `path` is a repository-root-relative POSIX path as git reports it.
+     */
+    isViolation(path) {
+        if (this.deny.some((pattern) => pattern.test(path)))
+            return true;
+        if (path.startsWith(exports.ALWAYS_ALLOWED_PREFIX) || path === this.contractPath)
+            return false;
+        return !this.allow.some((pattern) => pattern.test(path));
+    }
+}
+exports.ScopeMatcher = ScopeMatcher;
+// =============================================================================
+// Changed-path collection
+// =============================================================================
+/** Run a git plumbing command. No shell: every argument here is code-supplied. */
+function runGit(args, cwd) {
+    return new Promise((resolve) => {
+        let stdout = '';
+        let stderr = '';
+        const child = (0, child_process_1.spawn)('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+        child.stdout?.on('data', (chunk) => {
+            stdout += chunk.toString('utf8');
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr += chunk.toString('utf8');
+        });
+        child.on('error', (error) => resolve({ code: null, stdout: '', stderr: error.message }));
+        child.on('close', (code) => resolve({ code, stdout, stderr }));
+    });
+}
+function splitNul(output) {
+    return output.split('\0').filter((field) => field !== '');
+}
+/**
+ * Paths in `git status --porcelain -z -uall` output.
+ *
+ * Measured format (git 2.49): every record is `XY<space><path>NUL`, and a
+ * rename or copy appends the original path as the *next* NUL field —
+ * `R  new.txt\0old.txt\0`. Note that this is the reverse of the human
+ * `old -> new` rendering, and that `-z` writes paths verbatim while the human
+ * format C-quotes anything containing a space. Both paths of a rename are
+ * returned: moving a file *out of* a permitted directory is a change to that
+ * directory, and judging only the destination would miss it.
+ *
+ * Grouped per entry rather than flattened because work-evidence counts entries,
+ * and a rename that moved a contract file into real work has to stay countable
+ * as one change (#1580).
+ */
+function parsePorcelainEntries(output) {
+    const fields = output.split('\0');
+    const entries = [];
+    let i = 0;
+    while (i < fields.length) {
+        const entry = fields[i];
+        i += 1;
+        // "XY " plus at least one path character.
+        if (entry.length < 4)
+            continue;
+        const paths = [entry.slice(3)];
+        const [x, y] = entry;
+        if (x === 'R' || x === 'C' || y === 'R' || y === 'C') {
+            const original = fields[i];
+            i += 1;
+            if (original)
+                paths.push(original);
+        }
+        entries.push(paths);
+    }
+    return entries;
+}
+/**
+ * Every path this worktree changed relative to `baseRef`.
+ *
+ * The union of committed and uncommitted change is deliberate: looking only at
+ * commits misses a deviation the agent has not committed yet, and looking only
+ * at the working tree misses everything it did commit.
+ *
+ * @returns the paths, or a message describing which git call could not answer
+ */
+async function collectChangedPaths(worktreePath, baseRef) {
+    const mergeBase = await runGit(['merge-base', baseRef, 'HEAD'], worktreePath);
+    if (mergeBase.code !== 0 || mergeBase.stdout.trim() === '') {
+        return {
+            error: `'git merge-base ${baseRef} HEAD' failed; base ref is unreachable from this worktree.` +
+                (mergeBase.stderr.trim() ? `\n${mergeBase.stderr.trim()}` : ''),
+        };
+    }
+    const base = mergeBase.stdout.trim();
+    // --no-renames so a committed rename reports both paths (--name-only alone
+    // reports the destination only, once rename detection folds the pair).
+    const diff = await runGit(['diff', '--name-only', '-z', '--no-renames', base, 'HEAD'], worktreePath);
+    if (diff.code !== 0) {
+        return {
+            error: `'git diff --name-only ${base} HEAD' failed.` +
+                (diff.stderr.trim() ? `\n${diff.stderr.trim()}` : ''),
+        };
+    }
+    // -uall: without it a new directory collapses to a single `?? dir/` entry, and
+    // the gate would judge a directory name instead of the files inside it.
+    const status = await runGit(['status', '--porcelain', '-z', '--untracked-files=all'], worktreePath);
+    if (status.code !== 0) {
+        return {
+            error: "'git status --porcelain' failed." +
+                (status.stderr.trim() ? `\n${status.stderr.trim()}` : ''),
+        };
+    }
+    // Both sides are filtered, not just the working tree: an orchestrator may
+    // also have committed the contract as a setup commit (#1580).
+    const paths = new Set([...splitNul(diff.stdout), ...parsePorcelainEntries(status.stdout).flat()].filter((path) => !isContractPath(path)));
+    return { paths: [...paths].sort(), mergeBase: base };
+}
+// =============================================================================
+// Gate evaluation
+// =============================================================================
+function formatPatterns(patterns) {
+    return patterns.length > 0 ? patterns.join(', ') : '(none)';
+}
+/**
+ * Reasons the gate has nothing to judge, phrased for `log_tail`.
+ *
+ * A skip is recorded rather than omitted: a run with no scope row at all is
+ * indistinguishable from a run predating the gate, and "we looked and no
+ * contract declared a scope" is the answer the reader needs.
+ */
+exports.SCOPE_SKIP_NO_CONTRACT = 'scope: no contract is attached to this run, so no scope is declared to check.';
+exports.SCOPE_SKIP_NOT_REQUIRED = 'scope: the contract sets success.requireScopeClean: false.';
+/**
+ * The skip that is *not* harmless: a contract exists and this run could not be
+ * attached to it (#1620).
+ *
+ * Worded apart from {@link SCOPE_SKIP_NO_CONTRACT} on purpose. Both are skips,
+ * but only one of them means "there was nothing to judge" — reporting the other
+ * with the same sentence is what let a run whose scope was never checked read
+ * as a repository that simply does not use contracts. The task id is named so
+ * the reader can go and look at what was not judged.
+ */
+function scopeSkipDetachedContract(taskId, status) {
+    return (`scope: task ${taskId} declares a scope for this worktree, but it is ${status} and ` +
+        'this run was not attached to it, so its scope was NOT judged. ' +
+        'Name the task when starting the run (`wait --verify` does this automatically).');
+}
+/**
+ * Judge the worktree's changes against a contract's scope.
+ *
+ * @param scope declared scope, or null when no contract is attached to the run
+ * @param requireScopeClean the contract's `success.requireScopeClean`
+ * @param baseRef ref the change set is computed against; null when unresolved
+ * @param contractPath the contract's own path, always exempt from `allow`
+ */
+async function evaluateScope(worktreePath, scope, requireScopeClean, baseRef, contractPath = null) {
+    const startedAt = Date.now();
+    const done = (status, logTail, exitCode) => ({
+        status,
+        exitCode,
+        startedAt,
+        durationMs: Date.now() - startedAt,
+        logTail,
+    });
+    if (!scope)
+        return done('skipped', exports.SCOPE_SKIP_NO_CONTRACT, null);
+    if (!requireScopeClean)
+        return done('skipped', exports.SCOPE_SKIP_NOT_REQUIRED, null);
+    if (!baseRef) {
+        return done('error', 'scope: no base ref, so there is nothing to diff against. Set options.baseRef in ' +
+            '.commandmate/verify.yaml; origin/HEAD did not resolve a default branch.', null);
+    }
+    const changed = await collectChangedPaths(worktreePath, baseRef);
+    if ('error' in changed)
+        return done('error', `scope: ${changed.error}`, null);
+    const matcher = new ScopeMatcher(scope, contractPath);
+    const violations = changed.paths.filter((path) => matcher.isViolation(path));
+    const summary = `scope: baseRef=${baseRef} changed=${changed.paths.length} violations=${violations.length}\n` +
+        `allow: ${formatPatterns(scope.allow)}\ndeny: ${formatPatterns(scope.deny)}`;
+    if (violations.length === 0) {
+        // An empty change set passes: work-evidence is the gate that judges "nothing
+        // happened", and failing here too would report one problem as two.
+        return done('passed', summary, 0);
+    }
+    const listed = violations.slice(0, exports.MAX_REPORTED_VIOLATIONS);
+    const remainder = violations.length - listed.length;
+    const report = [
+        summary,
+        'out of scope:',
+        ...listed.map((path) => `  - ${path}`),
+        ...(remainder > 0 ? [`  ... and ${remainder} more`] : []),
+        exports.SCOPE_ALLOW_GUIDANCE,
+    ].join('\n');
+    return done('failed', report, 1);
+}

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

@@ -0,0 +1,281 @@
+"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.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.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';
+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;
+const GATE_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/;
+const TOP_LEVEL_KEYS = ['version', 'gates', 'options'];
+const GATE_KEYS = ['id', 'command', 'timeoutSec'];
+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)`);
+        }
+    }
+}
+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)) {
+        issues.push(`gates: must be a list (got ${describe(value)})`);
+        return [];
+    }
+    if (value.length === 0) {
+        issues.push('gates: at least one gate must be defined');
+        return [];
+    }
+    const gates = [];
+    const seenIds = new Set();
+    value.forEach((entry, index) => {
+        const at = `gates[${index}]`;
+        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 (!GATE_ID_PATTERN.test(entry.id)) {
+            issues.push(`${at}.id: "${entry.id}" must match ${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;
+            }
+        }
+        if (issues.length === issuesBefore) {
+            gates.push({ id: entry.id, command: entry.command, timeoutSec });
+        }
+    });
+    return gates;
+}
+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);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commandmate",
-  "version": "0.22.2",
+  "version": "0.23.0",
   "description": "A local control plane for agent CLIs — orchestration and visibility for Claude Code, Codex, Gemini CLI, and more across Git worktrees",
   "keywords": [
     "claude-code",