@cleocode/core 2026.10.21 → 2026.10.22

package/dist/tasks/evidence.js

@@ -40,6 +40,7 @@ import { bindTestRunReport, configSchemaCompositionGap, coveredTestFiles, TEST_R
 import { captureHead, captureTree, resolveSpawnTimeoutMs, runToolCached, } from './tool-cache.js';
 import { CANONICAL_TOOLS, canonicalToolName, listValidToolNames, resolveToolCommand, } from './tool-resolver.js';
 import { detectStaticVacuity, probeTscFileCount, VACUOUS_TOOL_FIX } from './tool-vacuity.js';
+import { classifyEvidenceTask, isDocumentArtifact, isDocumentEvidencePath, } from './verification-policy.js';
 /**
  * Valid tool names recognised by the `tool:<name>` evidence atom.
  *
@@ -203,6 +204,27 @@ siblingCommitSha, context) {
         storeRoot: projectRoot,
         executionRoot: resolveEvidenceExecutionRoot(projectRoot, undefined, executionRootHints),
     };
+    // T13912: `pr:<owner>/<repo>#<n>` names the repository the number belongs
+    // to; it must be the evidence git root's origin, never another repo's PR #n.
+    if ((parsed.kind === 'pr' || parsed.kind === 'ci') && parsed.repo !== undefined) {
+        const { originRepoSlug } = await import('../release/pr-evidence.js');
+        const origin = originRepoSlug(roots.executionRoot);
+        if (origin !== parsed.repo) {
+            return {
+                ok: false,
+                codeName: 'E_EVIDENCE_INVALID',
+                reason: `${parsed.kind}:${parsed.repo}#${parsed.prNumber} names ${parsed.repo}, but the evidence ` +
+                    `git root (${roots.executionRoot}) has origin ${origin ?? 'none on GitHub'}. Run it from ` +
+                    "that repository's checkout, or declare it with CLEO_EVIDENCE_GIT_ROOT / evidence.gitRoot.",
+            };
+        }
+        const { repo, ...bare } = parsed;
+        const named = await validateAtom(bare, projectRoot, taskId, siblingCommitSha, context);
+        if (named.ok && (named.atom.kind === 'pr' || named.atom.kind === 'ci')) {
+            return { ...named, atom: { ...named.atom, repo } };
+        }
+        return named;
+    }
     switch (parsed.kind) {
         case 'commit':
             return validateCommit(parsed.sha, roots, taskId);
@@ -797,6 +819,18 @@ export function extractTaskAcFilesWithProvenance(task) {
  * @task T11959 (DHQ-083 companion b — merge-commit first-parent diff)
  */
 async function gitShowFiles(sha, projectRoot) {
+    return (await commitFilesOrNull(sha, projectRoot)) ?? [];
+}
+/**
+ * {@link gitShowFiles}, but null when git fails, so a caller can tell an
+ * unreadable commit from one that touched nothing (T14001, review of #2413).
+ *
+ * @param sha - Commit SHA to inspect.
+ * @param projectRoot - Working directory for git operations.
+ * @returns File paths touched by the commit, or null on git failure.
+ * @task T14001
+ */
+async function commitFilesOrNull(sha, projectRoot) {
     // diff-tree with --first-parent gives a clean single-parent diff for both
     // regular commits and merge commits (compares merge result to first parent,
     // i.e. the branch tip before the PR was merged).
@@ -809,7 +843,7 @@ async function gitShowFiles(sha, projectRoot) {
     // evidence commit happens to be the very first commit in the repo (T11959).
     const r = await runCommand('git', ['diff-tree', '--root', '--no-commit-id', '-r', '--name-only', '-m', '--first-parent', sha], projectRoot);
     if (r.exitCode !== 0)
-        return [];
+        return null;
     return r.stdout
         .split('\n')
         .map((s) => s.trim())
@@ -1666,6 +1700,7 @@ async function validateTestRun(path, roots, taskId) {
     let runHeadSha;
     let configPaths = [];
     let typecheckDirs = [];
+    let untrackedSetAside = [];
     if (identity) {
         const binding = bindTestRunReport(parsed, abs, bindRoot, testFiles);
         if (!binding.ok)
@@ -1674,6 +1709,7 @@ async function validateTestRun(path, roots, taskId) {
         runHeadSha = binding.runHeadSha;
         configPaths = binding.configPaths ?? [];
         typecheckDirs = binding.typecheckDirs ?? [];
+        untrackedSetAside = binding.untrackedSetAside ?? [];
     }
     return {
         ok: true,
@@ -1702,6 +1738,7 @@ async function validateTestRun(path, roots, taskId) {
             ...(capture.runtimeExcluded.length > 0
                 ? { runtimeExcluded: [...capture.runtimeExcluded] }
                 : {}),
+            ...(untrackedSetAside.length > 0 ? { untrackedSetAside } : {}),
         },
     };
 }
@@ -1792,6 +1829,7 @@ async function validateQaRun(path, roots, taskId) {
                 : {}),
             ...(gaps?.nonCodeChange ? { nonCodeChange: true } : {}),
             ...(gaps?.configPaths ? { configPaths: gaps.configPaths } : {}),
+            ...(gaps?.untrackedSetAside ? { untrackedSetAside: gaps.untrackedSetAside } : {}),
         },
     };
 }
@@ -2697,6 +2735,9 @@ async function validatePrAtom(prNumber, roots, context, componentPrNumber) {
             kind: 'pr',
             prNumber: result.prNumber,
             mergeCommitSha: result.mergeCommitSha,
+            ...(componentPrNumber === undefined && result.headRefOid
+                ? { headSha: result.headRefOid }
+                : {}),
             mergedAt: result.mergedAt,
             successCount: result.successCount,
             totalChecks: result.totalChecks,
@@ -2747,40 +2788,9 @@ export async function linkedPrChange(prNumber, landing, roots, componentPrNumber
         },
     };
 }
-/**
- * Whether a path is a documentation artifact (`.md`/`.mdx`/`.rst`/`.adoc`/`.txt`,
- * README, LICENSE, CHANGELOG) — the rule `pr:` uses to refuse a docs-only PR
- * as implementation of a code task.
- *
- * @param path - Repo-relative path.
- * @returns True for a documentation artifact.
- */
-export function isDocumentArtifact(path) {
-    return (/\.(md|mdx|rst|adoc|txt)$/i.test(path) ||
-        /(?:^|\/)(README|LICENSE|CHANGELOG)(?:\.[^/]*)?$/i.test(path));
-}
-/**
- * Classify a task for evidence purposes: `research` (research/spike kind),
- * `documentation` (docs-only declared files or a docs label) or `code`.
- *
- * Exported so the read-only `cleo done --plan` planner chooses the same
- * documentary path the validators accept — one classification, not two.
- *
- * @param context - Task context; only `task` is read.
- * @returns The evidence classification.
- * @task T12624
- */
-export function classifyEvidenceTask(context) {
-    if (context.task.kind === 'research' || context.task.kind === 'spike')
-        return 'research';
-    if (context.task.files?.length && context.task.files.every(isDocumentArtifact))
-        return 'documentation';
-    if (context.task.kind === 'bug')
-        return 'code';
-    if (context.task.labels?.some((label) => label === 'docs' || label === 'documentation'))
-        return 'documentation';
-    return 'code';
-}
+// T14001: the evidence kind and the document rule live with the gate policy,
+// which every gate reader (verify, done --plan, complete, release plan) shares.
+export { classifyEvidenceTask, isDocumentArtifact };
 /**
  * Normalise an evidence path for comparison with PR changed paths: strip a
  * leading `./` and trailing slashes. One normaliser for anchoring, PR
@@ -3140,6 +3150,180 @@ export function composeGateEvidence(atoms, capturedBy, override, overrideReason,
     }
     return result;
 }
+/**
+ * Why a `test-run:`/`qa-run:` result does not describe this task's work
+ * (T14004), or null. The binding records the HEAD it was bound to, and that
+ * HEAD must have seen the task's `implemented` work:
+ *
+ * - `commit:` — the run head is that commit or contains it. An older commit
+ *   (the branch base, main before the work) never saw the work.
+ * - `pr:` — the run head is, or contains, the merge commit or the PR's final
+ *   head: its recorded `headSha` (a squash merge too), else the merge's second
+ *   parent. An earlier branch commit never saw the whole change.
+ *
+ * Evidence bound in another task's worktree is refused even when `cleo
+ * complete` runs from that same worktree. A commit git cannot read (a shallow
+ * clone) is refused and said so. Skipped while no implemented commit is
+ * recorded, or for an atom with no HEAD.
+ *
+ * @param task - The task (its recorded `implemented` evidence is read).
+ * @param atoms - The gate's atoms.
+ * @param projectRoot - The CLEO store root (the task's checkout is resolved from it).
+ * @returns The refusal, or null.
+ * @task T14004
+ */
+export async function boundHeadGapReason(task, atoms, projectRoot) {
+    const runs = atoms.filter((a) => (a.kind === 'test-run' || a.kind === 'qa-run') && typeof a.headSha === 'string');
+    if (runs.length === 0)
+        return null;
+    const implemented = (task.verification?.evidence?.implemented?.atoms ?? []).filter((a) => a.kind === 'commit' || a.kind === 'pr');
+    if (implemented.length === 0)
+        return null;
+    const { resolveChangeSetRoot } = await import('./change-set.js');
+    const root = resolveChangeSetRoot(projectRoot, task.id).root;
+    const gitOut = (args) => {
+        try {
+            return execFileSync('git', args, {
+                cwd: root,
+                encoding: 'utf-8',
+                env: discoveryEnv(),
+                stdio: ['ignore', 'pipe', 'ignore'],
+            }).trim();
+        }
+        catch {
+            return null;
+        }
+    };
+    // Exit 1 is "not an ancestor"; anything else (128) is an object git lacks.
+    let missing = null;
+    const contains = (descendant, ancestor) => {
+        try {
+            execFileSync('git', ['merge-base', '--is-ancestor', ancestor, descendant], {
+                cwd: root,
+                env: discoveryEnv(),
+                stdio: 'ignore',
+            });
+            return true;
+        }
+        catch (err) {
+            const status = err instanceof Error && 'status' in err ? err.status : undefined;
+            if (status !== 1)
+                missing ??= `${ancestor}..${descendant}`;
+            return false;
+        }
+    };
+    // A prefix match needs at least 7 hex characters on both sides: '' matches everything.
+    const sameCommit = (a, b) => a.length >= 7 && b.length >= 7 && (a.startsWith(b) || b.startsWith(a));
+    const reached = (head, sha) => sameCommit(head, sha) || contains(head, sha);
+    // Only positive checks accept: the run head is, or contains, the work's tip.
+    const sawWork = (head, atom) => {
+        if (atom.kind === 'commit')
+            return reached(head, atom.sha);
+        const merge = atom.mergeCommitSha;
+        if (reached(head, merge))
+            return true;
+        // The PR's final head; a legacy atom without it falls back to the merge's
+        // second parent. An ancestor of either (an earlier branch commit) never
+        // saw the whole change.
+        const tip = atom.headSha ?? gitOut(['rev-parse', '--verify', '--quiet', `${merge}^2`]);
+        return tip !== null && tip !== '' && reached(head, tip);
+    };
+    const shas = implemented
+        .map((a) => (a.kind === 'commit' ? a.sha : a.mergeCommitSha).slice(0, 12))
+        .join(', ');
+    for (const run of runs) {
+        const head = run.headSha;
+        missing = null;
+        if (implemented.every((atom) => sawWork(head, atom)))
+            continue;
+        const bound = `${run.kind}:${run.path} was bound at ${head.slice(0, 12)}`;
+        if (missing !== null) {
+            return (`${bound}, and git cannot read the commits that relate it to ${task.id}'s implemented ` +
+                `commit ${shas} (missing object, or a shallow clone: ${missing}). ` +
+                'Fetch the full history (git fetch --unshallow) and verify again.');
+        }
+        // A head carrying this task's own work, but not the recorded commit: the
+        // implemented evidence went stale (a rebase, an amend, or a squash merge
+        // recorded before the PR head was).
+        const message = gitOut(['log', '-n', '20', '--format=%B', head]) ?? '';
+        if (new RegExp(`\\b${task.id}\\b`).test(message)) {
+            return (`${bound}, which carries ${task.id}'s work but not its implemented commit ${shas}: ` +
+                'the branch was rebased, amended or squash-merged after implemented was recorded. ' +
+                `Re-record implemented (cleo verify ${task.id} --gate implemented ...), then the run.`);
+        }
+        return (`${bound}, which never saw ${task.id}'s implemented commit ${shas}: it tested other ` +
+            "work (another task's checkout, or a commit before the change). Run the tests on this " +
+            "task's checkout and record that report.");
+    }
+    return null;
+}
+/**
+ * The evidence kind whose gates a task owes now (T14001, reviews of #2413):
+ * {@link classifyEvidenceTask}, raised to `code` when its recorded
+ * `implemented` evidence or `extraPaths` (a change set) touch any
+ * non-document path — `files:` paths, a `pr:` atom's changed paths, a
+ * `commit:` atom's diff (merge and root commits included) — or when the
+ * task's own work does ({@link taskOwnWorkPaths}: branches citing it, commits
+ * on the default branch whose subject cites it, and its merged PRs). A kind
+ * or label set by any agent never lets a code change skip its tests, and
+ * work that cannot be inspected fails closed to `code`, with the reason.
+ *
+ * @param task - The task (kind, files, labels and recorded evidence are read).
+ * @param projectRoot - The CLEO store root (commits are read in the task's checkout).
+ * @param extraPaths - Further paths the work touched (a derived change set).
+ * @param cwd - Invocation directory, which locates the task's worktree.
+ * @param deps - Merged-PR discovery (tests inject; defaults to `gh`).
+ * @returns The kind, and the reason when a non-code kind owes the code gates.
+ * @task T14001
+ */
+export async function taskEvidenceKindReport(task, projectRoot, extraPaths = [], cwd, deps = {}) {
+    const kind = classifyEvidenceTask({ task });
+    if (kind === 'code')
+        return { kind };
+    const code = (reason) => ({ kind: 'code', reason });
+    const { resolveChangeSetRoot, taskOwnWorkPaths } = await import('./change-set.js');
+    // The task's own branches, commits and merged PRs, whatever its evidence
+    // cites: a spike that commits code and records `decision:` owes tests.
+    const ownWork = await taskOwnWorkPaths(projectRoot, task.id, cwd, deps);
+    if (!ownWork.ok)
+        return code(`its work could not be inspected: ${ownWork.reason}`);
+    const paths = [...extraPaths, ...ownWork.paths];
+    const atoms = task.verification?.evidence?.implemented?.atoms ?? [];
+    const root = resolveChangeSetRoot(projectRoot, task.id, cwd).root;
+    for (const atom of atoms) {
+        if (atom.kind === 'files')
+            paths.push(...atom.files.map((f) => f.path));
+        // A legacy `pr:` atom without its changed paths proves nothing about documents.
+        else if (atom.kind === 'pr') {
+            if (atom.changedPaths === undefined) {
+                return code(`pr:${atom.prNumber} was recorded without its changed files`);
+            }
+            paths.push(...atom.changedPaths);
+        }
+        else if (atom.kind === 'commit') {
+            // An unreadable commit proves nothing about documents: owe the code gates.
+            const files = await commitFilesOrNull(atom.sha, root);
+            if (files === null)
+                return code(`git cannot read commit:${atom.sha} in ${root}`);
+            paths.push(...files);
+        }
+    }
+    const codePath = paths.find((path) => !isDocumentEvidencePath(path));
+    return codePath === undefined ? { kind } : code(`its work touches ${codePath}`);
+}
+/**
+ * {@link taskEvidenceKindReport}'s kind alone.
+ *
+ * @param task - The task (kind, files, labels and recorded evidence are read).
+ * @param projectRoot - The CLEO store root.
+ * @param extraPaths - Further paths the work touched (a derived change set).
+ * @param cwd - Invocation directory, which locates the task's worktree.
+ * @returns The kind to read {@link requiredGatesFor} with.
+ * @task T14001
+ */
+export async function taskEvidenceKind(task, projectRoot, extraPaths = [], cwd) {
+    return (await taskEvidenceKindReport(task, projectRoot, extraPaths, cwd)).kind;
+}
 /**
  * Critical gates for which `override`-only evidence is NEVER accepted. Closes
  * the override-loophole proven 2026-05-12 — 13 mis-completed tasks in the
@@ -3258,6 +3442,8 @@ export async function revalidateEvidence(evidence, projectRoot, gate, taskId, op
             criteria: await accessor.getAcRows(taskId),
         };
         let reason = checkTaskEvidenceContext(context, gate, evidence.atoms);
+        // T14004: a run bound in another task's checkout is not this task's evidence.
+        reason ??= await boundHeadGapReason(task, evidence.atoms, projectRoot);
         if (!reason &&
             !(classifyEvidenceTask(context) !== 'code' &&
                 isDecisionOnlyImplementation(task.verification?.evidence?.implemented) &&