@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-release-check/release-check-json-assertion-helpers.mjs

@@ -0,0 +1,157 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { readonlySmokeMarkerSpecs } from './release-check-readonly-marker-data.mjs';
+
+function pathValue(source, path) {
+  return String(path)
+    .split('.')
+    .reduce((current, segment) => {
+      if (current == null) return undefined;
+      if (/^\d+$/.test(segment)) return current[Number(segment)];
+      return current[segment];
+    }, source);
+}
+
+export const READ_ONLY_RUNTIME_CONTROL_FLAGS = ['--confirm', '--write', '--preflight', '--dispatch', '--dispatch-intent', '--run', '--once', '--scan', '--auto-run'];
+
+export const READ_ONLY_RUNTIME_CONTROL_FLAGS_WITH_PREVIEW = ['--confirm', '--preview', ...READ_ONLY_RUNTIME_CONTROL_FLAGS.slice(1)];
+
+export const READ_ONLY_RUNTIME_CONTROL_FLAGS_WITH_DRY_RUN = [...READ_ONLY_RUNTIME_CONTROL_FLAGS, '--dry-run'];
+
+export const READ_ONLY_RUNTIME_CONTROL_FLAGS_WITH_DRY_RUN_SECOND = ['--confirm', '--dry-run', ...READ_ONLY_RUNTIME_CONTROL_FLAGS.slice(1)];
+
+export const READ_ONLY_RUNTIME_CONTROL_FLAGS_WITH_PREVIEW_AND_DRY_RUN = [...READ_ONLY_RUNTIME_CONTROL_FLAGS_WITH_PREVIEW, '--dry-run'];
+
+export function runForbiddenFlagChecks(run, beforeFlagArgs, afterFlagArgs, flags, expectedMessage, options) {
+  for (const forbidden of flags) {
+    run('node', [...beforeFlagArgs, forbidden, ...afterFlagArgs], {
+      allowFailure: true,
+      expectOutput: [expectedMessage],
+    }, options);
+  }
+}
+
+export function prepareSmokeTmpRoot(repoRoot, target) {
+  const absoluteTarget = path.join(repoRoot, target);
+  fs.rmSync(absoluteTarget, { recursive: true, force: true });
+  fs.mkdirSync(absoluteTarget, { recursive: true });
+  return absoluteTarget;
+}
+
+export function cleanupSmokeTmpRoot(absoluteTarget, options) {
+  if (!options.keepTmp) fs.rmSync(absoluteTarget, { recursive: true, force: true });
+}
+
+export function assertNoSmokeState(repoRoot, target, label) {
+  const statePath = path.join(repoRoot, target, '.vibecoding-state');
+  if (fs.existsSync(statePath)) throw new Error(`${label} created unexpected state directory`);
+}
+
+export function writeSmokeJsonFixture(repoRoot, file, fixture) {
+  const fixtureFile = path.join(repoRoot, file);
+  fs.mkdirSync(path.dirname(fixtureFile), { recursive: true });
+  fs.writeFileSync(fixtureFile, `${JSON.stringify(fixture, null, 2)}\n`, 'utf8');
+}
+
+export function writeSmokeTextFixtures(root, specs) {
+  return Object.fromEntries(
+    specs.map(({ key, fileName, content }) => {
+      const file = path.join(root, fileName);
+      fs.writeFileSync(file, content, 'utf8');
+      return [key, file];
+    }),
+  );
+}
+
+function assertMarkerSpec(spec, label) {
+  if (!Array.isArray(spec) || spec.length !== 2) throw new Error(`${label} marker spec must be [path, expected]`);
+  const [path, expected] = spec;
+  if (!path || typeof path !== 'string') throw new Error(`${label} marker spec has empty path`);
+  if (expected === undefined) throw new Error(`${label} marker spec has undefined expected value: ${path}`);
+}
+
+export function markerSpecs(source, prefix, specs, label = prefix) {
+  const seen = new Set();
+  return specs.map((spec) => {
+    assertMarkerSpec(spec, label);
+    const [path, expected] = spec;
+    const markerPath = prefix ? `${prefix}.${path}` : path;
+    if (seen.has(markerPath)) throw new Error(`${label} marker spec has duplicate path: ${markerPath}`);
+    seen.add(markerPath);
+    return [markerPath, pathValue(source, path), expected];
+  });
+}
+
+export function boundaryFalseMarkers(source, prefix, fields, label = prefix) {
+  return markerSpecs(
+    source,
+    prefix,
+    fields.map((field) => [`boundary_assertions.${field}`, false]),
+    label,
+  );
+}
+
+export function safetyFalseMarkers(source, fields, label = 'safety') {
+  return markerSpecs(
+    source,
+    'safety',
+    fields.map((field) => [field, false]),
+    label,
+  );
+}
+
+export function envelopeBaseMarkers(envelope, { command, mode, ok = true }, label = 'envelope') {
+  return markerSpecs(
+    envelope,
+    '',
+    [
+      ['command', command],
+      ['mode', mode],
+      ['ok', ok],
+    ],
+    label,
+  );
+}
+
+export function readonlyEnvelopeMarkers({
+  envelope,
+  payload,
+  payloadPrefix,
+  command,
+  mode,
+  stage,
+  payloadSpecs,
+  boundaryFields,
+  safetyFields,
+  label,
+}) {
+  return [
+    ...envelopeBaseMarkers(envelope, { command, mode }, `${label} envelope`),
+    ...markerSpecs(payload, payloadPrefix, payloadSpecs, `${label} payload`),
+    ...boundaryFalseMarkers(payload, payloadPrefix, boundaryFields, `${label} boundary`),
+    ...markerSpecs(envelope.safety, 'safety', [['stage', stage]], `${label} safety`),
+    ...safetyFalseMarkers(envelope.safety, safetyFields, `${label} safety`),
+  ];
+}
+
+export function readonlySmokeMarkerSpecKeys() {
+  return Object.keys(readonlySmokeMarkerSpecs);
+}
+
+export function readonlySmokeMarkers(envelope, smokeKey) {
+  const spec = readonlySmokeMarkerSpecs[smokeKey];
+  if (!spec) throw new Error(`unknown readonly smoke marker spec: ${smokeKey}`);
+  return readonlyEnvelopeMarkers({
+    envelope,
+    payload: envelope?.[spec.payloadKey],
+    payloadPrefix: spec.payloadPrefix,
+    command: spec.command,
+    mode: spec.mode,
+    stage: spec.stage,
+    payloadSpecs: spec.payloadSpecs,
+    boundaryFields: spec.boundaryFields,
+    safetyFields: spec.safetyFields,
+    label: spec.label,
+  });
+}

