docs(devx): SELF_TEST_MODES argues the seventh control family into gated, where the self-test body points (#15766)

[claude]

Fixes #15766

SELF_TEST_MODES's doc block is this file's declared rationale for which control
families each --self-test mode asserts. It carried a dedicated section for each
family that joined gated after the original three, but never one for
WORKLIST_READING_CONTROLS (#15503) — the family the self-test body sends the
reader to that very block to ask about. The argument was not missing from the
file, only from the place readers are pointed at.

Comments only. No behaviour change.

The three anchors, read on this branch's base (fa8575996)

The card cites line numbers from its own base (66e68adc6); the usage header that
landed as PR #15764 shifted them by 22 lines. Quoted from the base of this branch:

scripts/measure-durability-swallow-family.mjs:1004   * ## The FIFTH family (#13886) is in BOTH modes, and that is the point
scripts/measure-durability-swallow-family.mjs:1022   * ## The COPIED gate vocabulary (#15459) is in both modes, for the same reason

The argument this section CARRIES rather than invents, at the declaration's own
doc (:655-658, the card's :636-638):

scripts/measure-durability-swallow-family.mjs:655   * Asserted in BOTH self-test modes, by the test `SELF_TEST_MODES` states: can a
scripts/measure-durability-swallow-family.mjs:656   * successful repair destroy it? No — the empty worklist it pins is the state
scripts/measure-durability-swallow-family.mjs:657   * the repair programme is trying to reach, so the day this family matters most
scripts/measure-durability-swallow-family.mjs:658   * is the day the programme succeeds.

And the pointer that had nowhere to land, in the self-test body (:2085-2091,
the card's :2065-2068):

scripts/measure-durability-swallow-family.mjs:2087   // See WORKLIST_READING_CONTROLS for why these readings are exercised against
scripts/measure-durability-swallow-family.mjs:2088   // a declared population rather than against the tree — two of the three
scripts/measure-durability-swallow-family.mjs:2089   // cannot be reached from `packages/**` today — and SELF_TEST_MODES for why
scripts/measure-durability-swallow-family.mjs:2090   // this family is gated: it compares a producer against a declared population
scripts/measure-durability-swallow-family.mjs:2091   // and never touches membership, so no repair can destroy it.

What was added

Twenty comment lines at the end of the SELF_TEST_MODES block, after the COPIED
gate-vocabulary section, in that section's pattern:

 * ## The WORKLIST READINGS (#15503) are in both modes, for the same reason
 *
 * `WORKLIST_READING_CONTROLS` pins what the tier-1 worklist PRINTS, and the
 * `--self-test` exercises those readings against a DECLARED population rather
 * than against this tree: neither `(none …)` line has ever been printed by a run
 * of this instrument, and an unreachable reading is a reading nobody proofreads.
 * That does not weaken its claim to `gated`, it is the claim. The family passes
 * the test the two sections above apply, and its own declaration states the
 * answer in those words: can a successful repair destroy it? "No — the empty
 * worklist it pins is the state the repair programme is trying to reach", so the
 * day this family matters most is the day the programme succeeds. The self-test
 * body says the mechanical half: it "compares a producer against a declared
 * population and never touches membership", so no repair can destroy it.
 *
 * ⛔ That is the pattern and not a courtesy: A FAMILY THAT JOINS `gated` OWES A
 * SECTION HERE, arguing on those terms why a successful repair cannot destroy
 * it. This block is where the self-test body sends a reader asking that
 * question, and a pointer landing on a block that names every family but the one
 * asked about is how the next author learns the obligation is optional.

Two authorship choices worth naming for review:

• The heading NAMES the family instead of numbering it. The ruling calls it
  the seventh family; the header that landed as PR docs(devx): measure-durability-swallow-family's usage header names its seven control families and the six gated runs (#15754) #15764 moved this file off
  ordinals precisely so "the next one added contradicts a LIST and not an
  integer". The COPIED section is already in the named form, so the named form is
  both the newer pattern and the one that cannot go stale when a family is
  inserted ahead of this one. No count is restated as an integer anywhere in the
  addition.
• The pattern sentence is stated once, as the section's closing paragraph —
  the last thing a reader of the block sees, and the thing the card says is the
  real loss: not a paragraph, but an eroding convention.

Verification

Comments-only proof. Every added or removed line that is not a comment:

git diff -U0 origin/main -- scripts/measure-durability-swallow-family.mjs \
  | grep -E '^[-+]' | grep -vE '^(\+\+\+|---)' | grep -vE '^[-+]\s*(//|\*|/\*)'

prints nothing — zero lines. git diff --stat origin/main is
1 file changed, 20 insertions(+), and all twenty begin with *.

Syntax. node --check scripts/measure-durability-swallow-family.mjs → EXIT=0.

Both self-test modes were run for real, not skipped: typescript was made
available in the worktree, so the modes the card is about actually executed. Run
through scripts/pm/os-verify-lock.sh, whose verdict lines read
VERDICT command-exit 0 for each:

✓ measure-durability-swallow-family self-test, gated families (#13919): 3 negative control(s) yield none,
  2 regression control(s) stay clear, 6 resolution control(s) resolve as declared, 3 DETERMINED register
  row(s) cross-check clean, 20 copied gate-vocabulary name(s) match the gate's own declaration,
  3 worklist reading(s) print as declared over a fixture population, 56 member site(s) total

✓ measure-durability-swallow-family self-test: 4 positive control(s) yield members at their declared tier,
  3 negative control(s) yield none, 2 regression control(s) stay clear, 6 resolution control(s) resolve as
  declared, 3 DETERMINED register row(s) cross-check clean, 20 copied gate-vocabulary name(s) match the
  gate's own declaration, 3 worklist reading(s) print as declared over a fixture population,
  56 member site(s) total

Gate families, derived rather than guessed —
node scripts/pm/dispatch-gates.mjs --changed --commands --repo objectstack-ai/objectstack
(EXIT=0, change set of 1 path vs merge base fa8575996) named 29 commands.
All 29 were run and all 29 pass (pnpm check:pm-dispatch-gates needed a 900s budget for its
✓ dispatch-gates self-test: 1478 cases pass. — a 300s cap killed it once, which is a
harness limit and not a gate reading). Four of them first reported PREREQUISITE NOT MET
(exit 3, yaml) or ERR_MODULE_NOT_FOUND (@typescript-eslint/parser) in a
worktree with no install; those two packages were made resolvable and the four
re-run to a real green rather than left as an unmeasured hole:

node scripts/check-ci-filter-parity.mjs               EXIT=0
node scripts/check-closing-keyword-parity.mjs         EXIT=0
node scripts/check-closing-keyword-parity.mjs --self-test  EXIT=0
node scripts/check-comment-mask-corpus.mjs            EXIT=0

pnpm check:nul-bytes → EXIT=0, plus a manual scan of the file for
control characters outside tab/newline — no hits.
node scripts/pm/check-governed-merges.mjs --test scripts/measure-durability-swallow-family.mjs
prints ✅ NOT governed — ordinary queue landing applies to a PR with exactly this file list.

NOT MEASURED, by name. Three families the derivation itself marks unmeasurable
outside a CI run, because their argv takes a value from the workflow:

⊘ NOT MEASURED — scripts/check-cross-package-test-inputs.mjs --union-into "$RUNNER_TEMP/turbo-ls.json" --changed "$RUNNER_TEMP/changed-files.txt"
⊘ NOT MEASURED — scripts/check-shard-attestation.mjs --emit --job test --shard MATRIX.SHARD (a workflow expression, spelled as a placeholder here) --total 6 --out "$RUNNER_TEMP/shard-attestation"
⊘ NOT MEASURED — scripts/check-test-completeness.mjs "$RUNNER_TEMP/test-core.log" --scheduled "$RUNNER_TEMP/shard-packages.txt" --package-list "$RUNNER_TEMP/turbo-ls.json"

Also not measured here and left to CI: the always-runs tail with no path filter,
the repo-wide pnpm lint scan, the 10 families whose declared population is too
wide for any subtree glob to place, and the 38 artifact rosters whose silent
verdict is a fact about a list rather than about these paths.

Changeset

skip-changeset, applied to this PR. AGENTS.md: a changeset is owed for
"anything that publishes", and ⛔ never skip-changeset except for "a diff that
publishes nothing from any released package". This diff is twenty comment lines in
a repo-internal instrument under scripts/, which lint.yml calls out as exactly
that case: "this PR edits a CI-internal script" is "the textbook skip-changeset
case — such a PR releases nothing".

🤖 Generated with Claude Code

https://claude.ai/code/session_012zGPuVVX3deAx9LdjK8jCk

---

Generated by Claude Code

[claude]

ACCEPT — PR #15808 (head 519862b13, scripts/measure-durability-swallow-family.mjs +20/−0) reviewed against the GitHub three-dot diff, not the report.

Comments only (non-comment diff 0 lines; all 20 added lines begin *): the SELF_TEST_MODES doc block gains ## The WORKLIST READINGS (#15503) are in both modes, for the same reason in the fifth/sixth pattern, carrying the declaration's own argument and the self-test body's sentence, so the pointer at the gated-families comment now resolves to a section naming the family; the pattern is stated once; no integer count restated — the heading names the family rather than numbering it, which is the right reading of the ruling (PR #15764 moved this file off ordinals for exactly that reason). Anchors quoted from the dev's base at their shifted lines (+22 after #15764).

Measured by this seat: non-comment diff empty; node --check → EXIT=0; git merge-tree --write-tree origin/main <branch> → EXIT=0; governed test per the report NOT governed. NOT MEASURED here: both self-test modes (the dev made typescript resolvable and ran them under the lock — VERDICT command-exit 0, gated names six families, bare names seven — the record).

Flip + arm when both required jobs report success on 519862b13. On landing #15766 closes and measure-durability-swallow-family.mjs:259 (the fenced typescript import) goes to #15783's follow-up.

---

Generated by Claude Code

[claude]

Flipped ready + auto-merge enabled (09:12Z, method: MERGE). Required jobs on 519862b13: Lint & Repo Gates = success, TypeScript Type Check = success; git merge-tree --write-tree origin/main <branch> → EXIT=0 against the current main. Watched; on landing #15766 closes.

---

Generated by Claude Code