sneakoscope 0.9.13 → 0.9.14

package/src/commands/ppt.mjs

@@ -0,0 +1,44 @@
+import path from 'node:path';
+import { projectRoot, readJson, writeJsonAtomic } from '../core/fsx.mjs';
+import { findLatestMission, loadMission } from '../core/mission.mjs';
+import { flag } from '../cli/args.mjs';
+import { printJson } from '../cli/output.mjs';
+import { writePptBuildArtifacts, writePptRouteArtifacts } from '../core/ppt.mjs';
+import { finalizeRouteWithProof } from '../core/proof/route-finalizer.mjs';
+
+export async function run(_command, args = []) {
+  const root = await projectRoot();
+  const action = args[0] || 'status';
+  const missionArg = args[1] && !String(args[1]).startsWith('--') ? args[1] : 'latest';
+  const missionId = missionArg === 'latest' ? await findLatestMission(root) : missionArg;
+  if (!missionId) {
+    const result = { schema: 'sks.ppt-status.v1', ok: false, status: 'missing_mission' };
+    if (flag(args, '--json')) return printJson(result);
+    console.error('No mission found.');
+    process.exitCode = 1;
+    return;
+  }
+  const { dir, mission } = await loadMission(root, missionId);
+  const contract = await readJson(path.join(dir, 'decision-contract.json'), { prompt: mission.prompt, answers: {}, sealed_hash: null });
+  if (action === 'build') {
+    await writePptRouteArtifacts(dir, contract);
+    const build = await writePptBuildArtifacts(dir, contract);
+    const proof = await finalizeRouteWithProof(root, { missionId, route: '$PPT', mock: flag(args, '--mock'), artifacts: build.files || [], claims: [{ id: 'ppt-build-fixture', status: 'verified_partial' }] });
+    const result = { schema: 'sks.ppt-build.v1', ok: proof.ok, mission_id: missionId, build, proof: proof.validation };
+    if (flag(args, '--json')) return printJson(result);
+    console.log(`PPT build: ${proof.ok ? 'ok' : 'blocked'} ${missionId}`);
+    if (!proof.ok) process.exitCode = 1;
+    return;
+  }
+  if (action === 'status') {
+    const gate = await readJson(path.join(dir, 'ppt-gate.json'), null);
+    const result = { schema: 'sks.ppt-status.v1', ok: true, mission_id: missionId, gate };
+    if (flag(args, '--json')) return printJson(result);
+    console.log(`PPT mission: ${missionId}`);
+    console.log(`Gate: ${gate?.passed ? 'passed' : gate ? 'present' : 'missing'}`);
+    return;
+  }
+  await writeJsonAtomic(path.join(dir, 'ppt-command-error.json'), { action, args });
+  console.error('Usage: sks ppt build|status <mission-id|latest> [--json] [--mock]');
+  process.exitCode = 1;
+}

package/src/commands/profile.mjs

@@ -0,0 +1,5 @@
+import { profileCommand } from '../core/commands/route-cli.mjs';
+export async function run(_command, args = []) {
+  const [sub = 'show', ...rest] = args;
+  return profileCommand(sub, rest);
+}

package/src/commands/proof-field.mjs

@@ -0,0 +1,5 @@
+import { proofFieldCommand } from '../core/commands/route-cli.mjs';
+export async function run(_command, args = []) {
+  const [sub = 'scan', ...rest] = args;
+  return proofFieldCommand(sub, rest);
+}

package/src/commands/proof.mjs

@@ -5,6 +5,7 @@ import { collectProofEvidence } from '../core/proof/evidence-collector.mjs';
 import { findLatestMission } from '../core/mission.mjs';
 import { readLatestProof, readLatestProofMarkdown, readRouteProof } from '../core/proof/proof-reader.mjs';
 import { writeRouteCompletionProof } from '../core/proof/route-adapter.mjs';
+import { finalizeRouteWithProof } from '../core/proof/route-finalizer.mjs';
 import { renderProofMarkdown, writeCompletionProof } from '../core/proof/proof-writer.mjs';
 import { validateCompletionProof } from '../core/proof/validation.mjs';
 
@@ -41,6 +42,26 @@ export async function run(_command, args = []) {
     if (!result.ok) process.exitCode = 1;
     return;
   }
