@juzser/blacksmith 0.1.0 → 0.2.0

package/.claude/skills/bs/lessons.md

@@ -0,0 +1,73 @@
+# `/bs lessons` — review pending lesson candidates
+
+[`dispatch.md`](dispatch.md) binds every agent this playbook dispatches;
+none of it is restated here.
+
+1. `smith lessons candidates [--session <id>] [--db state/smith.db]` —
+   pending candidates with their statement, type, scope, and evidence/
+   provenance event ids.
+2. Present each to the operator. Approve, edit, or reject is **always**
+   their call — nothing here self-modifies an agent
+   (architecture §9.4, the memory-poisoning safety boundary).
+   - **Approve**: `smith lessons approve <lesson-id> --session <id>
+     --plan-version <n> --causal-parent <event-id> --actor operator
+     [--note "<why>"]`.
+   - **Edit then approve**: add `--statement`, `--lesson-type` and/or
+     `--lesson-scope` to the same call — it writes the `lesson-edited`
+     first and chains the approval onto it, one commit. A `--statement`
+     goes through **the same novelty gate `raise` uses** (P9-34): if the
+     new text duplicates another lesson the call exits 1 with
+     `lessons.edit-not-novel` and writes **nothing**. Report that to the
+     operator with the id it duplicates and let them choose — approve the
+     lesson it duplicates, reword, or re-run with `--accept-duplicate`,
+     which lands it and records `novelty_override` on the event. Never add
+     `--accept-duplicate` on your own initiative.
+   - **Read the `novelty` block on every approval** (P9-35). The gate
+     catches copy-paste and one-word re-raises — since P9-35 (a) the
+     threshold is corrected per pair for the shorter statement's length —
+     but two changed words, containment and any real rewording all pass it,
+     so the printed `mostSimilarLessonId` and score are the real
+     near-duplicate check, and the operator is the one making it. Quote the
+     score with the bar the block reports, not the configured threshold;
+     they differ whenever the correction applied. An
+     approval that lands non-novel text exits 1 *with the transition
+     applied*: surface it, do not retry it. The UI's Edit action runs the
+     same gate since P9-36 — but it has no `--accept-duplicate` control, so
+     a duplicate the operator decides to keep has to come back to the CLI.
+   - **Reject**: `smith lessons reject <lesson-id> …` — transitions to
+     `invalidated`, the same status the UI's reject action uses
+     (`ui/server/src/app.ts`'s `/reject` route); there is no separate
+     operator-rejection status in taxonomy.yml's `lesson_status`.
+   - `invalidated`, `novelty-rejected` and `superseded` are **terminal**
+     (`LEGAL_LESSON_TRANSITIONS`, `lessons.ts`). Reviving a rejected lesson
+     means raising it again with its own provenance — the command refuses
+     `lessons.illegal-transition` rather than rewriting the decision.
+3. Rebuild the projection so the change is visible:
+   `smith db apply --db state/smith.db --session <id>`.
+4. Periodically run `smith dream [--since <iso-date>]` to extract new raw
+   candidates from decision checkpoints (plan sign-offs, waiver decisions,
+   escalations, gate blocks) before this review — it needs the same
+   `--session/--plan-version/--causal-parent` envelope. Candidates it
+   raises carry `needs_distillation: true`; dispatch **`scribe`**
+   (`.claude/agents/scribe.md`) to turn a promising raw one into a
+   checkable, principle-level statement before presenting it, rather than
+   showing the operator raw event text.
+5. Once a batch is approved, recompile the committed file:
+   `smith lessons compile [--session <id>] [--db state/smith.db]` —
+   regenerates `factory/policies/lessons.md` from every `approved` lesson,
+   sectioned by scope (architecture §9.5). Commit the regenerated file — it
+   is the file every later dispatch reads (`smith lessons for-dispatch`), so
+   an approved-but-uncompiled lesson reaches nobody.
+6. After a compile — or whenever `lessons.md` has grown enough that nobody
+   reads it — ask which entries still earn their place:
+   `smith lessons audit <session-id> [--lessons <file>] [--state-dir <dir>]`.
+   It **recommends only**; every removal is still the operator's call, the
+   same boundary step 2 draws. Read the two evidence classes apart
+   (operator-guide/lessons-and-daemon.md §10b): `retire`/`unreachable` is
+   structural — an earlier entry shadows this one, provable from the corpus
+   text alone — while `idle`/`rescope` needs a log showing the entry was
+   actually loaded and still did not fire. `no-evidence` means the audit
+   could not see enough, and is **never** a reason to drop an entry.
+   Contradictions are reported,
+   not resolved: two entries that disagree are a question for the operator,
+   not something a tool should pick a winner in.

package/.claude/skills/bs/mcp.md

@@ -0,0 +1,29 @@
+# `/bs mcp <project>` — layer the MCP surface on
+
+Every project leaving the factory ships an MCP surface
+(`docs/standards/mcp.md`). It is due **late** — at the mandatory
+`<project> — mcp surface` milestone, once the tools worth exposing are known.
+Running this at `smith new` time would produce a manifest declaring nothing,
+which is the rubber stamp the standard exists to prevent.
+
+1. Run `smith mcp init <project>`. It layers `src/mcp/`, `test/mcp/`, and a
+   root `mcp.manifest.json` onto the already-scaffolded project, merges the
+   `mcp:serve` script and the pinned SDK dependency into its `package.json`,
+   and appends the `mcp surface` milestone to `factory/specs/roadmap.md`.
+   It refuses if the target has no `package.json` (run `/bs new` first) or if
+   a manifest already exists — re-scaffolding would discard declared tools and
+   their operator sign-off.
+2. The scaffold ships one read-only tool (`project_health`) as the worked
+   example. Every tool added after it is **declared in the manifest first**,
+   with a mutation class and matching annotations; anything that is not
+   `read-only` needs `approval: { operator, date, milestone }` — an operator
+   signature, taken at this milestone. Never sign one yourself.
+3. Tools that wrap a guardrail-gated action (deploy, outbound send, writes to
+   `main`) are not allowed at all (mcp.md MCP-S3). A signed `destructive` tool
+   is permission to act inside the project, never a way around an operator
+   gate.
+4. Run `smith mcp check <project>` before closing anything under that
+   milestone. Exit 0 means green; exit 1 prints one `{ rule, path, message }`
+   per violation. `smith epic close` runs the same check and refuses while it
+   is red — the only way past it is `--override-rationale`, which is the
+   operator's call and their name in the event log, never yours.

package/.claude/skills/bs/new.md

@@ -0,0 +1,35 @@
+# `/bs new <project> [--ui]` — scaffold a target project
+
+1. Ask where the project should live, then run `smith new <project> [--ui]
+   [--target-dir <dir>]`. Without `--target-dir` it lands beside the clone, in
+   `<repo-parent>/<project>` — or, when `smith` is an installed package rather
+   than a clone, in the directory you run it from, never inside the package.
+   Either way that is a default rather than a requirement —
+   the answer becomes the `<project-dir>` every later command takes, so take
+   it here rather than assuming it six steps in. The call
+   copies `factory/scaffold/` (TS strict, Biome, Vitest, CI) and layers
+   whatever `factory/policies/stack.yml` answered for: `--ui` adds the
+   frontend, generates `src/styles/main.css`, and vendors the named design
+   system into `design/` if there is one. Then it installs and runs the
+   project's own gates, commits it on a `setup` branch, and registers a
+   bootstrap milestone in `factory/specs/roadmap.md` — all in one call.
+   An answer the templates cannot build (`frontend: react`) makes it **refuse
+   before creating anything**, rather than quietly handing over the frontend
+   they do ship. `smith stack check` says in advance which answers are
+   honoured, merely recorded, or refused.
+2. The gate run is `pnpm install` then `lint`, `typecheck`, `test:coverage`,
+   `build` — `ci.yml`'s order, so the lockfile lands in the first commit and no
+   epic ever needs a serial `task-0-toolchain` (P9-19). It takes a minute or
+   two. Read `toolchain` in the JSON result:
+   - `verified` — every gate passed; plan the first epic against it.
+   - `failed` — `failedStep` names the gate, its `output` is the tail, and
+     `command` is the exact line to re-run by hand. The command exits **1** and
+     the tree is left in place to fix. Do not plan an epic against it.
+   - `skipped` — only when `--skip-toolchain` was passed (offline). Nothing was
+     proven; say so rather than reporting a green.
+3. The JSON result's `commands.ghRepoCreate` and `commands.push` are for the
+   **operator to run themselves** — never execute them from this session
+   (guardrails.md: only the operator pushes a brand-new remote/creates the
+   repo; this skill only prints what to run).
+4. Tell the operator: target dir, branch (`setup`), the `toolchain` verdict, and
+   the two commands.

package/.claude/skills/bs/plan.md

@@ -0,0 +1,172 @@
+# `/bs plan <goal>` — draft or re-plan an epic
+
+[`dispatch.md`](dispatch.md) binds every agent this playbook dispatches;
+none of it is restated here.
+
+The planner-session playbook (architecture §3, §12):
+
+**Pick the effort tier before step 1.** It is chosen per *epic*, not per
+project — the same repo runs a `small` internal-tool epic and a `huge`
+one — and it scales steps 3–4 below plus most of `/bs run`. Ask, do not
+recall:
+
+```bash
+smith effort show --effort <small|medium|huge>   # no plan file exists yet
+smith effort show --plan factory/specs/active/<epic>/plan-vN.json
+```
+
+`profile` is what this epic buys, and every step below that a tier touches
+says which field decides it. `invariants` is what no tier may touch: the
+gate pipeline, the integration check, claim disjointness and worktree
+isolation, the security-reviewer's own triggers, the operator's sign-off,
+the epic verdict, the event log and the escalation ladder run identically at
+every tier. A `small` epic is faster because it deliberates less, never
+because it verifies less — a tier that skipped tests would not be cheap,
+just unverified.
+
+Omit `--effort` and the epic takes `effort.yml`'s `default_tier`. Read
+`effective`, not `requested`: an epic whose live tasks fire `crosscheck.yml`'s
+`plan_quorum` security triggers is floored at `security_floor` no matter what
+was asked for, and `floorApplied: true` says so. An internal tool that
+touches auth is not a small epic. Without `--plan` the floor is *not
+evaluated* — `securityFloorEvaluated: false`, and an empty `securityTriggers`
+there means "not looked at", not "looked at and clean".
+
+1. **Static analysis for claims first.** Before any decomposition, get the
+   target repo's import/dependency graph so claims are computed, not
+   guessed (architecture §5) — dispatch `researcher`
+   (`.claude/agents/researcher.md`) for an unfamiliar repo, or do it
+   directly with Grep/Read for a small one.
+2. Dispatch a **`planner`** session (`.claude/agents/planner.md`, frontier
+   tier) with the goal + the claims analysis. It drafts the epic spec and
+   task specs (`factory/specs/schema/task-spec.schema.json` shape).
+3. Dispatch a **`spec-reviewer`** session (`.claude/agents/spec-reviewer.md`)
+   — a *different model* than the planner's, per its own frontmatter — to
+   hunt spec gaps/ambiguities/missing-nonfunctional clauses
+   (`docs/standards/agent-constraints.md` "planner"; `severity.yml`: most
+   spec gaps land S2, blocking sign-off).
+4. Planner fixes flagged issues; repeat 2–3 until the spec-reviewer has
+   nothing S1/S2 left — or exactly once when `profile.specReviewRounds` is
+   `single-pass` (`small`), where the planner fixes what came back and
+   anything still S1/S2 goes to the operator with the spec at step 5 instead
+   of round-tripping. Then run the plan quorum before sign-off — it
+   evaluates `factory/policies/crosscheck.yml`'s `plan_quorum.triggers`
+   (budget ≥50% of the epic cap, `case: infra`, security-sensitive, low
+   confidence) for you:
+
+   ```bash
+   smith plan quorum --plan <the draft's plan.json> --plan-version <n> \
+     --session <session-id> --causal-parent <event-id> \
+     --confidence <your own 0–1 confidence in this plan> \
+     --out <scratch>/quorum-v<n>.json
+   ```
+
+   `--plan` hands over the draft itself: at this step nothing has been
+   written to `factory/specs/active/<epic>/` yet — that is step 6, on
+   approval — so the verb cannot read a `plan-v<n>.json` that does not
+   exist. (`--epic <epic>` instead of `--plan` critiques a version already
+   filed.) The draft's own `epic_id`/`version` must be the ones the command
+   names, or it refuses (`plan.identity-mismatch`) rather than record one
+   plan's identity with another plan's triggers. `--out` keeps the outcome
+   — three rationales of several kB each — where step 5 can hand it to the
+   operator whole instead of quoting a terminal.
+
+   **Nothing runs this for you — you run it here** when
+   `profile.planQuorum` is `always` (`huge`). At `when-triggered` (`medium`,
+   `small`) run it only when you can already name the trigger from the plan
+   you just wrote — budget ≥50% of the epic cap, `case: infra`, a
+   security-sensitive clause, or your own confidence below 0.8. The command
+   is local and free either way; what the tier is buying back is the step,
+   not the tokens, because the two cross-provider judges are trigger-gated
+   inside `runPlanQuorum` at every tier. Exit 0 = nothing needs
+   the operator. Exit 1 (`critiqued`/`escalated`) is critique-only: never
+   rewrite the plan silently, surface the critique to the operator at step
+   5. If the output is `endorsed` with a non-empty `triggers` array, a
+   trigger fired but no external provider is `enabled` in `crosscheck.yml`
+   — say that plainly to the operator rather than signing off as if a
+   cross-provider quorum happened.
+5. **Present the epic spec + acceptance criteria to the operator.** Nothing
+   executes before they sign off (architecture §1; agent-constraints.md
+   "planner: autonomy — spec sign-off per epic").
+6. On approval, write task specs to
+   `factory/specs/active/<epic>/plan-v1.json` and validate:
+   `smith plan validate factory/specs/active/<epic>/plan-v1.json` must
+   report `{"valid":true}` before anything else touches this plan. Write the
+   tier onto the plan file as a top-level `"effort": "<tier>"` — that is
+   where `/bs run` reads it, and `smith plan amend` carries it into
+   v(n+1) so a re-plan is not a fresh choice. Omit the field to take the
+   policy default; a value that is not `small`/`medium`/`huge` fails
+   validation rather than degrading to it.
+
+   Then read the plan's parallelism ceiling before anyone is dispatched
+   against it:
+
+   ```bash
+   smith wave schedule factory/specs/active/<epic>/plan-v1.json \
+     --session <session-id> --repo <project-dir>
+   ```
+
+   `valid: true` says the plan is well-formed; this says whether it can ever
+   run wide. It replays the wave loop to exhaustion and reports `depth` (how
+   many sequential rounds) and `widest` (the most tasks any round starts —
+   the ceiling beyond which more agents buy nothing). Exit 1 means the plan
+   **stalls** and cannot be finished as written: fix it here, not by watching
+   `/bs run` hang. Exit 2 means it runs but loses width to `constraints` —
+   tasks whose dependencies were satisfied and were held back only by how you
+   drew the claims. That is a plan-time cost and this is the last step that
+   can pay it cheaply; a `widest: 1` plan serializes the whole epic while
+   every gate downstream reports a healthy wave of one. Deferrals for
+   `dependency-pending` never appear there, because a chain of real
+   dependencies is the shape of the work and not a defect. Exit 2 whose
+   `constraints` name `symbol-coupled` is a **re-plan round**, not
+   information: hand the planner the constraint list — the file pairs from
+   the deferral detail — and ask, per pair, for a dependency edge, a
+   `keeps_exports` promise on the producer, or a re-slice.
+   `claim-overlap` / `serialize-hotspot` constraints are the re-slice case
+   above. Exit 2 with no such constraint remains information, not a stop —
+   decide whether to re-slice, and say which you chose when you present the
+   plan.
+
+   Beside the schedule, the read that names what it only counts:
+
+   ```bash
+   smith claims impact --plan factory/specs/active/<epic>/plan-v1.json \
+     <task-id>... --repo <project-dir>
+   ```
+
+   Its `crossings` are the file pairs a `symbol-coupled` constraint points
+   at; `promised` holds the ones a producer's `keeps_exports` already
+   answers, which the schedule admits and the diff is later checked against.
+7. Log the sign-off itself as a decision checkpoint (this is exactly what
+   `smith dream`'s "plan sign-off" extraction looks for, `lessons.ts`):
+   `smith event append '{"session_id":"...","actor":"operator",
+   "event_type":"plan-version-created","plan_version":1,
+   "causal_parent":"...","payload":{"epic_id":"<epic>","version":1,
+   "note":"<operator's own words>"}}'`.
+
+   Then write the backlog that signature approved into the log, hung off
+   the sign-off event:
+
+   ```bash
+   smith plan ingest factory/specs/active/<epic>/plan-v1.json \
+     --session <session-id> --plan-version 1 --causal-parent <sign-off event id>
+   ```
+
+   This is where a task starts existing as far as the log — and so the DB,
+   the Kanban, the Flow graph and every dashboard number — is concerned
+   (D-46, D-254): one `task-added` per task, one `edges-recorded` for the
+   DAG. Nothing downstream runs it for you, and nothing refuses to run
+   without it: `wave next` reads the plan file, so an un-ingested plan still
+   runs, and its task rows then spring into being as a side effect of the
+   first wave or gate event to name an id — with no epic, no claims, no
+   budget and no edges, which is the flat, half-empty board the 2026-09-14
+   UI check found behind two epics. It is idempotent, so run it again on a
+   resumed session; read `added` and `edges` back, and say so when either is
+   0 on a plan that has tasks or edges.
+8. If this epic opens a new roadmap milestone, add it to
+   `factory/specs/roadmap.md` (planner-maintained, architecture §12) — a
+   roadmap change is itself a scope change and needs the same operator nod.
+   Give it a `- goal:` line and list the epic under `- epics:`. That line is
+   load-bearing, not documentation: it is the only text the spec-vs-goal gate
+   can grade the plan against (`/bs run` step 14), and a milestone without one
+   holds every epic it owns.

package/.claude/skills/bs/report.md

@@ -0,0 +1,129 @@
+# `/bs report` — the scribe's progress digest
+
+[`dispatch.md`](dispatch.md) binds every agent this playbook dispatches;
+none of it is restated here.
+
+The scribe-template digest playbook (agent-constraints.md "scribe (digest
+duties, v3.2)"), plus running the scheduler first — a report that omits
+pending proposals lets them sit invisible instead of surfacing them.
+
+1. **Ask what the factory is answerable for, then run the scheduler.**
+   `smith projects list` reads the roadmap's `- project:` bullets — the
+   register `smith new` writes to — and prints the factory itself plus every
+   project it built that has a checkout, ending in the `--project` line to
+   pass on. Do not assemble that list from memory: the maintenance pass
+   reads one lockfile per flag and reports one proposal per repo, so a repo
+   left off the line is not reported as missing, it is simply never
+   mentioned. (The daemon raises `unwatched-project` for a child project with
+   a checkout that is left off the line — not for the factory itself, which is in
+   the pass by default, and not for a declared project with no checkout at
+   all, which `smith projects list` marks with `?` instead of leaving it
+   off the printed list. The two surfaces no longer answer the same
+   question.) Then run `smith scheduler run
+   [--dry] --session <id> [--project <dir>...]` with those flags — a
+   deterministic pass over the event log, it never dispatches an agent
+   itself (`factory/policies/scheduler.yml`, architecture §12). Read its
+   `proposals` and route each kind before writing the digest:
+   - `recheck-proposed` → don't act on it silently; tick it into the next
+     `/bs plan` sign-off as an `origin: recheck` task, same spec/sign-off
+     flow as any other. Re-running the scheduler never duplicates an
+     already-pending proposal for the same task (idempotent by design) —
+     it re-proposes only after that recheck is resolved (a real recheck
+     task created for it, or explicitly declined).
+   - `maintenance-proposed` → read `projectDir` first: one pass can raise
+     several of these, one per `--project`, and they are not
+     interchangeable. Then check `autoSchedulable`: `true` (patch/
+     minor-only version bumps, `scheduler.yml`'s
+     `auto_schedule_confidence`) can go straight into the next `/bs plan`
+     without a fresh conversation; `false` (a major-version bump is
+     present) still needs one.
+   - `growth-review-due` → this is a TRIGGER only, never a scope proposal
+     itself (architecture §12). Open a fresh `/bs plan <goal>` session
+     where the planner reads the living spec/analytics/recheck outcomes
+     and proposes new epics — the operator's tick is required regardless
+     of confidence, same as any other plan sign-off.
+2. **Ask who may say yes.** `smith scheduler admit --session <id>
+   [--project <dir>...]`, with the same flag line step 1 printed, re-reads
+   the same proposals and classifies
+   each one `auto` or `operator` against `scheduler.yml`'s `autonomy:`
+   block (`src/autonomy.ts`). It enacts nothing — the split is printed so
+   it can be read and argued with before anything moves.
+   - `decision: auto` → dispatchable through `/bs run`'s ordinary wave
+     flow without a fresh sign-off. It is still a wave: same worktrees,
+     same gates, same reviewer, and the **PR is still merged by a
+     person**. That merge is the backstop that makes auto-dispatch safe
+     to widen, so never bypass it because the scheduler said `auto`.
+   - `decision: operator` → it waits, and `code` names the rule that held
+     it: `autonomy-disabled`, `growth-never-auto`, `kind-not-whitelisted`,
+     `reason-not-whitelisted`, `below-confidence-floor`, or
+     `security-surface`. Report the `reason` verbatim in the digest — it
+     is written in the terms an operator would use to argue with it.
+   - Every rule in that file can only **deny**. There is no branch that
+     promotes something the whitelist did not name, so "what runs without
+     me?" is answerable by reading `scheduler.yml` alone.
+   - **Never widen the whitelist to clear a denial mid-run.** Editing
+     `autonomy.auto_dispatch_kinds`, `auto_dispatch_recheck_reasons` or
+     `confidence_floor` is an operator decision about standing policy, not
+     a way past one proposal — and a `security-surface` denial is the one
+     nothing in the file can lift.
+3. Gather `smith stats overview [--session <id>]` and `smith stats roadmap
+   [--session <id>]` (milestone progress + budget burn per milestone).
+4. **Read back the disagreements.** `smith judge escalations --session
+   <id>` folds the lineage for `quorum-decision` events whose latest word
+   was `escalate` — a gate finding, an epic verdict or a plan critique the
+   cross-provider quorum could not settle. It exits `1` on an open
+   `disagreement` and `2` when the only thing open is
+   `insufficient-providers`, so **exit 2 is not a failure to fix here**: it
+   is one fact about `crosscheck.yml`'s gating arithmetic, already collapsed
+   to `ungated.count` plus a hint, and it belongs in the digest as a single
+   line. Report each `disagreement` individually — two providers read the
+   same thing and said different words, and nothing else in the pipeline
+   will raise it again. An entry with `held: false` goes first: the quorum
+   did not settle it and the work went ahead regardless (that includes a
+   `mode: shadow` disagreement, which the gate outcome never reported to
+   anyone). Resolving one is an operator reading, never this session
+   deciding on its own which provider was right.
+5. **Read back the parallelism.** `smith wave audit --session <id>
+   [--epic <id>]` folds every `wave-admitted` against the
+   `dispatch_decision` intervals underneath it and says whether a wave
+   admitted N wide actually *ran* N wide. `wave check` only ever certified
+   that it *could*, so without this the digest reports a factory running
+   many agents in parallel on the strength of a permission slip. Exit `1`
+   is a wave whose tasks never once overlapped — report it with the epic
+   id, because a serialized run is the failure this whole design exists to
+   prevent, not a slow day. Exit `2` is a wave admitted with no dispatch
+   under it at all: that is "cannot tell", not "ran narrow", and it usually
+   means the wrong `--state-dir` or a run whose agents wrote elsewhere —
+   check before reporting it as a stall. A `partial` verdict is **not** a
+   finding; put `widest` in the digest as the one number that says how wide
+   this factory has ever actually run.
+6. Dispatch **`scribe`** (`.claude/agents/scribe.md`, small tier) with that
+   JSON plus step 2's admissions as input: shipped / in-flight / blocked /
+   budget burn / next milestone / **N rechecks pending, M maintenance
+   bumps auto-schedulable** (never silently dropped), ≤300 words, linking
+   into the dashboard (`smith ui serve`'s URL) — never paraphrase numbers
+   the query didn't return.
+7. This fires automatically on a weekly cadence and immediately on any
+   milestone completion (architecture §12) — for an ad hoc `/bs report`,
+   the same digest, just on demand.
+8. Sending it to Slack is an **outbound send** — the permission layer
+   prompts on the `curl`/webhook call; never fire it without that prompt
+   resolving (`docs/standards/guardrails.md` "Deploy + outbound"). Print
+   the digest to the operator regardless, whether or not the Slack send is
+   approved.
+
+**Provider calibration note (Phase 8).** While any provider in
+`factory/policies/crosscheck.yml` is still `mode: shadow`, run
+`smith stats providers [--session <id>] [--since <iso-date>]` alongside the
+scheduler pass and fold a one-line mention into the digest when a provider
+has accumulated enough runs to review (`runs`, `verdicts`, `agreementRate`,
+`schemaFailureRate`, `transportFailureRate`, `failuresByCode` per provider —
+`docs/runbooks/providers.md`'s calibration procedure has the promotion
+threshold). Report `verdicts` alongside `agreementRate`: a `null` rate means
+no run ever answered, which is a transport problem to fix, not a provider
+that disagrees (D-168). When the rate is `null`, name the top entry in
+`failuresByCode` in the digest line — `provider.missing-api-key` is an unset
+environment variable and the whole repair, where `provider.invalid-output`
+is the prompt (D-253). Promoting a provider to
+`mode: active` is always an **operator edit** of `crosscheck.yml`, never
+something this session does on the digest's say-so.