jj-stack 0.1.4__tar.gz → 0.1.6__tar.gz

{jj_stack-0.1.4 → jj_stack-0.1.6}/.github/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           python-version: "3.14"
 
@@ -52,7 +52,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -65,6 +65,27 @@ jobs:
           fi
           printf '%s\n' "$install_dir" >> "$GITHUB_PATH"
 
+      - name: Install current Git
+        if: runner.os == 'macOS'
+        # The runner image's formula list can predate the current Git release.
+        run: |
+          brew update
+          brew install git
+
+      - name: Check Git version
+        shell: bash
+        run: |
+          git --version
+          # Git 2.56 changed which refs a push by URL updates. Other runners keep their own
+          # Git so older versions stay covered, but this one must run the newer behavior.
+          if [[ "$RUNNER_OS" == macOS ]]; then
+            IFS=. read -r major minor _ <<< "$(git --version | awk '{print $3}')"
+            if (( major < 2 || (major == 2 && minor < 56) )); then
+              echo "::error::The macOS job needs Git 2.56 or newer; found $(git --version)."
+              exit 1
+            fi
+          fi
+
       - name: Run local verification suite
         shell: bash
         run: ./check.py
@@ -79,7 +100,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           python-version: "3.14"
 

{jj_stack-0.1.4 → jj_stack-0.1.6}/.github/workflows/release.yml

@@ -34,7 +34,7 @@ jobs:
           ref: ${{ inputs.release_tag || github.ref }}
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           python-version: "3.14"
 
@@ -94,7 +94,7 @@ jobs:
 
     steps:
       - name: Set up uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           python-version: "3.14"
 
@@ -127,7 +127,7 @@ jobs:
 
     steps:
       - name: Set up uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           python-version: "3.14"
 

{jj_stack-0.1.4 → jj_stack-0.1.6}/CONTRIBUTING.md

@@ -39,20 +39,22 @@ just check
 ```
 
 Pyrefly is the default type checker, including a second pass targeting Windows. To select ty
-or mypy for the current platform instead, use `--type-checker` or its short form, `-t`:
+for the current platform instead, use `--type-checker` or its short form, `-t`:
 
 ```console
 just check -t ty
