@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-execution-evidence-binder.mjs

@@ -0,0 +1,537 @@
+import { buildAutomaticVerificationGateContract } from './runtime-automatic-verification-gate-contract.mjs';
+import crypto from 'node:crypto';
+
+const executionEvidenceStage = 'Stage 119';
+const executionEvidenceKind = 'execution-evidence-binding';
+
+const evidenceCategoryDefinitions = [
+  {
+    id: 'static_check',
+    label: 'Static check evidence',
+    aliases: ['static_check', 'static-check', 'static check', 'syntax', 'lint', 'typecheck', 'type check', 'node --check', 'release-check', 'runtime-check', 'git diff --check', '静态检查'],
+    required_by_default: true,
+  },
+  {
+    id: 'test',
+    label: 'Test evidence',
+    aliases: ['test', 'tests', 'unit test', 'integration test', 'vitest', 'jest', 'pytest', 'npm test', 'pnpm test', '测试'],
+    required_by_default: true,
+  },
+  {
+    id: 'manual_verification',
+    label: 'Manual verification evidence',
+    aliases: ['manual', 'manual verification', 'manual_verification', 'manual-verification', 'acceptance', 'human check', '验收', '人工验证'],
+    required_by_default: true,
+  },
+  {
+    id: 'review',
+    label: 'Review evidence',
+    aliases: ['review', 'review_intake', 'review_resolution', 'review envelope', 'code review', 'vibe-review', '评审'],
+    required_by_default: false,
+  },
+  {
+    id: 'tdd_trace',
+    label: 'TDD trace evidence',
+    aliases: ['tdd', 'tdd_trace', 'tdd-trace', 'red green refactor', 'red-green-refactor', 'RED', 'GREEN', 'REFACTOR'],
+    required_by_default: false,
+  },
+  {
+    id: 'diff_coverage',
+    label: 'Diff coverage evidence',
+    aliases: ['diff', 'diff_coverage', 'diff-coverage', 'diff coverage', 'changed files', 'git diff', '覆盖变更'],
+    required_by_default: false,
+  },
+];
+
+const evidenceCategoryIds = evidenceCategoryDefinitions.map((item) => item.id);
+const defaultRequiredEvidenceCategories = evidenceCategoryDefinitions.filter((item) => item.required_by_default).map((item) => item.id);
+
+export function runtimeExecutionEvidenceBinder({ evidence = {}, evidenceSource = {}, runbook = {}, runbookSource = {}, selectedStage = '', registry = {}, registryDigest = '' } = {}) {
+  const boundaryAssertions = runtimeExecutionEvidenceBoundaryAssertions();
+  const runbookStages = normalizeRunbookStages(runbook, selectedStage);
+  const evidenceItems = normalizeEvidenceItems(evidence);
+  const stageEvidenceStatus = runbookStages.map((stage) => stageStatus(stage, evidenceItems));
+  const stageEvidenceCategoryGate = stageEvidenceStatus.map((stage) => stage.evidence_category_gate);
+  const missingEvidence = stageEvidenceStatus.flatMap((stage) => stage.missing_evidence.map((item) => ({ stage_id: stage.stage_id, requirement: item })));
+  const missingEvidenceCategories = stageEvidenceStatus.flatMap((stage) => stage.missing_evidence_categories.map((category) => ({ stage_id: stage.stage_id, category })));
+  const staleEvidence = stageEvidenceStatus.flatMap((stage) => stage.stale_evidence.map((item) => ({ stage_id: stage.stage_id, evidence_id: item.id, command: item.command, freshness_status: item.freshness_status })));
+  const failedCommands = stageEvidenceStatus.flatMap((stage) => stage.failed_commands.map((item) => ({ stage_id: stage.stage_id, evidence_id: item.id, command: item.command, exit_status: item.exit_status })));
+  const structureFindings = structureFindingsFor(runbookStages, evidenceItems, evidenceSource, runbookSource);
+  const blockedReasons = dedupe([
+    ...structureFindings,
+    ...missingEvidence.map((item) => `missing evidence for ${item.stage_id}: ${item.requirement}`),
+    ...missingEvidenceCategories.map((item) => `missing evidence category for ${item.stage_id}: ${item.category}`),
+    ...staleEvidence.map((item) => `stale evidence for ${item.stage_id}: ${item.command || item.evidence_id}`),
+    ...failedCommands.map((item) => `failed command evidence for ${item.stage_id}: ${item.command || item.evidence_id}`),
+  ]).slice(0, 100);
+  const binding = {
+    version: 2,
+    stage: executionEvidenceStage,
+    binding_kind: executionEvidenceKind,
+    source_evidence: {
+      file: evidenceSource.relative || evidenceSource.file || '',
+      digest: evidenceSource.digest || '',
+      created_at: String(evidence.created_at || evidence.generated_at || evidence.timestamp || ''),
+      selected_stage: selectedStage || '',
+    },
+    source_runbook: {
+      file: runbookSource.relative || runbookSource.file || '',
+      digest: runbookSource.digest || '',
+      stage: runbook.stage || '',
+      runbook_kind: runbook.runbook_kind || '',
+      stage_runbook_digest: runbook.stage_runbook_digest || '',
+    },
+    source_bindings: {
+      runbook_stage: runbook.stage || '',
+      runbook_kind: runbook.runbook_kind || '',
+      stage_runbook_digest: runbook.stage_runbook_digest || '',
+      registry_stage: registry.registry_stage || '',
+      registry_kind: registry.registry_kind || '',
+      registry_version: registry.registry_version || 0,
+      registry_digest: registryDigest,
+    },
+    evidence_category_contract: {
+      contract_kind: 'stage-required-evidence-categories',
+      default_required_categories: defaultRequiredEvidenceCategories,
+      supported_categories: evidenceCategoryDefinitions.map((item) => ({
+        id: item.id,
+        label: item.label,
+        aliases: item.aliases,
+        required_by_default: item.required_by_default,
+      })),
+      tdd_review_diff_coverage_are_first_class: true,
+      commands_executed_by_stage_119: false,
+      evidence_generated_by_stage_119: false,
+      execution_authorized: false,
+    },
+    execution_evidence_binding: {
+      runbook_file_read: Boolean(runbookSource.digest),
+      evidence_file_read: Boolean(evidenceSource.digest),
+      selected_stage: selectedStage || 'all',
+      runbook_stage_count: runbookStages.length,
+      evidence_item_count: evidenceItems.length,
+      required_evidence_category_count: [...new Set(runbookStages.flatMap((stage) => stage.required_evidence_categories))].length,
+      missing_evidence_category_count: missingEvidenceCategories.length,
+      category_gate_pass: stageEvidenceCategoryGate.length > 0 && stageEvidenceCategoryGate.every((gate) => gate.pass),
+      commands_executed_by_stage_119: false,
+      evidence_generated_by_stage_119: false,
+      execution_authorized: false,
+      ready_for_next_stage: blockedReasons.length === 0 && runbookStages.length > 0,
+    },
+    automatic_verification_gate: buildAutomaticVerificationGateContract({
+      phase: 'execution-evidence-binding',
+      stageRunbookBound: Boolean(runbookSource.digest),
+      executionEvidenceBound: Boolean(evidenceSource.digest),
+      evidenceItemCount: evidenceItems.length,
+      missingEvidenceCount: missingEvidence.length + missingEvidenceCategories.length,
+      staleEvidenceCount: staleEvidence.length,
+      failedEvidenceCount: failedCommands.length,
+      blockedReasons,
+      nextManualAction: 'Resolve local execution evidence blockers before using this binding for completion or staged readiness.',
+    }),
+    stage_evidence_category_gate: stageEvidenceCategoryGate,
+    stage_evidence_status: stageEvidenceStatus,
+    missing_evidence: missingEvidence,
+    missing_evidence_categories: missingEvidenceCategories,
+    stale_evidence: staleEvidence,
+    failed_commands: failedCommands,
+    blocked_reasons: blockedReasons,
+    ready_for_next_stage: blockedReasons.length === 0 && runbookStages.length > 0,
+    resume_guidance: resumeGuidance(blockedReasons, stageEvidenceStatus),
+    allowed_followup: ['manual evidence repair outside Stage 119', 'Stage 120 staged commit readiness contract', 'manual runbook/evidence refinement before Stage 120'],
+    forbidden_actions: [
+      'executing runbook validation commands',
+      'rerunning checks, tests, repair, formatting, or code generation',
+      'creating or rewriting evidence artifacts',
+      'writing execution evidence binder sidecars or state directories',
+      'source write or plan/runbook mutation',
+      'git command, commit, push, PR, merge, tag, reset, checkout, or history rewrite',
+      'platform API, external network, model, MCP, or subagent invocation',
+      'treating evidence binding pass as runtime execution permission',
+    ],
+    boundary_assertions: boundaryAssertions,
+    writes: false,
+    state_directory_created: false,
+    local_only: true,
+    deterministic: true,
+  };
+  const invariants = runtimeExecutionEvidenceInvariants(binding);
+  return {
+    ...binding,
+    execution_evidence_invariants: invariants,
+    manual_action: invariants.pass
+      ? 'Execution evidence is bound to the Stage 118 runbook and required evidence categories. Stage 119 only read local JSON files and did not execute commands, write artifacts, or mutate git/source state.'
+      : 'Resolve the listed evidence binding blockers before using this evidence for Stage 120 staged commit readiness.',
+  };
+}
+
+export function runtimeExecutionEvidenceInvariants(binding) {
+  const writableBoundaries = Object.entries(binding.boundary_assertions || {})
+    .filter(([, value]) => value !== false)
+    .map(([key]) => key);
+  const forbiddenMissing = ['execution_evidence_artifact', 'evidence_artifact_write', 'sidecar_write', 'state_directory_created', 'source_write', 'runbook_mutation', 'command_execution', 'check_execution', 'test_execution', 'repair_execution', 'runtime_action', 'git', 'git_write', 'commit', 'push', 'pr', 'merge', 'platform_api', 'external_network', 'model_invocation', 'subagent', 'mcp', 'business_source_write']
+    .filter((key) => binding.boundary_assertions?.[key] !== false);
+  const executableItems = (binding.stage_evidence_status || [])
+    .flatMap((stage) => stage.evidence_items || [])
+    .filter((item) => item.execution_authorized !== false || item.command_executed_by_stage_119 !== false)
+    .map((item) => item.id || item.command || 'unknown');
+  const categoryGateFindings = (binding.stage_evidence_category_gate || [])
+    .filter((gate) => gate.pass !== true)
+    .map((gate) => `category gate must pass for ${gate.stage_id}: missing ${gate.missing_categories.join(', ')}`);
+  const statusWithoutCategoryGate = (binding.stage_evidence_status || [])
+    .filter((stage) => !stage.evidence_category_gate || !Array.isArray(stage.required_evidence_categories))
+    .map((stage) => stage.stage_id || 'unknown');
+  const findings = [
+    ...(binding.stage === executionEvidenceStage ? [] : ['stage must be Stage 119']),
+    ...(binding.binding_kind === executionEvidenceKind ? [] : ['binding_kind must be execution-evidence-binding']),
+    ...(binding.source_evidence?.digest ? [] : ['missing evidence source digest']),
+    ...(binding.source_runbook?.digest ? [] : ['missing runbook source digest']),
+    ...(binding.source_bindings?.stage_runbook_digest ? [] : ['missing Stage 118 runbook digest binding']),
+    ...(binding.stage_evidence_status?.length > 0 ? [] : ['stage_evidence_status must not be empty']),
+    ...(binding.evidence_category_contract?.tdd_review_diff_coverage_are_first_class === true ? [] : ['TDD, review, and diff coverage categories must be first-class']),
+    ...(binding.execution_evidence_binding?.category_gate_pass === true ? [] : ['evidence category gate must pass']),
+    ...categoryGateFindings,
+    ...statusWithoutCategoryGate.map((item) => `stage missing evidence category gate: ${item}`),
+    ...((binding.blocked_reasons || []).map((item) => `blocked: ${item}`)),
+    ...executableItems.map((item) => `execution boundary must remain false for evidence item: ${item}`),
+    ...writableBoundaries.map((item) => `boundary assertion must remain false: ${item}`),
+    ...forbiddenMissing.map((item) => `forbidden boundary missing or not false: ${item}`),
+  ];
+  return {
+    pass: findings.length === 0,
+    checked: [
+      'local_runbook_source_digest',
+      'local_evidence_source_digest',
+      'stage_118_runbook_digest_binding',
+      'stage_evidence_status_schema',
+      'stage_required_evidence_categories',
+      'tdd_review_diff_coverage_first_class_categories',
+      'missing_stale_failed_evidence',
+      'no_command_execution',
+      'read_only_boundary_assertions',
+    ],
+    findings,
+  };
+}
+
+export function runtimeExecutionEvidenceBoundaryAssertions() {
+  return {
+    execution_evidence_artifact: false,
+    evidence_artifact_write: false,
+    test_result_artifact: false,
+    sidecar_write: false,
+    state_directory_created: false,
+    source_write: false,
+    plan_mutation: false,
+    runbook_mutation: false,
+    evidence_mutation: false,
+    command_execution: false,
+    check_execution: false,
+    test_execution: false,
+    verification_execution: false,
+    repair_execution: false,
+    formatting_execution: false,
+    code_generation: false,
+    runtime_action: false,
+    workflow_execution: false,
+    action_item_execution: false,
+    scheduler: false,
+    daemon: false,
+    retry: false,
+    git: false,
+    git_write: false,
+    commit: false,
+    pr: false,
+    push: false,
+    merge: false,
+    tag: false,
+    history_rewrite: false,
+    platform_api: false,
+    external_network: false,
+    model_invocation: false,
+    subagent: false,
+    mcp: false,
+    worktree: false,
+    business_source_write: false,
+  };
+}
+
+export function runtimeExecutionEvidenceDigestPayload(binding) {
+  return {
+    stage: binding.stage,
+    binding_kind: binding.binding_kind,
+    source_evidence: binding.source_evidence,
+    source_runbook: binding.source_runbook,
+    source_bindings: binding.source_bindings,
+    evidence_category_contract: binding.evidence_category_contract,
+    execution_evidence_binding: binding.execution_evidence_binding,
+    automatic_verification_gate: binding.automatic_verification_gate,
+    stage_evidence_category_gate: binding.stage_evidence_category_gate,
+    stage_evidence_status: binding.stage_evidence_status,
+    missing_evidence: binding.missing_evidence,
+    missing_evidence_categories: binding.missing_evidence_categories,
+    stale_evidence: binding.stale_evidence,
+    failed_commands: binding.failed_commands,
+    blocked_reasons: binding.blocked_reasons,
+    ready_for_next_stage: binding.ready_for_next_stage,
+    allowed_followup: binding.allowed_followup,
+    forbidden_actions: binding.forbidden_actions,
+    boundary_assertions: binding.boundary_assertions,
+    execution_evidence_invariants: binding.execution_evidence_invariants,
+  };
+}
+
+export function digestExecutionEvidenceBinding(value) {
+  return crypto.createHash('sha256').update(stableStringify(value)).digest('hex');
+}
+
+function normalizeRunbookStages(runbook, selectedStage) {
+  const stages = Array.isArray(runbook.stage_sequence) ? runbook.stage_sequence : [];
+  const selected = String(selectedStage || '').trim();
+  const filtered = selected
+    ? stages.filter((stage) => stage.stage_id === selected || stage.title === selected || String(stage.sequence_index) === selected || String(stage.stage || '') === selected)
+    : stages;
+  return filtered.map((stage, index) => {
+    const normalizedStage = {
+      stage_id: String(stage.stage_id || `stage119-runbook-stage-${String(index + 1).padStart(2, '0')}`),
+      title: String(stage.title || stage.stage_id || ''),
+      sequence_index: Number(stage.sequence_index || index + 1),
+      validation_commands: arrayOfStrings(stage.validation_commands),
+      evidence_required: arrayOfStrings(stage.evidence_required),
+      stop_if: arrayOfStrings(stage.stop_if),
+      next_stage: String(stage.next_stage || ''),
+      commit_subject: String(stage.commit_subject || ''),
+    };
+    return {
+      ...normalizedStage,
+      required_evidence_categories: requiredEvidenceCategoriesFor(stage, normalizedStage),
+    };
+  });
+}
+
+function normalizeEvidenceItems(evidence) {
+  const rawItems = [
+    ...arrayOfObjects(evidence.stage_evidence),
+    ...arrayOfObjects(evidence.execution_evidence),
+    ...arrayOfObjects(evidence.commands),
+    ...arrayOfObjects(evidence.checks),
+    ...arrayOfObjects(evidence.items),
+  ];
+  return rawItems.map((item, index) => {
+    const exitStatus = item.exit_status ?? item.exit_code ?? item.status_code;
+    const manualStatus = typeof exitStatus === 'string' && /^manual$/i.test(exitStatus.trim());
+    const normalizedExitStatus = manualStatus ? null : Number(exitStatus);
+    const command = String(item.command || item.validation_command || item.check || item.name || '').trim();
+    const keyOutput = String(item.key_output || item.output || item.summary || item.stdout || '').slice(0, 1000);
+    const artifact = String(item.artifact || item.file || item.path || '').trim();
+    const covers = dedupe([...arrayOfStrings(item.covers), ...arrayOfStrings(item.coverage), ...arrayOfStrings(item.evidence_required), ...arrayOfStrings(item.requirements)]);
+    const category = normalizeEvidenceCategory(item.category || item.evidence_category || item.kind || item.type) || inferEvidenceCategory({ command, keyOutput, artifact, covers });
+    const freshness = normalizeFreshness(item.freshness ?? item.fresh ?? item.staleness);
+    return {
+      id: String(item.id || item.evidence_id || `stage119-evidence-${String(index + 1).padStart(2, '0')}`),
+      stage_id: String(item.stage_id || item.stage || item.runbook_stage_id || evidence.stage_id || '').trim(),
+      category,
+      command,
+      exit_status: manualStatus ? 'manual' : Number.isFinite(normalizedExitStatus) ? normalizedExitStatus : null,
+      key_output: keyOutput,
+      artifact,
+      source_digest: String(item.source_digest || item.digest || item.evidence_digest || item.tdd_trace_digest || item.review_intake_digest || item.review_resolution_digest || item.diff_coverage_digest || '').trim(),
+      covers,
+      freshness_status: freshness.status,
+      fresh: freshness.fresh,
+      passed: manualStatus || (Number.isFinite(normalizedExitStatus) && normalizedExitStatus === 0),
+      command_executed_by_stage_119: false,
+      execution_authorized: false,
+    };
+  });
+}
+
+function stageStatus(stage, evidenceItems) {
+  const stageEvidence = evidenceItems.filter((item) => evidenceMatchesStage(item, stage));
+  const missingEvidence = stage.evidence_required.filter((requirement) => !stageEvidence.some((item) => evidenceCoversRequirement(item, requirement)));
+  const missingEvidenceCategories = stage.required_evidence_categories.filter((category) => !stageEvidence.some((item) => evidenceCoversCategory(item, category)));
+  const staleEvidence = stageEvidence.filter((item) => item.fresh === false);
+  const failedCommands = stageEvidence.filter((item) => typeof item.exit_status === 'number' && item.exit_status !== 0);
+  const commandCoverage = stage.validation_commands.map((command) => ({
+    command,
+    covered: stageEvidence.some((item) => normalized(item.command) === normalized(command) || item.covers.some((cover) => normalized(cover) === normalized(command))),
+  }));
+  const coveredCategories = stage.required_evidence_categories.filter((category) => stageEvidence.some((item) => evidenceCoversCategory(item, category)));
+  const categoryGate = {
+    gate_kind: 'stage-evidence-category-gate',
+    stage_id: stage.stage_id,
+    required_categories: stage.required_evidence_categories,
+    covered_categories: coveredCategories,
+    missing_categories: missingEvidenceCategories,
+    category_sources: stageEvidence.map((item) => ({
+      evidence_id: item.id,
+      category: item.category,
+      source_digest: item.source_digest,
+      artifact: item.artifact,
+      execution_authorized: false,
+    })),
+    static_check_required: stage.required_evidence_categories.includes('static_check'),
+    test_required: stage.required_evidence_categories.includes('test'),
+    manual_verification_required: stage.required_evidence_categories.includes('manual_verification'),
+    review_required: stage.required_evidence_categories.includes('review'),
+    tdd_trace_required: stage.required_evidence_categories.includes('tdd_trace'),
+    diff_coverage_required: stage.required_evidence_categories.includes('diff_coverage'),
+    pass: missingEvidenceCategories.length === 0,
+    execution_authorized: false,
+  };
+  const ready = missingEvidence.length === 0 && missingEvidenceCategories.length === 0 && staleEvidence.length === 0 && failedCommands.length === 0 && stageEvidence.length > 0;
+  return {
+    stage_id: stage.stage_id,
+    title: stage.title,
+    sequence_index: stage.sequence_index,
+    evidence_items: stageEvidence,
+    required_evidence_count: stage.evidence_required.length,
+    required_evidence_categories: stage.required_evidence_categories,
+    matched_evidence_count: stageEvidence.length,
+    command_coverage: commandCoverage,
+    evidence_category_gate: categoryGate,
+    missing_evidence: missingEvidence,
+    missing_evidence_categories: missingEvidenceCategories,
+    stale_evidence: staleEvidence,
+    failed_commands: failedCommands,
+    status: ready ? 'bound' : 'blocked',
+    ready_for_next_stage: ready,
+    stop_if_triggered: dedupe([
+      ...(missingEvidence.length > 0 ? ['required evidence is missing'] : []),
+      ...(missingEvidenceCategories.length > 0 ? ['required evidence category is missing'] : []),
+      ...(staleEvidence.length > 0 ? ['required evidence is stale'] : []),
+      ...(failedCommands.length > 0 ? ['command evidence failed'] : []),
+    ]),
+    next_stage: stage.next_stage,
+    commit_subject: stage.commit_subject,
+    execution_authorized: false,
+  };
+}
+
+function evidenceMatchesStage(item, stage) {
+  if (!item.stage_id) return false;
+  return item.stage_id === stage.stage_id || item.stage_id === stage.title || item.stage_id === String(stage.sequence_index);
+}
+
+function evidenceCoversRequirement(item, requirement) {
+  const target = normalized(requirement);
+  if (!target) return false;
+  return item.covers.some((cover) => normalized(cover).includes(target) || target.includes(normalized(cover)))
+    || normalized(item.command).includes(target)
+    || normalized(item.key_output).includes(target)
+    || normalized(item.artifact).includes(target)
+    || normalized(item.category).includes(target);
+}
+
+function evidenceCoversCategory(item, category) {
+  const normalizedCategory = normalizeEvidenceCategory(category);
+  if (!normalizedCategory) return false;
+  if (item.category === normalizedCategory) return true;
+  const definition = evidenceCategoryDefinitions.find((candidate) => candidate.id === normalizedCategory);
+  const artifactName = basenameLike(item.artifact);
+  const haystack = [item.category, item.command, item.key_output, artifactName, item.source_digest, ...item.covers].map(normalized).join(' ');
+  return (definition?.aliases || []).some((alias) => haystack.includes(normalized(alias)));
+}
+
+function structureFindingsFor(runbookStages, evidenceItems, evidenceSource, runbookSource) {
+  const findings = [];
+  if (!runbookSource.digest) findings.push('missing local Stage 118 runbook file digest');
+  if (!evidenceSource.digest) findings.push('missing local execution evidence file digest');
+  if (runbookStages.length === 0) findings.push('no runbook stages selected or found');
+  if (evidenceItems.length === 0) findings.push('execution evidence must include stage_evidence, execution_evidence, commands, checks, or items array');
+  for (const stage of runbookStages) {
+    if (stage.required_evidence_categories.length === 0) findings.push(`stage missing required evidence categories: ${stage.stage_id}`);
+  }
+  for (const item of evidenceItems) {
+    if (!item.stage_id) findings.push(`evidence item missing stage_id: ${item.id}`);
+    if (!item.category) findings.push(`evidence item missing supported evidence category: ${item.id}`);
+    if (!item.command && item.covers.length === 0 && !item.key_output && !item.artifact && !item.source_digest) findings.push(`evidence item has no command, coverage, output, artifact, or digest binding: ${item.id}`);
+    if (item.exit_status === null) findings.push(`evidence item missing numeric exit_status/exit_code or manual exit_status: ${item.id}`);
+    if (item.category === 'manual_verification' && !item.key_output && !item.artifact) findings.push(`manual verification evidence requires key_output or artifact: ${item.id}`);
+    if (['tdd_trace', 'review', 'diff_coverage'].includes(item.category) && !item.source_digest && !item.artifact) findings.push(`${item.category} evidence requires source_digest or artifact binding: ${item.id}`);
+  }
+  return dedupe(findings).slice(0, 100);
+}
+
+function resumeGuidance(blockedReasons, stageEvidenceStatus) {
+  if (blockedReasons.length === 0) return 'Proceed to Stage 120 staged commit readiness with this local evidence binding. Runtime still must not commit automatically.';
+  const blockedStage = stageEvidenceStatus.find((stage) => stage.ready_for_next_stage !== true);
+  return `Stop before Stage 120. Repair local evidence for ${blockedStage?.stage_id || 'the selected stage'} and rerun verification --execution-evidence; Stage 119 must not run commands or create evidence.`;
+}
+
+function requiredEvidenceCategoriesFor(rawStage, normalizedStage) {
+  const declared = dedupe([
+    ...arrayOfStrings(rawStage.required_evidence_categories),
+    ...arrayOfStrings(rawStage.evidence_required_categories),
+    ...arrayOfStrings(rawStage.evidence_categories),
+    ...arrayOfStrings(rawStage.required_categories),
+  ]).map(normalizeEvidenceCategory).filter(Boolean);
+  const inferred = inferStageCategories(normalizedStage);
+  return dedupe([...defaultRequiredEvidenceCategories, ...declared, ...inferred])
+    .filter((item) => evidenceCategoryIds.includes(item));
+}
+
+function inferStageCategories(stage) {
+  const values = [...arrayOfStrings(stage.validation_commands), ...arrayOfStrings(stage.evidence_required), stage.title, stage.commit_subject];
+  return dedupe(values.map((value) => inferEvidenceCategory({ command: value, keyOutput: value, artifact: value, covers: [value] }))).filter(Boolean);
+}
+
+function inferEvidenceCategory({ command = '', keyOutput = '', artifact = '', covers = [] } = {}) {
+  const artifactName = basenameLike(artifact);
+  const haystack = [command, keyOutput, artifactName, ...covers].map(normalized).join(' ');
+  if (!haystack) return '';
+  for (const definition of evidenceCategoryDefinitions) {
+    if (definition.aliases.some((alias) => haystack.includes(normalized(alias)))) return definition.id;
+  }
+  return '';
+}
+
+function basenameLike(value) {
+  const parts = String(value || '').split(/[\\/]+/).filter(Boolean);
+  return parts.at(-1) || '';
+}
+
+function normalizeEvidenceCategory(value) {
+  const target = normalized(value).replace(/-/g, '_');
+  if (!target) return '';
+  if (evidenceCategoryIds.includes(target)) return target;
+  const definition = evidenceCategoryDefinitions.find((item) => item.aliases.some((alias) => normalized(alias).replace(/-/g, '_') === target));
+  return definition?.id || '';
+}
+
+function normalizeFreshness(value) {
+  if (value === true) return { status: 'fresh', fresh: true };
+  if (value === false) return { status: 'stale', fresh: false };
+  if (typeof value === 'string') return { status: value.trim(), fresh: /^fresh|current|ok|valid$/i.test(value.trim()) };
+  if (value && typeof value === 'object') {
+    const status = String(value.status || value.state || '').trim();
+    return { status, fresh: value.fresh === true || /^fresh|current|ok|valid$/i.test(status) };
+  }
+  return { status: '', fresh: false };
+}
+
+function arrayOfObjects(value) {
+  return Array.isArray(value) ? value.filter((item) => item && typeof item === 'object') : [];
+}
+
+function arrayOfStrings(value) {
+  if (Array.isArray(value)) return value.map((item) => String(item)).filter(Boolean);
+  if (typeof value === 'string' && value.trim()) return [value.trim()];
+  return [];
+}
+
+function normalized(value) {
+  return String(value || '').toLowerCase().replace(/\s+/g, ' ').trim();
+}
+
+function dedupe(items) {
+  return [...new Set((items || []).filter(Boolean).map((item) => String(item).trim()).filter(Boolean))];
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}

