feat(v0.1.3): resolve 26 ce-review findings + unify audience to kebab-case

[brettdavies]

Summary

Resolves all 26 findings from the ce-review of commit dc5d74168577 and unifies audience JSON values to kebab-case (a
post-review decision that eliminates a mixed-casing asymmetry flagged during review).

Changelog

Added

• audience_reason field on scorecard JSON — populated only when audience is null, with "suppressed" (signal check masked by --audit-profile) or "insufficient_signal" (signal check never produced) so consumers can see why the classifier withheld a label.
• audit_profiles array in coverage/matrix.json — each entry carries {name, description, suppresses[]}, letting agents and site renderers enumerate the four --audit-profile categories and what each one suppresses without scraping --help.

Changed

• Suppressed and errored results[].label values now show the check's human-readable label (e.g., "Respects NO_COLOR") instead of falling back to the check id.

Documentation

• README.md, AGENTS.md, and CLAUDE.md updated to describe the shipped v0.1.3 scorecard surface: audience + audience_reason + audit_profile field semantics, the --audit-profile flag with examples, and the audit_profiles section of coverage/matrix.json as the programmatic source for category enumeration.

Type of Change

• feat: New feature (non-breaking change which adds functionality)
• fix: Bug fix (non-breaking change which fixes an issue)
• refactor: Code refactoring (no functional changes)
• test: Adding or updating tests
• docs: Documentation update

Related Issues/Stories

• Plan (CLI-side): docs/plans/2026-04-21-v013-handoff-5-cli-audience-classifier.md — Implementation Log captures the
  post-review kebab-case deviation
• Plan (site-side coordination): agentnative-site/docs/plans/2026-04-21-v013-handoff-6-site-leaderboard-launch.md —
  Unit 0.5 covers the kebab-case absorption that must land before the v0.1.3 scorecard regen wave