-just check -t mypy
 ```
 
-Repeat the option to run several in the given order, for example
-`just check -t pyrefly -t ty -t mypy`. The runner installs the selected checkers from the lockfile,
-checks `src`, `tests`, `tools`, and `check.py`, and runs the usual Ruff and pytest checks. It stops
-at the first failed check. ty and mypy are optional during development and can report issues
-that Pyrefly does not; their failures are reported normally. Plain `just check` and CI continue
-to use Pyrefly. Before a release, follow the
-[requirement for all three type checkers to pass](docs/internals/releasing.md#qualify-the-candidate).
+Repeat the option to run several in the given order, for example `just check -t pyrefly -t ty`.
+The runner installs the selected checkers from the lockfile, checks `src`, `tests`, `tools`, and
+`check.py`, and runs the usual Ruff and pytest checks. It stops at the first failed check. ty is
+optional during development and can report issues that Pyrefly does not; its failures are
+reported normally. Plain `just check` and CI continue to use Pyrefly. Before a release, follow the
+[requirement for both type checkers to pass](docs/internals/releasing.md#qualify-the-candidate).
+
+mypy is deliberately not part of the toolchain. It fixes a variable's type at its first
+assignment and rejects a later assignment of another type, which Pyrefly and ty accept, so
+keeping it green required annotations whose only purpose was to satisfy mypy.
 
 Run focused tests while you iterate:
 

{jj_stack-0.1.4 → jj_stack-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: jj-stack
-Version: 0.1.4
+Version: 0.1.6
 Summary: Stacked GitHub pull requests for Jujutsu
 Project-URL: Homepage, https://www.serpentine.com/software/jj-stack/
 Project-URL: Documentation, https://www.serpentine.com/software/jj-stack/
@@ -99,10 +99,11 @@ your edit.
 2. Run `jj-stack submit`.
 3. Revise, add, remove, or reorder the changes locally as reviews come in.
 4. Run `jj-stack submit` again to refresh GitHub.
-5. Run `jj-stack merge --pull-request <last-pr-to-merge> --method squash` when the bottom
-   portion is ready. Choose a merge method your repo allows. Queues choose their own method.
-6. After a queued merge or a merge made through GitHub finishes, run
-   `jj-stack sync <head-change-id>`.
+5. Run `jj-stack merge` when the PRs at the bottom are ready. Pass `--pull-request <pr>` to
+   stop at an earlier PR, and `--method` to choose a merge method your repo allows. The command
+   waits for GitHub, including its merge queue, then updates your local stack and remaining PRs.
+6. If you used `--no-wait`, interrupted the wait, or merged through GitHub, run
+   `jj-stack sync <head-change-id>` after GitHub finishes.
 
 `view`, `submit`, `merge`, and `sync` accept a change ID when you need to select a stack other
 than the one ending at the working copy.

{jj_stack-0.1.4 → jj_stack-0.1.6}/README.md

@@ -71,10 +71,11 @@ your edit.
 2. Run `jj-stack submit`.
 3. Revise, add, remove, or reorder the changes locally as reviews come in.
 4. Run `jj-stack submit` again to refresh GitHub.
-5. Run `jj-stack merge --pull-request <last-pr-to-merge> --method squash` when the bottom
-   portion is ready. Choose a merge method your repo allows. Queues choose their own method.
-6. After a queued merge or a merge made through GitHub finishes, run
-   `jj-stack sync <head-change-id>`.
+5. Run `jj-stack merge` when the PRs at the bottom are ready. Pass `--pull-request <pr>` to
+   stop at an earlier PR, and `--method` to choose a merge method your repo allows. The command
+   waits for GitHub, including its merge queue, then updates your local stack and remaining PRs.
+6. If you used `--no-wait`, interrupted the wait, or merged through GitHub, run
+   `jj-stack sync <head-change-id>` after GitHub finishes.
 
 `view`, `submit`, `merge`, and `sync` accept a change ID when you need to select a stack other
 than the one ending at the working copy.

{jj_stack-0.1.4 → jj_stack-0.1.6}/check.py

@@ -20,7 +20,7 @@ VENV_PYTHON = (
 )
 PytestJobs = int | Literal["auto"]
 _TYPE_CHECK_TARGETS = ("src", "tests", "tools", "check.py")
-_TYPE_CHECKERS = ("pyrefly", "ty", "mypy")
+_TYPE_CHECKERS = ("pyrefly", "ty")
 _FRAGILE_TEST_OUTPUT_PATTERNS: tuple[tuple[str, re.Pattern[str]], ...] = (
     (
         "use output assertion helpers instead of exact captured output equality",
@@ -79,7 +79,7 @@ def _build_checks(
         )
     type_checks: list[tuple[str, tuple[str, ...]]] = []
     for checker in type_checkers:
-        command = ("-m", checker) if checker == "mypy" else ("-m", checker, "check")
+        command = ("-m", checker, "check")
         type_checks.append((checker, (*command, *_TYPE_CHECK_TARGETS)))
         if checker == "pyrefly":
             type_checks.append(

{jj_stack-0.1.4 → jj_stack-0.1.6}/complexity-budget.toml

@@ -12,8 +12,8 @@ c901 = 16
 governed_c901 = 0
 
 [pytest]
-fixed_property = 9
-merge_recovery = 60
+fixed_property = 11
+merge_recovery = 67
 
 [labels]
 production = "Production"

{jj_stack-0.1.4 → jj_stack-0.1.6}/docs/guides/close-or-separate.md

@@ -57,9 +57,10 @@ jj-stack cleanup <head-change-id>
 
 ### If cleanup keeps a branch
 
-Cleanup keeps a PR branch while another open or reopenable closed PR uses it as its base. The
-message names the dependent PR. Retarget an open PR to trunk. For a closed PR, either reopen and
-retarget it or delete its head branch if you no longer need to reopen it. Then rerun cleanup.
+Cleanup keeps a PR branch while another PR still uses it as its base: an open PR, or a closed PR
+that GitHub could still reopen. The message names that PR. Retarget an open PR to trunk. For a
+closed PR, either reopen and retarget it, or delete its head branch if you no longer need to
+reopen it. Then rerun cleanup.
 
 A branch also stays while an unmerged PR in a GitHub stack needs it. Remove that stack with
 `jj-stack unstack` before retrying cleanup.

{jj_stack-0.1.4 → jj_stack-0.1.6}/docs/guides/merge-and-sync.md

@@ -11,8 +11,8 @@ stack. Once the PRs have merged, `jj-stack sync` updates your local stack and an
 pull requests.
 
 GitHub can perform the merge immediately or put it through a merge queue. An immediate merge
-is called a **direct merge**, and `jj-stack merge` runs the sync automatically in this case.
-For a queued merge, you run `sync` yourself after GitHub finishes.
+is called a **direct merge**. In both cases, `jj-stack merge` waits for completion and runs
+the sync automatically.
 
 ## Before merging
 
@@ -28,11 +28,22 @@ jj-stack merge <head-change-id>
 that their PR branches and pull requests have not moved unexpectedly. GitHub decides whether
 checks, approvals, conflicts, and repo rules allow the merge.
 
+`jj-stack list` and `jj-stack view` show review decisions, checks, and specific merge warnings.
+`needs review` means GitHub still requires a review.
+
+To inspect unresolved review threads and failed or pending checks, including links, run:
+
+```console
+jj-stack view --verbose <head-change-id>
+```
+
+Verbose output includes thread excerpts, even for outdated threads.
+
 ## Choose a merge method
 
-Direct merges happen immediately on GitHub. If your repo allows only one merge method, `merge`
-uses it automatically. With several allowed methods and an unsigned stack, it prefers rebase,
-then squash, then a merge commit. Choose an allowed method with `--method`, or set a default once:
+For a direct merge, `merge` uses your repo's only allowed merge method if there is just one.
+With several allowed methods and an unsigned stack, it prefers rebase, then squash, then a merge
+commit. Choose an allowed method with `--method`, or set a default once:
 
 ```console
 jj config set --repo jj-stack.merge_method squash
