@eduardbar/drift 1.2.0 → 1.4.0

package/README.md

@@ -1,8 +1,8 @@
-![drift — technical debt detector for AI-generated code](./assets/og.png)
+![drift - AI Code Audit CLI for merge trust](./assets/og.png)
 
 # drift
 
-Detect technical debt in AI-generated TypeScript code. One command. Zero config.
+AI Code Audit CLI for AI-assisted PRs. Drift turns static signals into merge trust decisions before you merge.
 
 ![npm](https://img.shields.io/npm/v/@eduardbar/drift?color=6366f1&label=npm)
 ![license](https://img.shields.io/badge/license-MIT-green.svg)
@@ -20,7 +20,7 @@ AI coding tools ship code fast. They also leave behind consistent, predictable s
 
 GitClear's 2024 analysis of 211M lines of code found a **39.9% drop in refactoring activity** and an **8x increase in duplicated code blocks** since AI tools became mainstream. A senior engineer on r/vibecoding put it plainly: _"The code looks reviewed. It isn't. Nobody's reading 400-line files the AI dumped in one shot."_
 
-drift gives you a 0–100 score per file and project so you know what to look at before it reaches production.
+drift gives you debt signals (`scan`, `review`) and a trust decision layer (`trust`) so teams can merge with confidence instead of guesswork.
 
 **How drift compares to existing tools:**
 
@@ -50,12 +50,62 @@ npm install --save-dev @eduardbar/drift
 ## Product Docs
 
 - Product requirements and roadmap: [`docs/PRD.md`](./docs/PRD.md)
+- Trust core release checklist: [`docs/trust-core-release-checklist.md`](./docs/trust-core-release-checklist.md)
+- Rules catalog (source-of-truth snapshot): [`docs/rules-catalog.md`](./docs/rules-catalog.md)
 - Contributor/agent workflow guide: [`docs/AGENTS.md`](./docs/AGENTS.md)
 
 ---
 
 ## Commands
 
+### `drift init`
+
+Scaffold first-run setup for drift in an existing repository.
+
+```bash
+drift init
+drift init --preset node-backend
+drift init --preset react-app --ci --baseline
+```
+
+| Flag | Description |
+|------|-------------|
+| `--preset <type>` | Generate `drift.config.ts` using one of: `node-backend`, `react-app`, `hexagonal`, `monorepo` |
+| `--ci` | Generate `.github/workflows/drift-review.yml` |
+| `--baseline` | Generate `drift-baseline.json` from the current scan |
+
+`drift init` is non-destructive for pre-existing targets: drift skips generation when an output file already exists and prints a warning.
+
+---
+
+### `drift doctor`
+
+Run environment diagnostics for Node/runtime and project readiness.
+
+```bash
+drift doctor
+drift doctor --json
+```
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output structured doctor report JSON |
+
+Checks include Node major version support (`>=18`), `package.json`, ESM mode, `tsconfig.json`, source file count, optional `--low-memory` recommendation, and `drift.config.*` detection.
+
+---
+
+### Repository smoke (local source CLI)
+
+Run a non-destructive end-to-end smoke suite against any repository path using local source commands (`node --import tsx ./src/cli.ts ...`).
+
+```bash
+npm run smoke:repo -- ../target-repo --base origin/main
+npm run smoke:repo -- ../target-repo --dry-run
+```
+
+The script writes JSON + Markdown summaries and command logs under `.drift-smoke/<repo>-<timestamp>/`.
+
 ### `drift scan [path]`
 
 Scan a directory and print a scored report to stdout.
@@ -68,6 +118,7 @@ drift scan ./src --json
 drift scan ./src --ai
 drift scan ./src --fix
 drift scan ./src --min-score 50
+drift scan ./src --low-memory --max-file-size-kb 1024
 ```
 
 **Options:**
@@ -75,10 +126,18 @@ drift scan ./src --min-score 50
 | Flag | Description |
 |------|-------------|
 | `--output <file>` | Write Markdown report to a file instead of stdout |
+| `--format <type>` | Output format: `console\|json\|markdown\|ai\|sarif` |
 | `--json` | Output raw `DriftReport` JSON |
 | `--ai` | Output structured JSON optimized for LLM consumption (Claude, GPT, etc.) |
 | `--fix` | Print inline fix suggestions for each detected issue |
-| `--min-score <n>` | Exit with code 1 if the overall score meets or exceeds this threshold |
+| `--min-score <n>` | Exit with code 1 if the overall score strictly exceeds this threshold |
+| `--low-memory` | Analyze files in bounded chunks to reduce peak RAM |
+| `--chunk-size <n>` | Files per chunk in low-memory mode (default: 40) |
+| `--max-files <n>` | Soft cap on analyzed files; extra files are skipped with diagnostics |
+| `--max-file-size-kb <n>` | Skip oversized files with diagnostics to avoid OOM |
+| `--with-semantic-duplication` | Keep semantic duplication rule enabled in low-memory mode |
+
+`--min-score` currently fails when `totalScore > n` (strictly greater than), matching CLI behavior.
 
 **Example output:**
 
@@ -106,6 +165,33 @@ drift scan ./src --min-score 50
 
 ---
 
+### `drift guard [path]`
+
+Evaluate drift regression guardrails against a git diff (`--base`) or a baseline file/object.
+
+```bash
+drift guard ./src --base origin/main
+drift guard ./src --baseline drift-baseline.json
+drift guard ./src --base origin/main --budget 3 --by-severity error=0,warning=2,info=5
+drift guard ./src --base origin/main --json
+```
+
+| Flag | Description |
+|------|-------------|
+| `--base <ref>` | Diff mode: compare current state vs git ref |
+| `--baseline <file>` | Baseline mode: compare against baseline JSON (default file name: `drift-baseline.json`) |
+| `--budget <n>` | Maximum allowed score delta |
+| `--by-severity <spec>` | Severity thresholds as CSV `key=value` pairs (`error`, `warning`, `info`) |
+| `--json` | Output full `GuardResult` JSON |
+| `--low-memory` / `--chunk-size <n>` / `--max-files <n>` / `--max-file-size-kb <n>` / `--with-semantic-duplication` | Analysis resource controls shared with scan/diff/report/badge/ci/trust |
+
+Behavior:
+- With `--base`, guard enforces no-regression checks for score and total issues, then applies optional budget/severity thresholds.
+- Without `--base`, guard requires a baseline (inline or file) and compares only against available baseline anchors.
+- Exit code is `1` when any guard check fails.
+
+---
+
 ### `drift diff [ref]`
 
 Compare the current project state against any git ref. Defaults to `HEAD~1`.
@@ -115,6 +201,7 @@ drift diff                # HEAD vs HEAD~1
 drift diff HEAD~3         # HEAD vs 3 commits ago
 drift diff main           # HEAD vs branch main
 drift diff abc1234        # HEAD vs a specific commit
+drift diff --format sarif # Output SARIF for code scanning
 drift diff --json         # Output raw JSON diff
 ```
 
@@ -122,6 +209,7 @@ drift diff --json         # Output raw JSON diff
 
 | Flag | Description |
 |------|-------------|
+| `--format <type>` | Output format: `console\|json\|sarif` |
 | `--json` | Output raw JSON diff |
 
 Shows score delta, issues introduced, and issues resolved since the given ref.
@@ -136,16 +224,105 @@ Review drift against a git base ref and output a PR-ready markdown comment.
 drift review --base origin/main
 drift review --base main --comment
 drift review --base HEAD~3 --json
+drift review --base origin/main --format sarif
 drift review --base origin/main --fail-on 5
 ```
 
 | Flag | Description |
 |------|-------------|
 | `--base <ref>` | Git base ref to compare against (default: `origin/main`) |
+| `--format <type>` | Output format: `console\|json\|markdown\|sarif` |
 | `--json` | Output structured review JSON |
 | `--comment` | Print only the markdown body for PR comments |
 | `--fail-on <n>` | Exit code 1 when score delta is greater than or equal to `n` |
 
+`drift review` is best used as supplementary diff context alongside `drift trust` in pull-request workflows.
+
+---
+
+### `drift trust [path]`
+
+Compute merge trust baseline for local checks and CI merge gates.
+
+```bash
+drift trust
+drift trust ./src
+drift trust ./src --json
+drift trust ./src --base origin/main
+drift trust ./src --base origin/main --markdown
+drift trust ./src --format sarif
+drift trust ./src --markdown --output trust.md
+drift trust ./src --min-trust 45
+drift trust ./src --max-risk HIGH
+drift trust ./src --branch main
+drift trust ./src --branch release/v1.4.0 --policy-pack strict --explain-policy
+drift trust ./src --advanced-trust
+drift trust ./src --advanced-trust --previous-trust ./artifacts/prev-trust.json
+drift trust ./src --advanced-trust --history-file ./drift-history.json --markdown
+```
+
+| Flag | Description |
+|------|-------------|
+| `--base <ref>` | Compare against a git base ref and include deterministic diff-aware penalties/bonuses |
+| `--format <type>` | Output format: `console\|json\|markdown\|sarif` |
+| `--json` | Output structured trust JSON (`trust_score`, `merge_risk`, `top_reasons`, `fix_priorities`, optional `diff_context`) |
+| `--markdown` | Output PR-ready markdown trust summary |
+| `--output <file>` | Write selected trust output format to file |
+| `--min-trust <n>` | Exit code 1 when trust score is below `n` |
+| `--max-risk <level>` | Exit code 1 when computed merge risk exceeds `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL` |
+| `--branch <name>` | Branch used for `drift.config` trust policy matching (falls back to CI env vars) |
+| `--policy-pack <name>` | Optional trust policy pack from `trustGate.policyPacks` in `drift.config.*` |
+| `--explain-policy` | Print base/pack/branch/override resolution and effective gate policy to stderr |
+| `--advanced-trust` | Enable optional advanced trust layer (historical comparison + team guidance metadata) |
+| `--previous-trust <file>` | Compare current trust against a prior trust JSON file in advanced mode |
+| `--history-file <file>` | Use a specific `drift-history.json` file for advanced historical fallback |
+
+When `trustGate` policy is configured in `drift.config.*`, branch-based thresholds are applied automatically. CLI flags still override policy values.
+
+---
+
+### `drift trust-gate <trust-json-file>`
+
+Evaluate trust gate thresholds from a previously generated trust JSON file. This is ideal for CI workflows that already produced `drift-trust.json` and want a single source of truth for gate logic.
+
+```bash
+drift trust-gate drift-trust.json --min-trust 45 --max-risk HIGH
+drift trust-gate drift-trust.json --branch release/v1.2.0
+drift trust-gate drift-trust.json --branch main --policy-pack balanced --explain-policy
+```
+
+| Flag | Description |
+|------|-------------|
+| `--min-trust <n>` | Exit code 1 when trust score in JSON is below `n` |
+| `--max-risk <level>` | Exit code 1 when merge risk in JSON exceeds `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL` |
+| `--branch <name>` | Branch used for `drift.config` trust policy matching (falls back to CI env vars) |
+| `--policy-pack <name>` | Optional trust policy pack from `trustGate.policyPacks` in `drift.config.*` |
+| `--explain-policy` | Print base/pack/branch/override resolution and effective gate policy to stderr |
+
+---
+
+### `drift kpi <path>`
+
+Aggregate trust KPI evidence from local artifacts (directory or glob). Prints a compact console summary to stderr and structured KPI JSON to stdout.
+
+```bash
+drift kpi ./artifacts/trust
+drift kpi "./artifacts/**/drift-trust-*.json"
+drift kpi ./artifacts/trust --no-summary
+```
+
+| Flag | Description |
+|------|-------------|
+| `--no-summary` | Disable stderr console summary and output JSON only |
+
+Computed KPI fields include:
+- PRs evaluated count
+- Merge risk distribution (`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`)
+- Trust score average/median/min/max
+- High-risk ratio (`HIGH` + `CRITICAL`)
+- Diff trend aggregates when `diff_context` exists (`scoreDelta`, new/resolved issues, status distribution)
+- Diagnostics for malformed/missing/invalid JSON artifacts
+
 ---
 
 ### `drift map [path]`
@@ -216,6 +393,7 @@ Emit GitHub Actions annotations and a step summary. Designed to run inside a CI
 ```bash
 drift ci                  # scan current directory
 drift ci ./src
+drift ci ./src --format sarif
 drift ci ./src --min-score 60
 ```
 
@@ -223,7 +401,8 @@ drift ci ./src --min-score 60
 
 | Flag | Description |
 |------|-------------|
-| `--min-score <n>` | Exit with code 1 if the overall score meets or exceeds this threshold |
+| `--format <type>` | Output format: `console\|json\|sarif` |
+| `--min-score <n>` | Exit with code 1 if the overall score strictly exceeds this threshold |
 
 Outputs `::error` and `::warning` annotations visible in the PR diff. Writes a markdown summary to `$GITHUB_STEP_SUMMARY`.
 
@@ -290,11 +469,18 @@ drift fix ./src --dry-run   # alias of --preview
 
 ### `drift cloud`
 
-Local SaaS foundations backed by `.drift-cloud/store.json`.
+Local multi-tenant foundations backed by `.drift-cloud/store.json`.
 
 ```bash
-drift cloud ingest ./src --workspace acme --user u-123 --repo webapp
+drift cloud ingest ./src --org acme --workspace core --user u-123 --role owner --plan sponsor --repo webapp
 drift cloud summary
+drift cloud summary --org acme --workspace core
+drift cloud summary --org acme --workspace core --actor u-owner
+drift cloud ingest ./src --org acme --workspace core --user u-member --actor u-owner
+drift cloud ingest ./src --org acme --workspace core --user u-member --actor u-member # strict actor mode ready
+drift cloud plan-set --org acme --plan team --actor u-owner --reason "annual upgrade"
+drift cloud plan-changes --org acme --actor u-owner
+drift cloud usage --org acme --actor u-owner
 drift cloud summary --json
 drift cloud dashboard --output drift-cloud-dashboard.html
 ```
@@ -303,46 +489,53 @@ drift cloud dashboard --output drift-cloud-dashboard.html
 
 | Command | Description |
 |---------|-------------|
-| `drift cloud ingest [path] --workspace <id> --user <id> [--repo <name>] [--store <file>]` | Scans the path and stores one SaaS snapshot |
-| `drift cloud summary [--json] [--store <file>]` | Shows users/workspaces/repos usage and runs per month |
+| `drift cloud ingest [path] --org <id> --workspace <id> --user <id> [--role <owner\|member\|viewer>] [--plan <free\|sponsor\|team\|business>] [--repo <name>] [--actor <user>] [--store <file>]` | Scans the path and stores one tenant-scoped snapshot (`--actor` optional by default, required only when `saas.strictActorEnforcement=true`) |
+| `drift cloud summary [--json] [--org <id>] [--workspace <id>] [--actor <user>] [--store <file>]` | Shows users/workspaces/repos usage and runs per month; in strict mode, scoped reads (`--org`/`--workspace`) require `--actor` |
+| `drift cloud plan-set --org <id> --plan <free\|sponsor\|team\|business> --actor <user> [--reason <text>] [--store <file>]` | Updates organization plan and writes an audited plan-change event (owner-gated by actor) |
+| `drift cloud plan-changes --org <id> --actor <user> [--json] [--store <file>]` | Lists audited plan lifecycle events for the organization |
+| `drift cloud usage --org <id> --actor <user> [--month <yyyy-mm>] [--json] [--store <file>]` | Shows organization usage plus effective limits for current plan |
 | `drift cloud dashboard [--output <file>] [--store <file>]` | Generates an HTML dashboard with trends and hotspots |
 
-`drift cloud` ships with a free-until-7,500 strategy and configurable guardrails for the free phase: max runs per workspace per month, max repos per workspace, and retention window.
+`drift cloud` ships with tenant identity boundaries (`organizationId` + `workspaceId`), role primitives (`owner`/`member`/`viewer`), and plan placeholders (`free`/`sponsor`/`team`/`business`). It is an infrastructure foundation, not a full auth/billing platform.
+
+By default, local guardrails enforce one plan-based limit: max workspaces per organization (`free:20`, `sponsor:50`, `team:200`, `business:1000`), plus existing free-phase limits (runs per workspace, repos per workspace, retention window).
+
+To require actor identity on scoped cloud operations, enable strict actor mode in `drift.config.*`:
+
+```ts
+export default {
+  saas: {
+    strictActorEnforcement: true,
+  },
+}
+```
 
 ---
 
 ## Rules
 
-26 rules across three severity levels. All run automatically unless marked as requiring configuration.
+drift currently defines **35 rule IDs** in `RULE_WEIGHTS` (`src/analyzer.ts`): core detections, configurable architecture checks, AI/meta aggregation, plugin diagnostics, and analysis guardrail diagnostics.
+
+For the complete up-to-date catalog (id, severity, weight, phase/origin, note), see [`docs/rules-catalog.md`](./docs/rules-catalog.md).
+
+Highlights:
 
 | Rule | Severity | Weight | What it detects |
 |------|----------|--------|-----------------|
-| `large-file` | error | 20 | Files exceeding 300 lines — AI generates monolithic files instead of splitting responsibility |
-| `large-function` | error | 15 | Functions exceeding 50 lines — AI avoids decomposing logic into smaller units |
-| `duplicate-function-name` | error | 18 | Function names that appear more than once (case-insensitive) — AI regenerates helpers instead of reusing them |
-| `high-complexity` | error | 15 | Cyclomatic complexity above 10 — AI produces correct code, not necessarily simple code |
-| `circular-dependency` | error | 14 | Circular import chains between modules — AI doesn't reason about module topology |
-| `layer-violation` | error | 16 | Imports that cross architectural layers in the wrong direction (e.g., domain importing from infra) — requires `drift.config.ts` |
-| `debug-leftover` | warning | 10 | `console.log`, `console.warn`, `console.error`, and `TODO` / `FIXME` / `HACK` comments — AI leaves scaffolding in place |
-| `dead-code` | warning | 8 | Named imports that are never used in the file — AI imports broadly |
-| `any-abuse` | warning | 8 | Explicit `any` type annotations — AI defaults to `any` when type inference is unclear |
-| `catch-swallow` | warning | 10 | Empty `catch` blocks — AI makes code not throw without handling the error |
-| `comment-contradiction` | warning | 12 | Comments that restate what the surrounding code already expresses — AI over-documents the obvious |
-| `deep-nesting` | warning | 12 | Control flow nested more than 3 levels deep — results in code that is difficult to follow |
-| `too-many-params` | warning | 8 | Functions with more than 4 parameters — AI avoids grouping related arguments into objects |
-| `high-coupling` | warning | 10 | Files importing from more than 10 distinct modules — AI imports broadly without encapsulation |
-| `promise-style-mix` | warning | 7 | `async/await` and `.then()` / `.catch()` used together in the same file — AI combines styles inconsistently |
-| `unused-export` | warning | 8 | Named exports that are never imported anywhere in the project — cross-file dead code ESLint cannot detect |
-| `dead-file` | warning | 10 | Files never imported by any other file in the project — invisible dead code |
-| `unused-dependency` | warning | 6 | Packages listed in `package.json` with no corresponding import in source files |
-| `cross-boundary-import` | warning | 10 | Imports that cross module boundaries outside the allowed list — requires `drift.config.ts` |
-| `hardcoded-config` | warning | 10 | Hardcoded URLs, IP addresses, secrets, or connection strings — AI skips environment variable abstraction |
-| `inconsistent-error-handling` | warning | 8 | Mixed `try/catch` and `.catch()` patterns in the same file — AI combines approaches without a consistent strategy |
-| `unnecessary-abstraction` | warning | 7 | Wrapper functions or helpers that add no logic over what they wrap — AI over-engineers simple calls |
-| `naming-inconsistency` | warning | 6 | Mixed `camelCase` and `snake_case` in the same module — AI forgets project conventions mid-generation |
-| `semantic-duplication` | warning | 12 | Functions with structurally identical logic despite different names — detected via AST fingerprinting, not text comparison |
-| `no-return-type` | info | 5 | Functions missing an explicit return type annotation |
-| `magic-number` | info | 3 | Numeric literals used directly in logic without a named constant |
+| `large-file` | error | 20 | Files exceeding 300 lines |
+| `duplicate-function-name` | error | 18 | Same function name repeated across a file |
+| `high-complexity` | error | 15 | Cyclomatic complexity above threshold |
+| `layer-violation` | error | 16 | Invalid layer import direction (requires `layers` config) |
+| `cross-boundary-import` | warning | 10 | Invalid module boundary import (requires `modules`/legacy boundaries config) |
+| `controller-no-db` | warning | 11 | Controller touching DB directly (configurable architecture rule) |
+| `service-no-http` | warning | 11 | Service layer coupled to HTTP concerns (configurable architecture rule) |
+| `max-function-lines` | warning | 9 | Function line cap enforced by `architectureRules.maxFunctionLines` |
+| `semantic-duplication` | warning | 12 | AST-level semantic function duplication |
+| `ai-code-smell` | warning | 12 | Aggregated AI-smell signal from multiple heuristics in a file |
+| `plugin-error` | warning | 4 | Plugin load/contract/runtime failure surfaced as issue |
+| `plugin-warning` | info | 0 | Non-fatal plugin validation warning |
+| `analysis-skip-max-files` | info | 0 | File skipped by `maxFiles` guardrail |
+| `analysis-skip-file-size` | info | 0 | File skipped by `maxFileSizeKb` guardrail |
 
 ---
 
@@ -362,39 +555,63 @@ drift cloud dashboard --output drift-cloud-dashboard.html
 
 ## Configuration
 
-drift runs with zero configuration. Architectural rules (`layer-violation`, `cross-boundary-import`) require a `drift.config.ts` (or `.js` / `.json`) at your project root:
+drift runs with zero configuration. Architectural rules (`layer-violation`, `cross-boundary-import`) and configurable architecture checks use `drift.config.ts` (or `.js` / `.json`) at project root:
 
 ```typescript
 import type { DriftConfig } from '@eduardbar/drift'
 
 export default {
   plugins: ['drift-plugin-example'],
+  performance: {
+    lowMemory: true,
+    chunkSize: 40,
+    maxFiles: 8000,
+    maxFileSizeKb: 1024,
+    includeSemanticDuplication: false,
+  },
   architectureRules: {
     controllerNoDb: true,
     serviceNoHttp: true,
     maxFunctionLines: 80,
   },
+  trustGate: {
+    minTrust: 45,
+    maxRisk: 'HIGH',
+    presets: [
+      { branch: 'main', minTrust: 70, maxRisk: 'MEDIUM' },
+      { branch: 'release/*', minTrust: 80, maxRisk: 'LOW' },
+      { branch: 'legacy/*', enabled: false },
+    ],
+  },
   layers: [
     { name: 'domain',  patterns: ['src/domain/**'],  canImportFrom: [] },
     { name: 'app',     patterns: ['src/app/**'],     canImportFrom: ['domain'] },
     { name: 'infra',   patterns: ['src/infra/**'],   canImportFrom: ['domain', 'app'] },
   ],
-  boundaries: [
+  modules: [
     { name: 'auth',    root: 'src/modules/auth',    allowedExternalImports: ['src/shared'] },
     { name: 'billing', root: 'src/modules/billing', allowedExternalImports: ['src/shared'] },
   ],
-  exclude: [
-    'src/generated/**',
-    '**/*.spec.ts',
-  ],
-  rules: {
-    'large-file': { threshold: 400 },   // override default 300
-    'magic-number': 'off',              // disable a rule
-  },
 } satisfies DriftConfig
 ```
 
-Without a config file, `layer-violation` and `cross-boundary-import` are silently skipped. All other rules run with their defaults.
+For backwards compatibility, `moduleBoundaries` and `boundaries` are normalized to `modules`.
+
+Without a config file, `layer-violation`, `cross-boundary-import`, and configurable architecture checks (`controller-no-db`, `service-no-http`, `max-function-lines`) are skipped. All other rules run with defaults.
+
+### Memory guardrails (recommended for large repos)
+
+If your repository is large or your machine has limited RAM, start with:
+
+```bash
+drift scan . --low-memory --max-file-size-kb 1024 --max-files 8000
+```
+
+Practical tuning:
+- Lower `--chunk-size` to reduce peak memory further (slower but safer).
+- Keep `includeSemanticDuplication: false` in low-memory mode for the lowest memory footprint.
+- Set `maxFileSizeKb` to skip generated/vendor files that can explode AST memory usage.
+- Set `maxFiles` to protect CI runners from worst-case monorepo scans.
 
 ---
 
@@ -419,7 +636,7 @@ jobs:
         run: npx @eduardbar/drift scan ./src --min-score 60
 ```
 
-Exit code is `1` if the score meets or exceeds `--min-score`. Exit code `0` otherwise.
+Exit code is `1` if the score is strictly greater than `--min-score`. Exit code `0` otherwise.
 
 ### Annotations and step summary with `drift ci`
 
@@ -445,10 +662,50 @@ jobs:
 ### Auto PR comment with `drift review`
 
 The repository includes `.github/workflows/review-pr.yml`, which:
-- generates a PR-ready markdown comment from `drift review --comment`
+- generates a PR-ready markdown comment with `drift trust --markdown` first and `drift review --comment` as supplementary context
 - updates a single sticky comment (`<!-- drift-review -->`) on non-fork PRs
 - falls back to `$GITHUB_STEP_SUMMARY` for fork PRs
-- enforces a score delta threshold with `--fail-on`
+- enforces a trust baseline gate with `drift trust-gate drift-trust.json --min-trust 45 --max-risk HIGH`
+- uploads `drift trust --json` as `drift-trust-json-pr-<PR_NUMBER>-run-<RUN_ATTEMPT>` for manual KPI tracking
+- publishes a compact trust KPI summary in `$GITHUB_STEP_SUMMARY` (score, merge risk, new/resolved issues when diff context is available)
+- generates `drift.sarif` via `drift scan --format sarif`, uploads it to GitHub Code Scanning on non-fork PRs, and stores the SARIF file as workflow artifact for traceability
+
+Quick local SARIF export:
+
+```bash
+drift scan ./src --format sarif > drift.sarif
+```
+
+Example GitHub Code Scanning upload with SARIF:
+
+```yaml
+- name: Generate drift SARIF
+  run: npx @eduardbar/drift scan ./src --format sarif > drift.sarif
+
+- name: Upload SARIF to Code Scanning
+  uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: drift.sarif
+```
+
+Default gate behavior in this repo:
+- fail when trust is below 45
+- fail when merge risk is above `HIGH` (that means `CRITICAL` is blocked)
+
+### GitHub Action contract (v2)
+
+This repo also ships reusable local composite actions:
+
+- `./.github/actions/drift-scan`: score-focused scan gate using `npx @eduardbar/drift@<version>` (no global install).
+- `./.github/actions/drift-review`: trust/review/gate flow for PRs, aligned with `.github/workflows/review-pr.yml`.
+
+`drift-scan` exposes machine-friendly outputs for CI composition:
+- `score`, `grade`, `errors`, `warnings`, `infos`, `total-issues`, `files-affected`, `top-rules`
+
+`drift-review` exposes:
+- `trust-score`, `merge-risk`, `new-issues`, `resolved-issues`, `trust-json`, `trust-markdown`, `review-markdown`
+
+See `.github/actions/drift-scan/README.md` and `.github/actions/drift-review/README.md` for usage details.
 
 ---
 

package/ROADMAP.md

@@ -21,19 +21,20 @@ drift's goal is to be the tool that sits between ESLint and SonarQube — lightw
 **What drift is not:**
 - Not an ESLint replacement for style or correctness rules
 - Not a SonarQube replacement for security scanning
-- Not a cloud product, not a SaaS, not freemium
+- Not a cloud-only product or mandatory hosted backend
 
 **What drift is:**
 - A zero-config static analysis CLI that scores your TypeScript project's structural health
-- A CI gate that blocks debt from accumulating silently
+- An AI code audit CLI that helps teams decide merge trust on AI-assisted PRs
+- A CI gate that blocks risky merges using trust thresholds
 - A shared language for teams to talk about code quality: "our drift score went from 40 to 18 this sprint"
-- Always free. MIT. No tiers.
+- Core CLI is free and MIT; premium governance/sponsor tiers are a product direction for teams
 
 ---
 
 ## Principles that don't change
 
-- **Always free for the developer.** MIT. Forever. No paid tier, no cloud lock-in.
+- **Core stays free for developers.** MIT for the OSS CLI, no backend lock-in for the core workflow.
 - **Zero config to start.** One command, one number. Config is optional and additive.
 - **Fast.** Results in under 3 seconds on any normal project.
 - **One actionable number, not 400 warnings nobody reads.**
@@ -153,7 +154,7 @@ A score of 45 means nothing without context. A score that went from 80 to 45 ove
 
 - **26 rules active** across 9 detection categories
 - **Self-scan score: 14/100 (LOW)**
-- Published on npm as `@eduardbar/drift` — MIT, always free
+- Published on npm as `@eduardbar/drift` — MIT core CLI, optional premium direction documented in PRD
 - Cross-platform: Windows / Linux / macOS via `npx`
 
 ---

package/dist/analyzer.d.ts

@@ -1,4 +1,4 @@
-import type { DriftIssue, FileReport, DriftConfig, LoadedPlugin } from './types.js';
+import type { DriftIssue, FileReport, DriftConfig, DriftAnalysisOptions, LoadedPlugin } from './types.js';
 export { TrendAnalyzer } from './git/trend.js';
 export { BlameAnalyzer } from './git/blame.js';
 export declare const RULE_WEIGHTS: Record<string, {
@@ -10,5 +10,5 @@ export declare function analyzeFile(file: import('ts-morph').SourceFile, options
     loadedPlugins?: LoadedPlugin[];
     projectRoot?: string;
 }): FileReport;
-export declare function analyzeProject(targetPath: string, config?: DriftConfig): FileReport[];
+export declare function analyzeProject(targetPath: string, config?: DriftConfig, options?: DriftAnalysisOptions): FileReport[];
 //# sourceMappingURL=analyzer.d.ts.map