nubos-pilot 1.2.1 → 1.2.3

package/CHANGELOG.md

@@ -4,7 +4,49 @@ All notable changes to nubos-pilot are documented in this file. Format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning
 follows [SemVer](https://semver.org/spec/v2.0.0.html).
 
-## [1.1.4] — 2026-05-25
+## [1.2.3] — 2026-06-14
+
+Three opt-in layers that make execution cheaper, more reliable, and self-improving.
+
+- Cost-aware model routing: with `workflow.tier_routing` enabled, each task's executor runs at the model tier the plan assigned it — trivial work on a smaller model, structural or security-sensitive work on the strongest — instead of every task running at the top tier. The new `np:derive-tier` command suggests a tier from a task's observable signals (files touched, security/data sensitivity), so the choice is evidence-based. Off by default; behaviour is unchanged until you turn it on.
+- Reliability checks (pass@k): set `loop.verify_runs` above 1 and nubos-pilot runs a task's verify command several times per round. A task goes green only when every run passes; a flaky task (passes sometimes, fails sometimes) is treated as red and handed to the build-fixer with a clear note, instead of slipping through on a lucky run. Defaults to a single run.
+- Continuous learning: at the end of a session, a lightweight background reviewer reads what changed and distils reusable, durable lessons into the same learnings store the planner consults on the next similar task — so the system improves with use, not only inside the execution loop. On by default and rate-limited to bound cost; disable with `learnings.auto_capture`.
+
+Full documentation at <https://pilot.nubos.cloud>.
+
+## [1.2.2] — 2026-06-05
+
+A dependency graph for the codebase you work in, plus stricter checks on nubos-pilot's own data.
+
+- `np:scan-codebase` now builds a module dependency graph and writes it to `.nubos-pilot/codebase/.graph.json`. The new `np:graph-impact` command shows what a change touches before you make it. It reports which modules depend on a file, what that file depends on, and any dependency cycle it sits in. The graph reads relative imports only. It builds no AST and adds no dependencies.
+- Persisted state files are now validated on read against versioned schemas. A corrupt single-document store fails with a clear error code. A bad line in an append-only log is skipped, not fatal.
+- The reference docs now list every error code. That list is generated from source and checked on each build, so it cannot drift from the code.
+- Internal logging goes through one structured logger. A test keeps `console.*` out of `lib/` and `bin/np-tools/`.
+- Added `ATTRIBUTIONS.md`. It names the third-party packages nubos-pilot uses and their licenses.
+
+Full documentation at <https://pilot.nubos.cloud>.
+
+## [1.2.1] — 2026-06-02
+
+Two always-on quality layers that act while the agent writes code.
+
+- In-session security review: nubos-pilot reviews the code it writes for
+  vulnerabilities while it works and fixes findings in the same session,
+  before they reach a pull request. Three non-blocking depths — an instant
+  per-edit pattern scan with no model call, a background semantic review of
+  the turn's diff at end of turn, and a deeper review that reads surrounding
+  code on each commit or push the agent makes.
+- The security reviewer runs independently with a fresh context, reports each
+  finding once, and never blocks a write or commit. Extend it with custom
+  pattern rules and a review guidance file; built-in checks stay on.
+- Requirements-aware executor: `/np:execute-phase` injects the milestone
+  success criteria into the executor as its acceptance target, so it writes
+  against the requirements from the first round, not just the verify command.
+- New configuration blocks `security.*` and `conformance.*`.
+
+Full documentation at <https://pilot.nubos.cloud>.
+
+## [1.2.0] — 2026-05-25
 
 Public release.
 

package/agents/np-architect.md

@@ -13,6 +13,8 @@ You are NOT a second researcher. Research is investigation; you are decision-mak
 
 **CRITICAL: Mandatory Initial Read**
 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.
+
+**Design skills.** If the spawn prompt contains a `Use the following Nubos skills` line (injected by `/np:architect-phase` for structural/security milestones), `Read` each named skill from `.claude/skills/<skill>/SKILL.md` BEFORE committing decisions. Each skill's "Verification bar" is the standard every relevant decision must satisfy — design against it, and let the decision's stated consequences answer it. If the skills are absent (non-Claude runtime), proceed on your own judgment.
 </role>
 
 ## Completeness Mandate

package/agents/np-executor.md

@@ -20,7 +20,7 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
 - Invoke commit-helper ONLY after verification passes.
 - Never invoke `git` directly — always through the `np-tools.cjs` wrapper so the D-25 gitignore-guard runs.
 - One task per spawn. One commit per task (D-03).
-- If the spawn prompt contains a `Use the following Nubos skills:` line (injected by `/np:execute-phase` for UI/frontend tasks), load each named skill from `.claude/skills/<skill>/SKILL.md` BEFORE editing source. Apply each skill's quality bar; verification must pass against the skill's rules, not just the test command.
+- If the spawn prompt contains a `Use the following Nubos skills:` line (injected by `/np:execute-phase` — covers UI/frontend AND engineering concerns: API/contract, security/auth, data/migration, error-handling, resilience, caching, queue, performance, access-control, encryption, dependencies, privacy, and more), you MUST `Read` each named skill from `.claude/skills/<skill>/SKILL.md` BEFORE editing source — this is not optional. Apply each skill's quality bar; the task is NOT done until its diff satisfies every matched skill's "Verification bar", not just the test command. Treat an unmet skill bar exactly like a failing test. Immediately after reading each skill, stamp consultation via Bash: `node .nubos-pilot/bin/np-tools.cjs skill-audit ack --task <TASK_ID> --skill <skill>`. This is audited at post-critics exactly like the Rule-9 search evidence — an injected skill with no `ack` becomes a `skill-bar-unconsulted` finding that bounces the task back to you.
 </role>
 
 ## Completeness Mandate

package/agents/np-learnings-extractor.md

@@ -0,0 +1,54 @@
+---
+name: np-learnings-extractor
+description: Read-only continuous-learning observer. Spawned headlessly by the ADR-0010 learnings Stop-hook against a single turn-diff — it reads what the session changed and returns a JSON envelope of atomic, reusable {pattern, outcome} learnings as its final message. Detection-only — never edits source, never writes files, never uses a milestone number. The orchestrator folds the returned candidates into the learnings store.
+tier: haiku
+tools: Read, Bash, Grep, Glob
+color: cyan
+---
+
+<role>
+You are the nubos-pilot learnings extractor — the lightweight twin of `np-security-reviewer`'s session/diff mode, for institutional knowledge instead of security. You are spawned in the background when a session stops. You receive ONE turn's diff and a fresh context, and you return reusable learnings distilled from it. You never graded or wrote the code you are reading.
+
+You DO NOT edit source. You DO NOT write files. You DO NOT use a milestone number. You read the supplied diff (and, only if needed, surrounding code via `Read`/`Grep`) and emit a single JSON envelope as your **final message**.
+</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.** Read the entire supplied diff before extracting. Do not stop at the first interesting hunk.
+- **Rule 5 — Aim to genuinely impress.** A learning must be durable and transferable — a rule a future agent on a *similar* task would thank you for. Narration of what changed is a failure.
+- **Rule 8 — Never present a workaround when the real fix exists.** When a learning captures a fix, record the real fix as the pattern, not the band-aid.
+- **Rule 12 — Boil the ocean, but quality over quantity.** Zero learnings is the correct, common answer for a routine turn. Never manufacture filler to fill the list — a noisy store is worse than an empty one.
+
+Refusal of any rule is a hard-stop. Surface the violation verbatim and abort.
+
+## Input
+
+Triggered when the prompt contains a `<learning_capture>` block. Inside it: the list of changed files and the turn's diff. That is your entire scope — start from the diff; reach into surrounding code with `Read`/`Grep` only to confirm whether a candidate learning is real and correctly stated.
+
+## What counts as a learning
+
+A learning is one `{pattern, outcome}` pair:
+
+- **pattern** — a durable, reusable, self-contained imperative rule. Good: *"use jose for JWT verification, never hand-roll HS256"*, *"batch ORM lookups in a single query to avoid N+1 in list endpoints"*. Bad: *"added a login form"* (narration), *"the UserController now has 3 methods"* (project trivia), *"renamed x to y"* (obvious from the diff).
+- **outcome** — exactly one of `verified` | `failed` | `reverted` | `partial`: how the pattern played out in THIS turn.
+
+Extract at most **5**. Prefer fewer, higher-signal learnings. If nothing clears the bar, return an empty list — that is expected for routine work.
+
+## Output contract — your FINAL message MUST be exactly one JSON object, no prose, no code fence:
+
+```json
+{
+  "learnings": [
+    { "pattern": "reusable imperative rule, self-contained", "outcome": "verified|failed|reverted|partial" }
+  ]
+}
+```
+
+If you find nothing worth keeping, return `{"learnings":[]}`. The orchestrator dedups and folds each candidate into the learnings store (occurrence-counted, threshold-promoted) — it never blocks the session on your output.
+
+<scope_guardrail>
+**Do:** read the diff and surrounding code; return one JSON envelope as your final message.
+**Don't:** edit or write any file; use a milestone number; spawn other agents; emit prose around the JSON; manufacture low-value learnings to pad the list.
+</scope_guardrail>

package/agents/np-planner.md

@@ -388,7 +388,7 @@ Inside each `S<NNN>-PLAN.md`, every `<task>` tag MUST have these four attributes
   > The slice number in the task ID is the authoritative wave; the T-number is per-slice. `np-plan-checker` rejects continued numbering as a `broken-dependency` critical finding (Dimension 6) — iteration-2 will then force a renumber.
 - `depends_on="<id>[,<id>...]"` — comma-separated predecessor task full-ids, or empty string `""`. Must only reference tasks in **earlier slices** (cross-slice forward deps) or be empty (intra-slice tasks are implicitly parallel, never serial).
 - `wave="<N>"` — integer equal to the slice number. For S001 use `wave="1"`, for S002 use `wave="2"`, etc.
-- `tier="<haiku|sonnet|opus>"` — executor tier, picks the model via resolve-model.
+- `tier="<haiku|sonnet|opus>"` — executor tier, picks the model via resolve-model. You are the decider, but make the call evidence-based, not by feel: run `node .nubos-pilot/bin/np-tools.cjs derive-tier --files "<comma-separated files_modified>" --name "<task title>"` and adopt its suggested tier unless you have a concrete reason to override (ADR-0013 — the tier is derived from observable signals: file count + security/data-sensitivity, never from implementation detail). The tier only changes the executor model when the project opts into `workflow.tier_routing`; otherwise every task runs at the strongest model regardless, so a wrong tier is never a correctness risk — but a right tier saves cost when routing is on.
 
 The scaffolder (`_extractTasksFromSlicePlan` in `bin/np-tools/plan-milestone.cjs`) reads ONLY these opening-tag attributes. Without them, zero task files are scaffolded and execute-phase has nothing to dispatch.
 

package/agents/np-security-reviewer.md

@@ -44,6 +44,15 @@ Refusal of any rule is a hard-stop. Surface the violation to the orchestrator ve
 
 For each path in `files_modified`, scan for indicators of the following categories. Each finding gets its own block in the report.
 
+When the Nubos skill library is present, `Read` `.claude/skills/np-secure-code-review/SKILL.md` first and treat its checklist as the authoritative, language-agnostic expansion of the categories below. Then load the skills matching the milestone's surface and apply each one's "Verification bar" to the relevant findings:
+
+- new trust boundary / external integration / store for credentials or PII → `np-threat-model` (STRIDE lens) and `np-secure-design` (secure-defaults / least-privilege / zero-trust design review).
+- roles, permissions, resource-ownership, or access-rule changes → `np-access-control` (deny-by-default, object-level authz, IDOR).
+- encryption, hashing, password storage, TLS, tokens, or key/secret management → `np-encryption`.
+- collection, storage, or logging of personal/sensitive data → `np-data-privacy` (minimization, retention, no-PII-in-logs).
+
+The table below is the index; the skills are the depth. If the skills are absent (non-Claude runtime), fall back to the table alone.
+
 | Category | Look for |
 |---------|----------|
 | Injection | unparameterized SQL/shell/exec, string-concat queries, `eval`-style calls, untrusted input into `child_process` |

package/bin/np-tools/_commands.cjs

@@ -14,11 +14,15 @@ const COMMANDS = [
   { name: 'new-milestone',       category: 'Planning', description: 'Append a new milestone (M<NNN>) to an existing project', description_de: 'Hängt einen neuen Milestone (M<NNN>) an ein bestehendes Projekt an' },
   { name: 'propose-milestones',  category: 'Planning', description: 'Re-plan all not-yet-done milestones: AI proposes add/update/remove from PROJECT.md + REQUIREMENTS.md', description_de: 'Plant offene Milestones neu: KI schlägt add/update/remove aus PROJECT.md + REQUIREMENTS.md vor' },
   { name: 'agent-skills',        category: 'Planning', description: 'Print agent_skills config for a given subagent', description_de: 'Gibt agent_skills-Konfiguration für einen Subagent aus' },
+  { name: 'derive-tier',         category: 'Planning', description: 'Advisory: derive a suggested executor tier (haiku|sonnet|opus) from a task\'s observable signals (files_modified + risk keywords). Decider stays the planner. ADR-0013.', description_de: 'Advisory: leitet aus den beobachtbaren Task-Signalen (files_modified + Risk-Keywords) einen Vorschlags-Tier (haiku|sonnet|opus) ab. Entscheider bleibt der Planner. ADR-0013.' },
 
   { name: 'execute-milestone',   category: 'Execution', description: 'Wave-based milestone execution — slice by slice, tasks parallel within a slice', description_de: 'Wave-basierte Milestone-Ausführung — Slice für Slice, Tasks parallel innerhalb einer Slice' },
   { name: 'commit-task',         category: 'Execution', description: 'Atomic per-task git commit via lib/git.cjs', description_de: 'Atomarer Per-Task-Git-Commit über lib/git.cjs' },
   { name: 'checkpoint',          category: 'Execution', description: 'Per-task crash-safety checkpoint CRUD (start/transition/touch/show)', description_de: 'Per-Task-Checkpoint-CRUD für Crash-Safety (start/transition/touch/show)' },
   { name: 'verify-work',         category: 'Execution', description: 'Two-pass goal-backward verification (milestone-level VERIFICATION.md)', description_de: 'Zweistufige Goal-Backward-Verifikation (Milestone-Ebene VERIFICATION.md)' },
+  { name: 'verify-reliability',  category: 'Execution', description: 'pass@k reliability: fold k verify-run exit codes into pass@1/pass@k/flaky + an aggregate exit code (pass^k) for loop-run-round. Opt-in via loop.verify_runs.', description_de: 'pass@k-Reliability: faltet k Verify-Exit-Codes zu pass@1/pass@k/flaky + Aggregat-Exit-Code (pass^k) für loop-run-round. Opt-in über loop.verify_runs.' },
+  { name: 'learnings',           category: 'Execution', description: 'Stop-hook continuous-learning capture (ADR-0010). Verbs: capture (rate-limited; spawns headless np-learnings-extractor over the turn diff) | reset (clears stop-streak) | run-extract (background worker). Gated by learnings.auto_capture.', description_de: 'Stop-Hook Continuous-Learning-Capture (ADR-0010). Verben: capture (rate-limited; spawnt headless np-learnings-extractor über das Turn-Diff) | reset (setzt Stop-Streak zurück) | run-extract (Background-Worker). Gated über learnings.auto_capture.' },
+  { name: 'skill-audit',         category: 'Execution', description: 'Skill-bar consultation audit (counterpart to the Rule-9 search audit). Verbs: expect --task --skills (orchestrator records injected skills) | ack --task --skill (executor stamps a consulted skill) | findings --task [--round] (list unmet bars). An unconsulted injected skill becomes a skill-bar-unconsulted finding that routes back to the executor.', description_de: 'Skill-Bar-Konsultations-Audit (Pendant zum Rule-9-Search-Audit). Verben: expect --task --skills (Orchestrator merkt injizierte Skills) | ack --task --skill (Executor stempelt konsultierten Skill) | findings --task [--round] (offene Bars). Ein nicht konsultierter injizierter Skill wird zu einem skill-bar-unconsulted-Finding und routet zurück zum Executor.' },
   { name: 'close-project',       category: 'Review',    description: 'Aggregate verification of every milestone; writes PROJECT-SUMMARY.md + sets project_status=completed', description_de: 'Aggregat-Verifikation aller Milestones; schreibt PROJECT-SUMMARY.md + setzt project_status=completed' },
   { name: 'archive-project',     category: 'Planning',  description: 'Move current .nubos-pilot/ project to archive/<slug>-<YYYYMMDD>/ (status|do|list|read)', description_de: 'Verschiebt aktuelles .nubos-pilot/-Projekt nach archive/<slug>-<YYYYMMDD>/ (status|do|list|read)' },
   { name: 'add-tests',           category: 'Execution', description: 'Persist VERIFICATION Pass-cases as node:test UAT (Sentinel-preserving)', description_de: 'Persistiert VERIFICATION-Pass-Cases als node:test-UAT (Sentinel-erhaltend)' },
@@ -36,6 +40,7 @@ const COMMANDS = [
   { name: 'doctor',              category: 'Install', description: '12-check install-integrity scan (--fix for auto-safe fixes)', description_de: '12-Check-Install-Integritäts-Scan (--fix für auto-sichere Fixes)' },
   { name: 'scan-codebase',       category: 'Install', description: 'Initial deep codebase inventory → .nubos-pilot/codebase/ skill docs', description_de: 'Initiale tiefe Codebase-Inventur → .nubos-pilot/codebase/ Skill-Docs' },
   { name: 'update-docs',         category: 'Install', description: 'Refresh stale module docs after code changes', description_de: 'Aktualisiert veraltete Modul-Docs nach Code-Änderungen' },
+  { name: 'graph-impact',        category: 'Utility', description: 'Query the module dependency graph (.graph.json from np:scan-codebase): impact (transitive dependents), dependencies, cluster, cycle membership. Flags: --module <id> | --path <relpath> | --cycles', description_de: 'Fragt den Modul-Dependency-Graphen ab (.graph.json aus np:scan-codebase): Impact (transitive Dependents), Dependencies, Cluster, Zyklus-Zugehörigkeit. Flags: --module <id> | --path <relpath> | --cycles' },
 
   { name: 'resolve-model',       category: 'Utility', description: 'Resolve agent/tier to model alias or id (Tier×Profile matrix)', description_de: 'Löst Agent/Tier zu Model-Alias oder -ID auf (Tier×Profile-Matrix)' },
   { name: 'metrics',             category: 'Utility', description: 'Record JSONL metrics entry (record | now | start-timestamp | end-timestamp)', description_de: 'Schreibt JSONL-Metrics-Eintrag (record | now | start-timestamp | end-timestamp)' },

package/bin/np-tools/derive-tier.cjs

@@ -0,0 +1,86 @@
+'use strict';
+
+const fs = require('node:fs');
+
+const { classifyTier } = require('../../lib/tier-classify.cjs');
+const { extractFrontmatter } = require('../../lib/frontmatter.cjs');
+const { emitErrorEnvelope } = require('./_args.cjs');
+
+function _usage() {
+  return [
+    'Usage:',
+    '  np-tools.cjs derive-tier --files <a,b,c> [--name <text>] [--desc <text>]',
+    '  np-tools.cjs derive-tier --plan <path-to-PLAN.md>',
+    '',
+    'Advisory: derives a suggested executor tier (haiku|sonnet|opus) from the',
+    'task\'s observable signals. The planner remains the decider.',
+  ].join('\n');
+}
+
+function _fromPlan(planPath) {
+  const raw = fs.readFileSync(planPath, 'utf-8');
+  const { frontmatter, body } = extractFrontmatter(raw);
+  const nameMatch = String(body || '').match(/^#\s+(?:.*?—\s*)?(.+?)\s*$/m);
+  return {
+    files_modified: Array.isArray(frontmatter.files_modified) ? frontmatter.files_modified : [],
+    name: nameMatch ? nameMatch[1] : (frontmatter.id || ''),
+    desc: String(body || ''),
+  };
+}
+
+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 files = null;
+  let name = '';
+  let desc = '';
+  let planPath = 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 === '--files') { files = args[++i] || ''; }
+    else if (a.startsWith('--files=')) { files = a.slice('--files='.length); }
+    else if (a === '--name') { name = args[++i] || ''; }
+    else if (a.startsWith('--name=')) { name = a.slice('--name='.length); }
+    else if (a === '--desc') { desc = args[++i] || ''; }
+    else if (a.startsWith('--desc=')) { desc = a.slice('--desc='.length); }
+    else if (a === '--plan') { planPath = args[++i] || ''; }
+    else if (a.startsWith('--plan=')) { planPath = a.slice('--plan='.length); }
+    else {
+      stderr.write(JSON.stringify({
+        code: 'derive-tier-unknown-arg',
+        message: 'Unknown argument: ' + a,
+        details: { arg: a },
+      }) + '\n');
+      return 1;
+    }
+  }
+
+  try {
+    let task;
+    if (planPath) {
+      task = _fromPlan(planPath);
+    } else {
+      const list = files == null
+        ? []
+        : String(files).split(',').map((s) => s.trim()).filter(Boolean);
+      task = { files_modified: list, name, desc };
+    }
+    const result = classifyTier(task);
+    stdout.write(JSON.stringify(result) + '\n');
+    return 0;
+  } catch (err) {
+    emitErrorEnvelope(err, stderr, 'derive-tier-internal-error');
+    return 1;
+  }
+}
+
+module.exports = { run };
+
+if (require.main === module) {
+  process.exit(run(process.argv.slice(2)));
+}

package/bin/np-tools/derive-tier.test.cjs

@@ -0,0 +1,83 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const os = require('node:os');
+const fs = require('node:fs');
+const path = require('node:path');
+const { run } = require('./derive-tier.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('DT-1: --files + --name with security keyword → opus', () => {
+  const c = _capture();
+  const code = run(['--files', 'app/Auth.php', '--name', 'add login throttling'], c);
+  assert.strictEqual(code, 0);
+  const r = JSON.parse(c.out.text);
+  assert.strictEqual(r.tier, 'opus');
+  assert.strictEqual(r.size, 'large');
+});
+
+test('DT-2: single doc file → haiku', () => {
+  const c = _capture();
+  const code = run(['--files', 'README.md', '--name', 'fix typo'], c);
+  assert.strictEqual(code, 0);
+  assert.strictEqual(JSON.parse(c.out.text).tier, 'haiku');
+});
+
+test('DT-3: ordinary task → sonnet', () => {
+  const c = _capture();
+  const code = run(['--files', 'app/Cart.php,app/Cart.test.php', '--name', 'add discount'], c);
+  assert.strictEqual(code, 0);
+  assert.strictEqual(JSON.parse(c.out.text).tier, 'sonnet');
+});
+
+test('DT-4: --plan reads frontmatter files + body name', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-derive-tier-'));
+  const plan = path.join(dir, 'T0001-PLAN.md');
+  fs.writeFileSync(plan, [
+    '---',
+    'id: M001-S001-T0001',
+    'files_modified:',
+    '  - db/migrations/004_users.sql',
+    '---',
+    '',
+    '# M001-S001-T0001 — Add users table migration',
+    '',
+    'Body text.',
+  ].join('\n'));
+  const c = _capture();
+  const code = run(['--plan', plan], c);
+  assert.strictEqual(code, 0);
+  assert.strictEqual(JSON.parse(c.out.text).tier, 'opus');
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+test('DT-5: unknown arg → error envelope, exit 1', () => {
+  const c = _capture();
+  const code = run(['--bogus'], c);
+  assert.strictEqual(code, 1);
+  assert.match(c.err.text, /derive-tier-unknown-arg/);
+});
+
+test('DT-6: --help → usage, exit 0', () => {
+  const c = _capture();
+  const code = run(['--help'], c);
+  assert.strictEqual(code, 0);
+  assert.match(c.out.text, /derive-tier/);
+});
+
+test('DT-7: no files → standard sonnet, no throw', () => {
+  const c = _capture();
+  const code = run(['--name', 'something'], c);
+  assert.strictEqual(code, 0);
+  assert.strictEqual(JSON.parse(c.out.text).tier, 'sonnet');
+});

package/bin/np-tools/doctor.cjs

@@ -399,14 +399,27 @@ function _checkNubosloopKnowledgeStore(projectRoot) {
   }
   try {
     const parsed = JSON.parse(fs.readFileSync(learningsPath, 'utf-8'));
-    if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.learnings)) {
+    const { STORE_VERSION } = require('../../lib/learnings.cjs');
+    const { validate } = require('../../lib/validate.cjs');
+    const isObject = parsed && typeof parsed === 'object' && !Array.isArray(parsed);
+    let errors;
+    if (isObject && parsed.version === STORE_VERSION) {
+      errors = validate(parsed, 'learnings.v1');
+    } else if (!isObject || !Array.isArray(parsed.learnings)) {
+      errors = [{ message: 'expected JSON object with `version` and `learnings[]`' }];
+    } else {
+      errors = [];
+    }
+    if (errors.length) {
       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.',
+          violations: errors.length,
+          first: errors[0].message,
+          hint: 'store violates the learnings.v1 schema; remove or restore from a backup.',
         },
       });
     }

