chore(docs): put a completeness census on the docs that have none — the gated one has zero drift #1474

New issue

Open

opened 2026-09-08 13:26:19 +02:00 by bosun · 1 comment

bosun commented

2026-09-08 13:26:19 +02:00

Owner

Three contract docs have three different levels of gating, and drift tracks gate coverage exactly. This is a measurement, not an argument for automation.

doc                        gate                              drift
cli-surface.md             completeness census, all verbs    0 of 47 missing
workflow-api.md            a test covering 1 of 10 workflows 5 of 10 missing
05-building-block-view.md  none at all                       9 of 28 missing

Undocumented in the building-block view: cancelledcontext, credentials, forknotice, giteatwin, mirror, readmepin, releaseassets, secretsinherit, statuscontexts. Zero stale entries — nothing named has vanished. The drift is entirely by omission: packages arrived and were never added.

The template already exists

cmd/rt/main_test.go:226 is a registration census: it enumerates what the binary registers, requires each to appear in the doc, and carries a hand-maintained exclusion map where every entry has a reason and a tracker number. That last part is what keeps it from becoming noise — adding an exclusion is a deliberate surface decision; forgetting to document something is caught.

Scope note, stated rather than discovered

A census catches drift by omission, not prose that has become false. Presence is weaker than integrity. Omission is the failure mode we actually have here; do not let the gate be read as truth-checking.

Acceptance criteria

A census enumerates internal/* from the filesystem and fails when a package is absent from 05-building-block-view.md
It carries an explicit exclusion map, each entry with a reason
The census reddens on a newly-added package, verified by adding one
Its PASS states what it does NOT check — that the prose describing a named package is correct

Anchor

@bosun 2026-09-08, v1.0.0 readiness survey. The three-doc comparison was measured before looking at drift, so the ordering is not hindsight.

Three contract docs have three different levels of gating, and drift tracks gate coverage exactly. This is a measurement, not an argument for automation. ``` doc gate drift cli-surface.md completeness census, all verbs 0 of 47 missing workflow-api.md a test covering 1 of 10 workflows 5 of 10 missing 05-building-block-view.md none at all 9 of 28 missing ``` Undocumented in the building-block view: `cancelledcontext`, `credentials`, `forknotice`, `giteatwin`, `mirror`, `readmepin`, `releaseassets`, `secretsinherit`, `statuscontexts`. **Zero stale entries** — nothing named has vanished. The drift is entirely by omission: packages arrived and were never added. ## The template already exists `cmd/rt/main_test.go:226` is a registration census: it enumerates what the binary registers, requires each to appear in the doc, and carries a hand-maintained exclusion map where **every entry has a reason and a tracker number**. That last part is what keeps it from becoming noise — adding an exclusion is a deliberate surface decision; forgetting to document something is caught. ## Scope note, stated rather than discovered A census catches drift by **omission**, not prose that has become **false**. Presence is weaker than integrity. Omission is the failure mode we actually have here; do not let the gate be read as truth-checking. ## Acceptance criteria - [ ] A census enumerates `internal/*` from the filesystem and fails when a package is absent from `05-building-block-view.md` - [ ] It carries an explicit exclusion map, each entry with a reason - [ ] The census reddens on a newly-added package, verified by adding one - [ ] Its PASS states what it does NOT check — that the prose describing a named package is correct ## Anchor @bosun 2026-09-08, v1.0.0 readiness survey. The three-doc comparison was measured before looking at drift, so the ordering is not hindsight.

bosun added the

priority/high

size/M

kind/chore

labels

2026-09-08 13:26:19 +02:00

bosun referenced this issue

2026-09-08 13:26:47 +02:00

chore(contracts): workflow-api.md documents 5 of 10 reusable workflows, and the drift gate covers 1 #1473

bosun commented

2026-09-08 13:26:47 +02:00

Author

Owner

#1473 is the second consumer of this template — same census, enumerating .forgejo/workflows/reusable-*.yml instead of internal/*. Worth building the shared helper here rather than twice.

#1473 is the second consumer of this template — same census, enumerating `.forgejo/workflows/reusable-*.yml` instead of `internal/*`. Worth building the shared helper here rather than twice.