cans-spec 0.1.0

package/src/core/output.ts

@@ -0,0 +1,300 @@
+import type {
+  CommandResult, CheckResult, Issue, InitResult, NewResult, DoneResult, StatusResult,
+  BudgetReadResult, BudgetWriteResult, ImportResult, ExportResult, VersionResult,
+} from '../types';
+
+/** Single emission point. Commands never console.log or process.exit directly.
+ *  `refsOnly` (check only, §22/§36): human output is scoped to the References
+ *  section (+ Rules + summary); JSON output is always the full result. */
+export function emit(result: CommandResult, json: boolean, refsOnly?: boolean): void {
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  printHuman(result, refsOnly);
+}
+
+const CATEGORY_ORDER: Array<Issue['category']> = ['structure', 'style', 'refs', 'redundancy', 'overflow'];
+
+export function printHuman(result: CommandResult, refsOnly?: boolean): void {
+  switch (result.command) {
+    case 'check':
+      printCheckHuman(result as CheckResult, refsOnly);
+      break;
+    case 'help':
+      printHelp();
+      break;
+    case 'version': {
+      const r = result as VersionResult;
+      console.log(`cans ${r.version}`);
+      break;
+    }
+    case 'init': {
+      const r = result as InitResult;
+      if (!r.ok) {
+        console.log(`✗ ${r.error ?? 'cannot init here'}`);
+        break;
+      }
+      console.log(`Workspace: ${r.root}`);
+      if (r.created?.length) {
+        for (const c of r.created) console.log(`  + ${c}`);
+      }
+      if (r.skipped?.length) {
+        for (const s of r.skipped) console.log(`  = ${s} (exists, skipped)`);
+      }
+      break;
+    }
+    case 'new': {
+      const r = result as NewResult;
+      if (r.ok) {
+        console.log(`Created ${r.file}`);
+        if (r.warning) console.log(`  ⚠ ${r.warning}`);
+      } else {
+        console.log(`✗ ${r.error ?? 'failed to create'}`);
+      }
+      break;
+    }
+    case 'done': {
+      const r = result as DoneResult;
+      if (!r.ok) {
+        if (r.error) {
+          console.log(`✗ ${r.error}`);
+        } else if ((r.gates?.humanOpen ?? 0) > 0) {
+          console.log(`✗ BLOCKED: ${r.gates.humanOpen} unchecked ← @human gate${r.gates.humanOpen > 1 ? 's' : ''}`);
+          // §36: file:line — gate text
+          for (const g of r.gateDetails ?? []) {
+            if (g.text.includes('@human')) {
+              console.log(`  ${g.file}:${g.line} — ${g.text}`);
+            }
+          }
+          console.log('  Check the gate, then re-run cans done.');
+        } else if ((r.gates?.tasksOpen ?? 0) > 0) {
+          console.log(`✗ BLOCKED: ${r.gates.tasksOpen} open task${r.gates.tasksOpen > 1 ? 's' : ''} (--allow-incomplete to override)`);
+          for (const g of r.gateDetails ?? []) {
+            if (!g.text.includes('@human')) {
+              console.log(`  ${g.file}:${g.line} — ${g.text}`);
+            }
+          }
+        } else {
+          console.log(`✗ BLOCKED: cans check failed (--skip-check to override)`);
+        }
+      } else {
+        console.log(`✓ Archived ${r.archived}`);
+      }
+      break;
+    }
+    case 'status': {
+      const r = result as StatusResult;
+      if (!r.ok) {
+        // §37: say what actually happened. Arg/usage failures carry the real
+        // diagnosis in `error` — surface it verbatim (QA-10 M1: a rejected flag
+        // must never be re-diagnosed as a missing workspace). The genuine
+        // missing-workspace case also reports through `error`.
+        if (r.error) {
+          console.log(`✗ ${r.error}`);
+        } else {
+          console.log('✗ No cans workspace found.');
+          console.log('  Run `cans init` or cd into a project with a cans/ directory.');
+        }
+        break;
+      }
+      if (r.filter === 'owners') {
+        // Owners view: per-owner rollup, structurally distinct from the default report.
+        console.log('Owners view:');
+        const names = Object.keys(r.owners ?? {});
+        if (names.length === 0) console.log('  no owners assigned yet');
+        for (const name of names) {
+          const s = (r.owners ?? {})[name];
+          console.log(`  ${name}: ${s.tasks} task(s), ${s.done} done`);
+        }
+        if (r.conflicts > 0) console.log(`Conflicts: ${r.conflicts} unresolved in _collab/conflicts.md`);
+        break;
+      }
+      console.log(`Files: ${r.specFiles} specs, ${r.activeTasks} tasks, ${r.archivedTasks} archived, ${r.adrCount} ADRs`);
+      console.log(`Tasks: ${r.tasks?.done ?? 0}/${r.tasks?.total ?? 0} done, ${r.tasks?.unclaimed ?? 0} unclaimed, ${r.tasks?.blocked ?? 0} blocked`);
+      if (r.owners && Object.keys(r.owners).length > 0) {
+        console.log(`Owners: ${Object.keys(r.owners).join(', ')}`);
+      }
+      let shown = r.taskFiles ?? [];
+      if (r.filter === 'unclaimed') {
+        // Only task files that still hold unclaimed items (§25 semantics).
+        shown = shown.filter(tf => (tf.unclaimed ?? Math.max(tf.tasksTotal - tf.tasksDone, 0)) > 0);
+      } else if (r.filter === 'blocked') {
+        shown = shown.filter(tf => tf.blocked);
+      }
+      // §36: multi-line per-task block
+      for (const tf of shown) {
+        console.log(`  ${tf.name}:`);
+        console.log(`    Tasks: ${tf.tasksDone}/${tf.tasksTotal}`);
+        console.log(`    Gates: ${tf.gatesDone}/${tf.gatesTotal} ← @human`);
+        if (tf.blocked) console.log('    ⚠ BLOCKED');
+      }
+      if (r.conflicts > 0) console.log(`Conflicts: ${r.conflicts} unresolved in _collab/conflicts.md`);
+      break;
+    }
+    case 'budget-read': {
+      const r = result as BudgetReadResult;
+      if (!r.ok) {
+        console.log(`✗ ${r.error ?? `No files match concept "${r.concept}".`}`);
+        break;
+      }
+      console.log(`Reading plan for: ${r.concept}`);
+      let i = 1;
+      for (const item of r.plan ?? []) {
+        const anchor = item.anchor ? `#${item.anchor}` : '';
+        console.log(`  ${i++}. ${item.file}${anchor} ← ${item.reason} (${item.estTokens} tok)`);
+      }
+      if (r.skipped?.length) {
+        console.log(`Skipped:`);
+        for (const s of r.skipped) console.log(`  ${s}`);
+      }
+      console.log(`Budget: ${r.totalTokens} / ${r.budgetLimit} tokens (${r.usagePercent}%)`);
+      break;
+    }
+    case 'budget-write': {
+      const r = result as BudgetWriteResult;
+      if (!r.ok) {
+        console.log(`✗ ${r.error ?? `No files match concept "${r.concept}".`}`);
+        break;
+      }
+      console.log(`Writing scope for: ${r.concept}`);
+      console.log(`CAN edit:`);
+      for (const e of r.canEdit ?? []) console.log(`  ${e.file} ← ${e.reason}`);
+      console.log(`MUST NOT edit:`);
+      for (const e of r.mustNotEdit ?? []) console.log(`  ${e.file} ← ${e.reason}`);
+      break;
+    }
+    case 'import': {
+      const r = result as ImportResult;
+      if (!r.ok) {
+        console.log(`✗ ${r.error ?? 'import failed'}`);
+        break;
+      }
+      if (r.dryRun) {
+        console.log(`[dry-run] Would import ${r.format} from ${r.source}. No files written.`);
+      } else {
+        console.log(`Imported ${r.format} from ${r.source}`);
+      }
+      for (const f of r.newFiles ?? []) console.log(`  + ${f}`);
+      for (const f of r.merged ?? []) console.log(`  ~ ${f} (merged)`);
+      for (const c of r.conflicts ?? []) console.log(`  ! ${c.file}:${c.line} ${c.resolution}`);
+      break;
+    }
+    case 'export': {
+      const r = result as ExportResult;
+      if (!r.ok) {
+        console.log(`✗ ${r.error ?? 'export failed'}`);
+        break;
+      }
+      if (r.dryRun) {
+        console.log(`[dry-run] Would export ${r.format} → ${r.outputDir} (${r.filesExported} files). No files written.`);
+      } else {
+        console.log(`Exported ${r.format} → ${r.outputDir} (${r.filesExported} files)`);
+      }
+      break;
+    }
+    default: {
+      // §37: unknown command — say what happened and how to fix it.
+      const err = (result as { error?: string }).error;
+      if (err) {
+        console.log(`✗ ${err}`);
+      } else {
+        console.log(`✗ Unknown command "${result.command}".`);
+        console.log('  Run `cans help` for available commands.');
+      }
+    }
+  }
+}
+
+function printCheckHuman(r: CheckResult, refsOnly?: boolean): void {
+  // §37: check-level failures (unknown flag, no cans workspace, invalid
+  // _rules.yaml, unmatched file filter) carry their diagnosis in `error` —
+  // print it standalone, never inside a report-shaped body.
+  const failure = (r as { error?: string }).error;
+  if (failure) {
+    console.log(`✗ ${failure}`);
+    return;
+  }
+
+  const byCategory = new Map<string, Issue[]>();
+  for (const i of r.issues) {
+    const list = byCategory.get(i.category) ?? [];
+    list.push(i);
+    byCategory.set(i.category, list);
+  }
+  if (!refsOnly) {
+    console.log('Structure');
+    console.log(`  ${r.files} files, ${r.nodes} nodes, max depth ${r.maxDepth}`);
+    printIssues(byCategory.get('structure'));
+
+    console.log('Style');
+    printIssues(byCategory.get('style'));
+  }
+
+  console.log('References');
+  console.log(`  ${r.refs.total} see: refs, ${r.refs.broken} broken, ${r.refs.deepHops} deep hops`);
+  console.log(`  back-pointers: ${r.backPointers.current}/${r.backPointers.total} current`);
+  printIssues(byCategory.get('refs'));
+
+  if (!refsOnly) {
+    console.log('Redundancy');
+    printIssues(byCategory.get('redundancy'));
+    if (!byCategory.get('redundancy')?.length) {
+      const none = r.issues.filter(i => i.category === 'redundancy').length === 0;
+      if (none) console.log('  ✓ no redundancy detected');
+    }
+
+    console.log('Overflow');
+    if (!byCategory.get('overflow')?.length) {
+      console.log('  ✓ no code blocks, tables, or oversized nodes');
+    } else {
+      printIssues(byCategory.get('overflow'));
+    }
+  }
+
+  // §22: the fixed report order ends Structure → Style → References →
+  // Redundancy → Overflow → Rules → Summary (QA-02 F17).
+  if (r.rulesSummary !== undefined) {
+    console.log('Rules (_rules.yaml)');
+    console.log(`  ✓ ${r.rulesSummary}`);
+  }
+
+  void CATEGORY_ORDER;
+  console.log('');
+  console.log(`${r.errorCount} errors, ${r.warningCount} warnings.`);
+}
+
+function printIssues(issues: Issue[] | undefined): void {
+  for (const i of issues ?? []) {
+    const mark = i.level === 'error' ? '✗' : '⚠';
+    // Avoid duplicating the file path when the message already carries it (parse errors)
+    const msg = i.message.startsWith(`${i.file}:`) ? i.message.slice(i.file.length + 1) : i.message;
+    const linePart = i.line > 0 ? `:${i.line}` : '';
+    console.log(`  ${mark} ${i.file}${linePart} — ${msg}`);
+    if (i.suggestion) console.log(`    ${i.suggestion}`);
+  }
+}
+
+function printHelp(): void {
+  console.log(`CANS — Canonical Agent-Native Spec
+
+Usage: cans <command> [args]
+
+Commands:
+  init [--flat|--folders] [--bare] [--force] [--tool <name>]
+  check [--fix] [--strict] [--refs-only] [--no-redundancy] [file] [--json]
+  new adr <title>
+  new task <name>
+  done <name> [--allow-incomplete] [--skip-check] [--json]
+  status [--unclaimed] [--blocked] [--owners] [--json]
+  budget read <concept> [--limit <tokens>] [--change <name>] [--json]
+  budget write <concept> [--json]
+  import <format> <path> [--out <path>] [--dry-run] [--merge-strategy <s>] [--json]
+  export <format> [--from <path>] [--include-tasks] [--vault <path>] [--dry-run] [--json]
+  help
+  version
+
+Formats: opml, dynalist, logseq, obsidian
+Config:  cans/_rules.yaml
+Agents:  cans/AGENTS.md`);
+}

