issue #3397 · alpha.10 · 2026-08-10

Four surfaces. Four different numbers.

Ground truth at v10.0.0-alpha.10 is 105 skills, 36 agents, 217 hooks, 30 lifecycle events. Four places advertise those counts to the public and they do not agree with each other — the worst offender is the first thing anyone reads, and it is the one no CI check can ever see.

The disagreement

surfaceclaimsgated?
README markers (L6, L81-83)105 / 36 / 217yes — stamp-counts.sh
marketplace.json105 / 36 / 217yes
README prose (L135)218 hooks, 29 eventsno
GitHub About blurb114 / 37 / 212impossible

Why the prose drifted

The stamper has two strategies and this line fell between them

README / CLAUDE.md   →  <!--ork:KEY-->VALUE<!--/ork-->   marker replacement
docs/site *.mdx      →  explicit sed phrasings            (MDX renders comments literally)
README prose L135    →  bare number, neither path reaches it

So it was never stamped, and after enough merges it landed wrong in both directions at once: 218 against a real 217, and 29 against a real 30. An ungated claim does not drift in a consistent direction — it just stops being true.

Fix: gate the number, do not correct the digit

- OrchestKit registers 218 hooks across 29
+ OrchestKit registers <!--ork:hooks-->217<!--/ork--> hooks across <!--ork:events-->30<!--/ork-->

Plus a new ork:events marker in stamp-counts.sh, computed from the distinct event keys in hooks.json. Correcting 218→217 would have been true for exactly as long as it took to add hook 218.

Control — it must actually re-stamp

$ sed -i '' 's/217.*30/999 … 7/' README.md      # corrupt it on purpose
  L135: registers <!--ork:hooks-->999<!--/ork--> hooks across <!--ork:events-->7<!--/ork-->

$ bash scripts/stamp-counts.sh                   # exit 0
  L135: registers <!--ork:hooks-->217<!--/ork--> hooks across <!--ork:events-->30<!--/ork-->

Without this step the change is indistinguishable from hand-editing two digits, which is the thing that failed the first time.

The one that cannot be fixed by this PR

GitHub's About blurb lives outside the repository

It reads "114 skills, 37 agents, 212 hooks" — wrong on all three, and drifted far enough that those numbers predate any recent release. It sits in repo settings, reachable only via PATCH /repos/{owner}/{repo}, so no file in the tree contains it and no CI job can compare it against validate-counts.sh.

That makes it a permanent honesty gap rather than a bug with a fix: it needs a one-off update now, and it will drift again the next time the counts move. Worth saying plainly in the issue instead of closing it as done and letting the next person assume it is gated like the rest.

Why this belongs in milestone #164. The milestone is about machinery that claims more than it does, and component counts are the most literal case: a visitor's first impression of the project is four numbers, three surfaces disagreeing, and the loudest one wrong by nine skills. Nothing was broken in the code. The claim was just never checkable — which is the same defect as a hook registered but never dispatched, a guard that cannot observe, or a test whose only failing assertion is "valid JSON".