@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-control-plane-readonly-command.mjs

@@ -0,0 +1,537 @@
+import path from 'node:path';
+import process from 'node:process';
+
+const runtimeReadOnlyCommandContractSyncSurface = 'runtime-cli-usage runtime-cli-args runtime-cli-dispatch tools/vibe-release-check';
+
+export function createRuntimeControlPlaneReadOnlyCommands(commandDeps) {
+  const deps = commandDeps;
+  const {
+    ensureRoot,
+    emitReviewJsonEnvelope,
+    emitFeedbackJsonEnvelope,
+    printList,
+    localTextEvidenceDescriptor,
+    planActionManifestEnvelope,
+    runtimeAutomationReadinessEnvelope,
+    runtimeCapabilityRegistry,
+    runtimeStatePresent,
+    workflowStatePresent,
+    runtimeReviewIntakeEnvelope,
+    runtimeReviewIntakeDigestPayload,
+    runtimeReviewResolutionEnvelope,
+    runtimeReviewResolutionDigestPayload,
+    digestReviewEnvelope,
+    runReleaseCommand,
+    releaseDeps,
+    digestObject,
+    runtimePolicyCatalogDigest,
+    validateRuntimePolicyCatalogDigest,
+    stateDirectoryName,
+    feedbackLedgersDirectoryName,
+    feedbackLedgerSnapshotPath,
+    feedbackLedgerFilePath,
+    readJsonArtifact,
+    fileDigest,
+    artifactPayloadDigest,
+    plannerRouteFilePath,
+    plannerPlanFilePath,
+    plannerBriefsFilePath,
+    validatePlannerArtifact,
+    routerPlanFilePath,
+    routerApprovalFilePath,
+    validateRouterArtifact,
+    orchestratorPlanFilePath,
+    orchestratorDispatchPlanFilePath,
+    validateOrchestratorArtifact,
+    evalReportFilePath,
+    validateEvalArtifact,
+    releaseGateFilePath,
+    validateReleaseGateArtifact,
+    feedbackSafety,
+    validateStage53Safety,
+    feedbackPreviewAction,
+    feedbackPersistAction,
+    feedbackAuditAction,
+    persistFeedbackLedgerPayload,
+    jsonSchemaVersion,
+  } = deps;
+
+  if (!runtimeReadOnlyCommandContractSyncSurface.includes('runtime-cli-usage')) throw new Error('runtime read-only command contract sync marker missing');
+
+  function reviewIntakeEnvelope(root, reviewFile, { planFile = '' } = {}) {
+    ensureRoot(root);
+    if (!reviewFile) throw new Error('review --intake requires --from-file <local-review-file>');
+    const source = localTextEvidenceDescriptor(root, reviewFile, 'review --intake source');
+    let review;
+    try {
+      review = JSON.parse(source.text);
+    } catch (error) {
+      throw new Error(`review --intake requires JSON review input: ${error.message}`);
+    }
+    const planManifest = planFile ? planActionManifestEnvelope(root, planFile, { intent: 'implementation' }).plan_action_manifest : null;
+    const automationEnvelope = runtimeAutomationReadinessEnvelope(root);
+    const registry = runtimeCapabilityRegistry();
+    const intake = runtimeReviewIntakeEnvelope({
+      review,
+      reviewSource: source,
+      planActionManifest: planManifest,
+      registry,
+      registryDigest: automationEnvelope.runtime_automation_readiness.registry_digest,
+    });
+    const reviewIntake = {
+      ...intake,
+      review_intake_digest: digestReviewEnvelope(runtimeReviewIntakeDigestPayload(intake)),
+    };
+    return {
+      mode: 'review-intake-envelope',
+      ok: reviewIntake.review_intake_invariants.pass,
+      state_present: runtimeStatePresent(root),
+      review_intake: reviewIntake,
+      safety: { stage: 'Stage 112', ...reviewIntake.boundary_assertions },
+      quality: reviewIntake.review_intake_invariants.findings,
+      action: deps.reviewIntakeAction,
+    };
+  }
+
+  function reviewResolutionEnvelope(root, reviewIntakeFile, { evidenceFile = '' } = {}) {
+    ensureRoot(root);
+    if (!reviewIntakeFile) throw new Error('review --resolution requires --from-file <local-review-intake-file>');
+    if (!evidenceFile) throw new Error('review --resolution requires --from-evidence <local-evidence-file>');
+    const intakeSource = localTextEvidenceDescriptor(root, reviewIntakeFile, 'review --resolution intake source');
+    const evidenceSource = localTextEvidenceDescriptor(root, evidenceFile, 'review --resolution evidence source');
+    let reviewIntake;
+    let evidence;
+    try {
+      reviewIntake = JSON.parse(intakeSource.text);
+    } catch (error) {
+      throw new Error(`review --resolution requires JSON review intake: ${error.message}`);
+    }
+    try {
+      evidence = JSON.parse(evidenceSource.text);
+    } catch (error) {
+      throw new Error(`review --resolution requires JSON evidence: ${error.message}`);
+    }
+    const automationEnvelope = runtimeAutomationReadinessEnvelope(root);
+    const registry = runtimeCapabilityRegistry();
+    const resolution = runtimeReviewResolutionEnvelope({
+      reviewIntake,
+      reviewIntakeSource: intakeSource,
+      evidence,
+      evidenceSource,
+      registry,
+      registryDigest: automationEnvelope.runtime_automation_readiness.registry_digest,
+    });
+    const reviewResolution = {
+      ...resolution,
+      review_resolution_digest: digestReviewEnvelope(runtimeReviewResolutionDigestPayload(resolution)),
+    };
+    return {
+      mode: 'review-resolution-envelope',
+      ok: reviewResolution.review_resolution_invariants.pass,
+      state_present: runtimeStatePresent(root),
+      review_resolution: reviewResolution,
+      safety: { stage: 'Stage 112', ...reviewResolution.boundary_assertions },
+      quality: reviewResolution.review_resolution_invariants.findings,
+      action: deps.reviewResolutionAction,
+    };
+  }
+
+  function printReviewIntake(envelope) {
+    const intake = envelope.review_intake;
+    console.log('Vibecoding Runtime Review Intake Envelope');
+    console.log(`Stage: ${intake.stage}; Kind: ${intake.review_kind}; pass=${intake.review_intake_invariants.pass}`);
+    console.log(`Review: items=${intake.review_intake.review_item_count}; impacted_files=${intake.review_intake.impacted_file_count}; impacted_action_items=${intake.review_intake.impacted_action_item_count}; required_evidence=${intake.review_intake.required_evidence_count}; reviewer_invoked_by_stage_112=false; repair_executed_by_stage_112=false`);
+    for (const item of intake.review_items) console.log(`- ${item.id}: severity=${item.severity}; files=${item.impacted_files.join(', ') || 'none'}; execution_authorized=false`);
+    console.log(`Review feedback gate: stage=${intake.review_feedback_gate?.stage}; kind=${intake.review_feedback_gate?.gate_kind}; phase=${intake.review_feedback_gate?.phase}; next_task_blocked=${intake.next_task_gate?.blocked}`);
+    printList('Review feedback blockers', intake.next_task_gate?.blocked_reasons || []);
+    console.log(`Source bindings: review=${intake.source_review.digest}; plan_action_manifest=${intake.source_bindings.plan_action_manifest_digest || 'not-provided'}; registry=${intake.source_bindings.registry_digest}`);
+    printList('Required evidence', intake.required_evidence);
+    printList('Forbidden actions', intake.forbidden_actions);
+    console.log(deps.reviewBoundaryLine);
+    console.log(`Review intake digest: ${intake.review_intake_digest}`);
+    if (intake.blocked_reasons.length > 0) printList('Blocked reasons', intake.blocked_reasons);
+    console.log(`Manual action: ${intake.manual_action}`);
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  function printReviewResolution(envelope) {
+    const resolution = envelope.review_resolution;
+    console.log('Vibecoding Runtime Review Resolution Envelope');
+    console.log(`Stage: ${resolution.stage}; Kind: ${resolution.review_kind}; pass=${resolution.review_resolution_invariants.pass}`);
+    console.log(`Resolution: items=${resolution.review_resolution.resolution_item_count}; resolved=${resolution.review_resolution.resolved_count}; accepted_risk=${resolution.review_resolution.accepted_risk_count}; missing_evidence=${resolution.review_resolution.missing_evidence_count}; reviewer_invoked_by_stage_112=false; repair_executed_by_stage_112=false`);
+    for (const item of resolution.resolution_items) console.log(`- ${item.review_id}: resolved=${item.resolved}; accepted_risk=${item.accepted_risk}; missing=${item.missing_evidence.length}; execution_authorized=false`);
+    console.log(`Review feedback gate: stage=${resolution.review_feedback_gate?.stage}; kind=${resolution.review_feedback_gate?.gate_kind}; phase=${resolution.review_feedback_gate?.phase}; next_task_blocked=${resolution.next_task_gate?.blocked}`);
+    printList('Review feedback blockers', resolution.next_task_gate?.blocked_reasons || []);
+    console.log(`Source bindings: review_intake=${resolution.source_review_intake.digest}; evidence=${resolution.source_evidence.digest}; registry=${resolution.source_bindings.registry_digest}`);
+    printList('Missing evidence', resolution.missing_evidence);
+    printList('Forbidden actions', resolution.forbidden_actions);
+    console.log(deps.reviewBoundaryLine);
+    console.log(`Review resolution digest: ${resolution.review_resolution_digest}`);
+    if (resolution.blocked_reasons.length > 0) printList('Blocked reasons', resolution.blocked_reasons);
+    console.log(`Manual action: ${resolution.manual_action}`);
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  function runReview(options) {
+    ensureRoot(options.root);
+    const modes = [options.reviewIntake, options.reviewResolution].filter(Boolean);
+    if (modes.length !== 1) throw new Error('review requires exactly one mode: --intake or --resolution');
+    if (options.confirm || options.dryRun || options.recoveryPreview || options.hooksPreview || options.write || options.run || options.autoRun || options.scan || options.once || options.preflight || options.dispatch || options.dispatchIntent) throw new Error('review read-only modes do not accept execution, dispatch, confirm, preview, dry-run, run, scan, preflight, or write flags');
+    if (!options.fromFile) throw new Error(options.reviewResolution ? 'review --resolution requires --from-file <local-review-intake-file>' : 'review --intake requires --from-file <local-review-file>');
+    if (options.methodologyIntent || options.commitSubject || options.fromReadiness || options.plannerFile || options.plannerFromHook || options.methodologyKind || options.learningObservationFiles.length > 0 || options.learningInstinctFile || options.tokenCompactionFiles.length > 0) throw new Error('review read-only modes only accept local review, optional local plan, local evidence, and read-only output flags');
+    if (options.reviewIntake) {
+      if (options.fromEvidence) throw new Error('--from-evidence is only supported by review --resolution');
+      const envelope = reviewIntakeEnvelope(options.root, options.fromFile, { planFile: options.fromPlan });
+      if (options.json) emitReviewJsonEnvelope(envelope);
+      else printReviewIntake(envelope);
+      return;
+    }
+    if (options.fromPlan) throw new Error('--from-plan is only supported by review --intake');
+    if (!options.fromEvidence) throw new Error('review --resolution requires --from-evidence <local-evidence-file>');
+    const envelope = reviewResolutionEnvelope(options.root, options.fromFile, { evidenceFile: options.fromEvidence });
+    if (options.json) emitReviewJsonEnvelope(envelope);
+    else printReviewResolution(envelope);
+  }
+
+  function releaseCommandDeps() {
+    return releaseDeps();
+  }
+
+  function runRelease(options) {
+    return runReleaseCommand(releaseCommandDeps(), options);
+  }
+
+  function feedbackSourceDefinitions() {
+    return {
+      planner: [
+        { suffix: '.planner-route.json', type: 'planner-route', pathFor: plannerRouteFilePath, extract: (artifact) => artifact.planner_route || {}, validate: validatePlannerArtifact },
+        { suffix: '.planner-plan.json', type: 'planner-plan', pathFor: plannerPlanFilePath, extract: (artifact) => artifact.planner_plan || {}, validate: validatePlannerArtifact },
+        { suffix: '.planner-briefs.json', type: 'planner-briefs', pathFor: plannerBriefsFilePath, extract: (artifact) => artifact.planner_briefs || {}, validate: validatePlannerArtifact },
+      ],
+      router: [
+        { suffix: '.router-plan.json', type: 'router-plan', pathFor: routerPlanFilePath, extract: (artifact) => artifact.router_plan || {}, validate: validateRouterArtifact },
+        { suffix: '.router-approval.json', type: 'router-approval', pathFor: routerApprovalFilePath, extract: (artifact) => artifact.router_approval || {}, validate: validateRouterArtifact },
+      ],
+      orchestrator: [
+        { suffix: '.orchestrator-plan.json', type: 'orchestrator-plan', pathFor: orchestratorPlanFilePath, extract: (artifact) => artifact.orchestrator_plan || {}, validate: validateOrchestratorArtifact },
+        { suffix: '.orchestrator-dispatch-plan.json', type: 'orchestrator-dispatch-plan', pathFor: orchestratorDispatchPlanFilePath, extract: (artifact) => artifact.orchestrator_dispatch_plan || {}, validate: validateOrchestratorArtifact },
+      ],
+      eval: [
+        { suffix: '.eval-report.json', type: 'eval-report', pathFor: evalReportFilePath, extract: (artifact) => artifact.eval_report || {}, validate: validateEvalArtifact },
+      ],
+      release_gate: [
+        { suffix: '.release-gate.json', type: 'release-gate', pathFor: releaseGateFilePath, extract: (artifact) => artifact.release_gate || {}, validate: validateReleaseGateArtifact },
+      ],
+    };
+  }
+
+  function resolveFeedbackSource(root, family, fileName) {
+    const raw = String(fileName || '').trim();
+    if (!raw) throw new Error(`feedback ${family} source file is required`);
+    const definition = (feedbackSourceDefinitions()[family] || []).find((item) => raw.endsWith(item.suffix));
+    if (!definition) throw new Error(`unsupported feedback ${family} source file: ${raw}`);
+    const file = definition.pathFor(root, raw);
+    const artifact = readJsonArtifact(file, definition.type);
+    const verification = definition.validate(root, artifact, path.basename(file));
+    if (!verification.ok) throw new Error(`${definition.type} verification failed: ${verification.failures.join('; ')}`);
+    return {
+      family,
+      type: definition.type,
+      file: path.basename(file),
+      path: file,
+      digest: fileDigest(file),
+      artifact_digest: artifactPayloadDigest(artifact),
+      command: artifact.command || '',
+      mode: artifact.mode || '',
+      stage: definition.extract(artifact).stage || '',
+      payload: definition.extract(artifact),
+    };
+  }
+
+  function feedbackEntry(source, category, message, details = {}) {
+    const normalizedMessage = String(message || '').trim();
+    if (!normalizedMessage) return null;
+    const entry = {
+      source_family: source.family,
+      source_type: source.type,
+      source_file: source.file,
+      source_digest: source.digest,
+      category,
+      severity: details.severity || 'info',
+      message: normalizedMessage,
+      required_gates: [...new Set(details.required_gates || [])].sort(),
+      fallback: details.fallback || null,
+      budget: details.budget || null,
+      eval: details.eval || null,
+    };
+    return { ...entry, entry_digest: digestObject(entry) };
+  }
+
+  function feedbackEntriesForSource(source) {
+    const data = source.payload || {};
+    const entries = [];
+    for (const reason of data.blocked_reasons || []) entries.push(feedbackEntry(source, 'blocked-reason', reason, { severity: 'warning' }));
+    for (const gate of data.required_gates || []) entries.push(feedbackEntry(source, 'required-gate', gate, { required_gates: [gate] }));
+    for (const gate of data.allowed_followup || []) entries.push(feedbackEntry(source, 'required-followup', gate, { required_gates: [gate] }));
+    for (const route of data.fallback_routes || []) entries.push(feedbackEntry(source, 'fallback', route.reason || route.action || route.fallback || 'fallback route selected', { fallback: route, severity: 'info' }));
+    for (const rule of data.escalation_rules || []) entries.push(feedbackEntry(source, 'fallback', `${rule.when || 'condition'} -> ${rule.action || 'action'}`, { fallback: rule }));
+    for (const group of data.mutex_groups || []) entries.push(feedbackEntry(source, 'concurrency', group.reason || group.group_id || 'mutex group requires serialization', { budget: group }));
+    if (data.concurrency_budget) entries.push(feedbackEntry(source, 'concurrency', data.concurrency_budget.mode || 'concurrency budget recorded', { budget: data.concurrency_budget }));
+    for (const feedback of data.planner_feedback || []) entries.push(feedbackEntry(source, 'planner-feedback', feedback, { severity: 'warning', eval: { suite_id: data.suite_id || '', eval_kind: data.eval_kind || '' } }));
+    for (const feedback of data.router_feedback || []) entries.push(feedbackEntry(source, 'router-feedback', feedback, { severity: 'warning', eval: { suite_id: data.suite_id || '', eval_kind: data.eval_kind || '' } }));
+    for (const failure of data.gate_failures || []) entries.push(feedbackEntry(source, 'gate-failure', failure, { severity: 'error', eval: { suite_id: data.suite_id || '', eval_kind: data.eval_kind || '' } }));
+    for (const caseId of data.failing_case_ids || []) entries.push(feedbackEntry(source, 'eval-failing-case', caseId, { severity: 'error', eval: { suite_id: data.suite_id || '', eval_kind: data.eval_kind || '', case_id: caseId } }));
+    if (data.gate_status === 'blocked') entries.push(feedbackEntry(source, 'release-blocked', 'release gate blocked by upstream eval evidence', { severity: 'error' }));
+    return entries.filter(Boolean).sort((left, right) => left.category.localeCompare(right.category) || left.message.localeCompare(right.message) || left.source_file.localeCompare(right.source_file));
+  }
+
+  function buildFeedbackSourceList(root, options) {
+    const requested = [
+      ...options.feedbackPlannerFiles.map((file) => ['planner', file]),
+      ...options.feedbackRouterFiles.map((file) => ['router', file]),
+      ...options.feedbackOrchestratorFiles.map((file) => ['orchestrator', file]),
+      ...options.feedbackEvalFiles.map((file) => ['eval', file]),
+      ...options.feedbackReleaseGateFiles.map((file) => ['release_gate', file]),
+    ];
+    const unique = [];
+    const seen = new Set();
+    for (const [family, file] of requested) {
+      const key = `${family}:${file}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      unique.push(resolveFeedbackSource(root, family, file));
+    }
+    return unique;
+  }
+
+  function feedbackCoverageSummary(sources, entries) {
+    const source_types = Object.fromEntries([...new Set(sources.map((source) => source.type))].sort().map((type) => [type, sources.filter((source) => source.type === type).length]));
+    const categories = Object.fromEntries([...new Set(entries.map((entry) => entry.category))].sort().map((category) => [category, entries.filter((entry) => entry.category === category).length]));
+    return {
+      source_count: sources.length,
+      entry_count: entries.length,
+      source_types,
+      categories,
+      blocked_reason_count: entries.filter((entry) => entry.category === 'blocked-reason' || entry.category === 'release-blocked').length,
+      fallback_count: entries.filter((entry) => entry.category === 'fallback').length,
+      required_gate_count: entries.filter((entry) => entry.required_gates.length > 0).length,
+      eval_feedback_count: entries.filter((entry) => ['planner-feedback', 'router-feedback', 'gate-failure', 'eval-failing-case'].includes(entry.category)).length,
+      concurrency_signal_count: entries.filter((entry) => entry.category === 'concurrency').length,
+    };
+  }
+
+  function buildFeedbackLedgerEnvelope(root, options, { persist = false, artifactFile = '' } = {}) {
+    ensureRoot(root);
+    const sources = buildFeedbackSourceList(root, options);
+    if (sources.length === 0) throw new Error('feedback --ledger requires at least one source artifact');
+    const sourceDescriptors = sources.map((source) => ({
+      family: source.family,
+      type: source.type,
+      file: source.file,
+      digest: source.digest,
+      artifact_digest: source.artifact_digest,
+      command: source.command,
+      mode: source.mode,
+      stage: source.stage,
+    })).sort((left, right) => left.family.localeCompare(right.family) || left.type.localeCompare(right.type) || left.file.localeCompare(right.file));
+    const entries = sources.flatMap((source) => feedbackEntriesForSource(source))
+      .sort((left, right) => left.source_family.localeCompare(right.source_family)
+        || left.source_type.localeCompare(right.source_type)
+        || left.source_file.localeCompare(right.source_file)
+        || left.category.localeCompare(right.category)
+        || left.message.localeCompare(right.message)
+        || digestObject(left).localeCompare(digestObject(right)));
+    const coverage = feedbackCoverageSummary(sourceDescriptors, entries);
+    const ledgerFile = artifactFile || (persist ? path.basename(feedbackLedgerSnapshotPath(root)) : 'preview.feedback-ledger.json');
+    const core = {
+      version: 1,
+      stage: 'Stage 53',
+      created_at: new Date().toISOString(),
+      writes: Boolean(persist),
+      ledger_kind: 'runtime-feedback-ledger',
+      source_families: [...new Set(sourceDescriptors.map((source) => source.family))].sort(),
+      sources: sourceDescriptors,
+      entries,
+      coverage,
+      policy_catalog_digest: runtimePolicyCatalogDigest(),
+      evidence: {
+        sources_digest: digestObject(sourceDescriptors),
+        entries_digest: digestObject(entries),
+        coverage_digest: digestObject(coverage),
+        sidecar_only: true,
+      },
+      allowed_followup: [],
+      dispatch: false,
+      session_create: false,
+      platform_api: false,
+      external_network: false,
+      model_invocation: false,
+      runtime_action: false,
+      business_source_write: false,
+      source_merge: false,
+      pr: false,
+      push: false,
+      merge: false,
+      git: false,
+      worktree: false,
+      planned_writes: persist ? [path.join(stateDirectoryName, feedbackLedgersDirectoryName, '<timestamp>.feedback-ledger.json').replace(/\\/g, '/')] : [],
+    };
+    return {
+      mode: 'feedback-ledger',
+      ok: true,
+      state_present: workflowStatePresent(root),
+      feedback_ledger: { ...core, ledger_digest: digestObject(core) },
+      files: { feedback_ledger: ledgerFile },
+      safety: feedbackSafety({ writes: persist, artifact: persist }),
+      quality: entries.filter((entry) => entry.severity === 'error' || entry.severity === 'warning').map((entry) => entry.message),
+      action: persist ? feedbackPersistAction : feedbackPreviewAction,
+    };
+  }
+
+  function validateFeedbackLedgerArtifact(root, artifact, fileName = '') {
+    const failures = [];
+    if (artifact.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+    if (artifact.command !== 'feedback') failures.push('command must be feedback');
+    if (artifact.mode !== 'feedback-ledger') failures.push('mode must be feedback-ledger');
+    if (artifact.ok !== true) failures.push('feedback ledger artifact ok must be true');
+    if (fileName && artifact.files?.feedback_ledger !== fileName) failures.push('Stage 53 feedback ledger file identity mismatch');
+    failures.push(...validateStage53Safety(artifact.safety, 'feedback_ledger_artifact'));
+    if (artifact.safety?.writes !== true) failures.push('safety.writes must be true');
+
+    const ledger = artifact.feedback_ledger || {};
+    if (ledger.version !== 1) failures.push('feedback_ledger.version must be 1');
+    if (ledger.stage !== 'Stage 53') failures.push('feedback_ledger.stage must be Stage 53');
+    if (ledger.writes !== true) failures.push('feedback_ledger.writes must be true');
+    if (ledger.ledger_kind !== 'runtime-feedback-ledger') failures.push('feedback_ledger.ledger_kind must be runtime-feedback-ledger');
+    if (!Array.isArray(ledger.sources) || ledger.sources.length === 0) failures.push('feedback_ledger.sources must be a non-empty array');
+    if (!Array.isArray(ledger.entries)) failures.push('feedback_ledger.entries must be an array');
+    if (!ledger.coverage || typeof ledger.coverage !== 'object') failures.push('feedback_ledger.coverage is required');
+    failures.push(...validateRuntimePolicyCatalogDigest(ledger.policy_catalog_digest, 'feedback_ledger'));
+    if (ledger.evidence?.sources_digest !== digestObject(ledger.sources || [])) failures.push('feedback_ledger sources digest mismatch');
+    if (ledger.evidence?.entries_digest !== digestObject(ledger.entries || [])) failures.push('feedback_ledger entries digest mismatch');
+    if (ledger.evidence?.coverage_digest !== digestObject(ledger.coverage || {})) failures.push('feedback_ledger coverage digest mismatch');
+    if (ledger.evidence?.sidecar_only !== true) failures.push('feedback_ledger evidence.sidecar_only must be true');
+    if (!Array.isArray(ledger.allowed_followup) || digestObject(ledger.allowed_followup) !== digestObject([])) failures.push('feedback_ledger.allowed_followup must be empty');
+    for (const key of ['dispatch', 'session_create', 'platform_api', 'external_network', 'model_invocation', 'runtime_action', 'business_source_write', 'source_merge', 'pr', 'push', 'merge', 'git', 'worktree']) if (ledger[key] !== false) failures.push(`feedback_ledger.${key} must be false`);
+    if (!Array.isArray(ledger.planned_writes)) failures.push('feedback_ledger.planned_writes must be an array');
+    else if (digestObject(ledger.planned_writes) !== digestObject([path.join(stateDirectoryName, feedbackLedgersDirectoryName, '<timestamp>.feedback-ledger.json').replace(/\\/g, '/')])) failures.push('feedback_ledger.planned_writes must only contain feedback ledger artifact');
+    for (const entry of ledger.entries || []) {
+      const digestPayload = { ...entry };
+      delete digestPayload.entry_digest;
+      if (entry.entry_digest !== digestObject(digestPayload)) failures.push(`feedback entry digest mismatch: ${entry.source_file || '<unknown>'}`);
+    }
+    const digestPayload = { ...ledger };
+    delete digestPayload.ledger_digest;
+    if (ledger.ledger_digest !== digestObject(digestPayload)) failures.push('feedback_ledger digest mismatch');
+
+    if (root && Array.isArray(ledger.sources)) {
+      try {
+        const options = {
+          feedbackPlannerFiles: ledger.sources.filter((source) => source.family === 'planner').map((source) => source.file),
+          feedbackRouterFiles: ledger.sources.filter((source) => source.family === 'router').map((source) => source.file),
+          feedbackOrchestratorFiles: ledger.sources.filter((source) => source.family === 'orchestrator').map((source) => source.file),
+          feedbackEvalFiles: ledger.sources.filter((source) => source.family === 'eval').map((source) => source.file),
+          feedbackReleaseGateFiles: ledger.sources.filter((source) => source.family === 'release_gate').map((source) => source.file),
+        };
+        const rebuilt = buildFeedbackLedgerEnvelope(root, options, { persist: true, artifactFile: artifact.files?.feedback_ledger || path.basename(feedbackLedgerSnapshotPath(root)) });
+        const current = rebuilt.feedback_ledger;
+        if (digestObject(current.sources) !== digestObject(ledger.sources || [])) failures.push('feedback_ledger source list drift');
+        if (digestObject(current.entries) !== digestObject(ledger.entries || [])) failures.push('feedback_ledger entries drift');
+        if (digestObject(current.coverage) !== digestObject(ledger.coverage || {})) failures.push('feedback_ledger coverage drift');
+        for (const source of ledger.sources || []) {
+          const currentSource = current.sources.find((item) => item.family === source.family && item.file === source.file);
+          if (!currentSource) failures.push(`feedback source missing: ${source.family}/${source.file}`);
+          else {
+            if (currentSource.digest !== source.digest) failures.push(`${source.file}: source digest drift`);
+            if (currentSource.artifact_digest !== source.artifact_digest) failures.push(`${source.file}: source artifact digest drift`);
+          }
+        }
+      } catch (error) {
+        failures.push(error.message);
+      }
+    }
+
+    return { ok: failures.length === 0, failures };
+  }
+
+  function writeFeedbackLedgerArtifact(root, envelope) {
+    const file = feedbackLedgerFilePath(root, envelope.files?.feedback_ledger || path.basename(feedbackLedgerSnapshotPath(root)));
+    const payload = { schema_version: jsonSchemaVersion, command: 'feedback', ...envelope, safety: { ...envelope.safety, feedback_ledger_artifact: true } };
+    const verification = validateFeedbackLedgerArtifact(root, payload, path.basename(file));
+    if (!verification.ok) throw new Error(`feedback ledger verification failed: ${verification.failures.join('; ')}`);
+    return persistFeedbackLedgerPayload(path.dirname(file), path.basename(file), payload);
+  }
+
+  function feedbackLedgerAuditEnvelope(root, ledgerFile) {
+    const file = feedbackLedgerFilePath(root, ledgerFile);
+    const artifact = readJsonArtifact(file, 'Feedback ledger');
+    const verification = validateFeedbackLedgerArtifact(root, artifact, path.basename(file));
+    if (!verification.ok) throw new Error(`feedback ledger verification failed: ${verification.failures.join('; ')}`);
+    return {
+      mode: 'feedback-ledger-verify',
+      ok: verification.ok,
+      summary: {
+        file: path.basename(file),
+        source_count: artifact.feedback_ledger?.coverage?.source_count || 0,
+        entry_count: artifact.feedback_ledger?.coverage?.entry_count || 0,
+        categories: artifact.feedback_ledger?.coverage?.categories || {},
+      },
+      verification,
+      feedback_ledger: artifact.feedback_ledger,
+      artifact,
+      quality: verification.failures,
+      action: feedbackAuditAction,
+    };
+  }
+
+  function printFeedback(envelope, file = '') {
+    console.log('Vibecoding Runtime Feedback Ledger');
+    console.log(`Mode: ${envelope.mode}`);
+    if (envelope.feedback_ledger) {
+      console.log(`Sources: ${envelope.feedback_ledger.coverage?.source_count || 0}`);
+      console.log(`Entries: ${envelope.feedback_ledger.coverage?.entry_count || 0}`);
+    }
+    if (envelope.summary) {
+      console.log(`File: ${envelope.summary.file}`);
+      console.log(`Sources: ${envelope.summary.source_count}`);
+      console.log(`Entries: ${envelope.summary.entry_count}`);
+    }
+    if (file) console.log(`Feedback ledger: ${path.relative(process.cwd(), file)}`);
+    if (envelope.quality?.length > 0) printList('Feedback', envelope.quality);
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  function runFeedback(options) {
+    ensureRoot(options.root);
+    const modes = [options.feedbackLedger, options.feedbackVerifyLedger].filter(Boolean);
+    if (modes.length !== 1) throw new Error('feedback requires exactly one of --ledger or --verify-ledger');
+    if (options.feedbackVerifyLedger) {
+      if (options.confirm) throw new Error('feedback --verify-ledger is read-only');
+      if (!options.feedbackLedgerFile) throw new Error('feedback --verify-ledger requires a feedback ledger file');
+      const envelope = feedbackLedgerAuditEnvelope(options.root, options.feedbackLedgerFile);
+      if (options.json) emitFeedbackJsonEnvelope(envelope);
+      else printFeedback(envelope);
+      return;
+    }
+    const envelope = buildFeedbackLedgerEnvelope(options.root, options, { persist: options.confirm });
+    if (options.confirm) {
+      const file = writeFeedbackLedgerArtifact(options.root, envelope);
+      const response = { ...envelope, files: { feedback_ledger: path.basename(file) }, feedback_ledger_file: path.basename(file) };
+      if (options.json) emitFeedbackJsonEnvelope(response);
+      else printFeedback(response, file);
+      return;
+    }
+    if (options.json) emitFeedbackJsonEnvelope(envelope);
+    else printFeedback(envelope);
+  }
+
+  return {
+    releaseCommandDeps,
+    reviewIntakeEnvelope,
+    reviewResolutionEnvelope,
+    runFeedback,
+    runRelease,
+    runReview,
+    validateFeedbackLedgerArtifact,
+  };
+}