@moretea-labs/forge 1.7.2 → 1.8.0

package/packages/kernel/work/domain/project-engineering-contract.ts

@@ -0,0 +1,202 @@
+import type { EngineeringRiskClass, ProjectEngineeringContractReceipt } from './engineering-contracts';
+
+export const PROJECT_ENGINEERING_CONTRACT_SCHEMA_VERSION = 1 as const;
+export const DEFAULT_PROJECT_ENGINEERING_CONTRACT_PATH = '.forge/project-engineering.json' as const;
+const MAX_CONTRACT_ITEMS = 128;
+const MAX_TEXT = 2_000;
+
+export interface ProjectEngineeringContractCheck {
+  id: string;
+  purpose?: string;
+}
+
+export interface ProjectEngineeringContractJourney {
+  id: string;
+  purpose: string;
+  requiredFor?: EngineeringRiskClass[];
+}
+
+export interface ProjectEngineeringContractToolingRequirement {
+  id: string;
+  purpose?: string;
+  requiredFor?: EngineeringRiskClass[];
+}
+
+export interface ProjectEngineeringContractException {
+  id: string;
+  scope: string;
+  rationale: string;
+}
+
+export interface ProjectKnowledgeSource {
+  id: string;
+  kind: 'repository' | 'brain';
+  /** Relative to the repository or the explicitly configured Brain root. */
+  path: string;
+  required?: boolean;
+  expiresAt?: string;
+  applicability?: { channel?: string; account?: string; locale?: string };
+}
+
+export function validateProjectKnowledgeSources(value: unknown): ProjectKnowledgeSource[] {
+  if (value === undefined) return [];
+  const sources = objectList(value, 'PROJECT_KNOWLEDGE_SOURCES_INVALID').map((item): ProjectKnowledgeSource => {
+    const kind = item.kind;
+    if (kind !== 'repository' && kind !== 'brain') throw new Error('PROJECT_KNOWLEDGE_KIND_INVALID');
+    const path = text(item.path, 'PROJECT_KNOWLEDGE_PATH_INVALID');
+    if (/^(?:[/\\]|[A-Za-z]:)/.test(path) || path.split(/[/\\]/).includes('..')) throw new Error('PROJECT_KNOWLEDGE_PATH_INVALID');
+    if (item.required !== undefined && typeof item.required !== 'boolean') throw new Error('PROJECT_KNOWLEDGE_REQUIRED_INVALID');
+    if (item.expiresAt !== undefined && (typeof item.expiresAt !== 'string' || !Number.isFinite(Date.parse(item.expiresAt)))) throw new Error('PROJECT_KNOWLEDGE_EXPIRY_INVALID');
+    const applicability: NonNullable<ProjectKnowledgeSource['applicability']> = {};
+    if (item.applicability !== undefined) {
+      for (const [key, value] of Object.entries(object(item.applicability, 'PROJECT_KNOWLEDGE_APPLICABILITY_INVALID'))) {
+        if (!['channel', 'account', 'locale'].includes(key)) throw new Error('PROJECT_KNOWLEDGE_APPLICABILITY_INVALID');
+        applicability[key as keyof typeof applicability] = text(value, 'PROJECT_KNOWLEDGE_APPLICABILITY_INVALID');
+      }
+      if (applicability.account && !applicability.channel) throw new Error('PROJECT_KNOWLEDGE_CHANNEL_REQUIRED');
+    }
+    return { id: text(item.id, 'PROJECT_KNOWLEDGE_ID_INVALID'), kind, path, required: item.required as boolean | undefined,
+      expiresAt: item.expiresAt as string | undefined, applicability };
+  });
+  if (new Set(sources.map(source => source.id)).size !== sources.length) throw new Error('PROJECT_KNOWLEDGE_ID_DUPLICATE');
+  return sources;
+}
+
+/**
+ * Source-controlled project facts consumed by the generic Engineering Workloop.
+ * Generic language/debug/review method belongs in EngineeringWorkProfile/Skills,
+ * never in this project-owned contract.
+ */
+export interface ProjectEngineeringContract {
+  schemaVersion: 1;
+  contractId: string;
+  contractVersion: string;
+  projectId: string;
+  authority: {
+    product?: string[];
+    architecture?: string[];
+    source?: string[];
+  };
+  quality: {
+    ux?: string[];
+    performance?: string[];
+    nonRegression?: string[];
+  };
+  checks: ProjectEngineeringContractCheck[];
+  journeys: ProjectEngineeringContractJourney[];
+  platforms?: string[];
+  tooling?: ProjectEngineeringContractToolingRequirement[];
+  skillRefs?: string[];
+  exceptions?: ProjectEngineeringContractException[];
+  knowledgeSources?: ProjectKnowledgeSource[];
+}
+
+function text(value: unknown, code: string): string {
+  if (typeof value !== 'string') throw new Error(code);
+  const normalized = value.trim();
+  if (!normalized || normalized.length > MAX_TEXT) throw new Error(code);
+  return normalized;
+}
+
+function stringList(value: unknown, code: string): string[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > MAX_CONTRACT_ITEMS) throw new Error(code);
+  const normalized = value.map((item) => text(item, code));
+  if (new Set(normalized).size !== normalized.length) throw new Error(`${code}_DUPLICATE`);
+  return normalized;
+}
+
+function riskClasses(value: unknown, code: string): EngineeringRiskClass[] | undefined {
+  if (value === undefined) return undefined;
+  const values = stringList(value, code);
+  const allowed = new Set<EngineeringRiskClass>(['low', 'normal', 'high', 'critical']);
+  for (const item of values) if (!allowed.has(item as EngineeringRiskClass)) throw new Error(code);
+  return values as EngineeringRiskClass[];
+}
+
+function object(value: unknown, code: string): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(code);
+  return value as Record<string, unknown>;
+}
+
+function objectList(value: unknown, code: string): Record<string, unknown>[] {
+  if (!Array.isArray(value) || value.length > MAX_CONTRACT_ITEMS) throw new Error(code);
+  return value.map((item) => object(item, code));
+}
+
+export function validateProjectEngineeringContractReceipt(value: ProjectEngineeringContractReceipt): ProjectEngineeringContractReceipt {
+  if (value.schemaVersion !== 1) throw new Error('PROJECT_ENGINEERING_CONTRACT_RECEIPT_SCHEMA_INVALID');
+  const contractPath = text(value.contractPath, 'PROJECT_ENGINEERING_CONTRACT_RECEIPT_PATH_INVALID');
+  if (contractPath.startsWith('/') || contractPath.split('/').includes('..')) throw new Error('PROJECT_ENGINEERING_CONTRACT_RECEIPT_PATH_INVALID');
+  const sourceRevision = text(value.sourceRevision, 'PROJECT_ENGINEERING_CONTRACT_RECEIPT_SOURCE_INVALID');
+  const contentDigest = text(value.contentDigest, 'PROJECT_ENGINEERING_CONTRACT_RECEIPT_DIGEST_INVALID');
+  if (!/^[a-f0-9]{64}$/.test(contentDigest)) throw new Error('PROJECT_ENGINEERING_CONTRACT_RECEIPT_DIGEST_INVALID');
+  if (value.provenance?.source !== 'repository' || !Number.isFinite(Date.parse(value.provenance.loadedAt))) {
+    throw new Error('PROJECT_ENGINEERING_CONTRACT_RECEIPT_PROVENANCE_INVALID');
+  }
+  return {
+    schemaVersion: 1,
+    contractPath,
+    projectId: text(value.projectId, 'PROJECT_ENGINEERING_CONTRACT_RECEIPT_PROJECT_INVALID'),
+    contractId: text(value.contractId, 'PROJECT_ENGINEERING_CONTRACT_RECEIPT_CONTRACT_INVALID'),
+    contractVersion: text(value.contractVersion, 'PROJECT_ENGINEERING_CONTRACT_RECEIPT_VERSION_INVALID'),
+    sourceRevision,
+    contentDigest,
+    provenance: { source: 'repository', loadedAt: value.provenance.loadedAt },
+  };
+}
+
+export function validateProjectEngineeringContract(value: unknown): ProjectEngineeringContract {
+  const root = object(value, 'PROJECT_ENGINEERING_CONTRACT_INVALID');
+  if (root.schemaVersion !== PROJECT_ENGINEERING_CONTRACT_SCHEMA_VERSION) {
+    throw new Error('PROJECT_ENGINEERING_CONTRACT_SCHEMA_UNSUPPORTED');
+  }
+  const authority = object(root.authority ?? {}, 'PROJECT_ENGINEERING_CONTRACT_AUTHORITY_INVALID');
+  const quality = object(root.quality ?? {}, 'PROJECT_ENGINEERING_CONTRACT_QUALITY_INVALID');
+  const checks = objectList(root.checks ?? [], 'PROJECT_ENGINEERING_CONTRACT_CHECKS_INVALID').map((item) => ({
+    id: text(item.id, 'PROJECT_ENGINEERING_CONTRACT_CHECK_ID_INVALID'),
+    ...(item.purpose === undefined ? {} : { purpose: text(item.purpose, 'PROJECT_ENGINEERING_CONTRACT_CHECK_PURPOSE_INVALID') }),
+  }));
+  const journeys = objectList(root.journeys ?? [], 'PROJECT_ENGINEERING_CONTRACT_JOURNEYS_INVALID').map((item) => ({
+    id: text(item.id, 'PROJECT_ENGINEERING_CONTRACT_JOURNEY_ID_INVALID'),
+    purpose: text(item.purpose, 'PROJECT_ENGINEERING_CONTRACT_JOURNEY_PURPOSE_INVALID'),
+    ...(item.requiredFor === undefined ? {} : { requiredFor: riskClasses(item.requiredFor, 'PROJECT_ENGINEERING_CONTRACT_JOURNEY_RISK_INVALID') }),
+  }));
+  const tooling = root.tooling === undefined ? [] : objectList(root.tooling, 'PROJECT_ENGINEERING_CONTRACT_TOOLING_INVALID').map((item) => ({
+    id: text(item.id, 'PROJECT_ENGINEERING_CONTRACT_TOOLING_ID_INVALID'),
+    ...(item.purpose === undefined ? {} : { purpose: text(item.purpose, 'PROJECT_ENGINEERING_CONTRACT_TOOLING_PURPOSE_INVALID') }),
+    ...(item.requiredFor === undefined ? {} : { requiredFor: riskClasses(item.requiredFor, 'PROJECT_ENGINEERING_CONTRACT_TOOLING_RISK_INVALID') }),
+  }));
+  const exceptions = root.exceptions === undefined ? [] : objectList(root.exceptions, 'PROJECT_ENGINEERING_CONTRACT_EXCEPTIONS_INVALID').map((item) => ({
+    id: text(item.id, 'PROJECT_ENGINEERING_CONTRACT_EXCEPTION_ID_INVALID'),
+    scope: text(item.scope, 'PROJECT_ENGINEERING_CONTRACT_EXCEPTION_SCOPE_INVALID'),
+    rationale: text(item.rationale, 'PROJECT_ENGINEERING_CONTRACT_EXCEPTION_RATIONALE_INVALID'),
+  }));
+  for (const [kind, items] of [['check', checks], ['journey', journeys], ['tooling', tooling], ['exception', exceptions]] as const) {
+    const ids = items.map((item) => item.id);
+    if (new Set(ids).size !== ids.length) throw new Error(`PROJECT_ENGINEERING_CONTRACT_${kind.toUpperCase()}_ID_DUPLICATE`);
+  }
+  return {
+    schemaVersion: 1,
+    contractId: text(root.contractId, 'PROJECT_ENGINEERING_CONTRACT_ID_INVALID'),
+    contractVersion: text(root.contractVersion, 'PROJECT_ENGINEERING_CONTRACT_VERSION_INVALID'),
+    projectId: text(root.projectId, 'PROJECT_ENGINEERING_CONTRACT_PROJECT_ID_INVALID'),
+    authority: {
+      product: stringList(authority.product, 'PROJECT_ENGINEERING_CONTRACT_PRODUCT_AUTHORITY_INVALID'),
+      architecture: stringList(authority.architecture, 'PROJECT_ENGINEERING_CONTRACT_ARCHITECTURE_AUTHORITY_INVALID'),
+      source: stringList(authority.source, 'PROJECT_ENGINEERING_CONTRACT_SOURCE_AUTHORITY_INVALID'),
+    },
+    quality: {
+      ux: stringList(quality.ux, 'PROJECT_ENGINEERING_CONTRACT_UX_INVALID'),
+      performance: stringList(quality.performance, 'PROJECT_ENGINEERING_CONTRACT_PERFORMANCE_INVALID'),
+      nonRegression: stringList(quality.nonRegression, 'PROJECT_ENGINEERING_CONTRACT_NON_REGRESSION_INVALID'),
+    },
+    checks,
+    journeys,
+    platforms: stringList(root.platforms, 'PROJECT_ENGINEERING_CONTRACT_PLATFORMS_INVALID'),
+    tooling,
+    skillRefs: stringList(root.skillRefs, 'PROJECT_ENGINEERING_CONTRACT_SKILLS_INVALID'),
+    exceptions,
+    ...(root.knowledgeSources === undefined ? {} : { knowledgeSources: validateProjectKnowledgeSources(root.knowledgeSources) }),
+  };
+}

package/packages/kernel/work/domain/repository-completion-receipt.ts

@@ -0,0 +1,73 @@
+export type CompletionReceiptSource =
+  | 'direct_edit'
+  | 'controller_work'
+  | 'isolated_agent_run'
+  | 'workspace_run'
+  | 'remote_no_change_execution';
+
+export type CompletionReceiptDeliveryKind = 'commit' | 'no_change' | 'remote' | 'superseded';
+export type CompletionReceiptDeliveryStatus = 'integrated' | 'blocked';
+export type CompletionReceiptCleanupStatus = 'complete' | 'maintenance_warning' | 'blocked';
+
+export interface CompletionMaintenanceWarning {
+  code:
+    | 'worktree_cleanup_failed'
+    | 'branch_cleanup_failed'
+    | 'edit_session_backup_retained'
+    | 'cleanup_retained_by_request';
+  message: string;
+  resourceKind?: 'worktree' | 'branch' | 'edit_session' | 'lease' | 'process' | 'workspace';
+  resourceId?: string;
+  recordedAt: string;
+}
+
+export interface CompletionResourceBlocker {
+  code:
+    | 'unintegrated_changes'
+    | 'active_write_process'
+    | 'unknown_resource_ownership'
+    | 'dirty_owned_paths'
+    | 'edit_session_open'
+    | 'lease_active'
+    | 'run_not_terminal'
+    | 'target_revision_unreachable';
+  message: string;
+  resourceKind?: 'worktree' | 'branch' | 'edit_session' | 'lease' | 'process' | 'workspace';
+  resourceId?: string;
+  recordedAt: string;
+}
+
+/** Kernel-owned repository delivery receipt; legacy Task/Issue fields remain compatibility projection identity. */
+export interface RepositoryCompletionReceipt {
+  schemaVersion: 1;
+  receiptId: string;
+  source: CompletionReceiptSource;
+  issueId: string;
+  taskId: string;
+  runId?: string;
+  workId?: string;
+  editSessionId?: string;
+  targetBranch: string;
+  targetRevision: string;
+  sourceRevision?: string;
+  baseRevision?: string;
+  changedPaths: string[];
+  delivery: {
+    kind: CompletionReceiptDeliveryKind;
+    status: CompletionReceiptDeliveryStatus;
+    strategy: 'edit_session_commit' | 'already_integrated' | 'no_change' | 'remote';
+    reachable: boolean;
+    recordedAt: string;
+  };
+  cleanup: {
+    status: CompletionReceiptCleanupStatus;
+    warnings: CompletionMaintenanceWarning[];
+    blockers: CompletionResourceBlocker[];
+    recordedAt: string;
+  };
+  verifiedAt: string;
+  recordedAt: string;
+}
+
+/** Legacy public name retained as an inward projection. */
+export type CompletionReceipt = RepositoryCompletionReceipt;