package/tools/vibe-release-check/release-check-json-markers.mjs

@@ -0,0 +1,33 @@
+function jsonPathValue(value, pathExpression) {
+  return String(pathExpression).split('.').reduce((current, key) => {
+    if (current === undefined || current === null) return undefined;
+    if (key === 'length') return current.length;
+    return current[key];
+  }, value);
+}
+
+function formatJsonMarkerValue(value) {
+  return typeof value === 'string' ? value : JSON.stringify(value);
+}
+
+function assertJsonPathMarker(value, marker, label) {
+  const [pathExpression, expected] = marker;
+  const actual = jsonPathValue(value, pathExpression);
+
+  if (expected && typeof expected === 'object' && expected.exists === true) {
+    if (actual === undefined || actual === null || actual === '') {
+      throw new Error(`${label} JSON marker missing: path=${pathExpression}, expected=exists, actual=${formatJsonMarkerValue(actual)}`);
+    }
+    return;
+  }
+
+  if (actual !== expected) {
+    throw new Error(`${label} JSON marker mismatch: path=${pathExpression}, expected=${formatJsonMarkerValue(expected)}, actual=${formatJsonMarkerValue(actual)}`);
+  }
+}
+
+export function assertJsonPathMarkers(value, checks, label) {
+  for (const marker of checks) {
+    assertJsonPathMarker(value, marker, label);
+  }
+}

package/tools/vibe-release-check/release-check-learning-fixture-specs.mjs

