@verevoir/review 0.3.1 → 0.3.3

package/README.md

@@ -1,5 +1,8 @@
 # @verevoir/review
 
+**Adopting it? Start with [docs/ADOPTING.md](docs/ADOPTING.md)**: review a change locally in one
+command, or add it as a pre-push gate or a GitHub review stage.
+
 The review panel: lens-based diff review, fanned out across every declared
 lens with a shared cached prefix, aggregated into one verdict with a
 fail-closed outcome rule. One implementation, consumed by pump-internal
@@ -103,90 +106,20 @@ never folded into a generic failure.
 
 ## Consuming this library
 
-This is a **private** repository, consumed as a pinned git dependency --
-never via npm's registry, and never floating on a branch or tag.
-
-1. **Pin the full commit sha**, in `git+https://` form, never the
-   `github:owner/repo#sha` shorthand (npm's resolution of that
-   shorthand's own transport -- ssh vs https -- isn't guaranteed, and
-   the CI step below only works if npm goes over https):
-
-   ```json
-   "@verevoir/review": "git+https://github.com/verevoir/review.git#<full-sha>"
-   ```
-
-   A branch or tag is never acceptable here: this repo merges on green
-   (see "Merge policy" below), with no human gate between a PR and
-   `main` moving -- a consumer floating on `main` would pick up a change
-   with no review of its own on this side of the boundary. Pin the exact
-   sha you have actually run the ratchet against (or, for a mechanical
-   bump with no behaviour change, the exact sha you have confirmed
-   carries one).
-
-2. **Add `REVIEW_READ_TOKEN` as a repository secret** in the consumer's
-   own CI -- a fine-grained PAT scoped to `contents: read` on
-   `verevoir/review` ONLY. This repository is private, and a consumer's
-   ambient `GITHUB_TOKEN` cannot see a different private repository.
-   `REVIEW_READ_TOKEN` is the operator's standing secret name for every
-   consumer of this library -- used for nothing else, so it can stay
-   scoped this narrowly without colliding with any other credential a
-   consumer's CI might hold.
-
-3. **Before `npm ci` (or equivalent), rewrite git URLs for this
-   dependency's exact URL only** -- never every `https://github.com/`
-   URL -- then run the install with NO lifecycle scripts, remove the
-   rewrite immediately, and only then run the scripts that were skipped:
-
-   ```yaml
-   - run: |
-       if [ -z "${{ secrets.REVIEW_READ_TOKEN }}" ]; then
-         echo "::error::REVIEW_READ_TOKEN is not set (or is blank) -- required to install the private @verevoir/review git dependency over https."
-         exit 1
-       fi
-   - run: git config --global url."https://x-access-token:${{ secrets.REVIEW_READ_TOKEN }}@github.com/verevoir/review.git".insteadOf "https://github.com/verevoir/review.git"
-   - run: npm ci --ignore-scripts
-   - run: git config --global --unset url."https://x-access-token:${{ secrets.REVIEW_READ_TOKEN }}@github.com/verevoir/review.git".insteadOf
-     if: always()
-   - run: npm rebuild
-   - run: npm run build --prefix node_modules/@verevoir/review
-   ```
-
-   **Why `--ignore-scripts` plus the two steps after, not just the scoped
-   rewrite and an unset** -- an earlier version of this guidance claimed
-   scoping the rewrite to one URL meant the token was never exposed to
-   "any other dependency's install script". That was wrong, caught by a
-   lens-review round on a real consumer's cutover branch, scored
-   blocking: URL scoping only limits which git operations the rewrite
-   applies to. It does nothing to stop a DIFFERENT package's own
-   install/postinstall script from reading `~/.gitconfig` directly, as a
-   file -- any process in the job can do that regardless of which URL
-   the rewrite names. `--ignore-scripts` is what actually closes this:
-   no package's lifecycle script runs while the token is present. The
-   rewrite is then unset (`if: always()`, so a failed `npm ci` does not
-   leave it behind either), and only then do the deferred scripts run --
-   `npm rebuild` for every other dependency's own install/postinstall
-   (native modules among them, if your consumer has any), and an
-   explicit build of **this package's own** `dist/` specifically,
-   because it is gitignored here and normally produced by this
-   package's `prepare` script -- which `--ignore-scripts` also skipped,
-   and which `npm rebuild` does not run (rebuild covers preinstall/
-   install/postinstall only, never prepare).
-
-   **The precise claim this now supports**: the token exists in
-   `~/.gitconfig` only across the url.insteadOf write and
-   `npm ci --ignore-scripts` itself -- an install that runs no package
-   script. Nothing after that point can read it. The one residual,
-   accepted exposure is whatever npm does internally to fetch the git
-   dependency during that one command -- unavoidable, since that is the
-   minimum npm needs to resolve a private git dependency at all.
-
-   Run this on every CI leg/matrix entry that installs dependencies -- a
-   leg that skips it fails `npm ci` outright and loudly (a missing
-   credential), never silently.
-
-This is the exact mechanism in place on `aigency-runtime-v2`'s own
-`verify.yml`, on its consumer-cutover branch (held for operator review,
-per that repository's own protected-paths rule).
+`@verevoir/review` is **public on npm**. Install it from the registry, pinned to an exact version,
+never a range or a dist-tag:
+
+```sh
+npm install --save-exact @verevoir/review@0.3.2
+```
+
+The package carries its own `dist/`, so no build step is needed. To run the command line without
+installing anything, see "Command line" below and [docs/ADOPTING.md](docs/ADOPTING.md).
+
+A pinned version matters because this repo merges on green (see "Merge policy" below), with no
+human gate between a PR and `main` moving: a consumer floating on a range would pick up a change
+with no review of its own on this side of the boundary. Pin the exact version you have actually
+run the ratchet against.
 
 ## Round-aware review (opt-in)
 
@@ -304,8 +237,8 @@ blocking findings before calling `runPanel`/`runReviewNode` again.
 public one that cannot call governance's private reusable workflow:
 
 ```sh
-npx -y @verevoir/review aigency-review --base origin/main --title "My change"
-git diff origin/main...HEAD | npx -y @verevoir/review aigency-review
+npx -y -p @verevoir/review@0.3.2 aigency-review --base origin/main --title "My change"
+git diff origin/main...HEAD | npx -y -p @verevoir/review@0.3.2 aigency-review
 ```
 
 **Flags**
@@ -374,6 +307,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 +323,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.
@@ -423,11 +366,17 @@ v2); no YAML library.
 - uses: actions/checkout@v4
   with:
     fetch-depth: 0
