cans-spec 0.2.0 → 0.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cans-spec",
-  "version": "0.2.0",
-  "description": "Canonical Agent-Native Spec \u2014 the outline is the spec, the state, and the task board",
+  "version": "0.3.0",
+  "description": "Canonical Agent-Native Spec — the outline is the spec, the state, and the task board",
   "bin": {
     "cans": "./bin/cans.js"
   },

package/src/commands/check.ts

@@ -6,7 +6,7 @@ import {
   dirExists, detectFlatFolderConflicts, detectMalformedSpecDirs, discoverOverflowTargets,
 } from '../core/fs.ts';
 import {
-  parseOutline, extractBackPointers, flattenNodes, maxDepth as outlineMaxDepth,
+  parseOutline, extractBackPointers, realNodes, maxDepth as outlineMaxDepth,
   type ParseWarning,
 } from '../core/outline.ts';
 import { loadRules } from '../core/rules.ts';
@@ -42,6 +42,10 @@ const CHECK_FLAGS: FlagSpec[] = [
 ];
 
 const REF_BY_RE = /<!--\s*ref-by:\s*(.*?)\s*-->/;
+// Fence marker rule, mirrored from src/core/outline.ts (issue #6): a line whose
+// trimmed form starts with ``` toggles fence state. Kept as a regex to reuse
+// the outline.ts FENCE_RE convention; the two must never diverge.
+const FENCE_RE = /^```/;
 
 // globFiles throws ENOENT on missing dirs — guard the optional ones.
 function safeActiveTasks(root: string): string[] {
@@ -111,15 +115,56 @@ function refTargetKey(name: string, keys: Iterable<string>): string | null {
   return null;
 }
 
+/** Issue #6: remove ONLY the ref-by comment substring from a non-bullet line,
+ *  keeping the surrounding prose. Collapses the double space left where the
+ *  comment sat (one seam space absorbed) and trims trailing whitespace. The
+ *  caller drops the line only when nothing but the comment remains. */
+function stripRefByKeepProse(raw: string): string {
+  const m = raw.match(REF_BY_RE);
+  if (m === null || m.index === undefined) return raw;
+  let out = raw.slice(0, m.index) + raw.slice(m.index + m[0].length);
+  if (out.charAt(m.index - 1) === ' ' && out.charAt(m.index) === ' ') {
+    out = out.slice(0, m.index - 1) + out.slice(m.index);
+  }
+  return out.replace(/[ \t]+$/, '');
+}
+
 /** Rewrite `<!-- ref-by: ... -->` comments in one spec file source.
- *  Replaces the first existing comment's content, drops duplicates/stale ones,
- *  or inserts a fresh comment line right after the first root bullet. */
-function rewriteRefBy(source: string, body: string | null): string {
+ *  Fence-aware and prose-preserving (issue #6):
+ *  - Lines inside ``` fences (and the fence markers themselves) are preserved
+ *    byte-for-byte: never scanned as hits, never rewritten, never dropped, and
+ *    fenced "- fake bullets" are never insertion anchors.
+ *  - Replaces the first existing comment's content; duplicates/stale hits keep
+ *    their line — bullets are stripped as before, non-bullet prose loses only
+ *    the comment substring (the line is dropped only when bare).
+ *  - With no hits and a desired body, inserts a fresh comment line right after
+ *    the first root bullet outside any fence, appended at end when none exists
+ *    — unless the file ends inside an unterminated fence, in which case the
+ *    comment is inserted before the fence opener (never inside a fence).
+ *  Exported for regression tests (issue #6); behavior lives in this module. */
+export function rewriteRefBy(source: string, body: string | null): string {
   const lines: Array<string | null> = source.split('\n');
   const comment = body !== null && body !== '' ? `<!-- ref-by: ${body} -->` : null;
   const hits: number[] = [];
+  let fenceOpen = false;
+  let fenceOpener = -1;
+  const inFence: boolean[] = new Array(lines.length).fill(false);
   for (let i = 0; i < lines.length; i++) {
-    if (lines[i] !== null && REF_BY_RE.test(lines[i]!)) hits.push(i);
+    const raw = lines[i]!;
+    if (FENCE_RE.test(raw.trim())) {
+      // Fence marker: toggles state; never a hit, never an anchor, never touched.
+      inFence[i] = true;
+      if (fenceOpen) {
+        fenceOpen = false;
+      } else {
+        fenceOpen = true;
+        fenceOpener = i;
+      }
+      continue;
+    }
+    inFence[i] = fenceOpen;
+    if (fenceOpen) continue;
+    if (REF_BY_RE.test(raw)) hits.push(i);
   }
   if (hits.length > 0) {
     for (let j = 0; j < hits.length; j++) {
@@ -129,17 +174,27 @@ function rewriteRefBy(source: string, body: string | null): string {
         lines[i] = raw.replace(REF_BY_RE, comment);
       } else {
         const isBullet = /^\s*-\s/.test(raw);
-        lines[i] = isBullet ? raw.replace(REF_BY_RE, '').replace(/[ \t]+$/, '') : null;
+        if (isBullet) {
+          lines[i] = raw.replace(REF_BY_RE, '').replace(/[ \t]+$/, '');
+        } else {
+          // Issue #6: never delete a prose line whole — strip the comment only.
+          const stripped = stripRefByKeepProse(raw);
+          lines[i] = stripped.trim() === '' ? null : stripped;
+        }
       }
     }
   } else if (comment !== null) {
     let insertAt = lines.length;
     for (let i = 0; i < lines.length; i++) {
+      if (inFence[i]) continue; // fenced `- fake bullets` are not anchors
       if (/^- /.test(lines[i]!)) {
         insertAt = i + 1;
         break;
       }
     }
+    // Issue #6: never insert inside an open fence — appending at EOF while a
+    // fence is unterminated would corrupt the fenced region.
+    if (insertAt >= lines.length && fenceOpen) insertAt = fenceOpener;
     lines.splice(insertAt, 0, comment);
   }
   return lines.filter((l): l is string => l !== null).join('\n');
@@ -364,7 +419,13 @@ export async function checkWorkspace(root: string, opts: CheckArgs): Promise<Che
   let nodeCount = 0;
   let depthMax = 0;
   for (const nodes of specFiles.values()) {
-    nodeCount += flattenNodes(nodes).length;
+    // Issue #8: report REAL nodes only — synthetic "(table)"/"(code fence)"
+    // placeholders (leading table/fence before the first bullet) are not
+    // user content and inflated the header count and budget estimates.
+    nodeCount += realNodes(nodes).length;
+    // Depth keeps the full tree: a synthetic root sits at indent 0, so it can
+    // never raise depthMax; a workspace containing only phantoms now has
+    // nodeCount 0 and correctly reports maxDepth 0 (§35 empty-workspace case).
     depthMax = Math.max(depthMax, outlineMaxDepth(nodes));
   }
   const refsTotal = [...graph.forward.values()].reduce((a, ts) => a + ts.length, 0);

package/src/core/outline.ts

@@ -55,6 +55,9 @@ export function parseOutline(source: string, file: string, warnings?: ParseWarni
     refs: [],
     hasCodeFence: false,
     hasTable: false,
+    // Issue #8: real bullets are never synthetic; the two placeholder
+    // synthesis sites below flip this to true after makeNode.
+    synthetic: false,
   });
 
   for (let i = 0; i < lines.length; i++) {
@@ -78,6 +81,7 @@ export function parseOutline(source: string, file: string, warnings?: ParseWarni
         } else {
           const n = makeNode('(code fence)', fenceStartLine, 0);
           n.hasCodeFence = true;
+          n.synthetic = true; // issue #8: placeholder, not user content
           roots.push(n);
           stack.length = 0;
           stack.push(n);
@@ -97,6 +101,7 @@ export function parseOutline(source: string, file: string, warnings?: ParseWarni
         } else {
           const n = makeNode('(table)', lineNo, 0);
           n.hasTable = true;
+          n.synthetic = true; // issue #8: placeholder, not user content
           roots.push(n);
           stack.length = 0;
           stack.push(n);
@@ -170,20 +175,29 @@ export function parseOutline(source: string, file: string, warnings?: ParseWarni
         top.children.push(node);
         stack.push(node);
       } else {
-        // shallower: pop until we find the parent level
-        while (stack.length > 1 && stack[stack.length - 1].indent > indent) {
+        // shallower: pop until we find the parent level — all the way to an
+        // empty stack, not just down to stack[0] (issue #7). The stack bottom
+        // is only a real parent when the file's first bullet sits at column
+        // 0; when it opens indented (e.g. under a `#` heading) its indent
+        // must not swallow bullets that dedent past it, or the whole tree
+        // silently re-parents under that first node.
+        while (stack.length > 0 && stack[stack.length - 1].indent > indent) {
           stack.pop();
         }
-        const candidate = stack[stack.length - 1];
-        if (candidate.indent === indent) {
+        if (stack.length === 0) {
+          // dedented past every open node: a root sibling
+          roots.push(node);
+          stack.push(node);
+        } else if (stack[stack.length - 1].indent === indent) {
+          // sibling of the deepest open node at this level
           stack.pop();
           const parent = stack[stack.length - 1];
           if (parent) parent.children.push(node);
           else roots.push(node);
           stack.push(node);
         } else {
-          // indented jump deeper than expected under candidate
-          candidate.children.push(node);
+          // indented jump deeper than expected under that node
+          stack[stack.length - 1].children.push(node);
           stack.push(node);
         }
       }
@@ -194,6 +208,12 @@ export function parseOutline(source: string, file: string, warnings?: ParseWarni
   return roots;
 }
 
+/** Issue #8: true only for parser-created placeholder nodes ("(table)" /
+ *  "(code fence)") representing a leading table/fence — never user content. */
+export function isSyntheticNode(n: OutlineNode): boolean {
+  return n.synthetic === true;
+}
+
 export function flattenNodes(nodes: OutlineNode[]): OutlineNode[] {
   const out: OutlineNode[] = [];
   const walk = (ns: OutlineNode[]): void => {
@@ -209,8 +229,18 @@ export function flattenNodes(nodes: OutlineNode[]): OutlineNode[] {
 export function extractBackPointers(source: string, file: string): BackPointer[] {
   const out: BackPointer[] = [];
   const lines = normalizeEol(source).split('\n');
+  // Issue #6: fence awareness — a `<!-- ref-by: ... -->` quoted inside a fenced
+  // example is documentation, not a real back-pointer. Same toggle rule as
+  // parseOutline (trimmed line starts with ```); the marker line itself is
+  // fence infrastructure and never carries a counted comment either.
+  let fenceOpen = false;
   for (let i = 0; i < lines.length; i++) {
-    const m = lines[i].match(REF_BY_RE);
+    if (FENCE_RE.test(lines[i]!.trim())) {
+      fenceOpen = !fenceOpen;
+      continue;
+    }
+    if (fenceOpen) continue;
+    const m = lines[i]!.match(REF_BY_RE);
     if (!m) continue;
     const entries = m[1].split(',').map(s => s.trim()).filter(Boolean);
     for (const e of entries) {
@@ -220,6 +250,14 @@ export function extractBackPointers(source: string, file: string): BackPointer[]
   return out;
 }
 
+/** Flattened tree WITHOUT synthetic placeholder nodes — the view every
+ *  node-count and content-comparison consumer should use (issue #8).
+ *  flattenNodes itself is unchanged: the tree shape keeps the placeholders
+ *  (they carry hasTable/hasCodeFence for the overflow engine). */
+export function realNodes(nodes: OutlineNode[]): OutlineNode[] {
+  return flattenNodes(nodes).filter(n => !isSyntheticNode(n));
+}
+
 export function countNodes(nodes: OutlineNode[]): number {
   return flattenNodes(nodes).length;
 }

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;
@@ -133,21 +133,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,6 +201,7 @@ 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({
@@ -208,6 +251,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;
@@ -240,7 +287,9 @@ export function crossFileCanonicality(
 }
 
 /** 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 +298,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) : []),
   ];
 }

package/src/core/refs.ts

@@ -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

@@ -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/structure.ts

@@ -1,7 +1,10 @@
 import type { OutlineNode, Issue, StructureRules, ContentRules } from '../types.ts';
-import { flattenNodes } from './outline.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;
 }
 

package/src/core/style.ts

@@ -1,6 +1,23 @@
 import type { OutlineNode, Issue, StyleRules } from '../types.ts';
+import { isSyntheticNode } from './outline.ts';
 
-/** Style checks: shared-prefix nesting hint + unnecessary-nesting collapse hint.
+/** Style checks: shared-prefix nesting hint + unnecessary-nesting collapse hint,
+ *  modulated by `style.prefer` (issue #2 — the key was parsed and reconciled but
+ *  never read, so `prefer: nested` still advised "Collapse to sibling style.").
+ *
+ *  Prefer semantics:
+ *    - `prefer: 'sibling'` — the author prefers flat sibling lists: the
+ *      shared-prefix "Group under nested style." hint is suppressed (it argues
+ *      against the declared preference); the collapse-to-sibling hint still
+ *      fires (it agrees with it).
+ *    - `prefer: 'nested'` — the author prefers grouped outlines: the
+ *      "Collapse to sibling style." hint is suppressed; the shared-prefix
+ *      grouping hint still fires.
+ *    - `prefer: null` (key deleted, §18) — NO prefer-driven modulation: both
+ *      base hints fire exactly as they did before the prefer wiring existed.
+ *      "Deleted `prefer` disables prefer-driven style guidance" therefore means
+ *      the prefer-driven MODULATION is off, not that the base guidance is off.
+ *
  *  SEVERITY NOTE (arbitration, same class as the refs-severity decision): §14/§36
  *  show ✗ for style flags, but the frozen §35/§18 fixtures (flat-project,
  *  folder-project, init templates) structurally trigger the ≤N-leaf rule and the
@@ -8,8 +25,9 @@ import type { OutlineNode, Issue, StyleRules } from '../types.ts';
  *  findings stay `warning`-level. Changing test fixtures is out of bounds
  *  (test/ is frozen).
  *  §18 delete-key semantics: a style rule whose key is null/false no longer
- *  fires (deleted force_nested_above / force_sibling_below / prefer or
- *  shared_prefix_detection: false skip their rules entirely). */
+ *  fires — deleted force_nested_above / force_sibling_below or
+ *  shared_prefix_detection: false skip their rules entirely (deleted `prefer`
+ *  is the modulation-off case documented above; it skips nothing). */
 export function checkStyle(
   nodes: OutlineNode[],
   file: string,
@@ -21,49 +39,64 @@ export function checkStyle(
     for (const node of list) {
       const children = node.children;
 
-      const nestedAbove = rules.force_nested_above;
-      if (rules.shared_prefix_detection && nestedAbove !== null && children.length >= nestedAbove) {
-        const groups = new Map<string, number>();
-        for (const child of children) {
-          const word = child.text.split(/\s+/)[0] ?? '';
-          if (word === '') continue;
-          groups.set(word, (groups.get(word) ?? 0) + 1);
-        }
-        for (const [word, size] of groups) {
-          if (size >= nestedAbove) {
-            issues.push({
-              file,
-              line: node.line,
-              level: 'warning',
-              category: 'style',
-              message: `${size} siblings share prefix "${word}". Group under nested style.`,
-            });
+      // 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 nestedAbove = rules.force_nested_above;
+        // prefer: 'sibling' declares a flat-list preference — the grouping hint
+        // contradicts it and is suppressed ('nested'/null keep it firing).
+        if (
+          rules.shared_prefix_detection &&
+          rules.prefer !== 'sibling' &&
+          nestedAbove !== null &&
+          children.length >= nestedAbove
+        ) {
+          const groups = new Map<string, number>();
+          for (const child of children) {
+            const word = child.text.split(/\s+/)[0] ?? '';
+            if (word === '') continue;
+            groups.set(word, (groups.get(word) ?? 0) + 1);
+          }
+          for (const [word, size] of groups) {
+            if (size >= nestedAbove) {
+              issues.push({
+                file,
+                line: node.line,
+                level: 'warning',
+                category: 'style',
+                message: `${size} siblings share prefix "${word}". Group under nested style.`,
+              });
+            }
           }
         }
-      }
 
-      // §14: "Parent with ≤ force_sibling_below leaf children → collapse to
-      // sibling style." `≤` semantics (exactly N is flagged). The file root is
-      // exempt — a root concept with few subtopics is the normal spec shape,
-      // not unnecessary nesting. A single child is reported by the structure
-      // engine ("exactly 1 child"); don't double-report it here.
-      const siblingBelow = rules.force_sibling_below;
-      if (
-        siblingBelow !== null &&
-        node.indent > 0 &&
-        children.length >= 2 &&
-        children.length <= siblingBelow &&
-        children.every((c) => c.children.length === 0)
-      ) {
-        issues.push({
-          file,
-          line: node.line,
-          level: 'warning',
-          category: 'style',
-          // QA-03 F17 pluralization contract (unreachable for 1 — the ≥2 guard
-          // above plus the structure engine owns the 1-child case).
-          message: `"${node.text}" has ${children.length} ${children.length === 1 ? 'child' : 'children'}. Collapse to sibling style.`,
-        });
+        // §14: "Parent with ≤ force_sibling_below leaf children → collapse to
+        // sibling style." `≤` semantics (exactly N is flagged). The file root is
+        // exempt — a root concept with few subtopics is the normal spec shape,
+        // not unnecessary nesting. A single child is reported by the structure
+        // engine ("exactly 1 child"); don't double-report it here.
+        const siblingBelow = rules.force_sibling_below;
+        // prefer: 'nested' declares a grouped-outline preference — the collapse
+        // hint contradicts it and is suppressed ('sibling'/null keep it firing).
+        if (
+          siblingBelow !== null &&
+          rules.prefer !== 'nested' &&
+          node.indent > 0 &&
+          children.length >= 2 &&
+          children.length <= siblingBelow &&
+          children.every((c) => c.children.length === 0)
+        ) {
+          issues.push({
+            file,
+            line: node.line,
+            level: 'warning',
+            category: 'style',
+            // QA-03 F17 pluralization contract (unreachable for 1 — the ≥2 guard
+            // above plus the structure engine owns the 1-child case).
+            message: `"${node.text}" has ${children.length} ${children.length === 1 ? 'child' : 'children'}. Collapse to sibling style.`,
+          });
+        }
       }
 
       walk(children);

package/src/core/token-budget.ts

@@ -4,7 +4,7 @@ import type {
   OutlineNode, BackPointer, TokenBudgetRules,
   BudgetReadPlanItem, BudgetReadResult, BudgetWriteResult,
 } from '../types.ts';
-import { flattenNodes, parseOutline } from './outline.ts';
+import { flattenNodes, parseOutline, isSyntheticNode } from './outline.ts';
 import { targetMatchesKey } from './refs.ts';
 
 export function estimateTokens(text: string, charsPerToken: number): number {
@@ -19,7 +19,10 @@ function relPath(file: string): string {
 }
 
 function serializedNodeText(nodes: OutlineNode[]): string {
-  return flattenNodes(nodes).map(n => n.text).join('\n');
+  // Issue #8: synthetic "(table)"/"(code fence)" placeholders are not content —
+  // including them inflated every token estimate for files opening with a
+  // table/fence.
+  return flattenNodes(nodes).filter(n => !isSyntheticNode(n)).map(n => n.text).join('\n');
 }
 
 /** Token estimate for a workspace key (loaded nodes) or a raw file path (content read). */
@@ -53,6 +56,8 @@ export function findCanonicalHome(
   const candidates: Array<{ file: string; node: OutlineNode }> = [];
   for (const [file, nodes] of allFiles) {
     for (const node of flattenNodes(nodes)) {
+      // Issue #8: a synthetic placeholder must never be the canonical home.
+      if (isSyntheticNode(node)) continue;
       if (node.text.toLowerCase().includes(lc)) candidates.push({ file, node });
     }
   }

package/src/types.ts

@@ -20,6 +20,13 @@ export interface OutlineNode {
   refs: RefTarget[];
   hasCodeFence: boolean;
   hasTable: boolean;
+  /** Issue #8: true ONLY for parser-created placeholder nodes (text "(table)"
+   *  or "(code fence)") that represent a table/fence appearing BEFORE the
+   *  first bullet of a file. They carry the hasTable/hasCodeFence signal but
+   *  are not user content — consumers that count nodes or compare node text
+   *  as content must exclude them (isSyntheticNode). Never set on nodes
+   *  parsed from real bullets. */
+  synthetic?: boolean;
 }
 
 export interface BackPointer {
@@ -63,7 +70,9 @@ export interface StructureRules {
 }
 
 export interface StyleRules {
-  /** Deleted `prefer` disables prefer-driven style guidance (§18). */
+  /** Style-guide selector: `sibling` suppresses the nested-grouping hint,
+   *  `nested` suppresses the sibling-collapse hint; null (deleted, §18) → no
+   *  prefer-driven modulation — both base style hints fire unchanged. */
   prefer: 'sibling' | 'nested' | null;
   force_nested_above: number | null;
   force_sibling_below: number | null;
@@ -90,6 +99,8 @@ export interface RedundancyRules {
   word_frequency_threshold: number | null;
   phrase_overlap_threshold: number | null;
   cross_file_threshold: number | null;
+  /** Layer 3 switch: deleted → false (§18 delete-key semantics). */
+  fuzzy: boolean;
   /** Parameters (not checks): keep their defaults when deleted (§18). */
   stopwords: string[];
   synonyms: string[][];

package/templates/_rules.yaml

@@ -27,6 +27,7 @@ redundancy:
   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]