check-required-contexts.mjs reasons from "no agent seat can read the ruleset" — measured false: the rulesets API answers 200, and the required SET is readable

[os-steve]

Filed unassigned by the domain:devx os-dev seat while landing #9595 / PR for cross-repo-issue-closer.yml. Recording, not claiming — the seat needed the live required-set to re-derive that card's red/green judgement and found the premise wrong on the way. Dedup-searched (workflow name, "ruleset", "required set", "403"): #9533 and #6991 are the neighbours, and neither states this.

The premise, quoted

scripts/check-required-contexts.mjs, header (line 79):

Settings → Rulesets, and no agent seat can read it: GET /repos/objectstack-ai/objectstack/branches/main/protection answers HTTP 403

and again in the failure prescription (line 855):

(Settings → Rulesets is maintainer-only; the API answers 403 to every agent seat), so a legitimate rename …

lint.yml's step comment repeats it: "⚠️ It cannot verify the required SET itself — Settings → Rulesets is unreadable from every agent seat (403)".

The measurement (2026-08-18, this container, ordinary agent seat)

The endpoint named in the header does answer 403. It is also not the ruleset endpoint — it is the classic branch-protection endpoint, which this repository does not use. The rulesets endpoints answer 200:

endpoint	status
GET /repos/objectstack-ai/objectstack/branches/main/protection	403 Resource not accessible by integration
GET /repos/objectstack-ai/objectstack/rulesets	200 — one active ruleset, main, id 12119582, updated_at 2026-08-18T03:26:48Z
GET /repos/objectstack-ai/objectstack/rulesets/12119582	200 — full rules[], including required_status_checks

The required_status_checks rule from that second call, verbatim in list order:

TypeScript Type Check
Test Core
Dogfood Regression Gate
Build Core
Temporal Conformance (live PG + MySQL)
Lint & Repo Gates

strict_required_status_checks_policy: false. The same ruleset also carries deletion, non_fast_forward, merge_queue (SQUASH, grouping_strategy: ALLGREEN, check_response_timeout_minutes: 60) and pull_request (0 required approvals) rules. Only one ruleset exists, and it is repository-sourced, so no organization ruleset is being missed.

Why it matters

1. The gate's stated blind spot is not actually blind. The script says at length that it can assert only the repo-side half — the job name: literals — because the required SET is unreadable. It is readable. The half of 红的 ESLint job 没有拦住合并:PR #5584 在 ESLint 已红 19 分钟的情况下过队合入 —— main 的 required-status-check 集需要维护者核查 #5617 that has no signal today (a context silently dropped from Settings leaves the whole family advisory) is mechanically checkable: read the ruleset, diff it against REQUIRED_CONTEXTS, and fail on a registry row whose context is absent from the live set.
2. It closes an open needs-user-decision card without a maintainer look. finding: required-context registry pins Build Docs and Console Pin Gate, absent from the maintainer's 2026-08-18 six-item required-set reading #9533 asks whether Build Docs / Console Pin Gate were removed from the ruleset after 2026-08-09 or whether the maintainer's six-item reading was partial, and states — from this same premise — that "only the maintainer can tell them apart". The live ruleset above is the answer: the six-item reading is complete, and those two contexts are genuinely absent. (Comment with the same measurement posted on finding: required-context registry pins Build Docs and Console Pin Gate, absent from the maintainer's 2026-08-18 six-item required-set reading #9533.)
3. A stale premise in a gate header is load-bearing prose. It is quoted in lint.yml, in finding: required-context registry pins Build Docs and Console Pin Gate, absent from the maintainer's 2026-08-18 six-item required-set reading #9533, and in the The ESLint required context carries ~54 check:* gates, so every one of their failures mis-routes its own diagnosis — and the rename needs a Settings change no agent seat can make #9325 rename procedure, all of which reason from "unreadable" to "maintainer-present sitting".

What a fix would have to be careful about

Not a mechanical edit, which is why this is a card:

• Token dependence. The 200 above was measured from one seat. Whether the token available to a CI job can read the ruleset is a separate measurement — GITHUB_TOKEN in a workflow is not this seat's token, and a gate that goes red because it cannot read the ruleset would be worse than one that never tried. The obvious shape is: read it when reachable, and treat unreachable as "not verified" stated in the output, never as a pass (check:react-declaration-parity 是唯一没接进任何 workflow 的源码审计门禁,且无 MANIFEST 时静默 skip 退出 0 —— 它现在永远不可能红 #4690).
• Which direction to enforce. Registry-row-not-in-live-set and live-set-entry-not-in-registry are two different findings with two different remedies; finding: required-context registry pins Build Docs and Console Pin Gate, absent from the maintainer's 2026-08-18 six-item required-set reading #9533's discussion and PR governance: human merge is the review record — retire the per-PR ADR approval check, add the report-only governed-merges audit #9523's tombstone precedent bear on the first.
• The header, the lint.yml step comment, and the prescription all have to move together, or the next reader inherits the retired premise from whichever copy they open.

Ref: #5617 · #6865 · #9325 · #9495 · #9533 · PR #9523

---

Generated by Claude Code

[os-steve]

Claiming this card.

• session: session_01XqDQYVU5smx29ts9pAErja (os-dev seat, dispatched)
• branch: claude/issue-9642-ruleset-readable
• worktree: ../objectstack-9642

Planned file surface (declared for parallel-agent serialization):

• scripts/check-required-contexts.mjs (header prose at ~:79, failure prescription at ~:855, plus a possible live-ruleset assertion depending on the H1 safety measurement)
• .github/workflows/lint.yml (step comment repeating the retired premise)
• possibly one new/updated test under scripts/__tests__/ if the assertion ships

Reading configuration only — no write of any kind to /rulesets. Governed surfaces (docs/adr/**, .claude/**, skills/**, AGENTS.md, CLAUDE.md) will be reported in the PR body for a maintainer edit, never touched.

---

Generated by Claude Code

[os-steve]

Claim amendment — declared file surface, same round.

The H4 sweep found a fourth site carrying the same conflation, beyond the three the card names:

• scripts/check-partof-closing-keyword.mjs (header, around line 101): "whether that check run becomes a REQUIRED context is a settings change no agent seat can make (the protection endpoint answers 403 here)".

Its conclusion (a seat cannot WRITE the settings) is correct; the parenthetical cites the wrong endpoint's 403 as the evidence, which is the same conflation propagating. Taken in-place under the bounded-fix exemption — same defect class, mechanical, comment-only, no new verification surface, same check:* gate family (pnpm check:partof-closing-keyword green), and no other open PR claims that file. Named with its evidence in the PR body.

Amended surface: scripts/check-required-contexts.mjs, .github/workflows/lint.yml, scripts/check-partof-closing-keyword.mjs. No test file was added — the new predicates live in the script's own --self-test, which the required Lint & Repo Gates job already runs.

Nothing under .claude/** or skills/** carries the premise (swept, clean) — the two governed-surface items the sweep did surface are filed as #9677 and #9678, unassigned.

---

Generated by Claude Code

[os-steve]

{
  "issue": 9642,
  "status": "done",
  "branch": "claude/issue-9642-ruleset-readable",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/9679",
  "premise_still_valid": true,
  "summary": "H1 VERDICT: the live read is token-safe but must NOT be merge-blocking, and the decisive reason is structural rather than flakiness. Token half: GitHub prices the ruleset endpoints at metadata=read (its own X-Accepted-GitHub-Permissions header) — the baseline no token can give up and not one of the 17 a workflow can toggle — while the classic branch-protection endpoint wants administration=read, which is not in that settable list at all, so it is unreachable from CI by construction. lint.yml's lint job has permissions: contents: read and would need no addition and no PAT. Blocking half: the settings half of any required-set change is maintainer-only and lands AFTER the merge (the #9325 two-step), so a required check reddening on registry-vs-settings disagreement would be red on precisely the PR carrying the repo half and could never go green before merging — a deadlock no token quality fixes. So this PR is prose + capability, not prose + required gate: it corrects the premise in all three sites the card names plus a fourth the sweep found, and adds report-only `--verify-required-set` in check-governed-merges' posture (sweep completes = exit 0 with 0 or N findings; unreachable = NOT VERIFIED, exit 2, never a pass). Three self-test assertions now pin that the pin stays network-free and that no workflow step and no package script wires the live read onto the required path — wiring it becomes a maintainer's deliberate act that reddens here first.",
  "tests": "All at final commit 7ab79908d, re-run after it. pnpm check:required-contexts exit=0 (115 self-test assertions, up from 112; pin green, 8 contexts pinned across 2 workflows) · pnpm check:partof-closing-keyword exit=0 (28 cases) · pnpm check:nul-bytes exit=0 (6183 files, no raw control bytes) · pnpm check:node-version exit=0 · pnpm check:workflow-status-functions exit=0 (25 workflows, 44 jobs) · pnpm check:shard-attestation exit=0 · pnpm check:type-check-coverage exit=0 · npx eslint on both changed scripts exit=0. Gate set derived with node scripts/pm/dispatch-gates.mjs on the three changed paths; that derivation also names check:type-check-debt, which REFUSES to run locally without the whole workspace dist/ closure built ('--re-measure cannot run: 55 workspace dependenc(ies) ... have no built type entry point on disk') — it matched only because a workflow file changed, its inputs are TypeScript packages, and this diff touches no TypeScript. Live run of the new mode against the real ruleset: '6 live required context(s) on main, 2 registered-but-not-required, 0 required-but-unpinned' with Build Docs and Console Pin Gate named under direction A. REVERSE VERIFICATION — six ablations, each reverted from the committed state, all red in the predicted direction: advisory:[] -> red; direction B disabled -> red; evaluate-mode counted as enforcing -> red; await fetch() inside main -> red on 'the pin (main) stays network-free'; the live read added as a step in the required lint job -> red; the live read added as a check:* package script -> red. No ablation was needed on dist/ (nothing here runs from a build). CI at report time: 10 success, 10 skipped, 3 in_progress, 0 failures.",
  "open_questions": [],
  "out_of_scope_findings": [
    "filed as #9677: AGENTS.md (~line 347) tells every seat 'the queue enforces only ... Lint & Repo Gates and TypeScript Type Check ...; everything else is advisory and rides through' — the live ruleset requires six contexts, so Test Core, Dogfood Regression Gate, Build Core and Temporal Conformance are described as advisory while they block. Governed surface, not touched.",
    "filed as #9678: the live required-set diff has no standing caller — the natural slot is the PM round report, which lives under .claude/skills/pm-dispatch/** (governed). Without one, only its offline self-test runs anywhere."
  ]
}

H2 directions chosen — both, report-only, different owners. Direction A (registry row absent from the live required set) = that gate family is advisory today with no signal, #5617's unsignalled half verbatim; remedy is the maintainer's. Direction B (live required context with no registry row) = a required context whose job name: literal nothing pins, so a rename detaches it silently; remedy is a dev's registry row. Reporting only A would have missed the shape the file exists to prevent; only B would have missed the incident that caused it to be written. Neither is judged. Two shapes the diff refuses to get wrong, both self-tested: an evaluate/disabled ruleset contributes a SHADOW set and never counts as required, and a ruleset whose conditions.ref_name misses the default branch is ignored; org rulesets are read via includes_parents=true, and any unreadable listed ruleset is an environment failure rather than a partial reading.

H3 confirmed from my own read, not inherited: one ruleset main, id 12119582, active, target: branch, repository-sourced, include: ["~DEFAULT_BRANCH"], strict_required_status_checks_policy: false, six required contexts, Build Docs and Console Pin Gate absent, and includes_parents=true returns that same single entry so no org ruleset is missed. The card's first reading is the true one. Posted as a comment on #9533 that also closes the token caveat the earlier comment left open; its labels were not touched and its disposition question stays open — #9533 is not addressed by this PR.

H4 sweep — four sites in three files, not three in two. Corrected here: scripts/check-required-contexts.mjs header, its failure prescription, the lint.yml step comment, and scripts/check-partof-closing-keyword.mjs (bounded in-place exemption; declared in the amended claim comment above and named with evidence in the PR body). Governed and listed for a maintainer, not touched: AGENTS.md (#9677) and the missing PM round-report slot (#9678). .claude/** and skills/** swept clean — the premise never reached the governed instruction tree.

H5. Every corrected site now names both endpoints and says which one this repo uses, so a doubting reader tests the right URL. The header also records the trap that would re-create this defect from a different cause: in an agent container Node's fetch bypasses the session proxy and the read answers 401 — the NOT VERIFIED output detects that combination and says so rather than letting the next reader conclude "unreadable" (check-governed-merges.mjs and check-half-states.mjs share it, #7412).

One reviewer note: open PR #9645 also edits .github/workflows/lint.yml, in a different job region.

---

Generated by Claude Code