@cleocode/core 2026.9.8 → 2026.9.10

package/dist/tasks/evidence.js

@@ -26,6 +26,7 @@ import { readFile, stat } from 'node:fs/promises';
 import { dirname, isAbsolute, join, resolve as resolvePath } from 'node:path';
 import { EvidenceParseError, ExitCode, GATE_EVIDENCE_REQUIREMENTS, parseEvidenceString, validateEvidenceForGate, } from '@cleocode/contracts';
 import { CleoError } from '../errors.js';
+import { describeUnusableEvidenceGitRoot, E_EVIDENCE_GIT_ROOT, findNestedGitWorkTrees, findWorkTreeContainingCommit, gitToplevel, isGitWorkTree, resolveDeclaredEvidenceGitRoot, } from '../git/work-tree.js';
 import { pushWarning } from '../output.js';
 import { getEffectiveHead } from '../worktree/effective-head.js';
 import { DISABLE_ENV, describeMemoryLimit } from './heavy-tool-limit.js';
@@ -132,26 +133,69 @@ export function parseEvidence(raw) {
         throw err;
     }
 }
+/**
+ * Validate a single parsed atom against the filesystem / git / tools.
+ *
+ * @param parsed - Parsed atom from {@link parseEvidence}
+ * @param projectRoot - Absolute path to project root (for resolving files, git)
+ * @param taskId - Optional CLEO task ID. When provided, enables branch-scope
+ *   check (T9178), content-intersect check (T9245), worktree-aware HEAD
+ *   resolution (T-WT-3), and git-show file fallback for branch-only files
+ *   (T11959).
+ * @param siblingCommitSha - Optional sha of a sibling `commit:` atom from the
+ *   same evidence string. When provided, `files:` paths are resolved against
+ *   that commit's tree FIRST (T12107 / gh#1195) before falling back to the
+ *   worktree and git refs — covers a merged commit whose files are not yet
+ *   present in the local checkout.
+ * @param context - Current task, gate and acceptance criteria used to validate scoped proof.
+ * @returns Validation outcome with canonicalised form on success
+ * @example
+ * ```ts
+ * const result = await validateAtom(parsedAtom, projectRoot, task.id, undefined, context);
+ * ```
+ *
+ * @task T832
+ * @task T11959
+ * @task T12107
+ * @adr ADR-051 §3
+ */
 export async function validateAtom(parsed, projectRoot, 
 /** T9178: When provided, validates commit is on task/<taskId> branch. */
 taskId, 
 /** T12107: sha of a sibling `commit:` atom in the same evidence string. */
-siblingCommitSha) {
+siblingCommitSha, context) {
+    if (parsed.kind === 'pr' && (!Number.isInteger(parsed.prNumber) || parsed.prNumber <= 0)) {
+        return {
+            ok: false,
+            codeName: 'E_EVIDENCE_INVALID',
+            reason: 'PR number must be a positive integer.',
+        };
+    }
     // gh#1365: resolve the tree under test ONCE, here, and pass it down as a
     // required parameter. Resolving inside each validator would centralise the
     // logic but still let two of them resolve independently and drift — which is
     // exactly how gh#1419 happened (a revalidation key derived from one root
     // while the validation answered about another). A required parameter makes
     // that divergence unrepresentable rather than merely discouraged.
+    // T12308: hand the resolver the SHA this evidence is about so a CLEO root
+    // that parents several repositories resolves itself. `files:` atoms carry no
+    // SHA of their own, so the sibling `commit:`/`pr:` anchor supplies it — the
+    // same anchor `validateFiles` already uses to read bytes at that commit.
+    const executionRootHints = {
+        ...(parsed.kind === 'commit' ? { commitSha: parsed.sha } : {}),
+        ...(parsed.kind === 'files' && (context?.artifactCommitSha ?? siblingCommitSha) !== undefined
+            ? { commitSha: (context?.artifactCommitSha ?? siblingCommitSha) }
+            : {}),
+    };
     const roots = {
         storeRoot: projectRoot,
-        executionRoot: resolveEvidenceExecutionRoot(projectRoot),
+        executionRoot: resolveEvidenceExecutionRoot(projectRoot, undefined, executionRootHints),
     };
     switch (parsed.kind) {
         case 'commit':
             return validateCommit(parsed.sha, roots, taskId);
         case 'files':
-            return validateFiles(parsed.paths, roots, taskId, siblingCommitSha);
+            return validateFiles(parsed.paths, roots, taskId, context?.artifactCommitSha ?? siblingCommitSha, Boolean(context?.artifactCommitSha));
         case 'test-run':
             return validateTestRun(parsed.path, roots);
         case 'tool':
@@ -173,7 +217,7 @@ siblingCommitSha) {
             // db, which is CLEO's own record, not the repository's.
             return validateDecision(parsed.decisionId, roots);
         case 'pr':
-            return validatePrAtom(parsed.prNumber, roots);
+            return validatePrAtom(parsed.prNumber, roots, context);
         case 'satisfies': {
             // ADR-079-r2: 5-check validator pipeline shipped by T10507.
             // Delegates to the dedicated validator module to keep the dispatch
@@ -309,15 +353,17 @@ function resolveIntegrationBranches(env, projectContext) {
  *
  * Checking the remote-tracking ref preserves verification after a merged local
  * integration branch has been cleaned up.
+ *
+ * @param executionRoot - The repo the evidence is about, never the store root.
  */
-async function findReachableIntegrationBranch(sha, branches, projectRoot) {
+async function findReachableIntegrationBranch(sha, branches, executionRoot) {
     for (const branch of branches) {
         const refs = [`refs/heads/${branch}`, `refs/remotes/origin/${branch}`];
         for (const ref of refs) {
-            const exists = await runCommand('git', ['rev-parse', '--verify', ref], projectRoot);
+            const exists = await runCommand('git', ['rev-parse', '--verify', ref], executionRoot);
             if (exists.exitCode !== 0)
                 continue;
-            const reachable = await runCommand('git', ['merge-base', '--is-ancestor', sha, ref], projectRoot);
+            const reachable = await runCommand('git', ['merge-base', '--is-ancestor', sha, ref], executionRoot);
             if (reachable.exitCode === 0)
                 return branch;
         }
@@ -333,6 +379,17 @@ async function validateCommit(sha, roots, taskId) {
             codeName: 'E_EVIDENCE_INVALID',
         };
     }
+    // gh#1462: without a work tree every git call below fails, and the first one
+    // (`cat-file`) reported it as "Commit not found in repository" — which says
+    // the commit is absent, not that git never ran in a repository at all. Same
+    // distinction `pr:` needs, so it fails the same way.
+    if (!isGitWorkTree(executionRoot)) {
+        return {
+            ok: false,
+            reason: describeUnusableEvidenceGitRoot(projectRoot, executionRoot),
+            codeName: E_EVIDENCE_GIT_ROOT,
+        };
+    }
     const exists = await runCommand('git', ['cat-file', '-e', `${sha}^{commit}`], executionRoot);
     if (exists.exitCode !== 0) {
         return {
@@ -352,7 +409,7 @@ async function validateCommit(sha, roots, taskId) {
     const { loadProjectContext } = await import('../agents/variable-substitution.js');
     const projectCtx = loadProjectContext(projectRoot);
     const integrationBranches = resolveIntegrationBranches(process.env, projectCtx.loaded ? projectCtx.context : null);
-    const reachable = await runCommand('git', ['merge-base', '--is-ancestor', sha, effectiveHead], projectRoot);
+    const reachable = await runCommand('git', ['merge-base', '--is-ancestor', sha, effectiveHead], executionRoot);
     if (reachable.exitCode !== 0) {
         // DHQ-083 companion (a): when the commit is not reachable from the task
         // branch HEAD, also accept commits reachable from the configured
@@ -398,7 +455,7 @@ async function validateCommit(sha, roots, taskId) {
         const branchRef = `task/${taskId}`;
         const branchExists = await runCommand('git', ['rev-parse', '--verify', branchRef], executionRoot);
         if (branchExists.exitCode === 0) {
-            const onBranch = await runCommand('git', ['merge-base', '--is-ancestor', sha, branchRef], projectRoot);
+            const onBranch = await runCommand('git', ['merge-base', '--is-ancestor', sha, branchRef], executionRoot);
             if (onBranch.exitCode !== 0) {
                 // T11959 / DHQ-083 companion (a): also accept commits reachable from
                 // the configured integration branches. This covers:
@@ -406,7 +463,7 @@ async function validateCommit(sha, roots, taskId) {
                 //   - post-merge task branches that have been cleaned up (the SHA is now
                 //     only reachable from main, not from `task/<id>` which no longer exists)
                 // gh#1116 / T12028: reuses the integrationBranches resolved above.
-                const reachableIntegrationBranch = await findReachableIntegrationBranch(sha, integrationBranches, projectRoot);
+                const reachableIntegrationBranch = await findReachableIntegrationBranch(sha, integrationBranches, executionRoot);
                 if (reachableIntegrationBranch === null) {
                     const branchList = integrationBranches.join(', ');
                     return {
@@ -418,14 +475,16 @@ async function validateCommit(sha, roots, taskId) {
             }
         }
         // T9245: content-intersect check — diff MUST touch at least one AC file.
-        const intersectResult = await checkCommitContentIntersect(sha, taskId, projectRoot);
+        // gh#1462: the task row comes from the store, the diff from the repo under
+        // test — both roots, like every other mixed read on this switch.
+        const intersectResult = await checkCommitContentIntersect(sha, taskId, roots);
         if (!intersectResult.ok) {
             return intersectResult;
         }
     }
-    const short = await runCommand('git', ['rev-parse', '--short', sha], projectRoot);
+    const short = await runCommand('git', ['rev-parse', '--short', sha], executionRoot);
     const shortSha = short.stdout.trim() || sha.slice(0, 7);
-    const full = await runCommand('git', ['rev-parse', sha], projectRoot);
+    const full = await runCommand('git', ['rev-parse', sha], executionRoot);
     const fullSha = full.stdout.trim() || sha;
     return { ok: true, atom: { kind: 'commit', sha: fullSha, shortSha } };
 }
@@ -850,27 +909,26 @@ export function resolveCanonicalProjectRoot(projectRoot) {
  * Fix (T-WT-2): This function calls `resolveCanonicalProjectRoot(projectRoot)`
  * to obtain the main repo root before opening `tasks.db`. The canonical main
  * DB is authoritative for all task metadata reads during gate verification.
- * Git operations (`gitShowFiles`) continue to use `projectRoot` as `cwd` —
- * git resolves commits correctly from any directory sharing the object store.
+ * Git operations (`gitShowFiles`) use `executionRoot` — the repo the evidence is
+ * about, which gh#1462 showed is not necessarily the store root.
  *
  * @param sha - Commit SHA whose diff is inspected.
  * @param taskId - CLEO task ID used to load AC file declarations.
- * @param projectRoot - Absolute path for git operations (may be worktree path).
- *   DB reads use `resolveCanonicalProjectRoot(projectRoot)` internally.
+ * @param roots - Store root for the task row, execution root for the diff.
  *
  * @internal
  * @task T9245
  * @task T-WT-2
+ * @task gh#1462
  * @adr ADR-051-worktree-extension
  */
-async function checkCommitContentIntersect(sha, taskId, projectRoot) {
+async function checkCommitContentIntersect(sha, taskId, roots) {
+    const { storeRoot, executionRoot } = roots;
     // BUG-C FIX (T-WT-2 / E-WORKTREE-IVTR): always read task metadata from the
-    // canonical (main) repository DB. When projectRoot is a worktree path the
+    // canonical (main) repository DB. When the store root is a worktree path the
     // worktree's tasks.db is a stale spawn-time snapshot; the main DB is the
-    // authoritative source for task.files and task.acceptance. git operations
-    // below (gitShowFiles) still use the original projectRoot — git shares its
-    // object store across worktrees, so any dir in the shared tree works.
-    const canonicalRoot = resolveCanonicalProjectRoot(projectRoot);
+    // authoritative source for task.files and task.acceptance.
+    const canonicalRoot = resolveCanonicalProjectRoot(storeRoot);
     // Best-effort load — DB unavailability MUST NOT block verify.
     let task = null;
     try {
@@ -906,7 +964,7 @@ async function checkCommitContentIntersect(sha, taskId, projectRoot) {
      * is still reported; it just cannot fail the gate.
      */
     const enforcing = provenance === 'declared';
-    const diffFiles = await gitShowFiles(sha, projectRoot);
+    const diffFiles = await gitShowFiles(sha, executionRoot);
     const acPreview = `${acFiles.slice(0, 5).join(', ')}${acFiles.length > 5 ? '…' : ''}`;
     if (diffFiles.length === 0) {
         const reason = `Commit ${sha.slice(0, 7)} touches no files — cannot satisfy implemented gate ` +
@@ -1026,7 +1084,7 @@ async function gitShowFileContentAtCommit(relPath, sha, projectRoot) {
  * @task T11959
  * @task T12107
  */
-async function validateFiles(paths, roots, taskId, commitSha) {
+async function validateFiles(paths, roots, taskId, commitSha, requireCommitArtifact = false) {
     const { storeRoot: projectRoot, executionRoot } = roots;
     if (paths.length === 0) {
         return {
@@ -1051,6 +1109,13 @@ async function validateFiles(paths, roots, taskId, commitSha) {
         if (commitSha) {
             content = await gitShowFileContentAtCommit(p, commitSha, executionRoot);
         }
+        if (requireCommitArtifact && content === null) {
+            return {
+                ok: false,
+                codeName: 'E_EVIDENCE_INSUFFICIENT',
+                reason: `Cannot inspect ${p} at PR merge ${commitSha}; fetch that commit before recording evidence. Current checkout bytes cannot substitute.`,
+            };
+        }
         if (content === null && existsSync(abs)) {
             // Happy path — file exists on disk.
             const st = await stat(abs);
@@ -1109,11 +1174,38 @@ async function validateFiles(paths, roots, taskId, commitSha) {
  * pointing at a tmpdir, a non-git cwd) falls back to `projectRoot`, so
  * single-checkout behaviour is bit-for-bit unchanged.
  *
+ * gh#1462 added the other direction: when `projectRoot` is a PARENT of the
+ * checkout, neither the caller's cwd (which is that parent) nor `projectRoot`
+ * is a git work tree, and `gh`/`git` run there fail with "fatal: not a git
+ * repository". The checkout is a direct child in that layout, so it is used
+ * when exactly one child is a work tree.
+ *
+ * T12308 closed the two holes that layout still had. A root parenting SEVERAL
+ * repositories — the reported case had thirteen — had no resolution at all,
+ * and the remediation the failure printed (`GIT_DIR`/`GIT_WORK_TREE`) could not
+ * work, because the guard asks whether the CURRENT DIRECTORY is in a work tree
+ * and the CLEO root never is. So the order is now, most to least specific:
+ *
+ *  1. an operator declaration (`CLEO_EVIDENCE_GIT_ROOT`, `GIT_WORK_TREE`, or
+ *     `evidence.gitRoot` in `.cleo/project-context.json`) — honoured by
+ *     RUNNING there, which is what the old advice never did;
+ *  2. the caller's own checkout, when it belongs to this project;
+ *  3. `projectRoot` itself;
+ *  4. the one child checkout, or — when the evidence names a commit — the one
+ *     child checkout that actually CONTAINS it, which resolves a multi-repo
+ *     root with no configuration at all.
+ *
+ * Anything still ambiguous keeps `projectRoot`, and the atom reports the
+ * candidates by name rather than attesting against a guessed repository.
+ *
  * @param projectRoot - Absolute CLEO store root.
  * @param cwd - Directory the CLI was invoked from. Defaults to `process.cwd()`.
+ * @param hints - What the evidence itself reveals about which repo it is about.
  * @returns Absolute path of the tree to execute in.
  *
  * @task T12112 (gh#1220, gh#1226, gh#1230)
+ * @task gh#1462
+ * @task T12308
  */
 export function resolveEvidenceExecutionRoot(projectRoot, 
 // This function's entire purpose is to recover the tree the CLI was INVOKED
@@ -1124,20 +1216,27 @@ export function resolveEvidenceExecutionRoot(projectRoot,
 // while every test stayed green. The bare cwd is the only correct source,
 // and it only LOCATES a candidate; the same-project check below decides
 // whether it is honoured.
-cwd = process.cwd()) {
-    let toplevel;
+cwd = process.cwd(), // CWD-OK: the caller's invocation dir is the subject, not a stand-in for the project root (gh#1220)
+hints = {}) {
+    // T12308: an explicit declaration outranks every inference. Returned even
+    // when it is NOT a work tree, so the guard can reject it BY NAME — silently
+    // falling back would measure a different checkout than the operator named
+    // and attest the result as if it were theirs.
+    const declared = resolveDeclaredEvidenceGitRoot(projectRoot);
+    if (declared !== null)
+        return gitToplevel(declared.path) ?? declared.path;
+    let toplevel = null;
     try {
-        toplevel = execFileSync('git', ['rev-parse', '--show-toplevel'], {
-            cwd,
-            encoding: 'utf-8',
-            stdio: ['ignore', 'pipe', 'ignore'],
-        }).trim();
+        toplevel =
+            execFileSync('git', ['rev-parse', '--show-toplevel'], {
+                cwd,
+                encoding: 'utf-8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+            }).trim() || null;
     }
     catch {
-        return projectRoot; // not a git checkout — nothing better to offer
+        toplevel = null; // not a git checkout — try the store root and its children
     }
-    if (!toplevel)
-        return projectRoot;
     const sameProject = (a, b) => {
         const norm = (x) => {
             try {
@@ -1150,8 +1249,27 @@ cwd = process.cwd()) {
         return norm(a) === norm(b);
     };
     // Only redirect when the caller's tree is a worktree OF this project.
-    if (sameProject(resolveCanonicalProjectRoot(toplevel), projectRoot))
+    if (toplevel !== null && sameProject(resolveCanonicalProjectRoot(toplevel), projectRoot)) {
         return toplevel;
+    }
+    // The ordinary single-project layout: the CLEO root IS the checkout.
+    if (isGitWorkTree(projectRoot))
+        return projectRoot;
+    // gh#1462: the CLEO root is a PARENT of the checkout. `gh` and `git` run
+    // from `projectRoot` fail with "fatal: not a git repository", which reads as
+    // a broken tool or an unsatisfiable atom. Use the one direct child that is a
+    // work tree; ambiguity is reported, not guessed.
+    const candidates = findNestedGitWorkTrees(projectRoot);
+    if (candidates.length === 1)
+        return candidates[0];
+    // T12308: several children. The atom itself can still identify one — a SHA
+    // exists in exactly one of these repositories in every layout that is not a
+    // fork of itself. Zero or several matches stay unresolved.
+    if (candidates.length > 1 && hints.commitSha !== undefined) {
+        const byCommit = findWorkTreeContainingCommit(candidates, hints.commitSha);
+        if (byCommit !== null)
+            return byCommit;
+    }
     return projectRoot;
 }
 async function validateTestRun(path, roots) {
@@ -1703,7 +1821,14 @@ async function validateDecision(decisionId, roots) {
  *
  * @task T9764
  */
-async function validatePrAtom(prNumber, roots) {
+async function validatePrAtom(prNumber, roots, context) {
+    if (!context) {
+        return {
+            ok: false,
+            codeName: 'E_EVIDENCE_INSUFFICIENT',
+            reason: 'PR evidence requires current task, gate, and acceptance-criterion context.',
+        };
+    }
     // Dynamic import keeps the verification module free of a static dependency
     // on the release subtree, mirroring the pattern used by validateDecision.
     const { resolvePrEvidenceAtom } = await import('../release/pr-evidence.js');
@@ -1727,6 +1852,33 @@ async function validatePrAtom(prNumber, roots) {
     if (!result.ok) {
         return { ok: false, reason: result.reason, codeName: result.codeName };
     }
+    if (result.changedFileCount !== result.changedPaths.length || result.changedPaths.length === 0) {
+        return {
+            ok: false,
+            codeName: 'E_EVIDENCE_INSUFFICIENT',
+            reason: `PR #${prNumber} changed-file coverage is incomplete or empty (${result.changedPaths.length}/${result.changedFileCount}); inspect the full diff before recording evidence.`,
+        };
+    }
+    const declaredFiles = context.task.files ?? [];
+    const taskMention = new RegExp(`(^|[^A-Za-z0-9])${context.task.id}([^A-Za-z0-9]|$)`);
+    const explicitlyLinked = taskMention.test(`${result.title}\n${result.body}\n${result.headRefName}`);
+    const scopeIntersects = declaredFiles.length > 0 && diffIntersectsAc(result.changedPaths, declaredFiles);
+    if ((!explicitlyLinked && !scopeIntersects) || (declaredFiles.length > 0 && !scopeIntersects)) {
+        return {
+            ok: false,
+            codeName: 'E_EVIDENCE_CONTENT_MISMATCH',
+            reason: `PR #${prNumber} does not establish a relationship to task ${context.task.id}. Changed artifacts: ${result.changedPaths.join(', ')}. Declare task files or cite the exact task in the PR; declared scope must intersect the diff.`,
+        };
+    }
+    if (context.gates.includes('implemented') &&
+        classifyEvidenceTask(context) === 'code' &&
+        result.changedPaths.every(isDocumentArtifact)) {
+        return {
+            ok: false,
+            codeName: 'E_EVIDENCE_CONTENT_MISMATCH',
+            reason: `PR #${prNumber} changes only documentation and cannot implement code task ${context.task.id}. Changed artifacts: ${result.changedPaths.join(', ')}.`,
+        };
+    }
     return {
         ok: true,
         atom: {
@@ -1736,9 +1888,79 @@ async function validatePrAtom(prNumber, roots) {
             mergedAt: result.mergedAt,
             successCount: result.successCount,
             totalChecks: result.totalChecks,
+            changedPaths: result.changedPaths,
+            taskId: context.task.id,
         },
     };
 }
+function isDocumentArtifact(path) {
+    return (/\.(md|mdx|rst|adoc|txt)$/i.test(path) ||
+        /(?:^|\/)(README|LICENSE|CHANGELOG)(?:\.[^/]*)?$/i.test(path));
+}
+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';
+}
+/**
+ * Require explicit criterion linkage to inspected artifacts and real gate results.
+ * @param context - Current task classification, requested gates and criterion records.
+ * @param gate - Individual gate whose evidence is being assessed.
+ * @param atoms - Independently validated artifacts, results and criterion references.
+ * @returns A refusal reason when proof is insufficient, otherwise null.
+ * @remarks PR state and CI provenance alone cannot establish every acceptance gate.
+ * @example
+ * ```ts
+ * const refusal = checkTaskEvidenceContext(context, "implemented", validatedAtoms);
+ * ```
+ */
+export function checkTaskEvidenceContext(context, gate, atoms) {
+    const filePaths = atoms.flatMap((atom) => atom.kind === 'files' ? atom.files.map((file) => file.path) : []);
+    const prAtoms = atoms.filter((atom) => atom.kind === 'pr');
+    if (prAtoms.length > 1)
+        return 'Record one PR and its merge-pinned artifacts per verification attempt; multiple merge identities are ambiguous.';
+    for (const atom of prAtoms) {
+        if (atom.taskId !== context.task.id || !atom.changedPaths?.length)
+            return 'PR provenance lacks verified task scope; re-verify with current task context.';
+        if (gate === 'implemented' && !filePaths.some((path) => atom.changedPaths?.includes(path)))
+            return `PR #${atom.prNumber} requires files evidence for an artifact actually changed by that PR.`;
+        if (gate === 'implemented' &&
+            classifyEvidenceTask(context) === 'code' &&
+            atom.changedPaths.every(isDocumentArtifact))
+            return 'Documentation-only PR evidence cannot implement the current code task.';
+    }
+    if (!['implemented', 'testsPassed', 'qaPassed'].includes(gate))
+        return null;
+    if (classifyEvidenceTask(context) === 'code' &&
+        (gate === 'testsPassed' || gate === 'qaPassed') &&
+        !atoms.some((atom) => atom.kind === 'test-run' || (atom.kind === 'tool' && !atom.notApplicable))) {
+        return `Code task ${context.task.id} requires an actual verification result for ${gate}; absence of a toolchain is not a passing result.`;
+    }
+    const linked = atoms.filter((atom) => atom.kind === 'satisfies' && atom.targetTaskId === context.task.id);
+    if (context.criteria.length > 0 && linked.length === 0)
+        return `Task ${context.task.id} requires explicit criterion linkage: add satisfies:${context.task.id}#AC<n> alongside artifacts and verification results.`;
+    for (const atom of linked) {
+        if (!context.criteria.some((criterion) => criterion.id === atom.resolvedAcUuid))
+            return `Criterion ${atom.resolvedAcUuid ?? atom.targetAcAlias} is not in the current task criteria.`;
+    }
+    if (linked.length > 0 &&
+        gate === 'implemented' &&
+        filePaths.length === 0 &&
+        !atoms.some((atom) => atom.kind === 'decision'))
+        return 'Criterion implementation evidence requires inspected files or a sourced research decision.';
+    if (classifyEvidenceTask(context) === 'code' &&
+        gate === 'implemented' &&
+        atoms.some((atom) => atom.kind === 'decision') &&
+        !atoms.some((atom) => atom.kind === 'commit' || atom.kind === 'pr'))
+        return 'A research decision alone cannot implement a code-fix task.';
+    return null;
+}
 /**
  * Check that the provided evidence atoms satisfy the callsite-coverage
  * requirement for tasks carrying the `callsite-coverage` label.
@@ -1881,11 +2103,13 @@ export function checkGateEvidenceMinimumDetailed(gate, atoms) {
  * @param capturedBy - Agent identifier
  * @param override - True when CLEO_OWNER_OVERRIDE is set
  * @param overrideReason - Reason supplied with the override
+ * @param context - Task and criterion context used to capture durable proof bindings.
+ * @param gate - Gate associated with the captured result and artifact references.
  * @returns Canonical GateEvidence ready to persist
  *
  * @task T832
  */
-export function composeGateEvidence(atoms, capturedBy, override, overrideReason) {
+export function composeGateEvidence(atoms, capturedBy, override, overrideReason, context, gate) {
     const result = {
         atoms,
         capturedAt: new Date().toISOString(),
@@ -1896,6 +2120,34 @@ export function composeGateEvidence(atoms, capturedBy, override, overrideReason)
         if (overrideReason)
             result.overrideReason = overrideReason;
     }
+    if (context && gate) {
+        const linkedIds = new Set(atoms.flatMap((atom) => atom.kind === 'satisfies' && atom.targetTaskId === context.task.id && atom.resolvedAcUuid
+            ? [atom.resolvedAcUuid]
+            : []));
+        const artifactPaths = atoms.flatMap((atom) => atom.kind === 'files' ? atom.files.map((file) => file.path) : []);
+        const resultAtomIndices = atoms.flatMap((atom, index) => {
+            if (gate === 'implemented')
+                return atom.kind === 'commit' || atom.kind === 'pr' || atom.kind === 'decision'
+                    ? [index]
+                    : [];
+            return atom.kind === 'tool' || atom.kind === 'test-run' ? [index] : [];
+        });
+        result.scope = {
+            taskId: context.task.id,
+            gate,
+            classification: classifyEvidenceTask(context),
+            criteria: context.criteria
+                .filter((criterion) => linkedIds.has(criterion.id))
+                .map((criterion) => ({
+                criterionId: criterion.id,
+                criterionHash: createHash('sha256').update(criterion.text).digest('hex'),
+                artifactPaths: artifactPaths.length
+                    ? artifactPaths
+                    : (context.task.verification?.evidence?.implemented?.scope?.criteria.find((link) => link.criterionId === criterion.id)?.artifactPaths ?? []),
+                resultAtomIndices,
+            })),
+        };
+    }
     return result;
 }
 /**
@@ -1964,6 +2216,42 @@ export function isHardAtom(atom) {
  * @adr ADR-051 §5 / §8 (Decision 8)
  */
 export async function revalidateEvidence(evidence, projectRoot, gate, taskId, options) {
+    if (taskId && gate && !evidence.override) {
+        const { getTaskAccessor } = await import('../store/data-accessor.js');
+        const accessor = await getTaskAccessor(resolveCanonicalProjectRoot(projectRoot));
+        const task = await accessor.loadSingleTask(taskId);
+        if (!task)
+            throw new CleoError(ExitCode.NOT_FOUND, `Evidence task ${taskId} is missing`);
+        const context = {
+            task,
+            gates: [gate],
+            criteria: await accessor.getAcRows(taskId),
+        };
+        let reason = checkTaskEvidenceContext(context, gate, evidence.atoms);
+        if (!reason &&
+            !(classifyEvidenceTask(context) !== 'code' &&
+                isDecisionOnlyImplementation(task.verification?.evidence?.implemented) &&
+                DECISION_ONLY_INAPPLICABLE_GATES.includes(gate))) {
+            reason = checkGateEvidenceMinimum(gate, evidence.atoms);
+        }
+        if (!reason && evidence.scope) {
+            if (evidence.scope.taskId !== taskId || evidence.scope.gate !== gate)
+                reason = 'Evidence scope does not match the current task and gate.';
+            for (const link of evidence.scope.criteria) {
+                const criterion = context.criteria.find((row) => row.id === link.criterionId);
+                if (!criterion ||
+                    createHash('sha256').update(criterion.text).digest('hex') !== link.criterionHash)
+                    reason = `Criterion ${link.criterionId} changed after verification; record fresh evidence.`;
+            }
+        }
+        if (reason)
+            return {
+                stillValid: false,
+                failedAtoms: [
+                    { atom: evidence.atoms[0] ?? { kind: 'note', note: 'missing evidence' }, reason },
+                ],
+            };
+    }
     // T9245: critical-gate override rejection.
     // When the gate is `implemented` or `testsPassed`, evidence that has no
     // non-override hard atom is rejected outright. We define "override-only"
@@ -2004,7 +2292,11 @@ export async function revalidateEvidence(evidence, projectRoot, gate, taskId, op
                 const startedAt = Date.now();
                 const cached = await revalidateCommitAtom(atom.sha, {
                     storeRoot: projectRoot,
-                    executionRoot: resolveEvidenceExecutionRoot(projectRoot),
+                    // T12308: same hint as validation used, so a multi-repo root cannot
+                    // verify green and then re-validate against a different sibling.
+                    executionRoot: resolveEvidenceExecutionRoot(projectRoot, undefined, {
+                        commitSha: atom.sha,
+                    }),
                 });
                 if (!cached.check.ok)
                     failed.push({ atom, reason: cached.check.reason });
@@ -2022,12 +2314,21 @@ export async function revalidateEvidence(evidence, projectRoot, gate, taskId, op
                 // checked FIRST (the file may still be absent from the local checkout
                 // at complete time when local main was never fast-forwarded).
                 const siblingCommit = evidence.atoms.find((a) => a.kind === 'commit');
-                const siblingCommitSha = siblingCommit?.sha;
+                const siblingPr = evidence.atoms.find((atom) => atom.kind === 'pr');
+                const siblingCommitSha = siblingPr?.mergeCommitSha ?? siblingCommit?.sha;
+                const executionRoot = resolveEvidenceExecutionRoot(projectRoot, undefined, siblingCommitSha === undefined ? {} : { commitSha: siblingCommitSha });
                 for (const f of atom.files) {
-                    const abs = isAbsolute(f.path) ? f.path : resolvePath(projectRoot, f.path);
+                    const abs = isAbsolute(f.path) ? f.path : resolvePath(executionRoot, f.path);
                     let content = null;
                     if (siblingCommitSha) {
-                        content = await gitShowFileContentAtCommit(f.path, siblingCommitSha, projectRoot);
+                        content = await gitShowFileContentAtCommit(f.path, siblingCommitSha, executionRoot);
+                    }
+                    if (siblingPr && content === null) {
+                        failed.push({
+                            atom,
+                            reason: `Cannot inspect ${f.path} at recorded PR merge ${siblingCommitSha}; current checkout bytes cannot substitute.`,
+                        });
+                        continue;
                     }
                     if (!content && existsSync(abs)) {
                         content = await readFile(abs);
@@ -2036,7 +2337,7 @@ export async function revalidateEvidence(evidence, projectRoot, gate, taskId, op
                         // T11959: git-show fallback — file may have been on task branch at
                         // verify time and is now on main after merge, or it may still only
                         // exist on the branch. Use the same resolution path as validateFiles.
-                        content = await gitShowFileContent(f.path, taskId, projectRoot);
+                        content = await gitShowFileContent(f.path, taskId, executionRoot);
                     }
                     if (!content) {
                         failed.push({ atom, reason: `File removed since verify: ${f.path}` });