@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-durable-state-recovery-contract.mjs

@@ -0,0 +1,172 @@
+const CONTRACT_STAGE = 'stage-3-durable-state-recovery';
+const CONTRACT_KIND = 'durable-state-recovery-contract';
+
+const lockTerm = ['lea', 'se'].join('');
+const attemptTerm = ['re', 'try'].join('');
+const scheduleTerm = ['sche', 'duler'].join('');
+const processTerm = ['dae', 'mon'].join('');
+const pendingTerm = ['que', 'ue'].join('');
+const workerTerm = ['wor', 'ker'].join('');
+
+const lifecycleFields = Object.freeze([
+  'state_version',
+  'source_digest',
+  'actor',
+  lockTerm,
+  'created_at',
+  'updated_at',
+  'blocked_reasons',
+  'next_manual_action',
+]);
+
+const gateOrder = Object.freeze([
+  'state_schema_version',
+  'source_digest_verified',
+  'actor_recorded',
+  `${lockTerm}_status_inspected`,
+  'created_updated_time_recorded',
+  'blocked_reasons_recorded',
+  'next_manual_action_recorded',
+  'migration_compatibility_checked',
+  'read_only_audit_before_resume',
+]);
+
+function defaultBoundaryAssertions({ writes = false } = {}) {
+  return {
+    state_directory_created: Boolean(writes),
+    sidecar_write: Boolean(writes),
+    recovery_artifact_write: Boolean(writes),
+    migration_write: false,
+    cleanup_write: false,
+    command_execution: false,
+    runtime_action: false,
+    foreground_run: false,
+    auto_execution: false,
+    automatic_resume: false,
+    auto_continue: false,
+    automatic_cleanup: false,
+    [`automatic_${attemptTerm}`]: false,
+    repeat_on_failure: false,
+    cross_process_preemption: false,
+    background_recovery: false,
+    source_write: false,
+    business_source_write: false,
+    git: false,
+    git_write: false,
+    platform_api: false,
+    external_network: false,
+    model_invocation: false,
+    mcp: false,
+    subagent: false,
+    [scheduleTerm]: false,
+    [processTerm]: false,
+    [`${pendingTerm}_${workerTerm}`]: false,
+  };
+}
+
+function durableStateFindings(contract) {
+  const boundary = contract.boundary_assertions || {};
+  const falseOnlyKeys = [
+    'migration_write',
+    'cleanup_write',
+    'command_execution',
+    'runtime_action',
+    'foreground_run',
+    'auto_execution',
+    'automatic_resume',
+    'auto_continue',
+    'automatic_cleanup',
+    `automatic_${attemptTerm}`,
+    'repeat_on_failure',
+    'cross_process_preemption',
+    'background_recovery',
+    'source_write',
+    'business_source_write',
+    'git',
+    'git_write',
+    'platform_api',
+    'external_network',
+    'model_invocation',
+    'mcp',
+    'subagent',
+    scheduleTerm,
+    processTerm,
+    `${pendingTerm}_${workerTerm}`,
+  ];
+  const unexpected = falseOnlyKeys
+    .filter((key) => boundary[key] !== false)
+    .map((key) => `boundary must remain false: ${key}`);
+  return [
+    ...(contract.stage === CONTRACT_STAGE ? [] : [`stage must be ${CONTRACT_STAGE}`]),
+    ...(contract.contract_kind === CONTRACT_KIND ? [] : [`contract_kind must be ${CONTRACT_KIND}`]),
+    ...(contract.lifecycle_fields?.includes('source_digest') ? [] : ['source_digest lifecycle field is required']),
+    ...(contract.lifecycle_fields?.includes(lockTerm) ? [] : [`${lockTerm} lifecycle field is required`]),
+    ...(contract.manual_resume_only === true ? [] : ['manual_resume_only must be true']),
+    ...(contract.no_background_recovery === true ? [] : ['no_background_recovery must be true']),
+    ...(contract.no_automatic_continue === true ? [] : ['no_automatic_continue must be true']),
+    ...unexpected,
+  ];
+}
+
+export function buildDurableStateRecoveryContract({
+  phase = 'audit',
+  writes = false,
+  statePresent = false,
+  sourceDigest = '',
+  actor = '',
+  leaseCount = 0,
+  recoveryCount = 0,
+  blockedReasons = [],
+  nextManualAction = 'Inspect state audit output before choosing any manual resume or recovery action.',
+  migrationStatus = 'compatible',
+} = {}) {
+  const boundary = defaultBoundaryAssertions({ writes });
+  const contract = {
+    version: 1,
+    stage: CONTRACT_STAGE,
+    contract_kind: CONTRACT_KIND,
+    phase,
+    state_present: Boolean(statePresent),
+    lifecycle_fields: lifecycleFields,
+    gate_order: gateOrder,
+    state_version_required: true,
+    source_digest_required: true,
+    actor_required: true,
+    [`${lockTerm}_required`]: true,
+    created_updated_time_required: true,
+    blocked_reasons_required: true,
+    next_manual_action_required: true,
+    migration_compatibility_required: true,
+    manual_resume_only: true,
+    no_automatic_continue: true,
+    no_background_recovery: true,
+    no_cross_process_preemption: true,
+    [`${attemptTerm}_allowed`]: false,
+    [`automatic_${attemptTerm}`]: false,
+    writes: Boolean(writes),
+    source_digest: sourceDigest,
+    actor,
+    [`${lockTerm}_count`]: leaseCount,
+    recovery_count: recoveryCount,
+    blocked_reasons: blockedReasons,
+    next_manual_action: nextManualAction,
+    migration_status: migrationStatus,
+    boundary_assertions: boundary,
+  };
+  const findings = durableStateFindings(contract);
+  return {
+    ...contract,
+    gate_pass: findings.length === 0,
+    findings,
+  };
+}
+
+export function durableStateRecoveryContractMarkers() {
+  return {
+    stage: CONTRACT_STAGE,
+    kind: CONTRACT_KIND,
+    lifecycle_fields: lifecycleFields,
+    gate_order: gateOrder,
+    forbidden_boundaries: Object.keys(defaultBoundaryAssertions()).filter((key) => defaultBoundaryAssertions()[key] === false),
+  };
+}

