nubos-pilot 1.2.1 → 1.2.3

package/lib/codebase-graph.test.cjs

@@ -0,0 +1,174 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+
+const g = require('./codebase-graph.cjs');
+
+function fact(id, directory, files, extra) {
+  const source_paths = files.map((f) => f.path);
+  return Object.assign({
+    id,
+    name: directory || 'root',
+    directory: directory || '',
+    primary_language: 'javascript',
+    language_distribution: { javascript: files.length },
+    file_count: files.length,
+    source_paths,
+    symbols: [],
+    internal_deps: [],
+    external_deps: [],
+    files,
+  }, extra || {});
+}
+
+test('CG-1: buildModuleGraph creates a node per fact', () => {
+  const facts = [
+    fact('src-auth', 'src/auth', [{ path: 'src/auth/login.js', language: 'javascript', symbols: [], deps: [] }]),
+    fact('src-db', 'src/db', [{ path: 'src/db/index.js', language: 'javascript', symbols: [], deps: [] }]),
+  ];
+  const graph = g.buildModuleGraph(facts);
+  assert.equal(graph.module_count, 2);
+  assert.deepEqual(graph.nodes.map((n) => n.id), ['src-auth', 'src-db']);
+});
+
+test('CG-2: relative import resolves to a cross-module edge', () => {
+  const facts = [
+    fact('src-auth', 'src/auth', [
+      { path: 'src/auth/login.js', language: 'javascript', symbols: [], deps: ['../db', 'bcrypt'] },
+    ]),
+    fact('src-db', 'src/db', [
+      { path: 'src/db/index.js', language: 'javascript', symbols: [], deps: [] },
+    ]),
+  ];
+  const graph = g.buildModuleGraph(facts);
+  assert.equal(graph.edge_count, 1);
+  assert.deepEqual(graph.edges[0], { from: 'src-auth', to: 'src-db', weight: 1 });
+});
+
+test('CG-3: external (non-relative) deps never become edges', () => {
+  const facts = [
+    fact('src-auth', 'src/auth', [
+      { path: 'src/auth/login.js', language: 'javascript', symbols: [], deps: ['bcrypt', 'node:fs'] },
+    ]),
+  ];
+  const graph = g.buildModuleGraph(facts);
+  assert.equal(graph.edge_count, 0);
+});
+
+test('CG-4: same-module relative import is not a self-edge', () => {
+  const facts = [
+    fact('src-auth', 'src/auth', [
+      { path: 'src/auth/login.js', language: 'javascript', symbols: [], deps: ['./session'] },
+      { path: 'src/auth/session.js', language: 'javascript', symbols: [], deps: [] },
+    ]),
+  ];
+  const graph = g.buildModuleGraph(facts);
+  assert.equal(graph.edge_count, 0);
+});
+
+test('CG-5: repeated imports raise edge weight', () => {
+  const facts = [
+    fact('a', 'a', [
+      { path: 'a/one.js', language: 'javascript', symbols: [], deps: ['../b'] },
+      { path: 'a/two.js', language: 'javascript', symbols: [], deps: ['../b/helper'] },
+    ]),
+    fact('b', 'b', [
+      { path: 'b/index.js', language: 'javascript', symbols: [], deps: [] },
+      { path: 'b/helper.js', language: 'javascript', symbols: [], deps: [] },
+    ]),
+  ];
+  const graph = g.buildModuleGraph(facts);
+  assert.equal(graph.edges.length, 1);
+  assert.equal(graph.edges[0].weight, 2);
+});
+
+test('CG-6: unresolved internal-looking deps are counted, not edged', () => {
+  const facts = [
+    fact('a', 'a', [
+      { path: 'a/one.js', language: 'javascript', symbols: [], deps: ['../nonexistent'] },
+    ]),
+  ];
+  const graph = g.buildModuleGraph(facts);
+  assert.equal(graph.edge_count, 0);
+  assert.equal(graph.metrics.unresolved_internal_deps, 1);
+});
+
+test('CG-7: Tarjan detects a 2-module cycle', () => {
+  const facts = [
+    fact('a', 'a', [{ path: 'a/x.js', language: 'javascript', symbols: [], deps: ['../b'] }]),
+    fact('b', 'b', [{ path: 'b/index.js', language: 'javascript', symbols: [], deps: ['../a'] }]),
+  ];
+  const graph = g.buildModuleGraph(facts);
+  assert.equal(graph.cycles.length, 1);
+  assert.deepEqual(graph.cycles[0], ['a', 'b']);
+});
+
+test('CG-8: acyclic graph reports no cycles', () => {
+  const facts = [
+    fact('a', 'a', [{ path: 'a/x.js', language: 'javascript', symbols: [], deps: ['../b'] }]),
+    fact('b', 'b', [{ path: 'b/index.js', language: 'javascript', symbols: [], deps: ['../c'] }]),
+    fact('c', 'c', [{ path: 'c/index.js', language: 'javascript', symbols: [], deps: [] }]),
+  ];
+  const graph = g.buildModuleGraph(facts);
+  assert.equal(graph.cycles.length, 0);
+});
+
+test('CG-9: transitive dependents (impact) walk the reverse graph', () => {
+  const facts = [
+    fact('a', 'a', [{ path: 'a/x.js', language: 'javascript', symbols: [], deps: ['../b'] }]),
+    fact('b', 'b', [{ path: 'b/index.js', language: 'javascript', symbols: [], deps: ['../c'] }]),
+    fact('c', 'c', [{ path: 'c/index.js', language: 'javascript', symbols: [], deps: [] }]),
+  ];
+  const graph = g.buildModuleGraph(facts);
+  assert.deepEqual(g.transitiveDependents(graph, 'c'), ['a', 'b']);
+  assert.deepEqual(g.directDependents(graph, 'c'), ['b']);
+  assert.deepEqual(g.transitiveDependencies(graph, 'a'), ['b', 'c']);
+  assert.deepEqual(g.directDependencies(graph, 'a'), ['b']);
+});
+
+test('CG-10: deterministic clustering groups a connected component together', () => {
+  const facts = [
+    fact('a', 'a', [{ path: 'a/x.js', language: 'javascript', symbols: [], deps: ['../b'] }]),
+    fact('b', 'b', [{ path: 'b/index.js', language: 'javascript', symbols: [], deps: ['../a'] }]),
+    fact('lonely', 'lonely', [{ path: 'lonely/z.js', language: 'javascript', symbols: [], deps: [] }]),
+  ];
+  const graph = g.buildModuleGraph(facts);
+  const first = g.buildModuleGraph(facts);
+  assert.deepEqual(graph.clusters, first.clusters);
+  const clusterAB = graph.clusters.find((c) => c.members.includes('a'));
+  assert.ok(clusterAB.members.includes('b'));
+  assert.ok(!clusterAB.members.includes('lonely'));
+});
+
+test('CG-11: cycleFor and clusterOf locate a module', () => {
+  const facts = [
+    fact('a', 'a', [{ path: 'a/x.js', language: 'javascript', symbols: [], deps: ['../b'] }]),
+    fact('b', 'b', [{ path: 'b/index.js', language: 'javascript', symbols: [], deps: ['../a'] }]),
+  ];
+  const graph = g.buildModuleGraph(facts);
+  assert.deepEqual(g.cycleFor(graph, 'a'), ['a', 'b']);
+  assert.equal(typeof g.clusterOf(graph, 'a'), 'number');
+  assert.equal(g.cycleFor(graph, 'missing'), null);
+  assert.equal(g.clusterOf(graph, 'missing'), null);
+});
+
+test('CG-12: root-relative (/-prefixed) deps resolve from project root', () => {
+  const facts = [
+    fact('src-auth', 'src/auth', [
+      { path: 'src/auth/login.js', language: 'javascript', symbols: [], deps: ['/src/db'] },
+    ]),
+    fact('src-db', 'src/db', [
+      { path: 'src/db/index.js', language: 'javascript', symbols: [], deps: [] },
+    ]),
+  ];
+  const graph = g.buildModuleGraph(facts);
+  assert.equal(graph.edge_count, 1);
+  assert.deepEqual(graph.edges[0], { from: 'src-auth', to: 'src-db', weight: 1 });
+});
+
+test('CG-13: empty facts yield an empty graph', () => {
+  const graph = g.buildModuleGraph([]);
+  assert.equal(graph.module_count, 0);
+  assert.equal(graph.edge_count, 0);
+  assert.deepEqual(graph.cycles, []);
+  assert.deepEqual(graph.clusters, []);
+});

package/lib/codebase-manifest.cjs

@@ -3,8 +3,10 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { atomicWriteFileSync, NubosPilotError } = require('./core.cjs');
+const { assertValid } = require('./validate.cjs');
 
 const SCHEMA_VERSION = 1;
+const STORE_SCHEMA = 'codebase-manifest.v1';
 const CODEBASE_DIR_NAME = 'codebase';
 const MANIFEST_FILENAME = '.hashes.json';
 
@@ -63,6 +65,7 @@ function readManifest(projectRoot) {
     );
   }
   if (!parsed.files || typeof parsed.files !== 'object') parsed.files = {};
+  assertValid(parsed, STORE_SCHEMA, 'manifest-invalid-shape', { path: p });
   return parsed;
 }
 

package/lib/config-defaults.cjs

@@ -9,6 +9,7 @@ const DEFAULT_WORKFLOW = Object.freeze({
   commit_docs: true,
   commit_artifacts: true,
   worktree_isolation: false,
+  tier_routing: false,
   research_tools: DEFAULT_RESEARCH_TOOLS,
 });
 
@@ -21,6 +22,7 @@ const DEFAULT_AGENTS = Object.freeze({
 
 const DEFAULT_LOOP = Object.freeze({
   maxRounds: 3,
+  verify_runs: 1,
 });
 
 const DEFAULT_SWARM_RESEARCH = Object.freeze({
@@ -58,6 +60,14 @@ const DEFAULT_CONFORMANCE = Object.freeze({
   inject_criteria: true,
 });
 
+const DEFAULT_LEARNINGS = Object.freeze({
+  auto_capture: true,
+  max_captures_per_hour: 10,
+  max_in_a_row: 3,
+  timeout_ms: 120000,
+  max_files: 30,
+});
+
 const DEFAULT_AUTO_LOG_LEARNING = true;
 
 const DEFAULT_SPAWN_HEADLESS = Object.freeze({
@@ -86,6 +96,7 @@ const DEFAULT_CONFIG_TREE = Object.freeze({
   spawn: DEFAULT_SPAWN,
   security: DEFAULT_SECURITY,
   conformance: DEFAULT_CONFORMANCE,
+  learnings: DEFAULT_LEARNINGS,
   auto_log_learning: DEFAULT_AUTO_LOG_LEARNING,
 });
 
@@ -119,6 +130,7 @@ function buildInstallConfig(answers) {
     },
     security: { ...DEFAULT_SECURITY },
     conformance: { ...DEFAULT_CONFORMANCE },
+    learnings: { ...DEFAULT_LEARNINGS },
     auto_log_learning: DEFAULT_AUTO_LOG_LEARNING,
   };
 }
@@ -135,6 +147,7 @@ module.exports = {
   DEFAULT_SPAWN_HEADLESS,
   DEFAULT_SECURITY,
   DEFAULT_CONFORMANCE,
+  DEFAULT_LEARNINGS,
   DEFAULT_AUTO_LOG_LEARNING,
   DEFAULT_MODEL_PROFILE,
   DEFAULT_SCOPE,

package/lib/config-schema.cjs

@@ -21,6 +21,7 @@ const SCHEMA = Object.freeze({
       worktree_isolation: { type: 'boolean', optional: true },
       research_tools:     { type: 'object', shape: 'any', optional: true },
       text_mode:          { type: 'boolean', optional: true },
+      tier_routing:       { type: 'boolean', optional: true },
     },
   },
   agents: {
@@ -34,6 +35,7 @@ const SCHEMA = Object.freeze({
   loop: {
     type: 'object', optional: true, shape: {
       maxRounds: { type: 'number', optional: true },
+      verify_runs: { type: 'number', optional: true },
     },
   },
   swarm: {
@@ -86,6 +88,15 @@ const SCHEMA = Object.freeze({
       inject_criteria: { type: 'boolean', optional: true },
     },
   },
+  learnings: {
+    type: 'object', optional: true, shape: {
+      auto_capture:          { type: 'boolean', optional: true },
+      max_captures_per_hour: { type: 'number', optional: true },
+      max_in_a_row:          { type: 'number', optional: true },
+      timeout_ms:            { type: 'number', optional: true },
+      max_files:             { type: 'number', optional: true },
+    },
+  },
 });
 
 function _typeOf(v) {

package/lib/eval-reliability.cjs

@@ -0,0 +1,63 @@
+'use strict';
+
+// pass@k reliability: the orchestrator runs a task's <verify> command k times
+// and feeds the collected exit codes here. A task that passes only sometimes is
+// FLAKY — not green. summarize() folds k runs into a single aggregate exit code
+// (0 only when every run passed — pass^k semantics) so flakiness flows through
+// the EXISTING verify-red → build-fixer path. No new critic category is
+// introduced (that would risk the unknown-category spurious-stuck trap).
+
+const { NubosPilotError } = require('./core.cjs');
+
+/**
+ * @param {number[]} exitCodes  one exit code per verify run (0 = pass)
+ * @returns {{runs:number, passes:number, fails:number, pass_at_1:boolean, pass_at_k:boolean, flaky:boolean, verdict:string, aggregate_exit_code:number}}
+ */
+function summarize(exitCodes) {
+  if (!Array.isArray(exitCodes) || exitCodes.length === 0) {
+    throw new NubosPilotError(
+      'eval-reliability-no-runs',
+      'summarize requires a non-empty array of exit codes',
+      { got: exitCodes },
+    );
+  }
+  const codes = exitCodes.map((c) => Number(c));
+  if (codes.some((c) => !Number.isInteger(c))) {
+    throw new NubosPilotError(
+      'eval-reliability-bad-code',
+      'every exit code must be an integer',
+      { codes: exitCodes },
+    );
+  }
+
+  const runs = codes.length;
+  const passes = codes.filter((c) => c === 0).length;
+  const fails = runs - passes;
+  const passAt1 = codes[0] === 0;
+  const passAtK = passes === runs;
+  const flaky = passes > 0 && fails > 0;
+
+  let verdict;
+  if (passAtK) verdict = 'reliable-pass';
+  else if (passes === 0) verdict = 'reliable-fail';
+  else verdict = 'flaky';
+
+  // pass^k: green only if every run passed. Flaky and all-fail both aggregate
+  // to non-zero so the loop treats them as verify-red.
+  const aggregate_exit_code = passAtK ? 0 : 1;
+
+  return { runs, passes, fails, pass_at_1: passAt1, pass_at_k: passAtK, flaky, verdict, aggregate_exit_code };
+}
+
+/** One-line human summary for the verify log the build-fixer reads. */
+function describe(s) {
+  if (s.runs === 1) {
+    return s.pass_at_k ? 'verify passed (1 run)' : 'verify failed (1 run)';
+  }
+  if (s.verdict === 'reliable-pass') return 'verify reliably passed (' + s.passes + '/' + s.runs + ' runs)';
+  if (s.verdict === 'reliable-fail') return 'verify reliably failed (0/' + s.runs + ' runs passed)';
+  return 'FLAKY: verify passed only ' + s.passes + '/' + s.runs + ' runs — non-deterministic, treated as red. '
+    + 'Make the verified behaviour deterministic (no sleeps/real clock/network/ordering) before this task can go green.';
+}
+
+module.exports = { summarize, describe };

package/lib/eval-reliability.test.cjs

@@ -0,0 +1,56 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { summarize, describe } = require('./eval-reliability.cjs');
+
+test('ER-1: all pass → reliable-pass, aggregate 0', () => {
+  const s = summarize([0, 0, 0]);
+  assert.strictEqual(s.verdict, 'reliable-pass');
+  assert.strictEqual(s.pass_at_k, true);
+  assert.strictEqual(s.pass_at_1, true);
+  assert.strictEqual(s.flaky, false);
+  assert.strictEqual(s.aggregate_exit_code, 0);
+});
+
+test('ER-2: all fail → reliable-fail, aggregate non-zero', () => {
+  const s = summarize([1, 1, 1]);
+  assert.strictEqual(s.verdict, 'reliable-fail');
+  assert.strictEqual(s.pass_at_k, false);
+  assert.strictEqual(s.flaky, false);
+  assert.strictEqual(s.aggregate_exit_code, 1);
+});
+
+test('ER-3: mixed → flaky, aggregate non-zero (pass^k)', () => {
+  const s = summarize([0, 1, 0]);
+  assert.strictEqual(s.verdict, 'flaky');
+  assert.strictEqual(s.flaky, true);
+  assert.strictEqual(s.pass_at_1, true);
+  assert.strictEqual(s.pass_at_k, false);
+  assert.strictEqual(s.aggregate_exit_code, 1);
+});
+
+test('ER-4: first-run-fail-then-pass is still flaky and red', () => {
+  const s = summarize([1, 0, 0]);
+  assert.strictEqual(s.flaky, true);
+  assert.strictEqual(s.pass_at_1, false);
+  assert.strictEqual(s.aggregate_exit_code, 1);
+});
+
+test('ER-5: single run preserves classic behaviour', () => {
+  assert.strictEqual(summarize([0]).aggregate_exit_code, 0);
+  assert.strictEqual(summarize([2]).aggregate_exit_code, 1);
+  assert.strictEqual(summarize([0]).verdict, 'reliable-pass');
+});
+
+test('ER-6: empty/invalid input throws', () => {
+  assert.throws(() => summarize([]), (e) => e.code === 'eval-reliability-no-runs');
+  assert.throws(() => summarize('nope'), (e) => e.code === 'eval-reliability-no-runs');
+  assert.throws(() => summarize([0, 1.5]), (e) => e.code === 'eval-reliability-bad-code');
+});
+
+test('ER-7: describe is human-readable and flags flaky loudly', () => {
+  assert.match(describe(summarize([0])), /passed \(1 run\)/);
+  assert.match(describe(summarize([0, 0, 0])), /reliably passed/);
+  assert.match(describe(summarize([0, 1, 0])), /FLAKY/);
+});

package/lib/install/claude-hooks-learnings.test.cjs

@@ -0,0 +1,82 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const mod = require('./claude-hooks.cjs');
+
+function _mkSandbox() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-learn-hooks-'));
+  const hooksDir = path.join(dir, '.claude', 'nubos-pilot', 'hooks');
+  fs.mkdirSync(hooksDir, { recursive: true });
+  fs.writeFileSync(path.join(hooksDir, 'np-statusline.cjs'), '// stub\n');
+  fs.writeFileSync(path.join(hooksDir, 'np-ctx-monitor.cjs'), '// stub\n');
+  fs.writeFileSync(path.join(hooksDir, 'np-security-hook.cjs'), '// stub\n');
+  fs.writeFileSync(path.join(hooksDir, 'np-learnings-hook.cjs'), '// stub\n');
+  return dir;
+}
+
+test('LH-1: which=learnings registers capture on Stop + reset on UserPromptSubmit', () => {
+  const dir = _mkSandbox();
+  try {
+    const res = mod.installClaudeHooks({ projectRoot: dir, scope: 'local', which: 'learnings' });
+    assert.equal(res.results.learnings.capture.action, 'installed');
+    assert.equal(res.results.learnings.reset.action, 'installed');
+    const settings = JSON.parse(fs.readFileSync(res.path, 'utf-8'));
+    const stop = JSON.stringify(settings.hooks.Stop);
+    const ups = JSON.stringify(settings.hooks.UserPromptSubmit);
+    assert.ok(stop.includes('np-learnings-hook.cjs'));
+    assert.ok(stop.includes(' capture'));
+    assert.ok(ups.includes('np-learnings-hook.cjs'));
+    assert.ok(ups.includes(' reset'));
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('LH-2: which=all installs learnings alongside security', () => {
+  const dir = _mkSandbox();
+  try {
+    const res = mod.installClaudeHooks({ projectRoot: dir, scope: 'local', which: 'all' });
+    assert.ok(res.results.learnings);
+    assert.ok(res.results.security);
+    assert.equal(res.results.learnings.capture.action, 'installed');
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('LH-3: install is idempotent — second run updates, not duplicates', () => {
+  const dir = _mkSandbox();
+  try {
+    mod.installClaudeHooks({ projectRoot: dir, scope: 'local', which: 'learnings' });
+    const res2 = mod.installClaudeHooks({ projectRoot: dir, scope: 'local', which: 'learnings' });
+    assert.equal(res2.results.learnings.capture.action, 'updated');
+    const settings = JSON.parse(fs.readFileSync(res2.path, 'utf-8'));
+    const stopLearnings = settings.hooks.Stop.filter((e) =>
+      JSON.stringify(e).includes('np-learnings-hook.cjs'));
+    assert.equal(stopLearnings.length, 1);
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('LH-4: uninstall removes learnings hooks', () => {
+  const dir = _mkSandbox();
+  try {
+    mod.installClaudeHooks({ projectRoot: dir, scope: 'local', which: 'all' });
+    const res = mod.uninstallClaudeHooks({ projectRoot: dir, scope: 'local' });
+    assert.equal(res.results.learnings.action, 'removed');
+    const settings = JSON.parse(fs.readFileSync(res.path, 'utf-8'));
+    const dump = JSON.stringify(settings.hooks || {});
+    assert.ok(!dump.includes('np-learnings-hook.cjs'));
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('LH-5: missing learnings hook script throws claude-hooks-script-missing', () => {
+  const dir = _mkSandbox();
+  try {
+    fs.rmSync(path.join(dir, '.claude', 'nubos-pilot', 'hooks', 'np-learnings-hook.cjs'));
+    assert.throws(
+      () => mod.installClaudeHooks({ projectRoot: dir, scope: 'local', which: 'learnings' }),
+      (e) => e.code === 'claude-hooks-script-missing',
+    );
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});

package/lib/install/claude-hooks.cjs

@@ -17,9 +17,11 @@ const { atomicWriteFileSync, NubosPilotError, withFileLock } = require('../core.
 const STATUSLINE_REL = '.claude/nubos-pilot/hooks/np-statusline.cjs';
 const CTX_MONITOR_REL = '.claude/nubos-pilot/hooks/np-ctx-monitor.cjs';
 const SECURITY_HOOK_REL = '.claude/nubos-pilot/hooks/np-security-hook.cjs';
+const LEARNINGS_HOOK_REL = '.claude/nubos-pilot/hooks/np-learnings-hook.cjs';
 const NP_STATUSLINE_MARKER = 'np-statusline.';
 const NP_CTX_MONITOR_MARKER = 'np-ctx-monitor.';
 const NP_SECURITY_MARKER = 'np-security-hook.';
+const NP_LEARNINGS_MARKER = 'np-learnings-hook.';
 
 // ADR-0020: in-session security review layer. One DRY hook script, registered
 // against five Claude Code lifecycle events, differentiated by a trailing verb.
@@ -32,6 +34,15 @@ const SECURITY_HOOKS = Object.freeze([
 ]);
 const SECURITY_EVENTS = Object.freeze(['SessionStart', 'UserPromptSubmit', 'Stop', 'PostToolUse']);
 
+// ADR-0010 / ECC continuous-learning: one DRY hook script. `capture` on Stop
+// (rate-limited auto-extraction of the turn's learnings); `reset` on
+// UserPromptSubmit (clears the consecutive-stop streak).
+const LEARNINGS_HOOKS = Object.freeze([
+  { verb: 'reset',   event: 'UserPromptSubmit', matcher: undefined },
+  { verb: 'capture', event: 'Stop',             matcher: undefined },
+]);
+const LEARNINGS_EVENTS = Object.freeze(['UserPromptSubmit', 'Stop']);
+
 function _settingsPath(scope, projectRoot) {
   if (scope === 'global') return path.join(os.homedir(), '.claude', 'settings.json');
   return path.join(projectRoot, '.claude', 'settings.local.json');
@@ -119,14 +130,15 @@ function _verbOf(command) {
   return m ? m[1] : null;
 }
 
-function _installVerbHook(settings, eventName, matcher, cmd, verb) {
+function _installVerbHook(settings, eventName, matcher, cmd, verb, marker) {
+  const mark = marker || NP_SECURITY_MARKER;
   if (!settings.hooks || typeof settings.hooks !== 'object') settings.hooks = {};
   if (!Array.isArray(settings.hooks[eventName])) settings.hooks[eventName] = [];
   const list = settings.hooks[eventName];
   for (const entry of list) {
     const hooks = Array.isArray(entry.hooks) ? entry.hooks : [];
     for (const h of hooks) {
-      if (h && typeof h.command === 'string' && h.command.includes(NP_SECURITY_MARKER) && _verbOf(h.command) === verb) {
+      if (h && typeof h.command === 'string' && h.command.includes(mark) && _verbOf(h.command) === verb) {
         h.command = cmd;
         h.type = 'command';
         if (matcher !== undefined) entry.matcher = matcher;
@@ -145,11 +157,42 @@ function _installSecurity(settings, scope, projectRoot) {
   const base = _hookCommand(SECURITY_HOOK_REL, scope, projectRoot);
   const results = {};
   for (const h of SECURITY_HOOKS) {
-    results[h.verb] = _installVerbHook(settings, h.event, h.matcher, base + ' ' + h.verb, h.verb);
+    results[h.verb] = _installVerbHook(settings, h.event, h.matcher, base + ' ' + h.verb, h.verb, NP_SECURITY_MARKER);
+  }
+  return results;
+}
+
+function _installLearnings(settings, scope, projectRoot) {
+  const base = _hookCommand(LEARNINGS_HOOK_REL, scope, projectRoot);
+  const results = {};
+  for (const h of LEARNINGS_HOOKS) {
+    results[h.verb] = _installVerbHook(settings, h.event, h.matcher, base + ' ' + h.verb, h.verb, NP_LEARNINGS_MARKER);
   }
   return results;
 }
 
+function _removeLearnings(settings) {
+  if (!settings.hooks || typeof settings.hooks !== 'object') return { action: 'absent' };
+  let removed = 0;
+  for (const eventName of LEARNINGS_EVENTS) {
+    if (!Array.isArray(settings.hooks[eventName])) continue;
+    const filtered = [];
+    for (const entry of settings.hooks[eventName]) {
+      const hooks = Array.isArray(entry.hooks) ? entry.hooks : [];
+      const kept = hooks.filter((h) => !(h && typeof h.command === 'string' && h.command.includes(NP_LEARNINGS_MARKER)));
+      if (kept.length > 0) {
+        filtered.push(kept.length === hooks.length ? entry : Object.assign({}, entry, { hooks: kept }));
+      } else {
+        removed++;
+      }
+    }
+    settings.hooks[eventName] = filtered;
+    if (filtered.length === 0) delete settings.hooks[eventName];
+  }
+  if (settings.hooks && Object.keys(settings.hooks).length === 0) delete settings.hooks;
+  return { action: removed > 0 ? 'removed' : 'absent' };
+}
+
 function _removeSecurity(settings) {
   if (!settings.hooks || typeof settings.hooks !== 'object') return { action: 'absent' };
   let removed = 0;
@@ -214,6 +257,7 @@ function installClaudeHooks(opts) {
   const wantStatusline = which === 'statusline' || which === 'both' || which === 'all';
   const wantCtxMonitor = which === 'ctx-monitor' || which === 'both' || which === 'all';
   const wantSecurity = which === 'security' || which === 'all';
+  const wantLearnings = which === 'learnings' || which === 'all';
 
   const statuslineCmd = _hookCommand(STATUSLINE_REL, scope, projectRoot);
   const ctxMonitorCmd = _hookCommand(CTX_MONITOR_REL, scope, projectRoot);
@@ -222,6 +266,7 @@ function installClaudeHooks(opts) {
   const statuslineAbs = path.join(base, STATUSLINE_REL);
   const ctxMonitorAbs = path.join(base, CTX_MONITOR_REL);
   const securityAbs = path.join(base, SECURITY_HOOK_REL);
+  const learningsAbs = path.join(base, LEARNINGS_HOOK_REL);
 
   if (wantStatusline) {
     if (!fs.existsSync(statuslineAbs)) {
@@ -250,6 +295,15 @@ function installClaudeHooks(opts) {
       );
     }
   }
+  if (wantLearnings) {
+    if (!fs.existsSync(learningsAbs)) {
+      throw new NubosPilotError(
+        'claude-hooks-script-missing',
+        'Learnings hook script not found: ' + learningsAbs,
+        { script: learningsAbs },
+      );
+    }
+  }
 
   fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
 
@@ -266,6 +320,9 @@ function installClaudeHooks(opts) {
     if (wantSecurity) {
       results.security = _installSecurity(settings, scope, projectRoot);
     }
+    if (wantLearnings) {
+      results.learnings = _installLearnings(settings, scope, projectRoot);
+    }
 
     if (o.dryRun) return { dryRun: true, path: settingsPath, results, settings };
 
@@ -279,7 +336,7 @@ function uninstallClaudeHooks(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' }, security: { action: 'absent' } } };
+  if (!fs.existsSync(settingsPath)) return { path: settingsPath, results: { statusline: { action: 'absent' }, ctxMonitor: { action: 'absent' }, security: { action: 'absent' }, learnings: { action: 'absent' } } };
 
   return withFileLock(settingsPath, () => {
     const settings = _readJsonSafe(settingsPath);
@@ -287,6 +344,7 @@ function uninstallClaudeHooks(opts) {
       statusline: _removeStatusLine(settings),
       ctxMonitor: _removePostToolUse(settings),
       security: _removeSecurity(settings),
+      learnings: _removeLearnings(settings),
     };
     if (o.dryRun) return { dryRun: true, path: settingsPath, results, settings };
     atomicWriteFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
@@ -304,6 +362,9 @@ module.exports = {
   NP_CTX_MONITOR_MARKER,
   NP_SECURITY_MARKER,
   SECURITY_HOOKS,
+  LEARNINGS_HOOK_REL,
+  NP_LEARNINGS_MARKER,
+  LEARNINGS_HOOKS,
   _settingsPath,
   _hookCommand,
 };

package/lib/install/claude-hooks.test.cjs

@@ -230,7 +230,7 @@ function _mkSandboxAll() {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-claude-hooks-all-'));
   const hooksDir = path.join(dir, '.claude', 'nubos-pilot', 'hooks');
   fs.mkdirSync(hooksDir, { recursive: true });
-  for (const f of ['np-statusline.cjs', 'np-ctx-monitor.cjs', 'np-security-hook.cjs']) {
+  for (const f of ['np-statusline.cjs', 'np-ctx-monitor.cjs', 'np-security-hook.cjs', 'np-learnings-hook.cjs']) {
     fs.writeFileSync(path.join(hooksDir, f), '// stub\n');
   }
   return dir;
@@ -269,7 +269,10 @@ test('claude-hooks SEC: re-install is idempotent (no duplicate entries)', () =>
     assert.equal(res2.results.security.scan.action, 'updated');
     const s = JSON.parse(fs.readFileSync(res2.path, 'utf-8'));
     assert.equal(s.hooks.SessionStart.length, 1);
-    assert.equal(s.hooks.Stop.length, 1);
+    // Stop now carries the security 'review' hook + the learnings 'capture' hook (which=all installs both).
+    assert.equal(s.hooks.Stop.length, 2);
+    assert.equal(s.hooks.Stop.filter((e) => e.hooks[0].command.includes('np-security-hook.')).length, 1);
+    assert.equal(s.hooks.Stop.filter((e) => e.hooks[0].command.includes('np-learnings-hook.')).length, 1);
     assert.equal(s.hooks.PostToolUse.filter((e) => e.hooks[0].command.includes('np-security-hook.')).length, 2);
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });