feat(prompt-hook): graph-derived gate tier + confidence-tiered injection + gate telemetry (#1136)

The keyword gate (#1126) can never know a repo's domain nouns. This adds
the graph-derived tier the design discussion converged on: symbol names
are split into prose segments at index time (name_segment_vocab, riding
the insertNode write path), and the hook verifies a prompt's plain words
against them — "the state machine des commandes" → OrderStateMachine, in
any language whose technical nouns are Latin script.

Confidence now decides HOW MUCH to inject, not just whether:
- HIGH (keyword, or index-verified code token): full explore injection,
  unchanged — the validated adoption lever.
- MEDIUM (segment matches only): a ~500-byte pointer naming the matching
  symbols; the AGENT writes the explore query. Never runs explore, so a
  fuzzy match can't inject 16KB of wrong-feature context.
- Silent otherwise, as before.

Precision is derived from the repo's own naming statistics plus measured
FP fixes: co-occurrence (≥2 words on one name) always qualifies; a single
word must be ≥5 chars, cluster across 2–25 names (singletons are prose
coincidence: "deploy to production" → matchesNonProductionDir), match a
multi-segment name, and not be an English function/filler word (the one
place a word list is honest: identifiers are English, so only English
prose collides). Every candidate is re-verified against nodes before
being surfaced — vocab rows are proposals, deletions leave orphans by
design, a full index rebuilds from scratch, and sync heals pre-upgrade
databases (batched + yielding; emptiness captured at sync ENTRY so the
sync's own writes can't mask the backfill).

Schema v7 migration is DDL-only (instant; none of the #1067 row-churn
hazards). Gate outcomes roll up as anonymous usage counters
(prompt-hook-gate-<outcome>, names only, never content) through the
existing telemetry pipeline — recall becomes measurable, and the counters
are the agreed kill-criterion data for ever revisiting a local classifier.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

__tests__/db-perf.test.ts

@@ -343,7 +343,7 @@ describe('migration v6: dedup edges + add identity index on upgrade (#1034)', ()
     runMigrations(raw, 5);
 
     expect(count()).toBe(2); // duplicate collapsed, the distinct `calls` edge kept
-    expect(getCurrentVersion(raw)).toBe(6);
+    expect(getCurrentVersion(raw)).toBe(7);
     const idx = raw
       .prepare("SELECT name FROM sqlite_master WHERE type='index' AND name='idx_edges_identity'")
       .get();

__tests__/foundation.test.ts

@@ -370,7 +370,7 @@ describe('Database Connection', () => {
 
     const version = db.getSchemaVersion();
     expect(version).not.toBeNull();
-    expect(version?.version).toBe(6);
+    expect(version?.version).toBe(7);
 
     db.close();
   });

__tests__/identifier-segments.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect } from 'vitest';
+import {
+  splitIdentifierSegments,
+  extractProseCandidates,
+  normalizeProseWord,
+  segmentLookupVariants,
+} from '../src/search/identifier-segments';
+
+describe('splitIdentifierSegments — symbol names → prose words', () => {
+  it('splits camelCase / PascalCase at humps', () => {
+    expect(splitIdentifierSegments('OrderStateMachine')).toEqual(['order', 'state', 'machine']);
+    expect(splitIdentifierSegments('userId')).toEqual(['user', 'id']);
+  });
+
+  it('handles acronym runs — HTML stays one segment', () => {
+    expect(splitIdentifierSegments('parseHTMLDocument')).toEqual(['parse', 'html', 'document']);
+    expect(splitIdentifierSegments('HTMLParser')).toEqual(['html', 'parser']);
+  });
+
+  it('keeps digits glued to their word', () => {
+    expect(splitIdentifierSegments('base64Encode')).toEqual(['base64', 'encode']);
+    expect(splitIdentifierSegments('parseHTML5Doc')).toEqual(['parse', 'html5', 'doc']);
+  });
+
+  it('splits snake_case, kebab-case, and dotted file names', () => {
+    expect(splitIdentifierSegments('snake_case_name')).toEqual(['snake', 'case', 'name']);
+    expect(splitIdentifierSegments('MAX_RETRY_COUNT')).toEqual(['max', 'retry', 'count']);
+    expect(splitIdentifierSegments('checkout.service.ts')).toEqual(['checkout', 'service', 'ts']);
+    expect(splitIdentifierSegments('state-machine')).toEqual(['state', 'machine']);
+  });
+
+  it('drops sub-minimum and digit-only fragments, dedupes', () => {
+    expect(splitIdentifierSegments('x')).toEqual([]);
+    expect(splitIdentifierSegments('42')).toEqual([]);
+    expect(splitIdentifierSegments('getData_getData')).toEqual(['get', 'data']);
+  });
+});
+
+describe('extractProseCandidates — prompt prose → lookup words', () => {
+  it('keeps content words, drops short function words, in any Latin language', () => {
+    expect(extractProseCandidates('comment marche la state machine des commandes ?')).toEqual([
+      'comment', 'marche', 'state', 'machine', 'commandes',
+    ]);
+  });
+
+  it('strips diacritics so loanwords meet ASCII identifier segments', () => {
+    expect(extractProseCandidates('la résolution des références')).toEqual(['resolution', 'references']);
+    expect(normalizeProseWord('Übersicht')).toBe('ubersicht');
+  });
+
+  it("splits on apostrophes — l'architecture keeps the noun", () => {
+    expect(extractProseCandidates("explique l'architecture du module de stock")).toEqual([
+      'explique', 'architecture', 'module', 'stock',
+    ]);
+  });
+
+  it('caps candidates and skips unsegmented-script sentence runs', () => {
+    const many = Array.from({ length: 25 }, (_, i) => `distinctword${String.fromCharCode(97 + i)}`).join(' ');
+    expect(extractProseCandidates(many)).toHaveLength(16);
+    // A no-spaces CJK sentence is one giant run — over the length ceiling, skipped.
+    expect(extractProseCandidates('請解釋一下這個訂單狀態機的整體運作流程與架構設計方式')).toEqual([]);
+    // Short CJK runs pass through as candidates — no script filter; the graph
+    // verification tier rejects them (identifiers are almost never CJK).
+    expect(extractProseCandidates('修复这个拼写错误')).toEqual(['修复这个拼写错误']);
+  });
+
+  it('drops digit-only and sub-4-char words', () => {
+    expect(extractProseCandidates('fix the bug in v2 at 1234')).toEqual([]);
+  });
+});
+
+describe('segmentLookupVariants — light plural folding', () => {
+  it('folds trailing s/es so plurals hit singular segments', () => {
+    expect(segmentLookupVariants('services')).toContain('service');
+    expect(segmentLookupVariants('machines')).toContain('machine');
+  });
+
+  it('never strips a word below the minimum', () => {
+    expect(segmentLookupVariants('bus')).toEqual(['bus']);
+  });
+});

__tests__/pr19-improvements.test.ts

@@ -299,7 +299,7 @@ describe('Best-Candidate Resolution', () => {
 describe('Schema v2 Migration', () => {
   it.skipIf(!HAS_SQLITE)('should have correct current schema version', async () => {
     const { CURRENT_SCHEMA_VERSION } = await import('../src/db/migrations');
-    expect(CURRENT_SCHEMA_VERSION).toBe(6);
+    expect(CURRENT_SCHEMA_VERSION).toBe(7);
   });
 
   it.skipIf(!HAS_SQLITE)('should have migration for version 2', async () => {

__tests__/segment-vocab.test.ts

@@ -0,0 +1,144 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { CodeGraph } from '../src';
+import { extractProseCandidates } from '../src/search/identifier-segments';
+
+/**
+ * The graph-derived gate behind the prompt hook's MEDIUM tier: symbol names
+ * are segmented into the words a human uses for them in prose
+ * (name_segment_vocab, populated on the node write path), and
+ * CodeGraph.getSegmentMatches verifies prompt words against them with
+ * co-occurrence / rarity rules. Precision comes from the repo's own naming
+ * statistics — no keyword vocabulary involved.
+ */
+describe('name-segment vocabulary + getSegmentMatches (graph-derived gate)', () => {
+  let dir: string;
+  let cg: CodeGraph;
+
+  beforeEach(async () => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'segment-vocab-'));
+    fs.mkdirSync(path.join(dir, 'src'), { recursive: true });
+    fs.writeFileSync(
+      path.join(dir, 'src', 'state-machine.ts'),
+      `export class OrderStateMachine {
+  transition(from: string, to: string): boolean { return from !== to; }
+}
+`,
+    );
+    fs.writeFileSync(
+      path.join(dir, 'src', 'checkout.ts'),
+      `export class CheckoutService {
+  submitOrder(): void {}
+}
+export class CheckoutController {
+  handle(): void {}
+}
+export function loadConfig(): void {}
+`,
+    );
+    // 30 distinct names sharing the segment "data" — a ubiquitous segment that
+    // must NOT qualify as a single-word signal (rarity ceiling).
+    const noise = Array.from({ length: 30 }, (_, i) => {
+      const suffix = `${String.fromCharCode(65 + (i % 26))}${i}`;
+      return `export function dataLoader${suffix}(): number { return ${i}; }`;
+    }).join('\n');
+    // The measured-FP shapes: a repo-rare segment that is an English function
+    // word ("this"), and a common-verb segment ("write").
+    const fpBait = `
+export function resolveDeferredThisMemberRefs(): void {}
+export function writeConfig(): void {}
+`;
+    fs.writeFileSync(path.join(dir, 'src', 'noise.ts'), noise + fpBait + '\n');
+
+    cg = await CodeGraph.init(dir, { silent: true });
+    await cg.indexAll();
+  });
+
+  afterEach(() => {
+    cg.destroy();
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('co-occurrence: two prose words on one name find it — the reported-prompt shape', () => {
+    // The words a French prompt would produce: "comment marche la state
+    // machine des commandes ?" — no keyword list knows any of them.
+    const words = extractProseCandidates('comment marche la state machine des commandes ?');
+    const matches = cg.getSegmentMatches(words);
+    expect(matches.map((m) => m.name)).toContain('OrderStateMachine');
+    const hit = matches.find((m) => m.name === 'OrderStateMachine')!;
+    expect(hit.matchedWords).toEqual(['machine', 'state']);
+    expect(hit.filePath).toContain('state-machine.ts');
+    expect(hit.kind).not.toBe('file');
+  });
+
+  it('single rare word qualifies; ubiquitous and singleton words do not', () => {
+    // "checkout" clusters (Service + Controller) — a concept this repo is about.
+    expect(cg.getSegmentMatches(['checkout']).map((m) => m.name)).toContain('CheckoutService');
+    // "data" appears in 30 names here — noise, not signal.
+    expect(cg.getSegmentMatches(['data'])).toEqual([]);
+    // "machine" appears in exactly ONE name — a singleton is prose
+    // coincidence for a single word (the "deploy to production" FP shape);
+    // it stays reachable through co-occurrence ("state machine").
+    expect(cg.getSegmentMatches(['machine'])).toEqual([]);
+  });
+
+  it('plural folding: "services" still meets the "service" segment', () => {
+    const matches = cg.getSegmentMatches(['checkout', 'services']);
+    const hit = matches.find((m) => m.name === 'CheckoutService');
+    expect(hit).toBeDefined();
+    expect(hit!.matchedWords).toEqual(['checkout', 'services']);
+  });
+
+  it('vocab rows are proposals — a name with no surviving node is never surfaced', () => {
+    // Plant an orphan row (as file deletion would): the honesty gate must drop it.
+    const queries = (cg as unknown as { queries: { insertNameSegmentsBatch(names: string[]): void } }).queries;
+    queries.insertNameSegmentsBatch(['GhostSymbolMachine']);
+    const matches = cg.getSegmentMatches(['ghost', 'symbol']);
+    expect(matches).toEqual([]);
+  });
+
+  it('unrelated prose matches nothing', () => {
+    expect(cg.getSegmentMatches(extractProseCandidates('write a haiku about autumn leaves'))).toEqual([]);
+  });
+
+  it('English function/filler words are never single-word evidence — the measured FPs', () => {
+    // "fix this typo" — 'this' IS a (rare!) segment here via
+    // resolveDeferredThisMemberRefs; the stoplist keeps it out of candidates.
+    expect(cg.getSegmentMatches(extractProseCandidates('fix this typo'))).toEqual([]);
+    // "write …" — writeConfig exists; 'write' is stoplisted prose.
+    expect(cg.getSegmentMatches(extractProseCandidates('write something for the readme'))).toEqual([]);
+    // Engine-level backstop, independent of extraction: a sub-5-char single
+    // word never fires the single-word tier even if a caller passes it raw.
+    expect(cg.getSegmentMatches(['this'])).toEqual([]);
+    // But the same segments remain reachable through CO-OCCURRENCE — the
+    // stoplist only removes thin single-word evidence: naming both halves of
+    // writeConfig via prose is still a match ("config" is not stoplisted).
+    expect(cg.getSegmentMatches(['config']).map((m) => m.name)).toContain('writeConfig');
+  });
+
+  it('sync heals an empty vocab over a populated graph (pre-vocab-table upgrade path)', async () => {
+    const queries = (cg as unknown as { queries: { clearNameSegmentVocab(): void; isNameSegmentVocabEmpty(): boolean } }).queries;
+    queries.clearNameSegmentVocab();
+    expect(queries.isNameSegmentVocabEmpty()).toBe(true);
+    await cg.sync();
+    expect(queries.isNameSegmentVocabEmpty()).toBe(false);
+    expect(cg.getSegmentMatches(['state', 'machine']).map((m) => m.name)).toContain('OrderStateMachine');
+  });
+
+  it('heal covers UNCHANGED files even when the same sync also indexes changed ones', async () => {
+    // Regression: emptiness must be captured at sync ENTRY — the sync's own
+    // incremental writes populate rows for the files it touches, and an
+    // end-of-sync emptiness check would see those rows and skip the backfill,
+    // leaving every unchanged file's names unsegmented forever.
+    const queries = (cg as unknown as { queries: { clearNameSegmentVocab(): void } }).queries;
+    queries.clearNameSegmentVocab();
+    const touched = path.join(dir, 'src', 'state-machine.ts');
+    fs.writeFileSync(touched, fs.readFileSync(touched, 'utf8') + '\n// touched\n');
+    await cg.sync();
+    // The touched file's names came from the incremental write path; the
+    // UNTOUCHED file's names must come from the backfill.
+    expect(cg.getSegmentMatches(['checkout']).map((m) => m.name)).toContain('CheckoutService');
+  });
+});