@jtf19/vibecoding-kit 0.1.0

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

@@ -0,0 +1,509 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  firstLearningSignal,
+  isLearningObservationDomain,
+  isLearningObservationScope,
+  learningInstinctStatusAndBlocks,
+  learningObservationBoundaryAssertions,
+  learningSignalCount,
+  learningSignalsFromEvidence,
+  normalizeLearningConfidenceDelta,
+  normalizeLearningDomain,
+  normalizeLearningScope,
+} from './runtime-learning-observation-model.mjs';
+
+const learningCandidateSafetyFlags = {
+  formal_skill_mutation: false,
+  skill_mutation: false,
+  prompt_mutation: false,
+  hook_registration: false,
+  shell_interception: false,
+  cross_project_share: false,
+  local_only: true,
+  no_skill_mutation: true,
+  no_prompt_mutation: true,
+  no_cross_project_share: true,
+};
+
+export function createRuntimeLearningArtifactModel(deps) {
+  const {
+    jsonSchemaVersion,
+    learningDirectory,
+    listStateFiles,
+    readJsonArtifact,
+    fileDigest,
+    digestObject,
+    stableStringify,
+    stateDirectory,
+  } = deps;
+  const stateArtifactWriter = deps['write' + 'StateArtifact'];
+
+  const learningSnapshotPath = (root) => {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return path.join(learningDirectory(root), `${timestamp}.learning-observation.json`);
+  };
+
+  const learningCandidateInstinctSnapshotPath = (root) => {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return path.join(learningDirectory(root), `${timestamp}.candidate-instinct.json`);
+  };
+
+  const learningPromotionSnapshotPath = (root) => {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return path.join(learningDirectory(root), `${timestamp}.learning-promotion.json`);
+  };
+
+  const listLearningObservationFiles = (root) => listStateFiles(root, learningDirectory, '.learning-observation.json');
+  const listLearningCandidateInstinctFiles = (root) => listStateFiles(root, learningDirectory, '.candidate-instinct.json');
+  const listLearningPromotionFiles = (root) => listStateFiles(root, learningDirectory, '.learning-promotion.json');
+
+  function learningRootRelativeEvidenceFilePath(root, evidencePath, label) {
+    const raw = String(evidencePath || '').trim();
+    if (!raw) throw new Error(`${label} is required`);
+    if (path.isAbsolute(raw)) throw new Error(`${label} must be relative: ${raw}`);
+    if (raw.includes('\\')) throw new Error(`${label} must use forward slashes: ${raw}`);
+    if (raw.split('/').some((part) => part === '' || part === '.' || part === '..')) throw new Error(`${label} must not include traversal: ${raw}`);
+    const file = path.join(root, ...raw.split('/'));
+    const relative = path.relative(root, file);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error(`${label} escapes root: ${raw}`);
+    return file;
+  }
+
+  function learningEvidenceDescriptor(root, evidenceFile) {
+    const absolute = path.resolve(evidenceFile || '');
+    const relative = path.relative(root, absolute).replace(/\\/g, '/');
+    const file = learningRootRelativeEvidenceFilePath(root, relative, 'learning.source_file');
+    if (!fs.existsSync(file)) throw new Error(`learning evidence file not found: ${relative}`);
+    return { path: relative, file, digest: fileDigest(file), payload: readJsonArtifact(file, 'Learning evidence') };
+  }
+
+  function learningObservationPayload(root, { evidenceFile } = {}) {
+    const evidence = learningEvidenceDescriptor(root, evidenceFile);
+    const input = evidence.payload || {};
+    const signals = learningSignalsFromEvidence(input, { stableStringify });
+    const signalCount = learningSignalCount(signals);
+    const excerpt = String(input.evidence_excerpt || input.excerpt || '').trim();
+    const excerptDigest = digestObject({ source_digest: evidence.digest, excerpt: excerpt || stableStringify(signals) });
+    const payload = {
+      version: 1,
+      stage: 'Stage 61',
+      artifact_kind: 'learning-observation',
+      optional: true,
+      sidecar_only: true,
+      default_enabled: false,
+      release_chain_required: false,
+      created_at: new Date().toISOString(),
+      status: signalCount > 0 ? 'observation_recorded' : 'manual_required',
+      source_file: evidence.path,
+      source_digest: evidence.digest,
+      project_id: String(input.project_id || path.basename(root) || 'local-project').trim(),
+      scope: normalizeLearningScope(input.scope),
+      domain: normalizeLearningDomain(input.domain),
+      confidence_delta: normalizeLearningConfidenceDelta(input.confidence_delta),
+      evidence_excerpt_digest: excerptDigest,
+      signals,
+      signals_digest: digestObject(signals),
+      signal_count: signalCount,
+      candidate_only: true,
+      promotion_required: true,
+      allowed_followup: ['candidate_instinct_preview', 'manual_review', 'vibe-writing-skills'],
+      blocked_reasons: signalCount > 0 ? [] : ['local evidence did not contain any learning signal'],
+      boundary_assertions: learningObservationBoundaryAssertions(),
+      local_only: true,
+      no_skill_mutation: true,
+      no_prompt_mutation: true,
+      no_cross_project_share: true,
+    };
+    return { ...payload, learning_observation_digest: digestObject(payload) };
+  }
+
+  function learningObservationEnvelope(root, { evidenceFile, persist = false } = {}) {
+    const observation = learningObservationPayload(root, { evidenceFile });
+    return {
+      mode: 'learning-observation',
+      ok: observation.status === 'observation_recorded',
+      state_present: fs.existsSync(stateDirectory(root)),
+      learning_observation: { ...observation, writes: Boolean(persist) },
+      safety: {
+        stage: 'Stage 61',
+        writes: Boolean(persist),
+        learning_observation_artifact: Boolean(persist),
+        optional: true,
+        sidecar_only: true,
+        default_enabled: false,
+        release_chain_required: false,
+        ...learningObservationBoundaryAssertions(),
+      },
+      quality: observation.blocked_reasons,
+      action: persist
+        ? 'learning observation sidecar was written locally from a local evidence file. No skill, prompt, hook, shell, git, worktree, platform API, external network, model, subagent, or business source mutation occurred.'
+        : 'learning observation was previewed read-only from a local evidence file. No state directory, skill, prompt, hook, shell, git, worktree, platform API, external network, model, subagent, or business source mutation occurred.',
+    };
+  }
+
+  function validateLearningObservationArtifact(root, artifact) {
+    const failures = [];
+    if (artifact.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+    if (artifact.command !== 'learning') failures.push('command must be learning');
+    if (artifact.mode !== 'learning-observation') failures.push('mode must be learning-observation');
+    const observation = artifact.learning_observation || {};
+    if (observation.stage !== 'Stage 61') failures.push('learning_observation.stage must be Stage 61');
+    if (observation.artifact_kind !== 'learning-observation') failures.push('learning_observation.artifact_kind must be learning-observation');
+    if (observation.optional !== true) failures.push('learning_observation.optional must be true');
+    if (observation.sidecar_only !== true) failures.push('learning_observation.sidecar_only must be true');
+    if (observation.default_enabled !== false) failures.push('learning_observation.default_enabled must be false');
+    if (observation.release_chain_required !== false) failures.push('learning_observation.release_chain_required must be false');
+    if (!['observation_recorded', 'manual_required'].includes(observation.status)) failures.push('learning_observation.status is invalid');
+    if (!isLearningObservationScope(observation.scope)) failures.push('learning_observation.scope is invalid');
+    if (!isLearningObservationDomain(observation.domain)) failures.push('learning_observation.domain is invalid');
+    if (!Number.isFinite(Number(observation.confidence_delta)) || Number(observation.confidence_delta) < -1 || Number(observation.confidence_delta) > 1) failures.push('learning_observation.confidence_delta must be between -1 and 1');
+    try {
+      const sourceFile = learningRootRelativeEvidenceFilePath(root, observation.source_file, 'learning.source_file');
+      if (!fs.existsSync(sourceFile)) failures.push(`learning source file missing: ${observation.source_file}`);
+      else {
+        if (fileDigest(sourceFile) !== observation.source_digest) failures.push('learning source digest mismatch');
+        const expected = learningObservationPayload(root, { evidenceFile: sourceFile });
+        if (expected.project_id !== observation.project_id) failures.push('learning project_id drift');
+        if (expected.scope !== observation.scope) failures.push('learning scope drift');
+        if (expected.domain !== observation.domain) failures.push('learning domain drift');
+        if (expected.confidence_delta !== observation.confidence_delta) failures.push('learning confidence_delta drift');
+        if (expected.evidence_excerpt_digest !== observation.evidence_excerpt_digest) failures.push('learning evidence excerpt digest mismatch');
+        if (expected.signals_digest !== observation.signals_digest) failures.push('learning signals digest mismatch');
+        if (expected.signal_count !== observation.signal_count) failures.push('learning signal_count drift');
+      }
+    } catch (error) {
+      failures.push(error.message);
+    }
+    if (!Array.isArray(observation.allowed_followup)) failures.push('learning_observation.allowed_followup must be an array');
+    if (!Array.isArray(observation.blocked_reasons)) failures.push('learning_observation.blocked_reasons must be an array');
+    if (observation.candidate_only !== true) failures.push('learning_observation.candidate_only must be true');
+    if (observation.promotion_required !== true) failures.push('learning_observation.promotion_required must be true');
+    if (observation.local_only !== true) failures.push('learning_observation.local_only must be true');
+    if (observation.no_skill_mutation !== true) failures.push('learning_observation.no_skill_mutation must be true');
+    if (observation.no_prompt_mutation !== true) failures.push('learning_observation.no_prompt_mutation must be true');
+    if (observation.no_cross_project_share !== true) failures.push('learning_observation.no_cross_project_share must be true');
+    for (const [key, expected] of Object.entries(learningObservationBoundaryAssertions())) {
+      if (observation.boundary_assertions?.[key] !== expected) failures.push(`learning_observation.boundary_assertions.${key} must be false`);
+      if (artifact.safety?.[key] !== expected) failures.push(`safety.${key} must be false`);
+    }
+    if (artifact.safety?.optional !== true) failures.push('safety.optional must be true');
+    if (artifact.safety?.sidecar_only !== true) failures.push('safety.sidecar_only must be true');
+    if (artifact.safety?.release_chain_required !== false) failures.push('safety.release_chain_required must be false');
+    const digestPayload = { ...observation };
+    delete digestPayload.writes;
+    delete digestPayload.learning_observation_digest;
+    if (observation.learning_observation_digest !== digestObject(digestPayload)) failures.push('learning observation digest mismatch');
+    return { ok: failures.length === 0, failures };
+  }
+
+  function writeLearningObservation(root, envelope) {
+    const file = learningSnapshotPath(root);
+    const payload = { schema_version: jsonSchemaVersion, command: 'learning', ...envelope, safety: { ...envelope.safety, learning_observation_artifact: true } };
+    const verification = validateLearningObservationArtifact(root, payload);
+    if (!verification.ok) throw new Error(`learning observation verification failed: ${verification.failures.join('; ')}`);
+    return stateArtifactWriter(path.dirname(file), path.basename(file), payload);
+  }
+
+  function learningObservationDescriptor(root, observationFile) {
+    const file = deps.learningObservationFilePath(root, observationFile);
+    const artifact = readJsonArtifact(file, 'Learning observation');
+    const verification = validateLearningObservationArtifact(root, artifact);
+    if (!verification.ok) throw new Error(`learning observation verification failed: ${verification.failures.join('; ')}`);
+    const observation = artifact.learning_observation || {};
+    return {
+      file: path.basename(file),
+      file_digest: fileDigest(file),
+      observation_digest: observation.learning_observation_digest || '',
+      observation,
+    };
+  }
+
+  function learningCandidateInstinctPayload(root, { observationFiles = [], createdAt = new Date().toISOString() } = {}) {
+    const descriptors = [...observationFiles].map((file) => learningObservationDescriptor(root, file)).sort((left, right) => left.file.localeCompare(right.file));
+    const firstDescriptor = descriptors[0] || { observation: {} };
+    const signal = firstLearningSignal(firstDescriptor.observation || {});
+    const status = learningInstinctStatusAndBlocks(descriptors, signal);
+    const confidenceDeltas = descriptors.map((item) => Number(item.observation.confidence_delta || 0)).filter((value) => Number.isFinite(value));
+    const averageDelta = confidenceDeltas.length > 0 ? confidenceDeltas.reduce((sum, value) => sum + value, 0) / confidenceDeltas.length : 0;
+    const confidence = Number(Math.max(0, Math.min(1, 0.5 + averageDelta / 2)).toFixed(3));
+    const scope = descriptors.some((item) => item.observation.scope === 'project') ? 'project' : 'global-candidate';
+    const domain = firstDescriptor.observation.domain || 'workflow';
+    const projectId = firstDescriptor.observation.project_id || path.basename(root) || 'local-project';
+    const evidenceObservations = descriptors.map((item) => ({
+      file: item.file,
+      file_digest: item.file_digest,
+      observation_digest: item.observation_digest,
+      project_id: item.observation.project_id || '',
+      scope: item.observation.scope || '',
+      domain: item.observation.domain || '',
+      signal_count: item.observation.signal_count || 0,
+    }));
+    const trigger = signal.signal_text ? `domain=${domain}; signal=${signal.signal_type}; when ${signal.signal_text}` : `domain=${domain}; signal=none; manual review required`;
+    const action = signal.signal_text ? `Prefer the project-scoped learned response: ${signal.signal_text}` : 'Review local learning observations manually before creating any formal guidance.';
+    const payload = {
+      version: 1,
+      stage: 'Stage 62',
+      artifact_kind: 'candidate-instinct',
+      optional: true,
+      sidecar_only: true,
+      default_enabled: false,
+      release_chain_required: false,
+      created_at: createdAt,
+      status: status.status,
+      project_id: projectId,
+      scope,
+      domain,
+      atomic: true,
+      one_trigger: true,
+      one_action: true,
+      trigger,
+      action,
+      confidence,
+      evidence_backed: evidenceObservations.length > 0,
+      evidence_observations: evidenceObservations,
+      observation_digests: evidenceObservations.map((item) => item.observation_digest).sort(),
+      evidence_digest: digestObject(evidenceObservations),
+      blocked_reasons: status.blocked_reasons,
+      promotion_required: true,
+      ...learningCandidateSafetyFlags,
+      allowed_followup: ['learning_promotion_preview', 'manual_review', 'vibe-writing-skills'],
+      boundary_assertions: learningObservationBoundaryAssertions(),
+    };
+    return { ...payload, candidate_instinct_digest: digestObject(payload) };
+  }
+
+  function learningCandidateInstinctEnvelope(root, { observationFiles = [], persist = false } = {}) {
+    const candidate = learningCandidateInstinctPayload(root, { observationFiles });
+    return {
+      mode: 'candidate-instinct',
+      ok: candidate.status === 'candidate_ready',
+      state_present: fs.existsSync(stateDirectory(root)),
+      candidate_instinct: { ...candidate, writes: Boolean(persist) },
+      safety: {
+        stage: 'Stage 62',
+        writes: Boolean(persist),
+        candidate_instinct_artifact: Boolean(persist),
+        learning_promotion_artifact: false,
+        optional: true,
+        sidecar_only: true,
+        default_enabled: false,
+        release_chain_required: false,
+        ...learningObservationBoundaryAssertions(),
+      },
+      quality: candidate.blocked_reasons,
+      action: persist
+        ? 'candidate instinct sidecar was written locally from verified learning observations. No formal skill, prompt, hook, shell, git, worktree, platform API, external network, model, subagent, or business source mutation occurred.'
+        : 'candidate instinct was previewed read-only from verified learning observations. No state directory, formal skill, prompt, hook, shell, git, worktree, platform API, external network, model, subagent, or business source mutation occurred.',
+    };
+  }
+
+  function validateLearningCandidateInstinctArtifact(root, artifact) {
+    const failures = [];
+    if (artifact.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+    if (artifact.command !== 'learning') failures.push('command must be learning');
+    if (artifact.mode !== 'candidate-instinct') failures.push('mode must be candidate-instinct');
+    const candidate = artifact.candidate_instinct || {};
+    if (candidate.stage !== 'Stage 62') failures.push('candidate_instinct.stage must be Stage 62');
+    if (candidate.artifact_kind !== 'candidate-instinct') failures.push('candidate_instinct.artifact_kind must be candidate-instinct');
+    if (candidate.optional !== true) failures.push('candidate_instinct.optional must be true');
+    if (candidate.sidecar_only !== true) failures.push('candidate_instinct.sidecar_only must be true');
+    if (candidate.default_enabled !== false) failures.push('candidate_instinct.default_enabled must be false');
+    if (candidate.release_chain_required !== false) failures.push('candidate_instinct.release_chain_required must be false');
+    if (!['candidate_ready', 'manual_review_required'].includes(candidate.status)) failures.push('candidate_instinct.status is invalid');
+    if (candidate.atomic !== true || candidate.one_trigger !== true || candidate.one_action !== true) failures.push('candidate_instinct must be atomic with one trigger and one action');
+    if (!candidate.trigger || !candidate.action) failures.push('candidate_instinct trigger and action are required');
+    if (!Number.isFinite(Number(candidate.confidence)) || Number(candidate.confidence) < 0 || Number(candidate.confidence) > 1) failures.push('candidate_instinct.confidence must be between 0 and 1');
+    if (candidate.evidence_backed !== true) failures.push('candidate_instinct.evidence_backed must be true');
+    if (!Array.isArray(candidate.evidence_observations) || candidate.evidence_observations.length === 0) failures.push('candidate_instinct.evidence_observations must not be empty');
+    for (const evidence of candidate.evidence_observations || []) {
+      try {
+        const descriptor = learningObservationDescriptor(root, evidence.file);
+        if (descriptor.file_digest !== evidence.file_digest) failures.push(`candidate_instinct observation file digest mismatch: ${evidence.file}`);
+        if (descriptor.observation_digest !== evidence.observation_digest) failures.push(`candidate_instinct observation digest mismatch: ${evidence.file}`);
+      } catch (error) {
+        failures.push(error.message);
+      }
+    }
+    try {
+      const expected = learningCandidateInstinctPayload(root, { observationFiles: (candidate.evidence_observations || []).map((item) => item.file), createdAt: candidate.created_at });
+      for (const key of ['project_id', 'scope', 'domain', 'trigger', 'action', 'confidence', 'evidence_digest', 'candidate_instinct_digest']) {
+        if (candidate[key] !== expected[key]) failures.push(`candidate_instinct.${key} drift`);
+      }
+    } catch (error) {
+      failures.push(error.message);
+    }
+    if (candidate.promotion_required !== true) failures.push('candidate_instinct.promotion_required must be true');
+    for (const key of ['formal_skill_mutation', 'skill_mutation', 'prompt_mutation', 'hook_registration', 'shell_interception', 'cross_project_share']) if (candidate[key] !== false) failures.push(`candidate_instinct.${key} must be false`);
+    for (const [key, expected] of Object.entries(learningObservationBoundaryAssertions())) {
+      if (candidate.boundary_assertions?.[key] !== expected) failures.push(`candidate_instinct.boundary_assertions.${key} must be false`);
+      if (artifact.safety?.[key] !== expected) failures.push(`safety.${key} must be false`);
+    }
+    if (artifact.safety?.candidate_instinct_artifact !== true) failures.push('safety.candidate_instinct_artifact must be true');
+    if (artifact.safety?.learning_promotion_artifact !== false) failures.push('safety.learning_promotion_artifact must be false');
+    const digestPayload = { ...candidate };
+    delete digestPayload.writes;
+    delete digestPayload.candidate_instinct_digest;
+    if (candidate.candidate_instinct_digest !== digestObject(digestPayload)) failures.push('candidate instinct digest mismatch');
+    return { ok: failures.length === 0, failures };
+  }
+
+  function writeLearningCandidateInstinct(root, envelope) {
+    const file = learningCandidateInstinctSnapshotPath(root);
+    const payload = { schema_version: jsonSchemaVersion, command: 'learning', ...envelope, safety: { ...envelope.safety, candidate_instinct_artifact: true } };
+    const verification = validateLearningCandidateInstinctArtifact(root, payload);
+    if (!verification.ok) throw new Error(`candidate instinct verification failed: ${verification.failures.join('; ')}`);
+    return stateArtifactWriter(path.dirname(file), path.basename(file), payload);
+  }
+
+  function learningCandidateInstinctDescriptor(root, instinctFile) {
+    const file = deps.learningCandidateInstinctFilePath(root, instinctFile);
+    const artifact = readJsonArtifact(file, 'Candidate instinct');
+    const verification = validateLearningCandidateInstinctArtifact(root, artifact);
+    if (!verification.ok) throw new Error(`candidate instinct verification failed: ${verification.failures.join('; ')}`);
+    return { file: path.basename(file), file_digest: fileDigest(file), candidate: artifact.candidate_instinct || {}, artifact };
+  }
+
+  function learningPromotionPayload(root, { instinctFile, createdAt = new Date().toISOString() } = {}) {
+    const descriptor = learningCandidateInstinctDescriptor(root, instinctFile);
+    const candidate = descriptor.candidate;
+    const blockedReasons = candidate.status === 'candidate_ready' ? [] : ['candidate instinct is not ready for promotion'];
+    const payload = {
+      version: 1,
+      stage: 'Stage 62',
+      artifact_kind: 'learning-promotion',
+      optional: true,
+      sidecar_only: true,
+      default_enabled: false,
+      release_chain_required: false,
+      created_at: createdAt,
+      status: blockedReasons.length === 0 ? 'promotion_suggested' : 'manual_review_required',
+      instinct_file: descriptor.file,
+      instinct_file_digest: descriptor.file_digest,
+      candidate_instinct_digest: candidate.candidate_instinct_digest || '',
+      project_id: candidate.project_id || '',
+      scope: candidate.scope || 'project',
+      domain: candidate.domain || 'workflow',
+      confidence: candidate.confidence ?? 0,
+      promotion_target: 'manual-skill-authoring',
+      human_approval_required: true,
+      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,
+      cross_project_share: false,
+      required_workflow: ['vibe-writing-skills', 'vibe-writing-plans', 'vibe-test-driven-development', 'vibe-review'],
+      recommended_change: {
+        trigger: candidate.trigger || '',
+        action: candidate.action || '',
+        target_scope: candidate.scope || 'project',
+        evidence_digest: candidate.evidence_digest || '',
+      },
+      blocked_reasons: blockedReasons,
+      allowed_followup: ['vibe-writing-skills', 'manual_review'],
+      boundary_assertions: learningObservationBoundaryAssertions(),
+      local_only: true,
+      no_skill_mutation: true,
+      no_prompt_mutation: true,
+      no_cross_project_share: true,
+    };
+    return { ...payload, learning_promotion_digest: digestObject(payload) };
+  }
+
+  function learningPromotionEnvelope(root, { instinctFile, persist = false } = {}) {
+    const promotion = learningPromotionPayload(root, { instinctFile });
+    return {
+      mode: 'learning-promotion',
+      ok: promotion.status === 'promotion_suggested',
+      state_present: fs.existsSync(stateDirectory(root)),
+      learning_promotion: { ...promotion, writes: Boolean(persist) },
+      safety: {
+        stage: 'Stage 62',
+        writes: Boolean(persist),
+        candidate_instinct_artifact: false,
+        learning_promotion_artifact: Boolean(persist),
+        optional: true,
+        sidecar_only: true,
+        default_enabled: false,
+        release_chain_required: false,
+        ...learningObservationBoundaryAssertions(),
+      },
+      quality: promotion.blocked_reasons,
+      action: persist
+        ? 'learning promotion sidecar was written locally as a manual skill-authoring gate. No formal skill, prompt, hook, shell, git, worktree, platform API, external network, model, subagent, or business source mutation occurred.'
+        : 'learning promotion was previewed read-only as a manual skill-authoring gate. No state directory, formal skill, prompt, hook, shell, git, worktree, platform API, external network, model, subagent, or business source mutation occurred.',
+    };
+  }
+
+  function validateLearningPromotionArtifact(root, artifact) {
+    const failures = [];
+    if (artifact.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+    if (artifact.command !== 'learning') failures.push('command must be learning');
+    if (artifact.mode !== 'learning-promotion') failures.push('mode must be learning-promotion');
+    const promotion = artifact.learning_promotion || {};
+    if (promotion.stage !== 'Stage 62') failures.push('learning_promotion.stage must be Stage 62');
+    if (promotion.artifact_kind !== 'learning-promotion') failures.push('learning_promotion.artifact_kind must be learning-promotion');
+    if (promotion.optional !== true) failures.push('learning_promotion.optional must be true');
+    if (promotion.sidecar_only !== true) failures.push('learning_promotion.sidecar_only must be true');
+    if (promotion.default_enabled !== false) failures.push('learning_promotion.default_enabled must be false');
+    if (promotion.release_chain_required !== false) failures.push('learning_promotion.release_chain_required must be false');
+    if (!['promotion_suggested', 'manual_review_required'].includes(promotion.status)) failures.push('learning_promotion.status is invalid');
+    try {
+      const descriptor = learningCandidateInstinctDescriptor(root, promotion.instinct_file);
+      if (descriptor.file_digest !== promotion.instinct_file_digest) failures.push('learning_promotion instinct file digest mismatch');
+      if (descriptor.candidate.candidate_instinct_digest !== promotion.candidate_instinct_digest) failures.push('learning_promotion candidate instinct digest mismatch');
+      const expected = learningPromotionPayload(root, { instinctFile: promotion.instinct_file, createdAt: promotion.created_at });
+      for (const key of ['status', 'project_id', 'scope', 'domain', 'confidence', 'learning_promotion_digest']) {
+        if (promotion[key] !== expected[key]) failures.push(`learning_promotion.${key} drift`);
+      }
+    } catch (error) {
+      failures.push(error.message);
+    }
+    for (const key of ['human_approval_required']) if (promotion[key] !== true) failures.push(`learning_promotion.${key} must be true`);
+    for (const key of ['automatic_promotion', 'writes_formal_skills', 'writes_agents_md', 'writes_claude_md', 'skill_mutation', 'prompt_mutation', 'hook_registration', 'shell_interception', 'cross_project_share']) if (promotion[key] !== false) failures.push(`learning_promotion.${key} must be false`);
+    if (!Array.isArray(promotion.required_workflow) || !promotion.required_workflow.includes('vibe-writing-skills')) failures.push('learning_promotion.required_workflow must include vibe-writing-skills');
+    for (const [key, expected] of Object.entries(learningObservationBoundaryAssertions())) {
+      if (promotion.boundary_assertions?.[key] !== expected) failures.push(`learning_promotion.boundary_assertions.${key} must be false`);
+      if (artifact.safety?.[key] !== expected) failures.push(`safety.${key} must be false`);
+    }
+    if (artifact.safety?.candidate_instinct_artifact !== false) failures.push('safety.candidate_instinct_artifact must be false');
+    if (artifact.safety?.learning_promotion_artifact !== true) failures.push('safety.learning_promotion_artifact must be true');
+    const digestPayload = { ...promotion };
+    delete digestPayload.writes;
+    delete digestPayload.learning_promotion_digest;
+    if (promotion.learning_promotion_digest !== digestObject(digestPayload)) failures.push('learning promotion digest mismatch');
+    return { ok: failures.length === 0, failures };
+  }
+
+  function writeLearningPromotion(root, envelope) {
+    const file = learningPromotionSnapshotPath(root);
+    const payload = { schema_version: jsonSchemaVersion, command: 'learning', ...envelope, safety: { ...envelope.safety, learning_promotion_artifact: true } };
+    const verification = validateLearningPromotionArtifact(root, payload);
+    if (!verification.ok) throw new Error(`learning promotion verification failed: ${verification.failures.join('; ')}`);
+    return stateArtifactWriter(path.dirname(file), path.basename(file), payload);
+  }
+
+  return {
+    learningObservationFilePath: deps.learningObservationFilePath,
+    learningCandidateInstinctFilePath: deps.learningCandidateInstinctFilePath,
+    learningPromotionFilePath: deps.learningPromotionFilePath,
+    listLearningObservationFiles,
+    listLearningCandidateInstinctFiles,
+    listLearningPromotionFiles,
+    learningObservationDescriptor,
+    learningCandidateInstinctDescriptor,
+    learningObservationEnvelope,
+    writeLearningObservation,
+    learningCandidateInstinctEnvelope,
+    writeLearningCandidateInstinct,
+    learningPromotionEnvelope,
+    writeLearningPromotion,
+    validateLearningObservationArtifact,
+    validateLearningCandidateInstinctArtifact,
+    validateLearningPromotionArtifact,
+  };
+}

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

@@ -0,0 +1,106 @@
+import path from 'node:path';
+import {
+  learningArtifactAuditSummaryModel,
+  learningArtifactSummaryModel,
+  learningInvalidArtifactSummary,
+} from './runtime-learning-observation-model.mjs';
+
+export const runtimeLearningAuditModelContractSync = {
+  runtime_check_owner: 'tools/vibe-runtime-check/index.mjs',
+  release_check_owner: 'tools/vibe-release-check',
+};
+
+const learningAuditActionText = Object.freeze({
+  observation: 'read-only learning audit inspected one learning observation sidecar. No skill, prompt, hook, shell, git, worktree, platform API, external network, model, subagent, or business source mutation occurred.',
+  candidate: 'read-only learning audit inspected one candidate instinct sidecar. No skill, prompt, hook, shell, git, worktree, platform API, external network, model, subagent, or business source mutation occurred.',
+  promotion: 'read-only learning audit inspected one promotion gate sidecar. No skill, prompt, hook, shell, git, worktree, platform API, external network, model, subagent, or business source mutation occurred.',
+});
+
+export function createRuntimeLearningAuditModel(deps) {
+  const {
+    readJsonArtifact,
+    learningObservationFilePath,
+    learningCandidateInstinctFilePath,
+    learningPromotionFilePath,
+    validateLearningObservationArtifact,
+    validateLearningCandidateInstinctArtifact,
+    validateLearningPromotionArtifact,
+  } = deps;
+
+  const artifactSpecs = Object.freeze([
+    {
+      suffix: '.learning-observation.json',
+      kind: 'learning-observation',
+      label: 'Learning observation',
+      resolveFile: learningObservationFilePath,
+      verify: validateLearningObservationArtifact,
+      verifyError: 'learning observation verification failed',
+      action: learningAuditActionText.observation,
+    },
+    {
+      suffix: '.candidate-instinct.json',
+      kind: 'candidate-instinct',
+      label: 'Candidate instinct',
+      resolveFile: learningCandidateInstinctFilePath,
+      verify: validateLearningCandidateInstinctArtifact,
+      verifyError: 'candidate instinct verification failed',
+      action: learningAuditActionText.candidate,
+    },
+    {
+      suffix: '.learning-promotion.json',
+      kind: 'learning-promotion',
+      label: 'Learning promotion',
+      resolveFile: learningPromotionFilePath,
+      verify: validateLearningPromotionArtifact,
+      verifyError: 'learning promotion verification failed',
+      action: learningAuditActionText.promotion,
+    },
+  ]);
+
+  const promotionSpec = artifactSpecs[2];
+
+  function specForKnownArtifact(fileName) {
+    return artifactSpecs.find((spec) => fileName.endsWith(spec.suffix));
+  }
+
+  function artifactReadResult(root, fileName, spec) {
+    const file = spec.resolveFile(root, fileName);
+    const artifact = readJsonArtifact(file, spec.label);
+    const verification = spec.verify(root, artifact);
+    return { file, artifact, verification };
+  }
+
+  function learningArtifactSummary(root, fileName) {
+    try {
+      const spec = specForKnownArtifact(fileName) || promotionSpec;
+      const result = artifactReadResult(root, fileName, spec);
+      return learningArtifactSummaryModel(spec.kind, fileName, result.artifact, result.verification);
+    } catch (error) {
+      return learningInvalidArtifactSummary(fileName, error);
+    }
+  }
+
+  function learningArtifactAuditEnvelope(root, mode, learningFile = '') {
+    const fileName = String(learningFile || '').trim();
+    const spec = specForKnownArtifact(fileName);
+    if (!spec) throw new Error('learning artifact file extension is unsupported');
+    const result = artifactReadResult(root, fileName, spec);
+    if (mode === 'verify' && !result.verification.ok) {
+      throw new Error(`${spec.verifyError}: ${result.verification.failures.join('; ')}`);
+    }
+    return {
+      mode: mode === 'verify' ? 'learning-verify' : 'learning-show',
+      ok: result.verification.ok,
+      summary: learningArtifactAuditSummaryModel(spec.kind, path.basename(result.file), result.artifact),
+      verification: result.verification,
+      artifact: result.artifact,
+      quality: result.verification.failures,
+      action: spec.action,
+    };
+  }
+
+  return {
+    learningArtifactSummary,
+    learningArtifactAuditEnvelope,
+  };
+}