@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-skill-contract-schema.mjs

@@ -0,0 +1,221 @@
+const SKILL_CONTRACT_SCHEMA_VERSION = 1;
+const SKILL_CONTRACT_SCHEMA_STAGE = 'Stage 22';
+const SKILL_CONTRACT_SCHEMA_KIND = 'skill-contract-schema';
+
+const SKILL_CONTRACT_SCHEMA_FIELDS = Object.freeze([
+  'entry_conditions',
+  'required_inputs',
+  'required_outputs',
+  'stop_conditions',
+  'handoff_contract',
+  'evidence_required_before_claiming_done',
+  'forbidden_claims',
+]);
+
+const WORKFLOW_HANDOFF_MARKERS = Object.freeze([
+  '## 下一步调用',
+  '## Workflow Handoff',
+  'current_skill:',
+  'next_skill:',
+  'handoff:',
+  'stop_condition:',
+]);
+
+const USING_VIBECODING_ENTRY_MARKERS = Object.freeze([
+  '## Bootstrap contract / Start Here Contract',
+  'expected_first_skill: `using-vibecoding`',
+  'route gate:',
+  'stop conditions:',
+  'false claim guard:',
+  'safety boundary:',
+]);
+
+const SKILL_GATE_CONTRACTS = Object.freeze({
+  'skills/using-vibecoding/SKILL.md': Object.freeze([
+    'gate_kind: router_gate',
+    'must_not_skip: legacy-workflow-discipline-only',
+    'approval_required_before: subagent | source_write | git | platform_api',
+    'terminal_next_skill: selected_route | none',
+    'review_blocker_stops_next_task: true',
+    'completion_requires_evidence: true',
+    'one_percent_skill_rule: legacy-workflow-discipline-only',
+    'default_profile_full_workflow_required: false',
+  ]),
+  'skills/vibe-brainstorming/SKILL.md': Object.freeze([
+    'gate_kind: design_gate',
+    'must_not_skip: when_goal_scope_or_acceptance_unclear',
+    'approval_required_before: implementation',
+    'terminal_next_skill: vibe-planning | vibe-implementation | none',
+    'review_blocker_stops_next_task: false',
+    'completion_requires_evidence: false',
+  ]),
+  'skills/vibe-writing-plans/SKILL.md': Object.freeze([
+    'gate_kind: plan_gate',
+    'must_not_skip: when_work_needs_executable_tasks',
+    'approval_required_before: implementation',
+    'terminal_next_skill: vibe-workspace-isolation | vibe-dispatching-parallel-work | vibe-test-driven-development | vibe-planning | none',
+    'review_blocker_stops_next_task: false',
+    'completion_requires_evidence: false',
+  ]),
+  'skills/vibe-test-driven-development/SKILL.md': Object.freeze([
+    'gate_kind: verification_strategy_gate',
+    'must_not_skip: before_behavior_change_without_validation_strategy',
+    'approval_required_before: implementation',
+    'terminal_next_skill: vibe-executing-plans | vibe-implementation | vibe-planning | none',
+    'review_blocker_stops_next_task: false',
+    'completion_requires_evidence: true',
+  ]),
+  'skills/vibe-subagent-driven-development/SKILL.md': Object.freeze([
+    'gate_kind: subagent_review_gate',
+    'must_not_skip: when_subagent_or_parallel_execution_is_requested',
+    'approval_required_before: subagent_execution',
+    'terminal_next_skill: vibe-verification-before-completion | vibe-dispatching-parallel-work | vibe-writing-plans | vibe-workspace-isolation | vibe-test-driven-development | vibe-executing-plans | vibe-receiving-code-review | vibe-systematic-debugging | none',
+    'review_blocker_stops_next_task: true',
+    'completion_requires_evidence: true',
+    'Progress Ledger Discipline',
+    'review 出现 Critical / Important 阻塞时，不进入下一任务',
+  ]),
+  'skills/vibe-verification-before-completion/SKILL.md': Object.freeze([
+    'gate_kind: completion_evidence_gate',
+    'must_not_skip: before_claiming_complete_or_ready',
+    'approval_required_before: completion_claim',
+    'terminal_next_skill: vibe-finishing-a-development-branch | vibe-verification | vibe-systematic-debugging | vibe-implementation | vibe-planning | none',
+    'review_blocker_stops_next_task: true',
+    'completion_requires_evidence: true',
+  ]),
+  'skills/vibe-finishing-a-development-branch/SKILL.md': Object.freeze([
+    'gate_kind: branch_closeout_gate',
+    'must_not_skip: before_commit_pr_merge_or_branch_closeout',
+    'approval_required_before: git_write | push | pr | merge | destructive_cleanup',
+    'terminal_next_skill: none',
+    'review_blocker_stops_next_task: true',
+    'completion_requires_evidence: true',
+  ]),
+});
+
+function skillNameFromPath(file) {
+  return String(file || '').split('/')[1] || '';
+}
+
+function parseFrontmatter(text) {
+  const source = String(text || '');
+  if (!source.startsWith('---\n') && !source.startsWith('---\r\n')) return {};
+  const end = source.indexOf('\n---', 4);
+  if (end === -1) return {};
+  return source
+    .slice(4, end)
+    .split(/\r?\n/)
+    .reduce((frontmatter, line) => {
+      const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+      if (match) frontmatter[match[1]] = match[2];
+      return frontmatter;
+    }, {});
+}
+
+function markerPresence(text, markers) {
+  return markers.map((marker) => ({ marker, present: String(text || '').includes(marker) }));
+}
+
+export function workflowSkillContractRequiredMarkers(file) {
+  return file === 'skills/using-vibecoding/SKILL.md'
+    ? [...USING_VIBECODING_ENTRY_MARKERS]
+    : [...WORKFLOW_HANDOFF_MARKERS];
+}
+
+export function skillContractSchemaDocumentationMarkers() {
+  return ['skill_contract_schema_v1', ...SKILL_CONTRACT_SCHEMA_FIELDS];
+}
+
+export function skillGateContractDefinitions() {
+  return Object.fromEntries(Object.entries(SKILL_GATE_CONTRACTS).map(([file, markers]) => [file, [...markers]]));
+}
+
+export function trackedSkillGateContractFiles() {
+  return Object.keys(SKILL_GATE_CONTRACTS);
+}
+
+export function parseSkillContractDocument(file, text) {
+  const frontmatter = parseFrontmatter(text);
+  const requiredMarkers = workflowSkillContractRequiredMarkers(file);
+  const gateMarkers = SKILL_GATE_CONTRACTS[file] || [];
+  const name = frontmatter.name || skillNameFromPath(file);
+  const markerReport = markerPresence(text, requiredMarkers);
+  const gateMarkerReport = markerPresence(text, gateMarkers);
+  const handoffMarkerReport = markerPresence(text, WORKFLOW_HANDOFF_MARKERS);
+  const missing_required_markers = markerReport.filter((item) => !item.present).map((item) => item.marker);
+  const missing_gate_markers = gateMarkerReport.filter((item) => !item.present).map((item) => item.marker);
+
+  return {
+    stage: SKILL_CONTRACT_SCHEMA_STAGE,
+    schema_version: SKILL_CONTRACT_SCHEMA_VERSION,
+    schema_kind: SKILL_CONTRACT_SCHEMA_KIND,
+    file,
+    name,
+    frontmatter,
+    is_entry_skill: file === 'skills/using-vibecoding/SKILL.md',
+    tracked_gate_contract: gateMarkers.length > 0,
+    schema_fields: [...SKILL_CONTRACT_SCHEMA_FIELDS],
+    entry_conditions: { markers: markerReport },
+    required_inputs: { frontmatter_name: Boolean(frontmatter.name), skill_path: file },
+    required_outputs: { has_handoff_block: String(text || '').includes('## Workflow Handoff') },
+    stop_conditions: { markers: markerPresence(text, ['stop_condition:', 'stop conditions:']) },
+    handoff_contract: { markers: handoffMarkerReport },
+    evidence_required_before_claiming_done: { markers: markerPresence(text, ['completion_requires_evidence:', 'completion_requires_evidence: true']) },
+    forbidden_claims: { markers: markerPresence(text, ['approval_required_before:', 'safety boundary:', 'forbidden']) },
+    missing_required_markers,
+    missing_gate_markers,
+    parsed: Boolean(name && String(text || '').trim()),
+  };
+}
+
+export function skillContractSchemaBoundaryAssertions() {
+  return {
+    writes: false,
+    state_directory_created: false,
+    skill_contract_schema_artifact: false,
+    workflow_skill_execution: false,
+    skill_execution: false,
+    command_execution: false,
+    runtime_action: false,
+    auto_execution: false,
+    source_write: false,
+    business_source_write: false,
+    git: false,
+    worktree: false,
+    pr: false,
+    push: false,
+    merge: false,
+    platform_api: false,
+    external_network: false,
+    model_invocation: false,
+    subagent: false,
+    mcp: false,
+    daemon: false,
+  };
+}
+
+export function skillContractSchemaSnapshot(digestObject = (value) => JSON.stringify(value)) {
+  const snapshot = {
+    stage: SKILL_CONTRACT_SCHEMA_STAGE,
+    version: SKILL_CONTRACT_SCHEMA_VERSION,
+    schema_kind: SKILL_CONTRACT_SCHEMA_KIND,
+    owner_module: 'runtime-skill-contract-schema',
+    fields: [...SKILL_CONTRACT_SCHEMA_FIELDS],
+    workflow_handoff_markers: [...WORKFLOW_HANDOFF_MARKERS],
+    using_vibecoding_entry_markers: [...USING_VIBECODING_ENTRY_MARKERS],
+    tracked_gate_contracts: skillGateContractDefinitions(),
+    boundary_assertions: skillContractSchemaBoundaryAssertions(),
+    writes: false,
+    state_directory_created: false,
+    local_only: true,
+    deterministic: true,
+  };
+  return { ...snapshot, skill_contract_schema_digest: digestObject(snapshot) };
+}
+
+export {
+  SKILL_CONTRACT_SCHEMA_FIELDS,
+  SKILL_CONTRACT_SCHEMA_KIND,
+  SKILL_CONTRACT_SCHEMA_STAGE,
+  SKILL_CONTRACT_SCHEMA_VERSION,
+};

