@moretea-labs/forge 1.6.0 → 1.7.1

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';
@@ -14,3 +15,5 @@ export * from './goal-workloop-access';
 export * from './codex-delegation';
 export * from './self-healing-loop';
 export * from './operation-digest';
+export * from './requirement-authority';
+export * from './repository-work-admission';

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,18 @@ export interface CreatePlanContractInput {
   evidenceRefs?: EvidenceRef[];
 }
 
+export interface AdmitPlanContractInput extends CreatePlanContractInput {
+  planRelation?: PlanAdmissionRelation;
+  relatedPlanId?: string;
+}
+
+export interface RepairDraftPlanContractInput extends Omit<CreatePlanContractInput, 'planId' | 'repoId' | 'requirementId' | 'evidenceRefs'> {
+  /** Source revision observed before entering the admission lock; rejects stale draft writers. */
+  expectedSourceRevision?: string;
+}
+
+export type AdmitPlanContractResult = PlanAdmissionResolution;
+
 export interface PlanContractSummary {
   planId: string;
   repoId: string;
@@ -68,7 +89,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 +136,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 +234,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 +257,38 @@ export function createPlanContract(options: PlanContractStoreOptions, input: Cre
     createdAt: at,
     updatedAt: at,
   };
+}
+
+function draftContentErrors(plan: PlanContract): string[] {
+  const errors: string[] = [];
+  if (!plan.sourceRevision) errors.push('source_revision is required');
+  if (!plan.scopeKey || plan.scopeKey === 'unknown') errors.push('scope_key is required');
+  if (!plan.goal) errors.push('goal is required');
+  if (plan.steps.length === 0) errors.push('at least one plan step is required');
+  const ids = new Set<string>();
+  for (const step of plan.steps) {
+    if (!step.id || step.id === 'unknown') errors.push('every plan step needs an id');
+    else if (ids.has(step.id)) errors.push(`duplicate plan step id: ${step.id}`);
+    else ids.add(step.id);
+    if (!step.objective) errors.push(`step ${step.id || 'unknown'} needs an objective`);
+    if (step.checks.length === 0) errors.push(`step ${step.id || 'unknown'} needs at least one machine-checkable check`);
+    if (step.acceptanceCriteria.length === 0) errors.push(`step ${step.id || 'unknown'} needs acceptance criteria`);
+    if (step.status !== 'pending') errors.push(`step ${step.id || 'unknown'} must be pending before approval`);
+  }
+  for (const step of plan.steps) {
+    for (const dependency of step.dependencies) {
+      const dependencyStep = plan.steps.find((candidate) => candidate.id === dependency);
+      if (!dependencyStep) errors.push(`step ${step.id} references unknown dependency ${dependency}`);
+      else if (dependencyStep.status !== 'pending') errors.push(`step ${step.id} dependency ${dependency} must be pending before approval`);
+    }
+  }
+  return [...new Set(errors)];
+}
+
+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 +297,135 @@ 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;
+}
+
+function repairDraftPlanContractUnlocked(
+  options: PlanContractStoreOptions,
+  planId: string,
+  input: RepairDraftPlanContractInput,
+): PlanContract {
+  const store = readPlanContractStore(options);
+  const key = sanitizeFileComponent(planId);
+  const index = store.contracts.findIndex((contract) => contract.planId === key);
+  if (index < 0) throw new Error(`plan contract not found: ${key}`);
+  const current = store.contracts[index]!;
+  if (current.status !== 'draft') throw new Error(`PLAN_DRAFT_REPAIR_STATUS_INVALID: ${current.planId}:${current.status}`);
+  if (input.expectedSourceRevision !== undefined && current.sourceRevision !== input.expectedSourceRevision) {
+    throw new Error(`PLAN_DRAFT_REPAIR_STALE_SOURCE: ${current.planId}:expected=${input.expectedSourceRevision}:actual=${current.sourceRevision}`);
+  }
+  assertRequirementReference(options, current.requirementId);
+  const at = nowIso(options);
+  const candidate = buildPlanContract({
+    ...input,
+    planId: current.planId,
+    repoId: current.repoId,
+    requirementId: current.requirementId,
+    evidenceRefs: current.evidenceRefs,
+  }, at);
+  const contentErrors = draftContentErrors(candidate);
+  if (contentErrors.length > 0) {
+    throw new Error(`PLAN_DRAFT_REPAIR_INVALID: ${contentErrors.join('; ')}`);
+  }
+  const conflictingScope = store.contracts.find((existing, candidateIndex) => candidateIndex !== index
+    && !isTerminalPlanContractStatus(existing.status)
+    && existing.scopeKey === candidate.scopeKey);
+  if (conflictingScope) throw new Error(`PLAN_SCOPE_ALREADY_OWNED: ${candidate.scopeKey}:${conflictingScope.planId}`);
+  const repaired: PlanContract = {
+    ...candidate,
+    createdAt: current.createdAt,
+    updatedAt: at,
+  };
+  const contracts = [...store.contracts];
+  contracts[index] = repaired;
+  writePlanContractStore(options, { schemaVersion: 1, updatedAt: at, contracts });
+  return repaired;
+}
+
+export function repairDraftPlanContract(
+  options: PlanContractStoreOptions,
+  planId: string,
+  input: RepairDraftPlanContractInput,
+): PlanContract {
+  return withPlanAdmissionLock(options, () => repairDraftPlanContractUnlocked(options, planId, input));
+}
+
+export async function repairDraftPlanContractAsync(
+  options: PlanContractStoreOptions,
+  planId: string,
+  input: RepairDraftPlanContractInput,
+): Promise<PlanContract> {
+  return await withPlanAdmissionLockAsync(options, () => repairDraftPlanContractUnlocked(options, planId, input));
+}
+
+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));
 }
