zak.pub/tantalus

Fork 0

Improve merge-request-flow.md: clarify triggers, state, and edge cases #1

New issue

Closed

opened 2026-03-19 10:55:51 +00:00 by ReadyPlayerNaN · 3 comments

ReadyPlayerNaN commented

2026-03-19 10:55:51 +00:00

Owner

Summary

Several areas in merge-request-flow.md can be tightened to reduce ambiguity and prevent agent missteps.

Issues

1. Phase 1 trigger is too narrow

"An unassigned issue exists" excludes issues filed by maintainers who auto-assign to themselves (common default on GitHub/Forgejo). Agents will silently skip these.

Suggestion: Change the trigger to "An issue exists that is not assigned to another agent" or introduce an explicit opt-in mechanism (e.g. an agent label) so maintainers can request agent work on any issue regardless of assignment.

2. "Agent's domain" is undefined

Phase 1 says the issue must match "the agent's domain" but the document never defines what a domain is or how the agent determines whether an issue falls within it.

Suggestion: Either define domain selection (e.g. based on repo, labels, or config) or remove the qualifier if agents should process all issues in a repo.

3. Platform detection is underspecified

The doc says "determine the platform from the local repo's git remote" but doesn't handle edge cases: multiple remotes, ambiguous URL formats, or remotes pointing to different platforms.

Suggestion: Specify which remote to use (e.g. origin by default, overridable) and what to do when the URL can't be matched to a known platform.

4. Approval reaction is not verified against permissions

Phase 4 requires a thumbs-up from "a maintainer" but doesn't specify how the agent should verify the reactor actually has maintainer permissions. On GitHub/Forgejo, anyone can add reactions.

Suggestion: Add a step to verify the reactor's role via the platform API (e.g. check repository collaborator permissions) before treating the reaction as approval.

5. Concurrency rules assume persistent state

The "up to 3 issues" rule and "check in-flight issues" pattern assume the agent remembers state across loop iterations. The document doesn't specify how this state is tracked.

Suggestion: Specify the state mechanism — labels on the issues themselves (stateless agent, recommended) or a local state file. If labels are the mechanism, the current label scheme already supports this and just needs to be called out explicitly.

6. No timeout or escalation for waiting phases

Phases 4 (waiting for approval) and 7 (waiting for review) have no maximum wait time. An issue could sit indefinitely with no escalation.

Suggestion: Define a timeout (e.g. "if no response after 7 days, comment pinging the maintainer") or at least recommend one.

7. Label cleanup between phases could be clearer

Label transitions are consistent but scattered across phases. It's easy to miss one — e.g. Phase 2 to 3 removes triaging and adds planning, Phase 3 to 4 removes planning and adds planned, but this has to be pieced together from gate criteria.

Suggestion: Add a label state transition table or diagram showing the expected label at each phase.

## Summary Several areas in `merge-request-flow.md` can be tightened to reduce ambiguity and prevent agent missteps. ## Issues ### 1. Phase 1 trigger is too narrow "An unassigned issue exists" excludes issues filed by maintainers who auto-assign to themselves (common default on GitHub/Forgejo). Agents will silently skip these. **Suggestion:** Change the trigger to "An issue exists that is not assigned to another agent" or introduce an explicit opt-in mechanism (e.g. an `agent` label) so maintainers can request agent work on any issue regardless of assignment. ### 2. "Agent's domain" is undefined Phase 1 says the issue must match "the agent's domain" but the document never defines what a domain is or how the agent determines whether an issue falls within it. **Suggestion:** Either define domain selection (e.g. based on repo, labels, or config) or remove the qualifier if agents should process all issues in a repo. ### 3. Platform detection is underspecified The doc says "determine the platform from the local repo's git remote" but doesn't handle edge cases: multiple remotes, ambiguous URL formats, or remotes pointing to different platforms. **Suggestion:** Specify which remote to use (e.g. `origin` by default, overridable) and what to do when the URL can't be matched to a known platform. ### 4. Approval reaction is not verified against permissions Phase 4 requires a thumbs-up from "a maintainer" but doesn't specify how the agent should verify the reactor actually has maintainer permissions. On GitHub/Forgejo, anyone can add reactions. **Suggestion:** Add a step to verify the reactor's role via the platform API (e.g. check repository collaborator permissions) before treating the reaction as approval. ### 5. Concurrency rules assume persistent state The "up to 3 issues" rule and "check in-flight issues" pattern assume the agent remembers state across loop iterations. The document doesn't specify how this state is tracked. **Suggestion:** Specify the state mechanism — labels on the issues themselves (stateless agent, recommended) or a local state file. If labels are the mechanism, the current label scheme already supports this and just needs to be called out explicitly. ### 6. No timeout or escalation for waiting phases Phases 4 (waiting for approval) and 7 (waiting for review) have no maximum wait time. An issue could sit indefinitely with no escalation. **Suggestion:** Define a timeout (e.g. "if no response after 7 days, comment pinging the maintainer") or at least recommend one. ### 7. Label cleanup between phases could be clearer Label transitions are consistent but scattered across phases. It's easy to miss one — e.g. Phase 2 to 3 removes `triaging` and adds `planning`, Phase 3 to 4 removes `planning` and adds `planned`, but this has to be pieced together from gate criteria. **Suggestion:** Add a label state transition table or diagram showing the expected label at each phase.

