@moretea-labs/forge 1.8.0 → 1.8.2

package/adapters/mcp/runtime-gateway/work-learning-operations.ts

@@ -0,0 +1,145 @@
+import type { CallToolResult } from '../../../packages/protocols/mcp/tool-contract';
+import { getWorkContract } from '../../../packages/kernel/work/api/index';
+import {
+  recordControllerExperience,
+  recordControllerOutcome,
+  type ControllerExperienceDraft,
+  type ControllerOutcomeObservationDraft,
+} from '../../../src/runtime/context/assistant-work-context';
+import { parseControllerLearningSignalDrafts } from '../../../src/runtime/context/automatic-learning';
+import { persistDirectControllerLearning, recordDirectControllerLearningFeedback, type DirectControllerLearningFeedbackDraft } from '../../../src/runtime/context/direct-controller-learning';
+import { buildFacadeResult } from '../../../src/runtime/control-plane/facade';
+import type { MultiRepositoryMcpToolContext } from '../multi-repository';
+import { result } from './result-adapter';
+
+type RepositoryIdentity = { repoId: string; activeCheckoutId: string };
+
+/**
+ * rh_work learning dispatch is advisory. Generic learning needs no Work; Work-specific
+ * outcome/experience writes are bound to exact Work provenance and canonical evidence.
+ * ControllerSession/ControllerRound state never grants write authority here.
+ */
+export function callRhWorkLearningOperation(
+  ctx: MultiRepositoryMcpToolContext,
+  repository: RepositoryIdentity,
+  operation: string,
+  args: Record<string, unknown>,
+): CallToolResult | undefined {
+  if (!['learning_record', 'learning_feedback', 'outcome_record', 'experience_record'].includes(operation)) return undefined;
+  const store = { controllerHome: ctx.controllerHome, repoId: repository.repoId };
+  try {
+    if (operation === 'learning_feedback') {
+      if (!Array.isArray(args.learning_feedback) || args.learning_feedback.length === 0 || args.learning_feedback.length > 32) {
+        throw new Error('COGNITION_DIRECT_FEEDBACK_ITEMS_REQUIRED');
+      }
+      const feedback = args.learning_feedback.map((entry, index) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) throw new Error(`COGNITION_DIRECT_FEEDBACK_ITEM_INVALID: ${index}`);
+        const item = entry as Record<string, unknown>;
+        const decision = String(item.decision ?? '').trim();
+        const memoryAddress = String(item.memory_address ?? '').trim();
+        const reason = String(item.reason ?? '').trim();
+        const rejectionKind = typeof item.rejection_kind === 'string' ? item.rejection_kind.trim() : undefined;
+        if (!memoryAddress || !['used', 'rejected'].includes(decision)) throw new Error(`COGNITION_DIRECT_FEEDBACK_ITEM_INVALID: ${index}`);
+        if (decision === 'rejected' && !['irrelevant', 'stale', 'contradicted'].includes(rejectionKind ?? '')) {
+          throw new Error(`COGNITION_DIRECT_FEEDBACK_REJECTION_KIND_REQUIRED: ${index}`);
+        }
+        if (decision === 'used' && rejectionKind) throw new Error(`COGNITION_DIRECT_FEEDBACK_REJECTION_KIND_UNEXPECTED: ${index}`);
+        return {
+          memoryAddress,
+          decision,
+          reason,
+          ...(rejectionKind ? { rejectionKind } : {}),
+        } as DirectControllerLearningFeedbackDraft;
+      });
+      const recorded = recordDirectControllerLearningFeedback({
+        controllerHome: ctx.controllerHome,
+        repository,
+        feedback,
+        principalId: ctx.principalId,
+        sessionId: ctx.sessionId,
+        controllerInstanceId: ctx.controllerInstanceId,
+        workId: typeof args.work_id === 'string' && args.work_id.trim() ? args.work_id.trim() : undefined,
+      });
+      return result(buildFacadeResult({
+        summary: `Recorded ${recorded.observationIds.length} lifecycle-free Cognitive usage feedback observation(s).`,
+        data: {
+          recorded: true,
+          observationIds: recorded.observationIds,
+          scopes: recorded.scopes,
+          authorityBoundary: 'Usage feedback adjusts advisory retrieval utility only; it grants no execution, lifecycle, or semantic authority.',
+        },
+      }) as unknown as Record<string, unknown>);
+    }
+
+    if (operation === 'learning_record') {
+      const signals = parseControllerLearningSignalDrafts(args.learning_signals);
+      if (signals.length === 0) throw new Error('COGNITION_DIRECT_LEARNING_SIGNALS_REQUIRED');
+      const learning = persistDirectControllerLearning({
+        controllerHome: ctx.controllerHome,
+        repository,
+        signals,
+        principalId: ctx.principalId,
+        sessionId: ctx.sessionId,
+        controllerInstanceId: ctx.controllerInstanceId,
+        controllerType: ctx.controllerType,
+        workId: typeof args.work_id === 'string' && args.work_id.trim() ? args.work_id.trim() : undefined,
+      });
+      return result(buildFacadeResult({
+        summary: `Recorded ${learning.storedMemoryIds.length} model-authored advisory learning item(s) without creating Work lifecycle.`,
+        data: {
+          recorded: true,
+          storedMemoryIds: learning.storedMemoryIds,
+          associatedEdgeCount: learning.associatedEdgeCount,
+          consolidatedMemoryIds: learning.consolidatedMemoryIds,
+          scopes: learning.scopes,
+          authorityBoundary: 'Cognitive advisory memory only; it never grants execution or lifecycle authority.',
+        },
+      }) as unknown as Record<string, unknown>);
+    }
+
+    const workId = String(args.work_id ?? '').trim();
+    if (!workId) throw new Error('LEARNING_LOOP_WORK_ID_REQUIRED');
+    const work = getWorkContract(store, workId);
+    if (!work) throw new Error(`WORK_NOT_FOUND: ${workId}`);
+    const identity = { workId };
+
+    if (operation === 'outcome_record') {
+      if (!args.outcome_observation || typeof args.outcome_observation !== 'object' || Array.isArray(args.outcome_observation)) {
+        throw new Error('OUTCOME_OBSERVATION_REQUIRED');
+      }
+      const outcome = recordControllerOutcome({
+        controllerHome: ctx.controllerHome,
+        repoId: repository.repoId,
+        identity,
+        draft: args.outcome_observation as ControllerOutcomeObservationDraft,
+      });
+      return result(buildFacadeResult({
+        summary: `OutcomeObservation ${outcome.id} recorded from canonical Work evidence.`,
+        data: { outcome },
+      }) as unknown as Record<string, unknown>);
+    }
+
+    if (!args.experience_draft || typeof args.experience_draft !== 'object' || Array.isArray(args.experience_draft)) {
+      throw new Error('EXPERIENCE_DRAFT_REQUIRED');
+    }
+    const experience = recordControllerExperience({
+      controllerHome: ctx.controllerHome,
+      repoId: repository.repoId,
+      identity,
+      draft: args.experience_draft as ControllerExperienceDraft,
+      qualityAdjustmentFingerprint: typeof args.quality_adjustment_fingerprint === 'string'
+        ? args.quality_adjustment_fingerprint.trim() || undefined
+        : undefined,
+    });
+    return result(buildFacadeResult({
+      summary: `Experience ${experience.id} recorded from canonical Work evidence for later advisory reuse.`,
+      data: { experience },
+    }) as unknown as Record<string, unknown>);
+  } catch (error) {
+    return result(buildFacadeResult({
+      status: 'blocked',
+      summary: error instanceof Error ? error.message : 'Learning record failed.',
+      data: { recorded: false },
+    }) as unknown as Record<string, unknown>, true);
+  }
+}