@@ -266,28 +455,7 @@ export function summarizePlanContract(plan: PlanContract): PlanContractSummary {
 }
 
 function approvalErrors(plan: PlanContract, allPlans: readonly PlanContract[]): string[] {
-  const errors: string[] = [];
-  if (!plan.sourceRevision) errors.push('source_revision is required before approval');
-  if (!plan.scopeKey || plan.scopeKey === 'unknown') errors.push('scope_key is required before approval');
-  if (!plan.goal) errors.push('goal is required before approval');
-  if (plan.steps.length === 0) errors.push('at least one plan step is required before approval');
-  const ids = new Set<string>();
-  for (const step of plan.steps) {
-    if (!step.id || step.id === 'unknown') errors.push('every plan step needs an id');
-    else if (ids.has(step.id)) errors.push(`duplicate plan step id: ${step.id}`);
-    else ids.add(step.id);
-    if (!step.objective) errors.push(`step ${step.id || 'unknown'} needs an objective`);
-    if (step.checks.length === 0) errors.push(`step ${step.id || 'unknown'} needs at least one machine-checkable check`);
-    if (step.acceptanceCriteria.length === 0) errors.push(`step ${step.id || 'unknown'} needs acceptance criteria`);
-    if (step.status !== 'pending') errors.push(`step ${step.id || 'unknown'} must be pending before approval`);
-  }
-  for (const step of plan.steps) {
-    for (const dependency of step.dependencies) {
-      const dependencyStep = plan.steps.find((candidate) => candidate.id === dependency);
-      if (!dependencyStep) errors.push(`step ${step.id} references unknown dependency ${dependency}`);
-      else if (dependencyStep.status !== 'pending') errors.push(`step ${step.id} dependency ${dependency} must be pending before approval`);
-    }
-  }
+  const errors = draftContentErrors(plan).map((error) => `${error} before approval`);
   const scopeIsCommitted = (status: PlanContractStatus): boolean => [
     'approved',
     'executing',
@@ -301,11 +469,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 +486,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 +525,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 +546,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 +614,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 +626,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 +644,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/repository-work-admission.ts

@@ -0,0 +1,147 @@
+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 type { WorkContract } from './types';
+
+export interface PreparedRepositoryWorkAdmissionInput {
+  workId: string;
+  repoId: string;
+  objective: string;
+  acceptanceCriteria: string[];
+  allowedPaths: string[];
+  checks: string[];
+  accessMode: AccessMode;
+  isolated: boolean;
+  requestedBy: WorkContract['requestedBy'];
+  requestId: string;
+}
+
+/**
+ * Canonical WorkContract admission for the compatibility work_prepare surface.
+ * Workspace materialization remains an execution concern; this function owns
+ * the semantic contract shape so transports cannot invent a parallel policy.
+ */
+export function admitPreparedRepositoryWorkContract(
+  store: WorkContractStoreOptions,
+  input: PreparedRepositoryWorkAdmissionInput,
+): WorkContract {
+  return createWorkContract(store, {
+    workId: input.workId,
+    repoId: input.repoId,
+    mode: input.isolated ? 'goal_workloop' : 'direct_control',
+    objective: input.objective,
+    acceptanceCriteria: input.acceptanceCriteria,
+    allowedPaths: input.allowedPaths,
+    forbiddenPaths: [],
+    checks: input.checks,
+    constraints: {
+      accessMode: input.accessMode,
+      workspaceMode: input.isolated ? 'isolated' : 'current',
+      requireWorktree: input.isolated,
+      directMainProhibited: input.isolated,
+      allowCommit: true,
+      allowMerge: true,
+      allowCleanup: true,
+    },
+    worktreePolicy: {
+      required: input.isolated,
+      reason: input.isolated ? 'work_prepare selected isolated worktree execution' : 'explicitly reused a registered checkout',
+    },
+    requestedBy: input.requestedBy,
+    requestId: input.requestId,
+  });
+}
+
+export interface DirectEditWorkAdmissionInput {
+  workId: string;
+  repoId: string;
+  checkoutId?: string;
+  principalId?: string;
+  controllerInstanceId?: string;
+  baseRevision?: string;
+  workspaceFingerprint: string;
+  routeDecision: RouteDecision;
+  objective: string;
+  issueId?: string;
+  taskId?: string;
+  allowedPaths: string[];
+  checks: string[];
+  requestedBy: WorkContract['requestedBy'];
+}
+
+/**
+ * Canonical compatibility admission for an Edit Session bound to Direct Work.
+ * The caller supplies the canonical Route Policy decision as evidence; this
+ * boundary rejects any decision that requires isolation or a non-direct lane.
+ */
+export function admitDirectEditWorkContract(
+  store: WorkContractStoreOptions,
+  input: DirectEditWorkAdmissionInput,
+): WorkContract {
+  if (input.routeDecision.executionMode !== 'direct_control' || input.routeDecision.requiresIsolation) {
+    throw new Error('DIRECT_EDIT_WORK_ROUTE_CONFLICT: canonical Route Policy does not permit Direct Control');
+  }
+  return createWorkContract(store, {
+    workId: input.workId,
+    repoId: input.repoId,
+    checkoutId: input.checkoutId,
+    principalId: input.principalId,
+    controllerInstanceId: input.controllerInstanceId,
+    baseRevision: input.baseRevision,
+    workspaceFingerprint: input.workspaceFingerprint,
+    routeDecisionFingerprint: input.routeDecision.inputFingerprint,
+    routeDecision: input.routeDecision,
+    mode: 'direct_control',
+    objective: input.objective,
+    acceptanceCriteria: [],
+    constraints: { workspaceMode: 'current', requireWorktree: false, requireHandoffOnAmbiguity: true },
+    risk: 'low',
+    status: 'running',
+    phase: 'implementation',
+    issueId: input.issueId,
+    taskId: input.taskId,
+    scopeSummary: input.objective,
+    allowedPaths: input.allowedPaths,
+    forbiddenPaths: [],
+    checks: input.checks,
+    requestedBy: input.requestedBy,
+    evidenceRefs: [],
+    handoffRefs: [],
+    suggestedNextActions: [],
+    policyDecisions: [],
+    checkRefs: [],
+    reconciliations: [],
+  });
+}
+
+
+export interface MaterializedRepositoryWorkspace {
+  managed: boolean;
+  checkoutId?: string;
+  root?: string;
+  baseRevision?: string | null;
+}
+
+/**
+ * Canonical placement materialization transition for an admitted isolated
+ * WorkContract. The concrete worktree creator is injected by the execution
+ * boundary; only this authority decides how its evidence updates the Work.
+ */
+export function materializeRepositoryWorkPlacement(
+  store: WorkContractStoreOptions,
+  workId: string,
+  materialize: (contract: WorkContract) => MaterializedRepositoryWorkspace,
+): WorkContract | undefined {
+  const contract = getWorkContract(store, workId);
+  if (!contract || contract.worktreePolicy.required !== true || contract.worktreeRef) return contract;
+  const workspace = materialize(contract);
+  if (!workspace.managed || !workspace.checkoutId || !workspace.root) {
+    throw new Error('MANAGED_WORKSPACE_NOT_MATERIALIZED');
+  }
+  return updateWorkContract(store, workId, {
+    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

@@ -0,0 +1,83 @@
+import {
+  createRequirement,
+  readRequirement,
+  type CreateRequirementInput,
+  type Requirement,
+  type RequirementStoreOptions,
+} from '../persistence/requirement-store';
+
+export type RequirementAdmissionDecision = 'created' | 'reuse_existing' | 'existing_conflict';
+
+export interface RequirementAdmissionResult {
+  decision: RequirementAdmissionDecision;
+  requirement: Requirement;
+  created: boolean;
+}
+
+function bounded(values: readonly string[] | undefined, limit: number, maxLength = 500): string[] {
+  return (values ?? [])
+    .map((value) => String(value).trim())
+    .filter(Boolean)
+    .slice(0, limit)
+    .map((value) => value.slice(0, maxLength));
+}
+
+/**
+ * Canonical Requirement bootstrap request. Persistence performs the same
+ * defensive bounds before writing, but create/reuse/conflict admission lives
+ * only here so MCP/CLI adapters cannot grow their own Requirement lifecycle.
+ */
+export function normalizeRequirementAdmissionInput(input: CreateRequirementInput): CreateRequirementInput {
+  const requirementId = String(input.requirementId ?? '').trim();
+  if (!requirementId || requirementId.includes('/') || requirementId.includes('\\')) throw new Error('REQUIREMENT_ID_INVALID');
+  const normalized: CreateRequirementInput = {
+    requirementId: requirementId.slice(0, 160),
+    title: String(input.title ?? '').trim().slice(0, 500),
+    outcomeStatement: String(input.outcomeStatement ?? '').trim().slice(0, 2_000),
+    acceptanceCriteria: bounded(input.acceptanceCriteria, 50),
+    requiredDeliveryReferences: bounded(input.requiredDeliveryReferences, 50),
+    legacyAliases: bounded(input.legacyAliases, 20, 160),
+  };
+  if (!normalized.title || !normalized.outcomeStatement) throw new Error('REQUIREMENT_CONTENT_REQUIRED');
+  return normalized;
+}
+
+function sameBootstrapIdentity(existing: Requirement, requested: CreateRequirementInput): boolean {
+  return existing.requirementId === requested.requirementId
+    && existing.title === requested.title
+    && existing.outcomeStatement === requested.outcomeStatement
+    && JSON.stringify(existing.acceptanceCriteria) === JSON.stringify(requested.acceptanceCriteria ?? [])
+    && JSON.stringify(existing.requiredDeliveryReferences) === JSON.stringify(requested.requiredDeliveryReferences ?? [])
+    && JSON.stringify(existing.legacyAliases) === JSON.stringify(requested.legacyAliases ?? []);
+}
+
+function existingDecision(existing: Requirement, requested: CreateRequirementInput): RequirementAdmissionResult {
+  return {
+    decision: sameBootstrapIdentity(existing, requested) ? 'reuse_existing' : 'existing_conflict',
+    requirement: existing,
+    created: false,
+  };
+}
+
+/**
+ * Sole bootstrap admission authority for Requirement identity. A create race is
+ * closed by rereading the winner and applying the same identity comparison;
+ * adapters therefore never need read/compare/create policy of their own.
+ */
+export function admitRequirement(
+  options: RequirementStoreOptions,
+  input: CreateRequirementInput,
+): RequirementAdmissionResult {
+  const requested = normalizeRequirementAdmissionInput(input);
+  const existing = readRequirement(options, requested.requirementId)?.value;
+  if (existing) return existingDecision(existing, requested);
+
+  try {
+    return { decision: 'created', requirement: createRequirement(options, requested), created: true };
+  } catch (error) {
+    if (!(error instanceof Error) || !error.message.startsWith('REQUIREMENT_ALREADY_EXISTS:')) throw error;
+    const raced = readRequirement(options, requested.requirementId)?.value;
+    if (!raced) throw error;
+    return existingDecision(raced, requested);
+  }
+}