feat(scripts): guard a package's published contract fields, not only its source

[claude]

Fixes#6736

scripts/check-changeset-presence.mjs derived its guarded surface from paths alone, so a change to a released package's published contract — sideEffects, exports/main/module/types, files, peerDependencies/engines — was owed no declaration. The live instance is PR #6735, which gave @object-ui/app-shell a sideEffects ARRAY and got the gate's own No source of a released package changed in this range, so no changeset is owed. The changeset in that PR was there because its author decided it was owed.

The false-positive measurement — the ruling's precondition

Triage made measuring the false-positive population a condition of the change, on #11457 discipline: "一个被绕过的门禁比没有门禁更糟,因为它还占着「已覆盖」的名分". Method: extract the pre-change gate from origin/main, import both versions, and run analyze + verdict over each merged commit on origin/main as sha^..sha (these are squash merges, so that range is the PR's diff).

	last 200 merged PRs	last 500 merged PRs
moved a guarded contract field at all	3	4
NEWLY RED under the widened criterion	0	0
flipped red to green (must be 0)	0	0
unreadable	0	0

Zero false positives. All three field moves in the 200-PR window already carried a changeset:

green f99932a42 feat(app-shell): render `global:search` and `global:notifications` … (#6838)
@object-ui/app-shell: sideEffects (changesets added: 1)
green faac0d935 feat(app-shell): the precise `sideEffects` array … (#6735)
@object-ui/app-shell: sideEffects (changesets added: 1)
green 3e028c8d8 refactor(types,app-shell,plugin-designer): one tombstone registry … (#6627)
@object-ui/types: exports (changesets added: 1)

The two named exclusions, measured against real history rather than fixtures

The card names two changes that must NOT demand a declaration. Both were run through the old gate, the new gate, and a file-level counterfactual ("any edit to a released package's package.json"):

commit	released package.json edited	guarded fields moved	changesets added	old	new (field-level)	counterfactual (file-level)
59f61cfb8chore: release packages (#4655) — what changeset version writes	40	0	0	0	0	1
590dd6356chore(deps-dev): bump the dev-dependencies group … 11 updates (#4948) — Dependabot	9	0	0	0	0	1

This is the whole argument for reading FIELDS rather than the file. A release commit rewrites 40 manifests and adds no changeset — it empties.changeset/. A file-level gate would go red on the very commit that answers it, and red on every Dependabot bump. Neither exclusion is a branch in the code: they hold because the reading is an allowlist of eight fields and version/devDependencies are not in it. There is no bot identity to sniff and no commit message to parse.

Is the new green on the live instance earned, or vacuous?

The old gate passed #6735 while having looked at nothing, so "still green" is not evidence. Ablating the declarations from the analysis separates the two:

OLD, as merged : exit 0 (guarded source files: 0)
OLD, declarations ablated : exit 0 <== green either way; the old gate never looked
NEW, as merged : exit 0 (guarded source: 0, contract: 1, declarations: 1)
NEW, declarations ablated : exit 1 <== RED; the green is earned by the declaration

What changed

A second question asked of the manifest, not a fourth clause in the population.isPublishedSource stays path-only and still answers false for package.json — pinned. A new contractChanges reads both sides of the diff out of git, parses them, and compares the eight guarded fields by value.

• Values, not bytes, not mtime. Re-indenting a manifest or moving version above name is green. Comparison is order-preserving serialisation, which is correct rather than convenient: exports condition order is resolution order in Node, so a reorder that moves no key and no value is a behaviour change and goes red.
• One normalisation for files, shared with clause (c).publishedEntries is what clause (c) compares changed paths against, and it is now what the field diff compares too. Without that the gate could demand a declaration for a files respelling (dist to dist/) that its own clause (c) reports as changing nothing shipped — code contradicting itself inside one run.
• Failures name the FIELD. "your package.json changed" is also true of a version bump this gate passes, so a red without the field name sends the author looking for a change the gate did not object to.
• Unclassified and ignored packages route the same way as source, so the two classifications compose into one verdict.
• Loud on every missing input, in the established direction: an unparseable manifest on either side is a red build, never a quiet pass.

The docblock said this exclusion was deliberate — reconciled, not overwritten

The card frames the gap as an omission. It is not: line 137 stated it as a boundary — "package.json itself never counts. Clause (c) reads that file; it does not match it. A dependency bump can be just as user-visible, and this gate still does not see it. That was the first draft's trade and it is kept."

Read against the code, that is a scoping trade against noise, not a mechanism-level obstacle — the same population discipline the header states two paragraphs earlier ("too wide and every incidental file in a package directory demands a declaration … which is how a gate stops being read at all"). A field-level reading is the resolution of exactly that trade rather than its reversal, so this is not a fork.

The bullet is rewritten, and the part of the trade that is kept is now stated as kept: dependencies stays out, and a runtime dependency bump is still invisible to this gate. Nobody should read "the manifest is guarded now" off this change.

Tests

scripts/__tests__/check-changeset-presence.test.ts gains section 2c — 14 cases, both directions:

• POSITIVE: a sideEffects array with no changeset goes red naming the file and the field; the same change with a changeset is green because of the declaration.
• Each of the eight fields goes red on its own (one fixture per field — a single combined case passes as long as any one field is read, which is how a half-wired allowlist stays green), with an assertion that the case table and CONTRACT_FIELDS are the same set, so a field with no case cannot exist.
• Both named exclusions: a version-only bump and a devDependencies-only bump are green.
• Unguarded fields (scripts, dependencies, publishConfig, description) moving together: green. Reformatting: green. Root manifest: green. files respelling: green. exports condition reorder: red.
• Ignored package: skipped, not demanded. Unparseable manifest: loud.
• CONTRACT_FIELDS is pinned as a list, which is what makes the ruling mechanical: adding or dropping a field cannot happen without a deliberate edit here.

Verification

All on the final commit 354653832.

whole scripts/__tests__ tree 89 test files, 2516 tests, all passed (89 on disk, 89 run)
lint:root (full population) exit 0 — 219 files, 0 errors, 29 pre-existing warnings, none in this diff
type-check:scripts exit 0
check:control-bytes exit 0 — 5804 tracked text files
check:entry-guard exit 0 — 56 scripts/ files, ratchets unmoved
check:node-esm-load exit 0
check:shell-escape-residue exit 0 — 4/4 roots resolved
check:upstream-port-parity exit 0
check:governed-queue-guard exit 0 — 132 cases
check-type-check-coverage exit 0
check-lint-coverage exit 0 — 46/46 packages
check-changeset-fixed exit 0
the gate on its own diff exit 0 — no changeset owed (scripts/ is no package's source)

Ablation — replacing contract: contract.guarded with contract: [] in analyze, with the mutation confirmed on disk (anchor 1 to 0, marker 0 to 1, blob hash moved) before reading any result: 4 failed / 49 passed, and the four are the positive legs. The restore leg was confirmed the same way — git checkout HEAD -- on an absolute path, then blob hash equal to HEAD, marker gone, anchor back, git diff HEAD empty.

No changeset: this diff touches scripts/ only, which is no package's published source. The skip-changeset label is deliberately not applied — in this repository that label object exists from a historical mis-attachment, is read by no workflow, and exempts nothing.

Filed, not fixed here

Two pre-existing findings, both measured on origin/main at 4357ec754 and both outside this card's declared file surface:

• finding(docs): AGENTS.md states the changeset rule as src/ only — already narrower than the gate since #5733, and narrower again after #6736 #6997 — AGENTS.md line 161 states the changeset rule as src/ only. Already narrower than the gate since objectui#5733, and narrower again after this PR. Agent-facing text, so a rule stated too narrowly is paid by every reader.
• finding(scripts): js-comment-mask.mjs cites two line numbers as evidence and both point at the wrong line (86 and 107 lines off) #6998 — js-comment-mask.mjs cites two line numbers as evidence for a live mutation-blind shape, and both point at the wrong line (86 and 107 off). This PR moves one of the two targets further, which is the point: a line number into another file has nothing keeping it true.

Generated by Claude Code

---

Generated by Claude Code

[claude]

Fixes#6736

scripts/check-changeset-presence.mjs derived its guarded surface from paths alone, so a change to a released package's published contract — sideEffects, exports/main/module/types, files, peerDependencies/engines — was owed no declaration. The live instance is PR #6735, which gave @object-ui/app-shell a sideEffects ARRAY and got the gate's own No source of a released package changed in this range, so no changeset is owed. The changeset in that PR was there because its author decided it was owed.

The false-positive measurement — the ruling's precondition

Triage made measuring the false-positive population a condition of the change, on #11457 discipline: "一个被绕过的门禁比没有门禁更糟,因为它还占着「已覆盖」的名分". Method: extract the pre-change gate from origin/main, import both versions, and run analyze + verdict over each merged commit on origin/main as sha^..sha (these are squash merges, so that range is the PR's diff).

	last 200 merged PRs	last 500 merged PRs
moved a guarded contract field at all	3	4
NEWLY RED under the widened criterion	0	0
flipped red to green (must be 0)	0	0
unreadable	0	0

Zero false positives. All three field moves in the 200-PR window already carried a changeset:

green f99932a42 feat(app-shell): render `global:search` and `global:notifications` … (#6838)
@object-ui/app-shell: sideEffects (changesets added: 1)
green faac0d935 feat(app-shell): the precise `sideEffects` array … (#6735)
@object-ui/app-shell: sideEffects (changesets added: 1)
green 3e028c8d8 refactor(types,app-shell,plugin-designer): one tombstone registry … (#6627)
@object-ui/types: exports (changesets added: 1)

The two named exclusions, measured against real history rather than fixtures

The card names two changes that must NOT demand a declaration. Both were run through the old gate, the new gate, and a file-level counterfactual ("any edit to a released package's package.json"):

commit	released package.json edited	guarded fields moved	changesets added	old	new (field-level)	counterfactual (file-level)
59f61cfb8chore: release packages (#4655) — what changeset version writes	40	0	0	0	0	1
590dd6356chore(deps-dev): bump the dev-dependencies group … 11 updates (#4948) — Dependabot	9	0	0	0	0	1

This is the whole argument for reading FIELDS rather than the file. A release commit rewrites 40 manifests and adds no changeset — it empties.changeset/. A file-level gate would go red on the very commit that answers it, and red on every Dependabot bump. Neither exclusion is a branch in the code: they hold because the reading is an allowlist of eight fields and version/devDependencies are not in it. There is no bot identity to sniff and no commit message to parse.

Is the new green on the live instance earned, or vacuous?

The old gate passed #6735 while having looked at nothing, so "still green" is not evidence. Ablating the declarations from the analysis separates the two:

OLD, as merged : exit 0 (guarded source files: 0)
OLD, declarations ablated : exit 0 <== green either way; the old gate never looked
NEW, as merged : exit 0 (guarded source: 0, contract: 1, declarations: 1)
NEW, declarations ablated : exit 1 <== RED; the green is earned by the declaration

What changed

A second question asked of the manifest, not a fourth clause in the population.isPublishedSource stays path-only and still answers false for package.json — pinned. A new contractChanges reads both sides of the diff out of git, parses them, and compares the eight guarded fields by value.

• Values, not bytes, not mtime. Re-indenting a manifest or moving version above name is green. Comparison is order-preserving serialisation, which is correct rather than convenient: exports condition order is resolution order in Node, so a reorder that moves no key and no value is a behaviour change and goes red.
• One normalisation for files, shared with clause (c).publishedEntries is what clause (c) compares changed paths against, and it is now what the field diff compares too. Without that the gate could demand a declaration for a files respelling (dist to dist/) that its own clause (c) reports as changing nothing shipped — code contradicting itself inside one run.
• Failures name the FIELD. "your package.json changed" is also true of a version bump this gate passes, so a red without the field name sends the author looking for a change the gate did not object to.
• Unclassified and ignored packages route the same way as source, so the two classifications compose into one verdict.
• Loud on every missing input, in the established direction: an unparseable manifest on either side is a red build, never a quiet pass.

The docblock said this exclusion was deliberate — reconciled, not overwritten

The card frames the gap as an omission. It is not: line 137 stated it as a boundary — "package.json itself never counts. Clause (c) reads that file; it does not match it. A dependency bump can be just as user-visible, and this gate still does not see it. That was the first draft's trade and it is kept."

Read against the code, that is a scoping trade against noise, not a mechanism-level obstacle — the same population discipline the header states two paragraphs earlier ("too wide and every incidental file in a package directory demands a declaration … which is how a gate stops being read at all"). A field-level reading is the resolution of exactly that trade rather than its reversal, so this is not a fork.

The bullet is rewritten, and the part of the trade that is kept is now stated as kept: dependencies stays out, and a runtime dependency bump is still invisible to this gate. Nobody should read "the manifest is guarded now" off this change.

Tests

scripts/__tests__/check-changeset-presence.test.ts gains section 2c — 14 cases, both directions:

• POSITIVE: a sideEffects array with no changeset goes red naming the file and the field; the same change with a changeset is green because of the declaration.
• Each of the eight fields goes red on its own (one fixture per field — a single combined case passes as long as any one field is read, which is how a half-wired allowlist stays green), with an assertion that the case table and CONTRACT_FIELDS are the same set, so a field with no case cannot exist.
• Both named exclusions: a version-only bump and a devDependencies-only bump are green.
• Unguarded fields (scripts, dependencies, publishConfig, description) moving together: green. Reformatting: green. Root manifest: green. files respelling: green. exports condition reorder: red.
• Ignored package: skipped, not demanded. Unparseable manifest: loud.
• CONTRACT_FIELDS is pinned as a list, which is what makes the ruling mechanical: adding or dropping a field cannot happen without a deliberate edit here.

Verification

All on the final commit 354653832.

whole scripts/__tests__ tree 89 test files, 2516 tests, all passed (89 on disk, 89 run)
lint:root (full population) exit 0 — 219 files, 0 errors, 29 pre-existing warnings, none in this diff
type-check:scripts exit 0
check:control-bytes exit 0 — 5804 tracked text files
check:entry-guard exit 0 — 56 scripts/ files, ratchets unmoved
check:node-esm-load exit 0
check:shell-escape-residue exit 0 — 4/4 roots resolved
check:upstream-port-parity exit 0
check:governed-queue-guard exit 0 — 132 cases
check-type-check-coverage exit 0
check-lint-coverage exit 0 — 46/46 packages
check-changeset-fixed exit 0
the gate on its own diff exit 0 — no changeset owed (scripts/ is no package's source)

Ablation — replacing contract: contract.guarded with contract: [] in analyze, with the mutation confirmed on disk (anchor 1 to 0, marker 0 to 1, blob hash moved) before reading any result: 4 failed / 49 passed, and the four are the positive legs. The restore leg was confirmed the same way — git checkout HEAD -- on an absolute path, then blob hash equal to HEAD, marker gone, anchor back, git diff HEAD empty.

No changeset: this diff touches scripts/ only, which is no package's published source. The skip-changeset label is deliberately not applied — in this repository that label object exists from a historical mis-attachment, is read by no workflow, and exempts nothing.

Filed, not fixed here

Two pre-existing findings, both measured on origin/main at 4357ec754 and both outside this card's declared file surface:

• finding(docs): AGENTS.md states the changeset rule as src/ only — already narrower than the gate since #5733, and narrower again after #6736 #6997 — AGENTS.md line 161 states the changeset rule as src/ only. Already narrower than the gate since objectui#5733, and narrower again after this PR. Agent-facing text, so a rule stated too narrowly is paid by every reader.
• finding(scripts): js-comment-mask.mjs cites two line numbers as evidence and both point at the wrong line (86 and 107 lines off) #6998 — js-comment-mask.mjs cites two line numbers as evidence for a live mutation-blind shape, and both point at the wrong line (86 and 107 off). This PR moves one of the two targets further, which is the point: a line number into another file has nothing keeping it true.

Generated by Claude Code

---

Generated by Claude Code

[claude]

Fixes#6736

scripts/check-changeset-presence.mjs derived its guarded surface from paths alone, so a change to a released package's published contract — sideEffects, exports/main/module/types, files, peerDependencies/engines — was owed no declaration. The live instance is PR #6735, which gave @object-ui/app-shell a sideEffects ARRAY and got the gate's own No source of a released package changed in this range, so no changeset is owed. The changeset in that PR was there because its author decided it was owed.

The false-positive measurement — the ruling's precondition

Triage made measuring the false-positive population a condition of the change, on #11457 discipline: "一个被绕过的门禁比没有门禁更糟,因为它还占着「已覆盖」的名分". Method: extract the pre-change gate from origin/main, import both versions, and run analyze + verdict over each merged commit on origin/main as sha^..sha (these are squash merges, so that range is the PR's diff).

	last 200 merged PRs	last 500 merged PRs
moved a guarded contract field at all	3	4
NEWLY RED under the widened criterion	0	0
flipped red to green (must be 0)	0	0
unreadable	0	0

Zero false positives. All three field moves in the 200-PR window already carried a changeset:

green f99932a42 feat(app-shell): render `global:search` and `global:notifications` … (#6838)
@object-ui/app-shell: sideEffects (changesets added: 1)
green faac0d935 feat(app-shell): the precise `sideEffects` array … (#6735)
@object-ui/app-shell: sideEffects (changesets added: 1)
green 3e028c8d8 refactor(types,app-shell,plugin-designer): one tombstone registry … (#6627)
@object-ui/types: exports (changesets added: 1)

The two named exclusions, measured against real history rather than fixtures

The card names two changes that must NOT demand a declaration. Both were run through the old gate, the new gate, and a file-level counterfactual ("any edit to a released package's package.json"):

commit	released package.json edited	guarded fields moved	changesets added	old	new (field-level)	counterfactual (file-level)
59f61cfb8chore: release packages (#4655) — what changeset version writes	40	0	0	0	0	1
590dd6356chore(deps-dev): bump the dev-dependencies group … 11 updates (#4948) — Dependabot	9	0	0	0	0	1

This is the whole argument for reading FIELDS rather than the file. A release commit rewrites 40 manifests and adds no changeset — it empties.changeset/. A file-level gate would go red on the very commit that answers it, and red on every Dependabot bump. Neither exclusion is a branch in the code: they hold because the reading is an allowlist of eight fields and version/devDependencies are not in it. There is no bot identity to sniff and no commit message to parse.

Is the new green on the live instance earned, or vacuous?

The old gate passed #6735 while having looked at nothing, so "still green" is not evidence. Ablating the declarations from the analysis separates the two:

OLD, as merged : exit 0 (guarded source files: 0)
OLD, declarations ablated : exit 0 <== green either way; the old gate never looked
NEW, as merged : exit 0 (guarded source: 0, contract: 1, declarations: 1)
NEW, declarations ablated : exit 1 <== RED; the green is earned by the declaration

What changed

A second question asked of the manifest, not a fourth clause in the population.isPublishedSource stays path-only and still answers false for package.json — pinned. A new contractChanges reads both sides of the diff out of git, parses them, and compares the eight guarded fields by value.

• Values, not bytes, not mtime. Re-indenting a manifest or moving version above name is green. Comparison is order-preserving serialisation, which is correct rather than convenient: exports condition order is resolution order in Node, so a reorder that moves no key and no value is a behaviour change and goes red.
• One normalisation for files, shared with clause (c).publishedEntries is what clause (c) compares changed paths against, and it is now what the field diff compares too. Without that the gate could demand a declaration for a files respelling (dist to dist/) that its own clause (c) reports as changing nothing shipped — code contradicting itself inside one run.
• Failures name the FIELD. "your package.json changed" is also true of a version bump this gate passes, so a red without the field name sends the author looking for a change the gate did not object to.
• Unclassified and ignored packages route the same way as source, so the two classifications compose into one verdict.
• Loud on every missing input, in the established direction: an unparseable manifest on either side is a red build, never a quiet pass.

The docblock said this exclusion was deliberate — reconciled, not overwritten

The card frames the gap as an omission. It is not: line 137 stated it as a boundary — "package.json itself never counts. Clause (c) reads that file; it does not match it. A dependency bump can be just as user-visible, and this gate still does not see it. That was the first draft's trade and it is kept."

Read against the code, that is a scoping trade against noise, not a mechanism-level obstacle — the same population discipline the header states two paragraphs earlier ("too wide and every incidental file in a package directory demands a declaration … which is how a gate stops being read at all"). A field-level reading is the resolution of exactly that trade rather than its reversal, so this is not a fork.

The bullet is rewritten, and the part of the trade that is kept is now stated as kept: dependencies stays out, and a runtime dependency bump is still invisible to this gate. Nobody should read "the manifest is guarded now" off this change.

Tests

scripts/__tests__/check-changeset-presence.test.ts gains section 2c — 14 cases, both directions:

• POSITIVE: a sideEffects array with no changeset goes red naming the file and the field; the same change with a changeset is green because of the declaration.
• Each of the eight fields goes red on its own (one fixture per field — a single combined case passes as long as any one field is read, which is how a half-wired allowlist stays green), with an assertion that the case table and CONTRACT_FIELDS are the same set, so a field with no case cannot exist.
• Both named exclusions: a version-only bump and a devDependencies-only bump are green.
• Unguarded fields (scripts, dependencies, publishConfig, description) moving together: green. Reformatting: green. Root manifest: green. files respelling: green. exports condition reorder: red.
• Ignored package: skipped, not demanded. Unparseable manifest: loud.
• CONTRACT_FIELDS is pinned as a list, which is what makes the ruling mechanical: adding or dropping a field cannot happen without a deliberate edit here.

Verification

All on the final commit 354653832.

whole scripts/__tests__ tree 89 test files, 2516 tests, all passed (89 on disk, 89 run)
lint:root (full population) exit 0 — 219 files, 0 errors, 29 pre-existing warnings, none in this diff
type-check:scripts exit 0
check:control-bytes exit 0 — 5804 tracked text files
check:entry-guard exit 0 — 56 scripts/ files, ratchets unmoved
check:node-esm-load exit 0
check:shell-escape-residue exit 0 — 4/4 roots resolved
check:upstream-port-parity exit 0
check:governed-queue-guard exit 0 — 132 cases
check-type-check-coverage exit 0
check-lint-coverage exit 0 — 46/46 packages
check-changeset-fixed exit 0
the gate on its own diff exit 0 — no changeset owed (scripts/ is no package's source)

Ablation — replacing contract: contract.guarded with contract: [] in analyze, with the mutation confirmed on disk (anchor 1 to 0, marker 0 to 1, blob hash moved) before reading any result: 4 failed / 49 passed, and the four are the positive legs. The restore leg was confirmed the same way — git checkout HEAD -- on an absolute path, then blob hash equal to HEAD, marker gone, anchor back, git diff HEAD empty.

No changeset: this diff touches scripts/ only, which is no package's published source. The skip-changeset label is deliberately not applied — in this repository that label object exists from a historical mis-attachment, is read by no workflow, and exempts nothing.

Filed, not fixed here

Two pre-existing findings, both measured on origin/main at 4357ec754 and both outside this card's declared file surface:

• finding(docs): AGENTS.md states the changeset rule as src/ only — already narrower than the gate since #5733, and narrower again after #6736 #6997 — AGENTS.md line 161 states the changeset rule as src/ only. Already narrower than the gate since objectui#5733, and narrower again after this PR. Agent-facing text, so a rule stated too narrowly is paid by every reader.
• finding(scripts): js-comment-mask.mjs cites two line numbers as evidence and both point at the wrong line (86 and 107 lines off) #6998 — js-comment-mask.mjs cites two line numbers as evidence for a live mutation-blind shape, and both point at the wrong line (86 and 107 off). This PR moves one of the two targets further, which is the point: a line number into another file has nothing keeping it true.

Generated by Claude Code

---

Generated by Claude Code

[claude]

Fixes#6736

scripts/check-changeset-presence.mjs derived its guarded surface from paths alone, so a change to a released package's published contract — sideEffects, exports/main/module/types, files, peerDependencies/engines — was owed no declaration. The live instance is PR #6735, which gave @object-ui/app-shell a sideEffects ARRAY and got the gate's own No source of a released package changed in this range, so no changeset is owed. The changeset in that PR was there because its author decided it was owed.

The false-positive measurement — the ruling's precondition

Triage made measuring the false-positive population a condition of the change, on #11457 discipline: "一个被绕过的门禁比没有门禁更糟,因为它还占着「已覆盖」的名分". Method: extract the pre-change gate from origin/main, import both versions, and run analyze + verdict over each merged commit on origin/main as sha^..sha (these are squash merges, so that range is the PR's diff).

	last 200 merged PRs	last 500 merged PRs
moved a guarded contract field at all	3	4
NEWLY RED under the widened criterion	0	0
flipped red to green (must be 0)	0	0
unreadable	0	0

Zero false positives. All three field moves in the 200-PR window already carried a changeset:

green f99932a42 feat(app-shell): render `global:search` and `global:notifications` … (#6838)
@object-ui/app-shell: sideEffects (changesets added: 1)
green faac0d935 feat(app-shell): the precise `sideEffects` array … (#6735)
@object-ui/app-shell: sideEffects (changesets added: 1)
green 3e028c8d8 refactor(types,app-shell,plugin-designer): one tombstone registry … (#6627)
@object-ui/types: exports (changesets added: 1)

The two named exclusions, measured against real history rather than fixtures

The card names two changes that must NOT demand a declaration. Both were run through the old gate, the new gate, and a file-level counterfactual ("any edit to a released package's package.json"):

commit	released package.json edited	guarded fields moved	changesets added	old	new (field-level)	counterfactual (file-level)
59f61cfb8chore: release packages (#4655) — what changeset version writes	40	0	0	0	0	1
590dd6356chore(deps-dev): bump the dev-dependencies group … 11 updates (#4948) — Dependabot	9	0	0	0	0	1

This is the whole argument for reading FIELDS rather than the file. A release commit rewrites 40 manifests and adds no changeset — it empties.changeset/. A file-level gate would go red on the very commit that answers it, and red on every Dependabot bump. Neither exclusion is a branch in the code: they hold because the reading is an allowlist of eight fields and version/devDependencies are not in it. There is no bot identity to sniff and no commit message to parse.

Is the new green on the live instance earned, or vacuous?

The old gate passed #6735 while having looked at nothing, so "still green" is not evidence. Ablating the declarations from the analysis separates the two:

OLD, as merged : exit 0 (guarded source files: 0)
OLD, declarations ablated : exit 0 <== green either way; the old gate never looked
NEW, as merged : exit 0 (guarded source: 0, contract: 1, declarations: 1)
NEW, declarations ablated : exit 1 <== RED; the green is earned by the declaration

What changed

A second question asked of the manifest, not a fourth clause in the population.isPublishedSource stays path-only and still answers false for package.json — pinned. A new contractChanges reads both sides of the diff out of git, parses them, and compares the eight guarded fields by value.

• Values, not bytes, not mtime. Re-indenting a manifest or moving version above name is green. Comparison is order-preserving serialisation, which is correct rather than convenient: exports condition order is resolution order in Node, so a reorder that moves no key and no value is a behaviour change and goes red.
• One normalisation for files, shared with clause (c).publishedEntries is what clause (c) compares changed paths against, and it is now what the field diff compares too. Without that the gate could demand a declaration for a files respelling (dist to dist/) that its own clause (c) reports as changing nothing shipped — code contradicting itself inside one run.
• Failures name the FIELD. "your package.json changed" is also true of a version bump this gate passes, so a red without the field name sends the author looking for a change the gate did not object to.
• Unclassified and ignored packages route the same way as source, so the two classifications compose into one verdict.
• Loud on every missing input, in the established direction: an unparseable manifest on either side is a red build, never a quiet pass.

The docblock said this exclusion was deliberate — reconciled, not overwritten

The card frames the gap as an omission. It is not: line 137 stated it as a boundary — "package.json itself never counts. Clause (c) reads that file; it does not match it. A dependency bump can be just as user-visible, and this gate still does not see it. That was the first draft's trade and it is kept."

Read against the code, that is a scoping trade against noise, not a mechanism-level obstacle — the same population discipline the header states two paragraphs earlier ("too wide and every incidental file in a package directory demands a declaration … which is how a gate stops being read at all"). A field-level reading is the resolution of exactly that trade rather than its reversal, so this is not a fork.

The bullet is rewritten, and the part of the trade that is kept is now stated as kept: dependencies stays out, and a runtime dependency bump is still invisible to this gate. Nobody should read "the manifest is guarded now" off this change.

Tests

scripts/__tests__/check-changeset-presence.test.ts gains section 2c — 14 cases, both directions:

• POSITIVE: a sideEffects array with no changeset goes red naming the file and the field; the same change with a changeset is green because of the declaration.
• Each of the eight fields goes red on its own (one fixture per field — a single combined case passes as long as any one field is read, which is how a half-wired allowlist stays green), with an assertion that the case table and CONTRACT_FIELDS are the same set, so a field with no case cannot exist.
• Both named exclusions: a version-only bump and a devDependencies-only bump are green.
• Unguarded fields (scripts, dependencies, publishConfig, description) moving together: green. Reformatting: green. Root manifest: green. files respelling: green. exports condition reorder: red.
• Ignored package: skipped, not demanded. Unparseable manifest: loud.
• CONTRACT_FIELDS is pinned as a list, which is what makes the ruling mechanical: adding or dropping a field cannot happen without a deliberate edit here.

Verification

All on the final commit 354653832.

whole scripts/__tests__ tree 89 test files, 2516 tests, all passed (89 on disk, 89 run)
lint:root (full population) exit 0 — 219 files, 0 errors, 29 pre-existing warnings, none in this diff
type-check:scripts exit 0
check:control-bytes exit 0 — 5804 tracked text files
check:entry-guard exit 0 — 56 scripts/ files, ratchets unmoved
check:node-esm-load exit 0
check:shell-escape-residue exit 0 — 4/4 roots resolved
check:upstream-port-parity exit 0
check:governed-queue-guard exit 0 — 132 cases
check-type-check-coverage exit 0
check-lint-coverage exit 0 — 46/46 packages
check-changeset-fixed exit 0
the gate on its own diff exit 0 — no changeset owed (scripts/ is no package's source)

Ablation — replacing contract: contract.guarded with contract: [] in analyze, with the mutation confirmed on disk (anchor 1 to 0, marker 0 to 1, blob hash moved) before reading any result: 4 failed / 49 passed, and the four are the positive legs. The restore leg was confirmed the same way — git checkout HEAD -- on an absolute path, then blob hash equal to HEAD, marker gone, anchor back, git diff HEAD empty.

No changeset: this diff touches scripts/ only, which is no package's published source. The skip-changeset label is deliberately not applied — in this repository that label object exists from a historical mis-attachment, is read by no workflow, and exempts nothing.

Filed, not fixed here

Two pre-existing findings, both measured on origin/main at 4357ec754 and both outside this card's declared file surface:

• finding(docs): AGENTS.md states the changeset rule as src/ only — already narrower than the gate since #5733, and narrower again after #6736 #6997 — AGENTS.md line 161 states the changeset rule as src/ only. Already narrower than the gate since objectui#5733, and narrower again after this PR. Agent-facing text, so a rule stated too narrowly is paid by every reader.
• finding(scripts): js-comment-mask.mjs cites two line numbers as evidence and both point at the wrong line (86 and 107 lines off) #6998 — js-comment-mask.mjs cites two line numbers as evidence for a live mutation-blind shape, and both point at the wrong line (86 and 107 off). This PR moves one of the two targets further, which is the point: a line number into another file has nothing keeping it true.

Generated by Claude Code

---

Generated by Claude Code

[claude]

Fixes#6736

scripts/check-changeset-presence.mjs derived its guarded surface from paths alone, so a change to a released package's published contract — sideEffects, exports/main/module/types, files, peerDependencies/engines — was owed no declaration. The live instance is PR #6735, which gave @object-ui/app-shell a sideEffects ARRAY and got the gate's own No source of a released package changed in this range, so no changeset is owed. The changeset in that PR was there because its author decided it was owed.

The false-positive measurement — the ruling's precondition

Triage made measuring the false-positive population a condition of the change, on #11457 discipline: "一个被绕过的门禁比没有门禁更糟,因为它还占着「已覆盖」的名分". Method: extract the pre-change gate from origin/main, import both versions, and run analyze + verdict over each merged commit on origin/main as sha^..sha (these are squash merges, so that range is the PR's diff).

	last 200 merged PRs	last 500 merged PRs
moved a guarded contract field at all	3	4
NEWLY RED under the widened criterion	0	0
flipped red to green (must be 0)	0	0
unreadable	0	0

Zero false positives. All three field moves in the 200-PR window already carried a changeset:

green f99932a42 feat(app-shell): render `global:search` and `global:notifications` … (#6838)
@object-ui/app-shell: sideEffects (changesets added: 1)
green faac0d935 feat(app-shell): the precise `sideEffects` array … (#6735)
@object-ui/app-shell: sideEffects (changesets added: 1)
green 3e028c8d8 refactor(types,app-shell,plugin-designer): one tombstone registry … (#6627)
@object-ui/types: exports (changesets added: 1)

The two named exclusions, measured against real history rather than fixtures

The card names two changes that must NOT demand a declaration. Both were run through the old gate, the new gate, and a file-level counterfactual ("any edit to a released package's package.json"):

commit	released package.json edited	guarded fields moved	changesets added	old	new (field-level)	counterfactual (file-level)
59f61cfb8chore: release packages (#4655) — what changeset version writes	40	0	0	0	0	1
590dd6356chore(deps-dev): bump the dev-dependencies group … 11 updates (#4948) — Dependabot	9	0	0	0	0	1

This is the whole argument for reading FIELDS rather than the file. A release commit rewrites 40 manifests and adds no changeset — it empties.changeset/. A file-level gate would go red on the very commit that answers it, and red on every Dependabot bump. Neither exclusion is a branch in the code: they hold because the reading is an allowlist of eight fields and version/devDependencies are not in it. There is no bot identity to sniff and no commit message to parse.

Is the new green on the live instance earned, or vacuous?

The old gate passed #6735 while having looked at nothing, so "still green" is not evidence. Ablating the declarations from the analysis separates the two:

OLD, as merged : exit 0 (guarded source files: 0)
OLD, declarations ablated : exit 0 <== green either way; the old gate never looked
NEW, as merged : exit 0 (guarded source: 0, contract: 1, declarations: 1)
NEW, declarations ablated : exit 1 <== RED; the green is earned by the declaration

What changed

A second question asked of the manifest, not a fourth clause in the population.isPublishedSource stays path-only and still answers false for package.json — pinned. A new contractChanges reads both sides of the diff out of git, parses them, and compares the eight guarded fields by value.

• Values, not bytes, not mtime. Re-indenting a manifest or moving version above name is green. Comparison is order-preserving serialisation, which is correct rather than convenient: exports condition order is resolution order in Node, so a reorder that moves no key and no value is a behaviour change and goes red.
• One normalisation for files, shared with clause (c).publishedEntries is what clause (c) compares changed paths against, and it is now what the field diff compares too. Without that the gate could demand a declaration for a files respelling (dist to dist/) that its own clause (c) reports as changing nothing shipped — code contradicting itself inside one run.
• Failures name the FIELD. "your package.json changed" is also true of a version bump this gate passes, so a red without the field name sends the author looking for a change the gate did not object to.
• Unclassified and ignored packages route the same way as source, so the two classifications compose into one verdict.
• Loud on every missing input, in the established direction: an unparseable manifest on either side is a red build, never a quiet pass.

The docblock said this exclusion was deliberate — reconciled, not overwritten

The card frames the gap as an omission. It is not: line 137 stated it as a boundary — "package.json itself never counts. Clause (c) reads that file; it does not match it. A dependency bump can be just as user-visible, and this gate still does not see it. That was the first draft's trade and it is kept."

Read against the code, that is a scoping trade against noise, not a mechanism-level obstacle — the same population discipline the header states two paragraphs earlier ("too wide and every incidental file in a package directory demands a declaration … which is how a gate stops being read at all"). A field-level reading is the resolution of exactly that trade rather than its reversal, so this is not a fork.

The bullet is rewritten, and the part of the trade that is kept is now stated as kept: dependencies stays out, and a runtime dependency bump is still invisible to this gate. Nobody should read "the manifest is guarded now" off this change.

Tests

scripts/__tests__/check-changeset-presence.test.ts gains section 2c — 14 cases, both directions:

• POSITIVE: a sideEffects array with no changeset goes red naming the file and the field; the same change with a changeset is green because of the declaration.
• Each of the eight fields goes red on its own (one fixture per field — a single combined case passes as long as any one field is read, which is how a half-wired allowlist stays green), with an assertion that the case table and CONTRACT_FIELDS are the same set, so a field with no case cannot exist.
• Both named exclusions: a version-only bump and a devDependencies-only bump are green.
• Unguarded fields (scripts, dependencies, publishConfig, description) moving together: green. Reformatting: green. Root manifest: green. files respelling: green. exports condition reorder: red.
• Ignored package: skipped, not demanded. Unparseable manifest: loud.
• CONTRACT_FIELDS is pinned as a list, which is what makes the ruling mechanical: adding or dropping a field cannot happen without a deliberate edit here.

Verification

All on the final commit 354653832.

whole scripts/__tests__ tree 89 test files, 2516 tests, all passed (89 on disk, 89 run)
lint:root (full population) exit 0 — 219 files, 0 errors, 29 pre-existing warnings, none in this diff
type-check:scripts exit 0
check:control-bytes exit 0 — 5804 tracked text files
check:entry-guard exit 0 — 56 scripts/ files, ratchets unmoved
check:node-esm-load exit 0
check:shell-escape-residue exit 0 — 4/4 roots resolved
check:upstream-port-parity exit 0
check:governed-queue-guard exit 0 — 132 cases
check-type-check-coverage exit 0
check-lint-coverage exit 0 — 46/46 packages
check-changeset-fixed exit 0
the gate on its own diff exit 0 — no changeset owed (scripts/ is no package's source)

Ablation — replacing contract: contract.guarded with contract: [] in analyze, with the mutation confirmed on disk (anchor 1 to 0, marker 0 to 1, blob hash moved) before reading any result: 4 failed / 49 passed, and the four are the positive legs. The restore leg was confirmed the same way — git checkout HEAD -- on an absolute path, then blob hash equal to HEAD, marker gone, anchor back, git diff HEAD empty.

No changeset: this diff touches scripts/ only, which is no package's published source. The skip-changeset label is deliberately not applied — in this repository that label object exists from a historical mis-attachment, is read by no workflow, and exempts nothing.

Filed, not fixed here

Two pre-existing findings, both measured on origin/main at 4357ec754 and both outside this card's declared file surface:

• finding(docs): AGENTS.md states the changeset rule as src/ only — already narrower than the gate since #5733, and narrower again after #6736 #6997 — AGENTS.md line 161 states the changeset rule as src/ only. Already narrower than the gate since objectui#5733, and narrower again after this PR. Agent-facing text, so a rule stated too narrowly is paid by every reader.
• finding(scripts): js-comment-mask.mjs cites two line numbers as evidence and both point at the wrong line (86 and 107 lines off) #6998 — js-comment-mask.mjs cites two line numbers as evidence for a live mutation-blind shape, and both point at the wrong line (86 and 107 off). This PR moves one of the two targets further, which is the point: a line number into another file has nothing keeping it true.

Generated by Claude Code

---

Generated by Claude Code

[claude]

Fixes#6736

scripts/check-changeset-presence.mjs derived its guarded surface from paths alone, so a change to a released package's published contract — sideEffects, exports/main/module/types, files, peerDependencies/engines — was owed no declaration. The live instance is PR #6735, which gave @object-ui/app-shell a sideEffects ARRAY and got the gate's own No source of a released package changed in this range, so no changeset is owed. The changeset in that PR was there because its author decided it was owed.

The false-positive measurement — the ruling's precondition

Triage made measuring the false-positive population a condition of the change, on #11457 discipline: "一个被绕过的门禁比没有门禁更糟,因为它还占着「已覆盖」的名分". Method: extract the pre-change gate from origin/main, import both versions, and run analyze + verdict over each merged commit on origin/main as sha^..sha (these are squash merges, so that range is the PR's diff).

	last 200 merged PRs	last 500 merged PRs
moved a guarded contract field at all	3	4
NEWLY RED under the widened criterion	0	0
flipped red to green (must be 0)	0	0
unreadable	0	0

Zero false positives. All three field moves in the 200-PR window already carried a changeset:

green f99932a42 feat(app-shell): render `global:search` and `global:notifications` … (#6838)
@object-ui/app-shell: sideEffects (changesets added: 1)
green faac0d935 feat(app-shell): the precise `sideEffects` array … (#6735)
@object-ui/app-shell: sideEffects (changesets added: 1)
green 3e028c8d8 refactor(types,app-shell,plugin-designer): one tombstone registry … (#6627)
@object-ui/types: exports (changesets added: 1)

The two named exclusions, measured against real history rather than fixtures

The card names two changes that must NOT demand a declaration. Both were run through the old gate, the new gate, and a file-level counterfactual ("any edit to a released package's package.json"):

commit	released package.json edited	guarded fields moved	changesets added	old	new (field-level)	counterfactual (file-level)
59f61cfb8chore: release packages (#4655) — what changeset version writes	40	0	0	0	0	1
590dd6356chore(deps-dev): bump the dev-dependencies group … 11 updates (#4948) — Dependabot	9	0	0	0	0	1

This is the whole argument for reading FIELDS rather than the file. A release commit rewrites 40 manifests and adds no changeset — it empties.changeset/. A file-level gate would go red on the very commit that answers it, and red on every Dependabot bump. Neither exclusion is a branch in the code: they hold because the reading is an allowlist of eight fields and version/devDependencies are not in it. There is no bot identity to sniff and no commit message to parse.

Is the new green on the live instance earned, or vacuous?

The old gate passed #6735 while having looked at nothing, so "still green" is not evidence. Ablating the declarations from the analysis separates the two:

OLD, as merged : exit 0 (guarded source files: 0)
OLD, declarations ablated : exit 0 <== green either way; the old gate never looked
NEW, as merged : exit 0 (guarded source: 0, contract: 1, declarations: 1)
NEW, declarations ablated : exit 1 <== RED; the green is earned by the declaration

What changed

A second question asked of the manifest, not a fourth clause in the population.isPublishedSource stays path-only and still answers false for package.json — pinned. A new contractChanges reads both sides of the diff out of git, parses them, and compares the eight guarded fields by value.

• Values, not bytes, not mtime. Re-indenting a manifest or moving version above name is green. Comparison is order-preserving serialisation, which is correct rather than convenient: exports condition order is resolution order in Node, so a reorder that moves no key and no value is a behaviour change and goes red.
• One normalisation for files, shared with clause (c).publishedEntries is what clause (c) compares changed paths against, and it is now what the field diff compares too. Without that the gate could demand a declaration for a files respelling (dist to dist/) that its own clause (c) reports as changing nothing shipped — code contradicting itself inside one run.
• Failures name the FIELD. "your package.json changed" is also true of a version bump this gate passes, so a red without the field name sends the author looking for a change the gate did not object to.
• Unclassified and ignored packages route the same way as source, so the two classifications compose into one verdict.
• Loud on every missing input, in the established direction: an unparseable manifest on either side is a red build, never a quiet pass.

The docblock said this exclusion was deliberate — reconciled, not overwritten

The card frames the gap as an omission. It is not: line 137 stated it as a boundary — "package.json itself never counts. Clause (c) reads that file; it does not match it. A dependency bump can be just as user-visible, and this gate still does not see it. That was the first draft's trade and it is kept."

Read against the code, that is a scoping trade against noise, not a mechanism-level obstacle — the same population discipline the header states two paragraphs earlier ("too wide and every incidental file in a package directory demands a declaration … which is how a gate stops being read at all"). A field-level reading is the resolution of exactly that trade rather than its reversal, so this is not a fork.

The bullet is rewritten, and the part of the trade that is kept is now stated as kept: dependencies stays out, and a runtime dependency bump is still invisible to this gate. Nobody should read "the manifest is guarded now" off this change.

Tests

scripts/__tests__/check-changeset-presence.test.ts gains section 2c — 14 cases, both directions:

• POSITIVE: a sideEffects array with no changeset goes red naming the file and the field; the same change with a changeset is green because of the declaration.
• Each of the eight fields goes red on its own (one fixture per field — a single combined case passes as long as any one field is read, which is how a half-wired allowlist stays green), with an assertion that the case table and CONTRACT_FIELDS are the same set, so a field with no case cannot exist.
• Both named exclusions: a version-only bump and a devDependencies-only bump are green.
• Unguarded fields (scripts, dependencies, publishConfig, description) moving together: green. Reformatting: green. Root manifest: green. files respelling: green. exports condition reorder: red.
• Ignored package: skipped, not demanded. Unparseable manifest: loud.
• CONTRACT_FIELDS is pinned as a list, which is what makes the ruling mechanical: adding or dropping a field cannot happen without a deliberate edit here.

Verification

All on the final commit 354653832.

whole scripts/__tests__ tree 89 test files, 2516 tests, all passed (89 on disk, 89 run)
lint:root (full population) exit 0 — 219 files, 0 errors, 29 pre-existing warnings, none in this diff
type-check:scripts exit 0
check:control-bytes exit 0 — 5804 tracked text files
check:entry-guard exit 0 — 56 scripts/ files, ratchets unmoved
check:node-esm-load exit 0
check:shell-escape-residue exit 0 — 4/4 roots resolved
check:upstream-port-parity exit 0
check:governed-queue-guard exit 0 — 132 cases
check-type-check-coverage exit 0
check-lint-coverage exit 0 — 46/46 packages
check-changeset-fixed exit 0
the gate on its own diff exit 0 — no changeset owed (scripts/ is no package's source)

Ablation — replacing contract: contract.guarded with contract: [] in analyze, with the mutation confirmed on disk (anchor 1 to 0, marker 0 to 1, blob hash moved) before reading any result: 4 failed / 49 passed, and the four are the positive legs. The restore leg was confirmed the same way — git checkout HEAD -- on an absolute path, then blob hash equal to HEAD, marker gone, anchor back, git diff HEAD empty.

No changeset: this diff touches scripts/ only, which is no package's published source. The skip-changeset label is deliberately not applied — in this repository that label object exists from a historical mis-attachment, is read by no workflow, and exempts nothing.

Filed, not fixed here

Two pre-existing findings, both measured on origin/main at 4357ec754 and both outside this card's declared file surface:

• finding(docs): AGENTS.md states the changeset rule as src/ only — already narrower than the gate since #5733, and narrower again after #6736 #6997 — AGENTS.md line 161 states the changeset rule as src/ only. Already narrower than the gate since objectui#5733, and narrower again after this PR. Agent-facing text, so a rule stated too narrowly is paid by every reader.
• finding(scripts): js-comment-mask.mjs cites two line numbers as evidence and both point at the wrong line (86 and 107 lines off) #6998 — js-comment-mask.mjs cites two line numbers as evidence for a live mutation-blind shape, and both point at the wrong line (86 and 107 off). This PR moves one of the two targets further, which is the point: a line number into another file has nothing keeping it true.

Generated by Claude Code

---

Generated by Claude Code

[claude]

Fixes#6736

scripts/check-changeset-presence.mjs derived its guarded surface from paths alone, so a change to a released package's published contract — sideEffects, exports/main/module/types, files, peerDependencies/engines — was owed no declaration. The live instance is PR #6735, which gave @object-ui/app-shell a sideEffects ARRAY and got the gate's own No source of a released package changed in this range, so no changeset is owed. The changeset in that PR was there because its author decided it was owed.

The false-positive measurement — the ruling's precondition

Triage made measuring the false-positive population a condition of the change, on #11457 discipline: "一个被绕过的门禁比没有门禁更糟,因为它还占着「已覆盖」的名分". Method: extract the pre-change gate from origin/main, import both versions, and run analyze + verdict over each merged commit on origin/main as sha^..sha (these are squash merges, so that range is the PR's diff).

	last 200 merged PRs	last 500 merged PRs
moved a guarded contract field at all	3	4
NEWLY RED under the widened criterion	0	0
flipped red to green (must be 0)	0	0
unreadable	0	0

Zero false positives. All three field moves in the 200-PR window already carried a changeset:

green f99932a42 feat(app-shell): render `global:search` and `global:notifications` … (#6838)
@object-ui/app-shell: sideEffects (changesets added: 1)
green faac0d935 feat(app-shell): the precise `sideEffects` array … (#6735)
@object-ui/app-shell: sideEffects (changesets added: 1)
green 3e028c8d8 refactor(types,app-shell,plugin-designer): one tombstone registry … (#6627)
@object-ui/types: exports (changesets added: 1)

The two named exclusions, measured against real history rather than fixtures

The card names two changes that must NOT demand a declaration. Both were run through the old gate, the new gate, and a file-level counterfactual ("any edit to a released package's package.json"):

commit	released package.json edited	guarded fields moved	changesets added	old	new (field-level)	counterfactual (file-level)
59f61cfb8chore: release packages (#4655) — what changeset version writes	40	0	0	0	0	1
590dd6356chore(deps-dev): bump the dev-dependencies group … 11 updates (#4948) — Dependabot	9	0	0	0	0	1

This is the whole argument for reading FIELDS rather than the file. A release commit rewrites 40 manifests and adds no changeset — it empties.changeset/. A file-level gate would go red on the very commit that answers it, and red on every Dependabot bump. Neither exclusion is a branch in the code: they hold because the reading is an allowlist of eight fields and version/devDependencies are not in it. There is no bot identity to sniff and no commit message to parse.

Is the new green on the live instance earned, or vacuous?

The old gate passed #6735 while having looked at nothing, so "still green" is not evidence. Ablating the declarations from the analysis separates the two:

OLD, as merged : exit 0 (guarded source files: 0)
OLD, declarations ablated : exit 0 <== green either way; the old gate never looked
NEW, as merged : exit 0 (guarded source: 0, contract: 1, declarations: 1)
NEW, declarations ablated : exit 1 <== RED; the green is earned by the declaration

What changed

A second question asked of the manifest, not a fourth clause in the population.isPublishedSource stays path-only and still answers false for package.json — pinned. A new contractChanges reads both sides of the diff out of git, parses them, and compares the eight guarded fields by value.

• Values, not bytes, not mtime. Re-indenting a manifest or moving version above name is green. Comparison is order-preserving serialisation, which is correct rather than convenient: exports condition order is resolution order in Node, so a reorder that moves no key and no value is a behaviour change and goes red.
• One normalisation for files, shared with clause (c).publishedEntries is what clause (c) compares changed paths against, and it is now what the field diff compares too. Without that the gate could demand a declaration for a files respelling (dist to dist/) that its own clause (c) reports as changing nothing shipped — code contradicting itself inside one run.
• Failures name the FIELD. "your package.json changed" is also true of a version bump this gate passes, so a red without the field name sends the author looking for a change the gate did not object to.
• Unclassified and ignored packages route the same way as source, so the two classifications compose into one verdict.
• Loud on every missing input, in the established direction: an unparseable manifest on either side is a red build, never a quiet pass.

The docblock said this exclusion was deliberate — reconciled, not overwritten

The card frames the gap as an omission. It is not: line 137 stated it as a boundary — "package.json itself never counts. Clause (c) reads that file; it does not match it. A dependency bump can be just as user-visible, and this gate still does not see it. That was the first draft's trade and it is kept."

Read against the code, that is a scoping trade against noise, not a mechanism-level obstacle — the same population discipline the header states two paragraphs earlier ("too wide and every incidental file in a package directory demands a declaration … which is how a gate stops being read at all"). A field-level reading is the resolution of exactly that trade rather than its reversal, so this is not a fork.

The bullet is rewritten, and the part of the trade that is kept is now stated as kept: dependencies stays out, and a runtime dependency bump is still invisible to this gate. Nobody should read "the manifest is guarded now" off this change.

Tests

scripts/__tests__/check-changeset-presence.test.ts gains section 2c — 14 cases, both directions:

• POSITIVE: a sideEffects array with no changeset goes red naming the file and the field; the same change with a changeset is green because of the declaration.
• Each of the eight fields goes red on its own (one fixture per field — a single combined case passes as long as any one field is read, which is how a half-wired allowlist stays green), with an assertion that the case table and CONTRACT_FIELDS are the same set, so a field with no case cannot exist.
• Both named exclusions: a version-only bump and a devDependencies-only bump are green.
• Unguarded fields (scripts, dependencies, publishConfig, description) moving together: green. Reformatting: green. Root manifest: green. files respelling: green. exports condition reorder: red.
• Ignored package: skipped, not demanded. Unparseable manifest: loud.
• CONTRACT_FIELDS is pinned as a list, which is what makes the ruling mechanical: adding or dropping a field cannot happen without a deliberate edit here.

Verification

All on the final commit 354653832.

whole scripts/__tests__ tree 89 test files, 2516 tests, all passed (89 on disk, 89 run)
lint:root (full population) exit 0 — 219 files, 0 errors, 29 pre-existing warnings, none in this diff
type-check:scripts exit 0
check:control-bytes exit 0 — 5804 tracked text files
check:entry-guard exit 0 — 56 scripts/ files, ratchets unmoved
check:node-esm-load exit 0
check:shell-escape-residue exit 0 — 4/4 roots resolved
check:upstream-port-parity exit 0
check:governed-queue-guard exit 0 — 132 cases
check-type-check-coverage exit 0
check-lint-coverage exit 0 — 46/46 packages
check-changeset-fixed exit 0
the gate on its own diff exit 0 — no changeset owed (scripts/ is no package's source)

Ablation — replacing contract: contract.guarded with contract: [] in analyze, with the mutation confirmed on disk (anchor 1 to 0, marker 0 to 1, blob hash moved) before reading any result: 4 failed / 49 passed, and the four are the positive legs. The restore leg was confirmed the same way — git checkout HEAD -- on an absolute path, then blob hash equal to HEAD, marker gone, anchor back, git diff HEAD empty.

No changeset: this diff touches scripts/ only, which is no package's published source. The skip-changeset label is deliberately not applied — in this repository that label object exists from a historical mis-attachment, is read by no workflow, and exempts nothing.

Filed, not fixed here

Two pre-existing findings, both measured on origin/main at 4357ec754 and both outside this card's declared file surface:

• finding(docs): AGENTS.md states the changeset rule as src/ only — already narrower than the gate since #5733, and narrower again after #6736 #6997 — AGENTS.md line 161 states the changeset rule as src/ only. Already narrower than the gate since objectui#5733, and narrower again after this PR. Agent-facing text, so a rule stated too narrowly is paid by every reader.
• finding(scripts): js-comment-mask.mjs cites two line numbers as evidence and both point at the wrong line (86 and 107 lines off) #6998 — js-comment-mask.mjs cites two line numbers as evidence for a live mutation-blind shape, and both point at the wrong line (86 and 107 off). This PR moves one of the two targets further, which is the point: a line number into another file has nothing keeping it true.

Generated by Claude Code

---

Generated by Claude Code

[claude]

Fixes#6736

scripts/check-changeset-presence.mjs derived its guarded surface from paths alone, so a change to a released package's published contract — sideEffects, exports/main/module/types, files, peerDependencies/engines — was owed no declaration. The live instance is PR #6735, which gave @object-ui/app-shell a sideEffects ARRAY and got the gate's own No source of a released package changed in this range, so no changeset is owed. The changeset in that PR was there because its author decided it was owed.

The false-positive measurement — the ruling's precondition

Triage made measuring the false-positive population a condition of the change, on #11457 discipline: "一个被绕过的门禁比没有门禁更糟,因为它还占着「已覆盖」的名分". Method: extract the pre-change gate from origin/main, import both versions, and run analyze + verdict over each merged commit on origin/main as sha^..sha (these are squash merges, so that range is the PR's diff).

	last 200 merged PRs	last 500 merged PRs
moved a guarded contract field at all	3	4
NEWLY RED under the widened criterion	0	0
flipped red to green (must be 0)	0	0
unreadable	0	0

Zero false positives. All three field moves in the 200-PR window already carried a changeset:

green f99932a42 feat(app-shell): render `global:search` and `global:notifications` … (#6838)
@object-ui/app-shell: sideEffects (changesets added: 1)
green faac0d935 feat(app-shell): the precise `sideEffects` array … (#6735)
@object-ui/app-shell: sideEffects (changesets added: 1)
green 3e028c8d8 refactor(types,app-shell,plugin-designer): one tombstone registry … (#6627)
@object-ui/types: exports (changesets added: 1)

The two named exclusions, measured against real history rather than fixtures

The card names two changes that must NOT demand a declaration. Both were run through the old gate, the new gate, and a file-level counterfactual ("any edit to a released package's package.json"):

commit	released package.json edited	guarded fields moved	changesets added	old	new (field-level)	counterfactual (file-level)
59f61cfb8chore: release packages (#4655) — what changeset version writes	40	0	0	0	0	1
590dd6356chore(deps-dev): bump the dev-dependencies group … 11 updates (#4948) — Dependabot	9	0	0	0	0	1

This is the whole argument for reading FIELDS rather than the file. A release commit rewrites 40 manifests and adds no changeset — it empties.changeset/. A file-level gate would go red on the very commit that answers it, and red on every Dependabot bump. Neither exclusion is a branch in the code: they hold because the reading is an allowlist of eight fields and version/devDependencies are not in it. There is no bot identity to sniff and no commit message to parse.

Is the new green on the live instance earned, or vacuous?

The old gate passed #6735 while having looked at nothing, so "still green" is not evidence. Ablating the declarations from the analysis separates the two:

OLD, as merged : exit 0 (guarded source files: 0)
OLD, declarations ablated : exit 0 <== green either way; the old gate never looked
NEW, as merged : exit 0 (guarded source: 0, contract: 1, declarations: 1)
NEW, declarations ablated : exit 1 <== RED; the green is earned by the declaration

What changed

A second question asked of the manifest, not a fourth clause in the population.isPublishedSource stays path-only and still answers false for package.json — pinned. A new contractChanges reads both sides of the diff out of git, parses them, and compares the eight guarded fields by value.

• Values, not bytes, not mtime. Re-indenting a manifest or moving version above name is green. Comparison is order-preserving serialisation, which is correct rather than convenient: exports condition order is resolution order in Node, so a reorder that moves no key and no value is a behaviour change and goes red.
• One normalisation for files, shared with clause (c).publishedEntries is what clause (c) compares changed paths against, and it is now what the field diff compares too. Without that the gate could demand a declaration for a files respelling (dist to dist/) that its own clause (c) reports as changing nothing shipped — code contradicting itself inside one run.
• Failures name the FIELD. "your package.json changed" is also true of a version bump this gate passes, so a red without the field name sends the author looking for a change the gate did not object to.
• Unclassified and ignored packages route the same way as source, so the two classifications compose into one verdict.
• Loud on every missing input, in the established direction: an unparseable manifest on either side is a red build, never a quiet pass.

The docblock said this exclusion was deliberate — reconciled, not overwritten

The card frames the gap as an omission. It is not: line 137 stated it as a boundary — "package.json itself never counts. Clause (c) reads that file; it does not match it. A dependency bump can be just as user-visible, and this gate still does not see it. That was the first draft's trade and it is kept."

Read against the code, that is a scoping trade against noise, not a mechanism-level obstacle — the same population discipline the header states two paragraphs earlier ("too wide and every incidental file in a package directory demands a declaration … which is how a gate stops being read at all"). A field-level reading is the resolution of exactly that trade rather than its reversal, so this is not a fork.

The bullet is rewritten, and the part of the trade that is kept is now stated as kept: dependencies stays out, and a runtime dependency bump is still invisible to this gate. Nobody should read "the manifest is guarded now" off this change.

Tests

scripts/__tests__/check-changeset-presence.test.ts gains section 2c — 14 cases, both directions:

• POSITIVE: a sideEffects array with no changeset goes red naming the file and the field; the same change with a changeset is green because of the declaration.
• Each of the eight fields goes red on its own (one fixture per field — a single combined case passes as long as any one field is read, which is how a half-wired allowlist stays green), with an assertion that the case table and CONTRACT_FIELDS are the same set, so a field with no case cannot exist.
• Both named exclusions: a version-only bump and a devDependencies-only bump are green.
• Unguarded fields (scripts, dependencies, publishConfig, description) moving together: green. Reformatting: green. Root manifest: green. files respelling: green. exports condition reorder: red.
• Ignored package: skipped, not demanded. Unparseable manifest: loud.
• CONTRACT_FIELDS is pinned as a list, which is what makes the ruling mechanical: adding or dropping a field cannot happen without a deliberate edit here.

Verification

All on the final commit 354653832.

whole scripts/__tests__ tree 89 test files, 2516 tests, all passed (89 on disk, 89 run)
lint:root (full population) exit 0 — 219 files, 0 errors, 29 pre-existing warnings, none in this diff
type-check:scripts exit 0
check:control-bytes exit 0 — 5804 tracked text files
check:entry-guard exit 0 — 56 scripts/ files, ratchets unmoved
check:node-esm-load exit 0
check:shell-escape-residue exit 0 — 4/4 roots resolved
check:upstream-port-parity exit 0
check:governed-queue-guard exit 0 — 132 cases
check-type-check-coverage exit 0
check-lint-coverage exit 0 — 46/46 packages
check-changeset-fixed exit 0
the gate on its own diff exit 0 — no changeset owed (scripts/ is no package's source)

Ablation — replacing contract: contract.guarded with contract: [] in analyze, with the mutation confirmed on disk (anchor 1 to 0, marker 0 to 1, blob hash moved) before reading any result: 4 failed / 49 passed, and the four are the positive legs. The restore leg was confirmed the same way — git checkout HEAD -- on an absolute path, then blob hash equal to HEAD, marker gone, anchor back, git diff HEAD empty.

No changeset: this diff touches scripts/ only, which is no package's published source. The skip-changeset label is deliberately not applied — in this repository that label object exists from a historical mis-attachment, is read by no workflow, and exempts nothing.

Filed, not fixed here

Two pre-existing findings, both measured on origin/main at 4357ec754 and both outside this card's declared file surface:

• finding(docs): AGENTS.md states the changeset rule as src/ only — already narrower than the gate since #5733, and narrower again after #6736 #6997 — AGENTS.md line 161 states the changeset rule as src/ only. Already narrower than the gate since objectui#5733, and narrower again after this PR. Agent-facing text, so a rule stated too narrowly is paid by every reader.
• finding(scripts): js-comment-mask.mjs cites two line numbers as evidence and both point at the wrong line (86 and 107 lines off) #6998 — js-comment-mask.mjs cites two line numbers as evidence for a live mutation-blind shape, and both point at the wrong line (86 and 107 off). This PR moves one of the two targets further, which is the point: a line number into another file has nothing keeping it true.

Generated by Claude Code

---

Generated by Claude Code