cadet-agent 0.56.0 → 0.63.1

package/src/harness/commands.mjs

@@ -35,6 +35,10 @@ export const COMMANDS = {
     unattended: true,
   },
 
+  'state brief': {
+    mutates: false,
+    summary: 'Print the tier-0 summary of state.json: phase, active work item, every gate, and what compaction would archive.',
+  },
   'state validate': {
     mutates: false,
     summary: 'Validate .cadet/state.json against the current schema.',
@@ -141,7 +145,7 @@ export const COMMANDS = {
   'harness context plan': {
     mutates: true,
     summary: 'Write the context plan for the current phase: what must be loaded, and why.',
-    writes: ['.cadet/context/plan.json'],
+    writes: ['.cadet/context/plan.json', '.cadet/context/state-brief.md'],
     unattended: true,
   },
   'harness context record': {
@@ -165,13 +169,13 @@ export const COMMANDS = {
     writes: ['.cadet/runs/**', '.cadet/state.json'],
     unattended: true,
   },
-  'harness acceptance-form': {
+  'harness verify-play': {
     mutates: true,
-    summary: 'Write a human-acceptance form for an epic, pre-filled from state.',
-    // It writes exactly one file, and only when that file does not exist: a form is a
-    // person's worksheet once they have touched it, and a regeneration would discard
-    // what they wrote. It never writes state — recording the gate is `harness confirm`.
-    writes: ['.cadet/agent/project-plans/**'],
+    summary: 'Verify a story\'s Play: declaration; record the gate for a deferral, refuse it for a playable story.',
+    // Same posture as verify-reachability: it records evidence for its gate, so it writes
+    // the ledger and state. It writes no artifact of its own — the declaration lives in the
+    // story, and a playable story's record comes from the person's own answer instead.
+    writes: ['.cadet/runs/**', '.cadet/state.json'],
     unattended: true,
   },
   'harness report': {
@@ -206,6 +210,23 @@ export const COMMANDS = {
     mutates: false,
     summary: 'Report available CLI/Unity/MCP/hook/token/cost telemetry.',
   },
+  'harness diagram': {
+    mutates: true,
+    summary: 'Render UML component diagrams per package, coloured by workflow progress.',
+    // The tree is fully generated: one .noml + .svg per (package × epic), plus an
+    // index.html per package and at the root. `--out` may redirect it, but the
+    // default is the declared path, which is what the guard keys on.
+    writes: ['.cadet/diagrams/**'],
+    unattended: true,
+  },
+  'harness verify-diagrams': {
+    mutates: false,
+    summary: 'Check the committed diagram tree against a freshly computed model.',
+    // Read-only by construction: it regenerates the model in memory and compares
+    // it with the files on disk. It does not write the tree — a check that
+    // repaired the thing it checks would prove nothing — and `harness reconcile`
+    // calls the same function, so the two cannot disagree.
+  },
   'harness cleanup': {
     mutates: true,
     summary: 'Apply the retention policy to .cadet/runs/, deleting run records.',
@@ -229,6 +250,63 @@ export function readOnlyCommands() {
   return Object.entries(COMMANDS).filter(([, c]) => !c.mutates).map(([k]) => k);
 }
 
+/** Repository-relative form of a path: forward slashes, no leading `./`. */
+function normaliseRepoPath(path) {
+  return String(path).replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+/**
+ * Does one of a command's `writes` patterns cover a path?
+ *
+ * The shipped table uses exactly three shapes, and the matcher supports those and no more:
+ * an exact path (`AGENTS.md`), a directory subtree (`<dir>/**`), and a root-level suffix
+ * wildcard (`*.coverage.json`). `**` crosses directory boundaries and `*` does not — the
+ * distinction a shell makes, and the reason a `*` that crossed directories would refuse a
+ * file the command never touches.
+ *
+ * Wildcards are replaced FIRST, with placeholders that survive the escape pass. Doing it the
+ * other way round turns `**` into a literal `\*\*` and every declaration stops matching — the
+ * defect this function shipped with for one run, caught by the generated test below it.
+ *
+ * Absolute paths are deliberately not translated: `--files` carries repository-relative paths
+ * by contract, so an absolute path is a different mistake and not this function's to guess at.
+ */
+function writePatternMatches(pattern, path) {
+  const escaped = normaliseRepoPath(pattern)
+    .replace(/\*\*/g, '\u0000')
+    .replace(/\*/g, '\u0001')
+    .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    .replace(/\u0000/g, '.*')
+    .replace(/\u0001/g, '[^/]*');
+
+  return new RegExp(`^${escaped}$`).test(normaliseRepoPath(path));
+}
+
+/**
+ * The `--files` entries a command declares it WRITES, and which must therefore never be
+ * bound as its evidence.
+ *
+ * Why this exists: a record's `inputTreeHash` covers the files it binds, and the command
+ * then writes its own outputs — the run ledger and `.cadet/state.json`. Binding one of those
+ * makes the record stale at the instant it is created, because the write it records changes
+ * a file the hash covers. Measured on a consumer on 2026-10-01: a `storyTrackingUpdated`
+ * record that bound the story, the epic and `.cadet/state.json` was refused by the very next
+ * `state transition --dry-run` with "input tree hash changed since the evidence was
+ * recorded", and the gate had to be re-recorded twice before the boundary was allowed.
+ *
+ * The answer is a refusal rather than a filter. Filtering would leave the record claiming a
+ * coverage it does not have, and the caller asked for a binding that provably cannot hold —
+ * the same choice `AGENT_OWNED_GATES` and the swallowed `--command` flag both resolved the
+ * loud way. It is derived from the registry rather than hardcoded, so a new command's
+ * outputs are covered the moment it is registered.
+ */
+export function selfBoundFiles(commandKey, files = []) {
+  const writes = COMMANDS[commandKey]?.writes || [];
+  if (writes.length === 0 || !Array.isArray(files) || files.length === 0) return [];
+
+  return files.filter((file) => writes.some((pattern) => writePatternMatches(pattern, file)));
+}
+
 /**
  * Resolve the command key for a parsed invocation.
  *

package/src/harness/context-protocol.mjs

@@ -23,11 +23,13 @@
  * rules: what a phase requires, what a record may claim, and when the two disagree.
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
 
 import { ContextManifest } from './context.mjs';
 import { sha256, timestamp } from './util.mjs';
+import { buildStateBrief, renderStateBrief } from './state.mjs';
+import { PLANS_DEFAULT_DIR, walkDirs } from './reconcile.mjs';
 
 /** The levels a record may carry, strongest first. */
 export const CONTEXT_LEVELS = Object.freeze(['enforced', 'recorded', 'estimated', 'unavailable']);
@@ -37,6 +39,32 @@ export const CONTEXT_DIR = '.cadet/context';
 export const CONTEXT_PLAN_FILE = 'plan.json';
 export const CONTEXT_RECORD_FILE = 'record.json';
 
+/**
+ * The derived summary of `.cadet/state.json` that tier 0 names, in place of the document.
+ *
+ * The document is not the current story: it is the current story's live evidence plus lists that
+ * only ever grow — one row per work item ever closed, one entry per change checkpoint. In a real
+ * consumer it reached 94,547 B, about 31,500 tokens, of which the current story was 31%. This file
+ * carries what the phase reads, and nothing else.
+ */
+export const CONTEXT_BRIEF_FILE = 'state-brief.md';
+const STATE_BRIEF = `${CONTEXT_DIR}/${CONTEXT_BRIEF_FILE}`;
+
+/**
+ * Write the tier-0 brief, before a plan names and hashes it.
+ *
+ * `policy` is passed through so the written brief and the printed one are the SAME rendering. The
+ * brief's legal-edge line reports an opt-in gate (reachability, the playthrough, human acceptance,
+ * architecture fitness) only when the resolved policy requires it, so a caller that omits the policy
+ * writes a brief that under-reports the edge the transition itself would enforce.
+ */
+export function writeStateBrief(targetDir, state, policy = null, docs = null) {
+  const path = join(targetDir, CONTEXT_DIR, CONTEXT_BRIEF_FILE);
+  mkdirSync(join(targetDir, CONTEXT_DIR), { recursive: true });
+  writeFileSync(path, renderStateBrief(buildStateBrief(state, policy, docs)), 'utf-8');
+  return path;
+}
+
 export class ContextProtocolError extends Error {
   constructor(message, code = 'context-protocol') {
     super(message);
@@ -66,8 +94,8 @@ export const PHASE_SKILL = Object.freeze({
   closed: 'Resume.md',
 });
 
-/** The runtime contract every phase reads. */
-const HARNESS_CONTRACT = '.cadet/agent/core/Harness.md';
+/** The lean runtime contract every phase reads. */
+const HARNESS_CONTRACT = '.cadet/agent/core/HarnessRuntime.md';
 const KICKOFF = '.cadet/agent/core/cadet-agent.md';
 
 const normalise = (path) => String(path).replace(/\\/g, '/').replace(/^\.\//, '');
@@ -85,6 +113,88 @@ function entry(reference, { tier, reason, authority, required }) {
   return { reference: normalise(reference), tier, reason, authority, required };
 }
 
+/** A repo-relative path with forward slashes, as a plan entry's reference must be. */
+function relativePath(targetDir, abs) {
+  return normalise(relative(targetDir, abs));
+}
+
+/**
+ * Where the active work item's own documents are.
+ *
+ * WHY THIS EXISTS. The plan built these two paths by joining the plans root with the ids from
+ * `state.json`, which assumes the PACKAGED layout. A real project nests its plans and names its own
+ * folders — this repository keeps `.cadet/agent/project-plans/dolven-tactics-mvp/epics/<epic>/` — so the
+ * plan reported the host's own active story as MISSING on every phase of every story, and its epic as
+ * absent. A check that fires on a correct project teaches its reader to ignore the output; the
+ * reconciler records that same lesson, for this same repository, in its REQUIRED_ARTIFACTS comment.
+ *
+ * THE RULE, and it is deliberately narrow. Find the story by its own FILENAME, which is what
+ * `state.json` already holds, using the reconciler's bounded walk. Accept a match only when the epic id
+ * names one of its parent directories, so a same-named file under another epic cannot be taken for it.
+ * The story's own directory IS the epic's directory, and the epic document is whatever `epic.md` is
+ * called there, because the case varies between projects.
+ *
+ * TWO MATCHES ARE REPORTED, NOT GUESSED. A duplicate filename comes back in `ambiguous` so the plan can
+ * say so, rather than resolving to whichever the filesystem happened to list first.
+ *
+ * Reads directories and parses nothing. A missing or unreadable tree returns nulls instead of throwing,
+ * so the plan still reports the row — as MISSING, which is then true.
+ */
+export function resolveWorkItemDocs(targetDir, state, { plansDir = PLANS_DEFAULT_DIR } = {}) {
+  const epicId = state?.activeWorkItem?.epicId || null;
+  const storyId = state?.activeWorkItem?.storyId || null;
+  if (!epicId || !storyId) return { story: null, epic: null, ambiguous: [], root: plansDir };
+
+  const epicWanted = String(epicId).toLowerCase();
+  // `storyId` is a filename in most documents and a path in a few, so compare on the last segment.
+  const wanted = String(storyId).replace(/\\/g, '/').split('/').pop().toLowerCase();
+  const root = join(targetDir, plansDir);
+  const matches = [];
+
+  for (const dir of walkDirs(root)) {
+    // The epic id must name a directory BETWEEN the plans root and the file. Comparing only the relative
+    // part stops a drive letter or a user's own folder name from ever satisfying the test.
+    const rel = relative(root, dir).replace(/\\/g, '/').toLowerCase();
+    if (!rel.split('/').includes(epicWanted)) continue;
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch { continue; }
+    for (const item of entries) {
+      if (item.isFile() && item.name.toLowerCase() === wanted) matches.push(join(dir, item.name));
+    }
+  }
+
+  if (matches.length === 0) return { story: null, epic: null, ambiguous: [], root: plansDir };
+  if (matches.length > 1) {
+    return { story: null, epic: null, ambiguous: matches.map((p) => relativePath(targetDir, p)), root: plansDir };
+  }
+
+  const story = matches[0];
+  let epic = null;
+  try {
+    const epicFile = readdirSync(dirname(story), { withFileTypes: true })
+      .find((item) => item.isFile() && item.name.toLowerCase() === 'epic.md');
+    if (epicFile) epic = join(dirname(story), epicFile.name);
+  } catch { /* the epic document is advisory: its absence is reported, not raised */ }
+
+  return {
+    story: relativePath(targetDir, story),
+    epic: epic ? relativePath(targetDir, epic) : null,
+    ambiguous: [],
+    root: plansDir,
+  };
+}
+
+/** Why a work-item document could not be resolved, said in the plan's own words. */
+function unresolvedReason(work, storyId) {
+  if (work.ambiguous.length > 0) {
+    return `${work.ambiguous.length} files named ${storyId} under ${work.root}, so the plan will not `
+      + `guess which one is active: ${work.ambiguous.join(', ')}`;
+  }
+  return `not found under ${work.root}`;
+}
+
 /**
  * What the current phase requires, and what merely helps.
  *
@@ -92,22 +202,31 @@ function entry(reference, { tier, reason, authority, required }) {
  * from state and the framework's own layout rather than from a new policy key, because a policy
  * that restates the framework's folder conventions is another thing to keep in step.
  */
-export function planEntries({ targetDir, policy, state = null }) {
+export function planEntries({ targetDir, policy, state = null, docs = null }) {
   const phase = state?.session?.currentPhase || 'context-resolution';
   const required = [];
   const advisory = [];
+  // Resolved once per plan. A caller may pass what it already resolved, so a plan and the brief it
+  // writes do not walk the planning tree twice for the same answer.
+  const work = docs || resolveWorkItemDocs(targetDir, state);
 
   required.push(entry(KICKOFF, {
     tier: 'tier0', reason: 'always-load: the directive that routes every other decision', authority: 'framework', required: true,
   }));
   required.push(entry(HARNESS_CONTRACT, {
-    tier: 'tier0', reason: 'the runtime contract for gates, evidence and budgets', authority: 'framework', required: true,
+    tier: 'tier0', reason: 'the lean runtime contract for gates, evidence and budgets', authority: 'framework', required: true,
+  }));
+  required.push(entry('.cadet/harness.json', {
+    tier: 'tier0', reason: 'the resolved policy: budgets, the gate settings and the human-gate rules the phase obeys', authority: 'session', required: true,
+  }));
+  // THE STATE BRIEF, NOT THE STATE DOCUMENT (0.63.0). The document is not the current story — it
+  // holds every work item ever closed and every change checkpoint ever recorded, and it grows without
+  // bound. It was 94,547 B, about 31,500 tokens, of which the current story was 31%, and it was
+  // re-sent on every turn. The brief carries the phase, the work item, the gates and what is
+  // archivable; `state brief` prints it and `harness context plan` writes it here.
+  required.push(entry(STATE_BRIEF, {
+    tier: 'tier0', reason: 'the session state the phase reads: the phase, the active work item, every gate, and what compaction would archive', authority: 'session', required: true,
   }));
-  for (const ref of ['.cadet/harness.json', '.cadet/state.json']) {
-    required.push(entry(ref, {
-      tier: 'tier0', reason: 'the active policy and the session state the phase reads', authority: 'session', required: true,
-    }));
-  }
 
   // The phase's own instruction: the skill the dispatch table names.
   const skillFile = phase === 'architectureComplete' && policy?.designReview?.enabled !== true
@@ -123,13 +242,23 @@ export function planEntries({ targetDir, policy, state = null }) {
   const epicId = state?.activeWorkItem?.epicId || null;
   const storyId = state?.activeWorkItem?.storyId || null;
   if (epicId && storyId) {
-    required.push(entry(join('.cadet/agent/project-plans', epicId, storyId), {
-      tier: 'tier1', reason: 'the active story: its status, its acceptance criteria, its reachability', authority: 'session', required: true,
+    // The resolved path when the tree has the file; the packaged layout's guess otherwise, so an
+    // unresolvable story is still reported as MISSING rather than dropped from the required set.
+    required.push(entry(work.story || join(PLANS_DEFAULT_DIR, epicId, storyId), {
+      tier: 'tier1',
+      reason: work.story
+        ? 'the active story: its status, its acceptance criteria, its reachability'
+        : `the active story: its status, its acceptance criteria, its reachability — ${unresolvedReason(work, storyId)}`,
+      authority: 'session', required: true,
     }));
   }
   if (epicId) {
-    advisory.push(entry(join('.cadet/agent/project-plans', epicId, 'Epic.md'), {
-      tier: 'tier1', reason: 'the epic this story belongs to', authority: 'repository', required: false,
+    advisory.push(entry(work.epic || join(PLANS_DEFAULT_DIR, epicId, 'Epic.md'), {
+      tier: 'tier1',
+      reason: work.epic
+        ? 'the epic this story belongs to'
+        : `the epic this story belongs to — ${unresolvedReason(work, storyId)}`,
+      authority: 'repository', required: false,
     }));
   }
 
@@ -152,8 +281,8 @@ export function planEntries({ targetDir, policy, state = null }) {
  * Build the plan: the entries above, resolved through `ContextManifest` so each carries its hash,
  * size, estimated tokens and budget effect.
  */
-export function buildContextPlan({ targetDir, policy, state = null } = {}) {
-  const { phase, required, advisory } = planEntries({ targetDir, policy, state });
+export function buildContextPlan({ targetDir, policy, state = null, docs = null } = {}) {
+  const { phase, required, advisory } = planEntries({ targetDir, policy, state, docs });
 
   // A plan is a READING, not a load, and the load bounds must not bound it.
   //

package/src/harness/csharp.mjs

@@ -0,0 +1,259 @@
+/**
+ * C# structure scan for the component-diagram generator.
+ *
+ * A "package" is a Unity assembly definition (`.asmdef`) — the assembly is the
+ * unit a C# project is actually built and referenced in. A "component" is a
+ * namespace inside a package: the right granularity for a package-level diagram,
+ * where listing types would overflow the page.
+ *
+ * The scan is deliberately tolerant. A repository with no `.asmdef` files still
+ * gets packages (its top-level folders), because the generator must work on a
+ * plain C# tree and on this framework source itself, where it is run for its
+ * structure alone.
+ */
+
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, dirname, relative, basename } from 'node:path';
+
+/** Directory names never walked: build output, caches, and Cadet's own bookkeeping. */
+export const DEFAULT_EXCLUDED_DIRS = Object.freeze([
+  'node_modules', '.git', '.vs', '.idea', '.cadet',
+  'Library', 'Temp', 'obj', 'bin', 'Logs', 'UserSettings', 'Build', 'Builds', 'MemoryCaptures',
+]);
+
+function toPosix(path) {
+  return String(path).replace(/\\/g, '/');
+}
+
+function isInside(child, parent) {
+  const c = toPosix(child);
+  const p = toPosix(parent);
+  return c === p || c.startsWith(`${p}/`);
+}
+
+/** Every file under `rootDir`, skipping excluded directory names. */
+function walkFiles(rootDir, excluded) {
+  const out = [];
+  const visit = (dir) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!excluded.has(entry.name)) visit(full);
+      } else if (entry.isFile()) {
+        out.push(full);
+      }
+    }
+  };
+  visit(rootDir);
+  return out;
+}
+
+/** The GUID recorded in an `.asmdef.meta`, so `GUID:` references can be resolved. */
+function readMetaGuid(asmdefPath) {
+  try {
+    const text = readFileSync(`${asmdefPath}.meta`, 'utf-8');
+    const m = /guid:\s*([0-9a-fA-F]{32})/.exec(text);
+    return m ? m[1].toLowerCase() : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Discover packages under `rootDir`.
+ *
+ * Returns `{ id, name, dir, asmdefPath, references }`, sorted by id. `references`
+ * names the packages this one depends on; a reference Unity stored as a GUID is
+ * resolved through the `.asmdef.meta`, and one it stored by name through the
+ * assembly name.
+ */
+export function scanPackages(rootDir, { exclude = DEFAULT_EXCLUDED_DIRS } = {}) {
+  const excluded = new Set(exclude);
+  const files = walkFiles(rootDir, excluded);
+
+  const byDir = new Map();
+  const byName = new Map();
+  const byGuid = new Map();
+
+  for (const asmdefPath of files.filter((f) => f.endsWith('.asmdef'))) {
+    let json;
+    try {
+      json = JSON.parse(readFileSync(asmdefPath, 'utf-8'));
+    } catch {
+      // A malformed asmdef is still a package boundary; fall back to its folder.
+      json = {};
+    }
+    const dir = dirname(asmdefPath);
+    const name = typeof json.name === 'string' && json.name ? json.name : basename(dir);
+    const declaredReferences = Array.isArray(json.references)
+      ? json.references.filter((r) => typeof r === 'string')
+      : [];
+    const precompiled = Array.isArray(json.precompiledReferences)
+      ? json.precompiledReferences.filter((r) => typeof r === 'string')
+      : [];
+    const optional = Array.isArray(json.optionalUnityReferences) ? json.optionalUnityReferences : [];
+    const pkg = {
+      id: toPosix(name),
+      name,
+      dir,
+      asmdefPath,
+      // A Unity test assembly, recognised by what it references rather than by
+      // its name. Projects name test assemblies inconsistently, but a test
+      // assembly must reference the TestRunner or nunit to run under the Unity
+      // Test Framework, so that is the reliable signal.
+      isTest: optional.includes('TestAssemblies')
+        || declaredReferences.includes('UnityEngine.TestRunner')
+        || declaredReferences.includes('UnityEditor.TestRunner')
+        || precompiled.includes('nunit.framework.dll'),
+      rawReferences: declaredReferences,
+      references: [],
+    };
+    byDir.set(dir, pkg);
+    byName.set(name, pkg);
+    const guid = readMetaGuid(asmdefPath);
+    if (guid) byGuid.set(guid, pkg);
+  }
+
+  if (byDir.size === 0) return fallbackPackages(rootDir, files);
+
+  for (const pkg of byDir.values()) {
+    const resolved = [];
+    for (const ref of pkg.rawReferences) {
+      const target = ref.startsWith('GUID:')
+        ? byGuid.get(ref.slice(5).toLowerCase())
+        : byName.get(ref);
+      if (target && target.dir !== pkg.dir) resolved.push(target.id);
+    }
+    pkg.references = [...new Set(resolved)].sort();
+    delete pkg.rawReferences;
+  }
+
+  return [...byDir.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/** No `.asmdef` anywhere: each top-level folder that holds C# becomes a package. */
+function fallbackPackages(rootDir, files) {
+  const groups = new Map();
+  for (const file of files.filter((f) => f.endsWith('.cs'))) {
+    const parts = toPosix(relative(rootDir, file)).split('/');
+    const key = parts.length > 1 ? parts[0] : '(root)';
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(file);
+  }
+  return [...groups.keys()].sort().map((name) => ({
+    id: toPosix(name),
+    name,
+    dir: name === '(root)' ? rootDir : join(rootDir, name),
+    asmdefPath: null,
+    isTest: false,
+    references: [],
+  }));
+}
+
+/**
+ * The `.cs` files that belong to a package: those under its directory and not
+ * under a deeper package's directory. Unity nests assemblies, so a file's
+ * owning assembly is its nearest ancestor `.asmdef`.
+ */
+function filesForPackage(pkg, packages, excluded) {
+  const nested = packages
+    .filter((p) => p.dir !== pkg.dir && isInside(p.dir, pkg.dir))
+    .map((p) => p.dir);
+  return walkFiles(pkg.dir, excluded)
+    .filter((f) => f.endsWith('.cs'))
+    .filter((f) => !nested.some((dir) => isInside(dirname(f), dir)))
+    .sort();
+}
+
+/** The file's declared namespace, or null when it declares none. */
+function readNamespace(file) {
+  let text;
+  try {
+    text = readFileSync(file, 'utf-8');
+  } catch {
+    return null;
+  }
+  const m = /^\s*namespace\s+([A-Za-z_][\w.]*)/m.exec(text);
+  return m ? m[1] : null;
+}
+
+/**
+ * Group a package's files into components by namespace, falling back to the
+ * containing folder for files that declare none. Sorted by id for determinism.
+ */
+export function scanComponents(pkg, { packages = [pkg], exclude = DEFAULT_EXCLUDED_DIRS } = {}) {
+  const excluded = new Set(exclude);
+  const groups = new Map();
+  for (const file of filesForPackage(pkg, packages, excluded)) {
+    const namespace = readNamespace(file);
+    const key = namespace || toPosix(relative(pkg.dir, dirname(file))) || '(root)';
+    if (!groups.has(key)) groups.set(key, { namespace, files: [] });
+    groups.get(key).files.push(file);
+  }
+  return [...groups.entries()]
+    .map(([key, group]) => ({
+      id: toPosix(key),
+      name: key,
+      namespace: group.namespace,
+      files: group.files.sort(),
+    }))
+    .sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/**
+ * Best-effort component dependencies from `using` directives.
+ *
+ * A `using` names a namespace, which is matched to the longest component
+ * namespace that is a PREFIX of it: `using A.B.C` maps to a component `A.B` (or
+ * `A.B.C` when that exists), because a namespace nested deeper is a different
+ * component. The reverse match was a bug the real-project test caught: with both
+ * `Dolven.Game.Rendering` and `Dolven.Game.Rendering.Crowd` present, a plain
+ * `using Dolven.Game.Rendering;` was attributed to the longer `…Crowd` sibling.
+ *
+ * This is an approximation by design: it reads declarations, not the compiled
+ * type graph, and it says so in the docs.
+ */
+export function componentEdges(components) {
+  const byNamespace = new Map(components.filter((c) => c.namespace).map((c) => [c.namespace, c.id]));
+  const namespaces = [...byNamespace.keys()];
+
+  const resolve = (ns) => {
+    let best = null;
+    for (const candidate of namespaces) {
+      if (ns === candidate || ns.startsWith(`${candidate}.`)) {
+        if (!best || candidate.length > best.length) best = candidate;
+      }
+    }
+    return best ? byNamespace.get(best) : null;
+  };
+
+  const edges = new Map();
+  const usingRe = /^\s*using\s+(?:static\s+)?([A-Za-z_][\w.]*)\s*;/gm;
+  for (const component of components) {
+    for (const file of component.files) {
+      let text;
+      try {
+        text = readFileSync(file, 'utf-8');
+      } catch {
+        continue;
+      }
+      usingRe.lastIndex = 0;
+      let m;
+      while ((m = usingRe.exec(text)) !== null) {
+        const target = resolve(m[1]);
+        if (target && target !== component.id) {
+          edges.set(`${component.id}\u0000${target}`, { from: component.id, to: target, kind: 'uses' });
+        }
+      }
+    }
+  }
+  return [...edges.values()].sort((a, b) => `${a.from}\u0000${a.to}`.localeCompare(`${b.from}\u0000${b.to}`));
+}
+
+export { toPosix };