@moretea-labs/forge 1.6.0 → 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: {
@@ -392,6 +546,10 @@ export function completePlanStepForWork(
       // 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 };
@@ -400,7 +558,7 @@ export function completePlanStepForWork(
 
 export function acceptPlanStepEvidence(
   options: PlanContractStoreOptions,
-  input: { planId: string; stepId: string; reviewer: string; rationale: string },
+  input: { planId: string; stepId: string; reviewer: string; rationale: string; acceptedSourceRevision?: string },
 ): PlanContract {
   const reviewer = input.reviewer.trim();
   const rationale = input.rationale.trim();
@@ -418,6 +576,13 @@ export function acceptPlanStepEvidence(
       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) };
+    const acceptedSourceRevision = input.acceptedSourceRevision?.trim();
+    return {
+      ...current,
+      ...(acceptedSourceRevision ? { sourceRevision: acceptedSourceRevision } : {}),
+      status: allCompleted ? 'finalized' : 'executing',
+      steps,
+      updatedAt: nowIso(options),
+    };
   });
 }

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 {

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

@@ -1,13 +1,14 @@
 import type { ProcessCheckReceiptEvidence } from '../../evidence/process-check-receipt';
 import type { CompletionReceipt as RepositoryCompletionReceipt } from '../../../cli/controller/types';
 import type { AccessMode } from '../governance/access-policy';
-import { decideRoute, type RouteDecision, type RoutePolicyInput } from '../routing/route-policy';
+import { decideRoute, type ExplicitTaskMode, type RouteDecision, type RoutePolicyInput } from '../routing/route-policy';
 
 export const EXECUTION_MODES = ['direct_control', 'goal_workloop', 'handoff_only'] as const;
 export type ExecutionMode = (typeof EXECUTION_MODES)[number];
 
 export const FACADE_TOOLS = ['rh_access', 'rh_status', 'rh_inbox', 'rh_context', 'rh_work'] as const;
 export type FacadeTool = (typeof FACADE_TOOLS)[number];
+export type CapabilityExecutionSurface = FacadeTool | 'plugin_action_execute';
 
 export const FACADE_STATUSES = ['ok', 'blocked', 'failed', 'approval_required', 'not_found'] as const;
 export type FacadeStatus = (typeof FACADE_STATUSES)[number];
@@ -353,6 +354,8 @@ export interface WorkContractConstraints {
   conflictsWithThinHarnessPolicy?: boolean;
   /** True when the change alters the default routing or execution mode visible to users. */
   changesDefaultExecutionStrategy?: boolean;
+  /** Repository-change delivery must publish the exact integrated revision before Work terminalization. */
+  remoteDeliveryRequired?: boolean;
 }
 
 export interface WorkContractDriverPolicy {
@@ -476,6 +479,18 @@ export interface WorkContract {
   planStepId?: string;
   planSourceRevision?: string;
   scopeSummary?: string;
+  /**
+   * Discovery evidence, never an authorization boundary. Initial guesses,
+   * inspected paths, and observed changes remain distinct so early retrieval
+   * cannot masquerade as complete implementation scope.
+   */
+  scopeEvidence?: {
+    initialLikelyPaths: string[];
+    inspectedPaths: string[];
+    actualChangedPaths: string[];
+    recordedAt: string;
+  };
+  /** Explicit policy fence. This is not semantic completeness evidence. */
   allowedPaths: string[];
   forbiddenPaths: string[];
   checks: string[];
@@ -495,13 +510,12 @@ export interface WorkContract {
   continuationPrompt?: string;
   worktreeRef?: string;
   workerRef?: string;
-  /** Stable idempotency key when this Work was accepted via work_submit. */
   requestId?: string;
-  /** Accepted Kernel operation envelope. Does not imply ExecutionJob creation. */
+  /** Typed execution metadata; it does not imply ExecutionJob creation. */
   submittedOperation?: SubmittedWorkOperation;
 }
 
-/** Operation metadata retained on WorkContracts accepted through work_submit. */
+/** Typed execution metadata retained on execution-child WorkContracts. */
 export interface SubmittedWorkOperation {
   name: string;
   semanticKey: string;
@@ -630,7 +644,7 @@ export interface CapabilityDescriptor {
   group: CapabilityGroup;
   operationClass: CapabilityOperationClass;
   risk: CapabilityRisk;
-  exposedVia: FacadeTool;
+  exposedVia: CapabilityExecutionSurface;
   schemaExposure: CapabilitySchemaExposure;
   summary: string;
 }
@@ -639,6 +653,7 @@ export interface CapabilityGroupSummary {
   group: CapabilityGroup;
   capabilityCount: number;
   domains: CapabilityDomain[];
+  executionSurfaces: CapabilityExecutionSurface[];
   facadeTools: FacadeTool[];
   operationClasses: CapabilityOperationClass[];
   risks: CapabilityRisk[];
@@ -667,6 +682,7 @@ export interface ExecutionModeSelectionInput {
   requiresInvestigation?: boolean;
   requiresLongRunningChecks?: boolean;
   requiresParallelism?: boolean;
+  explicitMode?: ExplicitTaskMode;
   needsDependencies?: boolean;
   requiresRecovery?: boolean;
   /** True only when the user explicitly requested an agent/worker executor. Complexity alone must not enable workers. */
@@ -717,6 +733,7 @@ export function selectExecutionMode(input: ExecutionModeSelectionInput): Executi
       requiresInvestigation: input.requiresInvestigation,
       requiresLongRunningChecks: input.requiresLongRunningChecks,
       requiresParallelism: input.requiresParallelism,
+      explicitMode: input.explicitMode,
       needsDependencies: input.needsDependencies,
       agentRequested: input.requiresWorker,
     },