+  if (action === 'finalize') {
+    const missionArg = rest.find((arg) => !String(arg).startsWith('--')) || 'latest';
+    const missionId = missionArg === 'latest' ? await findLatestMission(root) : missionArg;
+    const routeIndex = args.indexOf('--route');
+    const route = routeIndex >= 0 && args[routeIndex + 1] ? args[routeIndex + 1] : '$SKS';
+    const result = await finalizeRouteWithProof(root, {
+      missionId,
+      route,
+      strict: flag(args, '--strict'),
+      mock: flag(args, '--mock'),
+      requireRelation: flag(args, '--require-relation'),
+      statusHint: flag(args, '--strict') ? 'verified_partial' : 'verified_partial',
+      claims: [{ id: 'proof-finalize', status: 'supported', evidence: `.sneakoscope/missions/${missionId}/completion-proof.json` }],
+      unverified: flag(args, '--mock') ? ['Finalizer ran in mock fixture mode.'] : []
+    });
+    if (flag(args, '--json')) return printJson({ schema: 'sks.completion-proof-finalize.v1', ok: result.ok, mission_id: missionId, validation: result.validation, files: result.files, proof: result.proof });
+    console.log(`Completion proof finalized: ${result.files.latest_json}`);
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
   if (action === 'export' && (flag(rest, '--md') || flag(args, '--md'))) {
     process.stdout.write(await readLatestProofMarkdown(root));
     return;
@@ -86,7 +107,7 @@ export async function run(_command, args = []) {
     console.log(`Completion proof written: ${result.files.latest_json}`);
     return;
   }
-  console.error('Usage: sks proof show|latest|validate|route <mission-id|latest>|export --md|repair latest|smoke [--json]');
+  console.error('Usage: sks proof show|latest|validate|route <mission-id|latest>|finalize <mission-id|latest> [--route route] [--strict] [--mock] [--json]|export --md|repair latest|smoke [--json]');
   process.exitCode = 1;
 }
 

package/src/commands/qa-loop.mjs

@@ -0,0 +1,5 @@
+import { qaLoopCommand } from '../core/commands/route-cli.mjs';
+export async function run(_command, args = []) {
+  const [sub, ...rest] = args;
+  return qaLoopCommand(sub, rest);
+}

package/src/commands/quickstart.mjs

@@ -0,0 +1,2 @@
+import { quickstartCommand } from '../core/commands/basic-cli.mjs';
+export async function run() { return quickstartCommand(); }

package/src/commands/reasoning.mjs

@@ -0,0 +1,2 @@
+import { reasoningCommand } from '../core/commands/basic-cli.mjs';
+export async function run(_command, args = []) { return reasoningCommand(args); }

package/src/commands/recallpulse.mjs

@@ -0,0 +1,5 @@
+import { recallPulseCommand } from '../cli/recallpulse-command.mjs';
+export async function run(_command, args = []) {
+  const [sub = 'status', ...rest] = args;
+  return recallPulseCommand(sub, rest);
+}

package/src/commands/research.mjs

@@ -0,0 +1,5 @@
+import { researchCommand } from '../core/commands/route-cli.mjs';
+export async function run(_command, args = []) {
+  const [sub, ...rest] = args;
+  return researchCommand(sub, rest);
+}

package/src/commands/selftest.mjs

@@ -0,0 +1,2 @@
+import { selftestCommand } from '../core/commands/basic-cli.mjs';
+export async function run(_command, args = []) { return selftestCommand(args); }

package/src/commands/setup.mjs

@@ -0,0 +1,2 @@
+import { setupCommand } from '../core/commands/basic-cli.mjs';
+export async function run(_command, args = []) { return setupCommand(args); }

package/src/commands/skill-dream.mjs

@@ -0,0 +1,5 @@
+import { skillDreamCommand } from '../core/commands/route-cli.mjs';
+export async function run(_command, args = []) {
+  const [sub = 'status', ...rest] = args;
+  return skillDreamCommand(sub, rest);
+}

package/src/commands/stats.mjs

@@ -0,0 +1,2 @@
+import { statsCommand } from '../core/commands/route-cli.mjs';
+export async function run(_command, args = []) { return statsCommand(args); }

package/src/commands/team.mjs

@@ -0,0 +1,2 @@
+import { team } from '../core/commands/route-cli.mjs';
+export async function run(_command, args = []) { return team(args); }

package/src/commands/tmux.mjs

@@ -0,0 +1,5 @@
+import { tmuxCommand } from '../core/commands/basic-cli.mjs';
+export async function run(_command, args = []) {
+  const [sub = 'check', ...rest] = args;
+  return tmuxCommand(sub, rest);
+}

package/src/commands/update-check.mjs

@@ -0,0 +1,2 @@
+import { updateCheckCommand } from '../core/commands/basic-cli.mjs';
+export async function run(_command, args = []) { return updateCheckCommand(args); }

package/src/commands/usage.mjs

@@ -0,0 +1,2 @@
+import { usageCommand } from '../core/commands/basic-cli.mjs';
+export async function run(_command, args = []) { return usageCommand(args); }

package/src/commands/validate-artifacts.mjs

@@ -0,0 +1,2 @@
+import { validateArtifactsCommand } from '../core/commands/route-cli.mjs';
+export async function run(_command, args = []) { return validateArtifactsCommand(args); }

package/src/commands/versioning.mjs

@@ -0,0 +1,16 @@
+import { projectRoot } from '../core/fsx.mjs';
+import { bumpProjectVersion, disableVersionGitHook, versioningStatus } from '../core/version-manager.mjs';
+import { flag } from '../cli/args.mjs';
+import { printJson } from '../cli/output.mjs';
+export async function run(_command, args = []) {
+  const root = await projectRoot();
+  const action = args[0] || 'status';
+  const result = action === 'bump'
+    ? await bumpProjectVersion(root, { force: true })
+    : ['disable', 'off', 'remove-hook', 'unhook'].includes(action)
+      ? await disableVersionGitHook(root)
+      : await versioningStatus(root);
+  if (flag(args, '--json')) return printJson(result);
+  console.log(JSON.stringify(result, null, 2));
+  if (result.ok === false) process.exitCode = 1;
+}

package/src/commands/wiki.mjs

@@ -85,8 +85,8 @@ export async function run(_command, args = []) {
     if (!result.ok) process.exitCode = 1;
     return;
   }
-  const legacy = await import('../cli/legacy-main.mjs');
-  return legacy.main(['wiki', ...args]);
+  const { wikiCommand } = await import('../core/commands/route-cli.mjs');
+  return wikiCommand(action, args.slice(1));
 }
 
 function parseBbox(raw) {

package/src/core/codex-lb-circuit.mjs

@@ -99,6 +99,24 @@ export function codexLbMetrics(circuit = emptyCircuit()) {
   };
 }
 
