@cleocode/core 2026.9.20 → 2026.9.22

package/dist/release/ci-evidence.js

@@ -0,0 +1,668 @@
+/**
+ * `ci:<pr>` evidence — required CI green on a merged PR's MERGE COMMIT.
+ *
+ * Owner decision D11149: when every required check completed with `success`
+ * on the commit a PR actually merged as, that satisfies `testsPassed` and
+ * `qaPassed` for the task the PR closes. It replaces the post-merge local
+ * full-suite rerun, which was the single largest override driver. Opt-in via
+ * `evidence.ciSatisfies: true` in `.cleo/project-context.json`.
+ *
+ * Verified the way `pr:` provenance is:
+ *
+ *  - the PR itself goes through {@link resolvePrEvidenceAtom} (merged, a real
+ *    merge-commit identity), so a `ci:` atom can never outrun `pr:`;
+ *  - the required-check list comes from the SAME resolver `pr:` uses
+ *    (env → `release.prRequiredWorkflows` → branch protection), and an
+ *    undetermined list refuses rather than accepting vacuously;
+ *  - each required name is judged on the merge commit's own check runs and
+ *    workflow runs (GitHub REST, by SHA). A run whose `head_sha` is anything
+ *    else — the PR head included — never counts, and a required check found
+ *    only there is named as such.
+ *
+ * Pending, failed, cancelled, skipped and missing required checks are each
+ * refused with the check's name and state.
+ *
+ * @task T12634
+ */
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isGitWorkTree } from '../git/work-tree.js';
+import { checkPrTaskLinkage, isDocumentArtifact, linkedPrChange, } from '../tasks/evidence.js';
+import { ghQueryTimeoutMs, isGhCliAvailable } from './github-pr.js';
+import { describeRequiredWorkflowsSource, readRequiredCheckPins, resolvePrEvidenceAtom, resolveRequiredWorkflowsDetailed, } from './pr-evidence.js';
+/** Parsed `.cleo/project-context.json` of the store root, or null. */
+function readProjectContextFile(projectRoot) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(projectRoot, '.cleo', 'project-context.json'), 'utf-8'));
+        return typeof parsed === 'object' && parsed !== null
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether the project opted in to merge-commit CI as test/QA evidence
+ * (`evidence.ciSatisfies === true`; anything else, including a missing file,
+ * is `false`).
+ *
+ * @param projectRoot - CLEO store root.
+ * @returns True only for an explicit boolean `true`.
+ * @task T12634
+ */
+export function readCiSatisfies(projectRoot) {
+    const evidence = readProjectContextFile(projectRoot)?.evidence;
+    return evidence?.ciSatisfies === true;
+}
+/**
+ * The checks that attest each gate (`evidence.ciChecks`, T12634).
+ *
+ * @param projectRoot - CLEO store root.
+ * @returns `tests` → testsPassed, `qa` → qaPassed; a missing list is absent.
+ * @task T12634
+ */
+export function readCiChecks(projectRoot) {
+    const raw = readProjectContextFile(projectRoot)
+        ?.evidence?.ciChecks;
+    if (typeof raw !== 'object' || raw === null)
+        return {};
+    const list = (v) => Array.isArray(v) && v.every((x) => typeof x === 'string' && x.trim() !== '')
+        ? v.map((x) => x.trim())
+        : undefined;
+    const { tests, qa, jobs } = raw;
+    const jobLists = typeof jobs === 'object' && jobs !== null
+        ? jobs
+        : undefined;
+    const jobTests = list(jobLists?.tests);
+    const jobQa = list(jobLists?.qa);
+    return {
+        ...(list(tests) ? { tests: list(tests) } : {}),
+        ...(list(qa) ? { qa: list(qa) } : {}),
+        ...(jobTests || jobQa
+            ? { jobs: { ...(jobTests ? { tests: jobTests } : {}), ...(jobQa ? { qa: jobQa } : {}) } }
+            : {}),
+    };
+}
+/**
+ * Top-level directories whose files are code for the `ci:` skip decision even
+ * when they are Markdown or text: a `.md` under `packages/**` can be a runtime
+ * template (CLEO-INJECTION.md is injected into every agent), and the CI `code`
+ * path filter plus the scripts, crates and workflow filters cover these roots.
+ */
+const CI_CODE_ROOTS = ['packages/', 'crates/', 'scripts/', '.github/'];
+/**
+ * Stricter than `pr:`'s {@link isDocumentArtifact}: a documentation artifact
+ * that lives outside every code root. Only a diff made entirely of these may
+ * leave its test and typecheck jobs honestly skipped.
+ *
+ * @param path - Repo-relative changed path.
+ * @returns True when the path cannot affect code, tests or CI.
+ * @task T12634
+ */
+export function isCiDocumentPath(path) {
+    return isDocumentArtifact(path) && !CI_CODE_ROOTS.some((root) => path.startsWith(root));
+}
+/** `*`-glob to an anchored regular expression. */
+function globToRegExp(glob) {
+    return new RegExp(`^${glob
+        .split('*')
+        .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
+        .join('.*')}$`);
+}
+/**
+ * Judge job globs on one SHA: every glob must match at least one job (check
+ * run) from the allowed workflows/app, and the latest run of each matched
+ * (job, event) must be `success` — a `skipped` job is refused by name.
+ *
+ * @param globs - Job-name globs for the gate.
+ * @param checks - Every check reported for the commit.
+ * @param sha - Commit being judged.
+ * @param scope - The app and workflow files the jobs must come from.
+ * @param onlyEvent - Restrict to runs of this event (the PR-head substitution).
+ * @returns The judged job names, or one reason per unmet glob.
+ * @task T12634
+ */
+export function evaluateJobs(globs, checks, sha, scope, onlyEvent) {
+    const inScope = checks.filter((c) => c.source === 'check-run' &&
+        c.headSha === sha &&
+        (onlyEvent === undefined || c.event === onlyEvent) &&
+        c.workflowPath !== undefined &&
+        scope.workflows.includes(c.workflowPath) &&
+        (scope.app === undefined ||
+            (typeof scope.app === 'number' ? c.appId === scope.app : c.appSlug === scope.app)));
+    const reasons = [];
+    const jobs = [];
+    for (const glob of globs) {
+        const re = globToRegExp(glob);
+        const matched = inScope.filter((c) => re.test(c.name));
+        if (matched.length === 0) {
+            reasons.push(`job ${glob}: not found in ${scope.workflows.join(', ')} on ${sha.slice(0, 12)}`);
+            continue;
+        }
+        const latest = new Map();
+        for (const c of matched) {
+            const key = `${c.name}\u0000${c.event ?? ''}`;
+            const prev = latest.get(key);
+            if (!prev || c.id > prev.id)
+                latest.set(key, c);
+        }
+        const bad = [...latest.values()].find((c) => c.status !== 'completed' || c.conclusion !== 'success');
+        if (bad) {
+            reasons.push(`job ${bad.name}: ${bad.status !== 'completed' ? `pending (${bad.status})` : bad.conclusion} on ${sha.slice(0, 12)}`);
+            continue;
+        }
+        jobs.push(...new Set([...latest.values()].map((c) => c.name)));
+    }
+    return reasons.length > 0 ? { ok: false, reasons } : { ok: true, jobs };
+}
+function pinMatches(check, pin) {
+    if (!pin)
+        return true;
+    if (pin.app !== undefined) {
+        const ok = typeof pin.app === 'number' ? check.appId === pin.app : check.appSlug === pin.app;
+        if (!ok)
+            return false;
+    }
+    if (pin.workflow !== undefined && check.workflowPath !== pin.workflow)
+        return false;
+    return true;
+}
+function describeApp(check) {
+    return check.appSlug ?? (check.appId !== undefined ? `app ${check.appId}` : 'an unknown app');
+}
+/**
+ * Judge required checks on one merge commit. Pure.
+ *
+ * For each required name, runs are grouped by source (job / workflow) and
+ * triggering event, and within a group only the LATEST attempt counts; every
+ * group on the merge commit must be `completed`/`success`. A pinned name only
+ * considers runs from its pinned app/workflow. When `treeEquivalentSha` is
+ * given, that commit's `pull_request` runs (and only those) stand in for a
+ * merge-commit verdict that failed or is missing.
+ *
+ * @param required - Required check names.
+ * @param checks - Every check reported for the commits involved.
+ * @param mergeCommitSha - The merge commit being judged.
+ * @param opts - Tree-equivalent PR head and pins.
+ * @returns The judged checks, or one reason per unmet name.
+ * @task T12634
+ */
+export function evaluateMergeCommitChecks(required, checks, mergeCommitSha, opts = {}) {
+    if (required.length === 0) {
+        return {
+            ok: false,
+            reasons: ['No required checks are configured, so merge-commit CI proves nothing.'],
+        };
+    }
+    const { treeEquivalentSha, pins = {} } = opts;
+    const reasons = [];
+    const matched = [];
+    for (const name of required) {
+        const named = checks.filter((c) => c.name === name);
+        const pinned = named.filter((c) => pinMatches(c, pins[name]));
+        const onMerge = judgeOnSha(pinned, mergeCommitSha);
+        if (onMerge.ok) {
+            matched.push(judged(name, onMerge.run, mergeCommitSha));
+            continue;
+        }
+        if (treeEquivalentSha !== undefined && treeEquivalentSha !== mergeCommitSha) {
+            const onHead = judgeOnSha(pinned, treeEquivalentSha, 'pull_request');
+            if (onHead.ok) {
+                matched.push(judged(name, onHead.run, treeEquivalentSha));
+                continue;
+            }
+        }
+        const impostor = named.find((c) => !pinMatches(c, pins[name]));
+        const elsewhere = pinned.find((c) => c.headSha !== mergeCommitSha && c.headSha !== treeEquivalentSha);
+        reasons.push(onMerge.verdict === 'missing' && impostor && pinned.length === 0
+            ? `${name}: posted by ${describeApp(impostor)}${impostor.workflowPath ? ` (${impostor.workflowPath})` : ''}, not the pinned ${describePin(pins[name])}`
+            : onMerge.verdict === 'missing' && elsewhere
+                ? `${name}: ran on ${elsewhere.headSha.slice(0, 12)}, not the merge commit ${mergeCommitSha.slice(0, 12)}`
+                : onMerge.verdict === 'missing'
+                    ? `${name}: not found on merge commit ${mergeCommitSha.slice(0, 12)}`
+                    : `${name}: ${onMerge.verdict} on merge commit ${mergeCommitSha.slice(0, 12)}`);
+    }
+    return reasons.length > 0 ? { ok: false, reasons } : { ok: true, checks: matched };
+}
+function describePin(pin) {
+    if (!pin)
+        return 'source';
+    return [
+        pin.app !== undefined ? `app ${pin.app}` : '',
+        pin.workflow ? `workflow ${pin.workflow}` : '',
+    ]
+        .filter(Boolean)
+        .join(' / ');
+}
+function judged(name, run, sha) {
+    return {
+        name,
+        conclusion: 'success',
+        sha,
+        ...(run.appSlug !== undefined
+            ? { app: run.appSlug }
+            : run.appId !== undefined
+                ? { app: String(run.appId) }
+                : {}),
+        ...(run.workflowPath ? { workflow: run.workflowPath } : {}),
+        ...(run.event ? { event: run.event } : {}),
+    };
+}
+/**
+ * Judge one required name on one SHA. Runs are grouped by (source, event) and
+ * the latest attempt of each group must have completed with `success`. With
+ * `onlyEvent`, only runs of that event are considered.
+ */
+function judgeOnSha(named, sha, onlyEvent) {
+    const onSha = named.filter((c) => c.headSha === sha && (onlyEvent === undefined || c.event === onlyEvent));
+    if (onSha.length === 0)
+        return { ok: false, verdict: 'missing' };
+    const groups = new Map();
+    for (const c of onSha) {
+        const key = `${c.source}\u0000${c.event ?? ''}`;
+        const prev = groups.get(key);
+        if (!prev || c.id > prev.id)
+            groups.set(key, c);
+    }
+    const latest = [...groups.values()];
+    const bad = latest.find((c) => c.status !== 'completed' || c.conclusion !== 'success');
+    if (bad) {
+        return {
+            ok: false,
+            verdict: bad.status !== 'completed' ? `pending (${bad.status})` : (bad.conclusion ?? 'unknown'),
+        };
+    }
+    return { ok: true, run: latest.find((c) => c.source === 'workflow-run') ?? latest[0] };
+}
+/** Default {@link ResolveCiEvidenceOptions.treeOf}: `git rev-parse <sha>^{tree}`. */
+function defaultTreeOf(sha, cwd) {
+    return gitRead(cwd, ['rev-parse', '--verify', '--quiet', `${sha}^{tree}`]);
+}
+function defaultIsAncestor(ancestor, descendant, cwd) {
+    return gitRead(cwd, ['merge-base', '--is-ancestor', ancestor, descendant]) !== null;
+}
+function defaultOnDefaultBranch(sha, cwd) {
+    // The forge is authoritative; a local origin/HEAD can be stale or unset.
+    const fromGh = ghDefaultBranch(cwd);
+    const symbolic = fromGh
+        ? null
+        : gitRead(cwd, ['symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD']);
+    let ref = fromGh
+        ? `origin/${fromGh}`
+        : symbolic
+            ? symbolic.replace(/^refs\/remotes\//, '')
+            : null;
+    if (ref === null) {
+        for (const candidate of ['origin/main', 'origin/master']) {
+            if (gitRead(cwd, ['rev-parse', '--verify', '--quiet', `refs/remotes/${candidate}`]) !== null) {
+                ref = candidate;
+                break;
+            }
+        }
+    }
+    if (ref === null)
+        return { ref: null, landed: false };
+    return { ref, landed: defaultIsAncestor(sha, ref, cwd) };
+}
+/** Default branch name from `gh repo view --json defaultBranchRef`, or null. */
+function ghDefaultBranch(cwd) {
+    if (!isGhCliAvailable())
+        return null;
+    try {
+        const name = execFileSync('gh', ['repo', 'view', '--json', 'defaultBranchRef', '--jq', '.defaultBranchRef.name'], { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], timeout: ghQueryTimeoutMs() }).trim();
+        return /^[A-Za-z0-9._/-]+$/.test(name) ? name : null;
+    }
+    catch {
+        return null;
+    }
+}
+function defaultFirstParentOf(sha, cwd) {
+    return gitRead(cwd, ['rev-parse', '--verify', '--quiet', `${sha}^1`]);
+}
+function gitRead(cwd, args) {
+    try {
+        return execFileSync('git', args, {
+            cwd,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+/** Run one read-only `gh api` GET; `null` on failure. */
+function ghApi(path, cwd) {
+    try {
+        return JSON.parse(execFileSync('gh', ['api', path], {
+            cwd,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            maxBuffer: 32 * 1024 * 1024,
+            timeout: ghQueryTimeoutMs(),
+        }));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Default {@link ResolveCiEvidenceOptions.fetchChecks}: check runs + workflow
+ * runs for a SHA. Workflow runs carry their event and workflow file; a check
+ * run inherits both from the workflow run of its check suite.
+ */
+async function defaultFetchChecks(sha, cwd) {
+    if (!isGitWorkTree(cwd) || !isGhCliAvailable()) {
+        return { ok: false, reason: `gh cannot query checks from ${cwd} (no work tree or gh CLI).` };
+    }
+    const wf = ghApi(`repos/{owner}/{repo}/actions/runs?head_sha=${sha}&per_page=100`, cwd);
+    if (wf === null)
+        return { ok: false, reason: `gh api workflow runs for ${sha} failed` };
+    const checks = [];
+    const bySuite = new Map();
+    for (const r of wf.workflow_runs ?? []) {
+        const event = typeof r.event === 'string' ? r.event : undefined;
+        const path = typeof r.path === 'string' ? r.path.replace(/@.*$/, '') : undefined;
+        if (typeof r.check_suite_id === 'number')
+            bySuite.set(r.check_suite_id, { event, path });
+        checks.push({
+            name: String(r.name ?? ''),
+            source: 'workflow-run',
+            status: String(r.status ?? ''),
+            conclusion: typeof r.conclusion === 'string' ? r.conclusion : null,
+            headSha: String(r.head_sha ?? ''),
+            id: Number(r.id ?? 0),
+            appSlug: 'github-actions',
+            ...(path ? { workflowPath: path } : {}),
+            ...(event ? { event } : {}),
+        });
+    }
+    for (let page = 1; page <= 10; page++) {
+        const body = ghApi(`repos/{owner}/{repo}/commits/${sha}/check-runs?per_page=100&page=${page}`, cwd);
+        if (body === null)
+            return { ok: false, reason: `gh api check-runs for ${sha} failed` };
+        const runs = body.check_runs ?? [];
+        for (const r of runs) {
+            const app = r.app;
+            const suite = r.check_suite?.id;
+            const origin = typeof suite === 'number' ? bySuite.get(suite) : undefined;
+            checks.push({
+                name: String(r.name ?? ''),
+                source: 'check-run',
+                status: String(r.status ?? ''),
+                conclusion: typeof r.conclusion === 'string' ? r.conclusion : null,
+                headSha: String(r.head_sha ?? ''),
+                id: Number(r.id ?? 0),
+                ...(typeof app?.slug === 'string' ? { appSlug: app.slug } : {}),
+                ...(typeof app?.id === 'number' ? { appId: app.id } : {}),
+                ...(origin?.path ? { workflowPath: origin.path } : {}),
+                ...(origin?.event ? { event: origin.event } : {}),
+            });
+        }
+        if (runs.length < 100)
+            break;
+    }
+    return { ok: true, checks };
+}
+/**
+ * Validate a `ci:<pr>` atom end to end.
+ *
+ * @param prNumber - The merged PR.
+ * @param roots - Store root (config, caches) and execution root (`gh` cwd).
+ * @param opts - Injectable PR resolution and check fetching.
+ * @returns The validated atom, or a refusal naming every unmet check.
+ * @example
+ * ```ts
+ * const r = await resolveCiEvidenceAtom(357, { storeRoot, executionRoot });
+ * ```
+ * @task T12634
+ */
+export async function resolveCiEvidenceAtom(prNumber, roots, opts = {}) {
+    if (!readCiSatisfies(roots.storeRoot)) {
+        return {
+            ok: false,
+            codeName: 'E_EVIDENCE_INSUFFICIENT',
+            reason: 'ci:<pr> evidence is disabled for this project (evidence.ciSatisfies is not true). Set "evidence": { "ciSatisfies": true } in ' +
+                ".cleo/project-context.json to accept required CI on a merged PR's merge commit for " +
+                'testsPassed and qaPassed (D11149), or record tool:test / tool:lint results instead.',
+        };
+    }
+    const context = opts.context;
+    if (!context) {
+        return {
+            ok: false,
+            codeName: 'E_EVIDENCE_INSUFFICIENT',
+            reason: 'CI evidence requires current task, gate and acceptance-criterion context.',
+        };
+    }
+    // T12634: which checks attest which gate is declared, never inferred.
+    const ciChecks = readCiChecks(roots.storeRoot);
+    const gateLists = context.gates
+        .filter((g) => g === 'testsPassed' || g === 'qaPassed')
+        .map((g) => ({
+        gate: g,
+        key: g === 'testsPassed' ? 'tests' : 'qa',
+        list: ciChecks[g === 'testsPassed' ? 'tests' : 'qa'],
+    }));
+    if (gateLists.length === 0) {
+        return {
+            ok: false,
+            codeName: 'E_EVIDENCE_INVALID',
+            reason: `ci:${prNumber} attests only testsPassed and qaPassed, not ${context.gates.join(', ')}.`,
+        };
+    }
+    const unconfigured = gateLists.filter((g) => !g.list || g.list.length === 0);
+    if (unconfigured.length > 0) {
+        return {
+            ok: false,
+            codeName: 'E_EVIDENCE_INSUFFICIENT',
+            reason: `ci:${prNumber} cannot attest ${unconfigured.map((g) => g.gate).join(', ')}: set ` +
+                unconfigured.map((g) => `evidence.ciChecks.${g.key}`).join(' and ') +
+                ' in .cleo/project-context.json to the required checks that prove it.',
+        };
+    }
+    const projectContext = opts.projectContext ?? null;
+    const readOnly = opts.readOnly === true;
+    const pr = await (opts.resolvePr ?? ((n, r) => resolvePrEvidenceAtom(n, r, { projectContext, readOnly })))(prNumber, roots);
+    if (!pr.ok)
+        return { ok: false, reason: pr.reason, codeName: pr.codeName };
+    // T12634: the same task linkage `pr:` enforces — never any merged PR for any
+    // task. T12671: through the component PR when the atom names one.
+    const linked = await linkedPrChange(prNumber, pr, roots, opts.componentPrNumber, opts.viewComponentPr);
+    if (!linked.ok) {
+        return {
+            ok: false,
+            reason: linked.reason,
+            codeName: linked.codeName === 'E_EVIDENCE_CONTENT_MISMATCH'
+                ? 'E_EVIDENCE_CONTENT_MISMATCH'
+                : 'E_EVIDENCE_INSUFFICIENT',
+        };
+    }
+    const unlinked = checkPrTaskLinkage(linked.prNumber, linked.pr, context);
+    if (unlinked) {
+        return {
+            ok: false,
+            reason: unlinked.reason,
+            codeName: unlinked.codeName === 'E_EVIDENCE_CONTENT_MISMATCH'
+                ? 'E_EVIDENCE_CONTENT_MISMATCH'
+                : 'E_EVIDENCE_INSUFFICIENT',
+        };
+    }
+    // The work must have LANDED on the default branch: a PR merged into an
+    // integration branch counts once that branch reached the default branch
+    // (its merge commit is then an ancestor), and never before.
+    const onDefault = (opts.onDefaultBranch ?? defaultOnDefaultBranch)(pr.mergeCommitSha, roots.executionRoot);
+    if (onDefault.ref === null) {
+        return {
+            ok: false,
+            codeName: 'E_EVIDENCE_INSUFFICIENT',
+            reason: `Cannot determine origin's default branch in ${roots.executionRoot}, so ci:${prNumber} cannot show the work landed (git remote set-head origin --auto).`,
+        };
+    }
+    if (!onDefault.landed) {
+        return {
+            ok: false,
+            codeName: 'E_EVIDENCE_INSUFFICIENT',
+            reason: `PR #${prNumber}'s merge commit ${pr.mergeCommitSha.slice(0, 12)} is not on ${onDefault.ref}: the work has not landed on the default branch (git fetch origin, or wait until its integration branch merges).`,
+        };
+    }
+    const required = await resolveRequiredWorkflowsDetailed(roots, { projectContext, readOnly });
+    if (required.source.tier === 'unknown') {
+        return {
+            ok: false,
+            codeName: 'E_EVIDENCE_INSUFFICIENT',
+            reason: `Cannot determine the required checks (${required.source.reason}); ci:${prNumber} cannot be judged.`,
+        };
+    }
+    const outside = gateLists.flatMap((g) => (g.list ?? []).filter((n) => !required.workflows.includes(n)).map((n) => `${g.key}:${n}`));
+    if (outside.length > 0) {
+        return {
+            ok: false,
+            codeName: 'E_EVIDENCE_INSUFFICIENT',
+            reason: `evidence.ciChecks names checks that are not required (${outside.join(', ')}); required: ${required.workflows.join(', ')}.`,
+        };
+    }
+    // Pins: branch protection's app ids when that tier supplied the list,
+    // otherwise object entries of release.prRequiredWorkflows.
+    const pins = required.pins ?? readRequiredCheckPins(projectContext);
+    // Round 2 (MEDIUM): a check that attests a gate must be pinned to the app
+    // that posts it — an unpinned name would match a run from any app.
+    const mapped = [...new Set(gateLists.flatMap((g) => g.list ?? []))];
+    const unpinned = mapped.filter((name) => pins[name]?.app === undefined);
+    if (unpinned.length > 0) {
+        return {
+            ok: false,
+            codeName: 'E_EVIDENCE_INSUFFICIENT',
+            reason: `ci:${prNumber} cannot trust unpinned check(s) ${unpinned.join(', ')}: declare each in ` +
+                'release.prRequiredWorkflows as { "name": "<check>", "app": "<app slug or id>", ' +
+                '"workflow": ".github/workflows/<file>.yml" } (or pin it in branch protection).',
+        };
+    }
+    // Round 2: a pull_request run executes the PR's OWN edited workflow, so a PR
+    // that touches a pinned workflow file cannot vouch for itself.
+    const pinnedWorkflows = [
+        ...new Set(mapped.flatMap((name) => (pins[name]?.workflow ? [pins[name].workflow] : []))),
+    ];
+    const editedWorkflows = pinnedWorkflows.filter((w) => pr.changedPaths.includes(w));
+    if (editedWorkflows.length > 0) {
+        return {
+            ok: false,
+            codeName: 'E_EVIDENCE_INSUFFICIENT',
+            reason: `PR #${prNumber} edits the pinned workflow ${editedWorkflows.join(', ')}, so its own CI ` +
+                'cannot attest it. Record local results instead (tool:test, tool:lint, tool:typecheck).',
+        };
+    }
+    const fetchChecks = opts.fetchChecks ?? defaultFetchChecks;
+    const fetched = await fetchChecks(pr.mergeCommitSha, roots.executionRoot);
+    if (!fetched.ok)
+        return { ok: false, reason: fetched.reason, codeName: 'E_EVIDENCE_TOOL_FAILED' };
+    // T12634 (review): a pull_request run on head H tested merge(H, base-at-run).
+    // Tree equality alone is unsound — base can gain X, CI tests H+X, then base
+    // reverts X and the merge still equals H's tree. Requiring the merge's
+    // first parent to be an ANCESTOR of H closes it: base only advances, so
+    // every base-at-run was already in H and the tested merge IS H. GitHub
+    // deletes refs/pull/<n>/merge after merge, so H stands in for it.
+    const cwd = roots.executionRoot;
+    const treeOf = opts.treeOf ?? defaultTreeOf;
+    const mergeTree = treeOf(pr.mergeCommitSha, cwd);
+    const head = pr.headRefOid;
+    const headTree = head ? treeOf(head, cwd) : null;
+    const parent = (opts.firstParentOf ?? defaultFirstParentOf)(pr.mergeCommitSha, cwd);
+    const treeEqualHead = head &&
+        mergeTree !== null &&
+        headTree !== null &&
+        headTree === mergeTree &&
+        parent !== null &&
+        (opts.isAncestor ?? defaultIsAncestor)(parent, head, cwd)
+        ? head
+        : undefined;
+    let checks = fetched.checks;
+    if (treeEqualHead && treeEqualHead !== pr.mergeCommitSha) {
+        const onHead = await fetchChecks(treeEqualHead, cwd);
+        if (onHead.ok)
+            checks = [...checks, ...onHead.checks];
+    }
+    const judgedChecks = evaluateMergeCommitChecks(required.workflows, checks, pr.mergeCommitSha, {
+        ...(treeEqualHead ? { treeEquivalentSha: treeEqualHead } : {}),
+        pins,
+    });
+    if (!judgedChecks.ok) {
+        return {
+            ok: false,
+            codeName: 'E_EVIDENCE_TESTS_FAILED',
+            reason: `Required CI on PR #${prNumber}'s merge commit ${pr.mergeCommitSha.slice(0, 12)} is not green ` +
+                `(source: ${describeRequiredWorkflowsSource(required.source)}):\n  - ${judgedChecks.reasons.join('\n  - ')}`,
+        };
+    }
+    // Round 2 (skipped tests): the aggregate counts skipped jobs as a pass. For a
+    // CODE task every configured job glob must have actually run and succeeded
+    // in the pinned workflows; a docs/research task keeps the honest skip.
+    // A PR whose whole diff is documentation had nothing for the test and
+    // typecheck jobs to run on — the same judgement `pr:` makes when it refuses a
+    // docs-only PR as a code task's implementation — so its skip is honest too.
+    // Round 3: the DIFF alone decides — a task label is agent-editable
+    // (`cleo update --labels docs`) and must never excuse skipped jobs.
+    const docsOnlyDiff = pr.changedPaths.length > 0 && pr.changedPaths.every(isCiDocumentPath);
+    const isCode = !docsOnlyDiff;
+    const jobsByGate = {};
+    if (isCode) {
+        for (const g of gateLists) {
+            const globs = readCiChecks(roots.storeRoot).jobs?.[g.key];
+            if (!globs || globs.length === 0) {
+                return {
+                    ok: false,
+                    codeName: 'E_EVIDENCE_INSUFFICIENT',
+                    reason: `ci:${prNumber} cannot attest ${g.gate} for code task ${context.task.id}: set ` +
+                        `evidence.ciChecks.jobs.${g.key} to the job names that must run (e.g. "Unit Tests*").`,
+                };
+            }
+            const scopeWorkflows = (g.list ?? []).flatMap((n) => pins[n]?.workflow ? [pins[n].workflow] : []);
+            const app = (g.list ?? []).map((n) => pins[n]?.app).find((a) => a !== undefined);
+            if (scopeWorkflows.length === 0) {
+                return {
+                    ok: false,
+                    codeName: 'E_EVIDENCE_INSUFFICIENT',
+                    reason: `ci:${prNumber}: no workflow file is pinned for ${g.gate}'s checks, so its jobs cannot be scoped; add "workflow" to their release.prRequiredWorkflows entries.`,
+                };
+            }
+            const scope = { ...(app !== undefined ? { app } : {}), workflows: scopeWorkflows };
+            let judgedJobs = evaluateJobs(globs, checks, pr.mergeCommitSha, scope);
+            if (!judgedJobs.ok && treeEqualHead) {
+                const onHead = evaluateJobs(globs, checks, treeEqualHead, scope, 'pull_request');
+                if (onHead.ok)
+                    judgedJobs = onHead;
+            }
+            if (!judgedJobs.ok) {
+                return {
+                    ok: false,
+                    codeName: 'E_EVIDENCE_TESTS_FAILED',
+                    reason: `${g.gate} for code task ${context.task.id} needs its jobs to have run on PR #${prNumber}:\n  - ` +
+                        judgedJobs.reasons.join('\n  - '),
+                };
+            }
+            jobsByGate[g.gate] = judgedJobs.jobs;
+        }
+    }
+    const gateChecks = {};
+    for (const g of gateLists)
+        gateChecks[g.gate] = [...(g.list ?? []), ...(jobsByGate[g.gate] ?? [])];
+    return {
+        ok: true,
+        atom: {
+            kind: 'ci',
+            prNumber,
+            mergeCommitSha: pr.mergeCommitSha,
+            checks: judgedChecks.checks,
+            ...(mergeTree !== null ? { testedTree: mergeTree } : {}),
+            requiredSource: required.source.tier,
+            taskId: context.task.id,
+            gateChecks,
+            ...(opts.componentPrNumber !== undefined
+                ? { componentPrNumber: opts.componentPrNumber }
+                : {}),
+        },
+    };
+}
+//# sourceMappingURL=ci-evidence.js.map