-- run: npx -y @verevoir/review@<next> aigency-review --base origin/${{ github.base_ref }} --title "${{ github.event.pull_request.title }}"
+- run: npx -y -p @verevoir/review@0.3.2 aigency-review --base "origin/${BASE_REF}" --title "${PR_TITLE}"
   env:
     ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+    BASE_REF: ${{ github.base_ref }}
+    PR_TITLE: ${{ github.event.pull_request.title }}
 ```
 
+Values reach the shell through `env:`, never through `${{ }}` inside `run:`. For the hardened,
+copy-and-use version (SHA-pinned actions, minimal permissions, check results, a corpus) see
+[docs/ADOPTING.md](docs/ADOPTING.md) and `examples/github/review.yml`.
+
 ## Merge policy
 
 Merges on green, same as this organisation's other rebuild repos. "Green"

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

@@ -6,6 +6,23 @@ export declare function modelText(requested: string, calls: readonly RawCall[]):
 export declare function tierLine(downgraded: number): string | undefined;
 /** The one line saying how many smells tier enforcement promoted to [blocking]; none for 0. */
 export declare function promotedLine(promoted: number): string | undefined;
-export declare function renderFooter(requested: string, route: RouteName, calls: readonly RawCall[], downgraded?: number, promoted?: number): string;
+/** Said when Reject promotion was switched off because every changed file is documentation. */
+export declare const PROMOTION_OFF_LINE = "Tier: promotion off: every changed file is documentation";
+/** Said when the spec framing was added but there is no tier, so no promotion to switch off. */
+export declare const SPEC_FRAMING_LINE = "Spec framing: every changed file is documentation (no tier signals, so promotion is not in play)";
+/** Said when a changed path could not be determined, so the diff is not treated as documentation. */
+export declare const PATH_UNDETERMINED_LINE = "Documentation check: a changed path could not be determined, so the diff is not treated as documentation (promotion stays on)";
+/** The one line saying how the documentation check affected this review; none when it did not. */
+export declare function docsLine(result: {
+    readonly promotionOff: boolean;
+    readonly docsOnly: boolean;
+    readonly pathUndetermined: boolean;
+}): 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, docsNote?: string): string;
 /** One stderr line per lens. */
 export declare function usageLines(calls: readonly RawCall[]): string[];

package/dist/cli/footer.js

@@ -42,14 +42,47 @@ export function promotedLine(promoted) {
         ? `Tier: ${String(promoted)} finding(s) promoted: quotes a Reject signal`
         : undefined;
 }
-export function renderFooter(requested, route, calls, downgraded = 0, promoted = 0) {
-    const lines = ['---', '', `Judged with ${modelText(requested, calls)}, route: ${route}.`];
+/** Said when Reject promotion was switched off because every changed file is documentation. */
+export const PROMOTION_OFF_LINE = 'Tier: promotion off: every changed file is documentation';
+/** Said when the spec framing was added but there is no tier, so no promotion to switch off. */
+export const SPEC_FRAMING_LINE = 'Spec framing: every changed file is documentation (no tier signals, so promotion is not in play)';
+/** Said when a changed path could not be determined, so the diff is not treated as documentation. */
+export const PATH_UNDETERMINED_LINE = 'Documentation check: a changed path could not be determined, so the diff is not treated as documentation (promotion stays on)';
+/** The one line saying how the documentation check affected this review; none when it did not. */
+export function docsLine(result) {
+    if (result.promotionOff)
+        return PROMOTION_OFF_LINE;
+    if (result.docsOnly)
+        return SPEC_FRAMING_LINE;
+    return result.pathUndetermined ? PATH_UNDETERMINED_LINE : 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, docsNote) {
+    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 (docsNote !== undefined)
+        lines.push('', docsNote);
     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 { promotedLine, renderFooter, tierLine, usageLines } from './footer.js';
+import { docsLine, 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,6 +494,7 @@ 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,
@@ -485,10 +515,13 @@ export async function main(argv, env, io, deps) {
         const promotion = promotedLine(result.promoted);
         if (promotion !== undefined)
             io.stderr(`${promotion}\n`);
+        const docsNote = docsLine(result);
+        if (docsNote !== undefined)
+            io.stderr(`${docsNote}\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)}`;
+        const footer = `\n\n${renderFooter(model, route, calls, result.downgraded, result.promoted, temperature, docsNote)}`;
         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;
@@ -23,8 +29,40 @@ export interface DiffPath {
  * path so the caller can say it was skipped.
  */
 export declare function diffPaths(diff: string): DiffPath[];
+/**
+ * EVERY path a diff changes, for deciding what kind of change it is (not for reading files).
+ * Unlike diffPaths it also sees what git writes WITHOUT `---`/`+++` headers: a pure rename
+ * (`rename from` / `rename to`), a copy, a binary change (`Binary files A and B differ`) and a
+ * mode-only change (the `diff --git` line itself). Both sides of a rename and the old path of a
+ * deletion are included, so moving code into a .md file is not a documentation change. A path
+ * that cannot be determined is reported as '' so the caller treats the diff as not understood.
+ * A diff with no `diff --git` lines (plain unified) falls back to diffPaths.
+ */
+export declare function changedPaths(diff: string): string[];
+/** Documentation by FILE TYPE (.md .mdx .rst .adoc, any depth; not .txt, which also names requirements.txt and CMakeLists.txt); a directory name alone is not enough. */
+export declare function isDocumentationPath(path: string): boolean;
+/**
+ * True when the diff changes at least one file and EVERY changed path is documentation. Drives
+ * the tier (promotion off) and the spec framing. Paths come from changedPaths; one that cannot
+ * be determined makes the diff NOT docs-only, so promotion stays on.
+ */
+export declare function isDocumentationOnly(diff: string): boolean;
+export interface DiffClassification {
+    /** At least one changed file, and every one is documentation. */
+    readonly documentationOnly: boolean;
+    /** At least one changed path could not be determined (so the diff is never docs-only). */
+    readonly undeterminedPath: boolean;
+}
+/** The single classification of a diff: callers compute it once and pass the answer down. */
+export declare function classifyDiff(diff: string): DiffClassification;
 /** 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.
@@ -67,6 +69,119 @@ export function diffPaths(diff) {
     }
     return out;
 }
+function stripEither(path) {
+    return path.startsWith('a/') || path.startsWith('b/') ? path.slice(2) : path;
+}
+/** The `a/X b/X` header of a `diff --git` line, when both halves are the same path. */
+function gitHeaderPath(line) {
+    const rest = line.slice('diff --git '.length);
+    if (rest.startsWith('"'))
+        return undefined;
+    const mid = (rest.length - 1) / 2;
+    if (!Number.isInteger(mid) || rest[mid] !== ' ')
+        return undefined;
+    const left = rest.slice(0, mid);
+    const right = rest.slice(mid + 1);
+    if (!left.startsWith('a/') || !right.startsWith('b/'))
+        return undefined;
+    return left.slice(2) === right.slice(2) ? left.slice(2) : undefined;
+}
+/**
+ * EVERY path a diff changes, for deciding what kind of change it is (not for reading files).
+ * Unlike diffPaths it also sees what git writes WITHOUT `---`/`+++` headers: a pure rename
+ * (`rename from` / `rename to`), a copy, a binary change (`Binary files A and B differ`) and a
+ * mode-only change (the `diff --git` line itself). Both sides of a rename and the old path of a
+ * deletion are included, so moving code into a .md file is not a documentation change. A path
+ * that cannot be determined is reported as '' so the caller treats the diff as not understood.
+ * A diff with no `diff --git` lines (plain unified) falls back to diffPaths.
+ */
+export function changedPaths(diff) {
+    const lines = diff.split(/\r?\n/);
+    if (!lines.some((l) => l.startsWith('diff --git '))) {
+        return diffPaths(diff).map((p) => p.path);
+    }
+    const out = new Set();
+    let block = [];
+    const flush = () => {
+        if (block.length === 0)
+            return;
+        const found = [];
+        let bad = false;
+        const take = (raw, strip) => {
+            const value = unquote(raw);
+            if (value === undefined || value === '')
+                bad = true;
+            else if (value !== '/dev/null')
+                found.push(strip ? stripEither(value) : value);
+        };
+        for (const line of block.slice(1)) {
+            if (line.startsWith('@@'))
+                break;
+            if (line.startsWith('rename from '))
+                take(line.slice(12), false);
+            else if (line.startsWith('rename to '))
+                take(line.slice(10), false);
+            else if (line.startsWith('copy from '))
+                take(line.slice(10), false);
+            else if (line.startsWith('copy to '))
+                take(line.slice(8), false);
+            else if (line.startsWith('--- ') || line.startsWith('+++ '))
+                take(line.slice(4), true);
+            else {
+                const binary = /^Binary files (.+) and (.+) differ$/.exec(line);
+                if (binary !== null) {
+                    take(binary[1] ?? '', true);
+                    take(binary[2] ?? '', true);
+                }
+            }
+        }
+        if (found.length === 0 && !bad) {
+            const header = gitHeaderPath(block[0] ?? '');
+            if (header === undefined)
+                bad = true;
+            else
+                found.push(header);
+        }
+        if (bad)
+            out.add('');
+        for (const p of found)
+            out.add(p);
+    };
+    for (const line of lines) {
+        if (line.startsWith('diff --git ')) {
+            flush();
+            block = [line];
+        }
+        else if (block.length > 0) {
+            block.push(line);
+        }
+    }
+    flush();
+    return [...out];
+}
+/** A documentation file type, at any depth. BACKLOG.md is covered by .md. */
+const DOCUMENTATION_FILE = /\.(?:md|mdx|rst|adoc)$/i;
+/** Documentation by FILE TYPE (.md .mdx .rst .adoc, any depth; not .txt, which also names requirements.txt and CMakeLists.txt); a directory name alone is not enough. */
+export function isDocumentationPath(path) {
+    return DOCUMENTATION_FILE.test(path);
+}
+/**
+ * True when the diff changes at least one file and EVERY changed path is documentation. Drives
+ * the tier (promotion off) and the spec framing. Paths come from changedPaths; one that cannot
+ * be determined makes the diff NOT docs-only, so promotion stays on.
+ */
+export function isDocumentationOnly(diff) {
+    return classifyDiff(diff).documentationOnly;
+}
+/** The single classification of a diff: callers compute it once and pass the answer down. */
+export function classifyDiff(diff) {
+    const paths = changedPaths(diff);
+    const undeterminedPath = paths.includes('');
+    return {
+        documentationOnly: paths.length > 0 && !undeterminedPath && paths.every((p) => isDocumentationPath(p)),
+        undeterminedPath,
+    };
+}
 /** Why a diff-supplied path must not be read, or undefined if it is acceptable. */
 export function unsafePathReason(path) {
     if (path === '')
@@ -84,6 +199,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 +258,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/prompt.d.ts

@@ -76,6 +76,12 @@ export interface Subject {
      * `buildPrompt` below for exactly how that slice is picked out.
      */
     readonly priorFindings?: ReadonlyArray<PriorFinding>;
+    /**
+     * Whether every changed file is documentation (context-files.ts classifyDiff). A caller that
+     * has already classified the diff passes the answer so it is decided once; absent, buildPrompt
+     * classifies `diff` itself. True adds SPEC_FRAMING to the shared prefix.
+     */
+    readonly docsOnly?: boolean;
 }
 /**
  * The two halves of what a reviewer is shown.
@@ -116,6 +122,8 @@ export declare const NO_PRACTICES_NOTICE = "No practices were supplied for this
  * disclosed, not silently unnoticed.
  */
 export declare const NO_REQUIREMENT_NOTICE: string;
+/** Added to the shared prefix when every changed file is documentation (see below). */
+export declare const SPEC_FRAMING = "This change is a specification or plan. Block only where its text commits to behaviour a practice rejects. Where it merely doesn't rule out a case, raise a smell.";
 /** Heading of the shared check-results section (`Subject.checks`). */
 export declare const CHECKS_HEADING = "## Checks on this change";
 /** Heading of the shared resolved-references section (`Subject.references`). */