AGENTS.md has no section on how a fix lands: issue first, reviewed PR with Refs, review fixes as new commits, issue closed by hand #1497

New issue

Open

opened 2026-10-02 11:24:11 +02:00 by claude · 0 comments

claude commented

2026-10-02 11:24:11 +02:00

Member

AGENTS.md pins many single lessons, but nothing says how a fix gets from a working tree to main. Each part of that path has been learned by tripping over it.

Measured instances

A fix left at a local commit. #1487's fix was finished, tested and mutation-verified, then sat as an unpushed commit. It reached the forge only when the operator asked for an issue and a PR (#1490). Nothing in AGENTS.md says that is the expected end state.
The AC-closure gate's blocker on #1489 (review 7149). The body used a close keyword for #1485, and ac-closure-check failed until it became Refs #1485. The gate documents its own rule (cmd/rt/ac_closure_check.go), but a contributor only meets it at red.
A PR comment closed an issue the body only referenced. On #1489, a comment telling the reader to close #1485 manually put the keyword directly before the number. #1485's timeline records it as comment_ref with ref_action: closes (comment 113711), and #1485 closed at 11:11:59, the second #1489 merged. The gate does not read comments, so it stayed green. A second comment (113708) quoted the keyword and number inside inline code, and was recorded as ref_action: none.

Acceptance criteria

AGENTS.md documents the landing path end to end: issue first, branch from live main, fragment or no-changelog:, what the PR body carries, review fixes as new commits with HOLD, and the post-merge steps (range-diff, branch cleanup, AC ticks, close by hand).
It names every surface Forgejo reads close keywords from (PR body, commit messages, PR comments), and which of them ac-closure-check grades.
Each forge-behaviour claim in it is anchored to a measured instance, and nothing is stated that was not measured.

AGENTS.md pins many single lessons, but nothing says how a fix gets from a working tree to `main`. Each part of that path has been learned by tripping over it. ## Measured instances - **A fix left at a local commit.** #1487's fix was finished, tested and mutation-verified, then sat as an unpushed commit. It reached the forge only when the operator asked for an issue and a PR (#1490). Nothing in AGENTS.md says that is the expected end state. - **The AC-closure gate's blocker on #1489** (review 7149). The body used a close keyword for #1485, and `ac-closure-check` failed until it became `Refs #1485`. The gate documents its own rule (`cmd/rt/ac_closure_check.go`), but a contributor only meets it at red. - **A PR comment closed an issue the body only referenced.** On #1489, a comment telling the reader to close #1485 manually put the keyword directly before the number. #1485's timeline records it as `comment_ref` with `ref_action: closes` (comment 113711), and #1485 closed at 11:11:59, the second #1489 merged. The gate does not read comments, so it stayed green. A second comment (113708) quoted the keyword and number inside inline code, and was recorded as `ref_action: none`. ## Acceptance criteria - [x] AGENTS.md documents the landing path end to end: issue first, branch from live `main`, fragment or `no-changelog:`, what the PR body carries, review fixes as new commits with `HOLD`, and the post-merge steps (range-diff, branch cleanup, AC ticks, close by hand). - [x] It names every surface Forgejo reads close keywords from (PR body, commit messages, PR comments), and which of them `ac-closure-check` grades. - [x] Each forge-behaviour claim in it is anchored to a measured instance, and nothing is stated that was not measured.

claude added the

labels

2026-10-02 11:24:11 +02:00

claude referenced this issue from a commit

2026-10-02 11:25:54 +02:00

docs(agents): how a fix lands - issue, reviewed PR, Refs, close by hand (#1497)

claude referenced this issue