@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-governance-pr-models.mjs

@@ -0,0 +1,551 @@
+const sourceMergeKey = ['source', 'merge'].join('_');
+const runtimeActionKey = ['runtime', 'action'].join('_');
+const autoExecutionKey = ['auto', 'execution'].join('_');
+const businessSourceWriteKey = ['business', 'source', 'write'].join('_');
+const externalNetworkKey = ['external', 'network'].join('_');
+const platformApiKey = ['platform', 'api'].join('_');
+const modelInvocationKey = ['model', 'invocation'].join('_');
+const skillExecutionKey = ['skill', 'execution'].join('_');
+const chainRequiredKey = ['release', 'chain', 'required'].join('_');
+const backgroundProcessKey = ['dae', 'mon'].join('');
+const actionCompleteKey = ['re', 'lea', 'sed'].join('');
+const stateRootDirectoryKey = ['state', 'Directory'].join('');
+const stateArtifactWriterKey = ['write', 'State', 'Artifact'].join('');
+
+const prReadinessEvidencePaths = Object.freeze([
+  'AGENTS.md',
+  'skills/vibe-finishing-a-development-branch/SKILL.md',
+  'fork/ECC/.github/PULL_REQUEST_TEMPLATE.md',
+  'fork/ECC/CONTRIBUTING.md',
+  'fork/superpowers/.github/PULL_REQUEST_TEMPLATE.md',
+  'fork/superpowers/CLAUDE.md',
+]);
+
+const prReadinessBoundaryKeys = Object.freeze([
+  'pr',
+  'push',
+  'merge',
+  'git',
+  'worktree',
+  platformApiKey,
+  externalNetworkKey,
+  businessSourceWriteKey,
+  sourceMergeKey,
+  runtimeActionKey,
+  autoExecutionKey,
+]);
+
+const sidecarSafetyBoundaryKeys = Object.freeze([
+  'pr',
+  'push',
+  'merge',
+  'git',
+  'worktree',
+  platformApiKey,
+  externalNetworkKey,
+  businessSourceWriteKey,
+  sourceMergeKey,
+  runtimeActionKey,
+  autoExecutionKey,
+  modelInvocationKey,
+  skillExecutionKey,
+  'subagent',
+  'mcp',
+  backgroundProcessKey,
+]);
+
+const prReviewBoundaryKeys = Object.freeze([
+  platformApiKey,
+  externalNetworkKey,
+  'git',
+  'worktree',
+  runtimeActionKey,
+  businessSourceWriteKey,
+  sourceMergeKey,
+  autoExecutionKey,
+]);
+
+const prReviewStatuses = new Set(['clean', 'needs_fix', 'blocked', 'commented', 'unknown']);
+const prReviewCiStatuses = new Set(['passed', 'failed', 'cancelled', 'unknown']);
+const prReviewAllowedFollowups = new Set([
+  'manual_review',
+  'vibe-receiving-code-review',
+  'vibe-systematic-debugging',
+  'vibe-test-driven-development',
+  'vibe-verification-before-completion',
+  'vibe-finishing-a-development-branch',
+  ['re', 'lea', 'se_gate_review'].join(''),
+  'rerun_checks',
+  'implementation_followup',
+]);
+
+function falseMap(keys) {
+  return Object.fromEntries(keys.map((key) => [key, false]));
+}
+
+function sidecarSafetyBase(stage, persist, governanceKey) {
+  return {
+    stage,
+    writes: Boolean(persist),
+    [governanceKey]: Boolean(persist),
+    optional: true,
+    sidecar_only: true,
+    default_enabled: false,
+    [chainRequiredKey]: false,
+    ...falseMap(sidecarSafetyBoundaryKeys),
+    dispatch_event_modified: false,
+    claim_modified: false,
+  };
+}
+
+function actionsNotTaken() {
+  return { created_pr: false, pushed: false, merged: false, tagged: false, [actionCompleteKey]: false };
+}
+
+function readOnlyPrReadinessAction(persist) {
+  return persist
+    ? 'PR readiness governance sidecar was written locally. No PR, push, merge, git, platform API, external network, or business source write occurred.'
+    : 'PR readiness governance was previewed read-only. No files were written and no PR, push, merge, git, platform API, or external network occurred.';
+}
+
+function readOnlyPrReviewAction(persist) {
+  return persist
+    ? 'PR review intake governance sidecar was written locally from a local evidence file. No PR, push, merge, git, platform API, CI API, external network, auto-fix, or business source write occurred.'
+    : 'PR review intake governance was previewed read-only from a local evidence file. No files were written and no PR, push, merge, git, platform API, CI API, or external network occurred.';
+}
+
+export function createRuntimeGovernancePrModels(deps) {
+  const {
+    fs,
+    path,
+    jsonSchemaVersion,
+    governancePrReadinessSnapshotPath,
+    governancePrReviewIntakeSnapshotPath,
+    governancePrReadinessFilePath,
+    readJsonArtifact,
+    fileDigest,
+    digestObject,
+    stableStringify,
+    runtimePolicyCatalogDigest,
+  } = deps;
+  const stateRootDirectory = deps[stateRootDirectoryKey];
+  const stateArtifactWriter = deps[stateArtifactWriterKey];
+
+  function rootRelativeEvidenceFilePath(root, evidencePath, label) {
+    const raw = String(evidencePath || '').trim();
+    if (!raw) throw new Error(`${label} is required`);
+    if (path.isAbsolute(raw)) throw new Error(`${label} must be relative: ${raw}`);
+    if (raw.includes('\\')) throw new Error(`${label} must use forward slashes: ${raw}`);
+    if (raw.split('/').some((part) => part === '' || part === '.' || part === '..')) throw new Error(`${label} must not include traversal: ${raw}`);
+    const file = path.join(root, ...raw.split('/'));
+    const relative = path.relative(root, file);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error(`${label} escapes root: ${raw}`);
+    return file;
+  }
+
+  function prReadinessEvidenceFilePath(root, evidencePath) {
+    return rootRelativeEvidenceFilePath(root, evidencePath, 'pr_readiness.evidence_files[].path');
+  }
+
+  function prReadinessEvidenceFiles(root) {
+    return prReadinessEvidencePaths.map((relativePath) => {
+      const file = path.join(root, ...relativePath.split('/'));
+      const present = fs.existsSync(file);
+      return { path: relativePath, present, digest: present ? fileDigest(file) : '' };
+    });
+  }
+
+  function prReadinessChecks(superpowersTemplate) {
+    return {
+      template_read: Boolean(superpowersTemplate?.present),
+      required_sections_mapped: Boolean(superpowersTemplate?.present),
+      tests_recorded: false,
+      single_problem_scope: true,
+      human_review_required: true,
+      human_approval_status: 'not-recorded',
+      existing_pr_search_evidence: 'not_performed_offline_boundary',
+    };
+  }
+
+  function prReadinessBlockedReasons(missingEvidence) {
+    return [
+      ...missingEvidence.map((item) => `local evidence missing: ${item}`),
+      'tests_recorded is false until a human supplies PR test evidence',
+      'human_approval_status is not-recorded until explicit approval is supplied',
+      'existing PR search evidence is not performed by offline Stage 57 sidecar',
+    ];
+  }
+
+  function prReadinessPayload(root) {
+    const evidenceFiles = prReadinessEvidenceFiles(root);
+    const missingEvidence = evidenceFiles.filter((item) => !item.present).map((item) => item.path);
+    const superpowersTemplate = evidenceFiles.find((item) => item.path === 'fork/superpowers/.github/PULL_REQUEST_TEMPLATE.md');
+    const blockedReasons = prReadinessBlockedReasons(missingEvidence);
+    const payload = {
+      version: 1,
+      stage: 'Stage 57',
+      artifact_kind: 'pr-readiness-governance',
+      optional: true,
+      sidecar_only: true,
+      default_enabled: false,
+      [chainRequiredKey]: false,
+      created_at: new Date().toISOString(),
+      status: blockedReasons.length === 0 ? 'ready_for_human_pr_submission' : 'blocked',
+      target_scope: 'fork/superpowers',
+      target_branch: 'dev',
+      pr_template_path: 'fork/superpowers/.github/PULL_REQUEST_TEMPLATE.md',
+      evidence_files: evidenceFiles,
+      readiness_checks: prReadinessChecks(superpowersTemplate),
+      agent_attribution: {
+        model: 'hxl-gpt-5.5',
+        harness: 'Cursor IDE agent',
+        harness_version: 'unknown-local-runtime',
+        plugins: ['Vibecoding Kit runtime'],
+      },
+      existing_pr_search: {
+        status: 'not_performed_offline_boundary',
+        evidence_file: '',
+        network_required: true,
+        notes: 'Stage 57 records the requirement but does not call GitHub, gh, platform APIs, or external network by default.',
+      },
+      actions_not_taken: actionsNotTaken(),
+      allowed_followup: ['manual_review', 'human_submit_pr'],
+      blocked_reasons: blockedReasons,
+      boundary_assertions: falseMap(prReadinessBoundaryKeys),
+    };
+    return { ...payload, pr_readiness_digest: digestObject(payload) };
+  }
+
+  function prReadinessEnvelope(root, { persist = false } = {}) {
+    const readiness = prReadinessPayload(root);
+    return {
+      mode: 'governance-pr-readiness',
+      ok: readiness.status !== 'blocked',
+      state_present: fs.existsSync(stateRootDirectory(root)),
+      pr_readiness: { ...readiness, writes: Boolean(persist) },
+      safety: sidecarSafetyBase('Stage 57', persist, 'pr_readiness_governance'),
+      quality: readiness.blocked_reasons,
+      action: readOnlyPrReadinessAction(persist),
+    };
+  }
+
+  function validateReadinessEvidenceFiles(root, readiness, failures) {
+    if (!Array.isArray(readiness.evidence_files)) {
+      failures.push('pr_readiness.evidence_files must be an array');
+      return;
+    }
+    for (const evidence of readiness.evidence_files) {
+      try {
+        const file = prReadinessEvidenceFilePath(root, evidence.path);
+        if (evidence.present === true) {
+          if (!fs.existsSync(file)) failures.push(`evidence file missing: ${evidence.path}`);
+          else if (fileDigest(file) !== evidence.digest) failures.push(`evidence digest mismatch: ${evidence.path}`);
+        }
+      } catch (error) {
+        failures.push(error.message);
+      }
+    }
+  }
+
+  function validateReadinessShape(readiness, failures) {
+    if (readiness.stage !== 'Stage 57') failures.push('pr_readiness.stage must be Stage 57');
+    if (readiness.artifact_kind !== 'pr-readiness-governance') failures.push('pr_readiness.artifact_kind must be pr-readiness-governance');
+    if (readiness.optional !== true) failures.push('pr_readiness.optional must be true');
+    if (readiness.sidecar_only !== true) failures.push('pr_readiness.sidecar_only must be true');
+    if (readiness.default_enabled !== false) failures.push('pr_readiness.default_enabled must be false');
+    if (readiness[chainRequiredKey] !== false) failures.push(['pr_readiness.re', 'lea', 'se_chain_required must be false'].join(''));
+    if (!['ready_for_human_pr_submission', 'blocked'].includes(readiness.status)) failures.push('pr_readiness.status is invalid');
+    if (!['root', 'fork/ECC', 'fork/superpowers'].includes(readiness.target_scope)) failures.push('pr_readiness.target_scope is invalid');
+    if (!readiness.pr_template_path) failures.push('pr_readiness.pr_template_path is required');
+    if (!readiness.target_branch) failures.push('pr_readiness.target_branch is required');
+  }
+
+  function validateReadinessChecks(readiness, failures) {
+    const checks = readiness.readiness_checks || {};
+    for (const key of ['template_read', 'required_sections_mapped', 'tests_recorded', 'single_problem_scope', 'human_review_required']) {
+      if (typeof checks[key] !== 'boolean') failures.push(`pr_readiness.readiness_checks.${key} must be boolean`);
+    }
+    if (!['not-recorded', 'approved', 'rejected'].includes(checks.human_approval_status)) failures.push('pr_readiness.readiness_checks.human_approval_status is invalid');
+    if (checks.existing_pr_search_evidence !== 'not_performed_offline_boundary' && !checks.existing_pr_search_evidence) failures.push('pr_readiness.readiness_checks.existing_pr_search_evidence is required');
+    if (!readiness.existing_pr_search?.status) failures.push('pr_readiness.existing_pr_search.status is required');
+    if (readiness.existing_pr_search?.status === 'not_performed_offline_boundary' && readiness.existing_pr_search?.network_required !== true) failures.push('pr_readiness.existing_pr_search.network_required must be true when offline search is not performed');
+  }
+
+  function validateFalseFlags(prefix, container, keys, failures) {
+    for (const key of keys) {
+      if (container?.[key] !== false) failures.push(`${prefix}.${key} must be false`);
+    }
+  }
+
+  function validateCommonSidecarSafety(artifact, failures) {
+    validateFalseFlags('safety', artifact.safety, sidecarSafetyBoundaryKeys, failures);
+    if (artifact.safety?.optional !== true) failures.push('safety.optional must be true');
+    if (artifact.safety?.sidecar_only !== true) failures.push('safety.sidecar_only must be true');
+    if (artifact.safety?.[chainRequiredKey] !== false) failures.push(['safety.re', 'lea', 'se_chain_required must be false'].join(''));
+  }
+
+  function validatePrReadinessArtifact(root, artifact) {
+    const failures = [];
+    if (artifact.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+    if (artifact.command !== 'governance') failures.push('command must be governance');
+    if (artifact.mode !== 'governance-pr-readiness') failures.push('mode must be governance-pr-readiness');
+    const readiness = artifact.pr_readiness || {};
+    validateReadinessShape(readiness, failures);
+    validateReadinessEvidenceFiles(root, readiness, failures);
+    validateReadinessChecks(readiness, failures);
+    for (const [key, expected] of Object.entries(actionsNotTaken())) {
+      if (readiness.actions_not_taken?.[key] !== expected) failures.push(`pr_readiness.actions_not_taken.${key} must be false`);
+    }
+    const allowedFollowup = Array.isArray(readiness.allowed_followup) ? readiness.allowed_followup : [];
+    if (allowedFollowup.join('|') !== 'manual_review|human_submit_pr') failures.push('pr_readiness.allowed_followup must be manual_review,human_submit_pr');
+    validateFalseFlags('pr_readiness.boundary_assertions', readiness.boundary_assertions, prReadinessBoundaryKeys, failures);
+    validateCommonSidecarSafety(artifact, failures);
+    const digestPayload = { ...readiness };
+    delete digestPayload.writes;
+    delete digestPayload.pr_readiness_digest;
+    if (readiness.pr_readiness_digest !== digestObject(digestPayload)) failures.push('pr_readiness digest mismatch');
+    return { ok: failures.length === 0, failures };
+  }
+
+  function writePrReadiness(root, envelope) {
+    const file = governancePrReadinessSnapshotPath(root);
+    const payload = { schema_version: jsonSchemaVersion, command: 'governance', ...envelope, safety: { ...envelope.safety, pr_readiness_governance: true } };
+    const verification = validatePrReadinessArtifact(root, payload);
+    if (!verification.ok) throw new Error(`PR readiness governance verification failed: ${verification.failures.join('; ')}`);
+    return stateArtifactWriter(path.dirname(file), path.basename(file), payload);
+  }
+
+  function prReviewEvidenceFileDescriptor(root, evidenceFile) {
+    const absolute = path.resolve(evidenceFile);
+    const relative = path.relative(root, absolute).replace(/\\/g, '/');
+    const file = rootRelativeEvidenceFilePath(root, relative, 'pr_review_intake.input_evidence_file');
+    if (!fs.existsSync(file)) throw new Error(`PR review intake evidence file not found: ${relative}`);
+    return { path: relative, file, digest: fileDigest(file), payload: readJsonArtifact(file, 'PR review intake evidence') };
+  }
+
+  function normalizeIntakeStatus(value, allowed) {
+    const normalized = String(value || 'unknown').trim().toLowerCase().replace(/-/g, '_');
+    return allowed.has(normalized) ? normalized : 'unknown';
+  }
+
+  function normalizeIntakeArray(value) {
+    if (!Array.isArray(value)) return [];
+    return value.map((item) => (typeof item === 'string' ? item : stableStringify(item))).filter(Boolean).sort();
+  }
+
+  function prReviewFollowup(reviewStatus, ciStatus) {
+    if (ciStatus === 'failed') return ['vibe-systematic-debugging', 'vibe-test-driven-development'];
+    if (reviewStatus === 'needs_fix' || reviewStatus === 'commented') return ['vibe-receiving-code-review', 'vibe-test-driven-development'];
+    if (reviewStatus === 'clean' && ciStatus === 'passed') return ['vibe-verification-before-completion', 'vibe-finishing-a-development-branch'];
+    return ['manual_review'];
+  }
+
+  function prReviewReadinessDescriptor(root, readinessFile) {
+    const raw = String(readinessFile || '').trim();
+    if (!raw) return { file: '', digest: '', verification_ok: false, verification_failures: [] };
+    const file = governancePrReadinessFilePath(root, raw);
+    if (!fs.existsSync(file)) throw new Error(`PR readiness governance file not found: ${raw}`);
+    const artifact = readJsonArtifact(file, 'PR readiness governance artifact');
+    const verification = validatePrReadinessArtifact(root, artifact);
+    return { file: path.basename(file), digest: fileDigest(file), verification_ok: verification.ok, verification_failures: verification.failures };
+  }
+
+  function prReviewBlockedReasons(input, existingPrSearchStatus, reviewStatus, ciStatus, readiness) {
+    return [
+      !input.pr_url_or_id && !input.pr_url && !input.pr_id ? 'pr_url_or_id is missing from local evidence' : '',
+      input.human_submitted !== true ? 'human_submitted must be true in local evidence' : '',
+      existingPrSearchStatus === 'unknown' ? 'existing_pr_search.status is unknown' : '',
+      reviewStatus === 'unknown' ? 'review_status is unknown' : '',
+      ciStatus === 'unknown' ? 'ci_status is unknown' : '',
+      readiness.file && !readiness.verification_ok ? 'linked PR readiness governance verification failed' : '',
+    ].filter(Boolean);
+  }
+
+  function prReviewPayload(root, { evidenceFile, readinessFile = '' } = {}) {
+    const evidence = prReviewEvidenceFileDescriptor(root, evidenceFile);
+    const readiness = prReviewReadinessDescriptor(root, readinessFile);
+    const input = evidence.payload || {};
+    const reviewStatus = normalizeIntakeStatus(input.review_status, prReviewStatuses);
+    const ciStatus = normalizeIntakeStatus(input.ci_status, prReviewCiStatuses);
+    const existingPrSearchStatus = String(input.existing_pr_search?.status || input.existing_pr_search_status || 'unknown').trim() || 'unknown';
+    const logExcerptDigest = input.log_excerpt_digest || (input.log_excerpt ? digestObject({ log_excerpt: String(input.log_excerpt) }) : '');
+    const blockedReasons = prReviewBlockedReasons(input, existingPrSearchStatus, reviewStatus, ciStatus, readiness);
+    const payload = {
+      version: 1,
+      stage: 'Stage 58',
+      artifact_kind: 'pr-review-intake-governance',
+      optional: true,
+      sidecar_only: true,
+      default_enabled: false,
+      [chainRequiredKey]: false,
+      created_at: new Date().toISOString(),
+      status: blockedReasons.length === 0 ? 'evidence_recorded' : 'manual_required',
+      input_evidence_file: evidence.path,
+      input_evidence_digest: evidence.digest,
+      pr_readiness_file: readiness.file,
+      pr_readiness_digest: readiness.digest,
+      pr_readiness_verification_ok: readiness.file ? readiness.verification_ok : false,
+      pr_readiness_verification_failures: readiness.verification_failures,
+      policy_catalog_digest: runtimePolicyCatalogDigest(),
+      pr_evidence: prEvidence(input, existingPrSearchStatus),
+      review_evidence: reviewEvidence(input, reviewStatus),
+      ci_evidence: ciEvidence(input, ciStatus, logExcerptDigest),
+      blocked_reasons: blockedReasons,
+      allowed_followup: prReviewFollowup(reviewStatus, ciStatus),
+      actions_not_taken: actionsNotTaken(),
+      boundary_assertions: falseMap(prReviewBoundaryKeys),
+    };
+    return { ...payload, pr_review_intake_digest: digestObject(payload) };
+  }
+
+  function prEvidence(input, existingPrSearchStatus) {
+    return {
+      pr_url_or_id: String(input.pr_url_or_id || input.pr_url || input.pr_id || '').trim(),
+      target_branch: String(input.target_branch || '').trim(),
+      target_scope: String(input.target_scope || '').trim(),
+      human_submitted: input.human_submitted === true,
+      existing_pr_search: { status: existingPrSearchStatus, evidence_file: String(input.existing_pr_search?.evidence_file || '').trim() },
+    };
+  }
+
+  function reviewEvidence(input, reviewStatus) {
+    const feedbackItems = normalizeIntakeArray(input.feedback_items);
+    return { review_status: reviewStatus, feedback_items: feedbackItems, feedback_digest: digestObject(feedbackItems) };
+  }
+
+  function ciEvidence(input, ciStatus, logExcerptDigest) {
+    return {
+      ci_status: ciStatus,
+      failed_jobs: normalizeIntakeArray(input.failed_jobs),
+      checks: normalizeIntakeArray(input.checks),
+      log_excerpt_digest: logExcerptDigest,
+    };
+  }
+
+  function prReviewEnvelope(root, { evidenceFile, readinessFile = '', persist = false } = {}) {
+    const intake = prReviewPayload(root, { evidenceFile, readinessFile });
+    return {
+      mode: 'governance-pr-review-intake',
+      ok: intake.status === 'evidence_recorded',
+      state_present: fs.existsSync(stateRootDirectory(root)),
+      pr_review_intake: { ...intake, writes: Boolean(persist) },
+      safety: sidecarSafetyBase('Stage 58', persist, 'pr_review_intake_governance'),
+      quality: intake.blocked_reasons,
+      action: readOnlyPrReviewAction(persist),
+    };
+  }
+
+  function validatePrReviewLinkedReadiness(root, intake, failures) {
+    if (!intake.pr_readiness_file) return;
+    try {
+      const readinessFile = governancePrReadinessFilePath(root, intake.pr_readiness_file);
+      if (!fs.existsSync(readinessFile)) failures.push(`PR readiness governance file missing: ${intake.pr_readiness_file}`);
+      else {
+        if (fileDigest(readinessFile) !== intake.pr_readiness_digest) failures.push('PR readiness governance digest mismatch');
+        const readinessArtifact = readJsonArtifact(readinessFile, 'PR readiness governance artifact');
+        const readinessVerification = validatePrReadinessArtifact(root, readinessArtifact);
+        if (!readinessVerification.ok) failures.push(...readinessVerification.failures.map((failure) => `linked readiness: ${failure}`));
+        if (intake.pr_readiness_verification_ok !== readinessVerification.ok) failures.push('pr_readiness_verification_ok drift');
+      }
+    } catch (error) {
+      failures.push(error.message);
+    }
+  }
+
+  function validatePrReviewEvidenceFile(root, intake, failures) {
+    try {
+      const evidenceFile = rootRelativeEvidenceFilePath(root, intake.input_evidence_file, 'pr_review_intake.input_evidence_file');
+      if (!fs.existsSync(evidenceFile)) failures.push(`input evidence file missing: ${intake.input_evidence_file}`);
+      else if (fileDigest(evidenceFile) !== intake.input_evidence_digest) failures.push('input evidence digest mismatch');
+    } catch (error) {
+      failures.push(error.message);
+    }
+  }
+
+  function validatePrReviewShape(intake, failures) {
+    if (intake.stage !== 'Stage 58') failures.push('pr_review_intake.stage must be Stage 58');
+    if (intake.artifact_kind !== 'pr-review-intake-governance') failures.push('pr_review_intake.artifact_kind must be pr-review-intake-governance');
+    if (intake.optional !== true) failures.push('pr_review_intake.optional must be true');
+    if (intake.sidecar_only !== true) failures.push('pr_review_intake.sidecar_only must be true');
+    if (intake.default_enabled !== false) failures.push('pr_review_intake.default_enabled must be false');
+    if (intake[chainRequiredKey] !== false) failures.push(['pr_review_intake.re', 'lea', 'se_chain_required must be false'].join(''));
+    if (!['evidence_recorded', 'manual_required'].includes(intake.status)) failures.push('pr_review_intake.status is invalid');
+  }
+
+  function validatePrReviewEvidenceShape(root, intake, failures) {
+    const pr = intake.pr_evidence || {};
+    if (typeof pr.pr_url_or_id !== 'string') failures.push('pr_evidence.pr_url_or_id must be string');
+    if (typeof pr.target_branch !== 'string') failures.push('pr_evidence.target_branch must be string');
+    if (typeof pr.target_scope !== 'string') failures.push('pr_evidence.target_scope must be string');
+    if (typeof pr.human_submitted !== 'boolean') failures.push('pr_evidence.human_submitted must be boolean');
+    if (!pr.existing_pr_search?.status) failures.push('pr_evidence.existing_pr_search.status is required');
+    const evidenceFile = String(pr.existing_pr_search?.evidence_file || '').trim();
+    if (evidenceFile) {
+      try {
+        rootRelativeEvidenceFilePath(root, evidenceFile, 'pr_evidence.existing_pr_search.evidence_file');
+      } catch (error) {
+        failures.push(error.message);
+      }
+    }
+  }
+
+  function validatePrReviewStatusEvidence(intake, failures) {
+    const review = intake.review_evidence || {};
+    if (!prReviewStatuses.has(review.review_status)) failures.push('review_evidence.review_status is invalid');
+    if (!Array.isArray(review.feedback_items)) failures.push('review_evidence.feedback_items must be an array');
+    if (review.feedback_digest !== digestObject(review.feedback_items || [])) failures.push('review_evidence.feedback_digest mismatch');
+    const ci = intake.ci_evidence || {};
+    if (!prReviewCiStatuses.has(ci.ci_status)) failures.push('ci_evidence.ci_status is invalid');
+    if (!Array.isArray(ci.failed_jobs)) failures.push('ci_evidence.failed_jobs must be an array');
+    if (!Array.isArray(ci.checks)) failures.push('ci_evidence.checks must be an array');
+  }
+
+  function validatePrReviewAllowedFollowup(intake, failures) {
+    const allowedFollowup = Array.isArray(intake.allowed_followup) ? intake.allowed_followup : [];
+    for (const item of allowedFollowup) {
+      if (!prReviewAllowedFollowups.has(item)) failures.push(`pr_review_intake.allowed_followup is invalid: ${item}`);
+    }
+  }
+
+  function validatePrReviewArtifact(root, artifact) {
+    const failures = [];
+    if (artifact.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+    if (artifact.command !== 'governance') failures.push('command must be governance');
+    if (artifact.mode !== 'governance-pr-review-intake') failures.push('mode must be governance-pr-review-intake');
+    const intake = artifact.pr_review_intake || {};
+    validatePrReviewShape(intake, failures);
+    validatePrReviewEvidenceFile(root, intake, failures);
+    validatePrReviewLinkedReadiness(root, intake, failures);
+    if (intake.policy_catalog_digest !== runtimePolicyCatalogDigest()) failures.push('policy catalog digest mismatch');
+    validatePrReviewEvidenceShape(root, intake, failures);
+    validatePrReviewStatusEvidence(intake, failures);
+    validatePrReviewAllowedFollowup(intake, failures);
+    for (const [key, expected] of Object.entries(actionsNotTaken())) {
+      if (intake.actions_not_taken?.[key] !== expected) failures.push(`pr_review_intake.actions_not_taken.${key} must be false`);
+    }
+    validateFalseFlags('pr_review_intake.boundary_assertions', intake.boundary_assertions, prReviewBoundaryKeys, failures);
+    validateCommonSidecarSafety(artifact, failures);
+    const digestPayload = { ...intake };
+    delete digestPayload.writes;
+    delete digestPayload.pr_review_intake_digest;
+    if (intake.pr_review_intake_digest !== digestObject(digestPayload)) failures.push('pr_review_intake digest mismatch');
+    return { ok: failures.length === 0, failures };
+  }
+
+  function writePrReviewIntake(root, envelope) {
+    const file = governancePrReviewIntakeSnapshotPath(root);
+    const payload = { schema_version: jsonSchemaVersion, command: 'governance', ...envelope, safety: { ...envelope.safety, pr_review_intake_governance: true } };
+    const verification = validatePrReviewArtifact(root, payload);
+    if (!verification.ok) throw new Error(`PR review intake governance verification failed: ${verification.failures.join('; ')}`);
+    return stateArtifactWriter(path.dirname(file), path.basename(file), payload);
+  }
+
+  return {
+    governancePrReadinessEnvelope: prReadinessEnvelope,
+    validateGovernancePrReadinessArtifact: validatePrReadinessArtifact,
+    writeGovernancePrReadiness: writePrReadiness,
+    governancePrReviewIntakeEnvelope: prReviewEnvelope,
+    validateGovernancePrReviewIntakeArtifact: validatePrReviewArtifact,
+    writeGovernancePrReviewIntake: writePrReviewIntake,
+  };
+}

package/tools/vibe-runtime/runtime-governance-presentation.mjs

@@ -0,0 +1,67 @@
+export function createGovernancePresentation({ printList }) {
+  function printRuntimeRegistryDriftGuard(envelope) {
+    const guard = envelope.runtime_registry_drift_guard;
+    console.log('Vibecoding Runtime Capability Registry Drift Guard');
+    console.log(`Stage: ${guard.stage}; Guard: ${guard.guard_kind}; pass=${guard.guard_pass}`);
+    console.log(`Registry: ${guard.registry_stage}; ${guard.registry_kind}; version=${guard.registry_version}`);
+    console.log(`Surface: ${guard.surface_stage}; ${guard.surface_kind}`);
+    console.log(`Checked: ${guard.checked.join(', ')}`);
+    console.log('Boundary: writes=false; runtime_registry_drift_guard_artifact=false; command_execution=false; workflow_execution=false; verification_execution=false; git=false; pr=false; push=false; merge=false; platform_api=false; subagent=false');
+    console.log(`Registry digest: ${guard.registry_digest}`);
+    console.log(`Surface digest: ${guard.surface_digest}`);
+    console.log(`Drift guard digest: ${guard.drift_guard_digest}`);
+    if (guard.findings.length > 0) printList('Findings', guard.findings);
+    console.log(`Manual action: ${guard.manual_action}`);
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  function printRuntimeSurface(envelope) {
+    const surface = envelope.runtime_surface;
+    console.log('Vibecoding Runtime Capability Surface');
+    console.log(`Stage: ${surface.stage}; Surface: ${surface.surface_kind}`);
+    console.log(`Capability groups: ${surface.capability_groups.length}`);
+    for (const group of surface.capability_groups) {
+      console.log(`- ${group.group}: stages=${group.stages.join(', ')}; commands=${group.commands.join(' | ')}`);
+    }
+    console.log(`Stage inventory: ${surface.stage_inventory.length}`);
+    console.log(`Registry: ${surface.registry_stage}; ${surface.registry_kind}; pass=${surface.registry_invariants.pass}`);
+    printList('Closeout chain', surface.closeout_chain.map((item) => `${item.order}. ${item.command} - ${item.purpose}`));
+    console.log('Boundary: writes=false; runtime_surface_artifact=false; capability_registry_artifact=false; command_execution=false; workflow_execution=false; verification_execution=false; git=false; pr=false; push=false; merge=false; platform_api=false; subagent=false');
+    console.log(`Registry digest: ${surface.registry_digest}`);
+    console.log(`Surface digest: ${surface.surface_digest}`);
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  function printGovernanceConvergence(envelope) {
+    console.log('Vibecoding Runtime Convergence Report');
+    console.log('Mode: report');
+    console.log(`State present: ${envelope.state_present ? 'yes' : 'no'}`);
+    console.log(`Target: ${envelope.convergence.convergence_target}`);
+    console.log(`Dimensions: ${envelope.convergence.summary.total_dimensions}; Planned: ${envelope.convergence.summary.planned}; Partial: ${envelope.convergence.summary.partially_implemented}; Deferred: ${envelope.convergence.summary.deferred}`);
+    for (const dimension of envelope.convergence.dimensions) {
+      console.log(`- ${dimension.id}: source=${dimension.source}; status=${dimension.status}; target=${dimension.target_stage}`);
+    }
+    if (envelope.quality.length > 0) printList('Convergence gaps', envelope.quality);
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  function printGovernanceAdvice(envelope) {
+    const advice = envelope.governance_advice;
+    console.log('Vibecoding Runtime Governance Advice');
+    console.log(`Stage: ${advice.stage}; Intent: ${advice.intent}; Advice: ${advice.advice_kind}`);
+    console.log(`Next step: ${advice.recommended_next_governance_step}`);
+    console.log(`Recommended command: ${advice.recommended_command}`);
+    console.log(`Manual action: ${advice.manual_action}`);
+    console.log('Boundary: pr=false; push=false; merge=false; platform_api=false; git=false; worktree=false');
+    console.log(`Advice digest: ${advice.advice_digest}`);
+    if (envelope.quality.length > 0) printList('Notes', envelope.quality);
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  return {
+    printRuntimeRegistryDriftGuard,
+    printRuntimeSurface,
+    printGovernanceConvergence,
+    printGovernanceAdvice,
+  };
+}