@@ -0,0 +1,199 @@
+// Contract surface covered by tools/vibe-release-check fast learning smoke.
+export const learningObservationEvidenceText = `${JSON.stringify({
+  project_id: 'stage61-release-smoke',
+  scope: 'project',
+  domain: 'workflow',
+  confidence_delta: 0.25,
+  evidence_excerpt: 'The user corrected the agent to avoid automatic subagent dispatch and keep local governance explicit.',
+  user_corrections: ['Do not auto-dispatch subagents without explicit user permission.'],
+  repeated_workflows: ['vibe-executing-plans -> vibe-review -> vibe-implementation'],
+  preferences: ['Prefer local sidecar evidence before automation.'],
+  project_constraints: ['Learning must not mutate formal skills automatically.'],
+}, null, 2)}\n`;
+
+export const learningInstinctEvidenceText = `${JSON.stringify({
+  project_id: 'stage62-release-smoke',
+  scope: 'project',
+  domain: 'workflow',
+  confidence_delta: 0.4,
+  evidence_excerpt: 'The user repeatedly requires local governance and manual learning promotion instead of automatic skill mutation.',
+  user_corrections: ['Do not automatically promote learned rules into formal skills.'],
+  repeated_workflows: ['vibe-executing-plans -> vibe-review -> vibe-implementation'],
+  project_constraints: ['Candidate instincts must remain sidecar-only until vibe-writing-skills is explicitly used.'],
+}, null, 2)}\n`;
+
+export const learningAdviceEvidenceText = `${JSON.stringify({
+  project_id: 'stage80-release-smoke',
+  scope: 'project',
+  domain: 'workflow',
+  confidence_delta: 0.35,
+  evidence_excerpt: 'The user repeatedly requires manual learning promotion and no formal skill mutation from runtime advice.',
+  user_corrections: ['Keep learning advice read-only and observation-first.'],
+  repeated_workflows: ['learning observation -> candidate instinct -> manual promotion boundary'],
+  project_constraints: ['Formal skill mutation must go through vibe-writing-skills.'],
+}, null, 2)}\n`;
+
+export function learningObservationPreviewJsonMarkers(preview) {
+  return [
+    ['command', preview.command, 'learning'],
+    ['mode', preview.mode, 'learning-observation'],
+    ['learning_observation.stage', preview.learning_observation?.stage, 'Stage 61'],
+    ['learning_observation.artifact_kind', preview.learning_observation?.artifact_kind, 'learning-observation'],
+    ['learning_observation.optional', preview.learning_observation?.optional, true],
+    ['learning_observation.sidecar_only', preview.learning_observation?.sidecar_only, true],
+    ['learning_observation.default_enabled', preview.learning_observation?.default_enabled, false],
+    ['learning_observation.release_chain_required', preview.learning_observation?.release_chain_required, false],
+    ['learning_observation.source_file', preview.learning_observation?.source_file, 'evidence/session-learning.json'],
+    ['learning_observation.scope', preview.learning_observation?.scope, 'project'],
+    ['learning_observation.domain', preview.learning_observation?.domain, 'workflow'],
+    ['learning_observation.candidate_only', preview.learning_observation?.candidate_only, true],
+    ['learning_observation.promotion_required', preview.learning_observation?.promotion_required, true],
+    ['safety.writes', preview.safety?.writes, false],
+    ['safety.skill_mutation', preview.safety?.skill_mutation, false],
+    ['safety.prompt_mutation', preview.safety?.prompt_mutation, false],
+    ['safety.hook_registration', preview.safety?.hook_registration, false],
+    ['safety.shell_interception', preview.safety?.shell_interception, false],
+    ['safety.external_network', preview.safety?.external_network, false],
+    ['safety.model_invocation', preview.safety?.model_invocation, false],
+    ['safety.platform_api', preview.safety?.platform_api, false],
+    ['safety.git', preview.safety?.git, false],
+    ['safety.worktree', preview.safety?.worktree, false],
+    ['safety.runtime_action', preview.safety?.runtime_action, false],
+    ['safety.subagent', preview.safety?.subagent, false],
+  ];
+}
+
+export function learningShowJsonMarkers(shown) {
+  return [
+    ['summary.status', shown.summary?.status, 'observation_recorded'],
+    ['summary.scope', shown.summary?.scope, 'project'],
+    ['summary.domain', shown.summary?.domain, 'workflow'],
+  ];
+}
+
+export function learningVerifyJsonMarkers(verified) {
+  return [
+    ['summary.status', verified.summary?.status, 'observation_recorded'],
+    ['verification.ok', verified.verification?.ok, true],
+  ];
+}
+
+export function learningInstinctPreviewJsonMarkers(instinctPreview) {
+  return [
+    ['command', instinctPreview.command, 'learning'],
+    ['mode', instinctPreview.mode, 'candidate-instinct'],
+    ['candidate_instinct.stage', instinctPreview.candidate_instinct?.stage, 'Stage 62'],
+    ['candidate_instinct.artifact_kind', instinctPreview.candidate_instinct?.artifact_kind, 'candidate-instinct'],
+    ['candidate_instinct.atomic', instinctPreview.candidate_instinct?.atomic, true],
+    ['candidate_instinct.one_trigger', instinctPreview.candidate_instinct?.one_trigger, true],
+    ['candidate_instinct.one_action', instinctPreview.candidate_instinct?.one_action, true],
+    ['candidate_instinct.evidence_backed', instinctPreview.candidate_instinct?.evidence_backed, true],
+    ['candidate_instinct.promotion_required', instinctPreview.candidate_instinct?.promotion_required, true],
+    ['candidate_instinct.formal_skill_mutation', instinctPreview.candidate_instinct?.formal_skill_mutation, false],
+    ['candidate_instinct.skill_mutation', instinctPreview.candidate_instinct?.skill_mutation, false],
+    ['candidate_instinct.prompt_mutation', instinctPreview.candidate_instinct?.prompt_mutation, false],
+    ['candidate_instinct.hook_registration', instinctPreview.candidate_instinct?.hook_registration, false],
+    ['candidate_instinct.shell_interception', instinctPreview.candidate_instinct?.shell_interception, false],
+    ['safety.writes', instinctPreview.safety?.writes, false],
+    ['safety.candidate_instinct_artifact', instinctPreview.safety?.candidate_instinct_artifact, false],
+  ];
+}
+
+export function learningPromotionPreviewJsonMarkers(promotionPreview) {
+  return [
+    ['command', promotionPreview.command, 'learning'],
+    ['mode', promotionPreview.mode, 'learning-promotion'],
+    ['learning_promotion.stage', promotionPreview.learning_promotion?.stage, 'Stage 62'],
+    ['learning_promotion.artifact_kind', promotionPreview.learning_promotion?.artifact_kind, 'learning-promotion'],
+    ['learning_promotion.promotion_target', promotionPreview.learning_promotion?.promotion_target, 'manual-skill-authoring'],
+    ['learning_promotion.human_approval_required', promotionPreview.learning_promotion?.human_approval_required, true],
+    ['learning_promotion.automatic_promotion', promotionPreview.learning_promotion?.automatic_promotion, false],
+    ['learning_promotion.writes_formal_skills', promotionPreview.learning_promotion?.writes_formal_skills, false],
+    ['learning_promotion.writes_agents_md', promotionPreview.learning_promotion?.writes_agents_md, false],
+    ['learning_promotion.writes_claude_md', promotionPreview.learning_promotion?.writes_claude_md, false],
+    ['safety.writes', promotionPreview.safety?.writes, false],
+    ['safety.learning_promotion_artifact', promotionPreview.safety?.learning_promotion_artifact, false],
+  ];
+}
+
+export function learningListJsonMarkers(listed) {
+  return [
+    ['summary.observation_count', listed.summary?.observation_count, 1],
+    ['summary.candidate_instinct_count', listed.summary?.candidate_instinct_count, 1],
+    ['summary.promotion_count', listed.summary?.promotion_count, 1],
+    ['summary.failed_count', listed.summary?.failed_count, 0],
+  ];
+}
+
+export function learningIntentAdviceJsonMarkers(intentAdvice) {
+  return [
+    ['command', intentAdvice.command, 'learning'],
+    ['mode', intentAdvice.mode, 'learning-model-advice'],
+    ['learning_advice.stage', intentAdvice.learning_advice?.stage, 'Stage 80'],
+    ['learning_advice.advice_kind', intentAdvice.learning_advice?.advice_kind, 'learning-model-advice'],
+    ['learning_advice.intent', intentAdvice.learning_advice?.intent, 'correction'],
+    ['learning_advice.recommended_next_learning_step', intentAdvice.learning_advice?.recommended_next_learning_step, 'capture-local-observation'],
+    ['learning_advice.promotion_boundary.automatic_promotion', intentAdvice.learning_advice?.promotion_boundary?.automatic_promotion, false],
+    ['learning_advice.promotion_boundary.writes_formal_skills', intentAdvice.learning_advice?.promotion_boundary?.writes_formal_skills, false],
+    ['safety.writes', intentAdvice.safety?.writes, false],
+    ['safety.learning_advice_artifact', intentAdvice.safety?.learning_advice_artifact, false],
+    ['safety.automatic_promotion', intentAdvice.safety?.automatic_promotion, false],
+    ['safety.writes_formal_skills', intentAdvice.safety?.writes_formal_skills, false],
+    ['safety.skill_mutation', intentAdvice.safety?.skill_mutation, false],
+    ['safety.prompt_mutation', intentAdvice.safety?.prompt_mutation, false],
+    ['safety.hook_registration', intentAdvice.safety?.hook_registration, false],
+    ['safety.shell_interception', intentAdvice.safety?.shell_interception, false],
+    ['safety.command_execution', intentAdvice.safety?.command_execution, false],
+    ['safety.model_invocation', intentAdvice.safety?.model_invocation, false],
+    ['safety.platform_api', intentAdvice.safety?.platform_api, false],
+    ['safety.subagent', intentAdvice.safety?.subagent, false],
+  ];
+}
+
+export const learningAdviceTextMarkers = Object.freeze([
+  'Vibecoding Runtime Learning Advice',
+  'Next step: capture-local-observation',
+  'automatic_promotion=false',
+  'writes_formal_skills=false',
+]);
+
+export function learningUnknownAdviceJsonMarkers(unknownAdvice) {
+  return [
+    ['learning_advice.intent', unknownAdvice.learning_advice?.intent, 'unknown'],
+    ['learning_advice.recommended_next_learning_step', unknownAdvice.learning_advice?.recommended_next_learning_step, 'capture-local-observation'],
+  ];
+}
+
+export function learningObservationAdviceJsonMarkers(observationAdvice) {
+  return [
+    ['learning_advice.intent', observationAdvice.learning_advice?.intent, 'observation'],
+    ['learning_advice.recommended_next_learning_step', observationAdvice.learning_advice?.recommended_next_learning_step, 'candidate-instinct-preview'],
+    ['learning_advice.observation_digest_refs.length', observationAdvice.learning_advice?.observation_digest_refs?.length, 1],
+  ];
+}
+
+export function learningInstinctAdviceJsonMarkers(instinctAdvice, instinctFile) {
+  return [
+    ['learning_advice.intent', instinctAdvice.learning_advice?.intent, 'candidate-instinct'],
+    ['learning_advice.recommended_next_learning_step', instinctAdvice.learning_advice?.recommended_next_learning_step, 'manual-promotion-preview'],
+    ['learning_advice.candidate_instinct_file', instinctAdvice.learning_advice?.candidate_instinct_file, instinctFile],
+  ];
+}
+
+export const learningAdviceForbiddenFlags = Object.freeze([
+  '--confirm',
+  '--preview',
+  '--write',
+  '--preflight',
+  '--dispatch',
+  '--dispatch-intent',
+  '--run',
+  '--once',
+  '--scan',
+]);
+
+export function learningAdviceForbiddenOutputMarkers(flag) {
+  return flag === '--once' || flag === '--scan' || flag === '--run' || flag === '--write'
+    ? ['learning supports local observation']
+    : ['learning --advice is read-only'];
+}

