@opengsd/gsd-core 1.14.0 → 1.16.0

package/gsd-core/bin/lib/gate-decision-coverage-verify.cjs

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * `check decision-coverage-verify` — advisory verify-phase decision-coverage gate, as a gate
+ * module (#5139, epic #5056, ADR-5057 §4 first bullet): it returns a `GateResult`; the command
+ * router formats it. Always `blocking:false` — a soft warning, never a verification failure.
+ * Imports no io module and performs no direct console/stdout/stderr write (ESLint-enforced).
+ *
+ * Argv after the verb: `<phase-dir> <context-path>` (positional; no `--context` flag here).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateDecisionCoverageVerify = evaluateDecisionCoverageVerify;
+const gate_verdict_cjs_1 = require("./gate-verdict.cjs");
+const gate_phase_context_cjs_1 = require("./gate-phase-context.cjs");
+const gate_config_cjs_1 = require("./gate-config.cjs");
+const decision_coverage_support_cjs_1 = require("./decision-coverage-support.cjs");
+/**
+ * The verdict when CONTEXT.md or a shipped artifact could not be read. The gate stays advisory
+ * (`block: false`, `blocking: false`); the outcome is `unreadable`, so the exit status is
+ * UNAVAILABLE and no decision is reported honored or not honored from content never seen (#5170).
+ */
+function unreadableVerify(readError) {
+    return (0, gate_verdict_cjs_1.gateUnreadable)(false, {
+        skipped: false,
+        blocking: false,
+        reason: 'unreadable evidence',
+        total: null,
+        honored: null,
+        not_honored: [],
+        readError,
+        message: `Decision coverage verify (warning): could not read its evidence (${readError}); no decision was checked.`,
+    });
+}
+/** The verdict when there is no CONTEXT.md: the legitimate green skip (authoritatively `none`, never `unreadable`). */
+function contextMissingSkip() {
+    return (0, gate_verdict_cjs_1.gateVerdict)('skip', false, { skipped: true, blocking: false, reason: 'CONTEXT.md missing', total: 0, honored: 0, not_honored: [], message: 'No CONTEXT.md - nothing to check.' });
+}
+function evaluateDecisionCoverageVerify(input) {
+    const { projectDir, args } = input;
+    let phaseDir = '';
+    if (args[0]) {
+        const resolved = (0, gate_phase_context_cjs_1.resolveContainedPath)(args[0], projectDir);
+        if ((0, gate_verdict_cjs_1.isGateUsageFailure)(resolved))
+            return resolved;
+        phaseDir = resolved;
+    }
+    let contextPath = '';
+    if (args[1]) {
+        const resolved = (0, gate_phase_context_cjs_1.resolveContainedPath)(args[1], projectDir);
+        if ((0, gate_verdict_cjs_1.isGateUsageFailure)(resolved))
+            return resolved;
+        contextPath = resolved;
+    }
+    if (!(0, gate_config_cjs_1.isDecisionCoverageGateEnabled)(projectDir)) {
+        return (0, gate_verdict_cjs_1.gateVerdict)('skip', false, { skipped: true, blocking: false, reason: 'workflow.context_coverage_gate is false', total: 0, honored: 0, not_honored: [], message: 'Decision coverage gate disabled by config.' });
+    }
+    // No context argument is the only up-front skip: an absent file is `none` and an unreadable one is
+    // `unreadable` below, from the one read that loads the decisions (`fs.existsSync` answered `false`
+    // for an EACCES on a parent, skipping a CONTEXT.md the gate never saw — #5170).
+    if (!contextPath) {
+        return contextMissingSkip();
+    }
+    const extracted = (0, decision_coverage_support_cjs_1.loadDecisionExtraction)(contextPath);
+    if (extracted.kind === 'unreadable')
+        return unreadableVerify(`${extracted.span ?? contextPath}: ${extracted.reason}`);
+    if (extracted.kind === 'none') {
+        return contextMissingSkip();
+    }
+    const { trackable: decisions, outcome: decisionOutcome } = extracted.value;
+    // Mirror could-not-parse surface for verify (non-blocking advisory WARN).
+    // Fire independent of decisions.length — a parse-miss on any bullet must surface,
+    // even when some decisions were partially extracted (#1365 fix-parity with plan gate).
+    if (decisionOutcome === 'could-not-parse') {
+        const partialParse = decisions.length > 0;
+        return (0, gate_verdict_cjs_1.gateVerdict)('advisory', false, {
+            skipped: false,
+            blocking: false,
+            reason: 'could-not-parse',
+            total: decisions.length,
+            honored: 0,
+            not_honored: [],
+            message: partialParse
+                ? 'Decision coverage verify (warning): decisions could not be fully parsed — one or more ' +
+                    '`- **D-NN ...**` bullets appear malformed (missing `:` or ` — ` separator, or a phase ' +
+                    'prefix that is not a digit run). Fix the bullet format in the CONTEXT.md decisions block.'
+                : 'Decision coverage verify (warning): could not parse decisions — possible format mismatch. ' +
+                    'Check the formatting of the CONTEXT.md decisions block (accepted forms: `- **D-NN:** text`, ' +
+                    '`- **D4-NN:** text` (phase-prefixed), `- **D-NN — title** body`).',
+        });
+    }
+    if (decisions.length === 0) {
+        return (0, gate_verdict_cjs_1.gateVerdict)('skip', false, { skipped: true, blocking: false, reason: 'no trackable decisions', total: 0, honored: 0, not_honored: [], message: 'No trackable decisions in CONTEXT.md.' });
+    }
+    // Every file the haystack is built from is typed evidence (#5170): one that exists but cannot be
+    // read is `unreadable`, never an empty slice of the haystack that makes a decision look unhonored.
+    const planContents = (0, decision_coverage_support_cjs_1.loadPlanContents)(phaseDir);
+    if (planContents.kind === 'unreadable')
+        return unreadableVerify(`${planContents.span ?? phaseDir}: ${planContents.reason}`);
+    const summaryParts = (0, decision_coverage_support_cjs_1.loadSummaryContents)(phaseDir);
+    if (summaryParts.kind === 'unreadable')
+        return unreadableVerify(`${summaryParts.span ?? phaseDir}: ${summaryParts.reason}`);
+    const modifiedFiles = (0, decision_coverage_support_cjs_1.readModifiedFilesContent)(projectDir, summaryParts.value);
+    if (modifiedFiles.kind === 'unreadable')
+        return unreadableVerify(`${modifiedFiles.span ?? 'files_modified'}: ${modifiedFiles.reason}`);
+    const haystack = [
+        planContents.value.join('\n\n'),
+        summaryParts.value.join('\n\n'),
+        modifiedFiles.value,
+        (0, decision_coverage_support_cjs_1.phaseCommitMessages)(projectDir, phaseDir),
+    ].join('\n\n');
+    const notHonored = [];
+    let honored = 0;
+    for (const decision of decisions) {
+        if ((0, decision_coverage_support_cjs_1.decisionMentioned)(haystack, decision))
+            honored++;
+        else
+            notHonored.push({ id: decision.id, text: decision.text, category: decision.category });
+    }
+    return (0, gate_verdict_cjs_1.gateVerdict)(notHonored.length === 0 ? 'pass' : 'advisory', false, {
+        skipped: false,
+        blocking: false,
+        total: decisions.length,
+        honored,
+        not_honored: notHonored,
+        message: (0, decision_coverage_support_cjs_1.buildVerifyMessage)(notHonored),
+    });
+}

package/gsd-core/bin/lib/gate-evaluation-scope.cjs

@@ -0,0 +1,555 @@
+"use strict";
+/**
+ * Evaluation-scope resolver (#5164, epic #5056, ADR-5057 §4 second bullet): the ONE answer to
+ * "which commits and which file set does this gate or workflow step evaluate for this plan,
+ * phase or quick task".
+ *
+ * Before this module every consumer derived its own answer — `HEAD~1..HEAD`, `DIFF_BASE..HEAD`,
+ * `git log --all --grep` — and all of them disagreed with each other and with the work they
+ * meant to scope. Three constraints from the design lock hold here:
+ *
+ *   1. The scope is the UNION of each commit's own file set, never a range. A range keeps every
+ *      interleaved non-phase commit in its window (measured on a 9,676-commit repo: the range
+ *      held 23, 194 and 602 files where the union of the phase's commits held 9, 42 and 69).
+ *   2. Only commits reachable from the evaluated ref count (`git log --all` is gone). A commit
+ *      that lives only on another branch is NAMED in `unreachable` and contributes nothing.
+ *   3. An empty union never becomes an empty scope that reviews nothing and reports success. It
+ *      degrades to wider evidence (the phase-directory range) and SAYS so (`status: 'degraded'`,
+ *      `reason`). What the union drops is named by path, not counted: `outsideUnion` (range
+ *      minus union) and `missingOnDisk` (scoped paths that no longer exist).
+ *
+ * A phase's commits are the `## Task Commits` rows of its SUMMARY files (path-anchored: no commit
+ * message grep, the class re-fixed in #2989/#3191/#3503/#3995). A plan's commits are the
+ * reachable commits whose SUBJECT is `<type>(<phase>-<plan>):`, anchored and zero-padding
+ * tolerant (#4003). The row parse is a port of the byte-parity model from the closed PR #4127.
+ *
+ * Every git call goes through the `execGit` seam, which bounds each subprocess (its default
+ * budget); a timeout or a missing git is `unresolvable`, never a throw and never an empty scope.
+ *
+ * A gate module: imports no io module and writes nothing; `evaluateEvaluationScope` returns a
+ * `GateResult` the command router formats (`check evaluation-scope`).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_COMMITS_CEILING = exports.SCOPE_EXCLUSION_PATHSPECS = void 0;
+exports.extractTaskCommitRefs = extractTaskCommitRefs;
+exports.planSubjectPattern = planSubjectPattern;
+exports.isSafeRefArgument = isSafeRefArgument;
+exports.isSafeDateArgument = isSafeDateArgument;
+exports.resolveEvaluationScope = resolveEvaluationScope;
+exports.evaluateEvaluationScope = evaluateEvaluationScope;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const gate_verdict_cjs_1 = require("./gate-verdict.cjs");
+const gate_phase_context_cjs_1 = require("./gate-phase-context.cjs");
+const pattern_cjs_1 = require("./pattern.cjs");
+const gate_evidence_cjs_1 = require("./gate-evidence.cjs");
+// ─── Constants ────────────────────────────────────────────────────────────────
+/** Paths that are never part of a code-review or UI scope (planning artifacts, lockfiles). */
+exports.SCOPE_EXCLUSION_PATHSPECS = Object.freeze([
+    ':!.planning/', ':!ROADMAP.md', ':!STATE.md',
+    ':!*-SUMMARY.md', ':!*-VERIFICATION.md', ':!*-PLAN.md',
+    ':!package-lock.json', ':!yarn.lock', ':!Gemfile.lock', ':!poetry.lock',
+]);
+/** 41 chars per sha; 400 of them stay well under the 28K Windows-safe argv chunk. */
+const SHA_CHUNK = 400;
+const DEFAULT_MAX_COMMITS = 200;
+const MAX_PATHSPECS = 20;
+// ─── SUMMARY `## Task Commits` extraction (port of the #4127 model) ───────────
+const TASK_COMMITS_HEADING = /^## Task Commits[ \t\r]*$/;
+const NEXT_HEADING = /^## /;
+const TASK_ROW_PREFIX = /^[ \t]*(?:[0-9]+\.|[-*])?[ \t]*\*\*Task[ \t]+[0-9]+:/;
+const HEX_TOKEN = /`[0-9a-f]{7,40}`/g;
+/**
+ * The commit ids a SUMMARY names, in document order, duplicates included. Section-scoped (every
+ * `## Task Commits` section), row-scoped (an optional list marker, the `**Task N:` label closed by
+ * its FIRST `**`) and backtick-anchored: only backticked lowercase hex AFTER that closing bold
+ * counts, so a sha quoted in prose or on the `**Plan metadata:**` line is not a task commit.
+ */
+function extractTaskCommitRefs(text) {
+    const refs = [];
+    let inside = false;
+    for (const line of text.split('\n')) {
+        if (TASK_COMMITS_HEADING.test(line)) {
+            inside = true;
+            continue;
+        }
+        if (NEXT_HEADING.test(line)) {
+            inside = false;
+            continue;
+        }
+        if (!inside)
+            continue;
+        const row = TASK_ROW_PREFIX.exec(line);
+        if (!row)
+            continue;
+        const rest = line.slice(row[0].length);
+        const close = rest.indexOf('**');
+        if (close === -1)
+            continue;
+        for (const token of rest.slice(close + 2).match(HEX_TOKEN) ?? [])
+            refs.push(token.slice(1, -1));
+    }
+    return refs;
+}
+// ─── Plan-id → anchored subject pattern ───────────────────────────────────────
+/**
+ * Tolerate zero padding in the leading integer of a phase or plan segment (#4003, #4619, #4748);
+ * everything after the integer (`A`, `.1.2`) is matched literally.
+ */
+function paddedPattern(value) {
+    const m = /^(\d+)(.*)$/.exec(value);
+    if (!m)
+        return (0, pattern_cjs_1.escapeEre)(value);
+    const intPart = (m[1] ?? '').replace(/^0+(?=\d)/, '');
+    return `0*${(0, pattern_cjs_1.escapeEre)(intPart)}${(0, pattern_cjs_1.escapeEre)(m[2] ?? '')}`;
+}
+/**
+ * The anchored subject pattern for a plan id, or null when `planId` is empty, over-long or carries a
+ * control / whitespace character.
+ *
+ * A `<phase>-<plan>` id (`03-01`) is zero-padding tolerant: `feat(03-01):`, `test(3-1):` and
+ * `fix(03-01)!:` match, `feat(03-010):` does not. Any other id (a plan FILE NAME that does not follow
+ * the numbering) is matched LITERALLY — every ERE metacharacter escaped — so `x.*` or `a[b]` can only
+ * match a commit that names that exact id, and never widens the pattern.
+ */
+function planSubjectPattern(planId) {
+    if (planId.length === 0 || planId.length > 200 || /[\s\x00-\x1f\x7f]/.test(planId))
+        return null;
+    const dash = planId.indexOf('-');
+    const phasePart = dash > 0 ? planId.slice(0, dash) : '';
+    const planPart = dash > 0 ? planId.slice(dash + 1) : '';
+    if (/^[0-9A-Za-z.]+$/.test(phasePart) && /^[0-9A-Za-z.]+$/.test(planPart)) {
+        return `^[a-z]+\\(${paddedPattern(phasePart)}-${paddedPattern(planPart)}\\)!?:`;
+    }
+    return `^[a-z]+\\(${(0, pattern_cjs_1.escapeEre)(planId)}\\)!?:`;
+}
+// ─── Git plumbing ─────────────────────────────────────────────────────────────
+class ScopeUnreadable extends Error {
+    reason;
+    /** git's exit status when the failure was a plain non-zero exit (not a timeout or a missing git). */
+    exitCode;
+    constructor(reason, exitCode = null) {
+        super(reason);
+        this.reason = reason;
+        this.exitCode = exitCode;
+    }
+}
+function makeGit(projectDir, runner) {
+    return (args, cwd = projectDir) => {
+        const result = runner(args, { cwd });
+        if (result.timedOut)
+            throw new ScopeUnreadable('git-timeout');
+        if (result.exitCode === 127)
+            throw new ScopeUnreadable('git-unavailable');
+        if (result.exitCode !== 0)
+            throw new ScopeUnreadable(`git-failed:${args[0] ?? ''}`, result.exitCode);
+        return result.stdout;
+    };
+}
+/**
+ * Run a git question whose exit status 1 is a legitimate "no" (`merge-base --is-ancestor`,
+ * `rev-parse --verify --quiet`). Exit 1 returns `null`; every other failure — a timeout, a missing
+ * git, a bad object (exit 128) — still rethrows, so a hung or broken git is `unresolvable`, never a
+ * silent "no".
+ */
+function gitOrNo(git, args, cwd) {
+    try {
+        return git(args, cwd);
+    }
+    catch (error) {
+        if (error instanceof ScopeUnreadable && error.exitCode === 1)
+            return null;
+        throw error;
+    }
+}
+function splitNul(output) {
+    return output.split('\0').filter((entry) => entry.length > 0);
+}
+function chunk(items, size) {
+    const out = [];
+    for (let i = 0; i < items.length; i += size)
+        out.push(items.slice(i, i + size));
+    return out;
+}
+function uniqueSorted(items) {
+    return [...new Set(items)].sort();
+}
+/** True when `candidate` cannot be read as a git option and carries no whitespace or control byte. */
+function isSafeRefArgument(candidate) {
+    return candidate.length > 0 && candidate.length <= 256 && !candidate.startsWith('-') && !/[\s\x00-\x1f\x7f]/.test(candidate);
+}
+/** A git approxidate: words, digits and `- : . ,` only, so it can never read as an option or a pathspec. */
+function isSafeDateArgument(candidate) {
+    return /^[A-Za-z0-9][A-Za-z0-9 .,:+-]{0,63}$/.test(candidate);
+}
+function isAncestor(git, sha, of) {
+    return gitOrNo(git, ['merge-base', '--is-ancestor', sha, of]) !== null;
+}
+// ─── The resolver ─────────────────────────────────────────────────────────────
+function emptyScope(unit) {
+    return {
+        unit, status: 'resolved', source: 'none', reason: null, commits: [],
+        changedFiles: [], files: [], missingOnDisk: [], outsideUnion: [], unreachable: [], rangeBase: null,
+    };
+}
+function resolveEvaluationScope(projectDir, unit, options = {}) {
+    const scope = emptyScope(unit);
+    const git = makeGit(projectDir, options.execGit ?? shell_command_projection_cjs_1.execGit);
+    const ref = options.ref ?? 'HEAD';
+    try {
+        if (!isSafeRefArgument(ref))
+            throw new ScopeUnreadable('unsafe-ref');
+        if (options.since !== undefined && !isSafeRefArgument(options.since))
+            throw new ScopeUnreadable('unsafe-since');
+        git(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]);
+        const repoRoot = git(['rev-parse', '--show-toplevel']);
+        if (unit.kind === 'phase')
+            resolvePhase(projectDir, unit, scope, git, ref, options, repoRoot);
+        else
+            resolveBySubject(unit, scope, git, ref, options, repoRoot);
+        return scope;
+    }
+    catch (error) {
+        const reason = error instanceof ScopeUnreadable ? error.reason : 'resolver-error';
+        return { ...emptyScope(unit), status: 'unresolvable', reason };
+    }
+}
+/** A commit's own file set. `--first-parent`: a merge commit contributes its diff against parent 1. */
+function commitFiles(git, sha) {
+    const out = git(['-c', 'core.quotepath=off', 'show', '--first-parent', '--pretty=format:', '--name-only', '-z', sha, '--', '.', ...exports.SCOPE_EXCLUSION_PATHSPECS]);
+    return splitNul(out);
+}
+function rangeFiles(git, base, tip) {
+    const out = git(['-c', 'core.quotepath=off', 'diff', '--name-only', '-z', `${base}..${tip}`, '--', '.', ...exports.SCOPE_EXCLUSION_PATHSPECS]);
+    return splitNul(out);
+}
+function finalizeFiles(scope, repoRoot, changed) {
+    scope.changedFiles = uniqueSorted(changed);
+    const existing = [];
+    const missing = [];
+    for (const file of scope.changedFiles) {
+        (node_fs_1.default.existsSync(node_path_1.default.join(repoRoot, file)) ? existing : missing).push(file);
+    }
+    scope.files = existing;
+    scope.missingOnDisk = missing;
+}
+function logFormat(withBody) {
+    return withBody ? '--format=%H%x1f%s%x1f%b%x1e' : '--format=%H%x1f%s%x1e';
+}
+function parseLog(out, withBody) {
+    const commits = [];
+    for (const record of out.split('\x1e')) {
+        const trimmed = record.replace(/^\n+/, '');
+        if (!trimmed)
+            continue;
+        const [sha, subject, body] = trimmed.split('\x1f');
+        if (!sha || !/^[0-9a-f]{40}$/.test(sha))
+            continue;
+        const commit = { sha, subject: subject ?? '' };
+        if (withBody)
+            commit.body = (body ?? '').trim();
+        commits.push(commit);
+    }
+    return commits;
+}
+function subjectsFor(git, shas, withBody, chunkSize) {
+    const out = [];
+    for (const group of chunk(shas, chunkSize)) {
+        out.push(...parseLog(git(['log', '--no-walk=unsorted', logFormat(withBody), ...group]), withBody));
+    }
+    return out;
+}
+/**
+ * The tip of `shas`: topological order lists a descendant before its ancestors, so the first
+ * commit of a walk started at all of them is one no other listed commit descends from. (Commit
+ * DATES are not used — commits made within one second tie, and a tie picks an arbitrary tip.)
+ */
+function newestOf(git, shas, chunkSize) {
+    // More shas than fit one argv chunk are reduced chunk by chunk: the chunks' tips are themselves a
+    // (shorter) list, until one chunk holds them all. Nothing is silently dropped.
+    if (shas.length > chunkSize) {
+        const tips = chunk(shas, chunkSize).map((group) => newestOf(git, group, chunkSize));
+        return newestOf(git, tips, chunkSize);
+    }
+    const tip = git(['rev-list', '--topo-order', '-n', '1', ...shas]).split('\n').filter(Boolean)[0];
+    return tip ?? shas[0] ?? 'HEAD';
+}
+/** One clamp for every commit cap, so the CLI limit and the resolver's ceiling cannot diverge. */
+exports.MAX_COMMITS_CEILING = 1000;
+function clampMaxCommits(requested) {
+    return Math.max(1, Math.min(requested ?? DEFAULT_MAX_COMMITS, exports.MAX_COMMITS_CEILING));
+}
+/** git's empty tree (SHA-1 repositories): the base a range needs to include a root commit's own files. */
+const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+/**
+ * The phase-start anchor on `ref`: the parent of the commit that first added anything under the
+ * phase dir. A phase directory that arrived with the repository's root commit has no parent, so the
+ * anchor is the empty tree — `<empty>..<ref>` then includes the root commit's own files.
+ */
+function phaseRangeBase(git, phaseDir, ref) {
+    const first = git(['log', ref, '--format=%H', '--diff-filter=A', '--', '.'], phaseDir)
+        .split('\n').filter(Boolean).pop();
+    if (!first)
+        return null;
+    return gitOrNo(git, ['rev-parse', '--verify', '--quiet', `${first}^`]) ?? EMPTY_TREE;
+}
+function resolvePhase(projectDir, unit, scope, git, ref, options, repoRoot) {
+    let phaseDir = unit.phaseDir ?? '';
+    if (unit.phaseDir === undefined) {
+        const located = (0, gate_phase_context_cjs_1.resolvePhaseDir)(projectDir, unit.phase);
+        if (located.kind === 'unreadable')
+            throw new ScopeUnreadable(`phase-dir-lookup-failed:${located.reason}`);
+        if (located.kind === 'found')
+            phaseDir = located.value;
+    }
+    if (!phaseDir)
+        throw new ScopeUnreadable('phase-dir-not-found');
+    const refs = [];
+    let summaryCount = 0;
+    // The canonical LIVE summary set (root + nested, superseded excluded) from its single owner. A scan
+    // that did not see every summary (an existing nested plans/ that could not be read) is "could not
+    // look": a short summary set would narrow the phase's commits and report success (#5170).
+    const planScan = (0, gate_evidence_cjs_1.readPlanScanEvidence)(phaseDir);
+    if (planScan.kind === 'unreadable')
+        throw new ScopeUnreadable('phase-dir-unreadable');
+    const entries = [...planScan.value.summaryFiles].sort();
+    for (const name of entries) {
+        try {
+            refs.push(...extractTaskCommitRefs(node_fs_1.default.readFileSync(node_path_1.default.join(phaseDir, name), 'utf-8')));
+            summaryCount += 1;
+        }
+        catch {
+            throw new ScopeUnreadable(`summary-unreadable:${name}`);
+        }
+    }
+    // Resolve each listed id to a full sha reachable from the ref (and, for wave scoping, newer than `since`).
+    const shas = [];
+    const unreachable = [];
+    let sinceDropped = 0;
+    for (const id of [...new Set(refs)]) {
+        // Exit 1 = no object answers to the id (rebased away); exit 128 = an ambiguous short id. Both
+        // are named below, per id, and neither poisons the phase. A timeout still rethrows.
+        let full = '';
+        try {
+            full = gitOrNo(git, ['rev-parse', '--verify', '--quiet', `${id}^{commit}`]) ?? '';
+        }
+        catch (error) {
+            if (!(error instanceof ScopeUnreadable && error.exitCode === 128))
+                throw error;
+        }
+        if (!full || !isAncestor(git, full, ref)) {
+            unreachable.push(id);
+            continue;
+        }
+        if (options.since !== undefined && isAncestor(git, full, options.since)) {
+            sinceDropped += 1;
+            continue;
+        }
+        shas.push(full);
+    }
+    scope.unreachable = unreachable.sort();
+    scope.rangeBase = options.since ?? phaseRangeBase(git, phaseDir, ref);
+    const union = new Set();
+    const commits = [];
+    const withFiles = options.includeFiles ?? true;
+    // At least 2: a chunk of one never shrinks the list `newestOf` reduces.
+    const chunkSize = Math.max(2, options.shaChunk ?? SHA_CHUNK);
+    for (const meta of subjectsFor(git, [...new Set(shas)], options.includeBody === true, chunkSize)) {
+        const files = commitFiles(git, meta.sha);
+        for (const file of files)
+            union.add(file);
+        commits.push(withFiles ? { ...meta, files: [...files].sort() } : meta);
+    }
+    if (union.size > 0) {
+        scope.source = 'task-commits';
+        scope.commits = commits;
+        finalizeFiles(scope, repoRoot, union);
+        if (scope.rangeBase) {
+            const window = rangeFiles(git, scope.rangeBase, newestOf(git, commits.map((c) => c.sha), chunkSize));
+            scope.outsideUnion = uniqueSorted(window.filter((f) => !union.has(f)));
+        }
+        return;
+    }
+    // Empty union: the planning-only phase, a phase with no SUMMARY, or one whose ids are all gone.
+    const reason = summaryCount === 0 ? 'no-summary'
+        : refs.length === 0 ? 'no-task-commit-rows'
+            : shas.length === 0 ? (sinceDropped > 0 ? 'no-task-commits-since' : 'no-reachable-task-commits')
+                : 'empty-after-exclusions';
+    if (!scope.rangeBase)
+        throw new ScopeUnreadable(`${reason}:no-phase-start-anchor`);
+    scope.status = 'degraded';
+    scope.reason = reason;
+    scope.source = 'phase-range';
+    const max = clampMaxCommits(options.maxCommits);
+    scope.commits = parseLog(git(['log', `${scope.rangeBase}..${ref}`, logFormat(options.includeBody === true), '-n', String(max)]), options.includeBody === true);
+    finalizeFiles(scope, repoRoot, rangeFiles(git, scope.rangeBase, ref));
+}
+function resolveBySubject(unit, scope, git, ref, options, repoRoot) {
+    const withBody = options.includeBody === true;
+    // Refuse rather than truncate: a silently dropped positive pathspec narrows the match.
+    const pathspecs = options.pathspecs ?? [];
+    if (pathspecs.length > MAX_PATHSPECS)
+        throw new ScopeUnreadable('too-many-pathspecs');
+    const max = clampMaxCommits(options.maxCommits);
+    let range = ref;
+    if (options.milestoneBound === true) {
+        let tag = '';
+        try {
+            tag = git(['describe', '--tags', '--abbrev=0', ref]);
+        }
+        catch (error) {
+            // Exit 128 = no reachable tag → unbounded; a timeout or a missing git still rethrows.
+            if (!(error instanceof ScopeUnreadable && error.exitCode === 128))
+                throw error;
+        }
+        if (tag)
+            range = `${tag}..${ref}`;
+    }
+    const grepArgs = [];
+    let anchored = null;
+    if (unit.kind === 'plan') {
+        const pattern = planSubjectPattern(unit.planId);
+        if (pattern === null)
+            throw new ScopeUnreadable('invalid-plan-id');
+        grepArgs.push('--extended-regexp', `--grep=${pattern}`);
+        anchored = new RegExp(pattern);
+        scope.source = 'plan-subjects';
+    }
+    else {
+        if (!isSafeRefArgument(unit.id))
+            throw new ScopeUnreadable('invalid-quick-id');
+        grepArgs.push('--fixed-strings', `--grep=${unit.id}`);
+        scope.source = 'quick-subjects';
+    }
+    const sinceArgs = [];
+    if (options.committedSince !== undefined) {
+        if (!isSafeDateArgument(options.committedSince))
+            throw new ScopeUnreadable('unsafe-committed-since');
+        sinceArgs.push(`--since=${options.committedSince}`);
+    }
+    const out = git(['log', range, logFormat(withBody), '-n', String(max * 2), ...sinceArgs, ...grepArgs, ...(pathspecs.length > 0 ? ['--', ...pathspecs] : [])]);
+    // `--grep` matches ANY message line; a plan lookup is subject-anchored, so filter on the subject.
+    let commits = parseLog(out, withBody).filter((c) => anchored === null || anchored.test(c.subject)).slice(0, max);
+    const since = options.since;
+    if (since !== undefined)
+        commits = commits.filter((c) => !isAncestor(git, c.sha, since));
+    if (options.commitsOnly === true) {
+        scope.commits = commits;
+        if (commits.length === 0)
+            scope.reason = 'no-matching-commits';
+        return;
+    }
+    const withFiles = options.includeFiles ?? false;
+    const union = new Set();
+    const result = [];
+    for (const meta of commits) {
+        const files = commitFiles(git, meta.sha);
+        for (const file of files)
+            union.add(file);
+        result.push(withFiles ? { ...meta, files: [...files].sort() } : meta);
+    }
+    scope.commits = result;
+    finalizeFiles(scope, repoRoot, union);
+    // Found nothing: a truthful "none" (status stays `resolved` — git was read), said out loud so a
+    // caller can tell "no such commits" from "an empty scope that was never computed". Commits whose
+    // every path is excluded (planning-only) are an empty scope too, and say so.
+    if (result.length === 0)
+        scope.reason = 'no-matching-commits';
+    else if (scope.changedFiles.length === 0)
+        scope.reason = 'empty-after-exclusions';
+}
+// ─── The `check evaluation-scope` verb ────────────────────────────────────────
+const VALUE_FLAGS = new Set(['--phase', '--phase-dir', '--plan', '--quick', '--since', '--ref', '--pathspec', '--committed-since', '--max-commits']);
+const BOOLEAN_FLAGS = new Set(['--milestone-bound', '--include-body', '--include-files', '--commits-only']);
+function parseScopeArgs(args) {
+    const values = new Map();
+    const flags = new Set();
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i] ?? '';
+        if (BOOLEAN_FLAGS.has(arg)) {
+            flags.add(arg);
+            continue;
+        }
+        if (!VALUE_FLAGS.has(arg))
+            return `unknown argument: ${arg}`;
+        const value = args[i + 1];
+        if (value === undefined)
+            return `${arg} requires a value`;
+        i += 1;
+        values.set(arg, [...(values.get(arg) ?? []), value]);
+    }
+    const one = (flag) => values.get(flag)?.[0];
+    const phase = one('--phase');
+    const phaseDir = one('--phase-dir');
+    const plan = one('--plan');
+    const quick = one('--quick');
+    const given = [phase, phaseDir, plan, quick].filter((v) => v !== undefined).length;
+    if (given !== 1)
+        return 'exactly one of --phase <phase>, --phase-dir <dir>, --plan <phase>-<plan> or --quick <id> is required';
+    let unit;
+    if (quick !== undefined)
+        unit = { kind: 'quick', id: quick };
+    else if (plan !== undefined)
+        unit = { kind: 'plan', planId: plan };
+    else if (phaseDir !== undefined)
+        unit = { kind: 'phase', phase: '', phaseDir };
+    else
+        unit = { kind: 'phase', phase: phase ?? '' };
+    const options = {};
+    const ref = one('--ref');
+    const since = one('--since');
+    const pathspecs = values.get('--pathspec');
+    if (ref !== undefined)
+        options.ref = ref;
+    if (since !== undefined)
+        options.since = since;
+    if (pathspecs !== undefined)
+        options.pathspecs = pathspecs;
+    const committedSince = one('--committed-since');
+    if (committedSince !== undefined)
+        options.committedSince = committedSince;
+    const maxCommits = one('--max-commits');
+    if (maxCommits !== undefined) {
+        if (!/^[1-9][0-9]{0,3}$/.test(maxCommits) || Number(maxCommits) > exports.MAX_COMMITS_CEILING) {
+            return `--max-commits must be an integer from 1 to ${exports.MAX_COMMITS_CEILING}, got: ${maxCommits}`;
+        }
+        options.maxCommits = Number(maxCommits);
+    }
+    if (flags.has('--milestone-bound'))
+        options.milestoneBound = true;
+    if (flags.has('--include-body'))
+        options.includeBody = true;
+    if (flags.has('--include-files'))
+        options.includeFiles = true;
+    if (flags.has('--commits-only'))
+        options.commitsOnly = true;
+    return { unit, options };
+}
+/** `check evaluation-scope` — argv after the verb. A resolver, not a policy: it never blocks. */
+function evaluateEvaluationScope(input) {
+    const parsed = parseScopeArgs(input.args);
+    if (typeof parsed === 'string') {
+        return (0, gate_verdict_cjs_1.gateUsageFailure)(gate_verdict_cjs_1.GATE_FAILURE_CODE.USAGE, `check evaluation-scope: ${parsed}`);
+    }
+    const options = input.execGit ? { ...parsed.options, execGit: input.execGit } : parsed.options;
+    let unit = parsed.unit;
+    if (unit.kind === 'phase' && unit.phaseDir !== undefined) {
+        // `--phase-dir` is caller-supplied: it must stay inside the project (realpath containment).
+        const contained = (0, gate_phase_context_cjs_1.resolveContainedPath)(unit.phaseDir, input.projectDir);
+        if ((0, gate_verdict_cjs_1.isGateUsageFailure)(contained))
+            return contained;
+        unit = { kind: 'phase', phase: '', phaseDir: contained };
+    }
+    const scope = resolveEvaluationScope(input.projectDir, unit, options);
+    // An unresolvable scope is "could not look" (a missing git, a timeout): outcome `unreadable`, exit
+    // UNAVAILABLE, never a pass-shaped exit 0 (#5170). The payload is unchanged.
+    if (scope.status === 'unresolvable')
+        return (0, gate_verdict_cjs_1.gateUnreadable)(false, { ...scope });
+    // `pass` only for a scope with nothing to explain; an empty-but-resolved scope (it carries a reason) is advisory.
+    const outcome = scope.status === 'degraded' || scope.reason !== null ? 'advisory' : 'pass';
+    return (0, gate_verdict_cjs_1.gateVerdict)(outcome, false, { ...scope });
+}