nubos-pilot 0.6.0 → 0.6.2

package/agents/np-sc-extractor.md

@@ -0,0 +1,85 @@
+---
+name: np-sc-extractor
+description: Derives observable Success Criteria (SC-N) for a milestone from its goal, requirements, and captured decisions; persists them to roadmap.yaml via update-phase-meta. Spawned by /np:discuss-phase after the interview, before plan-phase.
+tier: haiku
+tools: Read, Bash, Grep, Glob
+color: "#10B981"
+---
+
+<role>
+You are the nubos-pilot Success-Criteria extractor. Your sole job: turn a milestone's vision (goal + requirements + interview decisions) into a short, observable, testable list of Success Criteria — and persist that list to `roadmap.yaml` via the `update-phase-meta` CLI helper.
+
+You do NOT interview the user. You do NOT edit code. You do NOT re-open scope debates. You read the context that `/np:discuss-phase` has just produced and translate it into SCs.
+</role>
+
+<input>
+- `milestone`, `milestone_id`, `milestone_name`, `milestone_dir`
+- `goal`: the milestone's goal string (from `roadmap.yaml`)
+- `requirements`: array of REQ-IDs in scope (from `roadmap.yaml`)
+- `context_path`: path to `<milestone_dir>/<milestone_id>-CONTEXT.md` (just written by the workflow)
+- `requirements_path`: path to `.nubos-pilot/REQUIREMENTS.md` (or `.planning/REQUIREMENTS.md`)
+- `existing_success_criteria`: current `success_criteria[]` from roadmap.yaml (may be empty)
+</input>
+
+<required_reading>
+1. `context_path` — the freshly captured decisions (WHAT the milestone locks in).
+2. `requirements_path` — filtered to the REQ-IDs in input; extract the observable behavior hints.
+3. Existing `M<NNN>-ROADMAP.md` and `M<NNN>-META.json` under `milestone_dir` IF they exist — they may already carry SCs a human drafted; prefer those verbatim over re-inventing.
+</required_reading>
+
+<extraction_rules>
+1. **Derive, don't invent.** Every SC must trace back to a concrete line in CONTEXT.md, REQUIREMENTS.md, or existing ROADMAP.md. If there is no basis, emit fewer SCs — do not invent requirements.
+2. **Observable.** Each SC must be checkable by a test or demo: "X happens when Y" / "metric Z stays under T". Avoid opinions ("code is clean", "UX feels fast").
+3. **Numbered.** IDs are strictly `SC-1`, `SC-2`, … (no gaps). Start at `SC-1` even if a different ID scheme appears in prose.
+4. **Reuse existing.** If `existing_success_criteria` is non-empty AND the content still matches the goal+requirements, return it unchanged (1:1). Only add/remove when the context materially disagrees.
+5. **Prefer sidecar source of truth.** If `M<NNN>-ROADMAP.md` or `M<NNN>-META.json` list SCs and `roadmap.yaml` does not, migrate them verbatim (fix only ID numbering).
+6. **Between 3 and 15 SCs.** Fewer than 3 = probably missing something; more than 15 = too granular (split the milestone in that case — but do not split here; instead emit a warning in your final message).
+</extraction_rules>
+
+<execution_flow>
+
+<step name="load">
+Read all `required_reading` files. Missing files: log and continue (e.g. META.json may not exist yet).
+</step>
+
+<step name="draft">
+Produce the SC list as a JSON array of `{id, text}` objects. `id` MUST match `/^SC-\d+$/`. `text` is one sentence, observable, testable.
+</step>
+
+<step name="persist">
+Call the helper:
+
+```bash
+echo '<JSON PATCH>' | node .nubos-pilot/bin/np-tools.cjs update-phase-meta <MILESTONE_NUMBER> --stdin
+```
+
+Where `<JSON PATCH>` is `{"success_criteria": [...your array...]}`. On success the helper returns `{"ok": true, ...}` — any other output is a failure and must be reported.
+</step>
+
+<step name="report">
+Emit a short summary to stdout:
+
+```
+np-sc-extractor: <N> success criteria persisted to roadmap.yaml (M<NNN>)
+  SC-1: <short text>
+  SC-2: <short text>
+  ...
+```
+
+If you had to WARN (>15 SCs, conflicting sources, no basis found), prepend `WARN:` lines before the summary. Never fail silently.
+</step>
+
+</execution_flow>
+
+<scope_guardrail>
+**Do:**
+- Read CONTEXT.md, REQUIREMENTS.md, existing sidecars.
+- Persist via `update-phase-meta --stdin`.
+- Reuse existing SCs verbatim when they still fit.
+
+**Don't:**
+- Ask the user questions (you are non-interactive).
+- Edit CONTEXT.md, ROADMAP.md, META.json, or any implementation file.
+- Invent SCs that have no basis in inputs.
+- Emit more than 15 SCs.
+</scope_guardrail>

package/bin/install.js

@@ -536,6 +536,21 @@ async function _runInstallLocked(ctx) {
     console.error(yellow + '  [codex] repair skipped: ' + (err && err.message) + reset);
   }
   manifestMod.writeManifest(payloadDir, newManifest);
+  if (selectedRuntimesEarly.includes('claude')) {
+    try {
+      const claudeHooks = require('../lib/install/claude-hooks.cjs');
+      const res = claudeHooks.installClaudeHooks({
+        projectRoot, scope: resolvedScope, which: 'both', force: false,
+      });
+      console.error(dim + '  [claude-hooks] statusline: ' + res.results.statusline.action
+        + ', ctx-monitor: ' + res.results.ctxMonitor.action + reset);
+      if (res.results.statusline.action === 'skipped-existing') {
+        console.error(yellow + '  [claude-hooks] foreign statusLine preserved — re-run `install-hooks --force` to overwrite' + reset);
+      }
+    } catch (err) {
+      console.error(yellow + '  [claude-hooks] skipped: ' + (err && err.message) + reset);
+    }
+  }
   console.error(green + '✓ Installation abgeschlossen' + reset);
   return { mode, dryRun: false, written: Object.keys(newManifest.files).length,
     backedUp: backupLog.length, deleted: diff.stale.length };
@@ -683,6 +698,10 @@ async function main() {
       const doctor = require('./np-tools/doctor.cjs');
       return await doctor.run(rest.slice(1), { cwd, stdout: process.stdout });
     }
+    case 'install-hooks':
+      return await runInstallHooks({ cwd, args: rest.slice(1) });
+    case 'uninstall-hooks':
+      return await runUninstallHooks({ cwd, args: rest.slice(1) });
     default:
       process.stderr.write(
         red + 'Unbekanntes Subcommand: ' + sub + reset + '\n',
@@ -692,6 +711,70 @@ async function main() {
   }
 }
 
