@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime-check/index.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { createSourceTextReader } from './runtime-source-bundle.mjs';
+import { checkArchitectureCheckTool } from './architecture-tool-contracts.mjs';
+import { checkRuntimeAutomationReadinessContracts } from './runtime-automation-readiness-contracts.mjs';
+import { checkRuntimeCapabilityRegistryContracts } from './runtime-capability-registry-contracts.mjs';
+import { checkRuntimeCloseLoopContracts } from './runtime-close-loop-contracts.mjs';
+import { checkProductArtifactGateContracts } from './product-artifact-contracts.mjs';
+import { checkRuntimeControlPlaneContracts } from './runtime-control-plane-contracts.mjs';
+import { checkRuntimeCliSurfaceContracts } from './runtime-cli-surface-contracts.mjs';
+import { checkRuntimeDocMarkerContracts } from './runtime-doc-marker-contracts.mjs';
+import { checkRuntimeDocFoundationContracts } from './runtime-doc-contracts.mjs';
+import { checkRuntimeExperienceCliContracts } from './runtime-experience-cli-contracts.mjs';
+import { checkRuntimeExperienceContracts } from './runtime-experience-contracts.mjs';
+import { checkRuntimeGovernanceLearningTokenContracts } from './runtime-governance-learning-token-contracts.mjs';
+import { checkRuntimeHighRiskBoundaryContracts } from './runtime-high-risk-boundary-contracts.mjs';
+import { checkRuntimeArchitectureManifestDriftContracts } from './runtime-architecture-manifest-drift-contracts.mjs';
+import { checkRuntimeIndexImportBoundaryContracts } from './runtime-index-import-boundary-contracts.mjs';
+import { checkRuntimePureModelBoundaryContracts } from './runtime-pure-model-boundary-contracts.mjs';
+import { checkRuntimeOptimizationBoundaryContracts } from './runtime-optimization-boundary-contracts.mjs';
+import { checkRuntimeReleaseCloseoutContracts } from './runtime-release-closeout-contracts.mjs';
+import { checkReleaseRuntimeSuiteLayerContracts } from './release-runtime-suite-layer-contracts.mjs';
+import { checkRuntimeToolReadmeContracts } from './runtime-tool-readme-contracts.mjs';
+import { checkInstallSummaryAdoptionContracts } from './install-summary-adoption-contracts.mjs';
+import {
+  checkReleaseCheckInstallPlacementContracts,
+  collectReleaseCheckInstallPlacementDiagnostics,
+} from './release-check-install-placement-contracts.mjs';
+import { printRuntimeCheckDiagnostics } from './runtime-check-diagnostics-presentation.mjs';
+import {
+  checkEntryFileSizeBudgets,
+  checkReadonlySmokeMarkerDataContracts,
+  checkRuntimeInteractionCommandDomainContracts,
+  checkRuntimeInteractionHighRiskSidecarBoundaryContracts,
+  checkRuntimePresentationCoverageContracts,
+  collectArchitecturePerformanceDiagnostics,
+} from './runtime-entry-size-contracts.mjs';
+import {
+  checkWorkflowSkillContracts,
+  listWorkflowSkills,
+} from './workflow-skill-contracts.mjs';
+import { checkWorkflowUxContracts } from './workflow-ux-contracts.mjs';
+
+const args = process.argv.slice(2);
+const results = [];
+
+function usage() {
+  return `Vibecoding Runtime Check\n\nUsage:\n  node tools/vibe-runtime-check/index.mjs [--root <path>] [--diagnostics]\n\nOptions:\n  --root <path>  Repository root to check. Defaults to current working directory.\n  --diagnostics  Print opt-in source reader cache diagnostics.\n  --help         Show this help.\n`;
+}
+
+function parseArgs(argv) {
+  const options = { root: process.cwd(), help: false, diagnostics: false };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+    } else if (arg === '--diagnostics') {
+      options.diagnostics = true;
+    } else if (arg === '--root') {
+      const value = argv[index + 1];
+      if (!value) throw new Error('--root requires a path');
+      options.root = path.resolve(value);
+      index += 1;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+function add(status, label, detail = '', fix = '') {
+  results.push({ status, label, detail, fix });
+}
+
+function ok(label, detail = '') {
+  add('ok', label, detail);
+}
+
+function warn(label, detail = '', fix = '') {
+  add('warn', label, detail, fix);
+}
+
+function fail(label, detail = '', fix = '') {
+  add('fail', label, detail, fix);
+}
+
+function toNative(root, relativePath) {
+  return path.join(root, ...relativePath.split('/'));
+}
+
+function exists(root, relativePath) {
+  return fs.existsSync(toNative(root, relativePath));
+}
+
+function readText(root, relativePath) {
+  return fs.readFileSync(toNative(root, relativePath), 'utf8');
+}
+
+function printResults(root, workflowSkills, options = {}) {
+  const counts = results.reduce(
+    (acc, item) => {
+      acc[item.status] += 1;
+      return acc;
+    },
+    { ok: 0, warn: 0, fail: 0 },
+  );
+
+  console.log('Vibecoding Runtime Check');
+  console.log(`Root: ${root}`);
+  console.log(`Workflow skills: ${workflowSkills.length}`);
+  console.log('');
+
+  for (const item of results) {
+    const prefix = item.status === 'ok' ? '[ok]' : item.status === 'warn' ? '[warn]' : '[fail]';
+    console.log(`${prefix} ${item.label}`);
+    if (item.detail) console.log(`       ${item.detail}`);
+    if (item.fix) console.log(`       fix: ${item.fix}`);
+  }
+
+  console.log('');
+  console.log(`Result: ${counts.fail > 0 ? 'failed' : counts.warn > 0 ? 'passed with warnings' : 'passed'}`);
+  console.log(`Checks: ${counts.ok} ok, ${counts.warn} warn, ${counts.fail} fail`);
+
+  if (options.diagnostics) {
+    printRuntimeCheckDiagnostics(options);
+  }
+
+  if (counts.fail > 0) process.exitCode = 1;
+}
+
+try {
+  const options = parseArgs(args);
+  if (options.help) {
+    console.log(usage());
+    process.exit(0);
+  }
+
+  const root = path.resolve(options.root);
+  const sourceReader = createSourceTextReader({ exists, readText }, root);
+  const checkApi = {
+    exists,
+    readText,
+    ok,
+    warn,
+    fail,
+    sourceReader,
+  };
+
+  checkEntryFileSizeBudgets(root, checkApi);
+  checkReadonlySmokeMarkerDataContracts(root, checkApi);
+  checkReleaseCheckInstallPlacementContracts(root, checkApi);
+  checkRuntimePresentationCoverageContracts(root, checkApi);
+  checkRuntimeInteractionCommandDomainContracts(root, checkApi);
+  checkRuntimeInteractionHighRiskSidecarBoundaryContracts(root, checkApi);
+  checkRuntimeDocFoundationContracts(root, checkApi);
+  checkRuntimeDocMarkerContracts(root, checkApi);
+  checkRuntimeHighRiskBoundaryContracts(root, checkApi);
+  checkRuntimeArchitectureManifestDriftContracts(root, checkApi);
+  checkRuntimeIndexImportBoundaryContracts(root, checkApi);
+  checkRuntimePureModelBoundaryContracts(root, checkApi);
+  checkRuntimeOptimizationBoundaryContracts(root, checkApi);
+  checkRuntimeToolReadmeContracts(root, checkApi);
+  checkInstallSummaryAdoptionContracts(root, checkApi);
+  checkRuntimeControlPlaneContracts(root, checkApi);
+  checkProductArtifactGateContracts(root, checkApi);
+  checkReleaseRuntimeSuiteLayerContracts(checkApi);
+  checkArchitectureCheckTool(root, checkApi);
+
+  const workflowSkills = listWorkflowSkills(root, checkApi);
+  if (workflowSkills.length === 0) {
+    fail('workflow skills missing', 'No skills/*/SKILL.md files found.', 'Run this check from the Vibecoding Kit repo root.');
+  }
+
+  checkWorkflowSkillContracts(root, workflowSkills, checkApi);
+  const architecturePerformanceDiagnostics = options.diagnostics ? collectArchitecturePerformanceDiagnostics(root, checkApi) : null;
+  const installPlacementDiagnostics = options.diagnostics ? collectReleaseCheckInstallPlacementDiagnostics(root, checkApi) : null;
+  printResults(root, workflowSkills, { diagnostics: options.diagnostics, sourceReader, architecturePerformanceDiagnostics, installPlacementDiagnostics });
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  process.exit(1);
+}

package/tools/vibe-runtime-check/install-summary-adoption-contracts.mjs

@@ -0,0 +1,115 @@
+const installedExperienceSummaryMarkers = Object.freeze([
+  'Installed Agent Experience Contract v2',
+  'installed-agent-experience-contract-v2',
+  'first_turn',
+  'continue_task',
+  'bug_debug',
+  'completion_closeout',
+  'hidden_execution=false',
+  'command_execution=false',
+  'skill_execution_claimed=false',
+  'subagent_dispatch_claimed=false',
+  'business_source_write=false',
+  'git_write_claimed=false',
+  'platform_api=false',
+  'model_invocation=false',
+]);
+
+const templateSummaryMarkers = Object.freeze([
+  'workflow --start',
+  'workflow_start.entry_summary',
+  'entry_summary.state_gap_is_expected=true',
+  'completion_evidence.task_completion_summary',
+  'blocked_reasons',
+  'readiness gates',
+  '不授权自动执行命令',
+  'subagent',
+  '平台 API',
+  'git',
+  'push',
+  'PR',
+  'merge',
+  ...installedExperienceSummaryMarkers,
+]);
+
+const adapterSummaryMarkers = Object.freeze([
+  '摘要优先入口',
+  'workflow_start.entry_summary',
+  'entry_summary.state_gap_is_expected=true',
+  'completion_evidence.task_completion_summary',
+  'blocked_reasons',
+  'readiness gates',
+  '不授予隐藏执行',
+  '自动写入',
+  '自动测试',
+  'subagent',
+  '平台 API',
+  'git',
+  'push',
+  'PR',
+  'merge',
+]);
+
+const installEntryFiles = Object.freeze([
+  {
+    path: 'templates/CLAUDE.md',
+    markers: templateSummaryMarkers,
+    rootMarker: 'CLAUDE.md',
+    okLabel: 'templates/CLAUDE.md documents summary-first installed entry semantics',
+    failLabel: 'templates/CLAUDE.md summary-first installed entry markers incomplete',
+  },
+  {
+    path: 'templates/AGENTS.md',
+    markers: templateSummaryMarkers,
+    rootMarker: 'AGENTS.md',
+    okLabel: 'templates/AGENTS.md documents summary-first installed entry semantics',
+    failLabel: 'templates/AGENTS.md summary-first installed entry markers incomplete',
+  },
+  {
+    path: 'adapters/claude/install.md',
+    markers: adapterSummaryMarkers,
+    rootMarker: 'CLAUDE.md',
+    okLabel: 'adapters/claude/install.md documents summary-first installed entry semantics',
+    failLabel: 'adapters/claude/install.md summary-first installed entry markers incomplete',
+  },
+  {
+    path: 'adapters/codex/install.md',
+    markers: adapterSummaryMarkers,
+    rootMarker: 'AGENTS.md',
+    okLabel: 'adapters/codex/install.md documents summary-first installed entry semantics',
+    failLabel: 'adapters/codex/install.md summary-first installed entry markers incomplete',
+  },
+  {
+    path: 'adapters/cursor/install.md',
+    markers: adapterSummaryMarkers,
+    rootMarker: 'AGENTS.md',
+    okLabel: 'adapters/cursor/install.md documents summary-first installed entry semantics',
+    failLabel: 'adapters/cursor/install.md summary-first installed entry markers incomplete',
+  },
+]);
+
+function checkMarkers(root, api, entry) {
+  const { exists, readText, ok, fail } = api;
+  if (!exists(root, entry.path)) {
+    fail(entry.failLabel, `Missing file: ${entry.path}`, 'Restore installed entry template or adapter install documentation.');
+    return;
+  }
+
+  const text = readText(root, entry.path);
+  const markers = [entry.rootMarker, ...entry.markers];
+  const missing = markers.filter((marker) => !text.includes(marker));
+  if (missing.length === 0) {
+    ok(entry.okLabel);
+    return;
+  }
+
+  fail(
+    entry.failLabel,
+    `Missing marker(s): ${missing.join(', ')}`,
+    'Keep installed templates and adapter docs aligned with summary-first workflow_start and completion evidence semantics without expanding execution/write boundaries.',
+  );
+}
+
+export function checkInstallSummaryAdoptionContracts(root, api) {
+  for (const entry of installEntryFiles) checkMarkers(root, api, entry);
+}

package/tools/vibe-runtime-check/marker-contract-core.mjs

@@ -0,0 +1,20 @@
+export function checkRequiredFiles(root, api, files, { missingFix }) {
+  for (const file of files) {
+    if (api.exists(root, file)) api.ok(`${file} exists`);
+    else api.fail(`${file} missing`, '', missingFix);
+  }
+}
+
+export function checkMarkers(root, api, file, markers, okLabel, failLabel, fix) {
+  if (!api.exists(root, file)) return;
+  const text = api.readText(root, file);
+  const missing = markers.filter((marker) => !text.includes(marker));
+  if (missing.length === 0) api.ok(okLabel);
+  else api.fail(failLabel, `Missing marker(s): ${missing.join(', ')}`, fix);
+}
+
+export function checkMarkerGroups(root, api, groups) {
+  for (const [file, okLabel, failLabel, markers, fix] of groups) {
+    checkMarkers(root, api, file, markers, okLabel, failLabel, fix);
+  }
+}

package/tools/vibe-runtime-check/product-artifact-contracts.mjs

@@ -0,0 +1,24 @@
+import {
+  checkMarkerGroups,
+  checkMarkers,
+  checkRequiredFiles,
+} from './marker-contract-core.mjs';
+import { productArtifactGateContractRegistry } from './runtime-contract-registry.mjs';
+
+export function checkProductArtifactGateContracts(root, api) {
+  checkRequiredFiles(root, api, productArtifactGateContractRegistry.requiredFiles, {
+    missingFix: productArtifactGateContractRegistry.requiredFilesFix,
+  });
+
+  for (const [file, markers] of productArtifactGateContractRegistry.docMarkerChecks) {
+    checkMarkers(root, api, file, markers, `${file} documents product/UI delivery artifact gates`, `${file} product/UI delivery artifact gate markers incomplete`, 'Document Stage 151-155 product, delivery, and full-chain completion evidence gates.');
+  }
+
+  checkMarkerGroups(root, api, productArtifactGateContractRegistry.runtimeMarkerChecks.map(([file, okLabel, failLabel, markers]) => [
+    file,
+    okLabel,
+    failLabel,
+    markers,
+    productArtifactGateContractRegistry.runtimeMarkerFix,
+  ]));
+}

package/tools/vibe-runtime-check/release-check-install-placement-contracts.mjs

@@ -0,0 +1,166 @@
+import { getSourceTextReader } from './runtime-source-bundle.mjs';
+
+function fileStats(reader, file) {
+  return { file, exists: reader.exists(file), text: reader.readText(file) };
+}
+
+function countText(text, needle) {
+  return String(text || '').split(needle).length - 1;
+}
+
+const releaseCheckEntryFile = 'tools/vibe-release-check/index.mjs';
+const releaseCheckInstallSuiteFile = 'tools/vibe-release-check/release-check-install-suite.mjs';
+const releaseCheckInstallMarkerSpecsFile = 'tools/vibe-release-check/release-check-install-marker-specs.mjs';
+const runtimeCheckEntryFile = 'tools/vibe-runtime-check/index.mjs';
+const runtimeCheckDiagnosticsPresentationFile = 'tools/vibe-runtime-check/runtime-check-diagnostics-presentation.mjs';
+const minimumInstallSmokeHandlerRefs = 2;
+const runtimeCheckInstallPlacementImport = "from './release-check-install-placement-contracts.mjs'";
+const runtimeCheckInstallPlacementCall = 'checkReleaseCheckInstallPlacementContracts(root, checkApi)';
+
+const runtimeCheckInstallPlacementDiagnosticsMarkers = Object.freeze([
+  'formatReleaseCheckInstallPlacementDiagnostics',
+  'printInstallPlacementDiagnostics(options.installPlacementDiagnostics)',
+]);
+
+const requiredInstallSuiteMarkers = Object.freeze([
+  'tools/vibe-init/index.mjs',
+  'tools/vibe-doctor/index.mjs',
+  'workflow_start.entry_summary',
+  'completion_evidence.task_completion_summary',
+  'CLAUDE.md',
+  'AGENTS.md',
+  '.vibecoding/VIBE-CODING.md',
+  '.vibecoding/config.json',
+  'installedConfigManifestMarkers',
+  'installed-agent-experience-contract-v2',
+  'Completion closeout acceptance prompt',
+  '.vibecoding/adapters/${platform}/install.md',
+  '.vibecoding/skills/using-vibecoding/SKILL.md',
+  '.vibecoding/hooks/session-start/session-start.mjs',
+]);
+
+const forbiddenReleaseCheckEntryMarkers = Object.freeze([
+  'tools/vibe-init/index.mjs',
+  'tools/vibe-doctor/index.mjs',
+  'installedEntrySummaryMarkers',
+  'installedTemplateSummaryMarkers',
+  'installedAdapterSummaryMarkers',
+  'assertInstalledSummaryAdoption',
+  'assertInstalledFileMarkers',
+  '.vibecoding/adapters/${platform}/install.md',
+  '.vibecoding/skills/using-vibecoding/SKILL.md',
+  '.vibecoding/hooks/session-start/session-start.mjs',
+  'workflow_start.entry_summary',
+  'completion_evidence.task_completion_summary',
+]);
+
+function releaseCheckInstallPlacementStats(root, api) {
+  const reader = getSourceTextReader(api, root);
+  const entryFile = fileStats(reader, releaseCheckEntryFile);
+  const suiteFile = fileStats(reader, releaseCheckInstallSuiteFile);
+  const markerSpecsFile = fileStats(reader, releaseCheckInstallMarkerSpecsFile);
+  const runtimeCheckEntry = fileStats(reader, runtimeCheckEntryFile);
+  const diagnosticsPresentationFile = fileStats(reader, runtimeCheckDiagnosticsPresentationFile);
+  const installSuiteSourceBundleText = `${suiteFile.text || ''}\n${markerSpecsFile.text || ''}`;
+  const runtimeCheckDiagnosticsBundleText = `${runtimeCheckEntry.text || ''}\n${diagnosticsPresentationFile.text || ''}`;
+  return {
+    entryFile,
+    suiteFile,
+    markerSpecsFile,
+    runtimeCheckEntry,
+    diagnosticsPresentationFile,
+    requiredSuiteMarkers: requiredInstallSuiteMarkers,
+    missingSuiteMarkers: requiredInstallSuiteMarkers.filter((marker) => !installSuiteSourceBundleText.includes(marker)),
+    entryLeaks: forbiddenReleaseCheckEntryMarkers.filter((marker) => entryFile.text?.includes(marker)),
+    suiteImportCount: countText(entryFile.text, "from './release-check-install-suite.mjs'"),
+    handlerWireCount: countText(entryFile.text, 'runSinglePlatformSmoke'),
+    runtimeCheckImportCount: countText(runtimeCheckEntry.text, runtimeCheckInstallPlacementImport),
+    runtimeCheckCallCount: countText(runtimeCheckEntry.text, runtimeCheckInstallPlacementCall),
+    missingDiagnosticsMarkers: runtimeCheckInstallPlacementDiagnosticsMarkers.filter((marker) => !runtimeCheckDiagnosticsBundleText.includes(marker)),
+  };
+}
+
+function hasInstallSuiteCoverage(stats) { return stats.suiteFile.exists && stats.markerSpecsFile.exists && stats.missingSuiteMarkers.length === 0; }
+function hasReleaseCheckEntryWiringOnly(stats) { return stats.entryFile.exists && stats.entryLeaks.length === 0 && stats.suiteImportCount === 1 && stats.handlerWireCount >= minimumInstallSmokeHandlerRefs; }
+function hasRuntimeCheckRegistration(stats) { return stats.runtimeCheckEntry.exists && stats.runtimeCheckImportCount === 1 && stats.runtimeCheckCallCount === 1; }
+function hasReadableInstallDiagnostics(stats) { return stats.runtimeCheckEntry.exists && stats.diagnosticsPresentationFile.exists && stats.missingDiagnosticsMarkers.length === 0; }
+
+const installPlacementContracts = Object.freeze([
+  { followup: 'install_suite_coverage', isOk: hasInstallSuiteCoverage, ok: ['release-check install suite keeps installed project marker coverage', (stats) => `markers=${stats.requiredSuiteMarkers.length}; files=${stats.suiteFile.file},${stats.markerSpecsFile.file}`], fail: ['release-check install suite marker coverage drifted', (stats) => `missing=${stats.missingSuiteMarkers.join(', ') || 'none'}; exists=suite:${stats.suiteFile.exists === true},markerSpecs:${stats.markerSpecsFile.exists === true}`, 'Keep install command/assertion checks in release-check-install-suite.mjs and marker specs in release-check-install-marker-specs.mjs.'] },
+  { followup: 'release_check_entry_boundary', isOk: hasReleaseCheckEntryWiringOnly, ok: ['release-check entry only wires install suite boundary', (stats) => `suiteImports=${stats.suiteImportCount}; handlerRefs=${stats.handlerWireCount}`], fail: ['release-check entry absorbed install suite details', (stats) => `leaks=${stats.entryLeaks.join(', ') || 'none'}; suiteImports=${stats.suiteImportCount}; handlerRefs=${stats.handlerWireCount}`, 'Keep installed project marker arrays and smoke assertions out of tools/vibe-release-check/index.mjs; route them through release-check-install-suite.mjs.'] },
+  { followup: 'runtime_check_registration', isOk: hasRuntimeCheckRegistration, ok: ['runtime-check entry registers install placement contract once', (stats) => `imports=${stats.runtimeCheckImportCount}; calls=${stats.runtimeCheckCallCount}`], fail: ['runtime-check entry install placement contract registration drifted', (stats) => `exists=${stats.runtimeCheckEntry.exists === true}; imports=${stats.runtimeCheckImportCount}; calls=${stats.runtimeCheckCallCount}`, 'Keep release-check-install-placement-contracts.mjs imported and executed from tools/vibe-runtime-check/index.mjs exactly once.'] },
+  { followup: 'diagnostics_readability', isOk: hasReadableInstallDiagnostics, ok: ['runtime-check diagnostics keep install placement health summary readable', () => `markers=${runtimeCheckInstallPlacementDiagnosticsMarkers.length}`], fail: ['runtime-check diagnostics install placement summary regressed', (stats) => `missing=${stats.missingDiagnosticsMarkers.join(', ') || 'none'}; exists=${stats.runtimeCheckEntry.exists === true}`, 'Keep --diagnostics output showing installPlacement health and named file presence, not only raw counts.'] },
+]);
+
+function hasHealthyInstallPlacement(stats) { return installPlacementContracts.every(({ isOk }) => isOk(stats)); }
+function installPlacementFollowup(stats) { return installPlacementContracts.filter(({ isOk }) => !isOk(stats)).map(({ followup }) => followup).join(',') || 'none'; }
+
+function reportInstallPlacementContract(stats, api, { isOk, ok: okReport, fail: failReport }) {
+  const [okLabel, okDetail] = okReport;
+  const [failLabel, failDetail, fix] = failReport;
+  if (isOk(stats)) {
+    api.ok(okLabel, okDetail(stats));
+  } else {
+    api.fail(failLabel, failDetail(stats), fix);
+  }
+}
+
+export function collectReleaseCheckInstallPlacementDiagnostics(root, api) {
+  const stats = releaseCheckInstallPlacementStats(root, api);
+  const healthy = hasHealthyInstallPlacement(stats);
+
+  return {
+    health: healthy ? 'healthy' : 'attention_needed',
+    followup: installPlacementFollowup(stats),
+    requiredMarkers: stats.requiredSuiteMarkers.length,
+    missingMarkers: stats.missingSuiteMarkers.length,
+    entryLeaks: stats.entryLeaks.length,
+    suiteImports: stats.suiteImportCount,
+    handlerRefs: stats.handlerWireCount,
+    runtimeCheckImports: stats.runtimeCheckImportCount,
+    runtimeCheckCalls: stats.runtimeCheckCallCount,
+    suiteFileExists: stats.suiteFile.exists === true,
+    markerSpecsFileExists: stats.markerSpecsFile.exists === true,
+    entryFileExists: stats.entryFile.exists === true,
+    runtimeCheckEntryExists: stats.runtimeCheckEntry.exists === true,
+  };
+}
+
+const installPlacementSummaryDiagnosticFields = Object.freeze([
+  ['health', ({ health }) => health],
+  ['followup', ({ followup }) => followup],
+]);
+
+const installPlacementDetailDiagnosticFields = Object.freeze([
+  ['requiredMarkers', ({ requiredMarkers }) => requiredMarkers],
+  ['missingMarkers', ({ missingMarkers }) => missingMarkers],
+  ['entryLeaks', ({ entryLeaks }) => entryLeaks],
+  ['suiteImports', ({ suiteImports }) => suiteImports],
+  ['handlerRefs', ({ handlerRefs }) => handlerRefs],
+  ['runtimeCheckImports', ({ runtimeCheckImports }) => runtimeCheckImports],
+  ['runtimeCheckCalls', ({ runtimeCheckCalls }) => runtimeCheckCalls],
+]);
+
+function formatDiagnosticFields(fields, diagnostics) {
+  return fields.map(([key, value]) => `${key}=${value(diagnostics)}`);
+}
+
+function formatInstallPlacementFiles(diagnostics) {
+  return `files=suite:${diagnostics.suiteFileExists},markerSpecs:${diagnostics.markerSpecsFileExists},entry:${diagnostics.entryFileExists},runtimeCheck:${diagnostics.runtimeCheckEntryExists}`;
+}
+
+export function formatReleaseCheckInstallPlacementDiagnostics(diagnostics) {
+  if (!diagnostics) return '';
+  const summary = formatDiagnosticFields(installPlacementSummaryDiagnosticFields, diagnostics)
+    .concat(formatInstallPlacementFiles(diagnostics));
+  const details = formatDiagnosticFields(installPlacementDetailDiagnosticFields, diagnostics);
+  return [
+    `installPlacement summary: ${summary.join('; ')}`,
+    `installPlacement details: ${details.join('; ')}`,
+  ].join('\n');
+}
+
+export function checkReleaseCheckInstallPlacementContracts(root, api) {
+  const stats = releaseCheckInstallPlacementStats(root, api);
+  installPlacementContracts.forEach((contract) => reportInstallPlacementContract(stats, api, contract));
+}

package/tools/vibe-runtime-check/release-runtime-suite-layer-contracts.mjs

@@ -0,0 +1,137 @@
+import { releaseCheckCommands } from '../vibe-release-check/release-check-command-manifest.mjs';
+import { commandMetadataEntry, commandEntryRuntimeSuiteLayer } from '../vibe-release-check/command-manifest/release-check-command-metadata.mjs';
+import { runtimeSuiteLayers } from '../vibe-release-check/command-manifest/release-check-runtime-smoke-commands.mjs';
+import { filterReleaseCheckCommands, normalizeReleaseCheckSuite } from '../vibe-release-check/release-check-suites.mjs';
+
+function commandKey(entry) {
+  const [command, args = [], settings = {}] = entry;
+  const metadata = settings.metadata || {};
+  return JSON.stringify({ command, args, handler: metadata.handler || '' });
+}
+
+function commandLabel(entry) {
+  const [command, args = []] = entry;
+  return [command, ...args].join(' ');
+}
+
+function metadataFailures(runtimeCommands, layers) {
+  const layerSet = new Set(layers);
+  const missing = [];
+  const unknown = [];
+
+  for (const entry of runtimeCommands) {
+    const layer = commandEntryRuntimeSuiteLayer(entry);
+    if (!layer) missing.push(commandLabel(entry));
+    else if (!layerSet.has(layer)) unknown.push(`${commandLabel(entry)} -> ${layer}`);
+  }
+
+  return { missing, unknown };
+}
+
+export function evaluateReleaseRuntimeSuiteLayerCoverage(commands, { layers = runtimeSuiteLayers, requireEveryLayer = true } = {}) {
+  const failures = [];
+  let runtimeCommands = [];
+
+  try {
+    runtimeCommands = filterReleaseCheckCommands(commands, 'runtime');
+  } catch (error) {
+    failures.push(`runtime suite selector failed: ${error.message}`);
+  }
+
+  const { missing, unknown } = metadataFailures(runtimeCommands, layers);
+  if (missing.length > 0) failures.push(`runtime command(s) missing suite layer: ${missing.join(', ')}`);
+  if (unknown.length > 0) failures.push(`runtime command(s) use unknown suite layer: ${unknown.join(', ')}`);
+
+  const runtimeKeys = new Set(runtimeCommands.map(commandKey));
+  const coveredKeys = new Set();
+  const layerCommandCounts = {};
+
+  for (const layer of layers) {
+    const suite = `runtime:${layer}`;
+    let selected = [];
+    try {
+      selected = filterReleaseCheckCommands(commands, suite);
+    } catch (error) {
+      if (requireEveryLayer) failures.push(`${suite} selector failed: ${error.message}`);
+    }
+
+    layerCommandCounts[layer] = selected.length;
+    if (requireEveryLayer && selected.length === 0) failures.push(`${suite} selected no commands`);
+
+    for (const entry of selected) {
+      const key = commandKey(entry);
+      const actualLayer = commandEntryRuntimeSuiteLayer(entry);
+      if (!runtimeKeys.has(key)) failures.push(`${suite} selected a command outside runtime suite: ${commandLabel(entry)}`);
+      if (actualLayer !== layer) failures.push(`${suite} selected command with mismatched layer: ${commandLabel(entry)} -> ${actualLayer || 'missing'}`);
+      coveredKeys.add(key);
+    }
+  }
+
+  const uncovered = runtimeCommands.filter((entry) => !coveredKeys.has(commandKey(entry)));
+  if (uncovered.length > 0) failures.push(`runtime command(s) not covered by layer suites: ${uncovered.map(commandLabel).join(', ')}`);
+
+  try {
+    normalizeReleaseCheckSuite('runtime:not-registered');
+    failures.push('unknown runtime layer selector was accepted');
+  } catch {
+    // Expected: layer selectors must be registered explicitly.
+  }
+
+  return {
+    ok: failures.length === 0,
+    failures,
+    runtimeCommandCount: runtimeCommands.length,
+    layerCommandCounts,
+  };
+}
+
+function releaseRuntimeSuiteLayerContractFixtures() {
+  return {
+    accepted: [commandMetadataEntry({ command: 'fixture-runtime-smoke', suites: ['runtime'], runtimeSuiteLayer: 'surface' })],
+    missingLayer: [commandMetadataEntry({ command: 'fixture-runtime-smoke', suites: ['runtime'] })],
+    unknownLayer: [commandMetadataEntry({ command: 'fixture-runtime-smoke', suites: ['runtime'], runtimeSuiteLayer: 'not-listed' })],
+  };
+}
+
+function checkReleaseRuntimeSuiteLayerFixtures(api) {
+  const fixtures = releaseRuntimeSuiteLayerContractFixtures();
+  const options = { layers: ['surface'], requireEveryLayer: false };
+  const accepted = evaluateReleaseRuntimeSuiteLayerCoverage(fixtures.accepted, options);
+  const missingLayer = evaluateReleaseRuntimeSuiteLayerCoverage(fixtures.missingLayer, options);
+  const unknownLayer = evaluateReleaseRuntimeSuiteLayerCoverage(fixtures.unknownLayer, options);
+  const unknownSelectorRejected = (() => {
+    try {
+      normalizeReleaseCheckSuite('runtime:not-listed');
+      return false;
+    } catch {
+      return true;
+    }
+  })();
+
+  if (accepted.ok && !missingLayer.ok && !unknownLayer.ok && unknownSelectorRejected) {
+    api.ok('release runtime suite layer fixtures reject missing and unknown layers');
+  } else {
+    api.fail(
+      'release runtime suite layer fixtures regressed',
+      `accepted=${accepted.ok}; missingLayer=${missingLayer.ok}; unknownLayer=${unknownLayer.ok}; unknownSelectorRejected=${unknownSelectorRejected}`,
+      'Keep runtime smoke layer metadata complete and keep runtime:<layer> suite names explicit.',
+    );
+  }
+}
+
+export function checkReleaseRuntimeSuiteLayerContracts(api) {
+  const evaluation = evaluateReleaseRuntimeSuiteLayerCoverage(releaseCheckCommands());
+  if (evaluation.ok) {
+    const layerSummary = Object.entries(evaluation.layerCommandCounts)
+      .map(([layer, count]) => `${layer}=${count}`)
+      .join(', ');
+    api.ok('release runtime suite layer coverage is complete', `runtimeCommands=${evaluation.runtimeCommandCount}; ${layerSummary}`);
+  } else {
+    api.fail(
+      'release runtime suite layer coverage regressed',
+      evaluation.failures.join('; '),
+      'Add an explicit runtimeSuiteLayer for every runtime smoke command and keep runtime:<layer> selectors aligned with the full runtime suite.',
+    );
+  }
+  checkReleaseRuntimeSuiteLayerFixtures(api);
+}