jj-stack 0.1.1__tar.gz → 0.1.2__tar.gz

{jj_stack-0.1.1 → jj_stack-0.1.2}/.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@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           python-version: "3.14"
 
@@ -51,7 +51,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -78,7 +78,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           python-version: "3.14"
 

{jj_stack-0.1.1 → jj_stack-0.1.2}/.github/workflows/codeql.yml

@@ -23,10 +23,10 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v4.37.3
+        uses: github/codeql-action/init@v4.37.7
         with:
           languages: python
           build-mode: none
 
       - name: Analyze
-        uses: github/codeql-action/analyze@v4.37.3
+        uses: github/codeql-action/analyze@v4.37.7

{jj_stack-0.1.1 → jj_stack-0.1.2}/.github/workflows/release.yml

@@ -34,7 +34,7 @@ jobs:
           ref: ${{ inputs.release_tag || github.ref }}
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           python-version: "3.14"
 
@@ -50,6 +50,17 @@ jobs:
         if: github.event_name == 'push' || inputs.release_tag != ''
         run: git merge-base --is-ancestor HEAD refs/remotes/origin/main
 
+      - name: Verify release notes
+        if: github.event_name == 'push' || inputs.release_tag != ''
+        env:
+          RELEASE_TAG: ${{ inputs.release_tag || github.ref_name }}
+        run: |
+          release_notes="release-notes/$RELEASE_TAG.md"
+          if ! test -s "$release_notes"; then
+            echo "::error file=$release_notes::Add human-written release notes for $RELEASE_TAG"
+            exit 1
+          fi
+
       - name: Install jj
         run: echo "$(tools/install-jj-release.sh "$JJ_VERSION")" >> "$GITHUB_PATH"
 
@@ -83,7 +94,7 @@ jobs:
 
     steps:
       - name: Set up uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           python-version: "3.14"
 
@@ -116,7 +127,7 @@ jobs:
 
     steps:
       - name: Set up uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           python-version: "3.14"
 
@@ -141,6 +152,11 @@ jobs:
       contents: write
 
     steps:
+      - name: Check out release
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ inputs.release_tag || github.ref }}
+
       - name: Download distributions
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
@@ -152,12 +168,22 @@ jobs:
           GH_TOKEN: ${{ github.token }}
           RELEASE_TAG: ${{ inputs.release_tag || github.ref_name }}
         run: |
+          release_notes="release-notes/$RELEASE_TAG.md"
           if gh release view "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+            expected_notes="$(cat "$release_notes")"
