@cleocode/core 2026.10.25 → 2026.10.26-rc.ci.697

package/dist/tasks/evidence.js

@@ -10,7 +10,8 @@
  *   - {@link resolveToolCommand} maps `tool:<name>` to a runnable command
  *     using `.cleo/project-context.json` and per-`primaryType` fallbacks.
  *   - {@link runToolCached} memoises results per
- *     `(canonical, cmd, args, treeHash, envFingerprint)` and serialises
+ *     `(canonical, cmd, args, treeHash, envFingerprint, resourceEnv)` (the
+ *     heap and worker limits the run gets, T12989) and serialises
  *     concurrent identical runs via a cross-process lock,
  *     preventing the resource thrash observed when multiple `cleo verify`
  *     invocations spawned full toolchains in parallel.
@@ -36,11 +37,11 @@ import { HEAVY_HEAP_ENV, HEAVY_WORKERS_ENV, isHeavyTool } from './heavy-tool-env
 import { DISABLE_ENV, describeMemoryLimit } from './heavy-tool-limit.js';
 import { qaRunUnionGapReason, typecheckCoverageGap } from './qa-run-binding.js';
 import { computeCommitRevalidationKey, readCommitRevalidationEntry, writeCommitRevalidationEntry, } from './revalidation-cache.js';
-import { bindTestRunReport, configSchemaCompositionGap, coveredTestFiles, TEST_RUN_MAX_RECORDED_FILES, } from './test-run-binding.js';
+import { bindTestRunReport, configSchemaCompositionGap, coveredTestFiles, playwrightTestRun, TEST_RUN_MAX_RECORDED_FILES, } from './test-run-binding.js';
 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';
+import { classifyEvidenceTask, declaredEvidenceKind, isDocumentArtifact, isDocumentEvidencePath, } from './verification-policy.js';
 /**
  * Valid tool names recognised by the `tool:<name>` evidence atom.
  *
@@ -229,7 +230,7 @@ siblingCommitSha, context) {
         case 'commit':
             return validateCommit(parsed.sha, roots, taskId);
         case 'files': {
-            const result = await validateFiles(parsed.paths, roots, taskId, anchorFor, Boolean(artifactPrs ?? context?.artifactCommitSha));
+            const result = await validateFiles(parsed.paths, roots, taskId, anchorFor, Boolean(artifactPrs ?? context?.artifactCommitSha), (path) => artifactPrs?.find((pr) => pr.deletedPaths?.some((deleted) => normalizeEvidencePath(deleted) === normalizeEvidencePath(path))));
             if (!result.ok || result.atom.kind !== 'files' || (artifactPrs?.length ?? 0) < 2)
                 return result;
             return {
@@ -238,7 +239,7 @@ siblingCommitSha, context) {
             };
         }
         case 'test-run':
-            return validateTestRun(parsed.path, roots, taskId ?? context?.task.id);
+            return validateTestRun(parsed.path, roots, taskId ?? context?.task.id, context?.testRunPaths ?? []);
         case 'qa-run':
             return validateQaRun(parsed.path, roots, taskId ?? context?.task.id);
         case 'tool':
@@ -875,7 +876,13 @@ async function commitFilesOrNull(sha, projectRoot) {
 export function diffIntersectsAc(diffFiles, acFiles) {
     const norm = (s) => s.replace(/^\.\//, '').replace(/\/+$/, '').toLowerCase();
     const acSet = new Set(acFiles.map(norm));
-    const acPrefixes = acFiles.map(norm).filter((p) => !p.includes('.') || p.endsWith('/'));
+    // A directory entry: declared with a trailing slash, or whose last segment
+    // has no extension. Judged on the raw entry and its last segment (T14073):
+    // the old test ran on the normalised path, whose trailing slash is already
+    // stripped, so any dot earlier in it (`.cleo/rcasd/T1/`) hid the directory.
+    const acPrefixes = acFiles
+        .filter((raw) => /\/\s*$/.test(raw) || !(norm(raw).split('/').pop() ?? '').includes('.'))
+        .map(norm);
     for (const f of diffFiles) {
         const nf = norm(f);
         if (acSet.has(nf))
@@ -1161,6 +1168,8 @@ async function gitShowFileContentAtCommit(relPath, sha, projectRoot) {
  *   enables the commit-tree-first check (T12107).
  * @param requireCommitArtifact - Refuse when the anchor tree lacks the path
  *   (a PR merge anchor: checkout bytes cannot substitute).
+ * @param deletedBy - The PR of the write that deleted a path, if any: such a
+ *   path is refused by name rather than as an unfetched merge (T14030).
  * @returns Validated atom on success, error on failure.
  *
  * @internal
@@ -1168,7 +1177,7 @@ async function gitShowFileContentAtCommit(relPath, sha, projectRoot) {
  * @task T11959
  * @task T12107
  */