package/adapters/mcp/runtime-gateway/work-list-projection.ts

@@ -0,0 +1,38 @@
+import type { CallToolResult } from '../../../packages/protocols/mcp/tool-contract';
+import {
+  listWorkContracts,
+  workSemanticView,
+  type WorkContractStoreOptions,
+} from '../../../packages/kernel/work/api/index';
+import { buildFacadeResult } from '../../../src/runtime/control-plane/facade';
+import { result } from './result-adapter';
+
+/**
+ * Bounded read-only collection projection for current and recent terminal semantic Work.
+ * Collection reads are separate from the semantic start/get/revise/complete
+ * mutation adapter so listing can never widen or gate semantic completion.
+ */
+export function callRhWorkListProjection(
+  store: WorkContractStoreOptions,
+  operation: string,
+  args: Record<string, unknown>,
+): CallToolResult | undefined {
+  if (operation !== 'list') return undefined;
+  const limit = Math.max(1, Math.min(Math.trunc(typeof args.limit === 'number' ? args.limit : 50), 100));
+  const historyLimit = Math.min(limit, 50);
+  const works = listWorkContracts({ ...store, state: 'active', limit });
+  const recentHistory = [
+    ...listWorkContracts({ ...store, state: 'completed', limit: historyLimit }),
+    ...listWorkContracts({ ...store, state: 'cancelled', limit: historyLimit }),
+  ]
+    .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))
+    .slice(0, historyLimit);
+  return result(buildFacadeResult({
+    summary: `${works.length} current and ${recentHistory.length} recent terminal semantic Work(s) in this repository.`,
+    data: {
+      works: works.map(workSemanticView),
+      recentHistory: recentHistory.map(workSemanticView),
+      bounded: true,
+    },
+  }) as unknown as Record<string, unknown>);
+}

