@jesdi/skills 0.0.44 → 0.0.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jesdi/skills",
-  "version": "0.0.44",
+  "version": "0.0.46",
   "description": "jesdi's agent skills (content package consumed by @jesdi/skills-cli)",
   "license": "MIT",
   "repository": {

package/skills/implement-spec/ARCHITECTURE.md

@@ -21,7 +21,9 @@ A comment in the code is for a line that looks wrong or removable without it.
 | `driver_merge.py` | Merges by git plumbing, the locked-file check of a landing, the move of the PR ref |
 | `driver_gate.py` | One run of the gate command and its record |
 | `driver_slots.py` | The worktrees that tickets run in, and the `git` helper |
-| `driver_state.py` | `state.json` (the resume contract) and the lock of one driver per repository |
+| `driver_state.py` | `state.json` (the resume contract) and the kernel lock |
+| `driver_names.py` | The names of one run: its ticket branches, its recovery ref and its lock file |
+| `driver_legacy.py` | The take-over of a run that an older driver started; delete it when no such run is left |
 | `driver_decisions.py`, `driver_answers.py`, `driver_review_page.py` | Operator questions, their answers, the page that shows them |
 | `driver_tidy.py`, `driver_summary.py` | The history with one commit per ticket; `summary.md` |
 
@@ -89,15 +91,17 @@ and do not know about the run, except `driver_run.py`, which the three deciding
 - The gate runs only on a commit the driver is about to trust, and one green record settles that commit.
   A gate on a dirty tree, or one that leaves the tree changed or HEAD moved, is red.
 - The end of run rewrites the branch one time, before the first final review, and never after a review. A history
-  that origin has is never rewritten. `refs/implement/recovery` holds the tip before the rewrite.
+  that origin has is never rewritten. `refs/implement-spec/<key>/recovery` holds the tip before the rewrite.
 - A rewrite never changes a file: the driver compares trees (`driver_tidy.same_tree`) before it moves the branch.
 - The push sends the reviewed commit, not the branch name, with no force.
 
 ### Work is never dropped
 
 - A role that commits keeps its tree after a timeout or an interrupt; its rerun continues from it.
-- A read-only role (reviewer, correctness, final-reviewer, pr-writer) has no work to keep. When it changes its slot, the
-  driver restores the slot and runs the review one more time (`Run.read_only`).
+- A read-only role (reviewer, correctness, final-reviewer, pr-writer) has no work to keep. When it changes its slot or
+  the shared git config, the driver restores them and runs the review one more time (`Run.read_only`). The config is
+  a byte copy taken before the role (`driver_review.shared_config`): every worktree reads that one file, so a key a
+  role writes there, such as a `core.worktree` on a temp directory, breaks git in all of them.
 - A slot with uncommitted work of an interrupted or parked ticket is kept for that ticket (`driver_state.kept`).
 - A blocked ticket keeps its slot when the slot is not clean.
 
@@ -110,8 +114,11 @@ and do not know about the run, except `driver_run.py`, which the three deciding
   `finish_interrupted_move` completes it at the next start.
 - At a resume, git must confirm each recorded tip (`driver_state.verified`). A ticket that git contradicts goes
   back to `implement` from its test-writer commit.
-- The lock of one driver per repository is a kernel lock on a file in the git common directory. The kernel frees
-  it when the process ends, so it is never stale.
+- The lock of one driver per PR branch is a kernel lock on a file in the git common directory. The kernel frees
+  it when the process ends, so it is never stale. Every ref that a run writes has the PR branch in its name
+  as one escaped name component. `driver_names.Names` (`Run.names`) makes every name of a run, so runs on
+  different PR branches share no ref. `driver_legacy.resume` takes over a run that an older driver started, once,
+  after the lock and before any check reads a ref.
 
 ### Agents
 

package/skills/implement-spec/README.md

@@ -23,7 +23,9 @@ Before any agent starts, the driver checks these. Each failed check prints one l
 
 A run that stopped is continued with the same command. `state.json` is the only input of a resume.
 
-One driver runs in a repository at a time. The driver holds a kernel file lock on `implement-spec.lock` in the git common directory (`git rev-parse --git-common-dir`) for the whole run. Each worktree of the repository shares that directory, so a second driver in the same worktree or in another one ends with exit 3 and names the lock file. The file is not in a worktree, so `git status` never shows it. The lock ends with its process, so a driver that was killed leaves no lock behind. `--dry-run` takes no lock. A wrong call in a worktree that has no `.agent/implement/` takes no lock and makes no file; where an earlier run left that folder, the driver takes the lock first, then makes the checks.
+One driver runs on a PR branch at a time. The driver holds a kernel file lock on `implement-spec/<key>.lock` in the git common directory (`git rev-parse --git-common-dir`) for the whole run. `<key>` is the PR branch as one name component: `%` becomes `%25` and `/` becomes `%2F`, so `feat/x` gives `feat%2Fx`. Each worktree of the repository shares that directory, so a second driver on the same PR branch, in the same worktree or in another one, ends with exit 3 and names the lock file. Drivers on different PR branches run at the same time: each ticket branch is `ticket/<key>/<NN>` and the recovery ref is `refs/implement-spec/<key>/recovery`, so two runs share no ref. Git refs are a tree, and one component per PR branch keeps the refs of one run from being a folder of the refs of another. The file is not in a worktree, so `git status` never shows it. The lock ends with its process, so a driver that was killed leaves no lock behind. `--dry-run` takes no lock. A wrong call in a worktree that has no `.agent/implement/` takes no lock and makes no file; where an earlier run left that folder, the driver takes the lock first, then makes the checks.
+
+A driver before this change named the ticket branches `ticket/<NN>` and the recovery ref `refs/implement/recovery`. An older driver holds `implement-spec.lock` in the git common directory alone for its whole run. Each newer driver also holds that file, shared, for its whole run: newer drivers do not stop each other, but while an older driver runs in the repository, a newer one ends with exit 3 and names that lock, and while a newer one runs, no older driver starts. A run that the newer driver started has `schema` 2 in `state.json`. When the newer driver resumes a run with no `schema`, it renames each `ticket/<NN>` that holds the start commit of the run and the tip that the run recorded, and moves `refs/implement/recovery` when it holds the recovery point of the run. It writes one ledger sentence for each, and then `schema`. A ref that git cannot rename ends the run with exit 3 and git's error, and nothing is lost.
 
 ## Flags
 
@@ -56,7 +58,7 @@ Default timeouts in minutes: explorer 30, test-writer 30, implementer 90, review
 | 0 | Done: every ticket is merged and no question is open. Also the end of a valid `--dry-run`. In local mode without `--push`, nothing is pushed. |
 | 1 | A ticket is BLOCKED, or the end of run is BLOCKED. The other tickets ran as far as they could. |
 | 2 | Parked: a question of kind `locked-test` or `final-finding` is open. Exit 2 wins over exit 1. |
-| 3 | Invalid input or a failed precondition: a usage error, a ticket error, a model error, an uncommitted change, a slot that cannot be made, another driver that runs in the same repository. No agent starts. The one exception: a review page that cannot be written gives exit 3 at the end of a run, after agents ran. |
+| 3 | Invalid input or a failed precondition: a usage error, a ticket error, a model error, an uncommitted change, a slot that cannot be made, another driver that runs on the same PR branch. No agent starts. The one exception: a review page that cannot be written gives exit 3 at the end of a run, after agents ran. |
 | 4 | Stopped: the CLI of an agent failed two times and wrote no report (for example, the account cannot use the model). The driver starts no other agent and lets the running agents end. No ticket is BLOCKED by it: fix the CLI or the model entry, then run the same command again to resume. |
 | 130 | The operator interrupted the run. The driver stops each agent. The work stays in the slots for the next run. |
 
@@ -75,7 +77,7 @@ Everything is under `.agent/`, which is never committed.
 | Path | Content |
 |---|---|
 | `.agent/implement/state.json` | The resume contract: the run record and one record for each ticket (`driver_state.py`). |
-| `<git common directory>/implement-spec.lock` | An empty file, not in the worktree. The driver that runs holds a kernel file lock on it (`driver_state.py` `lock`). Do not remove it during a run. |
+| `<git common directory>/implement-spec/<key>.lock` | An empty file, not in the worktree. The driver that runs holds a kernel file lock on it (`driver_state.py` `lock`). Do not remove it during a run. |
 | `.agent/implement/ledger.md` | One plain sentence for each event. Only the driver writes it, and it reads no fact from it. |
 | `.agent/implement/summary.md` | The result in sentences, and the measurement table: gates, agents, wall time, fix rounds, human stops, cost. |
 | `.agent/implement/decisions.json` | The open questions and their `revision`. Written only after a stop. |
@@ -88,7 +90,8 @@ Everything is under `.agent/`, which is never committed.
 | `.agent/implement-review.html` | The page with the open questions. |
 | `.agent/implement-answers.json` | The answers: `{"v": 1, "stage": "implement", "submitted": …, "revision": …, "answers": {…}}`. |
 | `.agent/worktrees/slot-K/` | Slots 2..N. Slot 1 is the PR worktree. |
-| `refs/implement/recovery` | A git ref: the PR tip before the tidy. |
+| `refs/implement-spec/<key>/recovery` | A git ref: the PR tip before the tidy. |
+| `ticket/<key>/<NN>` | The branch of one ticket. The driver deletes it when the ticket is merged. |
 
 ## Roles of one ticket
 
@@ -97,7 +100,7 @@ A ticket is ready when each ticket in its **Blocked by** line is merged and no r
 1. **test-writer** (`prompts/test-writer.md`). It writes one black-box test for each criterion through the Seam and commits them red. Those files are locked. A ticket with Seam `none — refactor` has no test-writer.
 2. **implementer** (`prompts/implementer.md`). It starts from that commit and makes the locked tests green. It makes the gate (`--gate`) green on its final commit before it reports DONE or DONE_WITH_CONCERNS.
 3. **Gate.** The driver runs `--gate` on the ticket tip.
-4. **Review.** The driver compares each locked file of the ticket with the test-writer commit. A file that differs is a critical finding `locked file changed: <path>`. A locked file of a merged ticket that the ticket changed since its merge base with the PR branch is a critical `fixture` finding `the ticket changed the locked file of a merged ticket: <path>`, so it goes to a correction (see **Before a correction**). Then the **reviewer** (`prompts/reviewer.md`) runs, and for a ticket with a **Risk** line the **correctness** pass (`prompts/correctness.md`) runs at the same time in the same slot.
+4. **Review.** The driver compares each locked file of the ticket with the test-writer commit. A file that differs is a critical finding `locked file changed: <path>`. A locked file of a merged ticket that the ticket changed since its merge base with the PR branch is a critical `fixture` finding `the ticket changed the locked file of a merged ticket: <path>`, so it goes to a correction (see **Before a correction**). Then the **reviewer** (`prompts/reviewer.md`) runs, and for a ticket with a **Risk** line the **correctness** pass (`prompts/correctness.md`) runs at the same time in the same slot. A read-only role (reviewer, correctness, final-reviewer, pr-writer) leaves its slot and the git config as it found them: all worktrees share one config, and one key written there, such as a `core.worktree` on a temp directory, breaks git in each of them. To run a check off the slot, a reviewer reads the driver's gate record or makes its own `git worktree add --detach` copy and removes it. After read-only roles, the driver checks the slot and the shared config (`git rev-parse --git-common-dir`, then `config`) against what they were before. When one of them changed, the driver restores it, writes `a read-only role broke its rule: ...` to the ledger, and runs the review one more time; a second change blocks the ticket.
 5. **Merge.** The driver merges the reviewed tip into the PR branch with git plumbing, then deletes the ticket branch. A conflict goes to the **conflict** agent (`prompts/conflict.md`) once. Its resolution may change no locked file of the ticket. A second conflict blocks the ticket.
    **The landing check.** Merges are serial. Before the PR branch moves, the driver compares the tree that is about to land (the ticket tip of a fast-forward, or the merge commit) with the PR tip: each locked file of each merged ticket must be the same tree entry in both: the same blob with the same mode, so a file that became a symlink is a difference. A file that only one of them has is a difference. A file that the landing ticket lists in its own `locked` is not checked: the test-writer of a later ticket can add a test to a file that an earlier ticket locked, and must list that file. A test-writer report that changes such a file and does not list it is rejected, with the usual one rerun. The review finds such a change first; the landing check catches a change that no review saw, for example of a ticket that merged after the last review. A difference refuses the landing: the ticket is BLOCKED with `locked file changed: <path>` in the ledger, the PR branch does not move, and no fix round runs. The PR branch moves only from the tip that the check read; when another hand moved the branch in between, the driver makes the merge, the check and the gate again, one time. Only that case starts the landing again: a refused landing and a red merge gate block the ticket. The second try runs no conflict agent, so a conflict there blocks the ticket, and so does a branch that moved again.
    **Before a correction.** A test-writer that corrects locked tests (after `overrule-test`, or for a `fixture` finding or a `test` finding on a locked file) starts from the locked versions: the driver puts back each locked file of the ticket and each locked file of a merged ticket that the ticket changed, commits them in one commit of its own, and the ledger names each file. A file of a merged ticket goes back to the version of the PR branch. The commit keeps the tree of the next fixer and of the gate clean, whatever files the correction commits. The correction's prompt names the restored files: when a test in one of them fails only because the ticket changed an interface that the test uses, the correction updates the file to the new interface, keeps what each test asserts, and lists the file in `locked`.
@@ -131,7 +134,7 @@ A red gate on the commit of the implementer or of a fixer is a critical finding
 
 The end of run starts only when every ticket is merged and every slot is idle. Its agents work in slot 1.
 
-1. **Tidy.** The driver saves the PR tip in `refs/implement/recovery`. It then makes one commit for each ticket, in merge order, named `feat(NN): <title>`. Each commit holds the tests, the implementation and the fixes of its ticket. The tree of the new tip must equal the tree of the old tip, or the branch stays as it was.
+1. **Tidy.** The driver saves the PR tip in `refs/implement-spec/<key>/recovery`. It then makes one commit for each ticket, in merge order, named `feat(NN): <title>`. Each commit holds the tests, the implementation and the fixes of its ticket. The tree of the new tip must equal the tree of the old tip, or the branch stays as it was.
 2. **Rebase** onto the fetched tip of the default branch of `origin`. A conflict goes to the conflict agent (`prompts/rebase-conflict.md`) once, and the rebased tip is gated.
 3. **Gate**, then the **final-reviewer** (`prompts/final-reviewer.md`) on the whole range, with the method of the `review-diff` skill. It gets the minor findings of the tickets and the rulings of the operator.
 4. **Fix batch.** Critical and important findings go to one fixer (`prompts/final-fixer.md`). The driver names each of its commits `fix(NN): …` from the ticket in the report. Then the gate, then one scoped review of those commits.

package/skills/implement-spec/driver.py

@@ -14,8 +14,10 @@ from __future__ import annotations
 import argparse
 import json
 import os
+import re
 import sys
 from concurrent.futures import FIRST_COMPLETED, ThreadPoolExecutor, wait
+from contextlib import ExitStack
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -24,7 +26,9 @@ import driver_answers
 import driver_decisions
 import driver_final
 import driver_fixloop
+import driver_gate
 import driver_graph
+import driver_legacy
 import driver_merge
 import driver_review
 import driver_review_page
@@ -32,6 +36,7 @@ import driver_slots
 import driver_state
 import driver_summary
 import driver_tickets
+from driver_names import Names
 from driver_run import FINAL, OUT, Blocked, Halted, Run, during, ledger
 from driver_slots import git
 from driver_tickets import Ticket
@@ -59,7 +64,7 @@ def _roles_left(ticket: Ticket, phase: str, only: str | None) -> list[str]:
 
 def _check_out_ticket(ticket: Ticket, slot_number: int, entry: dict, run: Run) -> str:
     """Put the ticket branch in the slot and return the commit its next role starts from."""
-    slot, branch = driver_slots.path(slot_number), f"ticket/{ticket.number}"
+    slot, branch = driver_slots.path(slot_number), run.names.ticket(ticket.number)
     if run.kept.get(ticket.number) == slot_number:
         # The slot holds the uncommitted work of an interrupted role: the branch and the tree stay as they are.
         return entry["tip"] or git(slot, "merge-base", "HEAD", run.tip()).stdout.strip()
@@ -80,7 +85,8 @@ def _prompt_values(ticket: Ticket, slot: str, run: Run) -> dict[str, str]:
     """The pointers every prompt of the ticket gets. An agent works in its slot, so paths are relative to it."""
     folder = OUT / ticket.number
     return {"spec": os.path.relpath(run.args.spec, slot), "seam": ticket.seam, "pr_branch": run.pr,
-            "branch": f"ticket/{ticket.number}", "ticket": os.path.relpath(Path(run.args.tickets) / ticket.file, slot),
+            "branch": run.names.ticket(ticket.number),
+            "ticket": os.path.relpath(Path(run.args.tickets) / ticket.file, slot),
             "correctness": str(driver_review.CORRECTNESS), "gate": run.args.gate,
             "blocked_report": os.path.relpath(_blocked_report(ticket.number, run), slot),
             "writer_report": os.path.relpath(folder / "test-writer-0.json", slot)}
@@ -104,7 +110,7 @@ def _run_roles(ticket: Ticket, slot_number: int, run: Run) -> None:
     values = {**_prompt_values(ticket, slot, run), "locked": " ".join(entry["locked"])}
     for role in roles:
         run.state.ticket(number, phase=DURING.get(role, "review"))
-        values["start_sha"] = start
+        values.update(start_sha=start, gate_record=os.path.relpath(driver_gate.record_path(OUT / number, start), slot))
         # A test-writer on a ticket that has locked tests is the correction after a ruling.
         check = {"correction": role == "test-writer" and bool(entry["test_writer_sha"])}
         if check["correction"] and (restored := run.restore_locked_files(number, slot)):
@@ -152,7 +158,7 @@ def _resolve_conflict(ticket: Ticket, slot: str, run: Run, tip: str, files: list
 
 def _merge_commit(ticket: Ticket, slot: str, run: Run, tip: str, may_resolve: bool) -> _Landing:
     """Merge the ticket tip with the PR tip into a commit that no ref holds yet."""
-    message = f"Merge ticket/{ticket.number} into {run.pr}"
+    message = f"Merge {run.names.ticket(ticket.number)} into {run.pr}"
     pr_tip = run.tip()
     commit, error = driver_merge.commit(pr_tip, tip, message)
     if not error:
@@ -171,7 +177,8 @@ def _merge_commit(ticket: Ticket, slot: str, run: Run, tip: str, may_resolve: bo
 def _checked_landing(ticket: Ticket, slot: str, run: Run, may_resolve: bool) -> _Landing:
     """The commit to land, with the locked-file check passed and the gate green. Call it under the merge lock."""
     number = ticket.number
-    git(slot, "checkout", "-q", f"ticket/{number}")  # an earlier try left the slot on its merge commit
+    # An earlier try left the slot on its merge commit.
+    git(slot, "checkout", "-q", run.names.ticket(number))
     tip = run.state.ticket(number, phase="merge")["tip"]
     landing = _merge_commit(ticket, slot, run, tip, may_resolve)
     refusal = driver_merge.refused(run.state.read()["tickets"], number, landing.pr_tip, landing.commit)
@@ -208,7 +215,7 @@ def _record_landing(state: dict, number: str, pr_tip: str) -> None:
 
 def _merge(ticket: Ticket, slot: str, run: Run) -> None:
     """Land the reviewed ticket tip on the PR branch, then delete the ticket branch."""
-    number, branch = ticket.number, f"ticket/{ticket.number}"
+    number, branch = ticket.number, run.names.ticket(ticket.number)
     # The merge gate and the conflict agent run under the lock: the commit the gate saw is the one that lands.
     with run.merging, during("the merge"):
         landing = _land(ticket, slot, run)
@@ -348,27 +355,16 @@ def _work(tickets: list[Ticket], slots: int, run: Run) -> tuple[bool, list[str]]
 
 # ---------------------------------------------------------------- before the first agent: resume and answers
 
-def _pr_branch(state: driver_state.State) -> tuple[str, str]:
-    """(the PR branch, "") or ("", why the run cannot start)."""
-    here = git(".", "symbolic-ref", "-q", "--short", "HEAD").stdout.strip()
-    # An interrupted run leaves slot 1 on a ticket branch or detached, so the record names the PR branch.
-    pr = state.read()["run"]["pr_branch"] if state.path.exists() else here
-    if not pr:
-        return "", "the PR worktree is on a detached HEAD: check out the PR branch"
-    if here not in ("", pr) and not here.startswith("ticket/"):
-        return "", f"{state.path} records a run on {pr}, not on {here}: check out {pr}, or remove {OUT}"
-    return pr, ""
-
-
 def _resume_error(number: str, state: driver_state.State) -> str:
     """Check the record of one ticket against git. A ticket that git contradicts goes back to its last verified
     phase; "" or the error that stops the run."""
-    entry, branch = state.read()["tickets"][number], f"ticket/{number}"
+    run, entry = state.read()["run"], state.read()["tickets"][number]
+    branch = Names(run["pr_branch"]).ticket(number)
     if entry["phase"] not in driver_state.PHASES:
         return f"{state.path}: ticket {number} has the unknown phase {entry['phase']!r}"
-    if entry["phase"] == "pending" and git(".", "rev-parse", "-q", "--verify", f"refs/heads/{branch}").returncode == 0:
+    if entry["phase"] == "pending" and driver_slots.branch_exists(branch):
         return f"branch {branch} exists and {state.path} does not record it: delete or rename the branch"
-    fields, why = driver_state.verified(entry, branch, state.read()["run"]["pr_branch"])
+    fields, why = driver_state.verified(entry, branch, run["pr_branch"])
     if fields:
         state.ticket(number, **fields)
         start = fields["tip"][:7] if fields["tip"] else "the PR tip"
@@ -376,15 +372,12 @@ def _resume_error(number: str, state: driver_state.State) -> str:
     return ""
 
 
-def _resume(tickets: list[Ticket], state: driver_state.State, slots: int, args, kept: dict) -> tuple[str, list[str]]:
-    """Start or resume state.json and make the slots: (the PR branch, the errors that stop the run)."""
-    pr, error = _pr_branch(state)
-    if error:
-        return "", [error]
+def _resume(tickets: list[Ticket], state: driver_state.State, pr: str, slots: int, args, kept: dict) -> list[str]:
+    """Start or resume state.json on the PR branch `pr` and make the slots: the errors that stop the run."""
     state.start(pr, [ticket.number for ticket in tickets])
     driver_final.finish_interrupted_move(state, pr)
     errors = [error for error in (_resume_error(ticket.number, state) for ticket in tickets) if error]
-    return pr, errors or driver_slots.setup(slots, args.prepare, set(kept.values()))
+    return errors or driver_slots.setup(slots, args.prepare, set(kept.values()))
 
 
 def _publish_questions(run: dict) -> str:
@@ -474,10 +467,10 @@ def _exit_code(final: dict, args, end_blocked: bool) -> int:
     return code
 
 
-def _run(tickets: list[Ticket], models: dict[str, list[str]], args, kept: dict[str, int]) -> int:
+def _run(tickets: list[Ticket], models: dict[str, list[str]], args, kept: dict[str, int], pr: str) -> int:
     state = driver_state.State(STATE)
     slots = 1 if args.only else min(args.parallel, len(tickets))
-    pr, errors = _resume(tickets, state, slots, args, kept)
+    errors = _resume(tickets, state, pr, slots, args, kept)
     errors = errors or _apply_answers(state, args)
     for error in errors:
         print(error)
@@ -564,7 +557,7 @@ def _validated(args: argparse.Namespace) -> tuple[list[Ticket], dict[str, list[s
         errors.append("--spec is required: the spec file the prompts point at")
     if args.parallel < 1:
         errors.append("--parallel must be 1 or more")
-    kept = driver_state.kept(json.loads(STATE.read_text())) if STATE.exists() else {}
+    kept = driver_state.kept(driver_state.State(STATE).read()) if STATE.exists() else {}
     errors += _worktree_errors(1 in kept.values())
     models, model_errors = driver_agents.load_models(args.models)
     tickets, ticket_errors = driver_tickets.parse(args.tickets)
@@ -579,16 +572,61 @@ def _print_width(tickets: list[Ticket]) -> None:
     print(f"max frontier width: {driver_tickets.max_frontier_width(tickets)}")
 
 
-def _lock_file(args: argparse.Namespace) -> Path | None:
-    """The file one driver per repository locks: in the git common directory, which every worktree shares and
-    `git status` never reports. None, with each error printed, when the call is not valid."""
+def _run_branch() -> str:
+    """The PR branch the run in this worktree is on: the one state.json records, else the one checked out."""
+    # HEAD first: a driver writes state.json before it moves HEAD, so a HEAD that a run moved has a state.json.
+    here = driver_slots.on_branch(".")
+    return driver_state.State(STATE).read()["run"]["pr_branch"] if STATE.exists() else here
+
+
+def _start_errors(pr: str) -> list[str]:
+    """Under the lock of `pr`, before any check reads a ref: the errors that stop the run, or [].
+
+    The run of this worktree must still be on `pr`, a run that an older driver started gets its new names first,
+    and slot 1 must be on `pr` or where an interrupted run left it: on one of its ticket branches, or detached."""
+    if _run_branch() != pr:
+        return [f"the run in this worktree left {pr} while the driver took its lock: run the driver again"]
+    if errors := driver_legacy.resume(driver_state.State(STATE)):
+        return errors
+    here = driver_slots.on_branch(".")
+    # An older driver named its ticket branches `ticket/NN`, and a branch that the resume does not rename stays so.
+    if here in ("", pr) or here.startswith(Names(pr).ticket("")) or re.fullmatch(r"ticket/\d+", here):
+        return []
+    return [f"{STATE} records a run on {pr}, not on {here}: check out {pr}, or remove {OUT}"]
+
+
+def _common_dir_and_branch(args: argparse.Namespace) -> tuple[Path, str] | None:
+    """(the git common directory, which every worktree shares and `git status` never reports, and the PR branch of
+    the run): what names the lock. None, with each error printed, when the call is not valid."""
     common = git(".", "rev-parse", "--git-common-dir")
     # A first call is validated before the lock, so a wrong call makes no file. After an earlier run the lock comes
     # first: the driver that holds it changes what the validation reads.
     first_call = common.returncode or not OUT.exists()
     if first_call and not _validated(args):
         return None
-    return Path(common.stdout.strip()).resolve() / "implement-spec.lock"
+    if not (pr := _run_branch()):
+        print("the PR worktree is on a detached HEAD: check out the PR branch")
+        return None
+    if pr.startswith("ticket/"):  # a slot of another run: its driver owns the worktree and the branch
+        print(f"the PR worktree is on the ticket branch {pr} of a run: check out the PR branch")
+        return None
+    return Path(common.stdout.strip()).resolve(), pr
+
+
+def _hold(common: Path, pr: str) -> tuple[ExitStack | None, str]:
+    """Take the locks of a run on `pr`: (the stack that holds them until it closes, "") or (None, why another
+    driver stops this one)."""
+    with ExitStack() as stack:
+        lock_file = Names(pr).lock_file(common)
+        if not (held := driver_state.lock(lock_file)):
+            return None, (f"another driver runs on {pr}: it holds the lock {lock_file}. Wait until it ends, then "
+                          "run the driver again.")
+        stack.enter_context(held)
+        older, error = driver_legacy.lock(common)
+        if not older:
+            return None, error
+        stack.enter_context(older)
+        return stack.pop_all(), ""
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -597,15 +635,19 @@ def main(argv: list[str] | None = None) -> int:
         if valid := _validated(args):
             _print_width(valid[0])
         return 0 if valid else 3
-    if not (lock_file := _lock_file(args)):
+    if not (locking := _common_dir_and_branch(args)):
         return 3
-    held = driver_state.lock(lock_file)
+    common, pr = locking
+    held, error = _hold(common, pr)
     if not held:
-        print(f"implement-spec: another driver runs in this repository: it holds the lock {lock_file}. Wait until it "
-              "ends, then run the driver again.")
+        print(f"implement-spec: {error}")
         return 3
     with held:
-        # Only what is read under the lock is trusted: no other driver changes state.json, the slots or the refs.
+        # Only what is read under the lock is trusted: no other driver changes state.json, the slots, the PR branch
+        # or its ticket branches. Drivers on other PR branches touch none of them.
+        if errors := _start_errors(pr):
+            print("".join(f"implement-spec: {error}\n" for error in errors), end="")
+            return 3
         if not (valid := _validated(args)):
             return 3
         tickets, models, kept = valid
@@ -614,7 +656,7 @@ def main(argv: list[str] | None = None) -> int:
             print("".join(error + "\n" for error in errors), end="")
             return 3
         _print_width(tickets)
-        return _run(tickets, models, args, kept)
+        return _run(tickets, models, args, kept, pr)
 
 
 if __name__ == "__main__":

package/skills/implement-spec/driver_final.py

@@ -4,7 +4,7 @@ commits with a scoped review, then stop before the push, or push and open the PR
 
 `run.final` of state.json is the resume contract (`driver_state._final` makes it with every key):
     skipped    why the end-of-run work did not start
-    recovery   the PR tip before the rewrite; the ref RECOVERY holds it. None when origin had the history already
+    recovery   the PR tip before the rewrite; Run.names names its ref. None when origin had the history already
     tidied     the tip the rewrite made, or the tip as the tickets left it when the history is kept
     base, onto the default branch of origin and its tip under the history; with no origin: "" and the start of the run
     commits    {ticket: its commit}
@@ -26,6 +26,7 @@ from pathlib import Path
 
 import driver_agents
 import driver_decisions
+import driver_gate
 import driver_merge
 import driver_review
 import driver_tidy
@@ -34,7 +35,6 @@ from driver_slots import git, head
 from driver_state import State
 from driver_tickets import Ticket
 
-RECOVERY = "refs/implement/recovery"
 KIND = "final-finding"
 ROUNDS = 2  # the full review and the scoped one after the fix batch
 # The final review runs through the review-diff skill, which is installed next to this one.
@@ -170,7 +170,8 @@ def _resolve_rebase_conflict(run: Run, env: dict, base: str, onto: str) -> None:
         raise Blocked(f"the conflict agent: {error}" if error else
                       f"the rebase onto {base} conflicts a second time, in {', '.join(again)}")
     # The resolution may not change a locked test: each one is as the recovery point has it.
-    changed = driver_review.locked_changes(".", git(".", "rev-parse", RECOVERY).stdout.strip(), _locked_files(run))
+    before = git(".", "rev-parse", run.names.recovery).stdout.strip()
+    changed = driver_review.locked_changes(".", before, _locked_files(run))
     if error := error or "; ".join(finding["title"] for finding in changed):
         raise Blocked(f"the conflict agent: {error}")
     ledger(f"Rebase: the conflict agent resolved the conflict with {base} in {', '.join(files)} at {head('.')[:7]}.")
@@ -249,7 +250,7 @@ def _rewrite_once(run: Run, tickets: list[Ticket]) -> None:
     final = run.state.read()["run"]["final"]
     if final["tidied"]:
         if not driver_merge.ancestor(final["tidied"], run.tip()):
-            raise Blocked(f"{run.pr} does not hold the tidied tip {final['tidied'][:7]}; {RECOVERY} holds the "
+            raise Blocked(f"{run.pr} does not hold the tidied tip {final['tidied'][:7]}; {run.names.recovery} holds the "
                           "history before the tidy")
         return
     base, onto = _base(run)
@@ -258,9 +259,9 @@ def _rewrite_once(run: Run, tickets: list[Ticket]) -> None:
         _keep_published_history(run, old, base, onto)
         return
     tree = git(".", "rev-parse", f"{old}^{{tree}}").stdout.strip()
-    git(".", "update-ref", "-m", "implement-spec: recovery point", RECOVERY, old)
+    git(".", "update-ref", "-m", "implement-spec: recovery point", run.names.recovery, old)
     ledger(f"Recovery point: {run.pr} was at {old} with the tree {tree} before the rebase and the tidy; "
-           f"{RECOVERY} holds that commit.")
+           f"{run.names.recovery} holds that commit.")
     git(".", "checkout", "-q", "--detach")  # slot 1 is off the branch while the history is made
     try:
         commits = _new_history(run, tickets, old, base, onto)
@@ -325,7 +326,7 @@ def _review(run: Run, final: dict, tip: str) -> None:
     """One round of the final review on `tip`: the full review, or after it the scoped one."""
     done, folder = final["round"], OUT / FINAL
     values = {**_prompt_values(run), "start_sha": tip, "range": f"{final['reviewed'] or final['onto']}..{tip}",
-              "gate": str(folder / f"gate-{tip[:7]}.log"), "review_diff": str(REVIEW_DIFF),
+              "gate": str(driver_gate.record_path(folder, tip)), "review_diff": str(REVIEW_DIFF),
               "ledger": str(OUT / "ledger.md"), "minors": _minor_findings(), "reviewed": str(final["reviewed"]),
               "rulings": "\n".join(driver_decisions.rulings(run.state.read()["run"]["questions"])),
               "findings": str(folder / f"findings-{done - 1}.json")}
@@ -441,7 +442,7 @@ def _write_body(run: Run, final: dict, tickets: list[Ticket]) -> Path:
         raise Blocked("the pr skill is missing: the PR body follows it; install it with "
                       "`npx skills add mattpocock/skills --skill pr`")
     values = {**_prompt_values(run), "start_sha": tip, "range": f"{final['onto']}..{tip}",
-              "gate": str(OUT / FINAL / f"gate-{tip[:7]}.log"), "pr_skill": str(method), "facts": facts}
+              "gate": str(driver_gate.record_path(OUT / FINAL, tip)), "pr_skill": str(method), "facts": facts}
     with during("the PR body"):
         report = run.read_only(FINAL, ".", run.pr, tip, lambda: run.agent("pr-writer", FINAL, ".", values))
     body.write_text(f"{report['body'].strip()}\n\n{facts}")

package/skills/implement-spec/driver_fixloop.py

@@ -11,6 +11,7 @@ from concurrent.futures import ThreadPoolExecutor
 from dataclasses import dataclass, field
 
 import driver_agents
+import driver_gate
 import driver_merge
 import driver_review
 import driver_slots
@@ -39,9 +40,11 @@ class Job:
         """The values of a prompt; `review` is the round whose findings the agent reads."""
         entry = self.run.state.read()["tickets"][self.ticket.number]
         findings = os.path.relpath(OUT / self.ticket.number / f"findings-{review}.json", self.slot)
+        gate = os.path.relpath(driver_gate.record_path(OUT / self.ticket.number, self.tip), self.slot)
         return {**self.values, "start_sha": self.tip, "from_sha": self.previous, "round": str(self.round),
                 "locked": " ".join(entry["locked"]), "test_writer_sha": str(entry["test_writer_sha"] or ""),
-                "findings": findings, "proofs": " ".join(f"{file}:{line}" for file, line in sorted(self.again))}
+                "findings": findings, "gate_record": gate,
+                "proofs": " ".join(f"{file}:{line}" for file, line in sorted(self.again))}
 
 
 def entry(models: dict[str, list[str]], round: int) -> str:

package/skills/implement-spec/driver_gate.py

@@ -25,12 +25,16 @@ def _after(slot: str, commit: str) -> str:
     return "not clean\n" + "".join(f"    {line}\n" for line in status.splitlines()).rstrip("\n") if status else "clean"
 
 
+def record_path(folder: Path, commit: str) -> Path:
+    return folder / f"gate-{commit[:7]}.log"
+
+
 def run(command: str, slot: str, folder: Path, pr_branch: str) -> tuple[bool, Path]:
     """Gate the HEAD of `slot`. Returns (green, the record)."""
     commit = head(slot)
     status = git(slot, "status", "--short").stdout
     folder.mkdir(parents=True, exist_ok=True)
-    record = folder / f"gate-{commit[:7]}.log"
+    record = record_path(folder, commit)
     # The cache of compiled Python stays out of the slot, so the gate leaves the tree clean.
     env = dict(os.environ, IMPLEMENT_SPEC_BASE=pr_branch, PYTHONPYCACHEPREFIX=str(folder.parent.resolve() / "pycache"))
     with record.open("w") as out:

package/skills/implement-spec/driver_legacy.py

@@ -0,0 +1,92 @@
+"""A run that an older driver started: one lock per repository, ticket branches `ticket/NN` and the recovery ref
+`refs/implement/recovery`.
+
+Every run of a newer driver holds `lock` (driver._hold), so a newer and an older driver never run in one repository
+at the same time. The driver calls `resume` once, after the locks and before any check reads a ref: a run with no
+`schema` in state.json gets the new names of its refs.
+ponytail: delete this module, tests/test_legacy.py and its one line in driver._hold and in driver._start_errors
+once no older driver is left.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import IO
+
+import driver_slots
+import driver_state
+from driver_names import Names
+from driver_run import ledger
+from driver_slots import git
+
+LOCK = "implement-spec.lock"  # in the git common directory: an older driver holds it for its whole run
+RECOVERY = "refs/implement/recovery"
+
+
+def _checked_out_elsewhere(branch: str) -> bool:
+    """True when a worktree that is not this one nor one of its slots has `branch` checked out."""
+    here = Path.cwd().resolve()
+    for block in git(".", "worktree", "list", "--porcelain").stdout.split("\n\n"):
+        lines = block.splitlines()
+        if lines and f"branch refs/heads/{branch}" in lines:
+            where = Path(lines[0].removeprefix("worktree ")).resolve()
+            return where != here and here / ".agent" / "worktrees" not in where.parents
+    return False
+
+
+def _this_runs(entry: dict, legacy: str, start: str) -> bool:
+    """A `ticket/NN` is this run's when it holds the commit the run started from and the tip the run recorded, and
+    no worktree outside this run has it checked out."""
+    if not driver_slots.ancestor(start, legacy) or _checked_out_elsewhere(legacy):
+        return False
+    return not entry["tip"] or driver_slots.ancestor(entry["tip"], legacy)
+
+
+def _branch(entry: dict, number: str, names: Names, start: str) -> str:
+    """Rename one `ticket/NN` of this run: "" or the error."""
+    legacy, new = f"ticket/{number}", names.ticket(number)
+    if entry["phase"] in ("pending", "merged") or not driver_slots.branch_exists(legacy):
+        return ""
+    if driver_slots.branch_exists(new) or not _this_runs(entry, legacy, start):
+        return ""
+    moved = git(".", "branch", "-m", legacy, new)  # git also moves the HEAD of a slot that has the branch
+    if moved.returncode:
+        return f"cannot rename the branch {legacy} of an older driver to {new}: {moved.stderr.strip()}"
+    ledger(f"Ticket {number}: renamed the branch {legacy} of an older driver to {new}.")
+    return ""
+
+
+def _recovery(run: dict, names: Names) -> str:
+    """Move `refs/implement/recovery` to the name of this run when it holds the recovery point that this run
+    recorded: "" or the error."""
+    recorded = run.get("final", {}).get("recovery")
+    if not recorded or git(".", "rev-parse", "-q", "--verify", RECOVERY).stdout.strip() != recorded:
+        return ""
+    # The old ref goes only when the new one holds the commit: a move that stopped half way is finished next time.
+    made = git(".", "update-ref", "-m", "implement-spec: rename", names.recovery, recorded)
+    if made.returncode:
+        return f"cannot move {RECOVERY} of an older driver to {names.recovery}: {made.stderr.strip()}"
+    git(".", "update-ref", "-d", RECOVERY, recorded)
+    ledger(f"Recovery point: moved {RECOVERY} of an older driver to {names.recovery}.")
+    return ""
+
+
+def lock(common_dir: Path) -> tuple[IO | None, str]:
+    """The lock of an older driver, shared: (the held file, "") or (None, the error) while an older driver runs in
+    the repository. Newer drivers hold it together, so they do not stop each other; an older driver holds it alone,
+    so it never runs beside one."""
+    if held := driver_state.lock(common_dir / LOCK, shared=True):
+        return held, ""
+    return None, (f"a driver of an older version runs in this repository: it holds the lock {common_dir / LOCK}. "
+                  "Wait until it ends, then run the driver again.")
+
+
+def resume(state: driver_state.State) -> list[str]:
+    """Give each ref of a run that an older driver started its new name, then mark the run: the errors, or []."""
+    if not state.path.exists() or state.read()["run"].get("schema", 1) >= driver_state.SCHEMA:
+        return []
+    run, names = state.read()["run"], Names(state.read()["run"]["pr_branch"])
+    moves = [_branch(entry, number, names, run["start"]) for number, entry in state.read()["tickets"].items()]
+    if errors := [error for error in [*moves, _recovery(run, names)] if error]:
+        return errors
+    state.update(lambda changed: changed["run"].update(schema=driver_state.SCHEMA))
+    return []

package/skills/implement-spec/driver_merge.py

@@ -8,11 +8,7 @@ from __future__ import annotations
 import os
 import subprocess
 
-from driver_slots import git, names
-
-
-def ancestor(commit: str, of: str) -> bool:
-    return git(".", "merge-base", "--is-ancestor", commit, of).returncode == 0
+from driver_slots import ancestor, git, names
 
 
 def identity(tip: str, slot: str = ".") -> dict[str, str]:

package/skills/implement-spec/driver_names.py

@@ -0,0 +1,32 @@
+"""The names of one run: its ticket branches, its recovery ref and its lock file.
+
+Each name carries the PR branch as one name component, so runs on other PR branches share none of them. One
+component, because git refs are a tree: `ticket/feat/01` and `ticket/feat/01/02` cannot both exist. `%` and `/` are
+escaped, so two PR branches never give the same component: `feat/x` gives `feat%2Fx`.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Names:
+    pr: str  # the PR branch
+
+    @property
+    def _key(self) -> str:
+        return self.pr.replace("%", "%25").replace("/", "%2F")
+
+    def ticket(self, number: str) -> str:
+        """The branch of ticket `number`."""
+        return f"ticket/{self._key}/{number}"
+
+    @property
+    def recovery(self) -> str:
+        """The ref that holds the PR tip before the tidy."""
+        return f"refs/implement-spec/{self._key}/recovery"
+
+    def lock_file(self, common_dir: Path) -> Path:
+        """The file one driver per PR branch locks, in the git common directory that every worktree shares."""
+        return common_dir / "implement-spec" / f"{self._key}.lock"