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

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

The doc that calls itself the primary compatibility contract for the toolkit covers half the surface it is a contract for, and the test that keeps it honest checks one workflow out of ten.

docs/architecture/contracts/workflow-api.md states its own scope: "the adopter surface is the reusable-workflow uses:@<ref> interface". Measured 2026-09-08:

reusable workflows in that surface   10
named in the contract doc            5   (fragment-check, manifest-check,
                                          prepared-uncut-check, release, workflow-parse-check)
missing                              5   (ac-closure-check, changelog-body-check,
                                          mirror-release, recover-pending-cut, register-check)
covered by the drift gate            1   (TestWorkflowAPISchemaMatchesReusableRelease)

v1.0.0's whole meaning is that this surface does not move. Nine tenths of it has no mechanism keeping that true.

Acceptance criteria

All 10 reusable workflows appear in workflow-api.md with their workflow_call inputs and outputs
A census test enumerates .forgejo/workflows/reusable-*.yml from the filesystem and fails when one is absent from the doc — modelled on cmd/rt/main_test.go:226 (c5ContractDoc), including its explicit exclusion map where each entry carries a reason and a tracker number
The schema drift gate covers all 10, not only reusable-release.yml
The census fails when a NEW reusable workflow is added and not documented, verified by adding one and watching it redden

Anchor

@bosun 2026-09-08, v1.0.0 readiness survey. See #NNN (doc-census) for the shared template and the natural experiment behind it.

The doc that calls itself the primary compatibility contract for the toolkit covers half the surface it is a contract for, and the test that keeps it honest checks one workflow out of ten. `docs/architecture/contracts/workflow-api.md` states its own scope: *"the adopter surface is the reusable-workflow `uses:@<ref>` interface"*. Measured 2026-09-08: ``` reusable workflows in that surface 10 named in the contract doc 5 (fragment-check, manifest-check, prepared-uncut-check, release, workflow-parse-check) missing 5 (ac-closure-check, changelog-body-check, mirror-release, recover-pending-cut, register-check) covered by the drift gate 1 (TestWorkflowAPISchemaMatchesReusableRelease) ``` v1.0.0's whole meaning is that this surface does not move. Nine tenths of it has no mechanism keeping that true. ## Acceptance criteria - [ ] All 10 reusable workflows appear in `workflow-api.md` with their `workflow_call` inputs and outputs - [ ] A census test enumerates `.forgejo/workflows/reusable-*.yml` from the filesystem and fails when one is absent from the doc — modelled on `cmd/rt/main_test.go:226` (`c5ContractDoc`), including its explicit exclusion map where each entry carries a reason and a tracker number - [ ] The schema drift gate covers all 10, not only `reusable-release.yml` - [ ] The census fails when a NEW reusable workflow is added and not documented, verified by adding one and watching it redden ## Anchor @bosun 2026-09-08, v1.0.0 readiness survey. See `#NNN` (doc-census) for the shared template and the natural experiment behind it.

bosun added the

priority/high

size/M

kind/chore

labels

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

bosun commented

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

Author

Owner

The census template and the three-doc natural experiment behind it are on #1474. Build it once there; this tracker consumes it for the reusable-workflow enumeration.

bosun referenced this issue

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

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