@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime-check/workflow-skill-contracts.mjs

@@ -0,0 +1,129 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  parseSkillContractDocument,
+  skillContractSchemaDocumentationMarkers,
+  skillGateContractDefinitions,
+  workflowSkillContractRequiredMarkers,
+} from '../vibe-runtime/runtime-skill-contract-schema.mjs';
+import { checkSkillRouteRegistryDrift } from './workflow-skill-route-registry-contracts.mjs';
+
+function toNative(root, relativePath) {
+  return path.join(root, ...relativePath.split('/'));
+}
+function skillNameFromPath(file) {
+  return file.split('/')[1];
+}
+
+export function listWorkflowSkills(root, api) {
+  const skillsDirectory = toNative(root, 'skills');
+  if (!fs.existsSync(skillsDirectory)) return [];
+
+  return fs.readdirSync(skillsDirectory, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => `skills/${entry.name}/SKILL.md`)
+    .filter((file) => file !== 'skills/using-vibecoding/SKILL.md')
+    .filter((file) => api.exists(root, file))
+    .sort();
+}
+
+function checkSkillContract(root, file, api) {
+  const text = api.readText(root, file);
+  const contract = parseSkillContractDocument(file, text);
+  const requiredMarkers = workflowSkillContractRequiredMarkers(file);
+
+  if (contract.parsed) {
+    api.ok(`${file} is parsed by Stage 22 skill contract schema`, `fields=${contract.schema_fields.join(', ')}`);
+  } else {
+    api.fail(`${file} skill contract schema parse failed`, '', 'Keep frontmatter and human-readable skill content available to the Stage 22 parser.');
+  }
+
+  if (contract.missing_required_markers.length === 0) {
+    api.ok(`${file} has runtime-readable handoff markers`);
+  } else {
+    api.fail(`${file} runtime contract markers missing`, `Missing marker(s): ${contract.missing_required_markers.join(', ')}`, `Add required Stage 22 marker(s): ${requiredMarkers.join(', ')}.`);
+  }
+
+  const name = skillNameFromPath(file);
+  if (text.includes(`current_skill: ${name}`) || text.includes('current_skill:')) {
+    api.ok(`${file} declares current_skill`);
+  } else {
+    api.fail(`${file} current_skill missing`, '', `Set current_skill to ${name} in Workflow Handoff.`);
+  }
+
+  if (text.includes('next_skill: none') || /next_skill:\s*vibe-[a-z-]+/.test(text)) {
+    api.ok(`${file} declares next_skill candidates`);
+  } else {
+    api.fail(`${file} next_skill candidates missing`, '', 'Declare at least one concrete next_skill or next_skill: none.');
+  }
+}
+
+function checkSkillGateContracts(root, api) {
+  for (const [file, markers] of Object.entries(skillGateContractDefinitions())) {
+    if (!api.exists(root, file)) {
+      api.fail(`${file} gate contract missing`, '', 'Restore the skill file so workflow gate markers can be checked.');
+      continue;
+    }
+
+    const text = api.readText(root, file);
+    const contract = parseSkillContractDocument(file, text);
+    if (contract.missing_gate_markers.length === 0) {
+      api.ok(`${file} declares machine-checkable gate contract`);
+    } else {
+      api.fail(`${file} gate contract markers missing`, `Missing marker(s): ${contract.missing_gate_markers.join(', ')}`, `Keep Stage 22 gate contract markers synchronized with runtime-skill-contract-schema: ${markers.join(', ')}.`);
+    }
+  }
+}
+
+function checkSkillContractSchemaDocumentation(root, api) {
+  const files = ['skills/using-vibecoding/SKILL.md', 'docs/workflow-chaining.md'];
+  const markers = skillContractSchemaDocumentationMarkers();
+  for (const file of files) {
+    if (!api.exists(root, file)) {
+      api.fail(`${file} skill contract schema documentation missing`, '', 'Document Stage 22 skill_contract_schema_v1 markers in the skill entry and workflow chaining guide.');
+      continue;
+    }
+    const text = api.readText(root, file);
+    const missing = markers.filter((marker) => !text.includes(marker));
+    if (missing.length === 0) {
+      api.ok(`${file} documents Stage 22 skill contract schema markers`);
+    } else {
+      api.fail(`${file} skill contract schema markers missing`, `Missing marker(s): ${missing.join(', ')}`, 'Keep entry skill docs and workflow chaining docs synchronized with runtime-skill-contract-schema.');
+    }
+  }
+}
+
+function checkWorkflowChaining(root, workflowSkills, api) {
+  const file = 'docs/workflow-chaining.md';
+  if (!api.exists(root, file)) return;
+
+  const text = api.readText(root, file);
+  const missing = workflowSkills
+    .map(skillNameFromPath)
+    .filter((skill) => !text.includes(skill));
+
+  if (missing.length === 0) {
+    api.ok(`${file} covers workflow skill markers`);
+  } else {
+    api.fail(`${file} workflow skill markers incomplete`, `Missing marker(s): ${missing.join(', ')}`, 'Document each workflow skill in workflow-chaining so runtime routing remains auditable.');
+  }
+
+  const boundaryMarkers = ['不做隐式自动跳转', '不依赖 MCP', '不调度多 agent'];
+  const missingBoundaries = boundaryMarkers.filter((marker) => !text.includes(marker));
+  if (missingBoundaries.length === 0) {
+    api.ok(`${file} preserves explicit workflow boundaries`);
+  } else {
+    api.warn(`${file} explicit boundary markers incomplete`, `Missing marker(s): ${missingBoundaries.join(', ')}`, 'Keep workflow-chaining clear that runtime does not silently execute next steps.');
+  }
+}
+
+export function checkWorkflowSkillContracts(root, workflowSkills, api) {
+  for (const file of workflowSkills) {
+    checkSkillContract(root, file, api);
+  }
+
+  checkSkillGateContracts(root, api);
+  checkSkillRouteRegistryDrift(root, workflowSkills, api);
+  checkSkillContractSchemaDocumentation(root, api);
+  checkWorkflowChaining(root, workflowSkills, api);
+}

