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

jj_stack-0.1.4/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,59 @@
+name: Bug report
+description: Report incorrect or surprising jj-stack behavior.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Before filing, check [Troubleshooting](https://www.serpentine.com/software/jj-stack/troubleshooting/).
+        Many errors end with a `Hint:` that resolves them.
+
+        Do not paste private repository contents, tokens, or internal URLs.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What you ran, what you expected, and what jj-stack did instead.
+      placeholder: |
+        I ran `jj-stack submit` on a three-change stack and expected ...
+        Instead it ...
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: >-
+        The local stack shape and the commands you ran, in order. `jj log` output for the
+        affected stack is usually the most useful thing you can include.
+    validations:
+      required: true
+  - type: textarea
+    id: doctor
+    attributes:
+      label: Output of `jj-stack doctor`
+      description: Run it in the affected repo. It reports repo setup, GitHub access, and leftovers.
+      render: console
+    validations:
+      required: false
+  - type: input
+    id: jj-stack-version
+    attributes:
+      label: jj-stack version
+      description: Output of `jj-stack --version`.
+    validations:
+      required: true
+  - type: input
+    id: jj-version
+    attributes:
+      label: jj version
+      description: Output of `jj --version`.
+    validations:
+      required: true
+  - type: input
+    id: platform
+    attributes:
+      label: Operating system
+      placeholder: macOS 15.5, Ubuntu 24.04, Windows 11
+    validations:
+      required: true

jj_stack-0.1.4/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Documentation
+    url: https://www.serpentine.com/software/jj-stack/
+    about: Guides, command reference, configuration, and automation.
+  - name: Troubleshooting
+    url: https://www.serpentine.com/software/jj-stack/troubleshooting/
+    about: Recovery steps for the common failure symptoms, organized by what you saw.
+  - name: Report a security vulnerability
+    url: https://github.com/bos/jj-stack/security/advisories/new
+    about: Use private vulnerability reporting. Do not open a public issue.

jj_stack-0.1.4/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,32 @@
+name: Feature request
+description: Suggest a capability or a change to an existing one.
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        jj-stack is deliberately opinionated: one `jj` change is one pull request, and it owns the
+        generated PR branches. [Compare tools](https://www.serpentine.com/software/jj-stack/tool-comparison/)
+        explains what that rules out. A request that conflicts with those choices may still be
+        worth making — say why the stance should change.
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: The workflow you are trying to complete, and where jj-stack gets in the way.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What you would like instead
+      description: The behavior you want. Include the command and output you imagine, if you have one.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: What you do today
+      description: The workaround you currently use, and why it is not good enough.
+    validations:
+      required: false

{jj_stack-0.1.2 → jj_stack-0.1.4}/.github/SECURITY.md

@@ -8,8 +8,8 @@ This project is under active development. Security fixes are supported on `main`
 
 Please do not report security vulnerabilities in public GitHub issues.
 
-Use GitHub's private vulnerability reporting for this repo if it is enabled. If you cannot
-use private reporting, contact the maintainers directly and include:
+Use [private vulnerability reporting](https://github.com/bos/jj-stack/security/advisories/new),
+which is enabled for this repo. Include:
 
 - a description of the issue
 - steps to reproduce or a proof of concept

jj_stack-0.1.4/.github/pull_request_template.md

@@ -0,0 +1,19 @@
+<!--
+See CONTRIBUTING.md. For a substantial change, please open an issue first.
+Commit subjects use `scope: summary`; explain why in the body, wrapped at 72 columns.
+-->
+
+## What this changes
+
+<!-- The user-visible behavior or rule this adds, alters, or fixes. -->
+
+## Why
+
+<!-- The motivation. For a fix, the symptom that is gone. -->
+
+## Checks
+
+- [ ] `just check` passes
+- [ ] `just complexity` passes, or the pull request explains why a budget must change
+- [ ] Documentation updated, or not required by the rules in `AGENTS.md`
+- [ ] Website snapshot refreshed with `just website` if user-facing docs or `--help` changed

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

@@ -23,11 +23,12 @@ jobs:
           python-version: "3.14"
 
       - name: Install tokei
-        env:
-          # Must match TOKEI_VERSION in tools/check_complexity.py; the budgets are baselined
-          # against this exact counter. 14.0.0 publishes no prebuilt binaries, so build it.
-          TOKEI_VERSION: 14.0.0
-        run: cargo install tokei --locked --version "$TOKEI_VERSION"
+        run: |
+          TOKEI_VERSION="$(
+            uv run --no-project --python 3.14 python -c \
+              'from tools.check_complexity import TOKEI_VERSIONS; print(TOKEI_VERSIONS[-1])'
+          )"
+          cargo install tokei --locked --version "^$TOKEI_VERSION"
 
       - name: Install project environment
         run: uv sync --locked
@@ -39,7 +40,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        jj-version: ["v0.44.0"]
+        jj-version: ["v0.45.1"]
         os: [ubuntu-latest, macos-latest, windows-latest]
         python-version: ["3.14"]
     runs-on: ${{ matrix.os }}
@@ -71,7 +72,7 @@ jobs:
   submit-property-smoke:
     runs-on: ubuntu-latest
     env:
-      JJ_VERSION: v0.44.0
+      JJ_VERSION: v0.45.1
 
     steps:
       - name: Check out repo
@@ -85,11 +86,6 @@ jobs:
       - name: Install jj
         run: echo "$(tools/install-jj-release.sh "$JJ_VERSION")" >> "$GITHUB_PATH"
 
-      - name: Run submit property smoke scenarios
+      - name: Run generated client and server sequences
         run: >-
-          tests/run_submit_property_scenarios.py 10 --random-seed -n auto
-          --stack-join-scenarios 5
-          --lifecycle-scenarios 10
-          --stack-move-scenarios 5
-          --retry-scenarios 5
-          --drift-scenarios 21
+          tests/run_submit_property_scenarios.py 5 --steps 20 --shards 8 --random-seed -n auto

{jj_stack-0.1.2 → jj_stack-0.1.4}/.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.7
+        uses: github/codeql-action/init@v4.37.9
         with:
           languages: python
           build-mode: none
 
       - name: Analyze
-        uses: github/codeql-action/analyze@v4.37.7
+        uses: github/codeql-action/analyze@v4.37.9

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

@@ -19,7 +19,7 @@ concurrency:
   cancel-in-progress: false
 
 env:
-  JJ_VERSION: v0.44.0
+  JJ_VERSION: v0.45.1
 
 jobs:
   build:

{jj_stack-0.1.2 → jj_stack-0.1.4}/.gitignore

@@ -10,3 +10,5 @@ htmlcov/
 .uv-cache/
 .venv
 .venv/
+
+.hypothesis/

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

@@ -1,15 +1,15 @@
-## Complexity control
+# Complexity control
 
 - A replacement is incomplete until it deletes the mechanism it supersedes in the same change.
-  Do not add a temporary parallel model with a promise to remove it in a later cleanup slice.
-- Define each jj-stack-owned durable policy fact once and store it one way. Shared observation or
-  storage code must not create a second path for deciding or changing it.
+  Do not keep a parallel model for a later cleanup.
+- Store each persistent fact in one form, with one owner. Shared observation and storage code
+  must not introduce competing policy decisions.
 - Batch independent read-only facts, but keep dependent mutations in order. Bind an irreversible
   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. Run `just complexity` locally
-  when the pinned `tokei` is installed; CI invokes the underlying checker. A budget increase is a
+- Check the cumulative complexity budgets after each code change. Run `just complexity` locally
+  when a supported `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.
@@ -22,6 +22,7 @@
 - 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.
+  Release-note prose follows `docs/internals/releasing.md` and is intentionally unwrapped.
 
 # Commit messages
 
@@ -37,25 +38,26 @@
 
 # Documentation
 
-- User-facing docs live in `docs/`. See [docs/AGENTS.md](docs/AGENTS.md) for the vocabulary
-  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.
+- User-facing docs live in `docs/`, except for contributor notes in `docs/internals/`. See
+  [docs/AGENTS.md](docs/AGENTS.md) for the vocabulary 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, 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
+  only when it names an existing type, field, or enduring rule, define it at first use, and prefer
   describing concrete inputs and effects.
-- `design.md` and `implementation-strategy.md` describe the current product and architecture, not
-  completed slices or abandoned mechanisms. Keep implementation history in `jj` commits.
-- Default to code and tests only. Update documentation only when a change intentionally adds or
-  changes a supported product rule or user workflow, or makes a specific existing statement
-  materially inaccurate. A bug and its fix are not by themselves a documentation trigger.
+- Internal design and strategy documents describe the current product and architecture. Keep
+  implementation history in `jj` commits.
+- For implementation work, update documentation when a change adds or alters a supported rule or
+  workflow, or makes an existing statement inaccurate. A bug fix alone does not require a docs
+  change. Documentation reviews and corrections can also address clarity, duplication, and gaps.
 - When documentation is required, update only the affected source: `design.md` for an enduring
-  product rule, user docs or `--help` for user guidance, and `implementation-strategy.md` for an
-  architecture, tooling, or test-layer strategy change.
+  product rule, user docs or `--help` for user guidance, and the relevant testing document for
+  test strategy.
 
 # Behaviour changes
 
@@ -66,8 +68,9 @@
   the other way around: evaluate a documented behavior on its merits before extending it, and
   prefer deleting case-specific rules that follow from the principles over adding new ones. Never
   add durable transaction or replay state; recovery is observational (see design.md).
-- Preserve the core invariants: the `jj` DAG determines stack topology, local cache is sparse,
-  GitHub pull requests are derived from the local `jj` stack, and ambiguous linkage fails closed.
+- Preserve the core invariants: the `jj` DAG determines stack topology, tracking stores only PR
+  links and submitted commits, GitHub PRs follow the local stack, and ambiguous linkage stops
+  mutation.
 
 # Testing
 

jj_stack-0.1.4/CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing
+
+Thanks for your interest in `jj-stack`.
+
+## Before you start
+
+Open an issue before writing a substantial change. `jj-stack` is deliberately opinionated about
+what it manages and what it leaves to `jj`, so a feature that fits your workflow may still be out
+of scope. [Compare tools](docs/tool-comparison.md) explains the stance and its trade-offs.
+
+Bug reports, documentation corrections, and small focused fixes are welcome without prior
+discussion.
+
+## Development setup
+
+You need `uv`, Git, `jj` 0.45.1 or newer, and `just`. The project requires Python 3.14 or newer;
+`uv` can provide the interpreter when it creates the locked development environment:
+
+```console
+just setup
+```
+
+Run `just` on its own to list every recipe.
+
+## Working on a change
+
+Run the CLI from your checkout with `just run ...` rather than invoking the module or the
+virtualenv path directly:
+
+```console
+just run view
+```
+
+Before finishing a code change, run the standard Ruff, type-check, and test pass. Docs-only edits
+under `docs/` do not require it:
+
+```console
+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`:
+
+```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).
+
+Run focused tests while you iterate:
+
+```console
+just test tests/unit/test_jj_client.py
+```
+
+CI also enforces the cumulative complexity budgets. Check them locally with `just complexity`
+when a supported `tokei` is installed. Raising a budget is a design decision, not routine
+maintenance — say why in the pull request.
+
+If your change touches user-facing guides or references, refresh the website snapshot with
+`just website` and include the resulting change in the sibling `website` repository.
+
+## Conventions
+
+[`AGENTS.md`](AGENTS.md) is the working agreement for this repo, and it applies to human
+contributors too. It covers commit message format, the 98-column wrap, when documentation
+changes are required, and where each kind of documentation belongs. The internal notes under
+[`docs/internals/`](docs/internals/) cover the design, testing philosophy, and review standard.
+
+The short version:
+
+- Write commit subjects as `scope: summary`, lowercase, no trailing period.
+- Explain *why* the change exists in the body, wrapped at 72 columns.
+- Add tests at the narrowest layer that covers a distinct risk; consolidate overlapping coverage
+  rather than adding parallel cases.
+- For code changes, update docs when supported rules, workflows, or existing statements change.
+  Documentation corrections and editorial improvements are welcome independently.
+
+## Submitting
+
+Pull requests go to `main`. `jj-stack` is developed with `jj-stack`, so a stacked series of small
+changes is easy to review and very welcome.
+
+By contributing, you agree that your contributions are licensed under the
+[Apache License 2.0](LICENSE).

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: jj-stack
-Version: 0.1.2
+Version: 0.1.4
 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/
@@ -20,7 +20,7 @@ Classifier: Programming Language :: Python :: 3.14
 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: httpx2<3,>=2.12.0
 Requires-Dist: markdown-it-py<5,>=4.0.0
 Requires-Dist: pydantic<3,>=2.13.3
 Requires-Dist: rich<16,>=15.0.0
@@ -29,64 +29,26 @@ Description-Content-Type: text/markdown
 # jj-stack: manage stacked GitHub PRs with jj
 
 `jj-stack` turns a linear series of local `jj` changes into a stack of GitHub pull requests.
-Rewrite, split, squash, or reorder the changes with `jj`, then let `jj-stack` update the
-matching PRs.
+Rewrite, split, squash, or reorder the changes with `jj`, then run `jj-stack submit` to update
+GitHub. Existing PRs follow their change IDs, keeping comments and review history together.
 
 ## Quick start
 
-### Requirements
+You need Python 3.14 or newer, `jj` 0.45.1 or newer, and a repo on github.com where you can push
+branches and open pull requests. `jj-stack` uses `GITHUB_TOKEN`, then `GH_TOKEN`, then your GitHub
+CLI login for authentication.
 
-- Python 3.14 or newer
-- `jj` 0.44.0 or newer
-- GitHub authentication
-
-### Install
-
-Install `jj-stack` from PyPI with `uv` in an isolated tool environment (recommended):
+Install with `uv`:
 
 ```bash
 uv tool install jj-stack
 ```
 
-`pipx` provides another isolated installation:
-
-```bash
-pipx install jj-stack
-```
-
-You can also use `pip` inside an activated virtual environment:
-
-```bash
-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`.
-
-### Invoke it as `jj stack`
-
-Add a command alias to your user configuration with `jj config edit --user`:
-
-```toml
-[aliases]
-stack = ["util", "exec", "--", "jj-stack"]
-```
-
-For tab completion of both `jj-stack` and `jj stack`, add the output of `jj-stack completion` to
-your shell startup file:
-
-```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
 
-Start with a linear series of local `jj` changes on top of `trunk()`. In a new repo, check
-the setup and apply the safe local fixes:
+Start with a linear series of local `jj` changes on top of `trunk()`. Authenticate with
+`gh auth login`, or supply a token in `GITHUB_TOKEN` or `GH_TOKEN`. Check the repo setup and
+apply the safe local fixes:
 
 ```bash
 jj-stack doctor --fix
@@ -109,20 +71,27 @@ refresh. Use `jj-stack list` to see every tracked stack in the repo.
 
 ## Mental model
 
-The local `jj` DAG determines which changes form a stack and their order. On GitHub, each change
-gets a stable PR branch and a PR; every PR targets the PR branch below it, except the
-bottom PR, which targets trunk by default:
+Your local `jj` history determines which changes form a stack and their order. On GitHub, each
+change gets a stable PR branch and a PR. The bottom PR targets trunk by default, and each PR
+above it targets the PR branch below:
 
 ```text
-jj-stack/add-ui-...         -> PR #3 (base: jj-stack/add-api-...)
-jj-stack/add-api-...        -> PR #2 (base: jj-stack/refactor-model-...)
-jj-stack/refactor-model-... -> PR #1 (base: main)
-main                        -> trunk
+Local changes:  trunk() <- A     <- B     <- C
+GitHub PRs:     main    <- PR #1 <- PR #2 <- PR #3
 ```
 
-The PR branches normally stay out of your local bookmark view. When you rewrite a change,
-`jj-stack` updates that change's existing PR branch and PR, along with the PR branches and PRs for
-dependent changes.
+Each PR's diff shows only the changes it adds on top of its base, so reviewers can consider
+one change at a time. `jj-stack` manages the PR branches for you, and they normally stay out
+of your local bookmark view.
+
+When you rewrite a change, its change ID still connects it to the same PR. Submitting again
+updates that PR and the PRs for any dependent changes, preserving their discussions.
+
+To select a stack, pass the change ID of its head (the top change). `jj-stack` follows the
+head's parents back to trunk to find the rest. If you don't name a head, it uses your working
+copy when it has both a description and changes, or its parent otherwise. After editing a
+lower change, pass the head's ID to `jj-stack submit` so the update includes the changes above
+your edit.
 
 ## Everyday workflow
 
@@ -130,8 +99,9 @@ dependent changes.
 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` when the changes at the bottom are ready.
-6. After a queued or externally initiated merge finishes, run
+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>`.
 
 `view`, `submit`, `merge`, and `sync` accept a change ID when you need to select a stack other
@@ -140,19 +110,58 @@ than the one ending at the working copy.
 See the [user guide](https://www.serpentine.com/software/jj-stack/) for drafts, descriptions,
 merge queues, cleanup, and working with multiple stacks.
 
+## Optional setup
+
+### Invoke it as `jj stack`
+
+Add a command alias to your user configuration with `jj config edit --user`:
+
+```toml
+[aliases]
+stack = ["util", "exec", "--", "jj-stack"]
+```
+
+For tab completion of both `jj-stack` and `jj stack`, add the output of `jj-stack completion` to
+your shell startup file:
+
+```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.
+
+### Other installation options
+
+`pipx` provides another isolated installation:
+
+```bash
+pipx install jj-stack
+```
+
+You can also use `pip` inside an activated virtual environment:
+
+```bash
+python -m pip install jj-stack
+```
+
+To upgrade an installation made with `uv`, run `uv tool upgrade jj-stack`. If the command is
+not on your shell `PATH`, run `uv tool update-shell`.
+
 ## Learn more
 
-- [Mental model](https://www.serpentine.com/software/jj-stack/mental-model/)
-- [Quick start](https://www.serpentine.com/software/jj-stack/quick-start/)
-- [Everyday workflows](https://www.serpentine.com/software/jj-stack/guides/submit-and-update/)
+- [How jj-stack works](https://www.serpentine.com/software/jj-stack/mental-model/)
+- [Submit and update](https://www.serpentine.com/software/jj-stack/guides/submit-and-update/)
+- [Merge and sync](https://www.serpentine.com/software/jj-stack/guides/merge-and-sync/)
+- [Multiple stacks](https://www.serpentine.com/software/jj-stack/guides/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/)
-- [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/)
+- [Compare tools](https://www.serpentine.com/software/jj-stack/tool-comparison/)
+- [Automation](https://www.serpentine.com/software/jj-stack/reference/automation/)
 
-The built-in help is the canonical flag reference:
+For all flags and aliases, use the built-in help:
 
 ```bash
 jj-stack --help
@@ -160,39 +169,18 @@ 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
-GitHub PRs safely:
+Install the bundled skill to give coding agents instructions for working with `jj-stack`:
 
 ```bash
 gh skill install bos/jj-stack jj-stack
 ```
 
-See the [skill source](https://github.com/bos/jj-stack/blob/main/skills/jj-stack/SKILL.md). In
-my evaluations with Codex and Claude Code, agents with the `jj-stack` skill succeeded in 11/12
-scenarios versus 6/12 without it, with one critical error versus four, using 60% fewer failed
-command attempts and 18% fewer tool calls. (The critical error was due to Claude Haiku
-understanding a rule and ignoring it. I haven't figured out how to get smaller Claude models to
-behave better, and I don't personally use them.)
-
-## Performance
-
-Although `jj-stack` is written in Python, this does not significantly affect its speed.
-The real determinants of its performance are the GitHub API and the `jj` command.
+The [skill source](skills/jj-stack/SKILL.md) and [evaluation notes](evals/jj-stack-skill.md) are
+included in this repo.
 
-The GitHub API is *slow*; a single roundtrip takes many hundreds of milliseconds. `jj-stack`
-reduces its impact with:
-
-- GraphQL batch requests where possible
-- concurrent use of the GitHub REST API
-- periodic audits that its queries are minimal in extent
+## Development
 
-In pursuit of good performance, `jj-stack` also batches calls to `jj` and minimizes the amount
-of work those calls must do.
+With `uv`, `jj`, and `just` installed, run `just` to list the development workflows. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for setup and validation instructions.