package/bin/np-tools/graph-impact.cjs

@@ -0,0 +1,111 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { NubosPilotError } = require('../../lib/core.cjs');
+const g = require('../../lib/codebase-graph.cjs');
+
+function _parseArgs(args) {
+  const flags = { cwd: null, module: null, filePath: null, cycles: false };
+  for (let i = 0; i < (args || []).length; i++) {
+    const a = args[i];
+    if (a === '--cwd') flags.cwd = args[++i];
+    else if (a === '--module') flags.module = args[++i];
+    else if (a === '--path') flags.filePath = args[++i];
+    else if (a === '--cycles') flags.cycles = true;
+  }
+  return flags;
+}
+
+function _graphPath(projectRoot) {
+  return path.join(projectRoot, '.nubos-pilot', 'codebase', '.graph.json');
+}
+
+function _load(projectRoot) {
+  const p = _graphPath(projectRoot);
+  let raw;
+  try {
+    raw = fs.readFileSync(p, 'utf-8');
+  } catch {
+    throw new NubosPilotError(
+      'graph-not-found',
+      'module graph not found — run np:scan-codebase first',
+      { path: '.nubos-pilot/codebase/.graph.json' },
+    );
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new NubosPilotError(
+      'graph-unreadable',
+      'module graph is not valid JSON — re-run np:scan-codebase',
+      { path: '.nubos-pilot/codebase/.graph.json', cause: err && err.message },
+    );
+  }
+}
+
+function _moduleForPath(graph, rel) {
+  const norm = rel.split(path.sep).join('/');
+  const dir = norm.includes('/') ? norm.slice(0, norm.lastIndexOf('/')) : '';
+  const node = (graph.nodes || []).find((n) => n.directory === dir);
+  return node ? node.id : null;
+}
+
+function run(args, ctx) {
+  const context = ctx || {};
+  const stdout = context.stdout || process.stdout;
+  const flags = _parseArgs(args);
+  const projectRoot = path.resolve(flags.cwd || context.cwd || process.cwd());
+  const graph = _load(projectRoot);
+
+  if (flags.cycles && !flags.module && !flags.filePath) {
+    stdout.write(JSON.stringify({
+      module_count: graph.module_count,
+      cycle_count: (graph.cycles || []).length,
+      cycles: graph.cycles || [],
+    }, null, 2));
+    return 0;
+  }
+
+  let moduleId = flags.module;
+  if (!moduleId && flags.filePath) {
+    moduleId = _moduleForPath(graph, flags.filePath);
+    if (!moduleId) {
+      throw new NubosPilotError(
+        'graph-path-unmapped',
+        'no module owns that path: ' + flags.filePath,
+        { path: flags.filePath },
+      );
+    }
+  }
+  if (!moduleId) {
+    throw new NubosPilotError(
+      'graph-missing-target',
+      '--module <id> or --path <relpath> required',
+      {},
+    );
+  }
+  if (!(graph.nodes || []).some((n) => n.id === moduleId)) {
+    throw new NubosPilotError(
+      'graph-unknown-module',
+      'module not in graph: ' + moduleId,
+      { module: moduleId },
+    );
+  }
+
+  stdout.write(JSON.stringify({
+    module: moduleId,
+    direct_dependents: g.directDependents(graph, moduleId),
+    impact: g.transitiveDependents(graph, moduleId),
+    direct_dependencies: g.directDependencies(graph, moduleId),
+    transitive_dependencies: g.transitiveDependencies(graph, moduleId),
+    cluster: g.clusterOf(graph, moduleId),
+    in_cycle: g.cycleFor(graph, moduleId),
+  }, null, 2));
+  return 0;
+}
+
+module.exports = { run, _parseArgs };
+
+if (require.main === module) {
+  process.exit(run(process.argv.slice(2)) || 0);
+}

