cans-spec 0.2.0 → 0.5.0

package/src/core/output.ts

@@ -1,25 +1,30 @@
 import type {
-  CommandResult, CheckResult, Issue, InitResult, NewResult, DoneResult, StatusResult,
+  CommandResult, CheckResult, InitResult, NewResult, DoneResult, StatusResult,
   BudgetReadResult, BudgetWriteResult, ImportResult, ExportResult, VersionResult,
 } from '../types.ts';
+import {
+  buildReport, topGroups, checkReportJson,
+  type IssueGroup, type SectionReport,
+} from './report.ts';
 
 /** 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 {
+ *  `refsOnly` (check only): human output is scoped to the REFS section (+ Rules).
+ *  `show` (check only, issue #41): sections rendered UNFOLDED by --show.
+ *  --json: check emits the lossless structured wire shape (sections → arrays
+ *  of {file, line, rule, detail}, issue #41); other commands the raw result. */
+export function emit(result: CommandResult, json: boolean, refsOnly?: boolean, show?: Set<string>): void {
   if (json) {
-    console.log(JSON.stringify(result, null, 2));
+    const body = result.command === 'check' ? checkReportJson(result as unknown as Parameters<typeof checkReportJson>[0]) : result;
+    console.log(JSON.stringify(body, null, 2));
     return;
   }
-  printHuman(result, refsOnly);
+  printHuman(result, refsOnly, show);
 }
 
-const CATEGORY_ORDER: Array<Issue['category']> = ['structure', 'style', 'refs', 'redundancy', 'overflow'];
-
-export function printHuman(result: CommandResult, refsOnly?: boolean): void {
+export function printHuman(result: CommandResult, refsOnly?: boolean, show?: Set<string>): void {
   switch (result.command) {
     case 'check':
-      printCheckHuman(result as CheckResult, refsOnly);
+      printCheckHuman(result as CheckResult, refsOnly, show);
       break;
     case 'help':
       printHelp();
@@ -206,7 +211,23 @@ export function printHuman(result: CommandResult, refsOnly?: boolean): void {
   }
 }
 
-function printCheckHuman(r: CheckResult, refsOnly?: boolean): void {
+// ── issue #41: aggregated check report ──
+// One line per pattern (`61× <min children (2/3)`), grouped by root cause,
+// top-N + fold with --show expansion, timing on the summary line, and a
+// ≤500-token default budget for issue-scale projects.
+
+const DISPLAY_NAMES: Record<string, string> = {
+  structure: 'STRUCTURE', style: 'STYLE', refs: 'REFS', redundancy: 'REDUNDANCY',
+  overflow: 'OVERFLOW', parse: 'PARSE', content: 'CONTENT', io: 'IO', other: 'OTHER',
+};
+const SECTION_PRINT_ORDER = ['structure', 'style', 'refs', 'redundancy', 'overflow', 'parse', 'content', 'io', 'other'];
+const FOLD_TOP_GROUPS = 5;
+const FOLD_KEYWORD_ITEMS = 5;
+const FOLD_OVERLAP_ITEMS = 3;
+const FOLD_TARGETS = 8;
+const WRAP_COLS = 72;
+
+function printCheckHuman(r: CheckResult, refsOnly?: boolean, show?: Set<string>): 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.
@@ -216,63 +237,186 @@ function printCheckHuman(r: CheckResult, refsOnly?: boolean): void {
     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'));
-  }
+  const expanded = (name: string): boolean => show !== undefined && (show.has('all') || show.has(name));
 
-  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'));
+  // issue #41: summary line first — severity mark, workspace shape, elapsed ms.
+  const mark = r.errorCount > 0 ? '✗' : r.warningCount > 0 ? '⚠' : '✓';
+  console.log(`${mark} ${r.files} files · ${r.nodes} nodes · depth ${r.maxDepth} · ${r.elapsedMs ?? 0}ms`);
 
-  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');
+  const report = buildReport(r.issues);
+  for (const name of SECTION_PRINT_ORDER) {
+    if (refsOnly && name !== 'refs') continue;
+    let section = report.sections[name];
+    // issue #11: a --fix run that rewrote back-pointer files always surfaces
+    // the REFS block — even when the refs engine has no findings of its own
+    // (the clean/healthy case), the run's writes stay visible there.
+    if (name === 'refs' && section === undefined && r.backPointersUpdatedFiles.length > 0) {
+      section = { name: 'refs', errorCount: 0, warningCount: 0, groups: [] };
     }
-
-    console.log('Overflow');
-    if (!byCategory.get('overflow')?.length) {
-      console.log('  ✓ no code blocks, tables, or oversized nodes');
-    } else {
-      printIssues(byCategory.get('overflow'));
+    // Compact contract: STRUCTURE/STYLE/REDUNDANCY (and the small sections)
+    // print only when they carry findings; REFS and OVERFLOW always print
+    // (they carry the ✓ healthy state, as in the issue's expected output).
+    if (section === undefined) {
+      if (name === 'overflow' && !refsOnly) {
+        console.log('');
+        console.log('OVERFLOW  ✓');
+      }
+      continue;
     }
+    console.log('');
+    if (name === 'refs') printRefsSection(r, section, expanded('refs'));
+    else printSection(section, expanded(name));
   }
 
-  // §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}`);
+    console.log('');
+    console.log(`RULES  ✓ ${compactRules(r.rulesSummary)}`);
   }
+}
+
+function printSection(section: SectionReport, expanded: boolean): void {
+  const mark = section.errorCount > 0 ? '✗' : '⚠';
+  console.log(`${DISPLAY_NAMES[section.name] ?? section.name.toUpperCase()}  ${mark} ${section.errorCount + section.warningCount}`);
+  const { shown, folded } = expanded ? { shown: section.groups, folded: 0 } : topGroups(section, FOLD_TOP_GROUPS);
+  for (const g of shown) printGroup(g, expanded);
+  if (folded > 0) console.log(`   … ${folded} more → cans check --show ${section.name}`);
+}
+
+function printRefsSection(r: CheckResult, section: SectionReport, expanded: boolean): void {
+  // Header: per-root-cause counts (issue #41 example: `REFS  ✗ 96 broken · ⚠ 8 stale · ⚠ 1 orphan`).
+  // Level-aware: named buckets subtract from the section totals, the residue
+  // prints as `✗ N` / `⚠ N` — no finding is ever hidden or double-counted.
+  const byRule = new Map<string, { err: number; warn: number }>();
+  for (const g of section.groups) {
+    const cur = byRule.get(g.rule) ?? { err: 0, warn: 0 };
+    if (g.level === 'error') cur.err += g.count;
+    else cur.warn += g.count;
+    byRule.set(g.rule, cur);
+  }
+  const named = ['refs.broken.file', 'refs.backpointer.stale', 'refs.orphan', 'refs.deep_hop'];
+  const namedErr = named.reduce((a, rl) => a + (byRule.get(rl)?.err ?? 0), 0);
+  const namedWarn = named.reduce((a, rl) => a + (byRule.get(rl)?.warn ?? 0), 0);
+  const parts: string[] = [];
+  const broken = byRule.get('refs.broken.file');
+  if (broken !== undefined && broken.err + broken.warn > 0) parts.push(`✗ ${broken.err + broken.warn} broken`);
+  const stale = byRule.get('refs.backpointer.stale');
+  if (stale !== undefined && stale.err + stale.warn > 0) parts.push(`⚠ ${stale.err + stale.warn} stale`);
+  const orphan = byRule.get('refs.orphan');
+  if (orphan !== undefined && orphan.err + orphan.warn > 0) parts.push(`⚠ ${orphan.err + orphan.warn} orphan`);
+  const hops = byRule.get('refs.deep_hop');
+  if (hops !== undefined && hops.err > 0) parts.push(`✗ ${hops.err} deep-hop`);
+  else if (hops !== undefined && hops.warn > 0) parts.push(`⚠ ${hops.warn} deep-hop`);
+  const errOther = section.errorCount - namedErr;
+  const warnOther = section.warningCount - namedWarn;
+  if (errOther > 0) parts.push(`✗ ${errOther}`);
+  if (warnOther > 0) parts.push(`⚠ ${warnOther}`);
+  if (parts.length > 0) {
+    console.log(`REFS  ${parts.join(' · ')}`);
+  } else {
+    const bp = r.backPointers.total > 0 ? ` · ${r.backPointers.current}/${r.backPointers.total} back-ptrs` : '';
+    console.log(`REFS  ✓ ${r.refs.total} refs${bp}`);
+  }
+  // Issue #11: name the files --fix actually rewrote (099e858 wording) —
+  // never printed as an empty list (plain checks show nothing here).
+  if (r.backPointersUpdatedFiles.length > 0) {
+    console.log(`  --fix updated ref-by in: ${r.backPointersUpdatedFiles.join(', ')}`);
+  }
+
+  // issue #41 design rule 2: all missing-file refs coalesce into ONE block
+  // (91 broken refs → 4 targets with per-target counts, one fix hint).
+  const brokenGroups = section.groups.filter(g => g.rule === 'refs.broken.file');
+  const rest = section.groups.filter(g => g.rule !== 'refs.broken.file');
+  if (brokenGroups.length > 0) printBrokenFileBlock(brokenGroups);
+  const { shown, folded } = expanded ? { shown: rest, folded: 0 } : topGroups({ ...section, groups: rest }, FOLD_TOP_GROUPS);
+  for (const g of shown) printGroup(g, expanded);
+  if (folded > 0) console.log(`   … ${folded} more → cans check --show refs`);
+}
+
+function printBrokenFileBlock(groups: IssueGroup[]): void {
+  const total = groups.reduce((a, g) => a + g.count, 0);
+  console.log(`  ${String(total).padStart(2)}× missing file`);
+  const targets = groups
+    .filter(g => g.key !== undefined)
+    .map(g => ({ label: g.key!, count: g.count }))
+    .sort((a, b) => b.count - a.count || (a.label < b.label ? -1 : 1));
+  const shown = targets.slice(0, FOLD_TARGETS);
+  for (const line of wrapText(shown.map(t => `${t.label} (${t.count})`).join(' · '), WRAP_COLS, 6)) console.log(line);
+  if (targets.length > shown.length) console.log(`      ↳ ${targets.length - shown.length} more targets → cans check --show refs`);
+  const hint = groups.map(g => g.suggestion).find(s => s !== undefined);
+  if (hint !== undefined) console.log(`      ↳ ${hint}`);
+}
 
-  void CATEGORY_ORDER;
-  console.log('');
-  console.log(`${r.errorCount} errors, ${r.warningCount} warnings.`);
+function printGroup(g: IssueGroup, expanded: boolean): void {
+  console.log(`  ${String(g.count).padStart(2)}× ${g.pattern}`);
+  switch (g.rule) {
+    case 'redundancy.keyword': {
+      const items = g.items ?? [];
+      const shownItems = expanded ? items : items.slice(0, FOLD_KEYWORD_ITEMS);
+      // issue #41: `artifacts:105  db:74` — keyword:nodeCount, metric-ranked.
+      for (const line of wrapText(shownItems.map(it => `${it.label}:${it.metric ?? it.count}`).join('  '), WRAP_COLS, 6)) console.log(line);
+      const hidden = items.slice(FOLD_KEYWORD_ITEMS).reduce((a, it) => a + it.count, 0);
+      if (!expanded && hidden > 0) console.log(`      ↳ ${hidden} more → cans check --show redundancy`);
+      else if (g.suggestion !== undefined) console.log(`      ↳ ${g.suggestion}`);
+      return;
+    }
+    case 'redundancy.overlap.exact':
+    case 'redundancy.overlap.fuzzy': {
+      const items = g.items ?? [];
+      const shownItems = expanded ? items : items.slice(0, FOLD_OVERLAP_ITEMS);
+      if (shownItems.length > 0) {
+        for (const line of wrapText(`worst: ${shownItems.map(it => it.label).join(' · ')}`, WRAP_COLS, 6)) console.log(line);
+      }
+      const hidden = items.length - shownItems.length;
+      if (!expanded && hidden > 0) console.log(`      ↳ ${hidden} more pairs → cans check --show redundancy`);
+      else if (g.suggestion !== undefined) console.log(`      ↳ ${g.suggestion}`);
+      return;
+    }
+    case 'refs.backpointer.stale': {
+      // `budget:2  ← agent, effect, interface` — target lines + referrers.
+      const referrers = (g.items ?? []).map(it => it.label).join(', ');
+      const line = referrers !== '' ? `${g.locations.join(' ')}  ← ${referrers}` : g.locations.join(' ');
+      for (const l of wrapText(line, WRAP_COLS, 6)) console.log(l);
+      break;
+    }
+    case 'refs.broken.anchor': {
+      const details = (expanded ? (g.items ?? []).map(it => it.label) : (g.detail !== undefined ? [g.detail] : (g.items ?? []).slice(0, FOLD_OVERLAP_ITEMS).map(it => it.label)));
+      for (const d of details) console.log(`      ${d}`);
+      break;
+    }
+    default: {
+      for (const line of wrapText(g.locations.join('  '), WRAP_COLS, 6)) console.log(line);
+    }
+  }
+  if (g.suggestion !== undefined) console.log(`      ↳ ${g.suggestion}`);
 }
 
-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}`);
+/** Greedy two-space-separator wrap (location lists), fixed indent. */
+function wrapText(text: string, cols: number, indent: number): string[] {
+  const pad = ' '.repeat(indent);
+  const budget = Math.max(cols - indent, 20);
+  if (text.length <= budget) return text === '' ? [] : [pad + text];
+  const pieces = text.split('  ');
+  const lines: string[] = [];
+  let cur = '';
+  for (const p of pieces) {
+    const candidate = cur === '' ? p : `${cur}  ${p}`;
+    if (cur === '' || candidate.length <= budget) cur = candidate;
+    else {
+      lines.push(pad + cur);
+      cur = p;
+    }
   }
+  if (cur !== '') lines.push(pad + cur);
+  return lines;
+}
+
+/** `node_length: 3–120 | siblings: 3–12 | depth: 5–7` → `len 3–120 · sib 3–12 · depth 5–7`. */
+function compactRules(s: string): string {
+  return s
+    .replace('node_length: ', 'len ')
+    .replaceAll('siblings: ', 'sib ')
+    .replace('depth: ', 'depth ')
+    .replaceAll(' | ', ' · ');
 }
 
 function printHelp(): void {
@@ -282,7 +426,8 @@ Usage: cans <command> [args]
 
 Commands:
   init [--flat|--folders] [--bare] [--force] [--tool <name>]
-  check [--fix] [--strict] [--refs-only] [--no-redundancy] [file] [--json]
+  check [--fix] [--strict] [--refs-only] [--no-redundancy] [--show <section>] [file] [--json]
+        --fix + [file] rewrites ref-by comments in matching files only
   new adr <title>
   new task <name>
   done <name> [--allow-incomplete] [--skip-check] [--json]

package/src/core/overflow.ts

@@ -24,6 +24,7 @@ export function checkOverflow(
           level: 'error',
           category: 'overflow',
           message: 'code fence detected — extract to file and reference via see:',
+          rule: 'overflow.code_fence', // issue #41: machine-readable rule key
         });
       }
       if (node.hasTable && forceSet.has('table')) {
@@ -33,6 +34,7 @@ export function checkOverflow(
           level: 'error',
           category: 'overflow',
           message: 'table detected — extract to file and reference via see:',
+          rule: 'overflow.table', // issue #41
         });
       }
       if (rules.max_node_chars !== null && node.text.length > rules.max_node_chars) {
@@ -42,6 +44,7 @@ export function checkOverflow(
           level: 'error',
           category: 'overflow',
           message: `node exceeds max chars (${node.text.length} > ${rules.max_node_chars})`,
+          rule: 'overflow.node_chars', // issue #41
         });
       }
       walk(node.children);
@@ -67,6 +70,7 @@ export function checkNoChaining(targets: Map<string, OutlineNode[]>): Issue[] {
           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`,
+          rule: 'refs.chaining', // issue #41: §16 chaining is a refs-category rule
         });
       }
     }

