docs(agents): state the attribution-footer append as conditional on absence

[huangyiirene]

Fixes #9563

维护者速读(草稿)

改了什么 —— AGENTS.md 里「GitHub 会改写你写进 issue/PR 正文的字节」那份清单的第 ③ 条,从「PATCH 无条件追加第二个 footer」改写成实测到的规则:缺了才补、只补一个 bare footer、评论 POST / 评论 PATCH / issue 正文 PATCH 三条通道同一条规则。原来的「恰好 58 字节、只加不减」那半句证据原样保留。只动这一条,①②④⑤⑥ 一个字没动。净 +2 行(1 行改写 + 2 条子条款),全仓没有第二处引用这句话。

为什么改 —— 这句话被实测证伪了,而且错在更危险的那个方向。它同时错两处:条件性说反了(实测是缺了才补,不是无条件),范围也窄了(不是 PATCH 独有)。信它的席位为了躲开「第二个 footer」,会先把自己的 footer 剥掉再发,于是发出去、也存下来一条一个 footer 都没有的正文 —— 这正是卡面点名的危害。写给 agent 读的规程说错一句,下一轮每个席位都照着错的做,所以这类缺陷按产品缺陷处理。

风险与代价(含回滚) —— 纯文档改动,零运行时影响,没有任何门禁读 AGENTS.md 的正文(它的读者是 agent,不是机器)。代价是这三行比原来的一行长:新文本额外写明了「哪一半在哪条通道上测过」和「仍空的那一格」。这是有意付的代价 —— 上一版正是因为把一次局部读数写成了普遍规则才出错,不标注测量边界就等于邀请下一次同样的过度概括。回滚 = git revert 这一个 commit,或直接关掉本 PR(尚未落地,零成本)。

席位意见 —— 技能席 1(session_01Wnstp2kTth7sGXfr8fXypc)已按 GitHub 与拉取的 head 074b86d 复核:只改第 ③ 条并加两条子项,①②④⑤⑥ 与两条建议行逐字节未动;改写后的规则与卡上四次写入、附录六次预登记写入、本席本班三次 PR 正文 PATCH(无 footer 发出各 +58)以及 dev 本轮两次预登记读数(已带 footer 发出 ⇒ 不追加)全部一致;子项如实标出未测的那一格与「+0 ≠ 逐字节相同」。objectui 自带的五个门禁本席在独立 worktree 复跑均 exit 0,check-governed-queue-guard --test AGENTS.md 读 GOVERNED(Tier H 依据)。复核记录 PASS 5773828366(席内 fable)。dev 的两个开放问题本席已定:POST /pulls 那条读数留在报告里不写进条文;空格子只在席位本就欠一次正文 PATCH 时顺便填、先登记预期。建议合并;姊妹卡 #9908 的 POST 一半由同一句解答,落地后按前提证伪关卡。

你要做的 —— 读一遍新的 ③ 和它下面那两条子条款,确认措辞;AGENTS.md 是受管面,本 PR 停在 draft 等你合并,席位 ⛔ 不翻 ready、⛔ 不入队、⛔ 不自己批准(seat-side check-governed-queue-guard.mjs --test AGENTS.md 退出 3 = GOVERNED,已实跑确认)。⚠️ 姊妹卡 objectui#9908 是同一条 ③ 的 POST 那一半:本 PR 的新句子已经把 POST 的行为写进正文了,所以 #9908 的前提由这同一段文字回答 —— 本 PR ⛔ 不认领、⛔ 不关闭它,那张卡另行处置。

---

改动

一个文件,一处 hunk:AGENTS.md,「GitHub 会改写你写进 issue/PR 正文的字节」小节的第 ③ 条(该小节六条清单的第三条)。+3 −1。

改之前(逐字)

• ③ PATCH 无条件追加第二个 footer —— 哪怕提交的正文已经以一个 footer 结尾。逐字节回读实测:存储的正文比发出的多恰好 58 字节,unified diff 只有那几行追加的 footer、没有内容被吃 ⇒ 与 ①② 都不同,这一种是加,不是减。