package/tools/vibe-release-check/release-check-learning-suite.mjs

@@ -0,0 +1,249 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  learningAdviceEvidenceText,
+  learningAdviceForbiddenFlags,
+  learningAdviceForbiddenOutputMarkers,
+  learningAdviceTextMarkers,
+  learningInstinctAdviceJsonMarkers,
+  learningInstinctEvidenceText,
+  learningInstinctPreviewJsonMarkers,
+  learningIntentAdviceJsonMarkers,
+  learningListJsonMarkers,
+  learningObservationAdviceJsonMarkers,
+  learningObservationEvidenceText,
+  learningObservationPreviewJsonMarkers,
+  learningPromotionPreviewJsonMarkers,
+  learningShowJsonMarkers,
+  learningUnknownAdviceJsonMarkers,
+  learningVerifyJsonMarkers,
+} from './release-check-learning-fixture-specs.mjs';
+
+export function releaseCheckLearningSuiteHandlers({ repoRoot, run, parseJsonOutput, assertJsonMarkers, digestObject }) {
+function runLearningObservationSmoke(options) {
+  const target = '.tmp/vibe-learning-observation';
+  const absoluteTarget = path.join(repoRoot, target);
+  const evidenceDirectory = path.join(absoluteTarget, 'evidence');
+  const evidenceFile = path.join(evidenceDirectory, 'session-learning.json');
+  fs.rmSync(absoluteTarget, { recursive: true, force: true });
+
+  try {
+    fs.mkdirSync(evidenceDirectory, { recursive: true });
+    fs.writeFileSync(evidenceFile, learningObservationEvidenceText, 'utf8');
+
+    const preview = parseJsonOutput(run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--observe', '--from-file', evidenceFile, '--preview', '--json', '--root', target], {}, options), 'learning --observe --preview --json');
+    assertJsonMarkers(learningObservationPreviewJsonMarkers(preview), 'learning --observe --preview --json');
+    if (!preview.learning_observation?.source_digest) throw new Error('learning preview missing source_digest');
+    if (!preview.learning_observation?.evidence_excerpt_digest) throw new Error('learning preview missing evidence_excerpt_digest');
+    if (!preview.learning_observation?.signals_digest) throw new Error('learning preview missing signals_digest');
+    if (!preview.learning_observation?.learning_observation_digest) throw new Error('learning preview missing learning_observation_digest');
+    if (fs.existsSync(path.join(absoluteTarget, '.vibecoding-state'))) throw new Error('learning preview created unexpected state directory');
+
+    const confirmed = parseJsonOutput(run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--observe', '--from-file', evidenceFile, '--confirm', '--json', '--root', target], {}, options), 'learning --observe --confirm --json');
+    const learningFile = confirmed.learning_file;
+    if (!learningFile || !learningFile.endsWith('.learning-observation.json')) throw new Error('learning confirm did not return a learning observation sidecar file');
+    const sidecarPath = path.join(absoluteTarget, '.vibecoding-state', 'learning', learningFile);
+    if (!fs.existsSync(sidecarPath)) throw new Error('learning confirm did not write learning observation sidecar');
+    const extraStateEntries = fs.readdirSync(path.join(absoluteTarget, '.vibecoding-state')).filter((entry) => entry !== 'learning');
+    if (extraStateEntries.length > 0) throw new Error(`learning confirm wrote unexpected state entries: ${extraStateEntries.join(', ')}`);
+
+    const listed = parseJsonOutput(run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--list', '--json', '--root', target], {}, options), 'learning --list --json');
+    if (!listed.observations?.some((item) => item.file === learningFile && item.domain === 'workflow' && item.scope === 'project')) throw new Error('learning sidecar is missing from learning list');
+
+    const shown = parseJsonOutput(run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--show', learningFile, '--json', '--root', target], {}, options), 'learning --show --json');
+    assertJsonMarkers(learningShowJsonMarkers(shown), 'learning --show --json');
+
+    const verified = parseJsonOutput(run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--verify', learningFile, '--json', '--root', target], {}, options), 'learning --verify --json');
+    assertJsonMarkers(learningVerifyJsonMarkers(verified), 'learning --verify --json');
+
+    const badPathSidecar = JSON.parse(fs.readFileSync(sidecarPath, 'utf8'));
+    badPathSidecar.learning_observation.source_file = '../evidence/session-learning.json';
+    const badPathDigestPayload = { ...badPathSidecar.learning_observation };
+    delete badPathDigestPayload.writes;
+    delete badPathDigestPayload.learning_observation_digest;
+    badPathSidecar.learning_observation.learning_observation_digest = digestObject(badPathDigestPayload);
+    fs.writeFileSync(path.join(absoluteTarget, '.vibecoding-state', 'learning', 'bad-path.learning-observation.json'), `${JSON.stringify(badPathSidecar, null, 2)}\n`, 'utf8');
+    run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--verify', 'bad-path.learning-observation.json', '--root', target], {
+      allowFailure: true,
+      expectOutput: ['learning observation verification failed:', 'learning.source_file must not include traversal'],
+    }, options);
+
+    const badDigestSidecar = JSON.parse(fs.readFileSync(sidecarPath, 'utf8'));
+    badDigestSidecar.learning_observation.source_digest = '0'.repeat(64);
+    const badDigestPayload = { ...badDigestSidecar.learning_observation };
+    delete badDigestPayload.writes;
+    delete badDigestPayload.learning_observation_digest;
+    badDigestSidecar.learning_observation.learning_observation_digest = digestObject(badDigestPayload);
+    fs.writeFileSync(path.join(absoluteTarget, '.vibecoding-state', 'learning', 'bad-digest.learning-observation.json'), `${JSON.stringify(badDigestSidecar, null, 2)}\n`, 'utf8');
+    run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--verify', 'bad-digest.learning-observation.json', '--root', target], {
+      allowFailure: true,
+      expectOutput: ['learning observation verification failed:', 'learning source digest mismatch'],
+    }, options);
+
+    const badScopeSidecar = JSON.parse(fs.readFileSync(sidecarPath, 'utf8'));
+    badScopeSidecar.learning_observation.scope = 'global';
+    const badScopePayload = { ...badScopeSidecar.learning_observation };
+    delete badScopePayload.writes;
+    delete badScopePayload.learning_observation_digest;
+    badScopeSidecar.learning_observation.learning_observation_digest = digestObject(badScopePayload);
+    fs.writeFileSync(path.join(absoluteTarget, '.vibecoding-state', 'learning', 'bad-scope.learning-observation.json'), `${JSON.stringify(badScopeSidecar, null, 2)}\n`, 'utf8');
+    run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--verify', 'bad-scope.learning-observation.json', '--root', target], {
+      allowFailure: true,
+      expectOutput: ['learning observation verification failed:', 'learning_observation.scope is invalid'],
+    }, options);
+
+    run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--observe', '--from-file', evidenceFile, '--preview', '--confirm', '--root', target], {
+      allowFailure: true,
+      expectOutput: ['learning --observe accepts either --preview or --confirm, not both'],
+    }, options);
+  } finally {
+    if (!options.keepTmp) fs.rmSync(absoluteTarget, { recursive: true, force: true });
+  }
+}
+
+function runLearningInstinctSmoke(options) {
+  const target = '.tmp/vibe-learning-instinct';
+  const absoluteTarget = path.join(repoRoot, target);
+  const evidenceDirectory = path.join(absoluteTarget, 'evidence');
+  const evidenceFile = path.join(evidenceDirectory, 'session-learning.json');
+  fs.rmSync(absoluteTarget, { recursive: true, force: true });
+
+  try {
+    fs.mkdirSync(evidenceDirectory, { recursive: true });
+    fs.writeFileSync(evidenceFile, learningInstinctEvidenceText, 'utf8');
+
+    const observed = parseJsonOutput(run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--observe', '--from-file', evidenceFile, '--confirm', '--json', '--root', target], {}, options), 'learning --observe --confirm --json');
+    const observationFile = observed.learning_file;
+    if (!observationFile || !observationFile.endsWith('.learning-observation.json')) throw new Error('learning observation setup did not return an observation sidecar');
+
+    const instinctPreview = parseJsonOutput(run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--instincts', '--from-observations', observationFile, '--preview', '--json', '--root', target], {}, options), 'learning --instincts --preview --json');
+    assertJsonMarkers(learningInstinctPreviewJsonMarkers(instinctPreview), 'learning --instincts --preview --json');
+    if (!instinctPreview.candidate_instinct?.candidate_instinct_digest) throw new Error('candidate instinct preview missing digest');
+    if (fs.existsSync(path.join(absoluteTarget, '.vibecoding-state', 'learning')) && fs.readdirSync(path.join(absoluteTarget, '.vibecoding-state', 'learning')).some((entry) => entry.endsWith('.candidate-instinct.json'))) throw new Error('learning --instincts preview wrote candidate instinct sidecar');
+
+    const instinctConfirmed = parseJsonOutput(run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--instincts', '--from-observations', observationFile, '--confirm', '--json', '--root', target], {}, options), 'learning --instincts --confirm --json');
+    const instinctFile = instinctConfirmed.candidate_instinct_file;
+    if (!instinctFile || !instinctFile.endsWith('.candidate-instinct.json')) throw new Error('learning --instincts confirm did not return candidate instinct sidecar file');
+    const instinctPath = path.join(absoluteTarget, '.vibecoding-state', 'learning', instinctFile);
+    if (!fs.existsSync(instinctPath)) throw new Error('learning --instincts confirm did not write candidate instinct sidecar');
+
+    const promotionPreview = parseJsonOutput(run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--promote', '--instinct', instinctFile, '--preview', '--json', '--root', target], {}, options), 'learning --promote --preview --json');
+    assertJsonMarkers(learningPromotionPreviewJsonMarkers(promotionPreview), 'learning --promote --preview --json');
+    if (!promotionPreview.learning_promotion?.required_workflow?.includes('vibe-writing-skills')) throw new Error('learning promotion preview missing vibe-writing-skills handoff');
+    if (fs.readdirSync(path.join(absoluteTarget, '.vibecoding-state', 'learning')).some((entry) => entry.endsWith('.learning-promotion.json'))) throw new Error('learning --promote preview wrote promotion sidecar');
+
+    const promotionConfirmed = parseJsonOutput(run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--promote', '--instinct', instinctFile, '--confirm', '--json', '--root', target], {}, options), 'learning --promote --confirm --json');
+    const promotionFile = promotionConfirmed.learning_promotion_file;
+    if (!promotionFile || !promotionFile.endsWith('.learning-promotion.json')) throw new Error('learning --promote confirm did not return promotion sidecar file');
+    const promotionPath = path.join(absoluteTarget, '.vibecoding-state', 'learning', promotionFile);
+    if (!fs.existsSync(promotionPath)) throw new Error('learning --promote confirm did not write promotion sidecar');
+    const extraStateEntries = fs.readdirSync(path.join(absoluteTarget, '.vibecoding-state')).filter((entry) => entry !== 'learning');
+    if (extraStateEntries.length > 0) throw new Error(`learning instinct smoke wrote unexpected state entries: ${extraStateEntries.join(', ')}`);
+
+    const listed = parseJsonOutput(run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--list', '--json', '--root', target], {}, options), 'learning --list --json');
+    assertJsonMarkers(learningListJsonMarkers(listed), 'learning --list --json');
+
+    for (const fileName of [observationFile, instinctFile, promotionFile]) {
+      const verified = parseJsonOutput(run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--verify', fileName, '--json', '--root', target], {}, options), `learning --verify ${fileName} --json`);
+      if (verified.verification?.ok !== true) throw new Error(`learning verify failed for ${fileName}`);
+    }
+
+    run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--instincts', '--from-observations', '../bad.learning-observation.json', '--root', target], {
+      allowFailure: true,
+      expectOutput: ['Learning observation file must not include path separators'],
+    }, options);
+
+    const badCandidate = JSON.parse(fs.readFileSync(instinctPath, 'utf8'));
+    badCandidate.candidate_instinct.evidence_observations[0].observation_digest = '0'.repeat(64);
+    const badCandidatePayload = { ...badCandidate.candidate_instinct };
+    delete badCandidatePayload.writes;
+    delete badCandidatePayload.candidate_instinct_digest;
+    badCandidate.candidate_instinct.candidate_instinct_digest = digestObject(badCandidatePayload);
+    fs.writeFileSync(path.join(absoluteTarget, '.vibecoding-state', 'learning', 'bad-digest.candidate-instinct.json'), `${JSON.stringify(badCandidate, null, 2)}\n`, 'utf8');
+    run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--verify', 'bad-digest.candidate-instinct.json', '--root', target], {
+      allowFailure: true,
+      expectOutput: ['candidate instinct verification failed:', 'candidate_instinct observation digest mismatch'],
+    }, options);
+
+    const badPromotion = JSON.parse(fs.readFileSync(promotionPath, 'utf8'));
+    badPromotion.learning_promotion.automatic_promotion = true;
+    const badPromotionPayload = { ...badPromotion.learning_promotion };
+    delete badPromotionPayload.writes;
+    delete badPromotionPayload.learning_promotion_digest;
+    badPromotion.learning_promotion.learning_promotion_digest = digestObject(badPromotionPayload);
+    fs.writeFileSync(path.join(absoluteTarget, '.vibecoding-state', 'learning', 'bad-boundary.learning-promotion.json'), `${JSON.stringify(badPromotion, null, 2)}\n`, 'utf8');
+    run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--verify', 'bad-boundary.learning-promotion.json', '--root', target], {
+      allowFailure: true,
+      expectOutput: ['learning promotion verification failed:', 'learning_promotion.automatic_promotion must be false'],
+    }, options);
+  } finally {
+    if (!options.keepTmp) fs.rmSync(absoluteTarget, { recursive: true, force: true });
+  }
+}
+
+function runLearningAdviceSmoke(options) {
+  const target = '.tmp/vibe-learning-advice';
+  const absoluteTarget = path.join(repoRoot, target);
+  const evidenceDirectory = path.join(absoluteTarget, 'evidence');
+  const evidenceFile = path.join(evidenceDirectory, 'session-learning.json');
+  fs.rmSync(absoluteTarget, { recursive: true, force: true });
+
+  try {
+    fs.mkdirSync(evidenceDirectory, { recursive: true });
+    fs.writeFileSync(evidenceFile, learningAdviceEvidenceText, 'utf8');
+
+    const intentAdvice = parseJsonOutput(run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--advice', '--intent', 'correction', '--json', '--root', target], {}, options), 'learning --advice --intent correction --json');
+    assertJsonMarkers(learningIntentAdviceJsonMarkers(intentAdvice), 'learning --advice --intent correction --json');
+    if (!intentAdvice.learning_advice?.advice_digest) throw new Error('learning advice missing advice digest');
+    if (fs.existsSync(path.join(absoluteTarget, '.vibecoding-state'))) throw new Error('learning --advice intent created state directory');
+
+    const textAdvice = run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--advice', '--intent', 'repeated-workflow', '--root', target], {
+      expectOutput: learningAdviceTextMarkers,
+    }, options);
+    if (textAdvice.status !== 0) throw new Error('learning --advice text smoke failed');
+
+    const unknownAdvice = parseJsonOutput(run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--advice', '--intent', 'unknown-kind', '--json', '--root', target], {}, options), 'learning --advice --intent unknown-kind --json');
+    assertJsonMarkers(learningUnknownAdviceJsonMarkers(unknownAdvice), 'learning --advice --intent unknown-kind --json');
+    if (!unknownAdvice.quality?.some((item) => item.includes('unknown learning advice intent'))) throw new Error('learning advice unknown intent did not report quality marker');
+
+    const observed = parseJsonOutput(run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--observe', '--from-file', evidenceFile, '--confirm', '--json', '--root', target], {}, options), 'learning --observe --confirm --json');
+    const observationFile = observed.learning_file;
+    if (!observationFile || !observationFile.endsWith('.learning-observation.json')) throw new Error('learning advice setup did not return observation sidecar');
+
+    const observationAdvice = parseJsonOutput(run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--advice', '--from-observations', observationFile, '--json', '--root', target], {}, options), 'learning --advice --from-observations --json');
+    assertJsonMarkers(learningObservationAdviceJsonMarkers(observationAdvice), 'learning --advice --from-observations --json');
+    if (!observationAdvice.learning_advice?.recommended_command?.includes('learning --instincts --from-observations')) throw new Error('learning observation advice missing candidate instinct preview command');
+    if (fs.readdirSync(path.join(absoluteTarget, '.vibecoding-state', 'learning')).some((entry) => entry.endsWith('.candidate-instinct.json'))) throw new Error('learning advice from observations wrote candidate instinct sidecar');
+
+    const instinctConfirmed = parseJsonOutput(run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--instincts', '--from-observations', observationFile, '--confirm', '--json', '--root', target], {}, options), 'learning --instincts --confirm --json');
+    const instinctFile = instinctConfirmed.candidate_instinct_file;
+    if (!instinctFile || !instinctFile.endsWith('.candidate-instinct.json')) throw new Error('learning advice setup did not return candidate instinct sidecar');
+
+    const instinctAdvice = parseJsonOutput(run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--advice', '--instinct', instinctFile, '--json', '--root', target], {}, options), 'learning --advice --instinct --json');
+    assertJsonMarkers(learningInstinctAdviceJsonMarkers(instinctAdvice, instinctFile), 'learning --advice --instinct --json');
+    if (!instinctAdvice.learning_advice?.candidate_instinct_digest) throw new Error('learning instinct advice missing candidate instinct digest');
+    if (fs.readdirSync(path.join(absoluteTarget, '.vibecoding-state', 'learning')).some((entry) => entry.endsWith('.learning-promotion.json'))) throw new Error('learning advice from instinct wrote promotion sidecar');
+
+    run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--advice', '--from-observations', observationFile, '--instinct', instinctFile, '--root', target], {
+      allowFailure: true,
+      expectOutput: ['learning --advice accepts either --from-observations or --instinct, not both'],
+    }, options);
+
+    for (const forbidden of learningAdviceForbiddenFlags) {
+      run('node', ['tools/vibe-runtime/index.mjs', 'learning', '--advice', '--intent', 'correction', forbidden, '--root', target], {
+        allowFailure: true,
+        expectOutput: learningAdviceForbiddenOutputMarkers(forbidden),
+      }, options);
+    }
+  } finally {
+    if (!options.keepTmp) fs.rmSync(absoluteTarget, { recursive: true, force: true });
+  }
+}
+
+
+  return {
+    runLearningObservationSmoke,
+    runLearningInstinctSmoke,
+    runLearningAdviceSmoke,
+  };
+}