@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-experience-upgrade-prioritizer.mjs

@@ -0,0 +1,451 @@
+import crypto from 'node:crypto';
+
+const upgradeStage = 'Stage 139';
+const upgradeKind = 'experience-upgrade-prioritizer';
+const comparisonStage = 'Stage 133';
+const dashboardStage = 'Stage 132';
+const installExperienceStage = 'Stage 137';
+
+const upgradeSeeds = [
+  {
+    id: 'entry_trigger_tightening',
+    title: 'Tighten visible entry trigger discipline',
+    source_dimension: 'skill_trigger_discipline',
+    user_value: 'fewer silent workflow skips before implementation',
+    recommended_stage: 'Stage 141',
+    base_impact: 88,
+    base_risk: 18,
+    base_cost: 34,
+    kind: 'guardrail',
+  },
+  {
+    id: 'session_start_shape_examples',
+    title: 'Make session-start shape examples copy-ready',
+    source_dimension: 'session_start_bootstrap',
+    user_value: 'less command and adapter format guessing at install time',
+    recommended_stage: 'Stage 142',
+    base_impact: 82,
+    base_risk: 20,
+    base_cost: 38,
+    kind: 'install_ux',
+  },
+  {
+    id: 'next_action_evidence_prompts',
+    title: 'Promote next-action evidence prompts',
+    source_dimension: 'daily_user_friction',
+    user_value: 'one clearer next step with explicit evidence requirement',
+    recommended_stage: 'Stage 143',
+    base_impact: 90,
+    base_risk: 16,
+    base_cost: 42,
+    kind: 'daily_flow',
+  },
+  {
+    id: 'context_budget_entry_defaults',
+    title: 'Prioritize context budget entry defaults',
+    source_dimension: 'token_and_context_economy',
+    user_value: 'lower entry-token cost while keeping workflow visible',
+    recommended_stage: 'Stage 144',
+    base_impact: 76,
+    base_risk: 22,
+    base_cost: 35,
+    kind: 'token_economy',
+  },
+  {
+    id: 'local_behavior_eval_contracts',
+    title: 'Expand local behavior eval contracts',
+    source_dimension: 'eval_and_test_harness',
+    user_value: 'more behavior-shaped acceptance evidence without live model evals',
+    recommended_stage: 'Stage 145',
+    base_impact: 78,
+    base_risk: 24,
+    base_cost: 48,
+    kind: 'evidence',
+  },
+  {
+    id: 'contributor_guardrail_evidence',
+    title: 'Strengthen contributor guardrail evidence',
+    source_dimension: 'contributor_guardrails',
+    user_value: 'fewer unsafe commit, PR, or review closeout mistakes',
+    recommended_stage: 'Stage 146',
+    base_impact: 74,
+    base_risk: 26,
+    base_cost: 44,
+    kind: 'release_guardrail',
+  },
+  {
+    id: 'subagent_permission_visibility',
+    title: 'Expose subagent permission gate without enabling delegation',
+    source_dimension: 'subagent_boundary',
+    user_value: 'clearer delegation boundary without hidden agent sessions',
+    recommended_stage: 'Stage 147',
+    base_impact: 62,
+    base_risk: 44,
+    base_cost: 40,
+    kind: 'boundary_visibility',
+  },
+  {
+    id: 'adapter_packaging_consistency',
+    title: 'Improve adapter packaging consistency checklist',
+    source_dimension: 'adapter_packaging',
+    user_value: 'fewer adapter-specific installation surprises',
+    recommended_stage: 'Stage 148',
+    base_impact: 72,
+    base_risk: 28,
+    base_cost: 46,
+    kind: 'adapter_ux',
+  },
+  {
+    id: 'default_live_agent_eval_runner',
+    title: 'Default live agent eval runner',
+    source_dimension: 'eval_and_test_harness',
+    user_value: 'could increase realism but crosses the current deterministic boundary',
+    recommended_stage: 'defer',
+    base_impact: 70,
+    base_risk: 88,
+    base_cost: 84,
+    kind: 'deferred_automation',
+    force_defer: true,
+  },
+  {
+    id: 'auto_subagent_execution',
+    title: 'Automatic subagent execution',
+    source_dimension: 'subagent_boundary',
+    user_value: 'would reduce manual work but violates explicit permission first',
+    recommended_stage: 'defer',
+    base_impact: 66,
+    base_risk: 92,
+    base_cost: 76,
+    kind: 'deferred_automation',
+    force_defer: true,
+  },
+];
+
+export function runtimeExperienceUpgradePrioritizer({ comparison = {}, dashboard = {}, installExperience = null, source = {} } = {}) {
+  const matrix = unwrapComparison(comparison);
+  const experienceDashboard = unwrapDashboard(dashboard);
+  const installScorecard = installExperience ? unwrapInstallExperience(installExperience) : null;
+  const context = upgradeContext(matrix, experienceDashboard, installScorecard);
+  const candidates = upgradeSeeds.map((seed) => candidateFromSeed(seed, context));
+  const actionable = candidates
+    .filter((candidate) => !candidate.defer)
+    .sort((a, b) => b.priority_score - a.priority_score || b.impact_score - a.impact_score || a.implementation_cost - b.implementation_cost);
+  const deferred = candidates
+    .filter((candidate) => candidate.defer)
+    .sort((a, b) => b.risk_score - a.risk_score || b.implementation_cost - a.implementation_cost);
+  const core = {
+    version: 1,
+    stage: upgradeStage,
+    prioritizer_kind: upgradeKind,
+    source_bindings: sourceBindingSummary(source, matrix, experienceDashboard, installScorecard),
+    input_summary: inputSummary(matrix, experienceDashboard, installScorecard),
+    upgrade_candidates: candidates,
+    recommended_stage_order: actionable.map((candidate) => ({
+      stage: candidate.recommended_stage,
+      candidate_id: candidate.id,
+      priority_score: candidate.priority_score,
+      why: candidate.why_now,
+    })),
+    defer: deferred.map((candidate) => ({
+      candidate_id: candidate.id,
+      reason: candidate.defer_reason,
+      risk_score: candidate.risk_score,
+      boundary: candidate.boundary,
+    })),
+    prioritization_policy: prioritizationPolicy(),
+    next_upgrade_bet: nextUpgradeBet(actionable, deferred),
+    boundary_assertions: runtimeExperienceUpgradePrioritizerBoundaryAssertions(),
+    writes: false,
+    state_directory_created: false,
+    local_only: true,
+    deterministic: true,
+  };
+  const invariants = runtimeExperienceUpgradePrioritizerInvariants(core);
+  const prioritizer = {
+    ...core,
+    ok: invariants.pass,
+    upgrade_invariants: invariants,
+  };
+  return {
+    ...prioritizer,
+    upgrade_digest: digestExperienceUpgradePrioritizer(runtimeExperienceUpgradePrioritizerDigestPayload(prioritizer)),
+  };
+}
+
+export function runtimeExperienceUpgradePrioritizerDigestPayload(prioritizer) {
+  return {
+    stage: prioritizer.stage,
+    prioritizer_kind: prioritizer.prioritizer_kind,
+    source_bindings: prioritizer.source_bindings,
+    input_summary: prioritizer.input_summary,
+    upgrade_candidates: prioritizer.upgrade_candidates,
+    recommended_stage_order: prioritizer.recommended_stage_order,
+    defer: prioritizer.defer,
+    prioritization_policy: prioritizer.prioritization_policy,
+    next_upgrade_bet: prioritizer.next_upgrade_bet,
+    boundary_assertions: prioritizer.boundary_assertions,
+    upgrade_invariants: prioritizer.upgrade_invariants,
+  };
+}
+
+export function runtimeExperienceUpgradePrioritizerBoundaryAssertions() {
+  return {
+    upgrade_artifact: false,
+    prioritizer_artifact: false,
+    comparison_artifact: false,
+    dashboard_artifact: false,
+    install_experience_artifact: false,
+    source_write: false,
+    sidecar_write: false,
+    state_directory_created: false,
+    command_execution: false,
+    check_execution: false,
+    smoke_execution: false,
+    test_execution: false,
+    eval_execution: false,
+    verification_execution: false,
+    workflow_execution: false,
+    skill_execution: false,
+    runtime_action: false,
+    auto_execution: false,
+    repair_execution: false,
+    prompt_mutation: false,
+    hook_registration: false,
+    dynamic_tool_execution: false,
+    embeddings: false,
+    remote_config: 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,
+  };
+}
+
+export function runtimeExperienceUpgradePrioritizerInvariants(prioritizer) {
+  const candidates = Array.isArray(prioritizer.upgrade_candidates) ? prioritizer.upgrade_candidates : [];
+  const candidateIds = candidates.map((candidate) => candidate.id);
+  const duplicateCandidates = candidateIds.filter((id, index, values) => values.indexOf(id) !== index);
+  const unsafeBoundaries = Object.entries(prioritizer.boundary_assertions || {})
+    .filter(([, value]) => value !== false)
+    .map(([key]) => key);
+  const missingForbidden = Object.keys(runtimeExperienceUpgradePrioritizerBoundaryAssertions())
+    .filter((key) => prioritizer.boundary_assertions?.[key] !== false);
+  const scoreFindings = candidates.flatMap((candidate) => ['impact_score', 'risk_score', 'implementation_cost', 'priority_score']
+    .flatMap((field) => integerInRange(candidate[field], 0, 100) ? [] : [`${candidate.id}.${field} must be integer 0..100`]));
+  const forbiddenActionable = candidates
+    .filter((candidate) => candidate.kind === 'deferred_automation' && !candidate.defer)
+    .map((candidate) => candidate.id);
+  const findings = [
+    ...(prioritizer.stage === upgradeStage ? [] : [`stage must be ${upgradeStage}`]),
+    ...(prioritizer.prioritizer_kind === upgradeKind ? [] : [`prioritizer_kind must be ${upgradeKind}`]),
+    ...(prioritizer.source_bindings?.comparison_file ? [] : ['comparison file binding is required']),
+    ...(prioritizer.source_bindings?.dashboard_file ? [] : ['dashboard file binding is required']),
+    ...(prioritizer.input_summary?.comparison_stage === comparisonStage ? [] : [`comparison stage must be ${comparisonStage}`]),
+    ...(prioritizer.input_summary?.dashboard_stage === dashboardStage ? [] : [`dashboard stage must be ${dashboardStage}`]),
+    ...(Array.isArray(prioritizer.recommended_stage_order) && prioritizer.recommended_stage_order.length > 0 ? [] : ['recommended_stage_order must be non-empty']),
+    ...(Array.isArray(prioritizer.defer) && prioritizer.defer.length > 0 ? [] : ['defer must include explicitly deferred unsafe upgrades']),
+    ...(candidates.length === upgradeSeeds.length ? [] : [`upgrade_candidates must contain ${upgradeSeeds.length} candidates`]),
+    ...duplicateCandidates.map((id) => `duplicate upgrade candidate: ${id}`),
+    ...scoreFindings,
+    ...forbiddenActionable.map((id) => `deferred automation candidate must not be actionable: ${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: ['stage_133_comparison_binding', 'stage_132_dashboard_binding', 'optional_stage_137_install_binding', 'candidate_scores', 'recommended_stage_order', 'defer_unsafe_automation', 'read_only_boundary_assertions'],
+    findings,
+  };
+}
+
+export function digestExperienceUpgradePrioritizer(value) {
+  return crypto.createHash('sha256').update(stableStringify(value)).digest('hex');
+}
+
+function unwrapComparison(input) {
+  return input.superpowers_comparison_matrix || input.comparison || input;
+}
+
+function unwrapDashboard(input) {
+  return input.experience_regression_dashboard || input.dashboard || input;
+}
+
+function unwrapInstallExperience(input) {
+  return input.install_experience_scorecard || input.install_experience || input;
+}
+
+function upgradeContext(matrix, dashboard, installScorecard) {
+  const parityGapDimensions = new Set(listValue(matrix.parity_gaps).map((gap) => stringValue(gap.dimension || gap.id)));
+  const dimensionById = new Map(listValue(matrix.dimensions).map((dimension) => [stringValue(dimension.id), dimension]));
+  const dashboardScore = numberValue(dashboard.experience_scorecard?.overall_experience_score, 50);
+  const frictionScore = numberValue(dashboard.daily_user_friction_delta?.friction_score, 50);
+  const installScore = installScorecard ? numberValue(installScorecard.install_experience_score, 50) : 50;
+  const manualSteps = installScorecard ? listValue(installScorecard.manual_steps_remaining).length : 0;
+  const blockers = [
+    ...listValue(dashboard.regression_blockers),
+    ...(installScorecard ? listValue(installScorecard.blockers) : []),
+  ];
+  return {
+    parityGapDimensions,
+    dimensionById,
+    dashboardScore,
+    frictionScore,
+    installScore,
+    manualSteps,
+    blockerCount: blockers.length,
+    installProvided: Boolean(installScorecard),
+  };
+}
+
+function candidateFromSeed(seed, context) {
+  const dimension = context.dimensionById.get(seed.source_dimension) || {};
+  const comparisonGap = context.parityGapDimensions.has(seed.source_dimension) || numberValue(dimension.delta, 0) > 0;
+  const dashboardPressure = clamp(100 - context.dashboardScore, 0, 100);
+  const frictionPressure = clamp(context.frictionScore, 0, 100);
+  const installPressure = seed.kind.includes('install') || seed.kind.includes('adapter') ? clamp(100 - context.installScore + (context.manualSteps * 4), 0, 100) : 0;
+  const impact = clampScore(seed.base_impact + (comparisonGap ? 8 : -4) + Math.round(dashboardPressure * 0.12) + Math.round(frictionPressure * 0.08) + Math.round(installPressure * 0.10));
+  const risk = clampScore(seed.base_risk + (seed.kind === 'boundary_visibility' ? context.blockerCount * 3 : 0) + (seed.force_defer ? 0 : Math.round(installPressure * 0.05)));
+  const cost = clampScore(seed.base_cost + (context.installProvided ? 0 : 6) + (comparisonGap ? 0 : 4));
+  const priority = seed.force_defer ? 0 : clampScore(Math.round((impact * 0.55) + ((100 - risk) * 0.25) + ((100 - cost) * 0.20)));
+  const defer = seed.force_defer || risk >= 75 || cost >= 85;
+  return {
+    id: seed.id,
+    title: seed.title,
+    kind: seed.kind,
+    source_dimension: seed.source_dimension,
+    user_value: seed.user_value,
+    recommended_stage: seed.recommended_stage,
+    impact_score: impact,
+    risk_score: risk,
+    implementation_cost: cost,
+    priority_score: priority,
+    comparison_gap: comparisonGap,
+    confidence: confidenceFor(seed, context, dimension),
+    why_now: whyNow(seed, comparisonGap, dashboardPressure, frictionPressure, installPressure),
+    boundary: boundaryFor(seed),
+    defer,
+    defer_reason: defer ? deferReason(seed, risk, cost) : '',
+  };
+}
+
+function confidenceFor(seed, context, dimension) {
+  const hasDimension = Boolean(dimension.id);
+  const hasDashboard = context.dashboardScore > 0;
+  const installRelevant = seed.kind.includes('install') || seed.kind.includes('adapter');
+  const hasInstall = !installRelevant || context.installProvided;
+  const score = [hasDimension, hasDashboard, hasInstall].filter(Boolean).length;
+  return score === 3 ? 'high' : score === 2 ? 'medium' : 'low';
+}
+
+function whyNow(seed, comparisonGap, dashboardPressure, frictionPressure, installPressure) {
+  const reasons = [];
+  if (comparisonGap) reasons.push(`comparison gap on ${seed.source_dimension}`);
+  if (dashboardPressure >= 20) reasons.push('experience dashboard has improvement pressure');
+  if (frictionPressure >= 35) reasons.push('daily friction remains visible');
+  if (installPressure >= 20) reasons.push('install experience still has manual steps');
+  return reasons.length > 0 ? reasons.join('; ') : `protect ${seed.user_value}`;
+}
+
+function boundaryFor(seed) {
+  if (seed.kind === 'deferred_automation') return 'deferred: would cross live execution, model, subagent, or automation boundary';
+  if (seed.kind === 'boundary_visibility') return 'visible permission gate only; no subagent dispatch';
+  if (seed.kind === 'evidence') return 'local contract expansion only; no live eval or model judge';
+  return 'local deterministic contract or documentation/checklist improvement only; no execution';
+}
+
+function deferReason(seed, risk, cost) {
+  if (seed.force_defer) return 'outside current deterministic local boundary';
+  if (risk >= 75) return `risk score ${risk} is too high for the next cycle`;
+  if (cost >= 85) return `implementation cost ${cost} is too high for the next cycle`;
+  return 'deferred by prioritization policy';
+}
+
+function sourceBindingSummary(source, matrix, dashboard, installScorecard) {
+  return {
+    comparison_file: stringValue(source.comparison_file),
+    comparison_digest: stringValue(source.comparison_digest || matrix.comparison_digest),
+    dashboard_file: stringValue(source.dashboard_file),
+    dashboard_digest: stringValue(source.dashboard_digest || dashboard.dashboard_digest),
+    install_experience_file: stringValue(source.install_experience_file),
+    install_experience_digest: stringValue(source.install_experience_digest || installScorecard?.install_experience_digest),
+    install_experience_provided: Boolean(installScorecard),
+  };
+}
+
+function inputSummary(matrix, dashboard, installScorecard) {
+  return {
+    comparison_stage: stringValue(matrix.stage),
+    comparison_kind: stringValue(matrix.comparison_kind),
+    parity_gap_count: listValue(matrix.parity_gaps).length,
+    borrowable_pattern_count: listValue(matrix.borrowable_patterns).length,
+    dashboard_stage: stringValue(dashboard.stage),
+    dashboard_kind: stringValue(dashboard.dashboard_kind),
+    overall_experience_score: numberValue(dashboard.experience_scorecard?.overall_experience_score, 0),
+    regression_blocker_count: listValue(dashboard.regression_blockers).length,
+    install_experience_stage: installScorecard ? stringValue(installScorecard.stage) : '',
+    install_experience_score: installScorecard ? numberValue(installScorecard.install_experience_score, 0) : 0,
+    install_experience_provided: Boolean(installScorecard),
+  };
+}
+
+function prioritizationPolicy() {
+  return {
+    priority_formula: 'impact_score 55% + inverse risk 25% + inverse implementation_cost 20%',
+    prefer: ['save one daily decision', 'make evidence requirements visible', 'reduce command discovery', 'preserve local deterministic boundaries'],
+    defer_when: ['default live agent eval required', 'automatic subagent execution required', 'platform API or network required', 'git/PR/push/merge side effect required'],
+  };
+}
+
+function nextUpgradeBet(actionable, deferred) {
+  const first = actionable[0];
+  return {
+    target_stage: first?.recommended_stage || 'none',
+    candidate_id: first?.id || 'none',
+    action: first ? `Implement ${first.title} as the next local deterministic experience upgrade.` : 'No safe upgrade candidate is currently actionable.',
+    deferred_count: deferred.length,
+  };
+}
+
+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);
+}
+
+function listValue(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function stringValue(value) {
+  return typeof value === 'string' ? value : '';
+}
+
+function numberValue(value, fallback = 0) {
+  return Number.isFinite(value) ? Number(value) : fallback;
+}
+
+function integerInRange(value, min, max) {
+  return Number.isInteger(value) && value >= min && value <= max;
+}
+
+function clampScore(value) {
+  return clamp(Math.round(Number.isFinite(value) ? value : 0), 0, 100);
+}
+
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(max, value));
+}