+export async function codexLbProofEvidence(root = packageRoot()) {
+  const circuit = await readCodexLbCircuit(root);
+  const metrics = codexLbMetrics(circuit);
+  return {
+    schema: 'sks.codex-lb-proof-evidence.v1',
+    ok: metrics.ok,
+    status: circuit.state === 'open' ? 'blocked' : 'verified_partial',
+    circuit_state: circuit.state,
+    report_path: codexLbReportPath(root),
+    last_ok_at: circuit.last_ok_at,
+    last_failure_at: circuit.last_failure_at,
+    last_warning_at: circuit.last_warning_at,
+    recent_failures: circuit.recent_failures?.length || 0,
+    recent_warnings: circuit.recent_warnings?.length || 0,
+    policy: metrics.policy
+  };
+}
+
 function emptyCircuit() {
   return {
     schema: CODEX_LB_CIRCUIT_SCHEMA,

package/src/core/commands/basic-cli.mjs

@@ -0,0 +1,315 @@
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { COMMANDS } from '../../cli/command-registry.mjs';
+import { flag } from '../../cli/args.mjs';
+import { printJson, sksTextLogo } from '../../cli/output.mjs';
+import { PACKAGE_VERSION, ensureDir, exists, nowIso, projectRoot, readJson, runProcess, sksRoot, tmpdir, writeJsonAtomic } from '../fsx.mjs';
+import { COMMAND_CATALOG, DOLLAR_COMMAND_ALIASES, DOLLAR_COMMANDS, USAGE_TOPICS, routePrompt, routeReasoning, reasoningInstruction } from '../routes.mjs';
+import { initProject, normalizeInstallScope, sksCommandPrefix } from '../init.mjs';
+import { buildFeatureRegistry, validateFeatureRegistry } from '../feature-registry.mjs';
+import { hooksExplainReport } from '../../cli/feature-commands.mjs';
+import { writeSelftestRouteProof } from '../proof/selftest-proof-fixtures.mjs';
+import { createMission } from '../mission.mjs';
+
+export async function helpCommand(args = []) {
+  const topic = args[0];
+  if (topic) return usageCommand([topic]);
+  console.log(`${sksTextLogo()}\n\nUsage\n`);
+  console.log('  sks');
+  console.log('  sks help [topic]');
+  console.log('  sks commands [--json]');
+  console.log('  sks dollar-commands [--json]');
+  console.log('  sks proof show --json');
+  console.log('');
+  for (const row of commandRows().filter((entry) => entry.maturity !== 'labs')) {
+    console.log(`  ${row.usage.padEnd(58)} ${row.description}`);
+  }
+  console.log('\nThree core promises: Completion Proof for serious routes, Image Voxel TriWiki for visual routes, and release-gated Codex App/codex-lb/hooks/Rust evidence.');
+}
+
+export function commandsCommand(args = []) {
+  const commands = commandRows();
+  if (flag(args, '--json')) {
+    return printJson({
+      schema: 'sks.command-registry.v1',
+      aliases: ['sks', 'sneakoscope'],
+      commands
+    });
+  }
+  console.log(`${sksTextLogo()}\n\nCommands\n`);
+  const width = Math.max(...commands.map((entry) => entry.usage.length));
+  for (const entry of commands) console.log(`${entry.usage.padEnd(width)}  ${entry.description}`);
+}
+
+export function dollarCommandsCommand(args = []) {
+  const out = { dollar_commands: DOLLAR_COMMANDS, app_skill_aliases: DOLLAR_COMMAND_ALIASES };
+  if (flag(args, '--json')) return printJson(out);
+  console.log(`${sksTextLogo()}\n\n$ Commands\n`);
+  const width = Math.max(...DOLLAR_COMMANDS.map((entry) => entry.command.length));
+  for (const entry of DOLLAR_COMMANDS) console.log(`${entry.command.padEnd(width)}  ${entry.route}: ${entry.description}`);
+  console.log(`\nCanonical Codex App picker skills: ${DOLLAR_COMMAND_ALIASES.map((entry) => entry.app_skill).join(', ')}`);
+}
+
+export function aliasesCommand() {
+  console.log('Aliases');
+  console.log('- sks, sneakoscope');
+  console.log('- $ aliases:');
+  for (const entry of DOLLAR_COMMAND_ALIASES) console.log(`  ${entry.app_skill} -> ${entry.canonical}`);
+}
+
+export function dfixCommand() {
+  console.log(`SKS Direct Fix Mode
+
+Prompt command:
+  $DFix <tiny direct fix request>
+
+Rules:
+  Apply only the requested tiny copy/config/docs/labels/spacing/translation/simple mechanical edit.
+  Keep verification cheap and explicit.
+  Finish with a DFix completion summary and one Honest check line.`);
+}
+
+export function usageCommand(args = []) {
+  const topic = args[0] || 'overview';
+  if (topic === 'overview') {
+    console.log(`Usage topics: ${USAGE_TOPICS}`);
+    console.log('Try: sks usage goal, sks usage team, sks usage image-ux-review');
+    return;
+  }
+  const row = commandRows().find((entry) => entry.name === topic);
+  if (row) {
+    console.log(`${row.name}\n`);
+    console.log(`Usage: ${row.usage}`);
+    console.log(row.description);
+    return;
+  }
+  const route = DOLLAR_COMMANDS.find((entry) => entry.command.toLowerCase() === `$${topic}`.toLowerCase());
+  if (route) {
+    console.log(`${route.command}\n`);
+    console.log(`${route.route}: ${route.description}`);
+    return;
+  }
+  console.log(`Unknown usage topic: ${topic}`);
+  console.log(`Known topics: ${USAGE_TOPICS}`);
+}
+
+export function quickstartCommand() {
+  console.log(`Sneakoscope Codex Quickstart
+
+  sks setup --local-only
+  sks doctor
+  sks commands
+  sks dollar-commands
+  sks all-features selftest --mock --execute-fixtures --strict-artifacts --json
+
+For implementation work, use Codex App prompt routes such as $Team, $Goal, $QA-LOOP, $Image-UX-Review, and $Computer-Use.`);
+}
+
+export async function updateCheckCommand(args = []) {
+  const latest = await npmViewVersion('sneakoscope');
+  const result = {
+    package: 'sneakoscope',
+    current: PACKAGE_VERSION,
+    runtime_current: PACKAGE_VERSION,
+    latest: latest.version,
+    update_available: latest.version ? compareVersions(latest.version, PACKAGE_VERSION) > 0 : false,
+    error: latest.error || null
+  };
+  if (flag(args, '--json')) return printJson(result);
+  console.log(`${sksTextLogo()}\n\nUpdate Check`);
+  console.log(`Current: ${result.current}`);
+  console.log(`Latest:  ${result.latest || 'unknown'}`);
+  console.log(`Update:  ${result.update_available ? 'available' : 'not needed'}`);
+  if (result.error) console.log(`Error:   ${result.error}`);
+  if (result.update_available) console.log(`Run:     npm i -g sneakoscope@${result.latest}`);
+}
+
+export async function setupCommand(args = []) {
+  const root = await projectRoot();
+  const installScope = installScopeFromArgs(args);
+  const res = await initProject(root, {
+    force: flag(args, '--force'),
+    installScope,
+    localOnly: flag(args, '--local-only'),
+    globalCommand: 'sks'
+  });
+  const result = {
+    schema: 'sks.setup.v1',
+    ok: true,
+    root,
+    install_scope: installScope,
+    command_prefix: sksCommandPrefix(installScope, { globalCommand: 'sks' }),
+    created: res.created || [],
+    local_only: flag(args, '--local-only')
+  };
+  if (flag(args, '--json')) return printJson(result);
+  console.log(`Setup complete: ${root}`);
+  console.log(`Install scope: ${installScope}`);
+  for (const file of result.created) console.log(`- ${file}`);
+}
+
+export async function bootstrapCommand(args = []) {
+  return setupCommand(['--local-only', ...args]);
+}
+
+export async function initCommand(args = []) {
+  return setupCommand(args);
+}
+
+export async function fixPathCommand(args = []) {
+  const root = await projectRoot();
+  const installScope = installScopeFromArgs(args);
+  await initProject(root, { installScope, localOnly: flag(args, '--local-only'), globalCommand: 'sks', force: true });
+  const result = {
+    schema: 'sks.fix-path.v1',
+    ok: true,
+    root,
+    install_scope: installScope,
+    hook_command_prefix: sksCommandPrefix(installScope, { globalCommand: 'sks' }),
+    hooks: path.join(root, '.codex', 'hooks.json')
+  };
+  if (flag(args, '--json')) return printJson(result);
+  console.log(`SKS hook path refreshed: ${path.relative(root, result.hooks)}`);
+}
+
+export async function depsCommand(sub = 'check', args = []) {
+  const action = sub || 'check';
+  if (action !== 'check' && action !== 'status') {
+    console.error('Usage: sks deps check [--json]');
+    process.exitCode = 1;
+    return;
+  }
+  const npm = whichSync('npm');
+  const nodeOk = Number(process.versions.node.split('.')[0]) >= 20;
+  const root = await sksRoot();
+  const result = {
+    schema: 'sks.deps-status.v1',
+    root,
+    ready: Boolean(nodeOk && npm),
+    node: { ok: nodeOk, version: process.version },
+    npm: { ok: Boolean(npm), bin: npm },
+    next_actions: [
+      ...(!nodeOk ? ['Install Node.js 20.11+.'] : []),
+      ...(!npm ? ['Install npm or a Node.js distribution that includes npm.'] : [])
+    ]
+  };
+  if (flag(args, '--json')) return printJson(result);
+  console.log('SKS Dependencies');
+  console.log(`Node: ${result.node.ok ? 'ok' : 'missing'} ${result.node.version}`);
+  console.log(`npm:  ${result.npm.ok ? 'ok' : 'missing'} ${result.npm.bin || ''}`.trim());
+  if (!result.ready) process.exitCode = 1;
+}
+
+export async function postinstallCommand(args = []) {
+  const { postinstall } = await import('../../cli/install-helpers.mjs');
+  return postinstall({ bootstrap: flag(args, '--bootstrap') });
+}
+
+export async function selftestCommand(args = []) {
+  process.env.CI = 'true';
+  const root = await projectRoot();
+  const tmp = tmpdir();
+  await ensureDir(tmp);
+  const registry = await buildFeatureRegistry({ root });
+  const coverage = validateFeatureRegistry(registry);
+  if (!coverage.ok) throw new Error(`selftest: feature registry blocked: ${coverage.blockers.join(', ')}`);
+  const mission = await createMission(tmp, { mode: 'team', prompt: 'selftest route proof fixture' });
+  await writeSelftestRouteProof(tmp, { missionId: mission.id, kind: 'team_gate' });
+  const proof = await readJson(path.join(tmp, '.sneakoscope', 'missions', mission.id, 'completion-proof.json'), null);
+  if (!proof?.mission_id) throw new Error('selftest: completion proof fixture missing');
+  const hookExplain = hooksExplainReport();
+  if (!hookExplain.events.includes('Stop')) throw new Error('selftest: hook explain missing Stop');
+  const result = {
+    schema: 'sks.selftest.v1',
+    ok: true,
+    version: PACKAGE_VERSION,
+    generated_at: nowIso(),
+    checks: ['feature_registry', 'route_completion_proof_fixture', 'hooks_policy_surface'],
+    tmp_root: tmp
+  };
+  if (flag(args, '--json')) return printJson(result);
+  console.log('SKS selftest passed');
+}
+
+export async function reasoningCommand(args = []) {
+  const prompt = args.filter((arg) => !String(arg).startsWith('--')).join(' ').trim();
+  const route = routePrompt(prompt || '$SKS');
+  const info = routeReasoning(route, prompt);
+  const result = {
+    route: route?.command || '$SKS',
+    effort: info.effort,
+    profile: info.profile,
+    reason: info.reason,
+    temporary: true,
+    instruction: reasoningInstruction(info)
+  };
+  if (flag(args, '--json')) return printJson(result);
+  console.log('SKS Reasoning Route');
+  console.log(`Route:   ${result.route}`);
+  console.log(`Effort:  ${result.effort}`);
+  console.log(`Profile: ${result.profile}`);
+}
+
+export async function tmuxCommand(sub = 'check', args = []) {
+  const { runTmuxStatus, tmuxReadiness } = await import('../tmux-ui.mjs');
+  const action = sub || 'check';
+  if (action === 'status' || action === 'banner') return runTmuxStatus(action === 'banner' ? ['--once', ...args] : args);
+  const status = await tmuxReadiness().catch((err) => ({ ok: false, error: err.message }));
+  if (flag(args, '--json')) return printJson({ schema: 'sks.tmux-status.v1', ...status });
+  console.log(`tmux: ${status.ok ? 'ok' : 'missing'} ${status.version || status.error || ''}`.trim());
+  if (!status.ok) process.exitCode = 1;
+}
+
+export async function autoReviewCommand(sub = 'status', args = []) {
+  const { autoReviewStatus, enableAutoReview, disableAutoReview } = await import('../auto-review.mjs');
+  const action = sub || 'status';
+  const result = action === 'enable' || action === 'start'
+    ? await enableAutoReview({ high: flag(args, '--high') })
+    : action === 'disable'
+      ? await disableAutoReview()
+      : await autoReviewStatus();
+  if (flag(args, '--json')) return printJson(result);
+  console.log(JSON.stringify(result, null, 2));
+}
+
+function commandRows() {
+  const registry = new Map(Object.entries(COMMANDS).map(([name, meta]) => [name, meta]));
+  return COMMAND_CATALOG.map((entry) => ({
+    name: entry.name,
+    usage: entry.usage,
+    description: entry.description,
+    maturity: registry.get(entry.name)?.maturity || entry.maturity || 'labs'
+  })).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function installScopeFromArgs(args = [], fallback = 'global') {
+  if (flag(args, '--project')) return 'project';
+  if (flag(args, '--global')) return 'global';
+  const index = args.indexOf('--install-scope');
+  return normalizeInstallScope(index >= 0 && args[index + 1] ? args[index + 1] : fallback);
+}
+
+async function npmViewVersion(name) {
+  const npm = whichSync('npm');
+  if (!npm) return { version: null, error: 'npm not found on PATH' };
+  const result = await runProcess(npm, ['view', name, 'version', '--silent'], { timeoutMs: 15000, maxOutputBytes: 4096 }).catch((err) => ({ code: 1, stdout: '', stderr: err.message }));
+  if (result.code !== 0) return { version: null, error: (result.stderr || result.stdout || 'npm view failed').trim() };
+  return { version: String(result.stdout || '').trim().split(/\s+/).pop() || null };
+}
+
+function compareVersions(a, b) {
+  const pa = String(a || '').split('.').map((x) => Number.parseInt(x, 10) || 0);
+  const pb = String(b || '').split('.').map((x) => Number.parseInt(x, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+    if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0);
+  }
+  return 0;
+}
+
+function whichSync(command) {
+  const result = spawnSync(process.platform === 'win32' ? 'where' : 'command', process.platform === 'win32' ? [command] : ['-v', command], {
+    encoding: 'utf8',
+    shell: process.platform !== 'win32'
+  });
+  return result.status === 0 ? String(result.stdout || '').trim().split(/\r?\n/)[0] : null;
+}

package/src/{cli/maintenance-commands.mjs → core/commands/route-cli.mjs}

@@ -1,43 +1,43 @@
 import path from 'node:path';
 import fsp from 'node:fs/promises';
 import { createHash } from 'node:crypto';
-import { readJson, readText, writeJsonAtomic, writeTextAtomic, appendJsonlBounded, nowIso, exists, ensureDir, packageRoot, dirSize, formatBytes, PACKAGE_VERSION, sksRoot, readStdin, runProcess } from '../core/fsx.mjs';
-import { initProject } from '../core/init.mjs';
-import { getCodexInfo, runCodexExec } from '../core/codex-adapter.mjs';
-import { createMission, loadMission, findLatestMission, missionDir, setCurrent, stateFile } from '../core/mission.mjs';
-import { buildQuestionSchema, writeQuestions } from '../core/questions.mjs';
-import { sealContract } from '../core/decision-contract.mjs';
-import { buildQaLoopQuestionSchema, buildQaLoopPrompt, evaluateQaGate, qaStatus, writeMockQaResult, writeQaLoopArtifacts } from '../core/qa-loop.mjs';
-import { containsUserQuestion, noQuestionContinuationReason } from '../core/no-question-guard.mjs';
-import { RESEARCH_GENIUS_SUMMARY_ARTIFACT, RESEARCH_SOURCE_SKILL_ARTIFACT, countGeniusOpinionSummaries, countResearchPaperSections, buildResearchPrompt, evaluateResearchGate, findResearchPaperArtifact, researchPaperArtifactForPlan, writeMockResearchResult, writeResearchPlan } from '../core/research.mjs';
-import { storageReport, enforceRetention, pruneWikiArtifacts } from '../core/retention.mjs';
-import { evaluateDoneGate } from '../core/hproof.mjs';
-import { renderCartridge, validateCartridge, driftCartridge, snapshotCartridge } from '../core/gx-renderer.mjs';
-import { DEFAULT_EVAL_THRESHOLDS, compareEvaluationReports, runEvaluationBenchmark } from '../core/evaluation.mjs';
-import { contextCapsule } from '../core/triwiki-attention.mjs';
-import { rgbaKey, rgbaToWikiCoord, validateWikiCoordinateIndex } from '../core/wiki-coordinate.mjs';
-import { ALLOWED_REASONING_EFFORTS, CODEX_COMPUTER_USE_ONLY_POLICY, DOLLAR_SKILL_NAMES, FROM_CHAT_IMG_CHECKLIST_ARTIFACT, FROM_CHAT_IMG_COVERAGE_ARTIFACT, FROM_CHAT_IMG_QA_LOOP_ARTIFACT, FROM_CHAT_IMG_SOURCE_INVENTORY_ARTIFACT, FROM_CHAT_IMG_TEMP_TRIWIKI_ARTIFACT, FROM_CHAT_IMG_TEMP_TRIWIKI_SESSIONS, FROM_CHAT_IMG_VISUAL_MAP_ARTIFACT, FROM_CHAT_IMG_WORK_ORDER_ARTIFACT, RECOMMENDED_SKILLS, ROUTES, hasFromChatImgSignal, reflectionRequiredForRoute, routeNeedsContext7, routePrompt, routeReasoning, routeRequiresSubagents, stackCurrentDocsPolicy, stripVisibleDecisionAnswerBlocks, triwikiContextTracking } from '../core/routes.mjs';
-import { TEAM_DECOMPOSITION_ARTIFACT, TEAM_GRAPH_ARTIFACT, TEAM_INBOX_DIR, TEAM_RUNTIME_TASKS_ARTIFACT, teamRuntimePlanMetadata, teamRuntimeRequiredArtifacts, writeTeamRuntimeArtifacts } from '../core/team-dag.mjs';
-import { appendTeamEvent, formatAgentReasoning, formatRoleCounts, initTeamLive, isTerminalTeamAgentStatus, normalizeTeamSpec, parseTeamSpecArgs, readTeamControl, readTeamDashboard, readTeamLive, readTeamTranscriptTail, renderTeamAgentLane, renderTeamCleanupSummary, renderTeamWatch, requestTeamSessionCleanup, teamCleanupRequested, teamReasoningPolicy } from '../core/team-live.mjs';
-import { evaluateTeamReviewPolicyGate, MIN_TEAM_REVIEWER_LANES, MIN_TEAM_REVIEW_POLICY_TEXT, teamReviewPolicy } from '../core/team-review-policy.mjs';
-import { ARTIFACT_FILES, writeValidationReport } from '../core/artifact-schemas.mjs';
-import { writeEffortDecision } from '../core/effort-orchestrator.mjs';
-import { createWorkOrderLedger, writeWorkOrderLedger } from '../core/work-order-ledger.mjs';
-import { writeFromChatImgArtifacts } from '../core/from-chat-img-forensics.mjs';
-import { renderTeamDashboardState, writeTeamDashboardState } from '../core/team-dashboard-renderer.mjs';
-import { runPerfBench, runWorkflowPerfBench } from '../core/perf-bench.mjs';
-import { writeProofFieldReport } from '../core/proof-field.mjs';
-import { PIPELINE_PLAN_ARTIFACT, validatePipelinePlan, writePipelinePlan } from '../core/pipeline.mjs';
-import { GOAL_BRIDGE_ARTIFACT, GOAL_WORKFLOW_ARTIFACT, updateGoalWorkflow, writeGoalWorkflow } from '../core/goal-workflow.mjs';
-import { scanCodeStructure, writeCodeStructureReport } from '../core/code-structure.mjs';
-import { writeMemorySweepReport } from '../core/memory-governor.mjs';
-import { cleanupTmuxTeamView, defaultTmuxSessionName, launchMadTmuxUi, launchTmuxTeamView, reconcileTmuxTeamCockpit, sanitizeTmuxSessionName } from '../core/tmux-ui.mjs';
-import { loadSkillDreamState, recordSkillDreamEvent, runSkillDream, writeSkillForgeReport } from '../core/skill-forge.mjs';
-import { writeMistakeMemoryReport } from '../core/mistake-memory.mjs';
-import { checkDbOperation, checkSqlFile, classifyCommand, classifySql, loadDbSafetyPolicy, safeSupabaseMcpConfig, scanDbSafety } from '../core/db-safety.mjs';
-import { harnessGrowthReport, writeHarnessGrowthReport } from '../core/evaluation.mjs';
-import { enableMadHighProfile, madHighProfileName } from '../core/auto-review.mjs';
-import { permissionGateSummary } from '../core/permission-gates.mjs';
+import { readJson, readText, writeJsonAtomic, writeTextAtomic, appendJsonlBounded, nowIso, exists, ensureDir, packageRoot, dirSize, formatBytes, PACKAGE_VERSION, sksRoot, readStdin, runProcess } from '../fsx.mjs';
+import { initProject } from '../init.mjs';
+import { getCodexInfo, runCodexExec } from '../codex-adapter.mjs';
+import { createMission, loadMission, findLatestMission, missionDir, setCurrent, stateFile } from '../mission.mjs';
+import { buildQuestionSchema, writeQuestions } from '../questions.mjs';
+import { sealContract } from '../decision-contract.mjs';
+import { buildQaLoopQuestionSchema, buildQaLoopPrompt, evaluateQaGate, qaStatus, writeMockQaResult, writeQaLoopArtifacts } from '../qa-loop.mjs';
+import { containsUserQuestion, noQuestionContinuationReason } from '../no-question-guard.mjs';
+import { RESEARCH_GENIUS_SUMMARY_ARTIFACT, RESEARCH_SOURCE_SKILL_ARTIFACT, countGeniusOpinionSummaries, countResearchPaperSections, buildResearchPrompt, evaluateResearchGate, findResearchPaperArtifact, researchPaperArtifactForPlan, writeMockResearchResult, writeResearchPlan } from '../research.mjs';
+import { storageReport, enforceRetention, pruneWikiArtifacts } from '../retention.mjs';
+import { evaluateDoneGate } from '../hproof.mjs';
+import { renderCartridge, validateCartridge, driftCartridge, snapshotCartridge } from '../gx-renderer.mjs';
+import { DEFAULT_EVAL_THRESHOLDS, compareEvaluationReports, runEvaluationBenchmark } from '../evaluation.mjs';
+import { contextCapsule } from '../triwiki-attention.mjs';
+import { rgbaKey, rgbaToWikiCoord, validateWikiCoordinateIndex } from '../wiki-coordinate.mjs';
+import { ALLOWED_REASONING_EFFORTS, CODEX_COMPUTER_USE_ONLY_POLICY, DOLLAR_SKILL_NAMES, FROM_CHAT_IMG_CHECKLIST_ARTIFACT, FROM_CHAT_IMG_COVERAGE_ARTIFACT, FROM_CHAT_IMG_QA_LOOP_ARTIFACT, FROM_CHAT_IMG_SOURCE_INVENTORY_ARTIFACT, FROM_CHAT_IMG_TEMP_TRIWIKI_ARTIFACT, FROM_CHAT_IMG_TEMP_TRIWIKI_SESSIONS, FROM_CHAT_IMG_VISUAL_MAP_ARTIFACT, FROM_CHAT_IMG_WORK_ORDER_ARTIFACT, RECOMMENDED_SKILLS, ROUTES, hasFromChatImgSignal, reflectionRequiredForRoute, routeNeedsContext7, routePrompt, routeReasoning, routeRequiresSubagents, stackCurrentDocsPolicy, stripVisibleDecisionAnswerBlocks, triwikiContextTracking } from '../routes.mjs';
+import { TEAM_DECOMPOSITION_ARTIFACT, TEAM_GRAPH_ARTIFACT, TEAM_INBOX_DIR, TEAM_RUNTIME_TASKS_ARTIFACT, teamRuntimePlanMetadata, teamRuntimeRequiredArtifacts, writeTeamRuntimeArtifacts } from '../team-dag.mjs';
+import { appendTeamEvent, formatAgentReasoning, formatRoleCounts, initTeamLive, isTerminalTeamAgentStatus, normalizeTeamSpec, parseTeamSpecArgs, readTeamControl, readTeamDashboard, readTeamLive, readTeamTranscriptTail, renderTeamAgentLane, renderTeamCleanupSummary, renderTeamWatch, requestTeamSessionCleanup, teamCleanupRequested, teamReasoningPolicy } from '../team-live.mjs';
+import { evaluateTeamReviewPolicyGate, MIN_TEAM_REVIEWER_LANES, MIN_TEAM_REVIEW_POLICY_TEXT, teamReviewPolicy } from '../team-review-policy.mjs';
+import { ARTIFACT_FILES, writeValidationReport } from '../artifact-schemas.mjs';
+import { writeEffortDecision } from '../effort-orchestrator.mjs';
+import { createWorkOrderLedger, writeWorkOrderLedger } from '../work-order-ledger.mjs';
+import { writeFromChatImgArtifacts } from '../from-chat-img-forensics.mjs';
+import { renderTeamDashboardState, writeTeamDashboardState } from '../team-dashboard-renderer.mjs';
+import { runPerfBench, runWorkflowPerfBench } from '../perf-bench.mjs';
+import { writeProofFieldReport } from '../proof-field.mjs';
+import { PIPELINE_PLAN_ARTIFACT, validatePipelinePlan, writePipelinePlan } from '../pipeline.mjs';
+import { GOAL_BRIDGE_ARTIFACT, GOAL_WORKFLOW_ARTIFACT, updateGoalWorkflow, writeGoalWorkflow } from '../goal-workflow.mjs';
+import { scanCodeStructure, writeCodeStructureReport } from '../code-structure.mjs';
+import { writeMemorySweepReport } from '../memory-governor.mjs';
+import { cleanupTmuxTeamView, defaultTmuxSessionName, launchMadTmuxUi, launchTmuxTeamView, reconcileTmuxTeamCockpit, sanitizeTmuxSessionName } from '../tmux-ui.mjs';
+import { loadSkillDreamState, recordSkillDreamEvent, runSkillDream, writeSkillForgeReport } from '../skill-forge.mjs';
+import { writeMistakeMemoryReport } from '../mistake-memory.mjs';
+import { checkDbOperation, checkSqlFile, classifyCommand, classifySql, loadDbSafetyPolicy, safeSupabaseMcpConfig, scanDbSafety } from '../db-safety.mjs';
+import { harnessGrowthReport, writeHarnessGrowthReport } from '../evaluation.mjs';
+import { enableMadHighProfile, madHighProfileName } from '../auto-review.mjs';
+import { permissionGateSummary } from '../permission-gates.mjs';
 
 const flag = (args, name) => args.includes(name);
 const promptOf = (args) => args.filter((x) => !String(x).startsWith('--')).join(' ').trim();