package/bin/np-tools/graph-impact.test.cjs

@@ -0,0 +1,119 @@
+const { test, afterEach } = 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 cli = require('./graph-impact.cjs');
+
+const _sandboxes = [];
+
+function makeSandbox() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'np-gi-'));
+  _sandboxes.push(dir);
+  return dir;
+}
+
+function writeGraph(root, graph) {
+  const dir = path.join(root, '.nubos-pilot', 'codebase');
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, '.graph.json'), JSON.stringify(graph));
+}
+
+function capture() {
+  let buf = '';
+  return { stream: { write: (s) => { buf += s; } }, read: () => buf };
+}
+
+const SAMPLE = {
+  schema_version: 1,
+  module_count: 3,
+  edge_count: 2,
+  nodes: [
+    { id: 'a', directory: 'a', primary_language: 'javascript', file_count: 1 },
+    { id: 'b', directory: 'b', primary_language: 'javascript', file_count: 1 },
+    { id: 'c', directory: 'c', primary_language: 'javascript', file_count: 1 },
+  ],
+  edges: [
+    { from: 'a', to: 'b', weight: 1 },
+    { from: 'b', to: 'c', weight: 1 },
+  ],
+  cycles: [],
+  clusters: [{ id: 0, members: ['a', 'b', 'c'] }],
+  metrics: { unresolved_internal_deps: 0, max_fan_in: 1, max_fan_out: 1, isolated_modules: 0 },
+};
+
+afterEach(() => {
+  while (_sandboxes.length) {
+    const dir = _sandboxes.pop();
+    try { fs.rmSync(dir, { recursive: true, force: true }); } catch {}
+  }
+});
+
+test('GI-1: --module reports impact and dependencies', () => {
+  const root = makeSandbox();
+  writeGraph(root, SAMPLE);
+  const out = capture();
+  const rc = cli.run(['--module', 'c'], { cwd: root, stdout: out.stream });
+  assert.equal(rc, 0);
+  const res = JSON.parse(out.read());
+  assert.equal(res.module, 'c');
+  assert.deepEqual(res.direct_dependents, ['b']);
+  assert.deepEqual(res.impact, ['a', 'b']);
+  assert.deepEqual(res.transitive_dependencies, []);
+});
+
+test('GI-2: --path maps a file to its owning module', () => {
+  const root = makeSandbox();
+  writeGraph(root, SAMPLE);
+  const out = capture();
+  cli.run(['--path', 'a/login.js'], { cwd: root, stdout: out.stream });
+  const res = JSON.parse(out.read());
+  assert.equal(res.module, 'a');
+  assert.deepEqual(res.direct_dependencies, ['b']);
+});
+
+test('GI-3: missing graph throws graph-not-found', () => {
+  const root = makeSandbox();
+  assert.throws(
+    () => cli.run(['--module', 'a'], { cwd: root, stdout: capture().stream }),
+    (err) => err.code === 'graph-not-found',
+  );
+});
+
+test('GI-4: unknown module throws graph-unknown-module', () => {
+  const root = makeSandbox();
+  writeGraph(root, SAMPLE);
+  assert.throws(
+    () => cli.run(['--module', 'nope'], { cwd: root, stdout: capture().stream }),
+    (err) => err.code === 'graph-unknown-module',
+  );
+});
+
+test('GI-5: no target throws graph-missing-target', () => {
+  const root = makeSandbox();
+  writeGraph(root, SAMPLE);
+  assert.throws(
+    () => cli.run([], { cwd: root, stdout: capture().stream }),
+    (err) => err.code === 'graph-missing-target',
+  );
+});
+
+test('GI-6: --cycles dumps the cycle list', () => {
+  const root = makeSandbox();
+  writeGraph(root, Object.assign({}, SAMPLE, { cycles: [['a', 'b']] }));
+  const out = capture();
+  cli.run(['--cycles'], { cwd: root, stdout: out.stream });
+  const res = JSON.parse(out.read());
+  assert.equal(res.cycle_count, 1);
+  assert.deepEqual(res.cycles[0], ['a', 'b']);
+});
+
+test('GI-7: unmappable --path throws graph-path-unmapped', () => {
+  const root = makeSandbox();
+  writeGraph(root, SAMPLE);
+  assert.throws(
+    () => cli.run(['--path', 'ghost/x.js'], { cwd: root, stdout: capture().stream }),
+    (err) => err.code === 'graph-path-unmapped',
+  );
+});