docs(os-dev): the skip-changeset clause states its criterion as the rule and its list as examples; dispatch-gates prints the same criterion (#13680)

[os-litant]

Fixes #13680

What changed

The os-dev skip-changeset clause stated a criterion ("publishes nothing from any package") beside a CLOSED surface list that omitted shapes the criterion covers — repo-root tooling config and the private example workspaces — so the two readings disagreed and every PR of those shapes cost an escalation. One sentence now settles it: the criterion is the rule; the list is illustrative. The two shapes that raised the card appear as EXAMPLES, never as list membership, and the list did not grow into a longer closed list. scripts/pm/dispatch-gates.mjs prints the same criterion in its pending-changeset heading and its self-test pins the new sentence exactly. The skip-changeset label description already stated the criterion; it is quoted below as the third text and not edited.

The three texts, side by side

1. .claude/agents/os-dev.md — the clause (the 13-line bullet at lines 328-340; the criterion/list sentence is its first three lines)

Before:

判据:不从任何包发布东西;闭合清单:仅含 docs/adr/** · .claude/** · scripts/pm/** · tests/workflow · 注释 的 diff。

After:

判据是规则:不从任何包发布东西;清单仅为示例(docs/adr/** · .claude/** · scripts/pm/** · 仓根工具配置 · examples/** 等私有 workspace · tests/workflow · 注释)。

2. scripts/pm/dispatch-gates.mjs:7551 — the printed heading, and its self-test at :15280

Before: Once a changeset exists, N more famil(ies) apply — write one unless this card is docs-only:

After: Once a changeset exists, N more famil(ies) apply — write one unless this card publishes nothing from any released package (then the skip-changeset label instead, per the os-dev clause):

The self-test case is renamed from "carries the docs-only escape" to "carries the publishes-nothing escape, stated as the os-dev clause states it"; its regex pins the new sentence exactly, and the 2 more famil(ies) count half of the assertion is kept. docs-only no longer occurs anywhere in the file (grep: 0). Nothing else in the file is touched — PR #14303 edits the tier-constant region and its self-tests, which are disjoint from these two lines.

3. The skip-changeset label description (read with the GitHub MCP get_label; unchanged, not editable from a dev seat)

PR has no user-facing published change; bypasses the changeset gate

All three now state one rule: a diff that publishes nothing from any released package takes the label, not a changeset.

Precedent — verified on GitHub, not copied from the card

Read from the zero-quota PR pages (/pull/N, /pull/N/files, /pull/N/checks): labels from data-name, files from the files page, Check Changeset conclusions from each check item's aria-label. REST is 403 for this session, so no REST reading is cited.

PR	files in the diff	labels	.changeset/*.md in the diff	state	Check Changeset on the head
#12332	eslint.config.mjs	size/s, skip-changeset	0	merged	succeeded (run 32885771857, the settling read); skipped on the later run 32885811681 (label present at event time)
#13679	eslint.config.mjs	size/s, skip-changeset	0	merged	succeeded (run 33363659498); skipped on run 33363667455
#14090	examples/app-showcase/src/data/seed/index.ts	size/xs, skip-changeset	0	merged	succeeded (run 33469880920); skipped on run 33469922857
#14449	examples/app-showcase/src/data/objects/field-zoo.object.ts, packages/qa/dogfood/test/temporal-storage-e2e.dogfood.test.ts	size/s, size/xs, skip-changeset, tests	0	merged	skipped (run 33605811739; label present at event time on every run)

The same file (root eslint.config.mjs) landed twice with the label and zero changesets, and examples/** twice; the gate accepted all four.

The decisive fact

scripts/check-empty-changeset.mjs REJECTS a newly added empty-frontmatter changeset (its --self-test and its scan of this branch both ran in the union below). So for a diff that names no package there is no honest changeset form at all — the only writable one names a package whose code did not change and emits a release-note row for it. The gate's own prescription already enumerates the releases-nothing shapes illustratively and routes them to the label (source, lines 357-359):

It releases nothing (.github/, .claude/, skills/, docs/, content/, examples/, tests-only, and the like) -> delete the changeset and apply the 'skip-changeset' label (route 2). The label is a gate-level exemption: it produces NO input for changesets/action.

A literal reading of the closed list asked for something this gate forbids; the clause now says what the gate, the label description and the merged precedent already said.

Line delta on os-dev.md — line-neutral under the ratchet

• Ratchet before the edit: ✓ check-skill-line-ratchet: .claude/agents/os-dev.md is 469 lines (ceiling 469; headroom 0). and widest table row is 0 bytes (pin 0; headroom 0).
• Ratchet after the edit (and again in the union on b22110ad): the same two lines, verbatim.
• Content accounting inside the one clause: the new sentence is +59 bytes; paid by deleting 74 bytes inside the same clause — the reachability aside's contrast 「、不是端点或席位的」 and its two measurement details 「门先于端点应答、」 and 「,门开会话实测 200」. What stays: 「⚠️ 可达性是会话属性(读写同拒;读数住 platform-readings)⇒ 先探后用」 — the rule, the reads-and-writes-alike fact, and the pointer to platform-readings, where the deleted readings live. Net −15 bytes; the 13-line bullet reflows to 13 lines. No re-wrap anywhere outside the clause, no ceiling change, scripts/pm/check-skill-line-ratchet.mjs untouched.

skip-changeset on this PR

Two files, .claude/agents/os-dev.md and scripts/pm/dispatch-gates.mjs, under .claude/ and scripts/pm/ — both inside check-empty-changeset's own releases-nothing enumeration; no package is published. The label is applied at open by MCP union-write with a compare read-back (REST is 403 for this session); the read-back is quoted in the report comment on the card.

Scope items and PM mechanism assumptions, measured

1. check:pm-skill-ratchet prices os-dev.md at ceiling 469 with a widest-table-row pin of 0 — true; verdict lines above.
2. premise_false: check:pm-skill-id-lint scans os-dev.md for section ids — it is an issue-number-citation lint (pattern /#[0-9]{3,}/ over the PM skill files, os-dev.md and AGENTS.md), not a section-id scan; the clause carries no citation; green before and after.
3. check:pm-dispatch-gates (the self-test battery) ran green on b22110ad under the lock; check:skill-frame-sync green in the derived family and check:skill-frame-freshness green as an extra — the frame gates extract the decision-frame sentence, and this diff is outside it.
4. node scripts/check-empty-changeset.mjs --self-test and its scan of this branch (--base origin/main) both green as extras; enumeration quoted above.
5. Family re-derived after the merge on b22110ad (node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands, change set 2 paths vs merge base 2514d49f) — unchanged from the pre-merge derivation; the whole list ran under scripts/pm/os-verify-lock.sh with OS_VERIFY_LOCK_SLOT=issue-13680 (lock verdict: command-exit 0 · held the lock 391s · waited 284s).
6. AGENTS.md: 0 occurrences of skip-changeset; it carries neither the closed list nor a competing rule for the label. Untouched. See follow-up for the adjacent changeset rule at 1116-1117.
7. .claude/skills/pm-dispatch/**, skills/**, the ratchet script: untouched. origin/main moved five commits during the run and was merged in (2514d49f); the incoming delta touched neither edited file.

Gates — head b22110ad, each gate's own verdict line, exit codes captured before any pipe

gate (as derived / extra)	exit	status	its own verdict line
node scripts/check-ci-filter-parity.mjs	0	green	OK: all 130 declared cross-package glob(s) (92 unique) are covered by core or crosspkg, every crosspkg entry still covers one, and the test job's if: still names both filters.
node scripts/check-cross-package-test-inputs.mjs	0	green	OK: 25 package(s) read outside themselves, all declared, and turbo.json hashes every declared glob.
node scripts/check-self-test-wired.mjs	0	green	✓ check-self-test-wired: every one of the 164 script(s) CI runs that ship a --self-test has that self-test run by CI.
node scripts/check-shard-attestation.mjs	0	green	✓ check-shard-attestation: 2 aggregate gate(s) count 3 declared leg(s) across 3 attesting job(s).
node scripts/check-test-completeness.mjs	3	NOT MEASURED	Fix: pass a saved turbo run test log — or, running the family locally, record this gate as NOT MEASURED.
pnpm --filter @objectstack/lint run check:doc-formula-expressions	3	NOT MEASURED	Exit status 3
pnpm check:agent-model-declared	0	green	✓ check-agent-model-declared: 1 agent definition(s) under .claude/agents/ all declare a model
pnpm check:agent-test-spelling	0	green	✓ check-agent-test-spelling: 0 violations — 428 file(s) · 5633 bare -- token(s) · 1380 launcher-rooted run(s) · 9 separator(s) JUDGED · 5 vitest-backed script name(s) derived from 81 manifest(s)
pnpm check:bash32-floor	0	green	✓ check-bash32-floor: 26 tracked shell file(s) under scripts/, .claude/hooks/, .githooks/** name no bash 4+ construct outside a comment, a guarded ${VAR:-} read, or a non-command position.
pnpm check:cli-command-ids	0	green	✓ check-cli-command-ids: 315 command-id literal(s) across 112 file(s) outside packages/cli all resolve to a real command path (73 ids derived; 3 declared fixture exemptions, 0 baselined violation(s) listed above).
pnpm check:cross-package-test-inputs	0	green	OK: 25 package(s) read outside themselves, all declared, and turbo.json hashes every declared glob.
pnpm check:declared-population-live	0	green	✓ check:declared-population-live — 158 of 202 famil(ies) declare a path population, and every one of them reaches this tree's 7989 tracked file(s).
pnpm check:doc-authoring	0	green	✓ doc authoring guard: sibling-package prose ids hold the baseline — 831 pinned site(s) across 231 file(s), 82730 string(s) read in 1124 parsed source(s), no growth, no burn-down unrecorded.
pnpm check:entry-guard	0	green	✓ check:entry-guard: 199 scripts/ file(s) — every entry guard goes through invoked-as.mjs; 150 export bindings, 148 of them inert on import (2 known-unsafe, ⛔ SHRINK-ONLY).
pnpm check:nul-bytes	0	green	check-nul-bytes: OK (scanned 7982 text file(s) -- 7982 tracked, 0 untracked-not-ignored; skipped 7 binary; no raw ASCII control bytes).
pnpm check:parse-guard	0	green	✓ check:parse-guard: 198 scripts/ file(s) — every TypeScript parse goes through ts-parse.mjs.
pnpm check:pm-governed-merges	0	green	✓ check-governed-merges --self-test: 243 assertions (the unified governed predicate + near misses, subject→PR spellings, window parsing, the #12633 landing window — the QS-7 regression pin in both directions, the topolog
pnpm check:pm-skill-id-lint	0	green	✓ check-skill-id-lint: 23 file(s) clean (pattern /#[0-9]{3,}/g).
pnpm check:pm-skill-ratchet	0	green	✓ check-skill-line-ratchet: CLAUDE.md is 86 lines (ceiling 86; headroom 0).
pnpm check:pnpm-filter-targets	0	green	✓ check:pnpm-filter-targets: 142/181 --filter occurrence(s) across 32 file(s) resolve against 79 workspace package(s); 39 not judged (2 foreign, 17 interpolated, 20 path); 46 more in comments or step labels and 59 in t
pnpm check:skill-frame-sync	0	green	✓ check-skill-frame-sync: 4 copies of the decision frame are structurally isomorphic across 3 files
pnpm check:watch-hint-literal	0	green	✓ check-watch-hint-literal: 45 declaration(s) across 4 rostered name(s) -- ROOT_DIR_WATCH_HINTS 29, ROOT_FILE_WATCH_HINTS 9, ROOT_WATCH_HINTS 2, DECLARED_WATCH_HINTS 5 -- every one an array of quoted literals inside its
pnpm check:skill-frame-freshness	0	green	✓ check-skill-frame-freshness: the decision frame in this tree is current with origin/main (fetched just now).
node scripts/check-empty-changeset.mjs --self-test	0	green	✓ check-empty-changeset --self-test: 118 assertions over real temp git repos (real scan() path)
node scripts/check-empty-changeset.mjs --base origin/main	0	green	✓ No empty-frontmatter changeset introduced by this diff (0 declaring changeset(s) added).
pnpm check:pm-dispatch-gates	0	green	✓ dispatch-gates self-test: 1240 cases pass.

NOT MEASURED (exit 3 = prerequisite not met, not a red)

• node scripts/check-test-completeness.mjs — exit 3; prerequisite: check-test-completeness: PREREQUISITE NOT MET — this gate grades a saved turbo run test log, and no log was named.
• pnpm --filter @objectstack/lint run check:doc-formula-expressions — exit 3; prerequisite: check-doc-formula-expressions: PREREQUISITE NOT MET — the workspace package @objectstack/formula is not built

Follow-up (out of scope here, untouched)

• AGENTS.md:1116-1117 — "Pure bug fixes do not require a changeset." — conflicts with the Check Changeset job (pr-automation.yml, step Count the changesets this PR adds: zero added and no label ⇒ red after the settling window) and with the criterion (a bug fix in a released package publishes something, so the label is not its exemption either). A pure bug fix PR following that sentence literally has no green path. Dedupe: a repo-scoped search_issues (56 results, non-empty) returned no card for this; not filed by this seat under the checkpoint (landing only) — listed here for the PM to file unassigned.
• [finding] The os-dev contract states skip-changeset as BOTH a closed path list and a publication test — a src/ file that never reaches dist satisfies one and violates the other #13432 remains open (on hold): the src/-file-that-never-reaches-dist shape is the same closed-list-vs-criterion tension from another angle; with the criterion now the rule, that card's remaining question is only how a seat measures "publishes nothing" for such a file.

Governed surface (.claude/**, scripts/pm/**) ⇒ this PR stays draft; landing is the maintainer's, by hand.

🤖 Generated with Claude Code

Generated by Claude Code

---

Generated by Claude Code