moflo 4.12.11 → 4.13.0

package/dist/src/cli/memory/learnings-audit.js

@@ -0,0 +1,420 @@
+/**
+ * Curation pass over the `learnings` namespace (#1466).
+ *
+ * `flo memory cleanup` purges by age, which is the wrong instrument for durable
+ * rows — a three-year-old lesson about a footgun that still exists is worth more
+ * than last week's note about a migration that finished. #1464 made that
+ * explicit by exempting durable namespaces from age-based cleanup, which left
+ * `learnings` with no evaluation surface at all: a consumer store reached 1,582
+ * entries with no way to tell which of them were still true.
+ *
+ * The shape that makes this affordable at that size is **mechanical filters
+ * first, model judgement last**. The filters here do not decide anything — they
+ * nominate. Four cheap passes (near-duplicate clustering over the embeddings
+ * already stored on the row, least-used-and-old ranking, retired-vocabulary
+ * matching, and dead-path resolution) narrow ~1,500 entries to a few dozen, and
+ * only those go to a model. A full-store LLM sweep is the design this exists to
+ * avoid.
+ *
+ * The dead-path pass (#1479) is the only one grounded in ground truth rather
+ * than prose shape — a repo-relative path either resolves in the tree or it does
+ * not. It is carved into `memory/learnings-dead-paths.ts` and re-exported from
+ * here; its filesystem half is `memory/learnings-tree.ts`.
+ *
+ * This module is pure by construction: no filesystem, no database, no spawning.
+ * Rows come in, a plan comes out. The command layer
+ * (`commands/memory-audit-learnings.ts`) owns every side effect, which is what
+ * makes the ranking and clustering testable without a store.
+ *
+ * @module memory/learnings-audit
+ */
+// The dead-path pass lives in its own module so this one stays the place the
+// passes are ASSEMBLED. Re-exported here because `learnings-audit.js` is the
+// audit's public surface — a caller configuring the pass should not have to
+// know which file the detector was carved into.
+import { findDeadPaths } from './learnings-dead-paths.js';
+export { DEFAULT_DEAD_PATHS_PER_ENTRY, extractCandidatePaths, findDeadPaths, resolvesInTree, } from './learnings-dead-paths.js';
+/** The namespace this audit is scoped to. */
+export const LEARNINGS_NAMESPACE = 'learnings';
+export const AUDIT_VERDICTS = ['KEEP', 'RETIRE', 'COMPRESS', 'MERGE'];
+/**
+ * Retired vocabulary. **Ships empty, and a guard test keeps it that way.**
+ *
+ * A rename is always local to one project: the consumer that renamed `foo` to
+ * `bar` is the only project where an entry saying `foo` is stale, and shipping
+ * their row would flag innocent entries in every other consumer's store — while
+ * also publishing that consumer's internal vocabulary to everyone who installs
+ * moflo (Rule #3). The row shape is documented rather than demonstrated for the
+ * same reason.
+ *
+ * A project that wants entries flagged fills this in downstream:
+ *
+ *     { from: 'old-term', to: 'new-term', note: 'renamed in <their ticket>' }
+ */
+export const SUPERSEDED_VOCABULARY = [];
+export const DEFAULT_DUPLICATE_THRESHOLD = 0.9;
+export const DEFAULT_UNUSED_MIN_AGE_MS = 90 * 24 * 60 * 60 * 1000;
+export const DEFAULT_UNUSED_LIMIT = 25;
+export const DEFAULT_JUDGE_LIMIT = 60;
+/**
+ * Group near-duplicate rows, returning the non-representative members.
+ *
+ * Greedy single-pass clustering: rows are walked newest-first, so the entry that
+ * survives a cluster is the most recently updated statement of the rule and the
+ * older restatements are the ones nominated. That ordering is the whole point —
+ * a duplicate pass that kept an arbitrary member would sometimes retire the
+ * corrected version and keep the one it replaced.
+ *
+ * Pass the FULL row set, not a filtered one: representatives are chosen from
+ * whatever is handed in, so clustering over a subset can promote an older
+ * restatement to representative and nominate the newer entry instead — exactly
+ * the inversion the newest-first sort exists to prevent. `buildAuditPlan`
+ * therefore clusters over every row and filters the nominations afterwards.
+ *
+ * O(n²) in rows that carry a vector. At the ~1,500 entries this exists for that
+ * is roughly a million comparisons — well under a second, and it costs no
+ * embedding calls at all, which is the trade the ticket asks for. Vectors are
+ * normalised once up front rather than through `cosineSim`, which would
+ * recompute both magnitudes on every one of those comparisons.
+ */
+export function findDuplicates(rows, threshold = DEFAULT_DUPLICATE_THRESHOLD) {
+    const embedded = rows
+        .filter((r) => Array.isArray(r.embedding) && r.embedding.length > 0)
+        .sort((a, b) => b.updatedAt - a.updatedAt)
+        .map((row) => {
+        let sumSquares = 0;
+        for (const component of row.embedding)
+            sumSquares += component * component;
+        const magnitude = Math.sqrt(sumSquares);
+        // A zero vector has no direction, so it can neither match nor be matched.
+        // `unit: null` keeps it in the walk without ever passing the threshold.
+        const unit = magnitude === 0 ? null : row.embedding.map((component) => component / magnitude);
+        return { row, unit };
+    });
+    const claimed = new Set();
+    const found = [];
+    for (let i = 0; i < embedded.length; i++) {
+        const representative = embedded[i];
+        if (!representative.unit || claimed.has(representative.row.key))
+            continue;
+        for (let j = i + 1; j < embedded.length; j++) {
+            const other = embedded[j];
+            if (!other.unit || claimed.has(other.row.key))
+                continue;
+            // Both vectors are unit length, so the dot product IS the cosine.
+            const length = Math.min(representative.unit.length, other.unit.length);
+            let similarity = 0;
+            for (let k = 0; k < length; k++)
+                similarity += representative.unit[k] * other.unit[k];
+            if (similarity < threshold)
+                continue;
+            // Claim the member, not the representative: a representative that stayed
+            // claimable could be absorbed into a later cluster and nominated itself,
+            // which would leave the rule with no surviving statement at all.
+            claimed.add(other.row.key);
+            found.push({ row: other.row, duplicateOf: representative.row.key, similarity });
+        }
+    }
+    return found;
+}
+/**
+ * Rank never-used entries older than `minAgeMs`, least-recently-updated first,
+ * and return the top `limit`.
+ *
+ * Nomination only. Zero recorded usage is weak evidence — usage recording is
+ * newer than most of the rows it is being read against — which is exactly why
+ * this feeds a model rather than a DELETE.
+ */
+export function findUnused(rows, options) {
+    const minAgeMs = options.minAgeMs ?? DEFAULT_UNUSED_MIN_AGE_MS;
+    const limit = options.limit ?? DEFAULT_UNUSED_LIMIT;
+    const cutoff = options.now - minAgeMs;
+    return rows
+        .filter((r) => r.accessCount <= 0 && r.updatedAt <= cutoff)
+        .sort((a, b) => a.updatedAt - b.updatedAt)
+        .slice(0, Math.max(0, limit));
+}
+/** Escape a vocabulary term for use inside a RegExp. */
+function escapeRegExp(term) {
+    return term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Find entries still using retired vocabulary.
+ *
+ * Matched on word boundaries so a retired `db` does not fire on `dbPath`, and
+ * case-insensitively so a rename survives the entry's own capitalisation. With
+ * the shipped table empty this returns nothing, which is the intended default.
+ */
+export function findSuperseded(rows, vocabulary = SUPERSEDED_VOCABULARY) {
+    if (vocabulary.length === 0)
+        return [];
+    const matchers = vocabulary.map((term) => ({
+        term,
+        re: new RegExp(`\\b${escapeRegExp(term.from)}\\b`, 'i'),
+    }));
+    const found = [];
+    for (const row of rows) {
+        const terms = matchers.filter((m) => m.re.test(row.content)).map((m) => m.term);
+        if (terms.length > 0)
+            found.push({ row, terms });
+    }
+    return found;
+}
+/**
+ * Run the mechanical passes and assemble the candidate set.
+ *
+ * Entries with a recorded verdict whose content has not changed since are
+ * dropped before any pass runs — that is what makes a second run immediately
+ * after `--apply` report nothing (the audit is idempotent), and it is also why
+ * the hash is part of the record: a rewritten entry is a new claim and gets
+ * judged again.
+ */
+export function buildAuditPlan(rows, options = {}) {
+    const now = options.now ?? Date.now();
+    const decided = options.decided ?? new Map();
+    const hash = options.hashContent;
+    const judgeLimit = options.judgeLimit ?? DEFAULT_JUDGE_LIMIT;
+    const pending = [];
+    let alreadyDecided = 0;
+    for (const row of rows) {
+        const record = decided.get(row.key);
+        // No hash function means we cannot tell a rewrite from the entry we judged;
+        // re-judging is the safe side of that, so the record is ignored.
+        if (record && hash && record.hash === hash(row.content)) {
+            alreadyDecided++;
+            continue;
+        }
+        pending.push(row);
+    }
+    const byKey = new Map();
+    const nominate = (row, bucket) => {
+        let candidate = byKey.get(row.key);
+        if (!candidate) {
+            candidate = {
+                key: row.key,
+                id: row.id,
+                content: row.content,
+                createdAt: row.createdAt,
+                updatedAt: row.updatedAt,
+                accessCount: row.accessCount,
+                buckets: [],
+            };
+            byKey.set(row.key, candidate);
+        }
+        if (!candidate.buckets.includes(bucket))
+            candidate.buckets.push(bucket);
+        return candidate;
+    };
+    const pendingKeys = new Set(pending.map((r) => r.key));
+    // Cluster over EVERY row, then keep only the pending nominations. Clustering
+    // over `pending` alone would let a previously-kept newest entry drop out of
+    // the candidate pool and promote an older restatement to representative,
+    // nominating the newer entry instead.
+    const duplicates = findDuplicates(rows, options.duplicateThreshold)
+        .filter((hit) => pendingKeys.has(hit.row.key));
+    for (const hit of duplicates) {
+        const candidate = nominate(hit.row, 'duplicate');
+        candidate.duplicateOf = hit.duplicateOf;
+        candidate.similarity = hit.similarity;
+    }
+    const unusedMatched = findUnused(pending, {
+        now,
+        minAgeMs: options.unusedMinAgeMs,
+        limit: Number.POSITIVE_INFINITY,
+    });
+    const unused = unusedMatched.slice(0, Math.max(0, options.unusedLimit ?? DEFAULT_UNUSED_LIMIT));
+    for (const row of unused)
+        nominate(row, 'unused');
+    const superseded = findSuperseded(pending, options.vocabulary);
+    for (const hit of superseded) {
+        const candidate = nominate(hit.row, 'superseded');
+        candidate.supersededTerms = hit.terms;
+    }
+    // Runs over `pending` rather than every row: unlike clustering, this pass
+    // reads one entry at a time and has no representative to protect, so a
+    // previously-judged entry contributes nothing to another entry's nomination.
+    const deadPaths = options.deadPaths ? findDeadPaths(pending, options.deadPaths) : [];
+    for (const hit of deadPaths) {
+        const candidate = nominate(hit.row, 'dead-path');
+        candidate.deadPaths = hit.deadPaths;
+    }
+    const counts = {
+        duplicate: duplicates.length,
+        unused: unused.length,
+        superseded: superseded.length,
+        deadPath: deadPaths.length,
+    };
+    // Most-nominated first, then oldest — an entry three passes agree on is the
+    // one a bounded prompt should spend its budget on.
+    const ranked = [...byKey.values()].sort((a, b) => b.buckets.length - a.buckets.length || a.updatedAt - b.updatedAt);
+    const candidates = ranked.slice(0, Math.max(0, judgeLimit));
+    return {
+        examined: rows.length,
+        alreadyDecided,
+        // Counted over every examined row, matching `examined`'s denominator.
+        withoutEmbedding: rows.filter((r) => !r.embedding || r.embedding.length === 0).length,
+        counts,
+        unusedCoverage: { matched: unusedMatched.length, nominated: unused.length },
+        candidates,
+        overflow: ranked.length - candidates.length,
+    };
+}
+/** Per-candidate body cap in the judge prompt — bounds cost, keeps the claim readable. */
+export const JUDGE_CONTENT_CAP = 400;
+function describeBuckets(candidate) {
+    const parts = [];
+    for (const bucket of candidate.buckets) {
+        if (bucket === 'duplicate') {
+            parts.push(`near-duplicate of "${candidate.duplicateOf}" (similarity ${(candidate.similarity ?? 0).toFixed(3)})`);
+        }
+        else if (bucket === 'unused') {
+            parts.push('never returned by a search since usage recording began');
+        }
+        else if (bucket === 'dead-path') {
+            parts.push(`cites path(s) that resolve nowhere in the tree: ${(candidate.deadPaths ?? []).join(', ')}`);
+        }
+        else {
+            const terms = (candidate.supersededTerms ?? [])
+                .map((t) => `"${t.from}" → "${t.to}"`)
+                .join(', ');
+            parts.push(`uses retired vocabulary: ${terms}`);
+        }
+    }
+    return parts.join('; ');
+}
+/**
+ * Build the judgement prompt for the nominated entries.
+ *
+ * The decision table is restated inline rather than referenced by path: the
+ * model answering this runs headless in a consumer's project, where
+ * `.claude/guidance/internal/memory-hygiene.md` does not exist.
+ */
+export function buildJudgePrompt(candidates, now = Date.now()) {
+    const dayMs = 24 * 60 * 60 * 1000;
+    const entries = candidates
+        .map((candidate, index) => {
+        const ageDays = Math.max(0, Math.round((now - candidate.createdAt) / dayMs));
+        const body = candidate.content.length > JUDGE_CONTENT_CAP
+            ? `${candidate.content.slice(0, JUDGE_CONTENT_CAP)}…`
+            : candidate.content;
+        return [
+            `### ${index + 1}. ${candidate.key}`,
+            `- flagged because: ${describeBuckets(candidate)}`,
+            `- age: ${ageDays} day(s); recorded uses: ${candidate.accessCount}`,
+            `- content: ${body.replace(/\s+/g, ' ').trim()}`,
+        ].join('\n');
+    })
+        .join('\n\n');
+    return [
+        'You are auditing durable engineering learnings stored in a project memory.',
+        'Each entry below was flagged by a mechanical filter. The filters nominate; you decide.',
+        '',
+        'Classify every entry into exactly one bucket:',
+        '',
+        '| Verdict | When to apply |',
+        '|---|---|',
+        '| KEEP | The entry still drives a decision someone might make today. |',
+        '| RETIRE | Resolved incident, completed migration, or a rule now enforced by a lint/test/CI gate. |',
+        '| COMPRESS | Load-bearing but verbose; the durable signal fits in 1-3 sentences. |',
+        '| MERGE | Restates another entry listed here; the two should become one. |',
+        '',
+        'Only RETIRE removes an entry. MERGE and COMPRESS are reported to a human to act on,',
+        'so use them when the content still needs to survive in some form somewhere.',
+        '',
+        'The test: "if this entry were removed today, would any future decision be wrong?"',
+        'If no — because the situation no longer arises, or a machine gate already prevents the',
+        'failure — it is RETIRE. When genuinely unsure, answer KEEP: a wrongly kept entry costs',
+        'a little search budget, a wrongly retired one costs the lesson.',
+        '',
+        'A near-duplicate flag is evidence, not a verdict: two entries can restate one rule',
+        '(MERGE) or cover genuinely different cases that merely read alike (KEEP).',
+        '',
+        'A dead-path flag is evidence with FOUR possible causes, and only reading the entry tells',
+        'them apart. Never read one as RETIRE on sight — the moved-file case is the common one:',
+        '',
+        '| Why the cited path does not resolve | Verdict |',
+        '|---|---|',
+        '| The file MOVED; the lesson still holds | COMPRESS — keep the rule, correct or drop the path |',
+        '| Deleted, and the lesson was about that code | RETIRE |',
+        '| Deleted, but the lesson generalises past it | COMPRESS — drop the path, keep the rule |',
+        '| The entry is a historical record, correct as written | KEEP |',
+        '',
+        `Answer with exactly ${candidates.length} line(s), nothing else. One line per entry:`,
+        '',
+        '<key><TAB><VERDICT><TAB><reason in under 15 words>',
+        '',
+        '---',
+        '',
+        entries,
+    ].join('\n');
+}
+/**
+ * Parse the model's verdict lines, keyed by entry key.
+ *
+ * Deliberately lenient about separators and surrounding prose — the cost of a
+ * strict parser here is discarding a whole batch of correct verdicts over a
+ * stray preamble. Keys not present in `expected` are ignored, so a hallucinated
+ * entry cannot cause an archive.
+ */
+export function parseVerdicts(text, expected) {
+    const known = new Set(expected);
+    const out = new Map();
+    for (const rawLine of String(text ?? '').split(/\r?\n/)) {
+        // Strip a list marker only — a bare `[-*\d.\s]+` class also eats the front
+        // of a key like `1466-lesson`, which then fails the `known` check and
+        // silently loses its verdict (and re-nominates on every future run).
+        const line = rawLine.trim().replace(/^(?:[-*+]|\d+[.)])\s+/, '');
+        if (!line)
+            continue;
+        const parts = line.split(/\t|\s*\|\s*|\s{2,}|\s+-\s+/).map((p) => p.trim()).filter(Boolean);
+        if (parts.length < 2)
+            continue;
+        const key = parts[0].replace(/^["'`]|["'`]$/g, '');
+        if (!known.has(key) || out.has(key))
+            continue;
+        const verdict = parts[1].toUpperCase().replace(/[^A-Z]/g, '');
+        if (!AUDIT_VERDICTS.includes(verdict))
+            continue;
+        out.set(key, { verdict, reason: parts.slice(2).join(' ') });
+    }
+    return out;
+}
+/**
+ * The entries `--apply` archives.
+ *
+ * **RETIRE only.** MERGE and COMPRESS both describe work that preserves content
+ * — fold this into that one, rewrite this shorter — and nothing here performs
+ * either. Archiving on those verdicts would delete the very signal the verdict
+ * said to keep, and MERGE is the more dangerous of the two: "restates another
+ * entry listed here" is a true statement about BOTH members of a pair, so a
+ * model answering MERGE twice would erase the rule entirely. They are reported
+ * for an author to act on instead.
+ *
+ * A cluster's representative is excluded even when it is itself nominated. The
+ * duplicate pass protects the newest statement of a rule from its own bucket,
+ * but `findUnused` and `findSuperseded` walk the same rows and can nominate that
+ * representative independently — and a RETIRE on it alongside RETIREs on its
+ * duplicates takes every statement of the rule at once.
+ */
+export function selectArchivable(candidates, verdicts) {
+    const survivors = new Set(candidates.map((candidate) => candidate.duplicateOf).filter((key) => Boolean(key)));
+    return candidates.filter((candidate) => {
+        if (survivors.has(candidate.key))
+            return false;
+        return verdicts.get(candidate.key)?.verdict === 'RETIRE';
+    });
+}
+/**
+ * Entries whose verdict asks for an author's hand rather than an archive —
+ * MERGE and COMPRESS. Reported so a verdict never silently evaporates.
+ */
+export function selectManualActions(candidates, verdicts) {
+    const out = [];
+    for (const candidate of candidates) {
+        const verdict = verdicts.get(candidate.key)?.verdict;
+        if (verdict === 'MERGE' || verdict === 'COMPRESS')
+            out.push({ candidate, verdict });
+    }
+    return out;
+}
+//# sourceMappingURL=learnings-audit.js.map

package/dist/src/cli/memory/learnings-dead-paths.js

@@ -0,0 +1,202 @@
+/**
+ * Dead-path nomination for the learnings audit (#1479).
+ *
+ * The audit's other three passes read prose shape — how similar two entries
+ * are, how long one has gone unused, whether it speaks a retired word. This one
+ * reads ground truth: a repo-relative path an entry cites either resolves in the
+ * tree or it does not. That also makes it the only pass that is portable across
+ * consumers — it resolves against the consumer's own tree and carries no
+ * project-specific data, unlike a vocabulary list.
+ *
+ * **It nominates, it never decides.** A dead path has four causes and only a
+ * reader can tell them apart. See {@link findDeadPaths}.
+ *
+ * Pure by construction, like `learnings-audit.ts`: resolution is injected as a
+ * predicate, so nothing here touches a disk. The filesystem half lives in
+ * `memory/learnings-tree.ts`.
+ *
+ * @module memory/learnings-dead-paths
+ */
+// Pure string composition, no disk: `path.posix.join` puts a workspace prefix in
+// front of a cited path. `posix` specifically, because the separator inside a
+// learning is whatever its author typed — `/` on every platform in practice — so
+// it is a wire format, not a host path. The host separator is applied once, at
+// the filesystem boundary in `memory/learnings-tree.ts`, with `path.join` (Rule #1).
+import { posix as posixPath } from 'path';
+/**
+ * How many unresolved paths are recorded per entry.
+ *
+ * Evidence, not an inventory: an entry citing thirty dead paths is nominated by
+ * the first few just as decisively, and the rest would only inflate the judge
+ * prompt this whole design exists to keep bounded.
+ */
+export const DEFAULT_DEAD_PATHS_PER_ENTRY = 5;
+/** A URL is not a tree path, and plenty of them end in `.json` or `.md`. */
+const URL_LIKE = /\S+:\/\/\S+/g;
+/** A glob is a pattern; there is nothing to look up. */
+const GLOB_LIKE = /\S*\*\S*/g;
+/**
+ * A path-shaped token: two or more segments joined by a separator.
+ *
+ * Group 1 pins the character BEFORE the token and rejects the ones that mean
+ * "not repo-relative" — a leading separator (`/tmp/x.log`), a home marker
+ * (`~/.claude/settings.json`), a drive colon (`C:\Users\x\y.ts`), or a longer
+ * path this token is merely the tail of. Backslashes are accepted on input and
+ * normalised away, because a learning written on Windows says `src\cli\x.ts`.
+ */
+const PATH_TOKEN = /(^|[^A-Za-z0-9._~@+\-/\\:])([A-Za-z0-9._~@+-]+(?:[/\\][A-Za-z0-9._~@+-]+)+[/\\]?)/g;
+/** Sentence punctuation that rides along on a path at the end of a clause. */
+const TRAILING_PUNCTUATION = /[.,;:!?)\]}'"`]+$/;
+/** A file extension, which is what separates `src/foo.ts` from `and/or`. */
+const FILE_EXTENSION = /\.[A-Za-z0-9]{1,10}$/;
+/**
+ * An environment variable standing in for a path root —
+ * `CLAUDE_PROJECT_DIR/.claude/helpers/gate.cjs`. The underscore is required, so
+ * an ordinary shouted directory (`API/v1.json`, `README/notes.md`) is untouched.
+ */
+const ENV_VAR_SEGMENT = /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/;
+/**
+ * Normalise one matched token, or reject it as unscoreable.
+ *
+ * Rejections are the load-bearing half. A detector whose output is mostly false
+ * positives gets ignored wholesale, so anything whose resolution would say
+ * something about the environment rather than about the entry is dropped here:
+ *
+ * - `node_modules/...` resolves or not depending on whether anyone has run an
+ *   install in this checkout. That is a fact about the checkout, not the entry.
+ * - An absolute, home-relative, or parent-relative path is not repo-relative,
+ *   so resolving it against the project root would be meaningless.
+ * - A bare filename (`package.json`) and an extensionless pair (`and/or`,
+ *   `KEEP/RETIRE`) are too ambiguous to score at all.
+ * - A path rooted at an environment variable resolves to wherever that variable
+ *   points, which is not this tree.
+ */
+function normalizeCandidate(raw) {
+    let candidate = raw.replace(TRAILING_PUNCTUATION, '').replace(/\\/g, '/');
+    if (candidate.startsWith('./'))
+        candidate = candidate.slice(2);
+    if (!candidate || candidate.startsWith('/') || candidate.startsWith('~') || candidate.startsWith('../')) {
+        return null;
+    }
+    if (candidate.includes('//'))
+        return null;
+    const lower = candidate.toLowerCase();
+    if (lower.startsWith('node_modules/') || lower.includes('/node_modules/'))
+        return null;
+    if (ENV_VAR_SEGMENT.test(candidate.split('/')[0]))
+        return null;
+    const isDirectory = candidate.endsWith('/');
+    const body = isDirectory ? candidate.slice(0, -1) : candidate;
+    if (!body.includes('/'))
+        return null;
+    if (!isDirectory && !FILE_EXTENSION.test(body))
+        return null;
+    return candidate;
+}
+/**
+ * Pull the repo-relative paths an entry cites, deduplicated, in first-seen
+ * order.
+ *
+ * Exported because it is where every false positive would come from: the rules
+ * above are only checkable by driving prose at them directly.
+ */
+export function extractCandidatePaths(content) {
+    // Blank URLs and globs out of the text BEFORE tokenising. Filtering them
+    // afterwards does not work — a URL's own path tail tokenises cleanly on its
+    // own and would survive as `docs/spec.md`.
+    const text = String(content ?? '').replace(URL_LIKE, ' ').replace(GLOB_LIKE, ' ');
+    const out = [];
+    const seen = new Set();
+    for (const match of text.matchAll(PATH_TOKEN)) {
+        const candidate = normalizeCandidate(match[2]);
+        if (!candidate || seen.has(candidate))
+            continue;
+        seen.add(candidate);
+        out.push(candidate);
+    }
+    return out;
+}
+/**
+ * Resolve a cited path as written, then under each workspace prefix.
+ *
+ * The second pass is what makes the detector usable rather than noise. A
+ * learning is authored from inside a workspace and routinely cites
+ * `src/routes/foo.ts` meaning `packages/api/src/routes/foo.ts`; without the
+ * retry every such citation reads as dead. The reference implementation this
+ * pass is ported from measured that single omission taking its findings from
+ * 103 entries to 261 — an auditor that is wrong more often than right gets
+ * ignored wholesale, which costs the other three buckets their audience too.
+ *
+ * A prefix the path already carries is skipped: retrying `packages/api/x.ts`
+ * under `packages/api` only ever asks about `packages/api/packages/api/x.ts`.
+ */
+export function resolvesInTree(relativePath, resolves, workspacePrefixes = []) {
+    return resolvesUnder(relativePath, resolves, normalizePrefixes(workspacePrefixes));
+}
+/**
+ * Put a prefix list into the one form {@link resolvesUnder} can compose with.
+ *
+ * Hoisted out of the resolution loop deliberately: the prefix list is the same
+ * for every candidate in the store, so normalising inside the loop would repeat
+ * this work once per candidate per prefix for no answer that changes.
+ */
+function normalizePrefixes(workspacePrefixes) {
+    const out = [];
+    for (const raw of workspacePrefixes) {
+        const prefix = raw.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '');
+        if (prefix)
+            out.push(prefix);
+    }
+    return out;
+}
+/** {@link resolvesInTree} over an already-normalised prefix list. */
+function resolvesUnder(relativePath, resolves, prefixes) {
+    if (resolves(relativePath))
+        return true;
+    for (const prefix of prefixes) {
+        if (relativePath === prefix || relativePath.startsWith(`${prefix}/`))
+            continue;
+        if (resolves(posixPath.join(prefix, relativePath)))
+            return true;
+    }
+    return false;
+}
+/**
+ * Nominate entries citing paths that resolve nowhere.
+ *
+ * **This nominates, it never decides.** A dead path has four causes and only a
+ * reader can tell them apart: the file moved and the lesson still holds, the
+ * file was deleted and the lesson was about that code, the file was deleted but
+ * the lesson generalises, or the entry is a historical record that is correct as
+ * written. The move case is the common one, which is why reading "dead path" as
+ * "retire" throws away lessons that are still entirely true. The verdict table
+ * goes to the model in {@link buildJudgePrompt}.
+ *
+ * Resolution is memoised across the whole store, not per entry: the same file is
+ * cited by many learnings, and every miss costs one lookup per workspace prefix.
+ */
+export function findDeadPaths(rows, options) {
+    const prefixes = normalizePrefixes(options.workspacePrefixes ?? []);
+    const maxPerEntry = Math.max(1, options.maxPathsPerEntry ?? DEFAULT_DEAD_PATHS_PER_ENTRY);
+    const resolved = new Map();
+    const found = [];
+    for (const row of rows) {
+        const deadPaths = [];
+        for (const candidate of extractCandidatePaths(row.content)) {
+            let alive = resolved.get(candidate);
+            if (alive === undefined) {
+                alive = resolvesUnder(candidate, options.resolves, prefixes);
+                resolved.set(candidate, alive);
+            }
+            if (alive)
+                continue;
+            deadPaths.push(candidate);
+            if (deadPaths.length >= maxPerEntry)
+                break;
+        }
+        if (deadPaths.length > 0)
+            found.push({ row, deadPaths });
+    }
+    return found;
+}
+//# sourceMappingURL=learnings-dead-paths.js.map