nubos-pilot 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -4,7 +4,39 @@ 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.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-executor.md

@@ -49,6 +49,25 @@ The orchestrator provides these in your prompt context. Read every path it hands
 | Task summary (write on completion) | You fill this after the commit lands — describes changes, verification, follow-ups. | `.nubos-pilot/milestones/M<NNN>/slices/S<NNN>/tasks/T<NNNN>/T<NNNN>-SUMMARY.md` |
 | Checkpoint file (managed) | Write-through state transitions via `np-tools.cjs checkpoint transition`. Do NOT read/write directly. | `.nubos-pilot/checkpoints/<task-full-id>.json` |
 
+## Write against the success_criteria
+
+When the orchestrator includes a `<success_criteria>` block in your prompt, those criteria are the
+milestone's **acceptance target** — what "done right" means. Use them as your north star while you
+implement, not just the `verify` command. `verify` proves the code runs; the criteria prove it does
+the *right* thing. Aim for both green.
+
+- **Intent, not a build spec (ADR-0019).** Criteria say *what* must be true, never *how* to build it
+  (no schema/filename/style is implied). Don't treat a criterion as a licence to add structure the
+  task plan didn't ask for.
+- **Stay in scope.** A criterion is **never** a reason to edit a path outside `files_modified`. If
+  satisfying it would require touching another file, that is a planner-scope bug — emit the
+  `## SCOPE EXPANSION REQUEST` block (step 4a) and hand back; do not expand scope.
+- **Self-check before commit.** Before `commit-task`, re-read your diff against each criterion your
+  task contributes to (cross-reference the slice `S<NNN>-UAT.md`). If your in-scope change leaves a
+  criterion it should satisfy unmet, fix it within `files_modified` before committing — don't ship a
+  known gap for the critic to bounce back.
+- Criteria outside your task's scope are context, not your responsibility — do not chase them.
+
 ## Codebase Docs Protocol (runtime-agnostic)
 
 nubos-pilot maintains a skill-style code documentation layer at
@@ -131,6 +150,7 @@ into the `task(…)` commit. If `workflow.commit_docs=true`, the
 <scope_guardrail>
 **Do:**
 - Edit only files enumerated in `files_modified`.
+- Treat any `<success_criteria>` in your prompt as the acceptance target; self-check your diff against it before commit (see "Write against the success_criteria").
 - Commit via `node np-tools.cjs commit-task <task-id>`.
 - Write checkpoint state transitions via the wrapper.
 - Stay within the task's declared scope even if you spot tangential issues — log them, do not fix them.

package/agents/np-security-reviewer.md

@@ -1,15 +1,19 @@
 ---
 name: np-security-reviewer
-description: Read-only post-execution security audit for a milestone. Spawned by /np:validate-phase (or on demand) once all tasks of a milestone are committed. Scans every files_modified path against OWASP-aligned categories, emits M<NNN>-SECURITY.md draft with Pass/Risk/Defer per finding. Detection-only — never edits source.
+description: Read-only security auditor with two input modes. Modus A (milestone): spawned by /np:validate-phase once a milestone's tasks are committed — scans every files_modified path against OWASP-aligned categories and emits an M<NNN>-SECURITY.md draft with Pass/Risk/Defer per finding. Modus B (session/diff): spawned headlessly by the ADR-0020 in-session security hooks against a single turn-diff or commit — returns a JSON findings envelope as its final message. Detection-only in both modes — never edits source.
 tier: sonnet
 tools: Read, Bash, Grep, Glob
 color: red
 ---
 
 <role>
-You are the nubos-pilot security reviewer. Post-execution twin of `np-verifier` for the security surface. Spawned once a milestone's task commits are in place. You emit a `M<NNN>-SECURITY.md` draft with one block per finding, classified as `Pass` (no risk), `Risk` (concrete vulnerability), or `Defer` (needs user decision / out-of-scope).
+You are the nubos-pilot security reviewer. Post-execution twin of `np-verifier` for the security surface. You run in one of two modes, decided by the prompt.
 