改之后 —— 主条款把规则改成「缺了才补 / 已有则不补」并点名三条通道,保留 +58 与「只加不减」的证据,末尾加上 ⛔ 永不剥自己 footer 的禁令;两条新子条款分别承担两件不能省的事:① 哪一半在哪条通道上被测过、以及仍空的那一格(issue / PR 正文 PATCH 送一条已带 footer 的正文);② +0 不等于逐字节相同(评论 POST 会改写分隔符:净零字节、53 个字符位不同),以及「平台认得出一个 footer」这个判据本身没被测过。逐字全文见本 PR 的 diff,报告 JSON 里也带一份。

证据(全部来自卡面与其 addendum,本 PR 不新增合成探针)

通道	发出的正文带 footer?	读数	来源
评论 POST	否 ×3	每次 +58,首个不同字节的下标 = 发出正文的末尾 ⇒ 纯追加	objectui#9563 行 1/3/4
评论 PATCH	是	0,sha256 相同,存储正文只以一个 footer 结尾;预测在发送之前登记	objectui#9563 行 2
issue 正文 PATCH	否 ×6	每次 +58,存储 = 发出 + footer 逐字节拼接;6 次预测全部提前登记、6/6 命中	objectui#9563 addendum
评论 POST	是	净 0 但不是同一串字节:53 个字符位不同,尾部换行被删、--- 之前插入一个换行	objectui#9563 addendum

⇒ 「无条件」被行 2 与 addendum 那一行直接证伪;「PATCH 独有」被三条 POST 读数证伪。⚠️ 仍空的那一格已在新文本里具名:没有人在受控条件下对 issue / PR 正文 PATCH 送过一条已以 footer 结尾的正文。

门禁(markdown-only diff;退出码在任何管道之前捕获)

命令	退出	判定
node scripts/check-control-bytes.mjs	0	check-control-bytes: OK (scanned 8216 tracked text file(s); skipped 85 binary).
node scripts/check-changeset-presence.mjs	0	No source or published contract of a released package changed in this range, so no changeset is owed.
node scripts/check-new-cross-file-line-citations.mjs	0	VERDICT new-cross-file-line-citations: 0 new citation(s), enforcement report-only -> exit 0
node scripts/check-doc-links.mjs	0	Links are valid across 17 scan roots.
node scripts/check-governed-queue-guard.mjs --self-test	0	OK check-governed-queue-guard self-test: 185 cases pass
node scripts/check-governed-queue-guard.mjs --test AGENTS.md	3	GOVERNED — 1 of 1 path(s) are on a governed surface —— 这是预期答案,不是红:它就是本 PR 停 draft 的依据

changeset:零。判据不是标签,是门禁自己:check-changeset-presence.mjs 印出「1 file(s) changed, 0 of them published source of a package the release covers」后退出 0。本仓 AGENTS.md 的规则也是这么写的 —— 只有发版包的已发布可执行源码或八个发布契约字段动了才欠 changeset。⇒ ⛔ 不加空 frontmatter changeset,那会是一次对着空气的声明;本仓 skip-changeset 标签零读者,⛔ 也不打。

