@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-cli-evidence-option-specs.mjs

@@ -0,0 +1,193 @@
+export const runtimeCliEvidenceOptionSpecs = [
+  {
+    arg: '--from-transcript',
+    option: 'fromTranscript',
+    commands: ['workflow'],
+    requiredMessage: '--from-transcript requires a local transcript JSON file',
+    unsupportedMessage: '--from-transcript is only supported by workflow --entry-discipline',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-gap',
+    option: 'fromGap',
+    commands: ['workflow'],
+    requiredMessage: '--from-gap requires a local Stage 115 gap JSON file',
+    unsupportedMessage: '--from-gap is only supported by workflow --entry-ux',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-readiness',
+    option: 'fromReadiness',
+    commands: ['governance', 'release'],
+    requiredMessage: '--from-readiness requires a PR readiness governance file or task commit readiness file',
+    unsupportedMessage: '--from-readiness is only supported by governance --pr-review-intake, release --task-commit, or release --closeout-readiness',
+    resolve: false,
+    risk: 'low',
+  },
+  {
+    arg: '--from-evidence',
+    option: 'fromEvidence',
+    commands: ['review', 'release', 'workflow', 'completion'],
+    requiredMessage: '--from-evidence requires a local evidence file',
+    unsupportedMessage: '--from-evidence is only supported by review --resolution, release --staged-commit-readiness, release --closeout-readiness, workflow --next-action-console, or completion --evidence-bundle',
+    resolve: false,
+    risk: 'low',
+  },
+  {
+    arg: '--from-style-pack',
+    option: 'fromStylePack',
+    commands: ['evals'],
+    requiredMessage: '--from-style-pack requires a local Stage 138 style pack JSON file',
+    unsupportedMessage: '--from-style-pack is only supported by evals --local-behavior-contracts',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-entry-tightening',
+    option: 'fromEntryTightening',
+    commands: ['evals'],
+    requiredMessage: '--from-entry-tightening requires a local Stage 141 entry tightening JSON file',
+    unsupportedMessage: '--from-entry-tightening is only supported by evals --local-behavior-contracts',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-discipline',
+    option: 'fromDiscipline',
+    commands: ['workflow'],
+    requiredMessage: '--from-discipline requires a local Stage 135 entry discipline JSON file',
+    unsupportedMessage: '--from-discipline is only supported by workflow --entry-tightening',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-scorecard',
+    option: 'fromScorecard',
+    commands: ['workflow', 'tokens', 'governance'],
+    requiredMessage: '--from-scorecard requires a local Stage 140 parity scorecard JSON file',
+    unsupportedMessage: '--from-scorecard is only supported by workflow --entry-tightening, tokens --entry-defaults, governance --contributor-guardrails, or governance --subagent-permission',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-evidence-prompts',
+    option: 'fromEvidencePrompts',
+    commands: ['governance'],
+    requiredMessage: '--from-evidence-prompts requires a local Stage 143 evidence prompts JSON file',
+    unsupportedMessage: '--from-evidence-prompts is only supported by governance --contributor-guardrails',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-guardrails',
+    option: 'fromGuardrails',
+    commands: ['governance'],
+    requiredMessage: '--from-guardrails requires a local Stage 146 contributor guardrails JSON file',
+    unsupportedMessage: '--from-guardrails is only supported by governance --subagent-permission',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-comparison',
+    option: 'fromComparison',
+    commands: ['evals', 'governance'],
+    requiredMessage: '--from-comparison requires a local Superpowers comparison JSON file',
+    unsupportedMessage: '--from-comparison is only supported by evals --superpowers-style-pack, governance --experience-upgrades, or governance --superpowers-parity-scorecard',
+    resolve: false,
+    risk: 'low',
+  },
+  {
+    arg: '--from-dashboard',
+    option: 'fromDashboard',
+    commands: ['governance', 'workflow'],
+    requiredMessage: '--from-dashboard requires a local Stage 132 experience dashboard JSON file',
+    unsupportedMessage: '--from-dashboard is only supported by governance --experience-upgrades or workflow --next-evidence-prompts',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-install-experience',
+    option: 'fromInstallExperience',
+    commands: ['governance', 'platforms'],
+    requiredMessage: '--from-install-experience requires a local Stage 137 install experience JSON file',
+    unsupportedMessage: '--from-install-experience is only supported by governance --experience-upgrades, governance --superpowers-parity-scorecard, or platforms --session-start-examples',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-shape',
+    option: 'fromShape',
+    commands: ['platforms'],
+    requiredMessage: '--from-shape requires a local Stage 134 session-start shape JSON file',
+    unsupportedMessage: '--from-shape is only supported by platforms --session-start-examples',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-entry-discipline',
+    option: 'fromEntryDiscipline',
+    commands: ['governance'],
+    requiredMessage: '--from-entry-discipline requires a local Stage 135 entry discipline JSON file',
+    unsupportedMessage: '--from-entry-discipline is only supported by governance --superpowers-parity-scorecard',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--evidence-file',
+    option: 'evidenceFile',
+    commands: ['workflow'],
+    requiredMessage: '--evidence-file requires a local evidence JSON file',
+    unsupportedMessage: '--evidence-file is only supported by workflow --next-evidence',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--diff-file',
+    option: 'diffFile',
+    commands: ['workflow'],
+    requiredMessage: '--diff-file requires a local diff file',
+    unsupportedMessage: '--diff-file is only supported by workflow --next-evidence',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--review-file',
+    option: 'reviewFile',
+    commands: ['workflow'],
+    requiredMessage: '--review-file requires a local review JSON file',
+    unsupportedMessage: '--review-file is only supported by workflow --next-evidence',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--tdd-file',
+    option: 'tddFile',
+    commands: ['workflow'],
+    requiredMessage: '--tdd-file requires a local TDD trace JSON file',
+    unsupportedMessage: '--tdd-file is only supported by workflow --next-evidence',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--verify-gate',
+    option: 'releaseGateFile',
+    flagOption: 'releaseVerifyGate',
+    commands: ['release'],
+    requiredMessage: '--verify-gate requires a release gate file',
+    unsupportedMessage: '--verify-gate is only supported by release',
+    resolve: false,
+    risk: 'low',
+  },
+  {
+    arg: '--verify-notes',
+    option: 'releaseNotesFile',
+    flagOption: 'releaseVerifyNotes',
+    commands: ['release'],
+    requiredMessage: '--verify-notes requires a release notes file',
+    unsupportedMessage: '--verify-notes is only supported by release',
+    resolve: false,
+    risk: 'low',
+  },
+];