package/tools/vibe-runtime/runtime-skill-route-registry.mjs

@@ -0,0 +1,47 @@
+const SKILL_ROUTE_REGISTRY_VERSION = 1;
+const SKILL_ROUTE_REGISTRY_STAGE = 'Stage 21';
+const SKILL_ROUTE_REGISTRY_KIND = 'skill-route-registry-drift-guard';
+
+function routeRegistryEntry(intent, aliases, workflow, gateKinds, rationale, stopCondition, nextGate = '', handoffRequired = true) {
+  return { route_registry_id: `skill-route:${intent}`, intent, aliases, required_skill: workflow[0] || 'using-vibecoding', next_gate: nextGate || gateKinds[0] || 'manual_workflow_judgment', stop_condition: stopCondition, handoff_required: handoffRequired, selected_workflow: workflow, gate_kinds: gateKinds, rationale };
+}
+
+export function skillRouteRegistryDefinitions() {
+  return [
+    routeRegistryEntry('feature', ['new-feature', 'new_feature', '需求', '功能'], ['vibe-brainstorming', 'vibe-planning', 'vibe-writing-plans', 'vibe-test-driven-development', 'vibe-executing-plans', 'vibe-verification-before-completion', 'vibe-finishing-a-development-branch'], ['spec', 'plan', 'tdd', 'completion'], 'new functionality needs intent shaping, planning, verification strategy, execution, and completion evidence', 'stop when goal, scope, acceptance, or validation strategy is missing', 'spec'),
+    routeRegistryEntry('refactor', ['restructure', '重构'], ['vibe-brainstorming', 'vibe-planning', 'vibe-writing-plans', 'vibe-test-driven-development', 'vibe-executing-plans', 'vibe-verification-before-completion', 'vibe-finishing-a-development-branch'], ['spec', 'plan', 'tdd', 'completion'], 'refactoring needs module boundary and data-flow review before implementation', 'stop when module ownership, dependency direction, data flow, or validation strategy is unclear', 'spec'),
+    routeRegistryEntry('architecture', ['design', '架构'], ['vibe-brainstorming', 'vibe-planning', 'vibe-writing-plans', 'vibe-test-driven-development', 'vibe-executing-plans', 'vibe-verification-before-completion', 'vibe-finishing-a-development-branch'], ['spec', 'plan', 'tdd', 'completion'], 'architecture work needs tradeoff analysis and explicit handoff before code changes', 'stop when owner, layer, dependency direction, data flow, state lifecycle, or contract sync is unclear', 'spec'),
+    routeRegistryEntry('plan', ['planning', '方案', '计划'], ['vibe-writing-plans', 'vibe-test-driven-development', 'vibe-executing-plans'], ['plan', 'tdd'], 'existing requirements should be converted into file/task/verification plan before execution', 'stop when target files, task sequence, risks, or verification commands are missing', 'plan'),
+    routeRegistryEntry('parallel', ['dispatching-parallel-work', 'parallel-work', '并行'], ['vibe-writing-plans', 'vibe-dispatching-parallel-work', 'vibe-test-driven-development'], ['plan', 'tdd'], 'parallel candidates require dependency and isolation boundaries before any dispatch decision', 'stop when task independence, ownership, acceptance, or user permission is missing', 'plan'),
+    routeRegistryEntry('workspace', ['workspace-isolation', 'isolation', 'worktree', '隔离'], ['vibe-workspace-isolation', 'vibe-writing-plans', 'vibe-test-driven-development', 'vibe-finishing-a-development-branch'], ['plan', 'tdd', 'completion'], 'large or risky work needs workspace boundary judgment before modification', 'stop when current worktree status, isolation need, or cleanup path is unclear', 'plan'),
+    routeRegistryEntry('subagent', ['agent', 'subagents', '代理'], ['vibe-subagent-driven-development', 'vibe-verification-before-completion', 'vibe-executing-plans'], ['automation', 'completion'], 'subagent work requires explicit user permission, eligibility, review gate, and fallback boundaries', 'stop when user permission, brief completeness, task boundaries, or review gate is missing', 'automation'),
+    routeRegistryEntry('debug', ['bug', 'failure', 'error', '异常', '失败'], ['vibe-systematic-debugging', 'vibe-test-driven-development', 'vibe-implementation', 'vibe-verification-before-completion'], ['debug', 'tdd', 'completion'], 'bugs and failures require reproduction and root-cause evidence before fixing', 'stop when reproduction, observed evidence, or root-cause hypothesis is missing', 'debug'),
+    routeRegistryEntry('implementation', ['small-task', 'implement', '明确小任务', '执行', '实现'], ['vibe-test-driven-development', 'vibe-implementation', 'vibe-verification-before-completion'], ['tdd', 'completion'], 'clear implementation work still needs a verification strategy before code changes', 'stop when validation strategy, accepted scope, or changed-file boundary is missing', 'tdd'),
+    routeRegistryEntry('review', ['code-review', 'pre-merge', '审查'], ['vibe-requesting-code-review', 'vibe-review'], ['review'], 'review work should declare target, scope, evidence, and high-risk focus before findings', 'stop when review scope, diff/evidence, severity criteria, or required-change policy is missing', 'review'),
+    routeRegistryEntry('review-feedback', ['feedback', 'review-fix', '处理反馈'], ['vibe-receiving-code-review'], ['review'], 'review feedback must be understood and verified before repair', 'stop when feedback source, required change, or verification path is unclear', 'review'),
+    routeRegistryEntry('skill', ['workflow-skill', 'skill-authoring', '技能'], ['vibe-writing-skills', 'vibe-writing-plans', 'vibe-test-driven-development'], ['spec', 'plan', 'tdd'], 'workflow skill changes need boundary, handoff, sync checklist, and behavior verification', 'stop when trigger, boundary, handoff, or drift-check sync list is missing', 'spec'),
+    routeRegistryEntry('context', ['compact', 'handoff', '上下文'], ['vibe-context-compact'], [], 'long context or handoff work should compact state instead of continuing with hidden assumptions', 'stop when current state, next action, evidence, or unresolved risks are unclear', 'manual_workflow_judgment'),
+    routeRegistryEntry('completion', ['finish', 'verify', 'closeout', '收口', '完成'], ['vibe-verification-before-completion', 'vibe-finishing-a-development-branch'], ['completion'], 'completion claims require fresh verification evidence and git boundary awareness', 'stop when validation summary, evidence gaps, or explicit user gate for git/release action is missing', 'completion'),
+  ];
+}
+
+export function skillRouteRegistryBoundaryAssertions() {
+  return { writes: false, state_directory_created: false, skill_route_registry_artifact: false, workflow_skill_execution: false, skill_execution: false, command_execution: false, runtime_action: false, auto_execution: false, source_write: false, business_source_write: false, git: false, worktree: false, pr: false, push: false, merge: false, platform_api: false, external_network: false, model_invocation: false, subagent: false, mcp: false, daemon: false };
+}
+
+export function skillRouteRegistrySnapshot(digestObject) {
+  const registry = { stage: SKILL_ROUTE_REGISTRY_STAGE, version: SKILL_ROUTE_REGISTRY_VERSION, registry_kind: SKILL_ROUTE_REGISTRY_KIND, source: 'runtime-skill-route-registry', drift_guard: true, docs_sync_required: true, using_vibecoding_sync_required: true, runtime_route_map_sync_required: true, template_sync_required: true, entries: skillRouteRegistryDefinitions(), boundary_assertions: skillRouteRegistryBoundaryAssertions(), writes: false, state_directory_created: false, local_only: true, deterministic: true };
+  return { ...registry, route_registry_digest: digestObject(registry) };
+}
+
+export function skillRouteRegistryIntents() {
+  return skillRouteRegistryDefinitions().map((entry) => entry.intent);
+}
+
+export function normalizeSkillRouteRegistryIntent(intent) {
+  const normalized = String(intent || '').trim().toLowerCase().replace(/_/g, '-');
+  const match = skillRouteRegistryDefinitions().find((entry) => entry.intent === normalized || entry.aliases.includes(normalized));
+  return match ? match.intent : normalized || 'unknown';
+}
+
+export { SKILL_ROUTE_REGISTRY_VERSION, SKILL_ROUTE_REGISTRY_STAGE, SKILL_ROUTE_REGISTRY_KIND };