package/tools/vibe-runtime-check/workflow-skill-route-registry-contracts.mjs

@@ -0,0 +1,106 @@
+import {
+  methodologyRouteDefinitions,
+} from '../vibe-runtime/runtime-methodology-route-model.mjs';
+import {
+  normalizeSkillRouteRegistryIntent,
+  skillRouteRegistryDefinitions,
+} from '../vibe-runtime/runtime-skill-route-registry.mjs';
+import { normalizeWorkflowReadinessIntent } from '../vibe-runtime/runtime-workflow-readiness-model.mjs';
+
+const routeRegistryDocumentationMarkers = [
+  'skill_route_registry_v1',
+  'route_registry_id',
+  'required_skill',
+  'next_gate',
+  'handoff_required',
+];
+
+function skillFile(skill) {
+  return `skills/${skill}/SKILL.md`;
+}
+
+function routeFieldChecks(route, entry) {
+  return [
+    ['required_skill', route.first_skill, entry.required_skill],
+    ['next_gate', route.next_gate, entry.next_gate],
+    ['stop_condition', route.stop_condition, entry.stop_condition],
+    ['handoff_required', route.handoff_required, entry.handoff_required],
+    ['workflow', route.workflow.join(' -> '), entry.selected_workflow.join(' -> ')],
+    ['gate_kinds', route.gate_kinds.join('|'), entry.gate_kinds.join('|')],
+  ];
+}
+
+function collectRegistryDrift(registry, routes, workflowSkillSet, root, api) {
+  const missingSkills = [];
+  const mismatchedRoutes = [];
+  const normalizationDrift = [];
+
+  for (const entry of registry) {
+    for (const skill of new Set([entry.required_skill, ...entry.selected_workflow].filter((item) => item !== 'none'))) {
+      const file = skillFile(skill);
+      if (!workflowSkillSet.has(file) || !api.exists(root, file)) missingSkills.push(`${entry.intent}:${skill}`);
+    }
+
+    const route = routes.find((item) => item.intent === entry.intent);
+    if (!route) {
+      mismatchedRoutes.push(`${entry.intent}:missing route`);
+    } else {
+      for (const [field, actual, expected] of routeFieldChecks(route, entry)) {
+        if (actual !== expected) mismatchedRoutes.push(`${entry.intent}.${field}`);
+      }
+    }
+
+    for (const alias of [entry.intent, ...entry.aliases]) {
+      if (normalizeSkillRouteRegistryIntent(alias) !== entry.intent) normalizationDrift.push(`${entry.intent}:${alias}:registry`);
+      if (normalizeWorkflowReadinessIntent(alias) !== entry.intent) normalizationDrift.push(`${entry.intent}:${alias}:readiness`);
+    }
+  }
+
+  return { missingSkills, mismatchedRoutes, normalizationDrift };
+}
+
+function collectDocumentationDrift(root, api) {
+  const usingText = api.exists(root, 'skills/using-vibecoding/SKILL.md') ? api.readText(root, 'skills/using-vibecoding/SKILL.md') : '';
+  const workflowChainingText = api.exists(root, 'docs/workflow-chaining.md') ? api.readText(root, 'docs/workflow-chaining.md') : '';
+  const templateFiles = ['templates/AGENTS.md', 'templates/CLAUDE.md', 'templates/VIBE-CODING.md'];
+  const missingUsingMarkers = routeRegistryDocumentationMarkers.filter((marker) => !usingText.includes(marker));
+  const missingDocMarkers = routeRegistryDocumentationMarkers.filter((marker) => !workflowChainingText.includes(marker));
+  const missingTemplateMarkers = templateFiles.flatMap((file) => {
+    if (!api.exists(root, file)) return [file];
+    const text = api.readText(root, file);
+    return ['skill_route_registry_v1'].filter((marker) => !text.includes(marker)).map((marker) => `${file}:${marker}`);
+  });
+  return { missingUsingMarkers, missingDocMarkers, missingTemplateMarkers };
+}
+
+export function checkSkillRouteRegistryDrift(root, workflowSkills, api) {
+  const registry = skillRouteRegistryDefinitions();
+  const routes = methodologyRouteDefinitions();
+  const workflowSkillSet = new Set(['skills/using-vibecoding/SKILL.md', ...workflowSkills]);
+  const { missingSkills, mismatchedRoutes, normalizationDrift } = collectRegistryDrift(registry, routes, workflowSkillSet, root, api);
+
+  if (missingSkills.length === 0) {
+    api.ok('skill route registry only references existing workflow skills', `routes=${registry.length}; skills=${workflowSkillSet.size}`);
+  } else {
+    api.fail('skill route registry references missing workflow skills', `Missing marker(s): ${missingSkills.join(', ')}`, 'Update the registry or restore the referenced skills.');
+  }
+
+  if (mismatchedRoutes.length === 0) {
+    api.ok('skill route registry and runtime route map stay synchronized', `routes=${routes.length}; registry=${registry.length}`);
+  } else {
+    api.fail('skill route registry and runtime route map drifted', `Mismatch(es): ${mismatchedRoutes.join(', ')}`, 'Derive runtime routes from the registry or update both together.');
+  }
+
+  if (normalizationDrift.length === 0) {
+    api.ok('skill route registry aliases match workflow readiness normalization', `aliases=${registry.reduce((count, entry) => count + entry.aliases.length + 1, 0)}`);
+  } else {
+    api.fail('skill route registry alias normalization drifted', `Mismatch(es): ${normalizationDrift.join(', ')}`, 'Keep using-vibecoding routing, methodology route aliases, and workflow readiness normalization aligned.');
+  }
+
+  const { missingUsingMarkers, missingDocMarkers, missingTemplateMarkers } = collectDocumentationDrift(root, api);
+  if (missingUsingMarkers.length === 0 && missingDocMarkers.length === 0 && missingTemplateMarkers.length === 0) {
+    api.ok('skill route registry markers are documented in using-vibecoding, workflow chaining, and templates');
+  } else {
+    api.fail('skill route registry documentation markers drifted', `Missing marker(s): ${[...missingUsingMarkers.map((marker) => `using:${marker}`), ...missingDocMarkers.map((marker) => `docs:${marker}`), ...missingTemplateMarkers].join(', ')}`, 'Keep the human-readable skill route table synchronized with runtime route registry markers.');
+  }
+}