package/tools/vibe-runtime/runtime-cli-evidence-options.mjs

@@ -0,0 +1,28 @@
+import path from 'node:path';
+import { runtimeCliEvidenceOptionSpecs } from './runtime-cli-evidence-option-specs.mjs';
+
+function requireValue(argv, index, message) {
+  const value = argv[index + 1];
+  if (!value) throw new Error(message);
+  return value;
+}
+
+function ensureCommand(options, commands, message) {
+  if (!commands.includes(options.command)) throw new Error(message);
+}
+
+function assignEvidenceOption(options, spec, value) {
+  if (spec.flagOption) options[spec.flagOption] = true;
+  options[spec.option] = spec.resolve ? path.resolve(value) : value;
+}
+
+export function parseLowRiskRuntimeCliEvidenceOption(options, argv, index) {
+  const arg = argv[index];
+  const spec = runtimeCliEvidenceOptionSpecs.find((candidate) => candidate.arg === arg);
+  if (!spec) return { handled: false, index };
+
+  const value = requireValue(argv, index, spec.requiredMessage);
+  ensureCommand(options, spec.commands, spec.unsupportedMessage);
+  assignEvidenceOption(options, spec, value);
+  return { handled: true, index: index + 1 };
+}

package/tools/vibe-runtime/runtime-cli-from-options.mjs