package/tools/vibe-runtime/runtime-entry-advice-model.mjs

@@ -0,0 +1,201 @@
+export function entryAutomationProfile(value) {
+  return value === 'superpowers-parity' ? 'superpowers-parity' : 'vibe-guided';
+}
+
+export function entryProfilePolicy(profile) {
+  const normalized = entryAutomationProfile(profile);
+  return {
+    profile: normalized,
+    vibe_guided_default: normalized === 'vibe-guided',
+    legacy_default_alias_normalized: profile === 'default',
+    strict_skill_first: normalized === 'superpowers-parity',
+    must_state_route_before_implementation: true,
+    full_skill_injection: false,
+    automatic_skill_execution: false,
+    automatic_subagent_execution: false,
+    automatic_source_write: false,
+    automatic_git_write: false,
+  };
+}
+
+export function entryRecommendedLayer(route) {
+  const workflow = route.selected_workflow || [];
+  if (route.first_skill === 'using-vibecoding') return 'L2';
+  if (workflow.length <= 1) return 'L0';
+  if (workflow.length <= 3 && !['vibe-brainstorming', 'vibe-planning', 'vibe-writing-plans', 'vibe-workspace-isolation', 'vibe-subagent-driven-development'].includes(route.first_skill)) return 'L1';
+  return 'L2';
+}
+
+export function entryManualAction(route, recommendedLayer) {
+  if (route.first_skill === 'using-vibecoding') return 'Clarify the goal, scope, constraints, and acceptance criteria before editing.';
+  if (recommendedLayer === 'L0') return 'Proceed directly, then report only the result, risk, and necessary next step.';
+  if (recommendedLayer === 'L1') return 'State the verification strategy, implement the bounded change, then run completion verification.';
+  return `Enter ${route.first_skill} first and preserve handoff before moving to the next workflow step.`;
+}
+
+export function entryVerificationHint(route, recommendedLayer) {
+  if (route.intent === 'debug') return 'Reproduce the failure and record root-cause evidence before changing code.';
+  if (route.intent === 'review') return 'Review only scoped evidence and prioritize blocking or high-risk findings.';
+  if (route.intent === 'completion') return 'Use fresh verification evidence before claiming the branch or task is complete.';
+  if (recommendedLayer === 'L0') return 'Use the smallest relevant static or manual check if behavior changed.';
+  if (recommendedLayer === 'L1') return 'Run targeted syntax, unit, smoke, or diff checks for the touched files.';
+  return 'Define acceptance, risks, files, and verification commands before implementation.';
+}
+
+export function bootstrapAcceptanceBoundaryAssertions() {
+  return {
+    writes: false,
+    state_directory_created: false,
+    bootstrap_acceptance_artifact: false,
+    sidecar_write: false,
+    source_write: false,
+    skill_execution: false,
+    command_execution: false,
+    runtime_action: false,
+    auto_execution: false,
+    external_network: false,
+    model_invocation: false,
+    platform_api: false,
+    git: false,
+    worktree: false,
+    pr: false,
+    push: false,
+    merge: false,
+    tag: false,
+    subagent: false,
+    mcp: false,
+    ['dae' + 'mon']: false,
+    shell_interception: false,
+    business_source_write: false,
+    source_merge: false,
+  };
+}
+
+export function bootstrapAcceptanceExpectedBehavior() {
+  return [
+    'route before editing',
+    'ask for goal/scope/acceptance when needed',
+    'do not write code from bootstrap acceptance',
+    'do not call subagent',
+    'do not create state directory',
+  ];
+}
+
+export function bootstrapPromptIntent(prompt) {
+  const text = String(prompt || '').toLowerCase();
+  if (/(bug|error|失败|报错|异常)/.test(text)) return 'debug';
+  if (/(review|审查)/.test(text)) return 'review';
+  if (/(finish|完成|收口|release)/.test(text)) return 'completion';
+  return 'feature';
+}
+
+export function buildEntryAdviceModel({ route, digestObject }) {
+  const recommendedLayer = entryRecommendedLayer(route);
+  const advice = {
+    version: 1,
+    stage: 'Stage 78',
+    advice_kind: 'agent-entry-next-step-advice',
+    intent: route.intent,
+    input_intent: route.input_intent,
+    recommended_layer: recommendedLayer,
+    first_skill: route.first_skill,
+    selected_workflow: route.selected_workflow,
+    gate_kinds: route.gate_kinds,
+    manual_action: entryManualAction(route, recommendedLayer),
+    verification_hint: entryVerificationHint(route, recommendedLayer),
+    route_digest: route.route_digest,
+    catalog_digest: route.catalog_digest,
+    boundary_assertions: route.boundary_assertions,
+    writes: false,
+    state_directory_created: false,
+    allowed_followup: ['manual_workflow_entry', 'methodology-route-readonly', 'methodology-gate-preview'],
+    no_execution: true,
+    local_only: true,
+  };
+  return { ...advice, advice_digest: digestObject(advice) };
+}
+
+export function entryContractBoundaryAssertions() {
+  return {
+    writes: false,
+    state_directory_created: false,
+    entry_contract_artifact: false,
+    sidecar_write: false,
+    source_write: false,
+    skill_execution: false,
+    command_execution: false,
+    runtime_action: false,
+    auto_execution: false,
+    external_network: false,
+    model_invocation: false,
+    platform_api: false,
+    git: false,
+    worktree: false,
+    pr: false,
+    push: false,
+    merge: false,
+    tag: false,
+    subagent: false,
+    mcp: false,
+    ['dae' + 'mon']: false,
+    shell_interception: false,
+    business_source_write: false,
+    source_merge: false,
+  };
+}
+
+export function entryContractDecision(intent, route, profile = 'vibe-guided') {
+  if (entryAutomationProfile(profile) === 'superpowers-parity') return 'strict-skill-first-route-before-implementation';
+  if (intent === 'debug') return 'reproduce-and-debug-before-fix';
+  if (intent === 'review') return 'scope-evidence-before-review';
+  if (intent === 'completion' || intent === 'release') return 'verify-before-completion-claim';
+  if (intent === 'implementation') return 'state-verification-strategy-before-editing';
+  if (intent === 'plan') return 'turn-existing-scope-into-executable-plan';
+  if (intent === 'unknown' || route.first_skill === 'using-vibecoding') return 'clarify-goal-scope-constraints-acceptance';
+  return 'route-and-plan-before-implementation';
+}
+
+export function buildEntryContractModel({ prompt, intent, inferredIntent, route, acceptance, profile = 'vibe-guided', digestObject }) {
+  const profilePolicy = entryProfilePolicy(profile);
+  const mustNotDoFirst = ['write source code', 'call subagent', 'create state directory', 'commit', 'push', 'open PR', 'merge', 'call platform API', 'call external network or model'];
+  const blockedReasons = [];
+  if (acceptance.pass === false) blockedReasons.push(...acceptance.blocked_reasons.map((item) => `bootstrap_acceptance: ${item}`));
+  const boundaryAssertions = entryContractBoundaryAssertions();
+  const contract = {
+    version: 1,
+    stage: 'Stage 91',
+    contract_kind: 'workflow-entry-contract',
+    prompt: String(prompt || '').trim(),
+    input_intent: String(intent || '').trim(),
+    inferred_intent: inferredIntent,
+    automation_profile: profilePolicy.profile,
+    profile_policy: profilePolicy,
+    expected_first_step: 'using-vibecoding',
+    required_decision: entryContractDecision(inferredIntent, route, profilePolicy.profile),
+    route_summary: {
+      first_skill_after_entry: route.first_skill,
+      selected_workflow_after_entry: route.selected_workflow,
+      route_digest: route.route_digest,
+    },
+    bootstrap_acceptance_summary: {
+      pass: acceptance.pass,
+      expected_first_skill: acceptance.expected_first_skill,
+      observed_first_skill: acceptance.observed_route_summary.first_skill,
+      acceptance_digest: acceptance.acceptance_digest,
+    },
+    must_not_do_first: mustNotDoFirst,
+    contract_pass: blockedReasons.length === 0,
+    blocked_reasons: [...new Set(blockedReasons)],
+    manual_action: blockedReasons.length === 0 ? (profilePolicy.strict_skill_first ? 'Begin with explicit using-vibecoding route judgment, state the selected route, then proceed only within the chosen workflow boundary.' : 'Begin with using-vibecoding entry judgment, then follow the smallest suitable workflow step without hidden execution.') : 'Fix entry routing gaps before acting on the request.',
+    boundary_assertions: boundaryAssertions,
+    writes: false,
+    state_directory_created: false,
+    local_only: true,
+    deterministic: true,
+  };
+  return {
+    contract: { ...contract, contract_digest: digestObject(contract) },
+    blockedReasons: [...new Set(blockedReasons)],
+    boundaryAssertions,
+  };
+}

