fix(review): v0.9.3 pre-release review findings

- Stamp `Installation.VERSION` into `engine.cliVersion` on the signed verdict
  envelope so auditors reconstructing a stored verdict months later can
  identify which policy version generated it. The version is included in the
  canonical body, so tampering breaks the HMAC signature.
- Add `staleManifest` boolean to the envelope, populated when a change-
  affecting source file has been modified after the manifest was written.
  Renames the internal `warnIfStale` to `detectStaleManifest` and removes
  the `opts.head` gate so the local working-tree workflow (compile once,
  edit for an hour, then review) also surfaces the signal instead of
  silently under-warning.
- Emit `tierReasons[]` on the envelope whenever the classifier lands on
  `full` tier, not only when `--explain-tier` / `--force-tier` /
  `pathTokenConfigError` fires. A REQUEST_CHANGES on a schema.yml diff
  now carries the "why" in the PR-comment blockquote by default;
  `trivial` / `lite` stay quiet to avoid noise on approvals.
- Document `--explain-tier`, `--force-tier`, `riskTierPathTokens`, and
  manifest auto-discovery in `docs/docs/usage/dbt-pr-review.md`.

Author: Haider

docs/docs/usage/dbt-pr-review.md

@@ -106,11 +106,13 @@ Options:
 |------|-------------|
 | `--base <ref>` | Base git ref. Defaults to the merge-base with `origin/main`. |
 | `--head <ref>` | Head git ref. Omit to review the working tree. |
-| `--manifest <path>` | Path to the compiled `manifest.json` (default `target/manifest.json`). |
+| `--manifest <path>` | Path to the compiled `manifest.json`. When omitted, the reviewer walks up from the current directory to find the nearest `dbt_project.yml` and uses its adjacent `target/manifest.json`; the discovered path is logged to stderr. |
 | `--mode comment\|gate` | `comment` never blocks; `gate` exits non-zero on `REQUEST_CHANGES`. |
 | `--severity <level>` | Minimum severity to surface: `critical`, `warning`, `suggestion`. |
 | `--post` | Post the verdict to the GitHub PR (uses `GITHUB_TOKEN` + the Actions event). |
 | `--no-ai` | Disable the advisory LLM reviewer lane (no model calls / cost) — deterministic-only. |
+| `--explain-tier` | Emit the classifier's tier-reason list on the verdict envelope so you can see why a diff was rated `trivial`, `lite`, or `full`. Reasons already surface in the PR comment for `full`-tier runs — this flag adds them to `trivial`/`lite` for debugging. |
+| `--force-tier <tier>` | **[EXPERIMENTAL / bench debug]** Bypass the classifier and force `trivial` / `lite` / `full`. The verdict envelope carries `tierForced: true` and the classifier's original decision for audit. |
 | `--json` / `--output <file>` | Emit the verdict envelope as JSON. |
 
 > **Full vs lint-only.** With a compiled `manifest.json` present, the reviewer
@@ -232,6 +234,9 @@ dataDiff:                     # OFF by default — see "Data-diff in CI" below
   warehouse: ""               # connection name; empty = default connection
 exclude:
   - models/legacy/**
+riskTierPathTokens:           # OFF by default — see "Risk-tier path tokens" below
+  finops: [preset:finops]     # promote any FinOps-named path to `full` tier
+  pii: [ssn, email, phone]    # or supply your own case-insensitive tokens
 rubric:
   blockOn: [lineage_breakage, contract_violation, pii_exposure, semantic_change]
   warningPatternThreshold: 3
@@ -242,6 +247,17 @@ rubric:
     skipNonProdModels: true
 ```
 
+### Risk-tier path tokens
+
+Named categories under `riskTierPathTokens` promote any diff touching a matching
+path to `full` review tier, so those areas never auto-approve on `trivial`
+classification. Values are case-insensitive substrings; the `preset:finops` marker
+expands to the built-in FinOps keyword list (cost, billing, spend, revenue, etc.).
+Prior to v0.9.3 the FinOps list was hardcoded and always on; it is now opt-in via
+this config. When a category value is invalid the CLI logs a stderr warning AND
+surfaces the error in the verdict envelope's `tierReasons[]` (and in the PR
+comment), so a typo can't silently kill your opt-in.
+
 ## Data-diff in CI
 
 Static equivalence proves a refactor *can't* change results. **Data-diff** goes

packages/opencode/src/altimate/review/orchestrate.ts

@@ -180,6 +180,8 @@ export interface OrchestrateInput {
   manifestHash?: string
   coreVersion?: string
   modelVersion?: string
+  /** altimate-code CLI release recorded in engine.cliVersion for audit reconstruction. */
+  cliVersion?: string
   /**
    * Optional LLM reviewer lane. Injected (not imported) so the orchestrator
    * stays pure/unit-testable: production wires `runAiReview` (harness LLM);
@@ -194,6 +196,8 @@ export interface OrchestrateInput {
   explainTier?: boolean
   /** G2 — override the classifier's tier decision. Envelope carries tierForced:true. */
   forceTier?: "trivial" | "lite" | "full"
