Merge pull request #42 from hack-dance/hack-agent/landing-orchestration

Add landing orchestration workflows

Author: roodboi

README.md

@@ -1,114 +1,137 @@
 # stack
 
-`stack` is a CLI for stacked pull requests on GitHub.
+`stack` is a CLI for stacked pull requests and landing orchestration on GitHub.
 
-It helps you split one large change into a chain of smaller dependent PRs, keep
-their branch relationships straight, update PR bases when parents move, and hand
-the ready bottom PR to GitHub merge queue without turning your repo into
-something only one tool understands.
+It helps you do two related jobs without inventing a hosted control plane:
+
+- keep an explicit parent graph for ordinary stacked PRs
+- turn a verified set of existing PRs into one explicit landing branch and landing PR
 
 ![Status demo](docs/demo/status.gif)
 
 ![Queue demo](docs/demo/queue.gif)
 
 ## What stacked PRs are
 
-A stacked PR flow takes one bigger feature and breaks it into a sequence:
+A stacked PR flow splits one larger change into a chain:
 
 - branch A targets `main`
 - branch B builds on A and its PR targets A
 - branch C builds on B and its PR targets B
 
-That makes review smaller and landing order clearer, but it also creates work:
-when A changes or merges, B and C need to move with it.
+That gives reviewers smaller PRs. It also makes landing order explicit. The
+cost is that branch heads and PR bases need to move together when something
+lower in the stack changes or merges.
 
 ## What `stack` does
 
 `stack` keeps that workflow explicit and repairable:
 
-- you create or track a branch inside a stack
-- you restack branches when parents move
-- you submit one normal GitHub PR per branch
-- you sync local stack state after merges or GitHub-side changes
-- you queue the bottom PR when it is ready
+- create or track branches inside a stack
+- restack branches when parents move
+- submit one normal GitHub PR per tracked branch
+- compose one landing branch from a selected verified subset
+- attach verification and ticket metadata to the landing branch
+- mark original PRs as superseded and close them out after landing
+- hand the real merge target to GitHub auto-merge or merge queue
 
 The branches stay ordinary Git branches. The PRs stay ordinary GitHub PRs. If
-you stop using `stack`, the repository still looks like a normal repository.
-
-## Merge queue
-
-`stack queue` is for the bottom branch in a healthy stack. It verifies the PR
-base, head, and remote state, then hands that PR to GitHub auto-merge or merge
-queue. After the merge lands, `stack sync` helps the rest of the stack catch up
-without guessing through ambiguous cases.
-
-That handoff uses GitHub's own auto-merge path via `gh pr merge --auto`, so the
-repository must have auto-merge enabled. If the repo also uses merge queue,
-GitHub decides whether the PR goes straight to auto-merge or enters the queue.
-
-## How it differs from Graphite and similar tools
-
-`stack` is closest in spirit to tools that keep explicit local stack metadata,
-but it is deliberately simple:
-
-- it works with ordinary branches and ordinary GitHub PRs
-- it keeps stack intent locally, not in a hosted control plane
-- it favors previews, confirmations, and repair loops over hidden automation
-- it stays legible even if someone on the team never installs the tool
-
-That makes it a good fit for teams that want stacked PRs on GitHub without
-adopting a more opinionated end-to-end workflow.
+you stop using `stack`, the repo still looks like a normal repo.
 
-## Install
+## Two landing paths
 
-```bash
-brew tap hack-dance/homebrew-tap
-brew install hack-dance/tap/stack
-```
+Use the basic stacked-PR flow when each branch should land in order as its own
+PR.
 
-More install and source-build options live in [docs/install.md](docs/install.md).
+Use the landing workflow when the graph is useful for organization and repair,
+but the real merge target should be one combined landing PR. That is the right
+path when you already have a pile of open PRs, want to verify a strict subset,
+and need the originals to become traceability-only.
 
 ## Quick start
 
+Clean stack:
+
 ```bash
 stack init --trunk main --remote origin
 stack create feature/base
 stack create feature/child
-stack status
 stack submit --all
 stack queue feature/base
 ```
 
-Before using `stack queue`, make sure the GitHub repository has auto-merge
-enabled.
+Landing workflow from an existing PR pile:
+
+```bash
+stack init --trunk main --remote origin
+stack adopt pr 353 --parent main
+stack adopt pr 354 --parent pr/353
+stack compose discovery-core --from pr/353 --to pr/354 --ticket LNHACK-66 --open-pr
+stack verify add stack/discovery-core --type sim --run-id run-123 --passed
+stack supersede --landing stack/discovery-core --prs 353,354 --close-after-merge
+stack queue stack/discovery-core
+stack closeout stack/discovery-core --apply
+```
 
 For the full daily workflow, start with [docs/usage.md](docs/usage.md).
 
