pmclSF
diff --git a/‎CHANGELOG.md‎
Lines changed: 1 addition & 1 deletion b/‎CHANGELOG.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎CONTRIBUTING.md‎
Lines changed: 13 additions & 10 deletions b/‎CONTRIBUTING.md‎
Lines changed: 13 additions & 10 deletions
diff --git a/‎DESIGN.md‎
Lines changed: 2 additions & 2 deletions b/‎DESIGN.md‎
Lines changed: 2 additions & 2 deletions
diff --git a/‎README.md‎
Lines changed: 3 additions & 3 deletions b/‎README.md‎
Lines changed: 3 additions & 3 deletions
diff --git a/‎docs/cli-spec.md‎
Lines changed: 17 additions & 11 deletions b/‎docs/cli-spec.md‎
Lines changed: 17 additions & 11 deletions
diff --git a/‎docs/examples/gate/github-action.yml‎
Lines changed: 16 additions & 15 deletions b/‎docs/examples/gate/github-action.yml‎
Lines changed: 16 additions & 15 deletions
diff --git a/‎docs/examples/serve-local-dev.md‎
Lines changed: 7 additions & 4 deletions b/‎docs/examples/serve-local-dev.md‎
Lines changed: 7 additions & 4 deletions
diff --git a/‎docs/glossary.md‎
Lines changed: 12 additions & 4 deletions b/‎docs/glossary.md‎
Lines changed: 12 additions & 4 deletions
diff --git a/‎docs/product/ai-risk-tiers.md‎
Lines changed: 3 additions & 1 deletion b/‎docs/product/ai-risk-tiers.md‎
Lines changed: 3 additions & 1 deletion
diff --git a/‎docs/product/ai-trust-boundary.md‎
Lines changed: 41 additions & 14 deletions b/‎docs/product/ai-trust-boundary.md‎
Lines changed: 41 additions & 14 deletions
@@ -29,7 +29,7 @@ status with pillar + tier is [`docs/release/feature-status.md`]
 The release groups deliverables by the three pillars:
 
 - **Understand** (Tier 1): full snapshot pipeline; `report
-  summary/posture/metrics/focus/insights/explain`; AI surface
+  summary/posture/metrics/insights/explain`; AI surface
   inventory; cross-repo views.
 - **Align** (Tier 1): framework migration with per-file confidence;
   alignment-first docs; multi-repo manifest format.
 
@@ -13,9 +13,9 @@ go test ./cmd/... ./internal/...
 ## Project Structure
 
 ```
-cmd/terrain/          CLI entry point (10 canonical commands + legacy aliases)
+cmd/terrain/          CLI entry point (11 canonical commands + legacy aliases)
 cmd/terrain-bench/    Benchmark harness
-internal/             49 Go packages
+internal/             53 Go packages
 ├── analysis/        Repository scanning and code surface inference
 ├── convert/         Go-native test conversion (25 directions)
 ├── depgraph/        Dependency graph with 5 reasoning engines
@@ -60,7 +60,7 @@ make release-verify
 - JSON output uses `json.NewEncoder(os.Stdout)` with `SetIndent("", "  ")`
 - Nil slices should be converted to empty slices before JSON encoding (serialize as `[]` not `null`)
 - Error messages go to stderr: `fmt.Fprintf(os.Stderr, "error: %v\n", err)`
-- Exit codes: 0 = success, 1 = error, 2 = usage error / policy violation
+- Exit codes: 0 = success, 1 = error, 2 = usage error / policy violation, 4 = AI gate block, 5 = entity not found, 6 = severity-gate block (`--fail-on`). See `docs/cli-spec.md` for the full table.
 - Commands with positional args use `reorderCLIArgs()` to support flags in any position
 
 ## Adding a New Conversion Direction
@@ -115,19 +115,23 @@ apply:
 
 | Pillar | Floor | Block release? |
 |--------|-------|----------------|
