nubos-pilot 0.1.0

package/bin/install.js

@@ -0,0 +1,500 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const { atomicWriteFileSync, withFileLock, NubosPilotError } = require('../lib/core.cjs');
+const { askUser: defaultAskUser } = require('../lib/askuser.cjs');
+const manifestMod = require('../lib/install/manifest.cjs');
+const stagingMod = require('../lib/install/staging.cjs');
+const managedBlockMod = require('../lib/install/managed-block.cjs');
+const agentsMdMod = require('../lib/install/agents-md.cjs');
+const codexTomlMod = require('../lib/install/codex-toml.cjs');
+const runtimeDetectMod = require('../lib/install/runtime-detect.cjs');
+const backupMod = require('../lib/install/backup.cjs');
+
+const cyan = '\x1b[36m', green = '\x1b[32m', yellow = '\x1b[33m',
+      red = '\x1b[31m', dim = '\x1b[2m', reset = '\x1b[0m';
+
+const PAYLOAD_SUBPATH = path.join('.claude', 'nubos-pilot');
+const STATE_SUBPATH = '.nubos-pilot';
+const SOURCE_PAYLOAD_DIR = path.join(__dirname, '..', 'templates', 'claude', 'payload');
+const OPENCODE_SUBPATH = path.join('.opencode', 'nubos-pilot');
+const OPENCODE_MANIFEST_PREFIX = '.opencode/nubos-pilot/';
+const SOURCE_OPENCODE_DIR = path.join(__dirname, '..', 'templates', 'opencode', 'payload');
+const OPENCODE_JSON_TEMPLATE = path.join(__dirname, '..', 'templates', 'opencode', 'opencode.json');
+
+function _autoAskUser(spec) {
+  return Promise.resolve({
+    value: spec && spec.default !== undefined ? spec.default : null,
+    source: 'auto',
+  });
+}
+
+const MANAGED_BLOCK_INNER =
+  'This project uses [nubos-pilot](https://github.com/nubos/nubos-pilot)'
+  + ' for planning and execution.\n\nRun `npx nubos-pilot doctor`'
+  + ' to check install integrity.';
+
+const VALID_AGENTS = ['claude', 'codex', 'gemini', 'opencode'];
+const VALID_SCOPES = ['local', 'global'];
+
+function parseInstallFlags(args) {
+  const flags = { agent: null, scope: null, mcp: false, yes: false };
+  const rest = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--agent' || a === '-a') { flags.agent = args[++i] || null; continue; }
+    if (a.startsWith('--agent=')) { flags.agent = a.slice('--agent='.length); continue; }
+    if (a === '--scope' || a === '-s') { flags.scope = args[++i] || null; continue; }
+    if (a.startsWith('--scope=')) { flags.scope = a.slice('--scope='.length); continue; }
+    if (a === '--mcp') { flags.mcp = true; continue; }
+    if (a === '--yes' || a === '-y') { flags.yes = true; continue; }
+    rest.push(a);
+  }
+  if (flags.agent !== null && !VALID_AGENTS.includes(flags.agent)) {
+    throw new NubosPilotError('invalid-flag',
+      '--agent must be one of: ' + VALID_AGENTS.join(', '),
+      { flag: '--agent', got: flags.agent });
+  }
+  if (flags.scope !== null && !VALID_SCOPES.includes(flags.scope)) {
+    throw new NubosPilotError('invalid-flag',
+      '--scope must be one of: ' + VALID_SCOPES.join(', '),
+      { flag: '--scope', got: flags.scope });
+  }
+  return { flags, rest };
+}
+
+function _payloadDirFor(projectRoot, scope) {
+  if (scope === 'global') return path.join(os.homedir(), '.claude', 'nubos-pilot');
+  return path.join(projectRoot, PAYLOAD_SUBPATH);
+}
+
+function _opencodePayloadDirFor(projectRoot, scope) {
+  if (scope === 'global') return path.join(os.homedir(), '.config', 'opencode', 'nubos-pilot');
+  return path.join(projectRoot, OPENCODE_SUBPATH);
+}
+
+function _opencodeManifestPrefix(scope) {
+  return scope === 'global'
+    ? '~/.config/opencode/nubos-pilot/'
+    : OPENCODE_MANIFEST_PREFIX;
+}
+
+function _stateDirFor(projectRoot) {
+  return path.join(projectRoot, STATE_SUBPATH);
+}
+
+function _readExistingScope(projectRoot) {
+  const cfgPath = path.join(_stateDirFor(projectRoot), 'config.json');
+  if (!fs.existsSync(cfgPath)) return null;
+  try {
+    const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));
+    return cfg && cfg.scope ? cfg.scope : null;
+  } catch { return null; }
+}
+
+function detectMode(projectRoot, scope) {
+  const s = scope || _readExistingScope(projectRoot) || 'local';
+  const payloadDir = _payloadDirFor(projectRoot, s);
+  return manifestMod.readManifest(payloadDir) ? 're-install' : 'init';
+}
+
+function _copyTree(src, dst) {
+  let entries;
+  try {
+    entries = fs.readdirSync(src, { withFileTypes: true });
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return; 
+    throw err;
+  }
+  fs.mkdirSync(dst, { recursive: true });
+  for (const e of entries) {
+    const from = path.join(src, e.name);
+    const to = path.join(dst, e.name);
+    if (e.isDirectory()) {
+      _copyTree(from, to);
+    } else if (e.isFile()) {
+      fs.copyFileSync(from, to);
+    }
+
+  }
+}
+
+async function _runInitQuestions(detectedRuntime, askUser, flags) {
+  const f = flags || {};
+  const runtime = f.agent || (await askUser({ type: 'select', question: 'Welche Runtime nutzt du?',
+    options: VALID_AGENTS, default: detectedRuntime || 'claude' })).value;
+  const scope = f.scope || (await askUser({ type: 'select', question: 'Installation scope?',
+    options: VALID_SCOPES, default: 'local' })).value;
+  const model_profile = (await askUser({ type: 'select', question: 'Model-Profile?',
+    options: ['inherit', 'quality', 'balanced', 'budget'], default: 'inherit' })).value;
+  const commit_docs = (await askUser({ type: 'confirm', question: 'Commit documentation artefacts?', default: true })).value;
+  const branching_strategy = (await askUser({ type: 'select', question: 'Branching strategy?',
+    options: ['single-branch', 'phase-branches', 'milestone-branches'], default: 'single-branch' })).value;
+  const phase_branch_template = (await askUser({ type: 'input', question: 'Phase branch template?', default: 'phase/{number}-{slug}' })).value;
+  const milestone_branch_template = (await askUser({ type: 'input', question: 'Milestone branch template?', default: 'milestone/{name}' })).value;
+  const parallelization = (await askUser({ type: 'confirm', question: 'Enable parallelization?', default: true })).value;
+  const research = (await askUser({ type: 'confirm', question: 'Enable research step?', default: false })).value;
+  const plan_checker = (await askUser({ type: 'confirm', question: 'Enable plan_checker?', default: true })).value;
+  const verifier = (await askUser({ type: 'confirm', question: 'Enable verifier?', default: true })).value;
+  const response_language = (await askUser({ type: 'input', question: 'Response language (ISO-639 code)?', default: 'en' })).value;
+  return { runtime, scope, mcp: !!f.mcp, model_profile, commit_docs, branching_strategy, phase_branch_template,
+    milestone_branch_template, parallelization, research, plan_checker, verifier, response_language };
+}
+
+function _repairCodexConfig() {
+  const codexConfig = path.join(os.homedir(), '.codex', 'config.toml');
+  if (!fs.existsSync(codexConfig)) return false;
+  let raw;
+  try { raw = fs.readFileSync(codexConfig, 'utf-8'); } catch { return false; }
+  if (!codexTomlMod.hasTrappedFeatures(raw)) return false;
+  const repaired = codexTomlMod.repairTrappedFeatures(raw);
+  atomicWriteFileSync(codexConfig, repaired);
+  console.error(green + '  [codex] trapped [features] repariert' + reset);
+  return true;
+}
+
+function _rewriteManagedMarkdown(projectRoot) {
+  const claudePath = path.join(projectRoot, 'CLAUDE.md');
+  const agentsPath = path.join(projectRoot, 'AGENTS.md');
+  const geminiPath = path.join(projectRoot, 'GEMINI.md');
+  const claudeExists = fs.existsSync(claudePath);
+  if (claudeExists) {
+    const content = fs.readFileSync(claudePath, 'utf-8');
+    const next = managedBlockMod.rewriteBlock(content, MANAGED_BLOCK_INNER);
+    atomicWriteFileSync(claudePath, next);
+  }
+
+  let agentsBase;
+  if (fs.existsSync(agentsPath)) {
+    agentsBase = fs.readFileSync(agentsPath, 'utf-8');
+  } else if (claudeExists) {
+    agentsBase = agentsMdMod.generateAgentsMd(fs.readFileSync(claudePath, 'utf-8'), 'codex');
+  } else {
+    return; 
+  }
+  const agentsNext = managedBlockMod.rewriteBlock(agentsBase, MANAGED_BLOCK_INNER);
+  atomicWriteFileSync(agentsPath, agentsNext);
+
+  let geminiBase;
+  if (fs.existsSync(geminiPath)) {
+    geminiBase = fs.readFileSync(geminiPath, 'utf-8');
+  } else if (claudeExists) {
+    geminiBase = agentsMdMod.generateAgentsMd(fs.readFileSync(claudePath, 'utf-8'), 'gemini');
+  } else {
+    return;
+  }
+  const geminiNext = managedBlockMod.rewriteBlock(geminiBase, MANAGED_BLOCK_INNER);
+  atomicWriteFileSync(geminiPath, geminiNext);
+}
+
+async function runInstall(opts) {
+  const o = opts || {};
+  const projectRoot = o.projectRoot || o.cwd || process.cwd();
+  const flags = o.flags || {};
+  const mode = o.mode || detectMode(projectRoot, flags.scope);
+  const dryRun = !!o.dryRun;
+  const askUser = flags.yes ? _autoAskUser : (o.askUser || defaultAskUser);
+  const sourceDir = o.sourceDir || SOURCE_PAYLOAD_DIR;
+  const stateDir = _stateDirFor(projectRoot);
+  fs.mkdirSync(stateDir, { recursive: true });
+  return withFileLock(path.join(stateDir, '.install.lock'),
+    () => _runInstallLocked({ projectRoot, mode, dryRun, askUser, sourceDir, stateDir, flags }),
+    { timeoutMs: 60000 });
+}
+
+async function _runInstallLocked(ctx) {
+  const { projectRoot, mode, dryRun, askUser, sourceDir, stateDir, flags } = ctx;
+  console.error(cyan + '→ nubos-pilot install (mode=' + mode + ')' + reset);
+
+  const preliminaryScope = (flags && flags.scope) || _readExistingScope(projectRoot) || 'local';
+  const preliminaryBase = preliminaryScope === 'global' ? os.homedir() : projectRoot;
+  stagingMod.cleanStaleStaging(preliminaryBase);
+
+  let initConfig = null;
+  if (mode === 'init') {
+    const det = runtimeDetectMod.detectRuntime({ cwd: projectRoot });
+    const config = await _runInitQuestions(det && det.runtime, askUser, flags);
+    if (flags && flags.agent) {
+      config.runtime = flags.agent;
+      config.runtime_source = 'flag';
+    } else {
+      config.runtime = det && det.runtime ? det.runtime : config.runtime || 'codex';
+      config.runtime_source = det && det.source ? det.source : 'asked';
+    }
+    const configPath = path.join(stateDir, 'config.json');
+    if (!dryRun) atomicWriteFileSync(configPath, JSON.stringify(config, null, 2));
+    else console.error(dim + 'DRY-RUN: würde schreiben ' + configPath + reset);
+    initConfig = config;
+  }
+
+  const resolvedScope = (initConfig && initConfig.scope) || preliminaryScope;
+  const payloadBase = resolvedScope === 'global' ? os.homedir() : projectRoot;
+  const payloadDir = _payloadDirFor(projectRoot, resolvedScope);
+  const oldManifest = manifestMod.readManifest(payloadDir);
+  const tmp = stagingMod.stageDir(payloadBase);
+  _copyTree(sourceDir, tmp);
+  let pkgVersion = '0.0.0';
+  try { pkgVersion = String(require('../package.json').version || '0.0.0'); } catch {}
+  const newManifest = manifestMod.buildManifest(tmp, pkgVersion);
+
+  const opencodeTarget = _opencodePayloadDirFor(projectRoot, resolvedScope);
+  const opencodeManifestPrefix = _opencodeManifestPrefix(resolvedScope);
+  const opencodeTmp = path.join(stateDir, '.opencode.tmp');
+  try { fs.rmSync(opencodeTmp, { recursive: true, force: true }); } catch {}
+  try {
+  let opencodeManifest = null;
+  if (fs.existsSync(SOURCE_OPENCODE_DIR)) {
+    _copyTree(SOURCE_OPENCODE_DIR, opencodeTmp);
+    opencodeManifest = manifestMod.buildManifest(opencodeTmp, pkgVersion);
+    for (const rel of Object.keys(opencodeManifest.files)) {
+      if (rel.includes('..') || path.isAbsolute(rel)) {
+        throw new NubosPilotError('manifest-path-traversal',
+          'Opencode payload contains suspicious path', { rel });
+      }
+      newManifest.files[opencodeManifestPrefix + rel] = opencodeManifest.files[rel];
+    }
+  }
+  const diff = manifestMod.diffManifests(oldManifest, newManifest);
+
+  const backupLog = [];
+  for (const rel of diff.changed) {
+    const existing = path.join(payloadDir, rel);
+    if (!fs.existsSync(existing)) continue;
+    try {
+      const existingHash = manifestMod.fileHashSync(existing);
+      const oldHash = (oldManifest && oldManifest.files && oldManifest.files[rel]) || null;
+      if (oldHash && existingHash !== oldHash) {
+        if (!dryRun) {
+          const backedUp = backupMod.backupFile(existing);
+          backupLog.push({ rel, backedUp });
+          console.error(yellow + '  [conflict] ' + rel + ' → ' + path.basename(backedUp) + reset);
+        } else {
+          console.error(dim + 'DRY-RUN: würde sichern ' + rel + reset);
+        }
+      }
+    } catch {}
+  }
+
+  if (dryRun) {
+    const summary = { mode, dryRun: true,
+      scope: resolvedScope,
+      wouldWrite: Object.keys(newManifest.files).length,
+      wouldBackup: backupLog.length, wouldDelete: diff.stale.length,
+      wouldWriteGemini: true,
+      wouldWriteOpencodeJson: !fs.existsSync(path.join(projectRoot, 'opencode.json')),
+      stale: diff.stale, changed: diff.changed, added: diff.added };
+    process.stdout.write(JSON.stringify(summary, null, 2) + '\n');
+    try { stagingMod.cleanStaleStaging(payloadBase); } catch {}
+    try { fs.rmSync(opencodeTmp, { recursive: true, force: true }); } catch {}
+    return summary;
+  }
+
+  if (fs.existsSync(payloadDir) && fs.lstatSync(payloadDir).isSymbolicLink()) {
+    try { stagingMod.cleanStaleStaging(payloadBase); } catch {}
+    throw new NubosPilotError('target-is-symlink',
+      'Refusing to swap into a symlink target: ' + payloadDir, { payloadDir });
+  }
+
+  stagingMod.finalizeSwap(payloadBase);
+  for (const rel of diff.stale) {
+    try { fs.unlinkSync(path.join(payloadDir, rel)); } catch {}
+  }
+
+  if (opencodeManifest) {
+    const opencodeBak = path.join(stateDir, '.opencode.bak');
+    try { fs.rmSync(opencodeBak, { recursive: true, force: true }); } catch {}
+    if (fs.existsSync(opencodeTarget)) {
+      if (fs.lstatSync(opencodeTarget).isSymbolicLink()) {
+        throw new NubosPilotError('target-is-symlink',
+          'Refusing to swap into a symlink target: ' + opencodeTarget,
+          { payloadDir: opencodeTarget });
+      }
+      fs.renameSync(opencodeTarget, opencodeBak);
+    }
+    const opencodeParent = path.dirname(opencodeTarget);
+    if (fs.existsSync(opencodeParent) && fs.lstatSync(opencodeParent).isSymbolicLink()) {
+      throw new NubosPilotError('target-is-symlink',
+        'Refusing to install into a symlinked parent: ' + opencodeParent,
+        { payloadDir: opencodeParent });
+    }
+    fs.mkdirSync(opencodeParent, { recursive: true });
+    fs.renameSync(opencodeTmp, opencodeTarget);
+    try { fs.rmSync(opencodeBak, { recursive: true, force: true }); } catch {}
+    const opencodeBase = resolvedScope === 'global' ? os.homedir() : projectRoot;
+    for (const rel of diff.stale) {
+      if (rel.startsWith(opencodeManifestPrefix)) {
+        const relFs = rel.startsWith('~/')
+          ? path.join(os.homedir(), rel.slice(2))
+          : path.join(opencodeBase, rel);
+        try { fs.unlinkSync(relFs); } catch {}
+      }
+    }
+  }
+
+  _rewriteManagedMarkdown(projectRoot);
+
+  if (initConfig && initConfig.mcp && !dryRun) {
+    try {
+      const mcpWriter = require('../lib/install/mcp-writer.cjs');
+      const result = mcpWriter.writeMcpConfig({
+        runtime: initConfig.runtime,
+        scope: initConfig.scope,
+        projectRoot,
+      });
+      console.error(green + '  [mcp] nubos MCP configured → ' + result.path + reset);
+    } catch (err) {
+      console.error(yellow + '  [mcp] skipped: ' + (err && err.message) + reset);
+    }
+  }
+
+  const projectOpencodeJson = path.join(projectRoot, 'opencode.json');
+  if (!fs.existsSync(projectOpencodeJson) && fs.existsSync(OPENCODE_JSON_TEMPLATE)) {
+    const template = fs.readFileSync(OPENCODE_JSON_TEMPLATE, 'utf-8');
+    atomicWriteFileSync(projectOpencodeJson, template);
+  }
+
+  try { _repairCodexConfig(); } catch (err) {
+    console.error(yellow + '  [codex] repair skipped: ' + (err && err.message) + reset);
+  }
+  manifestMod.writeManifest(payloadDir, newManifest);
+  console.error(green + '✓ Installation abgeschlossen' + reset);
+  return { mode, dryRun: false, written: Object.keys(newManifest.files).length,
+    backedUp: backupLog.length, deleted: diff.stale.length };
+  } finally {
+    try { fs.rmSync(opencodeTmp, { recursive: true, force: true }); } catch {}
+  }
+}
+
+async function runUninstall(opts) {
+  const options = opts || {};
+  const cwd = options.cwd || process.cwd();
+  const projectRoot = options.projectRoot || cwd;
+  const stateDir = _stateDirFor(projectRoot);
+  fs.mkdirSync(stateDir, { recursive: true });
+  const lockPath = path.join(stateDir, '.install.lock');
+  return withFileLock(lockPath, () => _runUninstallLocked(projectRoot),
+    { timeoutMs: 60000 });
+}
+
+function _runUninstallLocked(projectRoot) {
+  const scope = _readExistingScope(projectRoot) || 'local';
+  const payloadDir = _payloadDirFor(projectRoot, scope);
+  const manifest = manifestMod.readManifest(payloadDir);
+  if (!manifest) {
+    console.error(dim + 'Keine Installation gefunden' + reset);
+    return { uninstalled: false };
+  }
+
+  for (const rel of Object.keys(manifest.files)) {
+    if (rel.includes('..') || path.isAbsolute(rel)) {
+      throw new NubosPilotError(
+        'manifest-path-traversal',
+        'Manifest contains suspicious path',
+        { rel },
+      );
+    }
+  }
+
+  let removed = 0;
+  for (const rel of Object.keys(manifest.files)) {
+    const abs = path.join(payloadDir, rel);
+    try { fs.unlinkSync(abs); removed++; } catch (err) {
+      if (err && err.code !== 'ENOENT') {
+        console.error(yellow + '  [uninstall] ' + rel + ' not removed: ' + err.message + reset);
+      }
+    }
+  }
+
+  try { fs.unlinkSync(path.join(payloadDir, '.manifest.json')); } catch {}
+
+  try { fs.rmdirSync(payloadDir); } catch {  }
+
+  for (const name of ['CLAUDE.md', 'AGENTS.md', 'GEMINI.md']) {
+    const p = path.join(projectRoot, name);
+    if (!fs.existsSync(p)) continue;
+    const stripped = managedBlockMod.stripBlock(fs.readFileSync(p, 'utf-8'));
+    if (!stripped || !stripped.trim()) {
+      try { fs.unlinkSync(p); } catch {}
+    } else {
+      atomicWriteFileSync(p, stripped);
+    }
+  }
+
+  const opencodeDir = _opencodePayloadDirFor(projectRoot, scope);
+  if (fs.existsSync(opencodeDir)) {
+    try { fs.rmSync(opencodeDir, { recursive: true, force: true }); } catch {}
+  }
+  const opencodeParent = path.dirname(opencodeDir);
+  try { fs.rmdirSync(opencodeParent); } catch {}
+
+  console.error(green + '✓ Uninstall abgeschlossen' + reset);
+  let leftovers = [];
+  try {
+    if (fs.existsSync(payloadDir)) {
+      leftovers = fs.readdirSync(payloadDir).filter((f) => /\.bak(\.\d+|\.orphan-)?$/.test(f));
+    }
+  } catch {}
+  if (leftovers.length) {
+    console.error(dim + '  User-Backups belassen:' + reset);
+    for (const f of leftovers) console.error(dim + '    ' + f + reset);
+  }
+  return { uninstalled: true, removed, leftoverBaks: leftovers };
+}
+
+async function main() {
+  const rawArgs = process.argv.slice(2);
+  const { flags, rest } = parseInstallFlags(rawArgs);
+  const sub = rest[0];
+  const cwd = process.cwd();
+  switch (sub) {
+    case undefined:
+      return await runInstall({ cwd, mode: detectMode(cwd), flags });
+    case '--dry-run':
+      return await runInstall({ cwd, mode: detectMode(cwd), dryRun: true, flags });
+    case 'update':
+      return await runInstall({ cwd, mode: 'update', flags });
+    case 'uninstall':
+      return await runUninstall({ cwd, args: rest.slice(1) });
+    case 'doctor': {
+      const doctor = require('./np-tools/doctor.cjs');
+      return await doctor.run(rest.slice(1), { cwd, stdout: process.stdout });
+    }
+    default:
+      process.stderr.write(
+        red + 'Unbekanntes Subcommand: ' + sub + reset + '\n',
+      );
+      process.exit(1);
+      return undefined;
+  }
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    if (err && err.code) {
+      process.stderr.write(
+        JSON.stringify({
+          error: {
+            code: err.code,
+            message: err.message,
+            details: err.details || null,
+          },
+        }) + '\n',
+      );
+    } else {
+      process.stderr.write(((err && err.stack) || String(err)) + '\n');
+    }
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  runInstall, runUninstall, detectMode, main,
+  parseInstallFlags,
+  VALID_AGENTS, VALID_SCOPES,
+  SOURCE_PAYLOAD_DIR, PAYLOAD_SUBPATH, STATE_SUBPATH,
+  _payloadDirFor, _stateDirFor,
+};

package/bin/np-tools/_commands.cjs

@@ -0,0 +1,70 @@
+const COMMANDS = [
+  { name: 'next',     category: 'Utility', description: 'Print the next actionable step' },
+  { name: 'progress', category: 'Utility', description: 'Report % complete across phases and plans' },
+  { name: 'state',    category: 'Utility', description: 'Print the current project state snapshot' },
+  { name: 'help',     category: 'Utility', description: 'List available commands' },
+  { name: 'init',     category: 'Utility', description: 'Dispatcher init payload for workflows' },
+
+  { name: 'discuss-phase',       category: 'Planning', description: 'Adaptive phase-context interview (writes CONTEXT.md)' },
+  { name: 'discuss-phase-power', category: 'Planning', description: 'Bulk gray-area question file-UI (power mode)' },
+  { name: 'research-phase',      category: 'Planning', description: 'Optional phase-level research (WebFetch + MCP; offline fallback)' },
+  { name: 'plan-phase',          category: 'Planning', description: 'Creates PLAN.md with plan-checker verification loop' },
+  { name: 'new-project',         category: 'Planning', description: 'Greenfield project init (PROJECT.md + REQUIREMENTS.md + roadmap)' },
+  { name: 'new-milestone',       category: 'Planning', description: 'Append milestone + first phase to an existing project' },
+  { name: 'plan-milestone-gaps', category: 'Planning', description: 'Create corrective phases from audit gaps' },
+  { name: 'agent-skills',        category: 'Planning', description: 'Print agent_skills config for a given subagent' },
+
+  { name: 'execute-phase',       category: 'Execution', description: 'Wave-based phase execution (emits per-task executor-spawn payloads)' },
+  { name: 'execute-plan',        category: 'Execution', description: 'Single-plan execution (sub-case of execute-phase)' },
+  { name: 'commit-task',         category: 'Execution', description: 'Atomic per-task git commit via lib/git.cjs (D-03/D-25 enforced)' },
+  { name: 'checkpoint',          category: 'Execution', description: 'Per-task crash-safety checkpoint CRUD (start/transition/touch/show)' },
+  { name: 'autonomous',          category: 'Execution', description: 'In-session gate snapshot for auto-advance loop (ADR-0001, no daemon)' },
+  { name: 'verify-work',         category: 'Execution', description: 'Two-pass goal-backward verification (D-21/D-22 VERIFICATION.md render/record)' },
+  { name: 'add-tests',           category: 'Execution', description: 'Persist VERIFICATION Pass-cases as node:test UAT (Sentinel-preserving)' },
+  { name: 'pause-work',          category: 'Execution', description: 'Stamp STATE.session.stopped_at + resume_file for explicit handoff' },
+  { name: 'resume-work',         category: 'Execution', description: 'Classify session state (resume | orphan | clean) from STATE + checkpoints' },
+
+  { name: 'undo',                category: 'Execution', description: 'Revert all task commits of a phase or plan via git revert (no history rewrite)' },
+  { name: 'undo-task',           category: 'Execution', description: 'Revert a single task commit and reset task status to pending' },
+  { name: 'reset-slice',         category: 'Execution', description: 'Restore working-tree files of the in-flight task and clear current_task (no commit)' },
+  { name: 'skip',                category: 'Execution', description: 'Mark task status skipped (lifecycle CRUD)' },
+  { name: 'park',                category: 'Execution', description: 'Mark task status parked (lifecycle CRUD)' },
+  { name: 'unpark',              category: 'Execution', description: 'Return a parked task to pending (lifecycle CRUD)' },
+
+  { name: 'doctor',              category: 'Install', description: '5-check install-integrity scan (--fix for auto-safe fixes)' },
+  { name: 'dispatch',            category: 'Install', description: 'State-router: computes next action and delegates via Skill()' },
+  { name: 'queue',               category: 'Install', description: 'Unified queue across todos/backlog/UAT/unplanned phases' },
+  { name: 'triage',              category: 'Install', description: 'Interactive per-item triage loop (promote/keep/drop)' },
+
+  { name: 'resolve-model',       category: 'Utility', description: 'Resolve agent/tier to model alias or id (Tier×Profile matrix; consulted at Task-spawn sites by workflows)' },
+
+  { name: 'metrics',             category: 'Utility', description: 'Record JSONL metrics entry (record | now | start-timestamp | end-timestamp)' },
+
+  { name: 'plan-diff',           category: 'Planning', description: 'Render two-part PLAN.md diff (semantic + git) or archive-rejected with reason' },
+
+  { name: 'ai-integration-phase', category: 'Planning', description: 'AI-SPEC generator with framework-selector + eval-planner (spawns 4 np-agents)' },
+  { name: 'ui-phase',              category: 'Planning', description: 'UI-SPEC generator with researcher + checker revision loop' },
+  { name: 'ui-review',             category: 'Review', description: '6-pillar retroactive UI audit on a completed phase' },
+  { name: 'eval-review',           category: 'Review', description: 'Retroactive eval-coverage audit on a completed phase' },
+
+  { name: 'askuser',         category: 'Utility', description: 'Capability-layer prompt wrapper (reads spec JSON, returns chosen label)' },
+  { name: 'commit',          category: 'Utility', description: 'Atomic git commit wrapper with gitignore-guard (D-21)' },
+  { name: 'config-get',      category: 'Utility', description: 'Read value from .nubos-pilot/config.json by dotted key path' },
+  { name: 'generate-slug',   category: 'Utility', description: 'Slugify text via lib/phase.cjs.phaseSlug (used by add-todo, add-backlog, thread)' },
+  { name: 'phase',           category: 'Utility', description: 'Phase utilities (next-decimal <base> — used by add-backlog 999.x)' },
+  { name: 'stats',           category: 'Utility', description: 'Aggregated project stats (roadmap + STATE + git + metrics JSON shape)' },
+
+  { name: 'code-review',      category: 'Review',  description: 'Source-file review via np-code-reviewer (depth quick/standard/deep) — writes REVIEW.md sidecar' },
+  { name: 'code-review-fix',  category: 'Review',  description: 'Auto-fix REVIEW.md findings via np-code-fixer (atomic commit per finding)' },
+  { name: 'review',           category: 'Review',  description: 'Cross-AI peer review via 7-CLI fan-out (gemini/claude/codex/coderabbit/opencode/qwen/cursor)' },
+  { name: 'secure-phase',     category: 'Review',  description: 'Threat-mitigation audit via np-security-auditor against PLAN.md threat_model' },
+  { name: 'validate-phase',   category: 'Review',  description: 'Nyquist validation gap-fill via np-nyquist-auditor' },
+  { name: 'add-todo',         category: 'Capture', description: 'Capture a pending todo to .nubos-pilot/todos/pending/ + increment STATE count' },
+  { name: 'note',             category: 'Capture', description: 'Capture a free-form note (project default, --global writes to ~/.nubos-pilot/notes/)' },
+  { name: 'add-backlog',      category: 'Capture', description: 'Append backlog item 999.x to ROADMAP.md + scaffold phase dir' },
+  { name: 'thread',           category: 'Utility', description: 'Cross-session thread CRUD (create/resume under .nubos-pilot/threads/)' },
+  { name: 'session-report',   category: 'Utility', description: 'Generate session report from metrics since .last-session pointer' },
+  { name: 'cleanup',          category: 'Utility', description: 'Archive completed milestones to .nubos-pilot/archive/v<X.Y>/ + collapse ROADMAP <details> block' },
+];
+
+module.exports = { COMMANDS };