human-queue --json emits stateDescriptors: the machine's shape as data

README.md

@@ -1353,10 +1353,46 @@ grouped into four lanes so the dashboard can show where PRs pile up:
   ever shrinks.
 
 Each PR is bucketed **once**, by FSM precedence (a human decision dominates a
-stale `ai:*` label). The legacy `states` / `leaks` / `counts` keys are preserved
-unchanged; `lanes` and the additive `counts` keys (`reject`, `relink` (retired,
-counting down to zero), `humanReject`, `humanDesign`, `unvetted`) are the
-full-machine view the dashboard renders.
+stale `ai:*` label). `lanes` and the `counts` keys (`ready`, `design`,
+`blockedOn`, `blockedInfra`, `blockedDeploy` (retired), `reject`, `relink`
+(retired, counting down to zero), `humanReject`, `humanDesign`, `unvetted`) are
+the full-machine view the dashboard renders.
+
+### One population per state (#228)
+
+A state's inventory is its **lane cell**, and its `counts` key is that cell's
+size — derived by iterating the state table, so a key cannot measure something
+its own cell does not.
+
+Five of those keys used to be counted a second way, from the **label bucket**
+(`ai_state_label`, the first `ai:*` label a PR carries) rather than from
+`classify_lane` precedence. Both populations are defensible and neither said
+which it was, so the document answered the same question twice. On 2026-08-06
+`counts.ready` was **23** while the `vetter-verdicts` / `ai:ready` cell was
+**absent** — all 23 labelled PRs were un-vetted at their current head — and the
+dashboard drew the human's merge inbox at 0 beneath a sparkline plotted at 23.
+The daily human-readable review printed the same 23 under `MERGE — ai:ready`, so
+the tool disagreed with its own `--json`. Both now read the cell.
+
+The label population is **not** gone and did not need a second count key: the
+top-level `states` object is exactly that census. `states.<label>` is every PR
+carrying the label whatever its head, click-through like every other array, and
+it has never meant anything else. The two differ precisely on the PRs the
+classifier routes past their own label — a stale-at-head `ai:ready` PR is in
+`states["ai:ready"]` and in the `un-vetted` cell, because it carries the word
+and is not in the state.
+
+**This puts a step in the history series.** Each `human-queue-history.jsonl`
+line copies `counts` verbatim, so a series means whatever its key meant on the
+day it was sampled. `ready`, `design`, `blockedOn`, `blockedInfra` and
+`blockedDeploy` change meaning at the commit that landed this, and the past is
+**not** rewritten — those lines are true measurements of the machine as it then
+was. Only `ready` steps visibly (23 → 0 on the 2026-08-06 snapshot), because
+`ai:ready` is the only label the classifier splits on head drift; the inventory
+did not move (`un-vetted` already held those PRs), the measurement did. The
+other four have no such split and can differ only on a PR carrying two state
+labels, which is off-protocol. `unvetted`, `reject`, `relink`, `humanReject` and
+`humanDesign` were already the lane cell and do not move.
 
 The close-candidate lifecycle carries two further additive counts over BOTH
 subject types (#211/#212) — the legacy `closeCandidateIssues` keeps its