@verevoir/review 0.3.0 → 0.3.2

package/README.md

@@ -374,6 +374,15 @@ git diff origin/main...HEAD | npx -y @verevoir/review aigency-review
 - `AIGENCY_REVIEW_LENSES` -- lens set path (see above).
 - `AIGENCY_REVIEW_MODEL` -- default `claude-opus-5-5`.
 - `AIGENCY_REVIEW_MAX_TOKENS` -- positive integer, default `65536`.
+- `AIGENCY_REVIEW_LENS_PRACTICES` -- a default for `--practices <dir>`, for a local gate whose
+  command is argv with no shell and so cannot expand a variable. Used when `--practices` is
+  not given and this is set and non-blank (and `--lenses` is not given); the flag wins. A
+  directory that does not exist is refused like a bad `--practices`, naming this variable.
+- `AIGENCY_REVIEW_TEMPERATURE` -- optional sampling temperature, a number from 0 to 1, sent as
+  `temperature` on every Anthropic API call (lenses and the de-duplication call). Anything else
+  is `could_not_run`. Unset, nothing is sent and the provider default applies. The `claude-cli`
+  route cannot take a temperature (`claude -p` has no such flag): a set value is said not to
+  apply, on stderr and in the footer, and is never silently ignored.
 - `GITHUB_STEP_SUMMARY` -- when set, the report is appended to that file.
 
 **Report footer.** The report ends with what judged it: the model (the id the
@@ -381,7 +390,8 @@ transport reported, else the requested one, said as such), the reviewer route by
 name only (`env`, `key-file` or `claude-cli` -- never a key or a path), and one
 per-lens line with input/output tokens (and cache tokens when non-zero) and wall
 time. The same per-lens lines go to stderr. A route that reports no usage says
-`usage not reported`.
+`usage not reported`. A `temperature:` line records the temperature used, `provider default`
+when none was set, or `not supported on the claude-cli route`.
 
 **Output.** The markdown report goes to stdout; `RESULT: approved|out_of_scope|rejected|could_not_run`
 goes to stderr.

package/dist/cli/bin.js

@@ -3,7 +3,7 @@
 // The process boundary for `aigency-review`: construct the real adapters and
 // hand them to `main` (review.ts). No decision lives here.
 import { execFile } from 'node:child_process';
-import { appendFile, readFile, readdir, realpath, stat } from 'node:fs/promises';
+import { appendFile, lstat, readFile, readdir, realpath, stat } from 'node:fs/promises';
 import process from 'node:process';
 import { promisify } from 'node:util';
 import { main } from './review.js';
@@ -27,6 +27,7 @@ main(process.argv.slice(2), process.env, {
         isDir: e.isDirectory(),
     })),
     realpath: (path) => realpath(path),
