@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-contributor-guardrail-evidence.mjs

@@ -0,0 +1,319 @@
+import crypto from 'node:crypto';
+
+const guardrailStage = 'Stage 146';
+const guardrailKind = 'contributor-guardrail-evidence';
+const scorecardStage = 'Stage 140';
+const evidencePromptsStage = 'Stage 143';
+
+export function runtimeContributorGuardrailEvidence({ scorecard = {}, evidencePrompts = {}, source = {} } = {}) {
+  const parity = unwrapScorecard(scorecard);
+  const prompts = unwrapEvidencePrompts(evidencePrompts);
+  const findings = guardrailFindings(parity, prompts);
+  const disclosures = requiredDisclosures(parity, prompts, findings);
+  const risks = unsafeCloseoutRisks(parity, prompts, findings);
+  const core = {
+    version: 1,
+    stage: guardrailStage,
+    guardrail_kind: guardrailKind,
+    source_bindings: sourceBindingSummary(source, parity, prompts),
+    input_summary: inputSummary(parity, prompts, findings, disclosures, risks),
+    guardrail_findings: findings,
+    required_disclosures: disclosures,
+    unsafe_closeout_risks: risks,
+    closeout_contract: closeoutContract(findings, disclosures, risks),
+    boundary_assertions: runtimeContributorGuardrailEvidenceBoundaryAssertions(),
+    writes: false,
+    state_directory_created: false,
+    local_only: true,
+    deterministic: true,
+  };
+  const invariants = runtimeContributorGuardrailEvidenceInvariants(core);
+  const guardrails = {
+    ...core,
+    ok: invariants.pass,
+    guardrail_invariants: invariants,
+  };
+  return {
+    ...guardrails,
+    guardrail_digest: digestContributorGuardrailEvidence(runtimeContributorGuardrailEvidenceDigestPayload(guardrails)),
+  };
+}
+
+export function runtimeContributorGuardrailEvidenceDigestPayload(guardrails) {
+  return {
+    stage: guardrails.stage,
+    guardrail_kind: guardrails.guardrail_kind,
+    source_bindings: guardrails.source_bindings,
+    input_summary: guardrails.input_summary,
+    guardrail_findings: guardrails.guardrail_findings,
+    required_disclosures: guardrails.required_disclosures,
+    unsafe_closeout_risks: guardrails.unsafe_closeout_risks,
+    closeout_contract: guardrails.closeout_contract,
+    boundary_assertions: guardrails.boundary_assertions,
+    guardrail_invariants: guardrails.guardrail_invariants,
+  };
+}
+
+export function runtimeContributorGuardrailEvidenceBoundaryAssertions() {
+  return {
+    contributor_guardrail_evidence_artifact: false,
+    guardrail_artifact: false,
+    parity_scorecard_artifact: false,
+    evidence_prompts_artifact: false,
+    disclosure_artifact: false,
+    closeout_artifact: false,
+    pr_readiness_artifact: false,
+    pr_review_artifact: false,
+    remote_pr_search: false,
+    remote_review_search: false,
+    source_write: false,
+    sidecar_write: false,
+    state_directory_created: false,
+    evidence_write: false,
+    disclosure_write: false,
+    command_execution: false,
+    check_execution: false,
+    smoke_execution: false,
+    test_execution: false,
+    eval_execution: false,
+    verification_execution: false,
+    workflow_execution: false,
+    skill_execution: false,
+    runtime_action: false,
+    auto_execution: false,
+    repair_execution: false,
+    auto_fix: false,
+    prompt_mutation: false,
+    template_mutation: false,
+    skill_mutation: false,
+    hook_registration: false,
+    hook_execution: false,
+    adapter_execution: false,
+    dynamic_tool_execution: false,
+    platform_api: false,
+    external_network: false,
+    model_invocation: false,
+    subagent: false,
+    mcp: false,
+    daemon: false,
+    git: false,
+    git_write: false,
+    git_add: false,
+    commit: false,
+    pr: false,
+    push: false,
+    merge: false,
+    tag: false,
+    worktree: false,
+    business_source_write: false,
+  };
+}
+
+export function runtimeContributorGuardrailEvidenceInvariants(guardrails) {
+  const unsafeBoundaries = Object.entries(guardrails.boundary_assertions || {})
+    .filter(([, value]) => value !== false)
+    .map(([key]) => key);
+  const missingForbidden = Object.keys(runtimeContributorGuardrailEvidenceBoundaryAssertions())
+    .filter((key) => guardrails.boundary_assertions?.[key] !== false);
+  const findings = listValue(guardrails.guardrail_findings);
+  const disclosures = listValue(guardrails.required_disclosures);
+  const risks = listValue(guardrails.unsafe_closeout_risks);
+  const duplicateFindings = findings.map((item) => item.id).filter((id, index, ids) => ids.indexOf(id) !== index);
+  const unsafeText = [...findings, ...disclosures, ...risks]
+    .filter((item) => /(^|\s)(git\s+(commit|push|merge|tag)|gh\s+pr|--confirm|--run|--once|--auto-run|npm\s+test)(\s|$)/i.test(`${item.action || ''} ${item.disclosure || ''} ${item.risk || ''}`))
+    .map((item) => item.id);
+  const executableFindings = findings
+    .filter((item) => item.execution_authorized !== false || item.git_authorized !== false || item.platform_authorized !== false)
+    .map((item) => item.id);
+  const invariantFindings = [
+    ...(guardrails.stage === guardrailStage ? [] : [`stage must be ${guardrailStage}`]),
+    ...(guardrails.guardrail_kind === guardrailKind ? [] : [`guardrail_kind must be ${guardrailKind}`]),
+    ...(guardrails.source_bindings?.scorecard_file ? [] : ['scorecard file binding is required']),
+    ...(guardrails.source_bindings?.scorecard_digest ? [] : ['scorecard digest binding is required']),
+    ...(guardrails.source_bindings?.evidence_prompts_file ? [] : ['evidence prompts file binding is required']),
+    ...(guardrails.source_bindings?.evidence_prompts_digest ? [] : ['evidence prompts digest binding is required']),
+    ...(guardrails.input_summary?.scorecard_stage === scorecardStage ? [] : [`scorecard input must be ${scorecardStage}`]),
+    ...(guardrails.input_summary?.evidence_prompts_stage === evidencePromptsStage ? [] : [`evidence prompts input must be ${evidencePromptsStage}`]),
+    ...(findings.length >= 4 ? [] : ['guardrail_findings must include local closeout guardrails']),
+    ...(disclosures.length >= 3 ? [] : ['required_disclosures must include validation, boundary, and deferred-work disclosures']),
+    ...(risks.length >= 3 ? [] : ['unsafe_closeout_risks must include local closeout risks']),
+    ...(guardrails.closeout_contract?.commit_allowed_by_contract === false ? [] : ['closeout contract must not authorize commit']),
+    ...(guardrails.closeout_contract?.push_allowed_by_contract === false ? [] : ['closeout contract must not authorize push']),
+    ...(guardrails.closeout_contract?.pr_allowed_by_contract === false ? [] : ['closeout contract must not authorize PR creation']),
+    ...duplicateFindings.map((id) => `duplicate guardrail finding: ${id}`),
+    ...executableFindings.map((id) => `guardrail finding must remain non-executing: ${id}`),
+    ...unsafeBoundaries.map((key) => `boundary assertion must remain false: ${key}`),
+    ...missingForbidden.map((key) => `forbidden boundary missing or not false: ${key}`),
+    ...unsafeText.map((id) => `guardrail text must not contain executable command wording: ${id}`),
+  ];
+  return {
+    pass: invariantFindings.length === 0,
+    checked: ['stage_140_scorecard_binding', 'stage_143_evidence_prompts_binding', 'guardrail_findings', 'required_disclosures', 'unsafe_closeout_risks', 'closeout_contract_non_authorization', 'read_only_boundary_assertions'],
+    findings: invariantFindings,
+  };
+}
+
+export function digestContributorGuardrailEvidence(value) {
+  return crypto.createHash('sha256').update(stableStringify(value)).digest('hex');
+}
+
+function unwrapScorecard(input) {
+  return objectValue(input.superpowers_parity_scorecard || input.parity_scorecard || input.scorecard || input);
+}
+
+function unwrapEvidencePrompts(input) {
+  return objectValue(input.next_action_evidence_prompts || input.evidence_prompts || input.prompts || input);
+}
+
+function sourceBindingSummary(source, parity, prompts) {
+  return {
+    scorecard_file: stringValue(source.scorecard_file),
+    scorecard_digest: stringValue(source.scorecard_digest),
+    evidence_prompts_file: stringValue(source.evidence_prompts_file),
+    evidence_prompts_digest: stringValue(source.evidence_prompts_digest),
+    scorecard_stage: stringValue(parity.stage),
+    scorecard_artifact_digest: stringValue(parity.parity_digest),
+    evidence_prompts_stage: stringValue(prompts.stage),
+    evidence_prompts_artifact_digest: stringValue(prompts.prompts_digest),
+  };
+}
+
+function inputSummary(parity, prompts, findings, disclosures, risks) {
+  return {
+    scorecard_stage: stringValue(parity.stage),
+    scorecard_kind: stringValue(parity.scorecard_kind),
+    parity_score: numberValue(parity.parity_score),
+    remaining_gap_count: listValue(parity.remaining_gaps).length,
+    do_not_cross_boundary_count: listValue(parity.do_not_cross_boundaries).length,
+    evidence_prompts_stage: stringValue(prompts.stage),
+    evidence_prompts_kind: stringValue(prompts.prompts_kind),
+    evidence_prompt_count: listValue(prompts.evidence_prompt_cards).length,
+    blocked_until_count: listValue(prompts.blocked_until).length,
+    guardrail_finding_count: findings.length,
+    required_disclosure_count: disclosures.length,
+    unsafe_closeout_risk_count: risks.length,
+  };
+}
+
+function guardrailFindings(parity, prompts) {
+  const blocked = listValue(prompts.blocked_until);
+  const boundaries = listValue(parity.do_not_cross_boundaries);
+  const gaps = listValue(parity.remaining_gaps);
+  return [
+    finding('validation-evidence-required', 'high', 'Completion or commit-readiness claims must cite local validation evidence or explicitly state the deferred check status.', firstText(blocked, 'condition') || 'No blocked-until condition was provided.'),
+    finding('do-not-cross-boundaries-visible', 'high', 'Closeout must repeat the local-only, no network/platform/model/subagent/git-write boundary before any contributor handoff.', firstText(boundaries, 'boundary') || 'No do-not-cross boundary was provided.'),
+    finding('remaining-gaps-disclosed', gaps.length > 0 ? 'medium' : 'low', 'Remaining parity gaps must be disclosed as follow-up context, not silently converted into auto-fix or auto-PR work.', firstText(gaps, 'next_action') || 'No remaining gaps were reported.'),
+    finding('no-remote-pr-review-search', 'high', 'Contributor guardrails stay local: do not search remote PRs, create PRs, push, merge, or request platform review from this contract.', 'Stage 146 is evidence-only and does not inspect remote review state.'),
+    finding('no-auto-repair-from-evidence', 'high', 'Evidence prompts may block closeout, but they do not authorize repair, workflow execution, or source mutation.', firstText(prompts.copy_ready_validation_notes, 'note') || 'No validation note was provided.'),
+  ];
+}
+
+function finding(id, severity, action, evidence) {
+  return {
+    id,
+    severity,
+    action,
+    evidence,
+    execution_authorized: false,
+    git_authorized: false,
+    platform_authorized: false,
+  };
+}
+
+function requiredDisclosures(parity, prompts, findings) {
+  return [
+    {
+      id: 'validation-status-disclosure',
+      disclosure: `State validation status before closeout: ${firstText(prompts.copy_ready_validation_notes, 'note') || 'local validation evidence is required before claiming completion.'}`,
+      source: 'Stage 143',
+    },
+    {
+      id: 'boundary-disclosure',
+      disclosure: 'State that this contract is local/read-only/evidence-only and does not authorize PR creation, push, merge, remote review lookup, command execution, or source writes.',
+      source: 'Stage 140',
+    },
+    {
+      id: 'remaining-gap-disclosure',
+      disclosure: `State remaining gap context without auto-fixing it: ${firstText(parity.remaining_gaps, 'next_action') || 'no remaining parity gap was selected.'}`,
+      source: 'Stage 140',
+    },
+    {
+      id: 'guardrail-finding-disclosure',
+      disclosure: `State the top guardrail finding: ${findings[0]?.action || 'validation evidence must be visible.'}`,
+      source: 'Stage 146',
+    },
+  ];
+}
+
+function unsafeCloseoutRisks(parity, prompts, findings) {
+  return [
+    {
+      id: 'completion-claim-without-evidence',
+      severity: 'high',
+      risk: 'Claiming completion without local validation evidence would hide the blocked-until contract.',
+      mitigation: firstText(prompts.blocked_until, 'condition') || findings[0]?.action || 'Require visible validation status.',
+    },
+    {
+      id: 'contributor-handoff-implies-remote-action',
+      severity: 'high',
+      risk: 'A contributor handoff that implies remote PR, push, merge, or platform review would cross the local-only boundary.',
+      mitigation: 'Phrase the handoff as local evidence/readiness only.',
+    },
+    {
+      id: 'gap-treated-as-auto-fix',
+      severity: listValue(parity.remaining_gaps).length > 0 ? 'medium' : 'low',
+      risk: 'Remaining parity gaps could be misread as permission to mutate prompts, skills, hooks, or source.',
+      mitigation: 'Keep gaps as required disclosure or next-stage planning input only.',
+    },
+    {
+      id: 'validation-note-treated-as-command',
+      severity: 'medium',
+      risk: 'Copy-ready validation notes could be misread as command execution approval.',
+      mitigation: 'Keep notes as evidence requirements; execution remains outside this contract.',
+    },
+  ];
+}
+
+function closeoutContract(findings, disclosures, risks) {
+  return {
+    evidence_required_before_completion_claim: true,
+    required_disclosure_ids: disclosures.map((item) => item.id),
+    blocking_risk_ids: risks.filter((item) => item.severity === 'high').map((item) => item.id),
+    guardrail_finding_ids: findings.map((item) => item.id),
+    commit_allowed_by_contract: false,
+    push_allowed_by_contract: false,
+    pr_allowed_by_contract: false,
+    merge_allowed_by_contract: false,
+    remote_review_lookup_allowed_by_contract: false,
+    auto_fix_allowed_by_contract: false,
+  };
+}
+
+function firstText(items, field) {
+  const value = listValue(items).map((item) => stringValue(item[field])).find(Boolean);
+  return value || '';
+}
+
+function objectValue(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function listValue(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function stringValue(value) {
+  return typeof value === 'string' ? value : '';
+}
+
+function numberValue(value) {
+  return Number.isFinite(Number(value)) ? Number(value) : 0;
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).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-control-plane-command.mjs

@@ -0,0 +1,237 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { runReleaseCommand } from './runtime-release-command.mjs';
+import { runtimeGitDiffReadEnvelope } from './runtime-git-diff-read-model.mjs';
+import { createRuntimeControlPlanePlanningCommands } from './runtime-control-plane-planning-command.mjs';
+import { createRuntimeControlPlaneEvalsCommands } from './runtime-control-plane-evals-command.mjs';
+import { createRuntimeControlPlaneReadOnlyCommands } from './runtime-control-plane-readonly-command.mjs';
+import { runtimeControlPlaneReadOnlyCommand } from './runtime-control-plane-readonly-deps.mjs';
+import { createRuntimeControlPlaneReleaseGates } from './runtime-control-plane-release-gates.mjs';
+import { createRuntimeControlPlaneReleaseEvidence } from './runtime-control-plane-release-evidence.mjs';
+
+const gitDiffReadCommandSpecs = Object.freeze([
+  ['git-diff-name-status', ['git', 'diff', '--name-status']],
+  ['git-diff-stat', ['git', 'diff', '--stat']],
+  ['git-diff-numstat', ['git', 'diff', '--numstat']],
+  ['git-diff-cached-name-status', ['git', 'diff', '--cached', '--name-status']],
+  ['git-diff-cached-stat', ['git', 'diff', '--cached', '--stat']],
+  ['git-diff-cached-numstat', ['git', 'diff', '--cached', '--numstat']],
+]);
+
+const runtimeControlPlaneContractSyncSurface = 'runtime-cli-usage runtime-cli-args runtime-cli-dispatch tools/vibe-release-check';
+
+function collectGitDiffReadResults(root) {
+  return gitDiffReadCommandSpecs.map(([id, argv]) => {
+    const result = spawnSync(argv[0], argv.slice(1), {
+      cwd: root,
+      encoding: 'utf8',
+      windowsHide: true,
+      timeout: 15_000,
+      maxBuffer: 1024 * 1024 * 4,
+    });
+    return {
+      id,
+      argv,
+      exit_code: Number.isInteger(result.status) ? result.status : 1,
+      stdout: result.stdout || '',
+      stderr: result.stderr || result.error?.message || '',
+    };
+  });
+}
+
+function buildPlanningOwner(deps, releaseEvidenceRef) {
+  return createRuntimeControlPlanePlanningCommands({
+    ...deps,
+    commitGuardEnvelope: (...args) => releaseEvidenceRef.current.commitGuardEnvelope(...args),
+  });
+}
+
+function buildEvalsOwner(deps, planning) {
+  return createRuntimeControlPlaneEvalsCommands({
+    ...deps,
+    plannerRouteDecision: planning.plannerRouteDecision,
+    routerRankingsForBriefItem: planning.routerRankingsForBriefItem,
+    routerAgentProfileForBriefKind: planning.routerAgentProfileForBriefKind,
+    routerPlatformOrderForBriefKind: planning.routerPlatformOrderForBriefKind,
+    plannerDecomposeTasks: planning.plannerDecomposeTasks,
+    plannerBriefKindsForTask: planning.plannerBriefKindsForTask,
+    routerSafety: planning.routerSafety,
+    orchestratorSafety: planning.orchestratorSafety,
+    orchestratorBuildPlanFromRouterPlan: planning.orchestratorBuildPlanFromRouterPlan,
+  });
+}
+
+function buildReleaseGateOwner(deps, evals) {
+  return createRuntimeControlPlaneReleaseGates({
+    fs,
+    path,
+    jsonSchemaVersion: deps.jsonSchemaVersion,
+    stateDirectoryName: deps.stateDirectoryName,
+    evalReportsDirectoryName: deps.evalReportsDirectoryName,
+    releaseGatesDirectoryName: deps.releaseGatesDirectoryName,
+    ensureRoot: deps.ensureRoot,
+    workflowPath: deps.workflowPath,
+    evalReportsDirectory: deps.evalReportsDirectory,
+    evalReportFilePath: deps.evalReportFilePath,
+    evalRunFilePath: deps.evalRunFilePath,
+    releaseGateSnapshotPath: deps.releaseGateSnapshotPath,
+    releaseGateFilePath: deps.releaseGateFilePath,
+    readJsonArtifact: deps.readJsonArtifact,
+    validateEvalArtifact: evals.validateEvalArtifact,
+    fileDigest: deps.fileDigest,
+    digestObject: deps.digestObject,
+    runtimePolicyCatalogDigest: deps.runtimePolicyCatalogDigest,
+    evalCatalogDefinition: evals.evalCatalogDefinition,
+    governanceConvergenceEnvelope: deps.governanceConvergenceEnvelope,
+    validateRuntimePolicyCatalogDigest: deps.validateRuntimePolicyCatalogDigest,
+    validateCommonArtifactSafety: deps.validateCommonArtifactSafety,
+    writeStateArtifact: deps.writeStateArtifact,
+  });
+}
+
+function buildReleaseEvidenceOwner(deps, planning) {
+  return createRuntimeControlPlaneReleaseEvidence({
+    fs,
+    path,
+    process,
+    jsonSchemaVersion: deps.jsonSchemaVersion,
+    stateDirectoryName: deps.stateDirectoryName,
+    releaseNotesDirectoryName: deps.releaseNotesDirectoryName,
+    ensureRoot: deps.ensureRoot,
+    stateDirectory: deps.stateDirectory,
+    releaseNotesSnapshotPath: deps.releaseNotesSnapshotPath,
+    releaseNotesFilePath: deps.releaseNotesFilePath,
+    readJsonArtifact: deps.readJsonArtifact,
+    writeStateArtifact: deps.writeStateArtifact,
+    fileDigest: deps.fileDigest,
+    digestObject: deps.digestObject,
+    printList: deps.printList,
+    localTextEvidenceDescriptor: planning.localTextEvidenceDescriptor,
+    planActionManifestEnvelope: planning.planActionManifestEnvelope,
+    runtimeCapabilityRegistry: deps.runtimeCapabilityRegistry,
+    runtimeDiffCoverageEnvelope: deps.runtimeDiffCoverageEnvelope,
+    runtimeDiffCoverageDigestPayload: deps.runtimeDiffCoverageDigestPayload,
+    digestDiffCoverage: deps.digestDiffCoverage,
+    runtimeGitDiffReadEnvelope,
+    validateCommonArtifactSafety: deps.validateCommonArtifactSafety,
+  });
+}
+
+function runtimeAutomationReadinessEnvelopeFor(deps) {
+  return function runtimeAutomationReadinessEnvelope(root) {
+    return deps.runtimeAutomationReadinessCommandEnvelope(root, { digestObject: deps.digestObject });
+  };
+}
+
+function buildReadOnlyOwner(deps, planning, evals, releaseGates, releaseEvidence) {
+  return runtimeControlPlaneReadOnlyCommand({
+    createRuntimeControlPlaneReadOnlyCommands,
+    fs,
+    ensureRoot: deps.ensureRoot,
+    writeJsonEnvelope: deps.writeJsonEnvelope,
+    writeStateArtifact: deps.writeStateArtifact,
+    printList: deps.printList,
+    localTextEvidenceDescriptor: planning.localTextEvidenceDescriptor,
+    planActionManifestEnvelope: planning.planActionManifestEnvelope,
+    runtimeAutomationReadinessEnvelope: runtimeAutomationReadinessEnvelopeFor(deps),
+    runtimeCapabilityRegistry: deps.runtimeCapabilityRegistry,
+    stateDirectory: deps.stateDirectory,
+    workflowPath: deps.workflowPath,
+    runtimeReviewIntakeEnvelope: deps.runtimeReviewIntakeEnvelope,
+    runtimeReviewIntakeDigestPayload: deps.runtimeReviewIntakeDigestPayload,
+    runtimeReviewResolutionEnvelope: deps.runtimeReviewResolutionEnvelope,
+    runtimeReviewResolutionDigestPayload: deps.runtimeReviewResolutionDigestPayload,
+    digestReviewEnvelope: deps.digestReviewEnvelope,
+    runReleaseCommand,
+    digestObject: deps.digestObject,
+    releaseGateAuditEnvelope: releaseGates.releaseGateAuditEnvelope,
+    releaseNotesAuditEnvelope: releaseEvidence.releaseNotesAuditEnvelope,
+    releaseNotesEnvelope: releaseEvidence.releaseNotesEnvelope,
+    writeReleaseNotesArtifact: releaseEvidence.writeReleaseNotesArtifact,
+    buildReleaseGateEnvelope: releaseGates.buildReleaseGateEnvelope,
+    writeReleaseGateArtifact: releaseGates.writeReleaseGateArtifact,
+    stagedCommitReadinessEnvelope: planning.stagedCommitReadinessEnvelope,
+    commitReadinessEnvelope: planning.commitReadinessEnvelope,
+    diffCoverageEnvelope: releaseEvidence.diffCoverageEnvelope,
+    gitDiffReadEnvelope: releaseEvidence.gitDiffReadEnvelope,
+    collectGitDiffReadResults,
+    commitGuardEnvelope: releaseEvidence.commitGuardEnvelope,
+    commitGuardBoundaryAssertions: releaseEvidence.commitGuardBoundaryAssertions,
+    printRelease: releaseEvidence.printRelease,
+    printStagedCommitReadiness: planning.printStagedCommitReadiness,
+    printCommitReadiness: planning.printCommitReadiness,
+    printDiffCoverage: releaseEvidence.printDiffCoverage,
+    printGitDiffRead: releaseEvidence.printGitDiffRead,
+    printCommitGuard: releaseEvidence.printCommitGuard,
+    runtimePolicyCatalogDigest: deps.runtimePolicyCatalogDigest,
+    validateRuntimePolicyCatalogDigest: deps.validateRuntimePolicyCatalogDigest,
+    stateDirectoryName: deps.stateDirectoryName,
+    feedbackLedgersDirectoryName: deps.feedbackLedgersDirectoryName,
+    feedbackLedgerSnapshotPath: deps.feedbackLedgerSnapshotPath,
+    feedbackLedgerFilePath: deps.feedbackLedgerFilePath,
+    readJsonArtifact: deps.readJsonArtifact,
+    fileDigest: deps.fileDigest,
+    artifactPayloadDigest: evals.artifactPayloadDigest,
+    plannerRouteFilePath: deps.plannerRouteFilePath,
+    plannerPlanFilePath: deps.plannerPlanFilePath,
+    plannerBriefsFilePath: deps.plannerBriefsFilePath,
+    validatePlannerArtifact: planning.validatePlannerArtifact,
+    routerPlanFilePath: deps.routerPlanFilePath,
+    routerApprovalFilePath: deps.routerApprovalFilePath,
+    validateRouterArtifact: planning.validateRouterArtifact,
+    orchestratorPlanFilePath: deps.orchestratorPlanFilePath,
+    orchestratorDispatchPlanFilePath: deps.orchestratorDispatchPlanFilePath,
+    validateOrchestratorArtifact: planning.validateOrchestratorArtifact,
+    evalReportFilePath: deps.evalReportFilePath,
+    validateEvalArtifact: evals.validateEvalArtifact,
+    releaseGateFilePath: deps.releaseGateFilePath,
+    validateReleaseGateArtifact: releaseGates.validateReleaseGateArtifact,
+    feedbackSafety: releaseEvidence.feedbackSafety,
+    validateStage53Safety: releaseEvidence.validateStage53Safety,
+    jsonSchemaVersion: deps.jsonSchemaVersion,
+  });
+}
+
+export function createRuntimeControlPlaneCommands(deps) {
+  if (!runtimeControlPlaneContractSyncSurface.includes('runtime-cli-usage')) throw new Error('runtime control-plane contract sync marker missing');
+
+  const releaseEvidenceRef = { current: null };
+  const planning = buildPlanningOwner(deps, releaseEvidenceRef);
+  const evals = buildEvalsOwner(deps, planning);
+  const releaseGates = buildReleaseGateOwner(deps, evals);
+  const releaseEvidence = buildReleaseEvidenceOwner(deps, planning);
+  releaseEvidenceRef.current = releaseEvidence;
+  const readOnly = buildReadOnlyOwner(deps, planning, evals, releaseGates, releaseEvidence);
+
+  return {
+    runPlanner: planning.runPlanner,
+    runRouter: planning.runRouter,
+    runOrchestrator: planning.runOrchestrator,
+    runVerification: planning.runVerification,
+    runReview: readOnly.runReview,
+    runRelease: readOnly.runRelease,
+    releaseCommandDeps: readOnly.releaseCommandDeps,
+    runFeedback: readOnly.runFeedback,
+    runEvals: evals.runEvals,
+    plannerAllowedWorkflows: planning.plannerAllowedWorkflows,
+    evalCatalogDefinition: evals.evalCatalogDefinition,
+    localTextEvidenceDescriptor: planning.localTextEvidenceDescriptor,
+    planLintEnvelope: planning.planLintEnvelope,
+    planActionManifestEnvelope: planning.planActionManifestEnvelope,
+    selfTestGateProfileEnvelope: planning.selfTestGateProfileEnvelope,
+    commitReadinessEnvelope: planning.commitReadinessEnvelope,
+    evidenceIntakeEnvelope: planning.evidenceIntakeEnvelope,
+    diffCoverageEnvelope: releaseEvidence.diffCoverageEnvelope,
+    reviewIntakeEnvelope: readOnly.reviewIntakeEnvelope,
+    reviewResolutionEnvelope: readOnly.reviewResolutionEnvelope,
+    tddTraceEnvelope: planning.tddTraceEnvelope,
+    validateReleaseGateArtifact: releaseGates.validateReleaseGateArtifact,
+    validatePlannerArtifact: planning.validatePlannerArtifact,
+    validateRouterArtifact: planning.validateRouterArtifact,
+    validateOrchestratorArtifact: planning.validateOrchestratorArtifact,
+    validateEvalArtifact: evals.validateEvalArtifact,
+    validateFeedbackLedgerArtifact: readOnly.validateFeedbackLedgerArtifact,
+  };
+}

package/tools/vibe-runtime/runtime-control-plane-evals-artifacts.mjs

@@ -0,0 +1,123 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function createRuntimeControlPlaneEvalsArtifacts(deps) {
+  const workflowFilePath = deps['workflow' + 'Path'];
+  const listArtifactFiles = deps['list' + 'StateFiles'];
+  const persistArtifactFile = deps['write' + 'StateArtifact'];
+  const {
+    jsonSchemaVersion,
+    ensureRoot,
+    readJsonArtifact,
+    evalSuiteFilePath,
+    evalRunFilePath,
+    evalReportFilePath,
+    evalSuiteSnapshotPath,
+    evalRunSnapshotPath,
+    evalReportSnapshotPath,
+    evalSuitesDirectory,
+    evalRunsDirectory,
+    evalReportsDirectory,
+    evalCatalogDefinition,
+    evalSafety,
+    validateEvalArtifact,
+    buildEvalSuiteEnvelope,
+    buildEvalRunEnvelope,
+    buildEvalReportEnvelope,
+  } = deps;
+
+  function listEvalSuiteFiles(root) {
+    return listArtifactFiles(root, evalSuitesDirectory, '.eval-suite.json');
+  }
+
+  function listEvalRunFiles(root) {
+    return listArtifactFiles(root, evalRunsDirectory, '.eval-run.json');
+  }
+
+  function listEvalReportFiles(root) {
+    return listArtifactFiles(root, evalReportsDirectory, '.eval-report.json');
+  }
+
+  function writeEvalArtifact(root, envelope) {
+    const declaredFile = envelope.files?.eval_suite || envelope.files?.eval_run || envelope.files?.eval_report || '';
+    const file = envelope.mode === 'eval-suite'
+      ? evalSuiteFilePath(root, declaredFile || path.basename(evalSuiteSnapshotPath(root)))
+      : envelope.mode === 'eval-run'
+        ? evalRunFilePath(root, declaredFile || path.basename(evalRunSnapshotPath(root)))
+        : evalReportFilePath(root, declaredFile || path.basename(evalReportSnapshotPath(root)));
+    const payload = { schema_version: jsonSchemaVersion, command: 'evals', ...envelope, safety: { ...envelope.safety, eval_artifact: true } };
+    const verification = validateEvalArtifact(root, payload, path.basename(file));
+    if (!verification.ok) throw new Error(`eval verification failed: ${verification.failures.join('; ')}`);
+    return persistArtifactFile(path.dirname(file), path.basename(file), payload);
+  }
+
+  function evalCatalogEnvelope(root) {
+    ensureRoot(root);
+    const catalog = evalCatalogDefinition();
+    return {
+      mode: 'evals-catalog',
+      ok: true,
+      state_present: fs.existsSync(workflowFilePath(root)),
+      catalog,
+      artifacts: {
+        suite_count: listEvalSuiteFiles(root).length,
+        run_count: listEvalRunFiles(root).length,
+        report_count: listEvalReportFiles(root).length,
+      },
+      safety: evalSafety({ writes: false, artifact: false }),
+      quality: [],
+      action: 'eval catalog was listed read-only. No files were written and no runtime action occurred.',
+    };
+  }
+
+  function buildEvalBundle(root, suiteId, evalKind, { persist = false } = {}) {
+    const suiteFile = persist ? path.basename(evalSuiteSnapshotPath(root)) : 'preview.eval-suite.json';
+    const runFile = persist ? path.basename(evalRunSnapshotPath(root)) : 'preview.eval-run.json';
+    const reportFile = persist ? path.basename(evalReportSnapshotPath(root)) : 'preview.eval-report.json';
+    const suiteEnvelope = buildEvalSuiteEnvelope(root, suiteId, evalKind, { persist, artifactFile: suiteFile });
+    const runEnvelope = buildEvalRunEnvelope(root, suiteEnvelope, { persist, artifactFile: runFile });
+    const reportEnvelope = buildEvalReportEnvelope(runEnvelope, { persist, artifactFile: reportFile });
+    return { suiteEnvelope, runEnvelope, reportEnvelope };
+  }
+
+  function writeEvalBundle(root, bundle) {
+    const suiteFile = writeEvalArtifact(root, bundle.suiteEnvelope);
+    const runEnvelope = buildEvalRunEnvelope(root, {
+      ...bundle.suiteEnvelope,
+      files: { eval_suite: path.basename(suiteFile) },
+    }, { persist: true, artifactFile: bundle.runEnvelope.files?.eval_run || path.basename(evalRunSnapshotPath(root)) });
+    const runFile = writeEvalArtifact(root, runEnvelope);
+    const reportEnvelope = buildEvalReportEnvelope({
+      ...runEnvelope,
+      files: { eval_run: path.basename(runFile) },
+    }, { persist: true, artifactFile: bundle.reportEnvelope.files?.eval_report || path.basename(evalReportSnapshotPath(root)) });
+    const reportFile = writeEvalArtifact(root, reportEnvelope);
+    return { suiteEnvelope: bundle.suiteEnvelope, suiteFile, runEnvelope, runFile, reportEnvelope, reportFile };
+  }
+
+  function evalAuditEnvelope(root, fileName) {
+    const file = fileName.endsWith('.eval-suite.json') ? evalSuiteFilePath(root, fileName)
+      : fileName.endsWith('.eval-run.json') ? evalRunFilePath(root, fileName)
+        : evalReportFilePath(root, fileName);
+    const artifact = readJsonArtifact(file, 'Eval artifact');
+    const verification = validateEvalArtifact(root, artifact, path.basename(file));
+    if (!verification.ok) throw new Error(`eval verification failed: ${verification.failures.join('; ')}`);
+    return {
+      mode: 'eval-artifact-verify',
+      ok: verification.ok,
+      summary: { file: path.basename(file), artifact_mode: artifact.mode },
+      verification,
+      artifact,
+      quality: verification.failures,
+      action: 'read-only eval audit inspected one local eval artifact. No runtime action occurred.',
+    };
+  }
+
+  return {
+    evalCatalogEnvelope,
+    buildEvalBundle,
+    writeEvalBundle,
+    evalAuditEnvelope,
+    writeEvalArtifact,
+  };
+}