package/src/core/overflow.ts

@@ -0,0 +1,75 @@
+import type { OutlineNode, Issue, OverflowRules } from '../types';
+import { flattenNodes } from './outline';
+
+/** Overflow checks: code fences, tables, over-long nodes. All errors.
+ *  §18: `force_file_for` lists the content categories forced into files —
+ *  `code_block` gates code-fence flags, `table` gates table flags. Empty list
+ *  = nothing forced = no content-type flags; null (deleted key) = same.
+ *  §18 delete-key semantics: `max_node_chars` null (deleted) → the char-length
+ *  check is OFF — skipped entirely, never compared against null. */
+export function checkOverflow(
+  nodes: OutlineNode[],
+  file: string,
+  rules: OverflowRules,
+): Issue[] {
+  const issues: Issue[] = [];
+  const forceSet = new Set(rules.force_file_for ?? []);
+
+  const walk = (list: OutlineNode[]): void => {
+    for (const node of list) {
+      if (node.hasCodeFence && forceSet.has('code_block')) {
+        issues.push({
+          file,
+          line: node.line,
+          level: 'error',
+          category: 'overflow',
+          message: 'code fence detected — extract to file and reference via see:',
+        });
+      }
+      if (node.hasTable && forceSet.has('table')) {
+        issues.push({
+          file,
+          line: node.line,
+          level: 'error',
+          category: 'overflow',
+          message: 'table detected — extract to file and reference via see:',
+        });
+      }
+      if (rules.max_node_chars !== null && node.text.length > rules.max_node_chars) {
+        issues.push({
+          file,
+          line: node.line,
+          level: 'error',
+          category: 'overflow',
+          message: `node exceeds max chars (${node.text.length} > ${rules.max_node_chars})`,
+        });
+      }
+      walk(node.children);
+    }
+  };
+
+  walk(nodes);
+  return issues;
+}
+
+/** §16 no-chaining: "Overflow target files must NOT contain their own see: refs."
+ *  `targets` maps overflow target file → parsed nodes (files inside spec
+ *  subfolders, e.g. `04-api/request-schema.md`). */
+export function checkNoChaining(targets: Map<string, OutlineNode[]>): Issue[] {
+  const issues: Issue[] = [];
+  for (const [file, nodes] of targets) {
+    for (const node of flattenNodes(nodes)) {
+      for (const ref of node.refs) {
+        issues.push({
+          file,
+          line: ref.line,
+          level: 'error',
+          category: 'overflow',
+          message: `no chaining: overflow target ${file} must not contain its own see: refs (found see ${ref.file})`,
+          suggestion: `remove the see: ref inside ${file} — overflow targets are leaf content, reference them from a spec file instead`,
+        });
+      }
+    }
+  }
+  return issues;
+}

