@llman-sdd/core 0.1.3 → 0.2.0

package/src/config/surface.ts

@@ -0,0 +1,59 @@
+/**
+ * `config` command surface (r37/r38): read-only overview rendering and
+ * non-interactive extra_skills management with comment-preserving writeback.
+ */
+
+import { parseDocument } from 'yaml';
+
+import { loadConfig } from './load.ts';
+import { EXTRA_SKILLS } from './schema.ts';
+
+/** Render the five-element overview (v1 parity wording). */
+export function renderConfigOverview(source: string): string[] {
+  const config = loadConfig(source);
+  const enabled = (config.extra_skills ?? []).length;
+  const archive = config.archive;
+  const archiveConfigured =
+    archive !== null &&
+    archive !== undefined &&
+    (archive.strict_defer || archive.min_completion_ratio !== undefined);
+  return [
+    `schema: ${config.schema}`,
+    `locale: ${config.locale}`,
+    `extra_skills (enabled/total): ${enabled} / ${EXTRA_SKILLS.length}`,
+    `bdd: ${config.bdd ? 'on' : 'off'}`,
+    `archive: ${archiveConfigured ? 'configured' : 'default'}`,
+  ];
+}
+
+export class ExtraSkillsError extends Error {}
+
+/**
+ * Add/remove extra_skills entries with full comment preservation: only the
+ * `extra_skills` list node is touched, everything else (including the
+ * `$schema` header comment) stays byte-identical.
+ */
+export function setExtraSkills(
+  source: string,
+  change: { set?: readonly string[]; unset?: readonly string[] },
+): string {
+  for (const name of [...(change.set ?? []), ...(change.unset ?? [])]) {
+    if (!(EXTRA_SKILLS as readonly string[]).includes(name)) {
+      throw new ExtraSkillsError(`unknown extra skill: ${name}`);
+    }
+  }
+  const wanted = new Set<string>(loadConfig(source).extra_skills ?? []);
+  for (const name of change.set ?? []) wanted.add(name);
+  for (const name of change.unset ?? []) wanted.delete(name);
+
+  const doc = parseDocument(source);
+  const list = [...wanted].toSorted();
+  if (list.length > 0) doc.set('extra_skills', list);
+  else doc.delete('extra_skills');
+  return doc.toString();
+}
+
+/** Shape of `config skills --json` (v1 parity). */
+export function skillsJson(source: string): { enabled: string[]; available: readonly string[] } {
+  return { enabled: [...(loadConfig(source).extra_skills ?? [])], available: EXTRA_SKILLS };
+}

package/src/git/spawnGit.ts

