docs(agents): stop telling authors to hand-edit generated CHANGELOG.md - #14802

Merged
os-zhuang merged 1 commit into
mainfrom
claude/issue-14792-changelog-checklist-item
Sep 3, 2026
Merged

docs(agents): stop telling authors to hand-edit generated CHANGELOG.md#14802
os-zhuang merged 1 commit into
mainfrom
claude/issue-14792-changelog-checklist-item

Conversation

@os-litant

@os-litantos-litant commented Sep 3, 2026

Copy link
Copy Markdown
Collaborator

Fixes#14792

Post-task checklist item 6 in AGENTS.md told the author to hand-edit CHANGELOG.md. That file is generated output. This drops the CHANGELOG.md half of the line and keeps ROADMAP.md.

Before / after

AGENTS.md:1154

Before:

6. Update `CHANGELOG.md` / `ROADMAP.md` if user-facing or architectural.

After:

6. Update `ROADMAP.md` if user-facing or architectural.

Why

The same file says the opposite about CHANGELOG.md thirty-four lines above. At AGENTS.md:1120, inside checklist item 3, the changeset rule states that the changeset body "ships to consumers as CHANGELOG.md inside the npm package and is what an upgrading agent greps after the tombstone error". That makes CHANGELOG.md the output — written by the changesets release step from the .changeset/*.md entries item 3 already requires.

Item 6 treated the same file as an input. A contributor who obeyed it either hand-edited a generated artifact that the next Version Packages run overwrites or collides with, or read the two lines together and concluded the file contradicts itself on its most-traversed workflow. Nothing is lost by the trim: the changeset obligation is item 3, and it is unchanged here.

Neither reading of the name survives, which is what makes the trim safe rather than a judgement call. Item 6 could have meant the per-package CHANGELOG.md files or the repo-root one, so both were checked:

  • The per-package files are generated. packages/core/CHANGELOG.md and its siblings carry changeset-emitted release sections keyed by commit hash.
  • The root CHANGELOG.md disclaims hand-editing in its own header: the update history "is maintained in three layers rather than by hand-editing this file" — per-package detail "generated by [changesets] from the .changeset/ entries every PR adds", the curated per-major pages under content/docs/releases/, and this file "retained for its historical entries."

So there is no CHANGELOG.md in this repo that item 6 could have legitimately directed a PR author to update by hand.

ROADMAP.md is untouched and not in question, and the surviving half is not vacuous: the file exists at the repo root and its history shows real hand edits. This PR makes no claim about whether that obligation should stand.

Arithmetic

AGENTS.md is at its line-ratchet ceiling, so the edit adds no line and re-wraps nothing.

MeasureBeforeAfter
Lines (wc -l)1,1621,162
Ratchet ceiling / headroom1,162 / 01,162 / 0
Bytes (wc -c)85,10685,089 (-17)
The edited line72 bytes55 bytes (-17)
Widest table row1,081 (pin 1,081)1,081 (pin 1,081)
grep -c 'CHANGELOG.md' AGENTS.md2 (:1120, :1154)1 (:1120 only)

Byte-negative on one line, so nothing is paid same-file. git diff --stat is 1 file changed, 1 insertion(+), 1 deletion(-).

Scope held

Untouched, deliberately: the ROADMAP.md half of item 6, checklist item 3, and the changeset section at :1116-1122 — that region is being corrected by PR #14789, and a second PR editing it would be a merge conflict on a governed file for no gain. The hunk here at :1154 is disjoint from that one.

One argument recorded for the merging maintainer rather than acted on: a reading exists under which item 6 should be deleted outright rather than trimmed, on the grounds that ROADMAP.md updates are not obviously a per-PR obligation either. That is a scope decision, not this card's, so the line is trimmed as ruled and the argument is left here.

Gates

All run at head 9596a42386, exit codes captured by redirect before any pipe; each verdict below is the gate's own printed line.

CommandExitVerdict
pnpm check:pm-skill-ratchet0AGENTS.md is 1162 lines (ceiling 1162; headroom 0). · AGENTS.md: widest table row is 1081 bytes (pin 1081; headroom 0). · self-test 111 cases pass
pnpm check:pm-governed-prose02 instruction surface(s) name all 5 registered governed surfaces (docs/adr/** · .claude/** · skills/** · AGENTS.md · CLAUDE.md) and claim no others.
pnpm check:pm-skill-id-lint023 file(s) clean (pattern /#[0-9]{3,}/g).
pnpm check:nul-bytes0OK (scanned 8064 text file(s) -- 8064 tracked, 0 untracked-not-ignored; skipped 7 binary; no raw ASCII control bytes).
pnpm check:corpus-claim-drift0OK, no new claim sites beside a pinned spelling.
pnpm check:required-contexts06 required context name(s) pinned across 2 workflow(s); 5 instruction surface(s) scanned against 2 retired name(s).
node scripts/check-required-contexts.mjs0same sweep, direct invocation
pnpm check:agent-test-spelling0violating population empty, 9 separators judged and cleared on the rule
pnpm check:docs-audit-scope0docs-accuracy-audit scope is in sync with content/docs/: 190 hand-written doc(s)
pnpm check:pm-governed-merges0self-test 243 assertions; live: the real generator declared 9 output(s) and certified this tree

The family list was re-derived after the last edit, not taken from the dispatch:
node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands resolved its --repo assertion against this checkout's origin, derived the change set from git as 1 path (AGENTS.md, committed 1 / working tree 0 / untracked 0, three-dot against merge base fc648a256) and emitted 8 commands. All 8 ran; the two dispatch-named gates outside that union (check:nul-bytes, check:corpus-claim-drift) ran as well, so the set above is a superset.

ESLint

Not run repo-wide; narrowed, and the narrowing is a measurement rather than a skip:

  1. Population, read from eslint.config.mjs and not guessed. Every files: selector in the config is a JS/TS extension glob (**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs} and narrower variants; COMMENT_SWALLOW_FILES at :785 is that same glob). grep -cin 'markdown|[.]md' eslint.config.mjs returns 0 — no markdown processor, no .md selector anywhere. Confirmed through ESLint's own API: isPathIgnored('AGENTS.md') is true and calculateConfigForFile('AGENTS.md') yields no rules, against a positive control (eslint.config.mjs itself resolves 2 rules), so the API call is not vacuously quiet.
  2. Count, from --format json.pnpm exec eslint AGENTS.md --no-inline-config --format json gives errorCount: 0, warningCount: 1, the one warning being ruleId: null / File ignored because no matching configuration was supplied — zero rule results, because the file is outside the population.
  3. Invariance over untouched files. The config never enables type-aware linting for any file — no parserOptions.project, no typed rules, stated at eslint.config.mjs:325-332 with its own measured positive control. With no cross-file type program there is no mechanism by which an edit in one file moves a verdict on a file it does not touch, and this diff is one Markdown line in a file ESLint does not lint at all.

A full pnpm lint therefore measures the same nothing this narrowing measured.

Changeset

Labelled skip-changeset, route 2 of scripts/check-empty-changeset.mjs's own enumeration: "It releases nothing (.github/, .claude/, skills/, docs/, content/, examples/, tests-only, and the like) -- delete the changeset and apply the 'skip-changeset' label". This diff is one line of the repo-root instruction file; no packages/** source is touched and nothing publishes from any package. Per that script, the label is a gate-level exemption that produces no input for changesets/action — the shape an empty-frontmatter changeset would have broken.

Landing

Draft, and it stays draft — governed AGENTS.md, human merge is the review record. Not flipped ready, not queued, no auto-merge armed, no reviewers requested.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1

Post-task checklist item 6 read "Update `CHANGELOG.md` / `ROADMAP.md` if
user-facing or architectural", which contradicts the same file 34 lines
above: the changeset section states the changeset body "ships to consumers
as `CHANGELOG.md` inside the npm package". `CHANGELOG.md` is generated
output, written by the changesets release step from the entries item 3
already requires, so item 6 was directing the author to hand-edit a
generated artifact that the next Version Packages run overwrites or
collides with.
Drop the `CHANGELOG.md` half; keep `ROADMAP.md`, which may genuinely be
hand-maintained and is not in question here. Byte-negative on one line
(-17 bytes), no line added or re-wrapped: the file is at its ratchet
ceiling with headroom 0.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1
@github-actions

Copy link
Copy Markdown
Contributor

⛔ merge queue 构建失败 — 先分诊,再决定要不要重排

队列构建 33727530243 红了。队列跑的是全量套件(PR 侧 CI 只跑 affected 子集),
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job(日志抽取,best effort):

  • Test Core (1/6) — 失败步骤: Run this shard's tests

    @objectstack/cli:test: FAIL integration test/run-dev-unbuilt-workspace.e2e.test.ts > the mirror direction: a reader that is never coming back > gives up and exits instead of waiting forever
    ↳ 失败原因: @objectstack/cli:test: AssertionError: the harness SIGKILLed the child — it was still alive at the ceiling. cap 180000 ms (RUN_TIMEOUT_MS, constant and load-independent by design); this child ran 1801
    

↳ 失败原因 是判读的关键:超时Test timed out in … / Hook timed out in …)多半是负载/时序,不是本 PR 的回归;
断言AssertionError: …)才指向真实的行为改变。两者的 FAIL 行长得一模一样,只有这一行能区分。

⚠️断言这一侧有一类例外,判据是断言在测什么,不是它是不是 AssertionError 断言的对象是产品行为(一个值、一个形状、一次拒收)⇒ 照上面读:真实的行为改变,去查,⛔ 不要重排掉;
断言的对象是这次实验自身的有效性前提(跑完的耗时、负载下的先后、任何只在时间预算内才成立的条件)⇒ 它跟超时是同一类,同样对负载敏感,重排一次是合法的判别手段。
识别是机械的:断言的消息或它比较的值本身点名了一段时长、一个时间戳、一个耗时计数。实测过的一对 —— AssertionError: SecurityPlugin.init() ran: expected false to be true 测的是产品行为(真回归);
AssertionError: this run took over a second, so second-precision stamps could have differed too: expected 1006 to be less than 1000 测的是实验前提:它守护的那条不变式当时是绿的,同一个 head 原样重排一次即成功。
穿着 AssertionError 外衣的时间测量,仍然是时间测量。(⛔ 这只改「怎么读一次红」,不改「哪些测试可以重排」——后者由别处管。)

跨 PR 相同签名(24h,按失败测试文件聚合):

历史信号:

  • 本 PR 过去 24h 无队列失败记录(首次)。
  • 过去 24h 队列共有 97 个失败构建(不含本次)。

分诊清单:

  1. 失败测试在本 PR 改动的包里 → 真回归,修 PR。
  2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」;已有汇总 issue ⇒ flaky/环境问题实锤,去那张 issue 上谈,修好前重排只会再烧一轮全队列。
  3. 两者都不是 → 可能与同组 PR 语义冲突;等前面的 PR 落地或失败出队后再重排一次即可,不要连续重排。

Generated by Claude Code · merge-queue-triage workflow (#4859)

@github-actions

Copy link
Copy Markdown
Contributor

⛔ merge queue 构建失败 — 先分诊,再决定要不要重排

队列构建 33729340857 红了。队列跑的是全量套件(PR 侧 CI 只跑 affected 子集),
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job(日志抽取,best effort):

  • Test Core (1/6) — 失败步骤: Run this shard's tests

    @objectstack/cli:test: FAIL integration test/run-dev-unbuilt-workspace.e2e.test.ts > the mirror direction: a reader that is never coming back > gives up and exits instead of waiting forever
    ↳ 失败原因: @objectstack/cli:test: AssertionError: the harness SIGKILLed the child — it was still alive at the ceiling. cap 180000 ms (RUN_TIMEOUT_MS, constant and load-independent by design); this child ran 1800
    

↳ 失败原因 是判读的关键:超时Test timed out in … / Hook timed out in …)多半是负载/时序,不是本 PR 的回归;
断言AssertionError: …)才指向真实的行为改变。两者的 FAIL 行长得一模一样,只有这一行能区分。

⚠️断言这一侧有一类例外,判据是断言在测什么,不是它是不是 AssertionError 断言的对象是产品行为(一个值、一个形状、一次拒收)⇒ 照上面读:真实的行为改变,去查,⛔ 不要重排掉;
断言的对象是这次实验自身的有效性前提(跑完的耗时、负载下的先后、任何只在时间预算内才成立的条件)⇒ 它跟超时是同一类,同样对负载敏感,重排一次是合法的判别手段。
识别是机械的:断言的消息或它比较的值本身点名了一段时长、一个时间戳、一个耗时计数。实测过的一对 —— AssertionError: SecurityPlugin.init() ran: expected false to be true 测的是产品行为(真回归);
AssertionError: this run took over a second, so second-precision stamps could have differed too: expected 1006 to be less than 1000 测的是实验前提:它守护的那条不变式当时是绿的,同一个 head 原样重排一次即成功。
穿着 AssertionError 外衣的时间测量,仍然是时间测量。(⛔ 这只改「怎么读一次红」,不改「哪些测试可以重排」——后者由别处管。)

跨 PR 相同签名(24h,按失败测试文件聚合):

历史信号:

  • ⚠️本 PR 过去 24h 已在队列失败 1 次(不含本次)。 内容未变而反复失败 ⇒ 高度怀疑 flaky 测试或与同组 PR 的语义冲突,重排不解决。
  • 过去 24h 队列共有 105 个失败构建(不含本次)。

分诊清单:

  1. 失败测试在本 PR 改动的包里 → 真回归,修 PR。
  2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」;已有汇总 issue ⇒ flaky/环境问题实锤,去那张 issue 上谈,修好前重排只会再烧一轮全队列。
  3. 两者都不是 → 可能与同组 PR 语义冲突;等前面的 PR 落地或失败出队后再重排一次即可,不要连续重排。

Generated by Claude Code · merge-queue-triage workflow (#4859)

Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentationImprovements or additions to documentationsize/xsskip-changesetPR has no user-facing published change; bypasses the changeset gate

Projects

None yet

3 participants

@os-litant@os-zhuang@claude
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '
Skip to content

docs(agents): stop telling authors to hand-edit generated CHANGELOG.md - #14802

Merged
os-zhuang merged 1 commit into
mainfrom
claude/issue-14792-changelog-checklist-item
Sep 3, 2026
Merged

docs(agents): stop telling authors to hand-edit generated CHANGELOG.md#14802
os-zhuang merged 1 commit into
mainfrom
claude/issue-14792-changelog-checklist-item

Conversation

@os-litant

@os-litantos-litant commented Sep 3, 2026

Copy link
Copy Markdown
Collaborator

Fixes#14792

Post-task checklist item 6 in AGENTS.md told the author to hand-edit CHANGELOG.md. That file is generated output. This drops the CHANGELOG.md half of the line and keeps ROADMAP.md.

Before / after

AGENTS.md:1154

Before:

6. Update `CHANGELOG.md` / `ROADMAP.md` if user-facing or architectural.

After:

6. Update `ROADMAP.md` if user-facing or architectural.

Why

The same file says the opposite about CHANGELOG.md thirty-four lines above. At AGENTS.md:1120, inside checklist item 3, the changeset rule states that the changeset body "ships to consumers as CHANGELOG.md inside the npm package and is what an upgrading agent greps after the tombstone error". That makes CHANGELOG.md the output — written by the changesets release step from the .changeset/*.md entries item 3 already requires.

Item 6 treated the same file as an input. A contributor who obeyed it either hand-edited a generated artifact that the next Version Packages run overwrites or collides with, or read the two lines together and concluded the file contradicts itself on its most-traversed workflow. Nothing is lost by the trim: the changeset obligation is item 3, and it is unchanged here.

Neither reading of the name survives, which is what makes the trim safe rather than a judgement call. Item 6 could have meant the per-package CHANGELOG.md files or the repo-root one, so both were checked:

  • The per-package files are generated. packages/core/CHANGELOG.md and its siblings carry changeset-emitted release sections keyed by commit hash.
  • The root CHANGELOG.md disclaims hand-editing in its own header: the update history "is maintained in three layers rather than by hand-editing this file" — per-package detail "generated by [changesets] from the .changeset/ entries every PR adds", the curated per-major pages under content/docs/releases/, and this file "retained for its historical entries."

So there is no CHANGELOG.md in this repo that item 6 could have legitimately directed a PR author to update by hand.

ROADMAP.md is untouched and not in question, and the surviving half is not vacuous: the file exists at the repo root and its history shows real hand edits. This PR makes no claim about whether that obligation should stand.

Arithmetic

AGENTS.md is at its line-ratchet ceiling, so the edit adds no line and re-wraps nothing.

MeasureBeforeAfter
Lines (wc -l)1,1621,162
Ratchet ceiling / headroom1,162 / 01,162 / 0
Bytes (wc -c)85,10685,089 (-17)
The edited line72 bytes55 bytes (-17)
Widest table row1,081 (pin 1,081)1,081 (pin 1,081)
grep -c 'CHANGELOG.md' AGENTS.md2 (:1120, :1154)1 (:1120 only)

Byte-negative on one line, so nothing is paid same-file. git diff --stat is 1 file changed, 1 insertion(+), 1 deletion(-).

Scope held

Untouched, deliberately: the ROADMAP.md half of item 6, checklist item 3, and the changeset section at :1116-1122 — that region is being corrected by PR #14789, and a second PR editing it would be a merge conflict on a governed file for no gain. The hunk here at :1154 is disjoint from that one.

One argument recorded for the merging maintainer rather than acted on: a reading exists under which item 6 should be deleted outright rather than trimmed, on the grounds that ROADMAP.md updates are not obviously a per-PR obligation either. That is a scope decision, not this card's, so the line is trimmed as ruled and the argument is left here.

Gates

All run at head 9596a42386, exit codes captured by redirect before any pipe; each verdict below is the gate's own printed line.

CommandExitVerdict
pnpm check:pm-skill-ratchet0AGENTS.md is 1162 lines (ceiling 1162; headroom 0). · AGENTS.md: widest table row is 1081 bytes (pin 1081; headroom 0). · self-test 111 cases pass
pnpm check:pm-governed-prose02 instruction surface(s) name all 5 registered governed surfaces (docs/adr/** · .claude/** · skills/** · AGENTS.md · CLAUDE.md) and claim no others.
pnpm check:pm-skill-id-lint023 file(s) clean (pattern /#[0-9]{3,}/g).
pnpm check:nul-bytes0OK (scanned 8064 text file(s) -- 8064 tracked, 0 untracked-not-ignored; skipped 7 binary; no raw ASCII control bytes).
pnpm check:corpus-claim-drift0OK, no new claim sites beside a pinned spelling.
pnpm check:required-contexts06 required context name(s) pinned across 2 workflow(s); 5 instruction surface(s) scanned against 2 retired name(s).
node scripts/check-required-contexts.mjs0same sweep, direct invocation
pnpm check:agent-test-spelling0violating population empty, 9 separators judged and cleared on the rule
pnpm check:docs-audit-scope0docs-accuracy-audit scope is in sync with content/docs/: 190 hand-written doc(s)
pnpm check:pm-governed-merges0self-test 243 assertions; live: the real generator declared 9 output(s) and certified this tree

The family list was re-derived after the last edit, not taken from the dispatch:
node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands resolved its --repo assertion against this checkout's origin, derived the change set from git as 1 path (AGENTS.md, committed 1 / working tree 0 / untracked 0, three-dot against merge base fc648a256) and emitted 8 commands. All 8 ran; the two dispatch-named gates outside that union (check:nul-bytes, check:corpus-claim-drift) ran as well, so the set above is a superset.

ESLint

Not run repo-wide; narrowed, and the narrowing is a measurement rather than a skip:

  1. Population, read from eslint.config.mjs and not guessed. Every files: selector in the config is a JS/TS extension glob (**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs} and narrower variants; COMMENT_SWALLOW_FILES at :785 is that same glob). grep -cin 'markdown|[.]md' eslint.config.mjs returns 0 — no markdown processor, no .md selector anywhere. Confirmed through ESLint's own API: isPathIgnored('AGENTS.md') is true and calculateConfigForFile('AGENTS.md') yields no rules, against a positive control (eslint.config.mjs itself resolves 2 rules), so the API call is not vacuously quiet.
  2. Count, from --format json.pnpm exec eslint AGENTS.md --no-inline-config --format json gives errorCount: 0, warningCount: 1, the one warning being ruleId: null / File ignored because no matching configuration was supplied — zero rule results, because the file is outside the population.
  3. Invariance over untouched files. The config never enables type-aware linting for any file — no parserOptions.project, no typed rules, stated at eslint.config.mjs:325-332 with its own measured positive control. With no cross-file type program there is no mechanism by which an edit in one file moves a verdict on a file it does not touch, and this diff is one Markdown line in a file ESLint does not lint at all.

A full pnpm lint therefore measures the same nothing this narrowing measured.

Changeset

Labelled skip-changeset, route 2 of scripts/check-empty-changeset.mjs's own enumeration: "It releases nothing (.github/, .claude/, skills/, docs/, content/, examples/, tests-only, and the like) -- delete the changeset and apply the 'skip-changeset' label". This diff is one line of the repo-root instruction file; no packages/** source is touched and nothing publishes from any package. Per that script, the label is a gate-level exemption that produces no input for changesets/action — the shape an empty-frontmatter changeset would have broken.

Landing

Draft, and it stays draft — governed AGENTS.md, human merge is the review record. Not flipped ready, not queued, no auto-merge armed, no reviewers requested.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1

Post-task checklist item 6 read "Update `CHANGELOG.md` / `ROADMAP.md` if
user-facing or architectural", which contradicts the same file 34 lines
above: the changeset section states the changeset body "ships to consumers
as `CHANGELOG.md` inside the npm package". `CHANGELOG.md` is generated
output, written by the changesets release step from the entries item 3
already requires, so item 6 was directing the author to hand-edit a
generated artifact that the next Version Packages run overwrites or
collides with.
Drop the `CHANGELOG.md` half; keep `ROADMAP.md`, which may genuinely be
hand-maintained and is not in question here. Byte-negative on one line
(-17 bytes), no line added or re-wrapped: the file is at its ratchet
ceiling with headroom 0.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1
@github-actions

Copy link
Copy Markdown
Contributor

⛔ merge queue 构建失败 — 先分诊,再决定要不要重排

队列构建 33727530243 红了。队列跑的是全量套件(PR 侧 CI 只跑 affected 子集),
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job(日志抽取,best effort):

  • Test Core (1/6) — 失败步骤: Run this shard's tests

    @objectstack/cli:test: FAIL integration test/run-dev-unbuilt-workspace.e2e.test.ts > the mirror direction: a reader that is never coming back > gives up and exits instead of waiting forever
    ↳ 失败原因: @objectstack/cli:test: AssertionError: the harness SIGKILLed the child — it was still alive at the ceiling. cap 180000 ms (RUN_TIMEOUT_MS, constant and load-independent by design); this child ran 1801
    

↳ 失败原因 是判读的关键:超时Test timed out in … / Hook timed out in …)多半是负载/时序,不是本 PR 的回归;
断言AssertionError: …)才指向真实的行为改变。两者的 FAIL 行长得一模一样,只有这一行能区分。

⚠️断言这一侧有一类例外,判据是断言在测什么,不是它是不是 AssertionError 断言的对象是产品行为(一个值、一个形状、一次拒收)⇒ 照上面读:真实的行为改变,去查,⛔ 不要重排掉;
断言的对象是这次实验自身的有效性前提(跑完的耗时、负载下的先后、任何只在时间预算内才成立的条件)⇒ 它跟超时是同一类,同样对负载敏感,重排一次是合法的判别手段。
识别是机械的:断言的消息或它比较的值本身点名了一段时长、一个时间戳、一个耗时计数。实测过的一对 —— AssertionError: SecurityPlugin.init() ran: expected false to be true 测的是产品行为(真回归);
AssertionError: this run took over a second, so second-precision stamps could have differed too: expected 1006 to be less than 1000 测的是实验前提:它守护的那条不变式当时是绿的,同一个 head 原样重排一次即成功。
穿着 AssertionError 外衣的时间测量,仍然是时间测量。(⛔ 这只改「怎么读一次红」,不改「哪些测试可以重排」——后者由别处管。)

跨 PR 相同签名(24h,按失败测试文件聚合):

历史信号:

  • 本 PR 过去 24h 无队列失败记录(首次)。
  • 过去 24h 队列共有 97 个失败构建(不含本次)。

分诊清单:

  1. 失败测试在本 PR 改动的包里 → 真回归,修 PR。
  2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」;已有汇总 issue ⇒ flaky/环境问题实锤,去那张 issue 上谈,修好前重排只会再烧一轮全队列。
  3. 两者都不是 → 可能与同组 PR 语义冲突;等前面的 PR 落地或失败出队后再重排一次即可,不要连续重排。

Generated by Claude Code · merge-queue-triage workflow (#4859)

@github-actions

Copy link
Copy Markdown
Contributor

⛔ merge queue 构建失败 — 先分诊,再决定要不要重排

队列构建 33729340857 红了。队列跑的是全量套件(PR 侧 CI 只跑 affected 子集),
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job(日志抽取,best effort):

  • Test Core (1/6) — 失败步骤: Run this shard's tests

    @objectstack/cli:test: FAIL integration test/run-dev-unbuilt-workspace.e2e.test.ts > the mirror direction: a reader that is never coming back > gives up and exits instead of waiting forever
    ↳ 失败原因: @objectstack/cli:test: AssertionError: the harness SIGKILLed the child — it was still alive at the ceiling. cap 180000 ms (RUN_TIMEOUT_MS, constant and load-independent by design); this child ran 1800
    

↳ 失败原因 是判读的关键:超时Test timed out in … / Hook timed out in …)多半是负载/时序,不是本 PR 的回归;
断言AssertionError: …)才指向真实的行为改变。两者的 FAIL 行长得一模一样,只有这一行能区分。

⚠️断言这一侧有一类例外,判据是断言在测什么,不是它是不是 AssertionError 断言的对象是产品行为(一个值、一个形状、一次拒收)⇒ 照上面读:真实的行为改变,去查,⛔ 不要重排掉;
断言的对象是这次实验自身的有效性前提(跑完的耗时、负载下的先后、任何只在时间预算内才成立的条件)⇒ 它跟超时是同一类,同样对负载敏感,重排一次是合法的判别手段。
识别是机械的:断言的消息或它比较的值本身点名了一段时长、一个时间戳、一个耗时计数。实测过的一对 —— AssertionError: SecurityPlugin.init() ran: expected false to be true 测的是产品行为(真回归);
AssertionError: this run took over a second, so second-precision stamps could have differed too: expected 1006 to be less than 1000 测的是实验前提:它守护的那条不变式当时是绿的,同一个 head 原样重排一次即成功。
穿着 AssertionError 外衣的时间测量,仍然是时间测量。(⛔ 这只改「怎么读一次红」,不改「哪些测试可以重排」——后者由别处管。)

跨 PR 相同签名(24h,按失败测试文件聚合):

历史信号:

  • ⚠️本 PR 过去 24h 已在队列失败 1 次(不含本次)。 内容未变而反复失败 ⇒ 高度怀疑 flaky 测试或与同组 PR 的语义冲突,重排不解决。
  • 过去 24h 队列共有 105 个失败构建(不含本次)。

分诊清单:

  1. 失败测试在本 PR 改动的包里 → 真回归,修 PR。
  2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」;已有汇总 issue ⇒ flaky/环境问题实锤,去那张 issue 上谈,修好前重排只会再烧一轮全队列。
  3. 两者都不是 → 可能与同组 PR 语义冲突;等前面的 PR 落地或失败出队后再重排一次即可,不要连续重排。

Generated by Claude Code · merge-queue-triage workflow (#4859)

Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentationImprovements or additions to documentationsize/xsskip-changesetPR has no user-facing published change; bypasses the changeset gate

Projects

None yet

3 participants

@os-litant@os-zhuang@claude
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix"); } } catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + '
Skip to content

docs(agents): stop telling authors to hand-edit generated CHANGELOG.md - #14802

Merged
os-zhuang merged 1 commit into
mainfrom
claude/issue-14792-changelog-checklist-item
Sep 3, 2026
Merged

docs(agents): stop telling authors to hand-edit generated CHANGELOG.md#14802
os-zhuang merged 1 commit into
mainfrom
claude/issue-14792-changelog-checklist-item

Conversation

@os-litant

@os-litantos-litant commented Sep 3, 2026

Copy link
Copy Markdown
Collaborator

Fixes#14792

Post-task checklist item 6 in AGENTS.md told the author to hand-edit CHANGELOG.md. That file is generated output. This drops the CHANGELOG.md half of the line and keeps ROADMAP.md.

Before / after

AGENTS.md:1154

Before:

6. Update `CHANGELOG.md` / `ROADMAP.md` if user-facing or architectural.

After:

6. Update `ROADMAP.md` if user-facing or architectural.

Why

The same file says the opposite about CHANGELOG.md thirty-four lines above. At AGENTS.md:1120, inside checklist item 3, the changeset rule states that the changeset body "ships to consumers as CHANGELOG.md inside the npm package and is what an upgrading agent greps after the tombstone error". That makes CHANGELOG.md the output — written by the changesets release step from the .changeset/*.md entries item 3 already requires.

Item 6 treated the same file as an input. A contributor who obeyed it either hand-edited a generated artifact that the next Version Packages run overwrites or collides with, or read the two lines together and concluded the file contradicts itself on its most-traversed workflow. Nothing is lost by the trim: the changeset obligation is item 3, and it is unchanged here.

Neither reading of the name survives, which is what makes the trim safe rather than a judgement call. Item 6 could have meant the per-package CHANGELOG.md files or the repo-root one, so both were checked:

  • The per-package files are generated. packages/core/CHANGELOG.md and its siblings carry changeset-emitted release sections keyed by commit hash.
  • The root CHANGELOG.md disclaims hand-editing in its own header: the update history "is maintained in three layers rather than by hand-editing this file" — per-package detail "generated by [changesets] from the .changeset/ entries every PR adds", the curated per-major pages under content/docs/releases/, and this file "retained for its historical entries."

So there is no CHANGELOG.md in this repo that item 6 could have legitimately directed a PR author to update by hand.

ROADMAP.md is untouched and not in question, and the surviving half is not vacuous: the file exists at the repo root and its history shows real hand edits. This PR makes no claim about whether that obligation should stand.

Arithmetic

AGENTS.md is at its line-ratchet ceiling, so the edit adds no line and re-wraps nothing.

MeasureBeforeAfter
Lines (wc -l)1,1621,162
Ratchet ceiling / headroom1,162 / 01,162 / 0
Bytes (wc -c)85,10685,089 (-17)
The edited line72 bytes55 bytes (-17)
Widest table row1,081 (pin 1,081)1,081 (pin 1,081)
grep -c 'CHANGELOG.md' AGENTS.md2 (:1120, :1154)1 (:1120 only)

Byte-negative on one line, so nothing is paid same-file. git diff --stat is 1 file changed, 1 insertion(+), 1 deletion(-).

Scope held

Untouched, deliberately: the ROADMAP.md half of item 6, checklist item 3, and the changeset section at :1116-1122 — that region is being corrected by PR #14789, and a second PR editing it would be a merge conflict on a governed file for no gain. The hunk here at :1154 is disjoint from that one.

One argument recorded for the merging maintainer rather than acted on: a reading exists under which item 6 should be deleted outright rather than trimmed, on the grounds that ROADMAP.md updates are not obviously a per-PR obligation either. That is a scope decision, not this card's, so the line is trimmed as ruled and the argument is left here.

Gates

All run at head 9596a42386, exit codes captured by redirect before any pipe; each verdict below is the gate's own printed line.

CommandExitVerdict
pnpm check:pm-skill-ratchet0AGENTS.md is 1162 lines (ceiling 1162; headroom 0). · AGENTS.md: widest table row is 1081 bytes (pin 1081; headroom 0). · self-test 111 cases pass
pnpm check:pm-governed-prose02 instruction surface(s) name all 5 registered governed surfaces (docs/adr/** · .claude/** · skills/** · AGENTS.md · CLAUDE.md) and claim no others.
pnpm check:pm-skill-id-lint023 file(s) clean (pattern /#[0-9]{3,}/g).
pnpm check:nul-bytes0OK (scanned 8064 text file(s) -- 8064 tracked, 0 untracked-not-ignored; skipped 7 binary; no raw ASCII control bytes).
pnpm check:corpus-claim-drift0OK, no new claim sites beside a pinned spelling.
pnpm check:required-contexts06 required context name(s) pinned across 2 workflow(s); 5 instruction surface(s) scanned against 2 retired name(s).
node scripts/check-required-contexts.mjs0same sweep, direct invocation
pnpm check:agent-test-spelling0violating population empty, 9 separators judged and cleared on the rule
pnpm check:docs-audit-scope0docs-accuracy-audit scope is in sync with content/docs/: 190 hand-written doc(s)
pnpm check:pm-governed-merges0self-test 243 assertions; live: the real generator declared 9 output(s) and certified this tree

The family list was re-derived after the last edit, not taken from the dispatch:
node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands resolved its --repo assertion against this checkout's origin, derived the change set from git as 1 path (AGENTS.md, committed 1 / working tree 0 / untracked 0, three-dot against merge base fc648a256) and emitted 8 commands. All 8 ran; the two dispatch-named gates outside that union (check:nul-bytes, check:corpus-claim-drift) ran as well, so the set above is a superset.

ESLint

Not run repo-wide; narrowed, and the narrowing is a measurement rather than a skip:

  1. Population, read from eslint.config.mjs and not guessed. Every files: selector in the config is a JS/TS extension glob (**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs} and narrower variants; COMMENT_SWALLOW_FILES at :785 is that same glob). grep -cin 'markdown|[.]md' eslint.config.mjs returns 0 — no markdown processor, no .md selector anywhere. Confirmed through ESLint's own API: isPathIgnored('AGENTS.md') is true and calculateConfigForFile('AGENTS.md') yields no rules, against a positive control (eslint.config.mjs itself resolves 2 rules), so the API call is not vacuously quiet.
  2. Count, from --format json.pnpm exec eslint AGENTS.md --no-inline-config --format json gives errorCount: 0, warningCount: 1, the one warning being ruleId: null / File ignored because no matching configuration was supplied — zero rule results, because the file is outside the population.
  3. Invariance over untouched files. The config never enables type-aware linting for any file — no parserOptions.project, no typed rules, stated at eslint.config.mjs:325-332 with its own measured positive control. With no cross-file type program there is no mechanism by which an edit in one file moves a verdict on a file it does not touch, and this diff is one Markdown line in a file ESLint does not lint at all.

A full pnpm lint therefore measures the same nothing this narrowing measured.

Changeset

Labelled skip-changeset, route 2 of scripts/check-empty-changeset.mjs's own enumeration: "It releases nothing (.github/, .claude/, skills/, docs/, content/, examples/, tests-only, and the like) -- delete the changeset and apply the 'skip-changeset' label". This diff is one line of the repo-root instruction file; no packages/** source is touched and nothing publishes from any package. Per that script, the label is a gate-level exemption that produces no input for changesets/action — the shape an empty-frontmatter changeset would have broken.

Landing

Draft, and it stays draft — governed AGENTS.md, human merge is the review record. Not flipped ready, not queued, no auto-merge armed, no reviewers requested.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1

Post-task checklist item 6 read "Update `CHANGELOG.md` / `ROADMAP.md` if
user-facing or architectural", which contradicts the same file 34 lines
above: the changeset section states the changeset body "ships to consumers
as `CHANGELOG.md` inside the npm package". `CHANGELOG.md` is generated
output, written by the changesets release step from the entries item 3
already requires, so item 6 was directing the author to hand-edit a
generated artifact that the next Version Packages run overwrites or
collides with.
Drop the `CHANGELOG.md` half; keep `ROADMAP.md`, which may genuinely be
hand-maintained and is not in question here. Byte-negative on one line
(-17 bytes), no line added or re-wrapped: the file is at its ratchet
ceiling with headroom 0.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1
@github-actions

Copy link
Copy Markdown
Contributor

⛔ merge queue 构建失败 — 先分诊,再决定要不要重排

队列构建 33727530243 红了。队列跑的是全量套件(PR 侧 CI 只跑 affected 子集),
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job(日志抽取,best effort):

  • Test Core (1/6) — 失败步骤: Run this shard's tests

    @objectstack/cli:test: FAIL integration test/run-dev-unbuilt-workspace.e2e.test.ts > the mirror direction: a reader that is never coming back > gives up and exits instead of waiting forever
    ↳ 失败原因: @objectstack/cli:test: AssertionError: the harness SIGKILLed the child — it was still alive at the ceiling. cap 180000 ms (RUN_TIMEOUT_MS, constant and load-independent by design); this child ran 1801
    

↳ 失败原因 是判读的关键:超时Test timed out in … / Hook timed out in …)多半是负载/时序,不是本 PR 的回归;
断言AssertionError: …)才指向真实的行为改变。两者的 FAIL 行长得一模一样,只有这一行能区分。

⚠️断言这一侧有一类例外,判据是断言在测什么,不是它是不是 AssertionError 断言的对象是产品行为(一个值、一个形状、一次拒收)⇒ 照上面读:真实的行为改变,去查,⛔ 不要重排掉;
断言的对象是这次实验自身的有效性前提(跑完的耗时、负载下的先后、任何只在时间预算内才成立的条件)⇒ 它跟超时是同一类,同样对负载敏感,重排一次是合法的判别手段。
识别是机械的:断言的消息或它比较的值本身点名了一段时长、一个时间戳、一个耗时计数。实测过的一对 —— AssertionError: SecurityPlugin.init() ran: expected false to be true 测的是产品行为(真回归);
AssertionError: this run took over a second, so second-precision stamps could have differed too: expected 1006 to be less than 1000 测的是实验前提:它守护的那条不变式当时是绿的,同一个 head 原样重排一次即成功。
穿着 AssertionError 外衣的时间测量,仍然是时间测量。(⛔ 这只改「怎么读一次红」,不改「哪些测试可以重排」——后者由别处管。)

跨 PR 相同签名(24h,按失败测试文件聚合):

历史信号:

  • 本 PR 过去 24h 无队列失败记录(首次)。
  • 过去 24h 队列共有 97 个失败构建(不含本次)。

分诊清单:

  1. 失败测试在本 PR 改动的包里 → 真回归,修 PR。
  2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」;已有汇总 issue ⇒ flaky/环境问题实锤,去那张 issue 上谈,修好前重排只会再烧一轮全队列。
  3. 两者都不是 → 可能与同组 PR 语义冲突;等前面的 PR 落地或失败出队后再重排一次即可,不要连续重排。

Generated by Claude Code · merge-queue-triage workflow (#4859)

@github-actions

Copy link
Copy Markdown
Contributor

⛔ merge queue 构建失败 — 先分诊,再决定要不要重排

队列构建 33729340857 红了。队列跑的是全量套件(PR 侧 CI 只跑 affected 子集),
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job(日志抽取,best effort):

  • Test Core (1/6) — 失败步骤: Run this shard's tests

    @objectstack/cli:test: FAIL integration test/run-dev-unbuilt-workspace.e2e.test.ts > the mirror direction: a reader that is never coming back > gives up and exits instead of waiting forever
    ↳ 失败原因: @objectstack/cli:test: AssertionError: the harness SIGKILLed the child — it was still alive at the ceiling. cap 180000 ms (RUN_TIMEOUT_MS, constant and load-independent by design); this child ran 1800
    

↳ 失败原因 是判读的关键:超时Test timed out in … / Hook timed out in …)多半是负载/时序,不是本 PR 的回归;
断言AssertionError: …)才指向真实的行为改变。两者的 FAIL 行长得一模一样,只有这一行能区分。

⚠️断言这一侧有一类例外,判据是断言在测什么,不是它是不是 AssertionError 断言的对象是产品行为(一个值、一个形状、一次拒收)⇒ 照上面读:真实的行为改变,去查,⛔ 不要重排掉;
断言的对象是这次实验自身的有效性前提(跑完的耗时、负载下的先后、任何只在时间预算内才成立的条件)⇒ 它跟超时是同一类,同样对负载敏感,重排一次是合法的判别手段。
识别是机械的:断言的消息或它比较的值本身点名了一段时长、一个时间戳、一个耗时计数。实测过的一对 —— AssertionError: SecurityPlugin.init() ran: expected false to be true 测的是产品行为(真回归);
AssertionError: this run took over a second, so second-precision stamps could have differed too: expected 1006 to be less than 1000 测的是实验前提:它守护的那条不变式当时是绿的,同一个 head 原样重排一次即成功。
穿着 AssertionError 外衣的时间测量,仍然是时间测量。(⛔ 这只改「怎么读一次红」,不改「哪些测试可以重排」——后者由别处管。)

跨 PR 相同签名(24h,按失败测试文件聚合):

历史信号:

  • ⚠️本 PR 过去 24h 已在队列失败 1 次(不含本次)。 内容未变而反复失败 ⇒ 高度怀疑 flaky 测试或与同组 PR 的语义冲突,重排不解决。
  • 过去 24h 队列共有 105 个失败构建(不含本次)。

分诊清单:

  1. 失败测试在本 PR 改动的包里 → 真回归,修 PR。
  2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」;已有汇总 issue ⇒ flaky/环境问题实锤,去那张 issue 上谈,修好前重排只会再烧一轮全队列。
  3. 两者都不是 → 可能与同组 PR 语义冲突;等前面的 PR 落地或失败出队后再重排一次即可,不要连续重排。

Generated by Claude Code · merge-queue-triage workflow (#4859)

Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentationImprovements or additions to documentationsize/xsskip-changesetPR has no user-facing published change; bypasses the changeset gate

Projects

None yet

3 participants

@os-litant@os-zhuang@claude
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms"); } } catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + '
Skip to content

docs(agents): stop telling authors to hand-edit generated CHANGELOG.md - #14802

Merged
os-zhuang merged 1 commit into
mainfrom
claude/issue-14792-changelog-checklist-item
Sep 3, 2026
Merged

docs(agents): stop telling authors to hand-edit generated CHANGELOG.md#14802
os-zhuang merged 1 commit into
mainfrom
claude/issue-14792-changelog-checklist-item

Conversation

@os-litant

@os-litantos-litant commented Sep 3, 2026

Copy link
Copy Markdown
Collaborator

Fixes#14792

Post-task checklist item 6 in AGENTS.md told the author to hand-edit CHANGELOG.md. That file is generated output. This drops the CHANGELOG.md half of the line and keeps ROADMAP.md.

Before / after

AGENTS.md:1154

Before:

6. Update `CHANGELOG.md` / `ROADMAP.md` if user-facing or architectural.

After:

6. Update `ROADMAP.md` if user-facing or architectural.

Why

The same file says the opposite about CHANGELOG.md thirty-four lines above. At AGENTS.md:1120, inside checklist item 3, the changeset rule states that the changeset body "ships to consumers as CHANGELOG.md inside the npm package and is what an upgrading agent greps after the tombstone error". That makes CHANGELOG.md the output — written by the changesets release step from the .changeset/*.md entries item 3 already requires.

Item 6 treated the same file as an input. A contributor who obeyed it either hand-edited a generated artifact that the next Version Packages run overwrites or collides with, or read the two lines together and concluded the file contradicts itself on its most-traversed workflow. Nothing is lost by the trim: the changeset obligation is item 3, and it is unchanged here.

Neither reading of the name survives, which is what makes the trim safe rather than a judgement call. Item 6 could have meant the per-package CHANGELOG.md files or the repo-root one, so both were checked:

  • The per-package files are generated. packages/core/CHANGELOG.md and its siblings carry changeset-emitted release sections keyed by commit hash.
  • The root CHANGELOG.md disclaims hand-editing in its own header: the update history "is maintained in three layers rather than by hand-editing this file" — per-package detail "generated by [changesets] from the .changeset/ entries every PR adds", the curated per-major pages under content/docs/releases/, and this file "retained for its historical entries."

So there is no CHANGELOG.md in this repo that item 6 could have legitimately directed a PR author to update by hand.

ROADMAP.md is untouched and not in question, and the surviving half is not vacuous: the file exists at the repo root and its history shows real hand edits. This PR makes no claim about whether that obligation should stand.

Arithmetic

AGENTS.md is at its line-ratchet ceiling, so the edit adds no line and re-wraps nothing.

MeasureBeforeAfter
Lines (wc -l)1,1621,162
Ratchet ceiling / headroom1,162 / 01,162 / 0
Bytes (wc -c)85,10685,089 (-17)
The edited line72 bytes55 bytes (-17)
Widest table row1,081 (pin 1,081)1,081 (pin 1,081)
grep -c 'CHANGELOG.md' AGENTS.md2 (:1120, :1154)1 (:1120 only)

Byte-negative on one line, so nothing is paid same-file. git diff --stat is 1 file changed, 1 insertion(+), 1 deletion(-).

Scope held

Untouched, deliberately: the ROADMAP.md half of item 6, checklist item 3, and the changeset section at :1116-1122 — that region is being corrected by PR #14789, and a second PR editing it would be a merge conflict on a governed file for no gain. The hunk here at :1154 is disjoint from that one.

One argument recorded for the merging maintainer rather than acted on: a reading exists under which item 6 should be deleted outright rather than trimmed, on the grounds that ROADMAP.md updates are not obviously a per-PR obligation either. That is a scope decision, not this card's, so the line is trimmed as ruled and the argument is left here.

Gates

All run at head 9596a42386, exit codes captured by redirect before any pipe; each verdict below is the gate's own printed line.

CommandExitVerdict
pnpm check:pm-skill-ratchet0AGENTS.md is 1162 lines (ceiling 1162; headroom 0). · AGENTS.md: widest table row is 1081 bytes (pin 1081; headroom 0). · self-test 111 cases pass
pnpm check:pm-governed-prose02 instruction surface(s) name all 5 registered governed surfaces (docs/adr/** · .claude/** · skills/** · AGENTS.md · CLAUDE.md) and claim no others.
pnpm check:pm-skill-id-lint023 file(s) clean (pattern /#[0-9]{3,}/g).
pnpm check:nul-bytes0OK (scanned 8064 text file(s) -- 8064 tracked, 0 untracked-not-ignored; skipped 7 binary; no raw ASCII control bytes).
pnpm check:corpus-claim-drift0OK, no new claim sites beside a pinned spelling.
pnpm check:required-contexts06 required context name(s) pinned across 2 workflow(s); 5 instruction surface(s) scanned against 2 retired name(s).
node scripts/check-required-contexts.mjs0same sweep, direct invocation
pnpm check:agent-test-spelling0violating population empty, 9 separators judged and cleared on the rule
pnpm check:docs-audit-scope0docs-accuracy-audit scope is in sync with content/docs/: 190 hand-written doc(s)
pnpm check:pm-governed-merges0self-test 243 assertions; live: the real generator declared 9 output(s) and certified this tree

The family list was re-derived after the last edit, not taken from the dispatch:
node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands resolved its --repo assertion against this checkout's origin, derived the change set from git as 1 path (AGENTS.md, committed 1 / working tree 0 / untracked 0, three-dot against merge base fc648a256) and emitted 8 commands. All 8 ran; the two dispatch-named gates outside that union (check:nul-bytes, check:corpus-claim-drift) ran as well, so the set above is a superset.

ESLint

Not run repo-wide; narrowed, and the narrowing is a measurement rather than a skip:

  1. Population, read from eslint.config.mjs and not guessed. Every files: selector in the config is a JS/TS extension glob (**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs} and narrower variants; COMMENT_SWALLOW_FILES at :785 is that same glob). grep -cin 'markdown|[.]md' eslint.config.mjs returns 0 — no markdown processor, no .md selector anywhere. Confirmed through ESLint's own API: isPathIgnored('AGENTS.md') is true and calculateConfigForFile('AGENTS.md') yields no rules, against a positive control (eslint.config.mjs itself resolves 2 rules), so the API call is not vacuously quiet.
  2. Count, from --format json.pnpm exec eslint AGENTS.md --no-inline-config --format json gives errorCount: 0, warningCount: 1, the one warning being ruleId: null / File ignored because no matching configuration was supplied — zero rule results, because the file is outside the population.
  3. Invariance over untouched files. The config never enables type-aware linting for any file — no parserOptions.project, no typed rules, stated at eslint.config.mjs:325-332 with its own measured positive control. With no cross-file type program there is no mechanism by which an edit in one file moves a verdict on a file it does not touch, and this diff is one Markdown line in a file ESLint does not lint at all.

A full pnpm lint therefore measures the same nothing this narrowing measured.

Changeset

Labelled skip-changeset, route 2 of scripts/check-empty-changeset.mjs's own enumeration: "It releases nothing (.github/, .claude/, skills/, docs/, content/, examples/, tests-only, and the like) -- delete the changeset and apply the 'skip-changeset' label". This diff is one line of the repo-root instruction file; no packages/** source is touched and nothing publishes from any package. Per that script, the label is a gate-level exemption that produces no input for changesets/action — the shape an empty-frontmatter changeset would have broken.

Landing

Draft, and it stays draft — governed AGENTS.md, human merge is the review record. Not flipped ready, not queued, no auto-merge armed, no reviewers requested.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1

Post-task checklist item 6 read "Update `CHANGELOG.md` / `ROADMAP.md` if
user-facing or architectural", which contradicts the same file 34 lines
above: the changeset section states the changeset body "ships to consumers
as `CHANGELOG.md` inside the npm package". `CHANGELOG.md` is generated
output, written by the changesets release step from the entries item 3
already requires, so item 6 was directing the author to hand-edit a
generated artifact that the next Version Packages run overwrites or
collides with.
Drop the `CHANGELOG.md` half; keep `ROADMAP.md`, which may genuinely be
hand-maintained and is not in question here. Byte-negative on one line
(-17 bytes), no line added or re-wrapped: the file is at its ratchet
ceiling with headroom 0.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1
@github-actions

Copy link
Copy Markdown
Contributor

⛔ merge queue 构建失败 — 先分诊,再决定要不要重排

队列构建 33727530243 红了。队列跑的是全量套件(PR 侧 CI 只跑 affected 子集),
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job(日志抽取,best effort):

  • Test Core (1/6) — 失败步骤: Run this shard's tests

    @objectstack/cli:test: FAIL integration test/run-dev-unbuilt-workspace.e2e.test.ts > the mirror direction: a reader that is never coming back > gives up and exits instead of waiting forever
    ↳ 失败原因: @objectstack/cli:test: AssertionError: the harness SIGKILLed the child — it was still alive at the ceiling. cap 180000 ms (RUN_TIMEOUT_MS, constant and load-independent by design); this child ran 1801
    

↳ 失败原因 是判读的关键:超时Test timed out in … / Hook timed out in …)多半是负载/时序,不是本 PR 的回归;
断言AssertionError: …)才指向真实的行为改变。两者的 FAIL 行长得一模一样,只有这一行能区分。

⚠️断言这一侧有一类例外,判据是断言在测什么,不是它是不是 AssertionError 断言的对象是产品行为(一个值、一个形状、一次拒收)⇒ 照上面读:真实的行为改变,去查,⛔ 不要重排掉;
断言的对象是这次实验自身的有效性前提(跑完的耗时、负载下的先后、任何只在时间预算内才成立的条件)⇒ 它跟超时是同一类,同样对负载敏感,重排一次是合法的判别手段。
识别是机械的:断言的消息或它比较的值本身点名了一段时长、一个时间戳、一个耗时计数。实测过的一对 —— AssertionError: SecurityPlugin.init() ran: expected false to be true 测的是产品行为(真回归);
AssertionError: this run took over a second, so second-precision stamps could have differed too: expected 1006 to be less than 1000 测的是实验前提:它守护的那条不变式当时是绿的,同一个 head 原样重排一次即成功。
穿着 AssertionError 外衣的时间测量,仍然是时间测量。(⛔ 这只改「怎么读一次红」,不改「哪些测试可以重排」——后者由别处管。)

跨 PR 相同签名(24h,按失败测试文件聚合):

历史信号:

  • 本 PR 过去 24h 无队列失败记录(首次)。
  • 过去 24h 队列共有 97 个失败构建(不含本次)。

分诊清单:

  1. 失败测试在本 PR 改动的包里 → 真回归,修 PR。
  2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」;已有汇总 issue ⇒ flaky/环境问题实锤,去那张 issue 上谈,修好前重排只会再烧一轮全队列。
  3. 两者都不是 → 可能与同组 PR 语义冲突;等前面的 PR 落地或失败出队后再重排一次即可,不要连续重排。

Generated by Claude Code · merge-queue-triage workflow (#4859)

@github-actions

Copy link
Copy Markdown
Contributor

⛔ merge queue 构建失败 — 先分诊,再决定要不要重排

队列构建 33729340857 红了。队列跑的是全量套件(PR 侧 CI 只跑 affected 子集),
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job(日志抽取,best effort):

  • Test Core (1/6) — 失败步骤: Run this shard's tests

    @objectstack/cli:test: FAIL integration test/run-dev-unbuilt-workspace.e2e.test.ts > the mirror direction: a reader that is never coming back > gives up and exits instead of waiting forever
    ↳ 失败原因: @objectstack/cli:test: AssertionError: the harness SIGKILLed the child — it was still alive at the ceiling. cap 180000 ms (RUN_TIMEOUT_MS, constant and load-independent by design); this child ran 1800
    

↳ 失败原因 是判读的关键:超时Test timed out in … / Hook timed out in …)多半是负载/时序,不是本 PR 的回归;
断言AssertionError: …)才指向真实的行为改变。两者的 FAIL 行长得一模一样,只有这一行能区分。

⚠️断言这一侧有一类例外,判据是断言在测什么,不是它是不是 AssertionError 断言的对象是产品行为(一个值、一个形状、一次拒收)⇒ 照上面读:真实的行为改变,去查,⛔ 不要重排掉;
断言的对象是这次实验自身的有效性前提(跑完的耗时、负载下的先后、任何只在时间预算内才成立的条件)⇒ 它跟超时是同一类,同样对负载敏感,重排一次是合法的判别手段。
识别是机械的:断言的消息或它比较的值本身点名了一段时长、一个时间戳、一个耗时计数。实测过的一对 —— AssertionError: SecurityPlugin.init() ran: expected false to be true 测的是产品行为(真回归);
AssertionError: this run took over a second, so second-precision stamps could have differed too: expected 1006 to be less than 1000 测的是实验前提:它守护的那条不变式当时是绿的,同一个 head 原样重排一次即成功。
穿着 AssertionError 外衣的时间测量,仍然是时间测量。(⛔ 这只改「怎么读一次红」,不改「哪些测试可以重排」——后者由别处管。)

跨 PR 相同签名(24h,按失败测试文件聚合):

历史信号:

  • ⚠️本 PR 过去 24h 已在队列失败 1 次(不含本次)。 内容未变而反复失败 ⇒ 高度怀疑 flaky 测试或与同组 PR 的语义冲突,重排不解决。
  • 过去 24h 队列共有 105 个失败构建(不含本次)。

分诊清单:

  1. 失败测试在本 PR 改动的包里 → 真回归,修 PR。
  2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」;已有汇总 issue ⇒ flaky/环境问题实锤,去那张 issue 上谈,修好前重排只会再烧一轮全队列。
  3. 两者都不是 → 可能与同组 PR 语义冲突;等前面的 PR 落地或失败出队后再重排一次即可,不要连续重排。

Generated by Claude Code · merge-queue-triage workflow (#4859)

Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentationImprovements or additions to documentationsize/xsskip-changesetPR has no user-facing published change; bypasses the changeset gate

Projects

None yet

3 participants

@os-litant@os-zhuang@claude
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links"); } } catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); } })(); (function(){ try { var __m = "youtube.com"; var __re = new RegExp('^' + "youtube\\.com" + '
Skip to content

docs(agents): stop telling authors to hand-edit generated CHANGELOG.md - #14802

Merged
os-zhuang merged 1 commit into
mainfrom
claude/issue-14792-changelog-checklist-item
Sep 3, 2026
Merged

docs(agents): stop telling authors to hand-edit generated CHANGELOG.md#14802
os-zhuang merged 1 commit into
mainfrom
claude/issue-14792-changelog-checklist-item

Conversation

@os-litant

@os-litantos-litant commented Sep 3, 2026

Copy link
Copy Markdown
Collaborator

Fixes#14792

Post-task checklist item 6 in AGENTS.md told the author to hand-edit CHANGELOG.md. That file is generated output. This drops the CHANGELOG.md half of the line and keeps ROADMAP.md.

Before / after

AGENTS.md:1154

Before:

6. Update `CHANGELOG.md` / `ROADMAP.md` if user-facing or architectural.

After:

6. Update `ROADMAP.md` if user-facing or architectural.

Why

The same file says the opposite about CHANGELOG.md thirty-four lines above. At AGENTS.md:1120, inside checklist item 3, the changeset rule states that the changeset body "ships to consumers as CHANGELOG.md inside the npm package and is what an upgrading agent greps after the tombstone error". That makes CHANGELOG.md the output — written by the changesets release step from the .changeset/*.md entries item 3 already requires.

Item 6 treated the same file as an input. A contributor who obeyed it either hand-edited a generated artifact that the next Version Packages run overwrites or collides with, or read the two lines together and concluded the file contradicts itself on its most-traversed workflow. Nothing is lost by the trim: the changeset obligation is item 3, and it is unchanged here.

Neither reading of the name survives, which is what makes the trim safe rather than a judgement call. Item 6 could have meant the per-package CHANGELOG.md files or the repo-root one, so both were checked:

  • The per-package files are generated. packages/core/CHANGELOG.md and its siblings carry changeset-emitted release sections keyed by commit hash.
  • The root CHANGELOG.md disclaims hand-editing in its own header: the update history "is maintained in three layers rather than by hand-editing this file" — per-package detail "generated by [changesets] from the .changeset/ entries every PR adds", the curated per-major pages under content/docs/releases/, and this file "retained for its historical entries."

So there is no CHANGELOG.md in this repo that item 6 could have legitimately directed a PR author to update by hand.

ROADMAP.md is untouched and not in question, and the surviving half is not vacuous: the file exists at the repo root and its history shows real hand edits. This PR makes no claim about whether that obligation should stand.

Arithmetic

AGENTS.md is at its line-ratchet ceiling, so the edit adds no line and re-wraps nothing.

MeasureBeforeAfter
Lines (wc -l)1,1621,162
Ratchet ceiling / headroom1,162 / 01,162 / 0
Bytes (wc -c)85,10685,089 (-17)
The edited line72 bytes55 bytes (-17)
Widest table row1,081 (pin 1,081)1,081 (pin 1,081)
grep -c 'CHANGELOG.md' AGENTS.md2 (:1120, :1154)1 (:1120 only)

Byte-negative on one line, so nothing is paid same-file. git diff --stat is 1 file changed, 1 insertion(+), 1 deletion(-).

Scope held

Untouched, deliberately: the ROADMAP.md half of item 6, checklist item 3, and the changeset section at :1116-1122 — that region is being corrected by PR #14789, and a second PR editing it would be a merge conflict on a governed file for no gain. The hunk here at :1154 is disjoint from that one.

One argument recorded for the merging maintainer rather than acted on: a reading exists under which item 6 should be deleted outright rather than trimmed, on the grounds that ROADMAP.md updates are not obviously a per-PR obligation either. That is a scope decision, not this card's, so the line is trimmed as ruled and the argument is left here.

Gates

All run at head 9596a42386, exit codes captured by redirect before any pipe; each verdict below is the gate's own printed line.

CommandExitVerdict
pnpm check:pm-skill-ratchet0AGENTS.md is 1162 lines (ceiling 1162; headroom 0). · AGENTS.md: widest table row is 1081 bytes (pin 1081; headroom 0). · self-test 111 cases pass
pnpm check:pm-governed-prose02 instruction surface(s) name all 5 registered governed surfaces (docs/adr/** · .claude/** · skills/** · AGENTS.md · CLAUDE.md) and claim no others.
pnpm check:pm-skill-id-lint023 file(s) clean (pattern /#[0-9]{3,}/g).
pnpm check:nul-bytes0OK (scanned 8064 text file(s) -- 8064 tracked, 0 untracked-not-ignored; skipped 7 binary; no raw ASCII control bytes).
pnpm check:corpus-claim-drift0OK, no new claim sites beside a pinned spelling.
pnpm check:required-contexts06 required context name(s) pinned across 2 workflow(s); 5 instruction surface(s) scanned against 2 retired name(s).
node scripts/check-required-contexts.mjs0same sweep, direct invocation
pnpm check:agent-test-spelling0violating population empty, 9 separators judged and cleared on the rule
pnpm check:docs-audit-scope0docs-accuracy-audit scope is in sync with content/docs/: 190 hand-written doc(s)
pnpm check:pm-governed-merges0self-test 243 assertions; live: the real generator declared 9 output(s) and certified this tree

The family list was re-derived after the last edit, not taken from the dispatch:
node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands resolved its --repo assertion against this checkout's origin, derived the change set from git as 1 path (AGENTS.md, committed 1 / working tree 0 / untracked 0, three-dot against merge base fc648a256) and emitted 8 commands. All 8 ran; the two dispatch-named gates outside that union (check:nul-bytes, check:corpus-claim-drift) ran as well, so the set above is a superset.

ESLint

Not run repo-wide; narrowed, and the narrowing is a measurement rather than a skip:

  1. Population, read from eslint.config.mjs and not guessed. Every files: selector in the config is a JS/TS extension glob (**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs} and narrower variants; COMMENT_SWALLOW_FILES at :785 is that same glob). grep -cin 'markdown|[.]md' eslint.config.mjs returns 0 — no markdown processor, no .md selector anywhere. Confirmed through ESLint's own API: isPathIgnored('AGENTS.md') is true and calculateConfigForFile('AGENTS.md') yields no rules, against a positive control (eslint.config.mjs itself resolves 2 rules), so the API call is not vacuously quiet.
  2. Count, from --format json.pnpm exec eslint AGENTS.md --no-inline-config --format json gives errorCount: 0, warningCount: 1, the one warning being ruleId: null / File ignored because no matching configuration was supplied — zero rule results, because the file is outside the population.
  3. Invariance over untouched files. The config never enables type-aware linting for any file — no parserOptions.project, no typed rules, stated at eslint.config.mjs:325-332 with its own measured positive control. With no cross-file type program there is no mechanism by which an edit in one file moves a verdict on a file it does not touch, and this diff is one Markdown line in a file ESLint does not lint at all.

A full pnpm lint therefore measures the same nothing this narrowing measured.

Changeset

Labelled skip-changeset, route 2 of scripts/check-empty-changeset.mjs's own enumeration: "It releases nothing (.github/, .claude/, skills/, docs/, content/, examples/, tests-only, and the like) -- delete the changeset and apply the 'skip-changeset' label". This diff is one line of the repo-root instruction file; no packages/** source is touched and nothing publishes from any package. Per that script, the label is a gate-level exemption that produces no input for changesets/action — the shape an empty-frontmatter changeset would have broken.

Landing

Draft, and it stays draft — governed AGENTS.md, human merge is the review record. Not flipped ready, not queued, no auto-merge armed, no reviewers requested.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1

Post-task checklist item 6 read "Update `CHANGELOG.md` / `ROADMAP.md` if
user-facing or architectural", which contradicts the same file 34 lines
above: the changeset section states the changeset body "ships to consumers
as `CHANGELOG.md` inside the npm package". `CHANGELOG.md` is generated
output, written by the changesets release step from the entries item 3
already requires, so item 6 was directing the author to hand-edit a
generated artifact that the next Version Packages run overwrites or
collides with.
Drop the `CHANGELOG.md` half; keep `ROADMAP.md`, which may genuinely be
hand-maintained and is not in question here. Byte-negative on one line
(-17 bytes), no line added or re-wrapped: the file is at its ratchet
ceiling with headroom 0.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1
@github-actions

Copy link
Copy Markdown
Contributor

⛔ merge queue 构建失败 — 先分诊,再决定要不要重排

队列构建 33727530243 红了。队列跑的是全量套件(PR 侧 CI 只跑 affected 子集),
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job(日志抽取,best effort):

  • Test Core (1/6) — 失败步骤: Run this shard's tests

    @objectstack/cli:test: FAIL integration test/run-dev-unbuilt-workspace.e2e.test.ts > the mirror direction: a reader that is never coming back > gives up and exits instead of waiting forever
    ↳ 失败原因: @objectstack/cli:test: AssertionError: the harness SIGKILLed the child — it was still alive at the ceiling. cap 180000 ms (RUN_TIMEOUT_MS, constant and load-independent by design); this child ran 1801
    

↳ 失败原因 是判读的关键:超时Test timed out in … / Hook timed out in …)多半是负载/时序,不是本 PR 的回归;
断言AssertionError: …)才指向真实的行为改变。两者的 FAIL 行长得一模一样,只有这一行能区分。

⚠️断言这一侧有一类例外,判据是断言在测什么,不是它是不是 AssertionError 断言的对象是产品行为(一个值、一个形状、一次拒收)⇒ 照上面读:真实的行为改变,去查,⛔ 不要重排掉;
断言的对象是这次实验自身的有效性前提(跑完的耗时、负载下的先后、任何只在时间预算内才成立的条件)⇒ 它跟超时是同一类,同样对负载敏感,重排一次是合法的判别手段。
识别是机械的:断言的消息或它比较的值本身点名了一段时长、一个时间戳、一个耗时计数。实测过的一对 —— AssertionError: SecurityPlugin.init() ran: expected false to be true 测的是产品行为(真回归);
AssertionError: this run took over a second, so second-precision stamps could have differed too: expected 1006 to be less than 1000 测的是实验前提:它守护的那条不变式当时是绿的,同一个 head 原样重排一次即成功。
穿着 AssertionError 外衣的时间测量,仍然是时间测量。(⛔ 这只改「怎么读一次红」,不改「哪些测试可以重排」——后者由别处管。)

跨 PR 相同签名(24h,按失败测试文件聚合):

历史信号:

  • 本 PR 过去 24h 无队列失败记录(首次)。
  • 过去 24h 队列共有 97 个失败构建(不含本次)。

分诊清单:

  1. 失败测试在本 PR 改动的包里 → 真回归,修 PR。
  2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」;已有汇总 issue ⇒ flaky/环境问题实锤,去那张 issue 上谈,修好前重排只会再烧一轮全队列。
  3. 两者都不是 → 可能与同组 PR 语义冲突;等前面的 PR 落地或失败出队后再重排一次即可,不要连续重排。

Generated by Claude Code · merge-queue-triage workflow (#4859)

@github-actions

Copy link
Copy Markdown
Contributor

⛔ merge queue 构建失败 — 先分诊,再决定要不要重排

队列构建 33729340857 红了。队列跑的是全量套件(PR 侧 CI 只跑 affected 子集),
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job(日志抽取,best effort):

  • Test Core (1/6) — 失败步骤: Run this shard's tests

    @objectstack/cli:test: FAIL integration test/run-dev-unbuilt-workspace.e2e.test.ts > the mirror direction: a reader that is never coming back > gives up and exits instead of waiting forever
    ↳ 失败原因: @objectstack/cli:test: AssertionError: the harness SIGKILLed the child — it was still alive at the ceiling. cap 180000 ms (RUN_TIMEOUT_MS, constant and load-independent by design); this child ran 1800
    

↳ 失败原因 是判读的关键:超时Test timed out in … / Hook timed out in …)多半是负载/时序,不是本 PR 的回归;
断言AssertionError: …)才指向真实的行为改变。两者的 FAIL 行长得一模一样,只有这一行能区分。

⚠️断言这一侧有一类例外,判据是断言在测什么,不是它是不是 AssertionError 断言的对象是产品行为(一个值、一个形状、一次拒收)⇒ 照上面读:真实的行为改变,去查,⛔ 不要重排掉;
断言的对象是这次实验自身的有效性前提(跑完的耗时、负载下的先后、任何只在时间预算内才成立的条件)⇒ 它跟超时是同一类,同样对负载敏感,重排一次是合法的判别手段。
识别是机械的:断言的消息或它比较的值本身点名了一段时长、一个时间戳、一个耗时计数。实测过的一对 —— AssertionError: SecurityPlugin.init() ran: expected false to be true 测的是产品行为(真回归);
AssertionError: this run took over a second, so second-precision stamps could have differed too: expected 1006 to be less than 1000 测的是实验前提:它守护的那条不变式当时是绿的,同一个 head 原样重排一次即成功。
穿着 AssertionError 外衣的时间测量,仍然是时间测量。(⛔ 这只改「怎么读一次红」,不改「哪些测试可以重排」——后者由别处管。)

跨 PR 相同签名(24h,按失败测试文件聚合):

历史信号:

  • ⚠️本 PR 过去 24h 已在队列失败 1 次(不含本次)。 内容未变而反复失败 ⇒ 高度怀疑 flaky 测试或与同组 PR 的语义冲突,重排不解决。
  • 过去 24h 队列共有 105 个失败构建(不含本次)。

分诊清单:

  1. 失败测试在本 PR 改动的包里 → 真回归,修 PR。
  2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」;已有汇总 issue ⇒ flaky/环境问题实锤,去那张 issue 上谈,修好前重排只会再烧一轮全队列。
  3. 两者都不是 → 可能与同组 PR 语义冲突;等前面的 PR 落地或失败出队后再重排一次即可,不要连续重排。

Generated by Claude Code · merge-queue-triage workflow (#4859)

Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentationImprovements or additions to documentationsize/xsskip-changesetPR has no user-facing published change; bypasses the changeset gate

Projects

None yet

3 participants

@os-litant@os-zhuang@claude
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default"); } } catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + '
Skip to content

docs(agents): stop telling authors to hand-edit generated CHANGELOG.md - #14802

Merged
os-zhuang merged 1 commit into
mainfrom
claude/issue-14792-changelog-checklist-item
Sep 3, 2026
Merged

docs(agents): stop telling authors to hand-edit generated CHANGELOG.md#14802
os-zhuang merged 1 commit into
mainfrom
claude/issue-14792-changelog-checklist-item

Conversation

@os-litant

@os-litantos-litant commented Sep 3, 2026

Copy link
Copy Markdown
Collaborator

Fixes#14792

Post-task checklist item 6 in AGENTS.md told the author to hand-edit CHANGELOG.md. That file is generated output. This drops the CHANGELOG.md half of the line and keeps ROADMAP.md.

Before / after

AGENTS.md:1154

Before:

6. Update `CHANGELOG.md` / `ROADMAP.md` if user-facing or architectural.

After:

6. Update `ROADMAP.md` if user-facing or architectural.

Why

The same file says the opposite about CHANGELOG.md thirty-four lines above. At AGENTS.md:1120, inside checklist item 3, the changeset rule states that the changeset body "ships to consumers as CHANGELOG.md inside the npm package and is what an upgrading agent greps after the tombstone error". That makes CHANGELOG.md the output — written by the changesets release step from the .changeset/*.md entries item 3 already requires.

Item 6 treated the same file as an input. A contributor who obeyed it either hand-edited a generated artifact that the next Version Packages run overwrites or collides with, or read the two lines together and concluded the file contradicts itself on its most-traversed workflow. Nothing is lost by the trim: the changeset obligation is item 3, and it is unchanged here.

Neither reading of the name survives, which is what makes the trim safe rather than a judgement call. Item 6 could have meant the per-package CHANGELOG.md files or the repo-root one, so both were checked:

  • The per-package files are generated. packages/core/CHANGELOG.md and its siblings carry changeset-emitted release sections keyed by commit hash.
  • The root CHANGELOG.md disclaims hand-editing in its own header: the update history "is maintained in three layers rather than by hand-editing this file" — per-package detail "generated by [changesets] from the .changeset/ entries every PR adds", the curated per-major pages under content/docs/releases/, and this file "retained for its historical entries."

So there is no CHANGELOG.md in this repo that item 6 could have legitimately directed a PR author to update by hand.

ROADMAP.md is untouched and not in question, and the surviving half is not vacuous: the file exists at the repo root and its history shows real hand edits. This PR makes no claim about whether that obligation should stand.

Arithmetic

AGENTS.md is at its line-ratchet ceiling, so the edit adds no line and re-wraps nothing.

MeasureBeforeAfter
Lines (wc -l)1,1621,162
Ratchet ceiling / headroom1,162 / 01,162 / 0
Bytes (wc -c)85,10685,089 (-17)
The edited line72 bytes55 bytes (-17)
Widest table row1,081 (pin 1,081)1,081 (pin 1,081)
grep -c 'CHANGELOG.md' AGENTS.md2 (:1120, :1154)1 (:1120 only)

Byte-negative on one line, so nothing is paid same-file. git diff --stat is 1 file changed, 1 insertion(+), 1 deletion(-).

Scope held

Untouched, deliberately: the ROADMAP.md half of item 6, checklist item 3, and the changeset section at :1116-1122 — that region is being corrected by PR #14789, and a second PR editing it would be a merge conflict on a governed file for no gain. The hunk here at :1154 is disjoint from that one.

One argument recorded for the merging maintainer rather than acted on: a reading exists under which item 6 should be deleted outright rather than trimmed, on the grounds that ROADMAP.md updates are not obviously a per-PR obligation either. That is a scope decision, not this card's, so the line is trimmed as ruled and the argument is left here.

Gates

All run at head 9596a42386, exit codes captured by redirect before any pipe; each verdict below is the gate's own printed line.

CommandExitVerdict
pnpm check:pm-skill-ratchet0AGENTS.md is 1162 lines (ceiling 1162; headroom 0). · AGENTS.md: widest table row is 1081 bytes (pin 1081; headroom 0). · self-test 111 cases pass
pnpm check:pm-governed-prose02 instruction surface(s) name all 5 registered governed surfaces (docs/adr/** · .claude/** · skills/** · AGENTS.md · CLAUDE.md) and claim no others.
pnpm check:pm-skill-id-lint023 file(s) clean (pattern /#[0-9]{3,}/g).
pnpm check:nul-bytes0OK (scanned 8064 text file(s) -- 8064 tracked, 0 untracked-not-ignored; skipped 7 binary; no raw ASCII control bytes).
pnpm check:corpus-claim-drift0OK, no new claim sites beside a pinned spelling.
pnpm check:required-contexts06 required context name(s) pinned across 2 workflow(s); 5 instruction surface(s) scanned against 2 retired name(s).
node scripts/check-required-contexts.mjs0same sweep, direct invocation
pnpm check:agent-test-spelling0violating population empty, 9 separators judged and cleared on the rule
pnpm check:docs-audit-scope0docs-accuracy-audit scope is in sync with content/docs/: 190 hand-written doc(s)
pnpm check:pm-governed-merges0self-test 243 assertions; live: the real generator declared 9 output(s) and certified this tree

The family list was re-derived after the last edit, not taken from the dispatch:
node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands resolved its --repo assertion against this checkout's origin, derived the change set from git as 1 path (AGENTS.md, committed 1 / working tree 0 / untracked 0, three-dot against merge base fc648a256) and emitted 8 commands. All 8 ran; the two dispatch-named gates outside that union (check:nul-bytes, check:corpus-claim-drift) ran as well, so the set above is a superset.

ESLint

Not run repo-wide; narrowed, and the narrowing is a measurement rather than a skip:

  1. Population, read from eslint.config.mjs and not guessed. Every files: selector in the config is a JS/TS extension glob (**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs} and narrower variants; COMMENT_SWALLOW_FILES at :785 is that same glob). grep -cin 'markdown|[.]md' eslint.config.mjs returns 0 — no markdown processor, no .md selector anywhere. Confirmed through ESLint's own API: isPathIgnored('AGENTS.md') is true and calculateConfigForFile('AGENTS.md') yields no rules, against a positive control (eslint.config.mjs itself resolves 2 rules), so the API call is not vacuously quiet.
  2. Count, from --format json.pnpm exec eslint AGENTS.md --no-inline-config --format json gives errorCount: 0, warningCount: 1, the one warning being ruleId: null / File ignored because no matching configuration was supplied — zero rule results, because the file is outside the population.
  3. Invariance over untouched files. The config never enables type-aware linting for any file — no parserOptions.project, no typed rules, stated at eslint.config.mjs:325-332 with its own measured positive control. With no cross-file type program there is no mechanism by which an edit in one file moves a verdict on a file it does not touch, and this diff is one Markdown line in a file ESLint does not lint at all.

A full pnpm lint therefore measures the same nothing this narrowing measured.

Changeset

Labelled skip-changeset, route 2 of scripts/check-empty-changeset.mjs's own enumeration: "It releases nothing (.github/, .claude/, skills/, docs/, content/, examples/, tests-only, and the like) -- delete the changeset and apply the 'skip-changeset' label". This diff is one line of the repo-root instruction file; no packages/** source is touched and nothing publishes from any package. Per that script, the label is a gate-level exemption that produces no input for changesets/action — the shape an empty-frontmatter changeset would have broken.

Landing

Draft, and it stays draft — governed AGENTS.md, human merge is the review record. Not flipped ready, not queued, no auto-merge armed, no reviewers requested.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1

Post-task checklist item 6 read "Update `CHANGELOG.md` / `ROADMAP.md` if
user-facing or architectural", which contradicts the same file 34 lines
above: the changeset section states the changeset body "ships to consumers
as `CHANGELOG.md` inside the npm package". `CHANGELOG.md` is generated
output, written by the changesets release step from the entries item 3
already requires, so item 6 was directing the author to hand-edit a
generated artifact that the next Version Packages run overwrites or
collides with.
Drop the `CHANGELOG.md` half; keep `ROADMAP.md`, which may genuinely be
hand-maintained and is not in question here. Byte-negative on one line
(-17 bytes), no line added or re-wrapped: the file is at its ratchet
ceiling with headroom 0.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1
@github-actions

Copy link
Copy Markdown
Contributor

⛔ merge queue 构建失败 — 先分诊,再决定要不要重排

队列构建 33727530243 红了。队列跑的是全量套件(PR 侧 CI 只跑 affected 子集),
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job(日志抽取,best effort):

  • Test Core (1/6) — 失败步骤: Run this shard's tests

    @objectstack/cli:test: FAIL integration test/run-dev-unbuilt-workspace.e2e.test.ts > the mirror direction: a reader that is never coming back > gives up and exits instead of waiting forever
    ↳ 失败原因: @objectstack/cli:test: AssertionError: the harness SIGKILLed the child — it was still alive at the ceiling. cap 180000 ms (RUN_TIMEOUT_MS, constant and load-independent by design); this child ran 1801
    

↳ 失败原因 是判读的关键:超时Test timed out in … / Hook timed out in …)多半是负载/时序,不是本 PR 的回归;
断言AssertionError: …)才指向真实的行为改变。两者的 FAIL 行长得一模一样,只有这一行能区分。

⚠️断言这一侧有一类例外,判据是断言在测什么,不是它是不是 AssertionError 断言的对象是产品行为(一个值、一个形状、一次拒收)⇒ 照上面读:真实的行为改变,去查,⛔ 不要重排掉;
断言的对象是这次实验自身的有效性前提(跑完的耗时、负载下的先后、任何只在时间预算内才成立的条件)⇒ 它跟超时是同一类,同样对负载敏感,重排一次是合法的判别手段。
识别是机械的:断言的消息或它比较的值本身点名了一段时长、一个时间戳、一个耗时计数。实测过的一对 —— AssertionError: SecurityPlugin.init() ran: expected false to be true 测的是产品行为(真回归);
AssertionError: this run took over a second, so second-precision stamps could have differed too: expected 1006 to be less than 1000 测的是实验前提:它守护的那条不变式当时是绿的,同一个 head 原样重排一次即成功。
穿着 AssertionError 外衣的时间测量,仍然是时间测量。(⛔ 这只改「怎么读一次红」,不改「哪些测试可以重排」——后者由别处管。)

跨 PR 相同签名(24h,按失败测试文件聚合):

历史信号:

  • 本 PR 过去 24h 无队列失败记录(首次)。
  • 过去 24h 队列共有 97 个失败构建(不含本次)。

分诊清单:

  1. 失败测试在本 PR 改动的包里 → 真回归,修 PR。
  2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」;已有汇总 issue ⇒ flaky/环境问题实锤,去那张 issue 上谈,修好前重排只会再烧一轮全队列。
  3. 两者都不是 → 可能与同组 PR 语义冲突;等前面的 PR 落地或失败出队后再重排一次即可,不要连续重排。

Generated by Claude Code · merge-queue-triage workflow (#4859)

@github-actions

Copy link
Copy Markdown
Contributor

⛔ merge queue 构建失败 — 先分诊,再决定要不要重排

队列构建 33729340857 红了。队列跑的是全量套件(PR 侧 CI 只跑 affected 子集),
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job(日志抽取,best effort):

  • Test Core (1/6) — 失败步骤: Run this shard's tests

    @objectstack/cli:test: FAIL integration test/run-dev-unbuilt-workspace.e2e.test.ts > the mirror direction: a reader that is never coming back > gives up and exits instead of waiting forever
    ↳ 失败原因: @objectstack/cli:test: AssertionError: the harness SIGKILLed the child — it was still alive at the ceiling. cap 180000 ms (RUN_TIMEOUT_MS, constant and load-independent by design); this child ran 1800
    

↳ 失败原因 是判读的关键:超时Test timed out in … / Hook timed out in …)多半是负载/时序,不是本 PR 的回归;
断言AssertionError: …)才指向真实的行为改变。两者的 FAIL 行长得一模一样,只有这一行能区分。

⚠️断言这一侧有一类例外,判据是断言在测什么,不是它是不是 AssertionError 断言的对象是产品行为(一个值、一个形状、一次拒收)⇒ 照上面读:真实的行为改变,去查,⛔ 不要重排掉;
断言的对象是这次实验自身的有效性前提(跑完的耗时、负载下的先后、任何只在时间预算内才成立的条件)⇒ 它跟超时是同一类,同样对负载敏感,重排一次是合法的判别手段。
识别是机械的:断言的消息或它比较的值本身点名了一段时长、一个时间戳、一个耗时计数。实测过的一对 —— AssertionError: SecurityPlugin.init() ran: expected false to be true 测的是产品行为(真回归);
AssertionError: this run took over a second, so second-precision stamps could have differed too: expected 1006 to be less than 1000 测的是实验前提:它守护的那条不变式当时是绿的,同一个 head 原样重排一次即成功。
穿着 AssertionError 外衣的时间测量,仍然是时间测量。(⛔ 这只改「怎么读一次红」,不改「哪些测试可以重排」——后者由别处管。)

跨 PR 相同签名(24h,按失败测试文件聚合):

历史信号:

  • ⚠️本 PR 过去 24h 已在队列失败 1 次(不含本次)。 内容未变而反复失败 ⇒ 高度怀疑 flaky 测试或与同组 PR 的语义冲突,重排不解决。
  • 过去 24h 队列共有 105 个失败构建(不含本次)。

分诊清单:

  1. 失败测试在本 PR 改动的包里 → 真回归,修 PR。
  2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」;已有汇总 issue ⇒ flaky/环境问题实锤,去那张 issue 上谈,修好前重排只会再烧一轮全队列。
  3. 两者都不是 → 可能与同组 PR 语义冲突;等前面的 PR 落地或失败出队后再重排一次即可,不要连续重排。

Generated by Claude Code · merge-queue-triage workflow (#4859)

Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentationImprovements or additions to documentationsize/xsskip-changesetPR has no user-facing published change; bypasses the changeset gate

Projects

None yet

3 participants

@os-litant@os-zhuang@claude
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers"); } } catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + '
Skip to content

docs(agents): stop telling authors to hand-edit generated CHANGELOG.md - #14802

Merged
os-zhuang merged 1 commit into
mainfrom
claude/issue-14792-changelog-checklist-item
Sep 3, 2026
Merged

docs(agents): stop telling authors to hand-edit generated CHANGELOG.md#14802
os-zhuang merged 1 commit into
mainfrom
claude/issue-14792-changelog-checklist-item

Conversation

@os-litant

@os-litantos-litant commented Sep 3, 2026

Copy link
Copy Markdown
Collaborator

Fixes#14792

Post-task checklist item 6 in AGENTS.md told the author to hand-edit CHANGELOG.md. That file is generated output. This drops the CHANGELOG.md half of the line and keeps ROADMAP.md.

Before / after

AGENTS.md:1154

Before:

6. Update `CHANGELOG.md` / `ROADMAP.md` if user-facing or architectural.

After:

6. Update `ROADMAP.md` if user-facing or architectural.

Why

The same file says the opposite about CHANGELOG.md thirty-four lines above. At AGENTS.md:1120, inside checklist item 3, the changeset rule states that the changeset body "ships to consumers as CHANGELOG.md inside the npm package and is what an upgrading agent greps after the tombstone error". That makes CHANGELOG.md the output — written by the changesets release step from the .changeset/*.md entries item 3 already requires.

Item 6 treated the same file as an input. A contributor who obeyed it either hand-edited a generated artifact that the next Version Packages run overwrites or collides with, or read the two lines together and concluded the file contradicts itself on its most-traversed workflow. Nothing is lost by the trim: the changeset obligation is item 3, and it is unchanged here.

Neither reading of the name survives, which is what makes the trim safe rather than a judgement call. Item 6 could have meant the per-package CHANGELOG.md files or the repo-root one, so both were checked:

  • The per-package files are generated. packages/core/CHANGELOG.md and its siblings carry changeset-emitted release sections keyed by commit hash.
  • The root CHANGELOG.md disclaims hand-editing in its own header: the update history "is maintained in three layers rather than by hand-editing this file" — per-package detail "generated by [changesets] from the .changeset/ entries every PR adds", the curated per-major pages under content/docs/releases/, and this file "retained for its historical entries."

So there is no CHANGELOG.md in this repo that item 6 could have legitimately directed a PR author to update by hand.

ROADMAP.md is untouched and not in question, and the surviving half is not vacuous: the file exists at the repo root and its history shows real hand edits. This PR makes no claim about whether that obligation should stand.

Arithmetic

AGENTS.md is at its line-ratchet ceiling, so the edit adds no line and re-wraps nothing.

MeasureBeforeAfter
Lines (wc -l)1,1621,162
Ratchet ceiling / headroom1,162 / 01,162 / 0
Bytes (wc -c)85,10685,089 (-17)
The edited line72 bytes55 bytes (-17)
Widest table row1,081 (pin 1,081)1,081 (pin 1,081)
grep -c 'CHANGELOG.md' AGENTS.md2 (:1120, :1154)1 (:1120 only)

Byte-negative on one line, so nothing is paid same-file. git diff --stat is 1 file changed, 1 insertion(+), 1 deletion(-).

Scope held

Untouched, deliberately: the ROADMAP.md half of item 6, checklist item 3, and the changeset section at :1116-1122 — that region is being corrected by PR #14789, and a second PR editing it would be a merge conflict on a governed file for no gain. The hunk here at :1154 is disjoint from that one.

One argument recorded for the merging maintainer rather than acted on: a reading exists under which item 6 should be deleted outright rather than trimmed, on the grounds that ROADMAP.md updates are not obviously a per-PR obligation either. That is a scope decision, not this card's, so the line is trimmed as ruled and the argument is left here.

Gates

All run at head 9596a42386, exit codes captured by redirect before any pipe; each verdict below is the gate's own printed line.

CommandExitVerdict
pnpm check:pm-skill-ratchet0AGENTS.md is 1162 lines (ceiling 1162; headroom 0). · AGENTS.md: widest table row is 1081 bytes (pin 1081; headroom 0). · self-test 111 cases pass
pnpm check:pm-governed-prose02 instruction surface(s) name all 5 registered governed surfaces (docs/adr/** · .claude/** · skills/** · AGENTS.md · CLAUDE.md) and claim no others.
pnpm check:pm-skill-id-lint023 file(s) clean (pattern /#[0-9]{3,}/g).
pnpm check:nul-bytes0OK (scanned 8064 text file(s) -- 8064 tracked, 0 untracked-not-ignored; skipped 7 binary; no raw ASCII control bytes).
pnpm check:corpus-claim-drift0OK, no new claim sites beside a pinned spelling.
pnpm check:required-contexts06 required context name(s) pinned across 2 workflow(s); 5 instruction surface(s) scanned against 2 retired name(s).
node scripts/check-required-contexts.mjs0same sweep, direct invocation
pnpm check:agent-test-spelling0violating population empty, 9 separators judged and cleared on the rule
pnpm check:docs-audit-scope0docs-accuracy-audit scope is in sync with content/docs/: 190 hand-written doc(s)
pnpm check:pm-governed-merges0self-test 243 assertions; live: the real generator declared 9 output(s) and certified this tree

The family list was re-derived after the last edit, not taken from the dispatch:
node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands resolved its --repo assertion against this checkout's origin, derived the change set from git as 1 path (AGENTS.md, committed 1 / working tree 0 / untracked 0, three-dot against merge base fc648a256) and emitted 8 commands. All 8 ran; the two dispatch-named gates outside that union (check:nul-bytes, check:corpus-claim-drift) ran as well, so the set above is a superset.

ESLint

Not run repo-wide; narrowed, and the narrowing is a measurement rather than a skip:

  1. Population, read from eslint.config.mjs and not guessed. Every files: selector in the config is a JS/TS extension glob (**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs} and narrower variants; COMMENT_SWALLOW_FILES at :785 is that same glob). grep -cin 'markdown|[.]md' eslint.config.mjs returns 0 — no markdown processor, no .md selector anywhere. Confirmed through ESLint's own API: isPathIgnored('AGENTS.md') is true and calculateConfigForFile('AGENTS.md') yields no rules, against a positive control (eslint.config.mjs itself resolves 2 rules), so the API call is not vacuously quiet.
  2. Count, from --format json.pnpm exec eslint AGENTS.md --no-inline-config --format json gives errorCount: 0, warningCount: 1, the one warning being ruleId: null / File ignored because no matching configuration was supplied — zero rule results, because the file is outside the population.
  3. Invariance over untouched files. The config never enables type-aware linting for any file — no parserOptions.project, no typed rules, stated at eslint.config.mjs:325-332 with its own measured positive control. With no cross-file type program there is no mechanism by which an edit in one file moves a verdict on a file it does not touch, and this diff is one Markdown line in a file ESLint does not lint at all.

A full pnpm lint therefore measures the same nothing this narrowing measured.

Changeset

Labelled skip-changeset, route 2 of scripts/check-empty-changeset.mjs's own enumeration: "It releases nothing (.github/, .claude/, skills/, docs/, content/, examples/, tests-only, and the like) -- delete the changeset and apply the 'skip-changeset' label". This diff is one line of the repo-root instruction file; no packages/** source is touched and nothing publishes from any package. Per that script, the label is a gate-level exemption that produces no input for changesets/action — the shape an empty-frontmatter changeset would have broken.

Landing

Draft, and it stays draft — governed AGENTS.md, human merge is the review record. Not flipped ready, not queued, no auto-merge armed, no reviewers requested.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1

Post-task checklist item 6 read "Update `CHANGELOG.md` / `ROADMAP.md` if
user-facing or architectural", which contradicts the same file 34 lines
above: the changeset section states the changeset body "ships to consumers
as `CHANGELOG.md` inside the npm package". `CHANGELOG.md` is generated
output, written by the changesets release step from the entries item 3
already requires, so item 6 was directing the author to hand-edit a
generated artifact that the next Version Packages run overwrites or
collides with.
Drop the `CHANGELOG.md` half; keep `ROADMAP.md`, which may genuinely be
hand-maintained and is not in question here. Byte-negative on one line
(-17 bytes), no line added or re-wrapped: the file is at its ratchet
ceiling with headroom 0.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1
@github-actions

Copy link
Copy Markdown
Contributor

⛔ merge queue 构建失败 — 先分诊,再决定要不要重排

队列构建 33727530243 红了。队列跑的是全量套件(PR 侧 CI 只跑 affected 子集),
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job(日志抽取,best effort):

  • Test Core (1/6) — 失败步骤: Run this shard's tests

    @objectstack/cli:test: FAIL integration test/run-dev-unbuilt-workspace.e2e.test.ts > the mirror direction: a reader that is never coming back > gives up and exits instead of waiting forever
    ↳ 失败原因: @objectstack/cli:test: AssertionError: the harness SIGKILLed the child — it was still alive at the ceiling. cap 180000 ms (RUN_TIMEOUT_MS, constant and load-independent by design); this child ran 1801
    

↳ 失败原因 是判读的关键:超时Test timed out in … / Hook timed out in …)多半是负载/时序,不是本 PR 的回归;
断言AssertionError: …)才指向真实的行为改变。两者的 FAIL 行长得一模一样,只有这一行能区分。

⚠️断言这一侧有一类例外,判据是断言在测什么,不是它是不是 AssertionError 断言的对象是产品行为(一个值、一个形状、一次拒收)⇒ 照上面读:真实的行为改变,去查,⛔ 不要重排掉;
断言的对象是这次实验自身的有效性前提(跑完的耗时、负载下的先后、任何只在时间预算内才成立的条件)⇒ 它跟超时是同一类,同样对负载敏感,重排一次是合法的判别手段。
识别是机械的:断言的消息或它比较的值本身点名了一段时长、一个时间戳、一个耗时计数。实测过的一对 —— AssertionError: SecurityPlugin.init() ran: expected false to be true 测的是产品行为(真回归);
AssertionError: this run took over a second, so second-precision stamps could have differed too: expected 1006 to be less than 1000 测的是实验前提:它守护的那条不变式当时是绿的,同一个 head 原样重排一次即成功。
穿着 AssertionError 外衣的时间测量,仍然是时间测量。(⛔ 这只改「怎么读一次红」,不改「哪些测试可以重排」——后者由别处管。)

跨 PR 相同签名(24h,按失败测试文件聚合):

历史信号:

  • 本 PR 过去 24h 无队列失败记录(首次)。
  • 过去 24h 队列共有 97 个失败构建(不含本次)。

分诊清单:

  1. 失败测试在本 PR 改动的包里 → 真回归,修 PR。
  2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」;已有汇总 issue ⇒ flaky/环境问题实锤,去那张 issue 上谈,修好前重排只会再烧一轮全队列。
  3. 两者都不是 → 可能与同组 PR 语义冲突;等前面的 PR 落地或失败出队后再重排一次即可,不要连续重排。

Generated by Claude Code · merge-queue-triage workflow (#4859)

@github-actions

Copy link
Copy Markdown
Contributor

⛔ merge queue 构建失败 — 先分诊,再决定要不要重排

队列构建 33729340857 红了。队列跑的是全量套件(PR 侧 CI 只跑 affected 子集),
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job(日志抽取,best effort):

  • Test Core (1/6) — 失败步骤: Run this shard's tests

    @objectstack/cli:test: FAIL integration test/run-dev-unbuilt-workspace.e2e.test.ts > the mirror direction: a reader that is never coming back > gives up and exits instead of waiting forever
    ↳ 失败原因: @objectstack/cli:test: AssertionError: the harness SIGKILLed the child — it was still alive at the ceiling. cap 180000 ms (RUN_TIMEOUT_MS, constant and load-independent by design); this child ran 1800
    

↳ 失败原因 是判读的关键:超时Test timed out in … / Hook timed out in …)多半是负载/时序,不是本 PR 的回归;
断言AssertionError: …)才指向真实的行为改变。两者的 FAIL 行长得一模一样,只有这一行能区分。

⚠️断言这一侧有一类例外,判据是断言在测什么,不是它是不是 AssertionError 断言的对象是产品行为(一个值、一个形状、一次拒收)⇒ 照上面读:真实的行为改变,去查,⛔ 不要重排掉;
断言的对象是这次实验自身的有效性前提(跑完的耗时、负载下的先后、任何只在时间预算内才成立的条件)⇒ 它跟超时是同一类,同样对负载敏感,重排一次是合法的判别手段。
识别是机械的:断言的消息或它比较的值本身点名了一段时长、一个时间戳、一个耗时计数。实测过的一对 —— AssertionError: SecurityPlugin.init() ran: expected false to be true 测的是产品行为(真回归);
AssertionError: this run took over a second, so second-precision stamps could have differed too: expected 1006 to be less than 1000 测的是实验前提:它守护的那条不变式当时是绿的,同一个 head 原样重排一次即成功。
穿着 AssertionError 外衣的时间测量,仍然是时间测量。(⛔ 这只改「怎么读一次红」,不改「哪些测试可以重排」——后者由别处管。)

跨 PR 相同签名(24h,按失败测试文件聚合):

历史信号:

  • ⚠️本 PR 过去 24h 已在队列失败 1 次(不含本次)。 内容未变而反复失败 ⇒ 高度怀疑 flaky 测试或与同组 PR 的语义冲突,重排不解决。
  • 过去 24h 队列共有 105 个失败构建(不含本次)。

分诊清单:

  1. 失败测试在本 PR 改动的包里 → 真回归,修 PR。
  2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」;已有汇总 issue ⇒ flaky/环境问题实锤,去那张 issue 上谈,修好前重排只会再烧一轮全队列。
  3. 两者都不是 → 可能与同组 PR 语义冲突;等前面的 PR 落地或失败出队后再重排一次即可,不要连续重排。

Generated by Claude Code · merge-queue-triage workflow (#4859)

Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentationImprovements or additions to documentationsize/xsskip-changesetPR has no user-facing published change; bypasses the changeset gate

Projects

None yet

3 participants

@os-litant@os-zhuang@claude
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode"); } } catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); } })(); })();
Skip to content

docs(agents): stop telling authors to hand-edit generated CHANGELOG.md - #14802

Merged
os-zhuang merged 1 commit into
mainfrom
claude/issue-14792-changelog-checklist-item
Sep 3, 2026
Merged

docs(agents): stop telling authors to hand-edit generated CHANGELOG.md#14802
os-zhuang merged 1 commit into
mainfrom
claude/issue-14792-changelog-checklist-item

Conversation

@os-litant

@os-litantos-litant commented Sep 3, 2026

Copy link
Copy Markdown
Collaborator

Fixes#14792

Post-task checklist item 6 in AGENTS.md told the author to hand-edit CHANGELOG.md. That file is generated output. This drops the CHANGELOG.md half of the line and keeps ROADMAP.md.

Before / after

AGENTS.md:1154

Before:

6. Update `CHANGELOG.md` / `ROADMAP.md` if user-facing or architectural.

After:

6. Update `ROADMAP.md` if user-facing or architectural.

Why

The same file says the opposite about CHANGELOG.md thirty-four lines above. At AGENTS.md:1120, inside checklist item 3, the changeset rule states that the changeset body "ships to consumers as CHANGELOG.md inside the npm package and is what an upgrading agent greps after the tombstone error". That makes CHANGELOG.md the output — written by the changesets release step from the .changeset/*.md entries item 3 already requires.

Item 6 treated the same file as an input. A contributor who obeyed it either hand-edited a generated artifact that the next Version Packages run overwrites or collides with, or read the two lines together and concluded the file contradicts itself on its most-traversed workflow. Nothing is lost by the trim: the changeset obligation is item 3, and it is unchanged here.

Neither reading of the name survives, which is what makes the trim safe rather than a judgement call. Item 6 could have meant the per-package CHANGELOG.md files or the repo-root one, so both were checked:

  • The per-package files are generated. packages/core/CHANGELOG.md and its siblings carry changeset-emitted release sections keyed by commit hash.
  • The root CHANGELOG.md disclaims hand-editing in its own header: the update history "is maintained in three layers rather than by hand-editing this file" — per-package detail "generated by [changesets] from the .changeset/ entries every PR adds", the curated per-major pages under content/docs/releases/, and this file "retained for its historical entries."

So there is no CHANGELOG.md in this repo that item 6 could have legitimately directed a PR author to update by hand.

ROADMAP.md is untouched and not in question, and the surviving half is not vacuous: the file exists at the repo root and its history shows real hand edits. This PR makes no claim about whether that obligation should stand.

Arithmetic

AGENTS.md is at its line-ratchet ceiling, so the edit adds no line and re-wraps nothing.

MeasureBeforeAfter
Lines (wc -l)1,1621,162
Ratchet ceiling / headroom1,162 / 01,162 / 0
Bytes (wc -c)85,10685,089 (-17)
The edited line72 bytes55 bytes (-17)
Widest table row1,081 (pin 1,081)1,081 (pin 1,081)
grep -c 'CHANGELOG.md' AGENTS.md2 (:1120, :1154)1 (:1120 only)

Byte-negative on one line, so nothing is paid same-file. git diff --stat is 1 file changed, 1 insertion(+), 1 deletion(-).

Scope held

Untouched, deliberately: the ROADMAP.md half of item 6, checklist item 3, and the changeset section at :1116-1122 — that region is being corrected by PR #14789, and a second PR editing it would be a merge conflict on a governed file for no gain. The hunk here at :1154 is disjoint from that one.

One argument recorded for the merging maintainer rather than acted on: a reading exists under which item 6 should be deleted outright rather than trimmed, on the grounds that ROADMAP.md updates are not obviously a per-PR obligation either. That is a scope decision, not this card's, so the line is trimmed as ruled and the argument is left here.

Gates

All run at head 9596a42386, exit codes captured by redirect before any pipe; each verdict below is the gate's own printed line.

CommandExitVerdict
pnpm check:pm-skill-ratchet0AGENTS.md is 1162 lines (ceiling 1162; headroom 0). · AGENTS.md: widest table row is 1081 bytes (pin 1081; headroom 0). · self-test 111 cases pass
pnpm check:pm-governed-prose02 instruction surface(s) name all 5 registered governed surfaces (docs/adr/** · .claude/** · skills/** · AGENTS.md · CLAUDE.md) and claim no others.
pnpm check:pm-skill-id-lint023 file(s) clean (pattern /#[0-9]{3,}/g).
pnpm check:nul-bytes0OK (scanned 8064 text file(s) -- 8064 tracked, 0 untracked-not-ignored; skipped 7 binary; no raw ASCII control bytes).
pnpm check:corpus-claim-drift0OK, no new claim sites beside a pinned spelling.
pnpm check:required-contexts06 required context name(s) pinned across 2 workflow(s); 5 instruction surface(s) scanned against 2 retired name(s).
node scripts/check-required-contexts.mjs0same sweep, direct invocation
pnpm check:agent-test-spelling0violating population empty, 9 separators judged and cleared on the rule
pnpm check:docs-audit-scope0docs-accuracy-audit scope is in sync with content/docs/: 190 hand-written doc(s)
pnpm check:pm-governed-merges0self-test 243 assertions; live: the real generator declared 9 output(s) and certified this tree

The family list was re-derived after the last edit, not taken from the dispatch:
node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands resolved its --repo assertion against this checkout's origin, derived the change set from git as 1 path (AGENTS.md, committed 1 / working tree 0 / untracked 0, three-dot against merge base fc648a256) and emitted 8 commands. All 8 ran; the two dispatch-named gates outside that union (check:nul-bytes, check:corpus-claim-drift) ran as well, so the set above is a superset.

ESLint

Not run repo-wide; narrowed, and the narrowing is a measurement rather than a skip:

  1. Population, read from eslint.config.mjs and not guessed. Every files: selector in the config is a JS/TS extension glob (**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs} and narrower variants; COMMENT_SWALLOW_FILES at :785 is that same glob). grep -cin 'markdown|[.]md' eslint.config.mjs returns 0 — no markdown processor, no .md selector anywhere. Confirmed through ESLint's own API: isPathIgnored('AGENTS.md') is true and calculateConfigForFile('AGENTS.md') yields no rules, against a positive control (eslint.config.mjs itself resolves 2 rules), so the API call is not vacuously quiet.
  2. Count, from --format json.pnpm exec eslint AGENTS.md --no-inline-config --format json gives errorCount: 0, warningCount: 1, the one warning being ruleId: null / File ignored because no matching configuration was supplied — zero rule results, because the file is outside the population.
  3. Invariance over untouched files. The config never enables type-aware linting for any file — no parserOptions.project, no typed rules, stated at eslint.config.mjs:325-332 with its own measured positive control. With no cross-file type program there is no mechanism by which an edit in one file moves a verdict on a file it does not touch, and this diff is one Markdown line in a file ESLint does not lint at all.

A full pnpm lint therefore measures the same nothing this narrowing measured.

Changeset

Labelled skip-changeset, route 2 of scripts/check-empty-changeset.mjs's own enumeration: "It releases nothing (.github/, .claude/, skills/, docs/, content/, examples/, tests-only, and the like) -- delete the changeset and apply the 'skip-changeset' label". This diff is one line of the repo-root instruction file; no packages/** source is touched and nothing publishes from any package. Per that script, the label is a gate-level exemption that produces no input for changesets/action — the shape an empty-frontmatter changeset would have broken.

Landing

Draft, and it stays draft — governed AGENTS.md, human merge is the review record. Not flipped ready, not queued, no auto-merge armed, no reviewers requested.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1

Post-task checklist item 6 read "Update `CHANGELOG.md` / `ROADMAP.md` if
user-facing or architectural", which contradicts the same file 34 lines
above: the changeset section states the changeset body "ships to consumers
as `CHANGELOG.md` inside the npm package". `CHANGELOG.md` is generated
output, written by the changesets release step from the entries item 3
already requires, so item 6 was directing the author to hand-edit a
generated artifact that the next Version Packages run overwrites or
collides with.
Drop the `CHANGELOG.md` half; keep `ROADMAP.md`, which may genuinely be
hand-maintained and is not in question here. Byte-negative on one line
(-17 bytes), no line added or re-wrapped: the file is at its ratchet
ceiling with headroom 0.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1
@github-actions

Copy link
Copy Markdown
Contributor

⛔ merge queue 构建失败 — 先分诊,再决定要不要重排

队列构建 33727530243 红了。队列跑的是全量套件(PR 侧 CI 只跑 affected 子集),
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job(日志抽取,best effort):

  • Test Core (1/6) — 失败步骤: Run this shard's tests

    @objectstack/cli:test: FAIL integration test/run-dev-unbuilt-workspace.e2e.test.ts > the mirror direction: a reader that is never coming back > gives up and exits instead of waiting forever
    ↳ 失败原因: @objectstack/cli:test: AssertionError: the harness SIGKILLed the child — it was still alive at the ceiling. cap 180000 ms (RUN_TIMEOUT_MS, constant and load-independent by design); this child ran 1801
    

↳ 失败原因 是判读的关键:超时Test timed out in … / Hook timed out in …)多半是负载/时序,不是本 PR 的回归;
断言AssertionError: …)才指向真实的行为改变。两者的 FAIL 行长得一模一样,只有这一行能区分。

⚠️断言这一侧有一类例外,判据是断言在测什么,不是它是不是 AssertionError 断言的对象是产品行为(一个值、一个形状、一次拒收)⇒ 照上面读:真实的行为改变,去查,⛔ 不要重排掉;
断言的对象是这次实验自身的有效性前提(跑完的耗时、负载下的先后、任何只在时间预算内才成立的条件)⇒ 它跟超时是同一类,同样对负载敏感,重排一次是合法的判别手段。
识别是机械的:断言的消息或它比较的值本身点名了一段时长、一个时间戳、一个耗时计数。实测过的一对 —— AssertionError: SecurityPlugin.init() ran: expected false to be true 测的是产品行为(真回归);
AssertionError: this run took over a second, so second-precision stamps could have differed too: expected 1006 to be less than 1000 测的是实验前提:它守护的那条不变式当时是绿的,同一个 head 原样重排一次即成功。
穿着 AssertionError 外衣的时间测量,仍然是时间测量。(⛔ 这只改「怎么读一次红」,不改「哪些测试可以重排」——后者由别处管。)

跨 PR 相同签名(24h,按失败测试文件聚合):

历史信号:

  • 本 PR 过去 24h 无队列失败记录(首次)。
  • 过去 24h 队列共有 97 个失败构建(不含本次)。

分诊清单:

  1. 失败测试在本 PR 改动的包里 → 真回归,修 PR。
  2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」;已有汇总 issue ⇒ flaky/环境问题实锤,去那张 issue 上谈,修好前重排只会再烧一轮全队列。
  3. 两者都不是 → 可能与同组 PR 语义冲突;等前面的 PR 落地或失败出队后再重排一次即可,不要连续重排。

Generated by Claude Code · merge-queue-triage workflow (#4859)

@github-actions

Copy link
Copy Markdown
Contributor

⛔ merge queue 构建失败 — 先分诊,再决定要不要重排

队列构建 33729340857 红了。队列跑的是全量套件(PR 侧 CI 只跑 affected 子集),
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job(日志抽取,best effort):

  • Test Core (1/6) — 失败步骤: Run this shard's tests

    @objectstack/cli:test: FAIL integration test/run-dev-unbuilt-workspace.e2e.test.ts > the mirror direction: a reader that is never coming back > gives up and exits instead of waiting forever
    ↳ 失败原因: @objectstack/cli:test: AssertionError: the harness SIGKILLed the child — it was still alive at the ceiling. cap 180000 ms (RUN_TIMEOUT_MS, constant and load-independent by design); this child ran 1800
    

↳ 失败原因 是判读的关键:超时Test timed out in … / Hook timed out in …)多半是负载/时序,不是本 PR 的回归;
断言AssertionError: …)才指向真实的行为改变。两者的 FAIL 行长得一模一样,只有这一行能区分。

⚠️断言这一侧有一类例外,判据是断言在测什么,不是它是不是 AssertionError 断言的对象是产品行为(一个值、一个形状、一次拒收)⇒ 照上面读:真实的行为改变,去查,⛔ 不要重排掉;
断言的对象是这次实验自身的有效性前提(跑完的耗时、负载下的先后、任何只在时间预算内才成立的条件)⇒ 它跟超时是同一类,同样对负载敏感,重排一次是合法的判别手段。
识别是机械的:断言的消息或它比较的值本身点名了一段时长、一个时间戳、一个耗时计数。实测过的一对 —— AssertionError: SecurityPlugin.init() ran: expected false to be true 测的是产品行为(真回归);
AssertionError: this run took over a second, so second-precision stamps could have differed too: expected 1006 to be less than 1000 测的是实验前提:它守护的那条不变式当时是绿的,同一个 head 原样重排一次即成功。
穿着 AssertionError 外衣的时间测量,仍然是时间测量。(⛔ 这只改「怎么读一次红」,不改「哪些测试可以重排」——后者由别处管。)

跨 PR 相同签名(24h,按失败测试文件聚合):

历史信号:

  • ⚠️本 PR 过去 24h 已在队列失败 1 次(不含本次)。 内容未变而反复失败 ⇒ 高度怀疑 flaky 测试或与同组 PR 的语义冲突,重排不解决。
  • 过去 24h 队列共有 105 个失败构建(不含本次)。

分诊清单:

  1. 失败测试在本 PR 改动的包里 → 真回归,修 PR。
  2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」;已有汇总 issue ⇒ flaky/环境问题实锤,去那张 issue 上谈,修好前重排只会再烧一轮全队列。
  3. 两者都不是 → 可能与同组 PR 语义冲突;等前面的 PR 落地或失败出队后再重排一次即可,不要连续重排。

Generated by Claude Code · merge-queue-triage workflow (#4859)

Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentationImprovements or additions to documentationsize/xsskip-changesetPR has no user-facing published change; bypasses the changeset gate

Projects

None yet

3 participants

@os-litant@os-zhuang@claude