@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-interaction-workflow-envelopes.mjs

@@ -0,0 +1,412 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { readonlyLocalJsonEnvelope } from './runtime-readonly-local-json-output-envelope.mjs';
+import {
+  bootstrapAcceptanceBoundaryAssertions,
+  bootstrapAcceptanceExpectedBehavior,
+  bootstrapPromptIntent,
+  entryAutomationProfile,
+} from './runtime-entry-advice-model.mjs';
+import { createRuntimeWorkflowEntryEnvelopes } from './runtime-workflow-entry-envelopes.mjs';
+import {
+  buildWorkflowReadinessModel,
+  normalizeWorkflowReadinessIntent,
+  workflowReadinessAdviceIntent,
+  workflowReadinessBoundaryAssertions,
+  workflowReadinessGateKinds,
+  workflowReadinessGatePreview,
+  workflowReadinessRouteIntent,
+} from './runtime-workflow-readiness-model.mjs';
+import {
+  buildAdviceHubModel,
+  adviceHubLaneMapping,
+  normalizeAdviceHubIntent,
+} from './runtime-advice-hub-model.mjs';
+import {
+  buildWorkflowCockpitModel,
+  onboardingBriefBoundaryAssertions,
+  onboardingBriefLines,
+  workflowSequenceBoundaryAssertions,
+  workflowSequenceDefinition,
+} from './runtime-workflow-ux-model.mjs';
+
+function readInstalledAutomationProfile(root) {
+  const file = path.join(root, '.vibecoding', 'config.json');
+  if (!fs.existsSync(file)) return { profile: entryAutomationProfile('vibe-guided'), source: 'vibe-guided-no-config' };
+  try {
+    const config = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return {
+      profile: entryAutomationProfile(config.automation_profile),
+      source: config.automation_profile === 'superpowers-parity' ? 'installed-config' : 'installed-config-vibe-guided',
+    };
+  } catch {
+    return { profile: entryAutomationProfile('vibe-guided'), source: 'vibe-guided-invalid-config' };
+  }
+}
+
+export function createRuntimeInteractionWorkflowEnvelopes(deps) {
+  const {
+    ensureRoot,
+    workflowPath,
+    stateDirectory,
+    localTextEvidenceDescriptor,
+    methodologyGateKinds,
+    methodologyRouteEnvelope,
+    methodologyEnvelope,
+    readinessEnvelope,
+    planLintEnvelope,
+    runtimeAutomationReadinessEnvelope,
+    runtimeCapabilityRegistry,
+    tokenAdviceEnvelope,
+    learningAdviceEnvelope,
+    governanceAdviceEnvelope,
+    digestObject,
+    digestWorkflowLoopContract,
+    runtimeWorkflowLoopContract,
+    runtimeWorkflowLoopContractDigestPayload,
+    digestProgressiveEntryUx,
+    runtimeProgressiveEntryUx,
+    runtimeProgressiveEntryUxDigestPayload,
+    digestEntryTriggerDiscipline,
+    runtimeEntryTriggerDiscipline,
+    runtimeEntryTriggerDisciplineDigestPayload,
+  } = deps;
+
+  function adviceHubEnvelope(root, { intent = '' } = {}) {
+    const inputIntent = String(intent || '').trim();
+    const normalizedIntent = normalizeAdviceHubIntent(inputIntent);
+    const laneMapping = adviceHubLaneMapping(normalizedIntent);
+    return buildAdviceHubModel({
+      intent,
+      entryEnvelope: entryAdviceEnvelope(root, laneMapping.entry),
+      tokenEnvelope: tokenAdviceEnvelope(root, { intent: laneMapping.tokens }),
+      learningEnvelope: learningAdviceEnvelope(root, { intent: laneMapping.learning }),
+      governanceEnvelope: governanceAdviceEnvelope(root, { intent: laneMapping.governance }),
+      statePresent: fs.existsSync(stateDirectory(root)),
+      digestObject,
+    });
+  }
+
+  function workflowReadinessEnvelope(root, { intent = '' } = {}) {
+    ensureRoot(root);
+    const inputIntent = String(intent || '').trim();
+    const normalizedIntent = normalizeWorkflowReadinessIntent(inputIntent);
+    const routeEnvelope = methodologyRouteEnvelope(root, workflowReadinessRouteIntent(normalizedIntent));
+    const route = routeEnvelope.methodology_route;
+    const requiredGateKinds = workflowReadinessGateKinds(route, normalizedIntent, methodologyGateKinds);
+    const gatePreviews = requiredGateKinds.map((kind) => workflowReadinessGatePreview(methodologyEnvelope(root, kind, { persist: false })));
+    const runtimeReadiness = readinessEnvelope(root, { persist: false });
+    const adviceHub = adviceHubEnvelope(root, { intent: workflowReadinessAdviceIntent(normalizedIntent) });
+    const { readiness, blockedReasons, boundaryAssertions } = buildWorkflowReadinessModel({
+      inputIntent,
+      normalizedIntent,
+      route,
+      requiredGateKinds,
+      gatePreviews,
+      runtimeReadiness,
+      adviceHub,
+      digestObject,
+    });
+    return readonlyLocalJsonEnvelope(root, {
+      mode: 'workflow-readiness-gate',
+      ok: true,
+      payloadKey: 'workflow_readiness',
+      payload: readiness,
+      extra: { methodology_route: route },
+      safety: { stage: 'Stage 85', ...boundaryAssertions },
+      quality: blockedReasons,
+      action: 'workflow readiness was computed read-only from methodology route, methodology gate previews, observability readiness summary, and unified advice hub. No state directory, workflow readiness artifact, methodology gate write, sidecar, workflow skill execution, command execution, runtime action, PR, push, merge, tag, platform API, external network, model, git, worktree, subagent, MCP, ' + 'dae' + 'mon' + ', shell interception, or business source mutation occurred.',
+    });
+  }
+
+  function workflowCockpitEnvelope(root, { intent = '', planFile = '' } = {}) {
+    ensureRoot(root);
+    const normalizedIntent = normalizeWorkflowReadinessIntent(intent || 'unknown');
+    const readiness = workflowReadinessEnvelope(root, { intent: normalizedIntent });
+    const adviceEnvelope = adviceHubEnvelope(root, { intent: workflowReadinessAdviceIntent(normalizedIntent) });
+    const tokenEnvelope = tokenAdviceEnvelope(root, { intent: normalizedIntent === 'completion' ? 'verification' : normalizedIntent });
+    const learningEnvelope = learningAdviceEnvelope(root, { intent: normalizedIntent === 'debug' ? 'failure-fix' : 'review' });
+    const governanceEnvelope = governanceAdviceEnvelope(root, { intent: normalizedIntent === 'review' ? 'review' : normalizedIntent === 'completion' || normalizedIntent === 'release' ? 'closeout' : 'compatibility' });
+    const planLint = planFile ? planLintEnvelope(root, planFile).plan_lint : null;
+    const { cockpit, blockedReasons, boundaryAssertions } = buildWorkflowCockpitModel({
+      inputIntent: String(intent || '').trim(),
+      normalizedIntent,
+      readiness: readiness.workflow_readiness,
+      advice: adviceEnvelope.advice_hub,
+      planLint,
+      tokenAdvice: tokenEnvelope.token_advice,
+      learningAdvice: learningEnvelope.learning_advice,
+      governanceAdvice: governanceEnvelope.governance_advice,
+    });
+    return readonlyLocalJsonEnvelope(root, {
+      mode: 'workflow-cockpit',
+      ok: true,
+      statePath: workflowPath(root),
+      payloadKey: 'workflow_cockpit',
+      payload: { ...cockpit, cockpit_digest: digestObject(cockpit) },
+      safety: { stage: 'Stage 87', ...boundaryAssertions },
+      quality: blockedReasons,
+      action: 'workflow cockpit was computed read-only from workflow readiness, advice hub, optional plan lint, token advice, learning advice, and governance advice. No state directory, sidecar, workflow skill execution, command execution, runtime action, platform API, external network, model, git, worktree, subagent, MCP, ' + 'dae' + 'mon' + ', shell interception, PR, push, merge, tag, or business source mutation occurred.',
+    });
+  }
+
+  function progressiveEntryUxEnvelope(root, { prompt = '', gapFile = '' } = {}) {
+    ensureRoot(root);
+    let gapMatrix = null;
+    let gapSource = { status: 'not_provided', file: '', digest: '' };
+    if (gapFile) {
+      const source = localTextEvidenceDescriptor(root, gapFile, 'workflow --entry-ux --from-gap');
+      try {
+        gapMatrix = JSON.parse(source.text);
+      } catch (error) {
+        throw new Error(`workflow --entry-ux --from-gap JSON parse failed: ${error.message}`);
+      }
+      gapSource = { status: 'provided', file: source.relative, digest: source.digest };
+    }
+    const base = runtimeProgressiveEntryUx({ prompt, gapMatrix });
+    const entryUx = {
+      ...base,
+      source_bindings: {
+        ...base.source_bindings,
+        gap_file_status: gapSource.status,
+        gap_file: gapSource.file,
+        gap_file_digest: gapSource.digest,
+      },
+    };
+    const contract = {
+      ...entryUx,
+      contract_digest: digestProgressiveEntryUx(runtimeProgressiveEntryUxDigestPayload(entryUx)),
+    };
+    return readonlyLocalJsonEnvelope(root, {
+      mode: 'progressive-entry-ux-contract',
+      ok: contract.entry_ux_invariants.pass,
+      statePath: workflowPath(root),
+      payloadKey: 'progressive_entry_ux',
+      payload: contract,
+      safety: { stage: 'Stage 116', ...contract.boundary_assertions },
+      quality: contract.entry_ux_invariants.findings,
+      action: 'progressive entry UX contract was computed read-only from the prompt and optional local Stage 115 gap JSON. No state directory, sidecar, source write, workflow skill execution, command execution, runtime action, check, test, git, commit, push, PR, merge, platform API, external network, model, MCP, subagent, worktree, or business source mutation occurred.',
+    });
+  }
+
+  function workflowSequenceEnvelope(root, { intent = '' } = {}) {
+    ensureRoot(root);
+    const normalizedIntent = normalizeWorkflowReadinessIntent(intent || 'implementation');
+    const route = methodologyRouteEnvelope(root, workflowReadinessRouteIntent(normalizedIntent)).methodology_route;
+    const definition = workflowSequenceDefinition(normalizedIntent);
+    const boundaryAssertions = workflowSequenceBoundaryAssertions();
+    const sequence = {
+      version: 1,
+      stage: 'Stage 94',
+      sequence_kind: 'execution-choreography',
+      input_intent: String(intent || '').trim(),
+      normalized_intent: normalizedIntent,
+      route_summary: {
+        first_skill: route.first_skill,
+        selected_workflow: route.selected_workflow,
+        route_digest: route.route_digest,
+      },
+      ...definition,
+      boundary_assertions: boundaryAssertions,
+      writes: false,
+      state_directory_created: false,
+      local_only: true,
+      deterministic: true,
+    };
+    return readonlyLocalJsonEnvelope(root, {
+      mode: 'execution-choreography',
+      ok: true,
+      statePath: workflowPath(root),
+      payloadKey: 'workflow_sequence',
+      payload: { ...sequence, sequence_digest: digestObject(sequence) },
+      safety: { stage: 'Stage 94', ...boundaryAssertions },
+      quality: [],
+      action: 'workflow sequence was computed read-only from deterministic workflow choreography rules. No test, review, subagent, workflow skill, state directory, sidecar, source write, command execution, runtime action, git, PR, push, merge, tag, platform API, external network, model, worktree, MCP, ' + 'dae' + 'mon' + ', shell interception, or business source mutation occurred.',
+    });
+  }
+
+  function workflowLoopContractEnvelope(root, { intent = '', prompt = '', planFile = '' } = {}) {
+    ensureRoot(root);
+    const startEnvelope = workflowStartEnvelope(root, { intent, prompt, planFile });
+    const start = startEnvelope.workflow_start;
+    const normalizedIntent = start.normalized_intent;
+    const sequenceEnvelope = workflowSequenceEnvelope(root, { intent: normalizedIntent });
+    const sequence = sequenceEnvelope.workflow_sequence;
+    const automationEnvelope = runtimeAutomationReadinessEnvelope(root);
+    const automationReadiness = automationEnvelope.runtime_automation_readiness;
+    const registry = runtimeCapabilityRegistry();
+    const contract = runtimeWorkflowLoopContract({
+      inputIntent: intent || prompt,
+      normalizedIntent,
+      workflowStart: start,
+      workflowSequence: sequence,
+      automationReadiness,
+      registry,
+      registryDigest: automationReadiness.registry_digest,
+      planFile,
+    });
+    const workflowLoopContract = {
+      ...contract,
+      loop_contract_digest: digestWorkflowLoopContract(runtimeWorkflowLoopContractDigestPayload(contract)),
+    };
+    return readonlyLocalJsonEnvelope(root, {
+      mode: 'workflow-loop-contract',
+      ok: workflowLoopContract.loop_contract_invariants.pass,
+      statePath: workflowPath(root),
+      payloadKey: 'workflow_loop_contract',
+      payload: workflowLoopContract,
+      safety: { stage: 'Stage 104', ...workflowLoopContract.boundary_assertions },
+      quality: workflowLoopContract.loop_contract_invariants.findings,
+      action: 'workflow loop contract was computed read-only from workflow start, workflow sequence, automation readiness, and registry closeout chain. No automation plan, state directory, sidecar, classified command execution, test/check/repair execution, workflow execution, runtime action, git, PR, push, merge, tag, platform API, external network, model, worktree, subagent, MCP, ' + 'dae' + 'mon' + ', or business source mutation occurred.',
+    });
+  }
+
+  function entryTriggerDisciplineEnvelope(root, transcriptFile, { intent = 'unknown', profile = 'default' } = {}) {
+    ensureRoot(root);
+    if (!transcriptFile) throw new Error('workflow --entry-discipline requires --from-transcript <local-transcript-json>');
+    const source = localTextEvidenceDescriptor(root, transcriptFile, 'workflow --entry-discipline transcript');
+    const discipline = runtimeEntryTriggerDiscipline({
+      transcript: source.text,
+      intent: intent || 'unknown',
+      profile: entryAutomationProfile(profile),
+      source: {
+        transcript_file: source.relative,
+        transcript_digest: source.digest,
+        requested_intent: intent || 'unknown',
+      },
+    });
+    const entryTriggerDiscipline = {
+      ...discipline,
+      discipline_digest: digestEntryTriggerDiscipline(runtimeEntryTriggerDisciplineDigestPayload(discipline)),
+    };
+    return readonlyLocalJsonEnvelope(root, {
+      mode: 'entry-trigger-discipline-contract',
+      ok: entryTriggerDiscipline.pass,
+      payloadKey: 'entry_trigger_discipline',
+      payload: entryTriggerDiscipline,
+      safety: { stage: 'Stage 135', ...entryTriggerDiscipline.boundary_assertions },
+      quality: entryTriggerDiscipline.missed_workflow_risks,
+      action: 'entry trigger discipline read one local transcript JSON only. gate_markers=using_vibecoding_first,protocol_layers_declared,intent_route_match,no_direct_implementation_jump,no_blind_bug_fix,no_false_skill_claim,no_forbidden_trigger entry_discipline_artifact=false transcript_write=false workflow_execution=false skill_execution=false command_execution=false check_execution=false test_execution=false runtime_action=false git=false git_write=false subagent=false. No workflow skill run, transcript write, prompt mutation, auto execution, command/check/test execution, state write, platform API, model, MCP, subagent, git, PR, push, merge, or worktree action occurred.',
+    });
+  }
+
+  function bootstrapAcceptanceEnvelope(root, { prompt = '' } = {}) {
+    ensureRoot(root);
+    const inputPrompt = String(prompt || '').trim() || '帮我做一个 React todo list';
+    const intent = bootstrapPromptIntent(inputPrompt);
+    const routeEnvelope = methodologyRouteEnvelope(root, intent);
+    const route = routeEnvelope.methodology_route;
+    const advice = adviceHubEnvelope(root, { intent: intent === 'debug' ? 'bug' : intent === 'completion' ? 'closeout' : intent }).advice_hub;
+    const expectedBehavior = bootstrapAcceptanceExpectedBehavior();
+    const blockedReasons = [];
+    if (!route.selected_workflow.includes('vibe-brainstorming') && intent === 'feature') blockedReasons.push('feature bootstrap did not include brainstorming');
+    if (route.first_skill === 'vibe-implementation') blockedReasons.push('bootstrap routed directly to implementation');
+    const boundaryAssertions = bootstrapAcceptanceBoundaryAssertions();
+    const acceptance = {
+      version: 1,
+      stage: 'Stage 90',
+      acceptance_kind: 'workflow-bootstrap-acceptance',
+      prompt: inputPrompt,
+      inferred_intent: intent,
+      expected_first_skill: intent === 'feature' ? 'vibe-brainstorming' : route.first_skill,
+      expected_behavior: expectedBehavior,
+      observed_route_summary: {
+        first_skill: route.first_skill,
+        selected_workflow: route.selected_workflow,
+        route_digest: route.route_digest,
+      },
+      advice_summary: {
+        primary_lane: advice.primary_lane,
+        primary_command: advice.primary_recommendation.recommended_command,
+        advice_digest: advice.advice_digest,
+      },
+      pass: blockedReasons.length === 0,
+      blocked_reasons: blockedReasons,
+      manual_action: blockedReasons.length === 0 ? 'Bootstrap acceptance passed; keep first response focused on workflow route and clarification before implementation.' : 'Fix bootstrap routing so feature requests do not jump directly to implementation.',
+      boundary_assertions: boundaryAssertions,
+      writes: false,
+      state_directory_created: false,
+      local_only: true,
+      deterministic: true,
+    };
+    return readonlyLocalJsonEnvelope(root, {
+      mode: 'workflow-bootstrap-acceptance',
+      ok: true,
+      statePath: workflowPath(root),
+      payloadKey: 'bootstrap_acceptance',
+      payload: { ...acceptance, acceptance_digest: digestObject(acceptance) },
+      safety: { stage: 'Stage 90', ...boundaryAssertions },
+      quality: blockedReasons,
+      action: 'bootstrap acceptance was computed read-only from the local route and advice rules. No session was created, no state directory, source, sidecar, workflow skill execution, command execution, runtime action, platform API, external network, model, git, worktree, subagent, MCP, ' + 'dae' + 'mon' + ', shell interception, PR, push, merge, tag, or business source mutation occurred.',
+    });
+  }
+
+  const {
+    entryAdviceEnvelope,
+    entryContractEnvelope,
+    workflowReceiptEnvelope,
+    workflowStartEnvelope,
+  } = createRuntimeWorkflowEntryEnvelopes({
+    ensureRoot,
+    isWorkflowRecorded: (root) => fs.existsSync(workflowPath(root)),
+    methodologyRouteEnvelope,
+    workflowReadinessEnvelope,
+    workflowCockpitEnvelope,
+    bootstrapAcceptanceEnvelope,
+    resolveAutomationProfile: readInstalledAutomationProfile,
+    digestObject,
+  });
+
+  function onboardingBriefEnvelope(root) {
+    ensureRoot(root);
+    const start = workflowStartEnvelope(root, { intent: 'feature' }).workflow_start;
+    const boundaryAssertions = onboardingBriefBoundaryAssertions();
+    const briefLines = onboardingBriefLines();
+    const brief = {
+      version: 1,
+      stage: 'Stage 95',
+      brief_kind: 'workflow-onboarding-brief',
+      recommended_start_command: 'node tools/vibe-runtime/index.mjs workflow --start --prompt "<request>" --json',
+      lines: briefLines,
+      start_summary: {
+        stage: start.stage,
+        start_kind: start.start_kind,
+        recommended_next_skill: start.cockpit_summary.recommended_next_skill,
+        start_digest: start.start_digest,
+      },
+      boundary_assertions: boundaryAssertions,
+      writes: false,
+      state_directory_created: false,
+      local_only: true,
+      deterministic: true,
+    };
+    return readonlyLocalJsonEnvelope(root, {
+      mode: 'workflow-onboarding-brief',
+      ok: true,
+      statePath: workflowPath(root),
+      payloadKey: 'onboarding_brief',
+      payload: { ...brief, brief_digest: digestObject(brief) },
+      safety: { stage: 'Stage 95', ...boundaryAssertions },
+      quality: [],
+      action: 'onboarding brief was computed read-only from deterministic workflow start guidance. No state directory, sidecar, source write, workflow skill execution, command execution, runtime action, git, PR, push, merge, tag, platform API, external network, model, worktree, subagent, MCP, ' + 'dae' + 'mon' + ', shell interception, or business source mutation occurred.',
+    });
+  }
+
+  return {
+    adviceHubEnvelope,
+    bootstrapAcceptanceEnvelope,
+    entryAdviceEnvelope,
+    entryContractEnvelope,
+    entryTriggerDisciplineEnvelope,
+    onboardingBriefEnvelope,
+    progressiveEntryUxEnvelope,
+    workflowCockpitEnvelope,
+    workflowLoopContractEnvelope,
+    workflowReadinessBoundaryAssertions,
+    workflowReadinessEnvelope,
+    workflowReceiptEnvelope,
+    workflowSequenceEnvelope,
+    workflowStartEnvelope,
+  };
+}

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

