@moretea-labs/forge 1.6.0 → 1.7.0

package/src/runtime/control-plane/execution/work-handle-store.ts

@@ -3,6 +3,7 @@ import { existsSync } from 'fs';
 import { join } from 'path';
 import { repositoryControllerRoot } from '../../../cli/repositories/controller-home';
 import { readJsonFile, sanitizeFileComponent } from '../../shared/json-files';
+import type { ProcessCheckExecutionIdentity } from '../../execution/process-runtime/types';
 import { listControlPlaneRecords, mutateControlPlaneRecord, readOrImportControlPlaneRecord, writeControlPlaneRecord } from '../persistence/sqlite-store';
 
 export const WORK_HANDLE_STATES = [
@@ -99,7 +100,12 @@ export interface WorkValidationRunState {
   workspaceFingerprint: string;
   requestedChecks: string[];
   resumeState: WorkHandleStateName;
-  processes: Record<string, { processId: string; requestId: string }>;
+  processes: Record<string, {
+    processId: string;
+    requestId: string;
+    /** Exact producer-side Check identity for this Work verification snapshot. */
+    checkExecution?: ProcessCheckExecutionIdentity;
+  }>;
 }
 
 interface WorkValidationIndex {
@@ -146,6 +152,8 @@ export interface WorkHandleState {
   managedWorktree: boolean;
   workContractId?: string;
   baseCommit?: string;
+  /** Latest canonical target HEAD incorporated into this Work candidate. Legacy records fall back to baseCommit. */
+  deliveryBaseCommit?: string;
   expectedHead?: string;
   permissionSnapshotVersion: number;
   state: WorkHandleStateName;
@@ -161,10 +169,27 @@ export interface WorkHandleState {
     owner: 'work_finalizer';
     registeredAt: string;
   };
+  /**
+   * Explicit terminal resource disposition. This is separate from finalization
+   * stage `skipped`, which is too ambiguous in legacy records to prove that a
+   * controller intentionally retained a managed branch/worktree.
+   */
+  terminalResourceDisposition?: {
+    mode: 'retained_by_request';
+    retainWorktree: boolean;
+    retainBranch: boolean;
+    recordedAt: string;
+  };
   /** Durable terminal cleanup progress. It is intentionally independent from completion/verification receipts. */
   cleanupReceipt?: WorkCleanupReceipt;
 }
 
+export function workDeliveryBaseRevision(
+  handle: Pick<WorkHandleState, 'baseCommit' | 'deliveryBaseCommit'>,
+): string | undefined {
+  return handle.deliveryBaseCommit?.trim() || handle.baseCommit?.trim() || undefined;
+}
+
 function workHandlePath(controllerHome: string, handle: Pick<WorkHandleState, 'repositoryId' | 'workId'>): string {
   return join(repositoryControllerRoot(controllerHome, handle.repositoryId), 'work-handles', `${sanitizeFileComponent(handle.workId)}.json`);
 }
@@ -330,7 +355,7 @@ export function transitionWorkHandle(
   controllerHome: string,
   handle: WorkHandleState,
   nextState: WorkHandleStateName,
-  patch: Partial<Pick<WorkHandleState, 'failureReason' | 'expectedHead' | 'finalization' | 'validationRun' | 'validatedInputFingerprint' | 'cleanupReceipt'>> = {},
+  patch: Partial<Pick<WorkHandleState, 'failureReason' | 'deliveryBaseCommit' | 'expectedHead' | 'finalization' | 'validationRun' | 'validatedInputFingerprint' | 'cleanupReceipt'>> = {},
 ): WorkHandleState {
   if (handle.state !== nextState && !TRANSITIONS[handle.state].includes(nextState)) {
     throw new Error(`WORK_HANDLE_LIFECYCLE_INVALID: cannot transition ${handle.state} -> ${nextState}`);

package/src/runtime/control-plane/execution/work-lifecycle-audit.ts

@@ -0,0 +1,258 @@
+import { spawnSync } from 'child_process';
+import { existsSync, realpathSync } from 'fs';
+import { resolve } from 'path';
+import type { RepositoryRecord } from '../../../cli/repositories/types';
+import { listWorkContracts } from '../facade/work-contract-store';
+import { isTerminalWorkContractStatus } from '../facade/types';
+import { listWorkHandles } from './work-handle-store';
+
+export interface WorkLifecycleAttention {
+  jobId: string;
+  status: string;
+  message: string;
+}
+
+interface LinkedWorktree {
+  path: string;
+  branch?: string;
+}
+
+function git(repositoryRoot: string, args: string[]): string | undefined {
+  const result = spawnSync('git', ['-C', repositoryRoot, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: 10_000,
+    maxBuffer: 4 * 1024 * 1024,
+  });
+  return result.status === 0 && typeof result.stdout === 'string' ? result.stdout.trim() : undefined;
+}
+
+export interface WorktreeGitSnapshot {
+  head?: string;
+  branch?: string;
+  clean: boolean;
+}
+
+export function gitCommitAtRef(repositoryRoot: string, ref: string): string | undefined {
+  const value = git(repositoryRoot, ['rev-parse', '--verify', `${ref}^{commit}`]);
+  return value?.trim() || undefined;
+}
+
+export function gitWorktreeSnapshot(repositoryRoot: string): WorktreeGitSnapshot | undefined {
+  const head = gitCommitAtRef(repositoryRoot, 'HEAD');
+  const branch = git(repositoryRoot, ['branch', '--show-current']);
+  const porcelain = git(repositoryRoot, ['status', '--porcelain']);
+  if (porcelain === undefined) return undefined;
+  return { head, branch: branch?.trim() || undefined, clean: porcelain.length === 0 };
+}
+
+function linkedWorktrees(repositoryRoot: string): LinkedWorktree[] {
+  const output = git(repositoryRoot, ['worktree', 'list', '--porcelain']);
+  if (output === undefined) return [];
+  const worktrees: LinkedWorktree[] = [];
+  let current: LinkedWorktree | undefined;
+  for (const line of output.split('\n')) {
+    if (line.startsWith('worktree ')) {
+      if (current) worktrees.push(current);
+      current = { path: line.slice('worktree '.length) };
+    } else if (current && line.startsWith('branch refs/heads/')) {
+      current.branch = line.slice('branch refs/heads/'.length);
+    }
+  }
+  if (current) worktrees.push(current);
+  return worktrees;
+}
+
+function dirty(path: string): boolean | undefined {
+  const status = git(path, ['status', '--porcelain']);
+  return status === undefined ? undefined : status.length > 0;
+}
+
+function canonicalPath(path: string): string {
+  try { return realpathSync.native(path); }
+  catch { return resolve(path); }
+}
+
+function refReachableFromTarget(repositoryRoot: string, ref: string, targetBranch: string): boolean | undefined {
+  const result = spawnSync('git', ['-C', repositoryRoot, 'merge-base', '--is-ancestor', ref, targetBranch], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'ignore', 'ignore'],
+    timeout: 10_000,
+  });
+  if (result.status === 0) return true;
+  if (result.status === 1) return false;
+  return undefined;
+}
+
+function branchIntegrated(repositoryRoot: string, branch: string, targetBranch: string): boolean | undefined {
+  const reachable = refReachableFromTarget(repositoryRoot, branch, targetBranch);
+  if (reachable !== false) return reachable;
+
+  // Rebase/cherry-pick delivery can preserve every patch while changing ancestry.
+  // Treat the branch as integrated only when Git proves it has no unique patches.
+  const cherry = spawnSync('git', ['-C', repositoryRoot, 'cherry', targetBranch, branch], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: 10_000,
+    maxBuffer: 4 * 1024 * 1024,
+  });
+  if (cherry.status !== 0 || typeof cherry.stdout !== 'string') return false;
+  return !cherry.stdout.split('\n').some((line) => line.startsWith('+ '));
+}
+
+function attention(code: string, identity: string, message: string): WorkLifecycleAttention {
+  return { jobId: `lifecycle:${code}:${identity}`, status: code, message };
+}
+
+/**
+ * Read-only reconciliation across canonical Work, WorkHandle, registry, and Git.
+ * It reports contradictions and live Work through the existing Runtime projection;
+ * it never changes lifecycle state or owns cleanup.
+ */
+export function collectWorkLifecycleAttention(
+  controllerHome: string,
+  repository: RepositoryRecord,
+): WorkLifecycleAttention[] {
+  const contracts = listWorkContracts({
+    controllerHome,
+    repoId: repository.repoId,
+    status: 'all',
+    limit: 100,
+  });
+  const handles = listWorkHandles(controllerHome, repository.repoId, 5_000);
+  const contractsByWork = new Map(contracts.map((contract) => [contract.workId, contract]));
+  const handlesByWork = new Map(handles.map((handle) => [handle.workContractId ?? handle.workId, handle]));
+  const findings: WorkLifecycleAttention[] = [];
+  const targetBranch = repository.defaultBranch || 'main';
+
+  for (const contract of contracts) {
+    const handle = handlesByWork.get(contract.workId);
+    const terminal = isTerminalWorkContractStatus(contract.status);
+    if (!terminal) {
+      findings.push(attention(
+        'work_active',
+        contract.workId,
+        `Work ${contract.workId} is ${contract.status} in ${contract.phase}; continue, block with a handoff, or finalize it explicitly.`,
+      ));
+      if (contract.workKind === 'repository_change' && !handle) {
+        findings.push(attention(
+          'active_work_handle_missing',
+          contract.workId,
+          `Repository Work ${contract.workId} is active but has no readable WorkHandle.`,
+        ));
+      }
+      if (handle?.managedWorktree && !existsSync(handle.worktreePath)) {
+        findings.push(attention(
+          'active_worktree_missing',
+          contract.workId,
+          `Active Work ${contract.workId} owns missing managed worktree ${handle.worktreePath}.`,
+        ));
+      }
+      continue;
+    }
+
+    if (contract.status === 'completed' && !contract.completionReceipt) {
+      findings.push(attention(
+        'completed_work_receipt_missing',
+        contract.workId,
+        `Completed Work ${contract.workId} has no Completion Receipt.`,
+      ));
+    }
+    if (contract.status === 'completed' && contract.completionReceipt?.source === 'controller_work') {
+      const receiptTargetRevision = contract.completionReceipt.targetRevision?.trim();
+      const receiptTargetBranch = contract.completionReceipt.targetBranch?.trim() || targetBranch;
+      if (!receiptTargetRevision || refReachableFromTarget(repository.canonicalRoot, receiptTargetRevision, receiptTargetBranch) !== true) {
+        findings.push(attention(
+          'completion_receipt_target_not_integrated',
+          contract.workId,
+          `Work ${contract.workId} receipt target ${receiptTargetRevision || 'missing'} is not reachable from ${receiptTargetBranch}.`,
+        ));
+      }
+    }
+    if (!handle || handle.terminalResourceDisposition?.mode === 'retained_by_request') continue;
+    const cleanupFailed = handle.finalization.branchCleanup === 'failed'
+      || handle.finalization.worktreeCleanup === 'failed';
+    const cleanupPending = handle.finalization.branchCleanup === 'pending'
+      || handle.finalization.worktreeCleanup === 'pending';
+    const repositoryOwnedCanonicalCheckout = !handle.managedWorktree
+      && canonicalPath(handle.worktreePath) === canonicalPath(repository.canonicalRoot)
+      && handle.branch === targetBranch;
+    const cleanupUnsettled = cleanupFailed || (cleanupPending && !repositoryOwnedCanonicalCheckout);
+    if (cleanupUnsettled) {
+      findings.push(attention(
+        'terminal_work_cleanup_unsettled',
+        contract.workId,
+        `Terminal Work ${contract.workId} still has unsettled branch/worktree cleanup stages.`,
+      ));
+    }
+    if (handle.state === 'cleaned' && handle.managedWorktree && existsSync(handle.worktreePath)) {
+      findings.push(attention(
+        'cleaned_worktree_still_present',
+        contract.workId,
+        `WorkHandle ${contract.workId} is cleaned but managed worktree ${handle.worktreePath} still exists.`,
+      ));
+    }
+  }
+
+  const activeBranches = new Set(
+    handles
+      .filter((handle) => {
+        const contract = contractsByWork.get(handle.workContractId ?? handle.workId);
+        return contract ? !isTerminalWorkContractStatus(contract.status) : false;
+      })
+      .map((handle) => handle.branch),
+  );
+  const retainedBranches = new Set(
+    handles
+      .filter((handle) => handle.terminalResourceDisposition?.retainBranch === true)
+      .map((handle) => handle.branch),
+  );
+  const activeRegistryRoots = new Set(
+    repository.checkouts
+      .filter((checkout) => (checkout.lifecycle ?? 'active') === 'active')
+      .map((checkout) => canonicalPath(checkout.canonicalRoot)),
+  );
+  const handleRoots = new Map(handles.map((handle) => [canonicalPath(handle.worktreePath), handle]));
+
+  for (const checkout of repository.checkouts) {
+    if ((checkout.lifecycle ?? 'active') === 'active' && !existsSync(checkout.canonicalRoot)) {
+      findings.push(attention(
+        'active_checkout_missing',
+        checkout.checkoutId,
+        `Registry checkout ${checkout.checkoutId} is active but ${checkout.canonicalRoot} is missing.`,
+      ));
+    }
+  }
+
+  const linked = linkedWorktrees(repository.canonicalRoot);
+  for (const worktree of linked) {
+    const root = canonicalPath(worktree.path);
+    if (activeRegistryRoots.has(root)) continue;
+    const isDirty = dirty(root);
+    const handle = handleRoots.get(root);
+    const code = isDirty === true ? 'dirty_linked_worktree_unregistered' : 'linked_worktree_unregistered';
+    findings.push(attention(
+      code,
+      handle?.workId ?? worktree.branch ?? root,
+      `Git worktree ${root}${worktree.branch ? ` on ${worktree.branch}` : ''} is linked but absent from the active checkout registry${isDirty === true ? ' and has uncommitted changes' : ''}.`,
+    ));
+  }
+
+  const branches = git(repository.canonicalRoot, ['for-each-ref', '--format=%(refname:short)', 'refs/heads/work', 'refs/heads/codex'])
+    ?.split('\n')
+    .map((branch) => branch.trim())
+    .filter(Boolean) ?? [];
+  for (const branch of branches) {
+    if (activeBranches.has(branch) || retainedBranches.has(branch)) continue;
+    if (branchIntegrated(repository.canonicalRoot, branch, targetBranch) !== false) continue;
+    findings.push(attention(
+      'work_branch_not_integrated',
+      branch,
+      `Work branch ${branch} is not reachable from ${targetBranch} and is not owned by an active or explicitly retained Work.`,
+    ));
+  }
+
+  return Array.from(new Map(findings.map((finding) => [finding.jobId, finding])).values())
+    .sort((left, right) => left.jobId.localeCompare(right.jobId))
+    .slice(0, 100);
+}

package/src/runtime/control-plane/execution/work-remote-delivery.ts

@@ -0,0 +1,215 @@
+import { spawnSync } from 'child_process';
+import type { RepositoryRecord } from '../../../cli/repositories/types';
+import { getWorkContract } from '../facade/work-contract-store';
+import { isTerminalWorkContractStatus } from '../facade/types';
+import { executeRepositoryCommandViaProcessRuntime, waitRepositoryCommandProcess } from '../../execution/process-runtime/command-facade';
+import { executionIdentityForRepository } from './execution-identity';
+
+export interface WorkRemoteDeliveryReceipt {
+  targetBranch: string;
+  targetRevision: string;
+  remoteRevisionBefore: string;
+  remoteRevisionAfter: string;
+  pushed: boolean;
+}
+
+function gitText(root: string, args: string[], timeoutMs = 30_000): string {
+  const result = spawnSync('git', ['-C', root, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: timeoutMs,
+  });
+  if (result.status !== 0 || result.error || typeof result.stdout !== 'string') {
+    throw new Error(`WORK_REMOTE_DELIVERY_GIT_FAILED: git ${args[0] ?? 'command'} failed`);
+  }
+  return result.stdout.trim();
+}
+
+function gitSucceeds(root: string, args: string[]): boolean {
+  const result = spawnSync('git', ['-C', root, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 15_000,
+  });
+  return result.status === 0 && !result.error;
+}
+
+function exactRevision(root: string, revision: string, label: string): string {
+  const value = gitText(root, ['rev-parse', '--verify', `${revision}^{commit}`]);
+  if (!/^[a-f0-9]{40}$/i.test(value)) throw new Error(`WORK_REMOTE_DELIVERY_${label}_INVALID`);
+  return value;
+}
+
+function assertTargetBranch(root: string, targetBranch: string): void {
+  if (!targetBranch.trim() || !gitSucceeds(root, ['check-ref-format', '--branch', targetBranch])) {
+    throw new Error(`WORK_REMOTE_DELIVERY_TARGET_BRANCH_INVALID: ${targetBranch || 'missing'}`);
+  }
+}
+
+function assertActiveWork(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  workId: string;
+}): void {
+  const contract = getWorkContract(
+    { controllerHome: input.controllerHome, repoId: input.repository.repoId },
+    input.workId,
+  );
+  if (
+    !contract
+    || contract.repoId !== input.repository.repoId
+    || (contract.checkoutId && contract.checkoutId !== input.repository.activeCheckoutId)
+    || isTerminalWorkContractStatus(contract.status)
+    || Boolean(contract.completionReceipt)
+  ) {
+    throw new Error(`WORK_REMOTE_DELIVERY_ACTIVE_AUTHORITY_REQUIRED: ${input.workId}`);
+  }
+}
+
+function remoteHead(root: string, targetBranch: string): string {
+  const line = gitText(root, ['ls-remote', '--heads', 'origin', `refs/heads/${targetBranch}`])
+    .split(/\r?\n/)
+    .find(Boolean);
+  const revision = line?.split(/\s+/)[0] ?? '';
+  if (!/^[a-f0-9]{40}$/i.test(revision)) {
+    throw new Error(`WORK_REMOTE_DELIVERY_REMOTE_BRANCH_MISSING: origin/${targetBranch}`);
+  }
+  return revision;
+}
+
+async function executeGit(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  workId: string;
+  command: string[];
+  timeoutMs: number;
+  commandId: string;
+}): Promise<{ ok: boolean; detail: string }> {
+  const result = await executeRepositoryCommandViaProcessRuntime({
+    controllerHome: input.controllerHome,
+    repository: input.repository,
+    command: input.command,
+    timeoutMs: input.timeoutMs,
+    interactiveWaitMs: Math.min(5_000, input.timeoutMs),
+    maxOutputBytes: 256 * 1024,
+    workId: input.workId,
+    commandId: input.commandId,
+    executionIdentity: executionIdentityForRepository(input.repository, { workId: input.workId }),
+  });
+  if (result.route === 'reject' || result.route === 'durable') {
+    return { ok: false, detail: result.reason ?? result.route };
+  }
+  if (result.process && !result.process.completed) {
+    const waited = await waitRepositoryCommandProcess(
+      input.controllerHome,
+      input.repository.repoId,
+      result.process.processId,
+      { timeoutMs: input.timeoutMs },
+    );
+    return { ok: waited.ok === true, detail: waited.stderr ?? waited.stdout ?? '' };
+  }
+  return {
+    ok: result.ok === true || result.process?.ok === true,
+    detail: result.stderr ?? result.stdout ?? result.process?.stderr ?? result.process?.stdout ?? '',
+  };
+}
+
+async function fetchRemoteTipObject(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  workId: string;
+  targetBranch: string;
+  timeoutMs: number;
+}): Promise<void> {
+  const fetched = await executeGit({
+    controllerHome: input.controllerHome,
+    repository: input.repository,
+    workId: input.workId,
+    command: ['git', 'fetch', '--no-tags', '--no-write-fetch-head', 'origin', `refs/heads/${input.targetBranch}`],
+    timeoutMs: input.timeoutMs,
+    commandId: `work-remote-delivery-fetch:${input.workId}:${input.targetBranch}`,
+  });
+  if (!fetched.ok) {
+    throw new Error(`WORK_REMOTE_DELIVERY_FETCH_FAILED: ${fetched.detail || `origin/${input.targetBranch}`}`);
+  }
+}
+
+async function observedRemoteContainsTarget(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  workId: string;
+  targetBranch: string;
+  targetRevision: string;
+  remoteRevision: string;
+  timeoutMs: number;
+}): Promise<boolean> {
+  await fetchRemoteTipObject(input);
+  if (!gitSucceeds(input.repository.canonicalRoot, ['cat-file', '-e', `${input.remoteRevision}^{commit}`])) {
+    throw new Error(`WORK_REMOTE_DELIVERY_REMOTE_OBJECT_UNAVAILABLE: ${input.remoteRevision}`);
+  }
+  return gitSucceeds(
+    input.repository.canonicalRoot,
+    ['merge-base', '--is-ancestor', input.targetRevision, input.remoteRevision],
+  );
+}
+
+export async function pushExactWorkRemoteDelivery(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  workId: string;
+  targetBranch: string;
+  targetRevision: string;
+  timeoutMs?: number;
+}): Promise<WorkRemoteDeliveryReceipt> {
+  assertTargetBranch(input.repository.canonicalRoot, input.targetBranch);
+  assertActiveWork(input);
+  const targetRevision = exactRevision(input.repository.canonicalRoot, input.targetRevision, 'TARGET_REVISION');
+  const timeoutMs = Math.min(Math.max(input.timeoutMs ?? 120_000, 5_000), 120_000);
+  const remoteRevisionBefore = remoteHead(input.repository.canonicalRoot, input.targetBranch);
+
+  if (await observedRemoteContainsTarget({ ...input, targetRevision, remoteRevision: remoteRevisionBefore, timeoutMs })) {
+    return {
+      targetBranch: input.targetBranch,
+      targetRevision,
+      remoteRevisionBefore,
+      remoteRevisionAfter: remoteRevisionBefore,
+      pushed: false,
+    };
+  }
+  if (!gitSucceeds(input.repository.canonicalRoot, ['merge-base', '--is-ancestor', remoteRevisionBefore, targetRevision])) {
+    throw new Error(`WORK_REMOTE_DELIVERY_REMOTE_DIVERGED: ${remoteRevisionBefore} is not an ancestor of ${targetRevision}`);
+  }
+
+  // Re-read durable authority immediately before the only remote mutation. A
+  // terminal Work may be inspected/reconciled, but it can never be reused as
+  // authority for an arbitrary post-finalize push.
+  assertActiveWork(input);
+  const pushed = await executeGit({
+    controllerHome: input.controllerHome,
+    repository: input.repository,
+    workId: input.workId,
+    command: ['git', 'push', '--porcelain', 'origin', `${targetRevision}:refs/heads/${input.targetBranch}`],
+    timeoutMs,
+    commandId: `work-remote-delivery-push:${input.workId}:${targetRevision}`,
+  });
+
+  const remoteRevisionAfter = remoteHead(input.repository.canonicalRoot, input.targetBranch);
+  const delivered = await observedRemoteContainsTarget({
+    ...input,
+    targetRevision,
+    remoteRevision: remoteRevisionAfter,
+    timeoutMs,
+  });
+  if (!delivered) {
+    throw new Error(
+      `WORK_REMOTE_DELIVERY_PUSH_FAILED: ${pushed.detail || `${targetRevision} is not reachable from origin/${input.targetBranch}`}`,
+    );
+  }
+  return {
+    targetBranch: input.targetBranch,
+    targetRevision,
+    remoteRevisionBefore,
+    remoteRevisionAfter,
+    pushed: pushed.ok,
+  };
+}

