@moretea-labs/forge 1.7.2 → 1.8.1

package/packages/kernel/work/domain/objective-graph.ts

@@ -0,0 +1,119 @@
+import type { WorkContract, WorkSemanticView } from './types';
+
+export const MAX_WORK_OBJECTIVE_RELATIONS = 32;
+export const MAX_WORK_OBJECTIVE_GRAPH_NODES = 100;
+export const MAX_WORK_OBJECTIVE_GRAPH_HISTORY_NODES = 200;
+
+export function normalizeWorkObjectiveRelationIds(ids: readonly string[] | undefined): string[] {
+  return [...new Set((ids ?? []).map((id) => id.trim()).filter(Boolean))].sort();
+}
+
+export function validateWorkObjectiveRelationShape(
+  work: Pick<WorkContract, 'workId' | 'lifecycleRole' | 'semanticParentWorkId' | 'dependsOnWorkIds'>,
+): void {
+  const workId = work.workId.trim();
+  const semanticParentWorkId = work.semanticParentWorkId?.trim();
+  const dependsOnWorkIds = normalizeWorkObjectiveRelationIds(work.dependsOnWorkIds);
+  if ((semanticParentWorkId || dependsOnWorkIds.length > 0) && (work.lifecycleRole ?? 'primary') !== 'primary') {
+    throw new Error('WORK_OBJECTIVE_RELATION_PRIMARY_REQUIRED');
+  }
+  if (semanticParentWorkId === workId) throw new Error('WORK_SEMANTIC_PARENT_SELF_REFERENCE');
+  if (dependsOnWorkIds.includes(workId)) throw new Error('WORK_DEPENDENCY_SELF_REFERENCE');
+  if (dependsOnWorkIds.length > MAX_WORK_OBJECTIVE_RELATIONS) throw new Error('WORK_DEPENDENCY_LIMIT_EXCEEDED');
+}
+
+export interface WorkObjectiveGraphEdge {
+  kind: 'decomposition' | 'dependency';
+  fromWorkId: string;
+  toWorkId: string;
+  workRevision: number;
+}
+
+export interface WorkObjectiveGraphProjection {
+  schemaVersion: 1;
+  rootWorkId?: string;
+  current: {
+    nodes: WorkSemanticView[];
+    edges: WorkObjectiveGraphEdge[];
+    truncated: boolean;
+  };
+  history: {
+    nodes: WorkSemanticView[];
+    edges: WorkObjectiveGraphEdge[];
+    truncated: boolean;
+  };
+}
+
+function relationEdges(view: WorkSemanticView): WorkObjectiveGraphEdge[] {
+  const edges: WorkObjectiveGraphEdge[] = [];
+  const parent = view.semanticParentWorkId?.trim();
+  if (parent) edges.push({ kind: 'decomposition', fromWorkId: parent, toWorkId: view.workId, workRevision: view.revision });
+  for (const dependency of normalizeWorkObjectiveRelationIds(view.dependsOnWorkIds)) {
+    edges.push({ kind: 'dependency', fromWorkId: dependency, toWorkId: view.workId, workRevision: view.revision });
+  }
+  return edges;
+}
+
+function connectedCurrentIds(current: readonly WorkSemanticView[], rootWorkId?: string): { ids: Set<string>; truncated: boolean } {
+  const byId = new Map(current.map((view) => [view.workId, view] as const));
+  if (!rootWorkId?.trim()) {
+    const ids = new Set([...byId.keys()].sort().slice(0, MAX_WORK_OBJECTIVE_GRAPH_NODES));
+    return { ids, truncated: byId.size > ids.size };
+  }
+  const root = rootWorkId.trim();
+  if (!byId.has(root)) return { ids: new Set(), truncated: false };
+  const adjacency = new Map<string, Set<string>>();
+  const link = (left: string, right: string) => {
+    if (!byId.has(left) || !byId.has(right)) return;
+    const leftSet = adjacency.get(left) ?? new Set<string>();
+    const rightSet = adjacency.get(right) ?? new Set<string>();
+    leftSet.add(right);
+    rightSet.add(left);
+    adjacency.set(left, leftSet);
+    adjacency.set(right, rightSet);
+  };
+  for (const view of current) {
+    const parent = view.semanticParentWorkId?.trim();
+    if (parent) link(parent, view.workId);
+    for (const dependency of normalizeWorkObjectiveRelationIds(view.dependsOnWorkIds)) link(dependency, view.workId);
+  }
+  const ids = new Set<string>();
+  const queue = [root];
+  while (queue.length > 0 && ids.size < MAX_WORK_OBJECTIVE_GRAPH_NODES) {
+    const workId = queue.shift()!;
+    if (ids.has(workId)) continue;
+    ids.add(workId);
+    for (const adjacent of [...(adjacency.get(workId) ?? [])].sort()) {
+      if (!ids.has(adjacent)) queue.push(adjacent);
+    }
+  }
+  return { ids, truncated: queue.some((workId) => !ids.has(workId)) };
+}
+
+export function projectWorkObjectiveGraph(
+  currentViews: readonly WorkSemanticView[],
+  historyViews: readonly WorkSemanticView[] = [],
+  rootWorkId?: string,
+): WorkObjectiveGraphProjection {
+  const currentById = new Map(currentViews.map((view) => [view.workId, view] as const));
+  const connected = connectedCurrentIds(currentViews, rootWorkId);
+  const currentNodes = [...connected.ids]
+    .map((workId) => currentById.get(workId))
+    .filter((view): view is WorkSemanticView => Boolean(view))
+    .sort((left, right) => left.workId.localeCompare(right.workId));
+  const currentEdges = currentNodes.flatMap(relationEdges)
+    .filter((edge) => connected.ids.has(edge.fromWorkId) && connected.ids.has(edge.toWorkId))
+    .sort((left, right) => `${left.kind}:${left.fromWorkId}:${left.toWorkId}`.localeCompare(`${right.kind}:${right.fromWorkId}:${right.toWorkId}`));
+  const allHistory = historyViews
+    .filter((view) => connected.ids.has(view.workId))
+    .sort((left, right) => left.workId.localeCompare(right.workId) || right.revision - left.revision);
+  const historyNodes = allHistory.slice(0, MAX_WORK_OBJECTIVE_GRAPH_HISTORY_NODES);
+  const historyEdges = historyNodes.flatMap(relationEdges)
+    .filter((edge) => connected.ids.has(edge.fromWorkId) && connected.ids.has(edge.toWorkId));
+  return {
+    schemaVersion: 1,
+    ...(rootWorkId?.trim() ? { rootWorkId: rootWorkId.trim() } : {}),
+    current: { nodes: currentNodes, edges: currentEdges, truncated: connected.truncated },
+    history: { nodes: historyNodes, edges: historyEdges, truncated: allHistory.length > historyNodes.length },
+  };
+}

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

