nubos-pilot 1.2.2 → 1.2.4

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

package/lib/nubosloop.cjs

@@ -24,6 +24,7 @@ const ROUTE_TABLE = {
   'lint-violation': 'executor',
   'critic-error': 'stuck',
   'rule-9-violation': 'executor',
+  'skill-bar-unconsulted': 'executor',
   'missing-test': 'executor',
   'edge-case-gap': 'executor',
   'weak-assertion': 'executor',
@@ -311,6 +312,10 @@ const {
   auditToolUse,
   recordSearchEvidence,
   searchEvidenceForRound,
+  recordSkillEvidence,
+  recordExpectedSkills,
+  skillFindingsFromState,
+  markSkillFindingsRoutedInArray,
   readToolUseAudit,
   auditFindingsForRound,
   auditFindingsFromAudits,
@@ -502,6 +507,10 @@ module.exports = {
   auditToolUse,
   recordSearchEvidence,
   searchEvidenceForRound,
+  recordSkillEvidence,
+  recordExpectedSkills,
+  skillFindingsFromState,
+  markSkillFindingsRoutedInArray,
   readToolUseAudit,
   auditFindingsForRound,
   auditFindingsFromAudits,

package/lib/tier-classify.cjs

@@ -0,0 +1,67 @@
+'use strict';
+
+const { VALID_TIERS } = require('./model-profiles.cjs');
+
+// ADR-0013: a tier is a routing/meta property derived from OBSERVABLE task
+// signals (files touched + risk keywords), never invented from implementation
+// detail. classifyTier is advisory — the planner remains the decider; this
+// helper only makes that decision evidence-based. Output is deterministic
+// (no clock, no randomness) so a given task always classifies the same way.
+
+const RISK_RE = /\b(auth|authn|authz|authoriz\w*|login|crypto|encrypt\w*|decrypt\w*|password|secret|credential|token|jwt|oauth|saml|session|payment|billing|invoice|permission|role|access[\s-]?control|migrat\w*|schema)\b/i;
+const ARCH_RE = /\b(architect\w*|cross[\s-]?cutting|multi[\s-]?module|redesign|breaking[\s-]?change|public[\s-]?api|contract|interface|protocol|state[\s-]?machine|concurren\w*|distributed|orchestrat\w*)\b/i;
+const TRIVIAL_RE = /\b(typo|comment|rename|docs?|readme|changelog|copy(?:writing)?|wording|spelling|version[\s-]?bump|bump[\s-]?version|lint|format(?:ting)?|whitespace|config[\s-]?value|constant|string[\s-]?literal)\b/i;
+
+const SIZE_TO_TIER = Object.freeze({ trivial: 'haiku', standard: 'sonnet', large: 'opus' });
+
+const LARGE_FILE_THRESHOLD = 6;
+
+function _text(name, desc) {
+  return [String(name || ''), String(desc || '')].join(' ');
+}
+
+/**
+ * @param {{files_modified?: string[], name?: string, desc?: string}} task
+ * @returns {{tier: string, size: string, rationale: string, signals: {file_count: number, risk: boolean, arch: boolean, trivial: boolean}}}
+ */
+function classifyTier(task) {
+  const t = task || {};
+  const files = Array.isArray(t.files_modified) ? t.files_modified : [];
+  const fileCount = files.length;
+  const haystack = _text(t.name, t.desc) + ' ' + files.join(' ');
+
+  const risk = RISK_RE.test(haystack);
+  const arch = ARCH_RE.test(haystack);
+  const trivial = TRIVIAL_RE.test(haystack);
+
+  let size;
+  let rationale;
+  if (risk) {
+    size = 'large';
+    rationale = 'security/data-sensitive surface (auth, crypto, secrets, or migration) — escalate to the strongest tier';
+  } else if (arch || fileCount >= LARGE_FILE_THRESHOLD) {
+    size = 'large';
+    rationale = arch
+      ? 'architectural / cross-cutting change — invariants span multiple units'
+      : 'broad change touching ' + fileCount + ' files — cross-file invariants likely';
+  } else if (fileCount <= 1 && trivial) {
+    size = 'trivial';
+    rationale = 'single-file mechanical edit (docs/rename/format/config) — narrow, low-risk';
+  } else {
+    size = 'standard';
+    rationale = 'ordinary single-concern implementation';
+  }
+
+  return {
+    tier: SIZE_TO_TIER[size],
+    size,
+    rationale,
+    signals: { file_count: fileCount, risk, arch, trivial },
+  };
+}
+
+function isValidTier(tier) {
+  return VALID_TIERS.includes(tier);
+}
+
+module.exports = { classifyTier, isValidTier, SIZE_TO_TIER, LARGE_FILE_THRESHOLD };