@wooojin/forgen 0.1.0

package/dist/engine/solution-index.js

@@ -0,0 +1,252 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { parseFrontmatterOnly, isV1Format, migrateV1toV3 } from './solution-format.js';
+import { defaultNormalizer } from './term-normalizer.js';
+import { withFileLockSync } from '../hooks/shared/file-lock.js';
+import { atomicWriteText } from '../hooks/shared/atomic-write.js';
+import { createLogger } from '../core/logger.js';
+const log = createLogger('solution-index');
+/**
+ * Cache keyed by an order-preserving directory signature.
+ *
+ * Why this matters:
+ *   - `buildIndex` accumulates entries in dir order, and `solution-reader`
+ *     returns the first match — so dir order is the precedence chain
+ *     (me > team > project, by convention).
+ *   - The previous single `cachedIndex` global was reused regardless of the
+ *     `dirs` argument, so different cwd contexts received stale results
+ *     when their cached dirs' mtimes hadn't changed.
+ *   - We must NOT sort the signature: `[me,project]` and `[project,me]` are
+ *     legitimately different precedence chains and need separate cache slots.
+ *
+ * PR2c-2: LRU eviction with insertion-order touch.
+ *   long-running MCP 서버가 여러 cwd를 처리하면 cache가 무한 누적될 수 있음.
+ *   Map의 insertion order를 LRU 시뮬레이션에 활용 — set/get 시 delete + set으로
+ *   touch해 가장 최근 사용된 entry가 마지막에 오게 한다. 32 초과 시 oldest evict.
+ */
+const MAX_CACHE_ENTRIES = 32;
+const cachedIndexes = new Map();
+/**
+ * SOFT_CAP: 디렉터리당 인덱싱되는 entry 수 상한 (parse 후 slice).
+ *   100 → 500 상향 (accumulated knowledge base에 100은 너무 낮음).
+ *
+ * HARD_CAP: 디렉터리당 read+parse하는 파일 수 상한.
+ *   SOFT_CAP만으로는 readFileSync + YAML parse가 N번 발생해 hook이 수십 초
+ *   블록될 수 있음. HARD_CAP 초과 시 statSync로 cheap mtime 정렬해 상위만 처리.
+ */
+const SOFT_CAP = 500;
+const HARD_CAP = 5000;
+/**
+ * Build an escape-safe, order-preserving signature for a dirs set.
+ * JSON.stringify avoids delimiter collisions when paths contain `|` or `:`.
+ */
+function dirsSignature(dirs) {
+    return JSON.stringify(dirs.map(d => [d.scope, d.dir]));
+}
+export function isIndexStale(index) {
+    for (const [dir, mtime] of Object.entries(index.directoryMtimes)) {
+        try {
+            const current = fs.statSync(dir).mtimeMs;
+            if (current !== mtime)
+                return true;
+        }
+        catch {
+            // Dir doesn't exist anymore
+            return true;
+        }
+    }
+    return false;
+}
+function buildIndex(dirs) {
+    const entries = [];
+    const directoryMtimes = {};
+    for (const dirConfig of dirs) {
+        const { dir } = dirConfig;
+        let dirStat;
+        try {
+            dirStat = fs.statSync(dir);
+        }
+        catch {
+            continue; // skip non-existent dirs
+        }
+        directoryMtimes[dir] = dirStat.mtimeMs;
+        let files;
+        try {
+            files = fs.readdirSync(dir).filter(f => f.endsWith('.md'));
+        }
+        catch {
+            continue;
+        }
+        // HARD_CAP: read+parse 비용 상한. 초과 시 cheap statSync 정렬로 상위만 처리.
+        if (files.length > HARD_CAP) {
+            console.warn(`[forgen] Warning: ${dir} contains ${files.length} files; pre-filtering to the ${HARD_CAP} most recent before parsing.`);
+            const stats = [];
+            for (const f of files) {
+                try {
+                    const m = fs.statSync(path.join(dir, f)).mtimeMs;
+                    stats.push({ f, m });
+                }
+                catch {
+                    // skip unreadable
+                }
+            }
+            stats.sort((a, b) => b.m - a.m);
+            files = stats.slice(0, HARD_CAP).map(s => s.f);
+        }
+        const fileEntries = [];
+        // C2: diagnostic counters for solutions dropped during index build.
+        // Pre-C2 these were silent `continue` statements — users had no way
+        // to know a file existed on disk but was missing from the index
+        // (observed cause: auto-compound writing frontmatter with the wrong
+        // evidence schema, which made the whole file disappear from searches
+        // without any user-visible feedback). Logging them at debug level
+        // makes `forgen doctor` / log inspection surface the gap while
+        // keeping the normal output quiet.
+        let droppedMalformed = 0;
+        let droppedRetired = 0;
+        let droppedIoError = 0;
+        let droppedSymlink = 0;
+        for (const file of files) {
+            try {
+                const filePath = path.join(dir, file);
+                // Security: symlink을 통한 임의 파일 읽기 방지 (모든 형식 공통)
+                const lst = fs.lstatSync(filePath);
+                if (lst.isSymbolicLink()) {
+                    droppedSymlink++;
+                    continue;
+                }
+                // A1 performance fix (2026-04-09): short-circuit tiny files
+                // before doing YAML parse on the hot path. A valid v3 solution
+                // needs at minimum a `---` fence + `name:` + `version:` +
+                // `status:` + `confidence:` + `type:` + `scope:` + `tags:` +
+                // `identifiers:` + `evidence:` block + closing `---` + a body,
+                // which is ~200 bytes at absolute minimum. Files smaller than
+                // 64 bytes cannot possibly contain valid frontmatter, so we
+                // skip the readFileSync + YAML parse on them. Observed in
+                // production: a test that planted 6000 empty .md files was
+                // spending the entire 3s hook budget parsing YAML on files
+                // that were 0 bytes. The optimization cuts that path from
+                // ~7s to ~100ms.
+                if (lst.size < 64) {
+                    droppedMalformed++;
+                    log.debug(`dropped (file too small: ${lst.size} bytes): ${filePath}`);
+                    continue;
+                }
+                let content = fs.readFileSync(filePath, 'utf-8');
+                const fileMtime = lst.mtimeMs;
+                if (!content.trimStart().startsWith('---') && isV1Format(content)) {
+                    // PR2b: V1→V3 migration도 lock으로 보호. 동시 hook이 같은 V1 파일을
+                    // 마이그레이션하면 last-writer-wins로 손상될 수 있다. parseSolutionV3를
+                    // 못 쓰는 케이스라 mutateSolutionFile API 대신 명시적 lock + atomic write.
+                    try {
+                        withFileLockSync(filePath, () => {
+                            const fresh = fs.readFileSync(filePath, 'utf-8');
+                            if (fresh.trimStart().startsWith('---'))
+                                return; // 다른 mutator가 이미 마이그레이션
+                            if (!isV1Format(fresh))
+                                return;
+                            const migrated = migrateV1toV3(fresh, filePath);
+                            atomicWriteText(filePath, migrated);
+                            content = migrated;
+                        });
+                    }
+                    catch { /* lock 실패는 non-fatal */ }
+                }
+                const fm = parseFrontmatterOnly(content);
+                if (!fm) {
+                    droppedMalformed++;
+                    log.debug(`dropped (malformed frontmatter): ${filePath}`);
+                    continue;
+                }
+                if (fm.status === 'retired') {
+                    droppedRetired++;
+                    continue;
+                }
+                fileEntries.push({
+                    entry: {
+                        name: fm.name,
+                        status: fm.status,
+                        confidence: fm.confidence,
+                        type: fm.type,
+                        scope: dirConfig.scope,
+                        tags: fm.tags,
+                        // T2: pre-expand via the shared term normalizer. Once per solution
+                        // per index build, not once per solution per query. Safe to
+                        // recompute on rebuild (cheap: O(N_tags) Map lookups).
+                        normalizedTags: defaultNormalizer.normalizeTerms(fm.tags),
+                        identifiers: fm.identifiers,
+                        filePath,
+                    },
+                    mtime: fileMtime,
+                });
+            }
+            catch (e) {
+                droppedIoError++;
+                log.debug(`dropped (i/o or parse error) ${file}: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+        // Summary log for silently dropped files.
+        //
+        // Design: the index is rebuilt on every hook invocation when the
+        // directory mtime is stale, so a warn-on-every-drop policy would
+        // spam stderr on every matching prompt. Instead:
+        //   - debug-level always: the per-file log calls above already
+        //     capture each drop path for log inspection / `forgen doctor`
+        //   - warn-level only when the drop rate is materially high
+        //     (>10% of files OR >10 files in absolute terms), which
+        //     indicates a structural problem — e.g. auto-compound writing
+        //     malformed frontmatter in bulk, not a single one-off file
+        //   - retired drops are always debug (expected filter semantics)
+        //
+        // Pre-H-1 (first pass of C2): every non-zero drop warn'd and
+        // leaked into test stderr. H-1 downgrades to debug for small counts.
+        const totalBad = droppedMalformed + droppedIoError + droppedSymlink;
+        const totalScanned = files.length;
+        const badRatio = totalScanned > 0 ? totalBad / totalScanned : 0;
+        if (totalBad >= 10 || (totalBad > 0 && badRatio >= 0.1)) {
+            log.warn(`${dir}: ${droppedMalformed} malformed, ${droppedIoError} i/o errors, ${droppedSymlink} symlinks skipped (${totalBad}/${totalScanned} files)`);
+        }
+        else if (totalBad > 0) {
+            log.debug(`${dir}: ${droppedMalformed} malformed, ${droppedIoError} i/o errors, ${droppedSymlink} symlinks skipped (${totalBad}/${totalScanned} files)`);
+        }
+        if (droppedRetired > 0) {
+            log.debug(`${dir}: ${droppedRetired} retired solutions filtered (expected)`);
+        }
+        fileEntries.sort((a, b) => b.mtime - a.mtime);
+        if (fileEntries.length > SOFT_CAP) {
+            console.warn(`[forgen] Warning: ${dir} has ${fileEntries.length} solutions, only the ${SOFT_CAP} most recent are indexed.`);
+        }
+        const limited = fileEntries.slice(0, SOFT_CAP);
+        for (const { entry } of limited) {
+            entries.push(entry);
+        }
+    }
+    return { entries, directoryMtimes, builtAt: Date.now() };
+}
+export function getOrBuildIndex(dirs) {
+    const sig = dirsSignature(dirs);
+    const cached = cachedIndexes.get(sig);
+    if (cached && !isIndexStale(cached)) {
+        // LRU touch: re-insert으로 가장 최근 사용 표시
+        cachedIndexes.delete(sig);
+        cachedIndexes.set(sig, cached);
+        return cached;
+    }
+    // Stale rebuild path도 LRU touch — JS Map.set on existing key는
+    // insertion order를 갱신하지 않으므로 hot cwd가 자주 invalidate되면
+    // 영원히 oldest로 남는다. delete + set으로 강제 reorder.
+    cachedIndexes.delete(sig);
+    const fresh = buildIndex(dirs);
+    cachedIndexes.set(sig, fresh);
+    // Evict oldest until size within cap
+    while (cachedIndexes.size > MAX_CACHE_ENTRIES) {
+        const oldestKey = cachedIndexes.keys().next().value;
+        if (oldestKey === undefined)
+            break;
+        cachedIndexes.delete(oldestKey);
+    }
+    return fresh;
+}
+export function resetIndexCache() {
+    cachedIndexes.clear();
+}

package/dist/engine/solution-matcher.d.ts

@@ -0,0 +1,364 @@
+import type { ScopeInfo } from '../core/types.js';
+import type { SolutionStatus, SolutionType } from './solution-format.js';
+/**
+ * @deprecated Use `defaultNormalizer.normalizeTerms` from
+ * `./term-normalizer.js` directly. Kept as a thin wrapper for the existing
+ * `synonym-tfidf.test.ts` and any external consumers.
+ */
+export declare function expandTagsWithSynonyms(tags: string[]): string[];
+/** Apply IDF-like weight: common tags get reduced weight */
+export declare function tagWeight(tag: string): number;
+export interface SolutionMatch {
+    name: string;
+    path: string;
+    scope: 'me' | 'team' | 'project';
+    relevance: number;
+    summary: string;
+    status: SolutionStatus;
+    confidence: number;
+    type: SolutionType;
+    tags: string[];
+    identifiers: string[];
+    matchedTags: string[];
+}
+/**
+ * Optional hints for the v3 `calculateRelevance` path. Used by hot-path
+ * callers (matchSolutions, searchSolutions) to avoid re-normalizing the
+ * same query tags on every solution.
+ */
+export interface CalculateRelevanceOptions {
+    /**
+     * Pre-normalized prompt tags (produced by `defaultNormalizer.normalizeTerms`).
+     * If provided, skips the per-call expansion. Callers loop-running against
+     * many solutions should compute this once outside the loop and pass it in.
+     */
+    normalizedPromptTags?: string[];
+    /**
+     * R4-T1: solution tags expanded with compound-split alternatives
+     * (`expandCompoundTags`). When supplied, the intersection/partial-match
+     * step uses this set INSTEAD of `solutionTags`, but the Jaccard union
+     * denominator still uses `solutionTags` (raw) so the score normalization
+     * stays semantically stable. Caller responsibility to pass the matching
+     * pair — `solutionTagsExpanded` MUST be a superset of `solutionTags`.
+     */
+    solutionTagsExpanded?: string[];
+}
+export declare function calculateRelevance(promptTags: string[], solutionTags: string[], confidence: number, options?: CalculateRelevanceOptions): {
+    relevance: number;
+    matchedTags: string[];
+};
+/** @deprecated */
+export declare function calculateRelevance(prompt: string, keywords: string[]): number;
+export declare function shouldRejectByR4T3Rules(promptTags: readonly string[], matchedTags: readonly string[]): boolean;
+/**
+ * In-memory solution shape for the bootstrap evaluator. Mirrors the index
+ * entry fields that `matchSolutions` consumes (tags, identifiers, confidence)
+ * but without any filesystem dependency — the evaluator is pure so CI can run
+ * it without mounting a starter pack.
+ */
+export interface EvalSolution {
+    name: string;
+    tags: string[];
+    identifiers?: string[];
+    confidence: number;
+}
+export interface EvalQuery {
+    query: string;
+    /** Names that should appear in the top-5. Empty array = expect no match (negative case). */
+    expectAnyOf: string[];
+}
+export interface EvalFixture {
+    solutions: EvalSolution[];
+    positive: EvalQuery[];
+    /** Bilingual or compound-word variants that exercise synonym expansion. */
+    paraphrase: EvalQuery[];
+    /** Unrelated queries that should not return a top-1 hit. */
+    negative: EvalQuery[];
+}
+/** Per-bucket metrics. Paraphrase and positive are reported separately so a
+ *  bilingual regression (T2 synonym change) can't hide inside the aggregate. */
+export interface BucketMetrics {
+    /** |{q : ∃i≤5, ranked[i] ∈ q.expectAnyOf}| / |q| */
+    recallAt5: number;
+    /** Σ (1 / firstMatchRank) / |q|; rank > 5 contributes 0. */
+    mrrAt5: number;
+    /** |{q : ranked is empty}| / |q| */
+    noResultRate: number;
+    /** Number of queries in this bucket. */
+    total: number;
+}
+export interface EvalResult {
+    /** Combined (positive ∪ paraphrase) metrics — backwards-compatible headline numbers. */
+    recallAt5: number;
+    mrrAt5: number;
+    noResultRate: number;
+    /**
+     * Fraction of negative queries where the matcher returned ≥ 1 candidate
+     * (regardless of rank). Name is honest: this is the "any result" rate on
+     * the negative bucket, not a rank-1 precision metric. It's the correct
+     * baseline for "did synonym/stemming leak into unrelated queries?".
+     */
+    negativeAnyResultRate: number;
+    /** Per-bucket breakdown — use these to catch paraphrase-only regressions. */
+    byBucket: {
+        positive: BucketMetrics;
+        paraphrase: BucketMetrics;
+    };
+    total: {
+        positive: number;
+        paraphrase: number;
+        negative: number;
+    };
+}
+/**
+ * Round 3 baseline metrics, recorded against the current `term-normalizer`
+ * + `calculateRelevance` + fixture `solution-match-bootstrap.json`. Used as
+ * a relative regression guard in `tests/solution-matcher-eval.test.ts` —
+ * downstream PRs must not regress any field by more than `BASELINE_TOLERANCE`.
+ *
+ * History (chronological ascending — v1 at top, latest at bottom):
+ *   - v1 (2026-04-08, fixture v1, 41+10+10 queries): 1.0 / 1.0 / 0.0 / 0.1
+ *     Recorded against the original 61-query fixture, all positive queries
+ *     PASS@1. Indicated a measurement plateau but masked the matcher's true
+ *     ranking and false-positive weaknesses because the fixture queries were
+ *     too tag-aligned.
+ *
+ *   - v2 (2026-04-08, fixture v2, 53+16+14 queries): 1.0 / 0.969 / 0.0 / 0.357
+ *     Expanded with 12 hard positive (multi-canonical / compound-tag tug-of-
+ *     war), 6 Korean subtle paraphrase, and 4 tricky negative queries. The
+ *     drops are intentional and represent genuine matcher behaviour:
+ *       * positive mrrAt5 1.0 → 0.959: 4 of 12 added positives rank #2-3:
+ *         (1) "managing api keys and credentials safely" → secret @3 vs
+ *             api-error-responses @1 — the `api` canonical in
+ *             DEFAULT_MATCH_TERMS expands to {api, rest, graphql, endpoint,
+ *             route}, so query `api` hits BOTH `api` AND `rest` on
+ *             starter-api-error-responses (matched=['api','rest']) — a
+ *             double-count numerator. starter-secret-management only scores
+ *             a single weak partial match on `credential`. The compound
+ *             `api-key` tag on secret-management is never reached because
+ *             extractTags strips the query-side hyphen and yields
+ *             ['api','keys'] (the solution-side tag remains hyphenated in
+ *             the index but has no query token to intersect with). T4 IDF
+ *             would down-weight both `api` and `rest`, neutralising the
+ *             double-count and letting `credential` outscore the noise.
+ *         (2) "avoiding hardcoded credentials in source code" → secret @2
+ *             vs code-review @1 — `code` partial-matches `code-review`
+ *             (len>3, code-review.includes('code')=true) at half weight.
+ *             secret-management's `credential` matches by partial too but
+ *             the union size differs.
+ *         (3) "red green refactor cycle for new features" → tdd @2 vs
+ *             refactor-safely @1 — `refactor` is a full-weight intersection
+ *             with both refactor-safely's `refactor` and `리팩토링` (via
+ *             the refactor canonical), giving 2 hits at 1.0 each. tdd-red-
+ *             green-refactor only matches the literal compound tag
+ *             `red-green-refactor` (one weighted hit) — the full-weight
+ *             generic `refactor` term overpowers the compound-tag specifity.
+ *         (4) "writing unit tests for a function with side effects" → tdd
+ *             @2 vs separation-of-concerns @1 — both solutions have a
+ *             SINGLE matching tag with weighted score 0.5: separation gets
+ *             `function` (COMMON_TAG, exact intersection, weight 0.5);
+ *             tdd-red-green-refactor gets `tests` partial-matching `test`
+ *             (len>3, partial weight 1.0 × 0.5 = 0.5). Both numerators are
+ *             identical. Separation wins because the `function` co-occurs
+ *             in both promptTags and solution.tags, shrinking its Jaccard
+ *             union by one element vs tdd's — a 1-element union-size
+ *             advantage drives the entire ranking. starter-dependency-
+ *             injection is *not* in top-5 despite having `testing`/`mock`/
+ *             `dependency` tags (`tests` does not partial-match `testing`
+ *             — neither is a substring of the other), so listing `di` in
+ *             expectAnyOf is purely defensive recall, not a live candidate.
+ *             T4 BM25 with proper length normalization would attack the
+ *             union-size tie-breaker more rigorously than current Jaccard.
+ *       * paraphrase mrrAt5 stays at 1.0: all 6 added Korean paraphrases
+ *         rank @1 (the originally hard "테스트 먼저 작성하고 리팩토링" is
+ *         documented in the fixture as legitimately matching either tdd
+ *         OR refactor-safely, since starter-refactor-safely's README also
+ *         covers test-first workflows — both are defensible answers).
+ *       * negativeAnyResultRate 0.1 → 0.357: 4 added tricky negatives all
+ *         trigger false positives via single common dev-adjacent words —
+ *         "performance review meeting notes" → caching (matches
+ *         `performance`), "system architecture overview document" →
+ *         separation-of-concerns (matches `architecture`), "database backup
+ *         recovery procedure" → n-plus-one-queries (matches `database`,
+ *         `query`, `데이터베이스`), "validation of insurance claims" →
+ *         error-handling (matches `validation`).
+ *     The original Round 3 plan staged these for T4 (BM25 + IDF). T4 was
+ *     EMPIRICALLY SKIPPED on 2026-04-08 — see
+ *     `docs/plans/2026-04-08-t4-bm25-skip-adr.md` for the full decision
+ *     record. Summary: BM25 prototypes (naive, hybrid Jaccard×IDF,
+ *     precision filter, soft penalty) all matched or underperformed the
+ *     current scorer on every metric. The starter corpus (N=15) is too
+ *     small for IDF to be informative, and the false positives are
+ *     semantic ("performance" is both a dev tag and an English noun) — not
+ *     statistical, so no frequency-based weighting can fix them. The real
+ *     follow-up candidates are tokenizer fix for compound tags, an n-gram
+ *     phrase matcher, and corpus growth — all deferred to Round 4 per the
+ *     ADR.
+ *
+ *   - v3 (2026-04-08, fixture v2 + R4-T1 compound-tag fix): 1.0 / 0.986 / 0.0 / 0.357
+ *     R4-T1 added `expandCompoundTags` (solution-side) and
+ *     `expandQueryBigrams` (query-side) so hyphenated solution tags like
+ *     `api-key`, `code-review`, `red-green-refactor` participate in direct
+ *     intersection rather than relying on the half-weight partialMatches
+ *     fallback. positive `mrrAt5` improved 0.959 → 0.981 (+0.022). 2 of
+ *     the 4 v2 hard positive cases were resolved (`managing api keys and
+ *     credentials safely` and `red green refactor cycle for new features`
+ *     now rank @1). The remaining 2 (`avoiding hardcoded credentials …`
+ *     and `writing unit tests for a function with side effects`) require
+ *     R4-T2 (phrase matcher) or R4-T3 (specificity classifier) — they're
+ *     about query-side English semantics, not compound-tag tokenization.
+ *     `negativeAnyResultRate` is unchanged at 0.357 because R4-T1 is a
+ *     ranking-quality fix, not a false-positive filter.
+ *
+ *   - v4 (2026-04-08, fixture v2 + R4-T1 + R4-T2 phrase blocklist):
+ *     1.0 / 0.986 / 0.0 / 0.143
+ *     R4-T2 added `phrase-blocklist.ts` with 17 curated 2-word English
+ *     non-dev compounds ("performance review", "system architecture",
+ *     "database backup", etc.) and a `maskBlockedTokens` step at the
+ *     top of `rankCandidates` and `searchSolutions`. When a query
+ *     contains a blocked phrase, the constituent tokens are removed
+ *     from the prompt tag list before bigram expansion / canonical
+ *     normalization runs — so the false-positive evidence is removed
+ *     at the source rather than demoted in scoring.
+ *
+ *     `negativeAnyResultRate` dropped 0.357 → 0.143 (3 of 5 v2 trigger
+ *     negatives fully blocked):
+ *       * "performance review meeting notes" — blocked via
+ *         `performance review` + `meeting notes`
+ *       * "system architecture overview document" — blocked via
+ *         `system architecture` + `overview document`
+ *       * "solar system planets astronomy" — blocked via `solar system`
+ *
+ *     2 false positives remain (both deferred to R4-T3 query-side
+ *     specificity classifier — the residuals share a common shape:
+ *     a single dev-tag homograph survives whatever masking is applied,
+ *     and the term-normalizer expansion still surfaces a false match):
+ *
+ *       * "database backup recovery procedure" → error-handling-patterns:
+ *         `database backup` is blocked, but the residual tokens
+ *         {`recovery`, `procedure`} survive. `recovery` is in the
+ *         `handling` canonical's matchTerms (intentional, for legitimate
+ *         "error recovery handler" queries), so the masked query still
+ *         hits `starter-error-handling-patterns` via the handling
+ *         family. A 3-word `recovery procedure` blocklist entry was
+ *         considered and rejected — it would silently mask legitimate
+ *         dev SRE queries like "disaster recovery procedure" or
+ *         "rollback recovery procedure" without a fixture-driven
+ *         signal. The right fix is at the query-specificity layer
+ *         (R4-T3): require ≥ 2 distinct dev-context signals before any
+ *         match is returned, not at the phrase-blocklist layer.
+ *
+ *       * "validation of insurance claims" → error-handling-patterns:
+ *         `insurance claim` is blocked, but the residual `validation`
+ *         token IS a legitimate dev tag (input-validation,
+ *         error-handling-patterns both have it). Same R4-T3 target.
+ *
+ *     positive/paraphrase mrrAt5 are unchanged from v3 because no
+ *     legitimate dev query in the fixture contains a blocked phrase.
+ *
+ *   - v5 (2026-04-08, fixture v2 + R4-T1 + R4-T2 + R4-T3 specificity guards):
+ *     1.0 / 0.986 / 0.0 / 0.000
+ *     R4-T3 added two narrow precision rules at the ORCHESTRATION LAYER —
+ *     NOT inside `calculateRelevance` (which remains a pure scoring
+ *     function for test symmetry). The rules are implemented as the
+ *     exported helper `shouldRejectByR4T3Rules(promptTags, matchedTags)`
+ *     and called from both `rankCandidates` (hook path) and
+ *     `searchSolutions` (MCP path) right after the per-solution
+ *     `calculateRelevance` call:
+ *       (Rule A) single-token query AND single-tag match → reject;
+ *       (Rule B) single-tag match with no literal hit in the prompt
+ *                (verbatim match, or substring partial length > 3, or
+ *                shared prefix ≥ 4 for morphological stems) → reject.
+ *     Both rules are scoped narrowly enough to fix exactly the 2 R4-T2
+ *     residuals without recall regression — every fixture positive and
+ *     paraphrase still ranks identically:
+ *       * "validation of insurance claims" → masked to `[validation]`
+ *         (length 1) with single-tag match `validation` → Rule A reject.
+ *       * "database backup recovery procedure" → masked to
+ *         `[recovery, procedure]` with single-tag match `handling`
+ *         (zero literal hit; `handling` is reached via the `recovery`
+ *         canonical-family expansion in term-normalizer) → Rule B reject.
+ *     `negativeAnyResultRate` is now 0.000 — every fixture v2 negative
+ *     produces zero candidates. positive/paraphrase metrics unchanged
+ *     from v4 because no fixture positive matches the (single-token AND
+ *     single-tag) or (all-expansion AND single-tag) shape.
+ *
+ *     Escape hatch: identifier-boost evidence (hook path) or name-match
+ *     evidence (MCP path) BYPASSES the R4-T3 rules. A candidate with
+ *     even a single weak tag match plus an identifier hit still
+ *     surfaces — the precision rules only fire when the candidate's
+ *     entire evidence pool is a single ambiguous tag.
+ *
+ *     Defensive precision note: Rule B's "shared prefix ≥ 4"
+ *     morphological check is currently NOT fixture-driven (no fixture
+ *     query masks down to the `caching/cache`-style morphological gap).
+ *     It exists as a pre-emptive fix against silently rejecting
+ *     legitimate future queries where the term-normalizer synonym
+ *     expansion is the only bridge between the query token and the
+ *     solution tag. If a production query surfaces a case the prefix
+ *     check misses, extend it (e.g. by lowering the threshold or
+ *     adding a Levenshtein-1 check) rather than removing it.
+ *
+ * Known matcher quirks (separate from the T4 BM25 investigation):
+ *   - `term-normalizer.ts` `error` canonical contains `debug` as a matchTerm
+ *     (intentional for `bug → error` recall), which causes any prompt
+ *     containing `error` to expand to `debug` and over-rank
+ *     `starter-debugging-systematic` on otherwise unrelated queries. This
+ *     is why `async await error propagation` could not be added as a hard
+ *     case — the matcher returns debugging-systematic at #1, which is
+ *     defensible-but-noisy. The fix is at the normalizer level (split
+ *     `debug` out of the `error` family or remove the `error → debug`
+ *     edge entirely) and is queued as a Round 4 follow-up. T4 BM25 was
+ *     considered as a partial mitigation but the T4 skip ADR (referenced
+ *     in the Round 3 outcome paragraph above) shows it does not help.
+ *
+ * Long-tail caveat:
+ *   - `"trying to handle authentication errors gracefully when our backend
+ *     api returns inconsistent response formats from different
+ *     microservices"` is a 17-word query intentionally added to exercise
+ *     long-tail behaviour. Currently PASS@1. Originally flagged as BM25
+ *     length-normalization sensitive, but since T4 BM25 was skipped this
+ *     caveat is now informational only — no length-norm code path is
+ *     planned in Round 3.
+ *
+ * If a PR legitimately improves a metric, update this constant in the same
+ * commit so future PRs guard against the new floor.
+ */
+export declare const ROUND3_BASELINE: EvalResult;
+/** Maximum allowed absolute regression per metric. 5% is tight enough to catch
+ *  ~3-4 query regressions in a 69-query combined bucket (positive+paraphrase)
+ *  but lenient enough that a single fixture edit won't spuriously fail the
+ *  guard. */
+export declare const BASELINE_TOLERANCE = 0.05;
+/**
+ * Test/diagnostic helper: evaluate one query against a fixture solution set
+ * and return the top-5 ranked candidates with their relevance + matched tags.
+ *
+ * Exists so per-query regression tests (e.g. the R4-T1 hard-positive guards
+ * in `tests/solution-matcher-eval.test.ts`) can assert specific ranking
+ * outcomes without scraping aggregate metrics. Wraps `rankCandidates` so
+ * the test path stays in sync with the production ranker.
+ *
+ * Returns the same shape as `rankCandidates` minus the generic carrier:
+ * `{name, relevance, matchedTags}`. Use the names to assert "expected
+ * solution at rank 1".
+ */
+export declare function evaluateQuery(query: string, solutions: readonly EvalSolution[]): Array<{
+    name: string;
+    relevance: number;
+    matchedTags: string[];
+}>;
+/**
+ * Evaluate the current matcher against a labeled fixture and return IR
+ * metrics. This is the Round 3 baseline — each downstream PR (T2/T3/T4) must
+ * not regress any of the thresholds asserted in `solution-matcher-eval.test.ts`.
+ *
+ * Uses `rankCandidates` (shared with `matchSolutions`) so the evaluator can't
+ * silently drift from production ranking behaviour.
+ *
+ * Metrics are reported both aggregated (positive ∪ paraphrase) and per-bucket,
+ * so paraphrase-only regressions surface in `byBucket.paraphrase` even if the
+ * aggregate looks fine.
+ */
+export declare function evaluateSolutionMatcher(fixture: EvalFixture): EvalResult;
+export declare function matchSolutions(prompt: string, scope: ScopeInfo, cwd: string): SolutionMatch[];