@verevoir/review 0.2.0 → 0.3.1

package/dist/references.js

@@ -0,0 +1,312 @@
+// Deterministic resolution of references in a diff's ADDED lines, so a lens can see whether
+// an `ADR 009` citation points at the right ADR, or a cited file path exists, instead of
+// guessing. No model call. Runs only when there is a context root.
+//
+// Scanned: ADR references (`ADR 009`, `ADR-009`, `ADR 9`) and repo-relative file paths with
+// common extensions, optionally with `:line`. Only lines the change ADDS are scanned.
+//
+// SAFETY: same rules as context-files.ts. A cited path with a `..` segment, an absolute path
+// or a NUL is refused without being touched; a path or ADR file that resolves (through a
+// symlink) outside the context root is refused. The ADR search lists directories to a depth of
+// 4 and skips node_modules, .git and dist.
+import { diffPaths, unsafePathReason } from './context-files.js';
+/** At most this many distinct references are resolved; the rest are counted, not resolved. */
+export const MAX_REFERENCES = 40;
+/** Directory levels below the root that the ADR search lists. */
+export const ADR_SEARCH_DEPTH = 4;
+/** The basename search visits at most this many entries before it stops and says so. */
+export const MAX_SEARCH_FILES = 5000;
+/** Directory levels below the root that the basename search descends. */
+export const BASENAME_SEARCH_DEPTH = 8;
+const SKIPPED_DIRS = new Set(['node_modules', '.git', 'dist']);
+const ADR_DIRS = new Set(['adrs', 'adr']);
+/** Lines the diff adds, with the file and new-side line number of each. */
+export function addedLines(diff) {
+    const out = [];
+    let file = '';
+    let inHunk = false;
+    let next = 0;
+    for (const line of diff.split(/\r?\n/)) {
+        if (line.startsWith('diff --git ')) {
+            inHunk = false;
+            continue;
+        }
+        if (!inHunk && line.startsWith('+++ ')) {
+            const raw = line.slice(4).split('\t')[0]?.trim() ?? '';
+            file = raw === '/dev/null' ? '' : raw.replace(/^b\//, '');
+            continue;
+        }
+        const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(line);
+        if (hunk !== null) {
+            inHunk = true;
+            next = Number(hunk[1]);
+            continue;
+        }
+        if (!inHunk)
+            continue;
+        if (line.startsWith('+')) {
+            out.push({ file, line: next, text: line.slice(1) });
+            next++;
+        }
+        else if (line.startsWith(' ')) {
+            next++;
+        }
+    }
+    return out;
+}
+const ADR_RE = /\bADR[ -]?0*(\d{1,4})\b/gi;
+const PATH_RE = /(?<![\w./-])((?:[\w.-]+\/)*[\w.-]+\.(?:md|ts|tsx|js|mjs|cjs|json|yml|yaml|sh))(?::(\d+))?(?![\w-])/g;
+/** Distinct references in the added lines, in order of first appearance. */
+export function findReferences(diff) {
+    const seen = new Set();
+    const out = [];
+    for (const added of addedLines(diff)) {
+        const where = `${added.file === '' ? '(unknown file)' : added.file}:${String(added.line)}`;
+        for (const m of added.text.matchAll(ADR_RE)) {
+            const target = String(Number(m[1]));
+            const key = `adr:${target}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push({ kind: 'adr', target, display: m[0], where });
+        }
+        for (const m of added.text.matchAll(PATH_RE)) {
+            const target = m[1] ?? '';
+            const key = `path:${target}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push({ kind: 'path', target, display: m[0], where });
+        }
+    }
+    return out;
+}
+function isAbsent(cause) {
+    const code = cause.code;
+    return code === 'ENOENT' || code === 'ENOTDIR';
+}
+function describe(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+function inside(root, real) {
+    return real === root.real || real.startsWith(root.prefix);
+}
+/** Relative paths of every file directly inside an `adrs` / `adr` directory, depth-limited. */
+async function adrFiles(root, fs) {
+    const list = fs.listDir;
+    if (list === undefined)
+        return undefined;
+    const found = [];
+    const queue = [{ rel: '', depth: 0 }];
+    while (queue.length > 0) {
+        const { rel, depth } = queue.shift() ?? { rel: '', depth: 0 };
+        let entries;
+        try {
+            entries = await list(rel === '' ? root.real : `${root.prefix}${rel}`);
+        }
+        catch {
+            continue;
+        }
+        entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const entry of entries) {
+            const childRel = rel === '' ? entry.name : `${rel}/${entry.name}`;
+            if (entry.isDir) {
+                if (SKIPPED_DIRS.has(entry.name))
+                    continue;
+                if (ADR_DIRS.has(entry.name.toLowerCase())) {
+                    try {
+                        for (const inner of await list(`${root.prefix}${childRel}`)) {
+                            if (!inner.isDir)
+                                found.push(`${childRel}/${inner.name}`);
+                        }
+                    }
+                    catch {
+                        // an unreadable ADR directory simply contributes nothing
+                    }
+                }
+                if (depth + 1 < ADR_SEARCH_DEPTH)
+                    queue.push({ rel: childRel, depth: depth + 1 });
+            }
+        }
+    }
+    return found;
+}
+function firstHeading(text) {
+    const match = /^# (.+?)[ \t]*$/m.exec(text);
+    return match?.[1]?.trim();
+}
+async function resolveAdr(ref, root, files, fs) {
+    if (files === undefined)
+        return 'could not be searched (this host cannot list directories)';
+    const pattern = new RegExp(`^0*${ref.target}-`);
+    const hits = files.filter((rel) => pattern.test(rel.slice(rel.lastIndexOf('/') + 1)));
+    if (hits.length === 0)
+        return 'not found in this repository';
+    const parts = [];
+    for (const rel of hits) {
+        try {
+            const real = await fs.realpath(`${root.prefix}${rel}`);
+            if (!inside(root, real)) {
+                parts.push(`${rel} (refused: resolves outside the context root)`);
+                continue;
+            }
+            const title = firstHeading(await fs.readFile(real));
+            parts.push(title === undefined ? `${rel} (no title)` : `${rel}: '${title}'`);
+        }
+        catch (cause) {
+            parts.push(`${rel} (could not be read: ${describe(cause)})`);
+        }
+    }
+    return parts.join('; ');
+}
+/** Breadth-first search for files named `name`, bounded by depth and entries visited. */
+async function findByBasename(root, fs, name, maxVisited) {
+    const list = fs.listDir;
+    if (list === undefined)
+        return { matches: [], capped: false, searchable: false };
+    const matches = [];
+    const queue = [{ rel: '', depth: 0 }];
+    let visited = 0;
+    while (queue.length > 0) {
+        const { rel, depth } = queue.shift() ?? { rel: '', depth: 0 };
+        let entries;
+        try {
+            entries = await list(rel === '' ? root.real : `${root.prefix}${rel}`);
+        }
+        catch {
+            continue;
+        }
+        entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const entry of entries) {
+            visited++;
+            if (visited > maxVisited)
+                return { matches, capped: true, searchable: true };
+            const childRel = rel === '' ? entry.name : `${rel}/${entry.name}`;
+            if (entry.isDir) {
+                if (SKIPPED_DIRS.has(entry.name))
+                    continue;
+                if (depth + 1 < BASENAME_SEARCH_DEPTH)
+                    queue.push({ rel: childRel, depth: depth + 1 });
+            }
+            else if (entry.name === name) {
+                matches.push(childRel);
+            }
+        }
+    }
+    return { matches, capped: false, searchable: true };
+}
+function basenameOf(path) {
+    return path.slice(path.lastIndexOf('/') + 1);
+}
+async function isRootDir(root, fs, name) {
+    try {
+        const real = await fs.realpath(`${root.prefix}${name}`);
+        return inside(root, real);
+    }
+    catch {
+        return false;
+    }
+}
+const OWNER_RE = /^[A-Za-z0-9][A-Za-z0-9-]*$/;
+async function resolvePath(ref, root, fs, deleted, maxVisited) {
+    const unsafe = unsafePathReason(ref.target);
+    if (unsafe !== undefined)
+        return `refused (${unsafe})`;
+    const segments = ref.target.split('/');
+    const bare = segments.length === 1;
+    // A real repo-relative path always wins.
+    try {
+        const real = await fs.realpath(`${root.prefix}${ref.target}`);
+        if (!inside(root, real))
+            return 'refused (resolves outside the context root)';
+        const stat = await fs.statFile(real);
+        return stat.isFile ? 'exists' : 'exists but is not a regular file';
+    }
+    catch (cause) {
+        if (!isAbsent(cause))
+            return `could not be checked (${describe(cause)})`;
+    }
+    // An exact repo-relative path the diff deletes.
+    if (!bare && deleted.includes(ref.target))
+        return 'deleted by this change';
+    if (bare) {
+        // Surviving files win; a deleted copy only matters when none survives.
+        const deletedCopies = deleted.filter((d) => basenameOf(d) === ref.target);
+        const found = await findByBasename(root, fs, ref.target, maxVisited);
+        if (!found.searchable) {
+            return deletedCopies.length > 0
+                ? `deleted by this change (${deletedCopies.join(', ')})`
+                : 'not found at the context root (cannot search elsewhere: this host cannot list ' +
+                    'directories)';
+        }
+        const capNote = found.capped ? ' (search capped)' : '';
+        const deletedNote = deletedCopies.length > 0
+            ? `; a copy at ${deletedCopies.join(', ')} was deleted by this change`
+            : '';
+        if (found.matches.length === 1)
+            return `${found.matches[0] ?? ''}${capNote}${deletedNote}`;
+        if (found.matches.length > 1) {
+            return (`ambiguous: ${String(found.matches.length)} matches, e.g. ` +
+                `${found.matches.slice(0, 2).join(', ')}${capNote}${deletedNote}`);
+        }
+        if (deletedCopies.length > 0)
+            return `deleted by this change (${deletedCopies.join(', ')})`;
+        return found.capped
+            ? 'not found in the part of this repository searched (search capped)'
+            : 'not found anywhere in this repository';
+    }
+    // owner/repo/... where neither first segment is a real directory here: another repository.
+    const [owner = '', repo = ''] = segments;
+    if (segments.length >= 3 &&
+        OWNER_RE.test(owner) &&
+        !(await isRootDir(root, fs, owner)) &&
+        !(await isRootDir(root, fs, `${owner}/${repo}`))) {
+        return 'external (another repository), not checked';
+    }
+    return 'not found in this repository';
+}
+/**
+ * The body of the "References in added lines" section for `diff`, resolved against `rootPath`.
+ * Throws only when the root itself cannot be resolved.
+ */
+export async function buildReferences(diff, rootPath, fs, options = {}) {
+    const maxVisited = options.maxSearchFiles ?? MAX_SEARCH_FILES;
+    const deleted = diffPaths(diff)
+        .filter((p) => p.deleted && p.path !== '')
+        .map((p) => p.path);
+    let real;
+    try {
+        real = await fs.realpath(rootPath);
+    }
+    catch (cause) {
+        throw new Error(`--context-root ${rootPath} could not be resolved: ${describe(cause)}`);
+    }
+    const root = { real, prefix: real.endsWith('/') ? real : `${real}/` };
+    const all = findReferences(diff);
+    if (all.length === 0)
+        return 'No ADR or file references were found in the added lines.';
+    const refs = all.slice(0, MAX_REFERENCES);
+    let adrs;
+    let adrsSearched = false;
+    const lines = [];
+    for (const ref of refs) {
+        let result;
+        if (ref.kind === 'adr') {
+            if (!adrsSearched) {
+                adrs = await adrFiles(root, fs);
+                adrsSearched = true;
+            }
+            result = await resolveAdr(ref, root, adrs, fs);
+        }
+        else {
+            result = await resolvePath(ref, root, fs, deleted, maxVisited);
+        }
+        const shown = ref.kind === 'adr' ? ref.display : `\`${ref.display}\``;
+        lines.push(`- ${shown} (${ref.where}) → ${result}`);
+    }
+    if (all.length > refs.length) {
+        lines.push(`- … and ${String(all.length - refs.length)} more reference(s) not resolved ` +
+            `(limit ${String(MAX_REFERENCES)}).`);
+    }
+    return lines.join('\n');
+}