-| Gate | every cell ≥ 4 | yes |
+| Gate | every cell ≥ 3 in 0.2.0 (≥ 4 in 0.3) | yes |
 | Understand | every cell ≥ 3 | yes |
 | Align | every cell ≥ 3 | soft (warn-only) |
 
+The Gate floor is 3 in 0.2.0 because P2 / E2 axes at level 4/5 require a
+labeled real-repo precision floor — the central deliverable of the 0.3
+program. Gate floor=3 reflects recall-anchored synthetic calibration in
+0.2.0; the level-4/5 jump lands cell-by-cell as the 0.3 corpus work
+materializes.
+
 ### How to lift a cell in your PR
 
 1. Find the cell you're improving in `docs/release/parity/scores.yaml`.
 2. Update the score (1–5) and replace the evidence line with a
    one-line pointer to the change you're making (file:line, test
    name, or short rationale).
-3. If your change touches the audit doc's narrative,
-   `docs/release/0.2.x-maturity-audit.md` updates in the same PR.
-4. Run `make pillar-parity` locally — your change should move at
+3. Run `make pillar-parity` locally — your change should move at
    least one cell; CI will compare the diff.
 
 ### Source-of-truth split
@@ -138,9 +142,8 @@ apply:
   means lives here.
 - **Per-cell scores**: `docs/release/parity/scores.yaml`. Changes
   every parity-lift PR. The shape is `area_id → axis_id → {score,
-  evidence}`.
-- **Human-readable companion**: `docs/release/0.2.x-maturity-audit.md`.
-  Same data, prose form. Update both together.
+  evidence}`. Each cell carries a one-line evidence pointer
+  (file:line, test name, PR number) so the lift is auditable.
 
 ### Local commands
 
 
@@ -37,8 +37,8 @@ See [docs/architecture.md](docs/architecture.md) for the full layered architectu
 ## Package Map
 
 ```
-cmd/terrain/          CLI entry point (10 canonical commands + legacy aliases)
-internal/             49 packages — see internal/README.md for the listing
+cmd/terrain/          CLI entry point (11 canonical commands + legacy aliases)
+internal/             53 packages — see internal/README.md for the listing
 ```
 
 See [docs/engineering/detector-architecture.md](docs/engineering/detector-architecture.md) for the detector plugin system architecture.
 
@@ -253,7 +253,7 @@ this is the summary view.
 
 Capabilities are tiered:
 
-- **Tier 1** — covered by tests, documented behavior, claimed publicly. Floor ≥ 4 on the parity rubric.
+- **Tier 1** — covered by tests, documented behavior, claimed publicly. Floor ≥ 3 on the parity rubric in 0.2.0; Gate floor lifts to ≥ 4 in 0.3 once the labeled real-repo precision corpus lands.
 - **Tier 2** — shipping but explicitly experimental; useful but not yet hardened. Floor ≥ 3.
 - **Tier 3** — in development, opt-in, no public claim. Wait for promotion.
 
@@ -262,7 +262,7 @@ Capabilities are tiered:
 **Understand** (Tier 1 unless noted):
 
 - `terrain analyze` — snapshot + signals + posture
-- `terrain report summary / posture / metrics / focus / insights / explain` — read-side queries
+- `terrain report summary / posture / metrics / insights / explain` — read-side queries
 - `terrain compare` — snapshots over time
 - AI surface inventory — what AI surfaces exist, where they are, what evals cover them
 - `terrain serve` (Tier 2) — local HTTP report; localhost-only, no auth
@@ -616,7 +616,7 @@ Repository scan  →  Signal detection  →  Risk modeling  →  Reporting
 cmd/terrain/     CLI — canonical surface (analyze, report, migrate,
                  convert, posture, doctor, ai, serve, version, help)
                  plus legacy aliases retained through 0.2.x
-internal/        47 Go packages covering analysis, signals, risk,
+internal/        53 Go packages covering analysis, signals, risk,
                  impact, depgraph, measurement, reporting, and more
 ```
 
 