package/src/core/redundancy.ts

@@ -0,0 +1,261 @@
+import type { OutlineNode, Issue, RedundancyRules } from '../types';
+import { flattenNodes } from './outline';
+
+interface NodeRef {
+  text: string;
+  file: string;
+  line: number;
+}
+
+const EDGE_PUNCT_RE = /^[.,;:!?"']+|[.,;:!?"']+$/g;
+
+/** §8/§13: ref syntax tokens (`see:`, `.md`) are structural pointers, not
+ *  content words — excluded from every redundancy layer (QA-02 F3). */
+const REF_SYNTAX_TOKENS = new Set(['see', 'md']);
+
+/** lowercase → strip edge punctuation → synonym group (any member → first member) → bare word. */
+export function normalizeWord(word: string, synonyms: string[][]): string {
+  const stripped = word.toLowerCase().replace(EDGE_PUNCT_RE, '');
+  for (const group of synonyms) {
+    if (group.includes(stripped)) return group[0];
+  }
+  return stripped;
+}
+
+function tokenize(text: string): string[] {
+  return text.split(/[^A-Za-z0-9]+/).filter(w => w.length > 0);
+}
+
+/** Normalized word set of a text; stopwords filtered when rules are given. */
+function wordSet(text: string, rules?: RedundancyRules): Set<string> {
+  const out = new Set<string>();
+  const synonyms = rules ? rules.synonyms : [];
+  const stopwords = rules ? rules.stopwords : null;
+  for (const raw of tokenize(text)) {
+    const w = normalizeWord(raw, synonyms);
+    if (w.length === 0) continue;
+    if (REF_SYNTAX_TOKENS.has(w)) continue;
+    if (stopwords !== null && stopwords.includes(w)) continue;
+    out.add(w);
+  }
+  return out;
+}
+
+/** Levenshtein edit distance (two-row DP). */
+function levenshtein(a: string, b: string): number {
+  if (a === b) return 0;
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  let prev = new Array<number>(n + 1);
+  let cur = new Array<number>(n + 1);
+  for (let j = 0; j <= n; j++) prev[j] = j;
+  for (let i = 1; i <= m; i++) {
+    cur[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+      cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + cost);
+    }
+    const swap = prev;
+    prev = cur;
+    cur = swap;
+  }
+  return prev[n];
+}
+
+/** Layer 1 — words appearing in >= threshold nodes (node count, not occurrences).
+ *  §18 delete-key semantics: `word_frequency_threshold` null (deleted) → the
+ *  layer is OFF — skipped entirely, never compared against null. */
+export function wordFrequency(
+  nodes: NodeRef[],
+  rules: RedundancyRules,
+): Issue[] {
+  const threshold = rules.word_frequency_threshold;
+  if (threshold === null) return [];
+  const counts = new Map<string, number>();
+  const firstLoc = new Map<string, NodeRef>();
+  for (const node of nodes) {
+    const seen = new Set<string>();
+    for (const w of wordSet(node.text, rules)) {
+      if (seen.has(w)) continue;
+      seen.add(w);
+      counts.set(w, (counts.get(w) ?? 0) + 1);
+      if (!firstLoc.has(w)) firstLoc.set(w, node);
+    }
+  }
+  const flagged = [...counts.entries()].filter(([, n]) => n >= threshold);
+  flagged.sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+  const issues: Issue[] = [];
+  for (const [word, n] of flagged) {
+    const loc = firstLoc.get(word)!;
+    issues.push({
+      file: loc.file, line: loc.line, level: 'warning', category: 'redundancy',
+      message: `"${word}" × ${n} nodes (threshold: ${threshold})`,
+      suggestion: `pick one canonical home for "${word}" and see: it from the others`,
+    });
+  }
+  return issues;
+}
+
+/** Layer 2 — pairwise word-set overlap of normalized word sets >= threshold.
+ *  §13: "Normalized word set overlap ≥ 70% → flag." Overlap is measured
+ *  against the LARGER of the two sets (|A∩B| / max(|A|,|B|)), after stopword
+ *  and synonym normalization. §18: threshold null (deleted key) → layer OFF. */
+export function phraseOverlap(
+  nodes: NodeRef[],
+  threshold: number | null,
+  rules?: RedundancyRules,
+): Issue[] {
+  if (threshold === null) return [];
+  const sets = nodes.map(n => ({ node: n, words: wordSet(n.text, rules) }));
+  const issues: Issue[] = [];
+  for (let i = 0; i < sets.length; i++) {
+    for (let j = i + 1; j < sets.length; j++) {
+      const a = sets[i];
+      const b = sets[j];
+      if (a.node.file === b.node.file && a.node.line === b.node.line) continue;
+      if (a.words.size === 0 || b.words.size === 0) continue;
+      let inter = 0;
+      for (const w of a.words) if (b.words.has(w)) inter++;
+      const larger = Math.max(a.words.size, b.words.size);
+      const similarity = larger === 0 ? 0 : inter / larger;
+      if (similarity >= threshold) {
+        const pct = Math.round(similarity * 100);
+        issues.push({
+          file: a.node.file, line: a.node.line, level: 'warning', category: 'redundancy',
+          message: `${pct}% overlap: ${a.node.file}:${a.node.line} ↔ ${b.node.file}:${b.node.line}`,
+          suggestion: 'merge the duplicated bullets or see: the canonical one',
+        });
+      }
+    }
+  }
+  return issues;
+}
+
+/** Layer 3 — near-miss word forms (Levenshtein <= 2, both words > 4 chars) → possible typo.
+ *  §13: "NOT ALREADY SYNONYM-MATCHED" — words are normalized with the rules'
+ *  synonym groups first, so members of the same group collapse to one word and
+ *  never pair up as typos. */
+export function fuzzyDistance(
+  nodes: NodeRef[],
+  rules?: RedundancyRules,
+): Issue[] {
+  const synonyms = rules ? rules.synonyms : [];
+  const words: NodeRef[] = [];
+  const seen = new Set<string>();
+  for (const node of nodes) {
+    for (const raw of tokenize(node.text)) {
+      const w = normalizeWord(raw, synonyms);
+      if (w.length === 0 || seen.has(w)) continue;
+      seen.add(w);
+      words.push({ text: w, file: node.file, line: node.line });
+    }
+  }
+  const issues: Issue[] = [];
+  for (let i = 0; i < words.length; i++) {
+    for (let j = i + 1; j < words.length; j++) {
+      const a = words[i];
+      const b = words[j];
+      if (a.text.length <= 4 || b.text.length <= 4) continue;
+      if (Math.abs(a.text.length - b.text.length) > 2) continue;
+      const d = levenshtein(a.text, b.text);
+      if (d <= 2) {
+        issues.push({
+          file: a.file, line: a.line, level: 'warning', category: 'redundancy',
+          message: `possible typo: "${a.text}" (${a.file}:${a.line}) ↔ "${b.text}" (${b.file}:${b.line}) — Levenshtein ${d}`,
+          suggestion: 'unify the spelling or map the variant as a synonym',
+        });
+      }
+    }
+  }
+  return issues;
+}
+
+/** Candidate ref-name spellings for a workspace key (flat and folder layouts). */
+function refNamesForKey(key: string): string[] {
+  const names = new Set<string>([key]);
+  if (key.endsWith('.md')) names.add(key.slice(0, -3));
+  if (key.endsWith('/index.md')) {
+    const base = key.slice(0, -9);
+    names.add(base);
+    names.add(`${base}.md`);
+  }
+  return [...names];
+}
+
+function filesConnected(
+  allFiles: Map<string, OutlineNode[]>,
+  a: string,
+  b: string,
+): boolean {
+  const aNodes = flattenNodes(allFiles.get(a) ?? []);
+  const bNodes = flattenNodes(allFiles.get(b) ?? []);
+  const bNames = new Set(refNamesForKey(b));
+  const aNames = new Set(refNamesForKey(a));
+  const refsTo = (ns: OutlineNode[], names: Set<string>): boolean =>
+    ns.some(n => n.refs.some(r => names.has(r.file)));
+  return refsTo(aNodes, bNames) || refsTo(bNodes, aNames);
+}
+
+/** Layer 4 — identical node text at depth 0-1 in >= threshold files without see: linkage.
+ *  §18 delete-key semantics: threshold null (deleted) → layer OFF. */
+export function crossFileCanonicality(
+  allFiles: Map<string, OutlineNode[]>,
+  threshold: number | null,
+): Issue[] {
+  if (threshold === null) return [];
+  const concepts = new Map<string, { files: Set<string>; first: NodeRef }>();
+  for (const [key, nodes] of allFiles) {
+    for (const node of flattenNodes(nodes)) {
+      if (node.indent > 1) continue;
+      const text = node.text.trim().toLowerCase();
+      if (text.length === 0) continue;
+      let entry = concepts.get(text);
+      if (entry === undefined) {
+        entry = { files: new Set<string>(), first: { text, file: key, line: node.line } };
+        concepts.set(text, entry);
+      }
+      entry.files.add(key);
+    }
+  }
+  const issues: Issue[] = [];
+  for (const [concept, entry] of concepts) {
+    if (entry.files.size < threshold) continue;
+    const files = [...entry.files].sort();
+    let connected = false;
+    for (let i = 0; i < files.length && !connected; i++) {
+      for (let j = i + 1; j < files.length && !connected; j++) {
+        if (filesConnected(allFiles, files[i], files[j])) connected = true;
+      }
+    }
+    if (connected) continue;
+    issues.push({
+      file: entry.first.file, line: entry.first.line, level: 'warning', category: 'redundancy',
+      message: `"${concept}" at depth 0-1 in ${files.length}+ files without see: (${files.join(', ')})`,
+      suggestion: `keep "${concept}" in one canonical file and see: it from the others`,
+    });
+  }
+  return issues;
+}
+
+/** All four redundancy layers over every loaded spec node.
+ *  `duplicateHomeCheck` (§18 references.duplicate_home_check) gates layer 4. */
+export function checkRedundancy(
+  allFiles: Map<string, OutlineNode[]>,
+  rules: RedundancyRules,
+  duplicateHomeCheck = true,
+): Issue[] {
+  const nodes: NodeRef[] = [];
+  for (const [file, tree] of allFiles) {
+    for (const node of flattenNodes(tree)) {
+      nodes.push({ text: node.text, file, line: node.line });
+    }
+  }
+  return [
+    ...wordFrequency(nodes, rules),
+    ...phraseOverlap(nodes, rules.phrase_overlap_threshold, rules),
+    ...fuzzyDistance(nodes, rules),
+    ...(duplicateHomeCheck ? crossFileCanonicality(allFiles, rules.cross_file_threshold) : []),
+  ];
+}