package/dist/report.d.ts

@@ -1,9 +1,25 @@
-import type { Outcome, Verdict } from './verdict.js';
+import type { Finding, Outcome, Verdict } from './verdict.js';
+/** One de-duplicated finding: the group's highest tier, its first member, and who raised it. */
+export interface DedupGroupView {
+    readonly blocking: boolean;
+    readonly finding: Finding;
+    readonly raisedBy: readonly {
+        readonly lens: string;
+        readonly practices: readonly string[];
+    }[];
+}
 export interface ReportContext {
     /** Where the lens set was read from, so a reader knows whose bar this was. */
     readonly source: string;
     /** What was reviewed. */
     readonly subject: string;
+    /** De-duplicated findings (replaces the per-lens finding lists), from `total` raised. */
+    readonly dedup?: {
+        readonly groups: readonly DedupGroupView[];
+        readonly total: number;
+    };
+    /** Why de-duplication did not happen, said in one line. */
+    readonly dedupSkipped?: string;
 }
 /**
  * The process exit code for an outcome. `approved` and `out_of_scope` are

package/dist/report.js

@@ -16,6 +16,11 @@ const HEADING = {
     could_not_run: 'Could not run',
     out_of_scope: 'Nothing in scope',
 };
+function raisedByText(view) {
+    return view.raisedBy
+        .map((r) => (r.practices.length === 0 ? r.lens : `${r.lens} (${r.practices.join(', ')})`))
+        .join(', ');
+}
 /**
  * The process exit code for an outcome. `approved` and `out_of_scope` are
  * both zero — a panel where every declared lens found nothing in its own
@@ -38,6 +43,16 @@ function findingsByLens(findings) {
     }
     return grouped;
 }
+/** `lens: verdict` plus the lens's own one-line reason when it gave one. */
+function verdictHeading(lens, verdict) {
+    const result = verdict.results.find((r) => r.lens === lens);
+    if (result === undefined)
+        return lens;
+    const reason = result.reason === undefined ? '' : result.reason.trim();
+    // The model's reason was written for the outcome it gave, not the one tier enforcement left.
+    const word = result.tierAdjusted === true ? `${result.outcome} (after tier enforcement)` : result.outcome;
+    return reason === '' ? `${lens}: ${word}` : `${lens}: ${word}: ${reason}`;
+}
 export function renderReport(verdict, context) {
     const lines = [
         `## Review: ${HEADING[verdict.outcome]}`,
@@ -62,20 +77,60 @@ export function renderReport(verdict, context) {
     const grouped = findingsByLens(verdict.findings);
     const blockingCount = verdict.findings.filter((finding) => finding.blocking).length;
     const smellCount = verdict.findings.length - blockingCount;
-    if (grouped.size > 0) {
+    const dedup = context.dedup !== undefined && context.dedup.groups.length > 0 ? context.dedup : undefined;
+    if (dedup !== undefined) {
+        const blocking = dedup.groups.filter((g) => g.blocking).length;
+        const smells = dedup.groups.length - blocking;
+        lines.push(`### ${dedup.groups.length} finding(s)` +
+            (smells > 0 ? ` (${blocking} blocking, ${smells} non-blocking)` : '') +
+            `, de-duplicated from ${dedup.total} raised`, '');
+        for (const group of dedup.groups) {
+            lines.push(`- [${group.blocking ? 'blocking' : 'smell'}] ${group.finding.summary}`);
+            const detail = group.finding.detail;
+            if (detail !== undefined && detail !== '') {
+                for (const detailLine of detail.split('\n')) {
+                    lines.push(detailLine === '' ? '' : `  ${detailLine}`);
+                }
+            }
+            lines.push(`  raised by: ${raisedByText(group)}`);
+        }
+        lines.push('');
+        // Per-lens verdict lines are unchanged: every lens that reviewed gets its own.
+        lines.push('### Lens verdicts', '');
+        for (const r of verdict.results) {
+            if (r.outcome === 'approved' || r.outcome === 'rejected') {
+                lines.push(`#### ${verdictHeading(r.lens, verdict)}`, '');
+            }
+        }
+    }
+    else if (grouped.size > 0) {
         lines.push(`### ${verdict.findings.length} finding(s)` +
             (smellCount > 0 ? ` (${blockingCount} blocking, ${smellCount} non-blocking)` : ''), '');
         for (const [lens, findings] of grouped) {
-            lines.push(`#### ${lens}`, '');
+            lines.push(`#### ${verdictHeading(lens, verdict)}`, '');
             for (const finding of findings) {
                 lines.push(`- [${finding.blocking ? 'blocking' : 'smell'}] ${finding.summary}`);
                 if (finding.detail !== undefined && finding.detail !== '') {
-                    lines.push(`  ${finding.detail}`);
+                    for (const detailLine of finding.detail.split('\n')) {
+                        lines.push(detailLine === '' ? '' : `  ${detailLine}`);
+                    }
                 }
             }
             lines.push('');
         }
     }
+    // Every lens gets a line: the approving ones, with no findings, are not otherwise
+    // visible. Lenses that did not run or had nothing in scope are listed above.
+    const quiet = verdict.results.filter((r) => r.outcome === 'approved' && !grouped.has(r.lens));
+    if (dedup === undefined && quiet.length > 0) {
+        if (grouped.size === 0)
+            lines.push('### Lens verdicts', '');
+        for (const r of quiet)
+            lines.push(`#### ${verdictHeading(r.lens, verdict)}`, '');
+    }
+    if (context.dedupSkipped !== undefined) {
+        lines.push(`De-duplication was skipped: ${context.dedupSkipped}.`, '');
+    }
     // BL-144: a substantiated rejection now wins the outcome WORD even when
     // lenses remain unrun (see verdict.ts's own header) — but that must never
     // read as "fix the findings above and this becomes approved". It cannot:
@@ -97,17 +152,19 @@ export function renderReport(verdict, context) {
             'the reason each lens gave.', '');
     }
     if (verdict.outcome === 'approved') {
+        // What the reader was shown: de-duplicated groups when the findings were merged.
+        const shownSmells = dedup === undefined ? smellCount : dedup.groups.filter((g) => !g.blocking).length;
         const base = verdict.outOfScope.length > 0
-            ? smellCount > 0
+            ? shownSmells > 0
                 ? 'Every lens with something in scope reviewed it. Nothing it found held this up. See ' +
                     'above for the lens(es) that had nothing in scope for this change.'
                 : 'Every lens with something in scope reviewed it and found nothing. See above for the ' +
                     'lens(es) that had nothing in scope for this change.'
-            : smellCount > 0
+            : shownSmells > 0
                 ? 'Every lens reviewed. Nothing it found held this up.'
                 : 'Every lens reviewed and none had a finding.';
-        const suffix = smellCount > 0
-            ? ` ${smellCount} non-blocking finding(s) are listed above; none of them held this up. ` +
+        const suffix = shownSmells > 0
+            ? ` ${shownSmells} non-blocking finding(s) are listed above; none of them held this up. ` +
                 'If this merges as-is, file each as a follow-up issue before merging, referenced ' +
                 'as `owner/repo#123`.'
             : '';

package/dist/reviewer-anthropic.js

@@ -100,7 +100,13 @@ export function anthropicReviewer(config, post, onResolvedModel) {
             // The shared half, marked cacheable — `Prompt`'s ordering contract made
             // real: identical bytes for every lens, sent first, so a five-lens
             // panel pays for the diff once.
-            system: [{ type: 'text', text: prompt.shared, cache_control: { type: 'ephemeral' } }],
+            // Unless the prompt says nothing else reads it (`cache: false`): a write nobody reads
+            // is pure cost.
+            system: [
+                prompt.cache === false
+                    ? { type: 'text', text: prompt.shared }
+                    : { type: 'text', text: prompt.shared, cache_control: { type: 'ephemeral' } },
+            ],
             messages: [{ role: 'user', content: prompt.perLens }],
         });
         let response;

package/dist/run-review.d.ts

@@ -35,6 +35,24 @@ export interface ReviewNodeInput {
      * leaves every existing call site building its Reviewer exactly as
      * before. */
     readonly reviewer?: Reviewer;
+    /** Run the first lens alone, then fan out the rest, so they read the prompt
+     * cache it wrote. Only applies with 2 or more lenses. Off when absent. */
+    readonly warmFirst?: boolean;
+    /** Per lens id: the signal lines its [blocking] findings must quote (see tier.ts). A lens
+     * with no entry is left as it was. Absent: no tier enforcement. */
+    readonly tierSignals?: Readonly<Record<string, readonly string[]>>;
+    /** Per lens id: just the `_Reject:_` lines of `tierSignals`; a smell quoting one is promoted. */
+    readonly tierRejects?: Readonly<Record<string, readonly string[]>>;
+    /** Every practice id in the corpus; ignored when matching a quote (see tier.ts). */
+    readonly practiceIds?: readonly string[];
+    /** After the panel (and tier enforcement), make ONE extra call through the same reviewer to
+     * group findings that describe the same defect (see dedup.ts). Off when absent. */
+    readonly dedup?: boolean;
+    /** Per lens id: its practices, so a de-duplicated finding can name them. */
+    readonly practiceNames?: Readonly<Record<string, readonly {
+        id: string;
+        title: string;
+    }[]>>;
 }
 export interface ReviewNodeResult {
     readonly verdict: Verdict;
@@ -44,5 +62,11 @@ export interface ReviewNodeResult {
     /** Every prompt as dispatched, keyed by lens id — proof the fan shares
      * one prefix, rather than merely claiming it. */
     readonly prompts: ReadonlyMap<string, Prompt>;
+    /** How many [blocking] findings tier enforcement downgraded to smells (0 when none). */
+    readonly downgraded: number;
+    /** How many smells tier enforcement promoted to [blocking] (0 when none). */
+    readonly promoted: number;
+    /** Stderr lines, one per member of every merged dedup group (empty when none merged). */
+    readonly dedupAudit: readonly string[];
 }
 export declare function runReviewNode(input: ReviewNodeInput, onCall?: (call: RawCall) => void): Promise<ReviewNodeResult>;

package/dist/run-review.js

@@ -34,6 +34,9 @@ import { exitCodeFor, renderReport } from './report.js';
 import { selectReviewer } from './reviewer-selection.js';
 import { describeThrown } from './raw-call.js';
 import { normaliseReviewerReply } from './panel.js';
+import { warmFirst } from './warm-first.js';
+import { enforceTier } from './tier.js';
+import { dedupAuditLines, dedupFindings, numberFindings, toGroupViews } from './dedup.js';
 // RECORD-NEVER-PREDICT discipline: `onCall` is OPTIONAL so every existing
 // call site, and every test that builds a ReviewNodeInput by hand, is
 // unaffected by this addition.
@@ -104,10 +107,49 @@ export async function runReviewNode(input, onCall) {
                 throw cause;
             }
         };
-    const { verdict, prompts } = await runPanel(input.lensSet, input.subject, observedReviewer, input.practices);
+    // Outside the observer, so each lens's recorded wall time is its own call,
+    // not the time it spent waiting for the warm-up.
+    const dispatched = input.warmFirst === true && input.lensSet.lenses.length >= 2
+        ? warmFirst(observedReviewer)
+        : observedReviewer;
+    const panel = await runPanel(input.lensSet, input.subject, dispatched, input.practices);
+    const prompts = panel.prompts;
+    // C1 runs before C2: de-duplication sees the tiers as enforced.
+    const tiered = input.tierSignals === undefined
+        ? { verdict: panel.verdict, downgraded: 0, promoted: 0 }
+        : enforceTier(panel.verdict, input.tierSignals, {
+            ...(input.tierRejects === undefined ? {} : { rejects: input.tierRejects }),
+            ...(input.practiceIds === undefined ? {} : { practiceIds: input.practiceIds }),
+        });
+    const verdict = tiered.verdict;
+    let dedup;
+    let dedupSkipped;
+    let dedupAudit = [];
+    if (input.dedup === true && verdict.findings.length >= 2) {
+        const numbered = numberFindings(verdict.findings);
+        // The observed reviewer, outside warm-first: the extra call is recorded like a lens call.
+        const outcome = await dedupFindings(numbered, observedReviewer);
+        if (outcome.ok) {
+            dedup = { groups: toGroupViews(outcome.groups, input.practiceNames), total: numbered.length };
+            dedupAudit = dedupAuditLines(outcome.groups);
+        }
+        else {
+            dedupSkipped = outcome.reason;
+        }
+    }
     const report = renderReport(verdict, {
         source: input.lensSetSource,
         subject: input.subject.title,
+        ...(dedup === undefined ? {} : { dedup }),
+        ...(dedupSkipped === undefined ? {} : { dedupSkipped }),
     });
-    return { verdict, report, exitCode: exitCodeFor(verdict.outcome), prompts };
+    return {
+        verdict,
+        report,
+        exitCode: exitCodeFor(verdict.outcome),
+        prompts,
+        downgraded: tiered.downgraded,
+        promoted: tiered.promoted,
+        dedupAudit,
+    };
 }

package/dist/source-access.d.ts

@@ -0,0 +1,8 @@
+export interface SourceAccess {
+    /** Every file path under the root, relative to it, forward-slashed. */
+    listFiles(): Promise<readonly string[]>;
+    /** A file's content, or `undefined` if it does not exist (never a
+     * thrown error for a missing file -- a diff may touch a file that was
+     * deleted, or that sits outside this source root). */
+    readFile(path: string): Promise<string | undefined>;
+}

package/dist/source-access.js

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

package/dist/subject-context-render.d.ts

@@ -0,0 +1,8 @@
+import type { SubjectContext } from './context-types.js';
+/** Renders a `SubjectContext` into the markdown block prompt.ts inserts
+ * as `Subject.subjectContext`. Kept as its own small, pure function --
+ * not inlined into the assembler, and not inlined into prompt.ts -- so a
+ * caller that assembles context some other way can still use this
+ * renderer, and so prompt.ts never has to import anything tree-sitter-
+ * shaped. */
+export declare function renderSubjectContext(context: SubjectContext): string;

package/dist/subject-context-render.js

@@ -0,0 +1,29 @@
+/** Renders a `SubjectContext` into the markdown block prompt.ts inserts
+ * as `Subject.subjectContext`. Kept as its own small, pure function --
+ * not inlined into the assembler, and not inlined into prompt.ts -- so a
+ * caller that assembles context some other way can still use this
+ * renderer, and so prompt.ts never has to import anything tree-sitter-
+ * shaped. */
+export function renderSubjectContext(context) {
+    if (context.entries.length === 0 && context.omitted.length === 0)
+        return '';
+    const parts = [];
+    for (const entry of context.entries) {
+        parts.push(`### \`${entry.symbol}\` (${entry.file})`, '');
+        if (entry.definition !== undefined) {
+            parts.push('```', entry.definition, '```', '');
+        }
+        parts.push(entry.callers.length > 0
+            ? `Called by: ${entry.callers.join(', ')}`
+            : 'Called by: (no callers found in the source tree)');
+        parts.push(entry.callees.length > 0 ? `Calls: ${entry.callees.join(', ')}` : 'Calls: (none resolved)');
+        parts.push('');
+    }
+    if (context.omitted.length > 0) {
+        parts.push('### Not resolved', '');
+        for (const o of context.omitted)
+            parts.push(`- \`${o.symbol}\`: ${o.reason}`);
+        parts.push('');
+    }
+    return parts.join('\n').trimEnd();
+}

package/dist/tier.d.ts

@@ -0,0 +1,35 @@
+import type { Verdict } from './verdict.js';
+/** The shortest verbatim run of a signal line that counts as quoting it. */
+export declare const MIN_QUOTE = 24;
+/** Appended to the summary of a finding that was downgraded. */
+export declare const DOWNGRADE_NOTE = " (downgraded: no signal quoted)";
+/** Appended to the summary of a smell that was promoted. */
+export declare const PROMOTE_NOTE = " (promoted: quotes a Reject signal)";
+export declare function normaliseForQuote(text: string): string;
+/**
+ * Whether `text` contains a verbatim quote (per the rule above) of any of `signals`.
+ * `practiceIds` are the corpus's practice ids, which are ignored on both sides.
+ */
+export declare function quotesSignal(text: string, signals: readonly string[], practiceIds?: readonly string[]): boolean;
+export interface TierContext {
+    /** Per lens id: just the `_Reject:_` lines. A lens with an entry can have smells promoted. */
+    readonly rejects?: Readonly<Record<string, readonly string[]>>;
+    /** Every practice id in the corpus, ignored when matching. */
+    readonly practiceIds?: readonly string[];
+}
+export interface TierResult {
+    readonly verdict: Verdict;
+    /** How many findings were downgraded. */
+    readonly downgraded: number;
+    /** How many smells were promoted to [blocking]. */
+    readonly promoted: number;
+}
+/**
+ * Downgrade unquoted [blocking] findings of every lens that has an entry in `signals`, promote
+ * smells that quote one of the lens's own Reject lines (`context.rejects`), then re-aggregate.
+ * A lens that was `rejected` and is left with no [blocking] finding counts as `approved`; one
+ * that was `approved` and gained a promoted finding counts as `rejected`; either is marked
+ * `tierAdjusted`. Lenses without an entry (bundled lenses) are untouched. With nothing changed
+ * the verdict is returned as it was.
+ */
+export declare function enforceTier(verdict: Verdict, signals: Readonly<Record<string, readonly string[]>>, context?: TierContext): TierResult;