feat(cli): derive default metric thresholds from evidence

[dekobon]

Summary

The [thresholds] table bca init scaffolds was chosen by eye and pinned
byte-for-byte to this repository's own bca.toml by a drift test, so "what
adopters get on day one" and "what this Rust project gates itself at" were the
same numbers by construction. This derives them from evidence instead,
decouples the two, and documents per-language and per-use-case guidance that
did not exist anywhere.

Evidence

43 shallow-cloned real-world repositories across 20 languages (test, vendored,
and generated trees excluded), measured with the release bca binary: ~254k
function spaces, 40k container spaces, 27k files. Values binned by the same
File / Function / Container scope bca check applies, so a container's nom
never lands in a per-function distribution.

Published anchors disagree by wide margins — cyclomatic defaults alone span 7
(RuboCop) to 30 (gocyclo) — so each limit is anchored to a published value
and checked against measurement. The sizing rule: a default should flag
roughly the worst 1-3% of spaces in the median language. Below that it is inert
and gives false comfort; above it the gate becomes a style rule people route
around.

Shipped defaults

Metric	From	To	Why
cognitive	25	15	SonarSource's own default for the metric they designed; 25 came from clippy, which lints rather than gates
nargs	7	5	RuboCop's value. 7 fired on under 1% of functions and on nothing in this repository — a limit that cannot fire
abc	50	40	Was the loosest gate in the set; 40 matches cyclomatic's strictness
loc.ploc	—	600	New: the working file-size limit, code only
loc.sloc	800	1200	Demoted to a comment-inclusive bloat backstop

cyclomatic, nexits, halstead.effort, nom, and wmc are unchanged.
halstead.volume is deliberately not gated: the widely-cited "function volume
under 1000" guideline fires on ~7% of functions in the median language and 20%
in the worst, which is advisory-grade, not gate-grade.

Existing bca.toml files are unaffected; this changes what a fresh bca init
writes.

Decoupling

default_thresholds.rs is now the single source of truth, and the scaffold
renders its [thresholds] block from it, rationale comments included. The
init_template_thresholds_match_repo_root drift test is replaced by one
pinning the scaffold to that table, leaving the repo-root manifest free to keep
its own Rust-specific calibration (it says so inline).

Documentation

New book recipe Choosing thresholds: the derivation, a per-language table
with the measured 97.5th percentile for every supported language, and four
use-case profiles (blocking CI gate, agent feedback loop, legacy triage,
safety-critical). AGENTS.md carries the summary table and the caveats so
coding agents read them by default.

Recorded caveats that make the numbers honest: C#'s distribution is dominated
by property accessors, which bca counts as functions; nom and wmc measure
an Elixir defmodule rather than a class, so ~1/3 of Elixir modules breach;
nargs is inert for Bash, Perl, and Elixir; and four languages have samples
too thin to derive file-size figures from.

Repo self-scan (closes #1138)

loc.sloc = 800 was calibrated for test-inclusive SLOC and never revisited
after exclude_tests = true landed twelve days later. Because SLOC counts
comments, it charged the same price for a paragraph of rationale as for a new
branch, and seven files had settled into a four-line band ending exactly on the
soft limit — trimming-to-fit, not a natural distribution.

This repo now gates loc.ploc = 550 (just above its p99 of 545) with
loc.sloc = 1300 as the backstop. Baseline regenerated in the same commit; net
21 fewer entries.

Testing

make pre-commit green. Every new guard was verified by perturbation rather
than by passing alone — each fails with the intended message, and nothing else
does:

• rendering entry.limit + 1 fails the round-trip, scaffold, and quoting tests
• dropping a name from either rendered inventory fails the registry guard
• editing one row of the AGENTS.md or book table fails the doc drift guard
• raising nargs to 500 fails the new offender test
• dropping loc.sloc below loc.ploc fails the two-tier invariant

The offender test is the one worth calling out: the pre-existing scaffold test
asserts a clean file passes, which a scaffold with every limit at 1,000,000
would also do. Since this PR's central finding is that an inert limit is the
bug, "the defaults catch something" needed its own coverage.

Follow-ups filed

• feat(config): per-language [thresholds] overrides in bca.toml #1141 — per-language [thresholds] in bca.toml. The per-language table is
  currently advice a polyglot repo cannot apply, since one manifest carries one
  table.
• fix(metrics/nargs): Elixir reports 0 arguments for every function #1142 — Elixir nargs reports 0 for every function.
• fix(metrics/nargs): Perl reports 0 arguments for signature subs #1147 — Perl nargs reports 0 for signature subs. Found while correcting a
  claim in this PR's own docs that said the Perl zero was correct.
• chore(self-scan): converge repo thresholds onto the shipped defaults #1143 — converge this repo's cognitive / nargs / abc onto the shipped
  defaults, one metric per change. Deliberately not done here: converging all
  three at once costs ~95 baseline entries in one commit, which reads as debt
  rather than as a decision. bca.toml says so inline.

Closes #1140