@northtek/overstory 0.1.0

package/dist/core/gate.js

@@ -0,0 +1,155 @@
+import { sha256 } from './hash.js';
+/** Builder-side helper: cite lines start..end (1-based, inclusive) of a file as it
+ * currently exists in the corpus. Throws if the file is absent — you cannot honestly
+ * cite what you cannot see. */
+export const makeSpan = (file, startLine, endLine, corpus) => {
+    const entry = corpus.files.get(file);
+    if (!entry)
+        throw new Error(`makeSpan: ${file} is not in the corpus`);
+    const last = Math.min(endLine, entry.lines.length);
+    const first = Math.max(1, Math.min(startLine, last));
+    const text = entry.lines.slice(first - 1, last).join('\n');
+    return { file, startLine: first, endLine: last, text, contentHash: sha256(text) };
+};
+/** Locate exact normalized text in a file at line granularity. Returns 1-based lines. */
+const findText = (lines, needle) => {
+    if (needle.length === 0)
+        return null;
+    const hay = lines.join('\n');
+    let from = 0;
+    for (;;) {
+        const idx = hay.indexOf(needle, from);
+        if (idx === -1)
+            return null;
+        const startsOnBoundary = idx === 0 || hay[idx - 1] === '\n';
+        const end = idx + needle.length;
+        const endsOnBoundary = end === hay.length || hay[end] === '\n';
+        if (startsOnBoundary && endsOnBoundary) {
+            const startLine = hay.slice(0, idx).split('\n').length;
+            const endLine = startLine + needle.split('\n').length - 1;
+            return { startLine, endLine };
+        }
+        from = idx + 1;
+    }
+};
+/** Mechanical span verification against the live corpus. Assumes an internally
+ * consistent receipt (text/hash agreement is enforced upstream in verifyClaim).
+ * Self-heals when the cited text merely moved (edits above the span). */
+export const verifySpan = (span, corpus) => {
+    const file = corpus.files.get(span.file);
+    if (!file)
+        return { verdict: 'OUT_OF_CORPUS' };
+    const atRecorded = file.lines.slice(span.startLine - 1, span.endLine).join('\n');
+    if (sha256(atRecorded) === span.contentHash)
+        return { verdict: 'VERIFIED' };
+    // Healing anchors to the first byte-identical occurrence. When the text appears more
+    // than once, any occurrence is equally valid EVIDENCE (the receipt is the text itself,
+    // not its position), so first-match is deliberate, not an oversight.
+    const moved = findText(file.lines, span.text);
+    if (moved)
+        return { verdict: 'VERIFIED', healed: moved };
+    return { verdict: 'STALE' };
+};
+const SEVERITY = {
+    VERIFIED: 0,
+    STALE: 1,
+    OUT_OF_CORPUS: 2,
+    UNGROUNDED: 3,
+};
+const worse = (a, b) => (SEVERITY[a] >= SEVERITY[b] ? a : b);
+/** Fail-closed claim verification. A claim is VERIFIED only when every citation
+ * verifies. Any internally inconsistent receipt (text/hash mismatch — a forgery or
+ * corruption) voids the claim's grounding entirely: UNGROUNDED. Interior claims
+ * (citing child claims) verify transitively; staleness propagates upward.
+ *
+ * `path` holds only the claims on the CURRENT recursion path (backtracked on return):
+ * true cycles fail closed, while duplicate citations of the same evidence — a common
+ * LLM habit — and diamond-shaped grounding verify correctly. Duplicate refs within one
+ * claim are verified once (evidence is idempotent). */
+export const verifyClaim = (claim, tree, corpus, path = new Set()) => {
+    const spans = [];
+    if (claim.citations.length === 0)
+        return { claimId: claim.id, verdict: 'UNGROUNDED', spans };
+    let verdict = 'VERIFIED';
+    const refsVerified = new Set();
+    for (const citation of claim.citations) {
+        if (citation.kind === 'span') {
+            const { span } = citation;
+            if (span.text.length === 0 || sha256(span.text) !== span.contentHash) {
+                return { claimId: claim.id, verdict: 'UNGROUNDED', spans };
+            }
+            const result = verifySpan(span, corpus);
+            spans.push(result);
+            verdict = worse(verdict, result.verdict);
+        }
+        else {
+            const { nodeId, claimId } = citation.ref;
+            const key = `${nodeId}:${claimId}`;
+            if (refsVerified.has(key))
+                continue;
+            refsVerified.add(key);
+            const node = Object.hasOwn(tree.nodes, nodeId) ? tree.nodes[nodeId] : undefined;
+            const child = node?.claims.find((c) => c.id === claimId);
+            if (!child || path.has(key)) {
+                verdict = worse(verdict, 'OUT_OF_CORPUS');
+                continue;
+            }
+            path.add(key);
+            const childResult = verifyClaim(child, tree, corpus, path);
+            path.delete(key);
+            verdict = worse(verdict, childResult.verdict);
+        }
+    }
+    return { claimId: claim.id, verdict, spans };
+};
+/** Verify every claim in the tree. Freshness is the VERIFIED fraction (1.0 for an
+ * empty tree — nothing claimed, nothing wrong). */
+export const verifyTree = (tree, corpus) => {
+    const verdicts = new Map();
+    const details = new Map();
+    const byNode = new Map();
+    let verified = 0;
+    let total = 0;
+    for (const node of Object.values(tree.nodes)) {
+        const counts = { verified: 0, total: 0 };
+        for (const claim of node.claims) {
+            const result = verifyClaim(claim, tree, corpus);
+            verdicts.set(claim.id, result.verdict);
+            details.set(claim.id, result);
+            counts.total += 1;
+            total += 1;
+            if (result.verdict === 'VERIFIED') {
+                counts.verified += 1;
+                verified += 1;
+            }
+        }
+        byNode.set(node.id, counts);
+    }
+    return { verdicts, details, byNode, freshness: total === 0 ? 1 : verified / total };
+};
+/** Write verdicts + healed span positions back into a (copied) tree. Healing updates only
+ * line numbers — text and hash are untouched, so the receipt itself never changes. */
+export const applyVerification = (tree, verification) => {
+    const nodes = {};
+    for (const [id, node] of Object.entries(tree.nodes)) {
+        nodes[id] = {
+            ...node,
+            claims: node.claims.map((claim) => {
+                const result = verification.details.get(claim.id);
+                if (!result)
+                    return claim;
+                let spanIdx = 0;
+                const citations = claim.citations.map((citation) => {
+                    if (citation.kind !== 'span')
+                        return citation;
+                    const sv = result.spans[spanIdx++];
+                    if (!sv?.healed)
+                        return citation;
+                    return { ...citation, span: { ...citation.span, startLine: sv.healed.startLine, endLine: sv.healed.endLine } };
+                });
+                return { ...claim, citations, verdict: result.verdict };
+            }),
+        };
+    }
+    return { ...tree, nodes };
+};