@@ -0,0 +1,222 @@
+import path from 'node:path';
+
+const runtimeCliFromOptionContractSyncSurface = 'runtime-cli-usage runtime-cli-args JSON envelope artifact schema';
+
+export const runtimeCliFromOptionSpecs = [
+  {
+    arg: '--from-product-discovery',
+    option: 'fromProductDiscovery',
+    commands: ['completion'],
+    requiredMessage: '--from-product-discovery requires a local product discovery artifact',
+    unsupportedMessage: '--from-product-discovery is only supported by completion --evidence-bundle',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-product-spec',
+    option: 'fromProductSpec',
+    commands: ['completion'],
+    requiredMessage: '--from-product-spec requires a local product spec artifact',
+    unsupportedMessage: '--from-product-spec is only supported by completion --evidence-bundle',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-ui-design',
+    option: 'fromUiDesign',
+    commands: ['completion'],
+    requiredMessage: '--from-ui-design requires a local UI design contract artifact',
+    unsupportedMessage: '--from-ui-design is only supported by completion --evidence-bundle',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-architecture',
+    option: 'fromArchitecture',
+    commands: ['completion'],
+    requiredMessage: '--from-architecture requires a local architecture design artifact',
+    unsupportedMessage: '--from-architecture is only supported by completion --evidence-bundle',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-traceability',
+    option: 'fromTraceability',
+    commands: ['completion'],
+    requiredMessage: '--from-traceability requires a local delivery traceability artifact',
+    unsupportedMessage: '--from-traceability is only supported by completion --evidence-bundle',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-scenarios',
+    option: 'fromScenarios',
+    commands: ['completion'],
+    requiredMessage: '--from-scenarios requires a local scenario acceptance artifact',
+    unsupportedMessage: '--from-scenarios is only supported by completion --evidence-bundle',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-product-acceptance',
+    option: 'fromProductAcceptance',
+    commands: ['completion'],
+    requiredMessage: '--from-product-acceptance requires a local product acceptance artifact',
+    unsupportedMessage: '--from-product-acceptance is only supported by completion --evidence-bundle',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-test-evidence',
+    option: 'fromTestEvidence',
+    commands: ['completion'],
+    requiredMessage: '--from-test-evidence requires a local test evidence file',
+    unsupportedMessage: '--from-test-evidence is only supported by completion --evidence-bundle',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-diff-coverage',
+    option: 'fromDiffCoverage',
+    commands: ['completion', 'release'],
+    requiredMessage: '--from-diff-coverage requires a local diff coverage file',
+    unsupportedMessage: '--from-diff-coverage is only supported by completion --evidence-bundle or release --closeout-readiness',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-commit-readiness',
+    option: 'fromCommitReadiness',
+    commands: ['completion'],
+    requiredMessage: '--from-commit-readiness requires a local commit readiness file',
+    unsupportedMessage: '--from-commit-readiness is only supported by completion --evidence-bundle',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-plan',
+    option: 'fromPlan',
+    commands: ['completion', 'sdd', 'workspace'],
+    requiredMessage: '--from-plan requires a scheduler hook plan file, planner plan file, local plan file, or completion evidence plan file',
+    unsupportedMessage: '--from-plan is only supported by verification --evidence-intake, verification --tdd-trace, release --diff-coverage, review --intake, automation --stage-runbook, subagents, planner, sdd, workspace, or completion --evidence-bundle',
+    resolve: false,
+    risk: 'low',
+    deferUnsupported: true,
+  },
+  {
+    arg: '--from-friction',
+    option: 'fromFriction',
+    commands: ['workflow', 'tokens', 'learning', 'governance'],
+    requiredMessage: '--from-friction requires a local Stage 126 friction JSON file',
+    unsupportedMessage: '--from-friction is only supported by workflow --next-action-console, tokens --savior-budget, learning --experience-pattern, or governance --experience-dashboard',
+    resolve: false,
+    risk: 'low',
+  },
+  {
+    arg: '--from-console',
+    option: 'fromConsole',
+    commands: ['automation', 'governance', 'workflow'],
+    requiredMessage: '--from-console requires a local Stage 127 console JSON file',
+    unsupportedMessage: '--from-console is only supported by automation --stage-scriptlet, governance --experience-dashboard, or workflow --next-evidence-prompts',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-token-budget',
+    option: 'fromTokenBudget',
+    commands: ['governance'],
+    requiredMessage: '--from-token-budget requires a local Stage 128 token budget JSON file',
+    unsupportedMessage: '--from-token-budget is only supported by governance --experience-dashboard',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-budget',
+    option: 'fromBudget',
+    commands: ['tokens'],
+    requiredMessage: '--from-budget requires a local Stage 128 token budget JSON file',
+    unsupportedMessage: '--from-budget is only supported by tokens --entry-defaults',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-learning-pattern',
+    option: 'fromLearningPattern',
+    commands: ['governance'],
+    requiredMessage: '--from-learning-pattern requires a local Stage 129 learning pattern JSON file',
+    unsupportedMessage: '--from-learning-pattern is only supported by governance --experience-dashboard',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-bootstrap-matrix',
+    option: 'fromBootstrapMatrix',
+    commands: ['platforms'],
+    requiredMessage: '--from-bootstrap-matrix requires a local Stage 122 bootstrap matrix JSON file',
+    unsupportedMessage: '--from-bootstrap-matrix is only supported by platforms --install-experience or platforms --adapter-packaging-consistency',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-entry-acceptance',
+    option: 'fromEntryAcceptance',
+    commands: ['platforms'],
+    requiredMessage: '--from-entry-acceptance requires a local Stage 131 entry acceptance JSON file',
+    unsupportedMessage: '--from-entry-acceptance is only supported by platforms --install-experience',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-session-examples',
+    option: 'fromSessionExamples',
+    commands: ['platforms'],
+    requiredMessage: '--from-session-examples requires a local Stage 142 session-start examples JSON file',
+    unsupportedMessage: '--from-session-examples is only supported by platforms --adapter-packaging-consistency',
+    resolve: true,
+    risk: 'low',
+  },
+  {
+    arg: '--from-upgrades',
+    option: 'fromUpgrades',
+    commands: ['governance', 'workflow'],
+    requiredMessage: '--from-upgrades requires a local Stage 139 experience upgrades JSON file',
+    unsupportedMessage: '--from-upgrades is only supported by governance --superpowers-parity-scorecard or workflow --next-evidence-prompts',
+    resolve: true,
+    risk: 'low',
+  },
+];
+
+function requireValue(argv, index, message) {
+  const value = argv[index + 1];
+  if (!value) throw new Error(message);
+  return value;
+}
+
+function ensureCommand(options, commands, message) {
+  if (!commands.includes(options.command)) throw new Error(message);
+}
+
+function assignFromOption(options, spec, value) {
+  const releaseCloseoutLocalFile = options.command === 'release' && spec.option === 'fromDiffCoverage';
+  options[spec.option] = spec.resolve && !releaseCloseoutLocalFile ? path.resolve(value) : value;
+}
+
+function assertRuntimeCliFromOptionContractSurface() {
+  if (!runtimeCliFromOptionContractSyncSurface.includes('runtime-cli-args')) {
+    throw new Error('runtime CLI from-option contract marker missing');
+  }
+}
+
+export function parseLowRiskRuntimeCliFromOption(options, argv, index) {
+  assertRuntimeCliFromOptionContractSurface();
+
+  const arg = argv[index];
+  const spec = runtimeCliFromOptionSpecs.find((candidate) => candidate.arg === arg);
+  if (!spec) return { handled: false, index };
+  if (spec.deferUnsupported && !spec.commands.includes(options.command)) return { handled: false, index };
+
+  const value = requireValue(argv, index, spec.requiredMessage);
+  ensureCommand(options, spec.commands, spec.unsupportedMessage);
+  assignFromOption(options, spec, value);
+  return { handled: true, index: index + 1 };
+}

