@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-staged-commit-readiness.mjs

@@ -0,0 +1,469 @@
+import { buildControlledChangeDeliveryContract } from './runtime-controlled-change-delivery-contract.mjs';
+import crypto from 'node:crypto';
+
+const stagedCommitReadinessStage = 'Stage 120';
+const stagedCommitReadinessKind = 'staged-commit-readiness-contract';
+
+export function runtimeStagedCommitReadiness({ runbook = {}, runbookSource = {}, evidence = {}, evidenceSource = {}, selectedStage = '', subject = '', registry = {}, registryDigest = '' } = {}) {
+  const boundaryAssertions = runtimeStagedCommitReadinessBoundaryAssertions();
+  const runbookStages = normalizeRunbookStages(runbook);
+  const selected = selectRunbookStage(runbookStages, selectedStage);
+  const executionBinding = normalizeExecutionEvidenceBinding(evidence);
+  const stageEvidence = selected ? evidenceStatusForStage(executionBinding, selected) : null;
+  const stageEvidenceCategoryGate = selected ? evidenceCategoryGateForStage(executionBinding, selected, stageEvidence) : null;
+  const subjectGuard = subjectGuardFor(subject, selected);
+  const requiredFiles = selected ? selected.files_to_change : [];
+  const validationCommands = selected ? selected.validation_commands : [];
+  const evidencePass = executionBinding.binding_pass === true && executionBinding.ready_for_next_stage === true && stageEvidence?.ready_for_next_stage === true;
+  const diffCoverageRequired = requiredFiles.length > 0;
+  const commitReadinessGate = commitReadinessGateFor({
+    selected,
+    subjectGuard,
+    requiredFiles,
+    validationCommands,
+    stageEvidence,
+    stageEvidenceCategoryGate,
+    evidencePass,
+    diffCoverageRequired,
+  });
+  const blockedReasons = dedupe([
+    ...structureFindingsFor({ selectedStage, selected, runbookStages, runbookSource, evidenceSource, executionBinding }),
+    ...subjectGuard.blocked_reasons,
+    ...(evidencePass ? [] : ['Stage 119 execution evidence binding is not pass-ready for selected stage']),
+    ...(diffCoverageRequired ? [] : ['selected stage has no required_files from Stage 118 runbook']),
+    ...commitReadinessGate.blocking_gaps.map((item) => `commit readiness gate gap: ${item}`),
+  ]).slice(0, 100);
+  const contractReady = blockedReasons.length === 0;
+  const readiness = {
+    version: 1,
+    stage: stagedCommitReadinessStage,
+    readiness_kind: stagedCommitReadinessKind,
+    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_evidence: {
+      file: evidenceSource.relative || evidenceSource.file || '',
+      digest: evidenceSource.digest || '',
+      binding_kind: executionBinding.binding_kind || '',
+      execution_evidence_digest: executionBinding.execution_evidence_digest || '',
+    },
+    source_bindings: {
+      runbook_stage: runbook.stage || '',
+      runbook_kind: runbook.runbook_kind || '',
+      stage_runbook_digest: runbook.stage_runbook_digest || '',
+      execution_evidence_stage: executionBinding.stage || '',
+      execution_evidence_kind: executionBinding.binding_kind || '',
+      execution_evidence_digest: executionBinding.execution_evidence_digest || '',
+      registry_stage: registry.registry_stage || '',
+      registry_kind: registry.registry_kind || '',
+      registry_version: registry.registry_version || 0,
+      registry_digest: registryDigest,
+    },
+    staged_commit_readiness: {
+      stage_id: selected?.stage_id || String(selectedStage || ''),
+      selected_stage_title: selected?.title || '',
+      runbook_stage_found: Boolean(selected),
+      suggested_commit_subject: commitReadinessGate.suggested_commit_subject,
+      subject_guard_pass: subjectGuard.pass,
+      subject_matches_runbook: subjectGuard.subject_matches_runbook,
+      evidence_pass: evidencePass,
+      stage_119_category_gate_pass: stageEvidenceCategoryGate?.pass === true,
+      commit_readiness_gate_pass: commitReadinessGate.pass,
+      diff_coverage_required: diffCoverageRequired,
+      diff_coverage_evidence_bound: commitReadinessGate.diff_coverage_evidence_bound,
+      required_file_count: requiredFiles.length,
+      validation_command_count: validationCommands.length,
+      required_evidence_category_count: commitReadinessGate.required_evidence_categories.length,
+      missing_evidence_category_count: commitReadinessGate.missing_evidence_categories.length,
+      contract_ready: contractReady,
+      commit_allowed_by_contract: false,
+      runtime_git_execution_authorized: false,
+      agent_commit_next_action_allowed: contractReady,
+    },
+    controlled_change_delivery: buildControlledChangeDeliveryContract({
+      phase: 'staged-commit-readiness-contract',
+      changeSetSummary: {
+        source_stage: stagedCommitReadinessStage,
+        selected_stage_id: selected?.stage_id || String(selectedStage || ''),
+        required_file_count: requiredFiles.length,
+        validation_command_count: validationCommands.length,
+        suggested_commit_subject: commitReadinessGate.suggested_commit_subject,
+      },
+      planTaskBinding: Boolean(selected),
+      diffCoverageBound: commitReadinessGate.diff_coverage_evidence_bound === true,
+      testEvidenceBound: stageEvidenceCategoryGate?.covered_categories?.includes('test') === true || stageEvidenceCategoryGate?.source_categories?.includes('test') === true,
+      reviewVerdictBound: stageEvidenceCategoryGate?.covered_categories?.includes('review') === true || stageEvidenceCategoryGate?.source_categories?.includes('review') === true,
+      commitSubjectBound: subjectGuard.pass === true,
+      rollbackNoteBound: false,
+      blockedReasons,
+      nextManualAction: contractReady
+        ? 'Use this readiness only for a separate human-approved local delivery decision; runtime git, PR, push, and merge remain unauthorized.'
+        : 'Resolve staged commit readiness blockers before any delivery decision.',
+    }),
+    stage_id: selected?.stage_id || String(selectedStage || ''),
+    suggested_commit_subject: commitReadinessGate.suggested_commit_subject,
+    subject_guard: subjectGuard,
+    commit_readiness_gate: commitReadinessGate,
+    required_files: requiredFiles,
+    validation_commands: validationCommands,
+    evidence_pass: evidencePass,
+    diff_coverage_required: diffCoverageRequired,
+    stage_evidence_category_gate: stageEvidenceCategoryGate ? [stageEvidenceCategoryGate] : [],
+    stage_evidence_status: stageEvidence ? [stageEvidence] : [],
+    blocked_reasons: blockedReasons,
+    commit_allowed_by_contract: false,
+    manual_or_agent_commit_next_action: manualOrAgentCommitNextAction(contractReady, selected, subjectGuard),
+    recovery_guidance: recoveryGuidance(blockedReasons, selected),
+    allowed_followup: ['manual or agent git status/diff review outside Stage 120', 'human-approved local git commit outside Stage 120', 'Stage 119 evidence repair before rerunning Stage 120'],
+    forbidden_actions: [
+      'runtime git status, diff, add, commit, push, PR, merge, tag, reset, checkout, or history rewrite',
+      'executing runbook validation commands, checks, tests, repair, formatting, or code generation',
+      'creating commit readiness artifacts, evidence artifacts, sidecars, or state directories',
+      'mutating source, runbook, evidence, worktree, or business files',
+      'platform API, external network, model, MCP, or subagent invocation',
+      'treating contract pass as runtime commit authorization',
+    ],
+    boundary_assertions: boundaryAssertions,
+    writes: false,
+    state_directory_created: false,
+    local_only: true,
+    deterministic: true,
+  };
+  const invariants = runtimeStagedCommitReadinessInvariants(readiness);
+  return {
+    ...readiness,
+    staged_commit_readiness_invariants: invariants,
+    manual_action: invariants.pass
+      ? 'Staged commit readiness is pass-ready as a local contract. Stage 120 did not call git or authorize runtime commit; commit remains a separate human-approved local action.'
+      : 'Resolve the listed staged commit readiness blockers before any manual or agent local commit.',
+  };
+}
+
+export function runtimeStagedCommitReadinessInvariants(readiness) {
+  const writableBoundaries = Object.entries(readiness.boundary_assertions || {})
+    .filter(([, value]) => value !== false)
+    .map(([key]) => key);
+  const forbiddenMissing = ['staged_commit_readiness_artifact', 'commit_artifact', 'evidence_artifact_write', 'sidecar_write', 'state_directory_created', 'source_write', 'runbook_mutation', 'evidence_mutation', 'worktree_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) => readiness.boundary_assertions?.[key] !== false);
+  const findings = [
+    ...(readiness.stage === stagedCommitReadinessStage ? [] : ['stage must be Stage 120']),
+    ...(readiness.readiness_kind === stagedCommitReadinessKind ? [] : ['readiness_kind must be staged-commit-readiness-contract']),
+    ...(readiness.source_runbook?.digest ? [] : ['missing local Stage 118 runbook source digest']),
+    ...(readiness.source_evidence?.digest ? [] : ['missing local Stage 119 evidence source digest']),
+    ...(readiness.source_bindings?.stage_runbook_digest ? [] : ['missing Stage 118 runbook digest binding']),
+    ...(readiness.source_bindings?.execution_evidence_digest ? [] : ['missing Stage 119 execution evidence digest binding']),
+    ...(readiness.staged_commit_readiness?.stage_id ? [] : ['missing selected stage_id']),
+    ...(readiness.subject_guard?.pass === true ? [] : ['subject_guard must pass']),
+    ...(readiness.commit_readiness_gate?.pass === true ? [] : ['commit_readiness_gate must pass']),
+    ...(readiness.staged_commit_readiness?.commit_readiness_gate_pass === true ? [] : ['nested commit_readiness_gate_pass must be true']),
+    ...(readiness.staged_commit_readiness?.subject_matches_runbook === true ? [] : ['subject must match selected Stage 118 runbook commit_subject']),
+    ...(readiness.evidence_pass === true ? [] : ['evidence_pass must be true']),
+    ...(readiness.stage_evidence_category_gate?.[0]?.pass === true ? [] : ['Stage 119 stage_evidence_category_gate must pass for selected stage']),
+    ...(readiness.commit_readiness_gate?.diff_coverage_evidence_bound === true ? [] : ['diff_coverage evidence must be bound before staged commit readiness']),
+    ...(readiness.diff_coverage_required === true ? [] : ['diff_coverage_required must be true']),
+    ...(readiness.commit_allowed_by_contract === false ? [] : ['commit_allowed_by_contract must remain false']),
+    ...(readiness.staged_commit_readiness?.commit_allowed_by_contract === false ? [] : ['nested commit_allowed_by_contract must remain false']),
+    ...(readiness.staged_commit_readiness?.runtime_git_execution_authorized === false ? [] : ['runtime_git_execution_authorized must remain false']),
+    ...((readiness.blocked_reasons || []).map((item) => `blocked: ${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_stage_118_runbook_binding',
+      'local_stage_119_execution_evidence_binding',
+      'selected_stage_binding',
+      'subject_guard',
+      'suggested_commit_subject_bound_to_runbook',
+      'commit_readiness_gate',
+      'stage_119_category_gate_binding',
+      'required_files_present',
+      'validation_evidence_present',
+      'evidence_pass',
+      'diff_coverage_evidence_bound',
+      'diff_coverage_required',
+      'commit_allowed_by_contract_false',
+      'no_git_or_command_execution',
+      'read_only_boundary_assertions',
+    ],
+    findings,
+  };
+}
+
+export function runtimeStagedCommitReadinessBoundaryAssertions() {
+  return {
+    staged_commit_readiness_artifact: false,
+    commit_readiness_artifact: false,
+    commit_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,
+    worktree_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 runtimeStagedCommitReadinessDigestPayload(readiness) {
+  return {
+    stage: readiness.stage,
+    readiness_kind: readiness.readiness_kind,
+    source_runbook: readiness.source_runbook,
+    source_evidence: readiness.source_evidence,
+    source_bindings: readiness.source_bindings,
+    staged_commit_readiness: readiness.staged_commit_readiness,
+    controlled_change_delivery: readiness.controlled_change_delivery,
+    stage_id: readiness.stage_id,
+    suggested_commit_subject: readiness.suggested_commit_subject,
+    subject_guard: readiness.subject_guard,
+    commit_readiness_gate: readiness.commit_readiness_gate,
+    required_files: readiness.required_files,
+    validation_commands: readiness.validation_commands,
+    evidence_pass: readiness.evidence_pass,
+    diff_coverage_required: readiness.diff_coverage_required,
+    stage_evidence_category_gate: readiness.stage_evidence_category_gate,
+    stage_evidence_status: readiness.stage_evidence_status,
+    blocked_reasons: readiness.blocked_reasons,
+    commit_allowed_by_contract: readiness.commit_allowed_by_contract,
+    manual_or_agent_commit_next_action: readiness.manual_or_agent_commit_next_action,
+    recovery_guidance: readiness.recovery_guidance,
+    allowed_followup: readiness.allowed_followup,
+    forbidden_actions: readiness.forbidden_actions,
+    boundary_assertions: readiness.boundary_assertions,
+    staged_commit_readiness_invariants: readiness.staged_commit_readiness_invariants,
+  };
+}
+
+export function digestStagedCommitReadiness(value) {
+  return crypto.createHash('sha256').update(stableStringify(value)).digest('hex');
+}
+
+function normalizeRunbookStages(runbook) {
+  const stages = Array.isArray(runbook.stage_sequence) ? runbook.stage_sequence : [];
+  return stages.map((stage, index) => ({
+    stage_id: String(stage.stage_id || `stage120-runbook-stage-${String(index + 1).padStart(2, '0')}`),
+    title: String(stage.title || stage.stage_id || ''),
+    sequence_index: Number(stage.sequence_index || index + 1),
+    files_to_change: arrayOfStrings(stage.files_to_change),
+    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 || ''),
+  }));
+}
+
+function selectRunbookStage(stages, selectedStage) {
+  const selected = String(selectedStage || '').trim();
+  if (!selected) return null;
+  return stages.find((stage) => stage.stage_id === selected || stage.title === selected || String(stage.sequence_index) === selected || String(stage.stage || '') === selected) || null;
+}
+
+function normalizeExecutionEvidenceBinding(evidence) {
+  const binding = evidence?.execution_evidence_binding?.binding_kind === 'execution-evidence-binding'
+    ? evidence.execution_evidence_binding
+    : evidence?.binding_kind === 'execution-evidence-binding'
+      ? evidence
+      : null;
+  if (!binding) {
+    return {
+      stage: '',
+      binding_kind: '',
+      execution_evidence_digest: '',
+      binding_pass: false,
+      ready_for_next_stage: false,
+      stage_evidence_status: [],
+    };
+  }
+  return {
+    ...binding,
+    binding_pass: binding.execution_evidence_invariants?.pass === true,
+    ready_for_next_stage: binding.ready_for_next_stage === true,
+    stage_evidence_status: arrayOfObjects(binding.stage_evidence_status),
+  };
+}
+
+function evidenceStatusForStage(binding, stage) {
+  return (binding.stage_evidence_status || []).find((item) => item.stage_id === stage.stage_id || item.title === stage.title || String(item.sequence_index) === String(stage.sequence_index)) || null;
+}
+
+function evidenceCategoryGateForStage(binding, stage, stageEvidence) {
+  const directGate = arrayOfObjects(binding.stage_evidence_category_gate)
+    .find((item) => item.stage_id === stage.stage_id || item.title === stage.title || String(item.sequence_index) === String(stage.sequence_index));
+  const rawGate = directGate || stageEvidence?.evidence_category_gate || null;
+  const evidenceItems = arrayOfObjects(stageEvidence?.evidence_items);
+  const categorySources = arrayOfObjects(rawGate?.category_sources);
+  const sourceCategories = dedupe([
+    ...categorySources.map((item) => item.category),
+    ...evidenceItems.map((item) => item.category),
+  ]);
+  const requiredCategories = dedupe(arrayOfStrings(rawGate?.required_categories));
+  const coveredCategories = dedupe([
+    ...arrayOfStrings(rawGate?.covered_categories),
+    ...sourceCategories,
+  ]);
+  const missingCategories = dedupe(arrayOfStrings(rawGate?.missing_categories));
+  return {
+    gate_kind: 'stage-119-evidence-category-gate-binding',
+    stage_id: stage.stage_id,
+    source_gate_found: Boolean(rawGate),
+    required_categories: requiredCategories,
+    covered_categories: coveredCategories,
+    missing_categories: missingCategories,
+    source_categories: sourceCategories,
+    category_sources: categorySources,
+    stage_119_gate_pass: rawGate?.pass === true,
+    diff_coverage_evidence_bound: coveredCategories.includes('diff_coverage') || sourceCategories.includes('diff_coverage'),
+    execution_authorized: false,
+    pass: Boolean(rawGate) && rawGate.pass === true && missingCategories.length === 0,
+  };
+}
+
+function commitReadinessGateFor({ selected, subjectGuard, requiredFiles, validationCommands, stageEvidence, stageEvidenceCategoryGate, evidencePass, diffCoverageRequired }) {
+  const requiredEvidenceCategories = dedupe([
+    ...arrayOfStrings(stageEvidence?.required_evidence_categories),
+    ...arrayOfStrings(stageEvidenceCategoryGate?.required_categories),
+    ...(diffCoverageRequired ? ['diff_coverage'] : []),
+  ]);
+  const diffCoverageEvidenceBound = stageEvidenceCategoryGate?.diff_coverage_evidence_bound === true;
+  const missingEvidenceCategories = dedupe([
+    ...arrayOfStrings(stageEvidenceCategoryGate?.missing_categories),
+    ...(diffCoverageRequired && !diffCoverageEvidenceBound ? ['diff_coverage'] : []),
+  ]);
+  const blockingGaps = dedupe([
+    ...(selected ? [] : ['selected Stage 118 runbook stage is required']),
+    ...(subjectGuard.pass ? [] : ['suggested commit subject must pass and match runbook']),
+    ...(requiredFiles.length > 0 ? [] : ['required_files must be present for selected stage']),
+    ...(validationCommands.length > 0 ? [] : ['validation_commands must be present for selected stage']),
+    ...(evidencePass ? [] : ['Stage 119 execution evidence must be pass-ready']),
+    ...(stageEvidence?.ready_for_next_stage === true ? [] : ['selected Stage 119 evidence status must be ready_for_next_stage=true']),
+    ...(stageEvidenceCategoryGate?.source_gate_found ? [] : ['Stage 119 stage_evidence_category_gate must be present for selected stage']),
+    ...(stageEvidenceCategoryGate?.pass === true ? [] : ['Stage 119 stage_evidence_category_gate must pass for selected stage']),
+    ...(diffCoverageRequired ? [] : ['diff coverage is required whenever files_to_change is present']),
+    ...(diffCoverageRequired && diffCoverageEvidenceBound ? [] : ['diff_coverage evidence category must be bound before commit readiness']),
+  ]);
+  return {
+    gate_kind: 'stage-120-staged-commit-readiness-gate',
+    stage_id: selected?.stage_id || '',
+    suggested_commit_subject: subjectGuard.expected_subject || subjectGuard.subject,
+    subject_matches_runbook: subjectGuard.subject_matches_runbook,
+    required_file_count: requiredFiles.length,
+    validation_command_count: validationCommands.length,
+    required_evidence_categories: requiredEvidenceCategories,
+    missing_evidence_categories: missingEvidenceCategories,
+    stage_119_category_gate_pass: stageEvidenceCategoryGate?.pass === true,
+    diff_coverage_required: diffCoverageRequired,
+    diff_coverage_evidence_bound: diffCoverageEvidenceBound,
+    validation_evidence_ready: evidencePass === true && stageEvidence?.ready_for_next_stage === true,
+    runtime_git_execution_authorized: false,
+    command_execution_authorized: false,
+    commit_execution_authorized: false,
+    blocking_gaps: blockingGaps,
+    pass: blockingGaps.length === 0,
+  };
+}
+
+function subjectGuardFor(subject, stage) {
+  const normalizedSubject = String(subject || '').trim();
+  const expectedSubject = String(stage?.commit_subject || '').trim();
+  const findings = [];
+  if (!normalizedSubject) findings.push('subject is required');
+  if (/^`{3,}|```/.test(normalizedSubject)) findings.push('subject must not contain markdown fences');
+  if (normalizedSubject.length > 120) findings.push('subject should be 120 characters or less');
+  if (normalizedSubject && !/^(feat|fix|docs|chore|refactor|test|build|ci|perf|style|revert|release|runtime)(\([^)]+\))?:\s+/.test(normalizedSubject)) findings.push('subject should follow conventional commit format');
+  if (expectedSubject && normalized(expectedSubject) !== normalized(normalizedSubject)) findings.push('subject must match selected Stage 118 runbook commit_subject');
+  return {
+    subject: normalizedSubject,
+    expected_subject: expectedSubject,
+    subject_matches_runbook: Boolean(expectedSubject) && normalized(expectedSubject) === normalized(normalizedSubject),
+    conventional_subject: /^(feat|fix|docs|chore|refactor|test|build|ci|perf|style|revert|release|runtime)(\([^)]+\))?:\s+/.test(normalizedSubject),
+    commit_execution_authorized: false,
+    pass: findings.length === 0,
+    blocked_reasons: findings,
+  };
+}
+
+function structureFindingsFor({ selectedStage, selected, runbookStages, runbookSource, evidenceSource, executionBinding }) {
+  const findings = [];
+  if (!runbookSource.digest) findings.push('missing local Stage 118 runbook file digest');
+  if (!evidenceSource.digest) findings.push('missing local Stage 119 execution evidence file digest');
+  if (runbookStages.length === 0) findings.push('Stage 118 runbook has no stage_sequence');
+  if (!String(selectedStage || '').trim()) findings.push('--stage is required for staged commit readiness');
+  if (!selected) findings.push(`selected stage not found in Stage 118 runbook: ${selectedStage || 'missing'}`);
+  if (!executionBinding.binding_kind) findings.push('local evidence must be a Stage 119 execution evidence binding envelope');
+  if (executionBinding.stage && executionBinding.stage !== 'Stage 119') findings.push('execution evidence binding stage must be Stage 119');
+  if (executionBinding.binding_kind && executionBinding.binding_kind !== 'execution-evidence-binding') findings.push('execution evidence binding kind must be execution-evidence-binding');
+  return findings;
+}
+
+function manualOrAgentCommitNextAction(contractReady, stage, subjectGuard) {
+  if (!contractReady) return 'Stop before local commit. Repair the runbook/evidence/subject blockers and rerun release --staged-commit-readiness.';
+  return `Runtime contract is ready for a separate human-approved local commit outside Stage 120 using subject: ${subjectGuard.subject || stage?.commit_subject || '<subject-required>'}. Do not push, PR, merge, tag, amend, or rewrite history.`;
+}
+
+function recoveryGuidance(blockedReasons, stage) {
+  if (blockedReasons.length === 0) return 'If the subsequent manual commit fails, keep the worktree intact, capture the failure as local evidence, and rerun Stage 119 then Stage 120.';
+  return `Recover by fixing the earliest blocker for ${stage?.stage_id || 'the selected stage'}: ${blockedReasons[0] || 'unknown blocker'}. Stage 120 must not repair files or run git.`;
+}
+
+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-state-directory-model.mjs

@@ -0,0 +1,7 @@
+import path from 'node:path';
+
+export const stateDirectoryName = '.vibecoding-state';
+
+export function stateDirectory(root) {
+  return path.join(path.resolve(root), stateDirectoryName);
+}

package/tools/vibe-runtime/runtime-state-io.mjs

@@ -0,0 +1,41 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function readJsonArtifact(file, label) {
+  if (!fs.existsSync(file)) throw new Error(`${label} file not found: ${path.basename(file)}`);
+  if (!fs.statSync(file).isFile()) throw new Error(`${label} is not a file: ${path.basename(file)}`);
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    throw new Error(`${label} JSON is invalid: ${path.basename(file)}`);
+  }
+}
+
+export function writeStateArtifact(directory, fileName, payload) {
+  fs.mkdirSync(directory, { recursive: true });
+  const file = path.join(directory, fileName);
+  fs.writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+  return file;
+}
+
+export function fileDigest(file) {
+  if (!fs.existsSync(file)) return '';
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+export function optionalFileDigest(file) {
+  return fs.existsSync(file) && fs.statSync(file).isFile() ? fileDigest(file) : '';
+}
+
+export function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export function digestObject(value) {
+  return crypto.createHash('sha256').update(stableJson(value)).digest('hex');
+}