package/tools/vibe-runtime/runtime-execution-plan-artifacts.mjs

@@ -0,0 +1,136 @@
+export const createRuntimeExecutionPlanArtifacts = function (deps) {
+  const { fs, path, crypto, stateDirectoryName, executionsDirectoryName, stage11RuntimeActionName, runtimeActionCatalogStage, runtimeActionCatalogVersion, stage11AllowedExecutionSkills, forbiddenDispatchActions, stage13ApprovalStaleAfterMs, executionPolicySnapshot, runtimeActionCatalogSnapshot, evaluateRuntimeActionCatalog, policyProfileSnapshot, dispatchEventDigest, workflowPath, executionEnabledProfileBuilder, runtimeTestRunProfiles, listExecutionFiles, readExecutionFile, executionSummary, validateExecutionEnvelope, executionsDirectory, executionAuditState } = deps;
+const executionIdempotencyKey = function (eventSha256, actor, targetSkill) {
+  return crypto.createHash('sha256').update(`${eventSha256}:${actor || ''}:${targetSkill || ''}`).digest('hex');
+}
+
+const executionPlan = function (eventFile, event, claim, eventPath) {
+  const targetSkill = event.dispatch?.target_skill || '';
+  const allowlisted = stage11AllowedExecutionSkills.has(targetSkill);
+  const eventSha256 = dispatchEventDigest(eventPath);
+  const actor = claim?.actor || '';
+  const runtimeActionEvaluation = evaluateRuntimeActionCatalog(stage11RuntimeActionName, policyProfileSnapshot('controlled-local-runtime'));
+  return {
+    status: 'planned',
+    event_file: String(eventFile),
+    event_sha256: eventSha256,
+    claim_status: claim?.status || 'not_claimed',
+    actor,
+    from_skill: event.dispatch?.from_skill || '',
+    target_skill: targetSkill,
+    allowlisted,
+    idempotency_key: executionIdempotencyKey(eventSha256, actor, targetSkill),
+    policy: executionPolicySnapshot(),
+    runtime_action: stage11RuntimeActionName,
+    runtime_action_catalog: {
+      stage: runtimeActionCatalogStage,
+      version: runtimeActionCatalogVersion,
+      catalog_digest: runtimeActionEvaluation.catalog_digest,
+      action_id: stage11RuntimeActionName,
+      known: runtimeActionEvaluation.known,
+      allowed: runtimeActionEvaluation.allowed,
+      blocked_reasons: runtimeActionEvaluation.blocked_reasons,
+    },
+    runtime_action_contract: {
+      name: stage11RuntimeActionName,
+      version: 1,
+      input_summary: {
+        event_file: String(eventFile),
+        event_sha256: eventSha256,
+        actor,
+        from_skill: event.dispatch?.from_skill || '',
+        target_skill: targetSkill,
+      },
+      output_summary: {
+        artifact_type: 'supervised-handoff-package',
+        writes_business_source: false,
+        executes_workflow_skill: false,
+      },
+      skill_execution: false,
+      business_source_write: false,
+    },
+    manual_action: 'Human-supervised executor may continue only after explicit confirm, --run, allowlisted target skill, and matching picked claim. Stage 11 generates a supervised execution package and lifecycle record; it does not call platform APIs or modify business source.',
+    writes: [path.join(stateDirectoryName, executionsDirectoryName, '<timestamp>-<dispatch-hash>.execution.json').replace(/\\/g, '/')],
+    forbidden_actions: forbiddenDispatchActions,
+  };
+}
+
+const findActiveExecutionByIdempotencyKey = function (root, idempotencyKey) {
+  for (const fileName of listExecutionFiles(root)) {
+    try {
+      const execution = readExecutionFile(path.join(executionsDirectory(root), fileName));
+      if (
+        execution.mode === 'supervised-run'
+        && execution.execution?.idempotency_key === idempotencyKey
+        && execution.execution?.status === 'running'
+      ) {
+        return { file: fileName, execution };
+      }
+    } catch {
+      // Invalid execution records are handled by executions audit; they do not become runnable guards.
+    }
+  }
+  return null;
+}
+
+const assertNoActiveExecution = function (root, plan) {
+  const active = findActiveExecutionByIdempotencyKey(root, plan.idempotency_key);
+  if (active) {
+    throw new Error(`Active supervised run already exists for idempotency key: ${active.file}`);
+  }
+}
+
+const activeExecutionCount = function (root) {
+  return listExecutionFiles(root).reduce((count, fileName) => {
+    try {
+      return count + (executionAuditState(readExecutionFile(path.join(executionsDirectory(root), fileName))).active ? 1 : 0);
+    } catch {
+      return count;
+    }
+  }, 0);
+}
+
+const readExecutionProfileConfig = function (root) {
+  const file = path.join(root, '.vibecoding', 'config.json');
+  if (!fs.existsSync(file)) return { file, config: null, present: false, error: '' };
+  try {
+    return { file, config: JSON.parse(fs.readFileSync(file, 'utf8')), present: true, error: '' };
+  } catch (error) {
+    return { file, config: null, present: true, error: error.message };
+  }
+}
+
+const executionEnabledPreflight = function (root) {
+  return executionEnabledProfileBuilder({
+    root,
+    configRead: readExecutionProfileConfig(root),
+    policy: policyProfileSnapshot('controlled-local-runtime'),
+    actions: runtimeActionCatalogSnapshot().actions,
+    testProfiles: runtimeTestRunProfiles(),
+    activeCount: activeExecutionCount(root),
+    statePresent: fs.existsSync(workflowPath(root)),
+    tempPresent: fs.existsSync(path.join(root, '.tmp')),
+    approvalFreshnessMs: stage13ApprovalStaleAfterMs,
+  });
+}
+
+const executionHistorySummary = function (root, idempotencyKey) {
+  const records = listExecutionFiles(root).map((fileName) => {
+    try {
+      const execution = readExecutionFile(path.join(executionsDirectory(root), fileName));
+      const summary = executionSummary(fileName, execution, validateExecutionEnvelope(execution));
+      return execution.execution?.idempotency_key === idempotencyKey ? summary : null;
+    } catch {
+      return null;
+    }
+  }).filter(Boolean);
+  return {
+    count: records.length,
+    active_count: records.filter((item) => item.active).length,
+    terminal_count: records.filter((item) => item.terminal).length,
+    records,
+  };
+}
+
+  return { executionIdempotencyKey, executionPlan, findActiveExecutionByIdempotencyKey, assertNoActiveExecution, activeExecutionCount, readExecutionProfileConfig, executionEnabledPreflight, executionHistorySummary };
+};