+For the real operator workflow around one combined landing PR, start with
+[docs/landing-workflow.md](docs/landing-workflow.md).
+
+## Merge queue
+
+`stack` does not reimplement merge queue. It only hands off the chosen PR
+through `gh pr merge --auto`.
+
+Sometimes that PR is the bottom tracked branch. Sometimes it is the landing PR.
+GitHub decides whether the handoff becomes auto-merge or queue entry.
+
+The repo must have auto-merge enabled before `stack queue` can work.
+
 ## Starting from existing PRs
 
 You do not need to start with a clean stack on day one.
 
-If you already have a pile of open PRs, `stack` can still help you turn them
-into an explicit stack so you can test them as a composed set, land them in a
-clean order, and handle conflicts with less guesswork.
+If you already have a larger PR pile, `stack` can help you:
+
+- adopt the existing heads into an explicit graph
+- repair parent order and base drift
+- compose one strict landing branch from a verified subset
+- keep the original PRs for traceability instead of queueing them directly
+
+Use [docs/adopting-existing-prs.md](docs/adopting-existing-prs.md) to make the
+graph explicit, then [docs/landing-workflow.md](docs/landing-workflow.md) to
+turn that graph into one landing PR.
+
+## How it differs from Graphite and similar tools
+
+`stack` stays deliberately simple:
+
+- ordinary branches
+- ordinary GitHub PRs
+- explicit local metadata
+- previews and repair loops instead of hidden automation
 
-The practical path is:
+That makes it a good fit for teams that want stacked PRs and landing batches on
+GitHub without committing the repo to a hosted workflow layer.
+
+## Install
 
-1. check out the repo locally and make sure you have local branches for the PR heads you care about
-2. decide the intended parent chain or grouping
-3. run `stack track <branch> --parent <parent>` for each branch
-4. run `stack status` and `stack sync` to see what does not match yet
-5. use `stack move`, `stack restack`, and `stack submit` to bring the stack into shape
+```bash
+brew tap hack-dance/homebrew-tap
+brew install hack-dance/tap/stack
+```
 
-That adoption flow is documented in [docs/adopting-existing-prs.md](docs/adopting-existing-prs.md).
+More install and source-build options live in [docs/install.md](docs/install.md).
 
 ## Documentation
 
 - [docs/README.md](docs/README.md) for the full docs index
-- [docs/adopting-existing-prs.md](docs/adopting-existing-prs.md) for grouping and ordering an existing PR set
+- [docs/usage.md](docs/usage.md) for the standard stacked-PR loop
+- [docs/landing-workflow.md](docs/landing-workflow.md) for the landing-orchestration path
+- [docs/adopting-existing-prs.md](docs/adopting-existing-prs.md) for making an existing PR graph explicit
 - [docs/how-it-works.md](docs/how-it-works.md) for the model and workflow
-- [docs/usage.md](docs/usage.md) for everyday commands and repair loops
-- [docs/troubleshooting.md](docs/troubleshooting.md) for common failure modes
+- [docs/troubleshooting.md](docs/troubleshooting.md) for failure modes and repair paths
 - [docs/cli/stack.md](docs/cli/stack.md) for generated command reference
 
 Contributor docs live in [docs/testing.md](docs/testing.md) and

docs/README.md

@@ -1,18 +1,34 @@
 # Docs
 
-Start here if you want the public documentation for `stack`.
+Start here if you want the public docs for `stack`.
+
+## Choose your path
+
+If you are starting a clean stack and want the normal branch-by-branch flow:
+
+- read [usage.md](usage.md)
+
+If you already have a PR pile and want one explicit landing PR:
+
+- read [landing-workflow.md](landing-workflow.md)
+
+If you first need to make an existing PR graph explicit before either path:
+
+- read [adopting-existing-prs.md](adopting-existing-prs.md)
 
 ## Product docs
 
 - [install.md](install.md) for Homebrew, release artifacts, and source builds
-- [adopting-existing-prs.md](adopting-existing-prs.md) for turning an existing PR set into an explicit stack
-- [how-it-works.md](how-it-works.md) for stacked PR concepts, merge queue, and workflow shape
-- [usage.md](usage.md) for the everyday command flow
+- [usage.md](usage.md) for the standard stacked-PR loop
+- [landing-workflow.md](landing-workflow.md) for landing-branch composition, verification, superseded PRs, queue handoff, and closeout
+- [adopting-existing-prs.md](adopting-existing-prs.md) for turning an existing PR set into an explicit graph
+- [how-it-works.md](how-it-works.md) for the core model and workflow shape
 - [troubleshooting.md](troubleshooting.md) for repair paths when state drifts
 - [cli/stack.md](cli/stack.md) for generated command reference
 
-## More docs
+## Contributor docs
 
 - [testing.md](testing.md) for unit, fixture, and live sandbox verification
 - [releasing.md](releasing.md) for release automation and Homebrew publishing
 - [demo/README.md](demo/README.md) if you need to regenerate the README demos
+- [landing-workflow-followups.md](landing-workflow-followups.md) for the historical feature request that drove the landing-orchestration work