@moretea-labs/forge 1.8.0 → 1.8.1

package/adapters/mcp/runtime-gateway/work-repair-adapter.ts

@@ -0,0 +1,308 @@
+import type { CallToolResult } from '../../../packages/protocols/mcp/tool-contract';
+import { getWorkContract, listWorkContracts } from '../../../packages/kernel/work/api/index';
+import type { MultiRepositoryMcpToolContext } from '../multi-repository';
+import { collectRuntimePerformanceDiagnostics } from '../../../src/runtime/diagnostics/performance';
+import { listControllerChecks } from '../../../src/cli/controller/check-runner';
+import { readForgeRuntimeStatus } from '../../../src/runtime/control-plane/runtime-status-client';
+import { buildWorkflowWatchdogReport } from '../../../src/runtime/watchdog/workflow-watchdog';
+import { applyRuntimeMaintenance, buildRuntimeMaintenanceStatus } from '../../../src/runtime/recovery';
+import {
+  buildFacadeResult,
+  getPlanContract,
+  normalizeCheckIds,
+  repairDraftPlanContractAsync,
+  runSelfHealingLoop,
+  summarizePlanContract,
+  summarizeWorkContract,
+} from '../../../src/runtime/control-plane/facade';
+import { result } from './result-adapter';
+import { selected } from './shared-adapter';
+import { controllerReadinessEvidence, repositoryRevisionContains } from './status-inbox-adapter';
+
+// Bounded rh_work repair transport orchestration. Canonical lifecycle/persistence authority remains in application services.
+export 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 async function runFacadeRepair(
+  ctx: MultiRepositoryMcpToolContext,
+  repository: ReturnType<typeof selected>,
+  args: Record<string, unknown>,
+): Promise<CallToolResult> {
+  const store = {
+    controllerHome: ctx.controllerHome,
+    repoId: repository.repoId,
+    revisionContains: (ancestorRevision: string, descendantRevision: string) =>
+      repositoryRevisionContains(repository.canonicalRoot, ancestorRevision, descendantRevision),
+  };
+  let maintenanceSnapshot: ReturnType<typeof buildRuntimeMaintenanceStatus> | undefined;
+  let maintenanceStatus: {
+    readyForExecution?: boolean;
+    recommendedActions?: string[];
+    candidates?: Array<{ kind?: string; reason?: string; suggestedAction?: string; safe?: boolean }>;
+    warnings?: string[];
+  } | undefined;
+  try {
+    const status = buildRuntimeMaintenanceStatus(repository, ctx.controllerHome, {
+      minAgeMinutes: typeof args.min_age_minutes === 'number' ? args.min_age_minutes : undefined,
+      maxCandidates: typeof args.max_candidates === 'number' ? args.max_candidates : 20,
+    });
+    maintenanceSnapshot = status;
+    maintenanceStatus = {
+      readyForExecution: status.readyForExecution,
+      recommendedActions: status.recommendedActions,
+      candidates: status.candidates.map((candidate) => ({
+        kind: candidate.kind,
+        reason: candidate.reason,
+        suggestedAction: candidate.suggestedAction,
+        safe: candidate.safe,
+      })),
+      warnings: status.warnings,
+    };
+  } catch {
+    maintenanceStatus = {
+      readyForExecution: false,
+      recommendedActions: [],
+      candidates: [],
+      warnings: ['runtime_maintenance_status inspection failed; treating as infrastructure issue, not acceptance failure'],
+    };
+  }
+
+  const repairOperation = args.repair_operation === 'repair' || args.repair_operation === 'verify' || args.repair_operation === 'handoff'
+    ? args.repair_operation
+    : 'diagnose';
+  const dryRun = args.dry_run === undefined ? true : args.dry_run === true;
+  const elevatedRepair = args.destructive === true || args.remote_write === true || args.remote_effect === true;
+  const planId = typeof args.plan_id === 'string' ? args.plan_id.trim() : '';
+  const planStepId = typeof args.plan_step_id === 'string' ? args.plan_step_id.trim() : '';
+  const exactWorkId = typeof args.work_id === 'string' ? args.work_id.trim() : '';
+
+  if (planId && !planStepId) {
+    const plan = getPlanContract(store, planId);
+    if (!plan) {
+      const facade = buildFacadeResult({ status: 'not_found', summary: `PlanContract ${planId} not found.`, data: { operation: repairOperation, dryRun, planId, repaired: false } });
+      return result(facade as unknown as Record<string, unknown>, true);
+    }
+    const pendingRevision = plan.status === 'replanning' ? plan.pendingRevision : undefined;
+    if (plan.status !== 'draft' && !pendingRevision) {
+      const facade = buildFacadeResult({ status: 'blocked', summary: `PLAN_DRAFT_REPAIR_STATUS_INVALID: ${plan.planId}:${plan.status}`, data: { operation: repairOperation, dryRun, planId, repaired: false } });
+      return result(facade as unknown as Record<string, unknown>, true);
+    }
+    const repairBase = pendingRevision ?? plan;
+    if (repairOperation !== 'repair' || dryRun) {
+      const facade = buildFacadeResult({
+        summary: pendingRevision
+          ? `PlanContract ${plan.planId} has staged revision r${pendingRevision.revision}. Exact in-place revision repair is available; stable Plan identity and committed revision remain authoritative until approval.`
+          : `PlanContract ${plan.planId} is a draft. Exact in-place repair is available; the Plan identity and Requirement authority are preserved and only a fully valid draft may be persisted.`,
+        data: { operation: repairOperation, dryRun, plan: summarizePlanContract(plan), repaired: false, repairRequired: true },
+        suggestedNextActions: [{ label: 'Repair this exact draft Plan', tool: 'rh_work', operation: 'repair', payload: { plan_id: plan.planId, repair_operation: 'repair', dry_run: false }, risk: 'workspace_write', confidence: 'high' }],
+      });
+      return result(facade as unknown as Record<string, unknown>);
+    }
+    const rawSteps = Array.isArray(args.plan_steps)
+      ? args.plan_steps
+      : repairBase.steps.map((step) => ({
+          id: step.id, objective: step.objective, dependencies: step.dependencies, authoritative_files: step.authoritativeFiles,
+          allowed_paths: step.allowedPaths, forbidden_paths: step.forbiddenPaths, check_ids: step.checks, acceptance_criteria: step.acceptanceCriteria,
+        }));
+    const 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) : [],
+      }));
+    const availableChecks = listControllerChecks(repository.canonicalRoot);
+    const normalizedPlanChecks = normalizeCheckIds(steps.flatMap((step) => step.checks), availableChecks);
+    if (normalizedPlanChecks.invalidCheckIds.length > 0) {
+      const facade = buildFacadeResult({
+        status: 'failed',
+        summary: `PLAN_CHECKS_INVALID: ${normalizedPlanChecks.invalidCheckIds.join(', ')}. Draft repair was not persisted.`,
+        data: { operation: repairOperation, dryRun: false, planId, repaired: false, normalizedChecks: normalizedPlanChecks, registeredCheckIds: availableChecks.map((check) => check.id).slice(0, 80) },
+        suggestedNextActions: [],
+      });
+      return result(facade as unknown as Record<string, unknown>, true);
+    }
+    try {
+      const repaired = await repairDraftPlanContractAsync(store, planId, {
+        expectedSourceRevision: repairBase.sourceRevision,
+        scopeKey: typeof args.scope_key === 'string' ? args.scope_key : plan.scopeKey,
+        sourceRevision: typeof args.source_revision === 'string' ? args.source_revision : repairBase.sourceRevision,
+        goal: typeof args.objective === 'string' ? args.objective : repairBase.goal,
+        nonGoals: Array.isArray(args.non_goals) ? args.non_goals.map(String) : repairBase.nonGoals,
+        assumptions: Array.isArray(args.assumptions) ? args.assumptions.map(String) : repairBase.assumptions,
+        resolvedDecisions: Array.isArray(args.resolved_decisions) ? args.resolved_decisions.map(String) : repairBase.resolvedDecisions,
+        stopConditions: Array.isArray(args.stop_conditions) ? args.stop_conditions.map(String) : repairBase.stopConditions,
+        replanConditions: Array.isArray(args.replan_conditions) ? args.replan_conditions.map(String) : repairBase.replanConditions,
+        integrationStrategy: typeof args.integration_strategy === 'string' ? args.integration_strategy : repairBase.integrationStrategy,
+        obligationDispositions: planObligationDispositionsFromArgs(args.obligation_dispositions) ?? repairBase.obligationDispositions,
+        steps,
+      });
+      const facade = buildFacadeResult({
+        summary: pendingRevision ? `PlanContract ${repaired.planId} staged revision repaired in place; stable Plan identity and committed authority were preserved.` : `PlanContract ${repaired.planId} draft repaired in place; identity and Requirement authority were preserved.`,
+        data: { operation: repairOperation, dryRun: false, plan: summarizePlanContract(repaired), repaired: true, replacementPlanCreated: false },
+        suggestedNextActions: [{ label: 'Read repaired Plan', tool: 'rh_work', operation: 'plan_get', payload: { plan_id: repaired.planId }, risk: 'readonly', confidence: 'medium' }],
+      });
+      return result(facade as unknown as Record<string, unknown>);
+    } catch (error) {
+      const facade = buildFacadeResult({ status: 'blocked', summary: error instanceof Error ? error.message : 'PLAN_DRAFT_REPAIR_FAILED', data: { operation: repairOperation, dryRun: false, planId, repaired: false } });
+      return result(facade as unknown as Record<string, unknown>, true);
+    }
+  }
+
+  if (planStepId && !planId) {
+    const facade = buildFacadeResult({ status: 'blocked', summary: 'PLAN_STEP_REPAIR_CONTEXT_REQUIRED: plan_id and plan_step_id are both required.', data: { operation: repairOperation, dryRun, repaired: false } });
+    return result(facade as unknown as Record<string, unknown>, true);
+  }
+
+  if (planId && planStepId) {
+    // Plan items are authored working memory. Repair reports the observable
+    // relationship as a read-only fact and never clears a binding, replans a
+    // scope or decides replacement admission on the Plan's behalf.
+    const plan = getPlanContract(store, planId);
+    const step = plan?.steps.find((candidate) => candidate.id === planStepId);
+    if (!plan || !step) {
+      const facade = buildFacadeResult({ status: 'not_found', summary: !plan ? `PlanContract ${planId} not found.` : `PLAN_STEP_NOT_FOUND: ${planStepId}`, data: { operation: repairOperation, dryRun, planId, planStepId, repaired: false } });
+      return result(facade as unknown as Record<string, unknown>, true);
+    }
+    const boundWork = step.workId ? getWorkContract(store, step.workId) : undefined;
+    const facade = buildFacadeResult({
+      summary: `PLAN_STEP_AUTHORED_FACT: ${planId}/${planStepId} is ${step.status}${boundWork ? ` and records terminal-or-active Work ${boundWork.workId} (${boundWork.semanticState})` : ''}. Repair does not mutate model-authored Plan progress; revise the stable Plan explicitly with expected_revision when this fact should change it.`,
+      data: {
+        operation: repairOperation,
+        dryRun,
+        planId,
+        planStepId,
+        planItemStatus: step.status,
+        recordedWorkId: step.workId ?? null,
+        ...(boundWork ? { workState: boundWork.semanticState } : {}),
+        repaired: false,
+        repairRequired: false,
+        compatibilityNoop: true,
+      },
+      suggestedNextActions: [{ label: 'Read current Plan', tool: 'rh_work', operation: 'plan_get', payload: { plan_id: planId }, risk: 'readonly', confidence: 'high' }],
+    });
+    return result(facade as unknown as Record<string, unknown>);
+  }
+
+
+  // The self-healing facade is a policy/planning surface; the authoritative
+  // maintenance executor owns mutations. Execute it here only for an explicit,
+  // non-dry-run repair whose entire observed candidate set is already classified
+  // safe. Unsafe/destructive/remote repair continues through the approval path.
+  if (
+    repairOperation === 'repair'
+    && !dryRun
+    && !elevatedRepair
+    && !exactWorkId
+    && maintenanceSnapshot
+    && maintenanceSnapshot.candidates.length > 0
+  ) {
+    const applied = applyRuntimeMaintenance(repository, ctx.controllerHome, {
+      actionId: 'full_maintenance_pass',
+      confirmMaintenance: true,
+      minAgeMinutes: typeof args.min_age_minutes === 'number' ? args.min_age_minutes : undefined,
+      maxCandidates: typeof args.max_candidates === 'number' ? args.max_candidates : 20,
+    });
+    const actions = applied.applied.slice(0, 20).map((entry) => ({
+      kind: entry.kind,
+      id: entry.id,
+      applied: entry.applied,
+      result: entry.result,
+      ...(entry.error ? { error: entry.error.slice(0, 300) } : {}),
+    }));
+    const appliedCount = applied.applied.filter((entry) => entry.applied).length;
+    // Protected stale runtime temp entries are intentionally non-blocking maintenance
+    // diagnostics. Keep repair completion semantics aligned with rh_status readiness so
+    // their presence does not falsely report a blocked repair after safe debt is cleared.
+    const remainingCandidateCount = applied.candidates.filter((candidate) => candidate.kind !== 'stale_runtime_temp_entry').length;
+    const blocked = remainingCandidateCount > 0;
+    const facade = buildFacadeResult({
+      status: blocked ? 'blocked' : 'ok',
+      summary: blocked
+        ? `Runtime maintenance applied ${appliedCount} candidate(s); ${remainingCandidateCount} candidate(s) remain after the authoritative executor pass.`
+        : `Runtime maintenance applied ${appliedCount} candidate(s); no maintenance candidates remain.`,
+      data: {
+        operation: 'repair',
+        dryRun: false,
+        applied: appliedCount > 0,
+        actionId: 'full_maintenance_pass',
+        appliedCount,
+        remainingCandidateCount,
+        actions,
+        classification: 'infrastructure_recovery',
+        isAcceptanceFailure: false,
+      },
+      warnings: applied.warnings.slice(0, 5),
+      suggestedNextActions: [{
+        label: 'Verify controller status after repair',
+        tool: 'rh_status',
+        operation: 'get',
+        risk: 'readonly',
+        confidence: 'high',
+      }],
+      rawAvailable: false,
+    });
+    return result(facade as unknown as Record<string, unknown>, blocked);
+  }
+
+  let watchdogSummary: string | undefined;
+  let performanceSummary: string | undefined;
+  try {
+    const watchdog = buildWorkflowWatchdogReport(ctx.controllerHome, repository, { includeProcesses: false });
+    watchdogSummary = `status=${watchdog.status}; findings=${watchdog.findings.length}; stale=${watchdog.staleWork.length}`.slice(0, 240);
+  } catch {
+    watchdogSummary = undefined;
+  }
+  try {
+    const perf = collectRuntimePerformanceDiagnostics({
+      repoId: repository.repoId,
+      repoRoot: repository.canonicalRoot,
+      includeProcesses: false,
+      includeTempDirs: false,
+    });
+    performanceSummary = perf.summary.slice(0, 240);
+  } catch {
+    performanceSummary = undefined;
+  }
+
+  const daemon = readForgeRuntimeStatus(ctx.controllerHome);
+  const readiness = await controllerReadinessEvidence(ctx, repository);
+  const facade = runSelfHealingLoop(
+    { repoId: repository.repoId, handoffStore: store },
+    {
+      operation: repairOperation,
+      dryRun,
+      approvalConfirmed: args.approval_confirmed === true,
+      workId: typeof args.work_id === 'string' ? args.work_id : undefined,
+      chatgptPullFailed: args.chatgpt_pull_failed === true,
+      destructive: args.destructive === true,
+      remoteEffect: args.remote_write === true || args.remote_effect === true,
+      maintenanceStatus,
+      diagnostics: {
+        watchdogSummary,
+        performanceSummary,
+        controllerDaemonUnhealthy: daemon.status !== 'ready',
+        schedulerUnhealthy: readiness.durableScheduler.status !== 'ready',
+        codexUnavailable: args.codex_available === false,
+        grokUnavailable: args.grok_available === false || args.target === 'grok',
+        pluginUnavailable: args.plugin_unavailable === true,
+      },
+    },
+  );
+  return result(facade as unknown as Record<string, unknown>, facade.status === 'blocked' || facade.status === 'approval_required' || facade.status === 'failed');
+}

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