package/dist/core/hash.d.ts

@@ -0,0 +1,7 @@
+/** Split on LF or CRLF; a single trailing empty line (from a final newline) is dropped. */
+export declare const splitLines: (text: string) => string[];
+/** Canonical text form: LF endings, per-line trailing whitespace stripped, indentation kept.
+ * All hashing runs over this form so CRLF checkouts and trailing-space edits never
+ * invalidate a receipt. */
+export declare const normalizeText: (text: string) => string;
+export declare const sha256: (text: string) => string;

package/dist/core/hash.js

@@ -0,0 +1,15 @@
+import { createHash } from 'node:crypto';
+/** Split on LF or CRLF; a single trailing empty line (from a final newline) is dropped. */
+export const splitLines = (text) => {
+    const lines = text.split(/\r?\n/);
+    if (lines.length > 1 && lines[lines.length - 1] === '')
+        lines.pop();
+    return lines;
+};
+/** Canonical text form: LF endings, per-line trailing whitespace stripped, indentation kept.
+ * All hashing runs over this form so CRLF checkouts and trailing-space edits never
+ * invalidate a receipt. */
+export const normalizeText = (text) => splitLines(text)
+    .map((line) => line.replace(/[ \t]+$/u, ''))
+    .join('\n');
+export const sha256 = (text) => createHash('sha256').update(text, 'utf8').digest('hex');