@@ -0,0 +1,224 @@
+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 ProjectEngineeringContractSkillBinding {
+  id: string;
+  version?: string;
+  kinds: string[];
+}
+
+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[];
+  skillBindings?: ProjectEngineeringContractSkillBinding[];
+  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 skillBindings = root.skillBindings === undefined
+    ? []
+    : objectList(root.skillBindings, 'PROJECT_ENGINEERING_CONTRACT_SKILL_BINDINGS_INVALID').map((item) => {
+      const kinds = stringList(item.kinds, 'PROJECT_ENGINEERING_CONTRACT_SKILL_KINDS_INVALID')
+        .map((kind) => kind.toLowerCase());
+      if (kinds.length === 0 || new Set(kinds).size !== kinds.length) {
+        throw new Error('PROJECT_ENGINEERING_CONTRACT_SKILL_KINDS_INVALID');
+      }
+      return {
+        id: text(item.id, 'PROJECT_ENGINEERING_CONTRACT_SKILL_BINDING_ID_INVALID'),
+        ...(item.version === undefined ? {} : { version: text(item.version, 'PROJECT_ENGINEERING_CONTRACT_SKILL_BINDING_VERSION_INVALID') }),
+        kinds,
+      };
+    });
+  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], ['skill_binding', skillBindings], ['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'),
+    skillBindings,
+    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' | 'work_fast_forward' | '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/{src/runtime/control-plane/facade/work-state-machine.ts → packages/kernel/work/domain/state-machine.ts}

