Skip to content

Docs: bring the pipeline contract in line with two months of practice #905

Closed

Description

@Birfy

Written-by: Docs

Docs only. This changes process documentation, not a product feature: no code, no behaviour, no test change.

The pipeline contract in AGENTS.md was written on 2026-10-18/19. Seven rules from the last two months of practice are missing or wrong, and step 6 grew into a single ~200-word paragraph.

  1. The branch base is never checked. "Branch from latest origin/main" has no verification. Three incidents (feat(rooms): answer a local room's invite link (#852) #864, A local room's invite link has no Members-card row and no redemption dialog, and the preview card would be copied a second time #876, feat(rooms): the local room invite's plumbing and one shared preview card (#885) #887) opened a PR on an old base that silently reverted what had just merged, with a green PR page; feat(rooms): the local room invite's plumbing and one shared preview card (#885) #887 removed the 84 test lines Decide a hold on Bot Social's hold_reason, not a guess from reasons (#865) #869 had merged. Fix: git diff origin/main...HEAD --stat must list only your files, otherwise rebuild the branch and never stack.
  2. Can-merge is decided on the merge tree, not the PR page (fix(resume): keep and resume a turn whose end never reached FlyBot (#727) #759: 9/9 green, kicked twice, red on main at core/test/follow-through.test.js:264).
  3. Docs-not-needed: must also go in the PR body. core/scripts/check-arch-docs.mjs reads git log <base>..HEAD; after the squash merge the commit on main carries only the PR title and body, and arch-docs runs again on that push.
  4. One conclusion per tip is not written down anywhere: a second Verdict: at the same SHA is an incident, a new commit voids the old one, a correction reads Correction from <Bot>: ….
  5. A merged PR body cannot close an issue. Fixes #N is evaluated once, at merge; editing the body afterwards closes nothing and triggers no guard.
  6. Board discipline (Research: measure and cut token spend per Bot turn (prompt overhead, history growth, tool output, fan-out) #796): one read of the open state per round, the facts written into the PR body or a comment, no re-pulls, no restating in chat, no more than five lines of log.
  7. The entry-point paragraph is stale: Grok Bot as the single entry point, OpenCode and Codex are gone. Today it is person → Chief → Triage / Dev / Reviewer.

Two quality fixes in the same change: step 6 splits into five short checks (tier, one conclusion, enqueue, merge tree, never bypass), and the merge-gate / test-first rules duplicated in CONTRIBUTING.md become pointers to AGENTS.md.

Files: AGENTS.md, CONTRIBUTING.md, LESSONS.md, docs/code-standards.md, docs/autonomous-dev.md.

Every statement was checked against main at 093ff4d4: core/scripts/check-arch-docs.mjs (trailer read from commit messages, ARCH_DOCS_BASE), .github/agent/risk-rules.json (these five files are T3 paths), .github/scripts/enqueue-guard.mjs, .github/scripts/risk-gate.mjs.

This is a T3 change, so it needs a Reviewer PASS at the tip; I am not merging it.

Activity

  1. added a commit that references this issue on Oct 24, 2026
    ef66032
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:docsDocumentationdocumentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions