nubos-pilot 1.2.2 → 1.2.3

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

package/lib/learnings/capture-ledger.cjs

@@ -0,0 +1,80 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+// Rate-limit ledger for Stop-hook learning auto-capture. Mirrors the ADR-0020
+// security ledger's posture (sliding per-hour window + consecutive-stop streak)
+// but is its own concern and its own file. Per-session JSON under the OS temp
+// dir; a session that never stops leaves nothing behind worth cleaning.
+
+const DIR = path.join(os.tmpdir(), 'nubos-pilot-learnings');
+
+function sanitizeSid(sid) {
+  return String(sid || 'nosid').replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 128);
+}
+
+function ledgerPath(sid) {
+  return path.join(DIR, sanitizeSid(sid) + '.json');
+}
+
+function _read(sid) {
+  try {
+    return JSON.parse(fs.readFileSync(ledgerPath(sid), 'utf-8'));
+  } catch {
+    return { session_id: sanitizeSid(sid), created_at: Date.now(), capture_times: [], stop_streak: 0 };
+  }
+}
+
+function _write(sid, l) {
+  try {
+    fs.mkdirSync(DIR, { recursive: true });
+    fs.writeFileSync(ledgerPath(sid), JSON.stringify(l), 'utf-8');
+  } catch { /* a rate-limit ledger must never break the session */ }
+}
+
+/**
+ * Record an attempt to auto-capture on this session's Stop. Returns whether the
+ * capture is allowed under both caps. The per-hour window prevents runaway cost;
+ * the in-a-row streak prevents back-to-back Stops (e.g. a tight edit loop) each
+ * firing an extraction.
+ * @returns {{allowed: boolean, count: number, streak: number, reason?: string}}
+ */
+function tryRecordCapture(sid, opts) {
+  const maxPerHour = opts && Number.isFinite(opts.maxPerHour) ? opts.maxPerHour : 10;
+  const maxStreak = opts && Number.isFinite(opts.maxStreak) ? opts.maxStreak : 3;
+  const now = Date.now();
+  const hourAgo = now - 3600 * 1000;
+
+  const l = _read(sid);
+  l.capture_times = (Array.isArray(l.capture_times) ? l.capture_times : []).filter((t) => t > hourAgo);
+  l.stop_streak = Number.isFinite(l.stop_streak) ? l.stop_streak : 0;
+
+  if (l.capture_times.length >= maxPerHour) {
+    _write(sid, l);
+    return { allowed: false, count: l.capture_times.length, streak: l.stop_streak, reason: 'per-hour-cap' };
+  }
+  if (l.stop_streak >= maxStreak) {
+    _write(sid, l);
+    return { allowed: false, count: l.capture_times.length, streak: l.stop_streak, reason: 'streak-cap' };
+  }
+
+  l.capture_times.push(now);
+  l.stop_streak += 1;
+  _write(sid, l);
+  return { allowed: true, count: l.capture_times.length, streak: l.stop_streak };
+}
+
+/** Reset the consecutive-stop streak — call after a user prompt (real activity). */
+function resetStreak(sid) {
+  const l = _read(sid);
+  l.stop_streak = 0;
+  _write(sid, l);
+}
+
+function removeLedger(sid) {
+  try { fs.unlinkSync(ledgerPath(sid)); } catch {}
+}
+
+module.exports = { tryRecordCapture, resetStreak, removeLedger, ledgerPath, sanitizeSid, _read };

package/lib/learnings/capture-ledger.test.cjs