package/src/runtime/control-plane/execution/work-task-receipt.ts

@@ -4,7 +4,7 @@ import { getIssue, listIssues, recordTaskVerification, acceptVerifiedTask, proje
 import { resolveCompletionTargetBranch } from '../../../cli/controller/completion-target';
 import type { CompletionReceipt, ControllerIssue } from '../../../cli/controller/types';
 import { completeRequirementFromWork } from '../persistence/requirement-store';
-import { getWorkContract, recordWorkCompletionReceipt, updateWorkContract } from '../facade/work-contract-store';
+import { appendWorkEvidence, getWorkContract, recordWorkCompletionReceipt, updateWorkContract } from '../facade/work-contract-store';
 import { isRepositoryCompletionReceipt, WORK_RECONCILIATION_METHODS, WORK_RECONCILIATION_OUTCOMES } from '../facade/types';
 import type {
   WorkReconciliationMethod,
@@ -27,7 +27,7 @@ function commitRevision(repoRoot: string, revision: string | undefined, label: s
   return gitText(repoRoot, ['rev-parse', `${revision.trim()}^{commit}`]);
 }
 
-function changedPaths(repoRoot: string, baseRevision: string, targetRevision: string): string[] {
+export function changedPaths(repoRoot: string, baseRevision: string, targetRevision: string): string[] {
   const result = spawnSync('git', ['diff', '--name-only', '-z', baseRevision, targetRevision], {
     cwd: repoRoot,
     encoding: 'utf-8',
@@ -39,6 +39,22 @@ function changedPaths(repoRoot: string, baseRevision: string, targetRevision: st
   return [...new Set(result.stdout.split('\0').filter(Boolean))].sort();
 }
 
+
+function completionReceiptChangedPaths(
+  contract: NonNullable<ReturnType<typeof getWorkContract>>,
+  repoRoot: string,
+  baseRevision: string,
+  targetRevision: string,
+): string[] {
+  const reconciled = contract.reconciliations.find((entry) =>
+    entry.outcome === 'accepted_equivalence'
+    && entry.reachable
+    && entry.baseRevision === baseRevision
+    && entry.observedTargetRevision === targetRevision);
+  if (!reconciled) return changedPaths(repoRoot, baseRevision, targetRevision);
+  return [...new Set(reconciled.comparedPaths.map((path) => path.trim()).filter(Boolean))].sort();
+}
+
 function assertWorkNotBoundElsewhere(repoRoot: string, workId: string, issueId: string, taskId: string): void {
   for (const issue of listIssues(repoRoot)) {
     for (const task of issue.tasks) {
@@ -281,10 +297,23 @@ export function acceptVerifiedTaskFromReviewedWorkReconciliation(input: Controll
     contract.workKind,
   );
   if (recorded.requirementId) {
-    completeRequirementFromWork(
-      { controllerHome: input.controllerHome },
-      { requirementId: recorded.requirementId, work: recorded },
-    );
+    try {
+      completeRequirementFromWork(
+        { controllerHome: input.controllerHome },
+        { requirementId: recorded.requirementId, work: recorded },
+      );
+    } catch (error) {
+      try {
+        appendWorkEvidence({ controllerHome: input.controllerHome, repoId: input.repoId }, input.workId, {
+          title: 'requirement completion projection pending',
+          summary: `Work completion remains authoritative; Requirement projection could not be applied: ${error instanceof Error ? error.message : String(error)}`.slice(0, 2_000),
+          detailLevel: 'summary',
+        });
+      } catch {
+        // The completion receipt was already persisted; legacy Task projection
+        // remains retryable even if this diagnostic cannot be stored.
+      }
+    }
   }
   const recordedReceipt = recorded.completionReceipt;
   const projectedReceipt = recordedReceipt && isRepositoryCompletionReceipt(recordedReceipt) ? recordedReceipt : receipt;
@@ -361,7 +390,7 @@ export function acceptVerifiedTaskFromControllerWork(input: ControllerWorkTaskRe
   }
   assertCurrentRequiredChecks(contract, targetRevision);
   const baseRevision = commitRevision(input.repoRoot, handle.baseCommit, 'BASE_REVISION');
-  const receiptChangedPaths = changedPaths(input.repoRoot, baseRevision, targetRevision);
+  const receiptChangedPaths = completionReceiptChangedPaths(contract, input.repoRoot, baseRevision, targetRevision);
   if (noChange && receiptChangedPaths.length > 0) {
     throw new Error(`CONTROLLER_WORK_RECEIPT_NO_CHANGE_DIRTY: ${input.workId}`);
   }
@@ -416,10 +445,24 @@ export function acceptVerifiedTaskFromControllerWork(input: ControllerWorkTaskRe
     completionOutcome,
   );
   if (recorded.requirementId) {
-    completeRequirementFromWork(
-      { controllerHome: input.controllerHome },
-      { requirementId: recorded.requirementId, work: recorded },
-    );
+    try {
+      completeRequirementFromWork(
+        { controllerHome: input.controllerHome },
+        { requirementId: recorded.requirementId, work: recorded },
+      );
+    } catch (error) {
+      try {
+        appendWorkEvidence({ controllerHome: input.controllerHome, repoId: input.repoId }, input.workId, {
+          title: 'requirement completion projection pending',
+          summary: `Work completion remains authoritative; Requirement projection could not be applied: ${error instanceof Error ? error.message : String(error)}`.slice(0, 2_000),
+          detailLevel: 'summary',
+        });
+      } catch {
+        // The Work receipt is canonical and already durable. Keep historical
+        // reconciliation/task projection retryable instead of surfacing a false
+        // completion failure from this downstream diagnostic path.
+      }
+    }
   }
   const recordedReceipt = recorded.completionReceipt;
   const projectedReceipt = recordedReceipt && isRepositoryCompletionReceipt(recordedReceipt) ? recordedReceipt : receipt;