docs(canonical-api): close the anti-reinvention gaps + de-reinvent the examples

[drewstone]

What

The anti-reinvention decision table in docs/canonical-api.md (§2 — the doc agents are told to read before writing orchestration/measurement code) had zero rows for whole families of live exports, so agents kept hand-rolling them. This adds them, and de-reinvents the one example that hand-rolled primitives.

1. Reference gaps closed (docs/canonical-api.md §2)

Six grouped rows added, in the existing "I want to ___ → use ___ → NOT ___" voice:

Family	Use (the real primitive)	Was being hand-rolled as
statistics	every test on the agent-eval main barrel — pairedBootstrap, wilson, pairedTTest, wilcoxonSignedRank, mcnemar/mcnemarPower/mcnemarRequiredN, mannWhitneyU, passAtK, confidenceInterval, benjaminiHochberg/bonferroni, cohensD/cliffsDelta, requiredSampleSize/pairedMde, eProcess, weightedComposite, corpusInterRaterAgreement, pairedRiskDifference, pearsonR/spearmanR, paretoFrontier/dominates	a bootstrap-with-PRNG, a Wilson/McNemar/power calc, a Pareto sweep, a Cohen's-d per gate (the #1 measurement reinvention)
judge	a campaign JudgeConfig, or ensembleJudge for a multi-model panel	a hand-built judge prompt loop, or the @deprecated JudgeFn factories
authenticity	scoreAuthenticity → gateRealness over an AuthenticitySignals (agent-eval/authenticity subpath)	a regex realness scorer, or trusting a buildability score that rewards a polished fake
verification	new MultiLayerVerifier(layers).run(...) + gradeSemanticStatus(...)	a hand-chained compile→lint→test→semantic pipeline
reference-replay	runReferenceReplay/scoreReferenceReplay + decideReferenceReplayPromotion over jsonlReferenceReplayStore	a hand-rolled "does the candidate reproduce the reference" matcher
token/usage seam	extractLlmCallEvent / reportLoopUsage (UsageSink) — /loops	re-walking sandbox events to tally tokens yourself

The judge row also kills a recurring confusion: there is no llmJudge export in this version — that name appears only in a campaign-types docstring; the live judge surface is JudgeConfig + ensembleJudge. A future agent reading this doc can no longer conclude "no judge primitive exists."

The freshness gate (scripts/check-docs-freshness.mjs) now loads the agent-eval/authenticity subpath barrel into the §2 export universe, so a row that recommends importing from that subpath resolves — exactly parallel to how contract/campaign/index are already loaded. This strengthens coverage (a real published export surface the gate previously couldn't see), it does not weaken the gate.

2. Example de-reinvented

examples/self-improving-loop was the only example (of 21 audited) that hand-rolled substrate primitives:

• analyst — local interface AnalystFinding { rootCause; proposedMutation } + runAnalyst() → now the canonical AnalystFinding stamped by makeFinding (the exact shape improve(profile, findings, opts) reflects on); mutation rides recommended_action.
• gate — bare v1Mean - v0Mean >= 0.5 point comparison → now pairedBootstrap(v0Scores, v1Scores, { seed }), shipping only when the paired-bootstrap CI lower bound clears 0 — the statistical core the production held-out gate (HeldOutGate / improve() over selfImprove) is built on.

Stays offline + deterministic; the demo still ships v1, now on a +5.00 paired median, 95% CI [5.00, 6.00], n=3. README + comments mirror the already-clean companion examples (improve/, intelligence-recommend/). Only the analyst body, proposer, and LLM remain scripted (for reproducibility) — the finding type and gate statistic are now the real substrate.

Verify (all green)

• pnpm docs:check — docs freshness: OK (§2 table symbols against 4134 public exports; prose symbols against 5795 resolvable; docs/api regen diff clean)
• pnpm run build — clean
• pnpm run typecheck + typecheck:examples — clean (the fixed example compiles)
• pnpm run lint — Checked 319 files, no fixes applied
• Example runs offline e2e: ships v1 on the paired CI [5.00, 6.00]

DO NOT MERGE — operator review.

[tangletools]

✅ Auto-approved PR — 70e098d8

Blanket team auto-approval is enabled for this reviewer service.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: blanket_auto_approve · 2026-06-24T08:54:31Z}

[drewstone]

Superseded by #371. The primitive inventory is now GENERATED (docs/api/primitive-catalog.md, freshness-gate-enforced) so it can't go stale by hand — the root cause this PR hand-patched. The ~30 primitives catalogued here are now auto-generated; the one real example fix (self-improving-loop → HeldOutGate/selfImprove) was folded into #371.