@@ -0,0 +1,54 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { tryRecordCapture, resetStreak, removeLedger } = require('./capture-ledger.cjs');
+
+function _sid(name) { return 'np-test-ledger-' + name + '-' + process.pid; }
+
+test('CL-1: streak cap blocks after maxStreak consecutive stops', () => {
+  const sid = _sid('streak');
+  removeLedger(sid);
+  try {
+    assert.strictEqual(tryRecordCapture(sid, { maxPerHour: 100, maxStreak: 3 }).allowed, true);
+    assert.strictEqual(tryRecordCapture(sid, { maxPerHour: 100, maxStreak: 3 }).allowed, true);
+    assert.strictEqual(tryRecordCapture(sid, { maxPerHour: 100, maxStreak: 3 }).allowed, true);
+    const blocked = tryRecordCapture(sid, { maxPerHour: 100, maxStreak: 3 });
+    assert.strictEqual(blocked.allowed, false);
+    assert.strictEqual(blocked.reason, 'streak-cap');
+  } finally { removeLedger(sid); }
+});
+
+test('CL-2: resetStreak clears the streak so capture is allowed again', () => {
+  const sid = _sid('reset');
+  removeLedger(sid);
+  try {
+    tryRecordCapture(sid, { maxPerHour: 100, maxStreak: 2 });
+    tryRecordCapture(sid, { maxPerHour: 100, maxStreak: 2 });
+    assert.strictEqual(tryRecordCapture(sid, { maxPerHour: 100, maxStreak: 2 }).allowed, false);
+    resetStreak(sid);
+    assert.strictEqual(tryRecordCapture(sid, { maxPerHour: 100, maxStreak: 2 }).allowed, true);
+  } finally { removeLedger(sid); }
+});
+
+test('CL-3: per-hour cap blocks regardless of streak resets', () => {
+  const sid = _sid('hour');
+  removeLedger(sid);
+  try {
+    assert.strictEqual(tryRecordCapture(sid, { maxPerHour: 2, maxStreak: 100 }).allowed, true);
+    resetStreak(sid);
+    assert.strictEqual(tryRecordCapture(sid, { maxPerHour: 2, maxStreak: 100 }).allowed, true);
+    resetStreak(sid);
+    const blocked = tryRecordCapture(sid, { maxPerHour: 2, maxStreak: 100 });
+    assert.strictEqual(blocked.allowed, false);
+    assert.strictEqual(blocked.reason, 'per-hour-cap');
+  } finally { removeLedger(sid); }
+});
+
+test('CL-4: a fresh session starts allowed', () => {
+  const sid = _sid('fresh');
+  removeLedger(sid);
+  try {
+    assert.strictEqual(tryRecordCapture(sid, {}).allowed, true);
+  } finally { removeLedger(sid); }
+});

package/lib/learnings/extract.cjs