@@ -0,0 +1,148 @@
+import type { CallToolResult } from '../../../packages/protocols/mcp/tool-contract';
+import type { MultiRepositoryMcpToolContext } from '../multi-repository';
+import { admitRequirement, promoteRequirementCandidate } from '../../../src/runtime/control-plane/facade/requirement-authority';
+import { listRequirementRevisionRecords, readRequirement, requirementSemanticView, reviseRequirementSemantic } from '../../../src/runtime/control-plane/persistence/requirement-store';
+import { readForgeInstanceIdentity } from '../../../packages/kernel/identity/api/index';
+import { resolveProjectForRepositoryPlacement } from '../../../src/runtime/control-plane/workspace/workspace-store';
+import { buildFacadeResult } from '../../../src/runtime/control-plane/facade';
+import { result } from './result-adapter';
+
+const RH_WORK_REQUIREMENT_OPERATIONS = new Set([
+  'requirement_create',
+  'requirement_get',
+  'requirement_revise',
+  'requirement_promote_candidate',
+]);
+
+export function isRhWorkRequirementOperation(operation: string): boolean {
+  return RH_WORK_REQUIREMENT_OPERATIONS.has(operation);
+}
+
+export async function callRhWorkRequirementOperation(
+  ctx: MultiRepositoryMcpToolContext,
+  repository: { repoId: string; activeCheckoutId?: string } | undefined,
+  operation: string,
+  args: Record<string, unknown>,
+): Promise<CallToolResult | undefined> {
+  if (!isRhWorkRequirementOperation(operation)) return undefined;
+
+  if (operation === 'requirement_get') {
+    const requirementId = typeof args.requirement_id === 'string' ? args.requirement_id.trim() : '';
+    const record = requirementId ? readRequirement({ controllerHome: ctx.controllerHome }, requirementId) : undefined;
+    if (!record) return result(buildFacadeResult({
+      status: 'not_found', summary: `Requirement ${requirementId || '(missing)'} not found.`, data: { requirementId },
+    }) as unknown as Record<string, unknown>, true);
+    const semantic = requirementSemanticView(record.value);
+    return result(buildFacadeResult({
+      summary: `Requirement ${semantic.requirementId} retrieved at semantic revision ${semantic.revision}.`,
+      data: {
+        requirement: semantic,
+        ...(args.detail_level === 'detail' ? { revisionHistory: listRequirementRevisionRecords({ controllerHome: ctx.controllerHome }, semantic.requirementId, 100) } : {}),
+      },
+      detailLevel: args.detail_level === 'detail' ? 'detail' : 'summary',
+    }) as unknown as Record<string, unknown>);
+  }
+
+  if (operation === 'requirement_revise') {
+    const requirementId = typeof args.requirement_id === 'string' ? args.requirement_id.trim() : '';
+    const expectedRevision = Number(args.expected_revision);
+    try {
+      const revised = reviseRequirementSemantic({ controllerHome: ctx.controllerHome }, requirementId, {
+        expectedRevision,
+        ...(typeof args.requirement_title === 'string' ? { title: args.requirement_title } : {}),
+        ...(typeof args.requirement_outcome === 'string' ? { outcomeStatement: args.requirement_outcome } : {}),
+        ...(Array.isArray(args.requirement_acceptance_criteria) ? { acceptanceCriteria: args.requirement_acceptance_criteria.map(String) } : {}),
+        ...(Array.isArray(args.requirement_delivery_references) ? { requiredDeliveryReferences: args.requirement_delivery_references.map(String) } : {}),
+        ...(args.requirement_state === 'open' || args.requirement_state === 'completed' || args.requirement_state === 'cancelled' ? { state: args.requirement_state } : {}),
+      });
+      const semantic = requirementSemanticView(revised);
+      return result(buildFacadeResult({
+        summary: `Requirement ${semantic.requirementId} revised atomically to semantic revision ${semantic.revision}.`,
+        data: { requirement: semantic, expectedRevision, semanticRevision: semantic.revision },
+      }) as unknown as Record<string, unknown>);
+    } catch (error) {
+      const current = requirementId ? readRequirement({ controllerHome: ctx.controllerHome }, requirementId)?.value : undefined;
+      return result(buildFacadeResult({
+        status: 'blocked', summary: error instanceof Error ? error.message : String(error),
+        data: { requirementId, expectedRevision, ...(current ? { currentRequirement: requirementSemanticView(current) } : {}) },
+      }) as unknown as Record<string, unknown>, true);
+    }
+  }
+
+  const requirementId = typeof args.requirement_id === 'string' ? args.requirement_id : '';
+  const title = typeof args.requirement_title === 'string' ? args.requirement_title : '';
+  const outcomeStatement = typeof args.requirement_outcome === 'string' ? args.requirement_outcome : '';
+  if (!requirementId.trim() || !title.trim() || !outcomeStatement.trim()) {
+    return result(buildFacadeResult({
+      status: 'blocked',
+      summary: 'REQUIREMENT_CREATE_INPUT_REQUIRED: requirement_id, requirement_title, and requirement_outcome are required.',
+      data: { requirementCreated: false },
+    }) as unknown as Record<string, unknown>, true);
+  }
+  try {
+    const requirementInput = {
+      requirementId,
+      title,
+      outcomeStatement,
+      acceptanceCriteria: Array.isArray(args.requirement_acceptance_criteria) ? args.requirement_acceptance_criteria.map(String) : [],
+      requiredDeliveryReferences: Array.isArray(args.requirement_delivery_references) ? args.requirement_delivery_references.map(String) : [],
+      legacyAliases: Array.isArray(args.requirement_legacy_aliases) ? args.requirement_legacy_aliases.map(String) : [],
+    };
+    const admission = operation === 'requirement_promote_candidate'
+      ? (() => {
+          if (!repository) throw new Error('REQUIREMENT_CANDIDATE_REPOSITORY_PLACEMENT_REQUIRED');
+          const candidateMemoryId = typeof args.requirement_candidate_id === 'string' ? args.requirement_candidate_id.trim() : '';
+          if (!candidateMemoryId) throw new Error('REQUIREMENT_CANDIDATE_ID_REQUIRED');
+          const instance = readForgeInstanceIdentity(ctx.controllerHome);
+          if (!instance) throw new Error('REQUIREMENT_CANDIDATE_FORGE_INSTANCE_REQUIRED');
+          const project = resolveProjectForRepositoryPlacement({
+            controllerHome: ctx.controllerHome,
+            forgeInstanceId: instance.instanceId,
+            repositoryId: repository.repoId,
+            checkoutId: repository.activeCheckoutId,
+          });
+          if (!project) throw new Error('REQUIREMENT_CANDIDATE_PROJECT_BINDING_REQUIRED');
+          return promoteRequirementCandidate({ controllerHome: ctx.controllerHome }, {
+            ...requirementInput,
+            workspaceId: project.workspaceId,
+            candidateMemoryId,
+          });
+        })()
+      : admitRequirement({ controllerHome: ctx.controllerHome }, requirementInput);
+    if (admission.decision === 'existing_conflict') {
+      return result(buildFacadeResult({
+        status: 'blocked',
+        summary: `REQUIREMENT_ALREADY_EXISTS_CONFLICT: ${admission.requirement.requirementId}. Existing Requirement authority was not changed.`,
+        data: { requirement: requirementSemanticView(admission.requirement), requirementCreated: false, admissionDecision: admission.decision },
+        suggestedNextActions: [],
+      }) as unknown as Record<string, unknown>, true);
+    }
+    return result(buildFacadeResult({
+      summary: admission.decision === 'created'
+        ? operation === 'requirement_promote_candidate'
+          ? `Requirement ${admission.requirement.requirementId} created from an explicit Cognitive candidate promotion. Requirement authority does not imply a Plan; Controller chooses the next action.`
+          : `Requirement ${admission.requirement.requirementId} created. Requirement authority does not imply a Plan; Controller chooses the next action.`
+        : admission.decision === 'candidate_already_promoted'
+          ? `REQUIREMENT_CANDIDATE_ALREADY_PROMOTED: ${admission.requirement.requirementId}. Existing Requirement authority was reused; no duplicate Requirement was created.`
+          : `REQUIREMENT_AUTHORITY_REUSED: ${admission.requirement.requirementId}. Requirement authority does not imply a Plan; Controller chooses the next action.`,
+      data: {
+        requirement: requirementSemanticView(admission.requirement),
+        requirementCreated: admission.created,
+        admissionDecision: admission.decision,
+        ...('candidateAuditRef' in admission ? {
+          requirementCandidatePromoted: true,
+          candidateAuditRef: admission.candidateAuditRef,
+          candidateMemoryId: admission.candidateMemoryId,
+          workspaceId: admission.workspaceId,
+        } : {}),
+      },
+      suggestedNextActions: [],
+    }) as unknown as Record<string, unknown>);
+  } catch (error) {
+    return result(buildFacadeResult({
+      status: 'blocked',
+      summary: error instanceof Error ? error.message : String(error),
+      data: { requirementCreated: false },
+    }) as unknown as Record<string, unknown>, true);
+  }
+}