package/tools/vibe-runtime/runtime-cli-low-risk-option-specs.mjs

@@ -0,0 +1,128 @@
+const runtimeCliOptionHandlerContractSyncSurface = 'runtime-cli-usage runtime-cli-args';
+
+export const singleCommandFlags = Object.freeze({
+  '--gates': ['readiness', 'readinessGates', '--gates is only supported by readiness'],
+  '--contract': ['entry', 'entryContract', '--contract is only supported by entry'],
+  '--cockpit': ['workflow', 'workflowCockpit', '--cockpit is only supported by workflow'],
+  '--receipt': ['workflow', 'workflowReceipt', '--receipt is only supported by workflow'],
+  '--start': ['workflow', 'workflowStart', '--start is only supported by workflow'],
+  '--run-plan': ['workflow', 'workflowRunPlan', '--run-plan is only supported by workflow'],
+  '--entry-summary': ['workflow', 'workflowEntrySummary', '--entry-summary is only supported by workflow'],
+  '--entry-ux': ['workflow', 'workflowEntryUx', '--entry-ux is only supported by workflow'],
+  '--entry-discipline': ['workflow', 'workflowEntryDiscipline', '--entry-discipline is only supported by workflow'],
+  '--entry-tightening': ['workflow', 'workflowEntryTightening', '--entry-tightening is only supported by workflow'],
+  '--next-action-console': ['workflow', 'workflowNextActionConsole', '--next-action-console is only supported by workflow'],
+  '--next-evidence-prompts': ['workflow', 'workflowNextEvidencePrompts', '--next-evidence-prompts is only supported by workflow'],
+  '--sequence': ['workflow', 'workflowSequence', '--sequence is only supported by workflow'],
+  '--loop-contract': ['workflow', 'workflowLoopContract', '--loop-contract is only supported by workflow'],
+  '--close-loop-dashboard': ['workflow', 'workflowCloseLoopDashboard', '--close-loop-dashboard is only supported by workflow'],
+  '--close-loop': ['workflow', 'workflowCloseLoop', '--close-loop is only supported by workflow'],
+  '--next-evidence': ['workflow', 'workflowNextEvidence', '--next-evidence is only supported by workflow'],
+  '--evidence-bundle': ['completion', 'completionEvidenceBundle', '--evidence-bundle is only supported by completion'],
+  '--repair-plan': ['completion', 'completionRepairPlan', '--repair-plan is only supported by completion'],
+  '--brief': ['onboarding', 'onboardingBrief', '--brief is only supported by onboarding'],
+  '--acceptance': ['bootstrap', 'bootstrapAcceptance', '--acceptance is only supported by bootstrap'],
+  '--savior-budget': ['tokens', 'tokensSaviorBudget', '--savior-budget is only supported by tokens'],
+  '--entry-defaults': ['tokens', 'tokensEntryDefaults', '--entry-defaults is only supported by tokens'],
+  '--compact-output': ['tokens', 'tokensCompactOutput', '--compact-output is only supported by tokens'],
+  '--metrics': ['tokens', 'tokensMetrics', '--metrics is only supported by tokens'],
+  '--rewrite-preview': ['tokens', 'tokensRewritePreview', '--rewrite-preview is only supported by tokens'],
+  '--surface': ['governance', 'governanceSurface', '--surface is only supported by governance'],
+  '--drift-guard': ['governance', 'governanceSurfaceDriftGuard', '--drift-guard is only supported by governance --surface'],
+  '--compatibility': ['governance', 'governanceCompatibility', '--compatibility is only supported by governance'],
+  '--convergence': ['governance', 'governanceConvergence', '--convergence is only supported by governance'],
+  '--superpowers-gap': ['governance', 'governanceSuperpowersGap', '--superpowers-gap is only supported by governance'],
+  '--superpowers-comparison': ['governance', 'governanceSuperpowersComparison', '--superpowers-comparison is only supported by governance'],
+  '--superpowers-regression-guard': ['governance', 'governanceSuperpowersRegressionGuard', '--superpowers-regression-guard is only supported by governance'],
+  '--experience-friction': ['governance', 'governanceExperienceFriction', '--experience-friction is only supported by governance'],
+  '--experience-dashboard': ['governance', 'governanceExperienceDashboard', '--experience-dashboard is only supported by governance'],
+  '--experience-upgrades': ['governance', 'governanceExperienceUpgrades', '--experience-upgrades is only supported by governance'],
+  '--superpowers-parity-scorecard': ['governance', 'governanceSuperpowersParityScorecard', '--superpowers-parity-scorecard is only supported by governance'],
+  '--contributor-guardrails': ['governance', 'governanceContributorGuardrails', '--contributor-guardrails is only supported by governance'],
+  '--subagent-permission': ['governance', 'governanceSubagentPermission', '--subagent-permission is only supported by governance'],
+  '--traceability-map': ['governance', 'governanceTraceabilityMap', '--traceability-map is only supported by governance'],
+  '--pr-readiness': ['governance', 'governancePrReadiness', '--pr-readiness is only supported by governance'],
+  '--pr-review-intake': ['governance', 'governancePrReviewIntake', '--pr-review-intake is only supported by governance'],
+  '--report': ['governance', 'governanceReport', '--report is only supported by governance compatibility or convergence'],
+  '--coverage-map': ['methodology', 'methodologyCoverageMap', '--coverage-map is only supported by methodology'],
+  '--behavior-contract': ['evals', 'evalsBehaviorContract', '--behavior-contract is only supported by evals'],
+  '--transcript-intake': ['evals', 'evalsTranscriptIntake', '--transcript-intake is only supported by evals'],
+  '--superpowers-style-pack': ['evals', 'evalsSuperpowersStylePack', '--superpowers-style-pack is only supported by evals'],
+  '--local-behavior-contracts': ['evals', 'evalsLocalBehaviorContracts', '--local-behavior-contracts is only supported by evals'],
+  '--commit-guard': ['release', 'releaseCommitGuard', '--commit-guard is only supported by release'],
+  '--commit-readiness': ['release', 'releaseCommitReadiness', '--commit-readiness is only supported by release'],
+  '--staged-commit-readiness': ['release', 'releaseStagedCommitReadiness', '--staged-commit-readiness is only supported by release'],
+  '--local-commit-gate': ['release', 'releaseLocalCommitGate', '--local-commit-gate is only supported by release'],
+  '--closeout-readiness': ['release', 'releaseCloseoutReadiness', '--closeout-readiness is only supported by release'],
+  '--task-commit-readiness': ['release', 'releaseTaskCommitReadiness', '--task-commit-readiness is only supported by release'],
+  '--task-commit': ['release', 'releaseTaskCommit', '--task-commit is only supported by release'],
+  '--worker-plan': ['daemon', 'daemonWorkerPlan', '--worker-plan is only supported by daemon'],
+  '--diff-coverage': ['release', 'releaseDiffCoverage', '--diff-coverage is only supported by release'],
+  '--diff-read': ['release', 'releaseDiffRead', '--diff-read is only supported by release'],
+  '--suite-plan': ['release', 'releaseSuitePlan', '--suite-plan is only supported by release'],
+  '--with-convergence': ['release', 'releaseWithConvergence', '--with-convergence is only supported by release'],
+  '--notes': ['release', 'releaseNotes', '--notes is only supported by release'],
+  '--lint': ['planner', 'plannerLint', '--lint is only supported by planner'],
+  '--action-manifest': ['planner', 'plannerActionManifest', '--action-manifest is only supported by planner'],
+  '--executable-plan': ['planner', 'plannerExecutablePlan', '--executable-plan is only supported by planner'],
+  '--self-test-profile': ['verification', 'verificationSelfTestProfile', '--self-test-profile is only supported by verification'],
+  '--evidence-intake': ['verification', 'verificationEvidenceIntake', '--evidence-intake is only supported by verification'],
+  '--execution-evidence': ['verification', 'verificationExecutionEvidence', '--execution-evidence is only supported by verification'],
+  '--tdd-trace': ['verification', 'verificationTddTrace', '--tdd-trace is only supported by verification'],
+  '--intake': ['review', 'reviewIntake', '--intake is only supported by review'],
+  '--resolution': ['review', 'reviewResolution', '--resolution is only supported by review'],
+  '--ledger': ['feedback', 'feedbackLedger', '--ledger is only supported by feedback'],
+  '--one-shot-plan': ['automation', 'automationOneShotPlan', '--one-shot-plan is only supported by automation'],
+  '--stage-runbook': ['automation', 'automationStageRunbook', '--stage-runbook is only supported by automation'],
+  '--stage-scriptlet': ['automation', 'automationStageScriptlet', '--stage-scriptlet is only supported by automation'],
+  '--task-brief': ['sdd', 'sddTaskBrief', '--task-brief is only supported by sdd'],
+  '--review-package': ['sdd', 'sddReviewPackage', '--review-package is only supported by sdd'],
+  '--evidence-chain': ['sdd', 'sddEvidenceChain', '--evidence-chain is only supported by sdd'],
+  '--consume-adapter-result': ['sdd', 'sddConsumeAdapterResult', '--consume-adapter-result is only supported by sdd'],
+  '--isolate-plan': ['workspace', 'workspaceIsolatePlan', '--isolate-plan is only supported by workspace'],
+  '--cleanup-plan': ['workspace', 'workspaceCleanupPlan', '--cleanup-plan is only supported by workspace'],
+});
+
+export const learningFlags = Object.freeze({
+  '--observe': 'learningObserve',
+  '--observe-from-run': 'learningObserveFromRun',
+  '--instincts': 'learningInstincts',
+  '--promote': 'learningPromote',
+  '--experience-pattern': 'learningExperiencePattern',
+});
+
+export const platformFlags = Object.freeze({
+  '--bootstrap-matrix': 'platformsBootstrapMatrix',
+  '--entry-acceptance': 'platformsEntryAcceptance',
+  '--session-start-shape': 'platformsSessionStartShape',
+  '--session-start-examples': 'platformsSessionStartExamples',
+  '--adapter-packaging-consistency': 'platformsAdapterPackagingConsistency',
+  '--install-experience': 'platformsInstallExperience',
+});
+
+export const sharedOptionRouting = Object.freeze({
+  '--advice': Object.freeze({
+    entry: 'entryAdvice',
+    tokens: 'tokensAdvice',
+    learning: 'learningAdvice',
+    governance: 'governanceAdvice',
+  }),
+  '--catalog': Object.freeze({
+    hooks: 'hooksCatalog',
+    platforms: 'platformsCatalog',
+    evals: 'evalsCatalog',
+    policies: 'policyCatalog',
+    tokens: 'tokensCatalog',
+    defaultField: 'methodologyCatalog',
+  }),
+  '--gate': Object.freeze({
+    release: 'releaseGate',
+    defaultField: 'methodologyGate',
+  }),
+});
+
+export function assertRuntimeCliOptionHandlerContractSurface() {
+  if (!runtimeCliOptionHandlerContractSyncSurface.includes('runtime-cli-args')) {
+    throw new Error('runtime CLI option contract sync marker missing');
+  }
+}

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

@@ -0,0 +1,32 @@
+import process from 'node:process';
+import { usage } from './runtime-cli-usage.mjs';
+import { parseArgs } from './runtime-cli-args.mjs';
+import { dispatchRuntimeCommand } from './runtime-cli-dispatch.mjs';
+import { createRuntimeCommandHandlers } from './runtime-command-container.mjs';
+
+export function runRuntimeCli({
+  argv = process.argv.slice(2),
+  handlerDeps,
+  exit = process.exit,
+  log = console.log,
+  error = console.error,
+} = {}) {
+  try {
+    const options = parseArgs(argv);
+
+    if (options.help || !options.command) {
+      log(usage());
+      exit(0);
+      return 0;
+    }
+
+    const handlers = createRuntimeCommandHandlers(handlerDeps);
+    dispatchRuntimeCommand(options, handlers);
+    return 0;
+  } catch (caught) {
+    log(caught.message);
+    error(`Error: ${caught.message}`);
+    exit(1);
+    return 1;
+  }
+}