@@ -1,4 +1,7 @@
+import { assertImplementationReviewHistoryAppendOnly, validateImplementationReviewRecord } from './implementation-review';
+import { normalizeWorkObjectiveRelationIds, validateWorkObjectiveRelationShape } from './objective-graph';
 import {
+  WORK_PHASES,
   isDirectEditWorkCompletionReceipt,
   isReadOnlyReviewCompletionReceipt,
   isRemoteEffectCompletionReceipt,
@@ -8,21 +11,20 @@ import {
   type EvidenceState,
   type SuggestedNextAction,
   type WorkContract,
-  type WorkContractStatus,
   type WorkPhase,
   type WorkPhaseEvidence,
   type WorkPhaseEvidenceMap,
 } from './types';
 
 export function phaseIndex(phase: WorkPhase): number {
-  return ['implementation', 'verification', 'delivery', 'cleanup'].indexOf(phase);
+  return WORK_PHASES.indexOf(phase);
 }
 
 export function transitionPhaseEvidence(
   current: Pick<WorkContract, 'phaseEvidence' | 'evidenceRefs'>,
   targetPhase: WorkPhase,
   input: {
-    status: WorkContractStatus;
+    state?: WorkPhaseEvidence['state'];
     summary: string;
     evidenceRefs?: EvidenceRef[];
     recordedAt: string;
@@ -33,7 +35,7 @@ export function transitionPhaseEvidence(
   const evidenceRefs = (input.evidenceRefs ?? current.evidenceRefs).slice(0, 20);
   const source = input.source ?? 'recorded';
   const phaseEvidence = { ...current.phaseEvidence };
-  for (const phase of ['implementation', 'verification', 'delivery', 'cleanup'] as WorkPhase[]) {
+  for (const phase of WORK_PHASES) {
     const index = phaseIndex(phase);
     if (index < targetIndex) {
       phaseEvidence[phase] = {
@@ -54,13 +56,7 @@ export function transitionPhaseEvidence(
     }
   }
   phaseEvidence[targetPhase] = {
-    state: input.status === 'failed'
-      ? 'failed'
-      : input.status === 'cancelled'
-        ? 'skipped'
-        : input.status === 'blocked' || input.status === 'ready'
-          ? 'blocked'
-          : 'active',
+    state: input.state ?? 'active',
     source,
     summary: input.summary.trim().slice(0, 1_000) || `Work entered ${targetPhase}.`,
     evidenceRefs,
@@ -71,24 +67,9 @@ export function transitionPhaseEvidence(
 
 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 ['implementation', 'verification', 'delivery', 'cleanup'] as WorkPhase[]) {
-    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}`);
-    }
-  }
+  validateWorkObjectiveRelationShape(contract);
+  if (!['open', 'completed', 'cancelled'].includes(contract.semanticState)) throw new Error('WORK_SEMANTIC_STATE_INVALID');
+  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');
@@ -113,7 +94,9 @@ export function validateWorkSemantics(contract: WorkContract): WorkContract {
       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');
+      // Findings are durable observations the model/user acts on; they never block
+      // terminal completion. Only the exact inspected scope must stay consistent.
+      if (receipt.inspectedPaths.length === 0) throw new Error('WORK_COMPLETION_RECEIPT_READ_ONLY_REVIEW_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])) {
@@ -140,29 +123,15 @@ export function validateWorkSemantics(contract: WorkContract): WorkContract {
       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 ['implementation', 'verification', 'delivery', 'cleanup'] as WorkPhase[]) {
-      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}`);
-      }
-    }
+    // Delivery/effect receipts are mechanical evidence. They never require or imply semantic completion.
   }
   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 (!contract.completionReceipt) {
+    throw new Error(`WORK_SEMANTICS_INVALID: ${outcome} requires a delivery/effect receipt`);
   }
+  // completionOutcome classifies the attached delivery/effect receipt only.
+  // Dispatch and generic evidence axes remain independent execution observations.
   if (outcome === 'completed_changed' && contract.workKind !== 'repository_change') {
     throw new Error('WORK_SEMANTICS_INVALID: completed_changed requires repository_change WorkKind');
   }
@@ -211,22 +180,12 @@ const EVIDENCE_TRANSITIONS: Readonly<Record<EvidenceState, readonly EvidenceStat
 export function validateWorkSemanticTransition(
   current: WorkContract,
   next: WorkContract,
-  options: { allowRetainedCancelledResume?: boolean } = {},
+  options: { 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.phase === 'cleanup'
-    && current.phaseEvidence.cleanup.state === 'skipped'
-    && !current.completionReceipt
-    && !current.completionOutcome
-    && next.status === 'running'
-    && next.dispatchState === 'running'
-    && next.phase === 'implementation';
-  if (!retryingFailedWork && !resumingRetainedCancelledWork && !DISPATCH_TRANSITIONS[current.dispatchState].includes(next.dispatchState)) {
+  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 (!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)) {
@@ -241,10 +200,22 @@ export function validateWorkSemanticTransition(
   if (current.parentWorkId !== next.parentWorkId) {
     throw new Error('WORK_SEMANTICS_TRANSITION_INVALID: parentWorkId is immutable');
   }
+  if (current.semanticParentWorkId !== next.semanticParentWorkId) {
+    throw new Error('WORK_SEMANTICS_TRANSITION_INVALID: semanticParentWorkId requires semantic CAS');
+  }
+  const currentDependencies = normalizeWorkObjectiveRelationIds(current.dependsOnWorkIds).sort();
+  const nextDependencies = normalizeWorkObjectiveRelationIds(next.dependsOnWorkIds).sort();
+  if (currentDependencies.length !== nextDependencies.length || currentDependencies.some((id, index) => id !== nextDependencies[index])) {
+    throw new Error('WORK_SEMANTICS_TRANSITION_INVALID: dependsOnWorkIds requires semantic CAS');
+  }
+  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 [];
+export function suggestedActionsForSemanticState(state: 'open' | 'completed' | 'cancelled', actions: readonly SuggestedNextAction[]): SuggestedNextAction[] {
+  if (state !== 'open') return [];
   return actions.slice(0, 8);
 }