docs(agents): say what a pull request body must carry to merge #333

Merged

coilysiren merged 1 commit from docs/merge-lane-closing-reference into main

2026-08-13 10:04:53 +00:00

coilyco-ops commented

2026-08-13 10:01:32 +00:00

Member

closes #330

This pull request is also the experiment. Its body carries a bare hash-ref, which the tracker guard rejects in issue comments. If it exists, nothing on the pull request surface objected, and Darren's fix is a pure documentation change rather than a deadlock.

What Darren found

ward agent director merge refuses a body with no same-repo closing reference. A full issue URL never matches the pattern, and a URL is the house convention everywhere else, so the habit every agent builds is the one the merge verb cannot read.

What Olaf added, and why it needed testing first

Olaf flagged that another layer actively forbids the hash-ref syntax. That is true and I hit it myself tonight, but it is narrower than a deadlock: the guard fires on mcp__forgejo__comment_issue, an issue-comment surface. The two rules govern different surfaces and do not overlap.

Writing "use closes #N" into AGENTS.md without checking that would have been instructions that fail on contact, which is the class of defect this repository has spent the night removing.

What landed

AGENTS.md gains both accepted spellings, the explicit note that a URL does not satisfy the verb, and the partial-delivery rule. docs/sirens-echo-merge-lane.md carries the detail, including why the two conventions collide and which form belongs where.

The lane paragraph itself is untouched. It is declared byte-identical across the five PR-lane repos per agentic-os 994, so this lands beside it as repo-local guidance rather than editing shared text.

Not relaxing the regex, per Darren's reasoning. The strictness is what forces a merge to name what it closed.

ward exec gate green: build, policy-check, vet, test, test-skips, pre-commit.

closes #330 **This pull request is also the experiment.** Its body carries a bare hash-ref, which the tracker guard rejects in issue comments. If it exists, nothing on the pull request surface objected, and Darren's fix is a pure documentation change rather than a deadlock. ## What Darren found `ward agent director merge` refuses a body with no same-repo closing reference. A full issue URL never matches the pattern, and a URL is the house convention everywhere else, so the habit every agent builds is the one the merge verb cannot read. ## What Olaf added, and why it needed testing first Olaf flagged that another layer actively forbids the hash-ref syntax. That is true and I hit it myself tonight, but it is **narrower than a deadlock**: the guard fires on `mcp__forgejo__comment_issue`, an issue-comment surface. The two rules govern different surfaces and do not overlap. Writing "use `closes #N`" into `AGENTS.md` without checking that would have been instructions that fail on contact, which is the class of defect this repository has spent the night removing. ## What landed `AGENTS.md` gains both accepted spellings, the explicit note that a URL does not satisfy the verb, and the partial-delivery rule. `docs/sirens-echo-merge-lane.md` carries the detail, including why the two conventions collide and which form belongs where. **The lane paragraph itself is untouched.** It is declared byte-identical across the five PR-lane repos per agentic-os 994, so this lands beside it as repo-local guidance rather than editing shared text. Not relaxing the regex, per Darren's reasoning. The strictness is what forces a merge to name what it closed. `ward exec gate` green: build, policy-check, vet, test, test-skips, pre-commit.

coilyco-ops added 1 commit

2026-08-13 10:01:32 +00:00

docs(agents): say what a pull request body must carry to merge

ci / test (pull_request) Successful in 30s

Details

ci / publish-echo-image (pull_request) Has been skipped

Details

ci / publish-observed (pull_request) Has been skipped

Details

ci / image-build (pull_request) Successful in 16s

Details

fd79eb2518

The lane moved to pull-request-and-merge and did not say what makes a pull
request merge-eligible. ward agent director merge refuses a body with no
same-repo closing reference, and a full issue URL does not match its pattern.

That is the trap rather than an oversight. The tracker guard rejects a bare
hash-ref in an issue comment and demands the canonical URL, so the habit every
agent builds is exactly the form the merge verb cannot read. The two rules
govern different surfaces and each wants what the other refuses.

Documents both accepted spellings, the explicit note that a URL does not
satisfy the verb, and the partial-delivery rule: file the slice as its own
issue rather than weakening the reference.

The lane paragraph itself is untouched. It is declared byte-identical across
the five PR-lane repos, so this lands beside it as repo-local guidance.

Not relaxing the regex, per the director's reasoning on the issue. The
strictness is what forces a merge to name what it closed.

closes #330

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

coilyco-ops requested review from coilysiren

2026-08-13 10:01:32 +00:00

coilyco-ops referenced this pull request

2026-08-13 10:02:02 +00:00

Every PR on the new merge lane silently fails to merge, because the house URL convention is not a closing reference #330

coilyco-ops referenced this pull request

2026-08-13 10:03:25 +00:00

I pushed straight to main after the repo moved to the pull-request lane, and the guard that would catch it does not exist #329