@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-cli-args.mjs

@@ -0,0 +1,550 @@
+import path from 'node:path';
+import { createRuntimeCliDefaultOptions } from './runtime-cli-option-defaults.mjs';
+import { parseLowRiskRuntimeCliOption } from './runtime-cli-option-handlers.mjs';
+import { parseLowRiskRuntimeCliEvidenceOption } from './runtime-cli-evidence-options.mjs';
+import { parseLowRiskRuntimeCliFromOption } from './runtime-cli-from-options.mjs';
+import { parseLowRiskRuntimeCliValueOption } from './runtime-cli-value-options.mjs';
+
+const taskIdPattern = /^[A-Za-z0-9._-]+$/;
+const windowsReservedTaskBasenames = new Set([
+  'CON',
+  'PRN',
+  'AUX',
+  'NUL',
+  'COM1',
+  'COM2',
+  'COM3',
+  'COM4',
+  'COM5',
+  'COM6',
+  'COM7',
+  'COM8',
+  'COM9',
+  'LPT1',
+  'LPT2',
+  'LPT3',
+  'LPT4',
+  'LPT5',
+  'LPT6',
+  'LPT7',
+  'LPT8',
+  'LPT9',
+]);
+const taskIdRequirement = 'Use only letters, numbers, dot, underscore, and hyphen; path separators, traversal, Windows reserved device names, and trailing dots or spaces are not allowed.';
+const viewSpecs = Object.freeze({
+  executions: { show: ['executionsShow', 'dispatchEvent'], verify: ['executionsVerify', 'dispatchEvent'], list: 'executionsList' },
+  actions: { show: ['actionsShow', 'actionId'], verify: ['actionsVerify', 'actionId'], list: 'actionsList' },
+  approvals: { show: ['approvalsShow', 'approval'], verify: ['approvalsVerify', 'approval'], list: 'approvalsList' },
+  queue: { show: ['queueShow', 'queueFile'], verify: ['queueVerify', 'queueFile'], list: 'queueList' },
+  leases: { show: ['leasesShow', 'queueFile'], verify: ['leasesVerify', 'queueFile'], list: 'leasesList' },
+  recovery: { show: ['recoveryShow', 'recoveryFile'], verify: ['recoveryVerify', 'recoveryFile'] },
+  scheduler: { show: ['schedulerShowPlan', 'schedulerPlanFile'], verify: ['schedulerVerifyPlan', 'schedulerPlanFile'], list: 'schedulerListPlans' },
+  retry: { show: ['retryShowPackage', 'retryPackageFile'], verify: ['retryVerifyPackage', 'retryPackageFile'], list: 'retryListPackages' },
+  daemon: { show: ['daemonLoopsShow', 'daemonLoopFile'], verify: ['daemonLoopsVerify', 'daemonLoopFile'], list: 'daemonLoopsList' },
+  reply: { show: ['replyShow', 'replyFile'], verify: ['replyVerify', 'replyFile'], list: 'replyList' },
+  traces: { show: ['traceShow', 'traceFile'], verify: ['traceVerify', 'traceFile'], list: 'traceList' },
+  governance: { show: ['governanceShow', 'governanceFile'], verify: ['governanceVerify', 'governanceFile'], list: 'governanceList' },
+  methodology: { show: ['methodologyShow', 'methodologyFile'], verify: ['methodologyVerify', 'methodologyFile'], list: 'methodologyList' },
+  hooks: { show: ['hooksShow', 'hooksFile'], verify: ['hooksVerify', 'hooksFile'], list: 'hooksList' },
+  subagents: { show: ['subagentsShow', 'subagentsFile'], verify: ['subagentsVerify', 'subagentsFile'], list: 'subagentsList' },
+  platforms: { show: ['platformsShow', 'platformsFile'], verify: ['platformsVerify', 'platformsFile'], list: 'platformsList' },
+  source: { show: ['sourceShow', 'sourceFile'], verify: ['sourceVerify', 'sourceFile'], list: 'sourceList' },
+  merge: { show: ['mergeShow', 'mergeFile'], verify: ['mergeVerify', 'mergeFile'], list: 'mergeList' },
+  planner: { show: ['plannerShow', 'plannerFile'], verify: ['plannerVerify', 'plannerFile'], list: 'plannerList' },
+  router: { show: ['routerShow', 'routerFile'], verify: ['routerVerify', 'routerFile'], list: 'routerList' },
+  orchestrator: { show: ['orchestratorShow', 'orchestratorFile'], verify: ['orchestratorVerify', 'orchestratorFile'], list: 'orchestratorList' },
+  'scheduler-policies': { show: ['schedulerPolicyShow', 'profile'], list: 'schedulerPolicyList' },
+  policies: { show: ['policyShow', 'profile'], list: 'policyList' },
+  learning: { show: ['learningShow', 'learningFile'], verify: ['learningVerify', 'learningFile'], list: 'learningList' },
+  evals: { verify: ['evalsVerify', 'evalsFile'] },
+  tokens: { verify: ['tokensVerify', 'tokenFile'] },
+});
+const mappedValueOptionSpecs = Object.freeze({
+  '--from-superpowers': { commands: ['governance'], required: '--from-superpowers requires a local Superpowers directory', unsupported: '--from-superpowers is only supported by governance --superpowers-gap, governance --superpowers-comparison, or governance --superpowers-regression-guard', set: (options, value) => { options.fromSuperpowers = value; } },
+  '--from-superpowers-root': { commands: ['governance', 'methodology'], required: '--from-superpowers-root requires a local Superpowers root directory', unsupported: '--from-superpowers-root is only supported by governance --superpowers-comparison or methodology --coverage-map', set: (options, value) => { options.fromSuperpowers = value; options.fromSuperpowersRoot = true; } },
+  '--from-runbook': { commands: ['verification', 'release', 'workflow', 'automation'], required: '--from-runbook requires a local Stage 118 runbook JSON file', unsupported: '--from-runbook is only supported by verification --execution-evidence, release --staged-commit-readiness, workflow --next-action-console, or automation --stage-scriptlet', set: (options, value) => { options.fromRunbook = path.resolve(value); } },
+  '--stage': { commands: ['verification', 'release', 'automation'], required: '--stage requires a stage id', unsupported: '--stage is only supported by verification --execution-evidence, release --staged-commit-readiness, or automation --stage-scriptlet', set: (options, value) => { options.selectedStage = value; } },
+  '--base': { commands: ['sdd'], required: '--base requires a commit sha', unsupported: '--base is only supported by sdd --review-package', set: (options, value) => { options.base = value; } },
+  '--head': { commands: ['sdd'], required: '--head requires a commit sha', unsupported: '--head is only supported by sdd --review-package', set: (options, value) => { options.head = value; } },
+  '--actor': { required: '--actor requires an id', set: (options, value) => { options.actor = value; } },
+  '--reason': { required: '--reason requires text', set: (options, value) => { options.reason = value; } },
+  '--instinct': { commands: ['learning'], required: '--instinct requires a candidate instinct file', unsupported: '--instinct is only supported by learning --promote or learning --advice', set: (options, value) => { options.learningInstinctFile = value; } },
+  '--platform': { required: '--platform requires claude, cursor, or codex', set: (options, value) => { options.platform = value; } },
+  '--approval': { required: '--approval requires an approval file', set: (options, value) => { options.approval = value; } },
+  '--probe': { commands: ['platforms'], required: '--probe requires a platform', unsupported: '--probe is only supported by platforms', set: (options, value) => { options.platformsProbe = true; options.platform = value; } },
+  '--cancel-session': { commands: ['subagents'], required: '--cancel-session requires a platform session file', unsupported: '--cancel-session is only supported by subagents', set: (options, value) => { options.cancelSession = true; options.subagentsFile = value; } },
+  '--ingest-session-result': { commands: ['subagents'], required: '--ingest-session-result requires a platform session result file', unsupported: '--ingest-session-result is only supported by subagents', set: (options, value) => { options.sessionResultIngest = true; options.subagentsResultFile = value; } },
+  '--review-session-result': { commands: ['subagents'], required: '--review-session-result requires a platform session intake file', unsupported: '--review-session-result is only supported by subagents', set: (options, value) => { options.sessionResultReview = true; options.subagentsResultFile = value; } },
+  '--from-approval': { required: '--from-approval requires a platform session approval file', set: (options, value) => { options.fromApproval = value; } },
+  '--capability': { required: '--capability requires a platform capability file', set: (options, value) => { options.capabilityFile = value; } },
+  '--from-dispatch': { required: '--from-dispatch requires a dispatch event file', set: (options, value) => { options.fromDispatch = value; } },
+  '--from-session-review': { commands: ['source'], required: '--from-session-review requires a platform session review file', unsupported: '--from-session-review is only supported by source', set: (options, value) => { options.sourceFile = value; } },
+  '--from-task-result': { commands: ['release'], required: '--from-task-result requires a local task result file', unsupported: '--from-task-result is only supported by release --task-commit-readiness', set: (options, value) => { options.taskResultFile = value; } },
+  '--from-readiness': { commands: ['release', 'governance'], required: '--from-readiness requires a local readiness file', unsupported: '--from-readiness is only supported by release --local-commit-gate, release --task-commit, release --closeout-readiness, or governance --pr-review-intake', set: (options, value) => { options.fromReadiness = value; } },
+  '--from-verification': { commands: ['merge'], required: '--from-verification requires a source verification file', unsupported: '--from-verification is only supported by merge', set: (options, value) => { options.mergeFile = value; } },
+  '--ingest-result': { commands: ['subagents'], required: '--ingest-result requires a subagent run result file', unsupported: '--ingest-result is only supported by subagents', set: (options, value) => { options.subagentsIngestResult = true; options.subagentsResultFile = value; } },
+  '--review-gate': { commands: ['subagents'], required: '--review-gate requires a subagent result file', unsupported: '--review-gate is only supported by subagents', set: (options, value) => { options.subagentsReviewGate = true; options.subagentsResultFile = value; } },
+  '--from-briefs': { commands: ['router'], required: '--from-briefs requires a planner briefs file', unsupported: '--from-briefs is only supported by router', set: (options, value) => { options.routerFromBriefs = true; options.routerFile = value; } },
+  '--run-contract': { commands: ['evals'], required: '--run-contract requires an eval suite id', unsupported: '--run-contract is only supported by evals', set: (options, value) => { options.evalsRunContract = true; options.evalsSuite = value; } },
+  '--run-scenario': { commands: ['evals'], required: '--run-scenario requires an eval suite id', unsupported: '--run-scenario is only supported by evals', set: (options, value) => { options.evalsRunScenario = true; options.evalsSuite = value; } },
+  '--run-behavior': { commands: ['evals'], required: '--run-behavior requires an eval suite id', unsupported: '--run-behavior is only supported by evals', set: (options, value) => { options.evalsRunBehavior = true; options.evalsSuite = value; } },
+  '--run-adversarial': { commands: ['evals'], required: '--run-adversarial requires an eval suite id', unsupported: '--run-adversarial is only supported by evals', set: (options, value) => { options.evalsRunAdversarial = true; options.evalsSuite = value; } },
+  '--verify-ledger': { commands: ['feedback'], required: '--verify-ledger requires a feedback ledger file', unsupported: '--verify-ledger is only supported by feedback', set: (options, value) => { options.feedbackVerifyLedger = true; options.feedbackLedgerFile = value; } },
+  '--from-executable-plan': { commands: ['automation'], required: '--from-executable-plan requires a local Stage 117 executable plan JSON file', unsupported: '--from-executable-plan is only supported by automation --stage-runbook', set: (options, value) => { options.fromExecutablePlan = path.resolve(value); } },
+  '--from-route': { commands: ['planner'], required: '--from-route requires a planner route file', unsupported: '--from-route is only supported by planner', set: (options, value) => { options.plannerFile = value; } },
+  '--claim': { required: '--claim requires a dispatch event file', set: (options, value) => { options.dispatchClaim = true; options.dispatchEvent = value; } },
+  '--ack': { required: '--ack requires a dispatch event file', set: (options, value) => { options.dispatchAck = true; options.dispatchEvent = value; } },
+  '--pickup': { required: '--pickup requires a dispatch event file', set: (options, value) => { options.dispatchPickup = true; options.dispatchEvent = value; } },
+  '--pickup-verify': { required: '--pickup-verify requires a dispatch event file', set: (options, value) => { options.dispatchPickupVerify = true; options.dispatchEvent = value; } },
+  '--pickup-dry-run': { required: '--pickup-dry-run requires a dispatch event file', set: (options, value) => { options.dispatchPickupDryRun = true; options.dispatchEvent = value; } },
+  '--show-plan': { required: '--show-plan requires a scheduler plan file', set: (options, value) => { options.schedulerShowPlan = true; options.schedulerPlanFile = value; } },
+  '--verify-plan': { required: '--verify-plan requires a scheduler plan file', set: (options, value) => { options.schedulerVerifyPlan = true; options.schedulerPlanFile = value; } },
+  '--show-classification': { required: '--show-classification requires a recovery classification file', set: (options, value) => { options.recoveryShowClassification = true; options.recoveryClassificationFile = value; } },
+  '--verify-classification': { required: '--verify-classification requires a recovery classification file', set: (options, value) => { options.recoveryVerifyClassification = true; options.recoveryClassificationFile = value; } },
+  '--confirm-plan': { commands: ['automation', 'workflow'], required: '--confirm-plan requires a confirmation phrase', unsupported: '--confirm-plan is only supported by automation --one-shot-plan or workflow --close-loop-dashboard', set: (options, value) => { options.confirmPlan = value; } },
+  '--from-task': { commands: ['source'], required: '--from-task requires a task artifact file', unsupported: '--from-task is only supported by source --patch-plan', set: (options, value) => { options.fromTask = value; } },
+  '--verify-change': { commands: ['source'], required: '--verify-change requires a source sandbox run file', unsupported: '--verify-change is only supported by source', set: (options, value) => { options.sourceVerifyChange = true; options.sourceFile = value; } },
+});
+const mappedFlagOptionSpecs = Object.freeze({
+  '--session-approval': { commands: ['subagents'], unsupported: '--session-approval is only supported by subagents', set: (options) => { options.sessionApproval = true; } },
+  '--adapter-dispatch': { commands: ['subagents'], unsupported: '--adapter-dispatch is only supported by subagents', set: (options) => { options.subagentsAdapterDispatch = true; } },
+  '--create-session': { commands: ['subagents'], unsupported: '--create-session is only supported by subagents', set: (options) => { options.createSession = true; } },
+  '--auto-dispatch': { commands: ['subagents'], unsupported: '--auto-dispatch is only supported by subagents', set: (options) => { options.subagentsAutoDispatch = true; } },
+  '--hook-run': { commands: ['hooks'], unsupported: '--hook-run is only supported by hooks', set: (options) => { options.hooksRun = true; } },
+  '--claims': { set: (options) => { options.dispatchClaims = true; } },
+  '--list-plans': { set: (options) => { options.schedulerListPlans = true; } },
+  '--list-classifications': { set: (options) => { options.recoveryListClassifications = true; } },
+  '--recover': { set: (options) => { options.schedulerRecover = true; } },
+  '--run-loop': { commands: ['sdd'], unsupported: '--run-loop is only supported by sdd', set: (options) => { options.sddRunLoop = true; } },
+  '--isolate-plan': { commands: ['workspace'], unsupported: '--isolate-plan is only supported by workspace', set: (options) => { options.workspaceIsolatePlan = true; } },
+  '--cleanup-plan': { commands: ['workspace'], unsupported: '--cleanup-plan is only supported by workspace', set: (options) => { options.workspaceCleanupPlan = true; } },
+  '--create': { commands: ['workspace'], unsupported: '--create is only supported by workspace', set: (options) => { options.workspaceCreate = true; } },
+  '--score': { set: (options) => { options.readinessScore = true; } },
+  '--dry-run': { set: (options) => { options.dryRun = true; } },
+  '--write': { set: (options) => { options.write = true; } },
+  '--confirm': { set: (options) => { options.confirm = true; } },
+  '--once': { set: (options) => { options.once = true; } },
+  '--scan': { set: (options) => { options.scan = true; } },
+  '--preflight': { set: (options) => { options.preflight = true; } },
+  '--patch-plan': { commands: ['source'], unsupported: '--patch-plan is only supported by source', set: (options) => { options.sourcePatchPlan = true; } },
+  '--repair-plan': { commands: ['verification'], unsupported: '--repair-plan is only supported by verification', set: (options) => { options.verificationRepairPlan = true; } },
+  '--apply-to-worktree': { commands: ['source'], unsupported: '--apply-to-worktree is only supported by source', set: (options) => { options.sourceApplyToWorktree = true; } },
+  '--approval-package': { set: (options) => { options.approvalPackage = true; } },
+  '--auto-run': { set: (options) => { options.autoRun = true; } },
+  '--json': { set: (options) => { options.json = true; } },
+  '--dispatch-intent': { set: (options) => { options.dispatchIntent = true; } },
+});
+
+function requireArgValue(argv, index, message) {
+  const value = argv[index + 1];
+  if (!value) throw new Error(message);
+  return value;
+}
+
+function collectFollowingValues(argv, index) {
+  const values = [];
+  for (let valueIndex = index + 1; valueIndex < argv.length; valueIndex += 1) {
+    const value = argv[valueIndex];
+    if (!value || value.startsWith('-')) break;
+    values.push(value);
+  }
+  return values;
+}
+
+const notHandled = Object.freeze({ handled: false, index: 0 });
+
+function parseRuntimeCliViewOption(options, argv, index) {
+  const arg = argv[index];
+  if (arg === '--show' || arg === '--verify') {
+    const spec = viewSpecs[options.command]?.[arg.slice(2)] || (arg === '--show' ? ['dispatchShow', 'dispatchEvent'] : ['dispatchVerify', 'dispatchEvent']);
+    const [flag, fileField] = spec;
+    const message = arg === '--show' ? '--show requires an event file, profile, or queue file' : '--verify requires an event file or queue file';
+    options[flag] = true;
+    options[fileField] = requireArgValue(argv, index, message);
+    return { handled: true, index: index + 1 };
+  }
+  if (arg !== '--list') return notHandled;
+  options[viewSpecs[options.command]?.list || 'dispatchList'] = true;
+  return { handled: true, index };
+}
+
+function parseRuntimeCliPostViewOption(options, argv, index) {
+  const arg = argv[index];
+  const flags = { '--classify': 'recoveryClassify', '--build': 'traceBuild', '--attest': 'governanceAttest', '--list-packages': 'retryListPackages', '--loop': 'daemonLoop', '--stop': 'daemonStop', '--loops': 'daemonLoopsList', '--draft': 'replyDraft', '--source-bound': 'replySourceBound' };
+  const files = { '--show-package': ['retryShowPackage', 'retryPackageFile', '--show-package requires a retry package file'], '--verify-package': ['retryVerifyPackage', 'retryPackageFile', '--verify-package requires a retry package file'], '--review': ['replyReview', 'replyFile', '--review requires a reply draft file'], '--outbox': ['replyOutbox', 'replyFile', '--outbox requires a reply approval file'], '--send': ['replySend', 'replyFile', '--send requires a reply outbox file'] };
+  if (arg === '--transition') {
+    options.approvalsTransition = true;
+    options.approval = requireArgValue(argv, index, '--transition requires an approval file');
+    return { handled: true, index: index + 1 };
+  }
+  if (arg === '--preview') {
+    if (options.command === 'hooks') options.hooksPreview = true;
+    else if (options.command === 'governance' || options.command === 'learning' || options.command === 'tokens') options.dryRun = true;
+    else options.recoveryPreview = true;
+    return { handled: true, index };
+  }
+  if (arg === '--summary') {
+    if (options.command === 'policies') options.policySummary = true;
+    else options.observabilitySummary = true;
+    return { handled: true, index };
+  }
+  if (arg === '--max-iterations') {
+    options.maxIterations = Number.parseInt(requireArgValue(argv, index, '--max-iterations requires a number'), 10);
+    return { handled: true, index: index + 1 };
+  }
+  if (flags[arg]) {
+    options[flags[arg]] = true;
+    return { handled: true, index };
+  }
+  if (!files[arg]) return notHandled;
+  const [flag, fileField, message] = files[arg];
+  options[flag] = true;
+  options[fileField] = requireArgValue(argv, index, message);
+  return { handled: true, index: index + 1 };
+}
+
+function parseRuntimeCliBaseOption(options, argv, index) {
+  const arg = argv[index];
+  if (arg === '--help' || arg === '-h') {
+    options.help = true;
+    return { handled: true, index };
+  }
+  if (arg === '--root') {
+    options.root = path.resolve(requireArgValue(argv, index, '--root requires a path'));
+    return { handled: true, index: index + 1 };
+  }
+  if (arg === '--from-file') {
+    const value = requireArgValue(argv, index, '--from-file requires a path');
+    options.fromFile = ['tokens', 'release', 'sdd'].includes(options.command) ? value : path.resolve(value);
+    return { handled: true, index: index + 1 };
+  }
+  if (arg === '--prompt') {
+    const value = requireArgValue(argv, index, '--prompt requires text');
+    if (!['bootstrap', 'workflow', 'session', 'entry', 'tokens', 'automation'].includes(options.command)) throw new Error('--prompt is only supported by bootstrap --acceptance, workflow --start, session --start, workflow --entry-ux, entry --contract, tokens --savior-budget, or automation --plan');
+    options.prompt = value;
+    return { handled: true, index: index + 1 };
+  }
+  return notHandled;
+}
+
+function parseRuntimeCliTaskStatusOption(options, argv, index) {
+  const arg = argv[index];
+  if (arg === '--task') {
+    const value = requireArgValue(argv, index, '--task requires a task id');
+    validateTaskId(value);
+    options.task = value;
+    return { handled: true, index: index + 1 };
+  }
+  if (arg === '--status') {
+    if (options.command === 'workspace') {
+      options.workspaceStatus = true;
+      return { handled: true, index };
+    }
+    const value = requireArgValue(argv, index, '--status requires a value');
+    if (options.command === 'approvals') options.approvalLifecycleStatus = value;
+    else options.ackStatus = value;
+    return { handled: true, index: index + 1 };
+  }
+  return notHandled;
+}
+
+function parseRuntimeCliMappedOption(options, argv, index) {
+  const arg = argv[index];
+  const valueSpec = mappedValueOptionSpecs[arg];
+  if (valueSpec) {
+    const value = requireArgValue(argv, index, valueSpec.required);
+    if (valueSpec.commands && !valueSpec.commands.includes(options.command)) throw new Error(valueSpec.unsupported);
+    valueSpec.set(options, value, arg);
+    return { handled: true, index: index + 1 };
+  }
+  const flagSpec = mappedFlagOptionSpecs[arg];
+  if (!flagSpec) return notHandled;
+  if (flagSpec.commands && !flagSpec.commands.includes(options.command)) throw new Error(flagSpec.unsupported);
+  flagSpec.set(options, arg);
+  return { handled: true, index };
+}
+
+function parseRuntimeCliMultiValueOption(options, argv, index) {
+  const arg = argv[index];
+  const values = collectFollowingValues(argv, index);
+  if (arg === '--from-observations') {
+    if (options.command !== 'learning') throw new Error('--from-observations is only supported by learning --instincts, learning --advice, or learning --experience-pattern');
+    if (values.length === 0) throw new Error('--from-observations requires at least one learning observation file');
+    options.learningObservationFiles.push(...values);
+    return { handled: true, index: index + values.length };
+  }
+  if (arg === '--from-compactions') {
+    if (options.command !== 'tokens') throw new Error('--from-compactions is only supported by tokens --metrics');
+    if (values.length === 0) throw new Error('--from-compactions requires at least one token compaction file');
+    options.tokenCompactionFiles.push(...values);
+    return { handled: true, index: index + values.length };
+  }
+  return notHandled;
+}
+
+function parseRuntimeCliRoutingArtifactOption(options, argv, index) {
+  const arg = argv[index];
+  const values = collectFollowingValues(argv, index);
+  if (arg === '--from-router') {
+    if (options.command === 'orchestrator') {
+      if (values.length !== 1) throw new Error('--from-router requires exactly one router approval file for orchestrator');
+      options.orchestratorFromRouter = true;
+      options.orchestratorFile = values[0];
+    } else if (options.command === 'feedback') {
+      if (values.length === 0) throw new Error('--from-router requires at least one router artifact file');
+      options.feedbackRouterFiles.push(...values);
+    } else throw new Error('--from-router is only supported by orchestrator or feedback');
+    return { handled: true, index: index + values.length };
+  }
+  if (arg === '--from-orchestrator') {
+    if (options.command === 'subagents') {
+      if (values.length !== 1) throw new Error('--from-orchestrator requires exactly one orchestrator dispatch plan file for subagents');
+      options.subagentsFromOrchestrator = true;
+      options.orchestratorFile = values[0];
+    } else if (options.command === 'feedback') {
+      if (values.length === 0) throw new Error('--from-orchestrator requires at least one orchestrator artifact file');
+      options.feedbackOrchestratorFiles.push(...values);
+    } else throw new Error('--from-orchestrator is only supported by subagents or feedback');
+    return { handled: true, index: index + values.length };
+  }
+  return notHandled;
+}
+
+function parseRuntimeCliFeedbackInputOption(options, argv, index) {
+  const arg = argv[index];
+  const values = collectFollowingValues(argv, index);
+  if (arg === '--from-evals') {
+    if (options.command !== 'release' && options.command !== 'feedback') throw new Error('--from-evals is only supported by release or feedback');
+    if (values.length === 0) throw new Error('--from-evals requires at least one eval report file');
+    if (options.command === 'feedback') options.feedbackEvalFiles.push(...values);
+    else options.releaseEvalFiles.push(...values);
+    return { handled: true, index: index + values.length };
+  }
+  if (arg === '--from-planner' || arg === '--from-release-gate') {
+    const field = arg === '--from-planner' ? 'feedbackPlannerFiles' : 'feedbackReleaseGateFiles';
+    const label = arg === '--from-planner' ? 'planner artifact' : 'release gate';
+    if (options.command !== 'feedback') throw new Error(`${arg} is only supported by feedback`);
+    if (values.length === 0) throw new Error(`${arg} requires at least one ${label} file`);
+    options[field].push(...values);
+    return { handled: true, index: index + values.length };
+  }
+  return notHandled;
+}
+
+function parseRuntimeCliSubjectPlanOption(options, argv, index) {
+  const arg = argv[index];
+  if (arg === '--subject') {
+    if (options.command !== 'release' && options.command !== 'automation' && options.command !== 'workflow') throw new Error('--subject is only supported by release --commit-guard, release --commit-readiness, release --staged-commit-readiness, automation --one-shot-plan, workflow --close-loop-dashboard, or workflow --close-loop');
+    const values = collectFollowingValues(argv, index);
+    if (values.length === 0) throw new Error('--subject requires a commit subject');
+    options.commitSubject = values.join(' ');
+    return { handled: true, index: index + values.length };
+  }
+  if (arg === '--from-plan') {
+    const value = requireArgValue(argv, index, '--from-plan requires a scheduler hook plan file, planner plan file, local plan file, or completion evidence plan file');
+    if (['verification', 'release', 'review', 'automation', 'completion'].includes(options.command)) options.fromPlan = value;
+    else if (options.command === 'subagents') options.schedulerPlanFile = value;
+    else if (options.command === 'planner') options.plannerFile = value;
+    else throw new Error('--from-plan is only supported by verification --evidence-intake, verification --tdd-trace, release --diff-coverage, release --diff-read, review --intake, automation --stage-runbook, subagents, planner, or completion --evidence-bundle');
+    return { handled: true, index: index + 1 };
+  }
+  return notHandled;
+}
+
+function parseRuntimeCliPlanToggleOption(options, argv, index) {
+  const arg = argv[index];
+  const value = argv[index + 1];
+  if (arg === '--eligibility') {
+    if (value && !value.startsWith('-')) {
+      if (options.command !== 'subagents') throw new Error('--eligibility <file> is only supported by subagents');
+      options.subagentsEligibilityFile = value;
+      return { handled: true, index: index + 1 };
+    }
+    options.subagentsEligibility = true;
+    return { handled: true, index };
+  }
+  if (arg === '--dispatch-plan' || arg === '--decompose' || arg === '--briefs') return parseRuntimeCliOptionalPlanFileOption(options, argv, index);
+  return notHandled;
+}
+
+function parseRuntimeCliOptionalPlanFileOption(options, argv, index) {
+  const arg = argv[index];
+  const value = argv[index + 1];
+  const hasFile = value && !value.startsWith('-');
+  if (arg === '--dispatch-plan') {
+    if (options.command !== 'orchestrator') throw new Error('--dispatch-plan is only supported by orchestrator');
+    options.orchestratorDispatchPlan = true;
+    if (hasFile) options.orchestratorFile = value;
+  } else if (arg === '--decompose' || arg === '--briefs') {
+    if (options.command !== 'planner') throw new Error(`${arg} is only supported by planner`);
+    if (arg === '--decompose') options.plannerDecompose = true;
+    else options.plannerBriefs = true;
+    if (hasFile) options.plannerFile = value;
+  } else return notHandled;
+  return { handled: true, index: hasFile ? index + 1 : index };
+}
+
+function parseRuntimeCliRouteApplyOption(options, argv, index) {
+  const arg = argv[index];
+  if (arg === '--from-hook') {
+    const value = requireArgValue(argv, index, '--from-hook requires a hook intent file');
+    if (options.command === 'scheduler') { options.schedulerFromHook = true; options.schedulerHookFile = value; }
+    else if (options.command === 'planner') { options.plannerFromHook = true; options.plannerFile = value; }
+    else throw new Error('--from-hook is only supported by scheduler or planner');
+    return { handled: true, index: index + 1 };
+  }
+  if (arg === '--apply') {
+    const value = requireArgValue(argv, index, '--apply requires a recovery classification file or merge approval file');
+    if (options.command === 'merge') { options.mergeApply = true; options.mergeFile = value; }
+    else { options.recoveryApply = true; options.recoveryClassificationFile = value; }
+    return { handled: true, index: index + 1 };
+  }
+  if (arg === '--route') {
+    if (options.command === 'planner') options.plannerRoute = true;
+    else if (options.command === 'methodology') options.methodologyRoute = true;
+    else throw new Error('--route is only supported by planner or methodology');
+    return { handled: true, index };
+  }
+  return notHandled;
+}
+
+function parseRuntimeCliExecutionBoundaryOption(options, argv, index) {
+  const arg = argv[index];
+  if (arg === '--approve') {
+    const value = requireArgValue(argv, index, '--approve requires a reply draft or merge readiness file');
+    if (options.command === 'merge') { options.mergeApprove = true; options.mergeFile = value; }
+    else if (options.command === 'router') { options.routerApprove = true; options.routerFile = value; }
+    else { options.replyApprove = true; options.replyFile = value; }
+    return { handled: true, index: index + 1 };
+  }
+  if (arg === '--apply-sandbox' || arg === '--sandbox-apply') {
+    const value = requireArgValue(argv, index, `${arg} requires a source change candidate file`);
+    if (options.command !== 'source') throw new Error(`${arg} is only supported by source`);
+    options.sourceApplySandbox = true;
+    options.sourceFile = value;
+    return { handled: true, index: index + 1 };
+  }
+  if (arg === '--run') {
+    if (options.command === 'retry') { options.retryRunPackage = true; options.retryPackageFile = requireArgValue(argv, index, '--run requires a retry package file'); return { handled: true, index: index + 1 }; }
+    options.run = true;
+    return { handled: true, index };
+  }
+  return notHandled;
+}
+
+function parseRuntimeCliModeOption(options, argv, index) {
+  const arg = argv[index];
+  if (arg === '--adapter') {
+    const value = requireArgValue(argv, index, '--adapter requires an adapter id');
+    if (options.command === 'platforms') options.entryAdapter = value;
+    else options.replyAdapter = value;
+    return { handled: true, index: index + 1 };
+  }
+  if (arg === '--plan') {
+    if (options.command === 'automation') options.automationPlan = true;
+    else if (options.command === 'sdd') options.sddPlan = true;
+    else if (options.command === 'router') options.routerPlan = true;
+    else if (options.command === 'orchestrator') options.orchestratorPlan = true;
+    else options.schedulerPlan = true;
+    return { handled: true, index };
+  }
+  if (arg === '--readiness') {
+    if (options.command === 'methodology') options.methodologyReadiness = true;
+    else if (options.command === 'completion') options.completionReadiness = true;
+    else if (options.command === 'merge') options.mergeReadiness = true;
+    else if (options.command === 'automation') options.automationReadiness = true;
+    else throw new Error('--readiness is only supported by methodology, completion, merge, or automation');
+    return { handled: true, index };
+  }
+  return notHandled;
+}
+
+function parseRuntimeCliProfileDispatchOption(options, argv, index) {
+  const arg = argv[index];
+  if (arg === '--profile') {
+    if (options.command === 'tokens') {
+      options.tokensProfile = true;
+      const value = argv[index + 1];
+      if (value && !String(value).startsWith('--')) { options.tokenProfileName = value; return { handled: true, index: index + 1 }; }
+      return { handled: true, index };
+    }
+    options.profile = requireArgValue(argv, index, '--profile requires a policy profile');
+    return { handled: true, index: index + 1 };
+  }
+  if (arg === '--candidate') {
+    if (options.command === 'source') options.sourceCandidate = true;
+    else options.candidate = true;
+    return { handled: true, index };
+  }
+  if (arg === '--dispatch') {
+    if (options.command === 'subagents') options.subagentsDispatch = true;
+    else options.dispatch = true;
+    return { handled: true, index };
+  }
+  return notHandled;
+}
+
+function parseRuntimeCliKnownOption(options, argv, index) {
+  const fromOptionResult = parseLowRiskRuntimeCliFromOption(options, argv, index);
+  if (fromOptionResult.handled) return fromOptionResult;
+  const evidenceOptionResult = parseLowRiskRuntimeCliEvidenceOption(options, argv, index);
+  if (evidenceOptionResult.handled) return evidenceOptionResult;
+  const valueOptionResult = parseLowRiskRuntimeCliValueOption(options, argv, index);
+  if (valueOptionResult.handled) return valueOptionResult;
+  const viewOptionResult = parseRuntimeCliViewOption(options, argv, index);
+  if (viewOptionResult.handled) return viewOptionResult;
+  const postViewOptionResult = parseRuntimeCliPostViewOption(options, argv, index);
+  if (postViewOptionResult.handled) return postViewOptionResult;
+
+  const parsers = [
+    parseRuntimeCliBaseOption,
+    parseRuntimeCliTaskStatusOption,
+    parseRuntimeCliMappedOption,
+    parseRuntimeCliMultiValueOption,
+    parseRuntimeCliRoutingArtifactOption,
+    parseRuntimeCliFeedbackInputOption,
+    parseRuntimeCliSubjectPlanOption,
+    parseRuntimeCliPlanToggleOption,
+    parseRuntimeCliRouteApplyOption,
+    parseRuntimeCliExecutionBoundaryOption,
+    parseRuntimeCliModeOption,
+    parseRuntimeCliProfileDispatchOption,
+  ];
+  for (const parser of parsers) {
+    const result = parser(options, argv, index);
+    if (result.handled) return result;
+  }
+  if (parseLowRiskRuntimeCliOption(argv[index], options)) return { handled: true, index };
+  return notHandled;
+}
+
+export function parseArgs(argv) {
+  const options = createRuntimeCliDefaultOptions();
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (index === 0 && !arg.startsWith('-')) {
+      options.command = arg;
+      continue;
+    }
+    const result = parseRuntimeCliKnownOption(options, argv, index);
+    if (!result.handled) throw new Error(`Unknown argument: ${arg}`);
+    index = result.index;
+  }
+
+  return options;
+}
+
+export function validateTaskId(id) {
+  const reservedBasename = id.split('.')[0].toUpperCase();
+  if (
+    !taskIdPattern.test(id)
+    || id === '.'
+    || id === '..'
+    || id.endsWith('.')
+    || id.endsWith(' ')
+    || windowsReservedTaskBasenames.has(reservedBasename)
+  ) {
+    throw new Error(`Invalid task id: ${id}. ${taskIdRequirement}`);
+  }
+}

