finding(docs): AGENTS.md states the changeset rule as src/ only — already narrower than the gate since #5733, and narrower again after #6736

Found while implementing #6736 (widening scripts/check-changeset-presence.mjs to read published-contract fields of a package manifest). Filed, not fixed there: AGENTS.md was outside that card's declared file surface, and the correct fix covers two separate widenings at once, so it is better taken deliberately than ridden in.

What is stated

AGENTS.md line 161 states the rule the gate enforces:

改完代码提交时:只要改了发版包的 src/(.changeset/config.json 的 fixed 组,含 apps/console),就必须新增一个 .changeset/*.md

src/ is the whole population that sentence names.

What the gate actually guards

The gate's population has been wider than that for two landings now, and this sentence tracked neither:

objectui#5733 added the published-executable clauses. A changed file counts when it is under src/, OR it is the package-root index.html build entry, OR the package's own files list publishes it verbatim (minus documentation and licences). On this tree that is three real files outside src/ — apps/console/index.html, apps/console/plugin.ts, packages/runner/index.html.
objectui#6736 added a second question asked of the manifest itself: eight named fields (sideEffects; exports, main, module, types; files; peerDependencies, engines) are compared by value across the diff, and a move in any of them owes a declaration even when no file under src/ changed.

So an author who reads AGENTS.md and reasons "I did not touch src/, nothing is owed" gets the opposite answer from CI in two distinct ways.

Why it is worth a card and not a silent patch

This is agent-facing text. AGENTS.md is an input to every seat, every session, so a rule stated too narrowly is not paid once — it is paid by every reader, and it is paid in the direction that produces a red CI run the author believes is a false positive. That is the same amplifier scripts/check-shell-escape-residue.mjs's header records for its own class of bad agent-facing example.

The gate's own docblock is the accurate statement of the rule in both respects; the fix is to make line 161 agree with it (and to keep pointing at node scripts/check-changeset-presence.mjs as the local self-check, which line 163 already does correctly).

Not asserted here

Whether AGENTS.md should restate the population in full or compress to "run the gate; its header is the rule" is a judgement about how much of a moving surface belongs in agent-facing text. Both were considered and neither is recommended from here — it is the kind of choice worth taking once rather than inheriting from a rider on an unrelated PR.

Triage — R+124. Re-routed only: domain:devx → domain:skills. ⛔ Grading deliberately NOT done — see below. Not claimed, not dispatched.

Why the lane changes

The fix lands in root AGENTS.md. The skills lane's scope covers 指令架构文件 — 根 AGENTS.md + 根 CLAUDE.md(所有面向 agent 的宪法文本) — so this is that lane's surface, ⛔ not devx's, even though the subject is a changeset gate.

⭐ Independently corroborated this session: AGENTS.md is a governed surface in its own right. scripts/pm/check-governed-merges.mjs:641 lists it as id: 'agents-md' with an exact matcher, alongside CLAUDE.md, .claude/**, skills/** and docs/adr/**. ⇒ A change to it is a governed merge, which is the skills lane's territory by construction.

⚠️ Same principle as the four domain:ui → domain:spec re-routes I made this session, applied to a different pair: the lane follows where the fix lands, not what the card is about. A card about a gate whose fix is one line of agent-facing prose is not a gate card.

⛔ Why I am NOT grading it

domain:skills findings are self-triaged by that seat (全仓轮跳过). ⇒ Assigning priority or a pm:* state here would be this seat overriding that arrangement. The label stays finding, ungraded, and it now sits in the queue of the seat that owns it — which is the whole point of the re-route: a card in the wrong lane never reaches the seat that would self-triage it.

Verification — the card is still live, tree `origin/main` `d04e79a`, read 2026-09-03T18:05:55Z

What AGENTS.md says (:161, verbatim): 只要改了发版包的 src/(.changeset/config.json 的 fixed 组,含 apps/console),就必须新增一个 .changeset/*.md.

What the gate actually tests — scripts/check-changeset-presence.mjs:112-115 defines a three-clause population:

(a) it is under <pkg>/src/; or
(b) [a package-root NAME test — :154: "Clause (b) tests the NAME, not the bundler config"]; or
(c) the package's own package.json files list publishes it verbatim

⇒ Clauses (b) and (c) both reach files outside src/. The prose states only clause (a).

⭐ The script's own header says as much at :87 — "<pkg>/src/ is where nearly all of a package's published source is. It is not …" — so the narrowing is documented as incomplete at the source, and only the agent-facing prose still claims it.

⇒ The card's claim holds as written. ⛔ I did not re-derive the #5733 / #6736 history it cites — the current-tree divergence is enough to establish the card is live, and history reads here would need a deepen I did not perform.

For the skills seat

⚠️ The obvious fix — restate AGENTS.md:161 as the three clauses — has a trap worth naming: :161 is prose an agent acts on before running the gate, and the three-clause form is materially harder to apply from memory than "did I touch src/". ⇒ Worth considering whether the honest correction is to state the clauses or to point at node scripts/check-changeset-presence.mjs as the authority and stop paraphrasing it. :163 already tells the reader to run exactly that. ⛔ Not my call, and ⛔ not a recommendation — recording the fork because the cheap fix (paraphrase harder) is the one that rots again.

Generated by Claude Code

Self-triaged into the skills lane and dispatched (the lane owns root AGENTS.md; the re-route above is accepted as filed). Graded priority:p2: the sentence is agent-facing constitution text that every session reads before running the gate, and it states a population narrower than the gate's in two independent ways — a reader who follows it gets a red CI run they believe is a false positive. The fix is one sentence in one governed file.

The card's open judgement (restate the population, or point at the gate) is decided here as routine: the sentence states the population in plain words — the three file shapes and the manifest-field clause — AND names scripts/check-changeset-presence.mjs's header as the authoritative statement; no incident narrative is added.

Claim: PM loop round 5
Session: session_019RfFHiRCSs3JXLK4cwcfox
Branch: claude/issue-6997-agents-changeset-population
Worktree: objectui-issue-6997
Domain: domain:skills
File surface: AGENTS.md (objectui root) — the changeset sentence under "Housekeeping" and its own bullets only (stop on breach; explain in the report). ⛔ No edit to scripts/check-changeset-presence.mjs, to skills/** or to .claude/**.
Container & model: S (one prose sentence, no code; objectui carries no dispatch-gates.mjs, so the tier is the seat's reading of the surface), mode:subagent, model: opus
Clause-②: no (prose that describes an existing gate; the gate's behaviour and the published contract are unchanged)
Serial constraints cleared: no open objectui PR touches AGENTS.md (the seven open PRs are code, dependency bumps and the release PR); the two AGENTS.md PRs of this shift are MERGED. Governed (AGENTS.md is an exact matcher of check-governed-queue-guard.mjs) ⇒ draft PR, in-seat review, both approvers requested by the seat, human merge — never ready, never enqueued from the seat.

Decision re-read (13:44Z): no maintainer ruling is owed before this lands; the card's one judgement is routine and decided above.

Generated by Claude Code

os-dev-report

{
  "issue": 6997,
  "status": "done",
  "branch": "claude/issue-6997-agents-changeset-population",
  "pr": "https://github.com/objectstack-ai/objectui/pull/7640",
  "premise_still_valid": true,
  "summary": "Rewrote one sentence in root AGENTS.md under `### Housekeeping` (line 161; file still 558 lines, 1 insertion 1 deletion, nothing else touched). BEFORE: 只要改了发版包的 `src/`(`.changeset/config.json` 的 `fixed` 组,含 `apps/console`),就必须新增一个 `.changeset/*.md` — `src/` was the whole stated population. AFTER: 只要改了发版包(同一 `fixed` 组括注保留)的已发布可执行源码 —— `src/` 下的任何文件、包根的 `index.html` 构建入口、或该包 `package.json` 的 `files` 列表逐字发布的文件(后两类减去 `*.md` 与 `LICENSE*`,`src/` 下不减)—— 或者挪动了该包 `package.json` 里八个发布契约字段(`sideEffects`、`exports`、`main`、`module`、`types`、`files`、`peerDependencies`、`engines`)之一的值(哪怕一个源码文件都没动),就必须新增一个 `.changeset/*.md`;判据的权威表述是 `scripts/check-changeset-presence.mjs` 的文件头,这段话与它不一致时以它为准. Both halves of the seat's ruling are in: the population stated in plain words AND the gate header named as authoritative. Written from the CODE (`isPublishedSource` at scripts/check-changeset-presence.mjs:751, `isDocumentation` at :730, `CONTRACT_FIELDS` at :813), which agrees with its own header on all three clauses, on the (b)/(c)-only documentation subtraction, and on all eight field names — one cosmetic difference reported in the PR body and NOT acted on: the header's shorthand is `LICENSE*` while the code matches /^LICEN[SC]E/i, i.e. the British spelling too. The existing tail after 这一条由 … is byte-identical (verified programmatically). Both child bullets re-read and left untouched: neither the old feature/bug-fix criterion bullet nor the local self-check bullet contains a word the widened rule contradicts. No changeset added, no script touched, no other file touched.",
  "tests": "Gate union re-run AFTER the final commit, on head c20e2a8 (git rev-parse --short HEAD from that run); every exit code captured by redirect-then-capture, never through a pipe. (1) `pnpm check:control-bytes` EXIT=0 — verdict: '✅ check-control-bytes: OK (scanned 6242 tracked text file(s); skipped 85 binary).' (2) `node scripts/check-changeset-presence.mjs` EXIT=0 — verdict: 'Compared the working tree with 2e99852ca (merge-base with origin/main): 1 file(s) changed, 0 of them published source of a package the release covers, 0 of them a manifest whose published contract moved, 0 under a package changesets ignores, 0 changeset(s) added.' / '✅ No source or published contract of a released package changed in this range, so no changeset is owed.' — the gate itself says none is owed for this root-AGENTS.md-only diff, so none was added. (3) `pnpm check:shell-escape-residue` EXIT=0 — verdict: '✅ check-shell-escape-residue: OK (5/5 root(s) resolved -- AGENTS.md: 1 file(s), 15 fence(s); CLAUDE.md: 1 file(s), 0 fence(s); skills: 16 file(s), 210 fence(s); .claude/skills: 4 file(s), 20 fence(s); content/docs: 184 file(s), 1060 fence(s); 206 file(s) and 1305 fenced block(s) examined in total; 0 occurrence(s) outside a fence).' (4) `pnpm check:governed-queue-guard` EXIT=0 — verdict: 'OK check-governed-queue-guard self-test: 132 cases pass (…)'. (5) `pnpm check:doc-fences` EXIT=0 — verdict: '✅ check:doc-fences — every TypeScript block in 227 document(s) is fenced ts/tsx/typescript, except 80 declared file(s) carrying 90 block(s) … (⛔ SHRINK-ONLY).' (6) `node scripts/check-doc-links.mjs` EXIT=0 — verdict: 'Links are valid across 17 scan roots.' — AGENTS.md is in its population with rule 'disk' (scripts/check-doc-links.mjs:609); its header at :384 records that AGENTS.md carries no markdown links because its paths are code spans, which stripCode() blanks, so the backticked identifiers added here are not link candidates. Self-scan beyond the gate: `grep -naP '[control-byte class]' AGENTS.md` exit 1 (no match) on the edited file and again on the PR body before posting. CLAUDE.md grep: `grep -n changeset CLAUDE.md` exit 1 — ZERO hits, so objectui's CLAUDE.md does not restate the narrow `src/` rule and needs no companion fix. Also checked QUICK_REFERENCE.md (mentions changeset commands and the `fixed` group only, never the `src/` criterion) and skills/ + .claude/ (no restatement). Pin-test check before editing: grepped every scripts/__tests__ file that mentions AGENTS.md — none asserts on this sentence's text (check-changeset-presence.test.ts's only AGENTS.md mention is a comment at :270; check-governed-queue-guard.test.ts pins AGENTS.md as the 'agents-md' exact matcher, unaffected by content). Derived-gate derivation: objectui carries no scripts/pm/dispatch-gates.mjs, so the population was derived by hand — grep for AGENTS.md across scripts/ and .github/workflows/, plus an enumeration of every workflow lacking a `paths:` filter. NOT run, with reasons: `check-links.yml` drives lychee over external URLs and this diff adds none; `ci.yml`/`lint.yml` do start on a markdown-only PR but their in-job 'Decide whether this change needs a full run' switch excludes `**/*.md`, so their expensive steps skip; the live (non-self-test) leg of governed-surface-guard.yml needs the PR and the API and is CI's to run; no `pnpm test` suite is owed because no script or source file was edited. Declared narrowing: `pnpm install` was NOT run in the worktree. Evidence it changes nothing measured here — all six gate scripts import only node: builtins plus the sibling scripts/invoked-as.mjs (verified by grepping their import lines), and no vitest suite is owed for a prose-only diff. No ablation is meaningful for a prose change, and none was performed.",
  "mcp_calls": "0 — every GitHub read and write went through repo-scoped REST with curl and $GITHUB_TOKEN (issue body, comments, PR create, PR read-back, comment read-back). Zero GitHub MCP calls.",
  "open_questions": [],
  "out_of_scope_findings": []
}

Generated by Claude Code

ACCEPT — governed in-seat review of PR #7640, head c20e2a88 (skills seat, 2026-09-04T13:56Z).

Implemented-by: claude/issue-6997-agents-changeset-population (os-dev subagent)
Reviewed-by: session_019RfFHiRCSs3JXLK4cwcfox (skills seat)

Verified in a detached compare worktree at the PR head, not from the report:

One line, one file. git diff origin/main --stat = AGENTS.md | 2 +- (1 insertion, 1 deletion); the file stays 558 lines. The changed line is the changeset sentence under ### Housekeeping; both child bullets and the sentence's tail after 这一条由 are byte-identical to main.
Both halves of the ruling are in the sentence. The population is stated in plain words for all four clauses the gate implements (src/ files; the package-root index.html entry; files the package's files list publishes, the two latter minus *.md/LICENSE*; a value move in any of the eight published-contract fields of the package's manifest), and the gate's header is named as the authoritative statement. I read the sentence against scripts/check-changeset-presence.mjs on main (isPublishedSource, isDocumentation, CONTRACT_FIELDS): every clause in the PR body's clause-by-clause table is faithful. No incident narrative was added; the one pre-existing citation in the tail is untouched.
Gates at the head, exit codes captured by redirect: node scripts/check-changeset-presence.mjs exit 0 — 1 file(s) changed, 0 of them published source of a package the release covers, 0 of them a manifest whose published contract moved … No source or published contract of a released package changed in this range, so no changeset is owed (so no changeset is added, by the gate's own verdict); node scripts/check-control-bytes.mjs exit 0 (6242 files); node scripts/check-governed-queue-guard.mjs --self-test exit 0 (132 cases). PR checks at c20e2a88: 22 success, 3 skipped, 3 still running, none failed.
Report hygiene: dev report posted first on this card with the literal os-dev-report first line, JSON closes, footer intact; PR body starts Fixes #6997, carries the 改前 → 改后 table and the clause table for the two approvers, no model identifier, no issue number beyond the Fixes line; zero GitHub MCP calls.
One cosmetic reading the dev reported and did not act on, recorded here for the gate's owner: the header's LICENSE* shorthand is implemented as /^LICEN[SC]E/i (the British spelling too). Not a defect in this PR; no card filed.

Landing regime: root AGENTS.md is a governed surface ⇒ the PR stays a draft; reviewers os-zhuang + hotlong requested by the seat in this same act; human merge. ⛔ Not flipped ready, not enqueued, no auto-merge from the seat.

Generated by Claude Code

Claim: PM loop round 5 (canonical first-line form of the claim already posted as 5541296438 — same flight, same branch; posted so the patrol predicate that reads only a comment's first line finds it)
Session: session_019RfFHiRCSs3JXLK4cwcfox
Branch: claude/issue-6997-agents-changeset-population
Worktree: objectui-issue-6997
Domain: domain:skills
File surface: AGENTS.md (objectui root), the changeset sentence under Housekeeping.
Container & model: S, mode:subagent, model: opus
Clause-②: no
Serial constraints cleared: as read on 5541296438; delivered as PR #7640 and accepted (5541420935), at the governed terminal.

Generated by Claude Code

Navigation Menu

Repository navigation

finding(docs): AGENTS.md states the changeset rule as `src/` only — already narrower than the gate since #5733, and narrower again after #6736 #6997

What is stated

What the gate actually guards

Why it is worth a card and not a silent patch

Not asserted here

Why the lane changes

⛔ Why I am NOT grading it

Verification — the card is still live, tree `origin/main` `d04e79a`, read 2026-09-03T18:05:55Z

For the skills seat

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

finding(docs): AGENTS.md states the changeset rule as src/ only — already narrower than the gate since #5733, and narrower again after #6736 #6997

Description

What is stated

What the gate actually guards

Why it is worth a card and not a silent patch

Not asserted here

Activity

huangyiirene commented on Sep 3, 2026

Why the lane changes

⛔ Why I am NOT grading it

Verification — the card is still live, tree origin/main d04e79a, read 2026-09-03T18:05:55Z

For the skills seat

claude commented on Sep 4, 2026

claude commented on Sep 4, 2026

claude commented on Sep 4, 2026

claude commented on Sep 4, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

finding(docs): AGENTS.md states the changeset rule as `src/` only — already narrower than the gate since #5733, and narrower again after #6736 #6997

Verification — the card is still live, tree `origin/main` `d04e79a`, read 2026-09-03T18:05:55Z