package/tools/vibe-runtime/runtime-skill-runtime-traceability-map.mjs

@@ -0,0 +1,268 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const traceabilityStage = 'Stage 123';
+const traceabilityKind = 'skill-to-runtime-traceability-map';
+
+const expectedSkillRuntimeLinks = [
+  { skill: 'using-vibecoding', runtime_group: 'workflow', runtime_commands: ['workflow --start', 'entry --contract', 'workflow --receipt', 'methodology --route'], contract: 'lightweight entry routing and visible workflow receipt' },
+  { skill: 'vibe-brainstorming', runtime_group: 'methodology', runtime_commands: ['methodology --route', 'methodology --readiness'], contract: 'clarify unclear goals before implementation' },
+  { skill: 'vibe-product-discovery', runtime_group: 'completion', runtime_commands: ['completion --evidence-bundle'], contract: 'bind product discovery artifact into completion evidence without executing workflow skills' },
+  { skill: 'vibe-product-spec', runtime_group: 'completion', runtime_commands: ['completion --evidence-bundle'], contract: 'bind product spec requirements into requirements chain and completion readiness' },
+  { skill: 'vibe-ui-design', runtime_group: 'completion', runtime_commands: ['completion --evidence-bundle'], contract: 'bind UI design contract into UI readiness and scenario evidence chain' },
+  { skill: 'vibe-product-acceptance', runtime_group: 'completion', runtime_commands: ['completion --evidence-bundle'], contract: 'bind product acceptance artifact into final product readiness evidence' },
+  { skill: 'vibe-planning', runtime_group: 'methodology', runtime_commands: ['methodology --route', 'planner --lint'], contract: 'architecture and data-flow planning before execution' },
+  { skill: 'vibe-writing-plans', runtime_group: 'planner', runtime_commands: ['planner --executable-plan', 'planner --action-manifest'], contract: 'convert plans into exact files, outputs, gates, and local action manifests' },
+  { skill: 'vibe-test-driven-development', runtime_group: 'verification', runtime_commands: ['verification --tdd-trace', 'verification --self-test-profile'], contract: 'bind RED-GREEN-REFACTOR and self-test expectations without running checks' },
+  { skill: 'vibe-executing-plans', runtime_group: 'automation', runtime_commands: ['automation --stage-runbook', 'automation --one-shot-plan'], contract: 'execute accepted plans one stage at a time while runtime only emits control-plane contracts' },
+  { skill: 'vibe-verification-before-completion', runtime_group: 'verification', runtime_commands: ['verification --evidence-intake', 'verification --execution-evidence', 'release --diff-coverage'], contract: 'require completion evidence before claiming done' },
+  { skill: 'vibe-finishing-a-development-branch', runtime_group: 'release', runtime_commands: ['release --staged-commit-readiness', 'release --commit-readiness', 'release --commit-guard', 'completion --evidence-bundle'], contract: 'gate final handoff and manual commit readiness' },
+  { skill: 'vibe-implementation', runtime_group: 'verification', runtime_commands: ['verification --self-test-profile', 'verification --evidence-intake'], contract: 'implementation remains evidence-backed and bounded by verification' },
+  { skill: 'vibe-debugging', runtime_group: 'verification', runtime_commands: ['verification --evidence-intake', 'verification --tdd-trace'], contract: 'debugging requires observed failure evidence before repair' },
+  { skill: 'vibe-systematic-debugging', runtime_group: 'verification', runtime_commands: ['verification --evidence-intake', 'verification --tdd-trace'], contract: 'systematic failure isolation and evidence-backed fixes' },
+  { skill: 'vibe-requesting-code-review', runtime_group: 'review', runtime_commands: ['review --intake', 'governance --pr-review-intake'], contract: 'prepare scoped review evidence without invoking reviewers automatically' },
+  { skill: 'vibe-review', runtime_group: 'review', runtime_commands: ['review --intake', 'review --resolution'], contract: 'produce blocking/high-risk review findings from local evidence' },
+  { skill: 'vibe-receiving-code-review', runtime_group: 'review', runtime_commands: ['review --resolution', 'verification --evidence-intake'], contract: 'triage review feedback and verify accepted fixes' },
+  { skill: 'vibe-workspace-isolation', runtime_group: 'governance', runtime_commands: ['governance --surface', 'automation --readiness'], contract: 'check workspace and automation boundaries before risky work' },
+  { skill: 'vibe-dispatching-parallel-work', runtime_group: 'automation', runtime_commands: ['automation --readiness', 'automation --stage-runbook'], contract: 'plan parallel boundaries without spawning subagents automatically' },
+  { skill: 'vibe-subagent-driven-development', runtime_group: 'platforms', runtime_commands: ['platforms --catalog', 'platforms --probe', 'automation --readiness'], contract: 'subagent work remains explicit, permissioned, and platform-boundary aware' },
+  { skill: 'vibe-writing-skills', runtime_group: 'governance', runtime_commands: ['governance --traceability-map', 'governance --surface --drift-guard'], contract: 'skill design stays synchronized with runtime contracts and drift guards' },
+  { skill: 'vibe-context-compact', runtime_group: 'tokens', runtime_commands: ['tokens --compact-output', 'tokens --metrics', 'tokens --advice'], contract: 'context handoff and compaction remain digest-bound and local' },
+  { skill: 'vibe-verification', runtime_group: 'verification', runtime_commands: ['verification --self-test-profile', 'verification --evidence-intake'], contract: 'legacy verification route remains covered by current evidence contracts' },
+];
+
+export function runtimeSkillRuntimeTraceabilityMap(root, registry) {
+  const skillRows = listSkillRows(root);
+  const registryCommands = new Set(registry.capability_groups.flatMap((group) => group.commands));
+  const registryGroups = new Set(registry.capability_groups.map((group) => group.group));
+  const linkRows = expectedSkillRuntimeLinks.map((link) => skillRuntimeTraceabilityRow(root, link, skillRows, registryCommands, registryGroups));
+  const gateResults = skillRuntimeTraceabilityGateResults(skillRows, linkRows, registryCommands, registryGroups);
+  const boundaryAssertions = runtimeSkillRuntimeTraceabilityBoundaryAssertions();
+  const mapCore = {
+    version: 1,
+    stage: traceabilityStage,
+    map_kind: traceabilityKind,
+    source: 'local-skill-files-and-runtime-capability-registry',
+    expected_skills: expectedSkillRuntimeLinks.map((link) => link.skill).sort(),
+    skill_rows: skillRows,
+    traceability_rows: linkRows,
+    gate_results: gateResults,
+    blockers: gateResults.filter((gate) => !gate.pass).flatMap((gate) => gate.findings.map((finding) => `${gate.gate}: ${finding}`)),
+    digest_inputs: {
+      registry_version: registry.registry_version,
+      registry_digest: digestSkillRuntimeTraceability(registry),
+      skill_digests: skillRows.map((row) => ({ skill: row.skill, skill_digest: row.skill_digest })),
+      expected_link_digest: digestSkillRuntimeTraceability(expectedSkillRuntimeLinks),
+    },
+    boundary_assertions: boundaryAssertions,
+    writes: false,
+    state_directory_created: false,
+    local_only: true,
+    deterministic: true,
+  };
+  const invariants = runtimeSkillRuntimeTraceabilityInvariants(mapCore);
+  const map = {
+    ...mapCore,
+    ok: mapCore.blockers.length === 0 && invariants.pass,
+    skill_runtime_traceability_invariants: invariants,
+  };
+  return {
+    ...map,
+    traceability_digest: digestSkillRuntimeTraceability(runtimeSkillRuntimeTraceabilityDigestPayload(map)),
+    manual_action: map.ok
+      ? 'Skill-to-runtime traceability passed. Keep workflow skill triggers, handoff markers, and runtime registry commands synchronized before changing either side.'
+      : 'Fix the listed skill/runtime traceability blockers before claiming workflow/runtime parity or superiority.',
+  };
+}
+
+export function runtimeSkillRuntimeTraceabilityDigestPayload(map) {
+  return {
+    stage: map.stage,
+    map_kind: map.map_kind,
+    source: map.source,
+    expected_skills: map.expected_skills,
+    skill_rows: map.skill_rows,
+    traceability_rows: map.traceability_rows,
+    gate_results: map.gate_results,
+    blockers: map.blockers,
+    digest_inputs: map.digest_inputs,
+    boundary_assertions: map.boundary_assertions,
+    skill_runtime_traceability_invariants: map.skill_runtime_traceability_invariants,
+  };
+}
+
+export function runtimeSkillRuntimeTraceabilityBoundaryAssertions() {
+  return {
+    traceability_map_artifact: false,
+    skill_write: false,
+    runtime_registry_write: false,
+    docs_write: false,
+    sidecar_write: false,
+    state_directory_created: false,
+    command_execution: false,
+    check_execution: false,
+    test_execution: false,
+    runtime_action: false,
+    workflow_execution: false,
+    skill_execution: false,
+    auto_execution: false,
+    platform_api: false,
+    external_network: false,
+    model_invocation: false,
+    subagent: false,
+    mcp: false,
+    daemon: false,
+    git: false,
+    git_write: false,
+    worktree: false,
+    business_source_write: false,
+  };
+}
+
+export function runtimeSkillRuntimeTraceabilityInvariants(map) {
+  const findings = [];
+  const skills = map.skill_rows.map((row) => row.skill);
+  const linkedSkills = map.traceability_rows.map((row) => row.skill);
+  const expectedSkills = map.expected_skills || [];
+  const duplicateSkills = skills.filter((skill, index, items) => items.indexOf(skill) !== index);
+  const missingSkillRows = expectedSkills.filter((skill) => !skills.includes(skill));
+  const unmappedSkills = skills.filter((skill) => !linkedSkills.includes(skill));
+  const missingMappedSkills = linkedSkills.filter((skill) => !skills.includes(skill));
+  findings.push(...duplicateSkills.map((skill) => `duplicate skill row: ${skill}`));
+  findings.push(...missingSkillRows.map((skill) => `missing expected skill row: ${skill}`));
+  findings.push(...unmappedSkills.map((skill) => `skill missing traceability link: ${skill}`));
+  findings.push(...missingMappedSkills.map((skill) => `traceability link references missing skill: ${skill}`));
+
+  for (const row of map.skill_rows) {
+    if (row.frontmatter_name !== row.skill) findings.push(`${row.skill}: frontmatter name must equal directory skill name`);
+    if (!row.handoff_markers.current_skill) findings.push(`${row.skill}: current_skill marker missing`);
+    if (!row.handoff_markers.next_skill) findings.push(`${row.skill}: next_skill marker missing`);
+    if (!row.handoff_markers.handoff) findings.push(`${row.skill}: handoff marker missing`);
+    if (!row.handoff_markers.stop_condition) findings.push(`${row.skill}: stop_condition marker missing`);
+  }
+
+  for (const row of map.traceability_rows) {
+    if (row.stage !== traceabilityStage) findings.push(`${row.skill}: row stage must be ${traceabilityStage}`);
+    if (!row.skill_exists) findings.push(`${row.skill}: skill file missing`);
+    if (!row.runtime_group_exists) findings.push(`${row.skill}: runtime group missing: ${row.runtime_group}`);
+    findings.push(...row.missing_runtime_commands.map((command) => `${row.skill}: runtime command missing from registry: ${command}`));
+    if (!row.pass) findings.push(...row.blockers.map((blocker) => `${row.skill}: ${blocker}`));
+  }
+
+  const unsafeBoundaries = Object.entries(map.boundary_assertions || {})
+    .filter(([, value]) => value !== false)
+    .map(([key]) => key);
+  findings.push(...unsafeBoundaries.map((key) => `boundary assertion must remain false: ${key}`));
+
+  return {
+    pass: findings.length === 0,
+    checked: [
+      'skill_row_coverage',
+      'frontmatter_name_consistency',
+      'workflow_handoff_markers',
+      'runtime_group_registry_links',
+      'runtime_command_registry_links',
+      'read_only_boundary_assertions',
+    ],
+    findings,
+  };
+}
+
+export function digestSkillRuntimeTraceability(value) {
+  return crypto.createHash('sha256').update(stableStringify(value)).digest('hex');
+}
+
+function skillRuntimeTraceabilityRow(root, link, skillRows, registryCommands, registryGroups) {
+  const skill = skillRows.find((row) => row.skill === link.skill);
+  const missingRuntimeCommands = link.runtime_commands.filter((command) => !registryCommands.has(command));
+  const blockers = [
+    ...(!skill ? ['skill file missing'] : []),
+    ...(!registryGroups.has(link.runtime_group) ? [`runtime group missing: ${link.runtime_group}`] : []),
+    ...missingRuntimeCommands.map((command) => `runtime command missing: ${command}`),
+    ...(skill && !skill.handoff_complete ? ['workflow handoff markers incomplete'] : []),
+  ];
+  return {
+    stage: traceabilityStage,
+    skill: link.skill,
+    skill_file: skill?.skill_file || `skills/${link.skill}/SKILL.md`,
+    skill_exists: Boolean(skill),
+    skill_digest: skill?.skill_digest || '',
+    runtime_group: link.runtime_group,
+    runtime_group_exists: registryGroups.has(link.runtime_group),
+    runtime_commands: link.runtime_commands,
+    missing_runtime_commands: missingRuntimeCommands,
+    contract: link.contract,
+    handoff_complete: Boolean(skill?.handoff_complete),
+    pass: blockers.length === 0,
+    blockers,
+  };
+}
+
+function skillRuntimeTraceabilityGateResults(skillRows, linkRows, registryCommands, registryGroups) {
+  const skills = skillRows.map((row) => row.skill);
+  const linkedSkills = linkRows.map((row) => row.skill);
+  const expectedSkills = expectedSkillRuntimeLinks.map((link) => link.skill).sort();
+  const missingExpectedSkills = expectedSkills.filter((skill) => !skills.includes(skill));
+  const unmappedSkills = skills.filter((skill) => !linkedSkills.includes(skill));
+  const missingLinkTargets = linkedSkills.filter((skill) => !skills.includes(skill));
+  const badFrontmatter = skillRows.filter((row) => row.frontmatter_name !== row.skill).map((row) => `${row.skill}: ${row.frontmatter_name || 'missing'}`);
+  const missingHandoff = skillRows.filter((row) => !row.handoff_complete).map((row) => row.skill);
+  const missingGroups = linkRows.filter((row) => !registryGroups.has(row.runtime_group)).map((row) => `${row.skill}:${row.runtime_group}`);
+  const missingCommands = linkRows.flatMap((row) => row.runtime_commands.filter((command) => !registryCommands.has(command)).map((command) => `${row.skill}:${command}`));
+
+  return [
+    { gate: 'skill_row_coverage', pass: missingExpectedSkills.length === 0 && unmappedSkills.length === 0 && missingLinkTargets.length === 0, findings: [...missingExpectedSkills.map((skill) => `missing expected skill: ${skill}`), ...unmappedSkills.map((skill) => `unmapped skill: ${skill}`), ...missingLinkTargets.map((skill) => `link references missing skill: ${skill}`)] },
+    { gate: 'frontmatter_name_gate', pass: badFrontmatter.length === 0, findings: badFrontmatter.map((item) => `frontmatter name mismatch: ${item}`) },
+    { gate: 'workflow_handoff_gate', pass: missingHandoff.length === 0, findings: missingHandoff.map((skill) => `handoff markers incomplete: ${skill}`) },
+    { gate: 'runtime_registry_group_gate', pass: missingGroups.length === 0, findings: missingGroups.map((item) => `missing runtime group: ${item}`) },
+    { gate: 'runtime_registry_command_gate', pass: missingCommands.length === 0, findings: missingCommands.map((item) => `missing runtime command: ${item}`) },
+  ];
+}
+
+function listSkillRows(root) {
+  const skillsRoot = path.join(root, 'skills');
+  if (!fs.existsSync(skillsRoot)) return [];
+  return fs.readdirSync(skillsRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => skillRow(root, entry.name))
+    .filter(Boolean)
+    .sort((left, right) => left.skill.localeCompare(right.skill));
+}
+
+function skillRow(root, skill) {
+  const file = path.join(root, 'skills', skill, 'SKILL.md');
+  if (!fs.existsSync(file)) return null;
+  const text = fs.readFileSync(file, 'utf8');
+  const markers = {
+    current_skill: text.includes('current_skill:'),
+    next_skill: text.includes('next_skill:'),
+    handoff: text.includes('handoff:'),
+    stop_condition: text.includes('stop_condition:'),
+  };
+  return {
+    stage: traceabilityStage,
+    skill,
+    skill_file: path.relative(root, file).replace(/\\/g, '/'),
+    frontmatter_name: frontmatterValue(text, 'name'),
+    description_present: Boolean(frontmatterValue(text, 'description')),
+    handoff_markers: markers,
+    handoff_complete: Object.values(markers).every(Boolean),
+    skill_digest: fileDigest(file),
+  };
+}
+
+function frontmatterValue(text, key) {
+  const match = text.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'));
+  return match ? match[1].trim() : '';
+}
+
+function fileDigest(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+function stableStringify(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(',')}]`;
+  return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
+}