+function _parseHookFlags(args) {
+  const flags = { scope: null, which: 'both', force: false, dryRun: false };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--scope' || a === '-s') { flags.scope = args[++i] || null; continue; }
+    if (a.startsWith('--scope=')) { flags.scope = a.slice('--scope='.length); continue; }
+    if (a === '--statusline-only') { flags.which = 'statusline'; continue; }
+    if (a === '--ctx-monitor-only') { flags.which = 'ctx-monitor'; continue; }
+    if (a === '--force' || a === '-f') { flags.force = true; continue; }
+    if (a === '--dry-run') { flags.dryRun = true; continue; }
+  }
+  if (flags.scope && !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;
+}
+
+async function runInstallHooks(opts) {
+  const o = opts || {};
+  const projectRoot = o.projectRoot || o.cwd || process.cwd();
+  const flags = _parseHookFlags(o.args || []);
+  const scope = flags.scope || _readExistingScope(projectRoot) || 'local';
+  const claudeHooks = require('../lib/install/claude-hooks.cjs');
+  const res = claudeHooks.installClaudeHooks({
+    projectRoot, scope, which: flags.which, force: flags.force, dryRun: flags.dryRun,
+  });
+  if (res.dryRun) {
+    process.stdout.write(JSON.stringify({ dryRun: true, path: res.path, results: res.results }, null, 2) + '\n');
+    return res;
+  }
+  console.error(green + '✓ Claude Code hooks geschrieben → ' + res.path + reset);
+  if (res.results.statusline) {
+    console.error(dim + '  statusline: ' + res.results.statusline.action
+      + (res.results.statusline.existingCommand ? ' (existing: ' + res.results.statusline.existingCommand + ')' : '')
+      + reset);
+  }
+  if (res.results.ctxMonitor) {
+    console.error(dim + '  ctx-monitor: ' + res.results.ctxMonitor.action + reset);
+  }
+  if (res.results.statusline && res.results.statusline.action === 'skipped-existing') {
+    console.error(yellow + '  [statusline] existing non-nubos statusLine preserved. Pass --force to overwrite.' + reset);
+  }
+  return res;
+}
+
+async function runUninstallHooks(opts) {
+  const o = opts || {};
+  const projectRoot = o.projectRoot || o.cwd || process.cwd();
+  const flags = _parseHookFlags(o.args || []);
+  const scope = flags.scope || _readExistingScope(projectRoot) || 'local';
+  const claudeHooks = require('../lib/install/claude-hooks.cjs');
+  const res = claudeHooks.uninstallClaudeHooks({ projectRoot, scope, dryRun: flags.dryRun });
+  if (res.dryRun) {
+    process.stdout.write(JSON.stringify({ dryRun: true, path: res.path, results: res.results }, null, 2) + '\n');
+    return res;
+  }
+  console.error(green + '✓ Claude Code hooks entfernt ← ' + res.path + reset);
+  console.error(dim + '  statusline: ' + res.results.statusline.action + reset);
+  console.error(dim + '  ctx-monitor: ' + res.results.ctxMonitor.action + reset);
+  return res;
+}
+
 if (require.main === module) {
   main().catch((err) => {
     if (err && err.code) {

package/bin/np-tools/_commands.cjs

@@ -50,6 +50,7 @@ const COMMANDS = [
   { name: 'stats',           category: 'Utility', description: 'Aggregated project stats (roadmap + STATE + git + metrics JSON shape)' },
   { name: 'detect-runtime',  category: 'Utility', description: 'Print detected runtime id (claude, codex, gemini, …) — reads config.json ∨ env ∨ default' },
   { name: 'template-path',   category: 'Utility', description: 'Print absolute path to a package-shipped template by name (e.g. VALIDATION, milestone/CONTEXT)' },
+  { name: 'update-phase-meta', category: 'Planning', description: 'Update roadmap.yaml phase fields (name/goal/requirements/success_criteria) via JSON patch' },
 
   { 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' },

package/bin/np-tools/discuss-phase.test.cjs

@@ -83,7 +83,7 @@ test('DP-1: run(["3"]) on valid milestone returns JSON payload with expected sha
   }
 });
 
-test('DP-1b: CLAUDECODE=1 sets text_mode=true with runtime source', () => {
+test('DP-1b: CLAUDECODE=1 no longer flips text_mode (Claude Code uses AskUserQuestion)', () => {
   const restore = _clearClaudeEnv();
   try {
     process.env.CLAUDECODE = '1';
@@ -92,8 +92,8 @@ test('DP-1b: CLAUDECODE=1 sets text_mode=true with runtime source', () => {
     const cap = _captureStdout();
     subcmd.run(['3'], { cwd: sandbox, stdout: cap.stub });
     const payload = JSON.parse(cap.get().trim());
-    assert.equal(payload.text_mode, true);
-    assert.equal(payload.text_mode_source, 'runtime');
+    assert.equal(payload.text_mode, false);
+    assert.equal(payload.text_mode_source, 'default');
   } finally {
     restore();
   }

package/bin/np-tools/text-mode.test.cjs

@@ -56,7 +56,7 @@ test('text-mode CLI: default without config and without Claude env prints "false
   }
 });
 
-test('text-mode CLI: CLAUDECODE=1 prints "true"', () => {
+test('text-mode CLI: CLAUDECODE=1 no longer prints "true" (AskUserQuestion path)', () => {
   const restore = _clearClaudeEnv();
   try {
     process.env.CLAUDECODE = '1';
@@ -65,7 +65,7 @@ test('text-mode CLI: CLAUDECODE=1 prints "true"', () => {
       const io = _captureIO();
       const rc = subcmd.run([], { cwd: dir, stdout: io.stdout, stderr: io.stderr });
       assert.equal(rc, 0);
-      assert.equal(io.stdoutText().trim(), 'true');
+      assert.equal(io.stdoutText().trim(), 'false');
     } finally {
       fs.rmSync(dir, { recursive: true, force: true });
     }
@@ -74,18 +74,21 @@ test('text-mode CLI: CLAUDECODE=1 prints "true"', () => {
   }
 });
 
-test('text-mode CLI: --json emits detail object', () => {
+test('text-mode CLI: --json emits detail object with config source', () => {
   const restore = _clearClaudeEnv();
   try {
-    process.env.CLAUDECODE = '1';
     const dir = _mkSandbox();
     try {
+      fs.writeFileSync(
+        path.join(dir, '.nubos-pilot', 'config.json'),
+        JSON.stringify({ workflow: { text_mode: true } }),
+      );
       const io = _captureIO();
       const rc = subcmd.run(['--json'], { cwd: dir, stdout: io.stdout, stderr: io.stderr });
       assert.equal(rc, 0);
       const payload = JSON.parse(io.stdoutText().trim());
       assert.equal(payload.enabled, true);
-      assert.equal(payload.source, 'runtime');
+      assert.equal(payload.source, 'config');
     } finally {
       fs.rmSync(dir, { recursive: true, force: true });
     }
@@ -94,7 +97,7 @@ test('text-mode CLI: --json emits detail object', () => {
   }
 });
 
-test('text-mode CLI: config workflow.text_mode=false wins over CLAUDECODE', () => {
+test('text-mode CLI: config workflow.text_mode=false stays false even with CLAUDECODE', () => {
   const restore = _clearClaudeEnv();
   try {
     process.env.CLAUDECODE = '1';

package/bin/np-tools/update-phase-meta.cjs

@@ -0,0 +1,77 @@
+'use strict';
+
+const { NubosPilotError } = require('../../lib/core.cjs');
+const roadmap = require('../../lib/roadmap.cjs');
+
+function _parseArgs(args) {
+  const out = { milestone: null, json: null, stdin: false };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (!a.startsWith('-')) {
+      if (out.milestone == null) { out.milestone = a; continue; }
+      continue;
+    }
+    if (a === '--json' || a === '-j') { out.json = args[++i] || null; continue; }
+    if (a === '--stdin') { out.stdin = true; continue; }
+  }
+  return out;
+}
+
+function _readStdinSync() {
+  const fs = require('node:fs');
+  try {
+    return fs.readFileSync(0, 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+function _validateMilestone(raw) {
+  if (raw == null) {
+    throw new NubosPilotError('update-phase-meta-missing-milestone',
+      'milestone number required (e.g. M002 or 2)', {});
+  }
+  const s = String(raw).trim();
+  const m = s.match(/^M?(\d+(?:\.\d+)?)$/i);
+  if (!m) {
+    throw new NubosPilotError('update-phase-meta-invalid-milestone',
+      'milestone must be M<NNN> or <number>', { milestone: raw });
+  }
+  return m[1];
+}
+
+function run(args, opts) {
+  const o = opts || {};
+  const cwd = o.cwd || process.cwd();
+  const stdout = o.stdout || process.stdout;
+  const readStdin = typeof o.readStdin === 'function' ? o.readStdin : _readStdinSync;
+  const stdinIsTty = o.stdinIsTty != null ? !!o.stdinIsTty : !!process.stdin.isTTY;
+  const parsed = _parseArgs(args || []);
+  const mNum = _validateMilestone(parsed.milestone);
+
+  let rawJson = parsed.json;
+  if (!rawJson && parsed.stdin) rawJson = readStdin();
+  if (!rawJson && !stdinIsTty) rawJson = readStdin();
+  if (!rawJson) {
+    throw new NubosPilotError('update-phase-meta-missing-json',
+      'JSON patch required (via --json, --stdin, or piped stdin)', {});
+  }
+
+  let patch;
+  try {
+    patch = JSON.parse(rawJson);
+  } catch (err) {
+    throw new NubosPilotError('update-phase-meta-invalid-json',
+      'invalid JSON patch: ' + err.message, { cause: err.message });
+  }
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
+    throw new NubosPilotError('update-phase-meta-invalid-json',
+      'JSON patch must be an object', {});
+  }
+
+  const result = roadmap.updatePhase(mNum, patch, cwd);
+  stdout.write(JSON.stringify({ ok: true, milestone: mNum, result }, null, 2) + '\n');
+  return 0;
+}
+
+module.exports = { run, _parseArgs, _validateMilestone };

package/bin/np-tools/update-phase-meta.test.cjs

@@ -0,0 +1,132 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const mod = require('./update-phase-meta.cjs');
+const roadmap = require('../../lib/roadmap.cjs');
+
+const SEED = [
+  'schema_version: 1',
+  'milestones:',
+  '  - id: M001',
+  '    number: 1',
+  '    name: First',
+  '    goal: hello',
+  '    status: pending',
+  '    requirements: []',
+  '    success_criteria: []',
+  '    slices: []',
+  '',
+].join('\n');
+
+function mkSandbox() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-upm-'));
+  fs.mkdirSync(path.join(dir, '.nubos-pilot'));
+  fs.writeFileSync(path.join(dir, '.nubos-pilot', 'roadmap.yaml'), SEED);
+  return dir;
+}
+
+function captureStdout() {
+  const chunks = [];
+  return {
+    stream: { write: (c) => { chunks.push(c); } },
+    read: () => chunks.join(''),
+  };
+}
+
+test('UPM-1: _validateMilestone accepts M002, 2, and 2.1', () => {
+  assert.equal(mod._validateMilestone('M002'), '002');
+  assert.equal(mod._validateMilestone('2'), '2');
+  assert.equal(mod._validateMilestone('2.1'), '2.1');
+});
+
+test('UPM-2: _validateMilestone rejects garbage', () => {
+  assert.throws(
+    () => mod._validateMilestone('bogus'),
+    (err) => err.code === 'update-phase-meta-invalid-milestone',
+  );
+});
+
+test('UPM-3: run() writes SCs via --json flag', () => {
+  const dir = mkSandbox();
+  try {
+    const cap = captureStdout();
+    const rc = mod.run(['1', '--json', JSON.stringify({
+      success_criteria: [{ id: 'SC-1', text: 'log in works' }],
+    })], { cwd: dir, stdout: cap.stream, stdinIsTty: true });
+    assert.equal(rc, 0);
+    const p = roadmap.getPhase(1, dir);
+    assert.equal(p.success_criteria.length, 1);
+    const out = JSON.parse(cap.read());
+    assert.equal(out.ok, true);
+    assert.deepEqual(out.result.fields_updated, ['success_criteria']);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('UPM-4: invalid JSON via --json throws update-phase-meta-invalid-json', () => {
+  const dir = mkSandbox();
+  try {
+    const cap = captureStdout();
+    assert.throws(
+      () => mod.run(['1', '--json', '{broken'], { cwd: dir, stdout: cap.stream, stdinIsTty: true }),
+      (err) => err.code === 'update-phase-meta-invalid-json',
+    );
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('UPM-5: JSON-array (not object) patch rejected', () => {
+  const dir = mkSandbox();
+  try {
+    assert.throws(
+      () => mod.run(['1', '--json', '[]'], { cwd: dir, stdout: captureStdout().stream, stdinIsTty: true }),
+      (err) => err.code === 'update-phase-meta-invalid-json',
+    );
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('UPM-6: missing JSON throws update-phase-meta-missing-json', () => {
+  const dir = mkSandbox();
+  try {
+    assert.throws(
+      () => mod.run(['1'], { cwd: dir, stdout: captureStdout().stream, stdinIsTty: true }),
+      (err) => err.code === 'update-phase-meta-missing-json',
+    );
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('UPM-7: missing milestone arg throws update-phase-meta-missing-milestone', () => {
+  assert.throws(
+    () => mod.run(['--json', '{"goal":"x"}'], { cwd: process.cwd(), stdout: captureStdout().stream }),
+    (err) => err.code === 'update-phase-meta-missing-milestone',
+  );
+});
+
+test('UPM-8: run() reads from piped stdin when stdinIsTty false', () => {
+  const dir = mkSandbox();
+  try {
+    const cap = captureStdout();
+    const rc = mod.run(['1'], {
+      cwd: dir,
+      stdout: cap.stream,
+      stdinIsTty: false,
+      readStdin: () => JSON.stringify({ requirements: ['REQ-42'] }),
+    });
+    assert.equal(rc, 0);
+    const p = roadmap.getPhase(1, dir);
+    assert.deepEqual(p.requirements, ['REQ-42']);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

package/lib/agents.test.cjs

@@ -225,6 +225,7 @@ const NP_AGENTS = [
   { file: 'np-researcher', expected_tier: 'sonnet' },
   { file: 'np-codebase-documenter', expected_tier: 'sonnet' },
   { file: 'np-nyquist-auditor', expected_tier: 'haiku' },
+  { file: 'np-sc-extractor', expected_tier: 'haiku' },
 ];
 
 for (let i = 0; i < NP_AGENTS.length; i += 1) {

package/lib/install/claude-hooks.cjs

@@ -0,0 +1,195 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const { atomicWriteFileSync, NubosPilotError } = require('../core.cjs');
+
+const STATUSLINE_REL = '.claude/nubos-pilot/hooks/np-statusline.js';
+const CTX_MONITOR_REL = '.claude/nubos-pilot/hooks/np-ctx-monitor.js';
+const NP_STATUSLINE_MARKER = 'np-statusline.js';
+const NP_CTX_MONITOR_MARKER = 'np-ctx-monitor.js';
+
+function _settingsPath(scope, projectRoot) {
+  if (scope === 'global') return path.join(os.homedir(), '.claude', 'settings.json');
+  return path.join(projectRoot, '.claude', 'settings.local.json');
+}
+
+function _readJsonSafe(p) {
+  if (!fs.existsSync(p)) return {};
+  let raw;
+  try { raw = fs.readFileSync(p, 'utf-8'); } catch { return {}; }
+  try { return JSON.parse(raw); } catch (err) {
+    throw new NubosPilotError(
+      'claude-settings-invalid-json',
+      'Cannot parse Claude settings: ' + p + ' — ' + err.message,
+      { path: p },
+    );
+  }
+}
+
+function _hookCommand(rel, scope, projectRoot) {
+  if (scope === 'global') {
+    return 'node "' + path.join('$HOME', rel) + '"';
+  }
+  return 'node "' + path.join(projectRoot, rel) + '"';
+}
+
+function _containsNpHook(entry, marker) {
+  if (!entry || typeof entry !== 'object') return false;
+  const hooks = Array.isArray(entry.hooks) ? entry.hooks : [];
+  for (const h of hooks) {
+    if (h && typeof h.command === 'string' && h.command.includes(marker)) return true;
+  }
+  return false;
+}
+
+function _installStatusLine(settings, cmd, force) {
+  const existing = settings.statusLine;
+  if (existing && typeof existing === 'object' && existing.command) {
+    if (String(existing.command).includes(NP_STATUSLINE_MARKER)) {
+      settings.statusLine = { type: 'command', command: cmd };
+      return { action: 'updated', existed: true };
+    }
+    if (!force) {
+      return { action: 'skipped-existing', existed: true, existingCommand: existing.command };
+    }
+    settings.statusLine = { type: 'command', command: cmd };
+    return { action: 'overwrote', existed: true };
+  }
+  settings.statusLine = { type: 'command', command: cmd };
+  return { action: 'installed', existed: false };
+}
+
+function _installPostToolUse(settings, cmd) {
+  if (!settings.hooks || typeof settings.hooks !== 'object') settings.hooks = {};
+  if (!Array.isArray(settings.hooks.PostToolUse)) settings.hooks.PostToolUse = [];
+  const list = settings.hooks.PostToolUse;
+  for (const entry of list) {
+    if (_containsNpHook(entry, NP_CTX_MONITOR_MARKER)) {
+      const hooks = Array.isArray(entry.hooks) ? entry.hooks : [];
+      for (const h of hooks) {
+        if (h && typeof h.command === 'string' && h.command.includes(NP_CTX_MONITOR_MARKER)) {
+          h.command = cmd;
+          h.type = 'command';
+        }
+      }
+      return { action: 'updated' };
+    }
+  }
+  list.push({
+    matcher: '.*',
+    hooks: [{ type: 'command', command: cmd }],
+  });
+  return { action: 'installed' };
+}
+
+function _removeStatusLine(settings) {
+  const existing = settings.statusLine;
+  if (existing && typeof existing === 'object'
+      && typeof existing.command === 'string'
+      && existing.command.includes(NP_STATUSLINE_MARKER)) {
+    delete settings.statusLine;
+    return { action: 'removed' };
+  }
+  return { action: 'not-ours' };
+}
+
+function _removePostToolUse(settings) {
+  if (!settings.hooks || !Array.isArray(settings.hooks.PostToolUse)) return { action: 'absent' };
+  const filtered = [];
+  for (const entry of settings.hooks.PostToolUse) {
+    if (_containsNpHook(entry, NP_CTX_MONITOR_MARKER)) {
+      const hooks = Array.isArray(entry.hooks) ? entry.hooks : [];
+      const keptHooks = hooks.filter((h) => !(h && typeof h.command === 'string' && h.command.includes(NP_CTX_MONITOR_MARKER)));
+      if (keptHooks.length > 0) {
+        filtered.push(Object.assign({}, entry, { hooks: keptHooks }));
+      }
+      continue;
+    }
+    filtered.push(entry);
+  }
+  settings.hooks.PostToolUse = filtered;
+  if (filtered.length === 0) delete settings.hooks.PostToolUse;
+  if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+  return { action: 'removed' };
+}
+
+function installClaudeHooks(opts) {
+  const o = opts || {};
+  const projectRoot = o.projectRoot || process.cwd();
+  const scope = o.scope === 'global' ? 'global' : 'local';
+  const force = !!o.force;
+  const which = o.which || 'both';
+  const settingsPath = _settingsPath(scope, projectRoot);
+
+  const statuslineCmd = _hookCommand(STATUSLINE_REL, scope, projectRoot);
+  const ctxMonitorCmd = _hookCommand(CTX_MONITOR_REL, scope, projectRoot);
+
+  const statuslineAbs = path.join(scope === 'global' ? os.homedir() : projectRoot, STATUSLINE_REL);
+  const ctxMonitorAbs = path.join(scope === 'global' ? os.homedir() : projectRoot, CTX_MONITOR_REL);
+
+  if (which === 'statusline' || which === 'both') {
+    if (!fs.existsSync(statuslineAbs)) {
+      throw new NubosPilotError(
+        'claude-hooks-script-missing',
+        'Statusline hook script not found: ' + statuslineAbs + '. Run `npx nubos-pilot` install first.',
+        { script: statuslineAbs },
+      );
+    }
+  }
+  if (which === 'ctx-monitor' || which === 'both') {
+    if (!fs.existsSync(ctxMonitorAbs)) {
+      throw new NubosPilotError(
+        'claude-hooks-script-missing',
+        'Ctx-monitor hook script not found: ' + ctxMonitorAbs,
+        { script: ctxMonitorAbs },
+      );
+    }
+  }
+
+  const settings = _readJsonSafe(settingsPath);
+  const results = {};
+
+  if (which === 'statusline' || which === 'both') {
+    results.statusline = _installStatusLine(settings, statuslineCmd, force);
+  }
+  if (which === 'ctx-monitor' || which === 'both') {
+    results.ctxMonitor = _installPostToolUse(settings, ctxMonitorCmd);
+  }
+
+  if (o.dryRun) return { dryRun: true, path: settingsPath, results, settings };
+
+  fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+  atomicWriteFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  return { dryRun: false, path: settingsPath, results };
+}
+
+function uninstallClaudeHooks(opts) {
+  const o = opts || {};
+  const projectRoot = o.projectRoot || process.cwd();
+  const scope = o.scope === 'global' ? 'global' : 'local';
+  const settingsPath = _settingsPath(scope, projectRoot);
+  if (!fs.existsSync(settingsPath)) return { path: settingsPath, results: { statusline: { action: 'absent' }, ctxMonitor: { action: 'absent' } } };
+
+  const settings = _readJsonSafe(settingsPath);
+  const results = {
+    statusline: _removeStatusLine(settings),
+    ctxMonitor: _removePostToolUse(settings),
+  };
+  if (o.dryRun) return { dryRun: true, path: settingsPath, results, settings };
+  atomicWriteFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  return { dryRun: false, path: settingsPath, results };
+}
+
+module.exports = {
+  installClaudeHooks,
+  uninstallClaudeHooks,
+  STATUSLINE_REL,
+  CTX_MONITOR_REL,
+  NP_STATUSLINE_MARKER,
+  NP_CTX_MONITOR_MARKER,
+  _settingsPath,
+  _hookCommand,
+};