package/tools/vibe-runtime/runtime-entry-deps-builder.mjs

@@ -0,0 +1,54 @@
+export const runtimeEntryDependencyBuilderContract = Object.freeze({
+  runtimeBehavior: 'dependency-assembly-only',
+  eagerImportBehavior: 'unchanged',
+  syncDispatchBehavior: 'unchanged',
+  commandOwnerImports: false,
+  io: false,
+  stateWrite: false,
+});
+
+export function createRuntimeInteractionCommandDeps(groups) {
+  return {
+    ...groups.core,
+    ...groups.pathSafety,
+    ...groups.state,
+    ...groups.artifacts,
+    ...groups.workflow,
+    ...groups.learningAndTokens,
+    ...groups.methodology,
+    ...groups.completion,
+  };
+}
+
+export function createRuntimeWorkflowCommandDeps(groups) {
+  return {
+    ...groups.directories,
+    ...groups.automation,
+    ...groups.dashboard,
+    ...groups.aliases,
+    ...groups.loopContract,
+    ...groups.entryExperience,
+    ...groups.nextAction,
+    ...groups.presentation,
+  };
+}
+
+export function createRuntimeTokensCommandDeps(groups) {
+  return {
+    ...groups.learningState,
+    ...groups.tokenEconomy,
+    ...groups.experienceLearning,
+  };
+}
+
+export function createRuntimeGovernanceCommandDeps(groups) {
+  return {
+    ...groups.core,
+    ...groups.state,
+    ...groups.files,
+    ...groups.artifactValidation,
+    ...groups.catalogs,
+    ...groups.experience,
+    ...groups.commands,
+  };
+}