package/tools/vibe-runtime/runtime-cli-command-specs.mjs

@@ -0,0 +1,63 @@
+const runtimeCliDispatchContractSurface = 'runtime-cli-dispatch runtime-cli-args runtime-cli-usage governance release tasks reset';
+
+export const runtimeCommandSpecs = Object.freeze([
+  ['entry', 'runEntry'],
+  ['advice', 'runAdvice'],
+  ['status', 'runStatus'],
+  ['validate-handoff', 'runValidateHandoff'],
+  ['record-handoff', 'runRecordHandoff'],
+  ['next', 'runNext'],
+  ['dispatches', 'runDispatches'],
+  ['execute', 'runExecute'],
+  ['executions', 'runExecutions'],
+  ['actions', 'runActions'],
+  ['approvals', 'runApprovals'],
+  ['policies', 'runPolicies'],
+  ['queue', 'runQueue'],
+  ['leases', 'runLeases'],
+  ['recovery', 'runRecovery'],
+  ['observability', 'runObservability'],
+  ['readiness', 'runObservability'],
+  ['scheduler', 'runScheduler'],
+  ['scheduler-policies', 'runSchedulerPolicies'],
+  ['retry', 'runRetry'],
+  ['daemon', 'runDaemon'],
+  ['reply', 'runReply'],
+  ['traces', 'runTraces'],
+  ['governance', 'runGovernance'],
+  ['automation', 'runAutomation'],
+  ['methodology', 'runMethodology'],
+  ['workflow', 'runWorkflow'],
+  ['session', 'runSession'],
+  ['skill', 'runSkill'],
+  ['verification', 'runVerification'],
+  ['review', 'runReview'],
+  ['completion', 'runCompletion'],
+  ['bootstrap', 'runBootstrap'],
+  ['onboarding', 'runOnboarding'],
+  ['learning', 'runLearning'],
+  ['tokens', 'runTokens'],
+  ['hooks', 'runHooks'],
+  ['subagents', 'runSubagents'],
+  ['sdd', 'runSdd'],
+  ['workspace', 'runWorkspace'],
+  ['platforms', 'runPlatforms'],
+  ['source', 'runSource'],
+  ['merge', 'runMerge'],
+  ['planner', 'runPlanner'],
+  ['router', 'runRouter'],
+  ['orchestrator', 'runOrchestrator'],
+  ['evals', 'runEvals'],
+  ['release', 'runRelease'],
+  ['tests', 'runTests'],
+  ['feedback', 'runFeedback'],
+  ['artifacts', 'runArtifacts'],
+  ['tasks', 'runTasks'],
+  ['reset', 'runReset'],
+]);
+
+export function assertRuntimeCliDispatchContractSurface() {
+  if (!runtimeCliDispatchContractSurface.includes('runtime-cli-dispatch')) {
+    throw new Error('runtime CLI dispatch contract marker missing');
+  }
+}

package/tools/vibe-runtime/runtime-cli-dispatch.mjs

@@ -0,0 +1,21 @@
+import {
+  assertRuntimeCliDispatchContractSurface,
+  runtimeCommandSpecs,
+} from './runtime-cli-command-specs.mjs';
+
+export const runtimeCliDispatchSurfaceContractMarkers = Object.freeze(['governance', 'release', 'tasks', 'reset']);
+
+export const runtimeCommandNames = runtimeCommandSpecs.map(([command]) => command);
+
+export function runtimeCommandHandlers(runners) {
+  assertRuntimeCliDispatchContractSurface();
+  return Object.fromEntries(
+    runtimeCommandSpecs.map(([command, runnerName]) => [command, runners[runnerName]]),
+  );
+}
+
+export function dispatchRuntimeCommand(options, handlers) {
+  const handler = handlers[options.command];
+  if (!handler) throw new Error(`Unknown command: ${options.command}`);
+  return handler(options);
+}