ReadyPlayerNaN self-assigned this

2026-03-19 11:09:59 +00:00

ReadyPlayerNaN added the

triaging

label

2026-03-19 11:10:00 +00:00

ReadyPlayerNaN commented

2026-03-19 11:10:42 +00:00

Author

Owner

I've picked up this issue and I'm reviewing it now.

Triage Assessment

I've read the issue, the current merge-request-flow.md, and evaluated each of the 7 suggestions. Here's my assessment:

What's clear: All 7 items identify real gaps in the document. The suggestions are specific and actionable. The scope is well-bounded — this is a single-file change to merge-request-flow.md.

Evaluation of each item:

Phase 1 trigger too narrow — Agreed. The current wording would cause agents to skip issues filed by maintainers who auto-assign. An opt-in label or "not assigned to another agent" would fix this cleanly.
"Agent's domain" undefined — Agreed. This term is used but never defined. Removing it (agent processes all issues in its repo) is the simplest fix; alternatively, a brief definition tied to repo/labels/config would work.
Platform detection underspecified — Agreed. Specifying origin as default remote and handling ambiguous cases would be a small but useful addition.
Approval reaction not verified against permissions — Agreed, though this is the most complex item. The verification approach is necessarily platform-specific, so the doc should outline the principle and give examples rather than exhaustive API calls.
Concurrency rules assume persistent state — Agreed. The label-based state mechanism is already implied by the label table but calling it out explicitly would remove ambiguity.
No timeout for waiting phases — Agreed. A recommended timeout with escalation (e.g., ping after N days) would prevent indefinite stalls.
Label cleanup could be clearer — Agreed. A label state transition table would make the flow easier to follow at a glance.

No clarifying questions — the issue is clear and well-scoped. I'll proceed to planning.

I've picked up this issue and I'm reviewing it now. ## Triage Assessment I've read the issue, the current `merge-request-flow.md`, and evaluated each of the 7 suggestions. Here's my assessment: **What's clear:** All 7 items identify real gaps in the document. The suggestions are specific and actionable. The scope is well-bounded — this is a single-file change to `merge-request-flow.md`. **Evaluation of each item:** 1. **Phase 1 trigger too narrow** — Agreed. The current wording would cause agents to skip issues filed by maintainers who auto-assign. An opt-in label or "not assigned to another agent" would fix this cleanly. 2. **"Agent's domain" undefined** — Agreed. This term is used but never defined. Removing it (agent processes all issues in its repo) is the simplest fix; alternatively, a brief definition tied to repo/labels/config would work. 3. **Platform detection underspecified** — Agreed. Specifying `origin` as default remote and handling ambiguous cases would be a small but useful addition. 4. **Approval reaction not verified against permissions** — Agreed, though this is the most complex item. The verification approach is necessarily platform-specific, so the doc should outline the principle and give examples rather than exhaustive API calls. 5. **Concurrency rules assume persistent state** — Agreed. The label-based state mechanism is already implied by the label table but calling it out explicitly would remove ambiguity. 6. **No timeout for waiting phases** — Agreed. A recommended timeout with escalation (e.g., ping after N days) would prevent indefinite stalls. 7. **Label cleanup could be clearer** — Agreed. A label state transition table would make the flow easier to follow at a glance. **No clarifying questions** — the issue is clear and well-scoped. I'll proceed to planning.

ReadyPlayerNaN added

planning

and removed

triaging

labels

2026-03-19 11:10:49 +00:00

ReadyPlayerNaN commented

2026-03-19 11:11:14 +00:00

Author

Owner

Plan

Goal: Clarify ambiguous sections of merge-request-flow.md to reduce agent missteps by addressing all 7 items from this issue.

Approach: Edit merge-request-flow.md directly, making targeted changes to the affected sections. Each item maps to a specific location in the document.

Tasks:

Phase 1 trigger — Change "An unassigned issue exists that matches the agent's domain" to "An open issue exists that is not assigned to another agent and has no agent labels". This covers both unassigned issues and maintainer-self-assigned issues.
Remove "agent's domain" — Remove the qualifier "that matches the agent's domain" from Phase 1, since it is undefined and the simplest model is one agent per repo. If multi-domain is needed later, it can be added with a proper definition.
Platform detection — In the "Working Context" section, specify that origin is the default remote (overridable by agent config), and add guidance for when the URL format is unrecognized: log a warning and fall back to the Forgejo API as a generic Git forge default, or halt and ask.
Approval reaction verification — In Phase 4, add a step after detecting a 👍 reaction to verify the reactor has maintainer/write permissions via the platform API. Provide brief examples for GitHub (GET /repos/{owner}/{repo}/collaborators/{user}/permission) and Forgejo (GET /repos/{owner}/{repo}/collaborators/{user}). State the principle: "Do not treat reactions from users without write access as approval."
State mechanism — In the "Concurrency" section, add a paragraph clarifying that the agent tracks issue state via labels on the issues themselves (stateless agent model). The label table already exists; this just makes the mechanism explicit.
Waiting phase timeouts — Add a "Timeouts" subsection or note to Phases 4 and 7: "If no response is received within 7 days, post a comment pinging the maintainer. If no response after 14 days, unassign yourself and remove labels."
Label state transition table — Add a table or diagram after the existing Labels section showing: (none) → triaging → planning → planned → implementing → (none) with the phase transitions that trigger each change.

Risks:

Item 3 (platform fallback) is opinionated — the "halt and ask" vs "fall back to Forgejo API" choice depends on deployment context. I'll present both options in the text and let the reader choose.
Item 4 (permission verification) varies by platform. The doc can only give examples, not exhaustive coverage.

Test strategy:

Read through the updated document end-to-end to verify internal consistency.
Verify all 7 items from the issue are addressed.
Check that label transitions in the new table match the phase descriptions.
Ensure no existing behavior is removed — only clarifications added.

## Plan **Goal:** Clarify ambiguous sections of `merge-request-flow.md` to reduce agent missteps by addressing all 7 items from this issue. **Approach:** Edit `merge-request-flow.md` directly, making targeted changes to the affected sections. Each item maps to a specific location in the document. **Tasks:** 1. **Phase 1 trigger** — Change "An unassigned issue exists that matches the agent's domain" to "An open issue exists that is not assigned to another agent and has no agent labels". This covers both unassigned issues and maintainer-self-assigned issues. 2. **Remove "agent's domain"** — Remove the qualifier "that matches the agent's domain" from Phase 1, since it is undefined and the simplest model is one agent per repo. If multi-domain is needed later, it can be added with a proper definition. 3. **Platform detection** — In the "Working Context" section, specify that `origin` is the default remote (overridable by agent config), and add guidance for when the URL format is unrecognized: log a warning and fall back to the Forgejo API as a generic Git forge default, or halt and ask. 4. **Approval reaction verification** — In Phase 4, add a step after detecting a 👍 reaction to verify the reactor has maintainer/write permissions via the platform API. Provide brief examples for GitHub (`GET /repos/{owner}/{repo}/collaborators/{user}/permission`) and Forgejo (`GET /repos/{owner}/{repo}/collaborators/{user}`). State the principle: "Do not treat reactions from users without write access as approval." 5. **State mechanism** — In the "Concurrency" section, add a paragraph clarifying that the agent tracks issue state via labels on the issues themselves (stateless agent model). The label table already exists; this just makes the mechanism explicit. 6. **Waiting phase timeouts** — Add a "Timeouts" subsection or note to Phases 4 and 7: "If no response is received within 7 days, post a comment pinging the maintainer. If no response after 14 days, unassign yourself and remove labels." 7. **Label state transition table** — Add a table or diagram after the existing Labels section showing: `(none) → triaging → planning → planned → implementing → (none)` with the phase transitions that trigger each change. **Risks:** - Item 3 (platform fallback) is opinionated — the "halt and ask" vs "fall back to Forgejo API" choice depends on deployment context. I'll present both options in the text and let the reader choose. - Item 4 (permission verification) varies by platform. The doc can only give examples, not exhaustive coverage. **Test strategy:** - Read through the updated document end-to-end to verify internal consistency. - Verify all 7 items from the issue are addressed. - Check that label transitions in the new table match the phase descriptions. - Ensure no existing behavior is removed — only clarifications added.

👍 1

ReadyPlayerNaN added

implementing

and removed

planning

labels

2026-03-19 11:11:21 +00:00

ReadyPlayerNaN referenced this issue from a commit

2026-03-19 11:15:08 +00:00

docs: clarify triggers, state tracking, and edge cases

ReadyPlayerNaN referenced this issue from a pull request that will close it,

2026-03-19 11:15:18 +00:00

Clarify triggers, state tracking, and edge cases #4

ReadyPlayerNaN commented

2026-03-19 11:15:24 +00:00

Author

Owner

Implementation complete. Merge request created: #4

All 7 items have been addressed in a single commit. Waiting for review.

Implementation complete. Merge request created: https://git.zak.pub/zak.pub/tantalus/pulls/4 All 7 items have been addressed in a single commit. Waiting for review.

ReadyPlayerNaN

2026-03-19 11:16:02 +00:00