+    isSymlink: async (path) => (await lstat(path)).isSymbolicLink(),
     statFile: async (path) => {
         const s = await stat(path);
         return { size: s.size, isFile: s.isFile() };

package/dist/cli/footer.d.ts

@@ -4,6 +4,13 @@ export type RouteName = 'env' | 'key-file' | 'claude-cli';
 export declare function modelText(requested: string, calls: readonly RawCall[]): string;
 /** The one line saying how many [blocking] findings tier enforcement downgraded; none for 0. */
 export declare function tierLine(downgraded: number): string | undefined;
-export declare function renderFooter(requested: string, route: RouteName, calls: readonly RawCall[], downgraded?: number): string;
+/** The one line saying how many smells tier enforcement promoted to [blocking]; none for 0. */
+export declare function promotedLine(promoted: number): string | undefined;
+/**
+ * The temperature the judging used. The claude-cli route has no temperature option
+ * (`claude -p` documents no flag for it), so a requested one is said not to apply.
+ */
+export declare function temperatureLine(route: RouteName, temperature: number | undefined): string;
+export declare function renderFooter(requested: string, route: RouteName, calls: readonly RawCall[], downgraded?: number, promoted?: number, temperature?: number): string;
 /** One stderr line per lens. */
 export declare function usageLines(calls: readonly RawCall[]): string[];

package/dist/cli/footer.js

@@ -36,11 +36,37 @@ export function tierLine(downgraded) {
         ? `Tier: ${String(downgraded)} blocking finding(s) downgraded: no Reject/Expect signal quoted`
         : undefined;
 }
-export function renderFooter(requested, route, calls, downgraded = 0) {
-    const lines = ['---', '', `Judged with ${modelText(requested, calls)}, route: ${route}.`];
+/** The one line saying how many smells tier enforcement promoted to [blocking]; none for 0. */
+export function promotedLine(promoted) {
+    return promoted > 0
+        ? `Tier: ${String(promoted)} finding(s) promoted: quotes a Reject signal`
+        : undefined;
+}
+/**
+ * The temperature the judging used. The claude-cli route has no temperature option
+ * (`claude -p` documents no flag for it), so a requested one is said not to apply.
+ */
+export function temperatureLine(route, temperature) {
+    if (temperature === undefined)
+        return 'temperature: provider default';
+    return route === 'claude-cli'
+        ? 'temperature: not supported on the claude-cli route'
+        : `temperature: ${String(temperature)}`;
+}
+export function renderFooter(requested, route, calls, downgraded = 0, promoted = 0, temperature) {
+    const lines = [
+        '---',
+        '',
+        `Judged with ${modelText(requested, calls)}, route: ${route}.`,
+        '',
+        temperatureLine(route, temperature),
+    ];
     const tier = tierLine(downgraded);
     if (tier !== undefined)
         lines.push('', tier);
+    const promotion = promotedLine(promoted);
+    if (promotion !== undefined)
+        lines.push('', promotion);
     if (calls.length > 0) {
         lines.push('', 'Per-lens usage and wall time:', '');
         for (const call of byLens(calls)) {

package/dist/cli/review.d.ts

@@ -27,6 +27,8 @@ export interface ReviewIo {
         readonly size: number;
         readonly isFile: boolean;
     }>;
+    /** lstat: true when the path is itself a symbolic link. Required: the check fails closed. */
+    readonly isSymlink: (path: string) => Promise<boolean>;
     /** List a directory's entries (for the ADR search). Optional: absent, ADRs are not searched. */
     readonly listDir?: (path: string) => Promise<DirEntry[]>;
 }

package/dist/cli/review.js

@@ -24,7 +24,7 @@ import { buildPrompt, renderPrompt } from '../prompt.js';
 import { deriveLensSet, extractBar } from '../practice-lenses.js';
 import { buildFileContext, NO_FILE_CONTEXT_NOTE } from '../context-files.js';
 import { buildReferences } from '../references.js';
-import { renderFooter, tierLine, usageLines } from './footer.js';
+import { promotedLine, renderFooter, temperatureLine, tierLine, usageLines } from './footer.js';
 /** Governance's pinned default, sent to both routes. */
 export const DEFAULT_MODEL = 'claude-opus-5-5';
 /** Governance's default output-token budget (billed route only). */
@@ -44,7 +44,8 @@ const USAGE = [
     '  --title <text>   the title shown at the top of the report (default: "this change")',
     '  --lenses <path>  a lens set JSON file (else AIGENCY_REVIEW_LENSES, else the bundled set)',
     '  --practices <dir>  derive one lens per `lens:` front-matter value from the practice',
-    '                   markdown files in <dir> (cannot be combined with --lenses)',
+    '                   markdown files in <dir> (cannot be combined with --lenses). Default:',
+    '                   AIGENCY_REVIEW_LENS_PRACTICES, when set and non-blank; the flag wins',
     '  --print-lenses   with --practices: print the derived lenses as JSON and exit 0,',
     '                   with no reviewer call and no diff',
     '  --print-prompt <lens-id>  print the exact prompt that lens would be sent for the diff',
@@ -63,7 +64,9 @@ const USAGE = [
     '  -h, --help       print this and exit 0',
     '',
     'Environment: ANTHROPIC_API_KEY, ANTHROPIC_API_KEY_FILE, AIGENCY_REVIEW_LENSES,',
-    'AIGENCY_REVIEW_MODEL, AIGENCY_REVIEW_MAX_TOKENS, GITHUB_STEP_SUMMARY.',
+    'AIGENCY_REVIEW_MODEL, AIGENCY_REVIEW_MAX_TOKENS, AIGENCY_REVIEW_LENS_PRACTICES,',
+    'AIGENCY_REVIEW_TEMPERATURE (0 to 1; API routes only, unset sends none),',
+    'GITHUB_STEP_SUMMARY.',
 ].join('\n');
 function parseArgs(argv) {
     let base;
@@ -251,13 +254,18 @@ export async function main(argv, env, io, deps) {
         if (parsed.practices !== undefined && parsed.lenses !== undefined) {
             return await fail('--practices and --lenses cannot be used together; choose one lens source.');
         }
-        if (parsed.printLenses && parsed.practices === undefined) {
+        // The practices directory: the flag, else (with no --lenses either) the environment default.
+        const practicesFromEnv = parsed.practices === undefined && parsed.lenses === undefined
+            ? present(env['AIGENCY_REVIEW_LENS_PRACTICES'])
+            : undefined;
+        const practicesDir = parsed.practices ?? practicesFromEnv;
+        if (parsed.printLenses && practicesDir === undefined) {
             return await fail('--print-lenses needs --practices <dir>.');
         }
         let derived;
         let bar;
-        if (parsed.practices !== undefined) {
-            const dir = parsed.practices;
+        if (practicesDir !== undefined) {
+            const dir = practicesDir;
             // The grading rules (README), read first so its failure has its own reason.
             let readme;
             try {
@@ -266,7 +274,10 @@ export async function main(argv, env, io, deps) {
             catch (cause) {
                 return await fail(`The practices README at ${dir}/README.md could not be read, so the review has no ` +
                     'grading rules (reject / accept / expect): ' +
-                    `${cause instanceof Error ? cause.message : String(cause)}`);
+                    `${cause instanceof Error ? cause.message : String(cause)}` +
+                    (practicesFromEnv === undefined
+                        ? ''
+                        : '\n\nThe directory came from AIGENCY_REVIEW_LENS_PRACTICES.'));
             }
             try {
                 const names = (await io.readDir(dir)).filter((n) => n.endsWith('.md') && n.toLowerCase() !== 'readme.md');
@@ -336,6 +347,18 @@ export async function main(argv, env, io, deps) {
                 maxTokens = n;
             }
         }
+        // Optional sampling temperature: unset sends nothing; set, it must be a number 0 to 1.
+        let temperature;
+        const rawTemperature = present(env['AIGENCY_REVIEW_TEMPERATURE']);
+        if (rawTemperature !== undefined) {
+            const t = Number(rawTemperature);
+            if (!Number.isFinite(t) || t < 0 || t > 1) {
+                problems.push(`AIGENCY_REVIEW_TEMPERATURE must be a number from 0 to 1, got ${JSON.stringify(rawTemperature)}`);
+            }
+            else {
+                temperature = t;
+            }
+        }
         if (resolved.kind === 'problem' || problems.length > 0) {
             return await fail(`The configuration is present and wrong:\n\n${problems.map((p) => `- ${p}`).join('\n')}`);
         }
@@ -408,6 +431,7 @@ export async function main(argv, env, io, deps) {
                     realpath: io.realpath,
                     statFile: io.statFile,
                     readFile: io.readFile,
+                    isSymlink: io.isSymlink,
                 };
                 fileContext = await buildFileContext(diff, contextRoot, fs);
                 references = await buildReferences(diff, contextRoot, {
@@ -430,7 +454,7 @@ export async function main(argv, env, io, deps) {
         // 3. The lens set: --lenses, else AIGENCY_REVIEW_LENSES, else bundled.
         const lensPath = parsed.lenses ?? present(env['AIGENCY_REVIEW_LENSES']);
         const source = derived !== undefined
-            ? `practices in ${parsed.practices ?? ''} (derived: one lens per lens: value)`
+            ? `practices in ${practicesDir ?? ''} (derived: one lens per lens: value)`
             : (lensPath ?? 'bundled default lenses (aigency-governance review/lenses.json @ de238aa)');
         let lensSet;
         try {
@@ -456,6 +480,11 @@ export async function main(argv, env, io, deps) {
             return 0;
         }
         // 4. The panel.
+        if (temperature !== undefined && route === 'claude-cli') {
+            // The claude-cli transport has no temperature option: say so, never ignore silently.
+            io.stderr(`warning: ${temperatureLine(route, temperature)} ` +
+                `(AIGENCY_REVIEW_TEMPERATURE=${String(temperature)} was not applied)\n`);
+        }
         const calls = [];
         const result = await runReviewNode({
             subject,
@@ -465,19 +494,31 @@ export async function main(argv, env, io, deps) {
             account,
             model,
             maxTokens,
+            ...(temperature === undefined ? {} : { temperature }),
             ...(deps.reviewer === undefined ? {} : { reviewer: deps.reviewer }),
             warmFirst: parsed.warmFirst,
             dedup: parsed.dedup,
             ...(derived === undefined
                 ? {}
-                : { tierSignals: derived.signals, practiceNames: derived.practiceNames }),
+                : {
+                    tierSignals: derived.signals,
+                    tierRejects: derived.rejects,
+                    practiceIds: derived.practiceIds,
+                    practiceNames: derived.practiceNames,
+                }),
         }, (call) => void calls.push(call));
         for (const line of usageLines(calls))
             io.stderr(line);
         const tier = tierLine(result.downgraded);
         if (tier !== undefined)
             io.stderr(`${tier}\n`);
-        const footer = `\n\n${renderFooter(model, route, calls, result.downgraded)}`;
+        const promotion = promotedLine(result.promoted);
+        if (promotion !== undefined)
+            io.stderr(`${promotion}\n`);
+        // Audit trail for tier decisions behind merged groups: stderr, not the report (see dedup.ts).
+        for (const line of result.dedupAudit)
+            io.stderr(line);
+        const footer = `\n\n${renderFooter(model, route, calls, result.downgraded, result.promoted, temperature)}`;
         const note = derived !== undefined && derived.untagged.length > 0
             ? `\n\n> ${String(derived.untagged.length)} practice(s) had no "lens:" tag and were ` +
                 `not reviewed: ${derived.untagged.join(', ')}`

package/dist/context-files.d.ts

@@ -10,6 +10,12 @@ export interface ContextFs {
         readonly isFile: boolean;
     }>;
     readonly readFile: (path: string) => Promise<string>;
+    /**
+     * lstat-based: true when the path itself is a symbolic link (not followed). Rejects with an
+     * fs-style `code` if absent. REQUIRED: a security check must fail closed, so a host that
+     * cannot answer does not compile rather than silently skipping the refusal.
+     */
+    readonly isSymlink: (path: string) => Promise<boolean>;
 }
 export interface DiffPath {
     readonly path: string;
@@ -25,6 +31,12 @@ export interface DiffPath {
 export declare function diffPaths(diff: string): DiffPath[];
 /** Why a diff-supplied path must not be read, or undefined if it is acceptable. */
 export declare function unsafePathReason(path: string): string | undefined;
+/**
+ * True when any component of `rel` (taken under `prefix`, which ends in `/`) is a symbolic link.
+ * Never follows one: each cumulative path is lstat-ed. An absent component ends the walk
+ * (the caller's realpath reports absence); any other lstat failure counts as a refusal.
+ */
+export declare function hasSymlinkComponent(prefix: string, rel: string, fs: ContextFs): Promise<boolean>;
 /**
  * Build the body of the "Changed files in full" section for `diff`, reading
  * from `root`. Throws only when the root itself cannot be resolved; every

package/dist/context-files.js

@@ -7,7 +7,9 @@
 // untrusted. A path is refused (never read) when it is absolute, contains a
 // `..` segment or a NUL; and the resolved real path of every candidate must
 // stay inside the real path of the context root, so a symlink pointing out
-// of the tree is refused too. Refusals are listed in the section, not thrown.
+// of the tree is refused too. The host must supply `isSymlink` (an lstat; required, so the
+// check fails closed): a path is also refused when ANY of its components is a symbolic link,
+// even one pointing inside the root. A symlink is never followed. Refusals are listed in the section, not thrown.
 //
 // PURE-ish: all disk access goes through the injected `ContextFs`, so tests
 // use fakes.
@@ -84,6 +86,29 @@ function isAbsent(cause) {
     const code = cause.code;
     return code === 'ENOENT' || code === 'ENOTDIR';
 }
+/**
+ * True when any component of `rel` (taken under `prefix`, which ends in `/`) is a symbolic link.
+ * Never follows one: each cumulative path is lstat-ed. An absent component ends the walk
+ * (the caller's realpath reports absence); any other lstat failure counts as a refusal.
+ */
+export async function hasSymlinkComponent(prefix, rel, fs) {
+    const check = fs.isSymlink;
+    let current = prefix;
+    for (const part of rel.split('/')) {
+        if (part === '' || part === '.')
+            continue;
+        current = `${current}${part}`;
+        try {
+            if (await check(current))
+                return true;
+        }
+        catch (cause) {
+            return !isAbsent(cause);
+        }
+        current = `${current}/`;
+    }
+    return false;
+}
 function describe(cause) {
     return cause instanceof Error ? cause.message : String(cause);
 }
@@ -120,6 +145,10 @@ export async function buildFileContext(diff, root, fs) {
             skipped.push(`- \`${label}\`: refused (${unsafe})`);
             continue;
         }
+        if (await hasSymlinkComponent(prefix, entry.path, fs)) {
+            skipped.push(`- \`${label}\`: not shown: ${label} is a symbolic link`);
+            continue;
+        }
         let real;
         try {
             real = await fs.realpath(`${prefix}${entry.path}`);

package/dist/dedup.d.ts

@@ -29,6 +29,12 @@ export type DedupResult = {
 };
 /** Ask the model to group `items`; members come back in their input order. */
 export declare function dedupFindings(items: readonly NumberedFinding[], review: Reviewer): Promise<DedupResult>;
+/**
+ * The audit trail of every MERGED group (two or more members): one stderr line per member, with
+ * its own lens id, tier and text, because the report shows only the highest-tier member's text.
+ * Singletons are not listed: the report already shows them as they are.
+ */
+export declare function dedupAuditLines(groups: readonly (readonly NumberedFinding[])[]): string[];
 /**
  * The report view of each group: the highest tier among its members, the text of its highest-tier member (the first blocking one, else the first),
  * and who raised it, naming the practices of each lens that the members' text mentions (by id

package/dist/dedup.js

@@ -51,7 +51,8 @@ export function buildDedupPrompt(items) {
         'Reply with ONLY a JSON array of arrays of ids, for example ' +
             '[["a:0","b:1"],["a:1"],["b:0"]]. No prose, no markdown fence, no verdict line.',
     ].join('\n');
-    return { shared, perLens };
+    // `cache: false`: no other call reads this `shared`, so a cache write is pure cost.
+    return { shared, perLens, cache: false };
 }
 /** Parse and validate a reply: every one of `ids` in exactly one group. */
 export function parseGroups(reply, ids) {
@@ -119,6 +120,23 @@ export async function dedupFindings(items, review) {
         .sort((a, b) => (position.get(a[0]?.id ?? '') ?? 0) - (position.get(b[0]?.id ?? '') ?? 0));
     return { ok: true, groups };
 }
+/**
+ * The audit trail of every MERGED group (two or more members): one stderr line per member, with
+ * its own lens id, tier and text, because the report shows only the highest-tier member's text.
+ * Singletons are not listed: the report already shows them as they are.
+ */
+export function dedupAuditLines(groups) {
+    const lines = [];
+    groups.forEach((members, index) => {
+        if (members.length < 2)
+            return;
+        for (const { id, finding } of members) {
+            const text = `${finding.summary} ${finding.detail ?? ''}`.replace(/\s+/g, ' ').trim();
+            lines.push(`dedup group ${String(index + 1)}: ${id} [${finding.blocking ? 'blocking' : 'smell'}] ${text}\n`);
+        }
+    });
+    return lines;
+}
 /**
  * The report view of each group: the highest tier among its members, the text of its highest-tier member (the first blocking one, else the first),
  * and who raised it, naming the practices of each lens that the members' text mentions (by id

package/dist/practice-lenses.d.ts

@@ -20,6 +20,10 @@ export interface DerivedLenses {
      * practices' sensors (label stripped). A [blocking] finding must quote one of these.
      */
     readonly signals: Readonly<Record<string, readonly string[]>>;
+    /** Per lens id: only the `_Reject:_` lines of `signals`. A smell quoting one is promoted. */
+    readonly rejects: Readonly<Record<string, readonly string[]>>;
+    /** Every practice id in the corpus (tagged or not): ignored when matching a quote. */
+    readonly practiceIds: readonly string[];
     /** Per lens id: its practices' ids and H1 titles ('' when none), to name them in a report. */
     readonly practiceNames: Readonly<Record<string, readonly {
         readonly id: string;
@@ -60,6 +64,11 @@ export declare function extractSensorHalf(markdown: string): string | undefined;
  * continuation lines (not a new bullet, heading or bold label) are joined onto their line.
  */
 export declare function extractSignalLines(sensor: string): string[];
+/** As `extractSignalLines`, keeping which label each line carried. */
+export declare function extractLabelledSignals(sensor: string): {
+    readonly kind: 'reject' | 'expect';
+    readonly text: string;
+}[];
 /**
  * Group practice files by their `lens:` value and build one lens per group.
  * Files are taken in name order, a top-level README.md and non-.md files are

package/dist/practice-lenses.js

@@ -130,20 +130,25 @@ export function extractSensorHalf(markdown) {
         return undefined;
     return slice.trim();
 }
-const SIGNAL_LINE_RE = /^\s*(?:[-*+]\s+)?[_*]{1,2}(?:Reject|Expect):[_*]{1,2}\s*(.*)$/i;
+const SIGNAL_LINE_RE = /^\s*(?:[-*+]\s+)?[_*]{1,2}(Reject|Expect):[_*]{1,2}\s*(.*)$/i;
 const BLOCK_START_RE = /^\s*(?:[-*+]\s|\d+\.\s|#|\*\*)/;
 /**
  * The text of each `_Reject:_` / `_Expect:_` line in a sensor half, label stripped. Indented
  * continuation lines (not a new bullet, heading or bold label) are joined onto their line.
  */
 export function extractSignalLines(sensor) {
+    return extractLabelledSignals(sensor).map((s) => s.text);
+}
+/** As `extractSignalLines`, keeping which label each line carried. */
+export function extractLabelledSignals(sensor) {
     const out = [];
     const lines = sensor.split(/\r?\n/);
     for (let i = 0; i < lines.length; i++) {
         const match = SIGNAL_LINE_RE.exec(lines[i] ?? '');
         if (match === null)
             continue;
-        let text = (match[1] ?? '').trim();
+        const kind = (match[1] ?? '').toLowerCase() === 'reject' ? 'reject' : 'expect';
+        let text = (match[2] ?? '').trim();
         while (i + 1 < lines.length) {
             const next = lines[i + 1] ?? '';
             if (next.trim() === '' || !/^\s+\S/.test(next) || BLOCK_START_RE.test(next))
@@ -152,7 +157,7 @@ export function extractSignalLines(sensor) {
             i++;
         }
         if (text !== '')
-            out.push(text);
+            out.push({ kind, text });
     }
     return out;
 }
@@ -169,11 +174,14 @@ export function deriveLensSet(files) {
         .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
     const byLens = new Map();
     const signals = {};
+    const rejects = {};
+    const practiceIds = [];
     const practiceNames = {};
     const untagged = [];
     const missingSensor = [];
     for (const file of eligible) {
         const id = file.name.slice(0, -'.md'.length);
+        practiceIds.push(id);
         const lensId = parseLensFrontmatter(file.text);
         if (lensId === undefined) {
             untagged.push(id);
@@ -186,7 +194,9 @@ export function deriveLensSet(files) {
         const title = parseTitle(file.text);
         group.push({ id, title, sensor });
         byLens.set(lensId, group);
-        (signals[lensId] ??= []).push(...(sensor === undefined ? [] : extractSignalLines(sensor)));
+        const labelled = sensor === undefined ? [] : extractLabelledSignals(sensor);
+        (signals[lensId] ??= []).push(...labelled.map((s) => s.text));
+        (rejects[lensId] ??= []).push(...labelled.filter((s) => s.kind === 'reject').map((s) => s.text));
         (practiceNames[lensId] ??= []).push({ id, title: title ?? '' });
     }
     const lensIds = [...byLens.keys()].sort();
@@ -213,6 +223,8 @@ export function deriveLensSet(files) {
         untagged,
         missingSensor,
         signals,
+        rejects,
+        practiceIds,
         practiceNames,
     };
 }

package/dist/prompt.d.ts

@@ -94,6 +94,9 @@ export interface Prompt {
     readonly shared: string;
     /** The only part that varies by lens. Goes last. */
     readonly perLens: string;
+    /** `false` for a call whose `shared` no other call reads (the dedup call): a transport that
+     * marks `shared` cacheable must not, as the cache write would never be read. */
+    readonly cache?: false;
 }
 /** The two halves in the one order that preserves the shared prefix. */
 export declare function renderPrompt(prompt: Prompt): string;

package/dist/references.js

@@ -9,7 +9,7 @@
 // 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';
+import { diffPaths, hasSymlinkComponent, 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. */
@@ -145,6 +145,10 @@ async function resolveAdr(ref, root, files, fs) {
     const parts = [];
     for (const rel of hits) {
         try {
+            if (await hasSymlinkComponent(root.prefix, rel, fs)) {
+                parts.push(`${rel} (not shown: ${rel} is a symbolic link)`);
+                continue;
+            }
             const real = await fs.realpath(`${root.prefix}${rel}`);
             if (!inside(root, real)) {
                 parts.push(`${rel} (refused: resolves outside the context root)`);
@@ -214,8 +218,11 @@ async function resolvePath(ref, root, fs, deleted, maxVisited) {
         return `refused (${unsafe})`;
     const segments = ref.target.split('/');
     const bare = segments.length === 1;
-    // A real repo-relative path always wins.
+    // A real repo-relative path always wins. A symlink is never followed, even to check existence.
     try {
+        if (await hasSymlinkComponent(root.prefix, ref.target, fs)) {
+            return `not shown: ${ref.target} is a symbolic link`;
+        }
         const real = await fs.realpath(`${root.prefix}${ref.target}`);
         if (!inside(root, real))
             return 'refused (resolves outside the context root)';