package/tools/vibe-runtime-check/workflow-ux-contracts.mjs

@@ -0,0 +1,46 @@
+export function checkWorkflowUxContracts(_root, api, cliSurfaceText) {
+  const stage87Markers = ['workflow --cockpit', 'workflowCockpitEnvelope', 'workflowCockpitBoundaryAssertions', 'workflowCockpitSelfCheckSummary', "cockpit_kind: 'workflow-cockpit'", "mode: 'workflow-cockpit'", 'workflow_cockpit', 'self_check_summary', 'profile_check', 'entry_check', 'readiness_check', 'completion_check', 'evidence_gap_count', 'required_evidence_count', 'workflow_cockpit_artifact: false', 'command_execution: false', 'skill_execution: false', 'subagent: false', 'Stage 87'];
+  const missingStage87 = stage87Markers.filter((marker) => !cliSurfaceText.includes(marker));
+  if (missingStage87.length === 0) api.ok('tools/vibe-runtime/index.mjs supports Stage 87 workflow cockpit self-check boundaries');
+  else api.fail('tools/vibe-runtime/index.mjs Stage 87 markers incomplete', `Missing marker(s): ${missingStage87.join(', ')}`, 'Keep Stage 87 workflow cockpit self-check summary, evidence gap counts, digest output, and no workflow execution boundary synchronized.');
+
+  const stage90Markers = ['bootstrap --acceptance', 'bootstrapAcceptance', 'bootstrapAcceptanceEnvelope', 'bootstrapAcceptanceBoundaryAssertions', 'bootstrapPromptIntent', "acceptance_kind: 'workflow-bootstrap-acceptance'", "mode: 'workflow-bootstrap-acceptance'", 'bootstrap_acceptance', 'expected_first_skill', 'expected_behavior', 'observed_route_summary', 'acceptance_digest', 'bootstrap_acceptance_artifact: false', 'source_write: false', 'bootstrap --acceptance is read-only', 'Stage 90'];
+  const missingStage90 = stage90Markers.filter((marker) => !cliSurfaceText.includes(marker));
+  if (missingStage90.length === 0) api.ok('tools/vibe-runtime/index.mjs supports Stage 90 bootstrap acceptance boundaries');
+  else api.fail('tools/vibe-runtime/index.mjs Stage 90 markers incomplete', `Missing marker(s): ${missingStage90.join(', ')}`, 'Keep Stage 90 bootstrap acceptance command, deterministic route/advice reuse, digest output, and no source/subagent/state boundary synchronized.');
+
+  const stage91Markers = ['entry --contract', 'entryContractEnvelope', 'entryContractBoundaryAssertions', 'entryContractDecision', "contract_kind: 'workflow-entry-contract'", "mode: 'workflow-entry-contract'", 'entry_contract', 'expected_first_step', 'must_not_do_first', 'contract_digest', 'entry_contract_artifact: false', 'source_write: false', 'Stage 91'];
+  const missingStage91 = stage91Markers.filter((marker) => !cliSurfaceText.includes(marker));
+  if (missingStage91.length === 0) api.ok('tools/vibe-runtime/index.mjs supports Stage 91 entry contract boundaries');
+  else api.fail('tools/vibe-runtime/index.mjs Stage 91 markers incomplete', `Missing marker(s): ${missingStage91.join(', ')}`, 'Keep Stage 91 entry contract command, deterministic route/bootstrap reuse, digest output, and no source/subagent/state boundary synchronized.');
+
+  const stage92Markers = ['workflow --receipt', 'workflowReceiptEnvelope', 'workflowReceiptBoundaryAssertions', "receipt_kind: 'visible-skill-invocation'", "mode: 'visible-skill-invocation'", 'workflow_receipt', 'selected_skill', 'user_visible_sentence', 'false_claim_guardrails', 'receipt_digest', 'workflow_receipt_artifact: false', 'Stage 92'];
+  const missingStage92 = stage92Markers.filter((marker) => !cliSurfaceText.includes(marker));
+  if (missingStage92.length === 0) api.ok('tools/vibe-runtime/index.mjs supports Stage 92 visible skill receipt boundaries');
+  else api.fail('tools/vibe-runtime/index.mjs Stage 92 markers incomplete', `Missing marker(s): ${missingStage92.join(', ')}`, 'Keep Stage 92 visible skill receipt command, false-claim guardrails, digest output, and no execution boundary synchronized.');
+
+  const stage93Markers = ['workflow --start', 'workflowStartEnvelope', 'workflowStartBoundaryAssertions', 'buildWorkflowDisciplineSummary', 'runtime-agent-session-start-contract', 'agent-session-start-behavior-contract', "start_kind: 'unified-workflow-start'", "mode: 'unified-workflow-start'", 'workflow_start', 'entry_contract_summary', 'receipt_summary', 'cockpit_summary', 'readiness_summary', 'entry_summary', 'workflow_discipline_summary', 'start_here_contract', 'agent_session_start_contract', 'profile_source', 'discipline_kind', 'workflow-entry-discipline-summary', 'context_policy', 'tiny_context', 'full_skill_injection', 'visible_claims', 'skill_execution_claimed', 'workflow_execution_claimed', 'command_execution_claimed', 'subagent_dispatch_claimed', 'git_write_claimed', 'start_digest', 'workflow_start_artifact: false', 'command_execution: false', 'skill_execution: false', 'subagent: false', 'git_write', 'business_source_write', 'Stage 93'];
+  const missingStage93 = stage93Markers.filter((marker) => !cliSurfaceText.includes(marker));
+  if (missingStage93.length === 0) api.ok('tools/vibe-runtime/index.mjs supports Stage 93 unified workflow start boundaries');
+  else api.fail('tools/vibe-runtime/index.mjs Stage 93 markers incomplete', `Missing marker(s): ${missingStage93.join(', ')}`, 'Keep Stage 93 workflow start command, deterministic envelope aggregation, digest output, and no subcommand execution boundary synchronized.');
+
+  const stage16Markers = ['session --start', 'skill --select', 'runSessionCommand', 'runSkillCommand', 'runtime-session-skill-command', 'sessionStart', 'skillSelect', "mode: 'agent-session-start-alias'", "mode: 'skill-select-alias'", 'session_start_alias', 'skill_select_alias', 'canonical_command', 'workflow --start', 'workflow --receipt', 'skill_execution_claimed', 'workflow_execution_claimed', 'command_execution_claimed', 'subagent_dispatch_claimed', 'git_write_claimed', 'writes: false', 'state_directory_created: false', 'Stage 16'];
+  const missingStage16 = stage16Markers.filter((marker) => !cliSurfaceText.includes(marker));
+  if (missingStage16.length === 0) api.ok('tools/vibe-runtime/index.mjs supports Stage 16 session and skill alias boundaries');
+  else api.fail('tools/vibe-runtime/index.mjs Stage 16 alias markers incomplete', `Missing marker(s): ${missingStage16.join(', ')}`, 'Keep Stage 16 session --start and skill --select aliases synchronized with workflow start/receipt, no-claim fields, digest output, and no execution/write boundary.');
+
+  const stage20Markers = ['session --close', 'sessionClose', 'session-close-evidence-alias', 'session_close_alias', 'completionEvidenceBundleEnvelope', 'printSessionClose', 'completion --evidence-bundle', 'completion_evidence_bundle', 'human_completion_evidence_bundle', 'closeout_decision', 'completion_claim_allowed', 'next_manual_action', 'session_close_alias_artifact=false', 'command_execution=false', 'skill_execution=false', 'workflow_execution=false', 'git_write=false', 'business_source_write=false', 'Stage 20'];
+  const missingStage20 = stage20Markers.filter((marker) => !cliSurfaceText.includes(marker));
+  if (missingStage20.length === 0) api.ok('tools/vibe-runtime/index.mjs supports Stage 20 session close evidence alias boundaries');
+  else api.fail('tools/vibe-runtime/index.mjs Stage 20 session close markers incomplete', `Missing marker(s): ${missingStage20.join(', ')}`, 'Keep Stage 20 session --close alias synchronized with completion --evidence-bundle, one-screen human closeout evidence, digest bindings, and no execution/write/git/subagent boundary.');
+
+  const stage94Markers = ['workflow --sequence', 'workflowSequenceEnvelope', 'workflowSequenceBoundaryAssertions', 'workflowSequenceDefinition', "sequence_kind: 'execution-choreography'", "mode: 'execution-choreography'", 'workflow_sequence', 'phase_order', 'phase_entry_criteria', 'phase_exit_evidence', 'handoff_points', 'stop_conditions', 'sequence_digest', 'workflow_sequence_artifact: false', 'Stage 94'];
+  const missingStage94 = stage94Markers.filter((marker) => !cliSurfaceText.includes(marker));
+  if (missingStage94.length === 0) api.ok('tools/vibe-runtime/index.mjs supports Stage 94 workflow sequence boundaries');
+  else api.fail('tools/vibe-runtime/index.mjs Stage 94 markers incomplete', `Missing marker(s): ${missingStage94.join(', ')}`, 'Keep Stage 94 workflow choreography command, phase evidence, digest output, and no execution boundary synchronized.');
+
+  const stage95Markers = ['onboarding --brief', 'onboardingBriefEnvelope', 'onboardingBriefBoundaryAssertions', "brief_kind: 'workflow-onboarding-brief'", "mode: 'workflow-onboarding-brief'", 'onboarding_brief', 'recommended_start_command', 'brief_digest', 'onboarding_brief_artifact: false', 'Stage 95'];
+  const missingStage95 = stage95Markers.filter((marker) => !cliSurfaceText.includes(marker));
+  if (missingStage95.length === 0) api.ok('tools/vibe-runtime/index.mjs supports Stage 95 onboarding brief boundaries');
+  else api.fail('tools/vibe-runtime/index.mjs Stage 95 markers incomplete', `Missing marker(s): ${missingStage95.join(', ')}`, 'Keep Stage 95 onboarding brief command, start-here summary, digest output, and no state/source boundary synchronized.');
+}