nubos-pilot 1.2.2 → 1.2.3

package/bin/np-tools/skill-audit.test.cjs

@@ -0,0 +1,86 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { run } = require('./skill-audit.cjs');
+const checkpoint = require('../../lib/checkpoint.cjs');
+
+function _mkRoot() {
+  const r = fs.mkdtempSync(path.join(os.tmpdir(), 'np-skill-cli-'));
+  fs.mkdirSync(path.join(r, '.nubos-pilot', 'checkpoints'), { recursive: true });
+  fs.writeFileSync(
+    path.join(r, '.nubos-pilot', 'STATE.md'),
+    '---\nschema_version: 2\ncurrent_phase: null\ncurrent_plan: null\ncurrent_task: null\n---\n',
+    'utf-8',
+  );
+  return r;
+}
+function _cap(cwd) {
+  const out = { text: '' }; const err = { text: '' };
+  return { cwd, stdout: { write: (s) => { out.text += s; return true; } }, stderr: { write: (s) => { err.text += s; return true; } }, out, err };
+}
+const TID = 'M001-S001-T0001';
+
+test('SC-1: expect then findings reports the unacked skill', () => {
+  const r = _mkRoot();
+  try {
+    checkpoint.startTask({ id: TID }, r);
+    assert.equal(run(['expect', '--task', TID, '--skills', 'np-api-design,np-encryption'], _cap(r)), 0);
+    const c = _cap(r);
+    assert.equal(run(['findings', '--task', TID], c), 0);
+    const parsed = JSON.parse(c.out.text);
+    assert.equal(parsed.findings.length, 1);
+    assert.deepEqual(parsed.findings[0].raw.missing_skills.sort(), ['np-api-design', 'np-encryption']);
+  } finally { fs.rmSync(r, { recursive: true, force: true }); }
+});
+
+test('SC-2: ack clears the finding for that skill', () => {
+  const r = _mkRoot();
+  try {
+    checkpoint.startTask({ id: TID }, r);
+    run(['expect', '--task', TID, '--skills', 'np-api-design'], _cap(r));
+    run(['ack', '--task', TID, '--skill', 'np-api-design'], _cap(r));
+    const c = _cap(r);
+    run(['findings', '--task', TID], c);
+    assert.equal(JSON.parse(c.out.text).findings.length, 0);
+  } finally { fs.rmSync(r, { recursive: true, force: true }); }
+});
+
+test('SC-3: invalid task id → error envelope exit 1', () => {
+  const c = _cap(process.cwd());
+  assert.equal(run(['ack', '--task', 'bogus', '--skill', 'x'], c), 1);
+  assert.match(c.err.text, /skill-audit-invalid-task-id/);
+});
+
+test('SC-4: ack without --skill → error envelope exit 1', () => {
+  const r = _mkRoot();
+  try {
+    checkpoint.startTask({ id: TID }, r);
+    const c = _cap(r);
+    assert.equal(run(['ack', '--task', TID], c), 1);
+    assert.match(c.err.text, /skill-audit-missing-skill/);
+  } finally { fs.rmSync(r, { recursive: true, force: true }); }
+});
+
+test('SC-5: unknown verb → exit 1; --help → exit 0', () => {
+  const c1 = _cap(process.cwd());
+  assert.equal(run(['bogus'], c1), 1);
+  assert.match(c1.err.text, /skill-audit-unknown-verb/);
+  const c2 = _cap(process.cwd());
+  assert.equal(run(['--help'], c2), 0);
+  assert.match(c2.out.text, /skill-audit/);
+});
+
+test('SC-6: expect with empty skills is a no-op (no findings)', () => {
+  const r = _mkRoot();
+  try {
+    checkpoint.startTask({ id: TID }, r);
+    assert.equal(run(['expect', '--task', TID, '--skills', ''], _cap(r)), 0);
+    const c = _cap(r);
+    run(['findings', '--task', TID], c);
+    assert.equal(JSON.parse(c.out.text).findings.length, 0);
+  } finally { fs.rmSync(r, { recursive: true, force: true }); }
+});

package/bin/np-tools/verify-reliability.cjs

@@ -0,0 +1,65 @@
+'use strict';
+
+const { summarize, describe } = require('../../lib/eval-reliability.cjs');
+const { emitErrorEnvelope } = require('./_args.cjs');
+
+function _usage() {
+  return [
+    'Usage:',
+    '  np-tools.cjs verify-reliability --codes <c1,c2,...>',
+    '',
+    'pass@k reliability: the orchestrator runs a task\'s <verify> command k times',
+    'and passes the collected exit codes (0 = pass). Emits a JSON summary whose',
+    '`aggregate_exit_code` is 0 only when every run passed (pass^k) — feed it to',
+    '`loop-run-round --phase post-executor --verify-exit-code`. A flaky task',
+    'aggregates to red and flows through the normal build-fixer path.',
+  ].join('\n');
+}
+
+function run(argv, ctx) {
+  const context = ctx || {};
+  const stdout = context.stdout || process.stdout;
+  const stderr = context.stderr || process.stderr;
+  const args = Array.isArray(argv) ? argv.slice() : [];
+
+  let codesRaw = null;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '-h' || a === '--help') { stdout.write(_usage() + '\n'); return 0; }
+    else if (a === '--codes') { codesRaw = args[++i] || ''; }
+    else if (a.startsWith('--codes=')) { codesRaw = a.slice('--codes='.length); }
+    else {
+      stderr.write(JSON.stringify({
+        code: 'verify-reliability-unknown-arg',
+        message: 'Unknown argument: ' + a,
+        details: { arg: a },
+      }) + '\n');
+      return 1;
+    }
+  }
+
+  if (codesRaw == null) {
+    stderr.write(JSON.stringify({
+      code: 'verify-reliability-missing-codes',
+      message: '--codes <c1,c2,...> is required',
+      details: {},
+    }) + '\n');
+    return 1;
+  }
+
+  try {
+    const codes = String(codesRaw).split(',').map((s) => s.trim()).filter((s) => s !== '').map(Number);
+    const summary = summarize(codes);
+    stdout.write(JSON.stringify(Object.assign({}, summary, { description: describe(summary) })) + '\n');
+    return 0;
+  } catch (err) {
+    emitErrorEnvelope(err, stderr, 'verify-reliability-internal-error');
+    return 1;
+  }
+}
+
+module.exports = { run };
+
+if (require.main === module) {
+  process.exit(run(process.argv.slice(2)));
+}

package/bin/np-tools/verify-reliability.test.cjs

@@ -0,0 +1,69 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { run } = require('./verify-reliability.cjs');
+
+function _capture() {
+  const out = { text: '' };
+  const err = { text: '' };
+  return {
+    stdout: { write: (s) => { out.text += s; return true; } },
+    stderr: { write: (s) => { err.text += s; return true; } },
+    out, err,
+  };
+}
+
+test('VR-1: all-pass codes → aggregate 0, reliable-pass', () => {
+  const c = _capture();
+  const code = run(['--codes', '0,0,0'], c);
+  assert.strictEqual(code, 0);
+  const r = JSON.parse(c.out.text);
+  assert.strictEqual(r.aggregate_exit_code, 0);
+  assert.strictEqual(r.verdict, 'reliable-pass');
+});
+
+test('VR-2: flaky codes → aggregate 1, flaky verdict + loud description', () => {
+  const c = _capture();
+  const code = run(['--codes', '0,1,0'], c);
+  assert.strictEqual(code, 0);
+  const r = JSON.parse(c.out.text);
+  assert.strictEqual(r.aggregate_exit_code, 1);
+  assert.strictEqual(r.flaky, true);
+  assert.match(r.description, /FLAKY/);
+});
+
+test('VR-3: --codes= form supported', () => {
+  const c = _capture();
+  const code = run(['--codes=1,1'], c);
+  assert.strictEqual(code, 0);
+  assert.strictEqual(JSON.parse(c.out.text).verdict, 'reliable-fail');
+});
+
+test('VR-4: missing --codes → error envelope, exit 1', () => {
+  const c = _capture();
+  const code = run([], c);
+  assert.strictEqual(code, 1);
+  assert.match(c.err.text, /verify-reliability-missing-codes/);
+});
+
+test('VR-5: unknown arg → error envelope, exit 1', () => {
+  const c = _capture();
+  const code = run(['--bogus'], c);
+  assert.strictEqual(code, 1);
+  assert.match(c.err.text, /verify-reliability-unknown-arg/);
+});
+
+test('VR-6: empty codes → internal error envelope, exit 1', () => {
+  const c = _capture();
+  const code = run(['--codes', ''], c);
+  assert.strictEqual(code, 1);
+  assert.match(c.err.text, /eval-reliability-no-runs/);
+});
+
+test('VR-7: --help → usage exit 0', () => {
+  const c = _capture();
+  const code = run(['--help'], c);
+  assert.strictEqual(code, 0);
+  assert.match(c.out.text, /verify-reliability/);
+});

package/lib/agents.test.cjs

@@ -247,6 +247,7 @@ const NP_AGENTS = [
   { file: 'np-nyquist-auditor', expected_tier: 'haiku' },
   { file: 'np-sc-extractor', expected_tier: 'haiku' },
   { file: 'np-critic', expected_tier: 'sonnet' },
+  { file: 'np-learnings-extractor', expected_tier: 'haiku' },
 ];
 
 // Audit-surface modules — files in agents/ that carry agent-shaped frontmatter

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,
 };