package/dist/core/store.d.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import type { Tree } from './types.js';
+export declare const treeSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    name: z.ZodString;
+    root: z.ZodString;
+    nodes: z.ZodRecord<z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            dir: "dir";
+            leaf: "leaf";
+            root: "root";
+        }>;
+        path: z.ZodString;
+        title: z.ZodString;
+        summary: z.ZodString;
+        claims: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            text: z.ZodString;
+            citations: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"span">;
+                span: z.ZodObject<{
+                    file: z.ZodString;
+                    startLine: z.ZodNumber;
+                    endLine: z.ZodNumber;
+                    contentHash: z.ZodString;
+                    text: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"claim">;
+                ref: z.ZodObject<{
+                    nodeId: z.ZodString;
+                    claimId: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>]>>;
+            verdict: z.ZodOptional<z.ZodEnum<{
+                OUT_OF_CORPUS: "OUT_OF_CORPUS";
+                STALE: "STALE";
+                UNGROUNDED: "UNGROUNDED";
+                VERIFIED: "VERIFIED";
+            }>>;
+            faithfulness: z.ZodOptional<z.ZodEnum<{
+                supported: "supported";
+                unchecked: "unchecked";
+                unsupported: "unsupported";
+            }>>;
+        }, z.core.$strip>>;
+        childIds: z.ZodArray<z.ZodString>;
+        sourceHash: z.ZodOptional<z.ZodString>;
+        builtWith: z.ZodEnum<{
+            extractive: "extractive";
+            llm: "llm";
+        }>;
+        provider: z.ZodOptional<z.ZodString>;
+        builtAt: z.ZodString;
+    }, z.core.$strip>>;
+    corpusFiles: z.ZodRecord<z.ZodString, z.ZodObject<{
+        hash: z.ZodString;
+        lines: z.ZodNumber;
+    }, z.core.$strip>>;
+    corpusOptions: z.ZodOptional<z.ZodObject<{
+        include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        maxFiles: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    builtAt: z.ZodString;
+    generator: z.ZodString;
+}, z.core.$strip>;
+export declare const treePath: (root: string) => string;
+export declare const partialPath: (root: string) => string;
+/** Atomic save: write temp then rename, so a killed build never corrupts the tree. */
+export declare const saveTree: (path: string, tree: Tree) => Promise<void>;
+/** Load + schema-validate. Returns null when missing or invalid (caller decides whether
+ * that means "build needed" — a corrupt tree is never trusted). */
+export declare const loadTree: (path: string) => Promise<Tree | null>;

package/dist/core/store.js

@@ -0,0 +1,66 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { z } from 'zod';
+const spanSchema = z.object({
+    file: z.string(),
+    startLine: z.number().int().min(1),
+    endLine: z.number().int().min(1),
+    contentHash: z.string(),
+    text: z.string(),
+});
+const citationSchema = z.union([
+    z.object({ kind: z.literal('span'), span: spanSchema }),
+    z.object({ kind: z.literal('claim'), ref: z.object({ nodeId: z.string(), claimId: z.string() }) }),
+]);
+const claimSchema = z.object({
+    id: z.string(),
+    text: z.string(),
+    citations: z.array(citationSchema),
+    verdict: z.enum(['VERIFIED', 'STALE', 'OUT_OF_CORPUS', 'UNGROUNDED']).optional(),
+    faithfulness: z.enum(['supported', 'unsupported', 'unchecked']).optional(),
+});
+const nodeSchema = z.object({
+    id: z.string(),
+    kind: z.enum(['leaf', 'dir', 'root']),
+    path: z.string(),
+    title: z.string(),
+    summary: z.string(),
+    claims: z.array(claimSchema),
+    childIds: z.array(z.string()),
+    sourceHash: z.string().optional(),
+    builtWith: z.enum(['llm', 'extractive']),
+    provider: z.string().optional(),
+    builtAt: z.string(),
+});
+export const treeSchema = z.object({
+    version: z.literal(1),
+    name: z.string(),
+    root: z.string(),
+    nodes: z.record(z.string(), nodeSchema),
+    corpusFiles: z.record(z.string(), z.object({ hash: z.string(), lines: z.number().int() })),
+    corpusOptions: z
+        .object({ include: z.array(z.string()).optional(), maxFiles: z.number().int().optional() })
+        .optional(),
+    builtAt: z.string(),
+    generator: z.string(),
+});
+export const treePath = (root) => join(root, '.overstory', 'tree.json');
+export const partialPath = (root) => join(root, '.overstory', 'tree.partial.json');
+/** Atomic save: write temp then rename, so a killed build never corrupts the tree. */
+export const saveTree = async (path, tree) => {
+    await mkdir(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    await writeFile(tmp, JSON.stringify(tree), 'utf8');
+    await rename(tmp, path);
+};
+/** Load + schema-validate. Returns null when missing or invalid (caller decides whether
+ * that means "build needed" — a corrupt tree is never trusted). */
+export const loadTree = async (path) => {
+    try {
+        const raw = await readFile(path, 'utf8');
+        return treeSchema.parse(JSON.parse(raw));
+    }
+    catch {
+        return null;
+    }
+};

package/dist/core/types.d.ts

@@ -0,0 +1,96 @@
+export type Verdict = 'VERIFIED' | 'STALE' | 'OUT_OF_CORPUS' | 'UNGROUNDED';
+/** A contiguous source span. Stores its normalized text so receipts stay
+ * renderable without the repo present and citations can self-heal when code moves. */
+export interface SpanRef {
+    file: string;
+    startLine: number;
+    endLine: number;
+    contentHash: string;
+    text: string;
+}
+export interface NodeClaimRef {
+    nodeId: string;
+    claimId: string;
+}
+export type Citation = {
+    kind: 'span';
+    span: SpanRef;
+} | {
+    kind: 'claim';
+    ref: NodeClaimRef;
+};
+/** Semantic disclosure tier, set at build time. `supported`: the Reflexion critique
+ * confirmed the cited lines support the claim text. `unsupported`: the critique flagged a
+ * mismatch. `unchecked`: no critique ran (budget-capped or provider failure) — honest
+ * default, never upgraded silently. Extractive claims are supported-by-construction. */
+export type Faithfulness = 'supported' | 'unsupported' | 'unchecked';
+export interface Claim {
+    id: string;
+    text: string;
+    citations: Citation[];
+    verdict?: Verdict;
+    faithfulness?: Faithfulness;
+}
+export interface TreeNode {
+    id: string;
+    kind: 'leaf' | 'dir' | 'root';
+    path: string;
+    title: string;
+    summary: string;
+    claims: Claim[];
+    childIds: string[];
+    sourceHash?: string;
+    builtWith: 'llm' | 'extractive';
+    provider?: string;
+    builtAt: string;
+}
+export interface CorpusFileMeta {
+    hash: string;
+    lines: number;
+}
+export interface Tree {
+    version: 1;
+    name: string;
+    root: string;
+    nodes: Record<string, TreeNode>;
+    corpusFiles: Record<string, CorpusFileMeta>;
+    /** Corpus options the tree was built with. Verification MUST reuse these — verifying
+     * against a differently-scoped corpus produces wrong verdicts, not conservative ones. */
+    corpusOptions?: {
+        include?: string[];
+        maxFiles?: number;
+    };
+    builtAt: string;
+    generator: string;
+}
+/** Live view of the corpus used by the gate at verification time. */
+export interface CorpusSnapshot {
+    root: string;
+    files: Map<string, {
+        hash: string;
+        lines: string[];
+    }>;
+}
+export interface SpanVerification {
+    verdict: Extract<Verdict, 'VERIFIED' | 'STALE' | 'OUT_OF_CORPUS'>;
+    /** Present when the span text was found at a new location (code moved). */
+    healed?: {
+        startLine: number;
+        endLine: number;
+    };
+}
+export interface ClaimVerification {
+    claimId: string;
+    verdict: Verdict;
+    spans: SpanVerification[];
+}
+export interface TreeVerification {
+    verdicts: Map<string, Verdict>;
+    details: Map<string, ClaimVerification>;
+    byNode: Map<string, {
+        verified: number;
+        total: number;
+    }>;
+    /** Fraction of claims VERIFIED across the whole tree, 0..1. */
+    freshness: number;
+}

package/dist/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/fix/prompts.d.ts

@@ -0,0 +1,4 @@
+import type { Finding } from './scan.js';
+/** Render one finding as a complete, paste-ready prompt for a coding agent. */
+export declare const findingToPrompt: (f: Finding, index: number) => string;
+export declare const findingsToMarkdown: (findings: Finding[], repoName: string) => string;

package/dist/fix/prompts.js

@@ -0,0 +1,124 @@
+/** Per-kind goal/steps material. The composer wraps these in the spec shape: one bounded
+ * goal, receipts as context, explicit constraints, machine-checkable acceptance, steps. */
+const KIND_SPEC = {
+    'todo-comment': {
+        goal: (f) => `Resolve the ${f.title.split(' in ')[0]} comment: ${f.detail}. Implement what the comment promises (or, if it is genuinely obsolete, remove it with a one-line justification in the commit message).`,
+        steps: [
+            'Read the receipt lines and the surrounding function to understand what the comment defers.',
+            'Implement the smallest complete version of the deferred work.',
+            'Delete the comment — done work does not need a tombstone.',
+            'Add or extend one test that fails before your change and passes after.',
+        ],
+    },
+    'stale-doc-claim': {
+        goal: (f) => `Make the documentation true again: ${f.detail} Update the doc to match what the code does NOW (never change code to match old docs without evidence the code regressed).`,
+        steps: [
+            'Open the cited doc lines (receipts below) and the code they describe.',
+            'Determine which side is right: did the code intentionally move on, or did it regress?',
+            'Rewrite the stale passage to describe current behavior, precisely and briefly.',
+        ],
+        extraAcceptance: ['Rebuild the tree and confirm the claim flips back to VERIFIED: `npx @northtek/overstory build && npx @northtek/overstory verify` exits 0.'],
+    },
+    'oversized-file': {
+        goal: (f) => `${f.title}. Split it along its natural seams into focused modules without changing any behavior.`,
+        steps: [
+            'List the file\'s top-level declarations and group them by cohesion (what changes together).',
+            'Extract one cohesive group at a time into a new module; re-export from the original file to keep the public surface identical.',
+            'Move imports; run the type checker after each extraction, not just at the end.',
+        ],
+        extraAcceptance: ['No public API change: existing imports of this module compile untouched.'],
+    },
+    'empty-catch': {
+        goal: (f) => `${f.title}: ${f.detail} Decide what this failure MEANS and handle it explicitly.`,
+        steps: [
+            'Determine what can actually throw inside the try block (read the receipt).',
+            'Choose deliberately: propagate, retry, degrade with a logged warning, or prove it cannot throw and remove the try.',
+            'Never leave `catch {}` — even a comment explaining why ignoring is CORRECT beats silence.',
+        ],
+    },
+    'debug-leftover': {
+        goal: (f) => `${f.title}. Remove it or promote it to intentional, leveled logging.`,
+        steps: ['If it aided debugging once, delete it.', 'If operators genuinely need it, route it through the project\'s logging convention with a level.'],
+    },
+    'ts-escape-hatch': {
+        goal: (f) => `${f.title}: ${f.detail} Restore type safety at this point.`,
+        steps: [
+            'Read what the compiler was complaining about before the escape hatch.',
+            'Fix the underlying type (narrowing, generics, or a corrected signature) instead of silencing it.',
+            'If the silencing is truly required (third-party gap), leave @ts-expect-error WITH a one-line reason.',
+        ],
+    },
+    'untested-module': {
+        goal: (f) => `${f.title}. Write focused tests for its exported behavior.`,
+        steps: [
+            'For each receipt (an exported declaration), write the smallest test proving its contract: expected output for a representative input, plus one edge case.',
+            'Test through the public surface only — no reaching into internals.',
+            'Include one negative-control test: an input that must fail, failing the right way.',
+        ],
+        extraAcceptance: ['New tests fail if the module\'s behavior is broken (verify by temporarily inverting one assertion).'],
+    },
+    'undocumented-dir': {
+        goal: (f) => `${f.title}. Write a short README for this directory: what it is, how its files relate, where a reader starts.`,
+        steps: [
+            'Start from what the knowledge tree already says (in the finding detail).',
+            'Write 10-20 lines: purpose, the 2-3 load-bearing files, one usage example if applicable.',
+            'Precise beats complete — link to code rather than restating it.',
+        ],
+    },
+    'unsupported-claim': {
+        goal: (f) => `${f.detail} Make the code say what it means: rename, restructure, or comment the cited lines so a reader (and the next summarizer) cannot misread them.`,
+        steps: [
+            'Read the cited lines and the claim; identify exactly what misleads.',
+            'Prefer renames and small restructures over comments; comment only what code cannot express.',
+        ],
+        extraAcceptance: ['Rebuild and confirm the claim comes back `supported`: `npx @northtek/overstory build` then check the node in the explorer.'],
+    },
+};
+const BASE_CONSTRAINTS = [
+    'Smallest possible diff — change nothing beyond the stated goal.',
+    'No new dependencies.',
+    'Match the file\'s existing style and conventions exactly.',
+    'If you discover the premise is wrong (the finding misread the code), STOP and say so instead of forcing a change.',
+];
+const BASE_ACCEPTANCE = [
+    'The project\'s existing tests and type checks pass, with the command output shown.',
+    'Every claim in the change is verifiable from the diff — no "should work" without the proving command.',
+];
+/** Render one finding as a complete, paste-ready prompt for a coding agent. */
+export const findingToPrompt = (f, index) => {
+    const spec = KIND_SPEC[f.kind];
+    const receipts = f.receipts.length
+        ? f.receipts
+            .map((r) => `\`${r.file}:${r.startLine}-${r.endLine}\`\n\`\`\`\n${r.text}\n\`\`\``)
+            .join('\n')
+        : '_(structural finding — receipts are the directory listing itself)_';
+    const acceptance = [...(spec.extraAcceptance ?? []), ...BASE_ACCEPTANCE];
+    return `## Fix ${index}: ${f.title}
+
+**Goal** — ${spec.goal(f)}
+
+**Context (receipts — the exact lines this finding is grounded in):**
+${receipts}
+
+**Constraints:**
+${BASE_CONSTRAINTS.map((c) => `- ${c}`).join('\n')}
+
+**Acceptance criteria (machine-checkable):**
+${acceptance.map((a) => `- ${a}`).join('\n')}
+
+**Steps:**
+${spec.steps.map((s, i) => `${i + 1}. ${s}`).join('\n')}
+`;
+};
+export const findingsToMarkdown = (findings, repoName) => {
+    const bySeverity = [1, 2, 3].map((s) => findings.filter((f) => f.severity === s).length);
+    return `# Fix prompts for ${repoName}
+
+Generated by OVERSTORY from the verified knowledge tree — every prompt is grounded in
+receipts (exact lines), scoped to one bounded change, and closes with machine-checkable
+acceptance criteria. Paste one prompt per agent session; smallest diff wins.
+
+${findings.length} findings (${bySeverity[0]} fix-first · ${bySeverity[1]} soon · ${bySeverity[2]} when-convenient)
+
+${findings.map((f, i) => findingToPrompt(f, i + 1)).join('\n---\n\n')}`;
+};

package/dist/fix/scan.d.ts

@@ -0,0 +1,18 @@
+import type { CorpusSnapshot, Tree, TreeVerification } from '../core/types.js';
+export type FindingKind = 'todo-comment' | 'stale-doc-claim' | 'oversized-file' | 'empty-catch' | 'debug-leftover' | 'ts-escape-hatch' | 'untested-module' | 'undocumented-dir' | 'unsupported-claim';
+export interface FindingReceipt {
+    file: string;
+    startLine: number;
+    endLine: number;
+    text: string;
+}
+export interface Finding {
+    kind: FindingKind;
+    severity: 1 | 2 | 3;
+    title: string;
+    detail: string;
+    receipts: FindingReceipt[];
+}
+/** Deterministic issue scanner — no LLM anywhere. Every finding carries receipts (the
+ * exact lines), so the generated prompts are grounded, not vibes. Caps keep output usable. */
+export declare const scanFindings: (corpus: CorpusSnapshot, tree: Tree, verification: TreeVerification) => Finding[];