@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-interaction-completion-command.mjs

@@ -0,0 +1,220 @@
+import path from 'node:path';
+import {
+  completionEvidenceBundleActionText,
+  completionReadinessActionText,
+} from './runtime-completion-boundary-text.mjs';
+import {
+  buildCompletionEvidenceBundleModel,
+  completionEvidenceBundleBoundaryAssertions,
+  completionEvidenceSummary as completionEvidenceSummaryModel,
+  completionReadinessBoundaryAssertions,
+  completionReadinessDiagnosticSummary,
+} from './runtime-human-completion-evidence-model.mjs';
+import {
+  buildEvidenceRepairPlan,
+  printEvidenceRepairPlan,
+} from './runtime-evidence-repair-model.mjs';
+
+const completionSurfaceNames = Object.freeze([
+  'runCompletion',
+  'completionReadinessEnvelope',
+  'completionEvidenceBundleEnvelope',
+  'completionEvidenceRepairPlanEnvelope',
+]);
+
+const readonlyRuntimeFlags = Object.freeze([
+  'confirm',
+  'write',
+  'dryRun',
+  'recoveryPreview',
+  'hooksPreview',
+  'dispatch',
+  'dispatchIntent',
+  'run',
+  'autoRun',
+  'scan',
+  'once',
+  'preflight',
+]);
+
+export const runtimeInteractionCompletionCommandOwner = Object.freeze({
+  owner: 'runtime-interaction-completion-command',
+  domain: 'completion',
+  layer: 'commandWrapper',
+  risk: 'medium',
+  migration_state: 'read-only-wrapper',
+  behavior_change: false,
+  eager_import_behavior: 'unchanged',
+  dispatch_behavior: 'unchanged',
+  state_semantics: 'unchanged',
+  product_completion_bridge: 'delegated-unchanged',
+  surface_names: completionSurfaceNames,
+});
+
+export function runtimeInteractionCompletionSurfaceNames() {
+  return [...completionSurfaceNames];
+}
+
+function rejectRuntimeFlags(options, message) {
+  if (readonlyRuntimeFlags.some((flag) => options[flag])) throw new Error(message);
+}
+
+function completionEvidenceSummary({ root, evidenceFile, localTextEvidenceDescriptor }) {
+  if (!evidenceFile) return completionEvidenceSummaryModel();
+  const source = localTextEvidenceDescriptor(root, evidenceFile, 'completion --readiness evidence');
+  return completionEvidenceSummaryModel({ text: source.text, source });
+}
+
+export function createRuntimeInteractionCompletionCommands(deps = {}) {
+  const {
+    ensureRoot,
+    workflowPath,
+    fileExists,
+    localTextEvidenceDescriptor,
+    runtimeCapabilityRegistry,
+    digestObject,
+    writeJsonEnvelope,
+    printList,
+    completionPresentation,
+    hasProductCompletionEvidenceInputs,
+    runProductCompletionEvidenceBundleCommand,
+    localJsonFileWithinRoot,
+    stateDirectory,
+    writeStateArtifact,
+  } = deps;
+
+  function completionReadinessEnvelope(root, { evidenceFile = '' } = {}) {
+    ensureRoot(root);
+    const evidence = completionEvidenceSummary({ root, evidenceFile, localTextEvidenceDescriptor });
+    const blocked = [...new Set([
+      ...(evidence.verification_evidence.length === 0 ? ['fresh verification evidence is missing'] : []),
+      ...evidence.unverified_items.map((item) => `unverified: ${item}`),
+      ...(evidence.review_feedback_status === 'unresolved' ? ['review feedback is unresolved'] : []),
+      ...(evidence.release_boundary_summary.includes('without clear manual authorization') ? ['git/PR/release boundary requires explicit human authorization'] : []),
+    ])];
+    const diagnosticSummary = completionReadinessDiagnosticSummary({
+      blockedReasons: blocked,
+      evidenceStatus: evidence.status,
+    });
+    const boundaryAssertions = completionReadinessBoundaryAssertions();
+    const readiness = {
+      version: 1,
+      stage: 'Stage 88',
+      readiness_kind: 'completion-readiness',
+      evidence_file: evidence.evidence_file,
+      evidence_digest: evidence.evidence_digest,
+      evidence_status: evidence.status,
+      ready_to_report_done: blocked.length === 0,
+      verification_evidence: evidence.verification_evidence,
+      unverified_items: evidence.unverified_items,
+      review_feedback_status: evidence.review_feedback_status,
+      git_boundary_summary: 'read-only declaration only; no git command was executed by completion readiness',
+      release_boundary_summary: evidence.release_boundary_summary,
+      blocked_reasons: blocked,
+      diagnostic_summary: diagnosticSummary,
+      readiness_ok: diagnosticSummary.ok,
+      diagnostic_status: diagnosticSummary.status,
+      manual_action: blocked.length === 0 ? 'You may report completion with the listed verification evidence and no implied git/PR/release action.' : 'Do not claim completion yet; resolve missing verification, unresolved review feedback, or authorization gaps first.',
+      boundary_assertions: boundaryAssertions,
+      writes: false,
+      state_directory_created: false,
+      local_only: true,
+      deterministic: true,
+    };
+    return {
+      mode: 'completion-readiness',
+      ok: true,
+      state_present: fileExists(workflowPath(root)),
+      completion_readiness: { ...readiness, readiness_digest: digestObject(readiness) },
+      safety: { stage: 'Stage 88', ...boundaryAssertions },
+      quality: blocked,
+      action: completionReadinessActionText(),
+    };
+  }
+
+  function completionEvidenceBundleEnvelope(root, { evidenceFile = '' } = {}) {
+    ensureRoot(root);
+    const readinessEnvelope = completionReadinessEnvelope(root, { evidenceFile });
+    const readiness = readinessEnvelope.completion_readiness;
+    const boundaryAssertions = completionEvidenceBundleBoundaryAssertions(completionReadinessBoundaryAssertions());
+    const bundle = buildCompletionEvidenceBundleModel({
+      readiness,
+      registry: runtimeCapabilityRegistry(),
+      boundaryAssertions,
+      digestObject,
+    });
+    const humanBundle = bundle.human_completion_evidence_bundle;
+    return {
+      mode: 'completion-evidence-bundle',
+      ok: humanBundle.delivery_gate.pass,
+      state_present: fileExists(workflowPath(root)),
+      completion_evidence_bundle: bundle,
+      completion_readiness: readiness,
+      safety: { stage: 'Stage 124', ...boundaryAssertions },
+      quality: humanBundle.delivery_gate.blockers,
+      action: completionEvidenceBundleActionText(),
+    };
+  }
+
+  function completionEvidenceRepairPlanEnvelope(root, { bundleFile = '', persist = false } = {}) {
+    ensureRoot(root);
+    const source = localJsonFileWithinRoot(root, bundleFile, 'completion --repair-plan --from-file');
+    return buildEvidenceRepairPlan({
+      input: source.data,
+      source,
+      statePresent: fileExists(stateDirectory(root)),
+      persist,
+      digestObject,
+    });
+  }
+
+  function writeEvidenceRepairPlan(root, envelope) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const fileName = `${stamp}.evidence-repair-plan.json`;
+    const payload = { schema_version: 1, command: 'completion', ...envelope };
+    return writeStateArtifact(path.join(stateDirectory(root), 'evidence-repairs'), fileName, payload);
+  }
+
+  function runCompletion(options) {
+    ensureRoot(options.root);
+    const modes = [options.completionReadiness, options.completionEvidenceBundle, options.completionRepairPlan].filter(Boolean);
+    if (modes.length !== 1) throw new Error('completion requires exactly one mode: --readiness, --evidence-bundle, or --repair-plan');
+    if (!options.completionRepairPlan) rejectRuntimeFlags(options, 'completion --readiness is read-only; completion read-only modes do not accept execution, dispatch, preview, confirm, write, scan, or preflight flags');
+    if (options.completionRepairPlan && (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('completion --repair-plan only accepts --from-file, optional --confirm, and output flags');
+    if (options.methodologyIntent || options.fromReadiness || options.learningObservationFiles.length > 0 || options.learningInstinctFile || options.tokenCompactionFiles.length > 0 || options.methodologyKind || options.methodologyFile) throw new Error('completion modes do not accept intent, concrete sidecar, methodology gate, or audit input files');
+    if (options.completionRepairPlan) {
+      if (!options.fromFile) throw new Error('completion --repair-plan requires --from-file <local-completion-bundle-json>');
+      if (options.fromProductDiscovery || options.fromProductSpec || options.fromUiDesign || options.fromArchitecture || options.fromTraceability || options.fromScenarios || options.fromProductAcceptance || options.fromEvidence || options.fromPlan || options.fromTestEvidence || options.fromDiffCoverage || options.fromCommitReadiness) throw new Error('completion --repair-plan only accepts one local bundle file and optional --confirm');
+      const envelope = completionEvidenceRepairPlanEnvelope(options.root, { bundleFile: options.fromFile, persist: options.confirm });
+      if (options.confirm) {
+        const file = writeEvidenceRepairPlan(options.root, envelope);
+        const response = { ...envelope, evidence_repair_file: path.basename(file) };
+        if (options.json) writeJsonEnvelope('completion', response);
+        else printEvidenceRepairPlan(response, { printList });
+        return;
+      }
+      if (options.json) writeJsonEnvelope('completion', envelope);
+      else printEvidenceRepairPlan(envelope, { printList });
+      return;
+    }
+    if (!options.completionEvidenceBundle && (options.fromProductDiscovery || options.fromProductSpec || options.fromUiDesign || options.fromScenarios || options.fromProductAcceptance || options.fromEvidence)) throw new Error('product/UI evidence inputs are only supported by completion --evidence-bundle');
+    if (options.completionEvidenceBundle && hasProductCompletionEvidenceInputs(options)) {
+      runProductCompletionEvidenceBundleCommand({ writeJsonEnvelope, printList }, options);
+      return;
+    }
+    if (options.completionEvidenceBundle) {
+      const envelope = completionEvidenceBundleEnvelope(options.root, { evidenceFile: options.fromFile || '' });
+      if (options.json) writeJsonEnvelope('completion', envelope);
+      else completionPresentation.printCompletionEvidenceBundle(envelope);
+      return;
+    }
+    const envelope = completionReadinessEnvelope(options.root, { evidenceFile: options.fromFile || '' });
+    if (options.json) writeJsonEnvelope('completion', envelope);
+    else completionPresentation.printCompletionReadiness(envelope);
+  }
+
+  const commands = { runCompletion, completionReadinessEnvelope, completionEvidenceBundleEnvelope, completionEvidenceRepairPlanEnvelope };
+  const missing = completionSurfaceNames.filter((name) => typeof commands[name] !== 'function');
+  if (missing.length > 0) throw new Error(`completion command owner missing surface(s): ${missing.join(', ')}`);
+  return Object.freeze(commands);
+}

package/tools/vibe-runtime/runtime-interaction-entry-command.mjs

@@ -0,0 +1,130 @@
+const entryWorkflowSurfaceNames = Object.freeze([
+  'runBootstrap',
+  'runOnboarding',
+  'runAdvice',
+  'runEntry',
+  'humanFriendlyCloseLoopEnvelope',
+  'humanFriendlyNextEvidenceEnvelope',
+  'workflowReadinessEnvelope',
+  'workflowCockpitEnvelope',
+  'workflowReceiptEnvelope',
+  'workflowStartEnvelope',
+  'progressiveEntryUxEnvelope',
+  'workflowSequenceEnvelope',
+  'workflowLoopContractEnvelope',
+  'entryTriggerDisciplineEnvelope',
+  'closeLoopDashboardEnvelope',
+]);
+
+const readonlyRuntimeFlags = Object.freeze([
+  'write',
+  'confirm',
+  'dryRun',
+  'recoveryPreview',
+  'hooksPreview',
+  'dispatch',
+  'dispatchIntent',
+  'fromDispatch',
+  'run',
+  'autoRun',
+  'scan',
+  'once',
+  'preflight',
+]);
+
+export const runtimeInteractionEntryCommandOwner = Object.freeze({
+  owner: 'runtime-interaction-entry-command',
+  domain: 'entryWorkflow',
+  layer: 'commandWrapper',
+  risk: 'low',
+  migration_state: 'partial-wrapper',
+  behavior_change: false,
+  eager_import_behavior: 'unchanged',
+  dispatch_behavior: 'unchanged',
+  state_semantics: 'unchanged',
+  surface_names: entryWorkflowSurfaceNames,
+});
+
+export function runtimeInteractionEntrySurfaceNames() {
+  return [...entryWorkflowSurfaceNames];
+}
+
+function rejectRuntimeFlags(options, message, flags = readonlyRuntimeFlags) {
+  if (flags.some((flag) => options[flag])) throw new Error(message);
+}
+
+function rejectConcreteInputs(options, message) {
+  if (options.fromFile || options.fromReadiness || options.learningObservationFiles.length > 0 || options.learningInstinctFile || options.tokenCompactionFiles.length > 0) throw new Error(message);
+}
+
+export function createRuntimeInteractionEntryCommands(deps = {}) {
+  const {
+    ensureRoot,
+    entryPresentation,
+    bootstrapAcceptanceEnvelope,
+    onboardingBriefEnvelope,
+    adviceHubEnvelope,
+    entryAdviceEnvelope,
+    entryContractEnvelope,
+    ...surfaces
+  } = deps;
+  const jsonWriter = deps['writeJson' + 'Envelope'];
+
+  function runBootstrap(options) {
+    ensureRoot(options.root);
+    const modes = [options.bootstrapAcceptance].filter(Boolean);
+    if (modes.length !== 1) throw new Error('bootstrap requires exactly one mode: --acceptance');
+    rejectRuntimeFlags(options, 'bootstrap --acceptance is read-only and does not accept execution, dispatch, preview, confirm, write, scan, or preflight flags', readonlyRuntimeFlags.filter((flag) => flag !== 'fromDispatch'));
+    if (options.fromFile || options.methodologyIntent || options.fromReadiness || options.learningObservationFiles.length > 0 || options.learningInstinctFile || options.tokenCompactionFiles.length > 0 || options.methodologyKind || options.methodologyFile) throw new Error('bootstrap --acceptance only accepts --prompt plus read-only output flags');
+    const envelope = bootstrapAcceptanceEnvelope(options.root, { prompt: options.prompt });
+    if (options.json) jsonWriter('bootstrap', envelope);
+    else entryPresentation.printBootstrapAcceptance(envelope);
+  }
+
+  function runOnboarding(options) {
+    ensureRoot(options.root);
+    if (!options.onboardingBrief) throw new Error('onboarding requires --brief');
+    rejectRuntimeFlags(options, 'onboarding --brief is read-only and does not accept execution, dispatch, preview, confirm, write, scan, or preflight flags', readonlyRuntimeFlags.filter((flag) => flag !== 'fromDispatch'));
+    if (options.fromFile || options.prompt || options.methodologyIntent || options.fromReadiness || options.learningObservationFiles.length > 0 || options.learningInstinctFile || options.tokenCompactionFiles.length > 0 || options.methodologyKind || options.methodologyFile) throw new Error('onboarding --brief does not accept prompt, files, sidecars, methodology gates, or audit inputs');
+    const envelope = onboardingBriefEnvelope(options.root);
+    if (options.json) jsonWriter('onboarding', envelope);
+    else entryPresentation.printOnboardingBrief(envelope);
+  }
+
+  function runAdvice(options) {
+    ensureRoot(options.root);
+    const modes = [options.adviceHub].filter(Boolean);
+    if (modes.length !== 1) throw new Error('advice requires exactly one mode: --hub');
+    rejectRuntimeFlags(options, 'advice --hub is read-only and does not accept execution, dispatch, preview, confirm, or write flags');
+    rejectConcreteInputs(options, 'advice --hub does not accept concrete evidence or sidecar input files');
+    const envelope = adviceHubEnvelope(options.root, { intent: options.methodologyIntent });
+    if (options.json) jsonWriter('advice', envelope);
+    else entryPresentation.printAdviceHub(envelope);
+  }
+
+  function runEntry(options) {
+    rejectRuntimeFlags(options, 'entry advice and contract are read-only');
+    ensureRoot(options.root);
+    const modes = [options.entryAdvice, options.entryContract].filter(Boolean);
+    if (modes.length !== 1) throw new Error('entry requires exactly one mode: --advice or --contract');
+    if (options.profile && !['default', 'superpowers-parity'].includes(options.profile)) throw new Error('entry --profile must be default or superpowers-parity');
+    if (options.entryAdvice) {
+      if (!options.methodologyIntent) throw new Error('entry --advice requires --intent <kind>');
+      if (options.prompt) throw new Error('entry --advice does not accept --prompt; use --intent or entry --contract');
+      const envelope = entryAdviceEnvelope(options.root, options.methodologyIntent);
+      if (options.json) jsonWriter('entry', envelope);
+      else entryPresentation.printEntryAdvice(envelope);
+      return;
+    }
+    if (!options.methodologyIntent && !options.prompt) throw new Error('entry --contract requires --intent <kind> or --prompt <text>');
+    if (options.fromFile || options.fromReadiness || options.learningObservationFiles.length > 0 || options.learningInstinctFile || options.tokenCompactionFiles.length > 0 || options.methodologyKind || options.methodologyFile) throw new Error('entry --contract does not accept files, sidecars, methodology gates, or audit inputs');
+    const envelope = entryContractEnvelope(options.root, { intent: options.methodologyIntent, prompt: options.prompt, profile: options.profile });
+    if (options.json) jsonWriter('entry', envelope);
+    else entryPresentation.printEntryContract(envelope);
+  }
+
+  const commands = { ...surfaces, runBootstrap, runOnboarding, runAdvice, runEntry };
+  const missing = entryWorkflowSurfaceNames.filter((name) => typeof commands[name] !== 'function');
+  if (missing.length > 0) throw new Error(`entry/workflow command owner missing surface(s): ${missing.join(', ')}`);
+  return Object.freeze(Object.fromEntries(entryWorkflowSurfaceNames.map((name) => [name, commands[name]])));
+}