@@ -64,7 +75,7 @@ For example, in A → B → C, suppose the PRs are #1, #2, and #3. To merge only
 jj-stack merge --pull-request 1 --method squash
 ```
 
-After a direct merge, PR #1 is merged, PR #2 targets `main`, and PR #3 still targets PR #2's
+After the command finishes, PR #1 is merged, PR #2 targets `main`, and PR #3 still targets PR #2's
 branch. Both remaining PRs keep their numbers and discussions:
 
 ```mermaid
@@ -83,7 +94,8 @@ proceed because all three PRs belong to the same GitHub stack.
 
 After GitHub merges some or all of your pull requests, `sync` fetches the updated trunk and
 rebases your remaining changes onto it. It removes any obsolete local copies of the merged
-changes, updates the remaining PRs, and deletes PR branches that are no longer needed.
+changes, updates the remaining PRs, and deletes PR branches that are no longer needed. If your
+working copy is on a merged change, `sync` first moves it to a new empty change on trunk.
 
 Select the stack by its head change ID or by any linked pull request:
 
@@ -95,8 +107,8 @@ jj-stack sync --pull-request <pr>
 `sync --pull-request` updates the complete local stack containing the named PR, including
 changes above it. The selected PR can already be merged.
 
-For a PR outside a GitHub stack, `sync` can also close the PR and clean up after its submitted
-commit reaches trunk through an external fast-forward push.
+If someone pushes a PR's submitted commit straight to trunk instead of merging the PR, `sync`
+closes that PR and cleans up, provided the PR is not part of a GitHub stack.
 
 If no PR has merged, no submitted commit has reached trunk, and GitHub has not rebased the stack,
 `sync` leaves the pull requests unchanged. Run `jj-stack submit` explicitly when you want to
@@ -107,19 +119,25 @@ changes may still depend on the original local changes. `sync` rebases that work
 squashed result and removes the old copies. Other merge methods also need `sync` to update
 the remaining PRs and remove unused branches.
 
-### Direct merges
+### Merge queues
 