package/src/core/redundancy.ts

@@ -1,5 +1,5 @@
 import type { OutlineNode, Issue, RedundancyRules } from '../types.ts';
-import { flattenNodes } from './outline.ts';
+import { flattenNodes, isSyntheticNode } from './outline.ts';
 
 interface NodeRef {
   text: string;
@@ -93,6 +93,7 @@ export function wordFrequency(
       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`,
+      rule: 'redundancy.keyword', // issue #41: machine-readable rule key
     });
   }
   return issues;
@@ -126,6 +127,8 @@ export function phraseOverlap(
           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',
+          // issue #41: 100% overlap is an exact duplicate; below that is fuzzy.
+          rule: pct >= 100 ? 'redundancy.overlap.exact' : 'redundancy.overlap.fuzzy',
         });
       }
     }
@@ -133,21 +136,63 @@ export function phraseOverlap(
   return issues;
 }
 
+/** Light English suffixes for the inflection check (issue #3), longest first —
+ *  stripped iteratively from the end so "carries" → "carri" (→ i↔y → "carry"). */
+const INFLECTION_SUFFIXES = ['ing', 'ers', 'er', 'ed', 'es', 'ly', 's'];
+
+/** Reduce a word to a rough stem by iteratively stripping common English
+ *  suffixes, then a trailing `e`, folding a trailing `i` onto `y` (so
+ *  deny/denied → deny, approve/approved → approv). Deliberately NOT a real
+ *  stemmer — only good enough to recognize pure suffix inflections. */
+function lightStem(word: string): string {
+  let w = word;
+  for (;;) {
+    const suffix = INFLECTION_SUFFIXES.find(s => w.length > s.length && w.endsWith(s));
+    if (suffix === undefined) break;
+    w = w.slice(0, w.length - suffix.length);
+  }
+  if (w.endsWith('i')) w = `${w.slice(0, -1)}y`;
+  if (w.endsWith('e')) w = w.slice(0, -1);
+  return w;
+}
+
+/** Issue #3: is `a` a pure suffix-inflection of `b` (or vice versa)? Both words
+ *  are reduced with lightStem; equal stems — or a stem equal to the other word's
+ *  unstemmed form — mean the pair differs only by an English inflection
+ *  (approve/approved, session/sessions, deny/denied), not by a typo. Stems
+ *  shorter than 3 chars are treated as unsafe and the pair is NOT skipped
+ *  (e.g. sing/singe stays a typo candidate). Genuine near-misses with no suffix
+ *  relation (flavour/flavor, table/tabble) keep different stems → still flagged. */
+export function isInflectionOf(a: string, b: string): boolean {
+  const sa = lightStem(a);
+  const sb = lightStem(b);
+  if (sa.length < 3 || sb.length < 3) return false;
+  return sa === sb || sa === b || sb === a;
+}
+
 /** 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. */
+ *  never pair up as typos. Issue #3: the layer now applies the SAME collection
+ *  filter as the other layers — the configured `redundancy.stopwords` and the
+ *  §8/§13 ref-syntax tokens (`see`, `md`) are never collected — and skips
+ *  candidate pairs that are pure suffix inflections of each other
+ *  (isInflectionOf) before the Levenshtein comparison, so English inflections
+ *  (approved/approve, sessions/session) are no longer reported as typos. */
 export function fuzzyDistance(
   nodes: NodeRef[],
   rules?: RedundancyRules,
 ): Issue[] {
   const synonyms = rules ? rules.synonyms : [];
+  const stopwords = rules ? rules.stopwords : [];
   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;
+      if (REF_SYNTAX_TOKENS.has(w)) continue;
+      if (stopwords.includes(w)) continue;
       seen.add(w);
       words.push({ text: w, file: node.file, line: node.line });
     }
@@ -159,12 +204,14 @@ export function fuzzyDistance(
       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;
+      if (isInflectionOf(a.text, b.text)) 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',
+          rule: 'redundancy.typo', // issue #41: word-form layer of the redundancy scheme
         });
       }
     }
@@ -208,6 +255,10 @@ export function crossFileCanonicality(
   const concepts = new Map<string, { files: Set<string>; first: NodeRef }>();
   for (const [key, nodes] of allFiles) {
     for (const node of flattenNodes(nodes)) {
+      // Issue #8: synthetic "(table)"/"(code fence)" placeholders are not
+      // concepts — comparing them across files fabricated "canonical home"
+      // warnings with nonsense advice.
+      if (isSyntheticNode(node)) continue;
       if (node.indent > 1) continue;
       const text = node.text.trim().toLowerCase();
       if (text.length === 0) continue;
@@ -234,13 +285,16 @@ export function crossFileCanonicality(
       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`,
+      rule: 'redundancy.duplicate_home', // issue #41
     });
   }
   return issues;
 }
 
 /** All four redundancy layers over every loaded spec node.
- *  `duplicateHomeCheck` (§18 references.duplicate_home_check) gates layer 4. */
+ *  `duplicateHomeCheck` (§18 references.duplicate_home_check) gates layer 4.
+ *  Issue #3: `redundancy.fuzzy` (§18 delete-key semantics: deleted → false)
+ *  gates layer 3 independently of `enabled`, which still covers all layers. */
 export function checkRedundancy(
   allFiles: Map<string, OutlineNode[]>,
   rules: RedundancyRules,
@@ -249,13 +303,18 @@ export function checkRedundancy(
   const nodes: NodeRef[] = [];
   for (const [file, tree] of allFiles) {
     for (const node of flattenNodes(tree)) {
+      // Issue #8: synthetic "(table)"/"(code fence)" placeholders are not
+      // content — excluded from all three text-comparison layers (they made
+      // any two table-opening files 100%-overlapping and inflated the
+      // "table"/"code"/"fence" word-frequency counts).
+      if (isSyntheticNode(node)) continue;
       nodes.push({ text: node.text, file, line: node.line });
     }
   }
   return [
     ...wordFrequency(nodes, rules),
     ...phraseOverlap(nodes, rules.phrase_overlap_threshold, rules),
-    ...fuzzyDistance(nodes, rules),
+    ...(rules.fuzzy !== false ? fuzzyDistance(nodes, rules) : []),
     ...(duplicateHomeCheck ? crossFileCanonicality(allFiles, rules.cross_file_threshold) : []),
   ];
 }