-async function validateFiles(paths, roots, taskId, commitShaFor, requireCommitArtifact = false) {
+async function validateFiles(paths, roots, taskId, commitShaFor, requireCommitArtifact = false, deletedBy = () => undefined) {
     const { storeRoot: projectRoot, executionRoot } = roots;
     if (paths.length === 0) {
         return {
@@ -1195,6 +1204,16 @@ async function validateFiles(paths, roots, taskId, commitShaFor, requireCommitAr
             content = await gitShowFileContentAtCommit(p, commitSha, executionRoot);
         }
         if (requireCommitArtifact && content === null) {
+            const deleter = deletedBy(p);
+            if (deleter !== undefined)
+                // @sync-invariant none:input-shape a files: path the PR deleted is refused before anything is written
+                return {
+                    ok: false,
+                    codeName: 'E_EVIDENCE_INVALID',
+                    reason: `${p} was deleted by ${deleter.prNumber !== undefined ? `PR #${deleter.prNumber}` : 'the PR'}, ` +
+                        `so its merge ${deleter.mergeCommitSha} holds no bytes to inspect. Leave it out of files: ` +
+                        '(name the deletion in note: if it matters); files: lists artifacts the PR changed and kept.',
+                };
             return {
                 ok: false,
                 codeName: 'E_EVIDENCE_INSUFFICIENT',
@@ -1389,12 +1408,16 @@ async function runAffectedTests(tool, run, roots, taskId) {
         executionRoot,
         semaphoreOptions: { scope: 'affected', ...(taskId !== undefined ? { task: taskId } : {}) },
     });
+    const label = `tool:${tool} (affected: ${[run.command.cmd, ...run.command.args].join(' ')})`;
+    // T13013: an OOM or signal kill is reported as a kill, never as failing tests.
+    const killed = result.timedOut ? null : killedValidation(label, run.command.canonical, result);
+    if (killed !== null)
+        return killed;
     if (result.exitCode !== 0) {
         return {
             ok: false,
             codeName: result.timedOut ? 'E_EVIDENCE_TOOL_TIMEOUT' : 'E_EVIDENCE_TOOL_FAILED',
-            reason: `tool:${tool} (affected: ${[run.command.cmd, ...run.command.args].join(' ')}) exited ${result.exitCode}: ${(result.stderrTail || result.stdoutTail).trim().slice(-300)}` +
-                (result.signal !== null || result.resourceKill !== null ? resourcePlanNote(result) : ''),
+            reason: `${label} exited ${result.exitCode}: ${(result.stderrTail || result.stdoutTail).trim().slice(-300)}`,
         };
     }
     return {
@@ -1414,7 +1437,7 @@ async function runAffectedTests(tool, run, roots, taskId) {
             ...(run.testFiles ? { affectedTestFiles: run.testFiles } : {}),
             ...(run.configPaths ? { configPaths: run.configPaths } : {}),
             ...(run.untested.length > 0 ? { untestedPackages: run.untested } : {}),
-            ...toolRunAtomFields(result),
+            ...(await toolRunAtomFields(result)),
         },
     };
 }
@@ -1543,14 +1566,13 @@ hints = {}) {
     }
     return projectRoot;
 }
-async function validateTestRun(path, roots, taskId) {
+/**
+ * Resolve, read and parse a `test-run:` report. gh#1226: a relative path
+ * names a report the caller just wrote, in the caller's tree, so the
+ * execution root is tried before the store root.
+ */
+async function readTestRunReport(path, roots) {
     const { storeRoot: projectRoot, executionRoot } = roots;
-    // gh#1226: a relative test-run path names a report the caller just wrote,
-    // in the caller's tree. Resolving it against the shared store root made a
-    // report written in a worktree report "file does not exist". Try the
-    // execution root first, then fall back to the store root so an absolute or
-    // store-relative path keeps working. gh#1365: the root arrives as a
-    // parameter now; it is NOT re-resolved here.
     let abs;
     if (isAbsolute(path)) {
         abs = path;
@@ -1578,10 +1600,8 @@ async function validateTestRun(path, roots, taskId) {
             codeName: 'E_EVIDENCE_INVALID',
         };
     }
-    const sha256 = createHash('sha256').update(content).digest('hex');
-    let parsed;
     try {
-        parsed = JSON.parse(content.toString('utf-8'));
+        return { ok: true, abs, content, parsed: JSON.parse(content.toString('utf-8')) };
     }
     catch (err) {
         return {
@@ -1590,6 +1610,22 @@ async function validateTestRun(path, roots, taskId) {
             codeName: 'E_EVIDENCE_INVALID',
         };
     }
+}
+/**
+ * Validate a `test-run:` report: its counts, then bound to the change.
+ * `siblings` are every `test-run:` path of the same evidence write (T14031):
+ * the change's coverage is judged over the test files all of them passed, so
+ * a vitest report and a Playwright report together cover unit and e2e files.
+ * Each sibling is still validated on its own by its own atom.
+ */
+async function validateTestRun(path, roots, taskId, siblings = []) {
+    const { storeRoot: projectRoot, executionRoot } = roots;
+    const read = await readTestRunReport(path, roots);
+    if (!read.ok)
+        return read;
+    const { abs, content } = read;
+    let parsed = read.parsed;
+    const sha256 = createHash('sha256').update(content).digest('hex');
     if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
         return {
             ok: false,
@@ -1597,6 +1633,12 @@ async function validateTestRun(path, roots, taskId) {
             codeName: 'E_EVIDENCE_INVALID',
         };
     }
+    // T14031: a Playwright JSON report is read in the vitest shape.
+    const playwright = playwrightTestRun(parsed);
+    if (playwright !== null && 'refusal' in playwright)
+        return { ok: false, reason: playwright.refusal, codeName: playwright.codeName };
+    if (playwright !== null)
+        parsed = playwright;
     if (present(parsed.testResults) &&
         (!Array.isArray(parsed.testResults) ||
             parsed.testResults.some((tr) => tr === null || typeof tr !== 'object' || Array.isArray(tr)))) {
@@ -1614,7 +1656,7 @@ async function validateTestRun(path, roots, taskId) {
         return {
             ok: false,
             reason: `test-run report has no test counts. Expected one of: ${TEST_RUN_SHAPE_HINT}; ` +
-                "e.g. vitest's --reporter=json --outputFile, or " +
+                "e.g. vitest's --reporter=json --outputFile, Playwright's --reporter=json, or " +
                 '{"total":43,"passed":42,"failed":0,"skipped":1}',
             codeName: 'E_EVIDENCE_INVALID',
         };
@@ -1694,6 +1736,19 @@ async function validateTestRun(path, roots, taskId) {
     if (broken)
         return { ok: false, reason: broken, codeName: E_EVIDENCE_GIT_ROOT };
     const testFiles = coveredTestFiles(parsed, bindRoot);
+    // T14031: the other reports of this write cover the change with this one.
+    const siblingFiles = [];
+    for (const sibling of siblings) {
+        if (sibling === path)
+            continue;
+        const other = await readTestRunReport(sibling, roots);
+        if (!other.ok || other.parsed === null || typeof other.parsed !== 'object')
+            continue;
+        const adapted = playwrightTestRun(other.parsed);
+        if (adapted !== null && 'refusal' in adapted)
+            continue;
+        siblingFiles.push(...coveredTestFiles(adapted ?? other.parsed, bindRoot));
+    }
     // The tree hash is the tool cache's (T12958), so a bound test-run and a
     // cached tool run of the same content agree.
     const capture = await captureTree(bindRoot, await typedGateInputs(projectRoot, taskId, bindRoot));
@@ -1709,7 +1764,7 @@ async function validateTestRun(path, roots, taskId) {
     let typecheckDirs = [];
     let untrackedSetAside = [];
     if (identity) {
-        const binding = bindTestRunReport(parsed, abs, bindRoot, testFiles);
+        const binding = bindTestRunReport(parsed, abs, bindRoot, siblingFiles.length > 0 ? [...new Set([...testFiles, ...siblingFiles])].sort() : testFiles);
         if (!binding.ok)
             return { ok: false, reason: binding.reason, codeName: binding.codeName };
         untestedPackages = binding.untestedPackages;
@@ -1995,6 +2050,12 @@ async function validateConfigSchema(roots, context, siblingCommitSha) {
         const schema = JSON.parse(await readFile(schemaPath, 'utf-8'));
         for (const error of checkSchema(data, schema))
             failures.push(`${path}: ${error}`);
+        // T14039: a tool command that cannot run without a shell is a config error.
+        if (schemaName === 'project-context.schema.json') {
+            const { projectContextCommandProblems } = await import('./tool-resolver.js');
+            for (const problem of projectContextCommandProblems(data))
+                failures.push(`${path}: ${problem}`);
+        }
     }
     if (failures.length > 0)
         return {
@@ -2129,7 +2190,8 @@ async function validateTool(tool, roots, context, siblingCommitSha) {
         return {
             ok: false,
             reason: resolution.reason,
-            codeName: resolution.codeName === 'E_TOOL_UNKNOWN'
+            // T14039: a declared command with shell syntax is a config error, not a missing tool.
+            codeName: resolution.codeName === 'E_TOOL_UNKNOWN' || resolution.codeName === 'E_TOOL_COMMAND_INVALID'
                 ? 'E_EVIDENCE_INVALID'
                 : 'E_EVIDENCE_TOOL_UNAVAILABLE',
         };
@@ -2189,49 +2251,10 @@ async function validateTool(tool, roots, context, siblingCommitSha) {
             codeName: 'E_EVIDENCE_TOOL_BUSY',
         };
     }
-    // gh#1381: a tool KILLED after it started is a different fact from a tool
-    // that never started, and until the signal was bound in `spawnCmd` the two
-    // arrived here as the same `exitCode: null`. The message below used to say
-    // "binary missing or spawn error" for both — so an OOM-killed 41-minute test
-    // suite sent three separate operators hunting a binary that was present, and
-    // the one diagnostic that would have helped (you exceeded the memory
-    // ceiling) was the one fact discarded.
-    if (result.signal !== null) {
-        const limit = describeMemoryLimit(resolution.command.canonical);
-        return {
-            ok: false,
-            reason: `Tool "${tool}" → ${resolution.command.cmd} ${resolution.command.args.join(' ')} ` +
-                `RAN for ${Math.round(result.durationMs / 1000)}s in ${result.executionRoot} and was ` +
-                `KILLED by ${result.signal}. The binary is present and the command started — ` +
-                `this is not a resolution problem.${limit}${resourcePlanNote(result)} ` +
-                `Nothing was cached, so a retry re-runs the tool from scratch and will be killed ` +
-                `identically unless the cause is addressed.` +
-                (result.stdoutTail || result.stderrTail
-                    ? ` Last output before the kill: ${tailString(`${result.stdoutTail}\n${result.stderrTail}`, 512)}`
-                    : ''),
-            codeName: 'E_EVIDENCE_TOOL_KILLED',
-        };
-    }
-    // T12989: killed for resources with no signal reaching CLEO — a wrapper
-    // (`sh`, `pnpm`) reported the kill as exit 128 + n, or the runner caught a
-    // worker's heap OOM and exited 1. Reported as a failing suite, and cached
-    // as one, it replayed a 3 GB OOM to a retry given 6 GB.
-    if (result.resourceKill !== null) {
-        return {
-            ok: false,
-            reason: `Tool "${tool}" → ${resolution.command.cmd} ${resolution.command.args.join(' ')} ` +
-                `RAN for ${Math.round(result.durationMs / 1000)}s in ${result.executionRoot} and was ` +
-                `KILLED for resources (${result.resourceKill}). This is not a verdict on the code, ` +
-                `and nothing was cached.${resourcePlanNote(result)} Raise the heap with ` +
-                `${HEAVY_HEAP_ENV}=<MiB> (an inherited NODE_OPTIONS heap above the run's budget is ` +
-                `clamped, T13122) or lower the worker count with ${HEAVY_WORKERS_ENV}=<n>, and verify ` +
-                `again — both are part of the cache key, so the retry runs fresh.` +
-                (result.stdoutTail || result.stderrTail
-                    ? ` Last output: ${tailString(`${result.stdoutTail}\n${result.stderrTail}`, 512)}`
-                    : ''),
-            codeName: 'E_EVIDENCE_TOOL_KILLED',
-        };
-    }
+    // gh#1381 / T12989: killed after it started, for resources or by a signal.
+    const killed = killedValidation(`Tool "${tool}" → ${resolution.command.cmd} ${resolution.command.args.join(' ')}`, resolution.command.canonical, result);
+    if (killed !== null)
+        return killed;
     // gh#1397: CLEO wraps `test` and `build` in a systemd scope of its own
     // making (T12116). When that wrapper cannot start, `systemd-run` exits 1
     // WITHOUT ever running the tool — and 1 is also what a suite with a failing
@@ -2295,7 +2318,7 @@ async function validateTool(tool, roots, context, siblingCommitSha) {
             tool,
             exitCode: 0,
             stdoutTail: result.stdoutTail,
-            ...toolRunAtomFields(result),
+            ...(await toolRunAtomFields(result)),
             ...(fullScopeReason !== undefined
                 ? { scope: 'full', ...(fullScopeReason ? { scopeReason: fullScopeReason } : {}) }
                 : {}),
@@ -2308,9 +2331,13 @@ async function validateTool(tool, roots, context, siblingCommitSha) {
  * needed its one full retry — the `flaky` files, so a flaky pass stays
  * visible to gates instead of reading as a clean one.
  */
-function toolRunAtomFields(result) {
+async function toolRunAtomFields(result) {
+    // T13003: the HEAD the run measured, so boundHeadGapReason can refuse a run
+    // on a checkout that lacks the task's implemented commits.
+    const headSha = result.treeHash ? await captureHead(result.executionRoot) : null;
     return {
         ...(result.treeHash ? { treeHash: result.treeHash } : {}),
+        ...(headSha ? { headSha } : {}),
         cacheHit: result.cacheHit,
         ...(result.flaky ? { flaky: result.flaky } : {}),
         // T13122: the heap and worker count the run got, and why — including an
@@ -2322,6 +2349,48 @@ function toolRunAtomFields(result) {
  * One sentence naming the heap and worker plan a memory-bound tool ran under
  * (T13122), for a message about a kill; `''` for any other tool.
  */
+/**
+ * The `E_EVIDENCE_TOOL_KILLED` validation for a tool run that started and was
+ * killed, by a signal or for resources (a wrapper's exit 128 + n, a heap OOM
+ * the runner caught), else `null` (T13013). One message for every path that
+ * runs a tool (`tool:<name>`, the affected-tests run, `cleo done`), naming the
+ * systemd memory ceiling when one applies ({@link describeMemoryLimit}) and
+ * where the heap is really set.
+ *
+ * gh#1381: a tool killed after it started is a different fact from a tool
+ * that never started; "binary missing" sent operators hunting a binary that
+ * was present.
+ *
+ * @param label - How the run is named: `Tool "test" → pnpm run test`.
+ * @param canonical - The canonical tool, for the memory ceiling.
+ * @param result - The run.
+ * @returns The failed validation, or `null` when the run was not killed.
+ *
+ * @task T13013
+ */
+export function killedValidation(label, canonical, result) {
+    const how = result.signal !== null
+        ? `by ${result.signal}`
+        : result.resourceKill !== null
+            ? `for resources (${result.resourceKill})`
+            : null;
+    if (how === null)
+        return null;
+    const output = `${result.stdoutTail}\n${result.stderrTail}`.trim();
+    return {
+        ok: false,
+        reason: `${label} RAN for ${Math.round(result.durationMs / 1000)}s in ${result.executionRoot} and was ` +
+            `KILLED ${how}. The command started, so this is not a resolution problem and not a ` +
+            `verdict on the code; nothing was cached.${describeMemoryLimit(canonical)}` +
+            `${resourcePlanNote(result)} Raise the heap with ${HEAVY_HEAP_ENV}=<MiB> or lower the ` +
+            `worker count with ${HEAVY_WORKERS_ENV}=<n> (both are in the cache key, so the retry ` +
+            `runs fresh). A heap set by the test config (a vitest execArgv such as ` +
+            `--max-old-space-size in vitest.memory-safe) binds each worker and NODE_OPTIONS does ` +
+            `not override it: raise it there.` +
+            (output ? ` Last output: ${tailString(output, 512)}` : ''),
+        codeName: 'E_EVIDENCE_TOOL_KILLED',
+    };
+}
 function resourcePlanNote(result) {
     return result.resources ? ` It ran with ${result.resources.summary}.` : '';
 }
@@ -2738,12 +2807,17 @@ async function validatePrAtom(prNumber, roots, context, componentPrNumber) {
         restoredPaths = direct.restored;
     }
     if (context.gates.includes('implemented') &&
-        classifyEvidenceTask(context) === 'code' &&
+        classifyEvidenceTask({ ...context, changedPaths }) === 'code' &&
         changedPaths.every(isDocumentArtifact)) {
+        // T14065: name the supported reclassifications, not just the refusal.
         return {
             ok: false,
             codeName: 'E_EVIDENCE_CONTENT_MISMATCH',
-            reason: `PR #${linked.prNumber} changes only documentation and cannot implement code task ${context.task.id}. Changed artifacts: ${changedPaths.join(', ')}.`,
+            reason: `PR #${linked.prNumber} changes only documentation and cannot implement code task ${context.task.id}. ` +
+                `Changed artifacts: ${changedPaths.join(', ')}. If ${context.task.id} is a documentation task, ` +
+                `declare its documents with \`cleo update ${context.task.id} --files ${changedPaths.join(',')}\` ` +
+                `(declared documents decide), or label it with \`cleo update ${context.task.id} --add-labels docs\` ` +
+                'when it is not a bug and no declared file or acceptance criterion names code; then re-verify.',
         };
     }
     return {
@@ -2987,7 +3061,7 @@ export function checkTaskEvidenceContext(context, gate, atoms) {
                 return refusal;
         }
         if (gate === 'implemented' &&
-            classifyEvidenceTask(context) === 'code' &&
+            classifyEvidenceTask({ ...context, changedPaths: atom.changedPaths }) === 'code' &&
             atom.changedPaths.every(isDocumentArtifact))
             return 'Documentation-only PR evidence cannot implement the current code task.';
     }
@@ -3263,9 +3337,10 @@ 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:
+ * Why a `test-run:`/`qa-run:` result, or a `tool:` run (T13003), does not
+ * describe this task's work (T14004), or null. The binding records the HEAD it
+ * was bound to (a tool run, the HEAD it measured), 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.
@@ -3273,6 +3348,10 @@ export function composeGateEvidence(atoms, capturedBy, override, overrideReason,
  *   head: its recorded `headSha` (a squash merge too), else the merge's second
  *   parent. An earlier branch commit never saw the whole change.
  *
+ * "Seen" also holds when the HEAD carries a patch-equivalent commit
+ * (`git cherry`): a rebase or a message-only amend keeps the patch, not the
+ * SHA (T13003).
+ *
  * 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
@@ -3283,9 +3362,11 @@ export function composeGateEvidence(atoms, capturedBy, override, overrideReason,
  * @param projectRoot - The CLEO store root (the task's checkout is resolved from it).
  * @returns The refusal, or null.
  * @task T14004
+ * @task T13003
  */
 export async function boundHeadGapReason(task, atoms, projectRoot) {
-    const runs = atoms.filter((a) => (a.kind === 'test-run' || a.kind === 'qa-run') && typeof a.headSha === 'string');
+    const runs = atoms.filter((a) => (a.kind === 'test-run' || a.kind === 'qa-run' || a.kind === 'tool') &&
+        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');
@@ -3326,7 +3407,14 @@ export async function boundHeadGapReason(task, atoms, projectRoot) {
     };
     // 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);
+    // T13003: a rebased or amended copy of the commit (same patch) in the run's
+    // history. `git cherry` marks each commit of `sha^..sha` with `-` when the
+    // head has its patch; every one must be marked (merges have no patch).
+    const patchEquivalent = (head, sha) => {
+        const marks = (gitOut(['cherry', head, sha, `${sha}^`]) ?? '').split('\n').filter(Boolean);
+        return marks.length > 0 && marks.every((line) => line.startsWith('-'));
+    };
+    const reached = (head, sha) => sameCommit(head, sha) || contains(head, sha) || patchEquivalent(head, sha);
     // Only positive checks accept: the run head is, or contains, the work's tip.
     const sawWork = (head, atom) => {
         if (atom.kind === 'commit')
@@ -3348,7 +3436,9 @@ export async function boundHeadGapReason(task, atoms, projectRoot) {
         missing = null;
         if (implemented.every((atom) => sawWork(head, atom)))
             continue;
-        const bound = `${run.kind}:${run.path} was bound at ${head.slice(0, 12)}`;
+        const bound = run.kind === 'tool'
+            ? `tool:${run.tool} ran at ${head.slice(0, 12)}`
+            : `${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}). ` +
@@ -3379,6 +3469,8 @@ export async function boundHeadGapReason(task, atoms, projectRoot) {
  * 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.
+ * A task {@link declaredEvidenceKind} leaves undecided is classified by that
+ * same change set (T14048): documents only make it documentation.
  *
  * @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).
@@ -3390,9 +3482,11 @@ export async function boundHeadGapReason(task, atoms, projectRoot) {
  */
 export async function taskEvidenceKindReport(task, projectRoot, extraPaths = [], cwd, deps = {}) {
     const kind = classifyEvidenceTask({ task });
-    if (kind === 'code')
+    // T14048: a task its record leaves undecided is classified by what it changed.
+    const undecided = kind === 'code' && declaredEvidenceKind(task) === null;
+    if (kind === 'code' && !undecided)
         return { kind };
-    const code = (reason) => ({ kind: 'code', reason });
+    const code = (reason) => undecided ? { kind: 'code' } : { 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.
@@ -3420,6 +3514,8 @@ export async function taskEvidenceKindReport(task, projectRoot, extraPaths = [],
             paths.push(...files);
         }
     }
+    if (undecided)
+        return { kind: classifyEvidenceTask({ task, changedPaths: paths }) };
     const codePath = paths.find((path) => !isDocumentEvidencePath(path));
     return codePath === undefined ? { kind } : code(`its work touches ${codePath}`);
 }