-For a direct merge, `merge` waits for GitHub to finish and runs `sync` before it returns.
-Your local stack and remaining PRs are then ready for you to keep working.
+GitHub tests each queued PR on a temporary merge commit that combines it with the PRs ahead of
+it, so those checks appear on that commit rather than on the PR's own Checks tab. While waiting,
+`merge` shows each PR's queue position and the state of those checks.
 
-### Merge queues
+If GitHub removes a PR from the queue, `merge` stops, reports GitHub's reason, links to the
+checks on that commit, and names the next step. See [queue removal recovery][queue-removal].
 
-When a merge queue is in use, `merge` returns once GitHub accepts the PRs into the queue.
-They may still be waiting to merge at that point. Wait until GitHub reports that the merge
-has finished, then run `sync` for that stack.
+[queue-removal]: ../troubleshooting.md#a-stack-was-removed-from-the-merge-queue
 
 While any selected pull request is queued, `jj-stack submit` refuses to update the stack and
-`jj-stack sync` leaves it unchanged.
+`jj-stack sync` leaves it unchanged; rerun `jj-stack merge` to resume waiting.
+
+### Leaving before GitHub finishes
+
+Use `--no-wait` to return as soon as GitHub accepts the request, or press Ctrl-C to stop
+waiting. Neither cancels the request. Rerun the same `jj-stack merge` to keep watching it, or run
+`jj-stack sync <head-change-id>` once GitHub finishes.
 
 ### Merges outside jj-stack
 
@@ -163,19 +181,22 @@ jj-stack sync <head-change-id>
 ```
 
 If only cleanup failed, run the `jj-stack cleanup --pull-request <pr>` commands in the hint.
-The local changes may already be gone, so their former head cannot select the remaining cleanup.
+The hint names each PR because the merged local changes may already be gone.
 
 Your pull requests are already merged, so do not retry `jj-stack merge`.
 
 ## When trunk moves without one of your pull requests merging
 
-`sync` handles completed GitHub merges and stack rebases. If trunk merely advanced, fetch it,
-rebase your changes with `jj` if needed, then submit the rewritten changes:
+`jj-stack sync` handles completed GitHub merges and stack rebases. If trunk merely advanced,
+fetch it, rebase your changes with `jj` if needed, then submit the rewritten changes:
 
 ```console
 jj git fetch
-jj rebase -s '<bottom-change-id>' -o 'trunk()'
+jj rebase -b '<change-id>' -o 'trunk()'
 jj-stack submit <head-change-id>
 ```
 
+Use any change in the stack with `-b`; jj finds its base and moves the whole stack, including
+forks. You can even omit `-b` to use jj's default of `@`.
+
 Rebase when your work needs the latest trunk or GitHub requires it before merging.

{jj_stack-0.1.4 → jj_stack-0.1.6}/docs/guides/review-a-stack.md

@@ -29,7 +29,7 @@ version appears first and is marked **current**. Use **Changes from previous ver
 what changed in that update. Use **Submitted commit** to inspect the exact commit published for
 that version.
 
-The comment lists recent available versions. If you missed several updates, follow their diff
+The comment lists the most recent versions. If you missed several updates, follow their diff
 links in order; use the PR's **Files changed** tab to review the current layer as a whole.
 
 ## Review and merge in order
@@ -58,10 +58,11 @@ each PR.
 
 ## Merge queues
 
-GitHub adds a stack's pull requests to the queue in dependency order. Removing or ejecting a PR
-also removes every PR above it. Resolve the cause, then add the stack to the queue again. Wait
-until the merge completes before running `jj-stack sync`. See GitHub's
-[merge queue guidance][github-queue].
+GitHub adds a stack's pull requests to the queue in dependency order. If GitHub removes a PR, it
+also removes every PR above it; `jj-stack merge` stops, reports the reason, and names the next
+step. Fix the cause and rerun the same `jj-stack merge` command. See
+[queue removal recovery](../troubleshooting.md#a-stack-was-removed-from-the-merge-queue) and
+GitHub's [merge queue guidance][github-queue].
 
 [github-review]: https://docs.github.com/en/pull-requests/how-tos/review-pull-requests/reviewing-stacked-pull-requests
 [github-merge]: https://docs.github.com/en/pull-requests/how-tos/merge-and-close-pull-requests/merging-stacked-pull-requests

{jj_stack-0.1.4 → jj_stack-0.1.6}/docs/guides/submit-and-update.md

@@ -87,10 +87,11 @@ look again:
 jj-stack submit --re-request
 ```
 