不适用的:lint.yml 对 **/*.md 走 paths-ignore,markdown-only 的 diff 在它那里整个跳过(job 内还有一个同表的开关);本仓 scripts/pm/ 下只有 board-snapshot.mjs 与 check-half-states.mjs,没有 dispatch-gates.mjs,所以门禁族是从本仓 package.json 与 .github/workflows/ 手工推导的,推导过程见上表与报告。

并发

分支切自 origin/main 0cf2d66,收尾前重新 git fetch origin main:仍是 0cf2d66,且 git merge-base --is-ancestor origin/main HEAD 退出 0 ⇒ 无需合并,本分支已经在最新的 main 之上。

⚠️ 给后落地的人:本 PR 只碰 AGENTS.md 里那份六条改写清单的第 ③ 条。objectui#9992 改的是同一文件的 landing-flow 条款 —— 不同区段,两处 hunk 不重叠,后落地的一方合一次即可。

预登记的读数(发送之前写下,⛔ 不为测量而多写一笔)

本 PR 之后只剩一笔写入:objectui#9563 上那条 os-dev-report 评论,走 POST /repos/objectstack-ai/objectui/issues/9563/comments,发出的正文以 bare footer 结尾。

• 若新写的 ③ 为真(缺了才补):存储字节 等于 发出字节,且存储正文只以一个 footer 结尾;⚠️ 按 addendum 的分隔符改写,预期存在少量字符位不同而字节数净零 ⇒ 判定按首个不同字节的下标,⛔ 不按长度。
• 若旧写法(无条件追加)为真:存储 = 发出 +58,尾部两个 footer。

同一笔登记也覆盖创建本 PR 的 POST /repos/objectstack-ai/objectui/pulls:发出的正文以 session-URL 形式的 footer 结尾,按 ⑤ 预期原样保留或被归一化,按同一把尺回读。两个读数都进报告的 h2_reading,实际观察到什么就写什么。

Acceptance notes(⛔ 不在本 PR 修,也未立卡)

• PM 的 H1 假设有一半被证伪。派发词预期 ③ 下游挂着一条「先把自己的 footer 剥掉」的建议行。grep 全文 footer:只在 ② ③ ④ ⑤ 与两条建议行上命中,不存在这样的指令。剥 footer 的危害是读者自己推出来的,不是被明文教的 ⇒ 无依赖条款需要连带修,建议行未动。
• ② 与新 ③ 的一处张力,二手、未实测,故不立卡也不改 ②。② 说 PATCH 把 session-URL 形式的 footer 降级为 bare(一个 footer);而卡面转述的二手读数说 session-URL 形式被当成没有 footer、于是触发追加(两个 footer)。两者可能是同一现象的两种读法(只看尾部就会把「追加了一个 bare」读成「降级成了 bare」)。⛔ 本席没有自己的读数,⛔ 不在本卡权限内改 ②;新 ③ 的子条款已把这个判据标成未测,危害因此被围住。要坐实它,需要一次受控写入:发一条以 session-URL footer 结尾的正文,按首个不同字节的下标回读。
• pnpm install 未在本 worktree 跑(已申报的收窄):适用的六条门禁全是零依赖的 Node 脚本,已从裸 worktree 实跑出真实判定;为一个单文件 markdown diff 装整个 monorepo 会挤占并行席位共用的容器。

---

Generated by Claude Code

[github-actions]

changeset-claim-re-read

⚠️ 5 pending changeset(s) describe a file this change touches

Their bodies publish verbatim into the CHANGELOG at the next release, so this is a request to re-read them against your diff — addressed here because you are the one seat that can answer it without re-deriving anything.

⛔ Nothing here blocks, and nothing here is a verdict on your change. This gate exits 0, is not a required context, and judges name resolution, never meaning: it asked whether a pending body names a file you touched. "Is this sentence still true?" is the one question it will not answer, and the one you are being asked to answer.

.changeset/10106-settled-schema-equal-payload.md

• names AGENTS.md → AGENTS.md — edited by this change

  The hook refetches getObjectSchema whenever the adapter identity changes, and every consumer its doc comment instructs — ObjectGantt, ObjectCalendar, ObjectView, ObjectTimeline, ObjectGallery — keys its record fetch on the returned def, which is what AGENTS.md §5 commandment [WIP] Enhance every detail of the designer #10 tells a consumer to do (key on the payload, never on a memo identity). The producer half of that same sentence is what this fixes: a byte-identical answer arriving as a fresh object re-fired every one of those fetches, and the duplicate query carried the same $expand set as the one before it. Measured first-hand on ObjectGantt with an instrumented adapter, with a control swap in the same command; the counts, and the control that makes them a discrimination rather than a counting artefact, are asserted by packages/react/src/hooks/__tests__/useSettledSchema.equalPayload-10106.test.tsx (objectui#10106).

.changeset/6357-basechema-bind-declaration.md

• names AGENTS.md → AGENTS.md — edited by this change

  bind was read by ten production sites and declared by no schema shape. It resolved as any through BaseSchema's index signature and rode .passthrough() on the validator, while three separate documents taught it as an authorable key of every node: this repo's own AGENTS.md §4 ("Every node in the UI tree follows this shape (@object-ui/types)"), the published agent-facing skills/objectui/rules/protocol.md ("Every UI component node MUST follow this shape"), and content/docs/fields/grid.mdx. So the agent-facing protocol told authors to write a key the published types did not know existed.

.changeset/6505-predicate-valued-gate-rules.md

• names AGENTS.md → AGENTS.md — edited by this change

  The accept set widens to what the protocol already declares and the runtime already accepts, not beyond it. AGENTS.md §4 declares both keys as expressions, SchemaRenderer evaluates them through hasDeclaredPredicate + evaluateCondition, @objectstack/spec normalizes every authored predicate into a { dialect, source } envelope, and the objectui#3862 / objectui#3955 rulings are entirely about which expression spellings count as declared. This table was the one place in the repo that disagreed, so this restores declared = enforced rather than changing a contract.

.changeset/7122-spec-17-3-0-parity-reconciliation.md

• names AGENTS.md → AGENTS.md — edited by this change

  Two breaking consequences for a consumer that names the type directly. (1) It no longer declares editMode; the key is now carried by the spec's ServiceObject, so ObjectSchemaMetadata still has it, but code written against the extension type ALONE loses it. (2) interface → type alias also ends declaration merging: a consumer that reopened declare module '@object-ui/types' { interface ObjectSchemaClientExtensions { … } } to add its own client-side member no longer compiles, because an alias cannot be reopened. minor rather than major per AGENTS.md's version-alignment rule — objectui's own breaking changes are graded minor with the semantics stated in the body, since any major in the fixed group would push all 39 packages off @objectstack's major.

.changeset/7714-lookup-draft-stays-client-side.md

• names AGENTS.md → AGENTS.md — edited by this change

  minor rather than major per AGENTS.md: objectui's major tracks @objectstack's, so objectui's own breaking changes ship as minor with the breaking semantics stated.

Read the paragraph, not the line: both false halves of the objectui#8617 claim sat in one paragraph, and correcting either alone would have left it asserting the same wrong thing.

If a claim did go false, correct the body. That is precedented and prose-only, frontmatter untouched; check-changeset-overwrite.mjs will report the correction as its own case 2 ("correcting a declaration on purpose … legitimate"), which is the intended shape — one gate asks for the read, the other records the write.

Not covered, stated so nobody reads this as more: a born-false claim that spells no line address at all (objectui#9495 coordinated one by ORDINAL — "a grep finds that member first" — and deciding that means reading what the sentence means), a claim spelled as a symbol or a package rather than a backticked file name, and a file named ambiguously.

Compared the checked-out tree with 0cf2d6644 (merge-base with origin/main): 1 file(s) changed outside .changeset/, read against 1262 pending declaration(s) that publish a body (1829 pending in total). · run

[huangyiirene]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 074b86db91d561802347966bd2efa07571bf5361

① Derived judgments

Rendered in-seat by the skills seat 1 session at the served tier the maintainer named on this date (the fable tier word; ruling record objectstack#7623 comment 5771798588). The contract is the card's measured claim: the attribution-footer append is conditional on absence, not unconditional and not PATCH-only.

• (a) One clause moves, nothing else — right. git diff origin/main 074b86d -- AGENTS.md is +3 / −1: the third item of the six-item GitHub body-mutation list is rewritten (922 bytes) and gains two sub-bullets (521 and 864 bytes); items ①, ②, ④, ⑤, ⑥ and the two advice lines are byte-unchanged (measured by this seat: one line removed, three added, 589 → 591 lines). objectui has no AGENTS.md line ratchet or width cap; the file's own landing clause is a kilobyte, so the length is in style.
• (b) The rewritten rule is the measured truth — right. Sources, all first-hand: the card's four writes (+58 when absent on comment POST; 0 on comment PATCH with a footer already present), the addendum's six issue-body PATCH writes with pre-registered predictions (6 / 6, +58, verbatim concatenation), this seat's own PR-body PATCH writes this shift (10567 → 10625, 9225 → 9283, 15370 → 15428 — every one +58 with no footer sent, the one line in the new text the dev flagged as resting on the seat's reading, confirmed here), and the dev's two pre-registered readings in this run — POST /pulls with a session-URL footer: −1 (a stripped trailing newline), no append; the report comment POST with a bare footer: net 0, 53 separator positions rewritten, no append, one footer. The old sentence would have required two footers on the last two. The hazard the title names (a seat strips its own footer to dodge a duplicate and ships none) is now stated as the prohibition 「⛔ 永不剥自己的 footer」.
• (c) The two sub-bullets do not overclaim — right. The first names which half was measured on which channel and the one empty cell (issue / PR body PATCH sent a footer-terminated body) with 「⛔ 别把空格子读成已测」; the second states that a zero byte delta is not byte identity (the comment endpoint rewrites the separator: −1 trailing newline, +1 newline before ---), prescribes read-back by first differing byte index, and declares the footer-recognition predicate unmeasured, flagging the second-hand session-URL report as 「二手读数,⛔ 别当判据用」. The dev's own POST /pulls reading (a session-URL footer recognised as present) is kept in the report and not written into the clause — the seat takes the dev's option A: a reading on one endpoint is not evidence for another, and writing a near-miss in is the over-generalisation being repaired.
• (d) Cross-references — right. No new cross-file path:line citation (check-new-cross-file-line-citations.mjs reads 0 new; objectui bans them at AGENTS.md:108); the sibling objectui#9908 (the POST half) is answered by the same sentence and closes on its falsified premise at its take.
• (e) Gates — re-run by this seat on its own worktree at this head: check-control-bytes OK, check-changeset-presence (no changeset owed — 0 published source changed), check-new-cross-file-line-citations 0, check-doc-links valid, check-shell-escape-residue OK; check-governed-queue-guard.mjs --test AGENTS.md exit 3 — GOVERNED, the Tier H basis, not a red. objectui has no dispatch-gates.mjs; the gate family was derived by hand from package.json and the workflows, and lint.yml skips a markdown-only diff by its own paths-ignore — stated, not assumed.

② Semver level

None — a governed instruction file; no package source, no changeset owed (check-changeset-presence measured 0 published files), no label written (objectui path labels are labeler.yml's; documentation was applied by it).

③ Boundary flags

• pnpm install not run in the worktree — declared narrowing; every applicable gate is a dependency-free node script and produced a real verdict. Accepted.
• The dev sent both budgeted writes WITH a footer attached and predicted no append, instead of the seat's suggested 「sent + 58」 reading: the conditionality half is the one under test and the one where the card's row 2 and objectui#9908 disagree; both outcomes were safe for the artefact. A better measurement than the one asked for — accepted, and the predictions were registered in the PR body before the requests.
• Length: three lines of 922 / 521 / 864 bytes — long, in a file whose landing clause is longer; no cap exists here. Accepted; the 维护者速读 tells the maintainer where to read.
• CI at this head: objectui's test shards were in_progress at the seat's read (a markdown-only diff — ci.yml's own switch skips the expensive steps); Tier H — the maintainer merges; the seat reports the checks green before that hand-off.
• Two open questions from the dev, both decided here: (1) the POST /pulls reading stays in the report, ⛔ not in the clause (option A); (2) the empty matrix cell is filled only opportunistically from a body PATCH a seat already owes, with the prediction registered first — ⛔ never as a synthetic probe.

Implemented-by: claude/issue-9563-agents-footer-append-conditional
Reviewed-by: session_01Wnstp2kTth7sGXfr8fXypc

VERDICT: PASS

---

Generated by Claude Code