Add first-class stacked PR support to the author workflow (gitea_create_pr blocked on non-master base) #484

New Issue

2026-07-08T00:55:24-05:00

jcwalker3 commented

2026-07-08 00:55:24 -05:00

Problem

The author workflow can implement and push a stacked branch based on another unmerged PR branch, but gitea_create_pr is blocked because gitea_lock_issue requires the worktree to be base-equivalent to master before work. That makes legitimate stacked PRs impossible through MCP without either:

retargeting to master and entangling unrelated diffs, or
gaming the issue-lock / base-equivalence gate.

Neither is acceptable: the first pollutes the diff with the dependency's changes until it lands; the second defeats a safety gate.

Observed example

Issue: #482
Base PR: #479 / issue #478
Intended base branch: feat/issue-478-mcp-menu-shell
Head branch: feat/issue-482-skip-stale-request-changes-pr
Commit: 8f866ae
Branch and commit are pushed and validated (bash -n OK, py_compile OK, unittest 13/13 OK, git diff --check clean), but MCP PR creation was blocked because the worktree was intentionally not master-equivalent. The stacked PR had to be opened manually via the Gitea web compare view.

Acceptance criteria

Add first-class stacked PR support to the author workflow.
Allow issue locks to declare an approved non-master base branch when explicitly creating a stacked PR (opt-in, not default).
Require proof that the chosen base branch corresponds to an open PR or accepted dependency (not an arbitrary branch).
Require the PR body to include:
- stacked-on PR number
- base branch
- head branch
- merge ordering
- retarget/rebase requirement after the base lands, if applicable
Preserve the existing safety gate for normal master-based work (default path unchanged).
Add tests proving:
- normal issue PRs still require a master-equivalent base
- stacked PRs require explicit base-PR proof
- stacked PRs cannot silently target arbitrary/stale branches
- gitea_create_pr can create a PR with base set to the approved dependency branch
Update docs / menu prompts to explain when stacked PRs are allowed.

Constraints (must not weaken)

Do not weaken the root-checkout stability guard (#475).
Do not allow stacked PR support to bypass issue locks entirely — the lock stays mandatory; it gains an explicit, proof-backed non-master base mode.

Out of scope

Auto-retargeting a stacked PR onto master after its base lands (can be a follow-up).
Multi-level stacks (stack-on-a-stack) beyond a single approved dependency branch, unless it falls out for free.

## Problem The author workflow can implement and push a **stacked** branch based on another unmerged PR branch, but `gitea_create_pr` is blocked because `gitea_lock_issue` requires the worktree to be **base-equivalent to `master`** before work. That makes legitimate stacked PRs impossible through MCP without either: - retargeting to `master` and entangling unrelated diffs, or - gaming the issue-lock / base-equivalence gate. Neither is acceptable: the first pollutes the diff with the dependency's changes until it lands; the second defeats a safety gate. ## Observed example - Issue: **#482** - Base PR: **#479** / issue **#478** - Intended base branch: `feat/issue-478-mcp-menu-shell` - Head branch: `feat/issue-482-skip-stale-request-changes-pr` - Commit: `8f866ae` - Branch and commit are pushed and validated (bash `-n` OK, `py_compile` OK, `unittest` 13/13 OK, `git diff --check` clean), but **MCP PR creation was blocked** because the worktree was intentionally not master-equivalent. The stacked PR had to be opened manually via the Gitea web compare view. ## Acceptance criteria 1. Add first-class stacked PR support to the author workflow. 2. Allow issue locks to declare an approved **non-master base branch** when explicitly creating a stacked PR (opt-in, not default). 3. Require proof that the chosen base branch corresponds to an **open PR** or **accepted dependency** (not an arbitrary branch). 4. Require the PR body to include: - stacked-on PR number - base branch - head branch - merge ordering - retarget/rebase requirement after the base lands, if applicable 5. Preserve the existing safety gate for normal master-based work (default path unchanged). 6. Add tests proving: - normal issue PRs still require a master-equivalent base - stacked PRs require explicit base-PR proof - stacked PRs cannot silently target arbitrary/stale branches - `gitea_create_pr` can create a PR with `base` set to the approved dependency branch 7. Update docs / menu prompts to explain when stacked PRs are allowed. ## Constraints (must not weaken) - Do **not** weaken the root-checkout stability guard (#475). - Do **not** allow stacked PR support to bypass issue locks entirely — the lock stays mandatory; it gains an explicit, proof-backed non-master base mode. ## Out of scope - Auto-retargeting a stacked PR onto `master` after its base lands (can be a follow-up). - Multi-level stacks (stack-on-a-stack) beyond a single approved dependency branch, unless it falls out for free.

jcwalker3 added the status:in-progress label 2026-07-08 01:04:51 -05:00

jcwalker3 commented

2026-07-08 01:04:51 -05:00

Issue claim heartbeat

kind: claim
issue: Add first-class stacked PR support to the author workflow (gitea_create_pr blocked on non-master base) (#484)
branch: feat/issue-484-stacked-pr-support
phase: claimed
profile: prgs-author
pr: none
blocker: none
next_action: create worktree and begin implementation

**Issue claim heartbeat** - kind: claim - issue: #484 - branch: feat/issue-484-stacked-pr-support - phase: claimed - profile: prgs-author - pr: none - blocker: none - next_action: create worktree and begin implementation

jcwalker3 referenced this issue from a commit

2026-07-08 01:23:19 -05:00

feat: add first-class stacked PR support to author workflow (#484)

jcwalker3 referenced a pull request that will close this issue

2026-07-08 01:24:59 -05:00

feat: add first-class stacked PR support to author workflow (Closes #484) #489

sysadmin referenced this issue

2026-07-08 01:34:57 -05:00

feat: add first-class stacked PR support to author workflow (Closes #484) #489

sysadmin referenced this issue

2026-07-08 01:39:42 -05:00

feat: add first-class stacked PR support to author workflow (Closes #484) #489