@moretea-labs/forge 1.5.1 → 1.7.0

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

@@ -5,6 +5,7 @@ export * from './work-task-projection';
 export * from './work-continuation';
 export * from './controller-session-store';
 export * from './plan-contract-store';
+export * from './semantic-admission';
 export * from './facade-result';
 export * from './suggested-actions';
 export * from './capability-registry';

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

@@ -3,12 +3,21 @@ import { join } from 'path';
 import { repositoryControllerRoot } from '../../../cli/repositories/controller-home';
 import { withControllerLock } from '../../../cli/repositories/locks';
 import { readJsonFile, sanitizeFileComponent, writeJsonAtomic } from '../../shared/json-files';
+import {
+  normalizePlanScopeKey,
+  resolvePlanAdmission,
+  withPlanAdmissionLock,
+  withPlanAdmissionLockAsync,
+  type PlanAdmissionRelation,
+  type PlanAdmissionResolution,
+} from './semantic-admission';
 import {
   listControlPlaneRecords,
   readControlPlaneRecordWithinTransaction,
   withControlPlaneTransaction,
   writeControlPlaneRecordWithinTransaction,
 } from '../persistence/sqlite-store';
+import { readRequirement } from '../persistence/requirement-store';
 import {
   isTerminalPlanContractStatus,
   type EvidenceRef,
@@ -46,6 +55,13 @@ export interface CreatePlanContractInput {
   evidenceRefs?: EvidenceRef[];
 }
 
+export interface AdmitPlanContractInput extends CreatePlanContractInput {
+  planRelation?: PlanAdmissionRelation;
+  relatedPlanId?: string;
+}
+
+export type AdmitPlanContractResult = PlanAdmissionResolution;
+
 export interface PlanContractSummary {
   planId: string;
   repoId: string;
@@ -68,7 +84,7 @@ function bounded(values: readonly string[] | undefined, limit: number, maxLength
 }
 
 function normalizeScopeKey(value: string): string {
-  return sanitizeFileComponent(value).toLowerCase().slice(0, 160);
+  return normalizePlanScopeKey(value) || 'unknown';
 }
 
 function normalizeStep(step: CreatePlanContractInput['steps'][number]): PlanStep {
@@ -115,6 +131,14 @@ function updatePlanContract(
   );
 }
 
+function assertRequirementReference(options: PlanContractStoreOptions, requirementId: string | undefined): void {
+  const normalized = requirementId?.trim();
+  if (!normalized || !options.controllerHome) return;
+  if (!readRequirement({ controllerHome: options.controllerHome, now: options.now }, normalized)) {
+    throw new Error(`PLAN_REQUIREMENT_NOT_FOUND: ${normalized}`);
+  }
+}
+
 export function planContractRoot(location: PlanContractStoreLocation): string {
   if (location.root) {
     mkdirSync(location.root, { recursive: true });
@@ -205,11 +229,10 @@ function writePlanContractStore(options: PlanContractStoreOptions, store: PlanCo
   return store;
 }
 
-export function createPlanContract(options: PlanContractStoreOptions, input: CreatePlanContractInput): PlanContract {
-  const at = nowIso(options);
+function buildPlanContract(input: CreatePlanContractInput, at: string): PlanContract {
   const planId = sanitizeFileComponent(input.planId);
   if (!String(input.planId ?? '').trim() || planId === 'unknown') throw new Error('plan_id is required');
-  const plan: PlanContract = {
+  return {
     schemaVersion: 1,
     planId,
     repoId: input.repoId,
@@ -229,6 +252,12 @@ export function createPlanContract(options: PlanContractStoreOptions, input: Cre
     createdAt: at,
     updatedAt: at,
   };
+}
+
+function createPlanContractUnlocked(options: PlanContractStoreOptions, input: CreatePlanContractInput): PlanContract {
+  assertRequirementReference(options, input.requirementId);
+  const at = nowIso(options);
+  const plan = buildPlanContract(input, at);
   const store = readPlanContractStore(options);
   if (store.contracts.some((existing) => existing.planId === plan.planId)) {
     throw new Error(`plan contract already exists: ${plan.planId}`);
@@ -237,6 +266,77 @@ export function createPlanContract(options: PlanContractStoreOptions, input: Cre
   return plan;
 }
 
+function replacePlanContractUnlocked(
+  options: PlanContractStoreOptions,
+  predecessorId: string,
+  input: CreatePlanContractInput,
+): PlanContract {
+  assertRequirementReference(options, input.requirementId);
+  const at = nowIso(options);
+  const store = readPlanContractStore(options);
+  const predecessorKey = sanitizeFileComponent(predecessorId);
+  const predecessorIndex = store.contracts.findIndex((contract) => contract.planId === predecessorKey);
+  if (predecessorIndex < 0) throw new Error(`plan contract not found: ${predecessorKey}`);
+  const predecessor = store.contracts[predecessorIndex]!;
+  if (isTerminalPlanContractStatus(predecessor.status)) throw new Error(`plan contract ${predecessor.planId} is terminal (${predecessor.status})`);
+  const successor = buildPlanContract(input, at);
+  if (successor.planId === predecessor.planId) throw new Error('PLAN_SUCCESSOR_ID_MUST_CHANGE');
+  if (successor.repoId !== predecessor.repoId) throw new Error('PLAN_SUCCESSOR_REPOSITORY_MISMATCH');
+  if (store.contracts.some((existing) => existing.planId === successor.planId)) {
+    throw new Error(`plan contract already exists: ${successor.planId}`);
+  }
+  const conflictingScope = store.contracts.find((existing, index) => index !== predecessorIndex
+    && !isTerminalPlanContractStatus(existing.status)
+    && existing.scopeKey === successor.scopeKey);
+  if (conflictingScope) throw new Error(`PLAN_SCOPE_ALREADY_OWNED: ${successor.scopeKey}:${conflictingScope.planId}`);
+  const contracts = [...store.contracts];
+  contracts[predecessorIndex] = { ...predecessor, status: 'superseded', supersededBy: successor.planId, updatedAt: at };
+  writePlanContractStore(options, { schemaVersion: 1, updatedAt: at, contracts: [successor, ...contracts] });
+  return successor;
+}
+
+export function createPlanContract(options: PlanContractStoreOptions, input: CreatePlanContractInput): PlanContract {
+  return withPlanAdmissionLock(options, () => {
+    const store = readPlanContractStore(options);
+    const planId = sanitizeFileComponent(input.planId);
+    if (store.contracts.some((existing) => existing.planId === planId)) {
+      throw new Error(`plan contract already exists: ${planId}`);
+    }
+    const scopeKey = normalizeScopeKey(input.scopeKey);
+    const existingScopeAuthority = scopeKey === 'unknown' ? undefined : store.contracts.find((existing) =>
+      !isTerminalPlanContractStatus(existing.status) && existing.scopeKey === scopeKey);
+    if (existingScopeAuthority) {
+      throw new Error(`PLAN_SCOPE_ALREADY_OWNED: ${scopeKey}:${existingScopeAuthority.planId}`);
+    }
+    return createPlanContractUnlocked(options, input);
+  });
+}
+
+function admitPlanContractUnlocked(options: PlanContractStoreOptions, input: AdmitPlanContractInput): AdmitPlanContractResult {
+  assertRequirementReference(options, input.requirementId);
+  const activePlans = listPlanContracts({ ...options, status: 'active', limit: 100 });
+  const resolution = resolvePlanAdmission(activePlans, {
+    requirementId: input.requirementId,
+    scopeKey: input.scopeKey,
+    planRelation: input.planRelation,
+    relatedPlanId: input.relatedPlanId,
+  });
+  if (resolution.admissionDecision === 'extend_existing' && resolution.plan) {
+    const successor = replacePlanContractUnlocked(options, resolution.plan.planId, input);
+    return { ...resolution, admissionDecision: 'create_new', plan: successor };
+  }
+  if (resolution.admissionDecision !== 'create_new') return resolution;
+  return { ...resolution, plan: createPlanContractUnlocked(options, input) };
+}
+
+export function admitPlanContract(options: PlanContractStoreOptions, input: AdmitPlanContractInput): AdmitPlanContractResult {
+  return withPlanAdmissionLock(options, () => admitPlanContractUnlocked(options, input));
+}
+
+export async function admitPlanContractAsync(options: PlanContractStoreOptions, input: AdmitPlanContractInput): Promise<AdmitPlanContractResult> {
+  return await withPlanAdmissionLockAsync(options, () => admitPlanContractUnlocked(options, input));
+}
+
 export function getPlanContract(options: PlanContractStoreOptions, planId: string): PlanContract | undefined {
   return readPlanContractStore(options).contracts.find((contract) => contract.planId === sanitizeFileComponent(planId));
 }
@@ -301,11 +401,12 @@ function approvalErrors(plan: PlanContract, allPlans: readonly PlanContract[]):
   return [...new Set(errors)];
 }
 
-export function approvePlanContract(options: PlanContractStoreOptions, planId: string): PlanContract {
+function approvePlanContractUnlocked(options: PlanContractStoreOptions, planId: string): PlanContract {
   const store = readPlanContractStore(options);
   const index = store.contracts.findIndex((contract) => contract.planId === sanitizeFileComponent(planId));
   if (index < 0) throw new Error(`plan contract not found: ${sanitizeFileComponent(planId)}`);
   const current = store.contracts[index];
+  assertRequirementReference(options, current.requirementId);
   if (current.status !== 'draft' && current.status !== 'reviewing') throw new Error(`plan contract ${current.planId} cannot be approved from ${current.status}`);
   const errors = approvalErrors(current, store.contracts);
   if (errors.length > 0) throw new Error(`plan contract ${current.planId} cannot be approved: ${errors.join('; ')}`);
@@ -317,20 +418,33 @@ export function approvePlanContract(options: PlanContractStoreOptions, planId: s
   return next;
 }
 
+export function approvePlanContract(options: PlanContractStoreOptions, planId: string): PlanContract {
+  return withPlanAdmissionLock(options, () => approvePlanContractUnlocked(options, planId));
+}
+
+export async function approvePlanContractAsync(options: PlanContractStoreOptions, planId: string): Promise<PlanContract> {
+  return await withPlanAdmissionLockAsync(options, () => approvePlanContractUnlocked(options, planId));
+}
+
 export function supersedePlanContract(options: PlanContractStoreOptions, planId: string, supersededBy: string): PlanContract {
-  const store = readPlanContractStore(options);
-  const index = store.contracts.findIndex((contract) => contract.planId === sanitizeFileComponent(planId));
-  if (index < 0) throw new Error(`plan contract not found: ${sanitizeFileComponent(planId)}`);
-  const current = store.contracts[index];
-  if (isTerminalPlanContractStatus(current.status)) throw new Error(`plan contract ${current.planId} is terminal (${current.status})`);
-  const replacement = sanitizeFileComponent(supersededBy);
-  if (!replacement || replacement === 'unknown') throw new Error('superseded_by is required');
-  const at = nowIso(options);
-  const next = { ...current, status: 'superseded' as const, supersededBy: replacement, updatedAt: at };
-  const contracts = [...store.contracts];
-  contracts[index] = next;
-  writePlanContractStore(options, { schemaVersion: 1, updatedAt: at, contracts });
-  return next;
+  return withPlanAdmissionLock(options, () => {
+    const store = readPlanContractStore(options);
+    const index = store.contracts.findIndex((contract) => contract.planId === sanitizeFileComponent(planId));
+    if (index < 0) throw new Error(`plan contract not found: ${sanitizeFileComponent(planId)}`);
+    const current = store.contracts[index]!;
+    if (isTerminalPlanContractStatus(current.status)) throw new Error(`plan contract ${current.planId} is terminal (${current.status})`);
+    const replacement = sanitizeFileComponent(supersededBy);
+    if (!replacement || replacement === 'unknown') throw new Error('superseded_by is required');
+    if (replacement === current.planId) throw new Error('PLAN_SUCCESSOR_ID_MUST_CHANGE');
+    const successor = store.contracts.find((contract) => contract.planId === replacement);
+    if (!successor) throw new Error(`PLAN_SUCCESSOR_NOT_FOUND: ${replacement}`);
+    const at = nowIso(options);
+    const next = { ...current, status: 'superseded' as const, supersededBy: successor.planId, updatedAt: at };
+    const contracts = [...store.contracts];
+    contracts[index] = next;
+    writePlanContractStore(options, { schemaVersion: 1, updatedAt: at, contracts });
+    return next;
+  });
 }
 
 /**
@@ -343,6 +457,7 @@ export function claimPlanStepForWork(
   input: { planId: string; stepId: string; workId: string; sourceRevision: string },
 ): PlanContract {
   return updatePlanContract(options, input.planId, (current) => {
+    assertRequirementReference(options, current.requirementId);
     if (current.status !== 'approved' && current.status !== 'executing') {
       throw new Error(`PLAN_NOT_EXECUTABLE: ${current.planId} is ${current.status}`);
     }
@@ -363,6 +478,45 @@ export function claimPlanStepForWork(
   });
 }
 
+export function repairDanglingPlanStepWorkBinding(
+  options: PlanContractStoreOptions,
+  input: { planId: string; stepId: string; expectedWorkId: string; reason: string },
+): PlanContract {
+  const expectedWorkId = input.expectedWorkId.trim();
+  const reason = input.reason.trim();
+  if (!expectedWorkId) throw new Error('PLAN_STEP_REPAIR_EXPECTED_WORK_REQUIRED');
+  if (!reason) throw new Error('PLAN_STEP_REPAIR_REASON_REQUIRED');
+  return updatePlanContract(options, input.planId, (current) => {
+    if (isTerminalPlanContractStatus(current.status)) throw new Error(`PLAN_STEP_REPAIR_PLAN_TERMINAL: ${current.planId} is ${current.status}`);
+    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.workId !== expectedWorkId) {
+      throw new Error(`PLAN_STEP_REPAIR_BINDING_CHANGED: ${step.id} is bound to ${step.workId ?? 'no Work'}, expected ${expectedWorkId}`);
+    }
+    if (step.status !== 'executing') {
+      throw new Error(`PLAN_STEP_REPAIR_STATUS_INVALID: ${step.id} is ${step.status}`);
+    }
+    const at = nowIso(options);
+    const steps = [...current.steps];
+    steps[stepIndex] = {
+      ...step,
+      status: 'ready',
+      workId: undefined,
+      evidenceRefs: [{
+        title: 'dangling Work binding repaired',
+        summary: `${expectedWorkId}: ${reason}`.slice(0, 2_000),
+        detailLevel: 'summary' as const,
+      }, ...step.evidenceRefs].slice(0, 20),
+    };
+    // This is admission-state repair, not semantic replanning: the Plan and its
+    // acceptance criteria remain authoritative. Return the exact step to ready
+    // so a later start can atomically admit one replacement for the missing
+    // record without forcing a second Plan authority.
+    return { ...current, status: 'executing', steps, updatedAt: at };
+  });
+}
+
 export function completePlanStepForWork(
   options: PlanContractStoreOptions,
   input: {
@@ -376,28 +530,59 @@ 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',
+      // Successful delivery keeps the exact Work identity through semantic
+      // validation. Failed/cancelled Work releases the step authority so the
+      // replanning path cannot retain a ghost binding to a terminal Work.
+      workId: delivered ? step.workId : undefined,
+      evidenceRefs: input.work.evidenceRefs.length > 0 ? input.work.evidenceRefs.slice(0, 20) : step.evidenceRefs,
+    };
+    return { ...current, status: delivered ? 'verifying' : 'replanning', steps, updatedAt: at };
+  });
+}
+
+export function acceptPlanStepEvidence(
+  options: PlanContractStoreOptions,
+  input: { planId: string; stepId: string; reviewer: string; rationale: string; acceptedSourceRevision?: 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');
+    const acceptedSourceRevision = input.acceptedSourceRevision?.trim();
     return {
       ...current,
-      status: completed ? (allCompleted ? 'ready_to_finalize' : 'executing') : 'replanning',
+      ...(acceptedSourceRevision ? { sourceRevision: acceptedSourceRevision } : {}),
+      status: allCompleted ? 'finalized' : 'executing',
       steps,
-      updatedAt: at,
+      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/semantic-admission.ts

@@ -0,0 +1,205 @@
+import { withControllerLock, withControllerLockAsync } from '../../../cli/repositories/locks';
+import { sanitizeFileComponent } from '../../shared/json-files';
+import { isTerminalPlanContractStatus, type PlanContract } from './types';
+
+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';
+
+export interface PlanAdmissionInput {
+  requirementId?: string;
+  scopeKey: string;
+  planRelation?: PlanAdmissionRelation;
+  relatedPlanId?: string;
+}
+
+export interface PlanAdmissionResolution {
+  admissionDecision: 'reuse_existing' | 'resolution_required' | 'extend_existing' | 'create_new';
+  resolutionRequired: boolean;
+  reason: PlanAdmissionReason;
+  normalizedScopeKey: string;
+  plan?: PlanContract;
+  candidates: PlanContract[];
+  allowedPlanRelations?: readonly PlanAdmissionRelation[];
+}
+
+export function normalizePlanScopeKey(value: string): string {
+  const raw = String(value ?? '').trim();
+  if (!raw) return '';
+  const normalized = sanitizeFileComponent(raw).toLowerCase().slice(0, 160);
+  return normalized === 'unknown' ? '' : normalized;
+}
+
+export function resolvePlanAdmission(
+  plans: readonly PlanContract[],
+  input: PlanAdmissionInput,
+): PlanAdmissionResolution {
+  const activePlans = plans.filter((plan) => !isTerminalPlanContractStatus(plan.status));
+  const normalizedScopeKey = normalizePlanScopeKey(input.scopeKey);
+  const requirementId = input.requirementId?.trim() || undefined;
+  const requirementPlans = requirementId
+    ? activePlans.filter((candidate) => candidate.requirementId === requirementId)
+    : [];
+  const relatedPlanId = input.relatedPlanId?.trim() || undefined;
+  const explicitlyRelatedPlan = relatedPlanId
+    ? activePlans.find((candidate) => candidate.planId === relatedPlanId)
+    : undefined;
+  const relatedPlan = explicitlyRelatedPlan && (!requirementId || explicitlyRelatedPlan.requirementId === requirementId)
+    ? explicitlyRelatedPlan
+    : !relatedPlanId && requirementPlans.length === 1 ? requirementPlans[0] : undefined;
+  const exactScopeAuthority = normalizedScopeKey
+    ? 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.
+  if (input.planRelation === 'extend') {
+    if (!relatedPlan) {
+      return {
+        admissionDecision: 'resolution_required',
+        resolutionRequired: true,
+        reason: 'extension_target_required',
+        normalizedScopeKey,
+        candidates: (requirementPlans.length > 0 ? requirementPlans : activePlans).slice(0, 8),
+        allowedPlanRelations: PLAN_ADMISSION_RELATIONS,
+      };
+    }
+    if (exactScopeAuthority && exactScopeAuthority.planId !== relatedPlan.planId) {
+      return {
+        admissionDecision: 'reuse_existing',
+        resolutionRequired: false,
+        reason: 'exact_scope_authority',
+        normalizedScopeKey,
+        plan: exactScopeAuthority,
+        candidates: [exactScopeAuthority],
+      };
+    }
+    return {
+      admissionDecision: 'extend_existing',
+      resolutionRequired: false,
+      reason: 'extend_existing',
+      normalizedScopeKey,
+      plan: relatedPlan,
+      candidates: requirementPlans.length > 0 ? requirementPlans.slice(0, 8) : [relatedPlan],
+    };
+  }
+
+  if (exactScopeAuthority) {
+    return {
+      admissionDecision: 'reuse_existing',
+      resolutionRequired: false,
+      reason: 'exact_scope_authority',
+      normalizedScopeKey,
+      plan: exactScopeAuthority,
+      candidates: [exactScopeAuthority],
+    };
+  }
+
+  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,
+    reason: 'create_new',
+    normalizedScopeKey,
+    candidates: requirementPlans.slice(0, 8),
+  };
+}
+
+/**
+ * Short per-repository semantic admission critical section. The fixed task key
+ * keeps admission independent from repository/worktree execution locks while
+ * still coordinating competing controller processes for the same repository.
+ */
+const planAdmissionLockKey = (repoId: string) => ({
+  scope: 'task' as const,
+  repoId,
+  taskId: 'semantic-plan-admission',
+});
+
+export function withPlanAdmissionLock<T>(
+  options: { controllerHome?: string; repoId?: string },
+  operation: () => T,
+): T {
+  if (!options.controllerHome?.trim() || !options.repoId?.trim()) return operation();
+  return withControllerLock(
+    options.controllerHome,
+    planAdmissionLockKey(options.repoId),
+    'semantic-plan-admission',
+    operation,
+  );
+}
+
+/** Gateway-facing admission waits briefly for a competing controller to finish
+ * its tiny create/approve decision, then re-reads canonical state under lock. */
+export async function withPlanAdmissionLockAsync<T>(
+  options: { controllerHome?: string; repoId?: string },
+  operation: () => T | Promise<T>,
+): Promise<T> {
+  if (!options.controllerHome?.trim() || !options.repoId?.trim()) return await operation();
+  return await withControllerLockAsync(
+    options.controllerHome,
+    planAdmissionLockKey(options.repoId),
+    'semantic-plan-admission',
+    async () => await operation(),
+    undefined,
+    500,
+  );
+}
+
+const primaryWorkAdmissionLockKey = (repoId: string) => ({
+  scope: 'task' as const,
+  repoId,
+  taskId: 'semantic-primary-work-admission',
+});
+
+/**
+ * Primary Work admission protects only canonical ownership resolution and
+ * persistence. It must never span workspace materialization, dependency prep,
+ * checks, worker launch, or the Work execution lifetime.
+ */
+export function withPrimaryWorkAdmissionLock<T>(
+  options: { controllerHome?: string; repoId?: string },
+  operation: () => T,
+): T {
+  if (!options.controllerHome?.trim() || !options.repoId?.trim()) return operation();
+  return withControllerLock(
+    options.controllerHome,
+    primaryWorkAdmissionLockKey(options.repoId),
+    'semantic-primary-work-admission',
+    operation,
+  );
+}
+
+/** Gateway callers wait briefly for a competing admission, then re-read the
+ * canonical Plan/Work state while holding the same short critical section. */
+export async function withPrimaryWorkAdmissionLockAsync<T>(
+  options: { controllerHome?: string; repoId?: string },
+  operation: () => T | Promise<T>,
+): Promise<T> {
+  if (!options.controllerHome?.trim() || !options.repoId?.trim()) return await operation();
+  return await withControllerLockAsync(
+    options.controllerHome,
+    primaryWorkAdmissionLockKey(options.repoId),
+    'semantic-primary-work-admission',
+    async () => await operation(),
+    undefined,
+    500,
+  );
+}

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

@@ -11,10 +11,13 @@ function expectedActionRisk(action: SuggestedNextAction): SuggestedNextAction['r
     case 'delegate':
     case 'controller_claim':
     case 'controller_release':
+    case 'controller_disposition':
     case 'launcher_start':
+    case 'requirement_create':
     case 'schedule_create':
     case 'schedule_pause':
     case 'schedule_resume':
+    case 'schedule_delete':
     case 'schedule_trigger':
       return 'workspace_write';
     case 'controller_get_owner':
@@ -26,6 +29,7 @@ function expectedActionRisk(action: SuggestedNextAction): SuggestedNextAction['r
     case 'plan_list':
       return 'readonly';
     case 'plan_approve':
+    case 'plan_accept_step':
     case 'plan_supersede':
       return 'workspace_write';
     case 'finalize':
@@ -40,7 +44,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_get_owner', 'launcher_start', 'plan_create', 'plan_get', 'plan_list', 'plan_approve', 'plan_supersede', 'schedule_create', 'schedule_list', 'schedule_get', 'schedule_pause', 'schedule_resume', 'schedule_trigger'],
+  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'],
 };
 
 export interface SuggestedActionValidationOptions {