@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-implementation-task-registry.mjs

@@ -0,0 +1,334 @@
+import crypto from 'node:crypto';
+
+const taskIdPattern = /^[A-Za-z0-9._-]+$/;
+const taskStatuses = new Set(['planned', 'in_progress', 'done', 'deferred', 'not_started']);
+const taskOperations = new Set(['add', 'modify', 'delete', 'config', 'docs', 'test']);
+const taskRisks = new Set(['low', 'medium', 'high']);
+const listFields = new Set(['source_refs', 'expected_files', 'allowed_paths', 'expected_operations', 'required_scenario_refs']);
+const booleanFields = new Set(['required', 'test_required']);
+
+export function parseImplementationTaskRegistry(text) {
+  const section = sectionBody(text, 'Implementation Task Registry');
+  const tasks = [];
+  let current = null;
+  for (const rawLine of section.split(/\r?\n/)) {
+    const line = rawLine.trimEnd();
+    const start = line.match(/^\s*-\s*task_id:\s*(.*?)\s*$/);
+    if (start) {
+      if (current) tasks.push(normalizeTask(current));
+      current = { task_id: stripQuotes(start[1]) };
+      continue;
+    }
+    const field = line.match(/^\s+([A-Za-z0-9_]+):\s*(.*?)\s*$/);
+    if (field && current) current[field[1]] = parseTaskField(field[1], field[2]);
+  }
+  if (current) tasks.push(normalizeTask(current));
+  return {
+    tasks,
+    task_ids: tasks.map((task) => task.task_id),
+    registry_present: section.trim().length > 0,
+    registry_digest: digestObject(tasks),
+  };
+}
+
+export function validateImplementationTaskRegistry(registry, { scenarioRefs = [] } = {}) {
+  const findings = [];
+  const seen = new Set();
+  const knownScenarios = new Set(scenarioRefs);
+  if (!registry.registry_present) findings.push('implementation_plan.implementation_task_registry section is required');
+  if (registry.tasks.length === 0) findings.push('implementation_plan.tasks[] must not be empty');
+  for (const [index, task] of registry.tasks.entries()) {
+    const label = task.task_id || `task-${index}`;
+    if (!task.task_id) findings.push(`implementation_plan.tasks[${index}].task_id is required`);
+    if (task.task_id && !taskIdPattern.test(task.task_id)) findings.push(`implementation_plan.task.${label}.task_id has invalid characters`);
+    if (seen.has(task.task_id)) findings.push(`implementation_plan.task.${label}.task_id must be unique`);
+    if (task.task_id) seen.add(task.task_id);
+    if (typeof task.required !== 'boolean') findings.push(`implementation_plan.task.${label}.required must be true or false`);
+    if (!taskStatuses.has(task.status)) findings.push(`implementation_plan.task.${label}.status must be one of ${[...taskStatuses].join(', ')}`);
+    if (task.expected_files.length === 0 && task.allowed_paths.length === 0) findings.push(`implementation_plan.task.${label}.expected_files or allowed_paths is required`);
+    if (task.expected_operations.length === 0) findings.push(`implementation_plan.task.${label}.expected_operations must not be empty`);
+    for (const operation of task.expected_operations) {
+      if (!taskOperations.has(operation)) findings.push(`implementation_plan.task.${label}.expected_operation ${operation} is unsupported`);
+    }
+    if (task.risk && !taskRisks.has(task.risk)) findings.push(`implementation_plan.task.${label}.risk must be low, medium, or high`);
+    if ((task.status === 'deferred' || task.status === 'not_started') && !task.rationale) findings.push(`implementation_plan.task.${label}.rationale is required when status is ${task.status}`);
+    if (knownScenarios.size > 0) {
+      for (const scenarioRef of task.required_scenario_refs) {
+        if (!knownScenarios.has(scenarioRef)) findings.push(`implementation_plan.task.${label}.required_scenario_ref ${scenarioRef} not found in scenario acceptance artifact`);
+      }
+    }
+  }
+  return {
+    gate_kind: 'implementation_task_registry_gate',
+    ok: findings.length === 0,
+    summary: registrySummary(registry.tasks),
+    findings,
+    blocked_reasons: findings,
+  };
+}
+
+export function validateImplementationAlignment({ registry, diffCoverage, testEvidence, scenarioRefs = [] } = {}) {
+  const tasks = Array.isArray(registry?.tasks) ? registry.tasks : [];
+  const taskById = new Map(tasks.map((task) => [task.task_id, task]));
+  const diff = diffCoverage?.parsed || {};
+  const test = testEvidence?.parsed || {};
+  const taskCoverage = Array.isArray(diff.task_coverage) ? diff.task_coverage : [];
+  const topChangedFiles = Array.isArray(diff.changed_files) ? diff.changed_files.map(normalizePath) : [];
+  const runs = Array.isArray(test.runs) ? test.runs : [];
+  const findings = [];
+  const uncoveredRequiredTasks = [];
+  const unexplainedChangedFiles = [];
+  const operationMismatches = [];
+  const missingTestEvidenceForRequiredTasks = [];
+  const unknownTaskRefs = [];
+  const pathViolations = [];
+  const knownScenarios = new Set(scenarioRefs);
+  const coveredTaskIds = new Set();
+  const taskChangedFiles = new Set();
+
+  if (tasks.length === 0) findings.push('implementation_alignment requires implementation task registry tasks');
+  if (!diffCoverage || diffCoverage.status !== 'provided') findings.push('implementation_alignment requires diff coverage evidence');
+  if (!testEvidence || testEvidence.status !== 'provided') findings.push('implementation_alignment requires test evidence');
+  if (diffCoverage?.status === 'provided' && !Array.isArray(diff.task_coverage)) findings.push('implementation_alignment.diff_coverage.task_coverage[] is required');
+
+  const coverageContext = {
+    taskById,
+    coveredTaskIds,
+    taskChangedFiles,
+    findings,
+    unknownTaskRefs,
+    pathViolations,
+    operationMismatches,
+  };
+  for (const [coverageIndex, coverage] of taskCoverage.entries()) {
+    validateTaskCoverageEntry({ coverage, coverageIndex, context: coverageContext });
+  }
+
+  recordUnexplainedChangedFiles({ topChangedFiles, taskChangedFiles, unexplainedChangedFiles, findings });
+
+  for (const task of tasks) {
+    validateRequiredTaskEvidence({ task, runs, coveredTaskIds, uncoveredRequiredTasks, missingTestEvidenceForRequiredTasks, findings });
+  }
+
+  for (const [runIndex, run] of runs.entries()) {
+    validateTestEvidenceRun({ run, runIndex, taskById, knownScenarios, findings });
+  }
+
+  const testedTaskIds = new Set(runs.filter((run) => isPassingRun(run)).flatMap((run) => Array.isArray(run?.task_refs) ? run.task_refs : []).filter((taskRef) => taskById.has(taskRef)));
+  return {
+    gate_kind: 'implementation_alignment_gate',
+    ok: findings.length === 0,
+    summary: {
+      plan_task_count: tasks.length,
+      required_task_count: tasks.filter((task) => task.required === true).length,
+      covered_task_count: coveredTaskIds.size,
+      tested_task_count: testedTaskIds.size,
+      unexplained_changed_file_count: unexplainedChangedFiles.length,
+      operation_mismatch_count: operationMismatches.length,
+      missing_test_evidence_count: missingTestEvidenceForRequiredTasks.length,
+      unknown_task_ref_count: unknownTaskRefs.length,
+      path_violation_count: pathViolations.length,
+    },
+    uncovered_required_tasks: uncoveredRequiredTasks,
+    unexplained_changed_files: unexplainedChangedFiles,
+    operation_mismatches: operationMismatches,
+    missing_test_evidence_for_required_tasks: missingTestEvidenceForRequiredTasks,
+    path_violations: pathViolations,
+    unknown_task_refs: unknownTaskRefs,
+    findings,
+    blocked_reasons: findings,
+  };
+}
+
+export function implementationTaskRegistryDigest(registry) {
+  return digestObject(registry?.tasks || []);
+}
+
+function validateTaskCoverageEntry({ coverage, coverageIndex, context }) {
+  const { taskById, coveredTaskIds, taskChangedFiles, findings, unknownTaskRefs, pathViolations, operationMismatches } = context;
+  const taskRef = String(coverage?.task_ref || '').trim();
+  const task = taskById.get(taskRef);
+  if (!taskRef) {
+    findings.push(`implementation_alignment.task_coverage[${coverageIndex}].task_ref is required`);
+    return;
+  }
+  if (!task) {
+    const reason = `implementation_task_ref_unknown: ${taskRef}`;
+    unknownTaskRefs.push(reason);
+    findings.push(reason);
+    return;
+  }
+
+  const status = String(coverage?.status || '').trim();
+  if (status === 'covered') coveredTaskIds.add(taskRef);
+  if ((status === 'deferred' || status === 'not_started') && !String(coverage?.rationale || '').trim()) findings.push(`implementation_alignment.task.${taskRef}.rationale is required when coverage status is ${status}`);
+
+  const changedFiles = Array.isArray(coverage?.changed_files) ? coverage.changed_files : [];
+  if (status === 'covered' && changedFiles.length === 0) findings.push(`implementation_alignment.task.${taskRef}.changed_files[] must not be empty when covered`);
+  for (const file of changedFiles) {
+    validateTaskChangedFile({ file, task, taskRef, taskChangedFiles, findings, pathViolations, operationMismatches });
+  }
+}
+
+function validateTaskChangedFile({ file, task, taskRef, taskChangedFiles, findings, pathViolations, operationMismatches }) {
+  const filePath = normalizePath(file?.path || file);
+  const operation = String(file?.operation || '').trim();
+  if (!filePath) {
+    findings.push(`implementation_alignment.task.${taskRef}.changed_file.path is required`);
+    return;
+  }
+  taskChangedFiles.add(filePath);
+  if (!pathAllowedByTask(filePath, task)) {
+    const reason = `implementation_changed_file_outside_task_scope: ${taskRef} ${filePath}`;
+    pathViolations.push(reason);
+    findings.push(reason);
+  }
+  if (!task.expected_operations.includes(operation)) {
+    const reason = `implementation_operation_mismatch: ${taskRef} expected=${task.expected_operations.join('|')} actual=${operation || 'missing'} file=${filePath}`;
+    operationMismatches.push(reason);
+    findings.push(reason);
+  }
+  if (!String(file?.digest || '').trim()) findings.push(`implementation_alignment.task.${taskRef}.changed_file ${filePath} digest is required`);
+}
+
+function recordUnexplainedChangedFiles({ topChangedFiles, taskChangedFiles, unexplainedChangedFiles, findings }) {
+  for (const filePath of topChangedFiles) {
+    if (!taskChangedFiles.has(filePath)) {
+      const reason = `implementation_changed_file_unexplained: ${filePath}`;
+      unexplainedChangedFiles.push(reason);
+      findings.push(reason);
+    }
+  }
+}
+
+function validateRequiredTaskEvidence({ task, runs, coveredTaskIds, uncoveredRequiredTasks, missingTestEvidenceForRequiredTasks, findings }) {
+  const activeRequired = task.required === true && !['deferred', 'not_started'].includes(task.status);
+  if (activeRequired && !coveredTaskIds.has(task.task_id)) {
+    const reason = `implementation_task_uncovered: ${task.task_id}`;
+    uncoveredRequiredTasks.push(reason);
+    findings.push(reason);
+  }
+  if ((task.test_required === true || task.risk === 'high') && !taskHasPassingTest(task, runs)) {
+    const reason = `implementation_task_missing_test_evidence: ${task.task_id}`;
+    missingTestEvidenceForRequiredTasks.push(reason);
+    findings.push(reason);
+  }
+}
+
+function validateTestEvidenceRun({ run, runIndex, taskById, knownScenarios, findings }) {
+  const runId = String(run?.id || `run-${runIndex}`).trim();
+  const taskRefs = Array.isArray(run?.task_refs) ? run.task_refs : [];
+  if (taskRefs.length === 0) findings.push(`implementation_alignment.test_evidence.run.${runId}.task_refs[] must not be empty`);
+  for (const taskRef of taskRefs) {
+    if (!taskById.has(taskRef)) findings.push(`implementation_alignment.test_evidence.run.${runId}.task_ref ${taskRef} not found in implementation plan`);
+  }
+  if (knownScenarios.size > 0 && Array.isArray(run?.scenario_refs)) {
+    for (const scenarioRef of run.scenario_refs) {
+      if (!knownScenarios.has(scenarioRef)) findings.push(`implementation_alignment.test_evidence.run.${runId}.scenario_ref ${scenarioRef} not found in scenario acceptance artifact`);
+    }
+  }
+}
+
+function normalizeTask(task) {
+  return {
+    task_id: String(task.task_id || '').trim(),
+    required: typeof task.required === 'boolean' ? task.required : parseBoolean(task.required),
+    status: String(task.status || '').trim(),
+    source_refs: normalizeList(task.source_refs),
+    expected_files: normalizeList(task.expected_files).map(normalizePath),
+    allowed_paths: normalizeList(task.allowed_paths).map(normalizePath),
+    expected_operations: normalizeList(task.expected_operations),
+    required_scenario_refs: normalizeList(task.required_scenario_refs),
+    test_required: typeof task.test_required === 'boolean' ? task.test_required : parseBoolean(task.test_required),
+    risk: String(task.risk || '').trim(),
+    rollback: String(task.rollback || '').trim(),
+    rationale: String(task.rationale || '').trim(),
+  };
+}
+
+function parseTaskField(key, rawValue) {
+  const value = stripQuotes(rawValue);
+  if (listFields.has(key)) return normalizeList(value);
+  if (booleanFields.has(key)) return parseBoolean(value);
+  return value;
+}
+
+function normalizeList(value) {
+  if (Array.isArray(value)) return value.map((item) => String(item).trim()).filter(Boolean);
+  return String(value || '').split(',').map((item) => stripQuotes(item).trim()).filter(Boolean);
+}
+
+function parseBoolean(value) {
+  if (value === true || value === false) return value;
+  const normalized = String(value || '').trim().toLowerCase();
+  if (normalized === 'true') return true;
+  if (normalized === 'false') return false;
+  return undefined;
+}
+
+function registrySummary(tasks) {
+  return {
+    task_count: tasks.length,
+    required_task_count: tasks.filter((task) => task.required === true).length,
+    test_required_task_count: tasks.filter((task) => task.test_required === true).length,
+    high_risk_task_count: tasks.filter((task) => task.risk === 'high').length,
+  };
+}
+
+function taskHasPassingTest(task, runs) {
+  return runs.some((run) => {
+    if (!isPassingRun(run)) return false;
+    const taskRefs = Array.isArray(run?.task_refs) ? run.task_refs : [];
+    if (!taskRefs.includes(task.task_id)) return false;
+    if (task.required_scenario_refs.length === 0) return true;
+    const scenarioRefs = new Set(Array.isArray(run?.scenario_refs) ? run.scenario_refs : []);
+    return task.required_scenario_refs.every((scenarioRef) => scenarioRefs.has(scenarioRef));
+  });
+}
+
+function isPassingRun(run) {
+  return Number.isInteger(run?.exit_code) && run.exit_code === 0 && ['pass', 'passed'].includes(String(run?.status || '').toLowerCase());
+}
+
+function pathAllowedByTask(filePath, task) {
+  if (task.expected_files.includes(filePath)) return true;
+  return task.allowed_paths.some((pattern) => pathMatchesPattern(filePath, pattern));
+}
+
+function pathMatchesPattern(filePath, pattern) {
+  const normalized = normalizePath(pattern);
+  if (!normalized) return false;
+  if (normalized.endsWith('/**')) return filePath.startsWith(normalized.slice(0, -3));
+  const regex = new RegExp(`^${escapeRegex(normalized).replace(/\\\*\\\*/g, '.*').replace(/\\\*/g, '[^/]*')}$`);
+  return regex.test(filePath);
+}
+
+function sectionBody(text, sectionName) {
+  const escaped = escapeRegex(sectionName);
+  const match = text.match(new RegExp(`(^|\\n)##\\s+${escaped}\\s*\\n([\\s\\S]*?)(?=\\n##\\s+|$)`, 'i'));
+  return match ? match[2] : '';
+}
+
+function normalizePath(value) {
+  return String(value || '').trim().replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function stripQuotes(value) {
+  return String(value || '').trim().replace(/^['"]|['"]$/g, '');
+}
+
+function escapeRegex(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function digestObject(value) {
+  return crypto.createHash('sha256').update(stableStringify(value)).digest('hex');
+}
+
+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-install-experience-command.mjs

@@ -0,0 +1,120 @@
+import {
+  localJsonFileWithinRoot,
+} from './runtime-local-json-input.mjs';
+import {
+  emitReadonlyLocalJsonOutput,
+  readonlyLocalJsonEnvelope,
+} from './runtime-readonly-local-json-output-envelope.mjs';
+import {
+  digestInstallExperience,
+  runtimeInstallExperienceDigestPayload,
+  runtimeInstallExperienceScore,
+} from './runtime-install-experience-score.mjs';
+
+function printList(title, items) {
+  if (!items || items.length === 0) return;
+  console.log(`${title}:`);
+  for (const item of items) {
+    console.log(`- ${item}`);
+  }
+}
+
+export function installExperienceEnvelope(root, bootstrapMatrixFile, entryAcceptanceFile) {
+  if (!bootstrapMatrixFile) throw new Error('platforms --install-experience requires --from-bootstrap-matrix <local-bootstrap-matrix-json>');
+  if (!entryAcceptanceFile) throw new Error('platforms --install-experience requires --from-entry-acceptance <local-entry-acceptance-json>');
+  const bootstrapInput = localJsonFileWithinRoot(root, bootstrapMatrixFile, 'platforms --install-experience --from-bootstrap-matrix');
+  const entryInput = localJsonFileWithinRoot(root, entryAcceptanceFile, 'platforms --install-experience --from-entry-acceptance');
+  const score = runtimeInstallExperienceScore({
+    bootstrapMatrix: bootstrapInput.data,
+    entryAcceptance: entryInput.data,
+    source: {
+      bootstrap_matrix_file: bootstrapInput.relative,
+      bootstrap_matrix_digest: bootstrapInput.digest,
+      entry_acceptance_file: entryInput.relative,
+      entry_acceptance_digest: entryInput.digest,
+    },
+  });
+  const installExperience = {
+    ...score,
+    install_experience_digest: digestInstallExperience(runtimeInstallExperienceDigestPayload(score)),
+  };
+  return readonlyLocalJsonEnvelope(root, {
+    mode: 'hook-adapter-install-experience-score',
+    ok: installExperience.ok,
+    payloadKey: 'install_experience_score',
+    payload: installExperience,
+    safety: {
+      stage: 'Stage 137',
+      writes: false,
+      install_experience_artifact: false,
+      bootstrap_matrix_artifact: false,
+      entry_acceptance_artifact: false,
+      adapter_install: false,
+      adapter_execution: false,
+      hook_execution: false,
+      hook_registration: false,
+      manifest_write: false,
+      install_doc_write: false,
+      settings_write: false,
+      source_write: false,
+      transcript_write: false,
+      sidecar_write: false,
+      state_directory_created: false,
+      command_execution: false,
+      check_execution: false,
+      test_execution: false,
+      workflow_execution: false,
+      skill_execution: false,
+      runtime_action: false,
+      auto_execution: false,
+      platform_api: false,
+      external_network: false,
+      model_invocation: false,
+      subagent: false,
+      mcp: false,
+      daemon: false,
+      git: false,
+      git_write: false,
+      git_add: false,
+      commit: false,
+      pr: false,
+      push: false,
+      merge: false,
+      tag: false,
+      worktree: false,
+      business_source_write: false,
+    },
+    quality: installExperience.blockers,
+    action: 'install experience score read local Stage 122 bootstrap matrix JSON and local Stage 131 entry acceptance JSON only. It scores natural entry, adapter consistency, manual steps remaining, and docs friction; install_experience_artifact=false adapter_install=false adapter_execution=false hook_execution=false command_execution=false workflow_execution=false skill_execution=false git=false git_write=false subagent=false. No hook run, adapter install, adapter run, workflow execution, skill execution, state write, platform API, model, MCP, subagent, git, or worktree action occurred.',
+  });
+}
+
+export function printInstallExperience(envelope) {
+  console.log('Vibecoding Runtime Platform Capability');
+  console.log(`Mode: ${envelope.mode}`);
+  console.log(`Stage: ${envelope.install_experience_score.stage}; Score: ${envelope.install_experience_score.score_kind}; pass=${envelope.install_experience_score.ok}`);
+  console.log(`Install experience score: ${envelope.install_experience_score.install_experience_score}; natural_entry=${envelope.install_experience_score.natural_entry_score}; adapter_consistency=${envelope.install_experience_score.adapter_consistency_score}; Digest: ${envelope.install_experience_score.install_experience_digest}`);
+  for (const row of envelope.install_experience_score.adapter_scores) console.log(`- ${row.adapter}: natural_entry=${row.natural_entry_score}; consistency=${row.adapter_consistency_score}; bootstrap=${row.bootstrap_pass}; entry_acceptance=${row.entry_acceptance_ok}`);
+  const manualSteps = envelope.install_experience_score.manual_steps_remaining.length > 0 ? envelope.install_experience_score.manual_steps_remaining : ['none'];
+  printList('Manual steps remaining', manualSteps);
+  const docsFriction = envelope.install_experience_score.docs_friction.length > 0 ? envelope.install_experience_score.docs_friction : ['none'];
+  printList('Docs friction', docsFriction);
+  if (envelope.install_experience_score.blockers.length > 0) printList('Install experience blockers', envelope.install_experience_score.blockers);
+  if (envelope.quality?.length > 0) printList('Blocked reasons', envelope.quality);
+  console.log(`Action: ${envelope.action}`);
+}
+
+export function runInstallExperienceCommand(options, deps) {
+  if (options.confirm || options.dryRun || options.write || options.run || options.autoRun || options.dispatch || options.dispatchIntent || options.scan || options.once || options.preflight) throw new Error('platforms --install-experience is read-only and report-only');
+  if (!options.fromBootstrapMatrix) throw new Error('platforms --install-experience requires --from-bootstrap-matrix <local-bootstrap-matrix-json>');
+  if (!options.fromEntryAcceptance) throw new Error('platforms --install-experience requires --from-entry-acceptance <local-entry-acceptance-json>');
+  if (options.fromFile || options.entryAdapter || options.fromSuperpowers || options.fromFriction || options.fromConsole || options.fromRunbook || options.fromEvidence || options.fromTokenBudget || options.fromLearningPattern || options.methodologyIntent || options.prompt) throw new Error('platforms --install-experience only accepts --from-bootstrap-matrix, --from-entry-acceptance, --json, and --root');
+  const envelope = installExperienceEnvelope(options.root, options.fromBootstrapMatrix, options.fromEntryAcceptance);
+  emitReadonlyLocalJsonOutput({
+    deps,
+    options,
+    channel: 'platforms',
+    envelope,
+    print: printInstallExperience,
+  });
+}