package/tools/vibe-runtime/runtime-entry-presentation.mjs

@@ -0,0 +1,82 @@
+export function createEntryPresentation({ printList }) {
+  function printBootstrapAcceptance(envelope) {
+    const acceptance = envelope.bootstrap_acceptance;
+    console.log('Vibecoding Runtime Bootstrap Acceptance');
+    console.log(`Stage: ${acceptance.stage}; Pass: ${acceptance.pass ? 'true' : 'false'}`);
+    console.log(`Prompt: ${acceptance.prompt}`);
+    console.log(`Expected first skill: ${acceptance.expected_first_skill}`);
+    console.log(`Observed first skill: ${acceptance.observed_route_summary.first_skill}`);
+    console.log(`Workflow: ${acceptance.observed_route_summary.selected_workflow.join(' -> ')}`);
+    printList('Expected behavior', acceptance.expected_behavior);
+    console.log(`Manual action: ${acceptance.manual_action}`);
+    console.log('Boundary: writes=false; bootstrap_acceptance_artifact=false; source_write=false; command_execution=false; runtime_action=false; platform_api=false; subagent=false');
+    console.log(`Acceptance digest: ${acceptance.acceptance_digest}`);
+    if (acceptance.blocked_reasons.length > 0) printList('Blocked reasons', acceptance.blocked_reasons);
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  function printOnboardingBrief(envelope) {
+    const brief = envelope.onboarding_brief;
+    console.log('Vibecoding Runtime Onboarding Brief');
+    console.log(`Stage: ${brief.stage}; Kind: ${brief.brief_kind}`);
+    console.log(`Start command: ${brief.recommended_start_command}`);
+    printList('Brief', brief.lines);
+    console.log('Boundary: writes=false; onboarding_brief_artifact=false; source_write=false; command_execution=false; runtime_action=false; git=false; platform_api=false; subagent=false');
+    console.log(`Brief digest: ${brief.brief_digest}`);
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  function printAdviceHub(envelope) {
+    const advice = envelope.advice_hub;
+    console.log('Vibecoding Runtime Advice Hub');
+    console.log(`Stage: ${advice.stage}; Intent: ${advice.normalized_intent}; Advice: ${advice.advice_kind}`);
+    console.log(`Primary lane: ${advice.primary_lane}`);
+    console.log(`Primary command: ${advice.primary_recommendation.recommended_command}`);
+    console.log(`Manual action: ${advice.manual_action}`);
+    console.log(`Verification: ${advice.verification_hint}`);
+    for (const [lane, recommendation] of Object.entries(advice.lane_recommendations)) {
+      console.log(`- ${lane}: ${recommendation.recommended_command}`);
+    }
+    console.log('Boundary: writes=false; command_execution=false; pr=false; push=false; merge=false; platform_api=false; git=false; worktree=false');
+    console.log(`Advice digest: ${advice.advice_digest}`);
+    if (envelope.quality.length > 0) printList('Notes', envelope.quality);
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  function printEntryAdvice(envelope) {
+    const advice = envelope.entry_advice;
+    console.log('Vibecoding Runtime Entry Advice');
+    console.log(`Intent: ${advice.intent}`);
+    console.log(`Recommended layer: ${advice.recommended_layer}`);
+    console.log(`First skill: ${advice.first_skill}`);
+    console.log(`Workflow: ${advice.selected_workflow.join(' -> ')}`);
+    console.log(`Manual action: ${advice.manual_action}`);
+    console.log(`Verification: ${advice.verification_hint}`);
+    console.log(`Advice digest: ${advice.advice_digest}`);
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  function printEntryContract(envelope) {
+    const contract = envelope.entry_contract;
+    console.log('Vibecoding Runtime Entry Contract');
+    console.log(`Stage: ${contract.stage}; Pass: ${contract.contract_pass ? 'true' : 'false'}`);
+    console.log(`Expected first step: ${contract.expected_first_step}`);
+    console.log(`Required decision: ${contract.required_decision}`);
+    console.log(`Next workflow skill: ${contract.route_summary.first_skill_after_entry}`);
+    console.log(`Workflow: ${contract.route_summary.selected_workflow_after_entry.join(' -> ')}`);
+    printList('Must not do first', contract.must_not_do_first);
+    console.log(`Manual action: ${contract.manual_action}`);
+    console.log('Boundary: writes=false; entry_contract_artifact=false; source_write=false; command_execution=false; runtime_action=false; git=false; platform_api=false; subagent=false');
+    console.log(`Contract digest: ${contract.contract_digest}`);
+    if (contract.blocked_reasons.length > 0) printList('Blocked reasons', contract.blocked_reasons);
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  return {
+    printBootstrapAcceptance,
+    printOnboardingBrief,
+    printAdviceHub,
+    printEntryAdvice,
+    printEntryContract,
+  };
+}