+            published_notes="$(
+              gh release view "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" \
+                --json body --jq .body
+            )"
+            if test "$published_notes" != "$expected_notes"; then
+              echo "::error file=$release_notes::Published notes do not match $release_notes"
+              exit 1
+            fi
             for artifact in dist/*; do
               gh release verify-asset "$RELEASE_TAG" "$artifact" \
                 --repo "$GITHUB_REPOSITORY"
             done
           else
             gh release create "$RELEASE_TAG" dist/* --repo "$GITHUB_REPOSITORY" \
-              --verify-tag --generate-notes --title "$RELEASE_TAG"
+              --verify-tag --notes-file "$release_notes" --title "$RELEASE_TAG"
           fi

{jj_stack-0.1.1 → jj_stack-0.1.2}/AGENTS.md

@@ -8,10 +8,9 @@
   external mutation to the identity and version observed while planning when the platform
   supports a conditional write or lease. Re-observe only when an earlier mutation invalidates a
   precondition or when an observed trigger or platform contract requires it.
-- Apply the cumulative complexity budgets after every code slice. CI runs
-  `uv run tools/check_complexity.py`; run it locally when the pinned `tokei` is installed. A
-  budget increase is a design stop that requires explicit review, not routine maintenance of the
-  budget file.
+- Apply the cumulative complexity budgets after every code slice. Run `just complexity` locally
+  when the pinned `tokei` is installed; CI invokes the underlying checker. A budget increase is a
+  design stop that requires explicit review, not routine maintenance of the budget file.
 - If the same subsystem needs a third consecutive hardening change, stop patching it and
   re-derive the design from the core invariants.
 
@@ -20,8 +19,8 @@
 - This is a `jj` repo. Do not use `git` to work on the repo itself.
 - Do not use git worktree-based agent isolation in this repo. For isolated parallel work, use
   `jj workspace` instead.
-- Run the CLI locally with `uv run jj-stack ...` instead of invoking the module or virtualenv
-  path directly.
+- Run the CLI locally with `just run ...` instead of invoking the module or virtualenv path
+  directly.
 - Hard-wrap code and markdown files at 98 columns unless a file uses a different convention.
 
 # Commit messages
@@ -33,7 +32,7 @@
 - Hard-wrap commit message bodies at 72 columns.
 - The body should explain the motivation for the change, the intended behavior or design outcome,
   and any important scope or design constraints.
-- Do not use the body to narrate the code or to record routine validation such as `./check.py`.
+- Do not use the body to narrate the code or to record routine validation such as `just check`.
 - Prefer explaining why the commit exists and what rule or user-visible behavior it is enforcing.
 
 # Documentation
@@ -42,9 +41,10 @@
   rules and the public/internal split. Built-in `--help` text is held to the same standard as
   the user docs: assume jj/git familiarity, avoid `jj-stack` internal design jargon.
 - The web version of the user docs normally lives in the sibling jj repository at
-  `$(jj root)/../website`. When user-facing docs change here, inspect and update the corresponding
-  web docs there too when needed. If the change here is committed, commit the corresponding
-  website update in that repository as well; preserve unrelated work in either working copy.
+  `$(jj root)/../website`. When user-facing docs change here, run `just website`, inspect the
+  corresponding website changes, and update them as needed. If the change here is committed,
+  commit the corresponding website update in that repository as well; preserve unrelated work in
+  either working copy.
 - Active internal docs use ordinary technical language too. Introduce a project-specific term
   only when it names a real type, field, or enduring rule, define it at first use, and prefer
   describing concrete inputs and effects.
@@ -71,13 +71,9 @@
 
 # Testing
 
-- Run `./check.py` before finishing a code change. Docs-only edits under `docs/` do not require
-  a test run.
-- Run `./check.py` for the default local Ruff, type-check, and test pass before finishing a
-  code change.
-- For focused test runs, do not use plain `uv run pytest ...`; it can miss the repo's package
-  path in this project layout. First run `uv sync --locked`, then invoke pytest through the repo
-  virtualenv, for example `.venv/bin/python -m pytest tests/unit/test_jj_client.py`.
+- Run `just check` for the default local Ruff, type-check, and test pass before finishing a code
+  change. Docs-only edits under `docs/` do not require a test run.
+- Run focused tests with `just test`, for example `just test tests/unit/test_jj_client.py`.
 - Before adding, modifying, removing, or reviewing tests, fixtures, helpers, or property
   scenarios, read and follow
   [docs/internals/testing-philosophy.md](docs/internals/testing-philosophy.md). Add or retain

{jj_stack-0.1.1 → jj_stack-0.1.2}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.5
 Name: jj-stack
-Version: 0.1.1
+Version: 0.1.2
 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/
+Project-URL: Changelog, https://github.com/bos/jj-stack/releases
 Project-URL: Repository, https://github.com/bos/jj-stack
 Project-URL: Issues, https://github.com/bos/jj-stack/issues
 License-Expression: Apache-2.0
@@ -20,6 +21,7 @@ Classifier: Topic :: Software Development :: Version Control
 Classifier: Topic :: Software Development :: Version Control :: Git
 Requires-Python: >=3.14
 Requires-Dist: httpxyz<0.32,>=0.31.0
+Requires-Dist: markdown-it-py<5,>=4.0.0
 Requires-Dist: pydantic<3,>=2.13.3
 Requires-Dist: rich<16,>=15.0.0
 Description-Content-Type: text/markdown
@@ -61,16 +63,25 @@ python -m pip install jj-stack
 To upgrade an installation made with `uv`, rerun its command with `--force`. If the command is
 not on your shell `PATH`, run `uv tool update-shell`.
 
-For tab completion, add the output of `jj-stack completion` to your shell startup file:
+### Invoke it as `jj stack`
 
-```bash
-eval "$(jj-stack completion zsh)"
+Add a command alias to your user configuration with `jj config edit --user`:
+
+```toml
+[aliases]
+stack = ["util", "exec", "--", "jj-stack"]
 ```
 
-`bash` and `fish` work the same way.
+For tab completion of both `jj-stack` and `jj stack`, add the output of `jj-stack completion` to
+your shell startup file:
 
-To invoke it as `jj stack` and complete that alias too, see
-[Configuration](https://www.serpentine.com/software/jj-stack/reference/configuration/).
+```bash
+eval "$(jj-stack completion zsh --jj-alias stack)"
+```
+
+`bash` and `fish` work the same way. See
+[Configuration](https://www.serpentine.com/software/jj-stack/reference/configuration/) for more
+setup options.
 
 ### Submit your first stack
 
@@ -137,7 +148,7 @@ merge queues, cleanup, and working with multiple stacks.
 - [Configuration](https://www.serpentine.com/software/jj-stack/reference/configuration/)
 - [Writing PR descriptions](https://www.serpentine.com/software/jj-stack/reference/descriptions/)
 - [Troubleshooting](https://www.serpentine.com/software/jj-stack/troubleshooting/)
-- [`jj-stack` and `gh stack`](https://www.serpentine.com/software/jj-stack/gh-stack/)
+- [Tool comparison](https://www.serpentine.com/software/jj-stack/tool-comparison/)
 - [JSON output](https://www.serpentine.com/software/jj-stack/reference/json-output/)
 - [Automation and exit codes](https://www.serpentine.com/software/jj-stack/reference/automation/)
 
@@ -149,6 +160,12 @@ jj-stack <command> --help
 jj-stack help --all
 ```
 
+## Development
+
+Contributor workflows live in the [`justfile`](justfile). With `uv`, `jj`, and `just` installed,
+run `just` to list the setup, formatting, focused test, verification, documentation, and release
+recipes.
+
 ## Coding agent integration
 
 Install the bundled skill to teach coding agents to work with local `jj` stacks and refresh their

{jj_stack-0.1.1 → jj_stack-0.1.2}/README.md

@@ -35,16 +35,25 @@ python -m pip install jj-stack
 To upgrade an installation made with `uv`, rerun its command with `--force`. If the command is
 not on your shell `PATH`, run `uv tool update-shell`.
 
-For tab completion, add the output of `jj-stack completion` to your shell startup file:
+### Invoke it as `jj stack`
 
-```bash
-eval "$(jj-stack completion zsh)"
+Add a command alias to your user configuration with `jj config edit --user`:
+
+```toml
+[aliases]
+stack = ["util", "exec", "--", "jj-stack"]
 ```
 
-`bash` and `fish` work the same way.
+For tab completion of both `jj-stack` and `jj stack`, add the output of `jj-stack completion` to
+your shell startup file:
 
-To invoke it as `jj stack` and complete that alias too, see
-[Configuration](https://www.serpentine.com/software/jj-stack/reference/configuration/).
+```bash
+eval "$(jj-stack completion zsh --jj-alias stack)"
+```
+
+`bash` and `fish` work the same way. See
+[Configuration](https://www.serpentine.com/software/jj-stack/reference/configuration/) for more
+setup options.
 
 ### Submit your first stack
 
@@ -111,7 +120,7 @@ merge queues, cleanup, and working with multiple stacks.
 - [Configuration](https://www.serpentine.com/software/jj-stack/reference/configuration/)
 - [Writing PR descriptions](https://www.serpentine.com/software/jj-stack/reference/descriptions/)
 - [Troubleshooting](https://www.serpentine.com/software/jj-stack/troubleshooting/)
-- [`jj-stack` and `gh stack`](https://www.serpentine.com/software/jj-stack/gh-stack/)
+- [Tool comparison](https://www.serpentine.com/software/jj-stack/tool-comparison/)
 - [JSON output](https://www.serpentine.com/software/jj-stack/reference/json-output/)
 - [Automation and exit codes](https://www.serpentine.com/software/jj-stack/reference/automation/)
 
@@ -123,6 +132,12 @@ jj-stack <command> --help
 jj-stack help --all
 ```
 
+## Development
+
+Contributor workflows live in the [`justfile`](justfile). With `uv`, `jj`, and `just` installed,
+run `just` to list the setup, formatting, focused test, verification, documentation, and release
+recipes.
+
 ## Coding agent integration
 
 Install the bundled skill to teach coding agents to work with local `jj` stacks and refresh their

{jj_stack-0.1.1 → jj_stack-0.1.2}/check.py

@@ -18,6 +18,7 @@ VENV_PYTHON = (
     REPO_ROOT / ".venv" / (Path("Scripts/python.exe") if os.name == "nt" else Path("bin/python"))
 )
 PytestJobs = int | Literal["auto"]
+_PYREFLY_TARGETS = ("src", "tests", "tools", "check.py")
 _FRAGILE_TEST_OUTPUT_PATTERNS: tuple[tuple[str, re.Pattern[str]], ...] = (
     (
         "use output assertion helpers instead of exact captured output equality",
@@ -77,10 +78,17 @@ def _build_checks(
     return (
         ("ruff", ("-m", "ruff", "check")),
         ("ruff-format", ("-m", "ruff", "format", "--check")),
-        ("pyrefly", ("-m", "pyrefly", "check")),
+        ("pyrefly", ("-m", "pyrefly", "check", *_PYREFLY_TARGETS)),
         (
             "pyrefly-windows",
-            ("-m", "pyrefly", "check", "--python-platform", "win32"),
+            (
+                "-m",
+                "pyrefly",
+                "check",
+                "--python-platform",
+                "win32",
+                *_PYREFLY_TARGETS,
+            ),
         ),
         ("pytest", pytest_command),
     )

{jj_stack-0.1.1 → jj_stack-0.1.2}/docs/README.md

@@ -23,12 +23,13 @@ web navigation and presentation.
 ## Reference and troubleshooting
 
 - [Command reference](reference/commands.md)
+- [Bookmarks and stack selection](reference/bookmarks-and-selection.md)
 - [Configuration](reference/configuration.md)
 - [Pull request descriptions](reference/descriptions.md)
 - [Automation and agents](reference/automation.md)
 - [JSON output](reference/json-output.md)
 - [Troubleshooting](troubleshooting.md)
-- [`jj-stack` and `gh stack`](gh-stack.md)
+- [Compare `jj-stack` with other tools](tool-comparison.md)
 
 The built-in help is the exact flag and alias reference:
 

{jj_stack-0.1.1 → jj_stack-0.1.2}/docs/guides/submit-and-update.md

@@ -78,6 +78,12 @@ previously approved or asked for changes (i.e. revoking the approved state of yo
 jj-stack submit --re-request
 ```
 
+## PR history
+
+To make it easier for a reader to understand how a pull request has changed over time, when you
+run `submit` to update a PR that you have submitted before, `jj-stack` will keep a comment up to
+date on the PR that shows its most recent versions, with a link to the diff for each update.
+
 ## What the `submit` command changes
 
 | Surface | Effect |
@@ -86,6 +92,7 @@ jj-stack submit --re-request
 | PR branches | Created or updated |
 | Pull requests | Created or updated |
 | Pull request order | Updated to match the local change order |
+| Pull request comments | Revision history maintained |
 | Other local stacks | Not changed |
 
 With `jj`, you can easily move your changes between existing stacks. However, GitHub allows each

{jj_stack-0.1.1 → jj_stack-0.1.2}/docs/guides/working-on-github.md

@@ -25,28 +25,31 @@ edits and GitHub's rewritten contents disagree, `sync` stops instead of choosing
 ## What the next submit replaces
 
 `jj-stack submit` makes GitHub's stack match your local stack. It pushes each change in your stack
-to its PR branch, sets each pull request's base from the local parent order, refreshes titles and
-bodies from `jj` descriptions or supplied description files, and updates native stack membership.
+to its PR branch, sets each pull request's base from the local parent order, and updates native
+stack membership.
+
+By default, `submit` will generate a pull request description from the `jj` change. On a
+subsequent submit, if the PR description still matches the last automated PR description,
+`submit` will refresh it from the current change description. Otherwise, `submit` will leave it
+untouched.
+
+Use `--describe` to replace one body deliberately (or `--describe-with` or `--edit` for titles and
+bodies).
+
 `--draft` affects new pull requests. `--draft=all`, `--open`, and the choices made through
 `--edit` can change existing draft states. Labels and reviewer requests that submit applies are
-additive;
-unrelated existing labels and reviewers are not removed.
-
-Edits made directly to a pull request title or body are therefore temporary unless you copy them
-back into the change description or pass them again on the next submit.
+additive; unrelated existing labels and reviewers are not removed.
 
 ## Changes to avoid on GitHub
 
-Do not force-push, rename, or delete `jj-stack/` PR branches. Do not manually retarget pull
-request bases, reorder members, or add pull requests to the native stack when you intend the
-local stack order to remain authoritative. A later submit may replace grouping and bases; an
-unexpected branch move instead causes jj-stack to stop so it does not overwrite someone else's
-work.
+Do not force-push, rename, or delete `jj-stack/` PR branches. If a branch moves unexpectedly,
+jj-stack stops instead of overwriting it. See [troubleshooting](../troubleshooting.md) for the
+recovery steps.
 
-If an external edit was intentional, inspect the result before deciding whether to restore the
-GitHub state, reproduce the change with `jj` and submit it, or remove the GitHub grouping with
-`jj-stack unstack --stack <number>`. See [troubleshooting](../troubleshooting.md) for specific
-recovery paths.
+Do not change pull request bases or GitHub stack membership by hand. `jj-stack submit` derives
+both from the local `jj` history. To keep a different base or order, make that change locally and
+submit again. To leave the pull requests open but remove their GitHub stack grouping, run
+`jj-stack unstack --stack <number>`.
 
 For reviewer and repo configuration guidance, see
 [review and operate a stack](review-a-stack.md).

{jj_stack-0.1.1 → jj_stack-0.1.2}/docs/internals/code-reviews.md

@@ -54,8 +54,8 @@ wrong PR or ref, guessed linkage, then inconsistencies in reconstructible metada
 an elaborate recovery system to protect data that can be observed again.
 
 The limits in `complexity-budget.toml` are design constraints. Review changes to the limits,
-governed paths, and test markers as carefully as production code. CI runs
-`uv run tools/check_complexity.py`; run it locally when the pinned `tokei` version is installed.
+governed paths, and test markers as carefully as production code. Run `just complexity` locally
+when the pinned `tokei` version is installed; CI invokes the underlying checker.
 Moving the same logic into a helper or neighboring module is not a reduction in complexity.
 
 ## Review the user experience

{jj_stack-0.1.1 → jj_stack-0.1.2}/docs/internals/design.md

@@ -262,8 +262,9 @@ Three sources answer questions about a tracked PR, each for a different domain:
 
 1. The **`jj` DAG** determines which local changes exist, how they are related, and what they
    contain.
-2. **GitHub** reports PR existence, lifecycle, reviews, GitHub stack membership, and merge
-   results. Whether work actually reached trunk is proven separately by ancestry from it.
+2. **GitHub** reports PR existence, lifecycle, reviews, check rollups, GitHub stack membership,
+   and merge results. Whether work actually reached trunk is proven separately by ancestry from
+   it.
 3. **Local tracking** records only the PR identity and submitted baseline of each change. It
    prevents mutation of the wrong PR but cannot make a mutation safe on its own.
 
@@ -305,15 +306,16 @@ These facts are re-derived and never need tool-owned durable state:
 
 Tracking stores one pair, keyed by full `change_id`:
 
-- `PRIdentity`: GitHub repo owner/name, PR number, and one canonical head owner/ref
+- `PRIdentity`: the PR number and its one canonical head ref
 - `SubmittedBaseline`: the exact `commit_id` last successfully submitted for that identity
 
 Both records are created, replaced, and removed together. Partial pairs are invalid.
+The configured GitHub repo is command context, not per-change tracking; `jj-stack` does not carry
+tracking across repos.
 
 Two named checks recur throughout the policies:
 
-- **identity match**: the live PR's repo, number, and head owner/ref equal the saved
-  `PRIdentity`
+- **identity match**: the live PR's number and head ref equal the saved `PRIdentity`
 - **snapshot match**: an identity match whose live PR head SHA also equals
   `SubmittedBaseline.commit_id`
 
@@ -677,6 +679,10 @@ deletes a branch needed by an active GitHub stack member.
 GitHub stacks whose active members are all selected. It may also dissolve one partially selected
 GitHub stack when the selection is a maximal local path and touches no other GitHub stack. A
 non-maximal selection could silently truncate a still-valid stack, so it stops before mutation.
+An unselected active member does not trigger that guard when its observed PR number, branch, and
+head still match the saved PR number, branch, and submitted baseline, and its tracked change has
+no visible off-trunk copy. That change cannot be on an extension of the selected path. Rebuilding
+the grouping leaves the orphaned pull request open and retains its tracking.
 Likewise, a selection that partly overlaps one GitHub stack while including any previously
 submitted PR outside that resource stops; the user submits the source path first, then the
 destination path.
@@ -696,15 +702,26 @@ they do not block the mutation because they are no longer active.
 
 ### Derived artifacts
 
-PR titles, bodies, and the stack overview comment are derived on every submit and never determine
-topology; see [pull request descriptions](../reference/descriptions.md).
+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. PR text is
+not stored locally and never determines topology; 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
+no overview comment. New PRs are created in the requested draft state.
+
+Submit maintains a per-PR revision-history comment with the most recent versions available from
+GitHub's force-push timeline. The comment is presentation-only and remains after merge and
+cleanup. This makes it easier for a reader to understand how a PR has evolved.
 
-The managed overview comment is the first comment whose body contains its marker; its ID is never
-stored. A lone PR has no overview comment. New PRs are created in the requested draft state.
 Existing PRs become draft only with `--draft=all` and become ready only with `--open`; plain
 `submit --draft` never unpublishes an existing PR. With `--edit`, GitHub's current state and those
 command-wide defaults populate one editable draft choice per change. The validated document then
-determines each selected PR's draft state without adding local state.
+determines each selected PR's draft state without adding local state. A newly generated editor
+file remains until the entire submit succeeds. If the command stops, the user can pass that file
+back to `--edit`; the retry re-observes the local stack and GitHub, and accepts the file only when
+it names exactly the currently selected changes. The file carries no submit plan or phase.
 
 `--reviewers` and `--team-reviewers` request the named reviewers even when a PR is otherwise
 unchanged and never remove omitted reviewers. `--re-request` acts on an otherwise unchanged PR,
@@ -713,6 +730,9 @@ adds requests and never cancels a pending one. An explicit `--label` request app
 PR is otherwise unchanged; configured labels alone do not turn a no-op submit into a metadata
 update. Labels are also additive; omitted labels are never removed.
 
+Default PR bodies derived from change descriptions unfold Markdown soft line breaks into spaces.
+Markdown block boundaries, code, tables, and explicit hard line breaks remain unchanged.
+
 ### Unstack and cleanup
 
 `unstack` removes one exact GitHub stack grouping and leaves every pull request, PR branch,

{jj_stack-0.1.1 → jj_stack-0.1.2}/docs/internals/implementation-strategy.md

@@ -89,6 +89,15 @@ it does not add site navigation or styling. The website invokes that renderer fr
 jj-stack checkout whose canonical user guides it snapshots, then owns the generated page's front
 matter, CSS, and publication.
 
+## Development workflows
+
+The root `justfile` is the contributor entry point for setup, local CLI execution, formatting,
+focused tests, standard checks, complexity checks, generated scenarios, live GitHub qualification,
+website documentation synchronization, and release artifacts. Recipes delegate substantive
+behavior to existing scripts, including the website-owned documentation sync and the check scripts
+shared with CI; they do not reimplement them. The README points contributors to `just` instead of
+duplicating the underlying commands.
+
 ## Test boundaries
 
 The local integration environment uses real `jj` and Git repos with a purpose-built

{jj_stack-0.1.1 → jj_stack-0.1.2}/docs/internals/property-testing.md

@@ -39,10 +39,10 @@ hash-order dependence. Every pytest worker must collect the same cases. If gener
 the requested number of unique cases within its attempt limit, it returns the cases found instead
 of looping indefinitely.
 
-`./check.py` runs a small fixed set. Larger deterministic pools are opt-in:
+`just check` runs a small fixed set. Larger deterministic pools are opt-in:
 
 ```console
-$ tests/run_submit_property_scenarios.py 500
+$ just property 500
 ```
 
 The runner prints a complete reproduction command with the resolved seed, family counts, worker

jj_stack-0.1.2/docs/internals/releasing.md

@@ -0,0 +1,71 @@
+# Release process
+
+A release is built from a `v<version>`-tagged commit on `main`. The tag workflow builds and tests
+both distributions, publishes them to PyPI, and creates the matching GitHub Release. A manual
+workflow run publishes to TestPyPI unless it names an existing release tag to retry.
+
+## Write the release notes
+
+Create `release-notes/v<version>.md`, using the same version as `pyproject.toml`. This file is the
+source for the GitHub Release body and must be part of the tagged commit. The production workflow
+fails before publishing if the file is absent or empty. On a retry, it also fails if an existing
+GitHub Release does not contain exactly the notes from the tagged commit.
+
+Write for someone deciding whether to upgrade, not for someone reconstructing the commit history:
+
+- Open with a short summary of the release's user-visible value.
+- Group changes by user impact. Use headings such as `Breaking changes`, `Highlights`, `Fixes`,
+  and `Documentation`, but omit empty sections.
+- Put breaking changes first. State who is affected, what happens after upgrading, and the exact
+  migration or workaround.
+- Make each bullet describe one observable outcome in plain language. Include commands, version
+  requirements, and links to the relevant guide when they help the reader act.
+- Explain important fixes in terms of the symptom that is gone. Do not paste commit subjects,
+  internal type names, or an automatically generated pull request list.
+- End with a comparison link from the previous tag to the new tag, labeled `Full changelog`.
+
+Keep the notes self-contained even when they link to a pull request or issue. Proofread the
+rendered Markdown and check every command and link before tagging. A release with no breaking
+changes does not need a `Breaking changes` heading.
+
+## Qualify the candidate
+
+Set the intended version in `pyproject.toml`, finish the release changes and release notes, and
+run the release gates:
+
+```console
+just release-check
+```
+
+The live test requires a `gh` login that can create and delete a private repo, push to it, and
+manage its pull requests.
+
+Check the website snapshot and production build:
+
+```console
+just website-check
+cd ../website
+just check
+```
+
+If the snapshot is out of date, run `just website` from the jj-stack checkout, review and commit
+the website change, then rerun the checks. Push the release changes to `main` before creating the
+tag. A manual run of the release workflow is the optional TestPyPI smoke test.
+
+## Publish the tag
+
+Create the version tag and push it explicitly:
+
+```console
+jj tag set v0.1.0 -r main
+jj git push --tag v0.1.0
+```
+
+Use the version from `pyproject.toml` in place of `0.1.0`. After the workflow succeeds, verify the
+GitHub Release contains the authored notes and downloadable distributions. PyPI has no separate
+per-version release-notes field; its project page exposes the GitHub Releases page through the
+standard `Changelog` project link. Verify that link along with the package page, publish the
+already-checked website with `just publish`, and verify the live quick start and install command.
+
+Never move or reuse a published version tag. A failed workflow can be rerun against the same tag;
+a source change requires a new version and tag.

{jj_stack-0.1.1 → jj_stack-0.1.2}/docs/json-output.schema.json

@@ -132,6 +132,14 @@
         }
       ],
       "properties": {
+        "checks": {
+          "type": "string",
+          "enum": [
+            "passed",
+            "failed",
+            "pending"
+          ]
+        },
         "number": {
           "type": "integer",
           "minimum": 1