From 7a384b897c10d8bba927671ea432b575529645c9 Mon Sep 17 00:00:00 2001
From: Brett <brettdavies@users.noreply.github.com>
Date: Wed, 22 Apr 2026 18:13:49 -0500
Subject: [PATCH] feat(v0.1.3): resolve 26 ce-review findings + unify audience
 to kebab-case
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Applies every finding from the post-merge ce-review of commit dc5d74168577:
the P1 coverage-summary inflation fix, the full Check::label() trait
migration, the Pattern 2 extraction, the audience_reason field, the
audit_profiles matrix section, the codified regression guards, and the
audience kebab-case unification (post-review decision — see the v0.1.3 H5
plan's Implementation Log for rationale).

## Changelog

### Changed

- Scorecard JSON `audience` values now serialize as kebab-case
  (`agent-optimized` / `mixed` / `human-primary`) to match `audit_profile`'s
  kebab-case within the same document. Consumers keying on the v0.1.2
  `null` fallback are unaffected; any v0.1.3 consumer must pin on the
  kebab-case shape.
- `coverage_summary.{must,should,may}.verified` no longer counts
  `--audit-profile`-suppressed Skips. Suppression means the requirement
  was not verified, so the metric now matches what the site leaderboard
  renders per tool.

### Added

- `audience_reason` field on scorecard JSON, populated only when
  `audience` is `null`: `"suppressed"` (signal check masked by
  `--audit-profile`) or `"insufficient_signal"` (signal check never
  produced, e.g. source-only run). Additive to v1.1; omitted when
  `audience` has a label.
- Top-level `audit_profiles` array in `coverage/matrix.json` — each entry
  carries `{name, description, suppresses[]}`, letting agents enumerate
  the four categories and their per-category suppressions without
  scraping `--help`.
- `Check::label()` trait method; every check now exposes its human label
  at the trait level. `--audit-profile`-suppressed and errored results
  now show the human label (e.g., "Respects NO_COLOR") instead of
  falling back to the check id.
- `EnvHintSource` enum (`clap_annotation` / `proximity` / `env_section`)
  on every emitted `EnvHint` so agents debugging a Pattern 2 false
  positive can see which branch matched. `audit_profile` descriptions in
  the coverage-matrix artifact explain each suppression category.

### Fixed

- `p1-env-hints` Pattern 2 no longer matches `$PAGER` in flag prose
  (added to `SHELL_ENV_BLACKLIST`; the doc comment always cited it as
  the archetypal exclusion but the slice omitted it). Also no longer
  captures uppercase-underscored section-header lines such as
  `DOCKER_CONFIG:` as env hints.

## Type of Change

- [x] `feat`: New feature (non-breaking for v1.1 consumers that
  feature-detected `audience`/`audit_profile` as null)

## Testing

- Unit tests: 402 passing (net +8 new vs. v0.1.3-rc)
- Integration tests: 50 passing (net +3 new)
- `cargo clippy --all-targets -- -Dwarnings`: clean
- `cargo fmt --check`: clean
- `cargo deny check`: clean
- `scripts/hooks/pre-push` (full local CI mirror): all checks passed
- `anc generate coverage-matrix --check`: no drift
- Dogfood: `anc check . --output json` returns
  `schema_version: "1.1"`, `audience: "agent-optimized"`,
  `audit_profile: null`, with `audience_reason` omitted.
- Dogfood under profile: `anc check . --audit-profile human-tui` returns
  `audience: null`, `audience_reason: "suppressed"`,
  `coverage_summary.must.verified` drops from 17 → 15 (no longer counts
  the suppressed P1 checks).

## Key ce-review findings resolved

- **P1 #1** — `build_coverage_summary` excluded suppressed Skips via
  `audience::is_audit_profile_suppression`; regression test added.
- **P2 #2** — `PAGER` added to `SHELL_ENV_BLACKLIST`; negative test
  covers the full trio (`$PATH`, `$HOME`, `$PAGER`).
- **P2 #3** — `SUPPRESSION_EVIDENCE_PREFIX` extracted in
  `src/principles/registry.rs`; producer (`main.rs`), consumer
  (`scorecard::audience::is_audit_profile_suppression`), and filter
  (`build_coverage_summary`) all reference the single constant.
- **P2 #4, #5** — README.md and AGENTS.md rewritten for the shipped
  v0.1.3 JSON surface, including the `--audit-profile` flag example and
  the committed `audit_profiles` matrix pointer.
- **P2 #6** — `Check::label()` abstract trait method + full migration
  across all 40 check impls + `main.rs` error/suppression branches
  + `FakeCheck` stubs in matrix.rs and scorecard/mod.rs test modules.
- **P2 #7 / P3 #11** — `help_probe.rs` (931 LoC) extracted to
  `help_probe/mod.rs` (~540) + `help_probe/env_hints_bash.rs` (~440)
  via `git mv` (history preserved); `EnvHintSource` enum introduced at
  parent scope so both patterns can tag emitted hints.
- **P2 #8, #9, #10** — tightened `test_audit_profile_diagnostic_does_not_panic_on_self`
  to assert p5-dry-run suppression; added `test_audience_non_null_on_self_dogfood`
  + two `AuditProfile ↔ ExceptionCategory` parity drift tests.
- **P3 #12** — `audit_profiles` section in `coverage/matrix.json`.
- **P3 #13** — `audience_reason` field + `classify_reason()` helper.
- **P3 #15** — shared `is_section_header_line` predicate used by both
  `find_env_section` and `extract_env_tokens`.
- **P3 #18** — `test_scorecard_json_has_stable_top_level_keys` locks
  the v1.1 JSON shape bidirectionally.
- **P3 #23** — `debug_assert!` in `classify()` against duplicate signal
  IDs; `#[should_panic]` test pins the invariant.
- **P3 #25** — `test_principle_filter_forces_audience_null` covers
  `--principle` + audience interaction.
- **P3 #26** — Pattern 2 negative fixtures reject `$Path`, `[FILES]`,
  `<TEMPLATE>`, `CamelCase`, `MACROname`.
- **#16, #17, #20, #22** — codified tests for intentional exit-code
  behavior under suppression, kebab-case JSON contract, `fn run()`-only
  `CheckResult` construction in `src/checks/**`, and Pattern 2's
  bracketed-env-var rejection window.
- Several advisories (#14, #16, #17, #19, #20, #21, #22, #24) landed as
  targeted doc comments on `SUPPRESSION_TABLE`, `exit_code`, `Scorecard`,
  `extract_env_tokens`, and CLAUDE.md's Source Check Convention section.

## Files Modified

**Renamed:** `src/runner/help_probe.rs` → `src/runner/help_probe/mod.rs`
(detected as rename by git; blame preserved).

**New:** `src/runner/help_probe/env_hints_bash.rs`.

**Rust sources (45 files):** `src/check.rs`, `src/cli.rs`, `src/main.rs`,
40 check files under `src/checks/**`, `src/principles/{matrix.rs,registry.rs}`,
`src/runner/help_probe/{mod.rs,env_hints_bash.rs}`,
`src/scorecard/{audience.rs,mod.rs}`, `tests/integration.rs`.

**Artifacts:** `coverage/matrix.json` regenerated (adds `audit_profiles`).

**Docs:** `README.md`, `AGENTS.md`, `CLAUDE.md`.

## Breaking Changes

- [x] No breaking changes for v0.1.2 consumers (emitted `audience: null`
  and `audit_profile: null`).
- [x] Kebab-case audience values require v0.1.3 consumers that pinned on
  snake_case to update. The site's H6 leaderboard hasn't shipped; see
  `agentnative-site/docs/plans/2026-04-21-v013-handoff-6-site-leaderboard-launch.md`
  Unit 0.5 for the pre-regen site-side adaptation plan.

## Deployment Notes

- [x] Release-branch mechanics per `RELEASES.md` happen in the follow-up
  PR: branch off `origin/main`, cherry-pick these commits, bump
  `Cargo.toml` `0.1.2 → 0.1.3`, regenerate changelog, PR to `main`.
---
 AGENTS.md                                     |  28 +
 CLAUDE.md                                     |  15 +-
 README.md                                     |  19 +-
 coverage/matrix.json                          |  36 +-
 src/check.rs                                  |   9 +
 src/checks/behavioral/bad_args.rs             |   6 +-
 src/checks/behavioral/env_hints.rs            |   6 +-
 src/checks/behavioral/flag_existence.rs       |   8 +-
 src/checks/behavioral/help.rs                 |   6 +-
 src/checks/behavioral/json_output.rs          |   6 +-
 src/checks/behavioral/no_color.rs             |  10 +-
 src/checks/behavioral/no_pager_behavioral.rs  |   6 +-
 src/checks/behavioral/non_interactive.rs      |   6 +-
 src/checks/behavioral/quiet.rs                |   6 +-
 src/checks/behavioral/sigpipe.rs              |   6 +-
 src/checks/behavioral/version.rs              |   6 +-
 src/checks/project/agents_md.rs               |   6 +-
 src/checks/project/completions.rs             |   6 +-
 src/checks/project/dependencies.rs            |   6 +-
 src/checks/project/dry_run.rs                 |   6 +-
 src/checks/project/error_module.rs            |  10 +-
 src/checks/project/non_interactive.rs         |   6 +-
 src/checks/source/python/bare_except.rs       |   6 +-
 src/checks/source/python/no_color.rs          |   6 +-
 src/checks/source/python/sys_exit.rs          |   6 +-
 src/checks/source/rust/env_flags.rs           |   6 +-
 src/checks/source/rust/error_types.rs         |   6 +-
 src/checks/source/rust/exit_codes.rs          |   6 +-
 src/checks/source/rust/global_flags.rs        |   6 +-
 src/checks/source/rust/headless_auth.rs       |   6 +-
 src/checks/source/rust/naked_println.rs       |   6 +-
 src/checks/source/rust/no_color.rs            |   6 +-
 src/checks/source/rust/no_pager.rs            |   6 +-
 src/checks/source/rust/output_clamping.rs     |   6 +-
 src/checks/source/rust/output_module.rs       |   8 +-
 src/checks/source/rust/process_exit.rs        |   6 +-
 src/checks/source/rust/structured_output.rs   |   6 +-
 src/checks/source/rust/timeout_flag.rs        |   6 +-
 src/checks/source/rust/try_parse.rs           |   6 +-
 src/checks/source/rust/tty_detection.rs       |   6 +-
 src/checks/source/rust/unwrap.rs              |   6 +-
 src/cli.rs                                    |  51 ++
 src/main.rs                                   |   8 +-
 src/principles/matrix.rs                      |  96 +++-
 src/principles/registry.rs                    |  94 ++++
 src/runner/help_probe/env_hints_bash.rs       | 478 ++++++++++++++++++
 .../{help_probe.rs => help_probe/mod.rs}      | 397 ++-------------
 src/scorecard/audience.rs                     | 159 +++++-
 src/scorecard/mod.rs                          | 292 ++++++++++-
 tests/integration.rs                          | 248 ++++++++-
 50 files changed, 1728 insertions(+), 430 deletions(-)
 create mode 100644 src/runner/help_probe/env_hints_bash.rs
 rename src/runner/{help_probe.rs => help_probe/mod.rs} (58%)

diff --git a/AGENTS.md b/AGENTS.md
index 46a76ba..fdfb21e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -25,11 +25,39 @@ anc . --binary
 
 # Source checks only (no binary execution)
 anc . --source
+
+# Suppress inapplicable MUSTs for a categorical exception
+anc . --audit-profile human-tui
 ```
 
 Bare `anc` (no arguments) prints help and exits 2. This is a non-negotiable fork-bomb guard: when agentnative dogfoods
 itself, children spawned without arguments must not recurse into `check .`.
 
+## Agent-facing JSON surface
+
+`anc check <target> --output json` emits a `schema_version: "1.1"` scorecard. Four fields are additive to v1.1 and v1.1
+consumers feature-detect them:
+
+- `audience` — `"agent-optimized"` / `"mixed"` / `"human-primary"` / `null`. Derived from 4 signal behavioral checks
+  (`p1-non-interactive`, `p2-json-output`, `p7-quiet`, `p6-no-color-behavioral`). Informational only; never gates totals
+  or exit codes.
+- `audience_reason` — present only when `audience` is `null`. Values: `"suppressed"` (signal check masked by
+  `--audit-profile`) or `"insufficient_signal"` (signal check never produced). Tells an agent *why* there's no label.
+- `audit_profile` — echoes the applied `--audit-profile <category>` flag value. `null` when no profile is set.
+- `coverage_summary.{must,should,may}.verified` — requirements verified by a check that actually ran. Checks suppressed
+  by `--audit-profile` do not count as verified; suppression means verification was intentionally skipped.
+
+`--audit-profile` accepts exactly 4 values: `human-tui`, `file-traversal`, `posix-utility`, `diagnostic-only`.
+Unknown values exit 2 with a structured error. The full per-category mapping of suppressed check IDs is committed to
+`coverage/matrix.json` under the `audit_profiles` section — agents should read that file rather than scraping `--help`:
+
+```bash
+jaq '.audit_profiles' coverage/matrix.json
+```
+
+Suppressed checks appear in `results[]` as `status: "skip"` with evidence starting with `"suppressed by audit_profile:
+"` (the shared prefix is pinned in `src/principles/registry.rs` as `SUPPRESSION_EVIDENCE_PREFIX`).
+
 ## Exit Codes
 
 - `0` — all checks passed
diff --git a/CLAUDE.md b/CLAUDE.md
index f10cc53..01e0e95 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -69,11 +69,18 @@ Key decisions already made:
 Most source checks follow this structure (a few legacy helpers in `output_module.rs` and `error_types.rs` use
 different helper shapes but still satisfy the core contract that `run()` is the sole `CheckResult` constructor):
 
-- **Struct** implements `Check` trait with `id()`, `group()`, `layer()`, `applicable()`, `run()`
+- **Struct** implements `Check` trait with `id()`, `label()`, `group()`, `layer()`, `applicable()`, `run()`
 - **`check_x()` helper** takes `(source: &str)` (or `(source: &str, file: &str)` when evidence needs file location
   context) and returns `CheckStatus` (not `CheckResult`) — this is the unit-testable core
-- **`run()` is the sole `CheckResult` constructor** — uses `self.id()`, `self.group()`, `self.layer()` to build the
-  result. Never hardcode ID/group/layer string literals in `check_x()` or anywhere outside `run()`
+- **No `Check` impl constructs `CheckResult` outside its own `run()`.** `run()` is the sole place each check assembles
+  its own result — never hardcode ID/group/layer/label string literals in `check_x()` or anywhere outside `run()`. The
+  runtime layer (`main::run`'s error and `--audit-profile` suppression branches) legitimately constructs `CheckResult`
+  as a *second* site — it's the runner, not a `Check` impl, and it uses `check.id()`, `check.label()`, `check.group()`,
+  `check.layer()` from the trait (never string literals). Test doubles (`FakeCheck` in `src/principles/matrix.rs` and
+  `src/scorecard/mod.rs`) similarly sidestep the rule by design.
+- **`label()` returns `&'static str`** and feeds the `label` field in `run()`'s `CheckResult`. Having the label on the
+  trait also means the suppression and error branches can show the human label instead of falling back to the opaque
+  `id`. See `src/check.rs`.
 - **Tests call `check_x()`** and match on `CheckStatus` directly, not `result.status`
 
 This prevents ID triplication (the same string literal in `id()`, `run()`, and `check_x()`) and ensures the `Check`
@@ -139,7 +146,7 @@ deliberate commit, not a build-time artifact — the matrix is citable from outs
 - `coverage_summary` — three-way `{must, should, may} × {total, verified}` counts, computed from the checks that
   actually ran. Populated every run.
 - `audience` — `Option<String>`, derived by `src/scorecard/audience.rs::classify()` from the 4 signal behavioral checks.
-  Emits `"agent_optimized"`, `"mixed"`, `"human_primary"`, or `null` when any signal check is missing from results
+  Emits `"agent-optimized"`, `"mixed"`, `"human-primary"`, or `null` when any signal check is missing from results
   (including when suppressed by `--audit-profile`). The classifier is read-only over results and never gates totals or
   exit codes — per CEO review Finding #3, label mismatches are fixed via registry, not classifier logic.
 - `audit_profile` — `Option<String>`, echoes the applied `--audit-profile` flag value (`"human-tui"`,
diff --git a/README.md b/README.md
index b527548..0b0a7c9 100644
--- a/README.md
+++ b/README.md
@@ -186,15 +186,26 @@ Produces a scorecard (`schema_version: "1.1"`) with results, summary, and covera
     "should": { "total": 16, "verified": 2 },
     "may":   { "total": 7,  "verified": 0 }
   },
-  "audience": null,
+  "audience": "agent-optimized",
   "audit_profile": null
 }
 ```
 
 - `coverage_summary` — how many MUSTs/SHOULDs/MAYs the checks that ran actually verified, against the spec registry's
-  totals. See `docs/coverage-matrix.md` for the per-requirement breakdown.
-- `audience` / `audit_profile` — reserved for v0.1.3 (audience classifier + `registry.yaml` suppression). Serialize as
-  `null` today; consumers should feature-detect.
+  totals. See `docs/coverage-matrix.md` for the per-requirement breakdown. Checks suppressed by `--audit-profile` do
+  **not** count toward `verified` — suppression means the requirement was not verified, even if the check is skipped
+  rather than run.
+- `audience` — derived classification from 4 signal behavioral checks (`p1-non-interactive`, `p2-json-output`,
+  `p7-quiet`, `p6-no-color-behavioral`). Emits `agent-optimized` (0-1 Warns), `mixed` (2 Warns), or `human-primary` (3-4
+  Warns). Returns `null` when any signal check failed to run (source-only mode, missing runner, or `--audit-profile`
+  suppression). Informational only — never gates totals or exit codes. Values serialize as kebab-case to match
+  `audit_profile`'s format within the same JSON document.
+- `audience_reason` — present only when `audience` is `null`. Values: `suppressed` (at least one signal check was masked
+  by `--audit-profile`) or `insufficient_signal` (signal check never produced, e.g. source-only run). Additive to schema
+  v1.1; v1.1 consumers feature-detect.
+- `audit_profile` — echoes the applied `--audit-profile <category>` flag value (`human-tui`, `file-traversal`,
+  `posix-utility`, or `diagnostic-only`). `null` when no profile is set. See `coverage/matrix.json` under
+  `audit_profiles` for the committed per-category mapping of which check IDs each profile suppresses.
 
 ## Contributing
 
diff --git a/coverage/matrix.json b/coverage/matrix.json
index 13c5cee..2f349d5 100644
--- a/coverage/matrix.json
+++ b/coverage/matrix.json
@@ -627,5 +627,39 @@
       "total": 7,
       "covered": 0
     }
-  }
+  },
+  "audit_profiles": [
+    {
+      "name": "human-tui",
+      "description": "TUI-by-design tools (lazygit, k9s, btop). Interactive-prompt MUSTs suppressed; the TTY-driving contract is out of scope for verification.",
+      "suppresses": [
+        "p1-non-interactive",
+        "p1-flag-existence",
+        "p1-non-interactive-source",
+        "p1-tty-detection-source",
+        "p6-sigpipe"
+      ]
+    },
+    {
+      "name": "file-traversal",
+      "description": "File-traversal utilities (fd, find). Subcommand-structure SHOULDs relaxed; these tools have no subcommands by design.",
+      "suppresses": []
+    },
+    {
+      "name": "posix-utility",
+      "description": "POSIX utilities (cat, sed, awk). Stdin-as-primary-input is their contract; P1 interactive-prompt MUSTs satisfied vacuously.",
+      "suppresses": [
+        "p1-non-interactive",
+        "p1-flag-existence",
+        "p1-non-interactive-source"
+      ]
+    },
+    {
+      "name": "diagnostic-only",
+      "description": "Diagnostic tools (nvidia-smi, vmstat). No write operations, so the P5 mutation-boundary MUSTs do not apply.",
+      "suppresses": [
+        "p5-dry-run"
+      ]
+    }
+  ]
 }
\ No newline at end of file
diff --git a/src/check.rs b/src/check.rs
index 7cb9aa0..473a2a7 100644
--- a/src/check.rs
+++ b/src/check.rs
@@ -6,6 +6,15 @@ pub trait Check {
     /// Unique identifier for this check (e.g., "code-unwrap", "p3-help").
     fn id(&self) -> &str;
 
+    /// Human-readable one-line label. Surfaces in scorecard JSON
+    /// (`results[].label`) and text output. Every `run()` implementation
+    /// must hand this same string to `CheckResult`, and the suppression
+    /// and error branches in `main::run` use it so that a check
+    /// short-circuited by `--audit-profile` or an internal error
+    /// produces the same label the user would see on a successful run —
+    /// rather than falling back to the opaque `id`.
+    fn label(&self) -> &'static str;
+
     /// Which principle or category this check belongs to.
     fn group(&self) -> CheckGroup;
 
diff --git a/src/checks/behavioral/bad_args.rs b/src/checks/behavioral/bad_args.rs
index 273189f..10db5c6 100644
--- a/src/checks/behavioral/bad_args.rs
+++ b/src/checks/behavioral/bad_args.rs
@@ -10,6 +10,10 @@ impl Check for BadArgsCheck {
         "p4-bad-args"
     }
 
+    fn label(&self) -> &'static str {
+        "Rejects invalid arguments"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P4
     }
@@ -46,7 +50,7 @@ impl Check for BadArgsCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "Rejects invalid arguments".into(),
+            label: self.label().into(),
             group: CheckGroup::P4,
             layer: CheckLayer::Behavioral,
             status,
diff --git a/src/checks/behavioral/env_hints.rs b/src/checks/behavioral/env_hints.rs
index d59a92a..e0dc91f 100644
--- a/src/checks/behavioral/env_hints.rs
+++ b/src/checks/behavioral/env_hints.rs
@@ -20,6 +20,10 @@ impl Check for EnvHintsCheck {
         "p1-env-hints"
     }
 
+    fn label(&self) -> &'static str {
+        "Flags advertise env-var bindings in --help"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P1
     }
@@ -44,7 +48,7 @@ impl Check for EnvHintsCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "Flags advertise env-var bindings in --help".into(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status,
diff --git a/src/checks/behavioral/flag_existence.rs b/src/checks/behavioral/flag_existence.rs
index caf2252..6216c1a 100644
--- a/src/checks/behavioral/flag_existence.rs
+++ b/src/checks/behavioral/flag_existence.rs
@@ -42,6 +42,10 @@ impl Check for FlagExistenceCheck {
         "p1-flag-existence"
     }
 
+    fn label(&self) -> &'static str {
+        "Non-interactive gate flag advertised in --help"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P1
     }
@@ -72,7 +76,7 @@ impl Check for FlagExistenceCheck {
         if help_on_bare || stdin_clean_exit {
             return Ok(CheckResult {
                 id: self.id().to_string(),
-                label: "Non-interactive gate flag advertised in --help".into(),
+                label: self.label().into(),
                 group: self.group(),
                 layer: self.layer(),
                 status: CheckStatus::Skip(
@@ -104,7 +108,7 @@ impl Check for FlagExistenceCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "Non-interactive gate flag advertised in --help".into(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status,
diff --git a/src/checks/behavioral/help.rs b/src/checks/behavioral/help.rs
index 324c310..d92d369 100644
--- a/src/checks/behavioral/help.rs
+++ b/src/checks/behavioral/help.rs
@@ -10,6 +10,10 @@ impl Check for HelpCheck {
         "p3-help"
     }
 
+    fn label(&self) -> &'static str {
+        "Help flag produces useful output"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P3
     }
@@ -55,7 +59,7 @@ impl Check for HelpCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "Help flag produces useful output".into(),
+            label: self.label().into(),
             group: CheckGroup::P3,
             layer: CheckLayer::Behavioral,
             status,
diff --git a/src/checks/behavioral/json_output.rs b/src/checks/behavioral/json_output.rs
index fb02cba..998e72b 100644
--- a/src/checks/behavioral/json_output.rs
+++ b/src/checks/behavioral/json_output.rs
@@ -10,6 +10,10 @@ impl Check for JsonOutputCheck {
         "p2-json-output"
     }
 
+    fn label(&self) -> &'static str {
+        "Structured output support"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P2
     }
@@ -51,7 +55,7 @@ impl Check for JsonOutputCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "Structured output support".into(),
+            label: self.label().into(),
             group: CheckGroup::P2,
             layer: CheckLayer::Behavioral,
             status,
diff --git a/src/checks/behavioral/no_color.rs b/src/checks/behavioral/no_color.rs
index 791107d..dc62a4b 100644
--- a/src/checks/behavioral/no_color.rs
+++ b/src/checks/behavioral/no_color.rs
@@ -10,6 +10,10 @@ impl Check for NoColorBehavioralCheck {
         "p6-no-color-behavioral"
     }
 
+    fn label(&self) -> &'static str {
+        "Respects NO_COLOR"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P6
     }
@@ -47,9 +51,9 @@ impl Check for NoColorBehavioralCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "Respects NO_COLOR".into(),
-            group: CheckGroup::P6,
-            layer: CheckLayer::Behavioral,
+            label: self.label().into(),
+            group: self.group(),
+            layer: self.layer(),
             status,
             confidence: Confidence::High,
         })
diff --git a/src/checks/behavioral/no_pager_behavioral.rs b/src/checks/behavioral/no_pager_behavioral.rs
index e90b987..991a5de 100644
--- a/src/checks/behavioral/no_pager_behavioral.rs
+++ b/src/checks/behavioral/no_pager_behavioral.rs
@@ -24,6 +24,10 @@ impl Check for NoPagerBehavioralCheck {
         "p6-no-pager-behavioral"
     }
 
+    fn label(&self) -> &'static str {
+        "Pager-using CLI ships --no-pager escape hatch"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P6
     }
@@ -48,7 +52,7 @@ impl Check for NoPagerBehavioralCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "Pager-using CLI ships --no-pager escape hatch".into(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status,
diff --git a/src/checks/behavioral/non_interactive.rs b/src/checks/behavioral/non_interactive.rs
index 125fc96..d59b757 100644
--- a/src/checks/behavioral/non_interactive.rs
+++ b/src/checks/behavioral/non_interactive.rs
@@ -34,6 +34,10 @@ impl Check for NonInteractiveCheck {
         "p1-non-interactive"
     }
 
+    fn label(&self) -> &'static str {
+        "Non-interactive by default"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P1
     }
@@ -98,7 +102,7 @@ impl Check for NonInteractiveCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "Non-interactive by default".into(),
+            label: self.label().into(),
             group: CheckGroup::P1,
             layer: CheckLayer::Behavioral,
             status,
diff --git a/src/checks/behavioral/quiet.rs b/src/checks/behavioral/quiet.rs
index f4d89f8..7c34d35 100644
--- a/src/checks/behavioral/quiet.rs
+++ b/src/checks/behavioral/quiet.rs
@@ -10,6 +10,10 @@ impl Check for QuietCheck {
         "p7-quiet"
     }
 
+    fn label(&self) -> &'static str {
+        "Quiet mode available"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P7
     }
@@ -44,7 +48,7 @@ impl Check for QuietCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "Quiet mode available".into(),
+            label: self.label().into(),
             group: CheckGroup::P7,
             layer: CheckLayer::Behavioral,
             status,
diff --git a/src/checks/behavioral/sigpipe.rs b/src/checks/behavioral/sigpipe.rs
index 4255fee..a6b042e 100644
--- a/src/checks/behavioral/sigpipe.rs
+++ b/src/checks/behavioral/sigpipe.rs
@@ -10,6 +10,10 @@ impl Check for SigpipeCheck {
         "p6-sigpipe"
     }
 
+    fn label(&self) -> &'static str {
+        "Handles SIGPIPE gracefully"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P6
     }
@@ -40,7 +44,7 @@ impl Check for SigpipeCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "Handles SIGPIPE gracefully".into(),
+            label: self.label().into(),
             group: CheckGroup::P6,
             layer: CheckLayer::Behavioral,
             status,
diff --git a/src/checks/behavioral/version.rs b/src/checks/behavioral/version.rs
index d504016..2267bf9 100644
--- a/src/checks/behavioral/version.rs
+++ b/src/checks/behavioral/version.rs
@@ -10,6 +10,10 @@ impl Check for VersionCheck {
         "p3-version"
     }
 
+    fn label(&self) -> &'static str {
+        "Version flag works"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P3
     }
@@ -42,7 +46,7 @@ impl Check for VersionCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "Version flag works".into(),
+            label: self.label().into(),
             group: CheckGroup::P3,
             layer: CheckLayer::Behavioral,
             status,
diff --git a/src/checks/project/agents_md.rs b/src/checks/project/agents_md.rs
index dbd9f0c..0804cbf 100644
--- a/src/checks/project/agents_md.rs
+++ b/src/checks/project/agents_md.rs
@@ -14,6 +14,10 @@ impl Check for AgentsMdCheck {
         "p6-agents-md"
     }
 
+    fn label(&self) -> &'static str {
+        "AGENTS.md exists"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P6
     }
@@ -37,7 +41,7 @@ impl Check for AgentsMdCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "AGENTS.md exists".into(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status,
diff --git a/src/checks/project/completions.rs b/src/checks/project/completions.rs
index 81d075f..b631d7b 100644
--- a/src/checks/project/completions.rs
+++ b/src/checks/project/completions.rs
@@ -16,6 +16,10 @@ impl Check for CompletionsCheck {
         "p6-completions"
     }
 
+    fn label(&self) -> &'static str {
+        "Shell completions support"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P6
     }
@@ -56,7 +60,7 @@ impl Check for CompletionsCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "Shell completions support".into(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status,
diff --git a/src/checks/project/dependencies.rs b/src/checks/project/dependencies.rs
index 99b6407..687915f 100644
--- a/src/checks/project/dependencies.rs
+++ b/src/checks/project/dependencies.rs
@@ -28,6 +28,10 @@ impl Check for DependenciesCheck {
         "p6-dependencies"
     }
 
+    fn label(&self) -> &'static str {
+        "Recommended dependencies present"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P6
     }
@@ -67,7 +71,7 @@ impl Check for DependenciesCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "Recommended dependencies present".into(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status,
diff --git a/src/checks/project/dry_run.rs b/src/checks/project/dry_run.rs
index c567d95..cb0e861 100644
--- a/src/checks/project/dry_run.rs
+++ b/src/checks/project/dry_run.rs
@@ -45,6 +45,10 @@ impl Check for DryRunCheck {
         "p5-dry-run"
     }
 
+    fn label(&self) -> &'static str {
+        "Dry-run flag for write operations"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P5
     }
@@ -99,7 +103,7 @@ impl Check for DryRunCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "Dry-run flag for write operations".into(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status,
diff --git a/src/checks/project/error_module.rs b/src/checks/project/error_module.rs
index 98a004c..5848b5d 100644
--- a/src/checks/project/error_module.rs
+++ b/src/checks/project/error_module.rs
@@ -16,6 +16,10 @@ impl Check for ErrorModuleCheck {
         "p4-error-module"
     }
 
+    fn label(&self) -> &'static str {
+        "Dedicated error module exists"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P4
     }
@@ -41,7 +45,7 @@ impl Check for ErrorModuleCheck {
             if src_dir.join(candidate).exists() {
                 return Ok(CheckResult {
                     id: self.id().to_string(),
-                    label: "Dedicated error module exists".into(),
+                    label: self.label().into(),
                     group: self.group(),
                     layer: self.layer(),
                     status: CheckStatus::Pass,
@@ -60,7 +64,7 @@ impl Check for ErrorModuleCheck {
                             if path.join(name).exists() {
                                 return Ok(CheckResult {
                                     id: self.id().to_string(),
-                                    label: "Dedicated error module exists".into(),
+                                    label: self.label().into(),
                                     group: self.group(),
                                     layer: self.layer(),
                                     status: CheckStatus::Pass,
@@ -75,7 +79,7 @@ impl Check for ErrorModuleCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "Dedicated error module exists".into(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status: CheckStatus::Warn(
diff --git a/src/checks/project/non_interactive.rs b/src/checks/project/non_interactive.rs
index 4ef0208..50a5bf6 100644
--- a/src/checks/project/non_interactive.rs
+++ b/src/checks/project/non_interactive.rs
@@ -19,6 +19,10 @@ impl Check for NonInteractiveSourceCheck {
         "p1-non-interactive-source"
     }
 
+    fn label(&self) -> &'static str {
+        "No interactive prompt dependencies"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P1
     }
@@ -62,7 +66,7 @@ impl Check for NonInteractiveSourceCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "No interactive prompt dependencies".into(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status,
diff --git a/src/checks/source/python/bare_except.rs b/src/checks/source/python/bare_except.rs
index 6687f6a..6d52a72 100644
--- a/src/checks/source/python/bare_except.rs
+++ b/src/checks/source/python/bare_except.rs
@@ -19,6 +19,10 @@ impl Check for BareExceptCheck {
         "code-bare-except"
     }
 
+    fn label(&self) -> &'static str {
+        "No bare except: clauses"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::CodeQuality
     }
@@ -50,7 +54,7 @@ impl Check for BareExceptCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "No bare except: clauses".to_string(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status,
diff --git a/src/checks/source/python/no_color.rs b/src/checks/source/python/no_color.rs
index 478b17e..234e1db 100644
--- a/src/checks/source/python/no_color.rs
+++ b/src/checks/source/python/no_color.rs
@@ -24,6 +24,10 @@ impl Check for NoColorPythonCheck {
         "p6-no-color"
     }
 
+    fn label(&self) -> &'static str {
+        "Respects NO_COLOR"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P6
     }
@@ -64,7 +68,7 @@ impl Check for NoColorPythonCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "Respects NO_COLOR".to_string(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status,
diff --git a/src/checks/source/python/sys_exit.rs b/src/checks/source/python/sys_exit.rs
index b60e42d..2b015c2 100644
--- a/src/checks/source/python/sys_exit.rs
+++ b/src/checks/source/python/sys_exit.rs
@@ -20,6 +20,10 @@ impl Check for SysExitCheck {
         "p4-sys-exit"
     }
 
+    fn label(&self) -> &'static str {
+        "No sys.exit() outside __main__ guard"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P4
     }
@@ -56,7 +60,7 @@ impl Check for SysExitCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "No sys.exit() outside __main__ guard".to_string(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status,
diff --git a/src/checks/source/rust/env_flags.rs b/src/checks/source/rust/env_flags.rs
index 1a6efc5..66ece8a 100644
--- a/src/checks/source/rust/env_flags.rs
+++ b/src/checks/source/rust/env_flags.rs
@@ -27,6 +27,10 @@ impl Check for EnvFlagsCheck {
         "p1-env-flags-source"
     }
 
+    fn label(&self) -> &'static str {
+        "Agentic flags have env backing"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P1
     }
@@ -75,7 +79,7 @@ impl Check for EnvFlagsCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "Agentic flags have env backing".to_string(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status,
diff --git a/src/checks/source/rust/error_types.rs b/src/checks/source/rust/error_types.rs
index 9c570ea..93d934e 100644
--- a/src/checks/source/rust/error_types.rs
+++ b/src/checks/source/rust/error_types.rs
@@ -21,6 +21,10 @@ impl Check for ErrorTypesCheck {
         "p4-error-types"
     }
 
+    fn label(&self) -> &'static str {
+        "Structured error types"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P4
     }
@@ -60,7 +64,7 @@ impl Check for ErrorTypesCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "Structured error types".to_string(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status,
diff --git a/src/checks/source/rust/exit_codes.rs b/src/checks/source/rust/exit_codes.rs
index da023fc..7f11bc3 100644
--- a/src/checks/source/rust/exit_codes.rs
+++ b/src/checks/source/rust/exit_codes.rs
@@ -22,6 +22,10 @@ impl Check for ExitCodesCheck {
         "p4-exit-codes"
     }
 
+    fn label(&self) -> &'static str {
+        "Exit codes use named constants"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P4
     }
@@ -57,7 +61,7 @@ impl Check for ExitCodesCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "Exit codes use named constants".to_string(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status,
diff --git a/src/checks/source/rust/global_flags.rs b/src/checks/source/rust/global_flags.rs
index 9671f11..ef4c7d0 100644
--- a/src/checks/source/rust/global_flags.rs
+++ b/src/checks/source/rust/global_flags.rs
@@ -28,6 +28,10 @@ impl Check for GlobalFlagsCheck {
         "p6-global-flags"
     }
 
+    fn label(&self) -> &'static str {
+        "Agentic flags are global"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P6
     }
@@ -77,7 +81,7 @@ impl Check for GlobalFlagsCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "Agentic flags are global".to_string(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status,
diff --git a/src/checks/source/rust/headless_auth.rs b/src/checks/source/rust/headless_auth.rs
index 38ba7b9..850954e 100644
--- a/src/checks/source/rust/headless_auth.rs
+++ b/src/checks/source/rust/headless_auth.rs
@@ -34,6 +34,10 @@ impl Check for HeadlessAuthCheck {
         "p1-headless-auth"
     }
 
+    fn label(&self) -> &'static str {
+        "Headless auth supported"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P1
     }
@@ -85,7 +89,7 @@ impl Check for HeadlessAuthCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "Headless auth supported".to_string(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status,
diff --git a/src/checks/source/rust/naked_println.rs b/src/checks/source/rust/naked_println.rs
index 3713c07..0321c3a 100644
--- a/src/checks/source/rust/naked_println.rs
+++ b/src/checks/source/rust/naked_println.rs
@@ -21,6 +21,10 @@ impl Check for NakedPrintlnCheck {
         "p7-naked-println"
     }
 
+    fn label(&self) -> &'static str {
+        "No naked println!/print! outside output modules"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P7
     }
@@ -60,7 +64,7 @@ impl Check for NakedPrintlnCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "No naked println!/print! outside output modules".to_string(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status,
diff --git a/src/checks/source/rust/no_color.rs b/src/checks/source/rust/no_color.rs
index 3bdd04f..fda908e 100644
--- a/src/checks/source/rust/no_color.rs
+++ b/src/checks/source/rust/no_color.rs
@@ -24,6 +24,10 @@ impl Check for NoColorSourceCheck {
         "p6-no-color"
     }
 
+    fn label(&self) -> &'static str {
+        "Respects NO_COLOR"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P6
     }
@@ -63,7 +67,7 @@ impl Check for NoColorSourceCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "Respects NO_COLOR".to_string(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status,
diff --git a/src/checks/source/rust/no_pager.rs b/src/checks/source/rust/no_pager.rs
index 2de0482..a981085 100644
--- a/src/checks/source/rust/no_pager.rs
+++ b/src/checks/source/rust/no_pager.rs
@@ -23,6 +23,10 @@ impl Check for NoPagerCheck {
         "p6-no-pager"
     }
 
+    fn label(&self) -> &'static str {
+        "No pager blocking agents"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P6
     }
@@ -70,7 +74,7 @@ impl Check for NoPagerCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "No pager blocking agents".to_string(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status,
diff --git a/src/checks/source/rust/output_clamping.rs b/src/checks/source/rust/output_clamping.rs
index d2de96f..92200a4 100644
--- a/src/checks/source/rust/output_clamping.rs
+++ b/src/checks/source/rust/output_clamping.rs
@@ -32,6 +32,10 @@ impl Check for OutputClampingCheck {
         "p7-output-clamping"
     }
 
+    fn label(&self) -> &'static str {
+        "List output is clamped"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P7
     }
@@ -82,7 +86,7 @@ impl Check for OutputClampingCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "List output is clamped".to_string(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status,
diff --git a/src/checks/source/rust/output_module.rs b/src/checks/source/rust/output_module.rs
index 0e55b8b..1b085d6 100644
--- a/src/checks/source/rust/output_module.rs
+++ b/src/checks/source/rust/output_module.rs
@@ -23,6 +23,10 @@ impl Check for OutputModuleCheck {
         "p2-output-module"
     }
 
+    fn label(&self) -> &'static str {
+        "Centralized output module exists"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P2
     }
@@ -50,7 +54,7 @@ impl Check for OutputModuleCheck {
             if has_output_formatting_code(&parsed_file.source) {
                 return Ok(CheckResult {
                     id: self.id().to_string(),
-                    label: "Centralized output module exists".into(),
+                    label: self.label().into(),
                     group: self.group(),
                     layer: self.layer(),
                     status: CheckStatus::Pass,
@@ -61,7 +65,7 @@ impl Check for OutputModuleCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "Centralized output module exists".into(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status: CheckStatus::Warn(
diff --git a/src/checks/source/rust/process_exit.rs b/src/checks/source/rust/process_exit.rs
index 8287abc..779ebfa 100644
--- a/src/checks/source/rust/process_exit.rs
+++ b/src/checks/source/rust/process_exit.rs
@@ -18,6 +18,10 @@ impl Check for ProcessExitCheck {
         "p4-process-exit"
     }
 
+    fn label(&self) -> &'static str {
+        "No process::exit outside main"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P4
     }
@@ -55,7 +59,7 @@ impl Check for ProcessExitCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "No process::exit outside main".to_string(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status,
diff --git a/src/checks/source/rust/structured_output.rs b/src/checks/source/rust/structured_output.rs
index cb5a056..b6efe4f 100644
--- a/src/checks/source/rust/structured_output.rs
+++ b/src/checks/source/rust/structured_output.rs
@@ -19,6 +19,10 @@ impl Check for StructuredOutputCheck {
         "p2-structured-output"
     }
 
+    fn label(&self) -> &'static str {
+        "Structured output type exists"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P2
     }
@@ -70,7 +74,7 @@ impl Check for StructuredOutputCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "Structured output type exists".to_string(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status,
diff --git a/src/checks/source/rust/timeout_flag.rs b/src/checks/source/rust/timeout_flag.rs
index 207cb05..1dc1049 100644
--- a/src/checks/source/rust/timeout_flag.rs
+++ b/src/checks/source/rust/timeout_flag.rs
@@ -22,6 +22,10 @@ impl Check for TimeoutFlagCheck {
         "p6-timeout"
     }
 
+    fn label(&self) -> &'static str {
+        "Timeout flag for network ops"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P6
     }
@@ -73,7 +77,7 @@ impl Check for TimeoutFlagCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "Timeout flag for network ops".to_string(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status,
diff --git a/src/checks/source/rust/try_parse.rs b/src/checks/source/rust/try_parse.rs
index 65750ea..5bc9e0b 100644
--- a/src/checks/source/rust/try_parse.rs
+++ b/src/checks/source/rust/try_parse.rs
@@ -21,6 +21,10 @@ impl Check for TryParseCheck {
         "p4-try-parse"
     }
 
+    fn label(&self) -> &'static str {
+        "No .parse().unwrap()"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P4
     }
@@ -56,7 +60,7 @@ impl Check for TryParseCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "No .parse().unwrap()".to_string(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status,
diff --git a/src/checks/source/rust/tty_detection.rs b/src/checks/source/rust/tty_detection.rs
index 2715741..3ce8301 100644
--- a/src/checks/source/rust/tty_detection.rs
+++ b/src/checks/source/rust/tty_detection.rs
@@ -41,6 +41,10 @@ impl Check for TtyDetectionCheck {
         "p1-tty-detection-source"
     }
 
+    fn label(&self) -> &'static str {
+        "TTY detection for color output"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::P1
     }
@@ -95,7 +99,7 @@ impl Check for TtyDetectionCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "TTY detection for color output".to_string(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status,
diff --git a/src/checks/source/rust/unwrap.rs b/src/checks/source/rust/unwrap.rs
index b34a615..385f20f 100644
--- a/src/checks/source/rust/unwrap.rs
+++ b/src/checks/source/rust/unwrap.rs
@@ -18,6 +18,10 @@ impl Check for UnwrapCheck {
         "code-unwrap"
     }
 
+    fn label(&self) -> &'static str {
+        "No .unwrap() in source"
+    }
+
     fn group(&self) -> CheckGroup {
         CheckGroup::CodeQuality
     }
@@ -49,7 +53,7 @@ impl Check for UnwrapCheck {
 
         Ok(CheckResult {
             id: self.id().to_string(),
-            label: "No .unwrap() in source".to_string(),
+            label: self.label().into(),
             group: self.group(),
             layer: self.layer(),
             status,
diff --git a/src/cli.rs b/src/cli.rs
index 5c329d6..71efb66 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -141,3 +141,54 @@ impl From<AuditProfile> for ExceptionCategory {
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::principles::registry::ALL_EXCEPTION_CATEGORIES;
+    use clap::ValueEnum;
+
+    /// Every CLI `AuditProfile` variant must map to a distinct
+    /// `ExceptionCategory`, and every `ExceptionCategory` must be
+    /// reachable from at least one `AuditProfile` variant. Failing this
+    /// test means adding a category on one side without the other —
+    /// either the CLI accepts a profile that suppresses nothing, or the
+    /// registry defines a category no CLI user can reach.
+    #[test]
+    fn audit_profile_and_exception_category_variants_are_isomorphic() {
+        let cli_mapped: std::collections::HashSet<&'static str> = AuditProfile::value_variants()
+            .iter()
+            .map(|v| ExceptionCategory::from(*v).as_kebab_case())
+            .collect();
+        let registry_kebab: std::collections::HashSet<&'static str> = ALL_EXCEPTION_CATEGORIES
+            .iter()
+            .map(|c| c.as_kebab_case())
+            .collect();
+
+        assert_eq!(
+            cli_mapped, registry_kebab,
+            "AuditProfile (cli) and ExceptionCategory (registry) variants must be isomorphic. \
+             CLI-reachable: {cli_mapped:?}, registry: {registry_kebab:?}",
+        );
+    }
+
+    /// The kebab-case string clap renders for each `AuditProfile` variant
+    /// must equal the kebab-case the registry emits — otherwise the flag
+    /// value a user types on the CLI won't match the `audit_profile` field
+    /// echoed in JSON output.
+    #[test]
+    fn audit_profile_clap_name_matches_registry_kebab_case() {
+        for variant in AuditProfile::value_variants() {
+            let clap_name = variant
+                .to_possible_value()
+                .expect("AuditProfile variants have clap names")
+                .get_name()
+                .to_string();
+            let registry_name = ExceptionCategory::from(*variant).as_kebab_case();
+            assert_eq!(
+                clap_name, registry_name,
+                "clap value name and registry kebab-case must match for every variant",
+            );
+        }
+    }
+}
diff --git a/src/main.rs b/src/main.rs
index 2e2da05..fdbd9a2 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -21,7 +21,7 @@ use checks::source::all_source_checks;
 use cli::{Cli, Commands, GenerateKind, OutputFormat};
 use error::AppError;
 use principles::matrix;
-use principles::registry::{ExceptionCategory, suppresses};
+use principles::registry::{ExceptionCategory, SUPPRESSION_EVIDENCE_PREFIX, suppresses};
 use project::Project;
 use scorecard::audience;
 use scorecard::{exit_code, format_json, format_text};
@@ -145,11 +145,11 @@ fn run() -> Result<i32, AppError> {
             if suppresses(check.id(), cat) {
                 results.push(CheckResult {
                     id: check.id().to_string(),
-                    label: check.id().to_string(),
+                    label: check.label().to_string(),
                     group: check.group(),
                     layer: check.layer(),
                     status: CheckStatus::Skip(format!(
-                        "suppressed by audit_profile: {}",
+                        "{SUPPRESSION_EVIDENCE_PREFIX}{}",
                         cat.as_kebab_case()
                     )),
                     confidence: Confidence::High,
@@ -161,7 +161,7 @@ fn run() -> Result<i32, AppError> {
             Ok(r) => r,
             Err(e) => CheckResult {
                 id: check.id().to_string(),
-                label: check.id().to_string(),
+                label: check.label().to_string(),
                 group: check.group(),
                 layer: check.layer(),
                 status: CheckStatus::Error(e.to_string()),
diff --git a/src/principles/matrix.rs b/src/principles/matrix.rs
index 0c5cbf6..4659915 100644
--- a/src/principles/matrix.rs
+++ b/src/principles/matrix.rs
@@ -15,7 +15,9 @@ use std::fmt::Write as _;
 use serde::Serialize;
 
 use crate::check::Check;
-use crate::principles::registry::{Applicability, Level, REQUIREMENTS};
+use crate::principles::registry::{
+    ALL_EXCEPTION_CATEGORIES, Applicability, Level, REQUIREMENTS, SUPPRESSION_TABLE,
+};
 use crate::types::CheckLayer;
 
 /// A check that covers a given requirement.
@@ -36,6 +38,22 @@ pub struct MatrixRow {
     pub verifiers: Vec<Verifier>,
 }
 
+/// Programmatic listing of every `--audit-profile` value and what it
+/// suppresses. Consumed by the site's regen script and by agents that
+/// want to enumerate suppressible checks without scraping `--help`.
+#[derive(Debug, Serialize)]
+pub struct AuditProfileEntry {
+    /// Kebab-case flag value (e.g., `"human-tui"`) — exactly what a
+    /// caller passes to `anc check --audit-profile <name>`.
+    pub name: &'static str,
+    /// One-line human description of the category.
+    pub description: &'static str,
+    /// Check IDs that emit `Skip` with the audit_profile suppression
+    /// prefix when this profile is active. Empty slice = reserved
+    /// category with no current suppressions.
+    pub suppresses: Vec<&'static str>,
+}
+
 /// The rendered matrix, suitable for JSON serialization.
 #[derive(Debug, Serialize)]
 pub struct Matrix {
@@ -43,6 +61,10 @@ pub struct Matrix {
     pub generated_by: &'static str,
     pub rows: Vec<MatrixRow>,
     pub summary: MatrixSummary,
+    /// Every `--audit-profile` category in a stable order. Agents can
+    /// read this instead of running `anc check --help` to discover the
+    /// valid profile values and what each one excludes.
+    pub audit_profiles: Vec<AuditProfileEntry>,
 }
 
 #[derive(Debug, Serialize)]
@@ -102,9 +124,32 @@ pub fn build(checks: &[Box<dyn Check>]) -> Matrix {
         generated_by: GENERATED_BY,
         rows,
         summary,
+        audit_profiles: build_audit_profiles(),
     }
 }
 
+/// Build the `audit_profiles` section of the matrix. Iterates every
+/// `ExceptionCategory` variant in the registry order and pairs each with
+/// its `SUPPRESSION_TABLE` entry — the order is stable across runs so
+/// consumers can diff matrix.json without noise.
+fn build_audit_profiles() -> Vec<AuditProfileEntry> {
+    ALL_EXCEPTION_CATEGORIES
+        .iter()
+        .map(|cat| {
+            let suppresses: Vec<&'static str> = SUPPRESSION_TABLE
+                .iter()
+                .find(|(c, _)| *c == *cat)
+                .map(|(_, ids)| ids.to_vec())
+                .unwrap_or_default();
+            AuditProfileEntry {
+                name: cat.as_kebab_case(),
+                description: cat.description(),
+                suppresses,
+            }
+        })
+        .collect()
+}
+
 fn summarize(rows: &[MatrixRow]) -> MatrixSummary {
     let mut must = LevelSummary {
         total: 0,
@@ -310,6 +355,9 @@ mod tests {
         fn id(&self) -> &str {
             self.id
         }
+        fn label(&self) -> &'static str {
+            "fake"
+        }
         fn group(&self) -> CheckGroup {
             CheckGroup::P1
         }
@@ -400,4 +448,50 @@ mod tests {
         })];
         assert!(dangling_cover_ids(&checks).is_empty());
     }
+
+    #[test]
+    fn build_audit_profiles_covers_every_registry_variant() {
+        // Emitted list length must equal ALL_EXCEPTION_CATEGORIES length —
+        // an ordering or completeness drift on either side fails here.
+        let profiles = build_audit_profiles();
+        assert_eq!(profiles.len(), ALL_EXCEPTION_CATEGORIES.len());
+        for (i, cat) in ALL_EXCEPTION_CATEGORIES.iter().enumerate() {
+            assert_eq!(
+                profiles[i].name,
+                cat.as_kebab_case(),
+                "audit_profiles[{i}].name must match registry kebab-case",
+            );
+            let expected_suppresses: Vec<&'static str> = SUPPRESSION_TABLE
+                .iter()
+                .find(|(c, _)| *c == *cat)
+                .map(|(_, ids)| ids.to_vec())
+                .unwrap_or_default();
+            assert_eq!(
+                profiles[i].suppresses,
+                expected_suppresses,
+                "audit_profiles[{i}].suppresses must match SUPPRESSION_TABLE for {}",
+                cat.as_kebab_case(),
+            );
+        }
+    }
+
+    #[test]
+    fn matrix_json_includes_audit_profiles_section() {
+        // Build a minimal matrix and verify the rendered JSON has a
+        // top-level `audit_profiles` array that downstream consumers can
+        // key against without re-running suppression logic.
+        let checks: Vec<Box<dyn Check>> = vec![];
+        let matrix = build(&checks);
+        let json = render_json(&matrix);
+        let parsed: serde_json::Value = serde_json::from_str(&json).expect("valid JSON");
+        let arr = parsed["audit_profiles"]
+            .as_array()
+            .expect("audit_profiles is a JSON array");
+        assert_eq!(arr.len(), ALL_EXCEPTION_CATEGORIES.len());
+        for entry in arr {
+            assert!(entry["name"].is_string());
+            assert!(entry["description"].is_string());
+            assert!(entry["suppresses"].is_array());
+        }
+    }
 }
diff --git a/src/principles/registry.rs b/src/principles/registry.rs
index e9dcd74..4c26c89 100644
--- a/src/principles/registry.rs
+++ b/src/principles/registry.rs
@@ -57,8 +57,75 @@ impl ExceptionCategory {
             ExceptionCategory::DiagnosticOnly => "diagnostic-only",
         }
     }
+
+    /// One-line human description. Surfaces in `coverage/matrix.json`
+    /// under the `audit_profiles` section so agents + site renderers can
+    /// explain each category without re-deriving semantics from the
+    /// kebab-case name.
+    pub fn description(&self) -> &'static str {
+        match self {
+            ExceptionCategory::HumanTui => {
+                "TUI-by-design tools (lazygit, k9s, btop). Interactive-prompt MUSTs \
+                 suppressed; the TTY-driving contract is out of scope for verification."
+            }
+            ExceptionCategory::FileTraversal => {
+                "File-traversal utilities (fd, find). Subcommand-structure SHOULDs \
+                 relaxed; these tools have no subcommands by design."
+            }
+            ExceptionCategory::PosixUtility => {
+                "POSIX utilities (cat, sed, awk). Stdin-as-primary-input is their \
+                 contract; P1 interactive-prompt MUSTs satisfied vacuously."
+            }
+            ExceptionCategory::DiagnosticOnly => {
+                "Diagnostic tools (nvidia-smi, vmstat). No write operations, so the \
+                 P5 mutation-boundary MUSTs do not apply."
+            }
+        }
+    }
 }
 
+/// Every `ExceptionCategory` variant in order. Anchor for parity drift
+/// tests (CLI `AuditProfile` must stay isomorphic) and for callers that
+/// need to iterate the full set (suppression-table drift check,
+/// `coverage/matrix.json` audit_profile section).
+///
+/// A new variant on the enum is a breaking plan change — land it in
+/// `docs/plans/`, update this slice, update `SUPPRESSION_TABLE`, update
+/// `AuditProfile`, and regenerate completions. The drift tests below and
+/// in `src/cli.rs` tie all four sites together.
+pub const ALL_EXCEPTION_CATEGORIES: &[ExceptionCategory] = &[
+    ExceptionCategory::HumanTui,
+    ExceptionCategory::FileTraversal,
+    ExceptionCategory::PosixUtility,
+    ExceptionCategory::DiagnosticOnly,
+];
+
+// Compile-time guard that the slice above covers every variant. If a
+// new variant is added without updating ALL_EXCEPTION_CATEGORIES the
+// match is non-exhaustive and the build breaks — making this drift
+// impossible to merge rather than "test should catch it."
+#[allow(dead_code)]
+const fn _all_categories_covers_every_variant(c: ExceptionCategory) -> bool {
+    match c {
+        ExceptionCategory::HumanTui
+        | ExceptionCategory::FileTraversal
+        | ExceptionCategory::PosixUtility
+        | ExceptionCategory::DiagnosticOnly => true,
+    }
+}
+
+/// Prefix of the structured evidence string emitted for any check suppressed
+/// by `--audit-profile`. The full evidence takes the shape
+/// `"suppressed by audit_profile: <kebab-case-category>"`. This is the single
+/// source of truth — `main.rs` (producer), `scorecard::audience` (consumer
+/// sniffer), and the `scorecard::build_coverage_summary` filter all reference
+/// this constant so a rename can't silently desync the three sites.
+///
+/// Consumers outside this crate (the integration test asserting the literal,
+/// downstream site renderers) pin against the stable string shape — treat any
+/// edit here as a consumer-contract change.
+pub const SUPPRESSION_EVIDENCE_PREFIX: &str = "suppressed by audit_profile: ";
+
 /// Which check IDs each exception category suppresses. When a category
 /// applies, the listed checks emit `CheckStatus::Skip` with structured
 /// evidence (`"suppressed by audit_profile: <category>"`) instead of
@@ -77,6 +144,33 @@ impl ExceptionCategory {
 ///
 /// Every listed check ID is validated against the behavioral/source/project
 /// catalog at test time; a typo or rename breaks the build.
+///
+/// # Trust boundary
+///
+/// The CLI accepts `--audit-profile <category>` from the caller without
+/// validating that the target tool actually fits the declared category.
+/// A broken CLI can self-declare `--audit-profile human-tui` and silently
+/// mask the P1 interactive-prompt MUSTs + `p6-sigpipe` that would
+/// otherwise Fail. This is intentional: the CLI only knows what it was
+/// told, and hard-coding per-tool category detection would entangle the
+/// repo-agnostic CLI with a tool registry it deliberately doesn't own.
+/// Guarding against caller-chosen miscategorization is an upstream
+/// concern (site's regen script looks up each tool's declared profile;
+/// CI policy gates reviewer attention on registry changes). See also the
+/// drift test in `src/cli.rs` pinning `AuditProfile` ↔ `ExceptionCategory`
+/// parity and the `audit_profiles` section of `coverage/matrix.json`
+/// publishing the full mapping.
+///
+/// # Drift test scope
+///
+/// The `suppression_table_check_ids_exist_in_catalog` test below verifies
+/// that every listed check ID resolves to a real catalog entry — typos
+/// surface at build time. It does *not* assert that each ID is
+/// *semantically appropriate* for its category (e.g., a typo that
+/// accidentally moves `p2-json-output` into `HumanTui` would still pass
+/// because `p2-json-output` exists). At v0.1.3's 4 committed categories
+/// the per-category slice is short enough for eyeball review; revisit a
+/// per-category snapshot assertion if the table grows.
 pub static SUPPRESSION_TABLE: &[(ExceptionCategory, &[&str])] = &[
     (
         ExceptionCategory::HumanTui,
diff --git a/src/runner/help_probe/env_hints_bash.rs b/src/runner/help_probe/env_hints_bash.rs
new file mode 100644
index 0000000..ebd7143
--- /dev/null
+++ b/src/runner/help_probe/env_hints_bash.rs
@@ -0,0 +1,478 @@
+//! Pattern 2 env-hint detection — bash-style `$FOO` / `TOOL_FOO` tokens
+//! near flag definitions, or inside dedicated `ENVIRONMENT` sections.
+//!
+//! Extracted from `help_probe::mod` as a sibling submodule so the Pattern
+//! 2 machinery (its constants, helpers, and ~9 tests) doesn't crowd the
+//! orchestrator. Parent module's [`parse_env_hints`] calls
+//! [`parse_env_hints_bash_style`] as the second of two merge inputs;
+//! deduplication and source-tagging logic live on the parent side.
+//!
+//! The compounded learning behind these mitigations is
+//! `docs/solutions/best-practices/cli-env-var-shape-heuristic-2026-04-21.md`
+//! — edit both when widening detection.
+//!
+//! See [`super::EnvHint`] for the emitted shape and
+//! [`super::EnvHintSource`] for the provenance tag each pattern attaches.
+
+use std::collections::HashSet;
+
+use super::{EnvHint, EnvHintSource};
+
+/// Shell/system env vars we never want to flag as flag-bound. Tools
+/// routinely mention these in help prose (`respects $PAGER`, `uses $HOME`)
+/// without those being user-configurable flag bindings. Listing them as
+/// env hints would reward tools for documenting the ambient shell.
+const SHELL_ENV_BLACKLIST: &[&str] = &[
+    "PATH", "HOME", "USER", "SHELL", "PWD", "LANG", "TERM", "TMPDIR", "PAGER",
+];
+
+/// Window size (in lines, each direction) for Pattern 2's proximity scan
+/// around a flag definition. Four lines is enough to catch wrapped
+/// descriptions and the usual `[env: ...]`-adjacent prose without
+/// reaching into unrelated flag entries.
+const PATTERN2_WINDOW: usize = 4;
+
+/// Pattern 2 — bash-style `$FOO` or uppercase `FOO_BAR` tokens that
+/// co-occur with a flag definition within a ±4-line window, OR appear in
+/// a dedicated `ENVIRONMENT` / `ENV VARS` section. Filters the
+/// shell-environment blacklist and requires tool-scoped shape (uppercase,
+/// digits, underscores; length ≥ 3).
+///
+/// Strips `[env: ...]` annotations before scanning — those belong to
+/// Pattern 1. Salvaging tokens from rejected annotations (e.g.,
+/// `[env: 1ABC]` contributing `ABC`) would undermine Pattern 1's
+/// decision to reject them.
+///
+/// Each emitted hint carries a [`EnvHintSource`] tag distinguishing the
+/// proximity-window path from the ENVIRONMENT-section path, so agents
+/// debugging a false positive can see which branch matched.
+pub(super) fn parse_env_hints_bash_style(raw: &str) -> Vec<EnvHint> {
+    let stripped = strip_clap_env_annotations(raw);
+    let lines: Vec<&str> = stripped.lines().collect();
+    let flag_line_indices: Vec<usize> = lines
+        .iter()
+        .enumerate()
+        .filter_map(|(i, l)| is_flag_line(l).then_some(i))
+        .collect();
+    let env_section_range = find_env_section(&lines);
+
+    // Track each line's matching source. ENV-section wins over
+    // Proximity when both fire — a dedicated `ENVIRONMENT` header is a
+    // structured, explicit signal, whereas flag-adjacent prose is
+    // weaker (just "the token showed up near a flag line"). Apply
+    // Proximity first, then overwrite with EnvSection where it applies.
+    let mut line_source: Vec<Option<EnvHintSource>> = vec![None; lines.len()];
+    for &idx in &flag_line_indices {
+        let lo = idx.saturating_sub(PATTERN2_WINDOW);
+        let hi = (idx + PATTERN2_WINDOW + 1).min(lines.len());
+        for slot in line_source[lo..hi].iter_mut() {
+            *slot = Some(EnvHintSource::Proximity);
+        }
+    }
+    if let Some((lo, hi)) = env_section_range {
+        for slot in line_source[lo..hi].iter_mut() {
+            *slot = Some(EnvHintSource::EnvSection);
+        }
+    }
+
+    let mut hints = Vec::new();
+    let mut seen: HashSet<String> = HashSet::new();
+    for (i, line) in lines.iter().enumerate() {
+        let Some(source) = line_source[i] else {
+            continue;
+        };
+        for token in extract_env_tokens(line) {
+            if SHELL_ENV_BLACKLIST.contains(&token.as_str()) {
+                continue;
+            }
+            if seen.insert(token.clone()) {
+                hints.push(EnvHint { var: token, source });
+            }
+        }
+    }
+    hints
+}
+
+/// Replace `[env: ...]` annotations with spaces so Pattern 2 doesn't
+/// re-scan Pattern 1's territory. Space-padding (rather than deletion)
+/// keeps line indices and column offsets stable — useful for future
+/// callers that want to map tokens back to raw positions.
+fn strip_clap_env_annotations(raw: &str) -> String {
+    const TAG: &str = "[env:";
+    let mut out = String::with_capacity(raw.len());
+    let mut rest = raw;
+    while let Some(pos) = rest.find(TAG) {
+        out.push_str(&rest[..pos]);
+        let after = &rest[pos..];
+        let close = after.find(']').map(|i| i + 1).unwrap_or(after.len());
+        // Pad with spaces of the same width, preserving any newlines so
+        // line-by-line iteration downstream sees the same line count.
+        for ch in after[..close].chars() {
+            out.push(if ch == '\n' { '\n' } else { ' ' });
+        }
+        rest = &after[close..];
+    }
+    out.push_str(rest);
+    out
+}
+
+/// A "flag line" for proximity-window purposes: leading whitespace, then
+/// a dash (clap's canonical shape). Mirrors `parse_flags` but returns a
+/// bool so the caller can keep line indices in a Vec<usize>.
+fn is_flag_line(line: &str) -> bool {
+    if !line.starts_with(' ') {
+        return false;
+    }
+    let trimmed = line.trim_start();
+    trimmed.starts_with('-') && !trimmed.starts_with("---")
+}
+
+/// True when a line looks like a top-level help section header:
+/// non-indented, non-empty, trims to something ending in `:`, and
+/// contains at least one uppercase letter. Examples: `OPTIONS:`,
+/// `ENVIRONMENT:`, `DOCKER_CONFIG:` (if a tool happens to name a section
+/// after an env var). Used to terminate `ENVIRONMENT` sections AND to
+/// exclude the header line itself from Pattern 2's token scan — headers
+/// are never env-var references.
+fn is_section_header_line(line: &str) -> bool {
+    !line.is_empty()
+        && !line.starts_with(' ')
+        && line.trim().ends_with(':')
+        && line.chars().any(|c| c.is_ascii_uppercase())
+}
+
+/// Locate an `ENVIRONMENT` / `ENV VARS` / `ENVIRONMENT VARIABLES` section
+/// in the help output, returning the line-index range (exclusive upper).
+/// Tools like `gh` use this convention; `ripgrep` uses free prose instead
+/// and is caught by the flag-proximity window above.
+fn find_env_section(lines: &[&str]) -> Option<(usize, usize)> {
+    let start = lines.iter().position(|l| {
+        let t = l.trim();
+        matches!(
+            t,
+            "ENVIRONMENT"
+                | "ENVIRONMENT:"
+                | "ENVIRONMENT VARIABLES"
+                | "ENVIRONMENT VARIABLES:"
+                | "ENV VARS"
+                | "ENV VARS:"
+                | "Environment:"
+        )
+    })?;
+    // Section ends at the next top-level header or end-of-text.
+    let end = lines[start + 1..]
+        .iter()
+        .position(|l| is_section_header_line(l))
+        .map(|offset| start + 1 + offset)
+        .unwrap_or(lines.len());
+    Some((start, end))
+}
+
+/// Pull uppercase-identifier tokens from a single line. Accepts bare
+/// `FOO_BAR`, `$FOO`, or `${FOO}` shapes. Tokens must be at least 3 chars
+/// long AND either be `$`-prefixed OR contain an underscore — this is
+/// how the parser distinguishes tool-scoped env vars (`RIPGREP_CONFIG`,
+/// `$PATH`) from placeholders that litter help text (`OPTIONS`,
+/// `[COMMAND]`, `HTTP`).
+///
+/// Also rejects tokens immediately wrapped in `[FOO]` or `<FOO>` when
+/// they lack a `$` prefix — clap's usage syntax uses these for argument
+/// placeholders, not env-var references.
+///
+/// **Recall gap on bracketed ENV-section prose.** Some tools document
+/// env bindings inside an ENVIRONMENT section using `[VAR]` syntax
+/// (e.g., `"Uses [GH_TOKEN] when set."`). The bracket-rejection above
+/// loses these. Adding a `$`-prefix escape would over-match placeholder
+/// usage elsewhere; the conservative choice is to accept the recall
+/// gap and wait for a concrete tool whose ENV section needs this.
+///
+/// Section-header-shaped lines (e.g., `DOCKER_CONFIG:`) are excluded
+/// entirely: a header that happens to contain an underscored uppercase
+/// token is not a prose reference to an env var.
+fn extract_env_tokens(line: &str) -> Vec<String> {
+    if is_section_header_line(line) {
+        return Vec::new();
+    }
+    let mut out = Vec::new();
+    let bytes = line.as_bytes();
+    let mut i = 0;
+    while i < bytes.len() {
+        // Skip leading `$` and optional `{` for `$FOO` / `${FOO}` forms.
+        let mut start = i;
+        let mut had_dollar = false;
+        if bytes[i] == b'$' {
+            had_dollar = true;
+            start = i + 1;
+            if start < bytes.len() && bytes[start] == b'{' {
+                start += 1;
+            }
+        }
+        // Collect an identifier: [A-Z_][A-Z0-9_]*
+        if start < bytes.len() && (bytes[start].is_ascii_uppercase() || bytes[start] == b'_') {
+            let mut end = start + 1;
+            while end < bytes.len()
+                && (bytes[end].is_ascii_uppercase()
+                    || bytes[end].is_ascii_digit()
+                    || bytes[end] == b'_')
+            {
+                end += 1;
+            }
+            let candidate = &line[start..end];
+
+            // Reject lowercase-adjacent matches (CamelCase / MACROname).
+            let left_ok = start == 0 || !bytes[start - 1].is_ascii_lowercase();
+            let right_ok = end >= bytes.len() || !bytes[end].is_ascii_lowercase();
+
+            // Reject `[FOO]` or `<FOO>` placeholders unless `$`-prefixed —
+            // those are clap usage placeholders, not env-var references.
+            let in_placeholder_bracket = !had_dollar
+                && matches!(
+                    start.checked_sub(1).map(|p| bytes[p]),
+                    Some(b'[') | Some(b'<')
+                )
+                && matches!(bytes.get(end).copied(), Some(b']') | Some(b'>'));
+
+            // Require tool-scoped shape: `$`-prefixed or contains `_`.
+            // This is the defining filter that separates real env vars
+            // (`RIPGREP_CONFIG_PATH`, `$PATH`) from placeholders like
+            // `OPTIONS`, `COMMAND`, `HTTP`, `FILES`.
+            let is_tool_scoped = had_dollar || candidate.contains('_');
+
+            // `is_env_var_name(candidate)` would be redundant here —
+            // the greedy scan above only admits `[A-Z_][A-Z0-9_]*` bytes,
+            // so the candidate is already a valid env-var name by
+            // construction.
+            if left_ok
+                && right_ok
+                && !in_placeholder_bracket
+                && is_tool_scoped
+                && candidate.len() >= 3
+            {
+                out.push(candidate.to_string());
+            }
+            i = end;
+        } else {
+            i += 1;
+        }
+    }
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::parse_env_hints;
+    use super::*;
+
+    const GH_HELP: &str = "\
+Work seamlessly with GitHub from the command line.
+
+USAGE
+  gh <command> <subcommand> [flags]
+
+OPTIONS
+  --help   Show help for command.
+
+ENVIRONMENT VARIABLES
+  GH_TOKEN, GITHUB_TOKEN: authentication credentials.
+  GH_REPO: specifies default repo for commands.
+";
+
+    const RIPGREP_PROSE: &str = "\
+USAGE: rg [OPTIONS] PATTERN
+
+OPTIONS:
+  --config <FILE>
+          Use config file. If set to an empty string, RIPGREP_CONFIG_PATH
+          is read from $RIPGREP_CONFIG_PATH. Respects RIPGREP_COLOR env
+          variable when rendering output.
+";
+
+    #[test]
+    fn pattern2_captures_gh_environment_section() {
+        let hints = parse_env_hints(GH_HELP);
+        let names: Vec<&str> = hints.iter().map(|h| h.var.as_str()).collect();
+        assert!(names.contains(&"GH_TOKEN"), "got {names:?}");
+        assert!(names.contains(&"GITHUB_TOKEN"), "got {names:?}");
+        assert!(names.contains(&"GH_REPO"), "got {names:?}");
+    }
+
+    #[test]
+    fn pattern2_captures_ripgrep_prose_near_flag() {
+        // RIPGREP_CONFIG_PATH appears in the description of --config, within
+        // the 4-line window.
+        let hints = parse_env_hints(RIPGREP_PROSE);
+        let names: Vec<&str> = hints.iter().map(|h| h.var.as_str()).collect();
+        assert!(names.contains(&"RIPGREP_CONFIG_PATH"), "got {names:?}");
+        assert!(names.contains(&"RIPGREP_COLOR"), "got {names:?}");
+    }
+
+    #[test]
+    fn pattern2_blacklist_rejects_shell_env() {
+        // $PATH, $HOME, $PAGER in flag prose must not become an EnvHint.
+        // PAGER is the archetypal example named in the SHELL_ENV_BLACKLIST
+        // doc comment — tools like git and gh document "respects $PAGER"
+        // as ambient shell behavior, not as a flag-bound env var.
+        let src = "\
+USAGE: foo
+OPTIONS:
+      --bin    Runs the binary from $PATH. Use $HOME to override.
+      --less   Pipes output through $PAGER when stdout is a TTY.
+";
+        let hints = parse_env_hints(src);
+        let names: Vec<&str> = hints.iter().map(|h| h.var.as_str()).collect();
+        assert!(!names.contains(&"PATH"));
+        assert!(!names.contains(&"HOME"));
+        assert!(
+            !names.contains(&"PAGER"),
+            "$PAGER must stay in SHELL_ENV_BLACKLIST — it's ambient shell, \
+             not a flag binding (overlaps with p6-no-pager signalling)",
+        );
+    }
+
+    #[test]
+    fn pattern2_ignores_tokens_outside_flag_window() {
+        // MYVAR appears far from any flag and there's no ENVIRONMENT header
+        // — must not be captured.
+        let src = "\
+MyTool - does stuff.
+
+See also: MYVAR is described in the CONFIG manual, page 42.
+
+Completely unrelated paragraph with no flags in sight. MYVAR again.
+
+Another paragraph.
+
+Another paragraph.
+
+Another paragraph.
+
+Another paragraph.
+";
+        let hints = parse_env_hints(src);
+        let names: Vec<&str> = hints.iter().map(|h| h.var.as_str()).collect();
+        assert!(
+            !names.contains(&"MYVAR"),
+            "MYVAR outside flag window should be ignored, got {names:?}",
+        );
+    }
+
+    #[test]
+    fn pattern2_dedupes_against_pattern1() {
+        // A flag documented with BOTH `[env: FOO]` AND a bash-style mention
+        // of $FOO in prose must produce exactly one EnvHint for FOO.
+        let src = "\
+USAGE: tool [OPTIONS]
+
+OPTIONS:
+      --foo <VAL>    Configures foo. See $MY_FOO for details. [env: MY_FOO]
+";
+        let hints = parse_env_hints(src);
+        let my_foo_count = hints.iter().filter(|h| h.var == "MY_FOO").count();
+        assert_eq!(
+            my_foo_count, 1,
+            "expected MY_FOO deduped across patterns, got {hints:?}",
+        );
+    }
+
+    #[test]
+    fn pattern2_ignores_section_header_lines() {
+        // A section header that happens to be shaped like a tool-scoped
+        // env var (underscored uppercase, ends with `:`) must not be
+        // captured as a hint — it's prose structure, not a reference.
+        let src = "\
+USAGE: tool
+
+OPTIONS:
+      --flag    Does something.
+
+DOCKER_CONFIG:
+      /etc/tool/docker.conf
+";
+        let hints = parse_env_hints(src);
+        let names: Vec<&str> = hints.iter().map(|h| h.var.as_str()).collect();
+        assert!(
+            !names.contains(&"DOCKER_CONFIG"),
+            "section-header line must not contribute env hints, got {names:?}",
+        );
+    }
+
+    #[test]
+    fn pattern2_rejects_mixed_case_and_placeholders_near_flag() {
+        // Negative shapes that should never produce hints:
+        //   - `$Path`          — mixed case; not tool-scoped
+        //   - `[FILES]`        — clap placeholder bracket form, no $
+        //   - `<TEMPLATE>`     — clap angle-bracket placeholder, no $
+        //   - `CamelCase`      — not uppercase-only, not tool-scoped
+        //   - `MACROname`      — leading capital but not tool-scoped
+        let src = "\
+USAGE: tool [OPTIONS] [FILES]
+
+OPTIONS:
+      --tpl <TEMPLATE>   Uses CamelCase naming. Read $Path then MACROname.
+";
+        let hints = parse_env_hints(src);
+        let names: Vec<&str> = hints.iter().map(|h| h.var.as_str()).collect();
+        for rejected in ["Path", "FILES", "TEMPLATE", "CamelCase", "MACROname"] {
+            assert!(
+                !names.contains(&rejected),
+                "{rejected} must be rejected by Pattern 2, got {names:?}",
+            );
+        }
+    }
+
+    #[test]
+    fn pattern2_rejects_bracketed_env_vars_in_prose() {
+        // Some tools document env bindings as `[GH_TOKEN]` or
+        // `<GITHUB_TOKEN>` inside an ENVIRONMENT section rather than as
+        // bare tokens. Current Pattern 2 treats bracket-wrapped
+        // uppercase tokens as clap usage placeholders and rejects them,
+        // accepting a small recall gap.
+        //
+        // This test locks the current rejection behavior. Widening
+        // Pattern 2 to accept bracketed ENV-section tokens (e.g., by
+        // relaxing the `in_placeholder_bracket` check inside an ENV
+        // section window) must update this test deliberately — and
+        // remove the recall-gap note from `extract_env_tokens`'s
+        // doc comment. The regression surface is: "Pattern 2 started
+        // matching `[FOO]` everywhere" vs. "Pattern 2 matches `[FOO]`
+        // only inside ENVIRONMENT sections".
+        let src = "\
+USAGE: tool
+
+ENVIRONMENT:
+  Uses [GH_TOKEN] when set.
+  Also respects <GITHUB_TOKEN>.
+";
+        let hints = parse_env_hints(src);
+        let names: Vec<&str> = hints.iter().map(|h| h.var.as_str()).collect();
+        assert!(
+            !names.contains(&"GH_TOKEN"),
+            "bracketed [GH_TOKEN] must stay rejected; see \
+             extract_env_tokens doc comment (recall gap noted)",
+        );
+        assert!(
+            !names.contains(&"GITHUB_TOKEN"),
+            "angle-bracket <GITHUB_TOKEN> must stay rejected",
+        );
+    }
+
+    #[test]
+    fn pattern2_tags_source_for_each_hint() {
+        // ENV-section matches wire up as EnvSection; proximity-only
+        // matches wire up as Proximity. When both apply, EnvSection wins
+        // — a dedicated header is a stronger structured signal.
+        let hints = parse_env_hints(GH_HELP);
+        let gh_token = hints
+            .iter()
+            .find(|h| h.var == "GH_TOKEN")
+            .expect("GH_TOKEN in hints");
+        assert_eq!(gh_token.source, EnvHintSource::EnvSection);
+
+        let hints = parse_env_hints(RIPGREP_PROSE);
+        let rg_color = hints
+            .iter()
+            .find(|h| h.var == "RIPGREP_COLOR")
+            .expect("RIPGREP_COLOR in hints");
+        assert_eq!(rg_color.source, EnvHintSource::Proximity);
+    }
+}
diff --git a/src/runner/help_probe.rs b/src/runner/help_probe/mod.rs
similarity index 58%
rename from src/runner/help_probe.rs
rename to src/runner/help_probe/mod.rs
index e953797..77cf5f3 100644
--- a/src/runner/help_probe.rs
+++ b/src/runner/help_probe/mod.rs
@@ -57,12 +57,38 @@ impl Flag {
     }
 }
 
+mod env_hints_bash;
+
+/// Which detection pattern surfaced an [`EnvHint`]. Agents debugging a
+/// false positive need to know whether a hint came from a clap
+/// `[env: FOO]` annotation (high signal), flag-adjacent prose (medium),
+/// or a dedicated `ENVIRONMENT` section (medium). Serialized as
+/// snake_case if/when [`EnvHint`] is exposed in JSON.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum EnvHintSource {
+    /// Pattern 1 — clap's `[env: FOO]` / `[env: FOO=<default>]`
+    /// annotation. The strongest signal; clap emits this when
+    /// `env = "FOO"` is declared on an `Arg`.
+    ClapAnnotation,
+    /// Pattern 2a — a bash-style `$FOO` or `TOOL_FOO` token appears
+    /// within the ±4-line proximity window around a flag definition.
+    Proximity,
+    /// Pattern 2b — a token appears inside a dedicated `ENVIRONMENT` /
+    /// `ENV VARS` / `ENVIRONMENT VARIABLES` section.
+    EnvSection,
+}
+
 /// A bound between a flag surface and an environment variable — surfaces
 /// clap's `[env: FOO]` hints as first-class data so checks don't re-scan.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct EnvHint {
     /// Environment variable name, e.g., `RIPGREP_CONFIG_PATH`.
     pub var: String,
+    /// Which detection pattern surfaced this hint. Lets evidence strings
+    /// and downstream agents see where the signal came from without
+    /// re-running the parser.
+    pub source: EnvHintSource,
 }
 
 /// Shared, lazily-parsed view over `<binary> --help`. Construct via
@@ -228,8 +254,13 @@ fn parse_short_flag(candidate: &str) -> Option<String> {
 /// occurrence counts should inspect Pattern 1's raw output directly.
 fn parse_env_hints(raw: &str) -> Vec<EnvHint> {
     let pattern1 = parse_env_hints_clap_style(raw);
-    let pattern2 = parse_env_hints_bash_style(raw);
+    let pattern2 = env_hints_bash::parse_env_hints_bash_style(raw);
 
+    // Dedup by var name. Pattern 1 wins when both patterns match the same
+    // name — its signal (explicit clap annotation) is strictly stronger
+    // than proximity-or-section inference, and the emitted `source` tag
+    // reflects that provenance. Iteration order preserves Pattern 1's
+    // occurrences first, so `seen.insert` keeps the clap-annotation hint.
     let mut seen: HashSet<String> = HashSet::new();
     let mut merged = Vec::new();
     for hint in pattern1.into_iter().chain(pattern2) {
@@ -241,7 +272,8 @@ fn parse_env_hints(raw: &str) -> Vec<EnvHint> {
 }
 
 /// Pattern 1 — clap's `[env: FOO_BAR]` or `[env: FOO_BAR=<default>]`
-/// annotations. Each occurrence becomes one `EnvHint`.
+/// annotations. Each occurrence becomes one `EnvHint` tagged with
+/// [`EnvHintSource::ClapAnnotation`].
 fn parse_env_hints_clap_style(raw: &str) -> Vec<EnvHint> {
     const TAG: &str = "[env:";
     let mut hints = Vec::new();
@@ -254,6 +286,7 @@ fn parse_env_hints_clap_style(raw: &str) -> Vec<EnvHint> {
         if is_env_var_name(name) {
             hints.push(EnvHint {
                 var: name.to_string(),
+                source: EnvHintSource::ClapAnnotation,
             });
         }
         rest = &after[end..];
@@ -261,214 +294,6 @@ fn parse_env_hints_clap_style(raw: &str) -> Vec<EnvHint> {
     hints
 }
 
-/// Shell/system env vars we never want to flag as flag-bound. Tools
-/// routinely mention these in help prose (`respects $PAGER`, `uses $HOME`)
-/// without those being user-configurable flag bindings. Listing them as
-/// env hints would reward tools for documenting the ambient shell.
-const SHELL_ENV_BLACKLIST: &[&str] = &[
-    "PATH", "HOME", "USER", "SHELL", "PWD", "LANG", "TERM", "TMPDIR",
-];
-
-/// Window size (in lines, each direction) for Pattern 2's proximity scan
-/// around a flag definition. Four lines is enough to catch wrapped
-/// descriptions and the usual `[env: ...]`-adjacent prose without
-/// reaching into unrelated flag entries.
-const PATTERN2_WINDOW: usize = 4;
-
-/// Pattern 2 — bash-style `$FOO` or uppercase `FOO_BAR` tokens that
-/// co-occur with a flag definition within a ±4-line window, OR appear in
-/// a dedicated `ENVIRONMENT` / `ENV VARS` section. Filters the
-/// shell-environment blacklist and requires tool-scoped shape (uppercase,
-/// digits, underscores; length ≥ 3).
-///
-/// Strips `[env: ...]` annotations before scanning — those belong to
-/// Pattern 1. Salvaging tokens from rejected annotations (e.g.,
-/// `[env: 1ABC]` contributing `ABC`) would undermine Pattern 1's
-/// decision to reject them.
-fn parse_env_hints_bash_style(raw: &str) -> Vec<EnvHint> {
-    let stripped = strip_clap_env_annotations(raw);
-    let lines: Vec<&str> = stripped.lines().collect();
-    let flag_line_indices: Vec<usize> = lines
-        .iter()
-        .enumerate()
-        .filter_map(|(i, l)| is_flag_line(l).then_some(i))
-        .collect();
-    let env_section_range = find_env_section(&lines);
-
-    // Mark every line that's either within a flag's window or inside an
-    // ENVIRONMENT-style section. Pattern 2 tokens only count when they
-    // appear on one of these lines.
-    let mut in_window = vec![false; lines.len()];
-    for &idx in &flag_line_indices {
-        let lo = idx.saturating_sub(PATTERN2_WINDOW);
-        let hi = (idx + PATTERN2_WINDOW + 1).min(lines.len());
-        in_window[lo..hi].iter_mut().for_each(|b| *b = true);
-    }
-    if let Some((lo, hi)) = env_section_range {
-        in_window[lo..hi].iter_mut().for_each(|b| *b = true);
-    }
-
-    let mut hints = Vec::new();
-    let mut seen: HashSet<String> = HashSet::new();
-    for (i, line) in lines.iter().enumerate() {
-        if !in_window[i] {
-            continue;
-        }
-        for token in extract_env_tokens(line) {
-            if SHELL_ENV_BLACKLIST.contains(&token.as_str()) {
-                continue;
-            }
-            if seen.insert(token.clone()) {
-                hints.push(EnvHint { var: token });
-            }
-        }
-    }
-    hints
-}
-
-/// Replace `[env: ...]` annotations with spaces so Pattern 2 doesn't
-/// re-scan Pattern 1's territory. Space-padding (rather than deletion)
-/// keeps line indices and column offsets stable — useful for future
-/// callers that want to map tokens back to raw positions.
-fn strip_clap_env_annotations(raw: &str) -> String {
-    const TAG: &str = "[env:";
-    let mut out = String::with_capacity(raw.len());
-    let mut rest = raw;
-    while let Some(pos) = rest.find(TAG) {
-        out.push_str(&rest[..pos]);
-        let after = &rest[pos..];
-        let close = after.find(']').map(|i| i + 1).unwrap_or(after.len());
-        // Pad with spaces of the same width, preserving any newlines so
-        // line-by-line iteration downstream sees the same line count.
-        for ch in after[..close].chars() {
-            out.push(if ch == '\n' { '\n' } else { ' ' });
-        }
-        rest = &after[close..];
-    }
-    out.push_str(rest);
-    out
-}
-
-/// A "flag line" for proximity-window purposes: leading whitespace, then
-/// a dash (clap's canonical shape). Mirrors `parse_flags` but returns a
-/// bool so the caller can keep line indices in a Vec<usize>.
-fn is_flag_line(line: &str) -> bool {
-    if !line.starts_with(' ') {
-        return false;
-    }
-    let trimmed = line.trim_start();
-    trimmed.starts_with('-') && !trimmed.starts_with("---")
-}
-
-/// Locate an `ENVIRONMENT` / `ENV VARS` / `ENVIRONMENT VARIABLES` section
-/// in the help output, returning the line-index range (exclusive upper).
-/// Tools like `gh` use this convention; `ripgrep` uses free prose instead
-/// and is caught by the flag-proximity window above.
-fn find_env_section(lines: &[&str]) -> Option<(usize, usize)> {
-    let start = lines.iter().position(|l| {
-        let t = l.trim();
-        matches!(
-            t,
-            "ENVIRONMENT"
-                | "ENVIRONMENT:"
-                | "ENVIRONMENT VARIABLES"
-                | "ENVIRONMENT VARIABLES:"
-                | "ENV VARS"
-                | "ENV VARS:"
-                | "Environment:"
-        )
-    })?;
-    // Section ends at the next top-level header (non-indented, non-empty,
-    // ends-with-colon) or end-of-text.
-    let end = lines[start + 1..]
-        .iter()
-        .position(|l| {
-            !l.is_empty()
-                && !l.starts_with(' ')
-                && l.trim().ends_with(':')
-                && l.chars().any(|c| c.is_ascii_uppercase())
-        })
-        .map(|offset| start + 1 + offset)
-        .unwrap_or(lines.len());
-    Some((start, end))
-}
-
-/// Pull uppercase-identifier tokens from a single line. Accepts bare
-/// `FOO_BAR`, `$FOO`, or `${FOO}` shapes. Tokens must be at least 3 chars
-/// long AND either be `$`-prefixed OR contain an underscore — this is
-/// how the parser distinguishes tool-scoped env vars (`RIPGREP_CONFIG`,
-/// `$PATH`) from placeholders that litter help text (`OPTIONS`,
-/// `[COMMAND]`, `HTTP`).
-///
-/// Also rejects tokens immediately wrapped in `[FOO]` or `<FOO>` when
-/// they lack a `$` prefix — clap's usage syntax uses these for argument
-/// placeholders, not env-var references.
-fn extract_env_tokens(line: &str) -> Vec<String> {
-    let mut out = Vec::new();
-    let bytes = line.as_bytes();
-    let mut i = 0;
-    while i < bytes.len() {
-        // Skip leading `$` and optional `{` for `$FOO` / `${FOO}` forms.
-        let mut start = i;
-        let mut had_dollar = false;
-        if bytes[i] == b'$' {
-            had_dollar = true;
-            start = i + 1;
-            if start < bytes.len() && bytes[start] == b'{' {
-                start += 1;
-            }
-        }
-        // Collect an identifier: [A-Z_][A-Z0-9_]*
-        if start < bytes.len() && (bytes[start].is_ascii_uppercase() || bytes[start] == b'_') {
-            let mut end = start + 1;
-            while end < bytes.len()
-                && (bytes[end].is_ascii_uppercase()
-                    || bytes[end].is_ascii_digit()
-                    || bytes[end] == b'_')
-            {
-                end += 1;
-            }
-            let candidate = &line[start..end];
-
-            // Reject lowercase-adjacent matches (CamelCase / MACROname).
-            let left_ok = start == 0 || !bytes[start - 1].is_ascii_lowercase();
-            let right_ok = end >= bytes.len() || !bytes[end].is_ascii_lowercase();
-
-            // Reject `[FOO]` or `<FOO>` placeholders unless `$`-prefixed —
-            // those are clap usage placeholders, not env-var references.
-            let in_placeholder_bracket = !had_dollar
-                && matches!(
-                    start.checked_sub(1).map(|p| bytes[p]),
-                    Some(b'[') | Some(b'<')
-                )
-                && matches!(bytes.get(end).copied(), Some(b']') | Some(b'>'));
-
-            // Require tool-scoped shape: `$`-prefixed or contains `_`.
-            // This is the defining filter that separates real env vars
-            // (`RIPGREP_CONFIG_PATH`, `$PATH`) from placeholders like
-            // `OPTIONS`, `COMMAND`, `HTTP`, `FILES`.
-            let is_tool_scoped = had_dollar || candidate.contains('_');
-
-            // `is_env_var_name(candidate)` would be redundant here —
-            // the greedy scan above only admits `[A-Z_][A-Z0-9_]*` bytes,
-            // so the candidate is already a valid env-var name by
-            // construction.
-            if left_ok
-                && right_ok
-                && !in_placeholder_bracket
-                && is_tool_scoped
-                && candidate.len() >= 3
-            {
-                out.push(candidate.to_string());
-            }
-            i = end;
-        } else {
-            i += 1;
-        }
-    }
-    out
-}
-
 /// Env var names are ASCII uppercase, digits, underscores; must start with
 /// a letter or underscore.
 fn is_env_var_name(s: &str) -> bool {
@@ -572,51 +397,10 @@ A tiny HTTP client.
 Usage: xurl-rs URL
 "#;
 
-    // gh-style help: dedicated ENVIRONMENT section listing env vars by
-    // name. Pattern 2 must capture GH_TOKEN / GH_HOST / GH_REPO, reject
-    // the blacklisted $PATH, and not double-emit flags that also appear
-    // in the Options block.
-    const GH_HELP: &str = r#"Work seamlessly with GitHub.
-
-USAGE:
-  gh <command> <subcommand> [flags]
-
-OPTIONS:
-      --help       Show help for command
-      --version    Show version
-
-ENVIRONMENT:
-  GH_TOKEN, GITHUB_TOKEN      Authentication token. Overrides any `oauth_token`
-                              value in the config file.
-  GH_HOST                     Specify the GitHub hostname for commands that
-                              would otherwise assume the "github.com" host.
-  GH_REPO                     Specify the owner/name of the repository for
-                              commands where no repository argument is
-                              required or provided (for example, the `$PATH`
-                              lookup is unchanged).
-
-LEARN MORE:
-  Use `gh <command> <subcommand> --help` for more information about a command.
-"#;
-
-    // ripgrep-style help: env vars mentioned in free prose near a flag,
-    // no ENVIRONMENT header. Pattern 2's flag-window scan catches this.
-    const RIPGREP_PROSE_HELP: &str = r#"ripgrep 14.1
-
-USAGE:
-    rg [OPTIONS] PATTERN [PATH ...]
-
-OPTIONS:
-      --config <PATH>
-            Specify a path to a configuration file for ripgrep. The path given
-            may be relative to the current working directory. The
-            RIPGREP_CONFIG_PATH environment variable is consulted by default.
-            Setting $HOME has no effect here.
-
-      --color <WHEN>
-            Controls when to use color. See the RIPGREP_COLOR environment
-            variable for further customization.
-"#;
+    // Pattern 2 fixtures (GH_HELP, RIPGREP_PROSE_HELP) and Pattern 2
+    // tests live alongside the Pattern 2 code in
+    // `runner/help_probe/env_hints_bash.rs`. Parent keeps only Pattern 1
+    // + shared-fixture tests.
 
     // Localized help — ensures parsers degrade to empty without panicking.
     const NON_ENGLISH_HELP: &str = r#"用法: outil [选项]
@@ -683,105 +467,28 @@ OPTIONS:
         assert_eq!(hints[0].var, "VALID_1");
     }
 
-    #[test]
-    fn pattern2_captures_gh_environment_section() {
-        let hints = parse_env_hints(GH_HELP);
-        let names: Vec<&str> = hints.iter().map(|h| h.var.as_str()).collect();
-        assert!(names.contains(&"GH_TOKEN"), "got {names:?}");
-        assert!(names.contains(&"GH_HOST"), "got {names:?}");
-        assert!(names.contains(&"GH_REPO"), "got {names:?}");
-        assert!(names.contains(&"GITHUB_TOKEN"), "got {names:?}");
-        // $PATH in the ENVIRONMENT prose is blacklisted.
-        assert!(!names.contains(&"PATH"), "PATH must be blacklisted");
-    }
-
-    #[test]
-    fn pattern2_captures_ripgrep_prose_near_flag() {
-        // RIPGREP_CONFIG_PATH appears in the description of --config, within
-        // the 4-line window.
-        let hints = parse_env_hints(RIPGREP_PROSE_HELP);
-        let names: Vec<&str> = hints.iter().map(|h| h.var.as_str()).collect();
-        assert!(
-            names.contains(&"RIPGREP_CONFIG_PATH"),
-            "expected RIPGREP_CONFIG_PATH in {names:?}",
-        );
-        assert!(
-            names.contains(&"RIPGREP_COLOR"),
-            "expected RIPGREP_COLOR in {names:?}",
-        );
-        // $HOME mentioned adjacent to --config is blacklisted.
-        assert!(!names.contains(&"HOME"), "HOME must be blacklisted");
-    }
-
-    #[test]
-    fn pattern2_blacklist_rejects_shell_env() {
-        // $PATH in flag prose must not become an EnvHint.
-        let src = "\
-USAGE: foo
-OPTIONS:
-      --bin    Runs the binary from $PATH. Use $HOME to override.
-";
-        let hints = parse_env_hints(src);
-        let names: Vec<&str> = hints.iter().map(|h| h.var.as_str()).collect();
-        assert!(!names.contains(&"PATH"));
-        assert!(!names.contains(&"HOME"));
-    }
-
-    #[test]
-    fn pattern2_ignores_tokens_outside_flag_window() {
-        // MYVAR appears far from any flag and there's no ENVIRONMENT header
-        // — must not be captured.
-        let src = "\
-MyTool - does stuff.
-
-See also: MYVAR is described in the CONFIG manual, page 42.
-
-Completely unrelated paragraph with no flags in sight. MYVAR again.
-
-Another paragraph.
-
-Another paragraph.
-
-Another paragraph.
-
-Another paragraph.
-";
-        let hints = parse_env_hints(src);
-        let names: Vec<&str> = hints.iter().map(|h| h.var.as_str()).collect();
-        assert!(
-            !names.contains(&"MYVAR"),
-            "MYVAR outside flag window should be ignored, got {names:?}",
-        );
-    }
-
-    #[test]
-    fn pattern2_dedupes_against_pattern1() {
-        // A flag documented with BOTH `[env: FOO]` AND a bash-style mention
-        // of $FOO in prose must produce exactly one EnvHint for FOO.
-        let src = "\
-USAGE: tool [OPTIONS]
-
-OPTIONS:
-      --foo <VAL>    Configures foo. See $MY_FOO for details. [env: MY_FOO]
-";
-        let hints = parse_env_hints(src);
-        let my_foo_count = hints.iter().filter(|h| h.var == "MY_FOO").count();
-        assert_eq!(
-            my_foo_count, 1,
-            "expected MY_FOO deduped across patterns, got {hints:?}",
-        );
-    }
-
     #[test]
     fn pattern1_existing_behavior_unchanged() {
         // Regression guard: the Pattern 1 fixtures that shipped in v0.1.2
-        // must still produce the same hits post-widening.
+        // must still produce the same hits post-widening. Pattern 2
+        // specific coverage lives in env_hints_bash::tests.
         let rg = parse_env_hints(RIPGREP_HELP);
         assert!(rg.iter().any(|h| h.var == "RIPGREP_COLOR"));
         let clap = parse_env_hints(CLAP_HELP);
         assert!(clap.iter().any(|h| h.var == "AGENTNATIVE_QUIET"));
     }
 
+    #[test]
+    fn pattern1_tags_hints_as_clap_annotation() {
+        // Every Pattern 1 emission must carry EnvHintSource::ClapAnnotation.
+        let rg = parse_env_hints(RIPGREP_HELP);
+        let hint = rg
+            .iter()
+            .find(|h| h.var == "RIPGREP_COLOR")
+            .expect("RIPGREP_COLOR in Pattern 1 hits");
+        assert_eq!(hint.source, EnvHintSource::ClapAnnotation);
+    }
+
     #[test]
     fn parse_subcommands_reads_commands_block() {
         let subs = parse_subcommands(CLAP_HELP);
diff --git a/src/scorecard/audience.rs b/src/scorecard/audience.rs
index 7f47529..1f99c4f 100644
--- a/src/scorecard/audience.rs
+++ b/src/scorecard/audience.rs
@@ -1,5 +1,5 @@
 //! Derived audience classifier. Reads a completed `results[]` vector and
-//! labels the target as `agent_optimized`, `mixed`, or `human_primary` based
+//! labels the target as `agent-optimized`, `mixed`, or `human-primary` based
 //! on `Warn` counts across a fixed set of 4 signal checks.
 //!
 //! The classifier is **informational, not authoritative**. It does not gate
@@ -14,8 +14,12 @@
 //! introducing a new MUST in the spec — never by adjusting the classifier
 //! rules. Keep this file read-only over `results`.
 //!
-//! Labels serialize as snake_case to match the existing enum conventions
-//! (`CheckGroup`, `CheckLayer`, `Confidence`).
+//! Labels serialize as kebab-case (`agent-optimized`, `mixed`,
+//! `human-primary`) to match `audit_profile`'s kebab-case values within
+//! the same JSON document. The `CheckGroup` / `CheckLayer` / `Confidence`
+//! enums stay snake_case as type-system identifiers — those are a
+//! different contract (one per `results[]` row) with broader consumer
+//! history.
 
 use crate::types::{CheckResult, CheckStatus};
 
@@ -36,13 +40,23 @@ pub const SIGNAL_CHECK_IDS: [&str; 4] = [
 /// `results` — partial signal cannot produce an honest label. Counts
 /// only `CheckStatus::Warn`; every other status (including `Skip` and
 /// `Error`) is treated as not-a-Warn, so the denominator stays at 4
-/// but the classifier errs toward `agent_optimized` when signal is
+/// but the classifier errs toward `agent-optimized` when signal is
 /// ambiguous rather than punishing it.
 pub fn classify(results: &[CheckResult]) -> Option<String> {
     let mut warns = 0usize;
     let mut matched = 0usize;
 
     for signal_id in SIGNAL_CHECK_IDS {
+        // Duplicate signal IDs in `results[]` are a registry bug — the
+        // check catalog should guarantee uniqueness. `find()` takes the
+        // first match silently, which would mask a regression. Trip in
+        // debug builds so it surfaces in `cargo test` instead of shipping.
+        debug_assert!(
+            results.iter().filter(|r| r.id == signal_id).count() <= 1,
+            "duplicate signal check ID in results[]: {signal_id}. \
+             Every behavioral check ID must be unique across the catalog; \
+             classify() uses iter().find() and would silently ignore the duplicate.",
+        );
         let Some(r) = results.iter().find(|r| r.id == signal_id) else {
             continue;
         };
@@ -65,20 +79,59 @@ pub fn classify(results: &[CheckResult]) -> Option<String> {
 
     Some(
         match warns {
-            0..=1 => "agent_optimized",
+            0..=1 => "agent-optimized",
             2 => "mixed",
-            _ => "human_primary",
+            _ => "human-primary",
         }
         .to_string(),
     )
 }
 
-/// Evidence-string sniff for audit_profile suppression. The evidence
-/// format is produced by the main check-execution loop and is considered
-/// part of the behavioral contract — the integration test
-/// `test_audit_profile_suppresses_listed_checks` asserts the prefix.
-fn is_audit_profile_suppression(status: &CheckStatus) -> bool {
-    matches!(status, CheckStatus::Skip(e) if e.starts_with("suppressed by audit_profile:"))
+/// Diagnose *why* [`classify`] returned `None`. When the classifier
+/// withholds a label, callers (notably the scorecard emitter) can
+/// surface `audience_reason` so agents and UI don't have to rerun the
+/// logic to answer "why is this null".
+///
+/// - `None` — audience has a concrete label; there's no gap to explain.
+/// - `Some("suppressed")` — at least one signal check was skipped by
+///   `--audit-profile`. Caller chose to mask the signal; the right fix
+///   is to pick a different profile or live with the null.
+/// - `Some("insufficient_signal")` — at least one signal check didn't
+///   run at all (e.g., `--source` mode, missing runner, or an unsupported
+///   target). Caller can't fix this with a flag.
+///
+/// Suppression dominates when both conditions apply — the caller-chosen
+/// mask is the more actionable signal than "the check wasn't produced".
+pub fn classify_reason(results: &[CheckResult]) -> Option<&'static str> {
+    let mut any_suppressed = false;
+    let mut any_missing = false;
+    for signal_id in SIGNAL_CHECK_IDS {
+        match results.iter().find(|r| r.id == signal_id) {
+            None => any_missing = true,
+            Some(r) if is_audit_profile_suppression(&r.status) => any_suppressed = true,
+            Some(_) => {}
+        }
+    }
+    if !any_suppressed && !any_missing {
+        return None;
+    }
+    if any_suppressed {
+        Some("suppressed")
+    } else {
+        Some("insufficient_signal")
+    }
+}
+
+/// Evidence-string sniff for audit_profile suppression. The prefix is
+/// produced by the main check-execution loop and consumed here and by
+/// `build_coverage_summary`. The single source of truth is
+/// `registry::SUPPRESSION_EVIDENCE_PREFIX`; a rename there propagates
+/// without silent drift between producer and consumers.
+pub(crate) fn is_audit_profile_suppression(status: &CheckStatus) -> bool {
+    matches!(
+        status,
+        CheckStatus::Skip(e) if e.starts_with(crate::principles::registry::SUPPRESSION_EVIDENCE_PREFIX)
+    )
 }
 
 #[cfg(test)]
@@ -107,7 +160,7 @@ mod tests {
 
     #[test]
     fn four_passes_yields_agent_optimized() {
-        assert_eq!(classify(&all_pass()).as_deref(), Some("agent_optimized"));
+        assert_eq!(classify(&all_pass()).as_deref(), Some("agent-optimized"));
     }
 
     #[test]
@@ -116,7 +169,7 @@ mod tests {
             .iter()
             .map(|id| signal_result(id, CheckStatus::Warn("missing".into())))
             .collect();
-        assert_eq!(classify(&results).as_deref(), Some("human_primary"));
+        assert_eq!(classify(&results).as_deref(), Some("human-primary"));
     }
 
     #[test]
@@ -131,7 +184,7 @@ mod tests {
     fn one_warn_yields_agent_optimized() {
         let mut results = all_pass();
         results[2].status = CheckStatus::Warn("soft".into());
-        assert_eq!(classify(&results).as_deref(), Some("agent_optimized"));
+        assert_eq!(classify(&results).as_deref(), Some("agent-optimized"));
     }
 
     #[test]
@@ -140,7 +193,7 @@ mod tests {
         results[0].status = CheckStatus::Warn("a".into());
         results[1].status = CheckStatus::Warn("b".into());
         results[2].status = CheckStatus::Warn("c".into());
-        assert_eq!(classify(&results).as_deref(), Some("human_primary"));
+        assert_eq!(classify(&results).as_deref(), Some("human-primary"));
     }
 
     #[test]
@@ -157,11 +210,11 @@ mod tests {
     fn organic_skipped_signal_counts_as_not_warn() {
         // An organic Skip (e.g., target has no flags) is a legitimate
         // outcome — the check ran and decided it doesn't apply. It's not
-        // a Warn, so it doesn't push toward human_primary, and the signal
+        // a Warn, so it doesn't push toward human-primary, and the signal
         // still counts toward the denominator — all 4 present.
         let mut results = all_pass();
         results[3].status = CheckStatus::Skip("no flags".into());
-        assert_eq!(classify(&results).as_deref(), Some("agent_optimized"));
+        assert_eq!(classify(&results).as_deref(), Some("agent-optimized"));
     }
 
     #[test]
@@ -170,7 +223,10 @@ mod tests {
         // prefix tells us the check did NOT run — per R2, audience must
         // be null rather than a partial-count verdict.
         let mut results = all_pass();
-        results[0].status = CheckStatus::Skip("suppressed by audit_profile: human-tui".into());
+        results[0].status = CheckStatus::Skip(format!(
+            "{}human-tui",
+            crate::principles::registry::SUPPRESSION_EVIDENCE_PREFIX
+        ));
         assert!(
             classify(&results).is_none(),
             "audit_profile-suppressed signal should drop denominator and force None",
@@ -181,7 +237,68 @@ mod tests {
     fn errored_signal_counts_as_not_warn() {
         let mut results = all_pass();
         results[0].status = CheckStatus::Error("runner crashed".into());
-        assert_eq!(classify(&results).as_deref(), Some("agent_optimized"));
+        assert_eq!(classify(&results).as_deref(), Some("agent-optimized"));
+    }
+
+    #[test]
+    fn classify_reason_none_when_audience_has_label() {
+        let results = all_pass();
+        assert!(classify(&results).is_some());
+        assert_eq!(classify_reason(&results), None);
+    }
+
+    #[test]
+    fn classify_reason_suppressed_when_signal_audit_profile_suppressed() {
+        let mut results = all_pass();
+        results[0].status = CheckStatus::Skip(format!(
+            "{}human-tui",
+            crate::principles::registry::SUPPRESSION_EVIDENCE_PREFIX
+        ));
+        assert!(classify(&results).is_none());
+        assert_eq!(classify_reason(&results), Some("suppressed"));
+    }
+
+    #[test]
+    fn classify_reason_insufficient_when_signal_missing() {
+        // Source-only-style run: 0 signal checks present.
+        let results: Vec<CheckResult> = Vec::new();
+        assert!(classify(&results).is_none());
+        assert_eq!(classify_reason(&results), Some("insufficient_signal"));
+    }
+
+    #[test]
+    fn classify_reason_suppressed_dominates_missing() {
+        // One signal missing + one signal suppressed → reason is
+        // `suppressed` (caller-chosen mask is more actionable).
+        let results: Vec<CheckResult> = SIGNAL_CHECK_IDS
+            .iter()
+            .take(3) // drop the 4th entirely
+            .enumerate()
+            .map(|(i, id)| {
+                let status = if i == 0 {
+                    CheckStatus::Skip(format!(
+                        "{}human-tui",
+                        crate::principles::registry::SUPPRESSION_EVIDENCE_PREFIX
+                    ))
+                } else {
+                    CheckStatus::Pass
+                };
+                signal_result(id, status)
+            })
+            .collect();
+        assert_eq!(classify_reason(&results), Some("suppressed"));
+    }
+
+    #[test]
+    #[should_panic(expected = "duplicate signal check ID")]
+    fn duplicate_signal_in_results_trips_debug_assert() {
+        // Two results with the same signal ID is a registry drift hazard —
+        // the catalog should guarantee uniqueness. classify() must trip
+        // in debug builds rather than silently picking the first entry.
+        let mut results = all_pass();
+        // Duplicate p1-non-interactive.
+        results.push(signal_result(SIGNAL_CHECK_IDS[0], CheckStatus::Pass));
+        classify(&results);
     }
 
     #[test]
@@ -190,7 +307,7 @@ mod tests {
         let mut results = all_pass();
         results.push(signal_result("p6-sigpipe", CheckStatus::Warn("x".into())));
         results.push(signal_result("p4-bad-args", CheckStatus::Warn("y".into())));
-        assert_eq!(classify(&results).as_deref(), Some("agent_optimized"));
+        assert_eq!(classify(&results).as_deref(), Some("agent-optimized"));
     }
 
     #[test]
diff --git a/src/scorecard/mod.rs b/src/scorecard/mod.rs
index 9598fd1..ce9c141 100644
--- a/src/scorecard/mod.rs
+++ b/src/scorecard/mod.rs
@@ -13,15 +13,41 @@ use crate::types::{CheckGroup, CheckResult, CheckStatus};
 /// leaderboard pipeline) pin against this to detect shape changes.
 pub const SCHEMA_VERSION: &str = "1.1";
 
+/// v1.1 scorecard shape emitted by `anc check --output json`.
+///
+/// **Scorecard-level enum values are kebab-case.** Both `audience` and
+/// `audit_profile` serialize their enum values as kebab-case strings
+/// (`agent-optimized` / `mixed` / `human-primary` for `audience`;
+/// `human-tui` / `file-traversal` / `posix-utility` / `diagnostic-only`
+/// for `audit_profile`). `audit_profile` MUST be kebab-case because it
+/// echoes the CLI flag value a caller types (`--audit-profile human-tui`);
+/// `audience` uses the same convention so consumers don't have to juggle
+/// two casing rules inside one JSON document.
+///
+/// Per-result enum values in `results[].group` / `layer` / `confidence`
+/// stay snake_case via their `#[serde(rename_all = "snake_case")]`
+/// derives — they are a different contract (one row per check) with
+/// broader consumer history, and share spelling with the Rust
+/// type-system identifiers they come from.
+///
+/// Consumers key on the exact string; never transform case.
 #[derive(Serialize)]
 pub struct Scorecard {
     pub schema_version: &'static str,
     pub results: Vec<CheckResultView>,
     pub summary: Summary,
     pub coverage_summary: CoverageSummary,
-    /// Derived audience classification (human-primary, agent-primary, mixed).
-    /// Reserved for v0.1.3; emitted as `null` in v0.1.1 / v0.1.2.
+    /// Derived audience classification (`agent-optimized`, `mixed`,
+    /// `human-primary`). Reserved in v0.1.1 / v0.1.2 (always `null`);
+    /// populated in v0.1.3+.
     pub audience: Option<String>,
+    /// When `audience` is `null`, the reason the classifier declined to
+    /// label: `suppressed` (signal check masked by `--audit-profile`) or
+    /// `insufficient_signal` (signal check never produced, e.g. source-only
+    /// run). Omitted from JSON when `audience` has a label. Additive to
+    /// v1.1; consumers feature-detect.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub audience_reason: Option<String>,
     /// Registry-sourced exemption category (human-tui, file-traversal, etc.).
     /// Reserved for v0.1.3; emitted as `null` in v0.1.1 / v0.1.2.
     pub audit_profile: Option<String>,
@@ -229,12 +255,23 @@ pub fn build_scorecard(
     audience: Option<String>,
     audit_profile: Option<String>,
 ) -> Scorecard {
+    // `audience_reason` is derived from `results` rather than threaded
+    // through as a caller parameter — the reason is a property of the
+    // result set, not a caller decision, and deriving it here keeps the
+    // label and its explanation in lock-step. When audience has a label
+    // the field is omitted from JSON (see Scorecard's serde skip rule).
+    let audience_reason = if audience.is_some() {
+        None
+    } else {
+        audience::classify_reason(results).map(|s| s.to_string())
+    };
     Scorecard {
         schema_version: SCHEMA_VERSION,
         results: results.iter().map(CheckResultView::from_result).collect(),
         summary: build_summary(results),
         coverage_summary: build_coverage_summary(results, ran_checks),
         audience,
+        audience_reason,
         audit_profile,
     }
 }
@@ -258,8 +295,18 @@ fn build_coverage_summary(
     let covers_by_id: HashMap<&str, &'static [&'static str]> =
         ran_checks.iter().map(|c| (c.id(), c.covers())).collect();
 
+    // Verified = requirements covered by a check that actually executed.
+    // A check suppressed by --audit-profile did NOT verify its
+    // requirement — it emitted Skip with the `SUPPRESSION_EVIDENCE_PREFIX`
+    // sentinel. Counting it toward `verified` would overstate coverage on
+    // any --audit-profile run (a misleading public metric for the site
+    // leaderboard). Filter those out here and mirror the exclusion in the
+    // regression test below.
     let mut verified: HashSet<&'static str> = HashSet::new();
     for r in results {
+        if audience::is_audit_profile_suppression(&r.status) {
+            continue;
+        }
         if let Some(ids) = covers_by_id.get(r.id.as_str()) {
             verified.extend(ids.iter().copied());
         }
@@ -293,6 +340,21 @@ fn build_coverage_summary(
     CoverageSummary { must, should, may }
 }
 
+/// Derive the process exit code from the full result set.
+///
+/// - `0` — every check Pass or Skip.
+/// - `1` — at least one Warn.
+/// - `2` — at least one Fail or Error.
+///
+/// **`--audit-profile` affects the exit code by masking Fails to Skips.**
+/// A check that would otherwise Fail but is suppressed by the applied
+/// profile contributes nothing to `has_fail_or_error` and cannot lift the
+/// code above `0`/`1`. This is intentional per plan R4: the caller is
+/// declaring "this category of check doesn't apply to this tool", so
+/// scoring against that requirement would produce a misleading non-zero
+/// exit. The tradeoff is that callers passing the wrong profile can
+/// silently bless a broken tool — guarding against that lives upstream
+/// (site's regen script, CI policy), not here.
 pub fn exit_code(results: &[CheckResult]) -> i32 {
     let has_fail_or_error = results
         .iter()
@@ -375,6 +437,9 @@ mod tests {
             fn id(&self) -> &str {
                 self.id
             }
+            fn label(&self) -> &'static str {
+                "fake"
+            }
             fn group(&self) -> CheckGroup {
                 CheckGroup::P1
             }
@@ -406,6 +471,73 @@ mod tests {
         assert!(summary.must.total >= 1);
     }
 
+    #[test]
+    fn coverage_summary_excludes_audit_profile_suppressed_checks() {
+        use crate::check::Check;
+        use crate::principles::registry::SUPPRESSION_EVIDENCE_PREFIX;
+        use crate::project::Project;
+        use crate::types::CheckLayer;
+
+        struct FakeCheck {
+            id: &'static str,
+            covers: &'static [&'static str],
+        }
+
+        impl Check for FakeCheck {
+            fn id(&self) -> &str {
+                self.id
+            }
+            fn label(&self) -> &'static str {
+                "fake"
+            }
+            fn group(&self) -> CheckGroup {
+                CheckGroup::P1
+            }
+            fn layer(&self) -> CheckLayer {
+                CheckLayer::Behavioral
+            }
+            fn applicable(&self, _p: &Project) -> bool {
+                true
+            }
+            fn run(&self, _p: &Project) -> anyhow::Result<CheckResult> {
+                unreachable!()
+            }
+            fn covers(&self) -> &'static [&'static str] {
+                self.covers
+            }
+        }
+
+        // Two checks: one ran (Pass → counts as verified), one was
+        // suppressed by --audit-profile (Skip with the sentinel prefix →
+        // MUST NOT count as verified).
+        let results = vec![
+            make_result("verifier-ran", CheckStatus::Pass, CheckGroup::P1),
+            make_result(
+                "verifier-suppressed",
+                CheckStatus::Skip(format!("{SUPPRESSION_EVIDENCE_PREFIX}human-tui")),
+                CheckGroup::P1,
+            ),
+        ];
+        let checks: Vec<Box<dyn Check>> = vec![
+            Box::new(FakeCheck {
+                id: "verifier-ran",
+                covers: &["p1-must-no-interactive"],
+            }),
+            Box::new(FakeCheck {
+                id: "verifier-suppressed",
+                covers: &["p1-should-tty-detection"],
+            }),
+        ];
+
+        let summary = build_coverage_summary(&results, &checks);
+        assert_eq!(
+            summary.must.verified, 1,
+            "only the non-suppressed verifier's requirement should count; \
+             suppressed Skips MUST NOT inflate coverage_summary.verified",
+        );
+        assert_eq!(summary.should.verified, 0);
+    }
+
     #[test]
     fn test_exit_code_all_pass() {
         let results = vec![
@@ -476,7 +608,7 @@ mod tests {
         let audience = classify(&results);
         let json = format_json(&results, &[], audience, None);
         let parsed: serde_json::Value = serde_json::from_str(&json).expect("valid JSON");
-        assert_eq!(parsed["audience"], "agent_optimized");
+        assert_eq!(parsed["audience"], "agent-optimized");
         assert!(parsed["audit_profile"].is_null());
         assert_eq!(parsed["schema_version"], "1.1");
     }
@@ -500,7 +632,7 @@ mod tests {
         let audience = classify(&results);
         let json = format_json(&results, &[], audience, None);
         let parsed: serde_json::Value = serde_json::from_str(&json).expect("valid JSON");
-        assert_eq!(parsed["audience"], "human_primary");
+        assert_eq!(parsed["audience"], "human-primary");
     }
 
     #[test]
@@ -526,4 +658,156 @@ mod tests {
         let parsed: serde_json::Value = serde_json::from_str(&json).expect("valid JSON");
         assert_eq!(parsed["audit_profile"], "human-tui");
     }
+
+    #[test]
+    fn format_json_audience_reason_insufficient_signal() {
+        // Source-only-style run: no signal checks → audience null and
+        // audience_reason must explain why.
+        let results = vec![make_result(
+            "p1-env-flags-source",
+            CheckStatus::Pass,
+            CheckGroup::P1,
+        )];
+        let json = format_json(&results, &[], None, None);
+        let parsed: serde_json::Value = serde_json::from_str(&json).expect("valid JSON");
+        assert!(parsed["audience"].is_null());
+        assert_eq!(parsed["audience_reason"], "insufficient_signal");
+    }
+
+    #[test]
+    fn format_json_audience_reason_omitted_when_audience_labeled() {
+        use crate::scorecard::audience::{SIGNAL_CHECK_IDS, classify};
+
+        let results: Vec<CheckResult> = SIGNAL_CHECK_IDS
+            .iter()
+            .map(|id| make_result(id, CheckStatus::Pass, CheckGroup::P1))
+            .collect();
+        let audience = classify(&results);
+        let json = format_json(&results, &[], audience, None);
+        let parsed: serde_json::Value = serde_json::from_str(&json).expect("valid JSON");
+        // audience has a label, so audience_reason must be omitted — not
+        // merely null. `#[serde(skip_serializing_if = "Option::is_none")]`
+        // on the field makes this verifiable by key presence.
+        assert_eq!(parsed["audience"], "agent-optimized");
+        assert!(
+            parsed.get("audience_reason").is_none(),
+            "audience_reason key should be absent when audience is labeled, got {}",
+            parsed["audience_reason"],
+        );
+    }
+
+    #[test]
+    fn format_json_audience_reason_suppressed() {
+        use crate::principles::registry::SUPPRESSION_EVIDENCE_PREFIX;
+        use crate::scorecard::audience::{SIGNAL_CHECK_IDS, classify};
+
+        // One signal suppressed → audience null and reason "suppressed".
+        let results: Vec<CheckResult> = SIGNAL_CHECK_IDS
+            .iter()
+            .enumerate()
+            .map(|(i, id)| {
+                let status = if i == 0 {
+                    CheckStatus::Skip(format!("{SUPPRESSION_EVIDENCE_PREFIX}human-tui"))
+                } else {
+                    CheckStatus::Pass
+                };
+                make_result(id, status, CheckGroup::P1)
+            })
+            .collect();
+        let audience = classify(&results);
+        let json = format_json(&results, &[], audience, Some("human-tui".into()));
+        let parsed: serde_json::Value = serde_json::from_str(&json).expect("valid JSON");
+        assert!(parsed["audience"].is_null());
+        assert_eq!(parsed["audience_reason"], "suppressed");
+    }
+
+    #[test]
+    fn exit_code_drops_when_audit_profile_suppresses_a_would_have_failed_check() {
+        // Intentional behavior per plan R4: when --audit-profile suppresses
+        // a check that would otherwise Fail, the check emits Skip with the
+        // suppression prefix and the overall exit code reflects the
+        // masked state. This is a trust-boundary choice — the caller
+        // declared the requirement doesn't apply, so failing on it would
+        // be misleading.
+        //
+        // This test pins the behavior against a future well-meaning
+        // change that tries to "refuse to exit 0 if any check was
+        // suppressed." Such a change must update this test deliberately
+        // and resolve the conflict with plan R4, not sneak through.
+        use crate::principles::registry::SUPPRESSION_EVIDENCE_PREFIX;
+
+        let baseline = vec![
+            make_result("c-pass", CheckStatus::Pass, CheckGroup::P1),
+            make_result(
+                "c-would-fail",
+                CheckStatus::Fail("violates MUST".into()),
+                CheckGroup::P1,
+            ),
+        ];
+        assert_eq!(exit_code(&baseline), 2, "baseline: a Fail → exit 2");
+
+        let suppressed = vec![
+            make_result("c-pass", CheckStatus::Pass, CheckGroup::P1),
+            make_result(
+                "c-would-fail",
+                CheckStatus::Skip(format!("{SUPPRESSION_EVIDENCE_PREFIX}human-tui")),
+                CheckGroup::P1,
+            ),
+        ];
+        assert_eq!(
+            exit_code(&suppressed),
+            0,
+            "suppression by audit_profile must lower the exit code — \
+             Fail → Skip is intentional masking per plan R4",
+        );
+    }
+
+    #[test]
+    fn scorecard_level_enum_values_are_kebab_case() {
+        // Both `audience` and `audit_profile` enum values MUST serialize
+        // as kebab-case inside the v1.1 scorecard JSON. `audit_profile`
+        // echoes the CLI flag value (`--audit-profile human-tui`) and
+        // cannot change casing; `audience` adopts the same convention so
+        // consumers don't juggle two rules inside one document.
+        //
+        // A future serde `rename_all` edit, field reorder, or enum
+        // migration that silently flips either convention must fail here
+        // loudly. The snake_case negative assertions below guard against
+        // the most likely regression direction (adopting the per-result
+        // enum convention from `CheckGroup` / `CheckLayer` / `Confidence`).
+        use crate::scorecard::audience::{SIGNAL_CHECK_IDS, classify};
+
+        let results: Vec<CheckResult> = SIGNAL_CHECK_IDS
+            .iter()
+            .map(|id| make_result(id, CheckStatus::Pass, CheckGroup::P1))
+            .collect();
+        let audience = classify(&results);
+        let json = format_json(&results, &[], audience, Some("human-tui".into()));
+
+        // audience: kebab-case.
+        assert!(
+            json.contains("\"audience\": \"agent-optimized\""),
+            "audience must serialize as kebab-case 'agent-optimized', got:\n{json}",
+        );
+        assert!(
+            !json.contains("\"agent_optimized\""),
+            "audience must NOT render as snake_case 'agent_optimized' — \
+             kebab-case unified with audit_profile in v0.1.3",
+        );
+        assert!(
+            !json.contains("\"human_primary\""),
+            "audience must NOT render as snake_case 'human_primary'",
+        );
+
+        // audit_profile: kebab-case (echo of the CLI flag value).
+        assert!(
+            json.contains("\"audit_profile\": \"human-tui\""),
+            "audit_profile must serialize as kebab-case 'human-tui', got:\n{json}",
+        );
+        assert!(
+            !json.contains("\"human_tui\""),
+            "audit_profile must NOT render as snake_case 'human_tui' — \
+             would desync from the --audit-profile flag value shape",
+        );
+    }
 }
diff --git a/tests/integration.rs b/tests/integration.rs
index 01727a0..14f9d75 100644
--- a/tests/integration.rs
+++ b/tests/integration.rs
@@ -820,12 +820,121 @@ fn test_audit_profile_shrinks_audience_denominator() {
     );
 }
 
+#[test]
+fn test_audience_non_null_on_self_dogfood() {
+    // End-to-end guard for the main.rs → scorecard audience handoff.
+    // A unit test in `src/scorecard` feeds synthetic `CheckResult`s into
+    // `classify()`, but only an integration run exercises
+    // `run_check()` → `classify()` → `build_scorecard()` on real data.
+    // A regression that passes `None` at the main.rs call site would pass
+    // every existing unit test and only fail here.
+    //
+    // Self-dogfood produces `agent-optimized` today — but the specific
+    // label isn't the contract. What matters is that `audience` is a
+    // non-null string (classifier actually ran) and that `audience_reason`
+    // is absent (no gap to explain).
+    let assert = cmd().args(["check", ".", "--output", "json"]).assert();
+    let output = assert.get_output().stdout.clone();
+    let json_str = String::from_utf8(output).expect("utf8 stdout");
+    let parsed: serde_json::Value = serde_json::from_str(&json_str).expect("valid JSON");
+
+    let audience = parsed["audience"].as_str().unwrap_or_else(|| {
+        panic!(
+            "self-dogfood must produce a concrete audience label, got {:?}",
+            parsed["audience"]
+        )
+    });
+    assert!(
+        matches!(audience, "agent-optimized" | "mixed" | "human-primary"),
+        "audience must be one of the 3 enum values, got {audience:?}",
+    );
+    assert!(
+        parsed.get("audience_reason").is_none(),
+        "audience_reason key should be absent when audience is labeled, got {}",
+        parsed["audience_reason"],
+    );
+}
+
+#[test]
+fn test_principle_filter_forces_audience_null() {
+    // `--principle 2` drops every non-P2 check from `all_checks` before
+    // the run loop. Since the 4 audience signals span P1, P2, P6, P7,
+    // three of them disappear — audience must be null with
+    // `audience_reason: "insufficient_signal"`.
+    let assert = cmd()
+        .args(["check", ".", "--principle", "2", "--output", "json"])
+        .assert();
+    let output = assert.get_output().stdout.clone();
+    let json_str = String::from_utf8(output).expect("utf8 stdout");
+    let parsed: serde_json::Value = serde_json::from_str(&json_str).expect("valid JSON");
+
+    assert!(
+        parsed["audience"].is_null(),
+        "filtering to a single principle drops 3 of 4 signal checks — audience must be null",
+    );
+    assert_eq!(parsed["audience_reason"], "insufficient_signal");
+}
+
+#[test]
+fn test_scorecard_json_has_stable_top_level_keys() {
+    // Snapshot-style contract check: the site renderer and any agent
+    // consumer pin against this exact key set. A regression that
+    // accidentally renames or drops a top-level key fails here rather
+    // than silently breaking downstream consumption. New keys (always
+    // additive) should add to EXPECTED; removals or renames require a
+    // plan revision because they break v1.1 consumers.
+    //
+    // Enforcing "no unexpected keys" too (bidirectional check) means an
+    // accidental extra key also fails — which is the correct behavior
+    // for a versioned schema contract.
+    let assert = cmd().args(["check", ".", "--output", "json"]).assert();
+    let output = assert.get_output().stdout.clone();
+    let json_str = String::from_utf8(output).expect("utf8 stdout");
+    let parsed: serde_json::Value = serde_json::from_str(&json_str).expect("valid JSON");
+    let obj = parsed.as_object().expect("scorecard is a JSON object");
+
+    const EXPECTED: &[&str] = &[
+        "schema_version",
+        "results",
+        "summary",
+        "coverage_summary",
+        "audience",
+        "audit_profile",
+    ];
+    // `audience_reason` is present only when audience is null — on the
+    // self-dogfood it should NOT appear, consistent with the skip rule.
+    const OPTIONAL: &[&str] = &["audience_reason"];
+
+    for key in EXPECTED {
+        assert!(
+            obj.contains_key(*key),
+            "scorecard JSON missing required v1.1 key {key:?}; got {:?}",
+            obj.keys().collect::<Vec<_>>(),
+        );
+    }
+    let unexpected: Vec<&String> = obj
+        .keys()
+        .filter(|k| !EXPECTED.contains(&k.as_str()) && !OPTIONAL.contains(&k.as_str()))
+        .collect();
+    assert!(
+        unexpected.is_empty(),
+        "scorecard JSON grew unexpected top-level key(s): {unexpected:?}. Additive? \
+         Add to EXPECTED/OPTIONAL in this test. Breaking? Plan revision required.",
+    );
+
+    // Fixed enumerations also pin against the renderer contract.
+    assert_eq!(obj["schema_version"], "1.1");
+}
+
 #[test]
 fn test_audit_profile_diagnostic_does_not_panic_on_self() {
-    // Dogfood edge case from the plan: whimsical combination that still
-    // must not crash. diagnostic-only suppresses p5-dry-run, which is a
-    // project check that runs against the current directory.
-    cmd()
+    // Dogfood edge case from the plan: `diagnostic-only` suppresses
+    // p5-dry-run on the self-target. A regression that drops the
+    // suppression (check runs normally) would still exit with a valid
+    // code, so a stronger assertion is required: `p5-dry-run` must
+    // appear in `results[]` as `status: "skip"` with the structured
+    // suppression evidence.
+    let assert = cmd()
         .args([
             "check",
             ".",
@@ -836,6 +945,27 @@ fn test_audit_profile_diagnostic_does_not_panic_on_self() {
         ])
         .assert()
         .code(predicate::in_iter([0, 1, 2]));
+    let output = assert.get_output().stdout.clone();
+    let json_str = String::from_utf8(output).expect("utf8 stdout");
+    let parsed: serde_json::Value = serde_json::from_str(&json_str).expect("valid JSON");
+
+    let results = parsed["results"].as_array().expect("results is array");
+    let p5 = results
+        .iter()
+        .find(|r| r["id"] == "p5-dry-run")
+        .expect("p5-dry-run check should appear in results[]");
+    assert_eq!(
+        p5["status"], "skip",
+        "diagnostic-only must suppress p5-dry-run to Skip (got {p5})",
+    );
+    let evidence = p5["evidence"]
+        .as_str()
+        .expect("suppressed p5-dry-run carries evidence string");
+    assert!(
+        evidence.contains("suppressed by audit_profile: diagnostic-only"),
+        "expected suppression evidence prefix, got {evidence:?}",
+    );
+    assert_eq!(parsed["audit_profile"], "diagnostic-only");
 }
 
 /// instead of derived from self.id()/self.group()/self.layer(). This test walks the
@@ -906,3 +1036,113 @@ fn convention_check_x_returns_check_status_not_check_result() {
         }
     }
 }
+
+/// CLAUDE.md "Source Check Convention" says: **no `Check` impl constructs
+/// `CheckResult` outside its own `run()`.** Every check file's
+/// `CheckResult { ... }` struct literal must sit inside a `fn run(`
+/// function body — not in helpers, module-level code, or anything else.
+///
+/// The runtime layer (`src/main.rs`) is exempt — it legitimately
+/// constructs `CheckResult` in the error and audit_profile-suppression
+/// branches using `check.id()` / `check.label()` / `check.group()` /
+/// `check.layer()` from the trait, not string literals. Test doubles
+/// inside `#[cfg(test)]` are also exempt.
+///
+/// This test walks every `src/checks/**/*.rs` file, strips the
+/// `#[cfg(test)]` section, and flags any `CheckResult {` literal whose
+/// nearest preceding `fn <name>(` declaration is not named `run`. Paired
+/// with `convention_check_x_returns_check_status_not_check_result`
+/// above (which catches helpers returning CheckResult), this enforces
+/// the full convention.
+#[test]
+fn convention_check_result_constructed_only_in_run_body() {
+    use std::ffi::OsStr;
+    use std::fs;
+    use std::path::Path;
+
+    let root = Path::new(env!("CARGO_MANIFEST_DIR")).join("src/checks");
+    assert!(
+        root.is_dir(),
+        "checks root dir not found: {}",
+        root.display()
+    );
+
+    let mut violations: Vec<String> = Vec::new();
+    visit_dir_all(&root, &mut |path, contents| {
+        // Strip everything at and below the first `#[cfg(test)]` — test
+        // modules construct CheckResult via FakeCheck / make_result and
+        // are legitimately exempt from the convention.
+        let scan = match contents.find("#[cfg(test)]") {
+            Some(cut) => &contents[..cut],
+            None => contents,
+        };
+
+        let lines: Vec<&str> = scan.lines().collect();
+        for (i, line) in lines.iter().enumerate() {
+            // Match struct-literal construction, not the return-type
+            // position in a function signature (`-> CheckResult {`).
+            let trimmed = line.trim_start();
+            if trimmed.starts_with("//") {
+                continue;
+            }
+            let idx = match line.find("CheckResult {") {
+                Some(k) => k,
+                None => continue,
+            };
+            // Skip the signature return-type case.
+            let before = &line[..idx];
+            if before.trim_end().ends_with("->") {
+                continue;
+            }
+
+            // Walk backward to find the nearest `fn <name>(` declaration.
+            let enclosing_fn = lines[..i]
+                .iter()
+                .rev()
+                .find_map(|l| {
+                    let t = l.trim_start();
+                    // Ignore comment lines mentioning `fn foo(`.
+                    if t.starts_with("//") {
+                        return None;
+                    }
+                    let pos = t.find("fn ")?;
+                    let after = &t[pos + 3..];
+                    let name_end = after.find(|c: char| !c.is_ascii_alphanumeric() && c != '_')?;
+                    Some(after[..name_end].to_string())
+                })
+                .unwrap_or_else(|| "<module>".to_string());
+
+            if enclosing_fn != "run" {
+                violations.push(format!(
+                    "{}:{}: CheckResult constructed inside `fn {enclosing_fn}`, not `fn run`",
+                    path.display(),
+                    i + 1,
+                ));
+            }
+        }
+    });
+
+    assert!(
+        violations.is_empty(),
+        "Found {} CheckResult construction(s) outside `fn run` in src/checks/. \
+         CLAUDE.md 'Source Check Convention' requires run() to be the sole \
+         CheckResult constructor per Check impl. Move the construction into \
+         run() (helpers should return CheckStatus).\n\n\
+         Violations:\n{}",
+        violations.len(),
+        violations.join("\n")
+    );
+
+    fn visit_dir_all<F: FnMut(&Path, &str)>(dir: &Path, f: &mut F) {
+        for entry in fs::read_dir(dir).expect("read_dir") {
+            let entry = entry.expect("entry");
+            let path = entry.path();
+            if path.is_dir() {
+                visit_dir_all(&path, f);
+            } else if path.extension() == Some(OsStr::new("rs")) {
+                let contents = fs::read_to_string(&path).expect("read_to_string");
+                f(&path, &contents);
+            }
+        }
+    }
+}