@verevoir/review 0.3.2 → 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**
@@ -433,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/footer.d.ts

@@ -6,11 +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;
+/** 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): 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,6 +42,20 @@ export function promotedLine(promoted) {
         ? `Tier: ${String(promoted)} finding(s) promoted: quotes a Reject signal`
         : undefined;
 }
+/** 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.
@@ -53,7 +67,7 @@ export function temperatureLine(route, temperature) {
         ? 'temperature: not supported on the claude-cli route'
         : `temperature: ${String(temperature)}`;
 }
-export function renderFooter(requested, route, calls, downgraded = 0, promoted = 0, temperature) {
+export function renderFooter(requested, route, calls, downgraded = 0, promoted = 0, temperature, docsNote) {
     const lines = [
         '---',
         '',
@@ -67,6 +81,8 @@ export function renderFooter(requested, route, calls, downgraded = 0, promoted =
     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.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, temperatureLine, 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). */
@@ -515,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, temperature)}`;
+        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

@@ -29,6 +29,32 @@ 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;
 /**

package/dist/context-files.js

@@ -69,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 === '')

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`). */

package/dist/prompt.js

@@ -38,6 +38,7 @@
 // tests/review-round-aware.test.ts's own byte-identical pin, which
 // reproduces this file's PRE-feature template independently and asserts
 // equality against it.