@@ -0,0 +1,191 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const git = require('../git.cjs');
+const knowledgeAdapter = require('../knowledge-adapter.cjs');
+
+// Stop-hook learning auto-capture (ECC continuous-learning, np-native). A
+// background worker spawns the read-only np-learnings-extractor headlessly over
+// the turn's diff; it returns atomic {pattern, outcome} candidates which we fold
+// into the existing learnings store via the knowledge adapter — the same store
+// /np:execute-phase already auto-logs into. Mirrors lib/security/review.cjs.
+
+const EXTRACTOR_AGENT = 'np-learnings-extractor';
+const MAX_DIFF_BYTES = 64 * 1024;
+const MAX_UNTRACKED_BYTES = 12 * 1024;
+const MAX_CANDIDATES = 5;
+const MAX_PATTERN_LEN = 2000;
+const MAX_OUTCOME_LEN = 2000;
+const VALID_OUTCOMES = new Set(['verified', 'failed', 'reverted', 'partial']);
+
+function isRepo(cwd) {
+  const r = git.runGit(['rev-parse', '--is-inside-work-tree'], { cwd });
+  return r.ok && String(r.stdout).trim() === 'true';
+}
+
+function _lines(stdout) {
+  return String(stdout || '').split(/\r?\n/).filter(Boolean);
+}
+
+// "What changed this session": last commit (git show HEAD) plus any uncommitted
+// working changes and untracked files, each capped. No baseline tracking —
+// learnings are advisory, so a slightly wider window is acceptable.
+function computeTurnDiff(cwd, maxFiles) {
+  const cap = Number.isFinite(maxFiles) ? maxFiles : 30;
+  const committedNames = git.runGit(['diff-tree', '--no-commit-id', '--name-only', '-r', '--root', 'HEAD'], { cwd });
+  const workingNames = git.runGit(['--no-pager', 'diff', '--name-only'], { cwd });
+  const untracked = git.runGit(['ls-files', '--others', '--exclude-standard'], { cwd });
+
+  const files = [...new Set([
+    ..._lines(committedNames.stdout),
+    ..._lines(workingNames.stdout),
+    ..._lines(untracked.stdout),
+  ])];
+  const uniqueFiles = files.slice(0, cap);
+  const truncatedFiles = files.length > cap;
+
+  let diffText = '';
+  const show = git.runGit(['--no-pager', 'show', '--no-color', 'HEAD'], { cwd });
+  if (show.ok) diffText += String(show.stdout || '').slice(0, MAX_DIFF_BYTES);
+  const working = git.runGit(['--no-pager', 'diff', '--no-color'], { cwd });
+  if (working.ok && diffText.length < MAX_DIFF_BYTES) {
+    diffText += '\n' + String(working.stdout || '').slice(0, MAX_DIFF_BYTES - diffText.length);
+  }
+
+  let untrackedBudget = MAX_UNTRACKED_BYTES;
+  for (const f of _lines(untracked.stdout)) {
+    if (untrackedBudget <= 0) break;
+    let body = '';
+    try { body = fs.readFileSync(path.join(cwd, f), 'utf-8'); } catch { continue; }
+    const chunk = '\n--- new file: ' + f + ' ---\n' + body.slice(0, untrackedBudget);
+    diffText += chunk;
+    untrackedBudget -= chunk.length;
+  }
+
+  return { files: uniqueFiles, truncatedFiles, diffText };
+}
+
+function buildExtractorPrompt(opts) {
+  const o = opts || {};
+  const parts = [];
+  parts.push('<learning_capture>');
+  parts.push('You are running in learning-capture mode. Read the diff below — the work this session produced — and extract at most ' + MAX_CANDIDATES + ' ATOMIC, REUSABLE engineering learnings.');
+  parts.push('');
+  parts.push('A good learning is a durable, transferable rule a future agent on a SIMILAR task would benefit from — a convention discovered, a pitfall avoided, a fix that generalises. NOT a narration of what changed, NOT project-specific trivia, NOT anything obvious from reading the code.');
+  parts.push('');
+  parts.push('Each learning is one {pattern, outcome} pair:');
+  parts.push('- pattern: the reusable rule, imperative and self-contained (e.g. "use jose for JWT verification, never hand-roll HS256").');
+  parts.push('- outcome: one of verified | failed | reverted | partial — how it played out THIS session.');
+  parts.push('');
+  parts.push('If nothing meets the bar, return an empty list. Quality over quantity — zero is a valid, common answer.');
+  parts.push('');
+  parts.push('Changed files (' + o.files.length + (o.truncatedFiles ? '+, truncated' : '') + '):');
+  parts.push(o.files.map((f) => '- ' + f).join('\n'));
+  parts.push('');
+  parts.push('Diff:');
+  parts.push('```diff');
+  parts.push(o.diffText);
+  parts.push('```');
+  parts.push('');
+  parts.push('Output ONLY a single JSON object (no prose, no markdown fence):');
+  parts.push('{"learnings":[{"pattern":"...","outcome":"verified|failed|reverted|partial"}]}');
+  parts.push('</learning_capture>');
+  return parts.join('\n');
+}
+
+function _tryParseJson(s) { try { return JSON.parse(s); } catch { return null; } }
+function _stripFence(s) {
+  const m = String(s).match(/```(?:json)?\s*([\s\S]*?)```/);
+  return m ? m[1] : s;
+}
+
+function parseExtractorOutput(raw) {
+  if (!raw || typeof raw !== 'string') return { candidates: [], parse_ok: false };
+  let resultText = raw;
+  const outer = _tryParseJson(raw);
+  if (outer && typeof outer === 'object' && typeof outer.result === 'string') resultText = outer.result;
+
+  let env = _tryParseJson(resultText);
+  if (!env) env = _tryParseJson(_stripFence(resultText));
+  if (!env || typeof env !== 'object' || !Array.isArray(env.learnings)) {
+    return { candidates: [], parse_ok: false };
+  }
+  const candidates = env.learnings
+    .filter((l) => l && typeof l === 'object' && typeof l.pattern === 'string' && l.pattern.trim())
+    .map((l) => ({
+      pattern: l.pattern.trim().slice(0, MAX_PATTERN_LEN),
+      outcome: VALID_OUTCOMES.has(String(l.outcome)) ? String(l.outcome) : 'verified',
+    }))
+    .slice(0, MAX_CANDIDATES);
+  return { candidates, parse_ok: true };
+}
+
+function _defaultSpawn(promptText, opts) {
+  const spawnHeadless = require('../../bin/np-tools/spawn-headless.cjs');
+  const tmp = os.tmpdir();
+  const tag = process.pid + '-' + crypto.randomBytes(4).toString('hex');
+  const promptPath = path.join(tmp, 'np-learn-prompt-' + tag + '.txt');
+  const outputPath = path.join(tmp, 'np-learn-out-' + tag + '.json');
+  fs.writeFileSync(promptPath, promptText, 'utf-8');
+  try {
+    spawnHeadless.run(
+      ['--agent', EXTRACTOR_AGENT, '--prompt-path', promptPath, '--output-path', outputPath,
+        '--timeout-ms', String(opts.timeoutMs)],
+      { cwd: opts.cwd, stdout: { write: () => {} } },
+    );
+    return fs.readFileSync(outputPath, 'utf-8');
+  } finally {
+    try { fs.unlinkSync(promptPath); } catch {}
+    try { fs.unlinkSync(outputPath); } catch {}
+  }
+}
+
+function runExtract(opts) {
+  const o = opts || {};
+  const cwd = o.cwd || process.cwd();
+  const config = o.config || {};
+  const spawn = typeof o.spawnImpl === 'function' ? o.spawnImpl : _defaultSpawn;
+  const logImpl = typeof o.logImpl === 'function'
+    ? o.logImpl
+    : (cand) => knowledgeAdapter.getAdapter(cwd).log({ pattern: cand.pattern, outcome: cand.outcome });
+
+  if (!isRepo(cwd)) return { ran: false, reason: 'not-a-repo', logged: 0 };
+
+  const maxFiles = Number.isFinite(config.max_files) ? config.max_files : 30;
+  const diff = computeTurnDiff(cwd, maxFiles);
+  if (!String(diff.diffText).trim()) {
+    return { ran: true, logged: 0, reason: 'empty-diff' };
+  }
+
+  const promptText = buildExtractorPrompt(diff);
+  let raw = '';
+  try {
+    raw = spawn(promptText, { cwd, timeoutMs: config.timeout_ms || 120000 });
+  } catch {
+    return { ran: true, logged: 0, reason: 'spawn-failed' };
+  }
+
+  const parsed = parseExtractorOutput(raw);
+  if (!parsed.parse_ok) return { ran: true, logged: 0, reason: 'parse-failed' };
+
+  let logged = 0;
+  for (const cand of parsed.candidates) {
+    try { logImpl(cand); logged += 1; } catch { /* one bad candidate must not abort the rest */ }
+  }
+  return { ran: true, logged, candidates: parsed.candidates.length, reason: 'ok' };
+}
+
+module.exports = {
+  EXTRACTOR_AGENT,
+  isRepo,
+  computeTurnDiff,
+  buildExtractorPrompt,
+  parseExtractorOutput,
+  runExtract,
+  MAX_CANDIDATES,
+  VALID_OUTCOMES,
+};

