@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-control-plane-planning-command.mjs

@@ -0,0 +1,563 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { createRuntimeControlPlanePlanningInput } from './runtime-control-plane-planning-input.mjs';
+import { createRuntimeControlPlanePlanningListing } from './runtime-control-plane-planning-listing.mjs';
+import { createRuntimeControlPlanePlanningPresentation } from './runtime-control-plane-planning-presentation.mjs';
+import { createRuntimeControlPlanePlanningValidation } from './runtime-control-plane-planning-validation.mjs';
+import { createRuntimeControlPlanePlannerArtifacts } from './runtime-control-plane-planner-artifacts.mjs';
+import { createRuntimeControlPlaneRoutingArtifacts } from './runtime-control-plane-routing-artifacts.mjs';
+import { createRuntimeControlPlaneRouterPlanningModel } from './runtime-control-plane-router-planning-model.mjs';
+import { plannerAllowedWorkflows, plannerRouteDecision } from './runtime-planner-route-model.mjs';
+
+const runtimePlanningContractSyncSurface = 'runtime-cli-usage runtime-cli-args runtime-cli-dispatch tools/vibe-release-check';
+
+export function createRuntimeControlPlanePlanningCommands(deps) {
+  if (!runtimePlanningContractSyncSurface.includes('runtime-cli-usage')) throw new Error('runtime planning contract sync marker missing');
+  const {
+    jsonSchemaVersion,
+    stateDirectoryName,
+    plannerRoutesDirectoryName,
+    plannerPlansDirectoryName,
+    plannerBriefsDirectoryName,
+    routerPlansDirectoryName,
+    routerApprovalsDirectoryName,
+    orchestratorPlansDirectoryName,
+    orchestratorDispatchPlansDirectoryName,
+    evalSuitesDirectoryName,
+    evalRunsDirectoryName,
+    evalReportsDirectoryName,
+    releaseGatesDirectoryName,
+    releaseNotesDirectoryName,
+    feedbackLedgersDirectoryName,
+    hookIntentsDirectoryName,
+    runtimeTracesDirectoryName,
+    governanceDirectoryName,
+    methodologyGatesDirectoryName,
+    orchestratorDispatchTargetForTask,
+    subagentEligibilityBridgeGateResults,
+    subagentEligibilityGateIds,
+    subagentEligibilityRequiredEvidence,
+  } = deps;
+  function runtimeAutomationReadinessEnvelope(root) {
+    return runtimeAutomationReadinessCommandEnvelope(root, { digestObject });
+  }
+  const {
+    ensureRoot,
+    localJsonFileWithinRoot,
+    stateDirectory,
+    workflowPath,
+    readWorkflow,
+    workflowSummary,
+    listStateFiles,
+    latestStateFile,
+    fileDigest,
+    readJsonArtifact,
+    digestObject,
+    validateCommonArtifactSafety,
+    runtimeTraceGroup,
+    validateRuntimePolicyCatalogDigest,
+    runtimePolicyCatalogDigest,
+    platformCapabilityCatalog,
+    governanceConvergenceEnvelope,
+    workflowLoopContractEnvelope,
+    runtimeAutomationReadinessCommandEnvelope,
+    runtimeCapabilityRegistry,
+    runtimePlanActionManifest,
+    runtimePlanActionManifestDigestPayload,
+    digestPlanActionManifest,
+    runtimeExecutablePlanContract,
+    runtimeExecutablePlanContractDigestPayload,
+    digestExecutablePlanContract,
+    runtimeSelfTestGateProfile,
+    runtimeSelfTestGateProfileDigestPayload,
+    digestSelfTestGateProfile,
+    runtimeCommitReadinessEnvelope,
+    runtimeCommitReadinessDigestPayload,
+    digestCommitReadiness,
+    runtimeStagedCommitReadiness,
+    runtimeStagedCommitReadinessDigestPayload,
+    digestStagedCommitReadiness,
+    runtimeEvidenceIntakeEnvelope,
+    runtimeEvidenceIntakeDigestPayload,
+    digestEvidenceIntake,
+    runtimeExecutionEvidenceBinder,
+    runtimeExecutionEvidenceDigestPayload,
+    digestExecutionEvidenceBinding,
+    runtimeTddTraceContract,
+    runtimeTddTraceDigestPayload,
+    digestTddTraceContract,
+    buildVerificationDrivenRepairLoopPlan,
+    printVerificationDrivenRepairLoopPlan,
+    runtimeReviewIntakeEnvelope,
+    runtimeReviewIntakeDigestPayload,
+    runtimeReviewResolutionEnvelope,
+    runtimeReviewResolutionDigestPayload,
+    digestReviewEnvelope,
+    runtimeDiffCoverageEnvelope,
+    runtimeDiffCoverageDigestPayload,
+    digestDiffCoverage,
+    validateHookIntentArtifact,
+    hookIntentFilePath,
+    plannerRouteFilePath,
+    plannerPlanFilePath,
+    plannerBriefsFilePath,
+    routerPlanFilePath,
+    routerApprovalFilePath,
+    orchestratorPlanFilePath,
+    orchestratorDispatchPlanFilePath,
+    evalSuiteFilePath,
+    evalRunFilePath,
+    evalReportFilePath,
+    releaseGateFilePath,
+    releaseNotesFilePath,
+    feedbackLedgerFilePath,
+    plannerRouteSnapshotPath, plannerPlanSnapshotPath, plannerBriefsSnapshotPath, routerPlanSnapshotPath, routerApprovalSnapshotPath, orchestratorPlanSnapshotPath, orchestratorDispatchPlanSnapshotPath, evalSuiteSnapshotPath, evalRunSnapshotPath, evalReportSnapshotPath, releaseGateSnapshotPath, releaseNotesSnapshotPath, feedbackLedgerSnapshotPath,
+    plannerRoutesDirectory,
+    plannerPlansDirectory,
+    plannerBriefsDirectory,
+    routerPlansDirectory,
+    routerApprovalsDirectory,
+    orchestratorPlansDirectory,
+    orchestratorDispatchPlansDirectory,
+    evalSuitesDirectory,
+    evalRunsDirectory,
+    evalReportsDirectory,
+    releaseGatesDirectory,
+    releaseNotesDirectory,
+    feedbackLedgersDirectory,
+    runtimeTracesDirectory,
+    governanceDirectory,
+    methodologyGatesDirectory,
+    writeStateArtifact,
+    writeJsonEnvelope,
+    printList,
+    runtimeBehavioralEvaluationContract,
+    runtimeSuperpowersStyleEvalPack,
+    runtimeSuperpowersStyleEvalPackDigestPayload,
+    digestSuperpowersStyleEvalPack,
+    commitGuardEnvelope,
+  } = deps;
+  function createPlanningPresentationOwner() {
+    return createRuntimeControlPlanePlanningPresentation({ printList });
+  }
+
+  const {
+    printPlanLint,
+    printPlanActionManifest,
+    printExecutablePlanContract,
+    printSelfTestGateProfile,
+    printCommitReadiness,
+    printStagedCommitReadiness,
+    printEvidenceIntake,
+    printExecutionEvidenceBinding,
+    printTddTraceContract,
+    printPlanner,
+    printRouter,
+    printOrchestrator,
+  } = createPlanningPresentationOwner();
+
+  function createPlanningListingOwner() {
+    return createRuntimeControlPlanePlanningListing({
+    listStateFiles,
+    plannerRoutesDirectory,
+    plannerPlansDirectory,
+    plannerBriefsDirectory,
+    routerPlansDirectory,
+    routerApprovalsDirectory,
+    orchestratorPlansDirectory,
+    orchestratorDispatchPlansDirectory,
+  });
+  }
+
+  const {
+    listPlannerRouteFiles,
+    listPlannerPlanFiles,
+    listPlannerBriefsFiles,
+    listRouterPlanFiles,
+    listRouterApprovalFiles,
+    listOrchestratorPlanFiles,
+    listOrchestratorDispatchPlanFiles,
+  } = createPlanningListingOwner();
+  function createPlanningInputOwner() {
+    return createRuntimeControlPlanePlanningInput({
+    artifactRootName: stateDirectoryName,
+    hookIntentFolderName: hookIntentsDirectoryName,
+    traceFolderName: runtimeTracesDirectoryName,
+    governanceFolderName: governanceDirectoryName,
+    methodologyGateFolderName: methodologyGatesDirectoryName,
+    traceFolder: runtimeTracesDirectory,
+    governanceFolder: governanceDirectory,
+    methodologyGateFolder: methodologyGatesDirectory,
+    hookIntentFilePath,
+    validateHookIntentArtifact,
+    readWorkflow,
+    workflowSummary,
+    readJsonArtifact,
+    latestArtifactFile: latestStateFile,
+    fileDigest,
+  });
+  }
+
+  const {
+    plannerReadInput,
+    plannerEvidenceRefs,
+    localTextEvidenceDescriptor,
+  } = createPlanningInputOwner();
+
+  const {
+    routerAgentProfileForBriefKind,
+    routerPlatformOrderForBriefKind,
+    routerRankingsForBriefItem,
+    routerFallbackRoutesForBriefItem,
+    routerConcurrencyBudget,
+    orchestratorBuildPlanFromRouterPlan,
+  } = createRuntimeControlPlaneRouterPlanningModel({ platformCapabilityCatalog });
+
+  function createPlanningValidationOwner() {
+    return createRuntimeControlPlanePlanningValidation({
+    ensureRoot,
+    workflowPath,
+    stateDirectory,
+    localTextEvidenceDescriptor,
+    digestObject,
+    writeJsonEnvelope,
+    runtimeAutomationReadinessEnvelope,
+    workflowLoopContractEnvelope,
+    runtimeCapabilityRegistry,
+    runtimePlanActionManifest,
+    runtimePlanActionManifestDigestPayload,
+    digestPlanActionManifest,
+    runtimeExecutablePlanContract,
+    runtimeExecutablePlanContractDigestPayload,
+    digestExecutablePlanContract,
+    runtimeSelfTestGateProfile,
+    runtimeSelfTestGateProfileDigestPayload,
+    digestSelfTestGateProfile,
+    runtimeCommitReadinessEnvelope,
+    runtimeCommitReadinessDigestPayload,
+    digestCommitReadiness,
+    runtimeStagedCommitReadiness,
+    runtimeStagedCommitReadinessDigestPayload,
+    digestStagedCommitReadiness,
+    runtimeEvidenceIntakeEnvelope,
+    runtimeEvidenceIntakeDigestPayload,
+    digestEvidenceIntake,
+    runtimeExecutionEvidenceBinder,
+    runtimeExecutionEvidenceDigestPayload,
+    digestExecutionEvidenceBinding,
+    runtimeTddTraceContract,
+    runtimeTddTraceDigestPayload,
+    digestTddTraceContract,
+    buildVerificationDrivenRepairLoopPlan,
+    printVerificationDrivenRepairLoopPlan,
+    commitGuardEnvelope,
+    printPlanLint,
+    printPlanActionManifest,
+    printExecutablePlanContract,
+    printSelfTestGateProfile,
+    printEvidenceIntake,
+    printExecutionEvidenceBinding,
+    printTddTraceContract,
+  });
+  }
+
+  const {
+    planLintEnvelope,
+    planActionManifestEnvelope,
+    executablePlanContractEnvelope,
+    selfTestGateProfileEnvelope,
+    commitReadinessEnvelope,
+    stagedCommitReadinessEnvelope,
+    evidenceIntakeEnvelope,
+    tddTraceEnvelope,
+    runVerification,
+  } = createPlanningValidationOwner();
+
+  function createPlannerArtifactOwner() {
+    return createRuntimeControlPlanePlannerArtifacts({
+      fs,
+      path,
+      ensureRoot,
+      workflowPath,
+      plannerReadInput,
+      plannerRouteDecision,
+      plannerEvidenceRefs,
+      runtimePolicyCatalogDigest,
+      validateRuntimePolicyCatalogDigest,
+      plannerRouteSnapshotPath,
+      plannerPlanSnapshotPath,
+      plannerBriefsSnapshotPath,
+      plannerRouteFilePath,
+      plannerPlanFilePath,
+      plannerBriefsFilePath,
+      listPlannerRouteFiles,
+      listPlannerPlanFiles,
+      listPlannerBriefsFiles,
+      stateDirectoryName,
+      plannerRoutesDirectoryName,
+      plannerPlansDirectoryName,
+      plannerBriefsDirectoryName,
+      jsonSchemaVersion,
+      readJsonArtifact,
+      fileDigest,
+      digestObject,
+      validateCommonArtifactSafety,
+      writeStateArtifact,
+    });
+  }
+
+  const {
+    plannerSafety,
+    plannerRouteEnvelope,
+    plannerDecomposeTasks,
+    plannerPlanEnvelope,
+    plannerBriefKindsForTask,
+    plannerBriefsEnvelope,
+    validatePlannerArtifact,
+    writePlannerArtifact,
+    plannerAuditEnvelope,
+  } = createPlannerArtifactOwner();
+
+function runPlannerReadOnlyMode(options) {
+  if (options.plannerExecutablePlan) {
+    if (options.confirm || options.write || options.dryRun || options.recoveryPreview || options.hooksPreview || options.dispatch || options.dispatchIntent || options.run || options.autoRun || options.scan || options.once || options.preflight) throw new Error('planner --executable-plan is read-only and does not accept execution, dispatch, preview, confirm, write, scan, or preflight flags');
+    if (!options.fromFile) throw new Error('planner --executable-plan requires --from-file <local-plan-file>');
+    if (options.plannerFile || options.plannerFromHook || options.methodologyKind || options.methodologyIntent || options.fromReadiness || options.learningObservationFiles.length > 0 || options.learningInstinctFile || options.tokenCompactionFiles.length > 0) throw new Error('planner --executable-plan does not accept workflow artifact, evidence sidecar, methodology gate, intent, or audit input files');
+    const envelope = executablePlanContractEnvelope(options.root, options.fromFile);
+    if (options.json) writeJsonEnvelope('planner', envelope);
+    else printExecutablePlanContract(envelope);
+    return true;
+  }
+  if (options.plannerActionManifest) {
+    if (options.confirm || options.write || options.dryRun || options.recoveryPreview || options.hooksPreview || options.dispatch || options.dispatchIntent || options.run || options.autoRun || options.scan || options.once || options.preflight) throw new Error('planner --action-manifest is read-only and does not accept execution, dispatch, preview, confirm, write, scan, or preflight flags');
+    if (!options.fromFile) throw new Error('planner --action-manifest requires --from-file <local-plan-file>');
+    if (options.plannerFile || options.plannerFromHook || options.methodologyKind || options.fromReadiness || options.learningObservationFiles.length > 0 || options.learningInstinctFile || options.tokenCompactionFiles.length > 0) throw new Error('planner --action-manifest does not accept workflow artifact, evidence sidecar, methodology gate, or audit input files');
+    const envelope = planActionManifestEnvelope(options.root, options.fromFile, { intent: options.methodologyIntent || 'implementation' });
+    if (options.json) writeJsonEnvelope('planner', envelope);
+    else printPlanActionManifest(envelope);
+    return true;
+  }
+  if (options.plannerLint) {
+    if (options.confirm || options.write || options.dryRun || options.recoveryPreview || options.hooksPreview || options.dispatch || options.dispatchIntent || options.run || options.autoRun || options.scan || options.once || options.preflight) throw new Error('planner --lint is read-only and does not accept execution, dispatch, preview, confirm, write, scan, or preflight flags');
+    if (!options.fromFile) throw new Error('planner --lint requires --from-file <local-plan-file>');
+    if (options.plannerFile || options.plannerFromHook || options.methodologyIntent || options.methodologyKind || options.fromReadiness || options.learningObservationFiles.length > 0 || options.learningInstinctFile || options.tokenCompactionFiles.length > 0) throw new Error('planner --lint does not accept workflow artifact, evidence sidecar, or methodology inputs');
+    const envelope = planLintEnvelope(options.root, options.fromFile);
+    if (options.json) writeJsonEnvelope('planner', envelope);
+    else printPlanLint(envelope);
+    return true;
+  }
+  return false;
+}
+
+function emitPlannerArtifactOutput(options, envelope, artifactFieldName) {
+  if (options.confirm) {
+    const file = writePlannerArtifact(options.root, envelope);
+    if (options.json) writeJsonEnvelope('planner', { ...envelope, [artifactFieldName]: path.basename(file) });
+    else printPlanner(envelope, file);
+    return;
+  }
+  if (options.json) writeJsonEnvelope('planner', envelope);
+  else printPlanner(envelope);
+}
+
+function runPlannerArtifactMode(options) {
+  if (options.plannerRoute) {
+    const routeFile = options.confirm ? path.basename(plannerRouteSnapshotPath(options.root)) : '';
+    const envelope = plannerRouteEnvelope(options.root, options, { persist: options.confirm, artifactFile: routeFile });
+    emitPlannerArtifactOutput(options, envelope, 'planner_route_file');
+    return true;
+  }
+  if (options.plannerDecompose) {
+    if (!options.plannerFile) throw new Error('planner --decompose requires --from-route <planner-route-file>');
+    const envelope = plannerPlanEnvelope(options.root, options.plannerFile, { persist: options.confirm, artifactFile: options.confirm ? path.basename(plannerPlanSnapshotPath(options.root)) : '' });
+    emitPlannerArtifactOutput(options, envelope, 'planner_plan_file');
+    return true;
+  }
+  if (options.plannerBriefs) {
+    if (!options.plannerFile) throw new Error('planner --briefs requires --from-plan <planner-plan-file>');
+    const envelope = plannerBriefsEnvelope(options.root, options.plannerFile, { persist: options.confirm, artifactFile: options.confirm ? path.basename(plannerBriefsSnapshotPath(options.root)) : '' });
+    emitPlannerArtifactOutput(options, envelope, 'planner_briefs_file');
+    return true;
+  }
+  return false;
+}
+
+function runPlannerAuditMode(options) {
+  if (options.confirm) throw new Error('planner audit does not support --confirm');
+  const mode = options.plannerList ? 'list' : options.plannerVerify ? 'verify' : 'show';
+  if (mode !== 'list' && !options.plannerFile) throw new Error(`planner --${mode} requires a planner artifact file`);
+  const envelope = plannerAuditEnvelope(options.root, mode, options.plannerFile);
+  if (options.json) writeJsonEnvelope('planner', envelope);
+  else printPlanner(envelope);
+}
+
+function runPlanner(options) {
+  ensureRoot(options.root);
+  const modes = [options.plannerRoute, options.plannerDecompose, options.plannerBriefs, options.plannerLint, options.plannerActionManifest, options.plannerExecutablePlan, options.plannerList, options.plannerShow, options.plannerVerify].filter(Boolean);
+  if (modes.length !== 1) throw new Error('planner requires exactly one of --route, --decompose, --briefs, --lint, --action-manifest, --executable-plan, --list, --show, or --verify');
+  if (options.methodologyIntent && !options.plannerActionManifest) throw new Error('--intent is only supported by planner --action-manifest');
+  if (runPlannerReadOnlyMode(options)) return;
+  if (runPlannerArtifactMode(options)) return;
+  runPlannerAuditMode(options);
+}
+
+  const {
+    routerSafety,
+    orchestratorSafety,
+    routerPlanEnvelope,
+    routerApprovalEnvelope,
+    validateRouterArtifact,
+    writeRouterArtifact,
+    routerAuditEnvelope,
+    orchestratorPlanEnvelope,
+    orchestratorDispatchPlanEnvelope,
+    validateOrchestratorArtifact,
+    writeOrchestratorArtifact,
+    orchestratorAuditEnvelope,
+  } = createRuntimeControlPlaneRoutingArtifacts({
+    fs,
+    path,
+    ensureRoot,
+    workflowPath,
+    plannerBriefsFilePath,
+    routerPlanFilePath,
+    routerApprovalFilePath,
+    orchestratorPlanFilePath,
+    orchestratorDispatchPlanFilePath,
+    routerPlanSnapshotPath,
+    routerApprovalSnapshotPath,
+    orchestratorPlanSnapshotPath,
+    orchestratorDispatchPlanSnapshotPath,
+    routerPlansDirectoryName,
+    routerApprovalsDirectoryName,
+    orchestratorPlansDirectoryName,
+    orchestratorDispatchPlansDirectoryName,
+    stateDirectoryName,
+    jsonSchemaVersion,
+    readJsonArtifact,
+    fileDigest,
+    digestObject,
+    validateCommonArtifactSafety,
+    validateRuntimePolicyCatalogDigest,
+    runtimePolicyCatalogDigest,
+    validatePlannerArtifact,
+    platformCapabilityCatalog,
+    routerAgentProfileForBriefKind,
+    routerRankingsForBriefItem,
+    routerFallbackRoutesForBriefItem,
+    routerConcurrencyBudget,
+    orchestratorBuildPlanFromRouterPlan,
+    writeStateArtifact,
+    listRouterPlanFiles,
+    listRouterApprovalFiles,
+    listOrchestratorPlanFiles,
+    listOrchestratorDispatchPlanFiles,
+  });
+
+function runRouter(options) {
+  ensureRoot(options.root);
+  const modes = [options.routerPlan, options.routerApprove, options.routerList, options.routerShow, options.routerVerify].filter(Boolean);
+  if (modes.length !== 1) throw new Error('router requires exactly one of --plan, --approve, --list, --show, or --verify');
+  if (options.routerPlan) {
+    if (!options.routerFile) throw new Error('router --plan requires --from-briefs <planner-briefs-file>');
+    const envelope = routerPlanEnvelope(options.root, options.routerFile, { persist: options.confirm, artifactFile: options.confirm ? path.basename(routerPlanSnapshotPath(options.root)) : '' });
+    if (options.confirm) {
+      const file = writeRouterArtifact(options.root, envelope);
+      if (options.json) writeJsonEnvelope('router', { ...envelope, router_plan_file: path.basename(file) });
+      else printRouter(envelope, file);
+      return;
+    }
+    if (options.json) writeJsonEnvelope('router', envelope);
+    else printRouter(envelope);
+    return;
+  }
+  if (options.routerApprove) {
+    if (!options.routerFile) throw new Error('router --approve requires <router-plan-file>');
+    const envelope = routerApprovalEnvelope(options.root, options.routerFile, { persist: options.confirm, artifactFile: options.confirm ? path.basename(routerApprovalSnapshotPath(options.root)) : '' });
+    if (options.confirm) {
+      const file = writeRouterArtifact(options.root, envelope);
+      if (options.json) writeJsonEnvelope('router', { ...envelope, router_approval_file: path.basename(file) });
+      else printRouter(envelope, file);
+      return;
+    }
+    if (options.json) writeJsonEnvelope('router', envelope);
+    else printRouter(envelope);
+    return;
+  }
+  if (options.confirm) throw new Error('router audit does not support --confirm');
+  const mode = options.routerList ? 'list' : options.routerVerify ? 'verify' : 'show';
+  if (mode !== 'list' && !options.routerFile) throw new Error(`router --${mode} requires a router artifact file`);
+  const envelope = routerAuditEnvelope(options.root, mode, options.routerFile);
+  if (options.json) writeJsonEnvelope('router', envelope);
+  else printRouter(envelope);
+}
+
+function runOrchestrator(options) {
+  ensureRoot(options.root);
+  const modes = [options.orchestratorPlan, options.orchestratorDispatchPlan, options.orchestratorList, options.orchestratorShow, options.orchestratorVerify].filter(Boolean);
+  if (modes.length !== 1) throw new Error('orchestrator requires exactly one of --plan, --dispatch-plan, --list, --show, or --verify');
+  if (options.orchestratorPlan) {
+    if (!options.orchestratorFile) throw new Error('orchestrator --plan requires --from-router <router-approval-file>');
+    const envelope = orchestratorPlanEnvelope(options.root, options.orchestratorFile, { persist: options.confirm, artifactFile: options.confirm ? path.basename(orchestratorPlanSnapshotPath(options.root)) : '' });
+    if (options.confirm) {
+      const file = writeOrchestratorArtifact(options.root, envelope);
+      if (options.json) writeJsonEnvelope('orchestrator', { ...envelope, orchestrator_plan_file: path.basename(file) });
+      else printOrchestrator(envelope, file);
+      return;
+    }
+    if (options.json) writeJsonEnvelope('orchestrator', envelope);
+    else printOrchestrator(envelope);
+    return;
+  }
+  if (options.orchestratorDispatchPlan) {
+    if (!options.orchestratorFile) throw new Error('orchestrator --dispatch-plan requires <orchestrator-plan-file>');
+    const envelope = orchestratorDispatchPlanEnvelope(options.root, options.orchestratorFile, { persist: options.confirm, artifactFile: options.confirm ? path.basename(orchestratorDispatchPlanSnapshotPath(options.root)) : '' });
+    if (options.confirm) {
+      const file = writeOrchestratorArtifact(options.root, envelope);
+      if (options.json) writeJsonEnvelope('orchestrator', { ...envelope, orchestrator_dispatch_plan_file: path.basename(file) });
+      else printOrchestrator(envelope, file);
+      return;
+    }
+    if (options.json) writeJsonEnvelope('orchestrator', envelope);
+    else printOrchestrator(envelope);
+    return;
+  }
+  if (options.confirm) throw new Error('orchestrator audit does not support --confirm');
+  const mode = options.orchestratorList ? 'list' : options.orchestratorVerify ? 'verify' : 'show';
+  if (mode !== 'list' && !options.orchestratorFile) throw new Error(`orchestrator --${mode} requires an orchestrator artifact file`);
+  const envelope = orchestratorAuditEnvelope(options.root, mode, options.orchestratorFile);
+  if (options.json) writeJsonEnvelope('orchestrator', envelope);
+  else printOrchestrator(envelope);
+}
+
+  return {
+    runPlanner,
+    runRouter,
+    runOrchestrator,
+    runVerification,
+    plannerAllowedWorkflows,
+    localTextEvidenceDescriptor,
+    planLintEnvelope,
+    planActionManifestEnvelope,
+    selfTestGateProfileEnvelope,
+    commitReadinessEnvelope,
+    evidenceIntakeEnvelope,
+    tddTraceEnvelope,
+    plannerRouteDecision,
+    routerRankingsForBriefItem,
+    routerAgentProfileForBriefKind,
+    routerPlatformOrderForBriefKind,
+    plannerDecomposeTasks,
+    plannerBriefKindsForTask,
+    printCommitReadiness,
+    stagedCommitReadinessEnvelope,
+    printStagedCommitReadiness,
+    routerSafety,
+    orchestratorSafety,
+    orchestratorBuildPlanFromRouterPlan,
+    validatePlannerArtifact,
+    validateRouterArtifact,
+    validateOrchestratorArtifact,
+  };
+}

package/tools/vibe-runtime/runtime-control-plane-planning-input.mjs

@@ -0,0 +1,99 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+function plannerSkillEvidenceRefs() {
+  return [
+    'skills/using-vibecoding/SKILL.md',
+    'skills/vibe-writing-plans/SKILL.md',
+    'skills/vibe-dispatching-parallel-work/SKILL.md',
+  ];
+}
+
+export function createRuntimeControlPlanePlanningInput({
+  artifactRootName,
+  hookIntentFolderName,
+  traceFolderName,
+  governanceFolderName,
+  methodologyGateFolderName,
+  traceFolder,
+  governanceFolder,
+  methodologyGateFolder,
+  hookIntentFilePath,
+  validateHookIntentArtifact,
+  readWorkflow,
+  workflowSummary,
+  readJsonArtifact,
+  latestArtifactFile,
+  fileDigest,
+}) {
+  function plannerInputFromFile(file) {
+    const text = fs.readFileSync(file, 'utf8');
+    const normalized = text.trim();
+    return {
+      source_kind: 'input-file',
+      source_file: path.basename(file),
+      raw_text: normalized,
+      digest: fileDigest(file),
+    };
+  }
+
+  function plannerInputFromHook(root, hookFile) {
+    const file = hookIntentFilePath(root, hookFile);
+    const artifact = readJsonArtifact(file, 'Hook intent');
+    const verification = validateHookIntentArtifact(root, artifact);
+    if (!verification.ok) throw new Error(`hook intent verification failed: ${verification.failures.join('; ')}`);
+    const hookIntent = artifact.hook_intent || {};
+    const workflow = readWorkflow(root);
+    const workflowSummaryValue = workflowSummary(workflow);
+    const text = [
+      `hook_source=${hookIntent.hook_source || 'session_start'}`,
+      `trigger_reason=${hookIntent.trigger_reason || ''}`,
+      `workflow_current=${workflowSummaryValue?.current_skill || 'none'}`,
+      `workflow_next=${workflowSummaryValue?.next_skill || 'none'}`,
+      `workflow_reason=${workflowSummaryValue?.reason || ''}`,
+    ].join('\n');
+    return {
+      source_kind: 'hook-intent',
+      source_file: path.basename(file),
+      raw_text: text,
+      digest: fileDigest(file),
+      hook_artifact: artifact,
+      workflow_summary: workflowSummaryValue,
+    };
+  }
+
+  function plannerReadInput(root, options) {
+    if (options.plannerFromHook && options.fromFile) throw new Error('planner --route accepts either --from-file <path> or --from-hook <hook-intent-file>, not both');
+    if (options.plannerFromHook) return plannerInputFromHook(root, options.plannerFile);
+    if (options.fromFile) return plannerInputFromFile(options.fromFile);
+    throw new Error('planner --route requires --from-file <path> or --from-hook <hook-intent-file>');
+  }
+
+  function plannerEvidenceRefs(root, input) {
+    const refs = [...plannerSkillEvidenceRefs()];
+    if (input.source_kind === 'hook-intent') refs.push(`${artifactRootName}/${hookIntentFolderName}/${input.source_file}`);
+    const latestTrace = latestArtifactFile(root, traceFolder, '.runtime-trace.json');
+    if (latestTrace) refs.push(`${artifactRootName}/${traceFolderName}/${latestTrace}`);
+    const latestGovernance = latestArtifactFile(root, governanceFolder, '.governance-attestation.json');
+    if (latestGovernance) refs.push(`${artifactRootName}/${governanceFolderName}/${latestGovernance}`);
+    const latestMethodology = latestArtifactFile(root, methodologyGateFolder, '.methodology-gate.json');
+    if (latestMethodology) refs.push(`${artifactRootName}/${methodologyGateFolderName}/${latestMethodology}`);
+    return refs;
+  }
+
+  function localTextEvidenceDescriptor(root, inputFile, label) {
+    const file = path.resolve(inputFile || '');
+    if (!file) throw new Error(`${label} is required`);
+    if (!fs.existsSync(file)) throw new Error(`${label} file not found: ${inputFile}`);
+    if (!fs.statSync(file).isFile()) throw new Error(`${label} is not a file: ${inputFile}`);
+    const relative = path.relative(root, file).replace(/\\/g, '/');
+    if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error(`${label} must be inside root: ${inputFile}`);
+    return { file, relative, digest: fileDigest(file), text: fs.readFileSync(file, 'utf8') };
+  }
+
+  return {
+    plannerReadInput,
+    plannerEvidenceRefs,
+    localTextEvidenceDescriptor,
+  };
+}