@moretea-labs/forge 1.8.0 → 1.8.2

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

@@ -1,4 +1,5 @@
 import { assertImplementationReviewHistoryAppendOnly, validateImplementationReviewRecord } from './implementation-review';
+import { normalizeWorkObjectiveRelationIds, validateWorkObjectiveRelationShape } from './objective-graph';
 import {
   WORK_PHASES,
   isDirectEditWorkCompletionReceipt,
@@ -10,7 +11,6 @@ import {
   type EvidenceState,
   type SuggestedNextAction,
   type WorkContract,
-  type WorkContractStatus,
   type WorkPhase,
   type WorkPhaseEvidence,
   type WorkPhaseEvidenceMap,
@@ -24,7 +24,7 @@ export function transitionPhaseEvidence(
   current: Pick<WorkContract, 'phaseEvidence' | 'evidenceRefs'>,
   targetPhase: WorkPhase,
   input: {
-    status: WorkContractStatus;
+    state?: WorkPhaseEvidence['state'];
     summary: string;
     evidenceRefs?: EvidenceRef[];
     recordedAt: string;
@@ -56,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,
@@ -73,24 +67,8 @@ 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 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}`);
-    }
-  }
+  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;
@@ -116,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])) {
@@ -143,34 +123,27 @@ 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 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}`);
-      }
-    }
+    // 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');
   }
-  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');
+  // An empty repository delivery is evidence, not authority to rewrite WorkKind.
+  const emptyRepositoryDelivery = contract.workKind === 'repository_change'
+    && isRepositoryCompletionReceipt(contract.completionReceipt)
+    && contract.completionReceipt.delivery.kind === 'no_change'
+    && contract.completionReceipt.changedPaths.length === 0;
+  if (outcome === 'completed_no_change'
+    && !['completed_no_change', 'read_only_review'].includes(contract.workKind)
+    && !emptyRepositoryDelivery) {
+    throw new Error('WORK_SEMANTICS_INVALID: completed_no_change requires a no-change WorkKind or proven empty repository delivery');
   }
   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');
@@ -214,24 +187,12 @@ const EVIDENCE_TRANSITIONS: Readonly<Record<EvidenceState, readonly EvidenceStat
 export function validateWorkSemanticTransition(
   current: WorkContract,
   next: WorkContract,
-  options: { allowRetainedCancelledResume?: boolean; allowPhaseRegression?: 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.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)) {
+  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)) {
@@ -246,6 +207,14 @@ 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');
   }
@@ -253,7 +222,7 @@ export function validateWorkSemanticTransition(
   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);
 }

package/packages/kernel/work/domain/types.ts

@@ -1,12 +1,10 @@
 import type { ExecutionPlacement, ScopeRef } from '../../identity/api/index';
 import type { ProcessCheckReceiptEvidence } from './check-receipt';
-import type { WorkAccessMode, WorkRouteDecisionSnapshot } from './execution-snapshot';
+import type { WorkAccessMode } from './execution-snapshot';
 import type { RepositoryCompletionReceipt } from './repository-completion-receipt';
 import type { WorkImplementationReviewRecord } from './implementation-review';
 import type { EngineeringContextReceipt } from './engineering-contracts';
 
-/** Work-persisted orchestration metadata is Kernel-owned; facade is a consumer. */
-export type ExecutionMode = 'direct_control' | 'goal_workloop' | 'handoff_only';
 export type FacadeDetailLevel = 'summary' | 'detail' | 'raw';
 export interface EvidenceRef {
   evidenceId?: string;
@@ -17,7 +15,7 @@ export interface EvidenceRef {
 }
 export interface WorkExecutionConcurrencyProjection {
   schemaVersion: 1;
-  /** Projection only. Process Runtime leases and Controller ownership remain execution authority. */
+  /** Projection only. Concrete Process/resource owners remain execution authority. */
   status: 'waiting' | 'invalid';
   source: 'work_compatibility' | 'resource_lease' | 'scheduler_capacity';
   attemptId?: string;
@@ -31,7 +29,6 @@ export interface WorkExecutionConcurrencyProjection {
   wakeTrigger:
     | { kind: 'work_terminal'; workId: string }
     | { kind: 'resource_release'; resourceKeys: string[] }
-    | { kind: 'controller_release'; workId: string }
     | { kind: 'scheduler_capacity'; capacityKey: string }
     | { kind: 'work_contract_change'; workId: string };
   recordedAt: string;
@@ -39,7 +36,7 @@ export interface WorkExecutionConcurrencyProjection {
 
 export interface SuggestedNextAction {
   label: string;
-  tool: 'rh_access' | 'rh_status' | 'rh_inbox' | 'rh_context' | 'rh_work';
+  tool: 'rh_access' | 'rh_status' | 'rh_inbox' | 'rh_context' | 'rh_work' | 'capability_execute';
   operation: string;
   payload?: Record<string, unknown>;
   risk: 'readonly' | 'local_repo_write' | 'workspace_write' | 'remote_write' | 'destructive_remote' | 'destructive' | 'raw_secret_config' | 'unknown';
@@ -58,16 +55,28 @@ export interface PolicyDecision {
 }
 
 /** Canonical Kernel Work domain contracts. */
-export const WORK_CONTRACT_STATUSES = [
-  'open',
-  'running',
-  'blocked',
-  'ready',
-  'completed',
-  'failed',
-  'cancelled',
-] as const;
-export type WorkContractStatus = (typeof WORK_CONTRACT_STATUSES)[number];
+export const SEMANTIC_WORK_STATES = ['open', 'completed', 'cancelled'] as const;
+/** Thin semantic Work state. Execution/runtime conditions never add states here. */
+export type SemanticWorkState = (typeof SEMANTIC_WORK_STATES)[number];
+
+export interface WorkSemanticView {
+  workId: string;
+  revision: number;
+  semanticScope: ScopeRef;
+  objective: string;
+  state: SemanticWorkState;
+  requirementId?: string;
+  requirementRevision?: number;
+  planId?: string;
+  planRevision?: number;
+  /** Objective decomposition parent. Distinct from execution-child parentWorkId and continuation lineage. */
+  semanticParentWorkId?: string;
+  /** Explicit semantic ordering dependencies. Absence/empty means siblings are independently runnable. */
+  dependsOnWorkIds?: string[];
+  resultRefs: string[];
+  createdAt: string;
+  updatedAt: string;
+}
 
 /**
  * Work execution phases are intentionally small and technical. User-facing
@@ -95,13 +104,12 @@ export type WorkPhaseEvidenceMap = Record<WorkPhase, WorkPhaseEvidence>;
 export const WORK_RISKS = ['readonly', 'low', 'medium', 'high', 'destructive'] as const;
 export type WorkRisk = (typeof WORK_RISKS)[number];
 
-export const TERMINAL_WORK_CONTRACT_STATUSES: readonly WorkContractStatus[] = [
+export const TERMINAL_SEMANTIC_WORK_STATES: readonly SemanticWorkState[] = [
   'completed',
-  'failed',
   'cancelled',
 ] as const;
 
-/** Independent semantic axes; `status` remains a compatibility projection. */
+/** Independent execution/evidence classifications; none are Work lifecycle state. */
 export const WORK_KINDS = [
   'repository_change',
   'completed_no_change',
@@ -277,14 +285,10 @@ export interface WorkContractConstraints {
   allowMerge?: boolean;
   allowCleanup?: boolean;
   allowDestructive?: boolean;
-  requireHandoffOnAmbiguity?: boolean;
   /** Immutable execution-policy snapshot captured when work starts. */
   accessMode?: WorkAccessMode;
-  /** current is the stability-first default; isolated is opt-in or used for explicit parallelism. */
+  /** Explicit repository placement. `auto` is retained as the legacy durable-Work isolated/frozen-base default. */
   workspaceMode?: 'current' | 'isolated' | 'auto';
-  requireWorktree?: boolean;
-  /** Admission fence: repository mutation must not use the Direct Control/current-main lane. */
-  directMainProhibited?: boolean;
   /** True when a change alters the agreed architecture direction rather than only implementation details. */
   architectureStrategyChange?: boolean;
   /** True when the proposed change weakens the thin-harness / high-performance execution policy. */
@@ -295,12 +299,6 @@ export interface WorkContractConstraints {
   remoteDeliveryRequired?: boolean;
 }
 
-export interface WorkContractDriverPolicy {
-  preferred: 'direct_edit' | 'isolated_worktree' | 'external_controller' | 'handoff_only';
-  allowWorker: boolean;
-  allowDirectEdit: boolean;
-}
-
 export interface WorktreePolicy {
   required: boolean;
   reason?: string;
@@ -371,15 +369,15 @@ export interface WorkReconciliationRecord {
 }
 
 export interface WorkContract {
-  schemaVersion: 1 | 2 | 3;
+  schemaVersion: 1 | 2 | 3 | 4;
   workId: string;
   /** Portable semantic scope. New records derive this from Requirement/Plan/Work identity, never local repository registration. */
   scopeRef?: ScopeRef;
-  /** Replaceable node-local placement. repoId/checkoutId below remain compatibility fields during V2 migration. */
+  /** Replaceable node-local execution placement; never part of semantic Work identity. */
   executionPlacement?: ExecutionPlacement;
-  /** @deprecated Node-local placement compatibility field; do not use as semantic Work identity. */
+  /** Repository relationship used for local execution lookup; never semantic lifecycle authority. */
   repoId: string;
-  /** @deprecated Node-local placement compatibility field. Optional only for legacy/current-workspace records. */
+  /** Optional checkout relationship for local execution placement. */
   checkoutId?: string;
   principalId?: string;
   controllerInstanceId?: string;
@@ -387,10 +385,18 @@ export interface WorkContract {
   /** Authoritative repository baseline captured at Work admission. Absent means legacy/unknown, never implicitly unborn. */
   repositoryBaseState?: 'revision' | 'unborn';
   workspaceFingerprint?: string;
-  routeDecisionFingerprint?: string;
-  routeDecision?: WorkRouteDecisionSnapshot;
-  mode: ExecutionMode;
   objective: string;
+  /** Independent authored-context revision. Mechanical Work writes never use the SQLite row revision as semantic CAS. */
+  semanticRevision?: number;
+  /** Timestamp of the authored semantic content; mechanical Work writes must not change it. */
+  semanticUpdatedAt?: string;
+  /** The single authored Work lifecycle state. Execution/runtime conditions never add states here. */
+  semanticState: SemanticWorkState;
+  /** Optional provenance links to the Requirement/Plan semantic revisions used when this Work was authored. */
+  requirementRevision?: number;
+  planRevision?: number;
+  /** Model/user-selected semantic result references, separate from mechanical evidence and delivery receipts. */
+  semanticResultRefs?: string[];
   acceptanceCriteria: string[];
   constraints: WorkContractConstraints;
   /** Risk is immutable contract input and is projected to legacy Task reads. */
@@ -399,16 +405,20 @@ export interface WorkContract {
   engineeringContext?: EngineeringContextReceipt;
   /** Actionable concurrency wait projection. Absence means no currently known semantic/resource blocker. */
   executionConcurrency?: WorkExecutionConcurrencyProjection;
-  /** Technical phase; Requirement owns the user lifecycle. */
+  /** Repository-execution phase observation. Never semantic Work authority. */
   phase: WorkPhase;
-  /** Work-owned phase checkpoints. Task/Run/Process records may contribute evidence but cannot write this map directly. */
+  /** Mechanical phase evidence for execution/delivery observation only. */
   phaseEvidence: WorkPhaseEvidenceMap;
-  /** Explicit lifecycle semantics. `status` is retained as a compatibility/read projection, not transition authority. */
+  /** Execution/result classification. Semantic Work identity/state never depends on this field. */
   workKind: WorkKind;
   /** Primary is an objective-level business execution lane; execution_child is a resumable low-level operation handle owned by a primary Work or standalone caller. */
   lifecycleRole?: 'primary' | 'execution_child';
   /** Optional objective-level parent when this Work is only an execution child. */
   parentWorkId?: string;
+  /** Objective decomposition parent for primary semantic Work. Never execution ownership or continuation lineage. */
+  semanticParentWorkId?: string;
+  /** Explicit objective ordering dependencies for primary semantic Work. Never inferred from Plan items. */
+  dependsOnWorkIds?: string[];
   /** Immediate prior primary Work in the same semantic continuation lineage. Relationship evidence only; never execution or deletion authority. */
   predecessorWorkId?: string;
   /** Historical predecessors explicitly replaced by this Work. Relationship evidence only; never deletion authority. */
@@ -417,18 +427,18 @@ export interface WorkContract {
   supersededBy?: string;
   /** Bounded durable reason for the supersession edge. */
   supersessionReason?: string;
+  /** Mechanical execution/evidence projections; none may advance semanticState. */
   dispatchState: DispatchState;
   evidenceState: EvidenceState;
   completionOutcome?: CompletionOutcome;
-  status: WorkContractStatus;
   createdAt: string;
   updatedAt: string;
-  /** @deprecated Prefer Requirement/Plan/Work links; kept for compatibility reads only. */
+  /** Optional historical Issue/Task relationship identifiers; never lifecycle authority. */
   issueId?: string;
   taskId?: string;
   /** Stable Requirement authority that this Work may complete. */
   requirementId?: string;
-  /** Work-owned completion receipt. Legacy Task receipts are projections only. */
+  /** Work-owned delivery/effect receipt. It never determines semantic completion. */
   completionReceipt?: WorkCompletionReceipt;
   /** Provenance for complex work dispatched from a durable PlanContract step. */
   planId?: string;
@@ -450,11 +460,7 @@ export interface WorkContract {
   readOnlyReviewEvidence?: ReadOnlyReviewEvidence;
   /** Explicit Controller-reviewed acceptance bindings. Mechanical evidence attribution alone never writes this field. */
   semanticAcceptanceEvidence?: WorkSemanticAcceptanceEvidence[];
-  /** Explicit policy fence. This is not semantic completeness evidence. */
-  allowedPaths: string[];
-  forbiddenPaths: string[];
   checks: string[];
-  driver: WorkContractDriverPolicy;
   worktreePolicy: WorktreePolicy;
   evidencePolicy: EvidencePolicy;
   approvalPolicy: ApprovalPolicy;
@@ -505,7 +511,7 @@ export function semanticScopeRefForWork(
   return { schemaVersion: 1, kind: 'work', id: work.workId.trim() };
 }
 
-/** Resolve replaceable execution placement from explicit V2 placement or compatibility fields. */
+/** Resolve replaceable execution placement from explicit placement or stored repository relationships. */
 export function executionPlacementForWork(
   work: Pick<WorkContract, 'executionPlacement' | 'repoId' | 'checkoutId'>,
 ): ExecutionPlacement {
@@ -518,11 +524,11 @@ export function executionPlacementForWork(
 }
 
 export interface WorkContractStore {
-  schemaVersion: 1 | 2 | 3;
+  schemaVersion: 1 | 2 | 3 | 4;
   updatedAt: string;
   contracts: WorkContract[];
 }
 
-export function isTerminalWorkContractStatus(status: WorkContractStatus): boolean {
-  return TERMINAL_WORK_CONTRACT_STATUSES.includes(status);
+export function isTerminalSemanticWorkState(state: SemanticWorkState): boolean {
+  return TERMINAL_SEMANTIC_WORK_STATES.includes(state);
 }