@@ -79,3 +79,15 @@ export function defaultBranch(git: GitLike): string {
 export function revParseHead(git: GitLike): string {
   return git.run(['rev-parse', 'HEAD']);
 }
+
+/** Count uncommitted files (v1 "dirty tree: N uncommitted files"). */
+export function dirtyCount(git: GitLike): number {
+  const s = git.run(['status', '--porcelain']);
+  if (s === '') return 0;
+  return s.split('\n').filter((l) => l.trim() !== '').length;
+}
+
+/** Fork-point sha of `current` relative to `other` (v1 merge-base semantics). */
+export function mergeBase(git: GitLike, current: string, other: string): string {
+  return git.runOpt(['merge-base', current, other]) ?? git.run(['rev-parse', current]);
+}

package/src/index.ts

@@ -33,6 +33,18 @@ export {
   type SddConfigInput,
 } from './config/schema.ts';
 export { ConfigValidationError, MAX_REPORTED_ISSUES, loadConfig } from './config/load.ts';
+export {
+  ChangeIdError,
+  compileChangeIdPattern,
+  nextUniqueNumber,
+  renderChangeIdTemplate,
+} from './config/changeId.ts';
+export {
+  ExtraSkillsError,
+  renderConfigOverview,
+  setExtraSkills,
+  skillsJson,
+} from './config/surface.ts';
 
 export type {
   CapabilityDoc,
@@ -48,6 +60,16 @@ export {
   parseFeatureSource,
 } from './spec/parser.ts';
 export { buildReqRegistry, type ReqRegistry, type RegistryDuplicate } from './spec/reqRegistry.ts';
+export {
+  addReq,
+  addScenario,
+  allReqIds,
+  AuthoringError,
+  planDedupe,
+  resolveReq,
+  type DedupePlanItem,
+  type ResolvedReq,
+} from './spec/authoring.ts';
 export type {
   SpecEntry,
   SpecIo,
@@ -56,7 +78,26 @@ export type {
   ValidationLevel,
   ValidationReport,
 } from './validation/validate.ts';
-export { validateAllSpecs, validateCapability } from './validation/validate.ts';
+export { validateAllSpecs, validateCapability, applyStrict } from './validation/validate.ts';
+export { splitVerb } from './config/changeId.ts';
+export {
+  evaluateStaleness,
+  notApplicableStaleness,
+  type StalenessInfo,
+} from './validation/staleness.ts';
+export {
+  checkChangeDoc,
+  validateChange,
+  expandRunCommand,
+  hasPlaceholders,
+  STAGE_ORDER,
+  type ChangeCheckConfig,
+  type ChangeCheckInput,
+  type ChangeCheckResult,
+  type ChangeIssue,
+  type ChangeFsIoLite,
+  type StageGate,
+} from './validation/changeCheck.ts';
 export { discoverSpecs, type DiscoveryIo } from './validation/discover.ts';
 export type { ChangeBinding } from './change/frontmatter.ts';
 export { readBinding, writeBinding } from './change/frontmatter.ts';
@@ -70,6 +111,7 @@ export {
   type GitLike,
 } from './git/spawnGit.ts';
 export { DRAFT_PROPOSAL_TEMPLATE, deriveChangeId, isLegalChangeId } from './change/id.ts';
+export { extractUniqueNumber, harvestUniqueNumbers } from './change/nextId.ts';
 export {
   CHANGES_DIR,
   LifecycleError,
@@ -80,6 +122,9 @@ export {
   startChange,
   type FinalizeResult,
   type FsIo,
+  archiveChange,
+  archiveTaskGate,
+  changeDiffInfo,
 } from './change/lifecycle.ts';
 export { normalizeLocale, localeFallbacks } from './templates/locale.ts';
 export {
@@ -144,7 +189,13 @@ export {
   type SpecMorphology,
   type SpecSummary,
 } from './report/specs.ts';
-export { SevenZipError, makeWasmSevenZip, type SevenZipPort } from './archive/sevenzip.ts';
+export {
+  SevenZipError,
+  embeddedWasmBinary,
+  makeWasmSevenZip,
+  resolveEmbeddedWasmB64,
+  type SevenZipPort,
+} from './archive/sevenzip.ts';
 export {
   ARCHIVE_DIR_REL,
   FREEZE_ARCHIVE_NAME,

package/src/report/collect.ts

@@ -37,8 +37,10 @@ export function stageFor(
   hasTasks: boolean,
   hasBinding: boolean,
 ): ChangeSummary['stage'] {
-  if (hasBinding) return 'full';
-  if (hasTasks) return 'planned';
+  // Monotonic v1 parity (r34): design.md gates designed, tasks.md only
+  // upgrades on top of design, binding only upgrades the complete set.
+  if (hasDesign && hasTasks && hasBinding) return 'full';
+  if (hasDesign && hasTasks) return 'planned';
   if (hasDesign) return 'designed';
   return 'draft';
 }
@@ -64,17 +66,32 @@ export function firstH1(md: string): string {
   return '';
 }
 
-export function collectChanges(io: ChangeFsIo, root: string, now: Date): ChangeSummary[] {
+export function collectChanges(
+  io: ChangeFsIo,
+  root: string,
+  now: Date,
+  opts: { maxScanDepth?: number } = {},
+): ChangeSummary[] {
   const changesDir = `${root}/${CHANGES_DIR}`;
   if (!io.exists(changesDir) || !io.isDirectory(changesDir)) return [];
+  const maxDepth = opts.maxScanDepth ?? 8;
   const out: ChangeSummary[] = [];
-  for (const name of io.listDir(changesDir).toSorted()) {
-    if (name === 'archive') continue;
-    const dir = `${changesDir}/${name}`;
-    if (!io.isDirectory(dir)) continue;
+  // r58: recursive, depth-limited proposal discovery (v1 --max-scan-depth parity)
+  const visit = (dir: string, depth: number): void => {
+    if (depth > maxDepth) return;
+    for (const name of io.listDir(dir).toSorted()) {
+      if (name === 'archive' || name.startsWith('.')) continue;
+      const child = `${dir}/${name}`;
+      if (!io.isDirectory(child)) continue;
+      if (io.exists(`${child}/proposal.md`)) {
+        readChangeDir(child, name);
+      } else {
+        visit(child, depth + 1);
+      }
+    }
+  };
+  const readChangeDir = (dir: string, name: string): void => {
     const proposal = `${dir}/proposal.md`;
-    if (!io.exists(proposal)) continue;
-
     const hasDesign = io.exists(`${dir}/design.md`);
     const hasTasks = io.exists(`${dir}/tasks.md`);
     const hasBinding = readBinding(io.readText(proposal)) !== null;
@@ -101,7 +118,8 @@ export function collectChanges(io: ChangeFsIo, root: string, now: Date): ChangeS
       lastModified,
       idleDays,
     });
-  }
+  };
+  visit(changesDir, 1);
   // v1 lists newest-first
   return out.toSorted((a, b) => b.lastModified.getTime() - a.lastModified.getTime());
 }
@@ -130,12 +148,10 @@ export function pad(s: string, width: number): string {
 export function renderChangesList(changes: readonly ChangeSummary[], now: Date): string[] {
   const lines = ['Active changes:'];
   if (changes.length === 0) return lines;
-  const nameWidth = Math.max(...changes.map((c) => c.name.length)) + 2;
-  const stageWidth = Math.max(...changes.map((c) => c.stage.length)) + 7;
-  const statusWidth = Math.max(...changes.map((c) => statusHuman(c).length)) + 5;
+  const nameWidth = Math.max(...changes.map((c) => c.name.length));
   for (const c of changes) {
     lines.push(
-      `  ${pad(c.name, nameWidth)}${pad(c.stage, stageWidth)}${pad(statusHuman(c), statusWidth)}${relativeTime(
+      `  ${pad(c.name, nameWidth)}  ${pad(c.stage, 10)}  ${pad(statusHuman(c), 12)}  ${relativeTime(
         c.lastModified,
         now,
       )}${statusFor(c.totalTasks, c.completedTasks) === 'no-tasks' ? ` (idle ${c.idleDays}d)` : ''}`,

package/src/report/graph.ts

@@ -1,8 +1,10 @@
 /**
- * Change dependency graph (peripheral-commands capability, r21):
- * mermaid output with v1 conventions — node ids dash→underscore, archived
- * changes annotated "✓ done" with the archived class, depends_on edges.
+ * Change dependency graph (peripheral-commands capability, r21/r30/r54):
+ * v1 `commands/graph.rs` observable contract — scope parsing, connected
+ * component subgraphs, conditional classDef, empty placeholder, bidirectional
+ * seed BFS, error paths. Pure: IO injected.
  */
+
 import { CHANGES_DIR } from '../change/lifecycle.ts';
 
 export interface GraphFsIo {
@@ -15,77 +17,371 @@ export interface GraphFsIo {
 interface GraphNode {
   id: string;
   archived: boolean;
-  dependsOn: string[];
+  /** true = directory on disk; false = phantom (frozen/removed dependency). */
+  present: boolean;
+}
+
+interface DepEdge {
+  from: string;
+  to: string;
 }
 
-/** Extract depends_on entries from a proposal's YAML frontmatter. */
-function parseDeps(proposal: string): string[] {
+export class GraphError extends Error {}
+
+function extractArchivedId(name: string): string | null {
+  const m = name.match(/^\d{4}-\d{2}-\d{2}-(.+)$/u);
+  return m ? (m[1] ?? null) : null;
+}
+
+/** Extract depends_on entries (flow + block styles, r30). */
+export function parseDeps(proposal: string): string[] {
   const fm = proposal.match(/^---\n([\s\S]*?)\n---/u);
   const deps: string[] = [];
   if (!fm?.[1]) return deps;
   let inDeps = false;
   for (const line of fm[1].split('\n')) {
+    const flow = line.match(/^depends_on:\s*\[([^\]]*)\]\s*$/u);
+    if (flow) {
+      for (const item of flow[1]?.split(',') ?? []) {
+        const dep = item.trim().replaceAll(/^['"]|['"]$/gu, '');
+        if (dep !== '' && !/^[0-9]+$/u.test(dep)) deps.push(dep);
+      }
+      inDeps = false;
+      continue;
+    }
     if (/^depends_on:\s*$/u.test(line)) {
       inDeps = true;
       continue;
     }
     if (inDeps) {
       const m = line.match(/^\s*-\s+(\S+)/u);
-      if (m?.[1]) deps.push(m[1]);
+      if (m?.[1] && !/^[0-9]+$/u.test(m[1])) deps.push(m[1]);
       else if (line.trim() !== '') inDeps = false;
     }
   }
   return deps;
 }
 
-function collectNodes(io: GraphFsIo, root: string): GraphNode[] {
-  const nodes: GraphNode[] = [];
-  const scan = (dir: string, archived: boolean, stripDatePrefix: boolean): void => {
-    if (!io.exists(dir) || !io.isDirectory(dir)) return;
+type ScopeKind = 'active' | 'archived';
+
+function parseScope(scope: string): ScopeKind[] {
+  if (scope === 'all') return ['active', 'archived'];
+  const kinds: ScopeKind[] = [];
+  for (const part of scope.split(',')) {
+    const t = part.trim();
+    if (t === 'active') kinds.push('active');
+    else if (t === 'archived') kinds.push('archived');
+    else {
+      throw new GraphError(
+        `Unknown scope: '${flagClean(t)}'. Supported: active, archived, all (or comma-separated like active,archived)`,
+      );
+    }
+  }
+  if (kinds.length === 0) throw new GraphError('Scope cannot be empty');
+  return kinds;
+}
+
+function flagClean(v: string): string {
+  return v;
+}
+
+/** Active nodes: dirs (recursively) with a proposal.md (v1 discovery). */
+function collectActiveNodes(io: GraphFsIo, root: string): GraphNode[] {
+  const out: GraphNode[] = [];
+  const changesDir = `${root}/${CHANGES_DIR}`;
+  if (!io.exists(changesDir) || !io.isDirectory(changesDir)) return out;
+  const visit = (dir: string): void => {
     for (const name of io.listDir(dir).toSorted()) {
-      if (name === 'archive') continue;
-      const full = `${dir}/${name}`;
-      if (!io.isDirectory(full)) continue;
-      const proposal = `${full}/proposal.md`;
-      if (!io.exists(proposal)) continue;
-      const id = archived && stripDatePrefix ? name.replace(/^\d{4}-\d{2}-\d{2}-/u, '') : name;
-      nodes.push({ id, archived, dependsOn: parseDeps(io.readText(proposal)) });
+      if (name === 'archive' || name.startsWith('.')) continue;
+      const child = `${dir}/${name}`;
+      if (!io.isDirectory(child)) continue;
+      if (io.exists(`${child}/proposal.md`)) {
+        out.push({ id: name, archived: false, present: true });
+      } else {
+        visit(child);
+      }
     }
   };
-  scan(`${root}/${CHANGES_DIR}`, false, false);
-  // archived nodes appear only when referenced by an active depends_on
-  const referenced = new Set(nodes.flatMap((n) => n.dependsOn));
+  visit(changesDir);
+  return out;
+}
+
+function collectArchivedNodes(io: GraphFsIo, root: string): GraphNode[] {
   const archiveDir = `${root}/${CHANGES_DIR}/archive`;
-  if (io.exists(archiveDir) && io.isDirectory(archiveDir)) {
-    for (const name of io.listDir(archiveDir).toSorted()) {
-      if (!/\d{4}-\d{2}-\d{2}-/u.test(name)) continue;
-      const id = name.replace(/^\d{4}-\d{2}-\d{2}-/u, '');
-      if (!referenced.has(id)) continue;
-      // archived nodes keep their real depends_on — v1 emits their edges too
-      const proposal = `${archiveDir}/${name}/proposal.md`;
-      const deps = io.exists(proposal) ? parseDeps(io.readText(proposal)) : [];
-      nodes.push({ id, archived: true, dependsOn: deps });
+  if (!io.exists(archiveDir) || !io.isDirectory(archiveDir)) return [];
+  const out: GraphNode[] = [];
+  const seen = new Set<string>();
+  for (const name of io.listDir(archiveDir)) {
+    const child = `${archiveDir}/${name}`;
+    if (!io.isDirectory(child)) continue;
+    const id = extractArchivedId(name);
+    if (id !== null && !seen.has(id)) {
+      seen.add(id);
+      out.push({ id, archived: true, present: true });
     }
   }
-  return nodes;
+  return out;
 }
 
-export function graphMermaid(io: GraphFsIo, root: string): string[] {
-  const nodes = collectNodes(io, root);
-  const lines: string[] = ['flowchart TD'];
+function collectNodes(io: GraphFsIo, root: string, kinds: ScopeKind[]): GraphNode[] {
+  const combined: GraphNode[] = [];
+  const seen = new Set<string>();
+  for (const kind of kinds) {
+    const nodes = kind === 'active' ? collectActiveNodes(io, root) : collectArchivedNodes(io, root);
+    for (const node of nodes) {
+      if (!seen.has(node.id)) {
+        seen.add(node.id);
+        combined.push(node);
+      }
+    }
+  }
+  return combined;
+}
+
+function proposalFor(io: GraphFsIo, root: string, node: GraphNode): string {
+  if (node.archived) {
+    const archiveDir = `${root}/${CHANGES_DIR}/archive`;
+    // latest matching dirtategy: pick the newest date-prefixed dir
+    let best = '';
+    let bestDate = '';
+    for (const name of io.listDir(archiveDir)) {
+      const id = extractArchivedId(name);
+      if (id !== node.id) continue;
+      const date = name.slice(0, 10);
+      if (best === '' || date > bestDate) {
+        best = name;
+        bestDate = date;
+      }
+    }
+    const p = `${archiveDir}/${best}/proposal.md`;
+    return io.exists(p) ? io.readText(p) : '';
+  }
+  const changesDir = `${root}/${CHANGES_DIR}`;
+  const found: string[] = [];
+  const visit = (dir: string): void => {
+    for (const name of io.listDir(dir).toSorted()) {
+      if (name === 'archive' || name.startsWith('.')) continue;
+      const child = `${dir}/${name}`;
+      if (!io.isDirectory(child)) continue;
+      if (io.exists(`${child}/proposal.md`)) {
+        if (name === node.id) found.push(`${child}/proposal.md`);
+        continue;
+        // ^ leaf change dir — do not descend further
+      }
+      visit(child);
+    }
+  };
+  visit(changesDir);
+  if (found.length === 0) return '';
+  return io.readText(found[0] ?? '');
+}
+
+interface RelationMaps {
+  depends: Map<string, string[]>;
+  reverse: Map<string, string[]>;
+  nodeSet: Set<string>;
+}
+
+function buildMaps(io: GraphFsIo, root: string, nodes: GraphNode[]): RelationMaps {
+  const depends = new Map<string, string[]>();
+  const reverse = new Map<string, string[]>();
+  const nodeSet = new Set<string>();
   for (const node of nodes) {
-    const nid = node.id.replaceAll('-', '_');
-    const label = node.archived ? `${node.id} ✓ done` : node.id;
-    lines.push(`    ${nid}["${label}"]${node.archived ? ':::archived' : ''}`);
+    nodeSet.add(node.id);
+    if (!node.present) continue;
+    for (const dep of parseDeps(proposalFor(io, root, node))) {
+      depends.set(node.id, [...(depends.get(node.id) ?? []), dep]);
+      reverse.set(dep, [...(reverse.get(dep) ?? []), node.id]);
+    }
+  }
+  return { depends, reverse, nodeSet };
+}
+
+function buildDefaultNodes(io: GraphFsIo, root: string, kinds: ScopeKind[]): GraphNode[] {
+  const nodes = collectNodes(io, root, kinds);
+  const nodeIds = new Set(nodes.map((n) => n.id));
+  const all = collectNodes(io, root, ['active', 'archived']);
+  const allMap = new Map(all.map((n) => [n.id, n]));
+
+  const missing: string[] = [];
+  for (const node of all) {
+    if (!nodeIds.has(node.id) || !node.present) continue;
+    for (const dep of parseDeps(proposalFor(io, root, node))) {
+      if (!nodeIds.has(dep)) missing.push(dep);
+    }
+  }
+  const seenMissing = new Set<string>();
+  for (const dep of missing) {
+    if (seenMissing.has(dep)) continue;
+    seenMissing.add(dep);
+    const existing = allMap.get(dep);
+    if (existing !== undefined) nodes.push(existing);
+    else nodes.push({ id: dep, archived: false, present: false });
   }
-  const byId = new Set(nodes.map((n) => n.id));
+  return nodes;
+}
+
+function collectEdges(io: GraphFsIo, root: string, nodes: GraphNode[]): DepEdge[] {
+  const nodeIds = new Set(nodes.map((n) => n.id));
+  const edges: DepEdge[] = [];
   for (const node of nodes) {
-    for (const dep of node.dependsOn) {
-      // edges render only when both endpoints are shown nodes
-      if (!byId.has(dep)) continue;
-      lines.push(`    ${node.id.replaceAll('-', '_')} -->|depends on| ${dep.replaceAll('-', '_')}`);
+    if (!node.present) continue;
+    for (const dep of parseDeps(proposalFor(io, root, node))) {
+      if (nodeIds.has(dep)) edges.push({ from: node.id, to: dep });
     }
   }
-  lines.push('    classDef archived fill:#d4edda,stroke:#28a745,color:#333');
+  return edges;
+}
+
+function connectedComponents(nodeIds: string[], edges: DepEdge[]): string[][] {
+  if (nodeIds.length === 0) return [];
+  const parent = new Map<string, string>(nodeIds.map((id) => [id, id]));
+  const find = (x: string): string => {
+    let root = parent.get(x) ?? x;
+    while (parent.get(root) !== root) root = parent.get(root) ?? root;
+    return root;
+  };
+  const union = (a: string, b: string): void => {
+    const ra = find(a);
+    const rb = find(b);
+    if (ra !== rb) parent.set(ra, rb);
+  };
+  for (const edge of edges) union(edge.from, edge.to);
+  const groups = new Map<string, string[]>();
+  for (const id of nodeIds) {
+    const root = find(id);
+    groups.set(root, [...(groups.get(root) ?? []), id]);
+  }
+  return [...groups.values()].toSorted((a, b) => b.length - a.length);
+}
+
+function componentLabel(nodes: GraphNode[], ids: Set<string>): string {
+  const comp = nodes.filter((n) => ids.has(n.id));
+  const allActive = comp.every((n) => !n.archived && n.present);
+  const allArchived = comp.every((n) => n.archived);
+  if (allActive) return 'Active';
+  if (allArchived) return 'Done';
+  return 'Mixed';
+}
+
+const sanitize = (id: string): string => id.replaceAll('-', '_');
+
+export interface GraphOptions {
+  scope?: string;
+  depth?: number;
+  seed?: string;
+}
+
+export function graphMermaid(io: GraphFsIo, root: string, opts: GraphOptions = {}): string[] {
+  const scope = opts.scope ?? 'active';
+  const kinds = parseScope(scope);
+
+  let nodes: GraphNode[];
+  if (opts.seed !== undefined) {
+    nodes = buildSeedNeighborhood(io, root, opts.seed, opts.depth ?? 1, kinds);
+  } else {
+    nodes = buildDefaultNodes(io, root, kinds);
+  }
+
+  if (nodes.length === 0) {
+    return [
+      'flowchart TD',
+      opts.seed !== undefined
+        ? `    empty["Change '${opts.seed}' not found or has no relationships"]`
+        : `    empty["No changes in scope '${scope}'"]`,
+    ];
+  }
+
+  const edges = collectEdges(io, root, nodes);
+  const nodeIds = nodes.map((n) => n.id);
+  const components = connectedComponents(nodeIds, edges);
+  const hasArchived = nodes.some((n) => n.archived);
+  const hasMissing = nodes.some((n) => !n.present);
+
+  const lines = ['flowchart TD'];
+  if (components.length > 1) {
+    components.forEach((comp, idx) => {
+      const ids = new Set(comp);
+      const label = componentLabel(nodes, ids);
+      lines.push(`    subgraph sg${idx + 1}["${label}"]`);
+      renderNodesAndEdges(nodes, edges, ids, lines, true);
+      lines.push('    end');
+    });
+  } else {
+    renderNodesAndEdges(nodes, edges, new Set(nodeIds), lines, false);
+  }
+  if (hasArchived) lines.push('    classDef archived fill:#d4edda,stroke:#28a745,color:#333');
+  if (hasMissing) lines.push('    classDef missing fill:#f8d7da,stroke:#dc3545,color:#333');
   return lines;
 }
+
+function renderNodesAndEdges(
+  nodes: GraphNode[],
+  edges: DepEdge[],
+  ids: Set<string>,
+  lines: string[],
+  indented: boolean,
+): void {
+  const pad = indented ? '        ' : '    ';
+  for (const node of nodes) {
+    if (!ids.has(node.id)) continue;
+    if (!node.present) lines.push(`${pad}${sanitize(node.id)}["${node.id} ⚠ missing"]:::missing`);
+    else if (node.archived)
+      lines.push(`${pad}${sanitize(node.id)}["${node.id} ✓ done"]:::archived`);
+    else lines.push(`${pad}${sanitize(node.id)}["${node.id}"]`);
+  }
+  for (const edge of edges) {
+    if (!ids.has(edge.from)) continue;
+    lines.push(`${pad}${sanitize(edge.from)} -->|depends on| ${sanitize(edge.to)}`);
+  }
+}
+
+/** Seed neighborhood: bidirectional BFS (depends_on + reverse) over both sets. */
+function buildSeedNeighborhood(
+  io: GraphFsIo,
+  root: string,
+  seedId: string,
+  maxDepth: number,
+  _kinds: ScopeKind[],
+): GraphNode[] {
+  const resolved = resolveSeedId(io, root, seedId);
+  const allNodes = collectNodes(io, root, ['active', 'archived']);
+  const nodeMap = new Map(allNodes.map((n) => [n.id, n]));
+  if (!nodeMap.has(resolved)) {
+    const prefix = resolved.split('-')[0] ?? '';
+    const suggestions = [...nodeMap.keys()].filter((k) => k.startsWith(prefix));
+    const hint = suggestions.length > 0 ? ` Did you mean: ${suggestions.join(', ')}?` : '';
+    throw new GraphError(`change '${seedId}' not found.${hint}`);
+  }
+  const maps = buildMaps(io, root, allNodes);
+  const visited = new Set<string>([resolved]);
+  const queue: [string, number][] = [[resolved, 0]];
+  while (queue.length > 0) {
+    const [current, depth] = queue.shift() as [string, number];
+    if (depth >= maxDepth) continue;
+    const neighbors = [...(maps.depends.get(current) ?? []), ...(maps.reverse.get(current) ?? [])];
+    for (const neighbor of neighbors) {
+      if (maps.nodeSet.has(neighbor) && !visited.has(neighbor)) {
+        visited.add(neighbor);
+        queue.push([neighbor, depth + 1]);
+      }
+    }
+  }
+  const result = [...visited]
+    .filter((id) => nodeMap.has(id))
+    .map((id) => nodeMap.get(id) as GraphNode);
+  result.sort((a, b) => a.id.localeCompare(b.id));
+  return result;
+}
+
+function resolveSeedId(io: GraphFsIo, root: string, seedId: string): string {
+  const active = collectActiveNodes(io, root);
+  const archived = collectArchivedNodes(io, root);
+  const all = [...active.map((n) => n.id), ...archived.map((n) => n.id)];
+  if (all.includes(seedId)) return seedId;
+  const viaPrefix = all.filter((id) => id.startsWith(seedId));
+  if (viaPrefix.length === 1) return viaPrefix[0] ?? seedId;
+  const viaArchivedPrefix = archived.map((n) => n.id).filter((id) => id.startsWith(seedId));
+  if (viaArchivedPrefix.length === 1) return viaArchivedPrefix[0] ?? seedId;
+  return seedId;
+}