@moretea-labs/forge 1.7.0 → 1.7.2

package/src/runtime/control-plane/facade/goal-workloop.ts

@@ -12,7 +12,6 @@ import {
   createWorkContract,
   getWorkContract,
   listWorkContracts,
-  recordWorkCompletionReceipt,
   recordWorkScopeEvidence,
   summarizeWorkContract,
   transitionWorkContractPhase,
@@ -26,6 +25,8 @@ import {
   type PlanContractStoreOptions,
 } from './plan-contract-store';
 import { withPrimaryWorkAdmissionLock } from './semantic-admission';
+import { completeWorkWithReceipt } from '../execution/work-completion-authority';
+import { evaluateReadOnlyReviewSourceIdentity, evaluateWorkCompletionEvidence, evaluateWorkImplementationEvidence, verificationRecordAppliesToCurrentWorkspace } from '../execution/work-evidence-policy';
 import { readRequirement } from '../persistence/requirement-store';
 import {
   classifyVerificationOutcome,
@@ -51,6 +52,7 @@ import type {
   WorkRisk,
 } from './types';
 import { selectExecutionMode } from './types';
+import { resolveWorkspaceAdmissionConstraint } from '../routing/workspace-admission';
 
 export type GoalWorkloopOperation = 'start' | 'continue' | 'verify' | 'finalize' | 'stop';
 
@@ -67,6 +69,8 @@ export interface GoalWorkloopContext {
   workspaceFingerprint?: string;
   /** Current net repository paths changed from the Work base plus dirty checkout paths. */
   workspaceChangedPaths?: readonly string[];
+  /** Durable terminal repository Process ids explicitly bound to this Work + checkout. */
+  workBoundProcessEvidenceIds?: readonly string[];
   now?: () => string;
   /** True only while a Gateway caller holds the cross-process primary Work admission lock. */
   semanticAdmissionLocked?: boolean;
@@ -97,7 +101,13 @@ export interface GoalWorkloopStartInput {
   planId?: string;
   planStepId?: string;
   /** Explicit technical evidence shape chosen by the semantic Controller. Never inferred from objective/check text. */
-  workKind?: Extract<WorkKind, 'repository_change' | 'completed_no_change' | 'investigation' | 'local_effect' | 'remote_effect' | 'reconciliation'>;
+  workKind?: Extract<WorkKind, 'repository_change' | 'completed_no_change' | 'read_only_review' | 'investigation' | 'local_effect' | 'remote_effect' | 'reconciliation'>;
+}
+
+export interface GoalWorkloopAcceptanceEvidenceBinding {
+  criterion: string;
+  evidenceIds: string[];
+  rationale: string;
 }
 
 export interface GoalWorkloopContinueInput {
@@ -108,6 +118,10 @@ export interface GoalWorkloopContinueInput {
   checks?: string[];
   additionalLikelyPaths?: string[];
   inspectedPaths?: string[];
+  /** Concise semantic findings discovered by a first-class read-only review. */
+  reviewFindings?: string[];
+  /** Explicit Controller-reviewed bindings from exact declared criteria to durable Work evidence. */
+  acceptanceEvidence?: GoalWorkloopAcceptanceEvidenceBinding[];
   /** Explicit Controller decision after deterministic acceptance failure; never inferred from note text. */
   acceptanceFailureDecision?: 'repair' | 'rescope';
 }
@@ -163,6 +177,7 @@ function handoffIdFor(prefix: string): string {
 }
 
 function workRiskFor(input: GoalWorkloopStartInput): WorkRisk {
+  if (input.workKind === 'read_only_review') return 'readonly';
   const risk = input.modeInput.risk;
   if (input.modeInput.secretAccess === true || input.modeInput.destructive === true) return 'destructive';
   if (input.modeInput.remoteWrite === true) return 'high';
@@ -217,126 +232,6 @@ function initialEvidence(objective: string): EvidenceRef {
   };
 }
 
-type ReconciledVerificationHistory = ReturnType<typeof reconcileVerificationHistory>;
-
-interface WorkCompletionEvidenceEvaluation {
-  status: 'complete' | 'failed' | 'incomplete';
-  history: ReconciledVerificationHistory;
-  missingChecks: string[];
-  durableResultEvidence: boolean;
-  reasons: string[];
-}
-
-function verificationRecordAppliesToCurrentWorkspace(
-  record: VerificationRecord,
-  currentRevision?: string,
-  currentWorkspaceFingerprint?: string,
-): boolean {
-  if (currentRevision && record.sourceRevision && record.sourceRevision !== currentRevision) return false;
-  if (
-    currentWorkspaceFingerprint
-    && record.workspaceFingerprint
-    && record.workspaceFingerprint !== currentWorkspaceFingerprint
-  ) return false;
-  return true;
-}
-
-function isAuthoritativeCurrentWorkVerification(
-  work: WorkContract,
-  record: VerificationRecord,
-  currentRevision?: string,
-): boolean {
-  const receipt = record.receipt;
-  return Boolean(
-    currentRevision
-    && record.outcome === 'valid_pass'
-    && record.sourceRevision === currentRevision
-    && receipt
-    && receipt.repoId === work.repoId
-    && receipt.workId === work.workId
-    && receipt.checkId === record.checkId
-    && receipt.ok === true
-    && receipt.timedOut === false
-    && receipt.cancelled === false,
-  );
-}
-
-interface WorkImplementationEvidenceEvaluation {
-  status: 'complete' | 'incomplete';
-  changedPaths: string[];
-  reasons: string[];
-}
-
-function evaluateWorkImplementationEvidence(
-  work: WorkContract,
-  currentWorkspaceChangedPaths: readonly string[] = [],
-): WorkImplementationEvidenceEvaluation {
-  if (work.workKind !== 'repository_change') {
-    return { status: 'complete', changedPaths: [], reasons: [] };
-  }
-
-  const changedPaths = [...new Set(currentWorkspaceChangedPaths.map((path) => path.trim()).filter(Boolean))].sort();
-  if (changedPaths.length > 0) {
-    return { status: 'complete', changedPaths, reasons: [] };
-  }
-
-  return {
-    status: 'incomplete',
-    changedPaths: [],
-    reasons: ['Repository-change Work has no current net source changes relative to its base revision. Verification evidence cannot substitute for implementation evidence.'],
-  };
-}
-
-function evaluateWorkCompletionEvidence(
-  work: WorkContract,
-  currentRevision?: string,
-  currentWorkspaceFingerprint?: string,
-): WorkCompletionEvidenceEvaluation {
-  const applicableCheckRefs = work.checkRefs.filter((record) =>
-    verificationRecordAppliesToCurrentWorkspace(record, currentRevision, currentWorkspaceFingerprint));
-  const history = reconcileVerificationHistory(
-    applicableCheckRefs.map((record) => ({ checkId: record.checkId, outcome: record.outcome, recordedAt: record.recordedAt })),
-  );
-  const missingChecks = work.checks.filter((checkId) => !history.validPasses.includes(checkId));
-  const durableResultEvidence = work.evidenceRefs.some((evidence) => Boolean(evidence.evidenceId || evidence.artifactId))
-    || applicableCheckRefs.some((record) => isAuthoritativeCurrentWorkVerification(work, record, currentRevision));
-  const reasons: string[] = [];
-
-  if (history.acceptanceFailures.length > 0) {
-    reasons.push(`Acceptance checks failed: ${history.acceptanceFailures.join(', ')}.`);
-    return { status: 'failed', history, missingChecks, durableResultEvidence, reasons };
-  }
-  if (history.infrastructureIssues.length > 0) {
-    reasons.push(`Infrastructure issues remain: ${history.infrastructureIssues.join(', ')}.`);
-  }
-  if (history.invalidCheckIds.length > 0) {
-    reasons.push(`Invalid check ids remain: ${history.invalidCheckIds.join(', ')}.`);
-  }
-  if (missingChecks.length > 0) {
-    reasons.push(`Declared checks are missing valid_pass evidence: ${missingChecks.join(', ')}.`);
-  }
-  if (work.checks.length === 0 && !durableResultEvidence) {
-    const staleWorkVerification = work.checkRefs.some((record) =>
-      Boolean(record.receipt)
-      && !verificationRecordAppliesToCurrentWorkspace(record, currentRevision, currentWorkspaceFingerprint));
-    reasons.push(staleWorkVerification
-      ? 'Work-bound verification evidence is stale for the current source/workspace identity.'
-      : 'No durable result evidence (evidenceId, artifactId, or current Work-bound verification receipt) was recorded for this no-check WorkContract.');
-  }
-
-  const complete = history.infrastructureIssues.length === 0
-    && history.invalidCheckIds.length === 0
-    && missingChecks.length === 0
-    && (work.checks.length > 0 || durableResultEvidence);
-  return {
-    status: complete ? 'complete' : 'incomplete',
-    history,
-    missingChecks,
-    durableResultEvidence,
-    reasons,
-  };
-}
-
 /**
  * Mode selection for facade routing. Direct control never creates a WorkContract.
  * Goal workloop creates one. Handoff-only creates a handoff and stops.
@@ -345,14 +240,74 @@ export function routeWorkStart(
   ctx: GoalWorkloopContext,
   input: GoalWorkloopStartInput,
 ): FacadeResult {
+  const placementResolution = resolveWorkspaceAdmissionConstraint(input.constraints);
+  if (placementResolution.ok === false) {
+    return buildFacadeResult({
+      status: 'blocked',
+      summary: `${placementResolution.code}: ${placementResolution.message}`,
+      data: { executionStarted: false, workContractCreated: false, placementConstraintConflict: true },
+      rawAvailable: false,
+    });
+  }
+  const placementConstraint = placementResolution.constraint;
+  const canonicalConstraints: WorkContract['constraints'] = {
+    ...(input.constraints ?? {}),
+    workspaceMode: placementConstraint.workspaceMode,
+    requireWorktree: placementConstraint.requireWorktree,
+    directMainProhibited: placementConstraint.directMainProhibited,
+  };
   const strategyConflictRequiresApproval = input.constraints?.architectureStrategyChange === true
     || input.constraints?.conflictsWithThinHarnessPolicy === true
     || input.constraints?.changesDefaultExecutionStrategy === true;
+  const relatedLifecycleSource = input.relatedWorkId ? getWorkContract(ctx.workStore, input.relatedWorkId) : undefined;
+  const inheritedReadOnlyReview = Boolean(
+    input.workKind === undefined
+    && input.workRelation === 'new_goal'
+    && relatedLifecycleSource?.workKind === 'read_only_review'
+    && (relatedLifecycleSource.status === 'cancelled' || relatedLifecycleSource.status === 'completed' || relatedLifecycleSource.status === 'failed'),
+  );
+  if (
+    inheritedReadOnlyReview
+    && relatedLifecycleSource?.baseRevision
+    && ctx.sourceRevision
+    && relatedLifecycleSource.baseRevision !== ctx.sourceRevision
+  ) {
+    return buildFacadeResult({
+      status: 'blocked',
+      summary: `READ_ONLY_REVIEW_REPLACEMENT_SOURCE_DRIFT: replacement source ${ctx.sourceRevision} does not match frozen review base ${relatedLifecycleSource.baseRevision}.`,
+      data: { executionStarted: false, workContractCreated: false, relatedWorkId: relatedLifecycleSource.workId, sourceDrift: true },
+    });
+  }
+  const requestedWorkKind = input.workKind ?? (inheritedReadOnlyReview ? 'read_only_review' : undefined);
+  const typedReadOnlyReviewRequested = requestedWorkKind === undefined
+    && (input.modeInput.mutation === false || (input.modeInput.mutation === undefined && input.modeInput.risk === 'readonly'))
+    && input.modeInput.requiresInvestigation === true
+    && input.modeInput.requiresRecovery === true;
+  const effectiveWorkKind = requestedWorkKind ?? (typedReadOnlyReviewRequested ? 'read_only_review' : undefined);
+  const readOnlyReviewRequested = effectiveWorkKind === 'read_only_review';
+  const readOnlyMutationConflict = readOnlyReviewRequested && (
+    input.modeInput.mutation === true
+    || (input.modeInput.expectedFiles ?? 0) > 0
+    || (input.modeInput.expectedChangedLines ?? 0) > 0
+    || input.modeInput.requiresExternalEffect === true
+    || input.modeInput.remoteWrite === true
+    || input.modeInput.destructive === true
+  );
+  if (readOnlyMutationConflict) {
+    return buildFacadeResult({
+      status: 'blocked',
+      summary: 'READ_ONLY_REVIEW_MUTATION_CONFLICT: read_only_review cannot request repository mutation, external effects, remote writes, or destructive execution.',
+      data: { executionStarted: false, workContractCreated: false, workKind: effectiveWorkKind },
+    });
+  }
   const effectiveModeInput: ExecutionModeSelectionInput = {
     ...input.modeInput,
     objective: input.objective,
     knownPaths: input.allowedPaths,
-    mutation: input.modeInput.mutation ?? input.modeInput.risk !== 'readonly',
+    workspacePlacement: placementConstraint.workspaceMode,
+    directMainProhibited: placementConstraint.directMainProhibited,
+    mutation: readOnlyReviewRequested ? false : input.modeInput.mutation ?? input.modeInput.risk !== 'readonly',
+    risk: readOnlyReviewRequested ? 'readonly' : input.modeInput.risk,
     approvalConfirmed: input.approvalConfirmed === true,
     requiresUserApproval: input.approvalConfirmed === true
       ? false
@@ -376,7 +331,7 @@ export function routeWorkStart(
     : selected;
   const evaluateAccessPolicy = (selected: ReturnType<typeof selectExecutionMode>) => evaluatePolicyGate({
     capabilityId: selected.mode === 'direct_control' ? 'repository.direct_edit' : selected.mode === 'goal_workloop' ? 'controller.goal_workloop' : 'controller.handoff_inbox',
-    risk: input.modeInput.risk
+    risk: effectiveModeInput.risk
       ?? (input.modeInput.secretAccess === true ? 'raw_secret_config'
         : input.modeInput.destructive === true ? 'destructive'
           : input.modeInput.remoteWrite === true ? 'remote_write'
@@ -396,12 +351,24 @@ export function routeWorkStart(
   });
 
   let selectedMode = selectExecutionMode(effectiveModeInput);
+  if (input.forceMode === 'direct_control' && selectedMode.routeDecision.requiresIsolation) {
+    return buildFacadeResult({
+      status: 'blocked',
+      summary: 'WORKSPACE_PLACEMENT_DIRECT_CONTROL_FORBIDDEN: typed placement requires isolation, so force_mode=direct_control cannot override admission policy.',
+      data: { executionStarted: false, workContractCreated: false, routeDecision: selectedMode.routeDecision },
+      rawAvailable: false,
+    });
+  }
   let policy = evaluateAccessPolicy(selectedMode);
   if (policy.decision === 'allowed' && effectiveModeInput.requiresUserApproval !== true) {
     selectedMode = selectExecutionMode({ ...effectiveModeInput, approvalConfirmed: true });
     policy = evaluateAccessPolicy(selectedMode);
   }
   let mode = applyForcedMode(selectedMode);
+  const routeApprovalRequired = mode.routeDecision.requiresApproval
+    && mode.routeDecision.waitForUser
+    && mode.routeDecision.approvalState !== 'blocked_by_policy';
+  const approvalRequired = policy.decision === 'approval_required' || routeApprovalRequired;
 
   // Route Policy is the sole execution-depth authority. Existing Work is
   // ownership context, not a reason to upgrade an otherwise Direct operation
@@ -488,7 +455,7 @@ export function routeWorkStart(
       severity: policy.decision === 'denied' ? 'blocked' : 'needs_review',
       creationReason: !input.modeInput.scopeClear
         ? 'invalid_objective'
-        : policy.decision === 'approval_required'
+        : approvalRequired
           ? (input.modeInput.destructive ? 'destructive_action_requires_confirmation' : 'policy_approval_required')
           : 'missing_authorization',
       reason: mode.reason,
@@ -501,13 +468,13 @@ export function routeWorkStart(
       },
       attemptedActions: ['route_execution_mode'],
       evidenceRefs: [],
-      blockingDecision: policy.decision === 'approval_required'
+      blockingDecision: approvalRequired
         ? 'Approve side effects or restate a safer objective.'
         : 'Clarify objective, scope, and acceptance criteria.',
       recommendedDecision: 'Provide a clear objective and authorization, or cancel the request.',
       recommendedPrompt: `Resolve handoff and restate work for repo ${ctx.repoId}.`,
       recommendedContinuationPrompt: `After approval, start the approved work for ${ctx.repoId}.`,
-      approvalAction: policy.decision === 'approval_required'
+      approvalAction: approvalRequired
         ? {
             operation: 'start',
             label: 'Approve and start work',
@@ -528,6 +495,9 @@ export function routeWorkStart(
               requiresApproval: input.modeInput.requiresApproval === true || input.modeInput.requiresUserApproval === true,
               destructive: input.modeInput.destructive === true,
               accessMode: input.constraints?.accessMode,
+              workspaceMode: placementConstraint.workspaceMode,
+              requireWorktree: placementConstraint.requireWorktree,
+              directMainProhibited: placementConstraint.directMainProhibited,
               approvalConfirmed: true,
               forceMode: 'goal_workloop',
             },
@@ -545,7 +515,7 @@ export function routeWorkStart(
     });
 
     return buildFacadeResult({
-      status: policy.decision === 'denied' ? 'blocked' : policy.decision === 'approval_required' ? 'approval_required' : 'blocked',
+      status: policy.decision === 'denied' ? 'blocked' : approvalRequired ? 'approval_required' : 'blocked',
       summary: `Handoff-only: no WorkContract created and no execution started. ${mode.reason}`,
       data: {
         mode,
@@ -575,7 +545,12 @@ export function routeWorkStart(
     });
   }
 
-  return startGoalWorkloop(ctx, input, policy, 'goal_workloop', mode.routeDecision);
+  return startGoalWorkloop(ctx, {
+    ...input,
+    constraints: canonicalConstraints,
+    modeInput: effectiveModeInput,
+    workKind: effectiveWorkKind,
+  }, policy, 'goal_workloop', mode.routeDecision);
 }
 
 export function startGoalWorkloop(
@@ -585,6 +560,22 @@ export function startGoalWorkloop(
   executionMode: 'direct_control' | 'goal_workloop' = 'goal_workloop',
   routeDecision = selectExecutionMode({ ...input.modeInput, objective: input.objective, knownPaths: input.allowedPaths }).routeDecision,
 ): FacadeResult {
+  const placementResolution = resolveWorkspaceAdmissionConstraint(input.constraints);
+  if (placementResolution.ok === false) {
+    return buildFacadeResult({
+      status: 'blocked',
+      summary: `${placementResolution.code}: ${placementResolution.message}`,
+      data: { executionStarted: false, workContractCreated: false, placementConstraintConflict: true },
+      rawAvailable: false,
+    });
+  }
+  const placementConstraint = placementResolution.constraint;
+  const canonicalConstraints: WorkContract['constraints'] = {
+    ...(input.constraints ?? {}),
+    workspaceMode: placementConstraint.workspaceMode,
+    requireWorktree: placementConstraint.requireWorktree,
+    directMainProhibited: placementConstraint.directMainProhibited,
+  };
   const hasStrongAdmissionBinding = Boolean(input.planId || input.planStepId || input.requirementId || input.relatedWorkId || input.workRelation);
   if (hasStrongAdmissionBinding && !ctx.semanticAdmissionLocked) {
     return withPrimaryWorkAdmissionLock(ctx.workStore, () => startGoalWorkloop(
@@ -597,7 +588,7 @@ export function startGoalWorkloop(
   }
   const at = nowIso(ctx);
   const available = ctx.availableChecks ?? [];
-  const workspaceMode = input.constraints?.workspaceMode ?? 'auto';
+  const workspaceMode = placementConstraint.workspaceMode;
   const activeWorks = listWorkContracts({ ...ctx.workStore, status: 'active', limit: 100 })
     .filter((candidate) => (candidate.lifecycleRole ?? 'primary') === 'primary');
   const workspaceOwner = ctx.checkoutId
@@ -803,11 +794,10 @@ export function startGoalWorkloop(
   }
 
   const placementConflict = Boolean(workspaceOwner);
-  const needsWorktree = executionMode === 'goal_workloop' && (input.constraints?.requireWorktree
-    ?? (workspaceMode === 'isolated'
-      || placementConflict
-      || input.modeInput.requiresParallelism === true
-      || (workspaceMode === 'auto' && routeDecision.requiresIsolation === true)));
+  const needsWorktree = executionMode === 'goal_workloop' && (placementConstraint.requireWorktree
+    || placementConflict
+    || input.modeInput.requiresParallelism === true
+    || routeDecision.requiresIsolation === true);
   if (!needsWorktree && workspaceOwner) {
     return buildFacadeResult({
       status: 'blocked',
@@ -863,11 +853,17 @@ export function startGoalWorkloop(
   const repositoryChangeIntent = input.workKind === 'repository_change'
     || (input.modeInput.expectedFiles ?? 0) > 0
     || (input.modeInput.expectedChangedLines ?? 0) > 0;
+  const typedRecoverableReadOnlyReview = input.workKind === undefined
+    && input.modeInput.mutation === false
+    && input.modeInput.requiresInvestigation === true
+    && input.modeInput.requiresRecovery === true;
   const resolvedWorkKind = input.workKind ?? (
-    input.modeInput.requiresExternalEffect === true
-    && !repositoryChangeIntent
-      ? (input.modeInput.remoteWrite === true ? 'remote_effect' : 'local_effect')
-      : 'repository_change'
+    typedRecoverableReadOnlyReview
+      ? 'read_only_review'
+      : input.modeInput.requiresExternalEffect === true
+        && !repositoryChangeIntent
+        ? (input.modeInput.remoteWrite === true ? 'remote_effect' : 'local_effect')
+        : 'repository_change'
   );
   const remoteDeliveryRequired = resolvedWorkKind === 'repository_change'
     && input.modeInput.requiresExternalEffect === true
@@ -886,7 +882,7 @@ export function startGoalWorkloop(
     objective: input.objective,
     acceptanceCriteria: effectiveAcceptanceCriteria,
     constraints: {
-      ...(input.constraints ?? { requireHandoffOnAmbiguity: true }),
+      ...canonicalConstraints,
       ...(remoteDeliveryRequired ? { remoteDeliveryRequired: true } : {}),
     },
     risk: workRiskFor(input),
@@ -1030,6 +1026,24 @@ export function continueGoalWorkloop(ctx: GoalWorkloopContext, input: GoalWorklo
     });
   }
 
+  if ((input.reviewFindings?.length ?? 0) > 0 && work.workKind !== 'read_only_review') {
+    return buildFacadeResult({
+      status: 'blocked',
+      summary: `READ_ONLY_REVIEW_FINDINGS_KIND_REQUIRED: ${work.workId} is ${work.workKind}, not read_only_review.`,
+      data: { work: summarizeWorkContract(work), reviewFindingsRecorded: false },
+    });
+  }
+  if (work.workKind === 'read_only_review') {
+    const sourceIdentity = evaluateReadOnlyReviewSourceIdentity(work, ctx.sourceRevision, ctx.workspaceChangedPaths);
+    if (sourceIdentity.status !== 'complete') {
+      return buildFacadeResult({
+        status: 'blocked',
+        summary: `READ_ONLY_REVIEW_SOURCE_IDENTITY_REQUIRED: ${sourceIdentity.reasons.join(' ')}`,
+        data: { work: summarizeWorkContract(work), sourceIdentityProven: false },
+      });
+    }
+  }
+
   const explicitPolicyScope = input.allowedPaths !== undefined
     || input.forbiddenPaths !== undefined
     || input.checks !== undefined;
@@ -1072,6 +1086,104 @@ export function continueGoalWorkloop(ctx: GoalWorkloopContext, input: GoalWorklo
       inspectedPaths: input.inspectedPaths,
     });
   }
+  if ((input.acceptanceEvidence?.length ?? 0) > 0) {
+    if (work.workKind !== 'local_effect') {
+      return buildFacadeResult({
+        status: 'blocked',
+        summary: `WORK_SEMANTIC_ACCEPTANCE_LOCAL_EFFECT_REQUIRED: ${work.workId} is ${work.workKind}.`,
+        data: { work: summarizeWorkContract(work), semanticAcceptanceRecorded: false },
+      });
+    }
+    const declaredCriteria = new Map(work.acceptanceCriteria.map((criterion) => [criterion.trim(), criterion]));
+    const availableEvidenceIds = new Set([
+      ...work.evidenceRefs.flatMap((evidence) => [evidence.evidenceId, evidence.artifactId])
+        .map((value) => value?.trim())
+        .filter((value): value is string => Boolean(value)),
+      ...(ctx.workBoundProcessEvidenceIds ?? []).map((value) => value.trim()).filter(Boolean),
+    ]);
+    const normalizedBindings: Array<{ criterion: string; evidenceIds: string[]; rationale: string }> = [];
+    for (const binding of input.acceptanceEvidence ?? []) {
+      const requestedCriterion = binding.criterion.trim();
+      const criterion = declaredCriteria.get(requestedCriterion);
+      if (!criterion) {
+        return buildFacadeResult({
+          status: 'blocked',
+          summary: `WORK_SEMANTIC_ACCEPTANCE_CRITERION_UNKNOWN: ${requestedCriterion || '<empty>'}.`,
+          data: { work: summarizeWorkContract(work), semanticAcceptanceRecorded: false },
+        });
+      }
+      const evidenceIds = [...new Set(binding.evidenceIds.map((value) => value.trim()).filter(Boolean))];
+      if (evidenceIds.length === 0) {
+        return buildFacadeResult({
+          status: 'blocked',
+          summary: `WORK_SEMANTIC_ACCEPTANCE_EVIDENCE_REQUIRED: ${criterion}.`,
+          data: { work: summarizeWorkContract(work), semanticAcceptanceRecorded: false },
+        });
+      }
+      const unknownEvidenceIds = evidenceIds.filter((evidenceId) => !availableEvidenceIds.has(evidenceId));
+      if (unknownEvidenceIds.length > 0) {
+        return buildFacadeResult({
+          status: 'blocked',
+          summary: `WORK_SEMANTIC_ACCEPTANCE_EVIDENCE_UNKNOWN: ${unknownEvidenceIds.join(', ')}.`,
+          data: { work: summarizeWorkContract(work), semanticAcceptanceRecorded: false },
+        });
+      }
+      const rationale = binding.rationale.trim();
+      if (!rationale) {
+        return buildFacadeResult({
+          status: 'blocked',
+          summary: `WORK_SEMANTIC_ACCEPTANCE_RATIONALE_REQUIRED: ${criterion}.`,
+          data: { work: summarizeWorkContract(work), semanticAcceptanceRecorded: false },
+        });
+      }
+      normalizedBindings.push({ criterion, evidenceIds, rationale: rationale.slice(0, 1_000) });
+    }
+    const recordedAt = nowIso(ctx);
+    const byCriterion = new Map((work.semanticAcceptanceEvidence ?? []).map((review) => [review.criterion, review]));
+    for (const binding of normalizedBindings) {
+      const previous = byCriterion.get(binding.criterion);
+      byCriterion.set(binding.criterion, {
+        criterion: binding.criterion,
+        evidenceIds: [...new Set([...(previous?.evidenceIds ?? []), ...binding.evidenceIds])].slice(0, 50),
+        rationale: binding.rationale,
+        recordedAt,
+      });
+    }
+    work = updateWorkContract(ctx.workStore, work.workId, {
+      semanticAcceptanceEvidence: [...byCriterion.values()].slice(0, 20),
+    });
+    work = appendWorkEvidence(ctx.workStore, work.workId, {
+      title: 'Controller semantic acceptance review',
+      summary: `Controller reviewed ${normalizedBindings.length} exact acceptance criterion binding(s) against durable Work evidence.`,
+      detailLevel: 'summary',
+    });
+  }
+
+  if (work.workKind === 'read_only_review' && ((input.inspectedPaths?.length ?? 0) > 0 || input.reviewFindings !== undefined)) {
+    const findings = [...new Set([
+      ...(work.readOnlyReviewEvidence?.findings ?? []),
+      ...(input.reviewFindings ?? []).map((finding) => finding.trim()).filter(Boolean),
+    ])].slice(0, 50);
+    const inspectedPaths = [...new Set(work.scopeEvidence?.inspectedPaths ?? [])].slice(0, 200);
+    work = updateWorkContract(ctx.workStore, work.workId, {
+      readOnlyReviewEvidence: {
+        sourceRevision: ctx.sourceRevision!,
+        ...(ctx.workspaceFingerprint ? { workspaceFingerprint: ctx.workspaceFingerprint } : {}),
+        inspectedPaths,
+        findings,
+        recordedAt: nowIso(ctx),
+      },
+    });
+    for (const finding of input.reviewFindings ?? []) {
+      const summary = finding.trim();
+      if (!summary) continue;
+      work = appendWorkEvidence(ctx.workStore, work.workId, {
+        title: 'read-only review finding',
+        summary: summary.slice(0, 1_500),
+        detailLevel: 'summary',
+      });
+    }
+  }
 
   const currentCheckRefs = work.checkRefs.filter((record) =>
     verificationRecordAppliesToCurrentWorkspace(record, ctx.sourceRevision, ctx.workspaceFingerprint));
@@ -1104,7 +1216,7 @@ export function continueGoalWorkloop(ctx: GoalWorkloopContext, input: GoalWorklo
         acceptanceFailures: history.acceptanceFailures,
         infrastructureIssues: history.infrastructureIssues,
         backgroundCompleted: false,
-        nextStep: 'execute',
+        nextStep: work.workKind === 'read_only_review' ? 'review' : 'execute',
         acceptanceFailureDecision: decision,
       },
       evidenceRefs: work.evidenceRefs.slice(0, 5),
@@ -1368,7 +1480,13 @@ export function continueGoalWorkloop(ctx: GoalWorkloopContext, input: GoalWorklo
     });
   }
 
-  const completionEvidence = evaluateWorkCompletionEvidence(work, ctx.sourceRevision, ctx.workspaceFingerprint);
+  const completionEvidence = evaluateWorkCompletionEvidence(
+    work,
+    ctx.sourceRevision,
+    ctx.workspaceFingerprint,
+    ctx.workBoundProcessEvidenceIds,
+    ctx.workspaceChangedPaths,
+  );
   if (completionEvidence.status !== 'complete') {
     const suggested = validateSuggestedNextActions([
       {
@@ -1383,9 +1501,11 @@ export function continueGoalWorkloop(ctx: GoalWorkloopContext, input: GoalWorklo
     ]).actions;
     transitionWorkContractPhase(ctx.workStore, work.workId, {
       status: 'running',
-      phase: 'implementation',
+      phase: work.workKind === 'read_only_review' ? 'verification' : 'implementation',
       state: 'active',
-      summary: `Meaningful implementation evidence is still missing: ${completionEvidence.reasons.join(' ')}`,
+      summary: work.workKind === 'read_only_review'
+        ? `Read-only review completion evidence is incomplete: ${completionEvidence.reasons.join(' ')}`
+        : `Meaningful implementation evidence is still missing: ${completionEvidence.reasons.join(' ')}`,
       evidenceRefs: work.evidenceRefs,
     });
     const updated = updateWorkContract(ctx.workStore, work.workId, {
@@ -1398,7 +1518,7 @@ export function continueGoalWorkloop(ctx: GoalWorkloopContext, input: GoalWorklo
         work: summarizeWorkContract(updated),
         backgroundCompleted: false,
         nextStep: 'execute',
-        executionEvidencePresent: false,
+        executionEvidencePresent: Boolean(ctx.workBoundProcessEvidenceIds?.length),
         missingChecks: completionEvidence.missingChecks,
         durableResultEvidence: completionEvidence.durableResultEvidence,
         ignoredWeakReferences: {
@@ -1424,7 +1544,9 @@ export function continueGoalWorkloop(ctx: GoalWorkloopContext, input: GoalWorklo
     status: 'running',
     phase: 'delivery',
     state: 'active',
-    summary: 'Implementation and verification evidence are sufficient; exact delivery and cleanup receipt is next.',
+    summary: work.workKind === 'read_only_review'
+      ? 'Read-only review evidence is source-bound and clean; semantic no-change finalization is next.'
+      : 'Implementation and verification evidence are sufficient; exact delivery and cleanup receipt is next.',
     evidenceRefs: work.evidenceRefs,
   });
   const updated = updateWorkContract(ctx.workStore, work.workId, {
@@ -1642,7 +1764,13 @@ export function finalizeGoalWorkloop(ctx: GoalWorkloopContext, input: GoalWorklo
     });
   }
 
-  const completionEvidence = evaluateWorkCompletionEvidence(work, ctx.sourceRevision, ctx.workspaceFingerprint);
+  const completionEvidence = evaluateWorkCompletionEvidence(
+    work,
+    ctx.sourceRevision,
+    ctx.workspaceFingerprint,
+    ctx.workBoundProcessEvidenceIds,
+    ctx.workspaceChangedPaths,
+  );
   const history = completionEvidence.history;
 
   if (input.forceFailed || completionEvidence.status === 'failed') {
@@ -1717,6 +1845,50 @@ export function finalizeGoalWorkloop(ctx: GoalWorkloopContext, input: GoalWorklo
     });
   }
 
+  // Read-only review completion is semantic no-change authority, not Git delivery.
+  // The exact source/workspace fence is re-evaluated above at finalize time; only
+  // a clean review with persisted inspected paths and zero findings can close.
+  if (work.workKind === 'read_only_review' && !work.completionReceipt) {
+    const reviewEvidence = work.readOnlyReviewEvidence!;
+    const recordedAt = nowIso(ctx);
+    const completed = completeWorkWithReceipt(
+      ctx.workStore,
+      work.workId,
+      {
+        schemaVersion: 1,
+        receiptId: `ROR-WORK-${randomUUID()}`,
+        source: 'read_only_review',
+        workId: work.workId,
+        baseRevision: work.baseRevision!,
+        sourceRevision: ctx.sourceRevision!,
+        ...(ctx.workspaceFingerprint ? { workspaceFingerprint: ctx.workspaceFingerprint } : {}),
+        workspaceChangedPaths: [],
+        inspectedPaths: reviewEvidence.inspectedPaths,
+        findingCount: 0,
+        recordedAt,
+      },
+      'completed_no_change',
+      'read_only_review',
+    );
+    if (completed.planId && completed.planStepId && ctx.planStore) {
+      completePlanStepForWork(ctx.planStore, { planId: completed.planId, stepId: completed.planStepId, work: completed });
+    }
+    return buildFacadeResult({
+      status: 'ok',
+      summary: `Finalize result: clean read-only review completed with no source change for ${work.workId}.`,
+      data: {
+        work: summarizeWorkContract(completed),
+        finalStatus: 'completed',
+        completionOutcome: 'completed_no_change',
+        completionReceipt: completed.completionReceipt,
+        inspectedPathCount: reviewEvidence.inspectedPaths.length,
+        hiddenFailure: false,
+      },
+      evidenceRefs: completed.evidenceRefs.slice(0, 5),
+      suggestedNextActions: [{ label: 'Read controller status', tool: 'rh_status', operation: 'get', risk: 'readonly' }],
+    });
+  }
+
   // For a controller-local effect Work, the semantic Controller's explicit
   // finalize call is the terminalization decision, but it is admissible only
   // after durable result evidence exists. Record one canonical Work receipt here
@@ -1724,7 +1896,7 @@ export function finalizeGoalWorkloop(ctx: GoalWorkloopContext, input: GoalWorklo
   // remain bound to their durable plugin action receipt in the plugin layer.
   if (work.workKind === 'local_effect' && !work.completionReceipt && completionEvidence.durableResultEvidence) {
     const recordedAt = nowIso(ctx);
-    const completed = recordWorkCompletionReceipt(
+    const completed = completeWorkWithReceipt(
       ctx.workStore,
       work.workId,
       {
@@ -1947,6 +2119,7 @@ export function runGoalWorkloop(
         planStepId: typeof args.plan_step_id === 'string' ? args.plan_step_id : undefined,
         workKind: args.work_kind === 'repository_change'
           || args.work_kind === 'completed_no_change'
+          || args.work_kind === 'read_only_review'
           || args.work_kind === 'investigation'
           || args.work_kind === 'local_effect'
           || args.work_kind === 'remote_effect'
@@ -1963,6 +2136,14 @@ export function runGoalWorkloop(
         checks: Array.isArray(args.check_ids) ? args.check_ids.map(String) : undefined,
         additionalLikelyPaths: Array.isArray(args.additional_likely_paths) ? args.additional_likely_paths.map(String) : undefined,
         inspectedPaths: Array.isArray(args.inspected_paths) ? args.inspected_paths.map(String) : undefined,
+        reviewFindings: Array.isArray(args.review_findings) ? args.review_findings.map(String) : undefined,
+        acceptanceEvidence: Array.isArray(args.acceptance_evidence)
+          ? args.acceptance_evidence.filter((value): value is Record<string, unknown> => Boolean(value) && typeof value === 'object').map((value) => ({
+              criterion: typeof value.criterion === 'string' ? value.criterion : '',
+              evidenceIds: Array.isArray(value.evidence_ids) ? value.evidence_ids.map(String) : [],
+              rationale: typeof value.rationale === 'string' ? value.rationale : '',
+            }))
+          : undefined,
         acceptanceFailureDecision: args.acceptance_failure_decision === 'repair' || args.acceptance_failure_decision === 'rescope'
           ? args.acceptance_failure_decision
           : undefined,