-## PR history
+## Revision history
 
-After updates, jj-stack maintains a comment on each PR listing its recent versions with links
-to the diffs. Reviewers can use it to see what changed since their last review.
+After updates, jj-stack maintains a **Revision history** comment on each PR. It lists the PR's
+recent versions with links to the diff between each version and the next, so reviewers can see
+what changed since their last review.
 
 For edits made directly on GitHub, see [work with a stack on GitHub](working-on-github.md).
 If you move changes between stacks, follow

{jj_stack-0.1.4 → jj_stack-0.1.6}/docs/guides/working-on-github.md

@@ -52,5 +52,9 @@ both from the local `jj` history. To change the base or order, make that change
 submit again. To remove the GitHub stack while leaving the PRs open, see
 [separate a stack](close-or-separate.md#remove-a-github-stack).
 
+Do not enable auto-merge, shown as **Merge when ready** with a merge queue, on a pull request
+you will stack more changes on. GitHub refuses to add such a PR to a stack, so the next submit
+stops until you disable it.
+
 For reviewer and repo configuration guidance, see
 [review and merge a stack on GitHub](review-a-stack.md).

{jj_stack-0.1.4 → jj_stack-0.1.6}/docs/internals/README.md

@@ -43,3 +43,5 @@ describe current behavior and rationale; commit history records how the design c
 - [jj/client.py](../../src/jj_stack/jj/client.py) provides jj queries and mutations;
   [github/client.py](../../src/jj_stack/github/client.py) handles GitHub requests.
   [state/store.py](../../src/jj_stack/state/store.py) reads and writes tracking data.
+- [timing.py](../../src/jj_stack/timing.py) records the per-call durations that `--time-output`
+  reports. Start a performance investigation by running the slow command with that flag.

{jj_stack-0.1.4 → jj_stack-0.1.6}/docs/internals/design.md

@@ -128,7 +128,9 @@ rewrite is not mistaken for a local copy. Two untracked remote bookmarks pointin
 commit prevent this exception, even if both are in the reserved namespace. Trunk, tags, and
 bookmarks outside the namespace still make their targets immutable. If the submitted commit and
 one local rewrite are both visible, the submitted commit is treated as the submitted snapshot
-rather than a second local candidate.
+rather than a second local candidate. Rewrites that a command has already planned run with jj's
+immutability check disabled: an immutability revset that names a namespace bookmark would
+resurrect the hidden commit it points at when jj rewrites that commit's ancestor.
 
 An unknown or mismatched bookmark creates no ownership. It remains untouched and does not block an
 independent stack. `submit` refuses to claim a colliding visible name for a new PR, while remote
@@ -175,7 +177,7 @@ through a merge queue.
 | `submit` | Create PRs and refresh the selected stack; only this command publishes new changes. |
 | `sync` | Update a local stack after a merge or native GitHub stack rebase. |
 | `sync --all` | Sync stacks after merges and finish eligible PRs without local copies. |
-| `merge` | Request a GitHub merge; run sync after a direct merge completes. |
+| `merge` | Request a GitHub merge; wait for completion and run sync unless `--no-wait` is used. |
 | `unstack` | Remove a GitHub stack; `--local` instead forgets local tracking. |
 | `cleanup` | Remove eligible artifacts and links; optionally close explicitly selected PRs. |
 | `checkout` | Adopt existing PRs and edit the selected change in the current workspace. |
@@ -186,7 +188,7 @@ through a merge queue.
 
 `jj` owns general history editing. There is no standalone `jj-stack rebase` command.
 
-`sync` and `merge` fetch before planning, including during `--dry-run`. A direct merge fetches
+`sync` and `merge` fetch before planning, including during `--dry-run`. A merge that waits fetches
 again after GitHub completes it. `checkout --pull-request` fetches when the selected PR's head
 commit is not already local. Other commands do not fetch. Commands evaluate `trunk()` after any
 fetch they perform; without a fetch, they use the locally available trunk.
@@ -245,10 +247,11 @@ removed, so `in-use` continues to report adoption. `view`, `list`, and `in-use`
 An unreadable or invalid file blocks commands that load it and names the path to move aside before
 using `checkout` or `relink` to restore links. A newer unsupported schema requires an upgrade.
 
-Mutating commands serialize per repo. An interruption can leave completed external effects even
-if the command reports failure. A retry computes what remains from current observations; it never
-replays a saved plan or selector. The submitted baseline records an acknowledged commit, not
-pending work.
+Mutating commands serialize per repo while they observe and mutate. A command that waits for
+GitHub, an editor, or a describe helper releases that serialization while it waits and observes
+again before it mutates. An interruption can leave completed external effects even if the command
+reports failure. A retry computes what remains from current observations; it never replays a
+saved plan or selector. The submitted baseline records an acknowledged commit, not pending work.
 
 ## Policies
 
@@ -368,15 +371,27 @@ queue object or a `MERGE_QUEUE` branch rule. If that lookup fails, `merge` stops
 error before requesting anything. It sends the explicit action `merge_queue` when a queue is
 found and `direct_merge` otherwise.
 
-A `merged` result means a direct merge completed; `merge` then fetches and syncs the whole
-selected stack before returning, including changes above the last merged PR and commits GitHub
-rewrote. An `enqueued` result means GitHub accepted the selected PRs into the queue. The command
-succeeds, but the user must wait for the queued merge to finish before running `sync`. A rejection
-leaves local changes unchanged.
+`merge` waits for completion by default, then fetches and syncs the whole selected stack before
+returning, including changes above the last merged PR and commits GitHub rewrote. An `enqueued`
+result means GitHub accepted the PRs into the queue; waiting continues by observing every selected
+PR until all report merged. Observations must still match the planned PR identities and submitted
+heads. Queue progress is shown but never determines merge eligibility. GitHub removes a queue
+entry before it records the merge, so an open, unqueued PR with no recorded non-merge reason
+still counts as merging until that state persists; a recorded reason other than a merge is a
+removal. A removal stops the wait without local changes, reports the recorded reason and the
+temporary merge commit, and names the next step: `sync` when a lower PR already merged, otherwise
+the same `merge` again.
+
+`--no-wait` returns after GitHub accepts the request; the user runs `sync` once GitHub merges.
+Interrupting a wait does not cancel the request. Rerunning `merge` for the same action and
+expected head resumes waiting; a different action or expected head stops. A queue request's merge
+method is not part of that identity because the queue chooses it. Queue waiting has no deadline;
+polling a direct merge request does. A rejection leaves local changes unchanged.
 
 Automatic reconciliation identifies the containing stack by the full change ID of the head
-resolved before the merge request. It does not reinterpret the original revset
-after fetching the changed trunk.
+resolved before the merge request. It does not reinterpret the original revset after fetching
+the changed trunk. If the fetch leaves that head with no visible commit, the local copies are
+already gone, and the follow-up runs only cleanup for the merged PRs.
 
 GitHub merge success and local reconciliation are separate outcomes. If GitHub completes the
 merge but the automatic sync stops, `merge` returns the sync failure status and says that the
@@ -416,8 +431,8 @@ routing for the trunk branch, it does not preflight approvals, checks, conflicts
 state across the repo. GitHub applies those rules to the requested GitHub stack or
 single-PR mutation, and `jj-stack` reports the result.
 
-A rejected merge must explain what the user can do next: rebase onto trunk, resolve, and submit
-again for a conflict; address the failing check or repo rule on GitHub otherwise.
+A rejected merge preserves GitHub's reason and says what to do next: rebase onto trunk, resolve,
+and submit again for a conflict; address the reported issue on GitHub and retry otherwise.
 
 ### Trunk evidence and sync
 
@@ -435,8 +450,11 @@ work reached this repo's trunk:
 `sync` may use either result. `sync --all` uses each rewritten merge result to select and
 reconcile its affected local paths; it does not apply one PR's evidence to unrelated work. It
 continues with independent stacks when one is blocked. If no local copy remains, it uses that
-evidence only for ordinary cleanup. A native GitHub stack rebase without a merge requires `sync`
-for that stack; `sync --all` discovers work from merge evidence.
+evidence only for ordinary cleanup, or syncs the local stack still holding the open PRs of the
+same GitHub stack, which cleans up the merged PR itself. A `sync` whose selected change has a
+saved link but no visible commit after the fetch runs only cleanup for the merged PRs of that
+change's GitHub stack. A native GitHub stack rebase without a merge requires `sync` for that
+stack; `sync --all` discovers work from merge evidence.
 
 When an unmerged local change sits below a submitted change whose submitted commit or merge result
 is on trunk, `sync` stops without mutation. Rebasing would silently decide whether that local
@@ -469,9 +487,10 @@ It rebases surviving changes onto trunk even when they contain conflicts. If a s
 change remains conflicted, the local rebase stays in place but its PR is not updated. The
 user resolves the conflict with `jj` and runs `submit` for the remaining stack.
 
-If a workspace directly has an obsolete merged change checked out, `sync` does not remove that
+If another workspace has an obsolete merged change checked out, `sync` does not remove that
 change. Its diagnostic identifies the workspace and gives commands to move it to trunk or forget
-it and move its directory to the trash. A workspace on a surviving child does not block its
+it and move its directory to the trash. The current workspace moves to a new empty change on
+trunk before its merged change is removed. A workspace on a surviving child does not block its
 ordinary rebase.
 
 If another local path still depends on a merged change after the rebase, `sync` leaves the
@@ -488,13 +507,15 @@ merges. A matching full change ID on trunk identifies the successor rather than
 an arbitrary visible side copy. When trunk has no matching change ID, `sync` removes the
 old local change without relabeling that commit.
 
-When GitHub merges part of a stack and rewrites the remaining PRs, GitHub's rewrite of
-each remaining change starts from its submitted baseline. If every remaining local change is still
-at its baseline, `sync` uses the commits GitHub reports rather than replaying equivalent
-diffs; if any remaining change has local edits, `sync` adopts none, rebases the remaining changes
-onto trunk, records GitHub's reported heads as their baselines, and republishes them. It
-accepts those heads and bases only while a merged PR in the same GitHub stack matches its saved
-record and its merge result is on trunk.
+When GitHub merges part of a stack, each remaining PR is either rewritten from its submitted
+baseline or left at its submitted commit. `sync` uses the commits GitHub reports, rather than
+replaying equivalent diffs, only if every remaining local change is still at its baseline and
+GitHub rewrote every remaining PR. Otherwise it adopts none, rebases the remaining changes onto
+trunk, records GitHub's reported heads as their baselines, and republishes them. It accepts those
+heads and bases only while a merged PR in the same GitHub stack matches its saved record and its
+merge result is on trunk. GitHub roots the rewritten PRs on trunk's tip at the time of the
+rewrite, which may be past the merge result, so the rewritten chain's base must be on trunk at or
+after that merge result rather than exactly at it.
 
 #### Native GitHub stack rebase
 
@@ -551,8 +572,9 @@ they do not block the mutation because they are no longer active.
 ### Derived artifacts
 
 A subsequent submit refreshes a PR description only if it still matches the last automated PR
-description. Otherwise it is preserved; explicitly supplied text still takes effect. See
-[pull request descriptions](../reference/descriptions.md).
+description. Otherwise it is preserved; explicitly supplied text still takes effect. A saved
+baseline this repo never held leaves nothing to compare, so the description follows the change.
+See [pull request descriptions](../reference/descriptions.md).
 
 When a submit supplies no stack overview, the existing overview text is preserved and moves to
 the current head PR if the stack grows. An explicitly supplied overview replaces it. A lone PR has
@@ -674,7 +696,13 @@ changes that explicit submit boundaries placed in several native GitHub stacks.
 not segment the path by GitHub resource or infer an omitted submit boundary.
 
 Both report whether an open PR has a merge-queue entry; position and intermediate queue phases
-are not modeled.
+are not shown.
+
+Both report specific merge warnings alongside reviews and checks, omitting GitHub's generic
+`BLOCKED` label. Blocked PRs receive a batched lookup of applicable rules, review threads, and
+checks; `view --verbose` includes other open PRs. Drafts, queued PRs, and changes with a reported
+problem are excluded. Details are discarded if the PR head or base changes during the lookup.
+GitHub computes merge state lazily, so an unknown state is not reported or polled.
 
 Neither command guesses. A change with no saved PR identity is reported as not submitted,
 even if a PR happens to use the branch name that change would generate. A saved PR is always
@@ -689,10 +717,10 @@ Empty, undescribed, conflicted, and merge changes produce warnings, but do not b
 a report incomplete. A merge warning states that only the first-parent path is shown.
 
 `view` and `list` share the rule for incomplete reports: an unmerged divergent change, ambiguous
-PR, failed PR lookup, broken saved link, or unobserved saved PR state makes the report incomplete.
-A per-change lookup failure affects only its row; a failure before rows can be built returns its
-own error code. When several local changes claim one branch, `list` warns and skips live
-inspection for that branch. These incomplete reports exit 10.
+PR, failed PR or detail lookup, broken saved link, or unobserved saved PR state makes the report
+incomplete. A per-change lookup failure affects only its row; a failure before rows can be built
+returns its own error code. When several local changes claim one branch, `list` warns and skips
+live inspection for that branch. These incomplete reports exit 10.
 
 `view` and `submit` render stack rows through the user's `jj log` formatting. `--json`
 follows [`docs/json-output.schema.json`](../json-output.schema.json) and exposes no cache state,
@@ -727,6 +755,10 @@ and HTML body of the website's CLI reference page.
 
 Running the executable without a subcommand is equivalent to `view` without arguments.
 
+`--output=jsonl` is a renderer, not a second interface: it writes the same messages, activity
+updates, and `--json` payloads as one JSON object per line on standard output, and command code
+never branches on it.
+
 ### Exit codes
 
 Exit codes are a public interface; their table lives in

jj_stack-0.1.6/docs/internals/property-testing.md

@@ -0,0 +1,35 @@
+# Generated integration testing
+
+These constraints supplement the [testing philosophy](testing-philosophy.md):
+
+- In `StackMachine`, keep server events and recovery as separate actions. A server merge must
+  leave room for local edits before sync; an interrupted submit must leave room for edits or
+  remote changes before retry. Combining these actions would hide the inconsistent states the
+  harness exists to test.
+- An external stack merge may leave the survivors' rewrite pending, and `server_rewrite`
+  completes it later, rooted on trunk's tip at that time as GitHub does, optionally after
+  advancing trunk itself. Keep the merge and the rewrite separate actions so local work and
+  other server events can happen between them.
+- `interrupt_sync` fails a sync after it has rewritten the local stack and updated the
+  surviving PRs but before it cleans up the merged ones, the state a crashed or interrupted sync
+  leaves behind. Recovery must come from a later `sync`, `sync --all`, or `cleanup`, so keep the
+  interruption separate from those actions.
+- Shared-file edits use single-line replacements, and generated moves preserve the relative order
+  of changes that edit the same file. These restrictions let the harness predict conflicts without
+  implementing `jj`'s merge algorithm; broadening the edits requires revisiting that assumption.
+- Each independent seeded search (shard) in the property tests has its own Hypothesis example
+  database. Sharing a database would spend parallel search time replaying and shrinking the same
+  saved failure.
+- The generated search runs through `just property` and CI's smoke job; `just check` runs only
+  the fixed scenarios in `tests/property`. The runner ends by listing the rules the sequences
+  fired and the rules none reached. Treat an unreached rule as a search problem, not as missing
+  coverage: give it a richer starting state or fix its precondition.
+- A rule is eligible only when it has work to do; compute its candidates in a helper that its
+  precondition shares. Hypothesis picks uniformly among eligible rules, so a rule that finds
+  nothing wastes a step and a model check.
+- Server drift and injected faults are capped per sequence, and some sequences start after an
+  external merge of the bottom PR. Each disturbance pushes the state into a stop that later
+  commands only confirm, and every recovery rule needs a merged PR first; without both, a short
+  walk never reaches recovery.
+- `check_contents` skips a change whose commit and expected contents it already verified. A new
+  content check that depends on anything else must extend that key.