@@ -0,0 +1,157 @@
+export function learningAdviceBoundaryAssertions() {
+  return {
+    automatic_promotion: false,
+    writes_formal_skills: false,
+    writes_agents_md: false,
+    writes_claude_md: false,
+    skill_mutation: false,
+    prompt_mutation: false,
+    hook_registration: false,
+    shell_interception: false,
+    command_execution: false,
+    external_network: false,
+    model_invocation: false,
+    platform_api: false,
+    git: false,
+    worktree: false,
+    subagent: false,
+    mcp: false,
+    daemon: false,
+  };
+}
+
+export function normalizeLearningAdviceIntent(intent) {
+  const value = String(intent || '').trim().toLowerCase();
+  const known = new Set(['correction', 'failure-fix', 'repeated-workflow', 'preference', 'project-constraint', 'observation', 'candidate-instinct', 'promotion', 'review']);
+  return known.has(value) ? value : 'unknown';
+}
+
+function learningAdviceIntentRoute(intent) {
+  const routes = {
+    correction: {
+      next: 'capture-local-observation',
+      command: 'learning --observe --from-file <session-evidence-file> --preview --json',
+      action: 'Record the correction in a local evidence file first; do not edit formal skills from a single correction.',
+      hint: 'Evidence should include user_corrections[] and an evidence_excerpt before learning --observe.',
+    },
+    'failure-fix': {
+      next: 'capture-local-observation',
+      command: 'learning --observe --from-file <session-evidence-file> --preview --json',
+      action: 'Record the fix as local evidence, then preview a learning observation before considering candidate instinct aggregation.',
+      hint: 'Evidence should include failure_fixes[] and project_constraints[] when the fix changes future behavior.',
+    },
+    'repeated-workflow': {
+      next: 'capture-local-observation',
+      command: 'learning --observe --from-file <session-evidence-file> --preview --json',
+      action: 'Capture the repeated workflow as observation evidence before creating any candidate rule.',
+      hint: 'Evidence should include repeated_workflows[] and scope=project unless it is intentionally a global candidate.',
+    },
+    preference: {
+      next: 'capture-local-observation',
+      command: 'learning --observe --from-file <session-evidence-file> --preview --json',
+      action: 'Capture the preference as evidence and keep promotion manual until multiple signals justify it.',
+      hint: 'Evidence should include preferences[] and confidence_delta within -1..1.',
+    },
+    'project-constraint': {
+      next: 'capture-local-observation',
+      command: 'learning --observe --from-file <session-evidence-file> --preview --json',
+      action: 'Capture the project constraint as local evidence; only later aggregate it into a candidate instinct.',
+      hint: 'Evidence should include project_constraints[] and a narrow domain such as workflow or governance.',
+    },
+    observation: {
+      next: 'candidate-instinct-preview',
+      command: 'learning --instincts --from-observations <learning-observation-file...> --preview --json',
+      action: 'Preview candidate instinct aggregation from verified observations before writing any candidate sidecar.',
+      hint: 'Use only observations from one project_id and one domain to avoid manual_review_required.',
+    },
+    'candidate-instinct': {
+      next: 'manual-promotion-preview',
+      command: 'learning --promote --instinct <candidate-instinct-file> --preview --json',
+      action: 'Preview the manual promotion gate; do not write formal skills automatically.',
+      hint: 'Promotion must hand off to vibe-writing-skills and still requires human approval.',
+    },
+    promotion: {
+      next: 'manual-skill-authoring-boundary',
+      command: 'vibe-writing-skills -> vibe-writing-plans -> vibe-test-driven-development -> vibe-review',
+      action: 'Treat promotion as a manual skill-authoring workflow, not as runtime mutation.',
+      hint: 'Formal skill changes require a separate plan, validation, and review.',
+    },
+    review: {
+      next: 'manual-review',
+      command: 'learning --list --json; learning --show <learning-file> --json; learning --verify <learning-file> --json',
+      action: 'Audit existing local learning sidecars before deciding whether to aggregate or promote.',
+      hint: 'Verify sidecars and inspect blocked_reasons before any follow-up.',
+    },
+    unknown: {
+      next: 'capture-local-observation',
+      command: 'learning --observe --from-file <session-evidence-file> --preview --json',
+      action: 'Clarify the learning signal, then capture it as local evidence before candidate or promotion steps.',
+      hint: 'Unknown learning intent falls back to observation-first advice.',
+    },
+  };
+  return routes[intent] || routes.unknown;
+}
+
+function learningAdviceQuality({ inputIntent, observationDigestRefs, instinctDescriptor }) {
+  const quality = [];
+  if (inputIntent && normalizeLearningAdviceIntent(inputIntent) === 'unknown') quality.push('unknown learning advice intent; using observation-first advice');
+  if (observationDigestRefs.length > 0) quality.push('verified observation input; advice remains preview-only and does not write candidate instinct');
+  if (instinctDescriptor) quality.push('verified candidate instinct input; advice remains manual promotion boundary only');
+  return quality;
+}
+
+export function buildLearningAdviceModel({ intent = '', observationDigestRefs = [], instinctDescriptor = null, statePresent = false, digestObject } = {}) {
+  const inputIntent = String(intent || '').trim();
+  const inferredIntent = instinctDescriptor ? 'candidate-instinct' : observationDigestRefs.length > 0 ? 'observation' : inputIntent;
+  const normalizedIntent = normalizeLearningAdviceIntent(inferredIntent || 'unknown');
+  const route = learningAdviceIntentRoute(normalizedIntent);
+  const boundaryAssertions = learningAdviceBoundaryAssertions();
+  const quality = learningAdviceQuality({ inputIntent, observationDigestRefs, instinctDescriptor });
+  const recommendedCommand = observationDigestRefs.length > 0
+    ? `learning --instincts --from-observations ${observationDigestRefs.map((item) => item.file).join(' ')} --preview --json`
+    : instinctDescriptor
+      ? `learning --promote --instinct ${instinctDescriptor.file} --preview --json`
+      : route.command;
+  const advice = {
+    version: 1,
+    stage: 'Stage 80',
+    advice_kind: 'learning-model-advice',
+    intent: normalizedIntent,
+    input_intent: inputIntent,
+    recommended_next_learning_step: observationDigestRefs.length > 0 ? 'candidate-instinct-preview' : instinctDescriptor ? 'manual-promotion-preview' : route.next,
+    recommended_command: recommendedCommand,
+    promotion_boundary: {
+      promotion_target: 'manual-skill-authoring',
+      required_workflow: ['vibe-writing-skills', 'vibe-writing-plans', 'vibe-test-driven-development', 'vibe-review'],
+      human_approval_required: true,
+      automatic_promotion: false,
+      writes_formal_skills: false,
+      writes_agents_md: false,
+      writes_claude_md: false,
+    },
+    manual_action: instinctDescriptor ? 'Review the candidate instinct and, if still valid, explicitly enter vibe-writing-skills before any formal skill edit.' : route.action,
+    verification_hint: instinctDescriptor ? 'Run learning --verify on the candidate instinct and keep promotion preview separate from formal skill edits.' : route.hint,
+    observation_digest_refs: observationDigestRefs,
+    candidate_instinct_file: instinctDescriptor?.file || '',
+    candidate_instinct_digest: instinctDescriptor?.candidate?.candidate_instinct_digest || '',
+    boundary_assertions: boundaryAssertions,
+    writes: false,
+    state_directory_created: false,
+    no_skill_mutation: true,
+    local_only: true,
+  };
+  return {
+    mode: 'learning-model-advice',
+    ok: true,
+    state_present: Boolean(statePresent),
+    learning_advice: { ...advice, advice_digest: digestObject(advice) },
+    safety: {
+      stage: 'Stage 80',
+      writes: false,
+      learning_advice_artifact: false,
+      ...boundaryAssertions,
+    },
+    quality,
+    action: 'learning model advice was computed read-only from builtin Stage 61/62 learning boundaries and optional verified local sidecars. No state directory, automatic promotion, formal skill mutation, prompt mutation, hook registration, shell interception, command execution, external network, model, platform API, git, worktree, subagent, MCP, daemon, or business source mutation occurred.',
+  };
+}