+import { isDocumentationOnly } from './context-files.js';
 import { REPLY_CONTRACT, RULING_MARKER, RULING_RESOLVED_WORD, RULING_UNRESOLVED_WORD, } from './replyContract.js';
 /** The two halves in the one order that preserves the shared prefix. */
 export function renderPrompt(prompt) {
@@ -63,6 +64,8 @@ export const NO_REQUIREMENT_NOTICE = 'No requirement text was supplied for this
     "context -- is this run's own account of its own work; there is nothing " +
     'from outside the run to check it against. Say so plainly in your ' +
     'reasoning, and judge only whether the change is coherent on its own terms.';
+/** Added to the shared prefix when every changed file is documentation (see below). */
+export 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 const CHECKS_HEADING = '## Checks on this change';
 /** Heading of the shared resolved-references section (`Subject.references`). */
@@ -173,9 +176,11 @@ export function buildPrompt(lens, subject, practices, placement = 'shared') {
     const priorFindingsSection = hasPriorFindings
         ? ['', PRIOR_FINDINGS_HEADING, '', ...rulingSection, '', ...independentReviewSection]
         : [];
+    const specification = subject.docsOnly ?? isDocumentationOnly(subject.diff);
     const shared = [
         'You are one lens of a review panel. Several reviewers are reading this same change, each along a different dimension, and their verdicts are combined. Review only your own dimension: another lens is covering the rest, and a finding outside your dimension is noise in someone else’s report.',
         '',
+        ...(specification ? [SPEC_FRAMING, ''] : []),
         ...barInShared,
         '## Requirement',
         '',

package/dist/run-review.d.ts

@@ -68,6 +68,12 @@ export interface ReviewNodeResult {
     readonly downgraded: number;
     /** How many smells tier enforcement promoted to [blocking] (0 when none). */
     readonly promoted: number;
+    /** True when Reject promotion was switched off because every changed file is documentation. */
+    readonly promotionOff: boolean;
+    /** True when every changed file is documentation, whether or not a tier applied. */
+    readonly docsOnly: boolean;
+    /** True when a changed path could not be determined, so the diff was not treated as docs-only. */
+    readonly pathUndetermined: boolean;
     /** Stderr lines, one per member of every merged dedup group (empty when none merged). */
     readonly dedupAudit: readonly string[];
 }

package/dist/run-review.js

@@ -29,6 +29,7 @@
 //   - `citedContext` (a caller-curated prose field) is accepted and
 //     forwarded if a caller supplies it, but nothing here computes one --
 //     unchanged from v5, where this was also true.
+import { classifyDiff } from './context-files.js';
 import { runPanel } from './panel.js';
 import { exitCodeFor, renderReport } from './report.js';
 import { selectReviewer } from './reviewer-selection.js';
@@ -113,12 +114,20 @@ export async function runReviewNode(input, onCall) {
     const dispatched = input.warmFirst === true && input.lensSet.lenses.length >= 2
         ? warmFirst(observedReviewer)
         : observedReviewer;
-    const panel = await runPanel(input.lensSet, input.subject, dispatched, input.practices);
+    // The docs-only decision is made ONCE, here (context-files.ts classifyDiff). It reaches the
+    // prompt through the subject (spec framing, every mode) and the tier below (promotion off).
+    const docs = classifyDiff(input.subject.diff);
+    const subject = { ...input.subject, docsOnly: docs.documentationOnly };
+    const panel = await runPanel(input.lensSet, subject, dispatched, input.practices);
     const prompts = panel.prompts;
+    // Promotion is off when every changed file in the parsed diff is documentation
+    // (classified above by context-files.ts); with no tier signals there is no promotion to turn off.
+    const promotionOff = input.tierSignals !== undefined && docs.documentationOnly;
     // 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, {
+            ...(promotionOff ? { promote: false } : {}),
             ...(input.tierRejects === undefined ? {} : { rejects: input.tierRejects }),
             ...(input.practiceIds === undefined ? {} : { practiceIds: input.practiceIds }),
         });
@@ -151,6 +160,9 @@ export async function runReviewNode(input, onCall) {
         prompts,
         downgraded: tiered.downgraded,
         promoted: tiered.promoted,
+        promotionOff,
+        docsOnly: docs.documentationOnly,
+        pathUndetermined: docs.undeterminedPath,
         dedupAudit,
     };
 }

package/dist/tier.d.ts

@@ -16,6 +16,11 @@ export interface TierContext {
     readonly rejects?: Readonly<Record<string, readonly string[]>>;
     /** Every practice id in the corpus, ignored when matching. */
     readonly practiceIds?: readonly string[];
+    /**
+     * False turns Reject-quote promotion off (every changed file is documentation; see
+     * context-files.ts isDocumentationOnly). The C1 downgrade is unaffected. Default true.
+     */
+    readonly promote?: boolean;
 }
 export interface TierResult {
     readonly verdict: Verdict;

package/dist/tier.js

@@ -122,7 +122,8 @@ export function enforceTier(verdict, signals, context = {}) {
         if (!Object.prototype.hasOwnProperty.call(signals, result.lens))
             return result;
         const own = signals[result.lens] ?? [];
-        const rejectLines = context.rejects !== undefined &&
+        const rejectLines = context.promote !== false &&
+            context.rejects !== undefined &&
             Object.prototype.hasOwnProperty.call(context.rejects, result.lens)
             ? (context.rejects[result.lens] ?? [])
             : undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verevoir/review",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "The review panel: lens-based diff review. One implementation, consumed by pump-internal review, local preflight, eval-review, and CI.",
   "license": "Apache-2.0",
   "type": "module",
@@ -18,7 +18,6 @@
   "files": [
     "dist",
     "lenses.default.json",
-    "npm-shrinkwrap.json",
     "src",
     "tsconfig.json",
     "tsconfig.build.json",

package/src/cli/footer.ts

@@ -53,6 +53,28 @@ export function promotedLine(promoted: number): string | undefined {
     : undefined;
 }
 
+/** 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: {
+  readonly promotionOff: boolean;
+  readonly docsOnly: boolean;
+  readonly pathUndetermined: boolean;
+}): string | undefined {
+  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.
@@ -71,6 +93,7 @@ export function renderFooter(
   downgraded = 0,
   promoted = 0,
   temperature?: number,
+  docsNote?: string,
 ): string {
   const lines = [
     '---',
@@ -83,6 +106,7 @@ export function renderFooter(
   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/src/cli/review.ts

@@ -31,7 +31,14 @@ import { buildFileContext, NO_FILE_CONTEXT_NOTE } from '../context-files.js';
 import { buildReferences } from '../references.js';
 import type { DirEntry } from '../references.js';
 import type { RawCall } from '../raw-call.js';
-import { promotedLine, renderFooter, temperatureLine, tierLine, usageLines } from './footer.js';
+import {
+  docsLine,
+  promotedLine,
+  renderFooter,
+  temperatureLine,
+  tierLine,
+  usageLines,
+} from './footer.js';
 import type { RouteName } from './footer.js';
 import type { DerivedLenses } from '../practice-lenses.js';
 
@@ -642,9 +649,11 @@ export async function main(
     if (tier !== undefined) io.stderr(`${tier}\n`);
     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, temperature)}`;
+    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 ` +