fix: make submit and repair guidance actionable

docs/adopting-existing-prs.md

@@ -93,6 +93,7 @@ This tells you:
 - which tracked branches are healthy
 - which branches already have linked PRs
 - which PR bases or heads disagree with your intended stack
+- whether a branch needs `stack submit`, `stack restack`, or manual metadata repair next
 
 ### 5. Fix the shape
 
@@ -117,6 +118,11 @@ stack submit --all
 That is the step that turns your intended parent graph into updated PR bases and
 branch tips on GitHub.
 
+When `stack submit` creates a PR during adoption, it uses the tip commit subject
+and body by default. If the branch tip has no commit body yet, `stack` uses a
+deterministic fallback body so the first adoption submit stays non-interactive
+and reviewable.
+
 ## Large sets: how to keep them manageable
 
 For a larger PR set, the safest pattern is:
@@ -131,6 +137,10 @@ That gives you tighter feedback loops and makes conflicts easier to localize.
 If you try to adopt everything at once, you can still do it, but debugging
 parent mistakes gets slower and noisier.
 
+If `stack submit` reports multiple open PRs for one head branch, stop and clean
+that up before continuing. `stack` refuses to guess which open PR owns a reused
+head name.
+
 ## Testing a composed set
 
 Once the branches are tracked, the stack graph gives you a clearer local test

docs/landing-workflow-followups.md

@@ -0,0 +1,261 @@
+# Landing workflow follow-ups
+
+This document captures the next layer of work that became obvious while using
+`stack` to turn a pile of existing PRs into one verified landing PR in
+`TeamSidewinder/event-agent`.
+
+The current tool is already useful for:
+
+- adopting existing branches into an explicit parent graph
+- keeping parent/child intent legible
+- restacking after lower branches move
+- syncing PR base drift back to GitHub
+
+What it does not yet handle well is the operator workflow after the graph is
+known:
+
+- grouping already-open PRs into one strict landing batch
+- excluding later follow-up commits from that landing batch
+- marking original PRs as superseded by the landing PR
+- carrying verification evidence alongside the stack
+- telling the operator which tickets and original PRs are safe to close after
+  merge and deploy
+
+Those are not side concerns. For a team that produces many runner PRs in
+parallel, they are the difference between a stack tool and a landing workflow.
+
+## What we learned from a real workflow
+
+The `event-agent` discovery batch looked like this:
+
+- original PRs: `#353`, `#354`, `#363`, `#364`
+- intended outcome: one combined landing PR with the verified set
+- complication: the working composed branch later picked up an extra follow-up
+  commit that we did not want to include in the first merge
+
+`stack` was still useful:
+
+- it helped make the intended grouping explicit
+- it helped us reason about parent order and adoption
+
+But the final landing workflow was manual:
+
+1. identify the exact commit that represented the strict verified scope
+2. cut a fresh landing branch at that commit
+3. push it manually
+4. open a combined PR manually
+5. comment on the original PRs manually
+6. manually decide which Linear tickets were safe to close after deploy
+
+That is the gap this document is about.
+
+## Recommendation
+
+Keep `stack` and keep using it.
+
+Do not turn it into a hosted system or a merge queue reimplementation.
+
+Do extend it from:
+
+- branch graph management
+
+to:
+
+- branch graph management plus landing orchestration
+
+The shape should stay explicit, local-first, and Git/GitHub-native.
+
+## Priority follow-ups
+
+### 1. First-class landing branch composition
+
+The tool should help create a strict landing branch from a selected portion of
+the stack.
+
+Example operator need:
+
+```bash
+stack compose discovery-core \
+  --branches hack-agent/lnhack-66-... \
+  --branches hack-agent/lnhack-74-... \
+  --branches hack-agent/lnhack-68-... \
+  --branches hack-agent/lnhack-69-...
+```
+
+Or, when the stack already exists:
+
+```bash
+stack compose discovery-core --from <bottom-branch> --to <top-branch>
+```
+
+Expected behavior:
+
+- create a new ordinary branch, for example `stack/discovery-core`
+- base it on trunk
+- replay only the selected stack commits in order
+- exclude later unrelated or follow-up commits unless explicitly requested
+- show the exact commit set before mutating anything
+
+This is the biggest missing piece from the real workflow.
+
+### 2. Superseded PR support
+
+Once a composed landing PR exists, the original PRs should not remain ambiguous.
+
+Example:
+
+```bash
+stack supersede --landing stack/discovery-core --prs 353,354,363,364
+```
+
+Expected behavior:
+
+- add a comment to each original PR saying it is superseded by the landing PR
+- optionally add a local metadata link from original PRs to the landing PR
+- optionally close the originals after the landing PR merges
+- refuse to guess if more than one open PR appears to own the same branch
+
+This should be explicit and reversible.
+
+### 3. Verification metadata
+
+Right now verification lives in the PR body or in chat.
+
+That is too fragile for a stack tool that is supposed to support landing order
+and closeout decisions.
+
+Add a lightweight verification record per branch or landing branch.
+
+Example:
+
+```bash
+stack verify add stack/discovery-core \
+  --note "AA General Festival Discovery Deeplink" \
+  --run-id b2f34b20-... \
+  --score 100 \
+  --passed
+```
+
+Expected stored fields:
+
+- branch or landing branch
+- check type: sim, unit, integration, manual, deploy, smoke
+- identifier: run id, check URL, commit SHA
+- pass/fail
+- optional score
+- optional note
+- timestamp
+
+This should feed status and closeout views.
+
+### 4. Closeout planning
+
+After merge, the operator needs one command that answers:
+
+- which original PRs should now be closed as superseded
+- which tickets are safe to close immediately
+- which tickets remain pending post-deploy checks
+- what post-deploy checks are still outstanding
+
+Example:
+
+```bash
+stack closeout stack/discovery-core
+```
+
+Expected output:
+
+- landing PR
+- superseded PRs
+- tickets safe to close now
+- tickets blocked on deploy verification
+- required follow-up checks
+
+This should be read-only by default and optionally able to post comments or
+write local notes.
+
+### 5. Better status for operators
+
+`stack status` should grow from “stack health” into “what should I do next”.
+
+Useful additions:
+
+- landing branch detection
+- original PR to landing PR relationships
+- verification summary
+- unresolved post-deploy work
+- clear ready/blocking reasons
+
+Example questions it should answer directly:
+
+- which branch is the real merge target?
+- which original PRs are now traceability-only?
+- which stack item is blocked, and on what?
+- is this safe to queue?
+
+### 6. Better adoption ergonomics for existing PR piles
+
+The adoption fix for stale branches was necessary, but the operator experience
+is still too manual for a large pile of existing PRs.
+
+Improvements worth adding:
+
+- `stack adopt pr 353 --parent main`
+- `stack adopt pr 354 --parent pr/353`
+- optional helpers to fetch the PR head locally if missing
+- clearer warnings when a branch has drift that suggests “compose instead of
+  direct stack submit”
+
+The tool should not infer the whole dependency graph. It should make the
+adoption path faster and safer once the operator already knows the shape.
+
+## Commands worth adding
+
+Suggested command surface:
+
+- `stack compose`
+- `stack supersede`
+- `stack verify add`
+- `stack verify list`
+- `stack closeout`
+- `stack adopt pr`
+
+Commands that probably should not exist yet:
+
+- automatic ticket closure
+- automatic deployment polling
+- merge queue orchestration beyond normal `stack queue` handoff
+
+Those belong later, if at all.
+
+## Recommended v1 order
+
+1. `stack compose`
+2. `stack supersede`
+3. `stack verify add` and `stack verify list`
+4. `stack closeout`
+5. `stack status` improvements
+6. `stack adopt pr`
+
+This order matches the highest-friction steps from the real discovery landing.
+
+## Design constraints
+
+Keep the following properties:
+
+- ordinary local branches
+- ordinary GitHub PRs
+- explicit operator choices
+- deterministic repair flows
+- no hidden hosted state
+- no attempt to replace GitHub merge queue
+
+The tool should help an operator say:
+
+- “these are the changes I want to land together”
+- “these are the original PRs this replaces”
+- “this is the evidence that the landing branch is good”
+- “these are the tickets safe to close after deploy”
+
+without requiring a separate spreadsheet or a memory-heavy manual ritual.
+

docs/troubleshooting.md

@@ -67,6 +67,12 @@ stack sync
 
 Then choose a repair path deliberately.
 
+Common outcomes:
+
+- `run \`stack submit <branch>\`` when the remote branch or PR base/head is simply stale
+- relink or clear local PR metadata when the tracked PR was closed, deleted, or points at the wrong head
+- inspect the merged parent manually when GitHub-side history drift means `sync --apply` would have to guess
+
 ## `stack submit` or `stack queue` fails against GitHub
 
 Check:
@@ -88,6 +94,10 @@ If the CLI reports multiple open PRs for one head branch, it is refusing to
 guess which live PR owns that branch. Close or retarget the duplicate until one
 open PR remains for that head name, then rerun `stack submit`.
 
+When `stack submit` creates a new PR, it uses the tip commit subject and body by
+default. If the commit body is empty, the preview will show that `stack` is
+using its generated fallback body instead.
+
 ## Release automation does not update the tap
 
 The release workflow needs:

docs/usage.md

@@ -49,6 +49,13 @@ and cached PR state.
 4. Run `stack queue <branch>` only when the bottom branch targets trunk and is healthy.
 5. Run `stack sync` after merges or GitHub-side base changes.
 
+When `stack submit` creates a new PR, it stays non-interactive by default:
+
+- the PR title comes from the tip commit subject
+- the PR body comes from the tip commit body
+- if the tip commit body is empty, `stack` generates a deterministic fallback body that records the branch and parent
+- if the tip commit subject is empty, `stack` falls back to the branch name
+
 For `stack queue`, GitHub repository auto-merge must be enabled. `stack` hands
 off through `gh pr merge --auto`, then GitHub applies the repo's normal
 auto-merge or merge-queue policy.
@@ -58,7 +65,9 @@ auto-merge or merge-queue policy.
 Use `stack sync` first when local metadata and GitHub disagree.
 
 Use `stack sync --apply` only for clean repairs. If the CLI reports a
-manual-review case, keep it manual.
+manual-review case, keep it manual. `stack status` and `stack sync` should tell
+you whether the next step is `submit`, metadata repair, or deliberate manual
+inspection.
 
 If a rebase or restack stops for conflicts: