nubos-pilot 0.8.2 → 0.9.0

package/agents/np-security-reviewer.md

@@ -15,6 +15,17 @@ You DO NOT propose patches. You DO NOT edit source. You report.
 If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
 </role>
 
+## Completeness Mandate
+
+This agent operates under [`templates/COMPLETENESS.md`](../templates/COMPLETENESS.md). The rules that bind this role:
+
+- **Rule 1 — Do the whole thing.** Every `files_modified` path across the milestone gets scanned against every applicable OWASP category. No "skipped because it looks fine".
+- **Rule 5 — Aim to genuinely impress.** Each Risk finding cites the file, the line, the OWASP category, the concrete attack vector, and the remediation. Vague findings are findings against you.
+- **Rule 8 — Never present a workaround when the real fix exists.** Risk-level findings recommend the real fix; only when the real fix is structurally blocked do you escalate to a `Defer` with an ADR reference.
+- **Rule 12 — Boil the ocean.** No silent skips. If a category is not applicable, declare so explicitly with one-line justification — that is part of the audit, not its absence.
+
+Refusal of any rule is a hard-stop. Surface the violation to the orchestrator verbatim and abort the spawn.
+
 ## Inputs
 
 | Input | Purpose | Typical path |

package/agents/np-verifier.md

@@ -18,6 +18,17 @@ You do NOT propose fixes. You do NOT edit source files. You classify each criter
 If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
 </role>
 
+## Completeness Mandate
+
+This agent operates under [`templates/COMPLETENESS.md`](../templates/COMPLETENESS.md). You are the final gate that decides whether the milestone's work is genuinely "done" — uphold the standard. The rules that bind this role:
+
+- **Rule 5 — Aim to genuinely impress.** Honest verdicts only. "Mostly Pass" is not a category. If you would mark Pass with a footnote, the footnote means Fail.
+- **Rule 10 — Test before shipping.** Pass requires deterministic evidence (commit SHA + test name + grep hit). Manual "I tried it once" evidence is Fail.
+- **Rule 11 — Ship the complete thing.** Every milestone success_criterion gets a verdict. No "skipped because trivial".
+- **Rule 12 — Boil the ocean.** If evidence is missing, the verdict is Fail with the missing-evidence pattern documented — not a polite Defer.
+
+Refusal of any rule is a hard-stop. Surface the violation to the orchestrator verbatim and abort the spawn.
+
 ## Inputs
 
 The orchestrator provides these in your prompt context. Read every path it hands you via `Read` — do not guess.

package/bin/check-completeness.cjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const AGENTS_DIR = path.join(REPO_ROOT, 'agents');
+const WORKFLOWS_DIR = path.join(REPO_ROOT, 'workflows');
+const COMPLETENESS_PATH = path.join(REPO_ROOT, 'templates', 'COMPLETENESS.md');
+
+const AGENT_HEADING_RE = /^##\s+Completeness Mandate\b/m;
+const WORKFLOW_HEADING_RE = /^##\s+Definition of Done\b/m;
+const COMPLETENESS_LINK_RE = /COMPLETENESS\.md/;
+
+function _listMd(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith('.md'))
+    .map((f) => path.join(dir, f))
+    .sort();
+}
+
+function checkAgents(rootDir) {
+  const dir = rootDir ? path.join(rootDir, 'agents') : AGENTS_DIR;
+  const out = [];
+  for (const file of _listMd(dir)) {
+    const body = fs.readFileSync(file, 'utf-8');
+    if (!AGENT_HEADING_RE.test(body)) {
+      out.push({ file, kind: 'agent', code: 'missing-completeness-mandate', message: 'Agent file lacks "## Completeness Mandate" heading.' });
+      continue;
+    }
+    if (!COMPLETENESS_LINK_RE.test(body)) {
+      out.push({ file, kind: 'agent', code: 'missing-completeness-link', message: 'Agent file mentions Mandate but does not link to templates/COMPLETENESS.md.' });
+    }
+  }
+  return out;
+}
+
+function checkWorkflows(rootDir) {
+  const dir = rootDir ? path.join(rootDir, 'workflows') : WORKFLOWS_DIR;
+  const out = [];
+  for (const file of _listMd(dir)) {
+    const body = fs.readFileSync(file, 'utf-8');
+    if (!WORKFLOW_HEADING_RE.test(body)) {
+      out.push({ file, kind: 'workflow', code: 'missing-definition-of-done', message: 'Workflow file lacks "## Definition of Done" heading.' });
+      continue;
+    }
+    if (!COMPLETENESS_LINK_RE.test(body)) {
+      out.push({ file, kind: 'workflow', code: 'missing-completeness-link', message: 'Workflow file mentions Definition of Done but does not link to templates/COMPLETENESS.md.' });
+    }
+  }
+  return out;
+}
+
+function checkCompletenessFile(rootDir) {
+  const file = rootDir ? path.join(rootDir, 'templates', 'COMPLETENESS.md') : COMPLETENESS_PATH;
+  const out = [];
+  if (!fs.existsSync(file)) {
+    out.push({ file, kind: 'doctrine', code: 'missing-completeness-file', message: 'templates/COMPLETENESS.md is missing.' });
+    return out;
+  }
+  const body = fs.readFileSync(file, 'utf-8');
+  // R5/nit from fifth review: capture IDs in one matchAll pass instead of
+  // matching twice (once with /g to find headings, once per heading to pull
+  // out the digit). The /g + matchAll pattern surfaces the capture group
+  // directly.
+  const ids = [];
+  for (const m of body.matchAll(/^###\s+(\d+)\.\s+/gm)) {
+    ids.push(Number(m[1]));
+  }
+  const expected = Array.from({ length: 12 }, (_, i) => i + 1);
+  if (ids.length !== 12 || ids.some((id, i) => id !== expected[i])) {
+    out.push({ file, kind: 'doctrine', code: 'doctrine-drift', message: 'templates/COMPLETENESS.md must contain exactly 12 sequentially numbered rule headings ("### 1." through "### 12.").', ids });
+  }
+  return out;
+}
+
+function checkAll(rootDir) {
+  const root = rootDir || REPO_ROOT;
+  const violations = [
+    ...checkCompletenessFile(root),
+    ...checkAgents(root),
+    ...checkWorkflows(root),
+  ];
+  return { violations, exitCode: violations.length ? 1 : 0 };
+}
+
+function main() {
+  const { violations, exitCode } = checkAll(process.argv[2] || REPO_ROOT);
+  if (violations.length) {
+    process.stderr.write('check-completeness: ' + violations.length + ' violation(s)\n');
+    for (const v of violations) {
+      process.stderr.write('  ' + v.file + '  [' + v.kind + ':' + v.code + ']  ' + v.message + '\n');
+    }
+  }
+  process.exit(exitCode);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  checkAgents,
+  checkWorkflows,
+  checkCompletenessFile,
+  checkAll,
+  REPO_ROOT,
+  AGENT_HEADING_RE,
+  WORKFLOW_HEADING_RE,
+  COMPLETENESS_LINK_RE,
+};

package/bin/check-completeness.test.cjs

@@ -0,0 +1,168 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const cc = require('./check-completeness.cjs');
+
+function _mkRoot() {
+  const r = fs.mkdtempSync(path.join(os.tmpdir(), 'cc-test-'));
+  fs.mkdirSync(path.join(r, 'agents'), { recursive: true });
+  fs.mkdirSync(path.join(r, 'workflows'), { recursive: true });
+  fs.mkdirSync(path.join(r, 'templates'), { recursive: true });
+  return r;
+}
+
+function _seedDoctrine(root, opts) {
+  const { count } = Object.assign({ count: 12 }, opts || {});
+  const headings = [];
+  for (let i = 1; i <= count; i += 1) headings.push('### ' + i + '. Rule ' + i + '\n\nText.');
+  fs.writeFileSync(
+    path.join(root, 'templates', 'COMPLETENESS.md'),
+    '# Doctrine\n\n' + headings.join('\n\n') + '\n',
+    'utf-8',
+  );
+}
+
+function _seedAgent(root, name, body) {
+  const fm = '---\nname: ' + name + '\ndescription: x\ntier: sonnet\ntools: Read\n---\n';
+  fs.writeFileSync(path.join(root, 'agents', name + '.md'), fm + (body || ''), 'utf-8');
+}
+
+function _seedWorkflow(root, name, body) {
+  fs.writeFileSync(path.join(root, 'workflows', name + '.md'), body || '# ' + name + '\n', 'utf-8');
+}
+
+test('CC-1: complete root → no violations', () => {
+  const r = _mkRoot();
+  try {
+    _seedDoctrine(r);
+    _seedAgent(r, 'np-foo', '## Completeness Mandate\n\nSee templates/COMPLETENESS.md.\n');
+    _seedWorkflow(r, 'foo', '# foo\n\n## Definition of Done\n\nSee templates/COMPLETENESS.md.\n');
+    const res = cc.checkAll(r);
+    assert.deepEqual(res.violations, []);
+    assert.equal(res.exitCode, 0);
+  } finally {
+    fs.rmSync(r, { recursive: true, force: true });
+  }
+});
+
+test('CC-2: agent missing Completeness Mandate heading → violation', () => {
+  const r = _mkRoot();
+  try {
+    _seedDoctrine(r);
+    _seedAgent(r, 'np-foo', 'No mandate here.\n');
+    const v = cc.checkAgents(r);
+    assert.equal(v.length, 1);
+    assert.equal(v[0].code, 'missing-completeness-mandate');
+    assert.ok(v[0].file.endsWith('np-foo.md'));
+  } finally {
+    fs.rmSync(r, { recursive: true, force: true });
+  }
+});
+
+test('CC-3: agent has heading but no COMPLETENESS.md link → violation', () => {
+  const r = _mkRoot();
+  try {
+    _seedDoctrine(r);
+    _seedAgent(r, 'np-foo', '## Completeness Mandate\n\nThis lacks the link.\n');
+    const v = cc.checkAgents(r);
+    assert.equal(v.length, 1);
+    assert.equal(v[0].code, 'missing-completeness-link');
+  } finally {
+    fs.rmSync(r, { recursive: true, force: true });
+  }
+});
+
+test('CC-4: workflow missing Definition of Done heading → violation', () => {
+  const r = _mkRoot();
+  try {
+    _seedDoctrine(r);
+    _seedWorkflow(r, 'foo', '# foo\n\nNo DoD.\n');
+    const v = cc.checkWorkflows(r);
+    assert.equal(v.length, 1);
+    assert.equal(v[0].code, 'missing-definition-of-done');
+  } finally {
+    fs.rmSync(r, { recursive: true, force: true });
+  }
+});
+
+test('CC-5: workflow has heading but no COMPLETENESS.md link → violation', () => {
+  const r = _mkRoot();
+  try {
+    _seedDoctrine(r);
+    _seedWorkflow(r, 'foo', '# foo\n\n## Definition of Done\n\nText only.\n');
+    const v = cc.checkWorkflows(r);
+    assert.equal(v.length, 1);
+    assert.equal(v[0].code, 'missing-completeness-link');
+  } finally {
+    fs.rmSync(r, { recursive: true, force: true });
+  }
+});
+
+test('CC-6: doctrine file missing → violation', () => {
+  const r = _mkRoot();
+  try {
+    const v = cc.checkCompletenessFile(r);
+    assert.equal(v.length, 1);
+    assert.equal(v[0].code, 'missing-completeness-file');
+  } finally {
+    fs.rmSync(r, { recursive: true, force: true });
+  }
+});
+
+test('CC-7: doctrine has only 11 rules → drift violation', () => {
+  const r = _mkRoot();
+  try {
+    _seedDoctrine(r, { count: 11 });
+    const v = cc.checkCompletenessFile(r);
+    assert.equal(v.length, 1);
+    assert.equal(v[0].code, 'doctrine-drift');
+  } finally {
+    fs.rmSync(r, { recursive: true, force: true });
+  }
+});
+
+test('CC-8: doctrine with skipped numbering (1,2,4,…) → drift', () => {
+  const r = _mkRoot();
+  try {
+    fs.writeFileSync(
+      path.join(r, 'templates', 'COMPLETENESS.md'),
+      '### 1. A\n\n### 2. B\n\n### 4. C\n\n### 5. D\n\n### 6. E\n\n### 7. F\n\n### 8. G\n\n### 9. H\n\n### 10. I\n\n### 11. J\n\n### 12. K\n\n### 13. L\n',
+      'utf-8',
+    );
+    const v = cc.checkCompletenessFile(r);
+    assert.equal(v.length, 1);
+    assert.equal(v[0].code, 'doctrine-drift');
+  } finally {
+    fs.rmSync(r, { recursive: true, force: true });
+  }
+});
+
+test('CC-9: real nubos-pilot repo passes — every agent + workflow + doctrine compliant', () => {
+  const res = cc.checkAll();
+  if (res.violations.length) {
+    const lines = res.violations
+      .map((v) => '  ' + v.file + ' [' + v.code + '] ' + v.message)
+      .join('\n');
+    assert.fail('Real-tree completeness violations:\n' + lines);
+  }
+  assert.equal(res.exitCode, 0);
+});
+
+test('CC-10: CLI exits 1 on a sandbox missing the doctrine', () => {
+  const { spawnSync } = require('node:child_process');
+  const r = _mkRoot();
+  try {
+    const result = spawnSync(process.execPath, [path.join(__dirname, 'check-completeness.cjs'), r], {
+      encoding: 'utf-8',
+    });
+    assert.equal(result.status, 1);
+    assert.match(result.stderr, /violation/i);
+  } finally {
+    fs.rmSync(r, { recursive: true, force: true });
+  }
+});

package/bin/np-tools/_args.cjs

@@ -0,0 +1,63 @@
+'use strict';
+
+const { NubosPilotError } = require('../../lib/core.cjs');
+
+function getFlag(rest, name) {
+  const idx = rest.indexOf(name);
+  return idx !== -1 ? rest[idx + 1] : undefined;
+}
+
+function getJsonFlag(rest, name, missingCode, hint) {
+  const raw = getFlag(rest, name);
+  if (raw === undefined) {
+    throw new NubosPilotError(
+      missingCode,
+      name + ' is required',
+      hint ? { hint } : {},
+    );
+  }
+  try { return JSON.parse(raw); }
+  catch (err) {
+    throw new NubosPilotError(
+      missingCode + '-invalid-json',
+      name + ' must be valid JSON',
+      { cause: err && err.message },
+    );
+  }
+}
+
+function optionalJsonFlag(rest, name) {
+  const raw = getFlag(rest, name);
+  if (raw === undefined) return undefined;
+  try { return JSON.parse(raw); }
+  catch (err) {
+    throw new NubosPilotError(
+      'arg-invalid-json',
+      name + ' must be valid JSON when provided',
+      { cause: err && err.message, flag: name },
+    );
+  }
+}
+
+function assertMatch(value, re, code, label) {
+  if (typeof value !== 'string' || !re.test(value)) {
+    throw new NubosPilotError(
+      code,
+      label + ' must match ' + re.toString() + ' (got ' + JSON.stringify(value) + ')',
+      { value },
+    );
+  }
+}
+
+function assertOptionalMatch(value, re, code, label) {
+  if (value == null) return;
+  assertMatch(value, re, code, label);
+}
+
+module.exports = {
+  getFlag,
+  getJsonFlag,
+  optionalJsonFlag,
+  assertMatch,
+  assertOptionalMatch,
+};

package/bin/np-tools/_commands.cjs

@@ -77,6 +77,18 @@ const COMMANDS = [
   { name: 'context-stats',           category: 'Utility', description: 'Aggregated context-budget stats (file counts + bytes per group, knowledge-index size)', description_de: 'Aggregierte Context-Budget-Stats (Dateien/Bytes pro Gruppe, Knowledge-Index-Größe)' },
   { name: 'session-snapshot-write',  category: 'Utility', description: 'Capture session snapshot (current_task + recent commits + open handoffs) for resume', description_de: 'Erfasst Session-Snapshot (current_task + letzte Commits + offene Handoffs) für Resume' },
   { name: 'session-snapshot-read',   category: 'Utility', description: 'Print last session snapshot as JSON', description_de: 'Gibt letzten Session-Snapshot als JSON aus' },
+
+  { name: 'loop-state-read',         category: 'Execution', description: 'Read the per-task Nubosloop state from the checkpoint (round, last_action, findings)', description_de: 'Liest Nubosloop-State pro Task aus dem Checkpoint (round, last_action, findings)' },
+  { name: 'loop-state-record',       category: 'Execution', description: 'Atomically merge a partial Nubosloop state update into the task checkpoint', description_de: 'Mergt einen partiellen Nubosloop-State-Update atomar in den Task-Checkpoint' },
+  { name: 'loop-evaluate',           category: 'Execution', description: 'Run evaluateLoop over critic outputs JSON; emit next_action + findings + routing', description_de: 'Führt evaluateLoop auf Critic-Outputs (JSON) aus; gibt next_action + Findings + Routing aus' },
+  { name: 'loop-preflight',          category: 'Execution', description: 'Per-task pre-flight cache lookup (ADR-0010 Step 1) — short-circuits the Researcher-Schwarm on hit', description_de: 'Per-Task Pre-Flight-Cache-Lookup (ADR-0010 Step 1) — short-circuited den Researcher-Schwarm bei Treffer' },
+  { name: 'loop-run-round',          category: 'Execution', description: 'Drive the per-task Nubosloop state machine — phases: preflight | post-executor | post-critics | commit | stuck', description_de: 'Treibt die Per-Task Nubosloop-State-Machine — Phasen: preflight | post-executor | post-critics | commit | stuck' },
+  { name: 'loop-audit-tool-use',     category: 'Execution', description: 'Record/read the tool-use audit per spawn (Completeness Rule 9 mechanical check)', description_de: 'Tool-use Audit pro Spawn schreiben/lesen (Completeness Rule 9 mechanische Prüfung)' },
+  { name: 'loop-stuck',              category: 'Execution', description: 'Mark a task as stuck (writes loop-state + flips checkpoint status to stuck)', description_de: 'Markiert Task als stuck (schreibt Loop-State + setzt Checkpoint-Status auf stuck)' },
+  { name: 'loop-metrics',            category: 'Utility',   description: 'Aggregate Nubosloop telemetry across all checkpoints (commits, stuck, route distribution)', description_de: 'Aggregiert Nubosloop-Telemetrie über alle Checkpoints (Commits, Stuck, Routing)' },
+  { name: 'learning-log',            category: 'Execution', description: 'Persist a learning to the local store (or MCP adapter when configured)', description_de: 'Persistiert ein Learning im lokalen Store (oder MCP-Adapter falls konfiguriert)' },
+  { name: 'learning-match',          category: 'Utility',   description: 'Query the learnings store for cached patterns matching a free-text query', description_de: 'Fragt den Learnings-Store nach Cached-Patterns ab' },
+  { name: 'learning-list',           category: 'Utility',   description: 'List learnings sorted by occurrence (most-used first)', description_de: 'Listet Learnings sortiert nach Occurrence (meistgenutzt zuerst)' },
 ];
 
 const CATEGORY_LABELS = Object.freeze({

package/bin/np-tools/checkpoint.cjs

@@ -6,7 +6,7 @@ const {
   readCheckpoint,
 } = require('../../lib/checkpoint.cjs');
 
-const _VALID_STATUSES = new Set(['in-progress', 'verifying', 'pre-commit', 'done']);
+const _VALID_STATUSES = new Set(['in-progress', 'verifying', 'pre-commit', 'done', 'stuck']);
 
 function _parseFlags(rest) {
   const flags = {};

package/bin/np-tools/dashboard.test.cjs

@@ -76,5 +76,5 @@ test('CLI-DB-6: --json snapshot stays language-neutral', () => {
   const code = subcmd.run(['--json'], { cwd: root, stdout: cap.stub });
   assert.equal(code, 0);
   const parsed = JSON.parse(cap.get());
-  assert.deepEqual(Object.keys(parsed), ['milestones']);
+  assert.deepEqual(Object.keys(parsed).sort(), ['milestones', 'nubosloop']);
 });

package/bin/np-tools/doctor.cjs

@@ -336,6 +336,158 @@ function _checkMilestoneLayout(projectRoot) {
   return issues;
 }
 
+const NUBOSLOOP_CRITICS = ['np-critic-style', 'np-critic-tests', 'np-critic-acceptance'];
+
+function _checkNubosloopCritics(projectRoot) {
+  const issues = [];
+  const scope = _readScope(projectRoot);
+  const payloadDir = _payloadDirFor(projectRoot, scope);
+  const agentsDir = path.join(payloadDir, 'agents');
+  if (!fs.existsSync(agentsDir)) {
+    issues.push({
+      id: 'nubosloop-agents-dir-missing',
+      severity: 'warn',
+      fixable: 'reinstall',
+      details: {
+        expected: agentsDir,
+        hint: 'run `npx nubos-pilot update` to refresh the payload (Critic-Schwarm agents ship as part of the payload).',
+      },
+    });
+    return issues;
+  }
+  for (const agent of NUBOSLOOP_CRITICS) {
+    const agentPath = path.join(agentsDir, agent + '.md');
+    if (!fs.existsSync(agentPath)) {
+      issues.push({
+        id: 'nubosloop-critic-missing',
+        severity: 'warn',
+        fixable: 'reinstall',
+        details: {
+          agent,
+          expected: agentPath,
+          hint: 'run `npx nubos-pilot update` to refresh the payload.',
+        },
+      });
+    }
+  }
+  return issues;
+}
+
+function _checkNubosloopKnowledgeStore(projectRoot) {
+  const issues = [];
+  const stateDir = path.join(projectRoot, '.nubos-pilot');
+  if (!fs.existsSync(stateDir)) return issues;
+  const learningsPath = path.join(stateDir, 'knowledge', 'learnings.json');
+  if (!fs.existsSync(learningsPath)) {
+    issues.push({
+      id: 'nubosloop-knowledge-store-missing',
+      severity: 'info',
+      fixable: 'auto',
+      details: {
+        expected: learningsPath,
+        hint: 'auto-created on first Nubosloop commit; safe to ignore on a fresh project.',
+      },
+    });
+    return issues;
+  }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(learningsPath, 'utf-8'));
+    if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.learnings)) {
+      issues.push({
+        id: 'nubosloop-knowledge-store-corrupt',
+        severity: 'warn',
+        fixable: 'manual',
+        details: {
+          path: learningsPath,
+          hint: 'expected JSON with `version` and `learnings[]`; remove or restore from a backup.',
+        },
+      });
+    }
+  } catch (err) {
+    issues.push({
+      id: 'nubosloop-knowledge-store-corrupt',
+      severity: 'warn',
+      fixable: 'manual',
+      details: { path: learningsPath, cause: err && err.message },
+    });
+  }
+  return issues;
+}
+
+function _checkNubosloopConfig(projectRoot) {
+  const issues = [];
+  const cfgPath = path.join(projectRoot, '.nubos-pilot', 'config.json');
+  if (!fs.existsSync(cfgPath)) return issues;
+  let cfg;
+  try { cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf-8')); } catch { return issues; }
+  const swarm = cfg && cfg.swarm;
+  const adapter = swarm && swarm.knowledge_adapter;
+  if (adapter && adapter !== 'local' && adapter !== 'mcp') {
+    issues.push({
+      id: 'nubosloop-knowledge-adapter-invalid',
+      severity: 'warn',
+      fixable: 'manual',
+      details: {
+        value: adapter,
+        supported: ['local', 'mcp'],
+        hint: 'set swarm.knowledge_adapter to "local" or "mcp" — falls back to "local" silently otherwise.',
+      },
+    });
+  }
+  if (adapter === 'mcp') {
+    issues.push({
+      id: 'nubosloop-knowledge-adapter-mcp-pending',
+      severity: 'info',
+      fixable: 'manual',
+      details: {
+        hint: 'mcp adapter is configured but the transport ships in Phase 7/8; matchExistingLearning will throw mcp-adapter-not-implemented until then.',
+      },
+    });
+  }
+  const loop = cfg && cfg.loop;
+  if (loop && loop.maxRounds != null) {
+    const n = Number(loop.maxRounds);
+    if (!Number.isFinite(n) || n < 1 || n > 10) {
+      issues.push({
+        id: 'nubosloop-maxRounds-out-of-range',
+        severity: 'warn',
+        fixable: 'manual',
+        details: { value: loop.maxRounds, expected_range: '[1, 10]' },
+      });
+    }
+  }
+  return issues;
+}
+
+function _checkOrphanTmpFiles(projectRoot) {
+  const issues = [];
+  const stateDir = path.join(projectRoot, '.nubos-pilot');
+  const dirs = [
+    stateDir,
+    path.join(stateDir, 'checkpoints'),
+    path.join(stateDir, 'knowledge'),
+    path.join(stateDir, 'state'),
+  ];
+  const { sweepStaleTmpFiles } = require('../../lib/core.cjs');
+  for (const d of dirs) {
+    let result;
+    try { result = sweepStaleTmpFiles(d, { olderThanMs: 60 * 60 * 1000 }); }
+    catch { continue; }
+    if (!result || !Array.isArray(result.swept) || result.swept.length === 0) continue;
+    issues.push({
+      id: 'orphan-tmp-files-cleaned',
+      severity: 'info',
+      fixable: 'auto',
+      details: {
+        dir: d,
+        cleaned: result.swept.length,
+        hint: 'Orphaned tmp files (>1h old) from a hard-killed process were swept.',
+      },
+    });
+  }
+  return issues;
+}
+
 function _audit(projectRoot) {
   const scope = _readScope(projectRoot);
   const payloadDir = _payloadDirFor(projectRoot, scope);
@@ -349,6 +501,10 @@ function _audit(projectRoot) {
   issues.push(..._checkAskUserBroken());
   issues.push(..._checkCodebaseDocs(projectRoot));
   issues.push(..._checkMilestoneLayout(projectRoot));
+  issues.push(..._checkNubosloopCritics(projectRoot));
+  issues.push(..._checkNubosloopKnowledgeStore(projectRoot));
+  issues.push(..._checkNubosloopConfig(projectRoot));
+  issues.push(..._checkOrphanTmpFiles(projectRoot));
   return { issues, _codexContent: codex.content };
 }
 

package/bin/np-tools/doctor.test.cjs

@@ -139,3 +139,69 @@ test('DOC-5: no tbd flag after prose applied', async () => {
   const tbd = out.issues.find((i) => i.id === 'codebase-tbd-docs');
   assert.ok(!tbd, 'expected no codebase-tbd-docs');
 });
+
+test('DOC-7: flags nubosloop-knowledge-store-corrupt when JSON is malformed', async () => {
+  const root = makeSandbox();
+  fs.writeFileSync(path.join(root, 'src.js'), 'export function a(){}');
+  scanCodebase.run([], { cwd: root, stdout: captureStdout().stub });
+  fs.mkdirSync(path.join(root, '.nubos-pilot', 'knowledge'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.nubos-pilot', 'knowledge', 'learnings.json'), 'NOT JSON');
+
+  const cap = captureStdout();
+  await doctor.run([], { cwd: root, stdout: cap.stub, stderr: cap.stub, askUser: async () => ({ value: false }) });
+  const out = cap.json();
+  const ids = out.issues.map((i) => i.id);
+  assert.ok(ids.includes('nubosloop-knowledge-store-corrupt'));
+});
+
+test('DOC-8: flags nubosloop-knowledge-adapter-invalid for unsupported adapter', async () => {
+  const root = makeSandbox();
+  fs.writeFileSync(path.join(root, 'src.js'), 'export function a(){}');
+  scanCodebase.run([], { cwd: root, stdout: captureStdout().stub });
+  fs.writeFileSync(
+    path.join(root, '.nubos-pilot', 'config.json'),
+    JSON.stringify({ swarm: { knowledge_adapter: 'pinecone' } }),
+  );
+  const cap = captureStdout();
+  await doctor.run([], { cwd: root, stdout: cap.stub, stderr: cap.stub, askUser: async () => ({ value: false }) });
+  const out = cap.json();
+  const ids = out.issues.map((i) => i.id);
+  assert.ok(ids.includes('nubosloop-knowledge-adapter-invalid'));
+});
+
+test('DOC-9: flags nubosloop-maxRounds-out-of-range when value > 10', async () => {
+  const root = makeSandbox();
+  fs.writeFileSync(path.join(root, 'src.js'), 'export function a(){}');
+  scanCodebase.run([], { cwd: root, stdout: captureStdout().stub });
+  fs.writeFileSync(
+    path.join(root, '.nubos-pilot', 'config.json'),
+    JSON.stringify({ loop: { maxRounds: 99 } }),
+  );
+  const cap = captureStdout();
+  await doctor.run([], { cwd: root, stdout: cap.stub, stderr: cap.stub, askUser: async () => ({ value: false }) });
+  const out = cap.json();
+  const ids = out.issues.map((i) => i.id);
+  assert.ok(ids.includes('nubosloop-maxRounds-out-of-range'));
+});
+
+test('DOC-10: clean config produces no nubosloop issues', async () => {
+  const root = makeSandbox();
+  fs.writeFileSync(path.join(root, 'src.js'), 'export function a(){}');
+  scanCodebase.run([], { cwd: root, stdout: captureStdout().stub });
+  fs.mkdirSync(path.join(root, '.nubos-pilot', 'knowledge'), { recursive: true });
+  fs.writeFileSync(
+    path.join(root, '.nubos-pilot', 'knowledge', 'learnings.json'),
+    JSON.stringify({ version: 1, learnings: [] }),
+  );
+  fs.writeFileSync(
+    path.join(root, '.nubos-pilot', 'config.json'),
+    JSON.stringify({ loop: { maxRounds: 3 }, swarm: { knowledge_adapter: 'local' } }),
+  );
+  const cap = captureStdout();
+  await doctor.run([], { cwd: root, stdout: cap.stub, stderr: cap.stub, askUser: async () => ({ value: false }) });
+  const out = cap.json();
+  const ids = out.issues.map((i) => i.id);
+  assert.ok(!ids.some((id) => id.startsWith('nubosloop-knowledge-store-corrupt')));
+  assert.ok(!ids.some((id) => id.startsWith('nubosloop-knowledge-adapter-invalid')));
+  assert.ok(!ids.some((id) => id.startsWith('nubosloop-maxRounds')));
+});