Skip to content

Commit a4faeb0

Browse files
author
CodeWhale Bot
committed
docs(agents): record merge, contributor, and verification discipline
Every rule here is something that actually went wrong on the 2026-08-29 night shift, written down so the next agent does not rediscover it. Landing other people's work: - A contributor's branch goes stale because WE land things. #5686 was CONFLICTING purely from Route Contract Phase 1 plus that same contributor's own earlier PRs merging into the same files. A maintainer resolves that. - Conflicts that split mid-function do not resolve by keeping both sides — the markers landed inside two function bodies and the naive resolution failed to compile with 'unclosed delimiter'. Take one side whole, re-insert the other's additions at their anchor. - maintainerCanModify did not grant push access to the fork (403), so the resolved merge went to integration/moonshot-kimi-5686-20260829 instead. That integration-branch path is now the documented default for conflicted work. - whp233's #5714 and #5716 each had SEVEN workflows parked at action_required because the author was not on .github/APPROVED_CONTRIBUTORS. The PRs looked stalled; nobody had looked. Five contributors have since been added. - Credit is mechanical: AUTHOR_MAP and .mailmap are project conventions and GitHub reads neither for the contribution graph. Merging under a gate: - #5698 merged while ACCEPTANCE_MATRIX.md still said FAIL and 37 minutes after a review confirming five findings were unchanged. Five real bugs reached main. A gate is its artifact, and check rollups are not the review thread. Claiming a test passed: - cargo test with a non-matching filter exits 0 having run ZERO tests; that was briefly mistaken for a pass here. - A harness scored 72 PASS of which 12 were never evaluated: 'ok = ok and X or True' parses as '(ok and X) or True'. CLAUDE.md already imports this file, so no second entrypoint was created. No-Issue: process documentation from the night shift Signed-off-by: CodeWhale Bot <bot@codewhale.net>
1 parent d4ebff1 commit a4faeb0

1 file changed

Lines changed: 51 additions & 0 deletions

File tree

AGENTS.md

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,57 @@ instructions or memory. The nearest scoped `AGENTS.md` adds path-specific rules.
3333
- Never rewrite published history, retag a release, force-push a shared ref, or
3434
publish without explicit authorization. Preserve human contributor credit.
3535

36+
## Landing other people's work
37+
38+
An external contributor's branch goes stale because *we* land things, not
39+
because they did anything wrong. Treat their time as more expensive than ours.
40+
41+
- **Never make a contributor rebase around our churn.** If their PR conflicts
42+
only because main moved, a maintainer resolves it. Read their diff against
43+
the merge base first so you know exactly what they added, and re-apply that,
44+
rather than hand-merging two large sides and hoping.
45+
- **Conflicts that split mid-function do not resolve by keeping both sides.**
46+
Git's markers can land inside a body, so a both-sides resolution produces
47+
unbalanced braces that look plausible and do not compile. Take one side
48+
whole, then re-insert the other side's additions at their original anchor.
49+
- **`maintainerCanModify` does not guarantee push access to the fork.** When
50+
the push is refused, land the resolved merge on
51+
`integration/<topic>-<pr>-<date>` in this repo and land from there. An
52+
integration branch is the normal path for anything with conflicts or several
53+
moving PRs — it is cheaper than repeatedly rebasing onto a main that keeps
54+
moving, and it keeps the contributor's branch untouched.
55+
- **Check the contribution gate before assuming a PR is stalled.** An unlisted
56+
author's workflow runs sit at `action_required` and never start, so the PR
57+
looks abandoned when nobody has actually looked at it. Approve the runs, then
58+
fix the cause: add them to `.github/APPROVED_CONTRIBUTORS` (`all:username`),
59+
or comment `/lgtm` (PR scope) / `/lgtmi` (issue scope) on their thread.
60+
- **Preserve credit in the mechanical sense, not just the polite one.** Commit
61+
authorship and `Co-authored-by` trailers must use the contributor's own
62+
GitHub-linked address. `AUTHOR_MAP` and `.mailmap` are project conventions —
63+
GitHub reads neither for the contribution graph.
64+
65+
## Merging under a gate
66+
67+
- **A gate is its artifact.** When a rail says a PR merges only on a passing
68+
acceptance record, the record must literally say PASS at merge time. "I
69+
re-ran it and the failures are rows this PR does not own" is a judgement to
70+
write into the artifact first, not a reason to merge past it.
71+
- **Read the review thread, not the check rollup.** Green checks and an unread
72+
review with confirmed findings are a merge that ships known bugs.
73+
- **When the artifact is ambiguous, resolve the ambiguity — never the merge.**
74+
75+
## Claiming a test passed
76+
77+
- Quote the real `test result: N passed; M failed` line, and confirm `N > 0`
78+
for the tests that cover the change. `cargo test <filter>` exits 0 having run
79+
zero tests when the filter matches nothing, and an exit code alone has
80+
already been mistaken for a pass here.
81+
- Prefer proving a regression test fails without the fix. A test that passes
82+
either way pins the implementation, not the defect.
83+
- Audit any harness before trusting its score. `ok = ok and X or True` parses
84+
as `(ok and X) or True` and silently reported twelve unevaluated rows as
85+
passing.
86+
3687
## Current contracts
3788

3889
- The model-facing subagent tool is `agent`. Do not revive removed

0 commit comments

Comments
 (0)