+  /** Manifest was stale relative to change-affecting files (see run.ts::detectStaleManifest). */
+  staleManifest?: boolean
 }
 
 /** Derive the dbt model name from a model file path. */
@@ -1423,17 +1427,19 @@ export async function runReview(input: OrchestrateInput): Promise<VerdictEnvelop
     tier,
     mode: input.mode,
     rubric: input.rubric,
-    engine: { core: input.coreVersion, model: input.modelVersion },
+    engine: { core: input.coreVersion, model: input.modelVersion, cliVersion: input.cliVersion },
     manifestHash: input.manifestHash,
+    staleManifest: input.staleManifest,
     generatedAt: input.generatedAt,
     degraded,
     // Include tierReasons whenever `--explain-tier` / `--force-tier` is set,
-    // OR when a riskTierPathTokens config error was caught above — the error
-    // must surface in the envelope (and downstream PR comment) even in a
-    // normal `comment`/`gate` run, otherwise a config typo silently kills
-    // the user's opt-in with only a stderr trace they'll never see
-    // (coderabbit review, PR #1028 orchestrate.ts:1129).
-    tierReasons: input.explainTier || tierForced || pathTokenConfigError ? tierReasons : undefined,
+    // when a riskTierPathTokens config error was caught above, OR when the
+    // classifier lands on `full` tier — a naturally-full run is a customer-
+    // visible policy call ("why did my YAML-only diff get REQUEST_CHANGES?")
+    // and the reason list is what makes the verdict debuggable without the
+    // customer having to re-run with --explain-tier. `trivial`/`lite` runs
+    // stay silent to avoid noise on approvals.
+    tierReasons: input.explainTier || tierForced || pathTokenConfigError || tier === "full" ? tierReasons : undefined,
     tierForced: tierForced ? true : undefined,
     tierClassified: tierForced ? classifiedTier : undefined,
   })

packages/opencode/src/altimate/review/run.ts

@@ -37,6 +37,8 @@ export interface ReviewPullRequestOptions {
   /** Model identifier recorded in the envelope. */
   modelVersion?: string
   coreVersion?: string
+  /** altimate-code CLI release recorded in engine.cliVersion for audit reconstruction. */
+  cliVersion?: string
   /** Disable the LLM reviewer lane (default: enabled; self-degrades if no model). */
   noAi?: boolean
   /** PR metadata for the AI reviewer's intent check. */
@@ -129,7 +131,7 @@ async function autoDiscoverManifest(cwd: string): Promise<{ path: string; projec
  *  docs markdown blocks) or top-level dbt config. `README.md` at repo root,
  *  `.github/`, `package.json`, etc. are excluded so their mtimes don't
  *  trigger a stale warning. Exported for tests — see review-run-stale.test.ts.
- *  Referenced by `warnIfStale`. */
+ *  Referenced by `detectStaleManifest`. */
 export function isManifestAffecting(rel: string): boolean {
   // Code / schema / seed CSV live under any dbt source directory.
   if (/(^|\/)(models|seeds|snapshots|macros|tests|analyses)\/.*\.(sql|py|yml|yaml|csv)$/i.test(rel)) return true
@@ -144,12 +146,14 @@ export function isManifestAffecting(rel: string): boolean {
   return false
 }
 
-/** Warn to stderr when the manifest looks stale relative to changed files.
- *  Compares the manifest's mtime against every change-affecting path (per
- *  `isManifestAffecting`); a single change newer than the manifest is
- *  enough to fire the warning once and return. Non-fatal — the review
- *  proceeds against the (possibly stale) manifest. */
-async function warnIfStale(manifestAbs: string, changedPaths: string[], fsRoot: string): Promise<void> {
+/** Detect a stale manifest and warn to stderr. Returns `true` when a
+ *  change-affecting file was modified after the manifest — signalling the
+ *  verdict may have been computed against out-of-date metadata. Non-fatal;
+ *  the review proceeds against the (possibly stale) manifest and the
+ *  caller mirrors the flag onto the signed envelope so a downstream
+ *  auditor can distinguish stale-manifest verdicts from clean ones
+ *  (stderr alone is easy for CI to swallow). */
+async function detectStaleManifest(manifestAbs: string, changedPaths: string[], fsRoot: string): Promise<boolean> {
   try {
     const manifestMtime = (await stat(manifestAbs)).mtimeMs
     for (const rel of changedPaths) {
@@ -166,7 +170,7 @@ async function warnIfStale(manifestAbs: string, changedPaths: string[], fsRoot:
             `⚠️  manifest ${manifestAbs} appears stale — ${rel} was modified after the manifest was written. ` +
               `Re-run \`dbt compile\` (or \`dbt build\`) to refresh before reviewing.\n`,
           )
-          return
+          return true
         }
       } catch {
         /* file not on disk (e.g. removed by the change) — skip */
@@ -175,6 +179,7 @@ async function warnIfStale(manifestAbs: string, changedPaths: string[], fsRoot:
   } catch {
     /* manifest unreadable → detectDialect will have already returned undefined */
   }
+  return false
 }
 
 export async function reviewPullRequest(opts: ReviewPullRequestOptions): Promise<VerdictEnvelope> {
@@ -241,11 +246,17 @@ export async function reviewPullRequest(opts: ReviewPullRequestOptions): Promise
       }
     }
   }
-  // Freshness check: warn (don't fail) when the manifest predates changed files.
-  // Skip when we're diffing against the working tree (mtime signal is noisy
-  // during active edits) — only warn when the caller explicitly pinned a head
-  // ref, which is the CI / bench shape where a stale manifest is a real risk.
-  if (opts.head) await warnIfStale(manifestAbs, changedFiles.map((f) => f.path), gitRoot)
+  // Freshness check: detect (and warn — non-fatal) when the manifest predates
+  // change-affecting files. Runs for both the pinned-head CI shape AND the
+  // working-tree local shape — the local scenario "dbt compile once, edit for
+  // an hour, then altimate review" is where staleness actually bites in
+  // practice, so gating this behind `--head` (the prior behavior) silently
+  // under-warned the most common developer workflow. mtime granularity on
+  // the working tree can be noisy during a live edit session, but the check
+  // is limited to files that would materially change the manifest
+  // (`isManifestAffecting`), so noise is bounded. Return value is stamped
+  // into the signed envelope so downstream auditors see it too.
+  const staleManifest = await detectStaleManifest(manifestAbs, changedFiles.map((f) => f.path), gitRoot)
 
   // Resolve the SQL dialect: explicit config wins; otherwise auto-detect from
   // the dbt manifest's `adapter_type` (so a BigQuery/Redshift project isn't
@@ -306,10 +317,12 @@ export async function reviewPullRequest(opts: ReviewPullRequestOptions): Promise
     manifestHash: mhash,
     modelVersion: opts.modelVersion,
     coreVersion: opts.coreVersion,
+    cliVersion: opts.cliVersion,
     aiReview: opts.noAi || config.ai === false ? undefined : runAiReview,
     prTitle: opts.prTitle,
     prBody: opts.prBody,
     explainTier: opts.explainTier,
     forceTier: opts.forceTier,
+    staleManifest,
   })
 }