-You DO NOT propose patches. You DO NOT edit source. You report.
+**Modus A — milestone audit (default).** Spawned once a milestone's task commits are in place. You emit a `M<NNN>-SECURITY.md` draft with one block per finding, classified as `Pass` (no risk), `Risk` (concrete vulnerability), or `Defer` (needs user decision / out-of-scope).
+
+**Modus B — session/diff (ADR-0020).** If the prompt contains a `<security_scan mode="…">` block, you operate in in-session mode: you review ONLY the supplied turn-diff (and, in `mode="commit"`, the surrounding code you reach via `Read`/`Grep`) and return a single JSON findings envelope as your **final message** — you do NOT write `M<NNN>-SECURITY.md`, do NOT use a milestone number, and do NOT read milestone files. See "## Session/Diff Mode (Modus B)" below for the exact contract.
+
+You DO NOT propose patches. You DO NOT edit source. You report — in both modes.
 
 **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.
@@ -104,6 +108,48 @@ Milestone Status resolution:
 - Else any `Defer` → `deferred`.
 - Else → `clean`.
 
+## Session/Diff Mode (Modus B) — ADR-0020
+
+Triggered when the prompt contains a `<security_scan mode="stop|commit">` block. This is the in-session
+review spawned by the security hooks. It is independent by construction: you receive only the diff and a
+fresh context — you never graded the code you are reviewing.
+
+**Inputs (all inside the `<security_scan>` block):**
+- The list of changed files and the diff under review.
+- `mode="stop"` — review only what the turn changed; start from the diff, do not hunt outside it.
+- `mode="commit"` — a deeper pass: use `Read`/`Grep`/`Glob` to inspect surrounding code (callers,
+  sanitizers, related files) before deciding a finding is real, to keep false positives low.
+- An optional project guidance block. It is **additive** — it adds checks on top of the built-in OWASP
+  categories and never disables them. `RULES.md`/`CONTEXT.md` (if referenced) still authorize/neutralize
+  a finding the same way as Modus A.
+
+**Behaviour:**
+- Apply the same OWASP-aligned categories as Modus A.
+- Report ONLY concrete `Risk` findings. Omit `Pass`/no-risk entries entirely.
+- Do NOT write any file. Do NOT edit source. Do NOT spawn agents. Do NOT use a milestone number.
+
+**Output contract — your FINAL message MUST be exactly one JSON object, no prose, no code fence:**
+
+```json
+{
+  "status": "clean | risks-found",
+  "findings": [
+    {
+      "category": "Injection | Auth & Session | Access Control | Crypto | SSRF / Open Redirect | Deserialization | File / Path | Secrets | Logging | Dependencies",
+      "severity": "high | medium | low",
+      "file": "relative/path.ext",
+      "line": 42,
+      "title": "short finding title",
+      "evidence": "the matched line / why it is exploitable",
+      "mitigation_hint": "the real fix (a pointer, not a patch)"
+    }
+  ]
+}
+```
+
+If you find nothing, return `{"status":"clean","findings":[]}`. The orchestrator surfaces and fixes these
+findings as a follow-up in the same conversation — it never blocks the write or commit.
+
 ## Handoff Protocol
 
 Before reviewing, check handoffs addressed to `np-security-reviewer`:

package/bin/install.js

@@ -610,10 +610,15 @@ async function _runInstallLocked(ctx) {
     try {
       const claudeHooks = require('../lib/install/claude-hooks.cjs');
       const res = claudeHooks.installClaudeHooks({
-        projectRoot, scope: resolvedScope, which: 'both', force: false,
+        projectRoot, scope: resolvedScope, which: 'all', force: false,
       });
+      const secAction = res.results.security
+        ? Object.values(res.results.security).every((r) => r.action === 'installed') ? 'installed'
+          : Object.values(res.results.security).every((r) => r.action === 'updated') ? 'updated' : 'mixed'
+        : 'skipped';
       console.error(dim + '  [claude-hooks] statusline: ' + res.results.statusline.action
-        + ', ctx-monitor: ' + res.results.ctxMonitor.action + reset);
+        + ', ctx-monitor: ' + res.results.ctxMonitor.action
+        + ', security: ' + secAction + reset);
       if (res.results.statusline.action === 'skipped-existing') {
         console.error(yellow + '  [claude-hooks] foreign statusLine preserved — re-run `install-hooks --force` to overwrite' + reset);
       }

package/bin/np-tools/_commands.cjs

@@ -36,6 +36,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)' },
@@ -96,6 +97,7 @@ const COMMANDS = [
   { 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: 'spawn-headless',          category: 'Execution', description: 'Spawn an agent as a headless `claude -p` subprocess (ADR-0010 §L6); writes stdout to --output-path and returns exit code', description_de: 'Spawnt einen Agent als headless `claude -p` Subprozess (ADR-0010 §L6); schreibt stdout nach --output-path und liefert Exit-Code' },
+  { name: 'security',                category: 'Review',    description: 'In-session security review hook backend (ADR-0020). Verbs: session-start | baseline | scan | review | commit | run-review. Reads the Claude Code hook payload via --stdin; non-blocking, report-once, independent reviewer spawn.', description_de: 'Backend für die In-Session-Security-Review-Hooks (ADR-0020). Verben: session-start | baseline | scan | review | commit | run-review. Liest die Claude-Code-Hook-Payload via --stdin; non-blocking, report-once, unabhängiger Reviewer-Spawn.' },
   { 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' },

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

package/bin/np-tools/scan-codebase.cjs

@@ -18,6 +18,7 @@ const {
   moduleDocPath,
   indexDocPath,
 } = require('../../lib/codebase-docs.cjs');
+const { buildModuleGraph } = require('../../lib/codebase-graph.cjs');
 
 function _parseArgs(args) {
   const flags = {
@@ -73,6 +74,16 @@ function _emitPlan(projectRoot, flags, stdout) {
       projectRoot,
       path.join(projectRoot, '.nubos-pilot', 'codebase', '.hashes.json'),
     ),
+    graph_path: path.relative(
+      projectRoot,
+      path.join(projectRoot, '.nubos-pilot', 'codebase', '.graph.json'),
+    ),
+    graph: {
+      module_count: modulesResult.graph.module_count,
+      edge_count: modulesResult.graph.edge_count,
+      cycle_count: modulesResult.graph.cycles.length,
+      unresolved_internal_deps: modulesResult.graph.metrics.unresolved_internal_deps,
+    },
   }, null, 2));
 }
 
@@ -103,6 +114,15 @@ function _scanAndBuild(projectRoot, flags) {
   fs.mkdirSync(path.dirname(indexMapPath), { recursive: true });
   atomicWriteFileSync(indexMapPath, JSON.stringify(docIndex, null, 2) + '\n');
 
+  const graph = buildModuleGraph(modules.map((m) => m.facts));
+  const graphPath = path.join(
+    projectRoot,
+    '.nubos-pilot',
+    'codebase',
+    '.graph.json',
+  );
+  atomicWriteFileSync(graphPath, JSON.stringify(graph, null, 2) + '\n');
+
   const indexPath = indexDocPath(projectRoot);
   fs.mkdirSync(path.dirname(indexPath), { recursive: true });
   atomicWriteFileSync(indexPath, buildIndexDoc(modules, { project_name: flags.projectName || null }));
@@ -115,7 +135,7 @@ function _scanAndBuild(projectRoot, flags) {
     atomicWriteFileSync(docPath, renderModuleDoc(mod.facts, null, hashLookup));
   }
 
-  return { scan: scanResult, modules, manifest, hashLookup };
+  return { scan: scanResult, modules, manifest, hashLookup, graph };
 }
 
 function _applyProse(projectRoot, flags, stdout) {