cans-spec 0.1.2 → 0.3.0

package/src/core/refs.ts

@@ -1,8 +1,8 @@
 import { readFileSync } from 'fs';
 import { join } from 'path';
-import type { OutlineNode, RefTarget, BackPointer, Issue } from '../types';
-import { flattenNodes, parseOutline } from './outline';
-import { resolveSpecFile, toRelative, isFile } from './fs';
+import type { OutlineNode, RefTarget, BackPointer, Issue } from '../types.ts';
+import { flattenNodes, parseOutline } from './outline.ts';
+import { resolveSpecFile, toRelative, isFile } from './fs.ts';
 
 export interface RefGraph {
   forward: Map<string, RefTarget[]>;
@@ -46,6 +46,25 @@ export function anchorMatches(nodeText: string, anchor: string): boolean {
   return norm(nodeText) === norm(anchor);
 }
 
+/** Does an UNRESOLVED ref target look like an intended spec reference
+ *  (broken-ref error territory) or like English prose that merely contains
+ *  the word "see" (warning territory)? (issue #4)
+ *
+ *  The §11 ref regex intentionally keeps minting refs from any `see <token>`
+ *  prose ("see the runbook", "see below") so banner counts and deep-hop/orphan
+ *  machinery stay centralized in the graph. Classification happens only at
+ *  resolution time, in checkRefs: a target that itself looks spec-shaped keeps
+ *  the documented broken-ref error; anything else is prose, not a dangling
+ *  spec pointer. */
+export function looksLikeSpecRef(target: string, hasAnchor: boolean): boolean {
+  if (hasAnchor) return true;                      // see X#anchor — explicit anchor intent
+  if (/\.md$/i.test(target)) return true;           // explicit markdown target
+  if (/^_/.test(target)) return true;               // workspace service dirs (_tasks/, _collab/, ...)
+  if (target.includes('/')) return true;            // path-like
+  if (/^\d/.test(target)) return true;              // numeric-prefix spec stems (02-auth)
+  return false;
+}
+
 export function buildRefGraph(
   files: Map<string, OutlineNode[]>,
   root: string,
@@ -106,11 +125,28 @@ export function checkRefs(
         // loaded numeric span, a missing file is always a level:error broken
         // ref. (The former "unwritten spec slot" backward in-span downgrade
         // violated §12 and masked real holes as warnings — removed.)
-        issues.push({
-          file, line: ref.line, level: 'error', category: 'refs',
-          message: `broken ref: see ${ref.file} — file not found`,
-          suggestion: `create ${ref.file} or fix the ref target`,
-        });
+        //
+        // Issue #4 prose exemption: that error contract applies to targets that
+        // THEMSELVES look like intended spec references (looksLikeSpecRef —
+        // anchored, .md, workspace-service-dir, path-like, or numeric-prefix).
+        // English prose that merely contains the word "see" ("see the runbook",
+        // "see below") mints a ref target that resolves to nothing and is not
+        // spec-shaped — downgraded to a see-like-prose warning so natural
+        // language no longer fails the run. Genuinely malformed real refs
+        // (.md targets, anchors, paths, numeric stems) keep the exact error.
+        if (looksLikeSpecRef(ref.file, ref.anchor !== null)) {
+          issues.push({
+            file, line: ref.line, level: 'error', category: 'refs',
+            message: `broken ref: see ${ref.file} — file not found`,
+            suggestion: `create ${ref.file} or fix the ref target`,
+          });
+        } else {
+          issues.push({
+            file, line: ref.line, level: 'warning', category: 'refs',
+            message: `see-like prose: "see ${ref.file}" did not resolve to a spec file — rephrase or link explicitly`,
+            suggestion: 'use "see: <file>.md" (or "see: <file>.md#<anchor>") to link a spec file, or reword the sentence',
+          });
+        }
         continue;
       }
 
@@ -150,10 +186,33 @@ export function checkRefs(
 
 /** Deep-hop detection: a file that both receives refs and issues them extends
  *  the ref chain. `maxHops` (§18 references.max_hops, default 1) is the number
- *  of allowed hops: a chain whose hop count through `b` exceeds it is flagged.
- *  Hop count for file `b` with outgoing refs = (longest incoming chain into b) + 1.
- *  §18 delete-key semantics: maxHops null (key deleted) → the check is OFF —
- *  skipped entirely. */
+ *  of allowed hops.
+ *
+ *  Semantics (issue #5):
+ *  - Nodes are the loaded file keys; an edge a → b exists when a holds a see:
+ *    ref resolving to loaded file b (targetMatchesKey, flat and folder
+ *    layouts). Self-refs never form edges — checkRefs reports those.
+ *  - Strongly-connected meshes (2-cycles, 3-cycles, any mutual back-reference
+ *    cluster — the shape the engine's own redundancy guidance encourages) are
+ *    collapsed via Tarjan's SCC. A ref from b back into b's own mesh is the
+ *    documented back-reference pattern and is never a hop; only refs LEAVING
+ *    b's mesh extend a chain, so a pure mesh can never be flagged.
+ *  - For a file b with a mesh-exiting outgoing ref, the hop count is the
+ *    longest chain of refs ending at b (counted over simple paths, so a mesh
+ *    cannot poison the count) + 1 for b's outgoing edge. Chains are counted
+ *    with a cycle-safe bounded search: nothing is memoized from a truncated
+ *    traversal (the old depthOf cached values computed under its cycle guard,
+ *    making symmetric graphs flag asymmetrically depending on iteration
+ *    order); only confirmed saturations at maxHops are cached, and those hold
+ *    for every caller. Hop count above maxHops flags b.
+ *  - The suggested fix (`add "see: <out>" directly to <from>`, where from is
+ *    the deepest direct referrer of b, ties broken by file key sort so output
+ *    is stable) is never a self-reference: from ≠ b holds because incoming
+ *    lists exclude self, and from = out would place from, b and out in one
+ *    SCC — guarded defensively anyway, so the advice can never convert a
+ *    deep-hop error into a checkRefs self-reference error.
+ *  - §18 delete-key semantics: maxHops null (key deleted) → the check is OFF —
+ *    skipped entirely. */
 export function detectDeepHops(graph: RefGraph, maxHops: number | null = 1): Issue[] {
   if (maxHops === null) return [];
   const issues: Issue[] = [];
@@ -175,31 +234,109 @@ export function detectDeepHops(graph: RefGraph, maxHops: number | null = 1): Iss
     }
   }
 
-  // depth(x) = length of the longest incoming chain ending at x (0 = no incoming).
-  const depth = new Map<string, number>();
-  const visiting = new Set<string>();
+  // Tarjan's SCC over exactly the edges `incoming` encodes (adjacency is
+  // derived from it, so classification and cycle detection cannot disagree).
+  // Recursive is fine: spec workspaces are tiny, and traversal depth is
+  // bounded by the file count either way.
+  const sccId = new Map<string, number>();
+  {
+    const adj = new Map<string, string[]>();
+    for (const [b, referrers] of incoming) {
+      for (const a of referrers) {
+        const list = adj.get(a) ?? [];
+        if (!list.includes(b)) list.push(b);
+        adj.set(a, list);
+      }
+    }
+    const index = new Map<string, number>();
+    const low = new Map<string, number>();
+    const onStack = new Set<string>();
+    const stack: string[] = [];
+    let counter = 0;
+    let components = 0;
+    const strongconnect = (v: string): void => {
+      index.set(v, counter);
+      low.set(v, counter);
+      counter += 1;
+      stack.push(v);
+      onStack.add(v);
+      for (const w of adj.get(v) ?? []) {
+        if (!index.has(w)) {
+          strongconnect(w);
+          low.set(v, Math.min(low.get(v)!, low.get(w)!));
+        } else if (onStack.has(w)) {
+          low.set(v, Math.min(low.get(v)!, index.get(w)!));
+        }
+      }
+      if (low.get(v) === index.get(v)) {
+        let w: string;
+        do {
+          w = stack.pop()!;
+          onStack.delete(w);
+          sccId.set(w, components);
+        } while (w !== v);
+        components += 1;
+      }
+    };
+    for (const v of [...keys].sort()) {
+      if (!index.has(v)) strongconnect(v);
+    }
+  }
+
+  // First loaded key a raw ref target matches — the same first-match loop the
+  // incoming map uses, so ref classification and edge building always agree.
+  const resolveKey = (name: string): string | null => {
+    for (const key of keys) {
+      if (targetMatchesKey(name, key)) return key;
+    }
+    return null;
+  };
+
+  // depth(x) = longest chain of refs ending at x, over simple paths (no file
+  // repeats), saturated at maxHops — the flag decision only ever needs to know
+  // whether the chain reaches maxHops. Values are computed per query with a
+  // fresh path-visited set; ONLY confirmed saturations are cached, and a
+  // saturation is a graph property that holds for every caller.
+  const saturated = new Set<string>();
+  const explore = (x: string, visited: Set<string>, len: number): number => {
+    let best = len;
+    if (best >= maxHops) return best;
+    for (const u of incoming.get(x) ?? []) {
+      if (visited.has(u)) continue;
+      visited.add(u);
+      best = Math.max(best, explore(u, visited, len + 1));
+      visited.delete(u);
+      if (best >= maxHops) return best;
+    }
+    return best;
+  };
   const depthOf = (x: string): number => {
-    const memo = depth.get(x);
-    if (memo !== undefined) return memo;
-    if (visiting.has(x)) return 0; // cycle guard
-    visiting.add(x);
-    let d = 0;
-    for (const a of incoming.get(x) ?? []) {
-      if (a === x) continue;
-      d = Math.max(d, depthOf(a) + 1);
+    if (saturated.has(x)) return maxHops;
+    const d = explore(x, new Set([x]), 0);
+    if (d >= maxHops) {
+      saturated.add(x);
+      return maxHops;
     }
-    visiting.delete(x);
-    depth.set(x, d);
     return d;
   };
 
   for (const [b, outTargets] of graph.forward) {
-    const outgoing = outTargets.filter(r => r.file !== b);
+    const bScc = sccId.get(b);
+    if (bScc === undefined) continue; // unreachable: every key is a Tarjan node
+    const outgoing = outTargets.filter(r => {
+      if (r.file === b) return false; // self-reference, as before
+      const t = resolveKey(r.file);
+      if (t !== null && sccId.get(t) === bScc) return false; // back-ref into b's own mesh
+      return true;
+    });
     if (outgoing.length === 0) continue;
     if (depthOf(b) + 1 <= maxHops) continue;
+    // Deepest direct referrer names the chain; ties break by file key sort so
+    // the output never depends on map iteration order.
+    const referrers = (incoming.get(b) ?? []).slice().sort();
     let from: string | null = null;
     let best = -1;
-    for (const a of incoming.get(b) ?? []) {
+    for (const a of referrers) {
       const d = depthOf(a);
       if (d > best) {
         best = d;
@@ -208,6 +345,11 @@ export function detectDeepHops(graph: RefGraph, maxHops: number | null = 1): Iss
     }
     if (from === null) continue;
     const out = outgoing[0];
+    // Defensive invariant (issue #5 defect 2): the suggested fix must never be
+    // a self-reference — checkRefs rejects those, so the advice would turn one
+    // error into another. from ≠ b holds by construction; from = out would
+    // put from, b and out in one SCC. Skip rather than emit a broken fix.
+    if (from === b || from === out.file) continue;
     const anchor = out.anchor !== null ? `#${out.anchor}` : '';
     issues.push({
       file: b, line: out.line, level: 'error', category: 'refs',

package/src/core/rules.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import type { Rules } from '../types';
+import type { Rules } from '../types.ts';
 
 interface YLine {
   lineNo: number;
@@ -221,6 +221,7 @@ export function defaultRules(): Rules {
       word_frequency_threshold: 4,
       phrase_overlap_threshold: 0.7,
       cross_file_threshold: 2,
+      fuzzy: true,
       stopwords: ['the', 'a', 'an', 'of', 'to', 'in', 'for', 'and', 'or', 'with', 'must', 'shall', 'requires'],
       synonyms: [
         ['postgres', 'postgresql', 'pg'],
@@ -298,6 +299,21 @@ function validateRulesShape(merged: Record<string, unknown>, source: string): vo
       ) {
         throw new Error(`${at} — "${section}.${key}" must be a mapping like { min: 3, max: 120 }`);
       }
+      // Issue #2: style.prefer / references.mode are validated reserved values.
+      // The merged object always carries the (valid) defaults, so an invalid
+      // value can only come from the user's _rules.yaml. `null` (an empty
+      // `prefer:` / `mode:`) is accepted and means the documented default; a
+      // non-string (e.g. `prefer: 42`) fails the same got-value convention.
+      if (section === 'style' && key === 'prefer') {
+        if (v !== null && (typeof v !== 'string' || (v !== 'sibling' && v !== 'nested'))) {
+          throw new Error(`${at} — "style.prefer" must be "sibling" or "nested", got "${String(v)}"`);
+        }
+      }
+      if (section === 'references' && key === 'mode') {
+        if (v !== null && (typeof v !== 'string' || v !== 'pointer')) {
+          throw new Error(`${at} — "references.mode" must be "pointer", got "${String(v)}"`);
+        }
+      }
     }
   }
 }
@@ -307,7 +323,10 @@ function validateRulesShape(merged: Record<string, unknown>, source: string): vo
  *  token_budget.enabled/default_limit/estimate_chars_per_token) are listed too:
  *  they count towards a section's coverage but are never flipped OFF — omitted
  *  parameters keep their documented defaults (§18 overrides only what the file
- *  lists for them). */
+ *  lists for them). references.mode is additionally a VALIDATED reserved
+ *  parameter: validateRulesShape rejects any value other than 'pointer' (or a
+ *  deleted/empty null) with a line-numbered error, and style.prefer is
+ *  validated the same way against 'sibling' | 'nested'. */
 const SECTION_KEYS: Record<string, string[]> = {
   structure: ['node_length', 'siblings', 'depth', 'single_child_collapse', 'empty_nodes'],
   style: ['prefer', 'force_nested_above', 'force_sibling_below', 'shared_prefix_detection'],
@@ -318,6 +337,7 @@ const SECTION_KEYS: Record<string, string[]> = {
     'word_frequency_threshold',
     'phrase_overlap_threshold',
     'cross_file_threshold',
+    'fuzzy',
     'stopwords',
     'synonyms',
   ],
@@ -387,7 +407,8 @@ export function loadRules(root: string): Rules {
   // from its deep-merged default to its OFF state:
   //   boolean switch   → false   (single_child_collapse, empty_nodes, tbd_allowed,
   //                               shared_prefix_detection, back_pointers,
-  //                               orphan_check, duplicate_home_check, redundancy.enabled;
+  //                               orphan_check, duplicate_home_check,
+  //                               redundancy.enabled, redundancy.fuzzy;
   //                               an explicit `false` stays false — same OFF result)
   //   mapping/numeric  → null    (node_length, siblings, depth, max_tbd_per_file,
   //                               force_nested_above, force_sibling_below, max_hops,
@@ -498,9 +519,11 @@ export function loadRules(root: string): Rules {
   }
 
   // redundancy: enabled / word_frequency_threshold / phrase_overlap_threshold /
-  // cross_file_threshold. `stopwords`/`synonyms` are parameters (§13 inputs) —
-  // they keep their defaults when omitted so the remaining layers still
-  // normalize text exactly as documented.
+  // cross_file_threshold / fuzzy. `stopwords`/`synonyms` are parameters (§13
+  // inputs) — they keep their defaults when omitted so the remaining layers
+  // still normalize text exactly as documented. `fuzzy` is layer 3's own check
+  // switch (issue #3): deleted → the near-miss layer alone turns OFF while
+  // layers 1/2/4 keep running.
   if (!listed('redundancy')) {
     if (deleteMode) {
       rules.redundancy = {
@@ -509,6 +532,7 @@ export function loadRules(root: string): Rules {
         word_frequency_threshold: null,
         phrase_overlap_threshold: null,
         cross_file_threshold: null,
+        fuzzy: false,
       };
     }
   } else {
@@ -524,6 +548,9 @@ export function loadRules(root: string): Rules {
     if (deleted('redundancy', 'cross_file_threshold')) {
       rules.redundancy = { ...rules.redundancy, cross_file_threshold: null };
     }
+    if (deleted('redundancy', 'fuzzy')) {
+      rules.redundancy = { ...rules.redundancy, fuzzy: false };
+    }
   }
 
   // token_budget: warn_threshold omitted (deleted) → null → no usage warning.

package/src/core/runtime.ts

@@ -0,0 +1,110 @@
+/** Runtime shim — the ONLY module allowed to touch `Bun.*` APIs (issue #12).
+ *
+ *  Bun stays the primary runtime (fast path, behavior byte-identical to the
+ *  pre-#12 code); Node.js ≥22.6 is the fallback (Termux / no-Bun harnesses).
+ *  The Node path uses only `node:` builtins — the zero-dependency law holds on
+ *  both runtimes. Anything outside this module that needs a runtime-sensitive
+ *  operation MUST go through one of these exports; a repo self-audit test
+ *  (test/node-fallback.test.ts) enforces `Bun\.` never appears elsewhere.
+ */
+import { readdirSync, statSync } from 'node:fs';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Minimal structural type for the slice of the Bun global we use. Kept local
+ *  so the shim also type-checks without relying on ambient `@types/bun`. */
+interface BunGlobal {
+  file(path: string): { text(): Promise<string> };
+  write(path: string, data: string): Promise<number>;
+  Glob: new (pattern: string) => {
+    scanSync(opts: { cwd: string; onlyFiles: boolean }): Iterable<string>;
+  };
+}
+
+const BUN: BunGlobal | undefined = (globalThis as { Bun?: BunGlobal }).Bun;
+
+/** Which runtime is executing: `'bun'` (primary) or `'node'` (fallback). */
+export const RUNTIME: 'bun' | 'node' = BUN ? 'bun' : 'node';
+
+/** CLI arguments, portable across runtimes (`Bun.argv` is an alias of
+ *  `process.argv`, so the Node form works on both). */
+export function argv(): string[] {
+  return process.argv.slice(2);
+}
+
+/** Directory of the module file that passed its `import.meta.url` — the
+ *  portable replacement for Bun's `import.meta.dir` (Node has no equivalent
+ *  property; both runtimes support `node:url.fileURLToPath`). */
+export function dirFromUrl(moduleUrl: string): string {
+  return dirname(fileURLToPath(moduleUrl));
+}
+
+/** Read a UTF-8 text file. Bun: `Bun.file(path).text()` (unchanged fast path).
+ *  Node: `fs/promises.readFile`. Rejects on missing files on both runtimes. */
+export async function readText(path: string): Promise<string> {
+  if (BUN) return BUN.file(path).text();
+  return readFile(path, 'utf8');
+}
+
+/** Write a UTF-8 text file, creating missing parent directories — `Bun.write`
+ *  auto-creates parents, so the Node path replicates that (plain
+ *  `writeFile` would not) to keep behavior identical across runtimes. */
+export async function writeText(path: string, data: string): Promise<void> {
+  if (BUN) {
+    await BUN.write(path, data);
+    return;
+  }
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, data, 'utf8');
+}
+
+function isDir(p: string): boolean {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** Glob relative file paths under `dir`, sorted lexicographically — portable
+ *  replacement for `new Bun.Glob(pattern).scanSync({ cwd, onlyFiles: true })`.
+ *  Supported forms: single-segment (`*.md`) and recursive (a two-star prefix
+ *  followed by a slash, e.g. "**" + "/" + "*.md") wildcard patterns; `*` never
+ *  crosses `/` (same as Bun.Glob). Returns paths relative to `dir`, sorted.
+ *  Empty array when `dir` does not exist (unchanged contract used by
+ *  `_tasks`/`_adr` discovery). */
+export function globFiles(dir: string, pattern: string): string[] {
+  if (!isDir(dir)) return [];
+  if (BUN) {
+    const g = new BUN.Glob(pattern);
+    return [...g.scanSync({ cwd: dir, onlyFiles: true }) as Iterable<string>].sort();
+  }
+  const recursive = pattern.startsWith('**/');
+  const base = recursive ? pattern.slice(3) : pattern;
+  const re = new RegExp(
+    `^(?:${base.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*')})$`,
+  );
+  const out: string[] = [];
+  if (recursive) {
+    const walk = (d: string, prefix: string): void => {
+      let entries;
+      try {
+        entries = readdirSync(d, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const e of entries) {
+        const rel = prefix === '' ? e.name : `${prefix}/${e.name}`;
+        if (e.isFile() && re.test(e.name)) out.push(rel);
+        else if (e.isDirectory()) walk(join(d, e.name), rel);
+      }
+    };
+    walk(dir, '');
+  } else {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (e.isFile() && re.test(e.name)) out.push(e.name);
+    }
+  }
+  return out.sort();
+}

package/src/core/structure.ts

@@ -1,7 +1,10 @@
-import type { OutlineNode, Issue, StructureRules, ContentRules } from '../types';
-import { flattenNodes } from './outline';
+import type { OutlineNode, Issue, StructureRules, ContentRules } from '../types.ts';
+import { flattenNodes, isSyntheticNode } from './outline.ts';
 
 /** Structure checks: node length, depth, sibling count, single-child collapse, empty nodes.
+ *  Both sides of every range are enforced (issue #1 — siblings.min and depth.min
+ *  were banner-checked but never enforced): node_length, siblings and depth each
+ *  check their `min` (warning) as well as their `max`.
  *  §18 delete-key semantics: a check whose rules key is null/false is OFF — the
  *  check is skipped entirely (never compared against null, which would coerce
  *  to 0 and flag everything). */
@@ -14,75 +17,127 @@ export function checkStructure(
 
   const walk = (list: OutlineNode[]): void => {
     for (const node of list) {
-      const len = node.text.length;
-      const nl = rules.node_length;
-      if (nl !== null && nl.max !== null && len > nl.max) {
-        issues.push({
-          file,
-          line: node.line,
-          level: 'error',
-          category: 'structure',
-          message: `Node too long (${len} > ${nl.max}). Split or move to file.`,
-        });
-      } else if (nl !== null && nl.min !== null && len < nl.min) {
-        issues.push({
-          file,
-          line: node.line,
-          level: 'warning',
-          category: 'structure',
-          message: `Node too short (${len} < ${nl.min}).`,
-        });
-      }
+      // Issue #8: synthetic "(table)"/"(code fence)" placeholders are not user
+      // structure — never flagged themselves (their children, if any, still
+      // are: the walk recurses below regardless).
+      if (!isSyntheticNode(node)) {
+        const len = node.text.length;
+        const nl = rules.node_length;
+        if (nl !== null && nl.max !== null && len > nl.max) {
+          issues.push({
+            file,
+            line: node.line,
+            level: 'error',
+            category: 'structure',
+            message: `Node too long (${len} > ${nl.max}). Split or move to file.`,
+          });
+        } else if (nl !== null && nl.min !== null && len < nl.min) {
+          issues.push({
+            file,
+            line: node.line,
+            level: 'warning',
+            category: 'structure',
+            message: `Node too short (${len} < ${nl.min}).`,
+          });
+        }
 
-      const depth = node.indent + 1;
-      const depthMax = rules.depth !== null ? rules.depth.max : null;
-      if (depthMax !== null && depth > depthMax) {
-        issues.push({
-          file,
-          line: node.line,
-          level: 'error',
-          category: 'structure',
-          message: `Depth ${depth} exceeds max ${depthMax}. Flatten.`,
-        });
-      }
+        const depth = node.indent + 1;
+        const depthMax = rules.depth !== null ? rules.depth.max : null;
+        if (depthMax !== null && depth > depthMax) {
+          issues.push({
+            file,
+            line: node.line,
+            level: 'error',
+            category: 'structure',
+            message: `Depth ${depth} exceeds max ${depthMax}. Flatten.`,
+          });
+        }
 
-      const count = node.children.length;
-      const siblingsMax = rules.siblings !== null ? rules.siblings.max : null;
-      if (siblingsMax !== null && count > siblingsMax) {
-        issues.push({
-          file,
-          line: node.line,
-          level: 'warning',
-          category: 'structure',
-          message: `"${node.text}" has ${count} children (max ${siblingsMax}).`,
-        });
-      }
+        const count = node.children.length;
+        const siblingsMax = rules.siblings !== null ? rules.siblings.max : null;
+        if (siblingsMax !== null && count > siblingsMax) {
+          issues.push({
+            file,
+            line: node.line,
+            level: 'warning',
+            category: 'structure',
+            message: `"${node.text}" has ${count} children (max ${siblingsMax}).`,
+          });
+        }
+        // Issue #1: enforce siblings.min — a parent with 0 < count < min children
+        // is under the configured fan-out. Warning level, consistent with the
+        // siblings.max side above. The single_child_collapse advisory below is a
+        // separate check and may fire for the same node — that is acceptable.
+        const siblingsMin = rules.siblings !== null ? rules.siblings.min : null;
+        if (siblingsMin !== null && count > 0 && count < siblingsMin) {
+          issues.push({
+            file,
+            line: node.line,
+            level: 'warning',
+            category: 'structure',
+            message: `"${node.text}" has ${count} children (min ${siblingsMin}).`,
+          });
+        }
 
-      if (rules.single_child_collapse && count === 1) {
-        issues.push({
-          file,
-          line: node.line,
-          level: 'warning',
-          category: 'structure',
-          message: `"${node.text}" has exactly 1 child. Collapse.`,
-        });
+        if (rules.single_child_collapse && count === 1) {
+          issues.push({
+            file,
+            line: node.line,
+            level: 'warning',
+            category: 'structure',
+            message: `"${node.text}" has exactly 1 child. Collapse.`,
+          });
+        }
+
+        if (rules.empty_nodes && node.text.trim() === '') {
+          issues.push({
+            file,
+            line: node.line,
+            level: 'warning',
+            category: 'structure',
+            message: 'Empty node.',
+          });
+        }
       }
 
-      if (rules.empty_nodes && node.text.trim() === '') {
+      walk(node.children);
+    }
+  };
+
+  walk(nodes);
+
+  // Issue #1: enforce depth.min at file level — a file whose deepest node is
+  // above the configured minimum is under-specified. Attached to the first
+  // root node's line (there is always at least one node when the file has
+  // nodes); an empty tree skips the check entirely.
+  // LEVEL RATIONALE: depth.min is a warning — a too-shallow file is advisory
+  // (depth.max stays an error because it protects the token budget; making
+  // shallow files hard-fail would break legitimately shallow summary files).
+  // siblings.min is a warning for the same reason: it matches the warning
+  // level of the siblings.max side. Defaults (min: 1 both) can never fire —
+  // `0 < count < 1` is impossible and any non-empty file has max depth ≥ 1 —
+  // so default-rule workspaces stay clean.
+  if (nodes.length > 0) {
+    const depthMin = rules.depth !== null ? rules.depth.min : null;
+    if (depthMin !== null) {
+      let maxNodeDepth = 0;
+      for (const n of flattenNodes(nodes)) {
+        const d = n.indent + 1; // same convention as the per-node depth check above
+        if (d > maxNodeDepth) maxNodeDepth = d;
+      }
+      if (maxNodeDepth < depthMin) {
         issues.push({
           file,
-          line: node.line,
+          line: nodes[0]!.line,
           level: 'warning',
           category: 'structure',
-          message: 'Empty node.',
+          message: `Max depth ${maxNodeDepth} is below min ${depthMin}. Deepen the outline.`,
+          suggestion: `add nested sub-levels until the outline reaches depth ${depthMin}, or lower structure.depth.min in _rules.yaml`,
         });
       }
-
-      walk(node.children);
     }
-  };
+  }
 
-  walk(nodes);
   return issues;
 }