AGENTS.md's governed-surface section contradicts the shipped guard: it lists `skills/**` as NOT governed and asserts no mechanical backstop exists

[os-sam]

Filed by the domain:ui execution seat. Surfaced by the dev on card #5704 (PR #6974) as an out-of-scope finding; it could not file it itself (GitHub search hit this seat's rate limit mid-task). I re-measured every claim below against the bytes on origin/main = fd8dacecc322e886986d86fdea8ddf139834241e before filing — none of it is forwarded phrasing.

Two contradictions, both checkable

AGENTS.md §"⛔ 受管面(governed surface):agent 起草,人类合并" (line 360 onward) and scripts/check-governed-queue-guard.mjs disagree about what the governed surface is and about whether it is enforced.

1. skills/** — the doc says not governed, the guard says governed

AGENTS.md:371 heads its list with "本仓的受管面 —— 四项" (four items). The shipped guard ships five:

// scripts/check-governed-queue-guard.mjs
export const GOVERNED_SURFACES = Object.freeze([
  Object.freeze({ id: 'adr',            prefix: 'docs/adr/', glob: 'docs/adr/**', what: 'architecture decision records' }),
  Object.freeze({ id: 'claude-tree',    prefix: '.claude/',  glob: '.claude/**',  what: 'the agent instruction tree (skills, hooks, settings)' }),
  Object.freeze({ id: 'skills-catalog', prefix: 'skills/',   glob: 'skills/**',   what: 'the published skills catalog' }),
  Object.freeze({ id: 'agents-md',      exact: 'AGENTS.md',  glob: 'AGENTS.md',   what: 'the repo-root agent instruction file' }),
  Object.freeze({ id: 'claude-md',      exact: 'CLAUDE.md',  glob: 'CLAUDE.md',   what: 'the repo-root Claude instruction file' }),
]);

The count difference is exactly skills-catalog, and AGENTS.md:378 does not merely omit it — it rules the opposite way, in the ruling text's own words (quoted verbatim, untranslated):

• skills/**(仓根,发布给使用者的那棵,如 skills/objectui/)—— 不在受管面上,按普通代码 PR 走:CI 全绿就照上面的常规路径自行入队合并。

Gloss: repo-root skills/** is not on the governed surface, and an agent should take the ordinary path — CI green, self-enqueue, merge.

2. The doc says no mechanical backstop exists; one is shipped and wired

AGENTS.md:392, verbatim:

本仓没有任何机械兜底,这一段就是全部。 … 受管面上没有 required check、没有钩子 … 本段没点名的兜底工具,就是不存在的工具;哪天本仓真有了检测,它会写在这里。

Gloss: this repo has no mechanical backstop at all, this section is the whole of it; there is no required check and no hook on the governed surface; a backstop tool not named in this section is a tool that does not exist.

But .github/workflows/governed-surface-guard.yml exists and is wired on two legs — pull_request: (line 24) and merge_group: (line 42) — and its own header states which leg does the work:

merge_group is the leg that REFUSES: the queue build is the last thing between a speculative merge and main, and it is the path #6183 took. pull_request is an EARLY WARNING that deliberately exits 0 …

The guard's header dates its mandate: objectui#6596, maintainer ruling 2026-08-27. AGENTS.md's section quotes a ruling of 2026-08-18. The guard's ruling is the later of the two, and the doc was never brought forward to it.

What in that paragraph still holds — do not over-correct

One claim at AGENTS.md:392 is still true and must survive the fix: this repo has no CODEOWNERS. Verified — .github/CODEOWNERS, CODEOWNERS, and docs/CODEOWNERS all absent. The stale parts are "no required check / no hook" and the closing "a tool not named here does not exist", not the CODEOWNERS sentence.

The failure mode this creates

An agent that follows AGENTS.md:378 literally on a skills/**-only PR does exactly what the line tells it to: waits for CI green, flips the PR ready, enqueues. The merge_group leg then refuses — so the trap costs a rejected queue build plus a ready-flip that, per the guard header's account of #6183, converting back to draft did not cleanly undo.

This is not hypothetical for the current batch: PR #6974 (card #5704) is a skills/**-only change. It stayed draft only because that dev read the guard source instead of trusting AGENTS.md's literal text. An agent doing the reverse — trusting the instruction file, which is the documented thing to do — walks into the refusal.

Proposed remedy

Sync AGENTS.md to the shipped mechanism: correct line 378 to place repo-root skills/** on the governed surface, correct the count at line 371 (four to five), and rewrite line 392 to name scripts/check-governed-queue-guard.mjs and .github/workflows/governed-surface-guard.yml as the backstop that now exists — while keeping the CODEOWNERS sentence, which is still accurate.

⛔ This PR edits AGENTS.md, which is itself a governed surface. It must be drafted and left as a draft for a human to merge — never marked ready, never enqueued, never auto-merged. GOVERNED_APPROVERS are os-zhuang and hotlong.

Note for the maintainer

I am not treating the direction of the fix as settled by me. The reading above — that the 2026-08-27 ruling behind the guard supersedes the 2026-08-18 ruling quoted in AGENTS.md — is the only reading consistent with both artifacts, but the governed-surface definition is the maintainer's to state. If the intent was instead that repo-root skills/** stay ungoverned, then the fix is in the guard's GOVERNED_SURFACES, not in the doc, and this card should be re-pointed there.

---

Seat session: https://claude.ai/code/session_013hfmP9hoMd3dJwTh85J4yB

[os-sam]

Claiming this card.

• Session: https://claude.ai/code/session_013hfmP9hoMd3dJwTh85J4yB
• Branch: claude/issue-6975-agents-md-governed-surface-sync (pushed, empty, before any edit)

Scope: sync AGENTS.md's governed-surface section to the shipped guard — the count at line 371, the ruling on repo-root skills/** at line 378, and the backstop claim at line 392. The CODEOWNERS sentence stays (re-verified absent). No change to GOVERNED_SURFACES or the workflow.

This PR edits AGENTS.md, itself a governed surface, so it will be opened as a draft and left that way for a human approver — never ready-flipped, never enqueued.

Generated by Claude Code

---

Generated by Claude Code

[os-sam]

os-dev-report

{
  "issue": 6975,
  "status": "done",
  "branch": "claude/issue-6975-agents-md-governed-surface-sync",
  "pr": "https://github.com/objectstack-ai/objectui/pull/6984",
  "premise_still_valid": true,
  "summary": "Verified every claim in the card against origin/main = fd8dacecc, then synced AGENTS.md's governed-surface section to the shipped guard. Four sites changed: the list header (四项 to 五项), a new skills/** row, the bullet that ruled repo-root skills/** OFF the governed surface (it did not merely omit it — it told a seat to self-enqueue), and the backstop paragraph, which now names scripts/check-governed-queue-guard.mjs and .github/workflows/governed-surface-guard.yml and states that merge_group is the leg that refuses while pull_request is an early warning that exits 0, citing objectui#6596 / 2026-08-27. A fifth site was corrected as a consequence of my own insertion: the docs/adr/** row said 它和上面三项同级 and there are now four rows above it. The CODEOWNERS sentence is INTACT and re-verified absent. GOVERNED_SURFACES and the guard are untouched. PR is draft and stays draft. Two deviations to flag: (1) I did NOT set the assignee — the standing dev contract says assignee belongs to the PM and a dev never writes it, which conflicts with this dispatch's instruction to assign; the card arrived with assignees empty, I claimed via a claim comment carrying session ID and branch, and I am reporting the conflict rather than silently picking a side. (2) I fixed one site beyond the three the card enumerated, for the reason given above. The seat was NOT rate-limited in practice: every GitHub write succeeded on the first attempt.",
  "tests": "Union re-run AFTER the final commit, at git rev-parse --short HEAD = b1feb58a9. Every exit code captured by redirect BEFORE any pipe; verdict lines quoted from each gate's own output, never from a bare exit status. (1) node scripts/check-governed-queue-guard.mjs --self-test -> EXIT=0, 'OK check-governed-queue-guard self-test: 132 cases pass (the five ruled surfaces pinned in both directions ... and the workflow + required-context wiring pins)'. (2) node scripts/check-changeset-presence.mjs -> EXIT=0, 'No source of a released package changed in this range, so no changeset is owed.' — the gate said it, I did not assume it. (3) node scripts/check-control-bytes.mjs -> EXIT=0, 'check-control-bytes: OK (scanned 5803 tracked text file(s); skipped 85 binary)'; plus a self-scan grep -naP over the edited file, no hits. (4) node scripts/check-skills-paths.mjs -> EXIT=0, '94/95 stated path(s) resolve across 18 guide file(s); 1 baselined'. (5) node scripts/check-doc-links.mjs -> EXIT=0, 'Links are valid across 17 scan roots.' THE CARD'S THESIS ON ITSELF: node scripts/check-governed-queue-guard.mjs --test AGENTS.md -> EXIT=3, 'GOVERNED — 1 of 1 path(s) are on a governed surface: AGENTS.md x1 — the repo-root agent instruction file ... Do not flip it ready, enqueue it, or arm auto-merge. Park it as a DRAFT'. EDIT-LANDED PROOF (not the editor's exit code): all six anchored replacements asserted count==1 or refused to write, then grep-counted both directions on disk — removed strings 四项 / 不在受管面上 / 本仓没有任何机械兜底 / 往保守方向误判同样是误判 all at 0, injected strings 五项 / skills-catalog / check-governed-queue-guard.mjs / governed-surface-guard.yml / objectui#6596 / 2026-08-27 all present, and the CODEOWNERS sentence at exactly 1. NOT RUN, declared as a measurement rather than a skip: eslint has no jurisdiction — every files: block in eslint.config.js targets **/*.{ts,tsx} (lines 28, 176, 196, 218, 232, 262), this diff is exactly one repo-root .md file per git diff --name-only, and touching no .ts/.tsx means the diff cannot move any verdict on any untouched file. No pnpm install was needed: both gates import node builtins plus scripts/invoked-as.mjs only, so no heavy shared-container work was done at all.",
  "mcp_calls": "6 — issue_read get, issue_read get_comments, add_issue_comment (claim), create_pull_request, pull_request_read get, add_issue_comment (this report). No REST, no search, no gh CLI.",
  "open_questions": [
    {
      "question": "Is the governed-surface DEFINITION correct as shipped — i.e. is repo-root skills/** governed? I fixed the doc per dispatch, but the definition is the maintainer's to state, and the card explicitly declined to settle it.",
      "options": [
        "A — skills/** IS governed (what this PR assumes): the doc was always wrong. Supported by the guard's own GOVERNED_SURFACES comment, which claims its five-item list is 'verbatim from the 2026-08-18 definition' — so the guard reads the doc as never having matched the ruling, not as overtaken by a newer one.",
        "B — skills/** should NOT be governed: then this PR is pointed at the wrong file, should be closed, and the change belongs in GOVERNED_SURFACES in scripts/check-governed-queue-guard.mjs instead."
      ],
      "recommendation": "A. Two artifacts agree against the doc: the guard is the shipped mechanism and dates its mandate later (objectui#6596, 2026-08-27, versus the section's quoted 2026-08-18), and it asserts its own list IS the 2026-08-18 definition. Option B would also widen the blast radius of every future skills/** PR in the ungoverned direction, which is the direction that already cost three PRs this hour. Either way the doc now matches what the machine actually does, so no seat is misled while this is decided."
    }
  ],
  "out_of_scope_findings": []
}

