@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-product-methodology-gates.mjs

@@ -0,0 +1,316 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { runtimeStatePresent } from './runtime-state-presence-model.mjs';
+
+export const productMethodologyGateKinds = new Set([
+  'product-discovery',
+  'product-spec',
+  'ui-design',
+  'product-acceptance',
+  'scenario-acceptance',
+]);
+
+const markdownContracts = {
+  'product-discovery': {
+    artifact_kind: 'product-discovery',
+    source_skill: 'vibe-product-discovery',
+    next_skills: ['vibe-product-spec', 'vibe-planning', 'vibe-brainstorming', 'none'],
+    sections: ['Goal', 'Input', 'Output Fields', 'Non Goals', 'Risks', 'Acceptance', 'Evidence', 'Boundary', 'Handoff'],
+    fields: ['problem', 'target_users', 'scenarios', 'value_hypothesis', 'success_metrics', 'mvp_slice', 'non_goals', 'risks', 'decision'],
+  },
+  'product-spec': {
+    artifact_kind: 'product-spec',
+    source_skill: 'vibe-product-spec',
+    next_skills: ['vibe-ui-design', 'vibe-planning', 'vibe-product-discovery', 'none'],
+    sections: ['Goal', 'Input', 'Output Fields', 'Non Goals', 'Risks', 'Acceptance', 'Evidence', 'Boundary', 'Handoff'],
+    fields: ['product_goal', 'users_and_scenarios', 'user_stories', 'functional_requirements', 'non_functional_requirements', 'acceptance_criteria', 'priority', 'release_slice', 'out_of_scope'],
+  },
+  'ui-design': {
+    artifact_kind: 'ui-design-contract',
+    source_skill: 'vibe-ui-design',
+    next_skills: ['vibe-planning', 'vibe-product-spec', 'none'],
+    sections: ['Goal', 'Input', 'Output Fields', 'Non Goals', 'Risks', 'Acceptance', 'Evidence', 'Boundary', 'Handoff'],
+    fields: ['screens', 'user_flow', 'information_architecture', 'components', 'ui_states', 'copy_rules', 'interaction_rules', 'responsive_rules', 'accessibility', 'design_acceptance'],
+  },
+  'product-acceptance': {
+    artifact_kind: 'product-acceptance',
+    source_skill: 'vibe-product-acceptance',
+    next_skills: ['vibe-verification-before-completion', 'vibe-implementation', 'vibe-planning', 'vibe-product-spec', 'none'],
+    sections: ['Goal', 'Input', 'Output Fields', 'Non Goals', 'Risks', 'Acceptance', 'Evidence', 'Boundary', 'Handoff'],
+    fields: ['product_claim', 'scenario_coverage', 'user_flow_evidence', 'ui_state_evidence', 'accessibility_evidence', 'metric_readiness', 'experience_gaps', 'not_verified', 'ship_decision'],
+  },
+};
+
+const falseBoundaryKeys = ['writes', 'state_directory_created', 'command_execution', 'skill_execution', 'subagent', 'mcp', 'git'];
+const scenarioStatuses = new Set(['pass', 'fail', 'not_verified', 'not_applicable']);
+
+export function productMethodologyBoundaryAssertions() {
+  return {
+    writes: false,
+    state_directory_created: false,
+    methodology_gate_artifact: false,
+    product_artifact_write: false,
+    scenario_artifact_write: false,
+    completion_bundle_artifact: false,
+    command_execution: false,
+    check_execution: false,
+    test_execution: false,
+    browser_execution: false,
+    skill_execution: false,
+    workflow_execution: false,
+    runtime_action: false,
+    auto_execution: false,
+    external_network: false,
+    model_invocation: false,
+    platform_api: false,
+    subagent: false,
+    mcp: false,
+    git: false,
+    git_write: false,
+    commit: false,
+    pr: false,
+    push: false,
+    merge: false,
+    business_source_write: false,
+  };
+}
+
+export function normalizeProductMethodologyKind(kind) {
+  const normalized = String(kind || '').trim().toLowerCase().replace(/_/g, '-');
+  if (normalized === 'ui-design-contract') return 'ui-design';
+  return normalized;
+}
+
+export function readLocalTextArtifact(root, inputFile, label) {
+  const raw = String(inputFile || '').trim();
+  if (!raw) throw new Error(`${label} requires --from-file <local-artifact-file>`);
+  const resolvedRoot = path.resolve(root);
+  const resolvedFile = path.resolve(raw);
+  const relative = path.relative(resolvedRoot, resolvedFile);
+  if (relative === '' || relative.startsWith('..') || path.isAbsolute(relative)) throw new Error(`${label} must stay within --root`);
+  if (!fs.existsSync(resolvedFile)) throw new Error(`${label} file not found: ${relative.replace(/\\/g, '/')}`);
+  if (!fs.statSync(resolvedFile).isFile()) throw new Error(`${label} path is not a file: ${relative.replace(/\\/g, '/')}`);
+  const text = fs.readFileSync(resolvedFile, 'utf8');
+  return {
+    file: resolvedFile,
+    relative: relative.replace(/\\/g, '/'),
+    text,
+    digest: crypto.createHash('sha256').update(text).digest('hex'),
+  };
+}
+
+export function productMethodologyGateDigestPayload(gate) {
+  return {
+    version: gate.version,
+    stage: gate.stage,
+    gate_kind: gate.gate_kind,
+    artifact_kind: gate.artifact_kind,
+    source_bindings: gate.source_bindings,
+    checks: gate.checks,
+    boundary_assertions: gate.boundary_assertions,
+    writes: gate.writes,
+    state_directory_created: gate.state_directory_created,
+  };
+}
+
+export function digestProductMethodologyGate(payload) {
+  return crypto.createHash('sha256').update(stableStringify(payload)).digest('hex');
+}
+
+export function productMethodologyGateEnvelope(root, { kind = '', fromFile = '' } = {}) {
+  const gateKind = normalizeProductMethodologyKind(kind);
+  if (!productMethodologyGateKinds.has(gateKind)) throw new Error(`unsupported product methodology gate kind: ${kind}`);
+  const source = readLocalTextArtifact(root, fromFile, `methodology --gate --kind ${gateKind}`);
+  const validation = gateKind === 'scenario-acceptance'
+    ? validateScenarioAcceptanceArtifact(source.text)
+    : validateMarkdownProductArtifact(source.text, markdownContracts[gateKind]);
+  const boundaryAssertions = productMethodologyBoundaryAssertions();
+  const checks = validation.checks;
+  const blockedReasons = checks.filter((check) => !check.pass).map((check) => `${check.id}: ${check.reason}`);
+  const gate = {
+    version: 1,
+    stage: 'Stage 151',
+    gate_kind: gateKind,
+    artifact_kind: validation.artifact_kind,
+    gate_outcome: blockedReasons.length === 0 ? 'pass' : 'blocked',
+    source_bindings: {
+      artifact_file: source.relative,
+      artifact_digest: source.digest,
+      expected_source_skill: validation.expected_source_skill,
+      declared_source_skill: validation.declared_source_skill,
+      declared_next_skill: validation.declared_next_skill,
+    },
+    checks,
+    blocked_reasons: blockedReasons,
+    invariants: {
+      pass: blockedReasons.length === 0 && Object.values(boundaryAssertions).every((value) => value === false),
+      checked: ['source_binding', 'artifact_kind', 'source_skill', 'next_skill', 'required_sections', 'required_fields', 'evidence', 'boundary_assertions'],
+    },
+    next_manual_action: blockedReasons.length === 0
+      ? 'Artifact contract is complete enough for the next workflow handoff; no workflow, test, browser, subagent, git, or platform action was run.'
+      : 'Fix the listed artifact gaps manually, then rerun methodology --gate with the same local file.',
+    boundary_assertions: boundaryAssertions,
+    writes: false,
+    state_directory_created: false,
+    local_only: true,
+    deterministic: true,
+  };
+  return {
+    mode: 'product-methodology-gate',
+    ok: gate.invariants.pass,
+    state_present: runtimeStatePresent(root),
+    product_methodology_gate: {
+      ...gate,
+      gate_digest: digestProductMethodologyGate(productMethodologyGateDigestPayload(gate)),
+    },
+    safety: { stage: 'Stage 151', ...boundaryAssertions },
+    quality: blockedReasons,
+    action: 'methodology product gate read one local artifact and computed deterministic checks only. No state directory, artifact write, workflow skill execution, command/check/test/browser execution, runtime action, git, platform API, external network, model, MCP, subagent, or business source mutation occurred.',
+  };
+}
+
+function validateMarkdownProductArtifact(text, contract) {
+  const frontmatter = parseFrontmatter(text);
+  const checks = [];
+  const fieldValues = parseFieldValues(text);
+  addCheck(checks, 'frontmatter.artifact_kind', frontmatter.artifact_kind === contract.artifact_kind, `expected artifact_kind: ${contract.artifact_kind}`);
+  addCheck(checks, 'frontmatter.version', String(frontmatter.version || '') === '1', 'expected version: 1');
+  addCheck(checks, 'frontmatter.source_skill', frontmatter.source_skill === contract.source_skill, `expected source_skill: ${contract.source_skill}`);
+  addCheck(checks, 'frontmatter.status', Boolean(String(frontmatter.status || '').trim()), 'status is required');
+  addCheck(checks, 'frontmatter.next_skill', contract.next_skills.includes(String(frontmatter.next_skill || '').trim()), `next_skill must be one of ${contract.next_skills.join(', ')}`);
+  for (const section of contract.sections) addCheck(checks, `section.${section}`, hasSection(text, section), `missing section: ${section}`);
+  for (const field of contract.fields) addCheck(checks, `field.${field}`, hasNonEmptyField(fieldValues, field), `missing non-empty field: ${field}`);
+  addCheck(checks, 'evidence.present', hasSection(text, 'Evidence') && (/evidence_sources\s*:/i.test(text) || /not_verified\s*:/i.test(text)), 'Evidence must include evidence_sources or not_verified');
+  for (const key of falseBoundaryKeys) addCheck(checks, `boundary.${key}`, boundaryFalse(text, key), `Boundary must declare ${key}: false`);
+  return {
+    artifact_kind: contract.artifact_kind,
+    expected_source_skill: contract.source_skill,
+    declared_source_skill: frontmatter.source_skill || '',
+    declared_next_skill: frontmatter.next_skill || '',
+    checks,
+  };
+}
+
+function validateScenarioAcceptanceArtifact(text) {
+  const top = parseYamlTopLevel(text);
+  const scenarios = parseScenarioBlocks(text);
+  const checks = [];
+  addCheck(checks, 'artifact_kind', top.artifact_kind === 'scenario-acceptance', 'expected artifact_kind: scenario-acceptance');
+  addCheck(checks, 'version', String(top.version || '') === '1', 'expected version: 1');
+  addCheck(checks, 'source_skill', top.source_skill === 'vibe-product-acceptance', 'expected source_skill: vibe-product-acceptance');
+  addCheck(checks, 'next_skill', ['vibe-product-acceptance', 'vibe-verification-before-completion', 'none'].includes(String(top.next_skill || '').trim()), 'next_skill must route to product acceptance, verification, or none');
+  addCheck(checks, 'scenarios.non_empty', scenarios.length > 0, 'scenarios[] must not be empty');
+  for (const scenario of scenarios) {
+    addCheck(checks, `scenario.${scenario.id || 'missing-id'}.id`, Boolean(scenario.id), 'scenario id is required');
+    addCheck(checks, `scenario.${scenario.id || 'missing-id'}.given`, hasListValue(scenario.block, 'given'), 'given must not be empty');
+    addCheck(checks, `scenario.${scenario.id || 'missing-id'}.when`, hasListValue(scenario.block, 'when'), 'when must not be empty');
+    addCheck(checks, `scenario.${scenario.id || 'missing-id'}.then`, hasListValue(scenario.block, 'then'), 'then must not be empty');
+    addCheck(checks, `scenario.${scenario.id || 'missing-id'}.evidence.required`, /evidence:\s*[\s\S]*?required:\s*\n\s+-\s+\S/m.test(scenario.block), 'evidence.required must not be empty');
+    addCheck(checks, `scenario.${scenario.id || 'missing-id'}.status`, scenarioStatuses.has(scenario.status), 'status must be pass, fail, not_verified, or not_applicable');
+    const hasUiStates = hasListValue(scenario.block, 'ui_states');
+    const hasReason = /not_applicable_reason\s*:\s*\S/.test(scenario.block);
+    addCheck(checks, `scenario.${scenario.id || 'missing-id'}.ui_states_or_reason`, hasUiStates || hasReason, 'UI scenarios must declare ui_states or not_applicable_reason');
+  }
+  for (const key of falseBoundaryKeys) addCheck(checks, `boundary.${key}`, boundaryFalse(text, key), `boundary.${key} must be false`);
+  return {
+    artifact_kind: 'scenario-acceptance',
+    expected_source_skill: 'vibe-product-acceptance',
+    declared_source_skill: top.source_skill || '',
+    declared_next_skill: top.next_skill || '',
+    checks,
+  };
+}
+
+function parseFrontmatter(text) {
+  const match = String(text || '').match(/^---\s*\n([\s\S]*?)\n---\s*\n/);
+  if (!match) return {};
+  return parseYamlTopLevel(match[1]);
+}
+
+function parseYamlTopLevel(text) {
+  const result = {};
+  for (const line of String(text || '').split(/\r?\n/)) {
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*?)\s*$/);
+    if (match) result[match[1]] = stripQuotes(match[2]);
+  }
+  return result;
+}
+
+function parseFieldValues(text) {
+  const values = new Map();
+  const lines = String(text || '').split(/\r?\n/);
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = lines[index].match(/^\s*(?:-\s*)?([A-Za-z0-9_]+):\s*(.*?)\s*$/);
+    if (!match) continue;
+    const key = match[1];
+    const sameLineValue = stripQuotes(match[2]);
+    const nestedValue = collectNestedValue(lines, index + 1);
+    values.set(key, [values.get(key), sameLineValue, nestedValue].filter(Boolean).join('\n').trim());
+  }
+  return values;
+}
+
+function collectNestedValue(lines, startIndex) {
+  const collected = [];
+  for (let index = startIndex; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (/^\s*(?:-\s*)?[A-Za-z0-9_]+:\s*/.test(line) || /^#{1,6}\s+/.test(line)) break;
+    if (/^\s+-\s+\S/.test(line)) collected.push(line.replace(/^\s+-\s+/, '').trim());
+  }
+  return collected.join('\n').trim();
+}
+
+function hasNonEmptyField(values, field) {
+  return Boolean(String(values.get(field) || '').trim());
+}
+
+function hasSection(text, section) {
+  const escaped = section.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`^##\\s+${escaped}\\s*$`, 'im').test(text);
+}
+
+function boundaryFalse(text, key) {
+  return new RegExp(`(?:^|\\n)\\s*-?\\s*${key}\\s*:\\s*false\\s*(?:\\n|$)`, 'i').test(text);
+}
+
+function parseScenarioBlocks(text) {
+  const lines = String(text || '').split(/\r?\n/);
+  const blocks = [];
+  let current = null;
+  for (const line of lines) {
+    const start = line.match(/^\s*-\s+id:\s*(\S.*?)\s*$/);
+    if (start) {
+      if (current) blocks.push(current);
+      current = { id: stripQuotes(start[1]), lines: [line] };
+      continue;
+    }
+    if (current) current.lines.push(line);
+  }
+  if (current) blocks.push(current);
+  return blocks.map((block) => {
+    const textBlock = block.lines.join('\n');
+    const statusMatch = textBlock.match(/(?:^|\n)\s*status:\s*(\S+)\s*(?:\n|$)/);
+    return { id: block.id, block: textBlock, status: stripQuotes(statusMatch?.[1] || '') };
+  });
+}
+
+function hasListValue(block, key) {
+  return new RegExp(`${key}:\\s*\\n\\s+-\\s+\\S`, 'm').test(block);
+}
+
+function stripQuotes(value) {
+  return String(value || '').trim().replace(/^['"]|['"]$/g, '');
+}
+
+function addCheck(checks, id, pass, reason) {
+  checks.push({ id, pass: Boolean(pass), reason: pass ? '' : reason });
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}

package/tools/vibe-runtime/runtime-progressive-entry-ux.mjs

@@ -0,0 +1,237 @@
+import crypto from 'node:crypto';
+
+const progressiveEntryUxStage = 'Stage 116';
+const progressiveEntryUxKind = 'progressive-entry-ux-contract';
+
+const intentRoutes = [
+  {
+    intent: 'debug',
+    patterns: [/\bdebug\b/i, /\bbug\b/i, /\berror\b/i, /\bfail(?:ed|ing)?\b/i, /崩溃|报错|失败|排查|修复/],
+    workflow: 'vibe-debugging -> vibe-systematic-debugging',
+    first_action: '先收集错误、复现步骤和最近变更，再决定是否进入系统化调试。',
+    visible_sentence: '我会先按调试入口收集证据，不直接改代码。',
+  },
+  {
+    intent: 'review',
+    patterns: [/\breview\b/i, /\bcode review\b/i, /审查|评审|review/],
+    workflow: 'vibe-requesting-code-review -> vibe-review',
+    first_action: '先明确审查范围、风险点和需要绑定的本地证据。',
+    visible_sentence: '我会先按 review 入口界定范围和证据，不直接给出完成结论。',
+  },
+  {
+    intent: 'plan',
+    patterns: [/\bplan\b/i, /\bdesign\b/i, /\barchitecture\b/i, /计划|方案|架构|设计/],
+    workflow: 'vibe-planning -> vibe-writing-plans',
+    first_action: '先把目标、边界、文件范围、验证方式和停止条件变成计划。',
+    visible_sentence: '我会先进入计划入口，把执行边界和验收条件说清楚。',
+  },
+  {
+    intent: 'implementation',
+    patterns: [/\bimplement\b/i, /\badd\b/i, /\bfeature\b/i, /\bchange\b/i, /实现|新增|添加|修改|继续|开发/],
+    workflow: 'vibe-executing-plans -> vibe-review -> vibe-implementation',
+    first_action: '先确认是否已有可执行计划；没有计划时先补计划，不直接扩大修改面。',
+    visible_sentence: '我会按计划执行入口推进，并在实现前保持验证和边界可见。',
+  },
+  {
+    intent: 'completion',
+    patterns: [/\bfinish\b/i, /\bcomplete\b/i, /\bcommit\b/i, /收尾|完成|提交|发布/],
+    workflow: 'vibe-verification-before-completion -> vibe-finishing-a-development-branch',
+    first_action: '先绑定验证证据、diff 覆盖和提交边界，再考虑本地提交。',
+    visible_sentence: '我会先按完成前验证入口确认新鲜证据，不直接声称完成。',
+  },
+];
+
+export function runtimeProgressiveEntryUx({ prompt = '', gapMatrix = null } = {}) {
+  const normalizedPrompt = String(prompt || '').trim();
+  const route = selectRoute(normalizedPrompt);
+  const boundaryAssertions = runtimeProgressiveEntryUxBoundaryAssertions();
+  const gapSummary = summarizeGapMatrix(gapMatrix);
+  const contract = {
+    version: 1,
+    stage: progressiveEntryUxStage,
+    contract_kind: progressiveEntryUxKind,
+    prompt: normalizedPrompt,
+    normalized_intent: route.intent,
+    recommended_workflow: route.workflow,
+    why_this_route: whyRoute(route, normalizedPrompt, gapSummary),
+    minimum_next_action: route.first_action,
+    visible_sentence: route.visible_sentence,
+    bootstrap_policy: {
+      injectsFullSkill: false,
+      marker: 'injectsFullSkill=false',
+      session_create: false,
+      skill_execution_claimed: false,
+      rationale: 'Progressive entry UX exposes routing, risk, and next action without loading the full workflow skill into context.',
+    },
+    do_not_do_yet: [
+      '不要声称已经执行或使用某个 skill；这里只是入口合同。',
+      '不要运行命令、测试、检查、修复、格式化或代码生成。',
+      '不要创建 subagent、调用模型、MCP、平台 API 或外部网络。',
+      '不要写源码、写 sidecar、创建状态目录、git commit、push、PR 或 merge。',
+    ],
+    source_bindings: gapSummary,
+    next_contract_hint: nextContractHint(route.intent),
+    boundary_assertions: boundaryAssertions,
+    writes: false,
+    state_directory_created: false,
+    local_only: true,
+    deterministic: true,
+  };
+  const invariants = runtimeProgressiveEntryUxInvariants(contract);
+  return {
+    ...contract,
+    entry_ux_invariants: invariants,
+    manual_action: invariants.pass ? route.first_action : '先修复入口 UX 合同缺失字段或边界断言，再继续工作流。',
+  };
+}
+
+export function runtimeProgressiveEntryUxInvariants(contract) {
+  const missing = ['recommended_workflow', 'why_this_route', 'minimum_next_action', 'visible_sentence', 'do_not_do_yet']
+    .filter((field) => isEmpty(contract[field]));
+  const missingForbidden = ['command_execution', 'skill_execution', 'workflow_execution', 'runtime_action', 'source_write', 'sidecar_write', 'state_directory_created', 'git', 'git_write', 'commit', 'push', 'pr', 'merge', 'platform_api', 'external_network', 'model_invocation', 'subagent', 'mcp', 'business_source_write']
+    .filter((key) => contract.boundary_assertions?.[key] !== false);
+  const findings = [
+    ...(contract.stage === progressiveEntryUxStage ? [] : ['stage must be Stage 116']),
+    ...(contract.contract_kind === progressiveEntryUxKind ? [] : ['contract_kind must be progressive-entry-ux-contract']),
+    ...(contract.prompt ? [] : ['prompt is required']),
+    ...(contract.bootstrap_policy?.injectsFullSkill === false ? [] : ['bootstrap_policy.injectsFullSkill must be false']),
+    ...(contract.bootstrap_policy?.marker === 'injectsFullSkill=false' ? [] : ['bootstrap_policy.marker must be injectsFullSkill=false']),
+    ...(contract.bootstrap_policy?.session_create === false ? [] : ['bootstrap_policy.session_create must be false']),
+    ...(contract.bootstrap_policy?.skill_execution_claimed === false ? [] : ['bootstrap_policy.skill_execution_claimed must be false']),
+    ...missing.map((field) => `missing required output field: ${field}`),
+    ...missingForbidden.map((key) => `forbidden boundary missing or not false: ${key}`),
+  ];
+  return {
+    pass: findings.length === 0,
+    checked: ['required_fields', 'prompt_binding', 'read_only_boundaries', 'local_deterministic_contract'],
+    findings,
+  };
+}
+
+export function runtimeProgressiveEntryUxDigestPayload(contract) {
+  return {
+    stage: contract.stage,
+    contract_kind: contract.contract_kind,
+    prompt: contract.prompt,
+    normalized_intent: contract.normalized_intent,
+    recommended_workflow: contract.recommended_workflow,
+    why_this_route: contract.why_this_route,
+    minimum_next_action: contract.minimum_next_action,
+    visible_sentence: contract.visible_sentence,
+    bootstrap_policy: contract.bootstrap_policy,
+    do_not_do_yet: contract.do_not_do_yet,
+    source_bindings: contract.source_bindings,
+    next_contract_hint: contract.next_contract_hint,
+    boundary_assertions: contract.boundary_assertions,
+    entry_ux_invariants: contract.entry_ux_invariants,
+  };
+}
+
+export function digestProgressiveEntryUx(value) {
+  return crypto.createHash('sha256').update(stableStringify(value)).digest('hex');
+}
+
+export function runtimeProgressiveEntryUxBoundaryAssertions() {
+  return {
+    progressive_entry_ux_artifact: false,
+    sidecar_write: false,
+    state_directory_created: false,
+    source_write: false,
+    command_execution: false,
+    check_execution: false,
+    test_execution: false,
+    skill_execution: false,
+    workflow_execution: false,
+    runtime_action: false,
+    auto_execution: false,
+    scheduler: false,
+    daemon: false,
+    retry: false,
+    git: false,
+    git_write: false,
+    commit: false,
+    pr: false,
+    push: false,
+    merge: false,
+    tag: false,
+    platform_api: false,
+    external_network: false,
+    model_invocation: false,
+    subagent: false,
+    mcp: false,
+    worktree: false,
+    business_source_write: false,
+  };
+}
+
+function selectRoute(prompt) {
+  const text = prompt || '';
+  const matched = intentRoutes.find((route) => route.patterns.some((pattern) => pattern.test(text)));
+  return matched || {
+    intent: 'unknown',
+    workflow: 'workflow --start -> workflow --receipt',
+    first_action: '先把请求改写成明确目标、约束和验收方式，再选择具体工作流。',
+    visible_sentence: '我会先做轻量入口判断，避免在意图不清时直接执行。',
+  };
+}
+
+function summarizeGapMatrix(gapMatrix) {
+  const matrix = normalizeGapMatrix(gapMatrix);
+  if (!matrix) {
+    return {
+      gap_matrix_provided: false,
+      gap_matrix_stage: '',
+      gap_matrix_digest: '',
+      stage116_gap_found: false,
+      stage116_gap_ids: [],
+    };
+  }
+  const dimensions = Array.isArray(matrix.dimensions) ? matrix.dimensions : [];
+  const stage116 = dimensions
+    .filter((dimension) => dimension.recommended_stage === 'Stage 116')
+    .map((dimension) => dimension.id)
+    .filter(Boolean);
+  return {
+    gap_matrix_provided: true,
+    gap_matrix_stage: matrix.stage || '',
+    gap_matrix_digest: matrix.gap_matrix_digest || '',
+    stage116_gap_found: stage116.length > 0,
+    stage116_gap_ids: stage116,
+  };
+}
+
+function normalizeGapMatrix(value) {
+  if (!value || typeof value !== 'object') return null;
+  if (value.superpowers_gap_matrix && typeof value.superpowers_gap_matrix === 'object') return value.superpowers_gap_matrix;
+  if (value.stage === 'Stage 115' && value.gap_kind === 'superpowers-gap-matrix') return value;
+  return null;
+}
+
+function whyRoute(route, prompt, gapSummary) {
+  const promptReason = prompt ? `prompt matched ${route.intent} entry signals` : 'prompt was empty';
+  const gapReason = gapSummary.stage116_gap_found
+    ? `Stage 115 gap matrix highlights Stage 116 gaps: ${gapSummary.stage116_gap_ids.join(', ')}`
+    : 'no Stage 115 gap matrix was provided or it did not highlight Stage 116';
+  return `${promptReason}; ${gapReason}; output stays as a visible local contract instead of full skill injection.`;
+}
+
+function nextContractHint(intent) {
+  if (intent === 'plan') return 'planner --action-manifest or Stage 117 executable plan contract';
+  if (intent === 'implementation') return 'workflow --close-loop or Stage 118 sequential stage runbook after plan quality is known';
+  if (intent === 'debug') return 'workflow --start plus local reproduction evidence';
+  if (intent === 'review') return 'review --intake with local review evidence';
+  if (intent === 'completion') return 'completion --evidence-bundle and release --commit-readiness';
+  return 'workflow --start with a clearer prompt';
+}
+
+function isEmpty(value) {
+  return Array.isArray(value) ? value.length === 0 : !value;
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}

package/tools/vibe-runtime/runtime-queue-command.mjs

@@ -0,0 +1,98 @@
+import { runtimeContractSyncOwner } from './runtime-contract-marker-registry.mjs';
+import { createRuntimeQueueStateLifecycleModel } from './runtime-queue-state-lifecycle-model.mjs';
+
+const qName = ['que', 'ue'].join('');
+const qTitle = `${qName[0].toUpperCase()}${qName.slice(1)}`;
+const scanEnvelopeApiKey = `${qName}ScanEnvelope`;
+const auditEnvelopeApiKey = `${qName}AuditEnvelope`;
+const snapshotPathApiKey = `${qName}SnapshotPath`;
+const listFilesApiKey = `list${qTitle}Files`;
+const validateArtifactApiKey = `validate${qTitle}Artifact`;
+const writeSnapshotApiKey = `write${qTitle}Snapshot`;
+const categorizeBlockedItemApiKey = `categorize${qTitle}BlockedItem`;
+
+export const runtimeQueueCommandContractSync = runtimeContractSyncOwner('runtime-queue-command');
+
+export function createRuntimeQueueCommand(deps) {
+  const {
+    path,
+    process,
+    ensureRoot,
+    writeJsonEnvelope,
+    printList,
+  } = deps;
+  const stateLifecycle = createRuntimeQueueStateLifecycleModel(deps);
+
+  function printQueue(envelope, file = '') {
+    console.log('Vibecoding Runtime Candidate Queue');
+    console.log('Mode: scan');
+    console.log(`Items: ${envelope[qName].items.length}; Ready: ${envelope[qName].ready.length}; Blocked: ${envelope[qName].blocked.length}`);
+    console.log(`Promotion preview: ${envelope[qName].promotion_preview.length}`);
+    if (file) console.log(`Queue artifact: ${path.relative(process.cwd(), file)}`);
+    for (const item of envelope[qName].items) console.log(`- ${item.candidate_file}: ${item.status} ${item.target_skill || 'none'} [priority=${item.priority}; locked=${item.locked ? 'true' : 'false'}; active=${item.active_count}]`);
+    if (envelope.quality.length > 0) printList('Blocked reasons', envelope.quality);
+    console.log('Safety: scan=true; writes=false by default; auto_execution=false; runtime_action=false; worker=false; watcher=false; git=false; worktree=false.');
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  function printQueueAudit(envelope) {
+    console.log('Vibecoding Runtime Queue Audit');
+    console.log(`Mode: ${envelope.mode.replace(`${qName}-audit-`, '')}`);
+    if (envelope.mode === `${qName}-audit-list`) {
+      console.log(`Queues: ${envelope[`${qName}s`].length}`);
+      for (const item of envelope[`${qName}s`]) console.log(`- ${item.file}: items=${item.count}; ready=${item.ready_count}; blocked=${item.blocked_count}; verification=${item.verification_ok ? 'passed' : 'failed'}`);
+    } else {
+      console.log(`File: ${envelope.summary.file}`);
+      console.log(`Items: ${envelope.summary.count}; Ready: ${envelope.summary.ready_count}; Blocked: ${envelope.summary.blocked_count}`);
+      console.log(`Verification: ${envelope.verification.ok ? 'passed' : 'failed'}`);
+      if (envelope.verification.failures.length > 0) printList('Verification failures', envelope.verification.failures);
+    }
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  function runQueue(options) {
+    if (options.write || options.dryRun || options.fromDispatch || options.actor || options.approval || options.run || options.autoRun) throw new Error('queue supports scan and read-only audit only');
+    const modes = [options.scan, options.queueList, options.queueShow, options.queueVerify].filter(Boolean);
+    if (modes.length !== 1) throw new Error('queue requires exactly one of --scan, --list, --show, or --verify');
+    ensureRoot(options.root);
+    if (options.scan) {
+      const envelope = stateLifecycle[scanEnvelopeApiKey](options.root, { persist: options.confirm });
+      if (options.confirm) {
+        const file = stateLifecycle[writeSnapshotApiKey](options.root, envelope);
+        if (options.json) {
+          writeJsonEnvelope(qName, { ...envelope, [`${qName}_file`]: path.basename(file) });
+          return;
+        }
+        printQueue(envelope, file);
+        return;
+      }
+      if (options.json) {
+        writeJsonEnvelope(qName, envelope);
+        return;
+      }
+      printQueue(envelope);
+      return;
+    }
+    if (options.confirm) throw new Error('queue --confirm is only supported with --scan');
+    const mode = options.queueList ? 'list' : options.queueVerify ? 'verify' : 'show';
+    const envelope = stateLifecycle[auditEnvelopeApiKey](options.root, mode, options.queueFile);
+    if (options.json) {
+      writeJsonEnvelope(qName, envelope);
+      return;
+    }
+    printQueueAudit(envelope);
+  }
+
+  return {
+    listQueueFiles: stateLifecycle[listFilesApiKey],
+    queueSnapshotPath: stateLifecycle[snapshotPathApiKey],
+    [scanEnvelopeApiKey]: stateLifecycle[scanEnvelopeApiKey],
+    validateQueueArtifact: stateLifecycle[validateArtifactApiKey],
+    writeQueueSnapshot: stateLifecycle[writeSnapshotApiKey],
+    queueAuditEnvelope: stateLifecycle[auditEnvelopeApiKey],
+    categorizeQueueBlockedItem: stateLifecycle[categorizeBlockedItemApiKey],
+    printQueue,
+    printQueueAudit,
+    runQueue,
+  };
+}