@@ -13,22 +13,28 @@ It must be:
 
 ## Surface — canonical 11 + legacy aliases
 
-0.2.0 introduces three new namespace dispatchers
-(`terrain report`, `terrain migrate`, `terrain config`) plus
-`terrain debug`. The canonical surface is 10 top-level verbs:
+0.2.0 introduces namespace dispatchers (`terrain report`,
+`terrain migrate`, `terrain config`, `terrain debug`,
+`terrain ai`). The canonical surface is **11 top-level commands**:
 
 | Canonical | What it does |
 |---|---|
 | `terrain analyze` | Full snapshot pipeline; the headline command |
-| `terrain report <verb>` | Read-side views: summary, insights, explain, posture, portfolio, metrics, focus, show, impact, pr, select-tests |
-| `terrain migrate <verb>` | Conversion + migration: run, config, list, detect, shorthands, estimate, status, checklist, readiness, blockers, preview |
-| `terrain convert <file>` | Per-file conversion (legacy fall-through preserved) |
-| `terrain config <verb>` | feedback, telemetry, reset |
-| `terrain doctor` | Migration-readiness diagnostic |
-| `terrain ai <verb>` | AI surface inventory + eval orchestration |
-| `terrain serve` | Local HTTP server with HTML report + JSON API |
+| `terrain init [path]` | First-run scaffolder — runs analyze + emits a starter `.terrain/` layout |
+| `terrain report <verb>` | Read-side views: `summary`, `insights`, `metrics`, `explain`, `show`, `impact`, `pr`, `posture`, `select-tests` |
+| `terrain migrate <verb>` | Framework migration: `run`, `config`, `list`, `detect`, `shorthands`, `estimate`, `status`, `checklist`, `readiness`, `blockers`, `preview` |
+| `terrain ai <verb>` | AI inventory + eval orchestration: `list`, `run`, `replay`, `record`, `baseline`, `doctor` |
+| `terrain debug <verb>` | Dependency-graph drill-downs: `graph`, `coverage`, `fanout`, `duplicates`, `depgraph` |
+| `terrain config <verb>` | Workspace prefs: `feedback`, `telemetry` |
+| `terrain doctor [path]` | Diagnostics for current setup |
+| `terrain portfolio` | Single-repo (stable) and multi-repo manifest (experimental) portfolio analysis |
+| `terrain serve` | Local HTTP server with HTML report + JSON API (default port 8421, 127.0.0.1 only) |
 | `terrain version` | Version, commit, build date, snapshot schema version |
-| `terrain help` | Top-level help surface |
+
+Legacy aliases (`terrain summary`, `terrain insights`,
+`terrain compare`, `terrain convert <file>`, `terrain focus`,
+etc.) continue to route to the same handlers through 0.2.x.
+Removal targets 0.3.
 
 The legacy top-level commands documented in this file
 (`terrain summary`, `terrain insights`, etc.) continue to work
 
@@ -58,31 +58,32 @@ jobs:
           terrain version
 
       # ── Step 1 of the primary workflow: understand the test system ──
-      - name: terrain analyze
+      #
+      # `analyze` is the gate. `--new-findings-only --baseline <path>`
+      # filters to signals introduced AFTER the baseline snapshot, so
+      # established repos with pre-existing debt don't get blocked on
+      # day one. To gate, uncomment `--fail-on critical` (exit 6 on
+      # any Critical finding). The default below is warn-only — it
+      # produces output but does not fail the job.
+      - name: terrain analyze (warn-only by default)
         run: |
           terrain analyze \
             --write-snapshot \
+            --new-findings-only \
+            --baseline terrain-snapshot.json \
             --json > terrain-snapshot.json
+            # --fail-on critical    # uncomment to gate the build (exit 6)
 
-      # ── Step 2: gate the PR ────────────────────────────────────────
-      # Default: warn-only. The job stays green; the PR comment shows
-      # what Terrain found. Established repos with debt won't brick CI
-      # on day one.
-      #
-      # To enable blocking gates, uncomment the `--fail-on critical`
-      # line below. Combined with `--new-findings-only --baseline ...`,
-      # the gate fires only on findings introduced AFTER the snapshot
-      # in the baseline file (see `terrain analyze --write-snapshot`
-      # for how to persist the baseline).
-      - name: terrain report pr (warn-only by default)
+      # ── Step 2: render the PR comment ──────────────────────────────
+      # `report pr` summarizes the gated state. The exit status of
+      # this step is independent of the gating decision (which is
+      # already determined by step 1's `--fail-on`).
+      - name: terrain report pr
         run: |
           terrain report pr \
             --base ${{ github.event.pull_request.base.sha }} \
             --format markdown \
-            --new-findings-only \
-            --baseline terrain-snapshot.json \
             > terrain-pr-comment.md
-            # --fail-on critical    # uncomment to gate the build
 
       - name: Post or update the PR comment
         uses: peter-evans/create-or-update-comment@v5
 
@@ -18,11 +18,11 @@ time.
 ```bash
 # In your repo:
 terrain serve
-# → Listening on http://127.0.0.1:7344
+# → Listening on http://127.0.0.1:8421
 # → Press Ctrl-C to stop.
 ```
 
-Open `http://127.0.0.1:7344` in your browser. The page renders the
+Open `http://127.0.0.1:8421` in your browser. The page renders the
 same data shapes as `terrain analyze`, with sticky pillar
 navigation, signal cards, and tasteful typography.
 
@@ -32,12 +32,15 @@ navigation, signal cards, and tasteful typography.
 # Custom port
 terrain serve --port 8000
 
+# Bind to a different host (default is 127.0.0.1)
+terrain serve --host 127.0.0.1 --port 8421
+
 # Allow request to mutate state (the default is read-only — most
 # adopters want this off for local dev too):
 terrain serve --read-only=false
 
-# Use a saved snapshot instead of re-analyzing:
-terrain serve --snapshot .terrain/snapshots/latest.json
+# Run from a different repository root:
+terrain serve --root /path/to/other/repo
 ```
 
 ## What's safe
 
@@ -40,10 +40,18 @@ the snapshot and emits zero or more signals. See
 ## Posture
 
 The five-dimension health summary Terrain produces:
-**reliability**, **change-readiness**, **speed**, **governance**,
-and **AI**. Each dimension is backed by a band (A/B/C/D) plus
-contributing measurements. See
-[`docs/scoring-rubric.md`](scoring-rubric.md).
+**health**, **coverage_depth**, **coverage_diversity**,
+**structural_risk**, **operational_risk**. Each dimension is
+backed by a band (`strong` / `moderate` / `weak` for health-style
+dimensions; `low` / `moderate` / `elevated` / `critical` for
+risk-style dimensions, where lower = better). The companion view
+in `terrain insights` is the **Health Grade** (A / B / C / D), a
+distinct construct documented in
+[`docs/health-grade-rubric.md`](health-grade-rubric.md). See
+[`docs/product/posture-model.md`](product/posture-model.md) for
+the full dimension descriptions and
+[`docs/scoring-rubric.md`](scoring-rubric.md) for the underlying
+scoring constants.
 
 ## Severity clause
 
 
@@ -98,7 +98,9 @@ artifacts in CI.
 - `schemaParseFailure`, `wrongSourceSelected` — pipeline metadata
 
 These fire only when the corresponding eval artifact is present
-(via `terrain ai run` or `--ingest-only`). On a repo without eval
+(via `terrain ai run`, or via `terrain analyze` with
+`--promptfoo-results` / `--deepeval-results` / `--ragas-results`
+pointing at pre-existing eval output). On a repo without eval
 output, Terrain silently emits zero of these — that's the contract.
 
 ## How this surfaces in output
 
@@ -72,34 +72,61 @@ sandbox tool calls. Terrain is one layer above.
   shell command), the framework decides what's allowed. Terrain
   does not add a sandbox layer in 0.2.
 
-### `terrain ai run --baseline <path>` / `--ingest-only`
+### Ingesting pre-existing eval results without invoking the framework
 
-`--ingest-only` skips the framework invocation and only reads
-existing eval-output JSON files (via `--promptfoo-results`,
-`--deepeval-results`, `--ragas-results`). In this mode Terrain is
-fully passive — no child processes, no LLM calls.
+If you want Terrain to read eval-output JSON files without
+invoking any framework — useful when you run the eval framework
+yourself in your own sandbox — use `terrain analyze` with the
+adapter flags:
+
+```
+terrain analyze --root . \
+  --promptfoo-results path/to/promptfoo-output.json \
+  --deepeval-results path/to/deepeval-output.json \
+  --ragas-results    path/to/ragas-output.json
+```
+
+In this mode Terrain is fully passive: it parses the artifact
+files, surfaces ingestion diagnostics (per-field fallbacks), and
+flows the results through the same signals + posture pipeline as a
+fresh `analyze`. No child processes, no LLM calls.
+
+For baseline-aware regression gating (compare a current run to a
+known-good snapshot), use:
+
+```
+terrain ai record   ./baselines/known-good.json   # snapshot a good run
+terrain ai baseline compare --against ./baselines/known-good.json
+```
 
 ## Sandboxing roadmap
 
 | Capability | 0.2 | 0.3 |
 |------------|-----|-----|
 | Read-only filesystem access in `terrain analyze` | yes | yes |
+| Pre-computed-artifact ingestion via `terrain analyze --*-results` | yes | yes |
 | Sandbox `terrain ai run` child processes | no | yes |
 | Tool-call allowlist for AI tool invocations | no (framework's job) | terrain-side allowlist |
 | Network egress controls during eval execution | no (framework's job) | optional terrain-side network policy |
 
-If you need 0.3-grade sandboxing in 0.2, run `terrain ai run` with
-`--ingest-only` and execute the eval framework yourself in your
-preferred sandbox (Docker, gVisor, Firecracker, etc.). Terrain
-will read the framework's output without invoking it.
+If you need 0.3-grade sandboxing in 0.2, run the eval framework
+yourself in your preferred sandbox (Docker, gVisor, Firecracker,
+etc.) and use `terrain analyze --promptfoo-results` /
+`--deepeval-results` / `--ragas-results` to ingest the resulting
+JSON. Skip `terrain ai run` entirely — it's the only path that
+spawns a child process.
 
 ## Detector boundary (pure-static side)
 
-The 12 AI risk detectors that ship in 0.2 (`aiPromptInjectionRisk`,
-`aiHardcodedAPIKey`, `aiToolWithoutSandbox`, etc.) are all **pure
-static analysis** — they read source code on disk, never invoke an
-LLM. False positives are heuristic; AST-grade taint analysis lands
-in 0.3.
+The AI risk detectors that ship in 0.2 (`aiPromptInjectionRisk`,
+`aiHardcodedAPIKey`, `aiToolWithoutSandbox`,
+`aiModelDeprecationRisk`, `aiFewShotContamination`,
+`aiNonDeterministicEval`, `aiPromptVersioning`,
+`aiSafetyEvalMissing`, `aiToolWithoutSandbox`,
+`aiEmbeddingModelChange`, plus the inventory-tier signals) are all
+**pure static analysis** — they read source code on disk, never
+invoke an LLM. False positives are heuristic; AST-grade taint
+analysis lands in 0.3.
 
 ## What Terrain doesn't promise about AI risk in 0.2