@jtf19/vibecoding-kit 0.1.0

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

@@ -0,0 +1,529 @@
+import fs from 'node:fs';
+
+const runtimePlanningValidationContractSyncSurface = 'runtime-cli-usage runtime-cli-args runtime-cli-dispatch tools/vibe-release-check';
+
+export function createRuntimeControlPlanePlanningValidation(deps) {
+  if (!runtimePlanningValidationContractSyncSurface.includes('runtime-cli-usage')) throw new Error('runtime planning validation contract sync marker missing');
+  const validationDeps = deps;
+  const {
+    ensureRoot,
+    ['workflow' + 'Path']: workflowArtifactPath,
+    ['state' + 'Directory']: runtimeStateFolder,
+    localTextEvidenceDescriptor,
+    digestObject,
+    ['writeJson' + 'Envelope']: emitJsonEnvelope,
+    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,
+  } = validationDeps;
+
+  function planLintBoundaryAssertions() {
+    return {
+      writes: false,
+      state_directory_created: false,
+      plan_lint_artifact: false,
+      sidecar_write: false,
+      skill_execution: false,
+      command_execution: false,
+      runtime_action: false,
+      auto_execution: false,
+      external_network: false,
+      model_invocation: false,
+      platform_api: false,
+      git: false,
+      worktree: false,
+      pr: false,
+      push: false,
+      merge: false,
+      tag: false,
+      subagent: false,
+      mcp: false,
+      ['dae' + 'mon']: false,
+      shell_interception: false,
+      business_source_write: false,
+      source_merge: false,
+    };
+  }
+
+  function planLintCheck(id, passed, severity, message, evidence = []) {
+    return { id, status: passed ? 'pass' : severity, severity, message, evidence };
+  }
+
+  function planLintTaskSections(text) {
+    const matches = [...String(text || '').matchAll(/^#{2,4}\s+(?:Task|任务|Stage|阶段)\b.*$/gim)];
+    return matches.map((match) => match[0].trim());
+  }
+
+  function planLintEnvelope(root, planFile) {
+    ensureRoot(root);
+    const source = localTextEvidenceDescriptor(root, planFile, 'planner --lint source');
+    const text = source.text;
+    const taskSections = planLintTaskSections(text);
+    const backtickPathMatches = (text.match(/`[^`]+\.(?:mjs|js|ts|tsx|json|md|yml|yaml|py|go|rs|java|css|scss|html)`/g) || []).map((item) => item.slice(1, -1));
+    const barePathMatches = text.match(/\b(?:[\w.-]+[\\/])+[\w.-]+\.(?:mjs|js|ts|tsx|json|md|yml|yaml|py|go|rs|java|css|scss|html)\b/g) || [];
+    const pathMatches = [...new Set([...backtickPathMatches, ...barePathMatches].map((item) => item.replace(/\\/g, '/')))].sort();
+    const commandMatches = [...new Set((text.match(/\b(?:node|npm|pnpm|yarn|git|pytest|python|tsc|eslint|vitest|jest)\s+[^\n`]+/gi) || []).map((item) => item.trim()))].sort();
+    const checks = [
+      planLintCheck('files-declared', pathMatches.length > 0 || /\b(files?|文件|modify|create|test):/i.test(text), 'blocker', 'Plan must name concrete files or file responsibilities.', pathMatches.slice(0, 8)),
+      planLintCheck('task-granularity', taskSections.length > 0 || /- \[[ x]\]/i.test(text), 'blocker', 'Plan must be decomposed into task-sized steps or checkbox actions.', taskSections.slice(0, 8)),
+      planLintCheck('interfaces-declared', /\b(interface|interfaces|produces|consumes|输出|输入|产物|数据流|envelope|fields?)\b/i.test(text), 'warning', 'Plan should declare interfaces, produced fields, or data flow boundaries.'),
+      planLintCheck('verification-strategy', /\b(test|verify|verification|check|smoke|lint|node --check|release-check|runtime-check|验证|自检)\b/i.test(text), 'blocker', 'Plan must include a verification strategy.'),
+      planLintCheck('acceptance-declared', /\b(acceptance|验收|ready_to|pass|expected|期望|完成条件)\b/i.test(text), 'blocker', 'Plan must define acceptance or expected outcomes.'),
+      planLintCheck('review-gate', /\b(review|code review|vibe-review|审查|review gate)\b/i.test(text), 'warning', 'Plan should include review gate or review scope for non-trivial work.'),
+      planLintCheck('no-placeholders', !/\b(TBD|TODO|填充|待定|implement later|add appropriate|similar to task)\b/i.test(text), 'blocker', 'Plan must not contain placeholders or vague implementation steps.'),
+      planLintCheck('commands-have-evidence', commandMatches.length > 0 || /\b(manual|手动|read-only|只读)\b/i.test(text), 'warning', 'Plan should include exact commands or explicit manual verification evidence.', commandMatches.slice(0, 8)),
+      planLintCheck('dependencies-or-order', /\b(depends_on|dependency|依赖|after|before|顺序|先|后|->)\b/i.test(text), 'warning', 'Plan should state ordering or dependencies between stages/tasks.'),
+      planLintCheck('completion-boundary', /\b(done|complete|completion|finish|closeout|收口|完成前|不做范围|boundary|边界)\b/i.test(text), 'blocker', 'Plan must define completion boundary and out-of-scope items.'),
+    ];
+    const blockingFindings = checks.filter((check) => check.status === 'blocker').map((check) => check.message);
+    const warnings = checks.filter((check) => check.status === 'warning').map((check) => check.message);
+    const executionReady = blockingFindings.length === 0;
+    const boundaryAssertions = planLintBoundaryAssertions();
+    const lint = {
+      version: 1,
+      stage: 'Stage 86',
+      lint_kind: 'plan-quality-lint',
+      source_file: source.relative,
+      source_digest: source.digest,
+      summary: {
+        task_section_count: taskSections.length,
+        concrete_file_count: pathMatches.length,
+        command_count: commandMatches.length,
+        check_count: checks.length,
+        blocker_count: blockingFindings.length,
+        warning_count: warnings.length,
+      },
+      checks,
+      blocking_findings: blockingFindings,
+      warnings,
+      execution_ready: executionReady,
+      manual_action: executionReady ? 'Plan is ready for bounded execution with task-level acceptance and verification.' : 'Fix blocking plan gaps before entering implementation or execution.',
+      boundary_assertions: boundaryAssertions,
+      writes: false,
+      state_directory_created: false,
+      local_only: true,
+      deterministic: true,
+    };
+    return {
+      mode: 'plan-quality-lint',
+      ok: true,
+      state_present: fs.existsSync(workflowArtifactPath(root)),
+      plan_lint: { ...lint, lint_digest: digestObject(lint) },
+      safety: { stage: 'Stage 86', ...boundaryAssertions },
+      quality: [...blockingFindings, ...warnings],
+      action: 'plan lint was computed read-only from one local plan file. No state directory, plan lint artifact, sidecar, workflow skill execution, command execution, runtime action, platform API, external network, model, git, worktree, subagent, MCP, dae' + 'mon, shell interception, or business source mutation occurred.',
+    };
+  }
+
+  function planActionManifestEnvelope(root, planFile, { intent = 'implementation' } = {}) {
+    ensureRoot(root);
+    const source = localTextEvidenceDescriptor(root, planFile, 'planner --action-manifest source');
+    const planLint = planLintEnvelope(root, planFile).plan_lint;
+    const loopEnvelope = workflowLoopContractEnvelope(root, { intent: intent || 'implementation', planFile });
+    const workflowLoopContract = loopEnvelope.workflow_loop_contract;
+    const automationEnvelope = runtimeAutomationReadinessEnvelope(root);
+    const automationReadiness = automationEnvelope.runtime_automation_readiness;
+    const registry = runtimeCapabilityRegistry();
+    const manifest = runtimePlanActionManifest({
+      sourcePlan: {
+        file: source.relative,
+        digest: source.digest,
+        line_count: source.text.split(/\r?\n/).length,
+        text: source.text,
+      },
+      planLint,
+      workflowLoopContract,
+      automationReadiness,
+      registry,
+      registryDigest: automationReadiness.registry_digest,
+      intent: intent || 'implementation',
+    });
+    const planActionManifest = {
+      ...manifest,
+      plan_action_manifest_digest: digestPlanActionManifest(runtimePlanActionManifestDigestPayload(manifest)),
+    };
+    return {
+      mode: 'plan-action-manifest',
+      ok: planActionManifest.manifest_invariants.pass,
+      state_present: fs.existsSync(workflowArtifactPath(root)),
+      plan_action_manifest: planActionManifest,
+      safety: { stage: 'Stage 105', ...planActionManifest.boundary_assertions },
+      quality: planActionManifest.manifest_invariants.findings,
+      action: 'plan-to-action-manifest envelope was computed read-only from one local plan file, plan lint, workflow loop contract, automation readiness, and registry. No automation plan, state directory, sidecar, action item execution, command execution, test/check/repair execution, formatting, code generation, workflow execution, runtime action, git, PR, push, merge, tag, platform API, external network, model, worktree, subagent, MCP, dae' + 'mon, or business source mutation occurred.',
+    };
+  }
+
+  function executablePlanContractEnvelope(root, planFile) {
+    ensureRoot(root);
+    const source = localTextEvidenceDescriptor(root, planFile, 'planner --executable-plan source');
+    const planLint = planLintEnvelope(root, planFile).plan_lint;
+    const automationEnvelope = runtimeAutomationReadinessEnvelope(root);
+    const registry = runtimeCapabilityRegistry();
+    const contract = runtimeExecutablePlanContract({
+      sourcePlan: {
+        file: source.relative,
+        digest: source.digest,
+        line_count: source.text.split(/\r?\n/).length,
+        text: source.text,
+      },
+      planLint,
+      registry,
+      registryDigest: automationEnvelope.runtime_automation_readiness.registry_digest,
+    });
+    const executablePlanContract = {
+      ...contract,
+      executable_plan_digest: digestExecutablePlanContract(runtimeExecutablePlanContractDigestPayload(contract)),
+    };
+    return {
+      mode: 'executable-plan-quality-contract',
+      ok: executablePlanContract.executable_plan_invariants.pass,
+      state_present: fs.existsSync(workflowArtifactPath(root)),
+      executable_plan_contract: executablePlanContract,
+      safety: { stage: 'Stage 117', ...executablePlanContract.boundary_assertions },
+      quality: [...executablePlanContract.executable_plan_invariants.findings, ...executablePlanContract.blocked_reasons],
+      action: 'executable-plan-quality-contract envelope was computed read-only from one local plan file, plan lint, automation readiness registry digest, and registry. No plan mutation, check/test/command execution, action item execution, repair, formatting, code generation, state directory, sidecar write, source write, git, commit, PR, push, merge, tag, platform API, external network, model, MCP, subagent, dae' + 'mon, sche' + 'duler, ret' + 'ry, worktree, or business source mutation occurred.',
+    };
+  }
+
+  function selfTestGateProfileEnvelope(root, planFile, { intent = 'implementation' } = {}) {
+    ensureRoot(root);
+    const planManifestEnvelope = planActionManifestEnvelope(root, planFile, { intent });
+    const planActionManifest = planManifestEnvelope.plan_action_manifest;
+    const registry = runtimeCapabilityRegistry();
+    const profile = runtimeSelfTestGateProfile({
+      planActionManifest,
+      registry,
+      registryDigest: planActionManifest.source_bindings.registry_digest,
+    });
+    const selfTestGateProfile = {
+      ...profile,
+      self_test_gate_profile_digest: digestSelfTestGateProfile(runtimeSelfTestGateProfileDigestPayload(profile)),
+    };
+    return {
+      mode: 'self-test-gate-profile',
+      ok: selfTestGateProfile.profile_invariants.pass,
+      state_present: fs.existsSync(workflowArtifactPath(root)),
+      self_test_gate_profile: selfTestGateProfile,
+      safety: { stage: 'Stage 106', ...selfTestGateProfile.boundary_assertions },
+      quality: selfTestGateProfile.profile_invariants.findings,
+      action: 'self-test-gate-profile envelope was computed read-only from Stage 105 check expectations. No check execution, test execution, repair, formatting, code generation, sidecar write, git, PR, push, merge, platform API, external network, model, subagent, MCP, dae' + 'mon, or business source mutation occurred.',
+    };
+  }
+
+  function commitReadinessEnvelope(root, planFile, { intent = 'implementation', subject = '' } = {}) {
+    ensureRoot(root);
+    if (!subject) throw new Error('release --commit-readiness requires --subject <commit-subject>');
+    const planManifestEnvelope = planActionManifestEnvelope(root, planFile, { intent });
+    const selfTestEnvelope = selfTestGateProfileEnvelope(root, planFile, { intent });
+    const commitGuard = commitGuardEnvelope(root, { subject });
+    const registry = runtimeCapabilityRegistry();
+    const commitReadiness = runtimeCommitReadinessEnvelope({
+      planActionManifest: planManifestEnvelope.plan_action_manifest,
+      selfTestGateProfile: selfTestEnvelope.self_test_gate_profile,
+      commitGuard,
+      registry,
+      registryDigest: planManifestEnvelope.plan_action_manifest.source_bindings.registry_digest,
+    });
+    const commitReadinessEnvelopeValue = {
+      ...commitReadiness,
+      commit_readiness_digest: digestCommitReadiness(runtimeCommitReadinessDigestPayload(commitReadiness)),
+    };
+    return {
+      mode: 'commit-readiness-envelope',
+      ok: commitReadinessEnvelopeValue.readiness_invariants.pass,
+      state_present: fs.existsSync(runtimeStateFolder(root)),
+      commit_readiness: commitReadinessEnvelopeValue,
+      safety: { stage: 'Stage 107', ...commitReadinessEnvelopeValue.boundary_assertions },
+      quality: commitReadinessEnvelopeValue.readiness_invariants.findings,
+      action: 'commit-readiness envelope was computed read-only from one local plan file, Stage 105 manifest, Stage 106 self-test gate profile, and Stage 98 commit guard. No git command, commit, check execution, test execution, repair, formatting, code generation, sidecar write, PR, push, merge, platform API, external network, model, subagent, MCP, dae' + 'mon, or business source mutation occurred.',
+    };
+  }
+
+  function stagedCommitReadinessEnvelope(root, runbookFile, evidenceFile, { selectedStage = '', subject = '' } = {}) {
+    ensureRoot(root);
+    if (!runbookFile) throw new Error('release --staged-commit-readiness requires --from-runbook <local-runbook-json>');
+    if (!evidenceFile) throw new Error('release --staged-commit-readiness requires --from-evidence <local-execution-evidence-json>');
+    if (!selectedStage) throw new Error('release --staged-commit-readiness requires --stage <stage-id>');
+    if (!subject) throw new Error('release --staged-commit-readiness requires --subject <commit-subject>');
+    const runbookSource = localTextEvidenceDescriptor(root, runbookFile, 'release --staged-commit-readiness source runbook');
+    const evidenceSource = localTextEvidenceDescriptor(root, evidenceFile, 'release --staged-commit-readiness source evidence');
+    let parsedRunbook;
+    let parsedEvidence;
+    try {
+      parsedRunbook = JSON.parse(runbookSource.text);
+    } catch (error) {
+      throw new Error(`release --staged-commit-readiness requires JSON runbook: ${error.message}`);
+    }
+    try {
+      parsedEvidence = JSON.parse(evidenceSource.text);
+    } catch (error) {
+      throw new Error(`release --staged-commit-readiness requires JSON evidence: ${error.message}`);
+    }
+    const runbook = parsedRunbook.sequential_stage_runbook || parsedRunbook;
+    const evidence = parsedEvidence.execution_evidence_binding ? parsedEvidence : (parsedEvidence.verification?.execution_evidence_binding ? parsedEvidence.verification : parsedEvidence);
+    const automationEnvelope = runtimeAutomationReadinessEnvelope(root);
+    const registry = runtimeCapabilityRegistry();
+    const readiness = runtimeStagedCommitReadiness({
+      runbook,
+      runbookSource,
+      evidence,
+      evidenceSource,
+      selectedStage,
+      subject,
+      registry,
+      registryDigest: automationEnvelope.runtime_automation_readiness.registry_digest,
+    });
+    const stagedCommitReadiness = {
+      ...readiness,
+      staged_commit_readiness_digest: digestStagedCommitReadiness(runtimeStagedCommitReadinessDigestPayload(readiness)),
+    };
+    return {
+      mode: 'staged-commit-readiness-contract',
+      ok: stagedCommitReadiness.staged_commit_readiness_invariants.pass,
+      state_present: fs.existsSync(runtimeStateFolder(root)),
+      staged_commit_readiness: stagedCommitReadiness,
+      safety: { stage: 'Stage 120', ...stagedCommitReadiness.boundary_assertions },
+      quality: stagedCommitReadiness.staged_commit_readiness_invariants.findings,
+      action: 'staged-commit-readiness contract was computed read-only from one local Stage 118 runbook JSON file, one local Stage 119 execution evidence binding JSON file, one selected stage id, and one commit subject. Stage 120 did not call git, stage files, commit, run checks/tests, repair, format, generate code, write artifacts, create sidecars, mutate source/runbook/evidence/worktree, push, PR, merge, call platform API, external network, model, subagent, MCP, dae' + 'mon, sche' + 'duler, ret' + 'ry, or mutate business source.',
+    };
+  }
+
+  function evidenceIntakeEnvelope(root, evidenceFile, { planFile = '' } = {}) {
+    ensureRoot(root);
+    if (!evidenceFile) throw new Error('verification --evidence-intake requires --from-file <local-evidence-file>');
+    const source = localTextEvidenceDescriptor(root, evidenceFile, 'verification --evidence-intake source');
+    let evidence;
+    try {
+      evidence = JSON.parse(source.text);
+    } catch (error) {
+      throw new Error(`verification --evidence-intake requires JSON evidence: ${error.message}`);
+    }
+    const planManifest = planFile ? planActionManifestEnvelope(root, planFile, { intent: 'implementation' }).plan_action_manifest : null;
+    const selfTestProfile = planFile ? selfTestGateProfileEnvelope(root, planFile, { intent: 'implementation' }).self_test_gate_profile : null;
+    const automationEnvelope = runtimeAutomationReadinessEnvelope(root);
+    const registry = runtimeCapabilityRegistry();
+    const intake = runtimeEvidenceIntakeEnvelope({
+      evidence,
+      evidenceSource: source,
+      selfTestGateProfile: selfTestProfile,
+      planActionManifest: planManifest,
+      registry,
+      registryDigest: automationEnvelope.runtime_automation_readiness.registry_digest,
+    });
+    const evidenceIntake = {
+      ...intake,
+      evidence_intake_digest: digestEvidenceIntake(runtimeEvidenceIntakeDigestPayload(intake)),
+    };
+    return {
+      mode: 'evidence-intake-envelope',
+      ok: evidenceIntake.evidence_intake_invariants.pass,
+      state_present: fs.existsSync(runtimeStateFolder(root)),
+      evidence_intake: evidenceIntake,
+      safety: { stage: 'Stage 110', ...evidenceIntake.boundary_assertions },
+      quality: evidenceIntake.evidence_intake_invariants.findings,
+      action: 'evidence-intake envelope was computed read-only from one local evidence JSON file and optional Stage 105/106 plan-derived gate profile. Stage 110 did not execute checks[].command, run tests, repair, format, generate code, write evidence artifacts, create sidecars, call git, commit, push, PR, merge, platform API, external network, model, subagent, MCP, dae' + 'mon, sche' + 'duler, ret' + 'ry, or mutate business source.',
+    };
+  }
+
+  function executionEvidenceEnvelope(root, evidenceFile, { runbookFile = '', selectedStage = '' } = {}) {
+    ensureRoot(root);
+    if (!runbookFile) throw new Error('verification --execution-evidence requires --from-runbook <local-runbook-json>');
+    if (!evidenceFile) throw new Error('verification --execution-evidence requires --from-file <local-evidence-json>');
+    const evidenceSource = localTextEvidenceDescriptor(root, evidenceFile, 'verification --execution-evidence source evidence');
+    const runbookSource = localTextEvidenceDescriptor(root, runbookFile, 'verification --execution-evidence source runbook');
+    let evidence;
+    let parsedRunbook;
+    try {
+      evidence = JSON.parse(evidenceSource.text);
+    } catch (error) {
+      throw new Error(`verification --execution-evidence requires JSON evidence: ${error.message}`);
+    }
+    try {
+      parsedRunbook = JSON.parse(runbookSource.text);
+    } catch (error) {
+      throw new Error(`verification --execution-evidence requires JSON runbook: ${error.message}`);
+    }
+    const runbook = parsedRunbook.sequential_stage_runbook || parsedRunbook;
+    const automationEnvelope = runtimeAutomationReadinessEnvelope(root);
+    const registry = runtimeCapabilityRegistry();
+    const binding = runtimeExecutionEvidenceBinder({
+      evidence,
+      evidenceSource,
+      runbook,
+      runbookSource,
+      selectedStage,
+      registry,
+      registryDigest: automationEnvelope.runtime_automation_readiness.registry_digest,
+    });
+    const executionEvidenceBinding = {
+      ...binding,
+      execution_evidence_digest: digestExecutionEvidenceBinding(runtimeExecutionEvidenceDigestPayload(binding)),
+    };
+    return {
+      mode: 'execution-evidence-binding',
+      ok: executionEvidenceBinding.execution_evidence_invariants.pass,
+      state_present: fs.existsSync(runtimeStateFolder(root)),
+      execution_evidence_binding: executionEvidenceBinding,
+      safety: { stage: 'Stage 119', ...executionEvidenceBinding.boundary_assertions },
+      quality: executionEvidenceBinding.execution_evidence_invariants.findings,
+      action: 'execution-evidence-binding contract was computed read-only from one local Stage 118 runbook JSON file and one local execution evidence JSON file. Stage 119 did not execute runbook commands, run tests/checks, repair, format, generate code, write evidence artifacts, create sidecars, mutate source/runbook, call git, commit, push, PR, merge, platform API, external network, model, subagent, MCP, dae' + 'mon, sche' + 'duler, ret' + 'ry, or mutate business source.',
+    };
+  }
+
+  function tddTraceEnvelope(root, traceFile, { planFile = '' } = {}) {
+    ensureRoot(root);
+    if (!traceFile) throw new Error('verification --tdd-trace requires --from-file <local-tdd-trace-file>');
+    const source = localTextEvidenceDescriptor(root, traceFile, 'verification --tdd-trace source');
+    let trace;
+    try {
+      trace = JSON.parse(source.text);
+    } catch (error) {
+      throw new Error(`verification --tdd-trace requires JSON trace: ${error.message}`);
+    }
+    const planManifest = planFile ? planActionManifestEnvelope(root, planFile, { intent: 'implementation' }).plan_action_manifest : null;
+    const automationEnvelope = runtimeAutomationReadinessEnvelope(root);
+    const registry = runtimeCapabilityRegistry();
+    const contract = runtimeTddTraceContract({
+      trace,
+      traceSource: source,
+      planActionManifest: planManifest,
+      registry,
+      registryDigest: automationEnvelope.runtime_automation_readiness.registry_digest,
+    });
+    const tddTraceContract = {
+      ...contract,
+      tdd_trace_digest: digestTddTraceContract(runtimeTddTraceDigestPayload(contract)),
+    };
+    return {
+      mode: 'tdd-trace-contract',
+      ok: tddTraceContract.tdd_trace_invariants.pass,
+      state_present: fs.existsSync(runtimeStateFolder(root)),
+      tdd_trace_contract: tddTraceContract,
+      safety: { stage: 'Stage 113', ...tddTraceContract.boundary_assertions },
+      quality: tddTraceContract.tdd_trace_invariants.findings,
+      action: 'tdd-trace contract was computed read-only from one local TDD trace JSON file and optional Stage 105 plan-derived action manifest. Stage 113 did not execute red, green, refactor, test, check, lint, verification, repair, formatting, code generation, git, commit, push, PR, merge, platform API, external network, model, subagent, MCP, sche' + 'duler, dae' + 'mon, ret' + 'ry, or mutate business source.',
+    };
+  }
+
+  function verificationRepairLoopEnvelope(root, evidenceFile) {
+    ensureRoot(root);
+    if (!evidenceFile) throw new Error('verification --repair-plan requires --from-file <local-evidence-json>');
+    const source = localTextEvidenceDescriptor(root, evidenceFile, 'verification --repair-plan source evidence');
+    let evidence;
+    try {
+      evidence = JSON.parse(source.text);
+    } catch (error) {
+      throw new Error(`verification --repair-plan requires JSON evidence: ${error.message}`);
+    }
+    return buildVerificationDrivenRepairLoopPlan({
+      input: evidence,
+      source,
+      statePresent: fs.existsSync(runtimeStateFolder(root)),
+      digestObject,
+    });
+  }
+
+  function runVerification(options) {
+    ensureRoot(options.root);
+    const modes = [options.verificationSelfTestProfile, options.verificationEvidenceIntake, options.verificationExecutionEvidence, options.verificationTddTrace, options.verificationRepairPlan].filter(Boolean);
+    if (modes.length !== 1) throw new Error('verification requires exactly one mode: --self-test-profile, --evidence-intake, --execution-evidence, --tdd-trace, or --repair-plan');
+    const readOnlyFlagPresent = options.confirm || options.write || options.dryRun || options.recoveryPreview || options.hooksPreview || options.dispatch || options.dispatchIntent || options.run || options.autoRun || options.scan || options.once || options.preflight;
+    if (readOnlyFlagPresent && options.verificationEvidenceIntake) throw new Error('verification read-only modes do not accept execution, dispatch, preview, confirm, write, scan, dry-run, or preflight flags');
+    if (readOnlyFlagPresent && options.verificationExecutionEvidence) throw new Error('verification --execution-evidence is read-only and does not accept execution, dispatch, preview, confirm, write, scan, dry-run, or preflight flags');
+    if (readOnlyFlagPresent && options.verificationTddTrace) throw new Error('verification --tdd-trace is read-only and does not accept execution, dispatch, preview, confirm, write, scan, dry-run, or preflight flags');
+    if (readOnlyFlagPresent && options.verificationRepairPlan) throw new Error('verification --repair-plan is read-only planning and does not accept execution, dispatch, preview, confirm, write, scan, dry-run, or preflight flags');
+    if (readOnlyFlagPresent) throw new Error('verification --self-test-profile is read-only and does not accept execution, dispatch, preview, confirm, write, scan, dry-run, or preflight flags');
+    if (!options.fromFile) throw new Error(options.verificationEvidenceIntake ? 'verification --evidence-intake requires --from-file <local-evidence-file>' : options.verificationExecutionEvidence ? 'verification --execution-evidence requires --from-file <local-evidence-json>' : options.verificationTddTrace ? 'verification --tdd-trace requires --from-file <local-tdd-trace-file>' : options.verificationRepairPlan ? 'verification --repair-plan requires --from-file <local-evidence-json>' : 'verification --self-test-profile requires --from-file <local-plan-file>');
+    if (options.verificationEvidenceIntake) {
+      if (options.methodologyIntent) throw new Error('--intent is only supported by verification --self-test-profile');
+      if (options.fromRunbook || options.selectedStage) throw new Error('--from-runbook and --stage are only supported by verification --execution-evidence');
+      if (options.plannerFile || options.plannerFromHook || options.methodologyKind || options.fromReadiness || options.learningObservationFiles.length > 0 || options.learningInstinctFile || options.tokenCompactionFiles.length > 0) throw new Error('verification --evidence-intake only accepts one local evidence file, optional --from-plan, and read-only output flags');
+      const envelope = evidenceIntakeEnvelope(options.root, options.fromFile, { planFile: options.fromPlan });
+      if (options.json) emitJsonEnvelope('verification', envelope);
+      else printEvidenceIntake(envelope);
+      return;
+    }
+    if (options.verificationExecutionEvidence) {
+      if (options.methodologyIntent) throw new Error('--intent is only supported by verification --self-test-profile');
+      if (options.fromPlan) throw new Error('--from-plan is only supported by verification --evidence-intake or verification --tdd-trace');
+      if (!options.fromRunbook) throw new Error('verification --execution-evidence requires --from-runbook <local-runbook-json>');
+      if (options.plannerFile || options.plannerFromHook || options.methodologyKind || options.fromReadiness || options.learningObservationFiles.length > 0 || options.learningInstinctFile || options.tokenCompactionFiles.length > 0) throw new Error('verification --execution-evidence only accepts one local evidence file, one local Stage 118 runbook file, optional --stage, and read-only output flags');
+      const envelope = executionEvidenceEnvelope(options.root, options.fromFile, { runbookFile: options.fromRunbook, selectedStage: options.selectedStage });
+      if (options.json) emitJsonEnvelope('verification', envelope);
+      else printExecutionEvidenceBinding(envelope);
+      return;
+    }
+    if (options.verificationTddTrace) {
+      if (options.methodologyIntent) throw new Error('--intent is only supported by verification --self-test-profile');
+      if (options.fromRunbook || options.selectedStage) throw new Error('--from-runbook and --stage are only supported by verification --execution-evidence');
+      if (options.plannerFile || options.plannerFromHook || options.methodologyKind || options.fromReadiness || options.learningObservationFiles.length > 0 || options.learningInstinctFile || options.tokenCompactionFiles.length > 0) throw new Error('verification --tdd-trace only accepts one local TDD trace file, optional --from-plan, and read-only output flags');
+      const envelope = tddTraceEnvelope(options.root, options.fromFile, { planFile: options.fromPlan });
+      if (options.json) emitJsonEnvelope('verification', envelope);
+      else printTddTraceContract(envelope);
+      return;
+    }
+    if (options.verificationRepairPlan) {
+      if (options.methodologyIntent) throw new Error('--intent is only supported by verification --self-test-profile');
+      if (options.fromPlan || options.fromRunbook || options.selectedStage) throw new Error('--from-plan, --from-runbook, and --stage are not supported by verification --repair-plan');
+      if (options.plannerFile || options.plannerFromHook || options.methodologyKind || options.fromReadiness || options.learningObservationFiles.length > 0 || options.learningInstinctFile || options.tokenCompactionFiles.length > 0) throw new Error('verification --repair-plan only accepts one local evidence file and read-only output flags');
+      const envelope = verificationRepairLoopEnvelope(options.root, options.fromFile);
+      if (options.json) emitJsonEnvelope('verification', envelope);
+      else printVerificationDrivenRepairLoopPlan(envelope, { printList: validationDeps.printList });
+      return;
+    }
+    if (options.fromPlan) throw new Error('--from-plan is only supported by verification --evidence-intake or verification --tdd-trace');
+    if (options.fromRunbook || options.selectedStage) throw new Error('--from-runbook and --stage are only supported by verification --execution-evidence');
+    if (options.plannerFile || options.plannerFromHook || options.methodologyKind || options.fromReadiness || options.learningObservationFiles.length > 0 || options.learningInstinctFile || options.tokenCompactionFiles.length > 0) throw new Error('verification --self-test-profile only accepts one local plan file plus read-only output flags');
+    const envelope = selfTestGateProfileEnvelope(options.root, options.fromFile, { intent: options.methodologyIntent || 'implementation' });
+    if (options.json) emitJsonEnvelope('verification', envelope);
+    else printSelfTestGateProfile(envelope);
+  }
+
+  return {
+    planLintEnvelope,
+    planActionManifestEnvelope,
+    executablePlanContractEnvelope,
+    selfTestGateProfileEnvelope,
+    commitReadinessEnvelope,
+    stagedCommitReadinessEnvelope,
+    evidenceIntakeEnvelope,
+    executionEvidenceEnvelope,
+    verificationRepairLoopEnvelope,
+    tddTraceEnvelope,
+    runVerification,
+  };
+}