packages/opencode/src/altimate/review/verdict.ts

@@ -82,6 +82,10 @@ export const EngineVersions = z.object({
   reviewer: z.string().default("dbt-pr-review/1"),
   core: z.string().optional(),
   model: z.string().optional(),
+  /** The altimate-code CLI release that generated this verdict — lets an
+   *  auditor reconstruct which policy version applied months later, when
+   *  the verdict envelope has outlived the running binary. */
+  cliVersion: z.string().optional(),
 })
 export type EngineVersions = z.infer<typeof EngineVersions>
 
@@ -110,6 +114,12 @@ export const VerdictEnvelope = z.object({
   engine: EngineVersions,
   /** Hash of the dbt manifest the verdict was computed against, when present. */
   manifestHash: z.string().optional(),
+  /** True when a change-affecting source file was modified after the manifest
+   *  was written (checked via mtime; see run.ts::detectStaleManifest). Durably
+   *  records in the signed envelope that the verdict may have been computed
+   *  against out-of-date metadata — a stderr warning alone is easy for CI to
+   *  swallow. */
+  staleManifest: z.boolean().optional(),
   /** ISO timestamp; injected by the caller (no clock access in pure code). */
   generatedAt: z.string().optional(),
   /** Optional break-glass override record. */
@@ -166,6 +176,8 @@ export interface BuildEnvelopeInput {
   tierForced?: boolean
   /** G2 — classifier's original tier before the force override. */
   tierClassified?: RiskTier
+  /** True when mtime signals the manifest predates a change-affecting file. */
+  staleManifest?: boolean
 }
 
 function summarize(findings: Finding[], degraded: boolean): VerdictEnvelope["summary"] {
@@ -193,6 +205,7 @@ export function buildEnvelope(input: BuildEnvelopeInput): VerdictEnvelope {
     summary: summarize(input.findings, degraded),
     engine: EngineVersions.parse(input.engine ?? {}),
     manifestHash: input.manifestHash,
+    staleManifest: input.staleManifest ? true : undefined,
     generatedAt: input.generatedAt,
   })
 }

packages/opencode/src/cli/cmd/review.ts

@@ -2,6 +2,7 @@ import { promises as fs } from "node:fs"
 import { UI } from "../ui"
 import { cmd } from "./cmd"
 import { bootstrap } from "../bootstrap"
+import { Installation } from "../../installation"
 import { reviewPullRequest } from "../../altimate/review/run"
 import { renderSummary } from "../../altimate/review/format"
 import { postGitHubReview, resolveGitHubTarget } from "../../altimate/review/post-github"
@@ -85,6 +86,10 @@ export const ReviewCommand = cmd({
         noAi: args.noAi === true || args.ai === false,
         explainTier: args.explainTier === true,
         forceTier: args.forceTier as "trivial" | "lite" | "full" | undefined,
+        // Stamp the CLI version into engine.cliVersion so an auditor can
+        // reconstruct which policy version generated a stored verdict long
+        // after the binary that ran it is gone.
+        cliVersion: Installation.VERSION,
       })
 
       if (args.output) await fs.writeFile(args.output as string, JSON.stringify(env, null, 2))