README.md

@@ -171,16 +171,19 @@ local cache is reliable, and the UI is responsive on a five-year-old laptop.
 
 All work on quak is test-driven. No exceptions.
 
-1. Every change starts on a feature branch off `main`.
+1. Every change starts on a feature branch off `next`, and its pull request
+   targets `next`.
 2. The first commit on the branch is the test suite for what is being added or
    changed. Those tests must fail at that commit; the branch is red until the
    implementation lands.
 3. Subsequent commits add the implementation and any refactors needed to make
    the tests pass.
-4. A feature branch can only be merged into `main` when `make check` is green.
-   `main` is always green. CI runs `script/cibuild`, which builds the
-   `Dockerfile`: its `lint` and `test` phases, then the compile, so neither a
-   red branch nor one that does not compile can pass CI.
+4. A pull request can only be merged into `next` when `make check` is green.
+   Once it has passed review, the repository manager squash-merges it into
+   `next`. Only sneak merges `next` into `main`. `main` and `next` are always
+   green. CI runs `script/cibuild`, which builds the `Dockerfile`: its `lint`
+   and `test` phases, then the compile, so neither a red branch nor one that
+   does not compile can pass CI.
 5. Tests are the canonical API documentation for this library. Every test file
    is commented thoroughly enough that a reader who has never seen quak can
    learn how to use it from the tests alone. Comments explain why a behavior
@@ -198,7 +201,7 @@ All work on quak is test-driven. No exceptions.
    not the tests, and so not the full `make check`. This is deliberate so the
    TDD red-phase commit (failing tests, no implementation yet) can land. The
    `test` phase is part of the image build, which is what CI executes via
-   `script/cibuild`, so a red branch still cannot reach `main`.
+   `script/cibuild`, so a red branch still cannot reach `next`.
 
 ## Design
 
@@ -839,14 +842,15 @@ documents:
   `yarn.lock`. Never `git add -A`. Never force-push to main.
 
 - **The "Development workflow" section above.** All changes go on feature
-  branches. Tests are written first and committed in a failing state before the
-  implementation. Tests are the canonical API documentation and must be
-  commented thoroughly. `main` is always green.
+  branches off `next`, and every pull request targets `next`; only sneak merges
+  `next` into `main`. Tests are written first and committed in a failing state
+  before the implementation. Tests are the canonical API documentation and must
+  be commented thoroughly. `main` and `next` are always green.
 
 - **Required checks before every commit:** `make lint` must pass — that is
   eslint plus the prettier check, and it builds the `lint` phase of the
   `Dockerfile`, so it needs docker. The pre-commit hook enforces exactly that.
-  `make check` (which also runs the tests) must pass before merging to `main`.
+  `make check` (which also runs the tests) must pass before merging into `next`.
   `make fmt-check` is available for a host-side formatting check on its own, but
   it is not a separate requirement: `make lint` already covers it, and running
   both would check formatting twice. Never invoke eslint or prettier directly;

TODO.md

@@ -22,6 +22,11 @@ declares one.
 
 # Completed Steps
 
+- 2026-09-29: The README's "Development workflow" and "For LLMs" sections now
+  say work branches from `next`, every pull request targets `next`, the
+  repository manager squash-merges reviewed pull requests into `next`, and only
+  sneak merges `next` into `main` (issue 135).
+
 - 2026-09-29: Brought the README and this file in line with `next` after the
   milestone merge (issue 132). The Next Step says no implementation work is open
   and the cache design (issue 36) waits on sneak's review. README corrections: