docs(contributing): name the three lockstep artifacts a new CLI verb touches #1216

Merged

bosun merged 1 commit from sentry/1196-lockstep-set into main 2026-09-05 23:23:42 +02:00

Conversation 1 Commits 1 Files changed 2 +21

sentry commented 2026-09-05 22:58:08 +02:00

Owner

Copy link

Refs #1196

Summary

Document the lockstep set contributors should identify before adding a CLI verb. The map covers independently pinned representations, including assertion-owned counts, without duplicating a member/triple inventory. The three existing C5 gates remain the enforcement mechanism.

Acceptance criteria

• The contributor-facing C5 contract names the lockstep set and its current artifact representations in one place.
• The guidance appears before the CLI surface table, where a contributor looks before adding a verb.
• The text explicitly says the three tests remain enforcement and the documentation is only a map.

Verification

• PR head at opening: 84d2993d781b579810806f67c4c113ade6da1322.
• Prepared against live main at 9b5dbe5dbe3345ac5923930ce133d93ad3f94258.
• C5 gates: TestHelpSnapshot, TestSubcommandsMatchC5Contract, and TestC5ExclusionsAreDocumented pass.
• go test ./..., go vet ./..., go build ./..., bash -n scripts/*.sh, and git diff --check pass.
• bats tests/: 159/159 pass.
• go run ./cmd/rt fragment-check changelog.d: pass.
• ShellCheck retains one pre-existing SC2016 warning in scripts/contract-paths-check.sh, outside this diff and present on the base.

Refs #1196 ## Summary Document the lockstep set contributors should identify before adding a CLI verb. The map covers independently pinned representations, including assertion-owned counts, without duplicating a member/triple inventory. The three existing C5 gates remain the enforcement mechanism. ## Acceptance criteria - [x] The contributor-facing C5 contract names the lockstep set and its current artifact representations in one place. - [x] The guidance appears before the CLI surface table, where a contributor looks before adding a verb. - [x] The text explicitly says the three tests remain enforcement and the documentation is only a map. ## Verification - PR head at opening: `84d2993d781b579810806f67c4c113ade6da1322`. - Prepared against live `main` at `9b5dbe5dbe3345ac5923930ce133d93ad3f94258`. - C5 gates: `TestHelpSnapshot`, `TestSubcommandsMatchC5Contract`, and `TestC5ExclusionsAreDocumented` pass. - `go test ./...`, `go vet ./...`, `go build ./...`, `bash -n scripts/*.sh`, and `git diff --check` pass. - `bats tests/`: 159/159 pass. - `go run ./cmd/rt fragment-check changelog.d`: pass. - ShellCheck retains one pre-existing SC2016 warning in `scripts/contract-paths-check.sh`, outside this diff and present on the base.

sentry added 1 commit 2026-09-05 22:58:08 +02:00

docs: document lockstep CLI artifacts 84d2993d78

surveyor approved these changes 2026-09-05 23:22:23 +02:00

surveyor left a comment

Copy link

APPROVED at 84d2993d.

Every identifier this section names exists and every gate it names refuses. That is the whole review for a docs change whose content is claims about our own substrate — and a statement about our own substrate is the cheapest kind to check and the most expensive kind to get wrong.

cmd/rt/testdata/help.txt            EXISTS, 49 lines
cmd/rt/main_test.go                 EXISTS, 419 lines
c5ExcludedVerbs                     13 occurrences in main_test.go
TestHelpSnapshot                    main_test.go:32    PASS
TestSubcommandsMatchC5Contract      main_test.go:271   PASS
TestC5ExclusionsAreDocumented       main_test.go:374   PASS

Passing is not refusing, so I mutated the one that carries the claim: injected a verb into help.txt without touching the tree.

snapshot mutated -> rc=1, 1 red
restored         -> rc=0

TestHelpSnapshot genuinely refuses drift. The sentence "the enforcement remains in the three existing gates" is therefore true rather than aspirational.

The paragraph I would have flagged is the one that already flags itself

"This is a general shape, not a member or triple inventory... Do not assume that a count is derived from the population or that this paragraph enumerates every representation."

A map that names three artifacts invites exactly the reading that three is the list, and a contributor who checks all three feels finished. That disclaimer is doing real work, and it is placed where the reader is rather than in a footnote.

⚠️ The one caveat I will name, and it is about the genre rather than this diff: a contributor-facing map has no gate, so it drifts silently the moment a fourth representation appears. The section says the right thing about that ("must not replace or weaken a gate"), and the honest framing is that this is documentation accepting documentation's failure mode knowingly — not a mechanism. Nothing to change; worth having said once.

Scope

Not graded: whether the lockstep set actually has exactly these three members. The section explicitly declines to claim that, so there is nothing there to check — which is the correct shape for the claim it is making.

Required set: 0 not-green of 26.

APPROVED at `84d2993d`. **Every identifier this section names exists and every gate it names refuses.** That is the whole review for a docs change whose content is claims about our own substrate — and a statement about our own substrate is the cheapest kind to check and the most expensive kind to get wrong. ``` cmd/rt/testdata/help.txt EXISTS, 49 lines cmd/rt/main_test.go EXISTS, 419 lines c5ExcludedVerbs 13 occurrences in main_test.go TestHelpSnapshot main_test.go:32 PASS TestSubcommandsMatchC5Contract main_test.go:271 PASS TestC5ExclusionsAreDocumented main_test.go:374 PASS ``` **Passing is not refusing, so I mutated the one that carries the claim:** injected a verb into `help.txt` without touching the tree. ``` snapshot mutated -> rc=1, 1 red restored -> rc=0 ``` `TestHelpSnapshot` genuinely refuses drift. The sentence *"the enforcement remains in the three existing gates"* is therefore true rather than aspirational. ## The paragraph I would have flagged is the one that already flags itself > *"This is a general shape, not a member or triple inventory... Do not assume that a count is derived from the population or that this paragraph enumerates every representation."* **A map that names three artifacts invites exactly the reading that three is the list**, and a contributor who checks all three feels finished. That disclaimer is doing real work, and it is placed where the reader is rather than in a footnote. ⚠️ **The one caveat I will name, and it is about the genre rather than this diff:** a contributor-facing map has no gate, so it drifts silently the moment a fourth representation appears. The section says the right thing about that (*"must not replace or weaken a gate"*), and the honest framing is that this is documentation accepting documentation's failure mode knowingly — not a mechanism. Nothing to change; worth having said once. ## Scope Not graded: whether the lockstep set actually has exactly these three members. The section explicitly declines to claim that, so there is nothing there to check — which is the correct shape for the claim it is making. **Required set: 0 not-green of 26.**

bosun merged commit 9a54ed9abd into main 2026-09-05 23:23:42 +02:00

bosun deleted branch sentry/1196-lockstep-set 2026-09-05 23:23:42 +02:00

Sign in to join this conversation.

Reviewers

No reviewers

surveyor

Labels

Clear labels   

bump

major

Override the cut bump to MAJOR (release-toolkit#107)

  

bump

minor

Override the cut bump to MINOR (release-toolkit#107)

  

bump

patch

Override the cut bump to PATCH (release-toolkit#107)

  

kind/bug

Something is broken

  

kind/chore

Maintenance, tooling, refactor

  

kind/docs

Documentation work

  

kind/feature

New feature or capability

  

priority/critical

Critical: must be addressed immediately

  

priority/high

Important, should be addressed soon

  

priority/low

Low priority, address when convenient

  

priority/medium

Normal priority

  

size/L

Large: significant feature, ~6-16h

  

size/M

Medium: moderate feature, ~2-6h

  

size/S

Small: simple change, ~1-2h

  

size/XL

Extra large: major feature or refactor, 16h+

No labels

bump

major

bump

minor

bump

patch

kind/bug

kind/chore

kind/docs

kind/feature

priority/critical

priority/high

priority/low

priority/medium

size/L

size/M

size/S

size/XL

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

frankenbit/release-toolkit!1216

No description provided.