Skip to content

Handle same-branch staged proposals as PR intent lineage #186

Description

@catoncat

Problem

Mainline can leave a branch in a confusing preflight state when an agent seals and publishes several staged intents while iterating on the same PR branch. Each intermediate intent is valid in isolation, but once later commits supersede the earlier stage, preflight still treats the older proposed intents as active parallel work if their code_commit no longer matches the current HEAD.

The current self-overlap guard excludes the current branch's proposed intent only when the proposal's git_branch and code_commit match the current branch and HEAD. That handles the single-final-proposal case, but not a common agent workflow where a PR evolves through multiple sealed stages on the same branch.

Why this matters

For agent-first usage, this creates noisy or blocking proposed_overlap output even when there is no true semantic conflict. The agent then has to manually inspect lineage and abandon intermediate proposals before the PR can be represented by one final intent.

This is especially easy to trigger when an agent treats implementation milestones as review-ready proposals instead of appending to one branch-level intent until PR closeout.

Expected behavior

Mainline should help agents distinguish same-branch staged lineage from genuine parallel proposed work.

A branch with several proposed intents on the same git_branch should be guided toward an explicit finalization path, rather than surfacing all older same-branch staged proposals as ordinary competing overlaps.

Possible product directions

  • Add a first-class PR closeout/finalization command that creates a final intent for the current HEAD and supersedes or abandons earlier same-branch proposals with explicit provenance.
  • Make mainline start, seal, or publish warn when the same branch already has proposed intents that do not point at current HEAD.
  • Teach preflight to classify older same-branch proposals separately from cross-branch/cross-actor proposed overlap, with recommended commands for finalization.
  • Extend doctor --proposals to flag fresh same-branch staged proposals, not only stale proposals or later merged overlaps.
  • Prefer explicit superseded_by lineage when available, so abandoned history does not incorrectly imply that the underlying approach was rejected.

Acceptance criteria

  • A PR branch with multiple staged proposals can be brought to a single final review intent through a documented command path.
  • preflight no longer presents older same-branch staged proposals as indistinguishable from genuine parallel work.
  • Agents receive actionable guidance before creating another proposed intent on the same branch.
  • The final PR description can be generated from the final intent without manual cleanup of intermediate proposals.
  • Existing true parallel overlap detection remains intact for different branches, actors, or unrelated goals.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions