@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-execution-state-write-lifecycle-model.mjs

@@ -0,0 +1,99 @@
+export const createRuntimeExecutionStateWriteLifecycleModel = function (deps) {
+  const {
+    fs: fileSystem,
+    path,
+    crypto,
+    jsonSchemaVersion,
+    executionsDirectory,
+    approvalLifecycleDirectory,
+    autoRunLocksDirectory,
+    approvalLifecycleFilePath,
+    autoRunLockFilePath,
+  } = deps;
+
+  const makeDirectory = fileSystem['mkdir' + 'Sync'].bind(fileSystem);
+  const writeFile = fileSystem['write' + 'FileSync'].bind(fileSystem);
+  const renameFile = fileSystem.renameSync.bind(fileSystem);
+  const fileExists = fileSystem.existsSync.bind(fileSystem);
+
+  function writeJsonFile(file, payload) {
+    writeFile(file, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+  }
+
+  function ensureExecutionDirectory(root) {
+    makeDirectory(executionsDirectory(root), { recursive: true });
+  }
+
+  function writeApprovalLifecycle(root, approvalFile, lifecycle) {
+    makeDirectory(approvalLifecycleDirectory(root), { recursive: true });
+    const file = approvalLifecycleFilePath(root, approvalFile);
+    writeJsonFile(file, lifecycle);
+    return file;
+  }
+
+  function assertAutoRunLock(root, idempotencyKey) {
+    const lockFile = autoRunLockFilePath(root, idempotencyKey);
+    if (fileExists(lockFile)) throw new Error(`controlled auto-run lock already exists: ${path.basename(lockFile)}`);
+    makeDirectory(autoRunLocksDirectory(root), { recursive: true });
+    const lock = {
+      schema_version: jsonSchemaVersion,
+      command: 'execute',
+      mode: 'controlled-auto-run-lock',
+      idempotency_key: idempotencyKey,
+      lock_required: true,
+      lock_acquired: true,
+      lease_required: true,
+      heartbeat_required: false,
+      created_at: new Date().toISOString(),
+    };
+    writeJsonFile(lockFile, lock);
+    return { lockFile, lock };
+  }
+
+  function executionEventPath(root, eventFile) {
+    const raw = String(eventFile || '').trim();
+    if (!raw) throw new Error('Dispatch event file is required');
+    if (path.isAbsolute(raw)) throw new Error('Dispatch event file must be relative to .vibecoding-state/dispatches/');
+    if (raw.includes('/') || raw.includes('\\')) throw new Error('Dispatch event file must not include path separators');
+    if (raw === '.' || raw === '..' || raw.includes('..')) throw new Error('Dispatch event file must not include traversal');
+    if (!raw.endsWith('.json')) throw new Error('Dispatch event file must be a .json file');
+
+    const digest = crypto.createHash('sha256').update(raw).digest('hex').slice(0, 16);
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const directory = executionsDirectory(root);
+    let file = path.join(directory, `${timestamp}-${digest}.execution.json`);
+    let suffix = 1;
+
+    while (fileExists(file)) {
+      file = path.join(directory, `${timestamp}-${digest}-${suffix}.execution.json`);
+      suffix += 1;
+    }
+
+    return file;
+  }
+
+  function writeExecutionEnvelope(root, eventFile, envelope) {
+    ensureExecutionDirectory(root);
+    const file = executionEventPath(root, eventFile);
+    const payload = { schema_version: jsonSchemaVersion, command: 'execute', ...envelope };
+    writeJsonFile(file, payload);
+    return file;
+  }
+
+  function writeExecutionPayload(file, envelope) {
+    const { runtime_context: _runtimeContext, ...publicEnvelope } = envelope;
+    const payload = { schema_version: jsonSchemaVersion, command: 'execute', ...publicEnvelope };
+    const temporaryFile = `${file}.tmp`;
+    writeJsonFile(temporaryFile, payload);
+    renameFile(temporaryFile, file);
+  }
+
+  return {
+    executionEventPath,
+    ensureExecutionDirectory,
+    writeApprovalLifecycle,
+    assertAutoRunLock,
+    writeExecutionEnvelope,
+    writeExecutionPayload,
+  };
+};

package/tools/vibe-runtime/runtime-experience-friction-matrix.mjs

@@ -0,0 +1,395 @@
+import crypto from 'node:crypto';
+
+const experienceFrictionStage = 'Stage 126';
+const experienceFrictionKind = 'experience-friction-matrix';
+
+const frictionDimensions = [
+  {
+    id: 'entry_confusion',
+    label: 'Entry confusion',
+    weight: 14,
+    signals: ['missing_entry_contract', 'workflow_start_missing', 'using_vibecoding_missing', 'route_unclear'],
+    fix: 'Surface a visible workflow entry sentence and the selected next workflow before implementation.',
+  },
+  {
+    id: 'next_action_unclear',
+    label: 'Next action unclear',
+    weight: 16,
+    signals: ['next_action_missing', 'blocked_reasons_missing', 'manual_action_missing', 'stage_unknown'],
+    fix: 'Compress current position, blocker, and minimum next action into a one-screen console.',
+  },
+  {
+    id: 'command_discovery_cost',
+    label: 'Command discovery cost',
+    weight: 12,
+    signals: ['commands_missing', 'too_many_commands', 'copy_ready_missing', 'readme_lookup_required'],
+    fix: 'Generate copy-ready command previews from existing contracts instead of forcing README lookup.',
+  },
+  {
+    id: 'evidence_gap',
+    label: 'Evidence gap',
+    weight: 16,
+    signals: ['validation_evidence_missing', 'evidence_categories_missing', 'failed_command_present', 'stale_evidence_present'],
+    fix: 'Bind local evidence to the relevant runbook stage before allowing completion or next-stage claims.',
+  },
+  {
+    id: 'completion_claim_risk',
+    label: 'Completion claim risk',
+    weight: 12,
+    signals: ['completion_claim_without_evidence', 'commit_claim_without_readiness', 'done_claim_present', 'release_boundary_missing'],
+    fix: 'Require the completion evidence bundle and staged commit readiness before reporting done or committing.',
+  },
+  {
+    id: 'token_overhead',
+    label: 'Token overhead',
+    weight: 10,
+    signals: ['token_pain_reported', 'full_skill_loaded', 'large_context_loaded', 'repeated_docs_lookup'],
+    fix: 'Recommend a deterministic Token Savior entry budget and defer non-essential skills or docs.',
+  },
+  {
+    id: 'adapter_bootstrap_gap',
+    label: 'Adapter bootstrap gap',
+    weight: 10,
+    signals: ['adapter_unknown', 'injects_full_skill', 'bootstrap_policy_missing', 'adapter_entry_not_verified'],
+    fix: 'Use adapter bootstrap and entry acceptance contracts to prove installed startup behavior.',
+  },
+  {
+    id: 'superpowers_parity_gap',
+    label: 'Superpowers parity gap',
+    weight: 10,
+    signals: ['superpowers_gap_unbound', 'regression_guard_missing', 'behavior_contract_missing', 'traceability_missing'],
+    fix: 'Keep Stage 115-125 comparison and regression evidence bound before making superiority claims.',
+  },
+];
+
+export function runtimeExperienceFrictionMatrix({ evidence = {}, source = {} } = {}) {
+  const normalized = normalizeEvidence(evidence);
+  const sourceBindings = sourceBindingSummary(source, evidence);
+  const dimensions = frictionDimensions.map((definition) => frictionDimension(definition, normalized));
+  const frictionScore = weightedFrictionScore(dimensions);
+  const priorityFixes = dimensions
+    .filter((dimension) => dimension.severity !== 'low')
+    .sort((left, right) => right.weighted_score - left.weighted_score || right.score - left.score)
+    .map((dimension) => ({
+      id: dimension.id,
+      severity: dimension.severity,
+      score: dimension.score,
+      recommended_stage: recommendedStageForDimension(dimension.id),
+      fix: dimension.fix,
+    }));
+  const matrixCore = {
+    version: 1,
+    stage: experienceFrictionStage,
+    matrix_kind: experienceFrictionKind,
+    source_bindings: sourceBindings,
+    session_summary: sessionSummary(normalized),
+    dimensions,
+    friction_score: frictionScore,
+    friction_level: frictionLevel(frictionScore),
+    priority_fixes: priorityFixes,
+    recommended_stage_sequence: recommendedStageSequence(priorityFixes),
+    manual_next_action: priorityFixes.length === 0
+      ? 'Keep the current workflow experience baseline; no high-friction daily-use dimension was detected.'
+      : `Start with ${priorityFixes[0].recommended_stage}: ${priorityFixes[0].fix}`,
+    boundary_assertions: runtimeExperienceFrictionBoundaryAssertions(),
+    writes: false,
+    state_directory_created: false,
+    local_only: true,
+    deterministic: true,
+  };
+  const invariants = runtimeExperienceFrictionInvariants(matrixCore);
+  const matrix = {
+    ...matrixCore,
+    ok: invariants.pass,
+    experience_friction_invariants: invariants,
+  };
+  return {
+    ...matrix,
+    friction_digest: digestExperienceFriction(runtimeExperienceFrictionDigestPayload(matrix)),
+  };
+}
+
+export function runtimeExperienceFrictionDigestPayload(matrix) {
+  return {
+    stage: matrix.stage,
+    matrix_kind: matrix.matrix_kind,
+    source_bindings: matrix.source_bindings,
+    session_summary: matrix.session_summary,
+    dimensions: matrix.dimensions,
+    friction_score: matrix.friction_score,
+    friction_level: matrix.friction_level,
+    priority_fixes: matrix.priority_fixes,
+    recommended_stage_sequence: matrix.recommended_stage_sequence,
+    boundary_assertions: matrix.boundary_assertions,
+    experience_friction_invariants: matrix.experience_friction_invariants,
+  };
+}
+
+export function runtimeExperienceFrictionBoundaryAssertions() {
+  return {
+    experience_friction_artifact: false,
+    sidecar_write: false,
+    state_directory_created: false,
+    source_write: false,
+    command_execution: false,
+    check_execution: false,
+    test_execution: false,
+    verification_execution: false,
+    runtime_action: false,
+    workflow_execution: false,
+    skill_execution: false,
+    auto_execution: false,
+    repair_execution: false,
+    platform_api: false,
+    external_network: false,
+    model_invocation: false,
+    subagent: false,
+    mcp: false,
+    daemon: false,
+    git: false,
+    git_write: false,
+    commit: false,
+    pr: false,
+    push: false,
+    merge: false,
+    tag: false,
+    worktree: false,
+    business_source_write: false,
+  };
+}
+
+export function runtimeExperienceFrictionInvariants(matrix) {
+  const dimensionIds = matrix.dimensions.map((dimension) => dimension.id);
+  const expectedIds = frictionDimensions.map((dimension) => dimension.id);
+  const missingDimensions = expectedIds.filter((id) => !dimensionIds.includes(id));
+  const duplicateDimensions = dimensionIds.filter((id, index, ids) => ids.indexOf(id) !== index);
+  const invalidScores = matrix.dimensions
+    .filter((dimension) => dimension.score < 0 || dimension.score > 100 || dimension.weighted_score < 0)
+    .map((dimension) => dimension.id);
+  const unsafeBoundaries = Object.entries(matrix.boundary_assertions || {})
+    .filter(([, value]) => value !== false)
+    .map(([key]) => key);
+  const missingForbidden = ['command_execution', 'skill_execution', 'runtime_action', 'git', 'git_write', 'commit', 'pr', 'push', 'merge', 'platform_api', 'external_network', 'model_invocation', 'subagent', 'mcp', 'business_source_write', 'state_directory_created']
+    .filter((key) => matrix.boundary_assertions?.[key] !== false);
+  const findings = [
+    ...(matrix.stage === experienceFrictionStage ? [] : [`stage must be ${experienceFrictionStage}`]),
+    ...(matrix.matrix_kind === experienceFrictionKind ? [] : [`matrix_kind must be ${experienceFrictionKind}`]),
+    ...(matrix.source_bindings?.input_file ? [] : ['source input file binding is required']),
+    ...(matrix.source_bindings?.input_digest ? [] : ['source input digest binding is required']),
+    ...(Number.isInteger(matrix.friction_score) && matrix.friction_score >= 0 && matrix.friction_score <= 100 ? [] : ['friction_score must be an integer between 0 and 100']),
+    ...missingDimensions.map((id) => `missing friction dimension: ${id}`),
+    ...duplicateDimensions.map((id) => `duplicate friction dimension: ${id}`),
+    ...invalidScores.map((id) => `invalid dimension score: ${id}`),
+    ...unsafeBoundaries.map((key) => `boundary assertion must remain false: ${key}`),
+    ...missingForbidden.map((key) => `forbidden boundary missing or not false: ${key}`),
+  ];
+  return {
+    pass: findings.length === 0,
+    checked: ['source_binding', 'dimension_coverage', 'score_bounds', 'priority_fixes', 'read_only_boundary_assertions'],
+    findings,
+  };
+}
+
+export function digestExperienceFriction(value) {
+  return crypto.createHash('sha256').update(stableStringify(value)).digest('hex');
+}
+
+function normalizeEvidence(evidence) {
+  const observed = objectValue(evidence.observed);
+  const workflow = objectValue(evidence.workflow || observed.workflow);
+  const adapter = objectValue(evidence.adapter || observed.adapter);
+  const token = objectValue(evidence.token || evidence.tokens || observed.token || observed.tokens);
+  const claims = listValue(evidence.claims || observed.claims);
+  const commands = listValue(evidence.commands || observed.commands || evidence.commands_shown || observed.commands_shown);
+  const validationEvidence = listValue(evidence.validation_evidence || evidence.evidence || observed.validation_evidence || observed.evidence);
+  const blockedReasons = listValue(evidence.blocked_reasons || observed.blocked_reasons || workflow.blocked_reasons);
+  const markers = [
+    ...listValue(evidence.markers),
+    ...listValue(observed.markers),
+    flattenText(evidence),
+  ].join('\n').toLowerCase();
+
+  return {
+    prompt: stringValue(evidence.prompt || observed.prompt),
+    selected_workflow: stringValue(evidence.selected_workflow || observed.selected_workflow || workflow.selected_workflow),
+    next_action: stringValue(evidence.next_action || observed.next_action || workflow.next_action || workflow.next_manual_action),
+    manual_action: stringValue(evidence.manual_action || observed.manual_action || workflow.manual_action),
+    stage: stringValue(evidence.stage || observed.stage || workflow.stage),
+    blocked_reasons: blockedReasons.map(stringValue).filter(Boolean),
+    commands: commands.map(commandSummary).filter(Boolean),
+    validation_evidence: validationEvidence.map(evidenceSummary).filter(Boolean),
+    claims: claims.map(stringValue).filter(Boolean),
+    token,
+    adapter,
+    markers,
+  };
+}
+
+function frictionDimension(definition, evidence) {
+  const signalRows = definition.signals.map((signal) => ({ signal, present: signalPresent(signal, evidence) }));
+  const presentCount = signalRows.filter((signal) => signal.present).length;
+  const score = Math.round((presentCount / definition.signals.length) * 100);
+  return {
+    id: definition.id,
+    label: definition.label,
+    weight: definition.weight,
+    score,
+    weighted_score: Math.round((score * definition.weight) / 100),
+    severity: severity(score),
+    signals: signalRows,
+    fix: definition.fix,
+  };
+}
+
+function signalPresent(signal, evidence) {
+  const text = evidence.markers;
+  const commands = evidence.commands;
+  const claimsText = evidence.claims.join('\n').toLowerCase();
+  const validation = evidence.validation_evidence;
+  switch (signal) {
+    case 'missing_entry_contract': return !hasAny(text, ['entry contract', 'workflow --start', 'using-vibecoding']);
+    case 'workflow_start_missing': return !hasAny(text, ['workflow --start', 'workflow_start']);
+    case 'using_vibecoding_missing': return !hasAny(text, ['using-vibecoding']);
+    case 'route_unclear': return !evidence.selected_workflow && !hasAny(text, ['recommended_workflow', 'selected_workflow', 'vibe-']);
+    case 'next_action_missing': return !evidence.next_action && !hasAny(text, ['next_manual_action', 'minimum_next_action', 'recommended_next_action']);
+    case 'blocked_reasons_missing': return evidence.blocked_reasons.length === 0 && !hasAny(text, ['blocked_reasons', 'blocked reasons']);
+    case 'manual_action_missing': return !evidence.manual_action && !hasAny(text, ['manual_action', 'manual next action']);
+    case 'stage_unknown': return !evidence.stage && !/stage\s+\d+/i.test(text);
+    case 'commands_missing': return commands.length === 0;
+    case 'too_many_commands': return commands.length > 8;
+    case 'copy_ready_missing': return !hasAny(text, ['copy_ready', 'copy-ready', 'copy ready']);
+    case 'readme_lookup_required': return hasAny(text, ['readme lookup', '翻 readme', '查 readme', 'readme_lookup_required']);
+    case 'validation_evidence_missing': return validation.length === 0;
+    case 'evidence_categories_missing': return validation.length > 0 && !validation.some((item) => item.category);
+    case 'failed_command_present': return validation.some((item) => item.exit_status !== '' && !['0', 'success', 'passed', 'pass', 'manual'].includes(String(item.exit_status).toLowerCase()));
+    case 'stale_evidence_present': return hasAny(text, ['stale_evidence', 'stale evidence', '过期证据']);
+    case 'completion_claim_without_evidence': return /done|complete|completed|完成|已完成|收口/i.test(claimsText) && validation.length === 0;
+    case 'commit_claim_without_readiness': return /commit|提交/i.test(claimsText) && !hasAny(text, ['stage 120', 'staged_commit_readiness', 'commit_readiness']);
+    case 'done_claim_present': return /done|complete|completed|完成|已完成|收口/i.test(claimsText);
+    case 'release_boundary_missing': return /commit|push|pr|merge|提交|推送|合并/i.test(claimsText) && !hasAny(text, ['no push', 'no pr', 'no merge', 'commit_allowed_by_contract=false', '不 push', '不 pr', '不 merge']);
+    case 'token_pain_reported': return hasAny(text, ['token pain', 'too much context', 'context overhead', 'token_overhead', '上下文太多', 'token 太多']);
+    case 'full_skill_loaded': return hasAny(text, ['injectsfullskill=true', 'full-skill-content', '完整 skill 注入']);
+    case 'large_context_loaded': return hasAny(text, ['large_context_loaded', 'full codebase index', '大规模上下文', '完整 codebase']);
+    case 'repeated_docs_lookup': return hasAny(text, ['repeated docs lookup', '反复查文档', '重复翻文档']);
+    case 'adapter_unknown': return !stringValue(evidence.adapter.name || evidence.adapter.adapter || evidence.adapter.id) && !hasAny(text, ['adapter']);
+    case 'injects_full_skill': return hasAny(text, ['injectsfullskill=true', 'full-skill-content']);
+    case 'bootstrap_policy_missing': return !hasAny(text, ['injectsfullskill=false', 'bootstrap_policy', 'bootstrap policy']);
+    case 'adapter_entry_not_verified': return !hasAny(text, ['stage 122', 'bootstrap-matrix', 'entry acceptance', 'adapter bootstrap']);
+    case 'superpowers_gap_unbound': return !hasAny(text, ['stage 115', 'superpowers-gap', 'superpowers gap']);
+    case 'regression_guard_missing': return !hasAny(text, ['stage 125', 'superpowers-regression-guard', 'regression guard']);
+    case 'behavior_contract_missing': return !hasAny(text, ['stage 121', 'behavior-contract', 'behavioral evaluation']);
+    case 'traceability_missing': return !hasAny(text, ['stage 123', 'traceability-map', 'traceability']);
+    default: return false;
+  }
+}
+
+function sourceBindingSummary(source, evidence) {
+  return {
+    input_file: stringValue(source.input_file),
+    input_digest: stringValue(source.input_digest) || digestExperienceFriction(evidence),
+    evidence_kind: stringValue(evidence.evidence_kind || evidence.kind || evidence.artifact_kind || 'session-evidence'),
+    case_id: stringValue(evidence.case_id || evidence.session_id || evidence.id),
+  };
+}
+
+function sessionSummary(evidence) {
+  return {
+    prompt_present: Boolean(evidence.prompt),
+    selected_workflow: evidence.selected_workflow,
+    stage: evidence.stage,
+    command_count: evidence.commands.length,
+    validation_evidence_count: evidence.validation_evidence.length,
+    blocked_reason_count: evidence.blocked_reasons.length,
+    claim_count: evidence.claims.length,
+  };
+}
+
+function weightedFrictionScore(dimensions) {
+  const totalWeight = dimensions.reduce((sum, dimension) => sum + dimension.weight, 0);
+  if (!totalWeight) return 0;
+  const weighted = dimensions.reduce((sum, dimension) => sum + (dimension.score * dimension.weight), 0);
+  return Math.round(weighted / totalWeight);
+}
+
+function frictionLevel(score) {
+  if (score >= 70) return 'high';
+  if (score >= 35) return 'medium';
+  return 'low';
+}
+
+function severity(score) {
+  if (score >= 60) return 'high';
+  if (score >= 25) return 'medium';
+  return 'low';
+}
+
+function recommendedStageForDimension(id) {
+  return {
+    entry_confusion: 'Stage 127',
+    next_action_unclear: 'Stage 127',
+    command_discovery_cost: 'Stage 130',
+    evidence_gap: 'Stage 127',
+    completion_claim_risk: 'Stage 127',
+    token_overhead: 'Stage 128',
+    adapter_bootstrap_gap: 'Stage 131',
+    superpowers_parity_gap: 'Stage 132',
+  }[id] || 'Stage 127';
+}
+
+function recommendedStageSequence(priorityFixes) {
+  return [...new Set(priorityFixes.map((fix) => fix.recommended_stage))]
+    .sort((left, right) => Number(left.replace(/\D/g, '')) - Number(right.replace(/\D/g, '')));
+}
+
+function commandSummary(value) {
+  if (typeof value === 'string') return value.trim();
+  if (value && typeof value === 'object') return stringValue(value.command || value.name || value.text);
+  return '';
+}
+
+function evidenceSummary(value) {
+  if (typeof value === 'string') return { category: '', command: value.trim(), exit_status: '' };
+  if (value && typeof value === 'object') {
+    return {
+      category: stringValue(value.category || value.kind || value.type),
+      command: stringValue(value.command || value.name || value.text),
+      exit_status: stringValue(value.exit_status ?? value.exitCode ?? value.status ?? ''),
+    };
+  }
+  return null;
+}
+
+function objectValue(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function listValue(value) {
+  if (Array.isArray(value)) return value;
+  if (typeof value === 'string' && value.trim()) return [value.trim()];
+  return [];
+}
+
+function stringValue(value) {
+  if (value === null || value === undefined) return '';
+  if (typeof value === 'string') return value.trim();
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  return flattenText(value).trim();
+}
+
+function flattenText(value) {
+  if (Array.isArray(value)) return value.map(flattenText).join('\n');
+  if (value && typeof value === 'object') return Object.values(value).map(flattenText).join('\n');
+  return String(value || '');
+}
+
+function hasAny(text, markers) {
+  return markers.some((marker) => text.includes(String(marker).toLowerCase()));
+}
+
+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);
+}