docs(AGENTS.md): a table of contents; the mechanism prose of §Build & Test and §Multi-agent working discipline moves to docs/agents/ topic pages, every rule staying as one sentence plus a pointer (#27139)

Fixes #26081
Clause-②: no
Metadata-protocol: none
Ruling-ref: 6417533492

## 维护者速读

- **改了什么**:`AGENTS.md` 加了目录(`## Contents`,17 个二级标题各一行,GitHub 锚点);§Build
& Test 与 §Multi-agent working discipline 里的 34 段机制说明**原文逐字节**迁到
`docs/agents/build-and-test.md`、`docs/agents/multi-agent-discipline.md`(索引
`docs/agents/README.md`),每条规则仍留在 `AGENTS.md`——一句话加一个指针(31 个)。`AGENTS.md`
1112 → 1050 行、82,609 → 76,432 字节;两节 140 → 125、317 → 247 行;行数棘轮上限随之 1112
→ 1050。其余 15 节与 Prime Directives 逐字节未动。
- **为什么改**:裁决 6417533492 字母
A(维护者「其他同意」,2026-10-26T13:43Z):规则留一处、解释迁出;首次进门的贡献者和每个会话都加载它的席位,读到的是更短、可导航的规则文件,解释一链之遥。
- **风险与回滚**:风险是某段被我判为「解释」迁走,而你认为它是规则——下表逐段列出来源行与落点,任一段可单独拉回(改
`AGENTS.md` 并从 `docs/agents/` 删去同段)。回滚 = revert 本 PR 的单个 commit。
- **先看**:① 下表「Moved paragraphs」,按风险排:L534–546 Re-arm awareness
整段迁出只留一句新裁句;L596–632 §11 合并驱动的五段;L558–577 §9 过期产物表与 `check:dev-prereqs`
一句。② `AGENTS.md` 里 §7、§9、§11 的新留句(hunk 位于新文件 L531–621 一带)。③
`docs/agents/multi-agent-discipline.md` 页首那段「`AGENTS.md` 是权威」说明。
- **两分钟验证**:`git diff --color-moved=zebra origin/main...HEAD --
AGENTS.md docs/agents/` —— 预期:迁出段在两侧都以 moved 色成对出现(逐字节相同),`AGENTS.md`
侧只剩新增的指针行与新裁句;`pnpm check:pm-skill-ratchet` 预期印出 `AGENTS.md is 1050
lines (ceiling 1050; headroom 0)`。
- **需要你做的**:Tier H ——对本 PR 给一次 APPROVED review;落地由席位执行。

## What changes

- `AGENTS.md`: a `## Contents` block (23 lines: one anchor link per `##`
heading in file order, GitHub slug form; the two reworked sections also
link their topic page) after the preamble and before `## Communication`.
§Build & Test 140 → 125 lines and §Multi-agent working discipline 317 →
247 lines: 34 explanation fragments (150 BASE line-spans) moved out
verbatim, every rule sentence kept (every ⛔ line stays — 66 before, 66
after), 31 pointers of the form `([why](docs/agents/PAGE.md#anchor))`
added. The seven headings `CONTRIBUTING.md` links (10 links) are
unchanged and resolve. Nothing else in the file moved: Prime Directives
and every section from Monorepo Layout to the end are byte-equal to
`origin/main`.
- `docs/agents/build-and-test.md` (74 lines) and
`docs/agents/multi-agent-discipline.md` (257 lines): the moved
fragments, byte-identical to the BASE text, one `##` per source
paragraph with a back-link to the companion `AGENTS.md` section; the
page preamble says `AGENTS.md` is the authority and how to pull a
paragraph back. `docs/agents/README.md` (13 lines): the index — plain
repository markdown next to `docs/adr/` and `docs/qa/`, not
`content/docs/**`.
- `scripts/pm/check-skill-line-ratchet.mjs`: the `AGENTS.md` ceiling row
1112 → 1050 (a lowering, the ratchet's ordinary direction; landed count,
headroom 0; the widest-table-row pin 768 is unchanged — the widest row
is the translations row in Documentation Guardrails, untouched).

### Moved paragraphs — the ruling's condition, so any one can be pulled
back by name

Lines are `AGENTS.md` at BASE `07d18e69`; "shape" says which part of the
source paragraph moved (`whole`, or the `head` / `middle` / `tail` of
it); the last column says what stays in `AGENTS.md` and whether the
staying sentence is the original text ("verbatim") or newly cut from the
paragraph it summarises.

| Moved (BASE 07d18e6 lines, shape, size) | Destination | What stays in
`AGENTS.md` |
|:---|:---|:---|
| `AGENTS.md` L67–69 (middle, 3 lines) |
[`build-and-test.md#why-a-test-the-tsconfigjson-misses-is-hidden`](docs/agents/build-and-test.md#why-a-test-the-tsconfigjson-misses-is-hidden)
| the bullet’s rule sentences (tsconfig reaches every test file;
tsconfig.test.json carries module semantics, never strictness) verbatim
|
| `AGENTS.md` L80–82 (middle, 3 lines) |
[`build-and-test.md#ts7006-piles-the-missing-js-extension`](docs/agents/build-and-test.md#ts7006-piles-the-missing-js-extension)
| the bullet’s rule (one broken import upstream; fix the extension first
and re-measure), newly cut to name the `.js` extension |
| `AGENTS.md` L86–91 (head, 6 lines) |
[`build-and-test.md#why-the-cross-package-gate-needs-a-spelling-it-knows`](docs/agents/build-and-test.md#why-the-cross-package-gate-needs-a-spelling-it-knows)
| the seeding rule (seed from import.meta.url / __dirname / findUp,
write the path as one of the block) verbatim, with a newly cut lead
naming the gate |
| `AGENTS.md` L119–122 (whole, 4 lines) |
[`build-and-test.md#what-the-cross-package-gate-deliberately-does-not-flag`](docs/agents/build-and-test.md#what-the-cross-package-gate-deliberately-does-not-flag)
| nothing (pure gate behaviour); the pointer sits on the preceding rule
paragraph |
| `AGENTS.md` L141–143 (whole, 3 lines) |
[`build-and-test.md#what-the-fresh-flag-seeds`](docs/agents/build-and-test.md#what-the-fresh-flag-seeds)
| the command table row (`pnpm dev -- --fresh -p RANDOM`; ephemeral
tempdir; you must kill it), with the pointer added to its Notes cell |
| `AGENTS.md` L147–148 (middle, 2 lines) |
[`build-and-test.md#why-the-separator-works-for-dev-scripts-and-not-for-vitest`](docs/agents/build-and-test.md#why-the-separator-works-for-dev-scripts-and-not-for-vitest)
| the Rules sentence and the ⛔ do-not-carry-it-over-to-test-commands
sentence verbatim |
| `AGENTS.md` L164–166 (middle, 3 lines) |
[`build-and-test.md#the-sdui-manifest-in-ci`](docs/agents/build-and-test.md#the-sdui-manifest-in-ci)
| the regenerate-and-commit rule and the pointer to
docs/releases-maintenance.md verbatim |
| `AGENTS.md` L171–172 (middle, 2 lines) |
[`build-and-test.md#which-console-3001_console-serves`](docs/agents/build-and-test.md#which-console-3001_console-serves)
| the dev-server command, the run-the-backend-on-:3000 instruction and
the ui/AGENTS.md pointer verbatim |
| `AGENTS.md` L328–332 (middle, 5 lines) |
[`multi-agent-discipline.md#the-shared-stash`](docs/agents/multi-agent-discipline.md#the-shared-stash)
| the ⛔ never-bare-stash sentence, the hook sentence
(guard-shared-stash.sh, OS_ALLOW_STASH=1) and the replacements block
verbatim |
| `AGENTS.md` L347–355 (middle, 9 lines) |
[`multi-agent-discipline.md#shared-refs-and-fetch_head`](docs/agents/multi-agent-discipline.md#shared-refs-and-fetch_head)
| the four-namespaces sentence, the Practices sentence and the ⛔ no-hook
sentence verbatim |
| `AGENTS.md` L364–366 (tail, 3 lines) |
[`multi-agent-discipline.md#a-reading-names-its-tree`](docs/agents/multi-agent-discipline.md#a-reading-names-its-tree)
| the rule sentence (a reading is a count plus repository and commit)
verbatim |
| `AGENTS.md` L375–377 (middle, 3 lines) |
[`multi-agent-discipline.md#reverse-verification-against-an-uncommitted-edit`](docs/agents/multi-agent-discipline.md#reverse-verification-against-an-uncommitted-edit)
| commit the fix FIRST, the restore spelling, and the
prove-identical-then-re-run sentence verbatim |
| `AGENTS.md` L383–389 (middle, 7 lines) |
[`multi-agent-discipline.md#what-a-checkout-from-a-ref-does-to-the-index`](docs/agents/multi-agent-discipline.md#what-a-checkout-from-a-ref-does-to-the-index)
| the ⛔ STAGES sentence, the restore spellings and the
never-trust-git-diff-HEAD-alone sentence, and the don’t-stage-it-at-all
sentence verbatim |
| `AGENTS.md` L397–399 (middle, 3 lines) |
[`multi-agent-discipline.md#windowed-history-on-a-shallow-clone`](docs/agents/multi-agent-discipline.md#windowed-history-on-a-shallow-clone)
| the answer-or-REFUSE rule and the historyHorizon() sentence verbatim |
| `AGENTS.md` L418–420 (tail, 3 lines) |
[`multi-agent-discipline.md#the-shared-identitys-accepted-blind-spot`](docs/agents/multi-agent-discipline.md#the-shared-identitys-accepted-blind-spot)
| the whole ownership protocol (claim first, who writes what, release,
findings unassigned) verbatim |
| `AGENTS.md` L430–432 (middle, 3 lines) |
[`multi-agent-discipline.md#unsigned-writes-under-one-identity`](docs/agents/multi-agent-discipline.md#unsigned-writes-under-one-identity)
| ask-never-correct, the ⛔ never-extend-to-the-draft-flag sentence and
read-the-timeline-actor verbatim |
| `AGENTS.md` L450–455 (middle, 6 lines) |
[`multi-agent-discipline.md#how-the-platform-stores-a-comment-footer`](docs/agents/multi-agent-discipline.md#how-the-platform-stores-a-comment-footer)
| a newly cut sentence (the platform appends the block and recognises
only that shape) plus the ⛔ tail-footer sentence verbatim |
| `AGENTS.md` L482–485 (middle, 4 lines) |
[`multi-agent-discipline.md#why-a-stacked-series-is-not-a-supported-form`](docs/agents/multi-agent-discipline.md#why-a-stacked-series-is-not-a-supported-form)
| the ⛔ off-main-is-literal sentence, the trunk-branch rule and the ⛔
no-gate-change sentence verbatim |
| `AGENTS.md` L505–508 (middle, 4 lines) |
[`multi-agent-discipline.md#what-the-merge-queue-does-with-your-pr`](docs/agents/multi-agent-discipline.md#what-the-merge-queue-does-with-your-pr)
| §7’s head sentence and “Arm only what is already green and accepted”
verbatim |
| `AGENTS.md` L520–521 (middle, 2 lines) |
[`multi-agent-discipline.md#arming-a-red-pr-hides-it`](docs/agents/multi-agent-discipline.md#arming-a-red-pr-hides-it)
| the green-means-success sentence and read-two-things verbatim |
| `AGENTS.md` L525–526 (middle, 2 lines) |
[`multi-agent-discipline.md#advisory-checks-ride-through`](docs/agents/multi-agent-discipline.md#advisory-checks-ride-through)
| the nine required contexts and the treat-those-nine-names-as-contract
sentence verbatim |
| `AGENTS.md` L528–531 (middle, 4 lines) |
[`multi-agent-discipline.md#two-speeds-which-runs-carry-which-battery`](docs/agents/multi-agent-discipline.md#two-speeds-which-runs-carry-which-battery)
| the Main-red rule verbatim |
| `AGENTS.md` L534–546 (whole, 13 lines) |
[`multi-agent-discipline.md#re-arm-awareness`](docs/agents/multi-agent-discipline.md#re-arm-awareness)
| a newly cut sentence carrying the paragraph’s rule clauses (confirm it
is still in the queue; re-arm once, never reflexively; ready first, arm
second; a stale red clears only with a new commit; do not test gh pr
merge) |
| `AGENTS.md` L549–550 (tail, 2 lines) |
[`multi-agent-discipline.md#the-serial-merge-fallback`](docs/agents/multi-agent-discipline.md#the-serial-merge-fallback)
| the fallback rule (merge serially, only after remote CI is fully
green, rebasing other open branches first) verbatim |
| `AGENTS.md` L552–553 (middle, 2 lines) |
[`multi-agent-discipline.md#why-you-never-stop-someone-elses-server`](docs/agents/multi-agent-discipline.md#why-you-never-stop-someone-elses-server)
| §8’s head, the start-your-own instruction and the ⛔
kill-only-a-recorded-PID sentence verbatim |
| `AGENTS.md` L558–567 (middle, 10 lines) |
[`multi-agent-discipline.md#stale-build-state-after-a-merge-the-artefacts-that-lie`](docs/agents/multi-agent-discipline.md#stale-build-state-after-a-merge-the-artefacts-that-lie)
| §9’s head sentence, the remedy command and the OS_SKIP_DTS=1 note
verbatim |
| `AGENTS.md` L573–577 (tail, 5 lines) |
[`multi-agent-discipline.md#stale-build-state-after-a-merge-the-artefacts-that-lie`](docs/agents/multi-agent-discipline.md#stale-build-state-after-a-merge-the-artefacts-that-lie)
| (same paragraph as M18a) |
| `AGENTS.md` L579–580 (middle, 2 lines) |
[`multi-agent-discipline.md#why-a-clean-merge-is-not-a-working-merge`](docs/agents/multi-agent-discipline.md#why-a-clean-merge-is-not-a-working-merge)
| §10’s head, the before-opening-a-PR and after-the-PR-is-open rules and
the Always / Full bullets verbatim |
| `AGENTS.md` L593–594 (tail, 2 lines) |
[`multi-agent-discipline.md#where-joint-breakage-surfaces`](docs/agents/multi-agent-discipline.md#where-joint-breakage-surfaces)
| (same §10 as M19) |
| `AGENTS.md` L596–603 (middle, 8 lines) |
[`multi-agent-discipline.md#generated-artifacts-and-the-merge-driver`](docs/agents/multi-agent-discipline.md#generated-artifacts-and-the-merge-driver)
| §11’s head sentence and “Sequence after a merge unchanged from §9:
rebuild, then check:generated --fix” verbatim, plus a newly cut sentence
naming merge=os-regen, check:merge-driver and os-regen-pending |
| `AGENTS.md` L607–613 (middle, 7 lines) |
[`multi-agent-discipline.md#generated-artifacts-and-the-merge-driver`](docs/agents/multi-agent-discipline.md#generated-artifacts-and-the-merge-driver)
| the MERGE-commit-is-the-one-exemption head, os-regen-merge.sh as the
authority (commits before regenerating), and the ⛔
never-needs---no-verify sentence verbatim |
| `AGENTS.md` L615–619 (whole, 5 lines) |
[`multi-agent-discipline.md#generated-artifacts-and-the-merge-driver`](docs/agents/multi-agent-discipline.md#generated-artifacts-and-the-merge-driver)
| nothing (mechanism only) |
| `AGENTS.md` L620–626 (middle, 7 lines) |
[`multi-agent-discipline.md#generated-artifacts-and-the-merge-driver`](docs/agents/multi-agent-discipline.md#generated-artifacts-and-the-merge-driver)
| the Corollary head, a newly cut probe sentence (throwaway bare clone,
no driver, recipe in os-regen-merge.sh’s header) and the ⛔
never-with--c-merge.os-regen.driver sentence verbatim |
| `AGENTS.md` L630–632 (whole, 3 lines) |
[`multi-agent-discipline.md#generated-artifacts-and-the-merge-driver`](docs/agents/multi-agent-discipline.md#generated-artifacts-and-the-merge-driver)
| nothing (mechanism only); the ratchet-baselines bullet stays whole in
AGENTS.md |

Two staying sentences had their antecedent adjusted because the sentence
they leaned on moved: the dev-server rule now reads "⛔ Do not carry the
`--` separator over to test commands" (was "Do not carry it over"), and
§7's "Arming a red PR does not queue it, it hides it" survives as
"arming a red PR hides it" inside the green-means-success sentence.
Everything else that stays is the original wording.

### Sizing, measured against the route's expectation

The dispatch route expected roughly a third off the file; measured, the
net is −62 lines (−5.6 %) and −6,177 bytes (−7.5 %). The two sections
are denser in rule sentences than the card's 28 % "narrative" estimate
assumed: of their 457 lines, 150 line-spans met the move test of
hypothesis 1 (a reader who obeys the sentence that stays is no less safe
without the paragraph) — the ownership protocol, the force-push
criteria, the nine required contexts, the governed-PR classes, the
`Clocked windows` ruling chain and the footer forms are rules and stay.
The Contents block costs 23 of the lines back. A larger cut would have
meant compressing rule paragraphs into summaries, which 「一处维护」 and the
ruling ("no rule is restated, only its explanation moves") both refuse.

## Tests

No package is touched: no build closure, no package tests. Docs-only
verification on head `38d1ac7f`:

- Scratch verifier (ledger-driven; each fragment sliced out of BASE by
markers, so the moved text cannot be a retype): 34 fragments — all
present in BASE, none left in the new `AGENTS.md`
(whitespace-normalised), each byte-present in its page; 31 `docs/agents`
pointers in `AGENTS.md` resolve (file exists, anchor is a
`github-slugger` slug of a real heading); every moved fragment's anchor
is pointed at from `AGENTS.md`; 35 relative links inside
`docs/agents/*.md` resolve (file + anchor); Prime Directives region and
Monorepo Layout → end byte-equal.
- The ten `CONTRIBUTING.md` anchor links (seven distinct) resolve on the
new file: `git grep -oE 'AGENTS\.md#[a-z0-9-]+' -- CONTRIBUTING.md` →
`#build--test` ×1, `#communication` ×1, `#documentation-guardrails` ×1,
`#multi-agent-working-discipline` ×1, `#post-task-checklist` ×1,
`#prime-directives` ×4,
`#touched-packagesspec-regenerate-its-artifacts-before-pushing` ×1 —
each a slug of a heading in the new `AGENTS.md` (computed with the
workspace's `github-slugger`, the package fumadocs and
`check:doc-anchors` slug with).
- No ablation: no tested behaviour changed (docs and a ceiling row).

## Acceptance notes

- Precedent sizing: cloud#3194's PR NOT READ (the cloud repo is not
reachable from this container). The ui equivalent (#25919 PR 2, the
`ui/AGENTS.md` core + topic pages under rulings 6386217274 / 6407900763
/ 6435359095) has not landed: `ui/AGENTS.md` is still 261 lines / 36 KB
with its nine sections at `origin/main e6e4199`, so there is no merged
"core plus topic pages" PR in this repo to size against. Comment
6386217274 itself answers 404 on this repo's REST (NOT MEASURED); the
card body's quotation 「规范核心与事故史分家，注释写不变量不写事故史，存量不横扫」 was read from
#25919's own body, and the shape ruled there (every ⛔ / "never" rule
stays in the core verbatim) is the shape applied here.
- `check:agent-test-spelling` still judges and clears the three
`AGENTS.md` dev-server spellings (`pnpm dev -- --fresh -p RANDOM` in the
table row, the `dev:crm` block and §8): all three stayed in `AGENTS.md`.
- `lychee` is not installed in this container; `docs/**/*.md` is inside
`check-links.yml`'s paths filter (advisory lane, offline file-link
check), so CI will read the new pages' links. Locally the scratch
verifier resolved every relative link (file + fragment);
`check:doc-anchors` does not scan `AGENTS.md` or `docs/`, so the TOC
anchors have no gate — they were computed with the same `github-slugger`
the gate uses.
- "ruling record" citations: the two in the `Clocked windows` paragraph
stay where they were (that paragraph is rules and did not move); the one
in `Two speeds` (6120820653) moved with its sentence into
`docs/agents/multi-agent-discipline.md`. No `#NNNN` citation was added
anywhere (`check:pm-skill-id-lint` green; `docs/agents/` is outside its
scan roots).
- Nothing out of scope was found that meets a filing class;
`CONTRIBUTING.md` and `.github/PULL_REQUEST_TEMPLATE.md` are untouched
(PR 2 of the letter landed as #26375).

## Verification

Head `38d1ac7f`. Every exit code below was captured by redirecting the
command to a file and reading `$?` before any pipe.

`node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` derived 40 commands (the ratchet gate script
is in the diff, so its sibling scripts/pm families derive too); every
one was run with its exit recorded, then `--ran` reconciled:

```text
Run reconciliation — 40 derived, 40 run, 0 NOT-MEASURED, 0 UNRUN.
✓ dispatch-gates --ran: 40 derived famil(ies) accounted for — 40 run, 0 NOT-MEASURED (a DERIVED zero — all 40 recorded an exit code and none of them is 3).
```

All 40 recorded exit 0 (`check:doc-formula-expressions` after its
declared prerequisite build, see below).

Card-named gates (read from their own verdict lines):

- `pnpm check:pm-skill-ratchet` → exit 0 — `AGENTS.md is 1050 lines
(ceiling 1050; headroom 0)` · `AGENTS.md: widest table row is 768 bytes
(pin 768; headroom 0)` · no line over the 120-byte budget reported.
- `pnpm check:pm-governed-prose` → exit 0 — `2 instruction surface(s)
name all 13 registered governed surfaces that govern objectstack … and
claim no others`.
- `node scripts/check-published-list-mirrors.mjs --self-test` → exit 0
(`All 37 self-test cases passed`); `node
scripts/check-published-list-mirrors.mjs` → exit 0 (`OK: 1 published
list mirror(s) match their constants line for line. AGENTS.md ←
scripts/check-cross-package-test-inputs.mjs →
RECOGNISED_PATH_SPELLINGS`).
- `pnpm check:doc-authoring` → exit 0; `pnpm check:pm-skill-id-lint` →
exit 0 (`104 file(s) clean`); `pnpm check:nul-bytes` → exit 0 (`scanned
21857 text file(s) … no raw ASCII control bytes`).
- `pnpm check:pm-dispatch-gates` (the over-cap battery, run detached and
waited on with `tail --pid`) → exit 0 — `dispatch-gates self-test (fast
tier): 1935 cases pass; 7 slow section(s) deferred` (the fast tier is
what `pnpm check:pm-dispatch-gates` runs; the slow tier is CI's).
- `pnpm --filter @objectstack/lint run check:doc-formula-expressions` →
first run exit 3 (PREREQUISITE NOT MET: `@objectstack/formula` /
`@objectstack/lint` not built — nothing measured), then after `turbo run
build --filter=@objectstack/formula --filter=@objectstack/lint` under
the verify lock (`VERDICT command-exit 0`) → exit 0.

CI's own run of each family on the PR is the record of record; the local
subset above is not re-run by the seat.

---
_Generated by [Claude
Code](https://claude.ai/code/session_01QSeKYmhU5KEj1nukYhp1Tg)_

Co-authored-by: objectstack-fleet[bot] <objectstack-fleet[bot]@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]