@moretea-labs/forge 1.5.1 → 1.6.0

package/src/runtime/control-plane/facade/requirement-board.ts

@@ -28,7 +28,9 @@ export interface RequirementBoardItem {
   maintenanceSummary?: string;
   blocker?: string;
   requiredUserDecision?: string;
+  /** Compatibility projection for older UI clients; derived from activePlanIds. */
   activePlanId?: string;
+  activePlanIds: string[];
   latestDelivery?: {
     workId: string;
     receiptId: string;
@@ -55,10 +57,14 @@ function explicitUserDecision(requirement: Requirement): string | undefined {
   return decision || undefined;
 }
 
-function projectedRequirementState(requirement: Requirement): RequirementState {
+function activePlansForRequirement(requirementId: string, plans: readonly PlanContract[]): PlanContract[] {
+  return plans.filter((plan) => plan.requirementId === requirementId);
+}
+
+function projectedRequirementState(requirement: Requirement, activePlans: readonly PlanContract[]): RequirementState {
   if (requirement.state !== 'waiting_for_user') return requirement.state;
   if (explicitUserDecision(requirement)) return 'waiting_for_user';
-  return requirement.activePlanId ? 'active' : 'planned';
+  return activePlans.length > 0 ? 'active' : 'planned';
 }
 
 function loadScopedWork(options: RequirementBoardOptions): WorkContract[] {
@@ -92,8 +98,10 @@ function latestDelivery(requirementId: string, work: readonly WorkContract[]): R
   };
 }
 
-function projectRequirement(requirement: Requirement, work: readonly WorkContract[]): RequirementBoardItem {
-  const state = projectedRequirementState(requirement);
+function projectRequirement(requirement: Requirement, work: readonly WorkContract[], plans: readonly PlanContract[] = []): RequirementBoardItem {
+  const activePlans = activePlansForRequirement(requirement.requirementId, plans);
+  const activePlanIds = activePlans.map((plan) => plan.planId);
+  const state = projectedRequirementState(requirement, activePlans);
   const requiredUserDecision = explicitUserDecision(requirement);
   const maintenanceSummary = requirement.needsAttention
     ? boundedText(requirement.attentionSummary, 1_000) || 'This Requirement has a maintenance finding.'
@@ -108,7 +116,8 @@ function projectRequirement(requirement: Requirement, work: readonly WorkContrac
     maintenanceSummary,
     blocker: requirement.needsAttention && state !== 'waiting_for_user' ? maintenanceSummary : undefined,
     requiredUserDecision,
-    activePlanId: requirement.activePlanId,
+    activePlanId: activePlanIds[0],
+    activePlanIds,
     latestDelivery: latestDelivery(requirement.requirementId, work),
     updatedAt: requirement.updatedAt,
     detailPointer: {
@@ -132,7 +141,10 @@ function requirementCounts(requirements: readonly RequirementBoardItem[]): Recor
 
 export function buildRequirementBoard(options: RequirementBoardOptions): Record<string, unknown> {
   const work = loadScopedWork(options);
-  const allRequirements = loadRequirements(options).map((requirement) => projectRequirement(requirement, work));
+  const activePlans = options.repoId?.trim()
+    ? listPlanContracts({ controllerHome: options.controllerHome, repoId: options.repoId, status: 'active', limit: 100 })
+    : [];
+  const allRequirements = loadRequirements(options).map((requirement) => projectRequirement(requirement, work, activePlans));
   const requirements = allRequirements.slice(0, DEFAULT_REQUIREMENT_LIMIT);
   const counts = requirementCounts(allRequirements);
   return {
@@ -229,9 +241,13 @@ export function buildExecutionDiagnostics(
     : [];
   const scopedPlans = options.requirementId
     ? allPlans.filter((plan) => plan.requirementId === options.requirementId
-      || selectedRequirements.some((requirement) => requirement.activePlanId === plan.planId))
+      // Legacy migration compatibility only: current Plans own the forward
+      // requirementId relation, so the persisted Requirement pointer is not an
+      // execution/lifecycle authority.
+      || (!plan.requirementId && selectedRequirements.some((requirement) => requirement.activePlanId === plan.planId)))
     : allPlans;
-  const requirements = selectedRequirements.map((requirement) => projectRequirement(requirement, allWork));
+  const activePlans = allPlans.filter((plan) => !['finalized', 'superseded', 'cancelled', 'invalidated_by_drift'].includes(plan.status));
+  const requirements = selectedRequirements.map((requirement) => projectRequirement(requirement, allWork, activePlans));
   const works = scopedWork.slice(0, limit).map(summarizeDiagnosticWork);
   const plans = scopedPlans.slice(0, limit).map((plan) => summarizeDiagnosticPlan(plan, options.detailLevel));
   const maintenanceFindings = requirements

package/src/runtime/control-plane/facade/types.ts

@@ -156,18 +156,35 @@ export interface LocalEffectCompletionReceipt {
   recordedAt: string;
 }
 
+/** Durable completion authority for one typed remote plugin effect. */
+export interface RemoteEffectCompletionReceipt {
+  schemaVersion: 1;
+  /** Reuse the authoritative PLG-* receipt id rather than manufacturing parallel evidence. */
+  receiptId: string;
+  source: 'remote_effect';
+  workId: string;
+  pluginId: string;
+  actionId: string;
+  requestId: string;
+  semanticKey: string;
+  resultDigest: string;
+  recordedAt: string;
+}
+
 /**
  * Completion authority for a standalone Direct Edit that is not bound to the
- * retired Issue/Task completion model. The receipt proves that one finalized
- * edit session is present at an exact reachable Git revision with clean owned
- * paths, while keeping the WorkContract as the canonical lifecycle authority.
+ * retired Issue/Task completion model. Normal completion proves one finalized
+ * edit session at an exact reachable Git revision. Historical completion may
+ * instead reference one explicit reviewed reconciliation after exact revision,
+ * path-scope, verification, reachability, and cleanup proof checks.
  */
 export interface DirectEditWorkCompletionReceipt {
   schemaVersion: 1;
   receiptId: string;
   source: 'direct_edit_work';
   workId: string;
-  editSessionId: string;
+  editSessionId?: string;
+  reconciliationId?: string;
   targetBranch: string;
   targetRevision: string;
   sourceRevision?: string;
@@ -179,12 +196,18 @@ export interface DirectEditWorkCompletionReceipt {
   recordedAt: string;
 }
 
-export type WorkCompletionReceipt = RepositoryCompletionReceipt | DirectEditWorkCompletionReceipt | LocalEffectCompletionReceipt;
+export type WorkCompletionReceipt = RepositoryCompletionReceipt | DirectEditWorkCompletionReceipt | LocalEffectCompletionReceipt | RemoteEffectCompletionReceipt;
 
 export function isRepositoryCompletionReceipt(
   receipt: WorkCompletionReceipt,
 ): receipt is RepositoryCompletionReceipt {
-  return receipt.source !== 'local_effect' && receipt.source !== 'direct_edit_work';
+  return receipt.source !== 'local_effect' && receipt.source !== 'remote_effect' && receipt.source !== 'direct_edit_work';
+}
+
+export function isRemoteEffectCompletionReceipt(
+  receipt: WorkCompletionReceipt,
+): receipt is RemoteEffectCompletionReceipt {
+  return receipt.source === 'remote_effect';
 }
 
 export function isDirectEditWorkCompletionReceipt(
@@ -431,6 +454,10 @@ export interface WorkContract {
   phaseEvidence: WorkPhaseEvidenceMap;
   /** Explicit v2 execution semantics. `status` is retained for compatibility. */
   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;
   dispatchState: DispatchState;
   evidenceState: EvidenceState;
   completionOutcome?: CompletionOutcome;

package/src/runtime/control-plane/facade/work-contract-store.ts

@@ -32,6 +32,7 @@ import {
   type WorkPhaseEvidenceState,
   type WorkContractStore,
   isDirectEditWorkCompletionReceipt,
+  isRemoteEffectCompletionReceipt,
   isRepositoryCompletionReceipt,
   isTerminalWorkContractStatus,
 } from './types';
@@ -195,7 +196,7 @@ function legacyPhaseEvidence(
       state,
       source: completedByReceipt ? 'recorded' : source,
       summary: completedByReceipt
-        ? `Phase ${phase} accepted by Work completion receipt ${contract.completionReceipt!.receiptId}.`
+        ? `Phase ${phase} satisfied by Work completion receipt ${contract.completionReceipt!.receiptId}.`
         : index < currentIndex
           ? `Legacy Work advanced beyond ${phase}.`
           : `Legacy Work phase ${phase} is ${state}.`,
@@ -285,13 +286,20 @@ function validateWorkSemantics(contract: WorkContract): WorkContract {
       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)) {
-      if (!receipt.editSessionId.trim()) throw new Error('WORK_COMPLETION_RECEIPT_DIRECT_EDIT_SESSION_REQUIRED');
+      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 (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');
+      if (!receipt.pluginId.trim() || !receipt.actionId.trim() || !receipt.requestId.trim() || !receipt.semanticKey.trim() || !receipt.resultDigest.trim()) {
+        throw new Error('WORK_COMPLETION_RECEIPT_REMOTE_EFFECT_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');
@@ -335,6 +343,9 @@ function validateWorkSemantics(contract: WorkContract): WorkContract {
   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');
   }
@@ -372,6 +383,12 @@ function validateWorkSemanticTransition(current: WorkContract, next: WorkContrac
   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');
+  }
   return next;
 }
 
@@ -544,6 +561,8 @@ export function createWorkContract(options: WorkContractStoreOptions, input: Cre
       constraints: input.constraints ?? { requireHandoffOnAmbiguity: true },
       risk: input.risk ?? 'medium',
       workKind: input.workKind ?? 'repository_change',
+      lifecycleRole: input.lifecycleRole ?? 'primary',
+      parentWorkId: input.parentWorkId?.trim() || undefined,
       dispatchState: input.dispatchState ?? inferredDispatchState(input.status ?? 'open'),
       evidenceState: input.evidenceState ?? inferredEvidenceState(input.status ?? 'open'),
       completionOutcome: input.completionOutcome,
@@ -631,6 +650,7 @@ function workRequestIndexPath(controllerHome: string, requestId: string): string
 export interface AcceptSubmittedWorkInput {
   requestId: string;
   repoId: string;
+  parentWorkId?: string;
   semanticKey: string;
   operation: SubmittedWorkOperation;
   objective?: string;
@@ -690,6 +710,13 @@ export function acceptSubmittedWorkContract(
   if (!input.operation?.name?.trim()) {
     throw new Error('INVALID_ARGUMENT: work_submit is missing required argument(s): operation');
   }
+  const parentWorkId = input.parentWorkId?.trim() || undefined;
+  if (parentWorkId) {
+    const parent = getWorkContract({ controllerHome: home, repoId: input.repoId, now: options.now }, parentWorkId);
+    if (!parent) throw new Error(`PARENT_WORK_NOT_FOUND: ${parentWorkId}`);
+    if (isTerminalWorkContractStatus(parent.status)) throw new Error(`PARENT_WORK_TERMINAL: ${parentWorkId}:${parent.status}`);
+    if ((parent.lifecycleRole ?? 'primary') !== 'primary') throw new Error(`PARENT_WORK_NOT_PRIMARY: ${parentWorkId}`);
+  }
 
   const requestLockId = createHash('sha256').update(normalizedRequestId).digest('hex').slice(0, 24);
   return withControllerLock(home, { scope: 'global', resource: `work-request-${requestLockId}` }, `accept-work:${normalizedRequestId}`, () => {
@@ -715,6 +742,8 @@ export function acceptSubmittedWorkContract(
       principalId: input.principalId,
       controllerInstanceId: input.controllerInstanceId,
       mode: input.mode ?? 'direct_control',
+      lifecycleRole: 'execution_child',
+      parentWorkId,
       objective: (input.objective ?? `Accepted operation ${input.operation.name}`).slice(0, 2_000),
       acceptanceCriteria: input.acceptanceCriteria ?? [],
       workKind: input.workKind,