fix(extract): count a plural use of a singular-defined term as a use

STRUCT-005 flags defined terms with no downstream use as probable template
leftovers. Usage was matched by the exact term (`\bTerm\b`), so a term
defined in the singular but used only in the plural — "Confidential
Material" … "the Confidential Materials", "Disclosing Party" … "the
Disclosing Parties" — counted as zero uses and was wrongly reported as
unused. (Possessives already matched, since the apostrophe is a word
boundary.)

Match the term's regular plural alongside the term (final-word +s / y→ies /
sibilant +es). Terms whose final word already ends in "s" are left alone
(ambiguous). A prefix-sharing word like "Feedback" is not counted as a use
of "Fee" because the alternation is word-boundary anchored.

Zero golden churn: no fixture across the 327-doc corpus defines a term in
the singular and uses it only in the plural, so this is a prospective FP
reduction. `unused_terms` feeds STRUCT-005 (finding-level).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: clay-good

README.md

@@ -4,7 +4,7 @@
 
 **Vaulytica is the second pair of eyes you can cite.**
 
-`1,111 deterministic rules` · `20 cross-document checks` · `5 pre-disclosure checks` · `3 execution-readiness reconciliations` · `5 derived-deadline families` · `16 document sub-domains` · `88 state-law overlays (non-compete · security deposit · usury · will formalities)` · `10 export formats` · `0 servers` · `0 AI` · `5,856 passing tests` · `v9.41.0` · `MIT`
+`1,111 deterministic rules` · `20 cross-document checks` · `5 pre-disclosure checks` · `3 execution-readiness reconciliations` · `5 derived-deadline families` · `16 document sub-domains` · `88 state-law overlays (non-compete · security deposit · usury · will formalities)` · `10 export formats` · `0 servers` · `0 AI` · `5,858 passing tests` · `v9.41.0` · `MIT`
 
 ![Vaulytica landing page — "Drop legal docs. Get a report. Nothing leaves your browser."](docs/images/hero.png)
 
@@ -1332,7 +1332,7 @@ npm run dev          # open the printed URL
 npm run build        # static site → dist/
 npm run typecheck    # tsc --noEmit
 npm run lint         # eslint
-npm run test         # vitest — 5,856 tests, ~35s
+npm run test         # vitest — 5,858 tests, ~35s
 npm run coverage     # vitest + V8 coverage, enforces the regression floor
 npm run accuracy     # v5 Ground Truth harness → tools/accuracy/SCOREBOARD.md
 npm run mutation     # Stryker mutation score (scoped to extractors; slow, off the per-push path)

src/extract/definitions.test.ts

@@ -36,6 +36,32 @@ describe("extractDefinitions", () => {
     expect(terms).not.toContain("Headings");
   });
 
+  it("counts a plural use of a singular-defined term as a use", () => {
+    // A term defined in the singular but used only in the plural was reported by
+    // STRUCT-005 as an unused template leftover even though it is used.
+    const tree = buildTree([
+      "Definitions",
+      '"Confidential Material" means any non-public information.',
+      '"Disclosing Party" means the party sharing information.',
+      "Each party shall protect the Confidential Materials it receives from the Disclosing Parties.",
+    ]);
+    const map = extractDefinitions(tree);
+    expect(map.unused_terms).not.toContain("Confidential Material");
+    expect(map.unused_terms).not.toContain("Disclosing Party");
+    expect(map.entries.find((e) => e.term === "Confidential Material")?.used_at.length).toBe(1);
+  });
+
+  it("does not treat an unrelated word sharing a prefix as a plural use", () => {
+    const tree = buildTree([
+      "Definitions",
+      '"Fee" means the amount payable for the Services.',
+      "The Customer may submit Feedback about the platform.",
+    ]);
+    const map = extractDefinitions(tree);
+    // "Feedback" is not a use of "Fee"/"Fees"; the term stays unused.
+    expect(map.unused_terms).toContain("Fee");
+  });
+
   it("records defined-but-never-used terms", () => {
     const tree = buildTree([
       "Definitions",

src/extract/definitions.ts

@@ -542,7 +542,15 @@ export function extractDefinitions(tree: DocumentTree): DefinitionMap {
 
   // Pass 3: record every use of each term outside its definition.
   for (const entry of definitions.values()) {
-    const needle = new RegExp(`\\b${escapeRegExp(entry.term)}\\b`, "g");
+    // Match the term as defined and its regular plural — a term defined in the
+    // singular is routinely used in the plural ("… the Confidential Materials
+    // it receives"), which is still a use, not a template leftover.
+    const plural = regularPlural(entry.term);
+    const alternatives =
+      plural && plural !== entry.term
+        ? `${escapeRegExp(entry.term)}|${escapeRegExp(plural)}`
+        : escapeRegExp(entry.term);
+    const needle = new RegExp(`\\b(?:${alternatives})\\b`, "g");
     forEachParagraph(tree, (ctx) => {
       // Skip the definition itself. For an express definition that is the
       // whole paragraph — a term repeated inside its own definition body
@@ -1240,3 +1248,24 @@ function registerDefinition(map: Map<string, DefinitionEntry>, entry: Definition
 function escapeRegExp(s: string): string {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+
+/**
+ * Regular English plural of a term's final word — "Confidential Material" →
+ * "Confidential Materials", "Disclosing Party" → "Disclosing Parties",
+ * "Franchise" → "Franchises". Returns null when no simple rule applies (the
+ * final word already ends in "s", so its plural is ambiguous — "Losses" vs an
+ * already-plural "Fees"). Used only to count a singular-defined term that the
+ * body uses in the plural as a genuine use, so STRUCT-005 does not report it as
+ * an unused template leftover.
+ */
+function regularPlural(term: string): string | null {
+  const m = /^(.*?)(\S+)$/.exec(term);
+  if (!m) return null;
+  const [, head, last] = m as unknown as [string, string, string];
+  if (/s$/i.test(last)) return null;
+  let plural: string;
+  if (/[^aeiou]y$/i.test(last)) plural = last.replace(/y$/i, "ies");
+  else if (/(x|z|ch|sh)$/i.test(last)) plural = last + "es";
+  else plural = last + "s";
+  return head + plural;
+}