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: sahrizvi

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`. */
 exportfunctionisManifestAffecting(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))returntrue
@@ -144,12 +146,14 @@ export function isManifestAffecting(rel: string): boolean {
 returnfalse
 }
 
-/** 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. */
-asyncfunctionwarnIfStale(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). */
+asyncfunctiondetectStaleManifest(manifestAbs: string,changedPaths: string[],fsRoot: string): Promise<boolean>{
 try{
 constmanifestMtime=(awaitstat(manifestAbs)).mtimeMs
 for(constrelofchangedPaths){
@@ -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
+returntrue
 }
 }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 */
 }
+returnfalse
 }
 
 exportasyncfunctionreviewPullRequest(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)awaitwarnIfStale(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.
+conststaleManifest=awaitdetectStaleManifest(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(),
 })
 exporttypeEngineVersions=z.infer<typeofEngineVersions>
 
@@ -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
 }
 
 functionsummarize(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.forceTieras"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)awaitfs.writeFile(args.outputasstring,JSON.stringify(env,null,2))