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

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