docs: add Review & Auto-Merge Discipline (AGENTS.md §7 + guardrails)

[ranxianglei]

Part of billion-context#801 — codify, from a full-history audit of this repo + siblings, the rules humans enforce and the surfaces AI cannot safely self-judge. This is the CORE library, so its auto-merge surface is deliberately the narrowest of the three repos.

What changed (docs-only; no code, no version bump):

• New AUTO-MERGE-GUARDRAILS.md — measured baseline (295 items; 175 merged, 0 closed-unmerged), ≈25% second-round ("重灾区") rate among merged PRs that drew review, the implicit human rules with citations (prune/compress: a fold can split one tool call from its result (parallel burst) — unrecoverable 400 on strict OpenAI backends #286/fix(prune,compress): never split a tool call/result pair or an assistant run across a fold #287/fix(prune,compress): never split a tool call/result pair across a fold #293 tool-pair atomicity, Blank reasoning_content is destroyed by the core round-trip, so a strict-echo backend rejects the rebuilt request #289/fix: repair compound JSON damage (raw control chars + invalid escapes) in lenient parser #274 round-trip fidelity, fix(config): NudgeConfig docstring defaults drift from actuals; validateConfig accepts non-finite nudge scalars that silently kill growth nudges #163 doc-vs-default drift, fix(sync): keep host-expanded blocks deactivated across syncBlocks #181 block-state stability, Count-based tier nudges (tier2Trigger/tier3Trigger) fire below the usage band #237/fix(nudge): fire tier-2/3 distillation nudges on block COUNT, not summary token mass #162 tier nudges), and the kernel-owned contracts as first-class human-gates.
• AGENTS.md §7 "Review & Auto-Merge Discipline": before-you-start, review discipline, kernel-owned contracts (first-class, ALWAYS human-gated) — message-id/ref immutability (§2 principle 6), wire-artifact format (tag / acp_summary / token-snapshot freezing), single-owner content, lossless round-trip, tool-pair atomicity, protected-tool filtering, load-bearing Prompts rules, pipeline node ordering + nudge invariants — plus structural constraints (zero deps, platform-agnostic, state schema). Then an explicit narrow auto-merge gate + must-stay-human list + reviewer focus.

This is where the deferred kernel-side spec now lives: the format contract for ACP artifacts and the id-never-reused guarantee are promoted to first-class invariants in this repo (the host repos keep only their faithful-consumption duty). Any change to these is cross-repo by construction → always human + kernel-ships-first sequencing.

Docs only — no build/typecheck/test impact. Merging stays human.

[github-actions]

📦 Built Package Artifact

Branch: 2026-09-15_auto-merge-guardrails (ebaea36)

Option A — Install from npm PR tag (recommended)

In your adapter project:

npm install acp-kernel@pr-303

Each push to this PR publishes a new version under the pr-303 npm tag.

Option B — Download artifact

1. Download the artifact from the Actions run
2. Extract the tarball and install:

tar xzf acp-kernel-pr303.tgz
npm install ./package

---

This comment is automatically updated on each push.

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Verified this PR end-to-end (pulled the branch, inspected the diff vs current master, checked CI, and spot-checked every cited number/PR against live repo state). Summary:

Diff cleanliness — pass. Exactly 2 files, +154/−0, purely additive: AUTO-MERGE-GUARDRAILS.md (new, 108 lines) and AGENTS.md (+46 — new §7 appended after line 184, zero edits to existing text). git diff --check clean; no package.json/version change, so the "docs-only, no build impact" claim holds. Base is current master (8ee1801), mergeable_state: clean, no outstanding review comments.

CI — green. 4/4 checks on head 5804356: build-artifact, test (22), test (24), pr-validation.

Citations — all check out. Verified each cited item against the tracker: #286/#287→#293 tool-pair atomicity (#293 merged today; splitPairCount logic present in src/compress.ts), #289 blank reasoning_content round-trip (fixed by #290), #274 control-char repair, #163 NudgeConfig doc drift (still open — fair to cite as a standing rule), #181 sync deactivation (logic present in src/sync.ts), #237/#162 tier-nudge gating, and the #176→#191 revert chain. §7's cross-references are consistent with existing §2 (principles 3/6, the 9-node pipeline, the four load-bearing Prompts rules).

One factual concern — the §1 baseline. The doc states "295 tracked items (220 PR / 75 issues); 175 merged, 0 closed-unmerged, 21 open". Live counts today (GitHub search API): 225 PR / 77 issues; 177 merged, 25 closed-unmerged, 59 open. Two problems:

1. "0 closed-unmerged" is contradicted by 25 closed-unmerged PRs spread across the full history (feat: nudge lists protected ranges #21 … fix(prune,compress): never split a tool call/result pair or an assistant run across a fold #287). Spot-checks suggest most are superseded iterations — e.g. fix(prune,compress): never split a tool call/result pair or an assistant run across a fold #287 was closed in favor of merged fix(prune,compress): never split a tool call/result pair across a fold #293, and fix(sync): keep host-expanded blocks deactivated across syncBlocks #181's fix landed in src/sync.ts via another path — so the underlying intent may be "no work was lost", but as written the number isn't reproducible. That's exactly the doc-vs-reality drift §2.B condemns (fix(config): NudgeConfig docstring defaults drift from actuals; validateConfig accepts non-finite nudge scalars that silently kill growth nudges #163), so it's worth fixing in the one document whose job is to be trustworthy.
2. Internal arithmetic: 175 + 0 + 21 = 196, which partitions neither 295 nor 220.

(The ework-agent-pr marker count of 16 does match live exactly, so the snapshot is recent — these aren't timing artifacts.)

Suggested fix before merge: either re-run the count script and update §1 (my proposed replacement: "302 tracked items (225 PR / 77 issues); 177 merged, 25 closed-unmerged — mostly superseded iterations where the fix landed via a follow-up PR; 59 open"), or label §1 explicitly as a dated point-in-time snapshot with its counting definition. Happy to land the wording fix as a commit on the branch once you pick a framing. Everything else looks merge-ready; merging stays human per §4.

一句话中文摘要：PR 内容核实无误（diff 干净、CI 全绿、所有引用均可查证），唯一问题是 §1 基线数据与线上实际不符——"0 closed-unmerged" 实为 25 个，且 175+0+21=196 与总数 295 自相矛盾，建议作者修正基线数字或标注快照时间后合并。