package/lib/learnings/extract.test.cjs

@@ -0,0 +1,115 @@
+'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 cp = require('node:child_process');
+const extract = require('./extract.cjs');
+
+function _gitRepo(withCommit) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-extract-'));
+  const run = (args) => cp.spawnSync('git', args, { cwd: dir, encoding: 'utf-8' });
+  run(['init', '-q']);
+  run(['config', 'user.email', 'test@example.com']);
+  run(['config', 'user.name', 'Test']);
+  run(['config', 'commit.gpgsign', 'false']);
+  if (withCommit) {
+    fs.writeFileSync(path.join(dir, 'a.js'), 'function add(a,b){return a+b;}\n');
+    run(['add', '-A']);
+    run(['commit', '-q', '-m', 'add helper']);
+  }
+  return dir;
+}
+
+test('EX-1: buildExtractorPrompt frames a learning_capture block with diff + files', () => {
+  const p = extract.buildExtractorPrompt({ files: ['a.js'], truncatedFiles: false, diffText: '+ code' });
+  assert.match(p, /<learning_capture>/);
+  assert.match(p, /a\.js/);
+  assert.match(p, /```diff/);
+  assert.match(p, /"learnings"/);
+});
+
+test('EX-2: parseExtractorOutput unwraps {result} envelope', () => {
+  const raw = JSON.stringify({ result: JSON.stringify({ learnings: [{ pattern: 'use jose for jwt', outcome: 'verified' }] }) });
+  const r = extract.parseExtractorOutput(raw);
+  assert.strictEqual(r.parse_ok, true);
+  assert.strictEqual(r.candidates.length, 1);
+  assert.strictEqual(r.candidates[0].pattern, 'use jose for jwt');
+});
+
+test('EX-3: parseExtractorOutput strips a markdown fence', () => {
+  const raw = '```json\n{"learnings":[{"pattern":"p","outcome":"failed"}]}\n```';
+  const r = extract.parseExtractorOutput(raw);
+  assert.strictEqual(r.candidates.length, 1);
+  assert.strictEqual(r.candidates[0].outcome, 'failed');
+});
+
+test('EX-4: invalid outcome defaults to verified; empty pattern dropped', () => {
+  const raw = JSON.stringify({ learnings: [
+    { pattern: 'good', outcome: 'banana' },
+    { pattern: '   ', outcome: 'verified' },
+  ] });
+  const r = extract.parseExtractorOutput(raw);
+  assert.strictEqual(r.candidates.length, 1);
+  assert.strictEqual(r.candidates[0].outcome, 'verified');
+});
+
+test('EX-5: caps candidates at MAX_CANDIDATES', () => {
+  const many = Array.from({ length: 9 }, (_, i) => ({ pattern: 'p' + i, outcome: 'verified' }));
+  const r = extract.parseExtractorOutput(JSON.stringify({ learnings: many }));
+  assert.strictEqual(r.candidates.length, extract.MAX_CANDIDATES);
+});
+
+test('EX-6: non-JSON output → parse_ok false', () => {
+  assert.strictEqual(extract.parseExtractorOutput('totally not json').parse_ok, false);
+  assert.strictEqual(extract.parseExtractorOutput('').parse_ok, false);
+});
+
+test('EX-7: runExtract on a non-repo returns not-a-repo, logs nothing', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-norepo-'));
+  try {
+    const logged = [];
+    const r = extract.runExtract({ cwd: dir, spawnImpl: () => '{}', logImpl: (c) => logged.push(c) });
+    assert.strictEqual(r.ran, false);
+    assert.strictEqual(r.reason, 'not-a-repo');
+    assert.strictEqual(logged.length, 0);
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('EX-8: runExtract on empty repo (no commit, no changes) → empty-diff', () => {
+  const dir = _gitRepo(false);
+  try {
+    const r = extract.runExtract({ cwd: dir, spawnImpl: () => '{}', logImpl: () => {} });
+    assert.strictEqual(r.ran, true);
+    assert.strictEqual(r.reason, 'empty-diff');
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('EX-9: runExtract over a commit logs parsed candidates', () => {
+  const dir = _gitRepo(true);
+  try {
+    const logged = [];
+    const r = extract.runExtract({
+      cwd: dir,
+      spawnImpl: () => JSON.stringify({ result: JSON.stringify({ learnings: [
+        { pattern: 'keep add() pure and total', outcome: 'verified' },
+      ] }) }),
+      logImpl: (c) => logged.push(c),
+    });
+    assert.strictEqual(r.ran, true);
+    assert.strictEqual(r.logged, 1);
+    assert.strictEqual(logged[0].pattern, 'keep add() pure and total');
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('EX-10: runExtract with unparseable spawn output → parse-failed, no log', () => {
+  const dir = _gitRepo(true);
+  try {
+    const logged = [];
+    const r = extract.runExtract({ cwd: dir, spawnImpl: () => 'garbage', logImpl: (c) => logged.push(c) });
+    assert.strictEqual(r.reason, 'parse-failed');
+    assert.strictEqual(logged.length, 0);
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});

package/lib/nubosloop-audit.cjs

@@ -88,6 +88,106 @@ function searchEvidenceForRound(taskId, round, cwd) {
   return evidence.filter((e) => e && (Number(e.round) || 1) === target);
 }
 
+// ── Skill-bar consultation evidence (additive; mirrors search-evidence) ──────
+// The orchestrator records the skills it injected for a task (`recordExpectedSkills`);
+// the executor stamps each skill it actually consulted (`recordSkillEvidence`, via
+// `skill-audit ack`). skillFindingsFromState turns an unmet expectation into a
+// `skill-bar-unconsulted` finding (ROUTE_TABLE → executor), round-stamped and
+// emitted at most once per round via `skill_routed_rounds` — same anti-re-route
+// guarantee as the Rule-9 path. The Rule-9 functions below are left untouched.
+
+function _normSkillName(s) {
+  const v = String(s || '').trim();
+  // A path like `.claude/skills/<skill>/SKILL.md` names the skill by its directory.
+  const dir = v.match(/([^/]+)\/SKILL\.md$/i);
+  if (dir) return dir[1];
+  // Otherwise a bare name (optionally with a stray .md): take the basename.
+  return v.replace(/^.*\//, '').replace(/\.md$/i, '');
+}
+
+function recordSkillEvidence(taskId, skill, cwd) {
+  if (!TASK_ID_RE.test(taskId)) return null;
+  const name = _normSkillName(skill);
+  if (!name) return null;
+  let stampedRound = 1;
+  checkpoint.mergeCheckpoint(
+    taskId,
+    (cur) => {
+      const prev = (cur && cur.nubosloop) || {};
+      stampedRound = Number(prev.round) || 1;
+      const evidence = Array.isArray(prev.skill_evidence) ? prev.skill_evidence.slice() : [];
+      evidence.push({ round: stampedRound, skill: name, recorded_at: new Date().toISOString() });
+      return { nubosloop: safeAssign({}, prev, { skill_evidence: evidence }) };
+    },
+    cwd,
+  );
+  return { task_id: taskId, round: stampedRound, skill: name };
+}
+
+function recordExpectedSkills(taskId, skills, cwd) {
+  if (!TASK_ID_RE.test(taskId)) return null;
+  const names = (Array.isArray(skills) ? skills : []).map(_normSkillName).filter(Boolean);
+  if (names.length === 0) return { task_id: taskId, expected: [] };
+  let stampedRound = 1;
+  checkpoint.mergeCheckpoint(
+    taskId,
+    (cur) => {
+      const prev = (cur && cur.nubosloop) || {};
+      stampedRound = Number(prev.round) || 1;
+      const expect = Array.isArray(prev.skill_expect) ? prev.skill_expect.slice() : [];
+      expect.push({ round: stampedRound, skills: names, recorded_at: new Date().toISOString() });
+      return { nubosloop: safeAssign({}, prev, { skill_expect: expect }) };
+    },
+    cwd,
+  );
+  return { task_id: taskId, round: stampedRound, expected: names };
+}
+
+function _collectForRound(listVal, round, key) {
+  const out = [];
+  if (!Array.isArray(listVal)) return out;
+  for (const e of listVal) {
+    if (!e || (Number(e.round) || 1) !== round) continue;
+    const v = e[key];
+    if (Array.isArray(v)) out.push(...v);
+    else if (v) out.push(v);
+  }
+  return out;
+}
+
+// Pure: derive skill-bar findings from a checkpoint's nubosloop sub-object.
+function skillFindingsFromState(prevNubosloop, round, taskId) {
+  const prev = prevNubosloop || {};
+  const t = Number(round);
+  if (!Number.isFinite(t) || t < 1) return [];
+  const routed = Array.isArray(prev.skill_routed_rounds) ? prev.skill_routed_rounds : [];
+  if (routed.includes(t)) return [];
+  const expected = Array.from(new Set(_collectForRound(prev.skill_expect, t, 'skills')));
+  if (expected.length === 0) return [];
+  const acked = new Set(_collectForRound(prev.skill_evidence, t, 'skill'));
+  const missing = expected.filter((s) => !acked.has(s));
+  if (missing.length === 0) return [];
+  return [{
+    category: 'skill-bar-unconsulted',
+    severity: 'fail',
+    file: '-',
+    line: null,
+    remediation: 'Spawn was given Nubos skills as the quality bar for this task but did not consult '
+      + (missing.length === 1 ? 'it' : 'them') + ': [' + missing.join(', ') + ']. For each, `Read` '
+      + '`.claude/skills/<skill>/SKILL.md`, satisfy its "Verification bar" in the diff, then stamp '
+      + '`node np-tools.cjs skill-audit ack --task ' + taskId + ' --skill <skill>` — before editing.',
+    raw: { missing_skills: missing, expected_skills: expected },
+  }];
+}
+
+function markSkillFindingsRoutedInArray(routedRounds, round) {
+  const t = Number(round);
+  const arr = Array.isArray(routedRounds) ? routedRounds.slice() : [];
+  if (!Number.isFinite(t) || t < 1 || arr.includes(t)) return arr;
+  arr.push(t);
+  return arr;
+}
+
 function auditToolUse(taskId, agent, toolUseLog, cwd) {
   if (!TASK_ID_RE.test(taskId)) {
     throw new NubosPilotError(
@@ -232,6 +332,10 @@ module.exports = {
   auditToolUse,
   recordSearchEvidence,
   searchEvidenceForRound,
+  recordSkillEvidence,
+  recordExpectedSkills,
+  skillFindingsFromState,
+  markSkillFindingsRoutedInArray,
   readToolUseAudit,
   auditFindingsForRound,
   auditFindingsFromAudits,

package/lib/nubosloop-skill-audit.test.cjs

@@ -0,0 +1,98 @@
+'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 loop = require('./nubosloop.cjs');
+const checkpoint = require('./checkpoint.cjs');
+
+function _mkRoot() {
+  const r = fs.mkdtempSync(path.join(os.tmpdir(), 'np-skill-audit-'));
+  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;
+}
+const TID = 'M001-S001-T0001';
+function _nubosloop(r) { return (checkpoint.readCheckpoint(TID, r) || {}).nubosloop || {}; }
+
+test('SA-1: expected-but-unacked skill → skill-bar-unconsulted finding', () => {
+  const r = _mkRoot();
+  try {
+    checkpoint.startTask({ id: TID }, r);
+    loop.recordExpectedSkills(TID, ['np-secure-code-review', 'np-api-design'], r);
+    loop.recordSkillEvidence(TID, 'np-api-design', r); // only one acked
+    const findings = loop.skillFindingsFromState(_nubosloop(r), 1, TID);
+    assert.equal(findings.length, 1);
+    assert.equal(findings[0].category, 'skill-bar-unconsulted');
+    assert.deepEqual(findings[0].raw.missing_skills, ['np-secure-code-review']);
+  } finally { fs.rmSync(r, { recursive: true, force: true }); }
+});
+
+test('SA-2: all expected skills acked → no finding', () => {
+  const r = _mkRoot();
+  try {
+    checkpoint.startTask({ id: TID }, r);
+    loop.recordExpectedSkills(TID, ['np-api-design'], r);
+    loop.recordSkillEvidence(TID, 'np-api-design', r);
+    assert.equal(loop.skillFindingsFromState(_nubosloop(r), 1, TID).length, 0);
+  } finally { fs.rmSync(r, { recursive: true, force: true }); }
+});
+
+test('SA-3: no expected skills → no finding (skill block was correctly omitted)', () => {
+  const r = _mkRoot();
+  try {
+    checkpoint.startTask({ id: TID }, r);
+    assert.equal(loop.skillFindingsFromState(_nubosloop(r), 1, TID).length, 0);
+  } finally { fs.rmSync(r, { recursive: true, force: true }); }
+});
+
+test('SA-4: ack tolerates a SKILL.md path, not just a bare name', () => {
+  const r = _mkRoot();
+  try {
+    checkpoint.startTask({ id: TID }, r);
+    loop.recordExpectedSkills(TID, ['np-encryption'], r);
+    loop.recordSkillEvidence(TID, '.claude/skills/np-encryption/SKILL.md', r);
+    assert.equal(loop.skillFindingsFromState(_nubosloop(r), 1, TID).length, 0);
+  } finally { fs.rmSync(r, { recursive: true, force: true }); }
+});
+
+test('SA-5: routed round is not re-emitted (anti-spurious-loop)', () => {
+  const r = _mkRoot();
+  try {
+    checkpoint.startTask({ id: TID }, r);
+    loop.recordExpectedSkills(TID, ['np-secure-code-review'], r);
+    assert.equal(loop.skillFindingsFromState(_nubosloop(r), 1, TID).length, 1);
+    // simulate the loop marking round 1 routed
+    checkpoint.mergeCheckpoint(TID, (cur) => {
+      const prev = (cur && cur.nubosloop) || {};
+      return { nubosloop: Object.assign({}, prev, { skill_routed_rounds: [1] }) };
+    }, r);
+    assert.equal(loop.skillFindingsFromState(_nubosloop(r), 1, TID).length, 0);
+  } finally { fs.rmSync(r, { recursive: true, force: true }); }
+});
+
+test('SA-6: a skill finding routes to executor, never stuck (ROUTE_TABLE wired)', () => {
+  const r = _mkRoot();
+  try {
+    checkpoint.startTask({ id: TID }, r);
+    loop.recordExpectedSkills(TID, ['np-secure-code-review'], r);
+    const findings = loop.skillFindingsFromState(_nubosloop(r), 1, TID);
+    const evalRes = loop.evaluateLoop({ round: 1 }, [], { maxRounds: 3, auditFindings: findings });
+    assert.equal(evalRes.next_action, 'executor');
+    assert.equal(evalRes.stuck, false);
+    // and the merged finding kept its category (not downgraded to unknown→stuck)
+    assert.ok(evalRes.findings.some((f) => f.category === 'skill-bar-unconsulted' && f.route === 'executor'));
+  } finally { fs.rmSync(r, { recursive: true, force: true }); }
+});
+
+test('SA-7: markSkillFindingsRoutedInArray is idempotent', () => {
+  assert.deepEqual(loop.markSkillFindingsRoutedInArray([], 1), [1]);
+  assert.deepEqual(loop.markSkillFindingsRoutedInArray([1], 1), [1]);
+  assert.deepEqual(loop.markSkillFindingsRoutedInArray([1], 2), [1, 2]);
+});