@moretea-labs/forge 1.5.0 → 1.6.0

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

@@ -9,6 +9,7 @@ import {
   appendWorkHandoffRef,
   createWorkContract,
   getWorkContract,
+  listWorkContracts,
   summarizeWorkContract,
   transitionWorkContractPhase,
   updateWorkContract,
@@ -17,6 +18,7 @@ import {
 import {
   claimPlanStepForWork,
   completePlanStepForWork,
+  getPlanContract,
   type PlanContractStoreOptions,
 } from './plan-contract-store';
 import {
@@ -57,8 +59,11 @@ export interface GoalWorkloopContext {
   controllerInstanceId?: string;
   workspaceFingerprint?: string;
   now?: () => string;
+  materializeIsolatedWorkspace?: (input: { workId: string; title: string; baseRef?: string }) => { checkoutId: string; root: string; baseRevision?: string | null; managed: true };
 }
 
+export type WorkAdmissionRelation = 'continue' | 'extend' | 'parallel' | 'new_goal';
+
 export interface GoalWorkloopStartInput {
   objective: string;
   acceptanceCriteria?: string[];
@@ -68,6 +73,9 @@ export interface GoalWorkloopStartInput {
   constraints?: WorkContract['constraints'];
   modeInput: ExecutionModeSelectionInput;
   requestedBy?: WorkContract['requestedBy'];
+  relatedWorkId?: string;
+  workRelation?: WorkAdmissionRelation;
+  requirementId?: string;
   taskId?: string;
   issueId?: string;
   approvalConfirmed?: boolean;
@@ -280,11 +288,33 @@ export function routeWorkStart(
     selectedMode = selectExecutionMode({ ...effectiveModeInput, approvalConfirmed: true });
     policy = evaluateAccessPolicy(selectedMode);
   }
-  const mode = applyForcedMode(selectedMode);
+  let mode = applyForcedMode(selectedMode);
+
+  // Route Policy is the sole execution-depth authority. Existing Work is
+  // ownership context, not a reason to upgrade an otherwise Direct operation
+  // into Durable Work. Explicit Work/Plan ownership is resolved only after a
+  // durable route has already been selected; checkout writer conflicts affect
+  // placement, not semantic task identity.
 
   if (mode.mode === 'direct_control') {
     const available = ctx.availableChecks ?? [];
     const normalized = normalizeCheckIds(input.checks ?? [], available);
+    // Explicit ownership may annotate a Direct operation, but it never changes
+    // the RouteDecision. The actual repository mutation can pass this Work id
+    // to repository_safe_patch_apply / repository_command_execute for evidence
+    // attribution while staying on the Direct/Process path.
+    const directOwnershipCandidates = input.relatedWorkId || (input.planId && input.planStepId)
+      ? listWorkContracts({ ...ctx.workStore, status: 'active', limit: 100 })
+          .filter((candidate) => (candidate.lifecycleRole ?? 'primary') === 'primary')
+      : [];
+    const directPlan = input.planId && ctx.planStore ? getPlanContract(ctx.planStore, input.planId) : undefined;
+    const directPlanStep = directPlan && input.planStepId ? directPlan.steps.find((step) => step.id === input.planStepId) : undefined;
+    const directOwner = (input.relatedWorkId
+      ? directOwnershipCandidates.find((candidate) => candidate.workId === input.relatedWorkId)
+      : undefined)
+      ?? (directPlanStep?.workId
+        ? directOwnershipCandidates.find((candidate) => candidate.workId === directPlanStep.workId)
+        : undefined);
     const suggested = validateSuggestedNextActions([
       {
         label: 'Apply bounded direct edit',
@@ -315,6 +345,13 @@ export function routeWorkStart(
         directControlPreserved: true,
         objective: input.objective.slice(0, 1_000),
         normalizedChecks: normalized,
+        ...(directOwner ? {
+          ownership: {
+            workId: directOwner.workId,
+            relation: input.workRelation ?? 'continue',
+            executionDepthPreserved: true,
+          },
+        } : {}),
       },
       warnings: [...policy.warnings, ...normalized.warnings],
       suggestedNextActions: suggested,
@@ -437,12 +474,189 @@ export function startGoalWorkloop(
 ): FacadeResult {
   const at = nowIso(ctx);
   const available = ctx.availableChecks ?? [];
-  const normalized = normalizeCheckIds(input.checks ?? [], available);
   const workspaceMode = input.constraints?.workspaceMode ?? 'auto';
+  const activeWorks = listWorkContracts({ ...ctx.workStore, status: 'active', limit: 100 })
+    .filter((candidate) => (candidate.lifecycleRole ?? 'primary') === 'primary');
+  const workspaceOwner = ctx.checkoutId
+    ? activeWorks.find((candidate) => candidate.checkoutId === ctx.checkoutId
+      && candidate.worktreePolicy.required !== true
+      && !candidate.worktreeRef)
+    : undefined;
+  const explicitRelatedWork = input.relatedWorkId
+    ? activeWorks.find((candidate) => candidate.workId === input.relatedWorkId)
+    : undefined;
+  const plan = input.planId && ctx.planStore ? getPlanContract(ctx.planStore, input.planId) : undefined;
+  const planStep = plan && input.planStepId ? plan.steps.find((step) => step.id === input.planStepId) : undefined;
+  const sameStringSet = (provided: string[] | undefined, frozen: string[]): boolean => {
+    if (provided === undefined) return true;
+    const actual = [...new Set(provided)].sort();
+    const expected = [...new Set(frozen)].sort();
+    return actual.length === expected.length && actual.every((value, index) => value === expected[index]);
+  };
+  if (planStep) {
+    const mismatches = [
+      !sameStringSet(input.acceptanceCriteria, planStep.acceptanceCriteria) && 'acceptance_criteria',
+      !sameStringSet(input.allowedPaths, planStep.allowedPaths) && 'allowed_paths',
+      !sameStringSet(input.forbiddenPaths, planStep.forbiddenPaths) && 'forbidden_paths',
+      !sameStringSet(input.checks, planStep.checks) && 'check_ids',
+    ].filter((value): value is string => Boolean(value));
+    if (mismatches.length > 0) {
+      return buildFacadeResult({
+        status: 'blocked',
+        summary: `PLAN_STEP_WORK_CONTRACT_MISMATCH: ${input.planId}/${input.planStepId} conflicts with frozen Plan step field(s): ${mismatches.join(', ')}. Replan instead of widening or narrowing Work admission.`,
+        data: { executionStarted: false, workContractCreated: false, planId: input.planId, planStepId: input.planStepId, mismatches },
+      });
+    }
+  }
+  const effectiveAcceptanceCriteria = planStep?.acceptanceCriteria ?? input.acceptanceCriteria ?? [];
+  const effectiveAllowedPaths = planStep?.allowedPaths ?? input.allowedPaths ?? [];
+  const effectiveForbiddenPaths = planStep?.forbiddenPaths ?? input.forbiddenPaths ?? [];
+  const effectiveChecks = planStep?.checks ?? input.checks ?? [];
+  const normalized = normalizeCheckIds(effectiveChecks, available);
+  const planStepWork = planStep?.workId ? activeWorks.find((candidate) => candidate.workId === planStep.workId) : undefined;
+  const requirementWorks = input.requirementId
+    ? activeWorks.filter((candidate) => candidate.requirementId === input.requirementId)
+    : [];
+  const deterministicTarget = explicitRelatedWork ?? planStepWork ?? (requirementWorks.length === 1 ? requirementWorks[0] : undefined);
+  const requestedRelation = input.workRelation ?? (input.modeInput.requiresParallelism === true ? 'parallel' : undefined);
+  // Only strong semantic bindings participate in ownership resolution. An
+  // unrelated active Work or a checkout writer is a placement fact, not a
+  // semantic candidate for continue/extend/parallel/new_goal.
+  const candidateWorks = [...new Map(
+    [explicitRelatedWork, planStepWork, ...requirementWorks]
+      .filter((candidate): candidate is WorkContract => Boolean(candidate))
+      .map((candidate) => [candidate.workId, candidate]),
+  ).values()].slice(0, 8);
+
+  const resolutionRequired = (reason: string, target = deterministicTarget): FacadeResult => buildFacadeResult({
+    status: 'ok',
+    summary: reason,
+    data: {
+      executionStarted: false,
+      workContractCreated: false,
+      admissionDecision: 'resolution_required',
+      resolutionRequired: true,
+      requestedBy: input.requestedBy ?? 'chatgpt',
+      ...(target ? { recommendedWork: summarizeWorkContract(target) } : {}),
+      candidates: candidateWorks.map(summarizeWorkContract),
+      allowedRelations: ['continue', 'extend', 'parallel', 'new_goal'],
+    },
+    evidenceRefs: target?.evidenceRefs ?? [],
+    suggestedNextActions: target
+      ? [{
+          label: 'Continue existing Work',
+          tool: 'rh_work',
+          operation: 'continue',
+          payload: { work_id: target.workId },
+          risk: 'readonly',
+          confidence: planStepWork || explicitRelatedWork ? 'high' : 'medium',
+          reason: 'Resolve intent before execution; do not create a second Work until the relationship is explicit.',
+        }]
+      : [],
+    rawAvailable: false,
+  });
+
+  if ((input.requestedBy ?? 'chatgpt') === 'scheduler') {
+    return resolutionRequired(
+      deterministicTarget
+        ? `SCHEDULER_CONTINUATION_REQUIRED: scheduler-triggered execution must continue its bound Work ${deterministicTarget.workId}; it must not create a new durable Work.`
+        : 'SCHEDULER_WORK_BINDING_REQUIRED: scheduler-triggered execution must bind and wake an existing durable Work; it must not invent a new Work from a prompt.',
+    );
+  }
+
+  if (planStepWork && !requestedRelation) {
+    return buildFacadeResult({
+      status: 'ok',
+      summary: `PLAN_STEP_REUSES_ACTIVE_WORK: ${input.planId}/${input.planStepId} already executes as ${planStepWork.workId}; reuse that Work instead of creating another.`,
+      data: {
+        executionStarted: false,
+        workContractCreated: false,
+        admissionDecision: 'reuse_existing',
+        resolutionRequired: false,
+        work: summarizeWorkContract(planStepWork),
+      },
+      evidenceRefs: planStepWork.evidenceRefs,
+      suggestedNextActions: [{ label: 'Continue existing Work', tool: 'rh_work', operation: 'continue', payload: { work_id: planStepWork.workId }, risk: 'readonly', confidence: 'high' }],
+      rawAvailable: false,
+    });
+  }
+
+  if (requestedRelation === 'continue' || requestedRelation === 'extend') {
+    if (!deterministicTarget) {
+      return resolutionRequired(`${requestedRelation.toUpperCase()}_TARGET_REQUIRED: select related_work_id or bind the request to an active Plan/Requirement before execution.`);
+    }
+    if (requestedRelation === 'extend' && deterministicTarget.planId) {
+      return resolutionRequired(
+        `PLAN_EXTENSION_REQUIRES_REPLAN: Work ${deterministicTarget.workId} is governed by Plan ${deterministicTarget.planId}; extend the authoritative Plan/Requirement before continuing rather than silently widening Work scope.`,
+        deterministicTarget,
+      );
+    }
+    const selected = requestedRelation === 'extend'
+      ? updateWorkContract(ctx.workStore, deterministicTarget.workId, {
+          acceptanceCriteria: [...new Set([...deterministicTarget.acceptanceCriteria, ...(input.acceptanceCriteria ?? [])])].slice(0, 30),
+          allowedPaths: [...new Set([...deterministicTarget.allowedPaths, ...(input.allowedPaths ?? [])])].slice(0, 50),
+          forbiddenPaths: [...new Set([...deterministicTarget.forbiddenPaths, ...(input.forbiddenPaths ?? [])])].slice(0, 50),
+          checks: [...new Set([...deterministicTarget.checks, ...normalized.validCheckIds])].slice(0, 30),
+          scopeSummary: `Extended serially: ${input.objective}`.slice(0, 500),
+          continuationPrompt: `Continue work ${ctx.repoId}: ${deterministicTarget.objective.slice(0, 160)}. Additional requested scope: ${input.objective.slice(0, 500)}`,
+        })
+      : deterministicTarget;
+    return buildFacadeResult({
+      status: 'ok',
+      summary: `${requestedRelation === 'extend' ? 'Existing Work extended' : 'Existing Work selected'}: ${selected.workId}. No new WorkContract was created.`,
+      data: {
+        executionStarted: false,
+        workContractCreated: false,
+        admissionDecision: requestedRelation === 'extend' ? 'extend_existing' : 'reuse_existing',
+        resolutionRequired: false,
+        work: summarizeWorkContract(selected),
+      },
+      evidenceRefs: selected.evidenceRefs,
+      suggestedNextActions: [{ label: 'Continue existing Work', tool: 'rh_work', operation: 'continue', payload: { work_id: selected.workId }, risk: 'readonly', confidence: 'high' }],
+      rawAvailable: false,
+    });
+  }
+
+  if (!requestedRelation && candidateWorks.length > 0) {
+    return resolutionRequired(
+      `WORK_ADMISSION_RESOLUTION_REQUIRED: ${candidateWorks.length} active Work candidate(s) exist. Classify this request as continue, extend, parallel, or new_goal before any durable Work is created.`,
+    );
+  }
+
+  const placementConflict = Boolean(workspaceOwner);
   const needsWorktree = executionMode === 'goal_workloop' && (input.constraints?.requireWorktree
     ?? (workspaceMode === 'isolated'
+      || placementConflict
       || (workspaceMode === 'auto' && routeDecision.requiresIsolation === true)));
+  if (!needsWorktree && workspaceOwner) {
+    return buildFacadeResult({
+      status: 'blocked',
+      summary: `WORKSPACE_OWNERSHIP_INVARIANT: unresolved admission reached checkout ${ctx.checkoutId} while active Work ${workspaceOwner.workId} owns it. This is an internal routing invariant, not a normal fallback path.`,
+      data: {
+        executionStarted: false,
+        workContractCreated: false,
+        conflictType: 'workspace_single_writer_invariant',
+        existingWork: summarizeWorkContract(workspaceOwner),
+      },
+      evidenceRefs: workspaceOwner.evidenceRefs,
+      rawAvailable: false,
+    });
+  }
   const generatedWorkId = workIdFor(input.objective);
+  let isolatedWorkspace: ReturnType<NonNullable<GoalWorkloopContext['materializeIsolatedWorkspace']>> | undefined;
+  if (needsWorktree) {
+    if (!ctx.materializeIsolatedWorkspace) {
+      return buildFacadeResult({ status: 'blocked', summary: 'ISOLATED_WORKSPACE_MATERIALIZER_REQUIRED: isolated Work cannot enter running state without a concrete managed checkout.', data: { executionStarted: false, workContractCreated: false, worktreeRequired: true } });
+    }
+    try {
+      isolatedWorkspace = ctx.materializeIsolatedWorkspace({ workId: generatedWorkId, title: input.objective, baseRef: ctx.sourceRevision });
+      if (!isolatedWorkspace.checkoutId || !isolatedWorkspace.root || isolatedWorkspace.checkoutId === ctx.checkoutId) {
+        throw new Error('ISOLATED_WORKSPACE_NOT_DISTINCT');
+      }
+    } catch (error) {
+      return buildFacadeResult({ status: 'blocked', summary: error instanceof Error ? `ISOLATED_WORKSPACE_MATERIALIZATION_FAILED: ${error.message}` : 'ISOLATED_WORKSPACE_MATERIALIZATION_FAILED', data: { executionStarted: false, workContractCreated: false, worktreeRequired: true } });
+    }
+  }
   if (input.planId || input.planStepId) {
     if (!input.planId || !input.planStepId || !ctx.planStore || !ctx.sourceRevision) {
       return buildFacadeResult({ status: 'blocked', summary: 'PLAN_CONTEXT_REQUIRED: plan_id, plan_step_id and a current source revision are required.', data: { executionStarted: false } });
@@ -473,28 +687,32 @@ export function startGoalWorkloop(
   const work = createWorkContract(ctx.workStore, {
     workId: generatedWorkId,
     repoId: ctx.repoId,
-    checkoutId: ctx.checkoutId,
+    checkoutId: isolatedWorkspace?.checkoutId ?? ctx.checkoutId,
     principalId: ctx.principalId,
     controllerInstanceId: ctx.controllerInstanceId,
-    baseRevision: ctx.sourceRevision,
-    workspaceFingerprint: ctx.workspaceFingerprint,
+    baseRevision: isolatedWorkspace?.baseRevision ?? ctx.sourceRevision,
+    workspaceFingerprint: isolatedWorkspace ? undefined : ctx.workspaceFingerprint,
     routeDecisionFingerprint: routeDecision.inputFingerprint,
     routeDecision,
     mode: executionMode,
     objective: input.objective,
-    acceptanceCriteria: input.acceptanceCriteria ?? [],
+    acceptanceCriteria: effectiveAcceptanceCriteria,
     constraints: input.constraints ?? { requireHandoffOnAmbiguity: true },
     risk: workRiskFor(input),
+    workKind: input.modeInput.requiresExternalEffect === true && input.modeInput.remoteWrite === true
+      ? 'remote_effect'
+      : undefined,
     status: 'running',
     phase: 'implementation',
     issueId: input.issueId,
     taskId: input.taskId,
+    requirementId: input.requirementId,
     planId: input.planId,
     planStepId: input.planStepId,
     planSourceRevision: input.planId ? ctx.sourceRevision : undefined,
     scopeSummary: input.modeInput.scopeClear ? 'scope declared at start' : 'scope incomplete',
-    allowedPaths: input.allowedPaths ?? [],
-    forbiddenPaths: input.forbiddenPaths ?? [],
+    allowedPaths: effectiveAllowedPaths,
+    forbiddenPaths: effectiveForbiddenPaths,
     checks: normalized.validCheckIds,
     driver: {
       preferred: executionMode === 'direct_control'
@@ -509,6 +727,7 @@ export function startGoalWorkloop(
         ? 'Isolation was explicitly requested or required for parallel execution.'
         : 'Current workspace is the stability-first default; isolation remains opt-in.',
     },
+    worktreeRef: isolatedWorkspace?.root,
     evidencePolicy: {
       defaultDetailLevel: 'summary',
       allowRawOptIn: true,
@@ -1115,6 +1334,9 @@ export function stopGoalWorkloop(ctx: GoalWorkloopContext, input: GoalWorkloopSt
     // cleanup handler verifies ownership, cleanliness and successful removal.
     worktreeRef: work.worktreeRef,
   });
+  const plan = updated.planId && updated.planStepId && ctx.planStore
+    ? completePlanStepForWork(ctx.planStore, { planId: updated.planId, stepId: updated.planStepId, work: updated })
+    : undefined;
 
   return buildFacadeResult({
     status: 'ok',
@@ -1126,6 +1348,7 @@ export function stopGoalWorkloop(ctx: GoalWorkloopContext, input: GoalWorkloopSt
       worktreeDeleted: false,
       cleanupPending: destructiveCleanup && Boolean(work.worktreeRef),
       destructiveCleanupAuthorized: destructiveCleanup,
+      ...(plan ? { plan } : {}),
     },
     evidenceRefs: work.evidenceRefs.slice(0, 5),
     suggestedNextActions: [

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

@@ -376,28 +376,48 @@ export function completePlanStepForWork(
     if (stepIndex < 0) throw new Error(`PLAN_STEP_NOT_FOUND: ${input.stepId}`);
     const step = current.steps[stepIndex];
     if (step.workId !== input.work.workId) throw new Error(`PLAN_STEP_WORK_MISMATCH: ${input.stepId}`);
-    const completed = input.work.status === 'completed'
+    if (step.status === 'completed') return current;
+    const delivered = input.work.status === 'completed'
       && input.work.phase === 'cleanup'
       && input.work.evidenceState === 'valid'
       && Boolean(input.work.completionOutcome && input.work.completionOutcome !== 'superseded')
       && Boolean(input.work.completionReceipt);
     const failed = input.work.status === 'failed' || input.work.status === 'cancelled';
-    if (!completed && !failed) throw new Error(`PLAN_STEP_WORK_NOT_TERMINAL: ${input.work.workId}`);
+    if (!delivered && !failed) throw new Error(`PLAN_STEP_WORK_NOT_TERMINAL: ${input.work.workId}`);
     const at = nowIso(options);
     const steps = [...current.steps];
     steps[stepIndex] = {
       ...step,
-      status: completed ? 'completed' : 'validating',
-      evidenceRefs: input.work.evidenceRefs.length > 0
-        ? input.work.evidenceRefs.slice(0, 20)
-        : step.evidenceRefs,
+      // Work completion proves machine delivery only. The Plan step remains in
+      // semantic validation until an explicit Controller acceptance records it.
+      // Failed/cancelled Work returns the slice to ready for replanning.
+      status: delivered ? 'validating' : 'ready',
+      evidenceRefs: input.work.evidenceRefs.length > 0 ? input.work.evidenceRefs.slice(0, 20) : step.evidenceRefs,
     };
-    const allCompleted = steps.every((candidate) => candidate.status === 'completed');
-    return {
-      ...current,
-      status: completed ? (allCompleted ? 'ready_to_finalize' : 'executing') : 'replanning',
-      steps,
-      updatedAt: at,
+    return { ...current, status: delivered ? 'verifying' : 'replanning', steps, updatedAt: at };
+  });
+}
+
+export function acceptPlanStepEvidence(
+  options: PlanContractStoreOptions,
+  input: { planId: string; stepId: string; reviewer: string; rationale: string },
+): PlanContract {
+  const reviewer = input.reviewer.trim();
+  const rationale = input.rationale.trim();
+  if (!reviewer || !rationale) throw new Error('PLAN_STEP_SEMANTIC_ACCEPTANCE_METADATA_REQUIRED');
+  return updatePlanContract(options, input.planId, (current) => {
+    const stepIndex = current.steps.findIndex((step) => step.id === sanitizeFileComponent(input.stepId));
+    if (stepIndex < 0) throw new Error(`PLAN_STEP_NOT_FOUND: ${input.stepId}`);
+    const step = current.steps[stepIndex];
+    if (step.status === 'completed') return current;
+    if (step.status !== 'validating') throw new Error(`PLAN_STEP_NOT_READY_FOR_SEMANTIC_ACCEPTANCE: ${step.id} is ${step.status}`);
+    const steps = [...current.steps];
+    steps[stepIndex] = {
+      ...step,
+      status: 'completed',
+      evidenceRefs: [{ title: 'semantic acceptance', summary: `${reviewer}: ${rationale}`, detailLevel: 'summary' as const }, ...step.evidenceRefs].slice(0, 20),
     };
+    const allCompleted = steps.every((candidate) => candidate.status === 'completed');
+    return { ...current, status: allCompleted ? 'finalized' : 'executing', steps, updatedAt: nowIso(options) };
   });
 }

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,