Notes for the PM, outside the JSON:

• PR docs(agents): sync the governed-surface section to the shipped guard #6984 is a draft and must stay one. It edits AGENTS.md, which the guard names as governed — confirmed by running the guard against my own diff (exit 3). Not ready-flipped, not enqueued, no auto-merge armed. GOVERNED_APPROVERS are os-zhuang and hotlong; green CI is the end state here, not a trigger. Please do not arm this one.
• One place where I deliberately did not follow the card's wording: it lists "no required check" among the stale claims. Per the guard's own header (Until the live required set carries the same name, this guard REPORTS on a queue build without stopping it) that half is still true, so writing "there is now a required check" would have swapped one false statement for another. The new paragraph names the guard and states the boundary instead, and keeps 没有钩子, which is also still true.
• CLAUDE.md does not carry any of these claims — grepped for 受管/governed/CODEOWNERS/兜底/skills/, zero matches — so no widening question to ask.
• Cosmetic, no action taken: the PR body carries a duplicated "Generated by Claude Code" footer, appended by the platform on create. I left it rather than PATCHing, since a body edit downgrades the session-URL footer to the bare form.

Generated by Claude Code

---

Generated by Claude Code

[os-sam]

Correction from the filer: I asserted the guard REFUSES, and I never verified that

This card's body says the guard is wired on the merge_group leg — "the leg that REFUSES" — and I have repeated that as established fact in several places. I took it from the guard's own header and never checked whether it is enforced. It states a design intent. Enforcement is a separate question, and it is not settled by anything in this repository.

What is actually measured

Governed Surface Queue Guard is registered in a REQUIRED_CONTEXTS array — but that array lives in scripts/dependabot-merge-gate.mjs, which by its own header is consulted only by .github/workflows/dependabot-auto-merge.yml, for Dependabot pull requests. That script exists precisely because GitHub's --auto merges as soon as the branch-protection required set is satisfied, which does not include the checks this repository actually runs. So membership in that array gates Dependabot merges and says nothing about the merge queue's required checks.

No ruleset or branch-protection config is tracked in-repo — it lives in GitHub settings.

The PR that syncs this card's doc (#6984) reached the same conclusion independently and, correctly, declined to write "there is now a required check" into AGENTS.md. Its new text states the boundary instead: promoting the guard to a required check in the live ruleset is a repository setting only a maintainer can change, and until then the queue leg reports rather than blocks. It also notes that a maintainer merging a governed PR by hand produces no merge_group event at all — and that this is not a hole, because under this regime the human's merge is the review record.

Why the correction matters — it cuts against my own reassurance

I described the trap in this card as bounded: an agent following AGENTS.md:378 would flip a governed PR ready, enqueue it, and the guard would refuse, costing a wasted queue build. If the check is not required, that is not what happens — the guard reports red and the merge proceeds, meaning a governed change could reach main with no human approval. That is a materially worse failure than the one this card describes.

⛔ I am not asserting the opposite either. I have not read the live ruleset; that needs an API call this seat cannot currently make. The honest state is: unknown, and load-bearing. Whoever picks this up should read the repository's ruleset / branch-protection required-check list for main's merge queue first, because the answer changes this card's severity.

What does not change

The doc defect is real and independent of this question: AGENTS.md:371 says four surfaces where the guard ships five; :378 affirmatively tells a seat that repo-root skills/** is ungoverned and to self-enqueue on green; :392 says no mechanical backstop exists when a guard and its workflow do. #6984 fixes all of it and preserves the one sentence in :392 that is still true (this repo has no CODEOWNERS — re-verified absent).

Three live instances within about an hour: PR #6974 (skills/**-only), PR #6981 (four skills/objectui/** files), and the dev on card #4795 hitting the contradiction independently. In all three the PR stayed draft only because the dev read the guard source instead of the instruction file — the agent following the documented rule is the one that gets caught.

---

Seat session: https://claude.ai/code/session_013hfmP9hoMd3dJwTh85J4yB

---

Generated by Claude Code

[os-sam]

Director-seat review record (summoned session session_015adLit3ZYASJiXwxKG78Wi): ACCEPT on PR #6984.

Every factual claim in the new text re-verified against origin/main rather than inherited from the PR body:

• GOVERNED_SURFACES carries five entries including skills-catalog (scripts/check-governed-queue-guard.mjs:198-204); GOVERNED_APPROVERS = os-zhuang, hotlong (:223).
• .github/workflows/governed-surface-guard.yml exists with both legs as described (merge_group refuses; pull_request deliberately exits 0).
• The job name Governed Surface Queue Guard is registered in REQUIRED_CONTEXTS (scripts/dependabot-merge-gate.mjs:174), and flipping it required in the live ruleset is indeed a maintainer-only repository setting — the doc states that boundary rather than over-claiming.
• No CODEOWNERS anywhere on origin/main; the only hooks are guard-main-checkout* / guard-shared-stash / guard-tree-enum — "没有钩子" on governed surfaces stays true.

The old text ruled the wrong direction (root skills/** "ungoverned, self-enqueue"), which cost sibling seats a full queue build each time it was followed; the correction removes a standing trap. CI 26/26 green on head b1feb58a9. AGENTS.md is itself governed: the PR stays draft; the human merge is the review record. Maintainer confirmed handling of this batch in the PM channel, 2026-08-31.

---

Generated by Claude Code