scene-capability-engine 3.6.65 → 3.6.67

package/lib/commands/semantic.js

@@ -0,0 +1,1459 @@
+const fs = require('fs-extra');
+const chalk = require('chalk');
+const { getSceStateStore } = require('../state/sce-state-store');
+const { observeSemanticInteraction } = require('../semantic/interaction-observer');
+const {
+  collectSemanticReplayInputs,
+  evaluateSemanticCandidate
+} = require('../semantic/replay-evaluator');
+const {
+  syncSemanticCapabilityLedger,
+  listPromotedSemanticBehaviors,
+  promoteSemanticLessonCandidate,
+  rollbackPromotedSemanticLesson
+} = require('../semantic/kernel-loader');
+const { buildSemanticProgressReport } = require('../semantic/progress-ledger');
+const { buildSupremeIntentGovernanceReport } = require('../semantic/supreme-intent-report');
+const { buildSemanticBackflowReport } = require('../semantic/backflow-report');
+const { buildSemanticArchiveReport } = require('../semantic/archive-report');
+const { exportSemanticLibraryDelta } = require('../semantic/delta-export');
+const { publishSemanticLibraryDelta } = require('../semantic/shared-publication');
+const { exportSemanticSharedSyncBundle } = require('../semantic/shared-sync-export');
+const { syncSemanticSharedBundle, inspectSemanticSharedSource } = require('../semantic/shared-sync-intake');
+const { listSemanticSharedSources, upsertSemanticSharedSource } = require('../semantic/shared-source-config');
+const { connectSemanticSharedSource } = require('../semantic/shared-source-connect');
+const { mergeSemanticSharedBundles } = require('../semantic/shared-sync-merge');
+const { publishSemanticSharedRegistry } = require('../semantic/shared-sync-release');
+
+function normalizeString(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function normalizeInteger(value, fallback = 0) {
+  const parsed = Number.parseInt(`${value}`, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return fallback;
+  }
+  return parsed;
+}
+
+async function loadInputPayload(options = {}, fileSystem = fs) {
+  const inputFile = normalizeString(options.inputFile);
+  if (!inputFile) {
+    return {};
+  }
+  return fileSystem.readJson(inputFile);
+}
+
+function printPayload(payload, options = {}) {
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  if (payload.mode === 'semantic-observe') {
+    console.log(chalk.blue(`Semantic observation: ${payload.observation.observation_id}`));
+    console.log(`  Runtime: ${payload.observation.source_runtime}`);
+    console.log(`  Event: ${payload.observation.event_kind}`);
+    console.log(`  Intent: ${payload.observation.intent}`);
+    console.log(`  Outcome: ${payload.observation.outcome}`);
+    if (payload.lesson_candidate) {
+      console.log(`  Lesson: ${payload.lesson_candidate.lesson_id} (${payload.lesson_candidate.lesson_type})`);
+    }
+    return;
+  }
+
+  if (payload.mode === 'semantic-list') {
+    console.log(chalk.blue(`Semantic observations: ${payload.total}`));
+    for (const item of payload.items) {
+      console.log(`  - ${item.observation_id} | ${item.source_runtime} | ${item.event_kind} | ${item.intent} | ${item.outcome}`);
+    }
+    return;
+  }
+
+  if (payload.mode === 'semantic-lessons') {
+    console.log(chalk.blue(`Semantic lesson candidates: ${payload.total}`));
+    for (const item of payload.items) {
+      console.log(`  - ${item.lesson_id} | ${item.lesson_type} | ${item.status} | ${item.title}`);
+    }
+    return;
+  }
+
+  if (payload.mode === 'semantic-replay') {
+    console.log(chalk.blue(`Semantic replay dataset: ${payload.replay_dataset.total_observations}`));
+    console.log(`  Expected terms: ${payload.replay_dataset.expected_terms.join(', ') || 'none'}`);
+    console.log(`  Specs: ${payload.replay_dataset.context.spec_ids.join(', ') || 'unknown'}`);
+    return;
+  }
+
+  if (payload.mode === 'semantic-eval') {
+    console.log(chalk.blue(`Semantic evaluation: ${payload.evaluation_run.evaluation_run_id}`));
+    console.log(`  Verdict: ${payload.evaluation_run.verdict}`);
+    console.log(`  Score: ${payload.evaluation_run.score}/${payload.evaluation_run.threshold}`);
+    console.log(`  Drift: ${payload.evaluation_run.drift_level}`);
+    if (payload.evaluation_run.regression_reasons.length > 0) {
+      console.log(`  Reasons: ${payload.evaluation_run.regression_reasons.join(', ')}`);
+    }
+    return;
+  }
+
+  if (payload.mode === 'semantic-eval-runs') {
+    console.log(chalk.blue(`Semantic evaluation runs: ${payload.total}`));
+    for (const item of payload.items) {
+      console.log(`  - ${item.evaluation_run_id} | ${item.verdict} | ${item.score} | ${item.drift_level}`);
+    }
+    return;
+  }
+
+  if (payload.mode === 'semantic-promoted') {
+    console.log(chalk.blue(`Promoted semantic behaviors: ${payload.total}`));
+    for (const item of payload.items) {
+      console.log(`  - ${item.lesson_id} | ${item.lesson_type} | ${item.status} | ${item.title}`);
+    }
+    return;
+  }
+
+  if (payload.mode === 'semantic-promote') {
+    console.log(chalk.blue(`Semantic lesson promoted: ${payload.lesson.lesson_id}`));
+    console.log(`  Status: ${payload.lesson.status}`);
+    console.log(`  Evidence run: ${payload.evaluation_run_id}`);
+    if (payload.lesson.auto_publication && payload.lesson.auto_publication.totals) {
+      console.log(`  Publication: ${payload.lesson.auto_publication.totals.published}/${payload.lesson.auto_publication.totals.matched || payload.lesson.auto_publication.totals.entries}`);
+    }
+    return;
+  }
+
+  if (payload.mode === 'semantic-rollback') {
+    console.log(chalk.blue(`Semantic lesson rolled back: ${payload.lesson.lesson_id}`));
+    console.log(`  Status: ${payload.lesson.status}`);
+    return;
+  }
+
+  if (payload.mode === 'semantic-progress') {
+    console.log(chalk.blue(`Semantic progress snapshot`));
+    console.log(`  Observations: ${payload.observations.total}`);
+    console.log(`  Lessons: ${payload.lesson_candidates.total} | promoted=${payload.lesson_candidates.promoted}`);
+    console.log(`  Evaluations: ${payload.evaluation.total} | pass_rate=${payload.evaluation.pass_rate_percent}%`);
+    console.log(`  Capability ledger: ${payload.capability_ledger.total} | quarantined=${payload.capability_ledger.quarantined}`);
+    console.log(`  Archive: libraries=${payload.archive.totals.library_count} | missing=${payload.archive.totals.missing_archive_count}`);
+    console.log(`  Shared sources: pending_connect=${payload.shared_sources.pendingApprovedDescriptors || 0}`);
+    console.log(`  Supreme intent: ${payload.supreme_intent.total} | refuse=${payload.supreme_intent.refuse} | governed_rate=${payload.supreme_intent.governed_action_rate_percent}%`);
+    console.log(`  Native activated replies: ${payload.native_backflow.activated_reply_count} | hit_rate=${payload.native_backflow.activation_hit_rate_percent}%`);
+    console.log(`  Operator control: severity=${payload.operator_control_plane.highestSeverity || 'none'} | actionable=${payload.operator_control_plane.actionableCount || 0}`);
+    if (payload.operator_control_plane.primaryRecommendedCommand) {
+      console.log(`  Next: ${payload.operator_control_plane.primaryRecommendedCommand}`);
+    }
+    return;
+  }
+
+  if (payload.mode === 'semantic-supreme-intent-list') {
+    console.log(chalk.blue(`Supreme intent assessments: ${payload.total}`));
+    for (const item of payload.items) {
+      console.log(`  - ${item.assessment_id} | ${item.source_kind} | ${item.action} | ${item.scene_id || 'n/a'} | ${item.spec_id || 'n/a'}`);
+    }
+    return;
+  }
+
+  if (payload.mode === 'semantic-supreme-intent-show') {
+    console.log(chalk.blue(`Supreme intent assessment: ${payload.item.assessment_id}`));
+    console.log(`  Source: ${payload.item.source_kind}`);
+    console.log(`  Action: ${payload.item.action}`);
+    console.log(`  Scene: ${payload.item.scene_id || 'n/a'}`);
+    console.log(`  Spec: ${payload.item.spec_id || 'n/a'}`);
+    console.log(`  Session: ${payload.item.session_id || 'n/a'}`);
+    return;
+  }
+
+  if (payload.mode === 'semantic-governance-report') {
+    console.log(chalk.blue('Semantic governance report'));
+    console.log(`  Assessments: ${payload.totals.total}`);
+    console.log(`  Governed: ${payload.totals.governed} | rewrite=${payload.totals.rewrite} | refuse=${payload.totals.refuse}`);
+    console.log(`  Blocked: planning=${payload.totals.planning_blocked} | execution=${payload.totals.execution_blocked}`);
+    for (const item of payload.top_scope_hotspots) {
+      console.log(`  Hotspot: ${item.project_id || 'n/a'} | ${item.channel_id || 'n/a'} | ${item.spec_id || 'n/a'} | governed=${item.governed_count}`);
+    }
+    for (const item of payload.top_matched_rules) {
+      console.log(`  Rule: ${item.rule_id} | count=${item.count}`);
+    }
+    return;
+  }
+
+  if (payload.mode === 'semantic-backflow-report') {
+    console.log(chalk.blue('Semantic backflow report'));
+    console.log(`  Local blocked: ${payload.totals.local_publish_blocked}`);
+    console.log(`  Central merge blocked: ${payload.totals.central_merge_blocked}`);
+    console.log(`  Central release blocked: ${payload.totals.central_release_blocked}`);
+    for (const item of payload.local.blocked_by_reason) {
+      console.log(`  Local reason: ${item.reason} | count=${item.count}`);
+    }
+    for (const item of payload.central_merge.blocked_by_reason) {
+      console.log(`  Merge reason: ${item.reason} | count=${item.count}`);
+    }
+    for (const item of payload.central_release.blocked_by_reason) {
+      console.log(`  Release reason: ${item.reason} | count=${item.count}`);
+    }
+    return;
+  }
+
+  if (payload.mode === 'semantic-archive-report') {
+    console.log(chalk.blue('Semantic archive report'));
+    console.log(`  Lessons: ${payload.totals.lesson_total}`);
+    console.log(`  Ledgers: ${payload.totals.ledger_total}`);
+    console.log(`  Libraries: ${payload.totals.library_count} | missing=${payload.totals.missing_archive_count}`);
+    for (const item of payload.by_library) {
+      console.log(`  Library: ${item.target_library} | lessons=${item.lesson_count} | ledgers=${item.ledger_count} | shared=${item.published_shared_count}`);
+    }
+    return;
+  }
+
+  if (payload.mode === 'semantic-delta-export') {
+    console.log(chalk.blue(`Semantic delta export: ${payload.total}`));
+    if (payload.out_file) {
+      console.log(`  File: ${payload.out_file}`);
+    }
+    for (const item of payload.entries) {
+      console.log(`  - ${item.capability_id} | ${item.target_library} | ${item.publication.publish_state}`);
+    }
+    return;
+  }
+
+  if (payload.mode === 'semantic-publish-delta') {
+    console.log(chalk.blue(`Semantic delta publication: ${payload.totals.published}/${payload.totals.entries}`));
+    if (payload.source_manifest) {
+      console.log(`  Manifest: ${payload.source_manifest}`);
+    }
+    if (payload.out_file) {
+      console.log(`  Report: ${payload.out_file}`);
+    }
+    console.log(`  Mirror root: ${payload.mirror_root}`);
+    for (const item of payload.published) {
+      console.log(`  - ${item.capability_id} | ${item.target_library} | ${item.entry_file}`);
+    }
+    if (payload.blocked.length > 0) {
+      for (const item of payload.blocked) {
+        console.log(`  ! ${item.capability_id || item.lesson_id || 'unknown'} | ${item.reason}`);
+      }
+    }
+    return;
+  }
+
+  if (payload.mode === 'semantic-export-shared-sync') {
+    console.log(chalk.blue(`Semantic shared sync export: ${payload.totals.entries_exported}/${payload.totals.entries_matched}`));
+    if (payload.out_file) {
+      console.log(`  Bundle: ${payload.out_file}`);
+    }
+    if (payload.index_file) {
+      console.log(`  Index: ${payload.index_file}`);
+    }
+    if (payload.receipt_file) {
+      console.log(`  Receipt: ${payload.receipt_file}`);
+    }
+    console.log(`  Mirror root: ${payload.mirror_root}`);
+    for (const item of payload.libraries) {
+      console.log(`  - ${item.target_library} | ${item.entry_count} | ${item.shard_file || 'memory-only'}`);
+    }
+    if (payload.blocked.length > 0) {
+      for (const item of payload.blocked) {
+        console.log(`  ! ${item.capability_id || item.lesson_id || 'unknown'} | ${item.reason}`);
+      }
+    }
+    return;
+  }
+
+  if (payload.mode === 'semantic-sync-shared') {
+    console.log(chalk.blue(`Semantic shared sync intake: ${payload.totals.imported}/${payload.totals.libraries}`));
+    console.log(`  Source: ${payload.source}`);
+    if (payload.required_release_state) {
+      console.log(`  Release: ${payload.release_state || 'unreleased'} (required=${payload.required_release_state})`);
+    }
+    if (payload.out_file) {
+      console.log(`  Receipt: ${payload.out_file}`);
+    }
+    console.log(`  Mirror root: ${payload.mirror_root}`);
+    for (const item of payload.imported) {
+      console.log(`  - ${item.capability_id} | ${item.target_library} | ${item.entry_file}`);
+    }
+    for (const item of payload.skipped) {
+      console.log(`  ~ ${item.capability_id || item.lesson_id || 'unknown'} | ${item.reason}`);
+    }
+    for (const item of payload.blocked) {
+      console.log(`  ! ${item.capability_id || item.target_library || 'unknown'} | ${item.reason}`);
+    }
+    return;
+  }
+
+  if (payload.mode === 'semantic-health-shared-source') {
+    console.log(chalk.blue(`Semantic shared source health: ${payload.success ? 'ok' : 'issues'}`));
+    console.log(`  Source: ${payload.source || 'unconfigured'}`);
+    console.log(`  Bundle: ${payload.bundle_ok ? 'ok' : 'failed'}`);
+    if (payload.required_release_state) {
+      console.log(`  Release: ${payload.release_state || 'unreleased'} (required=${payload.required_release_state})`);
+    }
+    console.log(`  Shards: ${payload.shard_sources_ok}/${payload.shard_sources_checked}`);
+    console.log(`  Entries: ${payload.total_entries}`);
+    for (const item of payload.warnings) {
+      console.log(`  ~ ${item}`);
+    }
+    for (const item of payload.errors) {
+      console.log(`  ! ${item}`);
+    }
+    return;
+  }
+
+  if (payload.mode === 'semantic-list-shared-sources') {
+    console.log(chalk.blue(`Semantic shared sources: ${payload.total}`));
+    console.log(`  Config: ${payload.config_file}`);
+    for (const item of payload.items) {
+      console.log(`  - ${item.name} | ${item.enabled ? 'enabled' : 'disabled'} | ${item.bundle}`);
+    }
+    return;
+  }
+
+  if (payload.mode === 'semantic-set-shared-source') {
+    console.log(chalk.blue(`Semantic shared source upserted: ${payload.source.name}`));
+    console.log(`  Config: ${payload.config_file}`);
+    if (payload.descriptor_file) {
+      console.log(`  Descriptor: ${payload.descriptor_file}`);
+    }
+    console.log(`  Bundle: ${payload.source.bundle}`);
+    if (payload.source.required_release_state) {
+      console.log(`  Required release: ${payload.source.required_release_state}`);
+    }
+    return;
+  }
+
+  if (payload.mode === 'semantic-connect-shared-source') {
+    console.log(chalk.blue(`Semantic shared source connect: ${payload.success ? 'ok' : 'blocked'}`));
+    console.log(`  Descriptor: ${payload.descriptor_file}`);
+    console.log(`  Release: ${payload.descriptor_release_state || 'unreleased'}`);
+    if (payload.config_file) {
+      console.log(`  Config: ${payload.config_file}`);
+    }
+    if (payload.sync && payload.sync.out_file) {
+      console.log(`  Sync receipt: ${payload.sync.out_file}`);
+    }
+    for (const item of payload.blocked) {
+      console.log(`  ! ${item.reason}`);
+    }
+    return;
+  }
+
+  if (payload.mode === 'semantic-merge-shared') {
+    console.log(chalk.blue(`Semantic shared merge: ${payload.totals.merged_entries}/${payload.totals.candidate_entries}`));
+    if (payload.out_file) {
+      console.log(`  Bundle: ${payload.out_file}`);
+    }
+    if (payload.index_file) {
+      console.log(`  Index: ${payload.index_file}`);
+    }
+    if (payload.receipt_file) {
+      console.log(`  Receipt: ${payload.receipt_file}`);
+    }
+    if (payload.source_descriptor_file) {
+      console.log(`  Source descriptor: ${payload.source_descriptor_file}`);
+    }
+    console.log(`  Sources: ${payload.totals.sources}`);
+    for (const item of payload.libraries) {
+      console.log(`  - ${item.target_library} | ${item.entry_count} | ${item.shard_file || 'memory-only'}`);
+    }
+    for (const item of payload.superseded || []) {
+      console.log(`  ~ ${item.capability_id || 'unknown'} | kept=${item.kept_source || 'unknown'} | dropped=${item.dropped_source || 'unknown'}`);
+    }
+    for (const item of payload.blocked) {
+      console.log(`  ! ${item.source || item.target_library || 'unknown'} | ${item.reason}`);
+    }
+    return;
+  }
+
+  if (payload.mode === 'semantic-publish-shared-registry') {
+    console.log(chalk.blue(`Semantic shared registry publish: ${payload.success ? 'approved' : 'blocked'}`));
+    if (payload.out_file) {
+      console.log(`  Bundle: ${payload.out_file}`);
+    }
+    if (payload.index_file) {
+      console.log(`  Index: ${payload.index_file}`);
+    }
+    if (payload.receipt_file) {
+      console.log(`  Receipt: ${payload.receipt_file}`);
+    }
+    console.log(`  Sources: ${payload.totals.sources}`);
+    console.log(`  Entries: ${payload.totals.merged_entries}`);
+    for (const item of payload.libraries) {
+      console.log(`  - ${item.target_library} | ${item.entry_count} | ${item.shard_file || 'memory-only'}`);
+    }
+    for (const item of payload.blocked) {
+      console.log(`  ! ${item.reason} | ${item.required_sources || item.required_entries || item.blocked_entries || 'n/a'}`);
+    }
+    return;
+  }
+}
+
+async function runSemanticObserveCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const payloadFromFile = await loadInputPayload(options, fileSystem);
+  const payload = {
+    ...payloadFromFile,
+    project_id: options.projectId || payloadFromFile.project_id,
+    channel_id: options.channelId || payloadFromFile.channel_id,
+    session_id: options.sessionId || payloadFromFile.session_id,
+    scene_id: options.scene || payloadFromFile.scene_id,
+    spec_id: options.spec || payloadFromFile.spec_id,
+    task_ref: options.taskRef || payloadFromFile.task_ref,
+    source_runtime: options.runtime || payloadFromFile.source_runtime,
+    host_session_id: options.hostSession || payloadFromFile.host_session_id,
+    event_kind: options.event || payloadFromFile.event_kind,
+    role: options.role || payloadFromFile.role,
+    intent: options.intent || payloadFromFile.intent,
+    outcome: options.outcome || payloadFromFile.outcome,
+    quality_signal: options.quality || payloadFromFile.quality_signal,
+    summary: options.summary || payloadFromFile.summary,
+    text: options.text || payloadFromFile.text,
+    raw_ref: options.rawRef || payloadFromFile.raw_ref
+  };
+
+  const result = await observeSemanticInteraction(payload, {
+    projectPath,
+    fileSystem,
+    stateStore: dependencies.stateStore
+  });
+
+  const response = {
+    mode: 'semantic-observe',
+    success: true,
+    observation: result.observation,
+    lesson_candidate: result.lesson_candidate
+  };
+  printPayload(response, options);
+  return response;
+}
+
+async function runSemanticListCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const store = dependencies.stateStore || getSceStateStore(projectPath, {
+    fileSystem: dependencies.fileSystem || fs
+  });
+  const items = await store.listSemanticObservations({
+    project_id: options.projectId,
+    source_runtime: options.runtime,
+    session_id: options.sessionId,
+    limit: options.limit
+  });
+  const response = {
+    mode: 'semantic-list',
+    success: true,
+    total: Array.isArray(items) ? items.length : 0,
+    items: Array.isArray(items) ? items : []
+  };
+  printPayload(response, options);
+  return response;
+}
+
+async function runSemanticLessonsCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const store = dependencies.stateStore || getSceStateStore(projectPath, {
+    fileSystem: dependencies.fileSystem || fs
+  });
+  const items = await store.listSemanticLessonCandidates({
+    project_id: options.projectId,
+    status: options.status,
+    limit: options.limit
+  });
+  const response = {
+    mode: 'semantic-lessons',
+    success: true,
+    total: Array.isArray(items) ? items.length : 0,
+    items: Array.isArray(items) ? items : []
+  };
+  printPayload(response, options);
+  return response;
+}
+
+async function runSemanticReplayCommand(options = {}, dependencies = {}) {
+  const payloadFromFile = await loadInputPayload(options, dependencies.fileSystem || fs);
+  const response = await collectSemanticReplayInputs({
+    ...payloadFromFile,
+    project_id: options.projectId || payloadFromFile.project_id,
+    channel_id: options.channelId || payloadFromFile.channel_id,
+    session_id: options.sessionId || payloadFromFile.session_id,
+    scene_id: options.scene || payloadFromFile.scene_id,
+    spec_id: options.spec || payloadFromFile.spec_id,
+    source_runtime: options.runtime || payloadFromFile.source_runtime,
+    observation_ids: payloadFromFile.observation_ids,
+    limit: options.limit || payloadFromFile.limit
+  }, {
+    ...dependencies,
+    projectPath: dependencies.projectPath || process.cwd(),
+    fileSystem: dependencies.fileSystem || fs
+  });
+
+  const result = {
+    mode: 'semantic-replay',
+    success: true,
+    total: response.observations.length,
+    replay_dataset: response.replay_dataset,
+    observations: response.observations
+  };
+  printPayload(result, options);
+  return result;
+}
+
+async function runSemanticEvalCommand(options = {}, dependencies = {}) {
+  const payloadFromFile = await loadInputPayload(options, dependencies.fileSystem || fs);
+  const response = await evaluateSemanticCandidate({
+    ...payloadFromFile,
+    project_id: options.projectId || payloadFromFile.project_id,
+    channel_id: options.channelId || payloadFromFile.channel_id,
+    session_id: options.sessionId || payloadFromFile.session_id,
+    scene_id: options.scene || payloadFromFile.scene_id,
+    spec_id: options.spec || payloadFromFile.spec_id,
+    source_runtime: options.runtime || payloadFromFile.source_runtime,
+    lesson_id: options.lessonId || payloadFromFile.lesson_id,
+    release_gate: options.releaseGate || payloadFromFile.release_gate,
+    baseline_evaluation_run_id: options.baselineRunId || payloadFromFile.baseline_evaluation_run_id,
+    candidate_label: options.candidateLabel || payloadFromFile.candidate_label,
+    candidate_reply: options.candidateReply || payloadFromFile.candidate_reply,
+    candidate_plan: options.candidatePlan || payloadFromFile.candidate_plan,
+    observation_ids: payloadFromFile.observation_ids,
+    threshold: options.threshold || payloadFromFile.threshold,
+    limit: options.limit || payloadFromFile.limit
+  }, {
+    ...dependencies,
+    projectPath: dependencies.projectPath || process.cwd(),
+    fileSystem: dependencies.fileSystem || fs
+  });
+
+  const result = {
+    mode: 'semantic-eval',
+    success: true,
+    evaluation_run: response.evaluation_run,
+    replay_dataset: response.replay_dataset,
+    observations: response.observations
+  };
+  printPayload(result, options);
+  return result;
+}
+
+async function runSemanticEvalRunsCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const store = dependencies.stateStore || getSceStateStore(projectPath, {
+    fileSystem: dependencies.fileSystem || fs
+  });
+  const items = await store.listSemanticEvaluationRuns({
+    project_id: options.projectId,
+    session_id: options.sessionId,
+    spec_id: options.spec,
+    verdict: options.verdict,
+    limit: options.limit
+  });
+  const response = {
+    mode: 'semantic-eval-runs',
+    success: true,
+    total: Array.isArray(items) ? items.length : 0,
+    items: Array.isArray(items) ? items : []
+  };
+  printPayload(response, options);
+  return response;
+}
+
+async function runSemanticPromotedCommand(options = {}, dependencies = {}) {
+  const payloadFromFile = await loadInputPayload(options, dependencies.fileSystem || fs);
+  const items = await listPromotedSemanticBehaviors({
+    ...payloadFromFile,
+    project_id: options.projectId || payloadFromFile.project_id,
+    channel_id: options.channelId || payloadFromFile.channel_id,
+    scene_id: options.scene || payloadFromFile.scene_id,
+    spec_id: options.spec || payloadFromFile.spec_id,
+    limit: options.limit || payloadFromFile.limit
+  }, {
+    ...dependencies,
+    projectPath: dependencies.projectPath || process.cwd(),
+    fileSystem: dependencies.fileSystem || fs
+  });
+  const response = {
+    mode: 'semantic-promoted',
+    success: true,
+    total: Array.isArray(items) ? items.length : 0,
+    items: Array.isArray(items) ? items : []
+  };
+  printPayload(response, options);
+  return response;
+}
+
+async function runSemanticPromoteCommand(options = {}, dependencies = {}) {
+  const lesson = await promoteSemanticLessonCandidate({
+    lesson_id: options.lessonId,
+    evaluation_run_id: options.evalRunId,
+    actor: options.actor,
+    release_gate: options.releaseGate
+  }, {
+    ...dependencies,
+    projectPath: dependencies.projectPath || process.cwd(),
+    fileSystem: dependencies.fileSystem || fs
+  });
+
+  const response = {
+    mode: 'semantic-promote',
+    success: true,
+    evaluation_run_id: options.evalRunId,
+    lesson
+  };
+  printPayload(response, options);
+  return response;
+}
+
+async function runSemanticRollbackCommand(options = {}, dependencies = {}) {
+  const lesson = await rollbackPromotedSemanticLesson({
+    lesson_id: options.lessonId,
+    actor: options.actor,
+    reason: options.reason
+  }, {
+    ...dependencies,
+    projectPath: dependencies.projectPath || process.cwd(),
+    fileSystem: dependencies.fileSystem || fs
+  });
+
+  const response = {
+    mode: 'semantic-rollback',
+    success: true,
+    lesson
+  };
+  printPayload(response, options);
+  return response;
+}
+
+async function runSemanticProgressCommand(options = {}, dependencies = {}) {
+  const payload = await buildSemanticProgressReport({
+    project_id: options.projectId,
+    spec_id: options.spec,
+    session_id: options.sessionId,
+    limit: options.limit
+  }, {
+    ...dependencies,
+    projectPath: dependencies.projectPath || process.cwd(),
+    fileSystem: dependencies.fileSystem || fs
+  });
+  printPayload(payload, options);
+  return payload;
+}
+
+async function runSemanticSupremeIntentListCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const store = dependencies.stateStore || getSceStateStore(projectPath, {
+    fileSystem: dependencies.fileSystem || fs,
+    env: dependencies.env,
+    sqliteModule: dependencies.sqliteModule
+  });
+  const limit = normalizeInteger(options.limit, 20);
+  const items = await store.listSupremeIntentAssessments({
+    project_id: options.projectId,
+    channel_id: options.channelId,
+    session_id: options.sessionId,
+    scene_id: options.scene,
+    spec_id: options.spec,
+    job_id: options.jobId,
+    source_kind: options.sourceKind,
+    action: options.action,
+    limit
+  });
+  const response = {
+    mode: 'semantic-supreme-intent-list',
+    success: true,
+    filters: {
+      project_id: normalizeString(options.projectId) || null,
+      channel_id: normalizeString(options.channelId) || null,
+      session_id: normalizeString(options.sessionId) || null,
+      scene_id: normalizeString(options.scene) || null,
+      spec_id: normalizeString(options.spec) || null,
+      job_id: normalizeString(options.jobId) || null,
+      source_kind: normalizeString(options.sourceKind) || null,
+      action: normalizeString(options.action) || null,
+      limit
+    },
+    total: Array.isArray(items) ? items.length : 0,
+    items: Array.isArray(items) ? items : []
+  };
+  printPayload(response, options);
+  return response;
+}
+
+async function runSemanticSupremeIntentShowCommand(assessmentId, options = {}, dependencies = {}) {
+  const normalizedAssessmentId = normalizeString(assessmentId || options.assessmentId);
+  if (!normalizedAssessmentId) {
+    throw new Error('assessment id is required');
+  }
+  const projectPath = dependencies.projectPath || process.cwd();
+  const store = dependencies.stateStore || getSceStateStore(projectPath, {
+    fileSystem: dependencies.fileSystem || fs,
+    env: dependencies.env,
+    sqliteModule: dependencies.sqliteModule
+  });
+  const item = await store.getSupremeIntentAssessment(normalizedAssessmentId);
+  if (!item) {
+    throw new Error(`Supreme intent assessment not found: ${normalizedAssessmentId}`);
+  }
+  const response = {
+    mode: 'semantic-supreme-intent-show',
+    success: true,
+    item
+  };
+  printPayload(response, options);
+  return response;
+}
+
+async function runSemanticGovernanceReportCommand(options = {}, dependencies = {}) {
+  const payload = await buildSupremeIntentGovernanceReport({
+    project_id: options.projectId,
+    channel_id: options.channelId,
+    session_id: options.sessionId,
+    scene_id: options.scene,
+    spec_id: options.spec,
+    job_id: options.jobId,
+    source_kind: options.sourceKind,
+    action: options.action,
+    limit: options.limit,
+    hotspot_limit: options.hotspotLimit,
+    recent_limit: options.recentLimit
+  }, {
+    ...dependencies,
+    projectPath: dependencies.projectPath || process.cwd(),
+    fileSystem: dependencies.fileSystem || fs
+  });
+  printPayload(payload, options);
+  return payload;
+}
+
+async function runSemanticBackflowReportCommand(options = {}, dependencies = {}) {
+  const payload = await buildSemanticBackflowReport({
+    project_id: options.projectId,
+    spec_id: options.spec,
+    limit: options.limit,
+    recent_limit: options.recentLimit
+  }, {
+    ...dependencies,
+    projectPath: dependencies.projectPath || process.cwd(),
+    fileSystem: dependencies.fileSystem || fs
+  });
+  printPayload(payload, options);
+  return payload;
+}
+
+async function runSemanticArchiveReportCommand(options = {}, dependencies = {}) {
+  const payload = await buildSemanticArchiveReport({
+    project_id: options.projectId,
+    spec_id: options.spec,
+    session_id: options.sessionId,
+    limit: options.limit,
+    recent_limit: options.recentLimit
+  }, {
+    ...dependencies,
+    projectPath: dependencies.projectPath || process.cwd(),
+    fileSystem: dependencies.fileSystem || fs
+  });
+  printPayload(payload, options);
+  return payload;
+}
+
+async function runSemanticDeltaExportCommand(options = {}, dependencies = {}) {
+  const payload = await exportSemanticLibraryDelta({
+    project_id: options.projectId,
+    spec_id: options.spec,
+    limit: options.limit,
+    out_file: options.outFile
+  }, {
+    ...dependencies,
+    projectPath: dependencies.projectPath || process.cwd(),
+    fileSystem: dependencies.fileSystem || fs
+  });
+  printPayload(payload, options);
+  return payload;
+}
+
+async function runSemanticPublishDeltaCommand(options = {}, dependencies = {}) {
+  const payload = await publishSemanticLibraryDelta({
+    project_id: options.projectId,
+    spec_id: options.spec,
+    input_file: options.inputFile,
+    out_file: options.outFile,
+    limit: options.limit
+  }, {
+    ...dependencies,
+    projectPath: dependencies.projectPath || process.cwd(),
+    fileSystem: dependencies.fileSystem || fs,
+    syncSemanticCapabilityLedger
+  });
+  printPayload(payload, options);
+  return payload;
+}
+
+async function runSemanticExportSharedSyncCommand(options = {}, dependencies = {}) {
+  const payload = await exportSemanticSharedSyncBundle({
+    project_id: options.projectId,
+    spec_id: options.spec,
+    lesson_id: options.lessonId,
+    capability_id: options.capabilityId,
+    target_library: options.targetLibrary,
+    out_file: options.outFile,
+    limit: options.limit
+  }, {
+    ...dependencies,
+    projectPath: dependencies.projectPath || process.cwd(),
+    fileSystem: dependencies.fileSystem || fs
+  });
+  printPayload(payload, options);
+  return payload;
+}
+
+async function runSemanticSyncSharedCommand(options = {}, dependencies = {}) {
+  const payload = await syncSemanticSharedBundle({
+    source: options.source,
+    sourceName: options.sourceName,
+    sourceRoot: options.sourceRoot,
+    requiredReleaseState: options.requiredReleaseState,
+    config: options.config,
+    spec: options.spec,
+    outFile: options.outFile,
+    limit: options.limit
+  }, {
+    ...dependencies,
+    projectPath: dependencies.projectPath || process.cwd(),
+    fileSystem: dependencies.fileSystem || fs
+  });
+  printPayload(payload, options);
+  return payload;
+}
+
+async function runSemanticHealthSharedSourceCommand(options = {}, dependencies = {}) {
+  const payload = await inspectSemanticSharedSource({
+    source: options.source,
+    sourceName: options.sourceName,
+    sourceRoot: options.sourceRoot,
+    requiredReleaseState: options.requiredReleaseState,
+    config: options.config
+  }, {
+    ...dependencies,
+    projectPath: dependencies.projectPath || process.cwd(),
+    fileSystem: dependencies.fileSystem || fs
+  });
+  printPayload(payload, options);
+  return payload;
+}
+
+async function runSemanticListSharedSourcesCommand(options = {}, dependencies = {}) {
+  const payload = await listSemanticSharedSources({
+    config: options.config
+  }, {
+    ...dependencies,
+    projectPath: dependencies.projectPath || process.cwd(),
+    fileSystem: dependencies.fileSystem || fs
+  });
+  printPayload(payload, options);
+  return payload;
+}
+
+async function runSemanticSetSharedSourceCommand(options = {}, dependencies = {}) {
+  const payload = await upsertSemanticSharedSource({
+    inputFile: options.inputFile,
+    name: options.name,
+    bundle: options.bundle,
+    root: options.root,
+    enabled: options.enabled,
+    requiredReleaseState: options.requiredReleaseState,
+    config: options.config
+  }, {
+    ...dependencies,
+    projectPath: dependencies.projectPath || process.cwd(),
+    fileSystem: dependencies.fileSystem || fs
+  });
+  printPayload(payload, options);
+  return payload;
+}
+
+async function runSemanticConnectSharedSourceCommand(options = {}, dependencies = {}) {
+  const payload = await connectSemanticSharedSource({
+    inputFile: options.inputFile,
+    spec: options.spec,
+    name: options.name,
+    bundle: options.bundle,
+    root: options.root,
+    enabled: options.enabled,
+    requiredReleaseState: options.requiredReleaseState,
+    config: options.config,
+    healthCheck: options.healthCheck,
+    syncNow: options.syncNow,
+    allowNonApproved: options.allowNonApproved
+  }, {
+    ...dependencies,
+    projectPath: dependencies.projectPath || process.cwd(),
+    fileSystem: dependencies.fileSystem || fs
+  });
+  printPayload(payload, options);
+  return payload;
+}
+
+async function runSemanticMergeSharedCommand(options = {}, dependencies = {}) {
+  const payload = await mergeSemanticSharedBundles({
+    source: options.source,
+    sources: options.sources,
+    config: options.config,
+    spec: options.spec,
+    outFile: options.outFile,
+    limit: options.limit
+  }, {
+    ...dependencies,
+    projectPath: dependencies.projectPath || process.cwd(),
+    fileSystem: dependencies.fileSystem || fs
+  });
+  printPayload(payload, options);
+  return payload;
+}
+
+async function runSemanticPublishSharedRegistryCommand(options = {}, dependencies = {}) {
+  const payload = await publishSemanticSharedRegistry({
+    spec: options.spec,
+    input_file: options.inputFile,
+    out_file: options.outFile,
+    index_file: options.indexFile,
+    receipt_file: options.receiptFile,
+    source_name: options.sourceName,
+    source_descriptor_file: options.sourceDescriptorFile,
+    public_bundle: options.publicBundle,
+    public_root: options.publicRoot,
+    min_sources: options.minSources,
+    min_entries: options.minEntries,
+    require_zero_blocked: options.requireZeroBlocked
+  }, {
+    ...dependencies,
+    projectPath: dependencies.projectPath || process.cwd(),
+    fileSystem: dependencies.fileSystem || fs
+  });
+  printPayload(payload, options);
+  return payload;
+}
+
+function registerSemanticCommands(program) {
+  const semantic = program
+    .command('semantic')
+    .description('Manage semantic observation, lesson distillation, and candidate review');
+
+  semantic
+    .command('observe')
+    .description('Record one embedded-host semantic observation')
+    .option('--input-file <path>', 'JSON file containing observation payload')
+    .option('--project-id <project-id>', 'Project identifier')
+    .option('--channel-id <channel-id>', 'Collaboration channel identifier')
+    .option('--session-id <session-id>', 'Session identifier')
+    .option('--scene <scene-id>', 'Scene identifier')
+    .option('--spec <spec-id>', 'Spec identifier')
+    .option('--task-ref <task-ref>', 'Task reference')
+    .option('--runtime <runtime>', 'Source runtime, e.g. codex-cli')
+    .option('--host-session <host-session-id>', 'Embedded-host session identifier')
+    .option('--event <event-kind>', 'Observed event kind, e.g. reply')
+    .option('--role <role>', 'Role, e.g. assistant')
+    .option('--intent <intent>', 'Intent label override')
+    .option('--outcome <outcome>', 'Outcome override')
+    .option('--quality <signal>', 'Quality signal override')
+    .option('--summary <summary>', 'Summary override')
+    .option('--text <text>', 'Observed text preview')
+    .option('--raw-ref <ref>', 'Reference to raw trace')
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      try {
+        await runSemanticObserveCommand(options);
+      } catch (error) {
+        console.error(chalk.red(`Semantic observe failed: ${error.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  semantic
+    .command('list')
+    .description('List semantic observations')
+    .option('--project-id <project-id>', 'Filter by project')
+    .option('--runtime <runtime>', 'Filter by runtime')
+    .option('--session-id <session-id>', 'Filter by session')
+    .option('--limit <n>', 'Limit result count', parseInt)
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      try {
+        await runSemanticListCommand(options);
+      } catch (error) {
+        console.error(chalk.red(`Semantic list failed: ${error.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  semantic
+    .command('lessons')
+    .description('List semantic lesson candidates')
+    .option('--project-id <project-id>', 'Filter by project')
+    .option('--status <status>', 'Filter by lesson status')
+    .option('--limit <n>', 'Limit result count', parseInt)
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      try {
+        await runSemanticLessonsCommand(options);
+      } catch (error) {
+        console.error(chalk.red(`Semantic lessons failed: ${error.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  semantic
+    .command('replay')
+    .description('Build replay dataset from recorded semantic observations')
+    .option('--input-file <path>', 'JSON file containing replay filters')
+    .option('--project-id <project-id>', 'Filter by project')
+    .option('--channel-id <channel-id>', 'Filter by collaboration channel')
+    .option('--session-id <session-id>', 'Filter by session')
+    .option('--scene <scene-id>', 'Filter by scene')
+    .option('--spec <spec-id>', 'Filter by spec')
+    .option('--runtime <runtime>', 'Filter by runtime')
+    .option('--limit <n>', 'Limit observation count', parseInt)
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      try {
+        await runSemanticReplayCommand(options);
+      } catch (error) {
+        console.error(chalk.red(`Semantic replay failed: ${error.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  semantic
+    .command('eval')
+    .description('Replay semantic observations against a candidate reply or plan')
+    .option('--input-file <path>', 'JSON file containing evaluation payload')
+    .option('--project-id <project-id>', 'Project identifier')
+    .option('--channel-id <channel-id>', 'Collaboration channel identifier')
+    .option('--session-id <session-id>', 'Session identifier')
+    .option('--scene <scene-id>', 'Scene identifier')
+    .option('--spec <spec-id>', 'Spec identifier')
+    .option('--runtime <runtime>', 'Runtime identifier')
+    .option('--lesson-id <lesson-id>', 'Associated lesson candidate identifier')
+    .option('--release-gate <release-gate>', 'Release gate or promotion lane')
+    .option('--baseline-run-id <evaluation-run-id>', 'Compare against an earlier evaluation run')
+    .option('--candidate-label <label>', 'Human-readable candidate label')
+    .option('--candidate-reply <text>', 'Candidate reply text')
+    .option('--candidate-plan <text>', 'Candidate action-plan text')
+    .option('--threshold <score>', 'Pass threshold', parseFloat)
+    .option('--limit <n>', 'Limit replay observation count', parseInt)
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      try {
+        await runSemanticEvalCommand(options);
+      } catch (error) {
+        console.error(chalk.red(`Semantic eval failed: ${error.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  semantic
+    .command('eval-runs')
+    .description('List semantic evaluation runs')
+    .option('--project-id <project-id>', 'Filter by project')
+    .option('--session-id <session-id>', 'Filter by session')
+    .option('--spec <spec-id>', 'Filter by spec')
+    .option('--verdict <verdict>', 'Filter by verdict')
+    .option('--limit <n>', 'Limit result count', parseInt)
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      try {
+        await runSemanticEvalRunsCommand(options);
+      } catch (error) {
+        console.error(chalk.red(`Semantic eval-runs failed: ${error.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  semantic
+    .command('promoted')
+    .description('List promoted semantic behaviors')
+    .option('--input-file <path>', 'JSON file containing filters')
+    .option('--project-id <project-id>', 'Filter by project')
+    .option('--channel-id <channel-id>', 'Filter by collaboration channel')
+    .option('--scene <scene-id>', 'Filter by scene')
+    .option('--spec <spec-id>', 'Filter by spec')
+    .option('--limit <n>', 'Limit result count', parseInt)
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      try {
+        await runSemanticPromotedCommand(options);
+      } catch (error) {
+        console.error(chalk.red(`Semantic promoted failed: ${error.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  semantic
+    .command('promote')
+    .description('Promote a semantic lesson after it passes evaluation gates')
+    .requiredOption('--lesson-id <lesson-id>', 'Lesson candidate id')
+    .requiredOption('--eval-run-id <evaluation-run-id>', 'Evidence evaluation run id')
+    .option('--actor <actor>', 'Audit actor')
+    .option('--release-gate <release-gate>', 'Promotion gate or lane')
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      try {
+        await runSemanticPromoteCommand(options);
+      } catch (error) {
+        console.error(chalk.red(`Semantic promote failed: ${error.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  semantic
+    .command('rollback')
+    .description('Rollback one promoted semantic behavior')
+    .requiredOption('--lesson-id <lesson-id>', 'Lesson candidate id')
+    .option('--actor <actor>', 'Audit actor')
+    .option('--reason <reason>', 'Rollback reason')
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      try {
+        await runSemanticRollbackCommand(options);
+      } catch (error) {
+        console.error(chalk.red(`Semantic rollback failed: ${error.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  semantic
+    .command('progress')
+    .description('Summarize semantic learning, evaluation, promotion, and native backflow progress')
+    .option('--project-id <project-id>', 'Filter by project')
+    .option('--spec <spec-id>', 'Filter by spec')
+    .option('--session-id <session-id>', 'Filter by session')
+    .option('--limit <n>', 'Scan limit', parseInt)
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      try {
+        await runSemanticProgressCommand(options);
+      } catch (error) {
+        console.error(chalk.red(`Semantic progress failed: ${error.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  semantic
+    .command('supreme-intent')
+    .description('List supreme-intent governance assessments from the SQLite/state ledger')
+    .option('--project-id <project-id>', 'Filter by project')
+    .option('--channel-id <channel-id>', 'Filter by channel')
+    .option('--session-id <session-id>', 'Filter by session')
+    .option('--scene <scene-id>', 'Filter by scene')
+    .option('--spec <spec-id>', 'Filter by spec')
+    .option('--job-id <job-id>', 'Filter by studio job id')
+    .option('--source-kind <source-kind>', 'Filter by source kind, e.g. studio-plan or native-ask')
+    .option('--action <action>', 'Filter by governance action')
+    .option('--limit <n>', 'Limit result count', parseInt)
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      try {
+        await runSemanticSupremeIntentListCommand(options);
+      } catch (error) {
+        console.error(chalk.red(`Semantic supreme-intent failed: ${error.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  semantic
+    .command('supreme-intent-show <assessment-id>')
+    .description('Show one supreme-intent governance assessment from the SQLite/state ledger')
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (assessmentId, options) => {
+      try {
+        await runSemanticSupremeIntentShowCommand(assessmentId, options);
+      } catch (error) {
+        console.error(chalk.red(`Semantic supreme-intent-show failed: ${error.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  semantic
+    .command('governance-report')
+    .description('Summarize supreme-intent governance hotspots from the SQLite/state ledger')
+    .option('--project-id <project-id>', 'Filter by project')
+    .option('--channel-id <channel-id>', 'Filter by channel')
+    .option('--session-id <session-id>', 'Filter by session')
+    .option('--scene <scene-id>', 'Filter by scene')
+    .option('--spec <spec-id>', 'Filter by spec')
+    .option('--job-id <job-id>', 'Filter by studio job id')
+    .option('--source-kind <source-kind>', 'Filter by source kind')
+    .option('--action <action>', 'Filter by governance action')
+    .option('--limit <n>', 'Maximum assessments to scan', parseInt)
+    .option('--hotspot-limit <n>', 'Maximum hotspot groups to return', parseInt)
+    .option('--recent-limit <n>', 'Maximum recent governed items to return', parseInt)
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      try {
+        await runSemanticGovernanceReportCommand(options);
+      } catch (error) {
+        console.error(chalk.red(`Semantic governance-report failed: ${error.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  semantic
+    .command('backflow-report')
+    .description('Summarize local and central semantic backflow blockers across publication and registry gates')
+    .option('--project-id <project-id>', 'Filter by project')
+    .option('--spec <spec-id>', 'Filter by spec')
+    .option('--limit <n>', 'Maximum lessons/ledgers to scan', parseInt)
+    .option('--recent-limit <n>', 'Maximum recent blocked items/receipts to return', parseInt)
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      try {
+        await runSemanticBackflowReportCommand(options);
+      } catch (error) {
+        console.error(chalk.red(`Semantic backflow-report failed: ${error.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  semantic
+    .command('archive-report')
+    .description('Summarize how training value is routed and accumulated across the three semantic libraries')
+    .option('--project-id <project-id>', 'Filter by project')
+    .option('--spec <spec-id>', 'Filter by spec')
+    .option('--session-id <session-id>', 'Filter by session')
+    .option('--limit <n>', 'Maximum lessons/ledgers to scan', parseInt)
+    .option('--recent-limit <n>', 'Maximum recent archived items to return', parseInt)
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      try {
+        await runSemanticArchiveReportCommand(options);
+      } catch (error) {
+        console.error(chalk.red(`Semantic archive-report failed: ${error.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  semantic
+    .command('export-delta')
+    .description('Export governed publish-pending semantic deltas for shared libraries')
+    .option('--project-id <project-id>', 'Filter by project')
+    .option('--spec <spec-id>', 'Filter by spec')
+    .option('--limit <n>', 'Export limit', parseInt)
+    .option('--out-file <path>', 'Optional output file path')
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      try {
+        await runSemanticDeltaExportCommand(options);
+      } catch (error) {
+        console.error(chalk.red(`Semantic export-delta failed: ${error.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  semantic
+    .command('publish-delta')
+    .description('Publish governed semantic deltas into the shared-library mirror and advance publish state')
+    .option('--project-id <project-id>', 'Filter by project')
+    .option('--spec <spec-id>', 'Filter by spec')
+    .option('--input-file <path>', 'Existing delta manifest to publish')
+    .option('--out-file <path>', 'Optional publication report output path')
+    .option('--limit <n>', 'Publish limit', parseInt)
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      try {
+        await runSemanticPublishDeltaCommand(options);
+      } catch (error) {
+        console.error(chalk.red(`Semantic publish-delta failed: ${error.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  semantic
+    .command('export-shared-sync')
+    .description('Export the local semantic shared-library mirror into a governed spec-scoped sync bundle')
+    .option('--project-id <project-id>', 'Filter by project')
+    .option('--spec <spec-id>', 'Filter by spec and default output scope')
+    .option('--lesson-id <lesson-id>', 'Filter by lesson id')
+    .option('--capability-id <capability-id>', 'Filter by capability id')
+    .option('--target-library <library>', 'Filter by target shared library')
+    .option('--out-file <path>', 'Optional bundle output path')
+    .option('--limit <n>', 'Export limit', parseInt)
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      try {
+        await runSemanticExportSharedSyncCommand(options);
+      } catch (error) {
+        console.error(chalk.red(`Semantic export-shared-sync failed: ${error.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  semantic
+    .command('sync-shared')
+    .description('Sync a governed semantic shared-sync bundle into the local shared-library mirror')
+    .option('--source <url-or-path>', 'Shared-sync bundle source JSON')
+    .option('--source-name <name>', 'Shared-sync source label')
+    .option('--source-root <path-or-url>', 'Optional root path/url used to resolve shard files')
+    .option('--required-release-state <state>', 'Require the bundle governance release state to match before intake')
+    .option('--config <path>', 'Semantic shared source config path')
+    .option('--spec <spec-id>', 'Spec id used for default receipt output')
+    .option('--out-file <path>', 'Optional intake receipt output path')
+    .option('--limit <n>', 'Maximum libraries to scan', parseInt)
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      try {
+        await runSemanticSyncSharedCommand(options);
+      } catch (error) {
+        console.error(chalk.red(`Semantic sync-shared failed: ${error.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  semantic
+    .command('health-shared-source')
+    .description('Validate one configured or explicit semantic shared-sync source without intaking it')
+    .option('--source <url-or-path>', 'Shared-sync bundle source JSON')
+    .option('--source-name <name>', 'Configured source name to inspect')
+    .option('--source-root <path-or-url>', 'Optional root path/url used to resolve shard files')
+    .option('--required-release-state <state>', 'Require the bundle governance release state to match during health checks')
+    .option('--config <path>', 'Semantic shared source config path')
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      try {
+        await runSemanticHealthSharedSourceCommand(options);
+      } catch (error) {
+        console.error(chalk.red(`Semantic health-shared-source failed: ${error.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  semantic
+    .command('list-shared-sources')
+    .description('List configured semantic shared sources and their release-state policy')
+    .option('--config <path>', 'Semantic shared source config path')
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      try {
+        await runSemanticListSharedSourcesCommand(options);
+      } catch (error) {
+        console.error(chalk.red(`Semantic list-shared-sources failed: ${error.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  semantic
+    .command('set-shared-source')
+    .description('Upsert one configured semantic shared source into .sce/config/semantic-shared-sources.json')
+    .option('--input-file <path>', 'Optional published shared source descriptor JSON')
+    .option('--name <name>', 'Configured source name')
+    .option('--bundle <url-or-path>', 'Bundle file/url for the shared source')
+    .option('--root <path-or-url>', 'Optional root path/url used to resolve shard files')
+    .option('--enabled <true|false>', 'Whether the source should be enabled')
+    .option('--required-release-state <state>', 'Optional required governance release state for this source')
+    .option('--config <path>', 'Semantic shared source config path')
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      try {
+        await runSemanticSetSharedSourceCommand(options);
+      } catch (error) {
+        console.error(chalk.red(`Semantic set-shared-source failed: ${error.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  semantic
+    .command('connect-shared-source')
+    .description('Consume one approved source descriptor, register the source, run health gate, and sync it into the local mirror')
+    .option('--input-file <path>', 'Published shared source descriptor JSON')
+    .option('--spec <spec-id>', 'Use the default published descriptor under this spec')
+    .option('--name <name>', 'Optional source name override')
+    .option('--bundle <url-or-path>', 'Optional bundle override')
+    .option('--root <path-or-url>', 'Optional root override')
+    .option('--enabled <true|false>', 'Optional enabled override')
+    .option('--required-release-state <state>', 'Optional required release state override')
+    .option('--config <path>', 'Semantic shared source config path')
+    .option('--no-health-check', 'Skip health gate after source registration')
+    .option('--no-sync-now', 'Register the source but do not sync immediately')
+    .option('--allow-non-approved', 'Allow descriptors whose release state is not approved-central')
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      try {
+        await runSemanticConnectSharedSourceCommand(options);
+      } catch (error) {
+        console.error(chalk.red(`Semantic connect-shared-source failed: ${error.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  semantic
+    .command('merge-shared')
+    .description('Merge multiple governed semantic shared-sync bundles into one central/shared-truth candidate bundle')
+    .option('--source <url-or-path>', 'Shared-sync bundle source (repeat to accumulate)', (value, previous = []) => [...previous, value], [])
+    .option('--sources <csv>', 'Shared-sync bundle sources as csv')
+    .option('--config <path>', 'Semantic shared source config path')
+    .option('--spec <spec-id>', 'Spec id used for default registry output paths')
+    .option('--out-file <path>', 'Optional merged bundle output path')
+    .option('--limit <n>', 'Maximum merged entries retained', parseInt)
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      try {
+        await runSemanticMergeSharedCommand(options);
+      } catch (error) {
+        console.error(chalk.red(`Semantic merge-shared failed: ${error.message}`));
+        process.exitCode = 1;
+      }
+    });
+
+  semantic
+    .command('publish-shared-registry')
+    .description('Promote one merged semantic shared candidate bundle into the approved central registry after release gates pass')
+    .option('--spec <spec-id>', 'Spec id used for default candidate input and published output paths')
+    .option('--input-file <path>', 'Candidate bundle input path')
+    .option('--out-file <path>', 'Optional approved bundle output path')
+    .option('--index-file <path>', 'Optional approved index output path')
+    .option('--receipt-file <path>', 'Optional publish receipt output path')
+    .option('--source-name <name>', 'Descriptor source name emitted alongside the approved bundle')
+    .option('--source-descriptor-file <path>', 'Optional output path for the published source descriptor')
+    .option('--public-bundle <url-or-path>', 'Optional public bundle url/path written into the source descriptor')
+    .option('--public-root <url-or-path>', 'Optional public root url/path written into the source descriptor')
+    .option('--min-sources <n>', 'Minimum required merged source count', parseInt)
+    .option('--min-entries <n>', 'Minimum required merged entry count', parseInt)
+    .option('--no-require-zero-blocked', 'Allow publishing candidates that still carry blocked merge items')
+    .option('--json', 'Print machine-readable JSON output')
+    .action(async (options) => {
+      try {
+        await runSemanticPublishSharedRegistryCommand(options);
+      } catch (error) {
+        console.error(chalk.red(`Semantic publish-shared-registry failed: ${error.message}`));
+        process.exitCode = 1;
+      }
+    });
+}
+
+module.exports = {
+  runSemanticObserveCommand,
+  runSemanticListCommand,
+  runSemanticLessonsCommand,
+  runSemanticReplayCommand,
+  runSemanticEvalCommand,
+  runSemanticEvalRunsCommand,
+  runSemanticPromotedCommand,
+  runSemanticPromoteCommand,
+  runSemanticRollbackCommand,
+  runSemanticProgressCommand,
+  runSemanticSupremeIntentListCommand,
+  runSemanticSupremeIntentShowCommand,
+  runSemanticGovernanceReportCommand,
+  runSemanticBackflowReportCommand,
+  runSemanticArchiveReportCommand,
+  runSemanticDeltaExportCommand,
+  runSemanticPublishDeltaCommand,
+  runSemanticExportSharedSyncCommand,
+  runSemanticSyncSharedCommand,
+  runSemanticHealthSharedSourceCommand,
+  runSemanticListSharedSourcesCommand,
+  runSemanticSetSharedSourceCommand,
+  runSemanticConnectSharedSourceCommand,
+  runSemanticMergeSharedCommand,
+  runSemanticPublishSharedRegistryCommand,
+  registerSemanticCommands
+};