@moretea-labs/forge 1.7.1 → 1.8.0

package/src/runtime/control-plane/facade/repository-work-admission.ts

@@ -1,8 +1,18 @@
 import type { AccessMode } from '../governance/access-policy';
 import type { RouteDecision } from '../routing/route-policy';
-import { createWorkContract, getWorkContract, updateWorkContract, type WorkContractStoreOptions } from './work-contract-store';
+import { createWorkContract, executionPlacementForWork, getWorkContract, updateWorkContract, type WorkContractStoreOptions } from '../../../../packages/kernel/work/api/index';
+import { executionPlacement, readForgeInstanceIdentity } from '../../../../packages/kernel/identity/api/index';
 import type { WorkContract } from './types';
 
+function repositoryExecutionPlacement(store: WorkContractStoreOptions, repoId: string, checkoutId?: string) {
+  const forgeInstanceId = store.controllerHome ? readForgeInstanceIdentity(store.controllerHome)?.instanceId : undefined;
+  return executionPlacement({
+    ...(forgeInstanceId ? { forgeInstanceId } : {}),
+    repositoryId: repoId,
+    ...(checkoutId?.trim() ? { checkoutId: checkoutId.trim() } : {}),
+  });
+}
+
 export interface PreparedRepositoryWorkAdmissionInput {
   workId: string;
   repoId: string;
@@ -28,6 +38,7 @@ export function admitPreparedRepositoryWorkContract(
   return createWorkContract(store, {
     workId: input.workId,
     repoId: input.repoId,
+    executionPlacement: repositoryExecutionPlacement(store, input.repoId),
     mode: input.isolated ? 'goal_workloop' : 'direct_control',
     objective: input.objective,
     acceptanceCriteria: input.acceptanceCriteria,
@@ -85,6 +96,7 @@ export function admitDirectEditWorkContract(
     workId: input.workId,
     repoId: input.repoId,
     checkoutId: input.checkoutId,
+    executionPlacement: repositoryExecutionPlacement(store, input.repoId, input.checkoutId),
     principalId: input.principalId,
     controllerInstanceId: input.controllerInstanceId,
     baseRevision: input.baseRevision,
@@ -138,8 +150,14 @@ export function materializeRepositoryWorkPlacement(
   if (!workspace.managed || !workspace.checkoutId || !workspace.root) {
     throw new Error('MANAGED_WORKSPACE_NOT_MATERIALIZED');
   }
+  const currentPlacement = executionPlacementForWork(contract);
   return updateWorkContract(store, workId, {
     checkoutId: workspace.checkoutId,
+    executionPlacement: executionPlacement({
+      ...(currentPlacement.forgeInstanceId ? { forgeInstanceId: currentPlacement.forgeInstanceId } : {}),
+      repositoryId: contract.repoId,
+      checkoutId: workspace.checkoutId,
+    }),
     baseRevision: workspace.baseRevision ?? contract.baseRevision,
     worktreeRef: workspace.root,
     driver: { ...contract.driver, preferred: 'isolated_worktree', allowDirectEdit: false },

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

@@ -1,10 +1,20 @@
 import {
   createRequirement,
   readRequirement,
+  updateRequirement,
   type CreateRequirementInput,
   type Requirement,
   type RequirementStoreOptions,
 } from '../persistence/requirement-store';
+import { readPlanContractStore } from './plan-contract-store';
+import { withPlanAdmissionLock } from './semantic-admission';
+import {
+  getControllerRoundRelay,
+  submitControllerRoundDisposition,
+  type ControllerRoundRelayRecord,
+  type SubmitControllerRoundDispositionInput,
+} from '../../../../packages/kernel/controller/api/index';
+import { getWorkContract } from '../../../../packages/kernel/work/api/index';
 
 export type RequirementAdmissionDecision = 'created' | 'reuse_existing' | 'existing_conflict';
 
@@ -81,3 +91,211 @@ export function admitRequirement(
     return existingDecision(raced, requested);
   }
 }
+
+
+export interface RequirementContinueResult {
+  requirement: Requirement;
+  resumed: boolean;
+}
+
+/**
+ * Canonical explicit semantic continue for a Requirement that is waiting on
+ * ChatGPT/user judgement. Persistence owns transition legality; this facade
+ * owns the semantic meaning so adapters and launchers never mutate Requirement
+ * state directly.
+ */
+export function continueRequirement(
+  options: RequirementStoreOptions,
+  requirementId: string,
+): RequirementContinueResult {
+  const normalizedId = String(requirementId ?? '').trim();
+  const current = readRequirement(options, normalizedId)?.value;
+  if (!current) throw new Error(`REQUIREMENT_NOT_FOUND: ${normalizedId}`);
+  if (current.state === 'active') return { requirement: current, resumed: false };
+  if (current.state === 'done' || current.state === 'cancelled') {
+    throw new Error(`REQUIREMENT_TERMINAL: ${current.requirementId}:${current.state}`);
+  }
+  if (current.state !== 'waiting_for_user') {
+    throw new Error(`REQUIREMENT_CONTINUE_NOT_WAITING: ${current.requirementId}:${current.state}`);
+  }
+
+  const requirement = updateRequirement(options, {
+    requirementId: current.requirementId,
+    action: 'requirement_semantic_continue',
+    mutate: (latest) => {
+      if (latest.state === 'active') return latest;
+      if (latest.state === 'done' || latest.state === 'cancelled') {
+        throw new Error(`REQUIREMENT_TERMINAL: ${latest.requirementId}:${latest.state}`);
+      }
+      if (latest.state !== 'waiting_for_user') {
+        throw new Error(`REQUIREMENT_CONTINUE_NOT_WAITING: ${latest.requirementId}:${latest.state}`);
+      }
+      return {
+        ...latest,
+        state: 'active',
+        needsAttention: false,
+        attentionSummary: undefined,
+      };
+    },
+  });
+  return { requirement, resumed: true };
+}
+
+export interface RequirementAcceptanceResult {
+  requirement: Requirement;
+  accepted: boolean;
+  finalizedPlanIds: string[];
+}
+
+export interface RequirementAcceptanceReadiness {
+  requirement: Requirement;
+  finalizedPlanIds: string[];
+}
+
+function requirementAcceptanceContext(
+  options: RequirementStoreOptions & { repoId: string },
+  input: { requirementId: string; workId: string; reviewer: string; rationale: string },
+): RequirementAcceptanceReadiness {
+  const requirementId = String(input.requirementId ?? '').trim();
+  const workId = String(input.workId ?? '').trim();
+  const reviewer = String(input.reviewer ?? '').trim();
+  const rationale = String(input.rationale ?? '').trim();
+  if (!requirementId) throw new Error('REQUIREMENT_ACCEPTANCE_ID_REQUIRED');
+  if (!workId) throw new Error('REQUIREMENT_ACCEPTANCE_WORK_REQUIRED');
+  if (!reviewer || !rationale) throw new Error('REQUIREMENT_ACCEPTANCE_METADATA_REQUIRED');
+
+  const current = readRequirement(options, requirementId)?.value;
+  if (!current) throw new Error(`REQUIREMENT_NOT_FOUND: ${requirementId}`);
+  if (current.state === 'cancelled') throw new Error(`REQUIREMENT_TERMINAL: ${requirementId}:cancelled`);
+  if (current.state === 'planned') throw new Error(`REQUIREMENT_ACCEPTANCE_NOT_ACTIVE: ${requirementId}:planned`);
+  if (current.state === 'done') {
+    return { requirement: current, finalizedPlanIds: current.semanticAcceptance?.planIds ?? [] };
+  }
+
+  const currentPlans = readPlanContractStore({ controllerHome: options.controllerHome, repoId: options.repoId, now: options.now })
+    .contracts
+    .filter((plan) => plan.requirementId === requirementId && !plan.supersededBy?.trim() && plan.status !== 'superseded');
+  const incomplete = currentPlans.filter((plan) => plan.status !== 'finalized');
+  if (incomplete.length > 0) {
+    throw new Error(`REQUIREMENT_ACCEPTANCE_PLAN_INCOMPLETE: ${incomplete.map((plan) => `${plan.planId}:${plan.status}`).join(',')}`);
+  }
+  const work = getWorkContract({ controllerHome: options.controllerHome, repoId: options.repoId }, workId);
+  if (!work) throw new Error(`REQUIREMENT_ACCEPTANCE_WORK_NOT_FOUND: ${workId}`);
+  if (work.requirementId !== requirementId) throw new Error(`REQUIREMENT_ACCEPTANCE_WORK_MISMATCH: ${workId}:${work.requirementId ?? 'none'}:${requirementId}`);
+  if (work.status !== 'completed') throw new Error(`REQUIREMENT_ACCEPTANCE_WORK_NOT_COMPLETED: ${workId}:${work.status}`);
+  return { requirement: current, finalizedPlanIds: currentPlans.map((plan) => plan.planId).sort() };
+}
+
+function acceptRequirementOutcomeUnlocked(
+  options: RequirementStoreOptions & { repoId: string },
+  input: { requirementId: string; workId: string; reviewer: string; rationale: string },
+): RequirementAcceptanceResult {
+  const context = requirementAcceptanceContext(options, input);
+  const requirementId = context.requirement.requirementId;
+  const reviewer = String(input.reviewer ?? '').trim();
+  const rationale = String(input.rationale ?? '').trim();
+  const relay = getControllerRoundRelay({ controllerHome: options.controllerHome, repoId: options.repoId }, input.workId);
+  if (!relay) throw new Error(`REQUIREMENT_ACCEPTANCE_GOAL_COMPLETE_REQUIRED: ${input.workId}:missing_relay`);
+  if (relay.originWorkId !== input.workId
+    || relay.requirementId !== requirementId
+    || relay.disposition !== 'goal_complete'
+    || relay.status !== 'goal_complete') {
+    throw new Error(`REQUIREMENT_ACCEPTANCE_GOAL_COMPLETE_REQUIRED: ${input.workId}:${relay.status}:${relay.disposition}`);
+  }
+  if (relay.principalId !== reviewer) {
+    throw new Error(`REQUIREMENT_ACCEPTANCE_CONTROLLER_MISMATCH: ${input.workId}:${relay.principalId}:${reviewer}`);
+  }
+  if (context.requirement.state === 'done') {
+    return { requirement: context.requirement, accepted: false, finalizedPlanIds: context.finalizedPlanIds };
+  }
+
+  const acceptedAt = options.now?.() ?? new Date().toISOString();
+  let accepted = false;
+  const requirement = updateRequirement(options, {
+    requirementId,
+    action: 'requirement_semantic_acceptance',
+    mutate: (latest) => {
+      if (latest.state === 'done') return latest;
+      if (latest.state === 'cancelled') throw new Error(`REQUIREMENT_TERMINAL: ${requirementId}:cancelled`);
+      if (latest.state === 'planned') throw new Error(`REQUIREMENT_ACCEPTANCE_NOT_ACTIVE: ${requirementId}:planned`);
+      accepted = true;
+      return {
+        ...latest,
+        state: 'done',
+        needsAttention: false,
+        attentionSummary: undefined,
+        semanticAcceptance: {
+          reviewer: reviewer.slice(0, 256),
+          rationale: rationale.slice(0, 2_000),
+          planIds: context.finalizedPlanIds,
+          acceptedAt,
+        },
+      };
+    },
+  });
+  return { requirement, accepted, finalizedPlanIds: context.finalizedPlanIds };
+}
+
+/**
+ * Canonical explicit semantic acceptance for a Requirement. Direct callers are
+ * serialized with Plan admission so Requirement completion cannot race a new
+ * current Plan slice into existence.
+ */
+export function acceptRequirementOutcome(
+  options: RequirementStoreOptions & { repoId: string },
+  input: { requirementId: string; workId: string; reviewer: string; rationale: string },
+): RequirementAcceptanceResult {
+  return withPlanAdmissionLock(options, () => acceptRequirementOutcomeUnlocked(options, input));
+}
+
+export interface RequirementGoalCompletionResult {
+  relay: ControllerRoundRelayRecord;
+  requirementAcceptance: RequirementAcceptanceResult;
+}
+
+/**
+ * One Goal application boundary for Requirement-bound goal_complete. The same
+ * short semantic lock used by Plan admission covers readiness, ControllerRound
+ * disposition persistence, and Requirement acceptance. A retry reuses an
+ * already-recorded goal_complete relay and repairs only the missing Requirement
+ * projection; no second ControllerRound or Plan authority is created.
+ */
+export function completeRequirementGoal(
+  options: RequirementStoreOptions & { repoId: string },
+  input: Omit<SubmitControllerRoundDispositionInput, 'disposition' | 'requirementId' | 'reason'> & {
+    requirementId: string;
+    rationale: string;
+  },
+): RequirementGoalCompletionResult {
+  return withPlanAdmissionLock(options, () => {
+    const reviewer = input.identity.principalId.trim();
+    const readinessInput = {
+      requirementId: input.requirementId,
+      workId: input.workId,
+      reviewer,
+      rationale: input.rationale,
+    };
+    requirementAcceptanceContext(options, readinessInput);
+
+    const existing = getControllerRoundRelay(options, input.workId);
+    let relay: ControllerRoundRelayRecord;
+    if (existing?.status === 'goal_complete' && existing.disposition === 'goal_complete') {
+      relay = existing;
+    } else {
+      try {
+        relay = submitControllerRoundDisposition(options, {
+          ...input,
+          disposition: 'goal_complete',
+          requirementId: input.requirementId,
+          reason: input.rationale,
+        });
+      } catch (error) {
+        const raced = getControllerRoundRelay(options, input.workId);
+        if (!raced || raced.status !== 'goal_complete' || raced.disposition !== 'goal_complete') throw error;
+        relay = raced;
+      }
+    }
+    const requirementAcceptance = acceptRequirementOutcomeUnlocked(options, readinessInput);
+    return { relay, requirementAcceptance };
+  });
+}

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

@@ -1,12 +1,13 @@
 import {
   REQUIREMENT_STATES,
+  isLegacyMachineRequirementWait,
   listRequirements,
   type Requirement,
   type RequirementState,
 } from '../persistence/requirement-store';
 import { isRepositoryCompletionReceipt } from './types';
 import { listPlanContracts, summarizePlanContract } from './plan-contract-store';
-import { listWorkContracts, summarizeWorkContract } from './work-contract-store';
+import { listWorkContracts, summarizeWorkContract } from '../../../../packages/kernel/work/api/index';
 import type { PlanContract, WorkContract } from './types';
 
 const DEFAULT_REQUIREMENT_LIMIT = 12;
@@ -54,6 +55,10 @@ function boundedText(value: unknown, maxLength: number): string {
 function explicitUserDecision(requirement: Requirement): string | undefined {
   if (requirement.state !== 'waiting_for_user') return undefined;
   const decision = boundedText(requirement.attentionSummary, 1_000);
+  // Compatibility repair: older V2 Work completion projected a machine receipt
+  // as if the whole Requirement needed user acceptance. That message is not a
+  // user decision authority and must not hide still-active Plan slices.
+  if (isLegacyMachineRequirementWait(requirement)) return undefined;
   return decision || undefined;
 }
 

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

@@ -0,0 +1,48 @@
+/*
+ * Stable rh_work operation ABI.
+ *
+ * The MCP input schema and server-generated SuggestedNextAction validation must
+ * consume this single registry. Keeping separate handwritten operation lists
+ * lets the Runtime advertise transitions that a client contract cannot express,
+ * or reject valid lifecycle actions that the schema already exposes.
+ */
+export const RH_WORK_OPERATIONS = [
+  'start',
+  'continue',
+  'verify',
+  'review',
+  'repair',
+  'finalize',
+  'stop',
+  'delegate',
+  'controller_claim',
+  'controller_release',
+  'controller_disposition',
+  'controller_get_owner',
+  'launcher_start',
+  'requirement_create',
+  'requirement_continue',
+  'plan_create',
+  'plan_get',
+  'plan_list',
+  'plan_approve',
+  'plan_accept_step',
+  'plan_supersede',
+  'schedule_create',
+  'schedule_list',
+  'schedule_get',
+  'schedule_pause',
+  'schedule_resume',
+  'schedule_delete',
+  'schedule_trigger',
+  'workflow_execute',
+  'workflow_reconcile',
+  'outcome_record',
+  'experience_record',
+] as const;
+
+export type RhWorkOperation = (typeof RH_WORK_OPERATIONS)[number];
+
+export function isRhWorkOperation(operation: string): operation is RhWorkOperation {
+  return (RH_WORK_OPERATIONS as readonly string[]).includes(operation);
+}

package/src/runtime/control-plane/facade/semantic-admission.ts

@@ -2,12 +2,15 @@ import { withControllerLock, withControllerLockAsync } from '../../../cli/reposi
 import { sanitizeFileComponent } from '../../shared/json-files';
 import { isTerminalPlanContractStatus, type PlanContract } from './types';
 
+export function isPlanExtensionPredecessor(plan: PlanContract): boolean {
+  return !isTerminalPlanContractStatus(plan.status) || plan.status === 'invalidated_by_drift';
+}
+
 export const PLAN_ADMISSION_RELATIONS = ['extend', 'parallel'] as const;
 export type PlanAdmissionRelation = (typeof PLAN_ADMISSION_RELATIONS)[number];
 
 export type PlanAdmissionReason =
   | 'exact_scope_authority'
-  | 'requirement_relation_required'
   | 'extension_target_required'
   | 'extend_existing'
   | 'create_new';
@@ -48,7 +51,7 @@ export function resolvePlanAdmission(
     : [];
   const relatedPlanId = input.relatedPlanId?.trim() || undefined;
   const explicitlyRelatedPlan = relatedPlanId
-    ? activePlans.find((candidate) => candidate.planId === relatedPlanId)
+    ? plans.find((candidate) => candidate.planId === relatedPlanId && isPlanExtensionPredecessor(candidate))
     : undefined;
   const relatedPlan = explicitlyRelatedPlan && (!requirementId || explicitlyRelatedPlan.requirementId === requirementId)
     ? explicitlyRelatedPlan
@@ -57,9 +60,9 @@ export function resolvePlanAdmission(
     ? activePlans.find((candidate) => candidate.scopeKey === normalizedScopeKey)
     : undefined;
 
-  // An explicit extension is a serial replan, not a second active Plan. Resolve
-  // it before exact-scope reuse so a successor may retain the predecessor scope.
-  // If another Plan owns the requested successor scope, preserve that authority.
+  // An explicit extension is a serial replan of one stable Plan identity, not a
+  // second active Plan. Resolve it before exact-scope reuse so the same Plan may
+  // revise its semantic scope. If another Plan owns that scope, preserve it.
   if (input.planRelation === 'extend') {
     if (!relatedPlan) {
       return {
@@ -102,17 +105,6 @@ export function resolvePlanAdmission(
     };
   }
 
-  if (requirementPlans.length > 0 && !input.planRelation) {
-    return {
-      admissionDecision: 'resolution_required',
-      resolutionRequired: true,
-      reason: 'requirement_relation_required',
-      normalizedScopeKey,
-      candidates: requirementPlans.slice(0, 8),
-      allowedPlanRelations: PLAN_ADMISSION_RELATIONS,
-    };
-  }
-
   return {
     admissionDecision: 'create_new',
     resolutionRequired: false,

package/src/runtime/control-plane/facade/suggested-actions.ts

@@ -1,3 +1,4 @@
+import { RH_WORK_OPERATIONS } from './rh-work-operation-contract';
 import { FACADE_TOOLS, type EvidenceRef, type FacadeTool, type SuggestedNextAction } from './types';
 
 function expectedActionRisk(action: SuggestedNextAction): SuggestedNextAction['risk'] | undefined {
@@ -6,6 +7,7 @@ function expectedActionRisk(action: SuggestedNextAction): SuggestedNextAction['r
     case 'start':
     case 'continue':
     case 'verify':
+    case 'review':
     case 'repair':
     case 'stop':
     case 'delegate':
@@ -14,6 +16,7 @@ function expectedActionRisk(action: SuggestedNextAction): SuggestedNextAction['r
     case 'controller_disposition':
     case 'launcher_start':
     case 'requirement_create':
+    case 'requirement_continue':
     case 'schedule_create':
     case 'schedule_pause':
     case 'schedule_resume':
@@ -44,7 +47,7 @@ const ALLOWED_FACADE_OPERATIONS: Record<FacadeTool, readonly string[]> = {
   rh_status: ['list', 'get', 'repair'],
   rh_inbox: ['list', 'get', 'ack', 'accept', 'resolve', 'dismiss', 'create'],
   rh_context: ['list', 'get', 'search'],
-  rh_work: ['start', 'continue', 'verify', 'repair', 'finalize', 'stop', 'delegate', 'controller_claim', 'controller_release', 'controller_disposition', 'controller_get_owner', 'launcher_start', 'requirement_create', 'plan_create', 'plan_get', 'plan_list', 'plan_approve', 'plan_accept_step', 'plan_supersede', 'schedule_create', 'schedule_list', 'schedule_get', 'schedule_pause', 'schedule_resume', 'schedule_delete', 'schedule_trigger'],
+  rh_work: RH_WORK_OPERATIONS,
 };
 
 export interface SuggestedActionValidationOptions {