• Compounded learning: docs/solutions/best-practices/module-directory-promotion-pattern-2026-04-22.md — canonical git mv recipe for foo.rs → foo/mod.rs promotions (documented off the back of this PR's help_probe extraction)
• Compounded-trilogy cross-links: docs/solutions/best-practices/rust-module-splitting-srp-not-loc-20260327.md,
  docs/solutions/best-practices/rust-pub-crate-fields-for-cross-module-impl-pattern-2026-04-20.md
• Related PR (base commit under review): feat(v0.1.3): audience classifier + --audit-profile suppression + p1-env-hints Pattern 2 #26
• CE-review artifacts: .context/compound-engineering/ce-review/20260422-134229-565fc6d7/ (10 reviewer JSONs +
  metadata.json; local-only by convention)

Testing

• Unit tests added/updated
• Integration tests added/updated
• Manual testing completed
• All tests passing

Test Summary:

• Unit tests: 402 passing (net +8 new across scorecard::audience, scorecard::tests, principles::registry,
  principles::matrix, cli::tests, and runner::help_probe::env_hints_bash::tests)
• Integration tests: 50 passing (net +3 new: concrete non-null audience on self-dogfood, --principle forces audience: null, full-shape JSON snapshot lock)
• cargo fmt --check: clean
• cargo clippy --all-targets -- -Dwarnings: clean
• cargo deny check: advisories, bans, licenses, sources all OK
• cargo run -- generate coverage-matrix --check: no drift
• scripts/hooks/pre-push (full local-CI mirror): all checks passed
• GitHub CI on the PR head (7a384b8): all 5 required checks green
• Dogfood without profile: anc check . --output json → schema_version: "1.1", audience: "agent-optimized",
  audit_profile: null, audience_reason absent (omitted via skip_serializing_if).
• Dogfood with profile: anc check . --audit-profile human-tui → audience: null, audience_reason: "suppressed",
  coverage_summary.must.verified drops 17 → 15 (suppressed P1 checks no longer inflate the metric).

Files Modified

Modified:

• AGENTS.md, CLAUDE.md, README.md — v0.1.3 scorecard surface sync
• coverage/matrix.json — regenerated (adds top-level audit_profiles array)
• src/check.rs — new abstract label(&self) -> &'static str trait method
• src/checks/**/*.rs (40 files) — mechanical label() impl + run() body migration from label: "…".into() literals
  to label: self.label().into()
• src/cli.rs — AuditProfile ↔ ExceptionCategory parity drift tests
• src/main.rs — SUPPRESSION_EVIDENCE_PREFIX usage + check.label() in error and --audit-profile suppression
  branches
• src/principles/registry.rs — SUPPRESSION_EVIDENCE_PREFIX constant, ALL_EXCEPTION_CATEGORIES slice + compile-time
  variant guard, ExceptionCategory::description(), doc additions on SUPPRESSION_TABLE (trust boundary, drift-test
  scope)
• src/principles/matrix.rs — AuditProfileEntry struct, audit_profiles section + per-variant coverage test,
  matrix_json_includes_audit_profiles_section
• src/scorecard/audience.rs — kebab-case classify(), new classify_reason() helper, is_audit_profile_suppression
  promoted to pub(crate), debug_assert! against duplicate signal IDs, module doc + suppression-prefix references
• src/scorecard/mod.rs — audience_reason: Option<String> field (derived in build_scorecard, skip_serializing_if
  when audience has a label), build_coverage_summary filter, Scorecard struct doc, exit_code trust-boundary doc,
  snapshot + casing + duplicate-signal regression tests
• tests/integration.rs — convention test blocking CheckResult { … } outside fn run() in src/checks/**, non-null
  audience dogfood, --principle + audience interaction, full-shape JSON snapshot, tightened diagnostic-only
  assertion, Pattern 2 bracketed-rejection and mixed-case negative fixtures

Created:

• src/runner/help_probe/env_hints_bash.rs — Pattern 2 submodule extracted from the 931-line help_probe.rs; holds
  parse_env_hints_bash_style(), extract_env_tokens(), find_env_section(), is_section_header_line(),
  strip_clap_env_annotations(), SHELL_ENV_BLACKLIST, PATTERN2_WINDOW, and 9 Pattern 2 tests (including 3 new for
  PAGER, section-header exclusion, and mixed-case / placeholder negatives).

Renamed:

• src/runner/help_probe.rs → src/runner/help_probe/mod.rs (via git mv; git detects rename at 58% similarity, blame
  preserved).

Key Features

• Single source of truth for the suppression evidence string (SUPPRESSION_EVIDENCE_PREFIX): producer (main.rs),
  consumer (audience::is_audit_profile_suppression), and filter (build_coverage_summary) all reference the same
  constant so a rename can't silently desync the three sites.
• Check::label() on the trait means every emitted CheckResult — including the runtime layer's error and suppression
  branches — now uses a single source of truth for each check's human label. No more "scorecard row shows the cryptic
  id" when a check errors out or gets masked by a profile.
• EnvHintSource enum (clap_annotation / proximity / env_section) tags every emitted EnvHint with the pattern
  that matched, giving agents a structured signal when debugging a p1-env-hints false positive. Pattern 1 wins on
  duplicates; proximity loses to env_section when both apply.
• Compile-time guard (_all_categories_covers_every_variant) + runtime drift tests
  (audit_profile_and_exception_category_variants_are_isomorphic, suppression_table_check_ids_exist_in_catalog)
  triangulate the AuditProfile (CLI) ↔ ExceptionCategory (registry) ↔ SUPPRESSION_TABLE (registry) relationship so
  a fifth category can't land via partial edits.

Benefits

• Correctness of published metrics. Before this PR, every v0.1.3 scorecard emitted with --audit-profile overstated
  coverage_summary.verified — the site's H6 leaderboard would have rendered inflated coverage numbers that didn't
  match the results-level evidence. Shipped the fix before the site's regen wave.
• JSON consistency. Unifying audience to kebab-case closes the only document-level casing asymmetry in the
  scorecard shape, so consumers no longer need two-rule case logic for one document.
• Agent discoverability. Both the audit_profiles matrix section and the expanded AGENTS.md "Agent-facing JSON
  surface" section turn previously help-text-scraped knowledge into first-class, committed, machine-readable artifacts.
• Regression surface. Eight new positive / negative / drift tests pin intentional behavior that future refactors
  might unknowingly break: exit-code-under-suppression, JSON casing contract, CheckResult construction scope,
  bracketed-env-var rejection, AuditProfile↔ExceptionCategory parity, signal-ID uniqueness, full-shape JSON snapshot,
  --principle + audience interaction.

Breaking Changes

• No breaking changes for v0.1.2 consumers (which always received audience: null and audit_profile: null).
• Breaking for pre-release v0.1.3 consumers that had pinned on snake_case audience values. The only such consumer
  is in-house (agentnative-site's H6 leaderboard), which hasn't shipped yet. Unit 0.5 of the site's H6 plan covers the
  adaptation and must land before the v0.1.3 scorecard regen wave.

Deployment Notes

• No special deployment steps required for this PR into dev.

Release-branch mechanics per RELEASES.md happen in a follow-up PR:
branch off origin/main, cherry-pick these commits (plus 6fdca00 and dc5d741 from dev), bump Cargo.toml 0.1.2 →
0.1.3, regenerate changelog via generate-changelog.sh, PR → main. The Homebrew-tap finalize-release dispatch will
land on the wrong repo per todo 006 in brettdavies/.github — the manual recovery command is pre-staged in the v0.1.3
plan's operational notes section.

Checklist

• Code follows project conventions and style guidelines
• Commit messages follow Conventional Commits
• Self-review of code completed (via ce-review 10-reviewer pass against dc5d741; this PR resolves all findings)
• Tests added/updated and passing (net +11 new)
• No new warnings or errors introduced (-Dwarnings clean)
• Changes are backward compatible for v0.1.2 consumers (see Breaking Changes for the v0.1.3 pre-release note)

Additional Context

The ce-review process produced 10 per-reviewer JSON artifacts under
.context/compound-engineering/ce-review/20260422-134229-565fc6d7/ capturing every finding's full detail-tier fields
(why_it_matters + evidence[]). These are local-only by convention and useful for debugging which finding drove which
change.

The module-directory-promotion-pattern-2026-04-22.md solution doc published to docs/solutions/best-practices/ as
part of this session (not this PR — lives in the shared solutions-docs repo) compounds the
three-instances-of-the-same-refactor evidence (v0.1.2 H4 runner.rs split, v0.1.3 H5 scorecard.rs split, and this
PR's help_probe.rs split) into a canonical recipe. The companion trilogy cross-links across two older Rust
module-organization docs landed in the same solutions-docs push.