package/packages/kernel/work/domain/state-machine.ts

@@ -0,0 +1,259 @@
+import { assertImplementationReviewHistoryAppendOnly, validateImplementationReviewRecord } from './implementation-review';
+import {
+  WORK_PHASES,
+  isDirectEditWorkCompletionReceipt,
+  isReadOnlyReviewCompletionReceipt,
+  isRemoteEffectCompletionReceipt,
+  isRepositoryCompletionReceipt,
+  type DispatchState,
+  type EvidenceRef,
+  type EvidenceState,
+  type SuggestedNextAction,
+  type WorkContract,
+  type WorkContractStatus,
+  type WorkPhase,
+  type WorkPhaseEvidence,
+  type WorkPhaseEvidenceMap,
+} from './types';
+
+export function phaseIndex(phase: WorkPhase): number {
+  return WORK_PHASES.indexOf(phase);
+}
+
+export function transitionPhaseEvidence(
+  current: Pick<WorkContract, 'phaseEvidence' | 'evidenceRefs'>,
+  targetPhase: WorkPhase,
+  input: {
+    status: WorkContractStatus;
+    summary: string;
+    evidenceRefs?: EvidenceRef[];
+    recordedAt: string;
+    source?: WorkPhaseEvidence['source'];
+  },
+): WorkPhaseEvidenceMap {
+  const targetIndex = phaseIndex(targetPhase);
+  const evidenceRefs = (input.evidenceRefs ?? current.evidenceRefs).slice(0, 20);
+  const source = input.source ?? 'recorded';
+  const phaseEvidence = { ...current.phaseEvidence };
+  for (const phase of WORK_PHASES) {
+    const index = phaseIndex(phase);
+    if (index < targetIndex) {
+      phaseEvidence[phase] = {
+        state: ['satisfied', 'skipped'].includes(phaseEvidence[phase].state) ? phaseEvidence[phase].state : 'satisfied',
+        source,
+        summary: `Advanced to ${targetPhase}: ${input.summary}`.slice(0, 1_000),
+        evidenceRefs,
+        recordedAt: input.recordedAt,
+      };
+    } else if (index > targetIndex) {
+      phaseEvidence[phase] = {
+        state: 'pending',
+        source,
+        summary: `Waiting for Work phase ${phase}.`,
+        evidenceRefs: [],
+        recordedAt: input.recordedAt,
+      };
+    }
+  }
+  phaseEvidence[targetPhase] = {
+    state: input.status === 'failed'
+      ? 'failed'
+      : input.status === 'cancelled'
+        ? 'skipped'
+        : input.status === 'blocked' || input.status === 'ready'
+          ? 'blocked'
+          : 'active',
+    source,
+    summary: input.summary.trim().slice(0, 1_000) || `Work entered ${targetPhase}.`,
+    evidenceRefs,
+    recordedAt: input.recordedAt,
+  };
+  return phaseEvidence;
+}
+
+export function validateWorkSemantics(contract: WorkContract): WorkContract {
+  if (!contract.objective.trim()) throw new Error('WORK_OBJECTIVE_REQUIRED');
+  if (contract.status === 'completed' && !contract.completionReceipt) {
+    throw new Error('WORK_COMPLETION_RECEIPT_REQUIRED');
+  }
+  const currentPhaseIndex = phaseIndex(contract.phase);
+  for (const phase of WORK_PHASES) {
+    const checkpoint = contract.phaseEvidence?.[phase];
+    if (!checkpoint) throw new Error(`WORK_PHASE_EVIDENCE_REQUIRED: ${phase}`);
+    const index = phaseIndex(phase);
+    if (index < currentPhaseIndex && !['satisfied', 'skipped'].includes(checkpoint.state)) {
+      throw new Error(`WORK_PHASE_EVIDENCE_PREVIOUS_NOT_SATISFIED: ${phase}`);
+    }
+    if (index === currentPhaseIndex && checkpoint.state === 'pending') {
+      throw new Error(`WORK_PHASE_EVIDENCE_REQUIRED: ${phase}`);
+    }
+    if (index > currentPhaseIndex && checkpoint.state !== 'pending') {
+      throw new Error(`WORK_PHASE_EVIDENCE_FUTURE_NOT_PENDING: ${phase}`);
+    }
+  }
+  for (const review of contract.implementationReviews ?? []) validateImplementationReviewRecord(review);
+  if (contract.completionReceipt) {
+    const receipt = contract.completionReceipt;
+    if (receipt.workId !== contract.workId) throw new Error('WORK_COMPLETION_RECEIPT_IDENTITY_MISMATCH');
+    if (isRepositoryCompletionReceipt(receipt)) {
+      if (!receipt.targetBranch.trim() || !receipt.targetRevision.trim()) throw new Error('WORK_COMPLETION_RECEIPT_TARGET_REQUIRED');
+      if (receipt.delivery.status !== 'integrated' || !receipt.delivery.reachable) throw new Error('WORK_COMPLETION_RECEIPT_DELIVERY_NOT_PROVEN');
+      if (!['complete', 'maintenance_warning'].includes(receipt.cleanup.status) || receipt.cleanup.blockers.length > 0) throw new Error('WORK_COMPLETION_RECEIPT_CLEANUP_NOT_PROVEN');
+    } else if (isDirectEditWorkCompletionReceipt(receipt)) {
+      const directEditAuthorityCount = Number(Boolean(receipt.editSessionId?.trim())) + Number(Boolean(receipt.reconciliationId?.trim()));
+      if (directEditAuthorityCount !== 1) throw new Error('WORK_COMPLETION_RECEIPT_DIRECT_EDIT_AUTHORITY_REQUIRED');
+      if (!receipt.targetBranch.trim() || !receipt.targetRevision.trim()) throw new Error('WORK_COMPLETION_RECEIPT_TARGET_REQUIRED');
+      if (receipt.delivery.status !== 'integrated' || !receipt.delivery.reachable) throw new Error('WORK_COMPLETION_RECEIPT_DELIVERY_NOT_PROVEN');
+      if (!['complete', 'maintenance_warning'].includes(receipt.cleanup.status) || receipt.cleanup.blockers.length > 0) throw new Error('WORK_COMPLETION_RECEIPT_CLEANUP_NOT_PROVEN');
+      if (!['repository_change', 'completed_no_change'].includes(contract.workKind)) throw new Error('WORK_COMPLETION_RECEIPT_DIRECT_EDIT_KIND_REQUIRED');
+      const expectedOutcome = contract.workKind === 'completed_no_change' ? 'completed_no_change' : 'completed_changed';
+      if (contract.completionOutcome !== expectedOutcome) throw new Error('WORK_COMPLETION_RECEIPT_DIRECT_EDIT_OUTCOME_REQUIRED');
+    } else if (isReadOnlyReviewCompletionReceipt(receipt)) {
+      if (contract.workKind !== 'read_only_review') throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_KIND_REQUIRED');
+      if (contract.completionOutcome !== 'completed_no_change') throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_OUTCOME_REQUIRED');
+      if (!receipt.baseRevision.trim() || receipt.baseRevision !== receipt.sourceRevision) throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_SOURCE_REQUIRED');
+      if (contract.baseRevision && receipt.baseRevision !== contract.baseRevision) throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_BASE_MISMATCH');
+      if (receipt.workspaceChangedPaths.length !== 0) throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_WORKSPACE_CHANGED');
+      const reviewEvidence = contract.readOnlyReviewEvidence;
+      if (!reviewEvidence || reviewEvidence.sourceRevision !== receipt.sourceRevision) throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_EVIDENCE_REQUIRED');
+      if (reviewEvidence.findings.length !== 0 || receipt.findingCount !== 0 || receipt.inspectedPaths.length === 0) throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_CLEAN_SCOPE_REQUIRED');
+      const evidencePaths = [...new Set(reviewEvidence.inspectedPaths)].sort();
+      const receiptPaths = [...new Set(receipt.inspectedPaths)].sort();
+      if (evidencePaths.length !== receiptPaths.length || evidencePaths.some((path, index) => path !== receiptPaths[index])) {
+        throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_SCOPE_MISMATCH');
+      }
+      if (reviewEvidence.workspaceFingerprint && receipt.workspaceFingerprint && reviewEvidence.workspaceFingerprint !== receipt.workspaceFingerprint) {
+        throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_WORKSPACE_MISMATCH');
+      }
+    } else if (isRemoteEffectCompletionReceipt(receipt)) {
+      if (contract.workKind !== 'remote_effect') throw new Error('WORK_COMPLETION_RECEIPT_REMOTE_EFFECT_KIND_REQUIRED');
+      if (contract.completionOutcome !== 'completed_remote') throw new Error('WORK_COMPLETION_RECEIPT_REMOTE_EFFECT_OUTCOME_REQUIRED');
+      const authority = receipt.authority ?? 'plugin_action';
+      if (!receipt.actionId.trim() || !receipt.requestId.trim() || !receipt.semanticKey.trim() || !receipt.resultDigest.trim()) {
+        throw new Error('WORK_COMPLETION_RECEIPT_REMOTE_EFFECT_IDENTITY_REQUIRED');
+      }
+      if (authority === 'plugin_action' && !receipt.pluginId?.trim()) {
+        throw new Error('WORK_COMPLETION_RECEIPT_REMOTE_EFFECT_PLUGIN_IDENTITY_REQUIRED');
+      }
+      if (authority === 'repository_process' && !receipt.processId?.trim()) {
+        throw new Error('WORK_COMPLETION_RECEIPT_REMOTE_EFFECT_PROCESS_IDENTITY_REQUIRED');
+      }
+    } else {
+      if (contract.workKind !== 'local_effect') throw new Error('WORK_COMPLETION_RECEIPT_LOCAL_EFFECT_KIND_REQUIRED');
+      if (contract.completionOutcome !== 'completed_local') throw new Error('WORK_COMPLETION_RECEIPT_LOCAL_EFFECT_OUTCOME_REQUIRED');
+      if (!receipt.operation.trim() || !receipt.target.id.trim()) throw new Error('WORK_COMPLETION_RECEIPT_LOCAL_EFFECT_TARGET_REQUIRED');
+    }
+    if (contract.status !== 'completed') throw new Error('WORK_COMPLETION_RECEIPT_REQUIRES_COMPLETED_WORK');
+    for (const phase of WORK_PHASES) {
+      if (!['satisfied', 'skipped'].includes(contract.phaseEvidence[phase].state)) {
+        throw new Error(`WORK_COMPLETION_PHASE_NOT_SATISFIED: ${phase}`);
+      }
+    }
+    for (const phase of ['delivery', 'cleanup'] as WorkPhase[]) {
+      if (contract.phaseEvidence[phase].receiptId !== receipt.receiptId) {
+        throw new Error(`WORK_COMPLETION_PHASE_RECEIPT_MISMATCH: ${phase}`);
+      }
+    }
+  }
+  const outcome = contract.completionOutcome;
+  if (!outcome) return contract;
+  if (contract.status !== 'completed' || !contract.completionReceipt) {
+    throw new Error(`WORK_SEMANTICS_INVALID: ${outcome} requires a completed Work receipt`);
+  }
+  if (contract.dispatchState !== 'terminal') {
+    throw new Error(`WORK_SEMANTICS_INVALID: ${outcome} requires terminal dispatch`);
+  }
+  if (contract.evidenceState !== 'valid') {
+    throw new Error(`WORK_SEMANTICS_INVALID: ${outcome} requires valid evidence`);
+  }
+  if (outcome === 'completed_changed' && contract.workKind !== 'repository_change') {
+    throw new Error('WORK_SEMANTICS_INVALID: completed_changed requires repository_change WorkKind');
+  }
+  if (outcome === 'completed_no_change' && !['completed_no_change', 'read_only_review'].includes(contract.workKind)) {
+    throw new Error('WORK_SEMANTICS_INVALID: completed_no_change requires completed_no_change or read_only_review WorkKind');
+  }
+  if (outcome === 'completed_no_change' && contract.workKind === 'read_only_review' && contract.completionReceipt?.source !== 'read_only_review') {
+    throw new Error('WORK_SEMANTICS_INVALID: read_only_review completed_no_change requires a read_only_review completion receipt');
+  }
+  if (outcome === 'completed_local' && contract.workKind !== 'local_effect') {
+    throw new Error('WORK_SEMANTICS_INVALID: completed_local requires local_effect WorkKind');
+  }
+  if (outcome === 'completed_local' && contract.completionReceipt?.source !== 'local_effect') {
+    throw new Error('WORK_SEMANTICS_INVALID: completed_local requires a local_effect completion receipt');
+  }
+  if (outcome === 'completed_remote' && contract.workKind !== 'remote_effect') {
+    throw new Error('WORK_SEMANTICS_INVALID: completed_remote requires remote_effect WorkKind');
+  }
+  if (outcome === 'completed_remote' && contract.completionReceipt?.source !== 'remote_effect') {
+    throw new Error('WORK_SEMANTICS_INVALID: completed_remote requires a remote_effect completion receipt');
+  }
+  if (outcome === 'superseded' && contract.workKind !== 'superseded') {
+    throw new Error('WORK_SEMANTICS_INVALID: superseded requires superseded WorkKind');
+  }
+  return contract;
+}
+
+const DISPATCH_TRANSITIONS: Readonly<Record<DispatchState, readonly DispatchState[]>> = {
+  not_dispatched: ['not_dispatched', 'claimed', 'launching', 'running', 'blocked', 'terminal'],
+  claimed: ['claimed', 'launching', 'running', 'blocked', 'terminal'],
+  launching: ['launching', 'running', 'blocked', 'terminal'],
+  running: ['running', 'blocked', 'terminal'],
+  blocked: ['blocked', 'claimed', 'launching', 'running', 'terminal'],
+  terminal: ['terminal'],
+};
+
+const EVIDENCE_TRANSITIONS: Readonly<Record<EvidenceState, readonly EvidenceState[]>> = {
+  none: ['none', 'partial', 'valid', 'failed'],
+  partial: ['partial', 'valid', 'stale', 'contradictory', 'failed'],
+  valid: ['valid', 'stale', 'contradictory', 'failed'],
+  stale: ['stale', 'partial', 'valid', 'contradictory', 'failed'],
+  contradictory: ['contradictory', 'partial', 'valid', 'failed'],
+  failed: ['failed', 'partial', 'valid', 'contradictory'],
+};
+
+export function validateWorkSemanticTransition(
+  current: WorkContract,
+  next: WorkContract,
+  options: { allowRetainedCancelledResume?: boolean; allowPhaseRegression?: boolean } = {},
+): WorkContract {
+  const retryingFailedWork = current.status === 'failed'
+    && !current.completionOutcome
+    && ['claimed', 'launching', 'running', 'blocked'].includes(next.dispatchState);
+  const resumingRetainedCancelledWork = options.allowRetainedCancelledResume === true
+    && current.status === 'cancelled'
+    && current.dispatchState === 'terminal'
+    && current.phaseEvidence[current.phase].state === 'skipped'
+    && !current.completionReceipt
+    && !current.completionOutcome
+    && next.status === 'running'
+    && next.dispatchState === 'running'
+    && next.phase === 'implementation';
+  if (phaseIndex(next.phase) < phaseIndex(current.phase) && options.allowPhaseRegression !== true) {
+    throw new Error(`WORK_SEMANTICS_TRANSITION_INVALID: phase ${current.phase} -> ${next.phase} requires explicit regression authority`);
+  }
+  if (!retryingFailedWork && !resumingRetainedCancelledWork && !DISPATCH_TRANSITIONS[current.dispatchState].includes(next.dispatchState)) {
+    throw new Error(`WORK_SEMANTICS_TRANSITION_INVALID: dispatch ${current.dispatchState} -> ${next.dispatchState}`);
+  }
+  if (!EVIDENCE_TRANSITIONS[current.evidenceState].includes(next.evidenceState)) {
+    throw new Error(`WORK_SEMANTICS_TRANSITION_INVALID: evidence ${current.evidenceState} -> ${next.evidenceState}`);
+  }
+  if (current.completionOutcome && current.completionOutcome !== next.completionOutcome) {
+    throw new Error(`WORK_SEMANTICS_TRANSITION_INVALID: completion outcome ${current.completionOutcome} is immutable`);
+  }
+  if ((current.lifecycleRole ?? 'primary') !== (next.lifecycleRole ?? 'primary')) {
+    throw new Error('WORK_SEMANTICS_TRANSITION_INVALID: lifecycleRole is immutable');
+  }
+  if (current.parentWorkId !== next.parentWorkId) {
+    throw new Error('WORK_SEMANTICS_TRANSITION_INVALID: parentWorkId is immutable');
+  }
+  if (current.predecessorWorkId !== next.predecessorWorkId) {
+    throw new Error('WORK_SEMANTICS_TRANSITION_INVALID: predecessorWorkId is immutable');
+  }
+  assertImplementationReviewHistoryAppendOnly(current.implementationReviews ?? [], next.implementationReviews ?? []);
+  return next;
+}
+
+export function suggestedActionsForStatus(status: WorkContractStatus, actions: readonly SuggestedNextAction[]): SuggestedNextAction[] {
+  if (status === 'completed' || status === 'cancelled') return [];
+  return actions.slice(0, 8);
+}