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

Normal author work is unchanged: gitea_lock_issue still requires the worktree
to be base-equivalent to master/main/dev, and gitea_create_pr still targets a
normal base branch. A *stacked* PR (based on another unmerged PR's branch) is a
new explicit, proof-backed path — it never bypasses the issue lock.

- stacked_pr_support.py: pure policy. Approve a non-master base only when it is
  declared AND owned by a live OPEN PR whose number matches; reject arbitrary,
  mismatched, or stale (merged/closed) branches; require the PR body to document
  the stack (base branch, stacked-on PR, merge ordering).
- issue_lock_worktree.py: read_worktree_git_state / _find_matching_base_ref gain
  an opt-in extra_bases arg so an approved stacked base can anchor
  base-equivalence in addition to master/main/dev (empty by default = unchanged).
- gitea_mcp_server.py:
  - gitea_lock_issue gains stacked_base_branch + stacked_base_pr. When declared,
    it verifies the open PR owns the branch, anchors base-equivalence to it, and
    records approved_stacked_base = {branch, pr_number, verified_open} on the lock.
  - gitea_create_pr validates a non-master base against the lock's approved
    stacked base, re-checks the dependency PR is still open, and enforces the
    stacked-PR body fields. Master-based path untouched.
- Docs: llm-workflow-runbooks.md and work-issue.md document when stacked PRs are
  allowed and the required PR-body wording.

Tests: test_stacked_pr_support.py (18 policy cases), stacked base-equivalence in
test_issue_lock_worktree.py, approved_stacked_base persistence round-trip in
test_issue_lock_store.py. Existing lock/create_pr regressions still pass.

The #482 -> #479/#478 case motivates this: create_pr previously could not open a
stacked PR because the lock required a master-equivalent worktree.

Closes #484.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

issue_lock_worktree.py

@@ -30,8 +30,16 @@ def resolve_author_worktree_path(
     return os.path.realpath(os.path.abspath(path))
 
 
-def read_worktree_git_state(worktree_path: str) -> dict:
-    """Read branch name and porcelain status from a git worktree."""
+def read_worktree_git_state(
+    worktree_path: str,
+    extra_bases: tuple[str, ...] | list[str] = (),
+) -> dict:
+    """Read branch name and porcelain status from a git worktree.
+
+    ``extra_bases`` names additional branches (e.g. an approved stacked base)
+    that may anchor base-equivalence in addition to master/main/dev. When empty
+    (the default), only the normal base branches are considered.
+    """
     path = (worktree_path or "").strip()
     if not path:
         return {"current_branch": None, "porcelain_status": ""}
@@ -63,7 +71,7 @@ def read_worktree_git_state(worktree_path: str) -> dict:
         check=False,
     )
     head_sha = (head_res.stdout or "").strip() if head_res.returncode == 0 else None
-    base_branch, base_sha = _find_matching_base_ref(path, head_sha)
+    base_branch, base_sha = _find_matching_base_ref(path, head_sha, extra_bases)
     return {
         "current_branch": current_branch,
         "porcelain_status": status_res.stdout or "",
@@ -203,13 +211,26 @@ def _assessment(
     }
 
 
-def _find_matching_base_ref(path: str, head_sha: str | None) -> tuple[str | None, str | None]:
-    """Return the stable branch ref whose commit matches HEAD, if any."""
+def _find_matching_base_ref(
+    path: str,
+    head_sha: str | None,
+    extra_bases: tuple[str, ...] | list[str] = (),
+) -> tuple[str | None, str | None]:
+    """Return the stable branch ref whose commit matches HEAD, if any.
+
+    Normal base branches (master/main/dev) are always considered. ``extra_bases``
+    adds explicitly-approved stacked bases; each is checked as a local ref and via
+    the ``prgs``/``origin`` remotes.
+    """
     if not head_sha:
         return None, None
     candidates: list[str] = []
     for branch in sorted(BASE_BRANCHES):
         candidates.extend((f"origin/{branch}", branch))
+    for branch in extra_bases:
+        name = (branch or "").strip()
+        if name:
+            candidates.extend((f"prgs/{name}", f"origin/{name}", name))
     for ref in candidates:
         res = subprocess.run(
             ["git", "-C", path, "rev-parse", "--verify", ref],