package/adapters/mcp/runtime-gateway/work-plan-operations.ts

@@ -0,0 +1,382 @@
+import type { CallToolResult } from '../../../packages/protocols/mcp/tool-contract';
+import type { MultiRepositoryMcpToolContext } from '../multi-repository';
+import {
+  admitPlanContractAsync,
+  createPlanSemanticContext,
+  buildFacadeResult,
+  getPlanContract,
+  listPlanContracts,
+  normalizeCheckIds,
+  resolvePlanAdmission,
+  summarizePlanContract,
+  planSemanticView,
+  revisePlanSemanticContext,
+  listPlanSemanticRevisionRecords,
+  type CheckDefinitionLike,
+  type PlanContractStoreOptions,
+} from '../../../src/runtime/control-plane/facade';
+import { readRequirement } from '../../../src/runtime/control-plane/persistence/requirement-store';
+import { listRepositories } from '../../../src/cli/repositories/registry';
+import { SEMANTIC_SCOPE_KEY } from '../../../src/cli/repositories/controller-home';
+import { result } from './result-adapter';
+
+const RH_WORK_LIGHTWEIGHT_PLAN_OPERATIONS = new Set([
+  'plan_list',
+  'plan_get',
+  'plan_revise',
+]);
+
+export function isRhWorkLightweightPlanOperation(operation: string): boolean {
+  return RH_WORK_LIGHTWEIGHT_PLAN_OPERATIONS.has(operation);
+}
+
+export async function callRhWorkPlanOperation(
+  store: PlanContractStoreOptions,
+  operation: string,
+  args: Record<string, unknown>,
+): Promise<CallToolResult | undefined> {
+  if (!isRhWorkLightweightPlanOperation(operation)) return undefined;
+
+  if (operation === 'plan_list') {
+    const plans = listPlanContracts({ ...store, status: 'active', limit: typeof args.limit === 'number' ? args.limit : 20 });
+    const facade = buildFacadeResult({
+      summary: `${plans.length} current semantic Plan(s) in this repository.`,
+      data: { plans: plans.map(planSemanticView), bounded: true },
+    });
+    return result(facade as unknown as Record<string, unknown>);
+  }
+
+  if (operation === 'plan_get') {
+    const plan = getPlanContract(store, String(args.plan_id ?? ''));
+    const facade = plan
+      ? buildFacadeResult({
+          summary: `Plan ${plan.planId} current head retrieved at semantic revision ${planSemanticView(plan).revision}.`,
+          data: {
+            plan: planSemanticView(plan),
+            ...(args.detail_level === 'detail' ? { revisionHistory: listPlanSemanticRevisionRecords(store, plan.planId) } : {}),
+          },
+          detailLevel: args.detail_level === 'detail' ? 'detail' : 'summary',
+        })
+      : buildFacadeResult({
+          status: 'not_found',
+          summary: `PlanContract ${String(args.plan_id ?? '')} not found.`,
+          data: { planId: String(args.plan_id ?? '') },
+        });
+    return result(facade as unknown as Record<string, unknown>, !plan);
+  }
+
+  try {
+    if (operation === 'plan_revise') {
+      const planId = String(args.plan_id ?? '').trim();
+      const expectedRevision = Number(args.expected_revision);
+      const plan = revisePlanSemanticContext(store, planId, {
+        expectedRevision,
+        ...(typeof args.superseded_by === 'string' ? { supersededBy: args.superseded_by } : {}),
+        ...(typeof args.requirement_revision === 'number' ? { requirementBasisRevision: args.requirement_revision } : {}),
+        ...(typeof args.source_revision === 'string' ? { sourceBasisRevision: args.source_revision } : {}),
+        ...(typeof args.objective === 'string' ? { goal: args.objective } : {}),
+        ...(Array.isArray(args.non_goals) ? { nonGoals: args.non_goals.map(String) } : {}),
+        ...(Array.isArray(args.assumptions) ? { assumptions: args.assumptions.map(String) } : {}),
+        ...(Array.isArray(args.resolved_decisions) ? { resolvedDecisions: args.resolved_decisions.map(String) } : {}),
+        ...(Array.isArray(args.stop_conditions) ? { stopConditions: args.stop_conditions.map(String) } : {}),
+        ...(Array.isArray(args.replan_conditions) ? { replanConditions: args.replan_conditions.map(String) } : {}),
+        ...(args.integration_strategy === null || typeof args.integration_strategy === 'string' ? { integrationStrategy: args.integration_strategy as string | null } : {}),
+        ...(Array.isArray(args.plan_items) ? { items: args.plan_items
+          .filter((entry): entry is Record<string, unknown> => Boolean(entry) && typeof entry === 'object' && !Array.isArray(entry))
+          .map((entry) => ({
+            id: String(entry.id ?? ''),
+            objective: String(entry.objective ?? ''),
+            dependencies: Array.isArray(entry.dependencies) ? entry.dependencies.map(String) : [],
+          })) } : {}),
+      });
+      return result(buildFacadeResult({
+        summary: `Plan ${plan.planId} revised atomically to semantic revision ${planSemanticView(plan).revision}; source basis remains provenance metadata and no approval/execution transition was implied.`,
+        data: { plan: planSemanticView(plan), expectedRevision },
+      }) as unknown as Record<string, unknown>);
+    }
+
+    return undefined;
+  } catch (error) {
+    const currentPlanId = String(args.plan_id ?? '').trim();
+    const currentPlan = operation === 'plan_revise' && currentPlanId ? getPlanContract(store, currentPlanId) : undefined;
+    const facade = buildFacadeResult({
+      status: 'blocked',
+      summary: error instanceof Error ? error.message : 'PlanContract operation failed.',
+      data: {
+        operation,
+        executionStarted: false,
+        ...(currentPlan ? { currentPlan: planSemanticView(currentPlan) } : {}),
+      },
+    });
+    return result(facade as unknown as Record<string, unknown>, true);
+  }
+}
+
+function planObligationDispositionsFromArgs(value: unknown) {
+  if (!Array.isArray(value)) return undefined;
+  return value
+    .filter((entry): entry is Record<string, unknown> => Boolean(entry) && typeof entry === 'object' && !Array.isArray(entry))
+    .map((entry) => ({
+      predecessorPlanId: String(entry.predecessor_plan_id ?? ''),
+      obligationId: String(entry.obligation_id ?? ''),
+      disposition: String(entry.disposition ?? '') as 'keep' | 'change' | 'defer' | 'drop',
+      successorRefs: Array.isArray(entry.successor_refs) ? entry.successor_refs.map(String) : [],
+      rationale: typeof entry.rationale === 'string' ? entry.rationale : undefined,
+    }));
+}
+
+export interface RhWorkPlanCreateContext {
+  controllerHome: string;
+  /** Node-local placement provenance; absent when the Plan belongs to the ForgeInstance. */
+  repoId?: string;
+  checks: readonly CheckDefinitionLike[];
+}
+
+/**
+ * A Plan is authored semantic context: it can belong to the ForgeInstance with
+ * no repository and no source revision. When no repository target is available
+ * or explicitly requested, create it in the semantic scope; otherwise return
+ * undefined so the normal repository-bound path stays authoritative.
+ */
+export async function callRhWorkPlanCreateWithoutRepository(
+  ctx: MultiRepositoryMcpToolContext,
+  operation: string,
+  args: Record<string, unknown>,
+): Promise<CallToolResult | undefined> {
+  if (operation !== 'plan_create') return undefined;
+  const explicitRepoId = typeof args.repo_id === 'string' ? args.repo_id.trim() : '';
+  if (explicitRepoId || ctx.explicitRepository) return undefined;
+  const enabled = listRepositories(ctx.controllerHome).filter((record) => record.enabled && !record.removedAt);
+  // Zero repositories means "ForgeInstance-scoped Plan". One means the sole
+  // repository stays authoritative; several keep the explicit disambiguation
+  // error instead of silently creating an unscoped Plan.
+  if (enabled.length !== 0) return undefined;
+  return callRhWorkPlanCreateOperation(
+    { controllerHome: ctx.controllerHome, scopeKey: SEMANTIC_SCOPE_KEY },
+    operation,
+    args,
+    { controllerHome: ctx.controllerHome, checks: [] },
+  );
+}
+
+export async function callRhWorkPlanCreateOperation(
+  store: PlanContractStoreOptions,
+  operation: string,
+  args: Record<string, unknown>,
+  context: RhWorkPlanCreateContext,
+): Promise<CallToolResult | undefined> {
+  if (operation !== 'plan_create') return undefined;
+
+  if (!Array.isArray(args.plan_steps)) {
+    try {
+      const plan = createPlanSemanticContext(store, {
+        planId: String(args.plan_id ?? ''),
+        repoId: context.repoId,
+        requirementId: typeof args.requirement_id === 'string' && args.requirement_id.trim() ? args.requirement_id.trim() : undefined,
+        requirementBasisRevision: typeof args.requirement_revision === 'number' ? args.requirement_revision : undefined,
+        scopeKey: typeof args.scope_key === 'string' ? args.scope_key : undefined,
+        sourceBasisRevision: typeof args.source_revision === 'string' ? args.source_revision : undefined,
+        goal: String(args.objective ?? ''),
+        nonGoals: Array.isArray(args.non_goals) ? args.non_goals.map(String) : undefined,
+        assumptions: Array.isArray(args.assumptions) ? args.assumptions.map(String) : undefined,
+        resolvedDecisions: Array.isArray(args.resolved_decisions) ? args.resolved_decisions.map(String) : undefined,
+        stopConditions: Array.isArray(args.stop_conditions) ? args.stop_conditions.map(String) : undefined,
+        replanConditions: Array.isArray(args.replan_conditions) ? args.replan_conditions.map(String) : undefined,
+        integrationStrategy: typeof args.integration_strategy === 'string' ? args.integration_strategy : undefined,
+        items: Array.isArray(args.plan_items)
+          ? args.plan_items
+              .filter((entry): entry is Record<string, unknown> => Boolean(entry) && typeof entry === 'object' && !Array.isArray(entry))
+              .map((entry) => ({
+                id: String(entry.id ?? ''),
+                objective: String(entry.objective ?? ''),
+                dependencies: Array.isArray(entry.dependencies) ? entry.dependencies.map(String) : [],
+              }))
+          : [],
+      });
+      return result(buildFacadeResult({
+        summary: `Plan ${plan.planId} created at semantic revision 1. Plan items are descriptive working memory; no approval, PlanStep, path/check, scheduling, Work, or acceptance authority was created.`,
+        data: { plan: planSemanticView(plan), planContractCreated: true, executionStarted: false },
+      }) as unknown as Record<string, unknown>);
+    } catch (error) {
+      return result(buildFacadeResult({
+        status: 'blocked',
+        summary: error instanceof Error ? error.message : 'Semantic Plan creation failed.',
+        data: { planContractCreated: false, executionStarted: false },
+      }) as unknown as Record<string, unknown>, true);
+    }
+  }
+
+  try {
+    // Frozen-client compatibility only. Current model-facing schema no longer exposes plan_steps.
+    const rawSteps = args.plan_steps;
+    const requestedPlanId = String(args.plan_id ?? '').trim();
+    const requestedRequirementId = typeof args.requirement_id === 'string' && args.requirement_id.trim() ? args.requirement_id.trim() : undefined;
+    const requestedPlanRelation: 'extend' | 'parallel' | undefined = args.plan_relation === 'extend' || args.plan_relation === 'parallel'
+      ? args.plan_relation
+      : undefined;
+    const relatedPlanId = typeof args.related_plan_id === 'string' && args.related_plan_id.trim() ? args.related_plan_id.trim() : undefined;
+    if (requestedRequirementId && !readRequirement({ controllerHome: context.controllerHome }, requestedRequirementId)) {
+      const facade = buildFacadeResult({
+        status: 'failed',
+        summary: `PLAN_REQUIREMENT_NOT_FOUND: ${requestedRequirementId}. Plan was not persisted; create or reconcile the Requirement authority first.`,
+        data: { executionStarted: false, planContractCreated: false, admissionDecision: 'missing_requirement', requirementId: requestedRequirementId },
+      });
+      return result(facade as unknown as Record<string, unknown>, true);
+    }
+
+    const admissionInput = {
+      requirementId: requestedRequirementId,
+      scopeKey: String(args.scope_key ?? ''),
+      planRelation: requestedPlanRelation,
+      relatedPlanId,
+    };
+    const renderPlanAdmission = (admission: ReturnType<typeof resolvePlanAdmission>): CallToolResult | undefined => {
+      if (admission.admissionDecision === 'create_new') return undefined;
+      if (admission.reason === 'exact_scope_authority' && admission.plan) {
+        const exactDraftRepair = admission.plan.status === 'draft' && requestedPlanId === admission.plan.planId;
+        const facade = buildFacadeResult({
+          summary: exactDraftRepair
+            ? `PLAN_DRAFT_REPAIR_REQUIRED: draft Plan ${admission.plan.planId} already owns scope ${admission.normalizedScopeKey}; preserve that authority and amend it through rh_work repair.`
+            : `PLAN_AUTHORITY_REUSED: active Plan ${admission.plan.planId} already owns scope ${admission.normalizedScopeKey}; no duplicate draft was created.`,
+          data: {
+            plan: summarizePlanContract(admission.plan),
+            executionStarted: false,
+            planContractCreated: false,
+            admissionDecision: 'reuse_existing',
+            resolutionRequired: false,
+            ...(exactDraftRepair ? { repairRequired: true } : {}),
+          },
+          suggestedNextActions: exactDraftRepair
+            ? [{
+                label: 'Repair this exact draft Plan',
+                tool: 'rh_work',
+                operation: 'repair',
+                payload: {
+                  plan_id: admission.plan.planId,
+                  repair_operation: 'repair',
+                  dry_run: false,
+                  scope_key: args.scope_key,
+                  source_revision: args.source_revision,
+                  objective: args.objective,
+                  plan_steps: args.plan_steps,
+                  non_goals: args.non_goals,
+                  assumptions: args.assumptions,
+                  resolved_decisions: args.resolved_decisions,
+                  stop_conditions: args.stop_conditions,
+                  replan_conditions: args.replan_conditions,
+                  integration_strategy: args.integration_strategy,
+                },
+                risk: 'workspace_write',
+                confidence: 'high',
+              }]
+            : [{ label: 'Read active Plan', tool: 'rh_work', operation: 'plan_get', payload: { plan_id: admission.plan.planId }, risk: 'readonly', confidence: 'high' }],
+        });
+        return result(facade as unknown as Record<string, unknown>);
+      }
+      if (admission.reason === 'extension_target_required') {
+        const facade = buildFacadeResult({
+          summary: `PLAN_EXTENSION_TARGET_REQUIRED: select related_plan_id from the active Plan slices for Requirement ${requestedRequirementId}.`,
+          data: { executionStarted: false, planContractCreated: false, admissionDecision: 'resolution_required', resolutionRequired: true, candidates: admission.candidates.map(summarizePlanContract) },
+        });
+        return result(facade as unknown as Record<string, unknown>);
+      }
+      if (admission.reason === 'extend_existing' && admission.plan) {
+        // plan_create + plan_relation=extend revises the explicitly related stable
+        // Plan identity in place and advances its semantic head. Preflight continues
+        // into atomic admission; compatibility must not create a sibling revision Plan.
+        return undefined;
+      }
+      throw new Error(`PLAN_ADMISSION_RESULT_INVALID: ${admission.admissionDecision}:${admission.reason}`);
+    };
+
+    const plans = listPlanContracts({ ...store, status: 'all', limit: 100 });
+    const preflightAdmission = resolvePlanAdmission(plans, admissionInput);
+    const preflightResult = renderPlanAdmission(preflightAdmission);
+    if (preflightResult) return preflightResult;
+
+    const requestedPlanCheckIds = rawSteps
+      .filter((step): step is Record<string, unknown> => Boolean(step) && typeof step === 'object' && !Array.isArray(step))
+      .flatMap((step) => Array.isArray(step.check_ids) ? step.check_ids.map(String) : []);
+    const normalizedPlanChecks = normalizeCheckIds(requestedPlanCheckIds, context.checks);
+    if (normalizedPlanChecks.invalidCheckIds.length > 0) {
+      const facade = buildFacadeResult({
+        status: 'failed',
+        summary: `PLAN_CHECKS_INVALID: ${normalizedPlanChecks.invalidCheckIds.join(', ')}. Plan was not persisted; select replacement IDs from registeredCheckIds in this response, then request readiness only for the checks you choose.`,
+        data: {
+          executionStarted: false,
+          planContractCreated: false,
+          admissionDecision: 'invalid_checks',
+          normalizedChecks: normalizedPlanChecks,
+          registeredCheckIds: context.checks.map((check) => check.id).slice(0, 80),
+        },
+        suggestedNextActions: [],
+      });
+      return result(facade as unknown as Record<string, unknown>, true);
+    }
+
+    const admitted = await admitPlanContractAsync(store, {
+      planId: String(args.plan_id ?? ''),
+      repoId: context.repoId,
+      requirementId: requestedRequirementId,
+      scopeKey: String(args.scope_key ?? ''),
+      planRelation: requestedPlanRelation,
+      relatedPlanId,
+      sourceRevision: String(args.source_revision ?? ''),
+      goal: String(args.objective ?? ''),
+      nonGoals: Array.isArray(args.non_goals) ? args.non_goals.map(String) : undefined,
+      assumptions: Array.isArray(args.assumptions) ? args.assumptions.map(String) : undefined,
+      resolvedDecisions: Array.isArray(args.resolved_decisions) ? args.resolved_decisions.map(String) : undefined,
+      stopConditions: Array.isArray(args.stop_conditions) ? args.stop_conditions.map(String) : undefined,
+      replanConditions: Array.isArray(args.replan_conditions) ? args.replan_conditions.map(String) : undefined,
+      integrationStrategy: typeof args.integration_strategy === 'string' ? args.integration_strategy : undefined,
+      obligationDispositions: planObligationDispositionsFromArgs(args.obligation_dispositions),
+      steps: rawSteps.filter((step): step is Record<string, unknown> => Boolean(step) && typeof step === 'object' && !Array.isArray(step)).map((step) => ({
+        id: String(step.id ?? ''),
+        objective: String(step.objective ?? ''),
+        dependencies: Array.isArray(step.dependencies) ? step.dependencies.map(String) : [],
+        authoritativeFiles: Array.isArray(step.authoritative_files) ? step.authoritative_files.map(String) : [],
+        allowedPaths: Array.isArray(step.allowed_paths) ? step.allowed_paths.map(String) : [],
+        forbiddenPaths: Array.isArray(step.forbidden_paths) ? step.forbidden_paths.map(String) : [],
+        checks: Array.isArray(step.check_ids) ? step.check_ids.map(String) : [],
+        acceptanceCriteria: Array.isArray(step.acceptance_criteria) ? step.acceptance_criteria.map(String) : [],
+      })),
+    });
+    if (admitted.reason === 'extend_existing' && admitted.plan) {
+      const plan = admitted.plan;
+      const requestedLabel = requestedPlanId && requestedPlanId !== plan.planId
+        ? ` Requested compatibility plan_id ${requestedPlanId} was retained only as revision audit metadata.`
+        : '';
+      const facade = buildFacadeResult({
+        summary: `PLAN_REVISION_REUSED_AUTHORITY: Plan ${plan.planId} was revised in place; no successor PlanContract was created.${requestedLabel}`,
+        data: {
+          plan: summarizePlanContract(plan),
+          executionStarted: false,
+          planContractCreated: false,
+          admissionDecision: 'reuse_existing',
+          resolutionRequired: false,
+        },
+        // Plan approval is a retired ceremony no-op; the projection must not steer
+        // the model back into it. Reading the current revision is the honest action.
+        suggestedNextActions: [{ label: 'Read current Plan revision', tool: 'rh_work', operation: 'plan_get', payload: { plan_id: plan.planId }, risk: 'readonly', confidence: 'high' }],
+      });
+      return result(facade as unknown as Record<string, unknown>);
+    }
+    const racedAdmissionResult = renderPlanAdmission(admitted);
+    if (racedAdmissionResult) return racedAdmissionResult;
+    if (!admitted.plan) throw new Error('PLAN_ADMISSION_CREATE_MISSING_PLAN');
+    const plan = admitted.plan;
+    const facade = buildFacadeResult({
+      summary: `PlanContract ${plan.planId} created as draft after atomic authority admission; no execution was started.`,
+      data: { plan: summarizePlanContract(plan), executionStarted: false, planContractCreated: true, admissionDecision: 'create_new' },
+      suggestedNextActions: [{ label: 'Read current Plan revision', tool: 'rh_work', operation: 'plan_get', payload: { plan_id: plan.planId }, risk: 'readonly', confidence: 'high' }],
+    });
+    return result(facade as unknown as Record<string, unknown>);
+  } catch (error) {
+    const facade = buildFacadeResult({
+      status: 'blocked',
+      summary: error instanceof Error ? error.message : 'PlanContract operation failed.',
+      data: { operation, executionStarted: false },
+    });
+    return result(facade as unknown as Record<string, unknown>, true);
+  }
+}