Skip to content

[PR] docs(AGENTS.md): adopt the v3 gate-branch release contract - #4710

Closed
ranxianglei wants to merge 1 commit into
masterfrom
agents-md-v3-contract
Closed

ranxianglei wants to merge 1 commit into
masterfrom
agents-md-v3-contract

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

AGENTS.md is the every-session operative contract for all agents working this repo. It still described the PRE-v3 world and contained two rules that would actively mislead an Agent into breaking the 2026-10-25 model.

What was wrong (audited against current master):

  1. The old carve-out bullet said a lane "ships via the one-click release and may never merge that fix into master" — train mode is retired (v3 is merge-gated), and the alignment PR merging lane content INTO master is now the designed close-out. An Agent following that row would treat the P3/P4 flow as a violation.
  2. §4 Git-Safety table listed only *_release-v* / *_release-kernel-v* / bugfix-release/* — no knowledge of bugfix-vX.Y.Z lanes or the bugfix gate branch (rename/rebase/delete risk), and the version rule didn't match reality (mainline bump happens in the dispatch release commit; lane number is pre-bumped at cut).
  3. Missing entirely: THE FIRE shape (ship PR lane→gate is the only publish trigger), backport→carry routing semantics, the align-PR title machine contract (renaming kills auto-cut), and lane-freeze behavior.

This diff (single file, AGENTS.md, docs-only):

  • §4 Branch naming row: lists the bugfix-cycle branches; live lanes are sacred.
  • §4 version row → "NEVER hand-modify version": every bump is machinery-produced (dispatch release commit / cut-time pre-bump); content commits never touch it on any branch.
  • §4 owner-approval row: roster extended (lanes + bugfix gate + ship PRs); v3 amendment recorded — post-alignment AUTO-CUT is standing-approved workflow behavior (release v0.1.196 #2910 constraint on Agents unchanged).
  • Carve-out bullet replaced with a compact v3 lifecycle contract (three branch roles / THE FIRE / backport→carry / align-PR title contract / monotonic lane freeze) + pointer to reference/release.md → "Bugfix patch-lane channel" (which already carries the full mechanics since [PR] release: land the TRUE v3 gate-branch publish model (v2 arm self-fired at #4654) #4660); legacy bugfix-release/* marked DORMANT with do-not-use.

CI note: the current master test matrix is red from the pre-existing #4575/#4316 regression (triage complete, owner chose proper fix over revert, #4668 closed by owner) — this docs-only change cannot affect it; merge via required-check bypass as done for #4660 if it should land before the matrix goes green.

The operative agent contract predates the 2026-10-25 v3 model and
carried two actively misleading rules:

- L226 narrative: 'the lane ships via the one-click release and may
  never merge that fix into master' — train mode is RETIRED (v3 merge-
  gated) and the alignment PR merging lane content INTO master is now
  the designed close-out, so an Agent following this row would treat
  the return-to-master flow as a violation and look for a dead button.
- §4 table rows listed only *_release-v* / *_release-kernel-v* /
  bugfix-release/* — Agents had no rule set for bugfix-vX.Y.Z lanes or
  the bugfix gate branch (rebase/delete risk), and the version rule
  ('only on *_release-v*') did not match how versions are actually
  produced (mainline release commit on dispatch; lane pre-bump at cut).

Now:
- §4 Branch naming: bugfix cycle branches listed, live lanes sacred.
- §4 version row: 'NEVER hand-modify version' — all bumps are
  machinery-produced (dispatch commit / cut-time pre-bump).
- §4 owner-approval row: roster extended to lanes+gate+ship PRs; v3
  amendment recorded (post-alignment auto-cut is standing-approved
  WORKFLOW behavior, not an Agent act).
- Carve-out bullet replaced with the compact v3 lifecycle contract
  (roles / THE FIRE shape / backport->carry / align-PR title contract
  / lane freeze) + pointer to reference/release.md; legacy
  bugfix-release/* marked DORMANT.

Docs-only.
@github-actions

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: agents-md-v3-contract (46a2586)

Latest build — install this exact version

npm install -g billion-context@0.0.5737-pr.4710.053bc70

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Recent builds (commit → version)

commit version build
46a2586 billion-context@0.0.5737-pr.4710.053bc70 build

Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr4710.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

查重: 不重复——近期无其他触碰 AGENTS.md v3 发布契约的 PR/issue(最近的 #4704 ci carry、#4707 ci PATH 修复均为 CI 面,与本 docs 契约无关)。

接到这个 [PR]。这是已完成的工作,我不重做,按流程核对:①diff 与 issue 描述逐条比对;②新文本里的机制声明(v3 gate-branch、THE FIRE、backport→carry、align-PR 标题契约、monotonic freeze)对照当前 master 的 workflows / reference/release.md / 实际分支逐一验证;③CI 状态确认(正文已预告 master 矩阵红自 #4575/#4316,属继承性失败)。稍后给结构化八问结论。

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant