@jesdi/skills 0.0.43 → 0.0.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jesdi/skills",
-  "version": "0.0.43",
+  "version": "0.0.45",
   "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` |
 
@@ -68,8 +70,15 @@ and do not know about the run, except `driver_run.py`, which the three deciding
   is not clean, so a restore left in the tree would turn the next gate red and use a fix round. The correction's
   prompt names the restored files (`prompts/restored.md`): this is the one path for a change of an earlier ticket's
   locked test that a later ticket's interface needs.
-- The locked files of merged tickets are checked when a ticket lands (`driver_merge.refused`): the tree that lands
-  must have each of them as the PR tip has it. A ticket's test-writer may change one only when it lists it.
+- The driver, not the correction, decides whether a restored file fails with the ticket's code: in the fix loop it
+  gates the restore commit, whose parent has a green gate. A red gate goes to the correction as evidence
+  (`prompts/restored-red.md`), and a DONE correction must then list a restored file. An agent's judgement of
+  "this test does not fail" missed a red file and led to a refused merge (issue #90). After `overrule-test` the
+  parent has no green gate, so a red gate proves nothing there: the next review catches the file instead.
+- The locked files of merged tickets are checked before each review (`driver_review.merged_changes`): a change is a
+  `fixture` finding, so it goes to a correction, where the restore and its gate decide. They are checked again when
+  a ticket lands (`driver_merge.refused`): the tree that lands must have each of them as the PR tip has it. A
+  ticket's test-writer may change one only when it lists it.
 - A conflict resolution, of a merge or of the rebase, may not change a locked file.
 
 ### The PR branch
@@ -82,7 +91,7 @@ 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.
 
@@ -103,8 +112,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,10 +100,11 @@ 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>`. 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.
 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. 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.
+   **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`.
+   **The gate of the restore.** In the fix loop, the tip before the restore has a green gate, so the driver gates the restore commit and does not leave the question to the correction. A red gate means that a restored file fails with the ticket's code: the correction gets the gate record (`prompts/restored-red.md`), and a DONE correction must list a restored file in `locked`; else it reports BLOCKED with `locked test contradicts spec:`. A green gate with only driver findings to correct closes them with the restore: no test-writer runs. After `overrule-test` the driver does not gate the restore, because the tip before it has no green gate; a change that the next implementer makes to a merged ticket's file is a finding of the next review.
 
 Rules for each agent:
 
@@ -130,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.
@@ -172,7 +176,7 @@ Every report has `status` (`DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, `BLOCK
 
 | Role | Template | More fields | Checks after the schema |
 |---|---|---|---|
-| test-writer | `prompts/test-writer.md` | `locked` (test file paths), `red` (`test`, `line`) | The driver reads a test node id `<file>::<test>` in `locked` as its file. With DONE: one commit, one locked file and one red line or more. Each locked path is in a commit that the role made. Each `line` is in the log. A locked file of a merged ticket that the role changed is in `locked`. A correction (after `overrule-test`, or for a review finding) changes only the files that it lists in `locked` and the files that the driver restored before it. |
+| test-writer | `prompts/test-writer.md` | `locked` (test file paths), `red` (`test`, `line`) | The driver reads a test node id `<file>::<test>` in `locked` as its file. With DONE: one commit, one locked file and one red line or more. Each locked path is in a commit that the role made. Each `line` is in the log. A locked file of a merged ticket that the role changed is in `locked`. A correction (after `overrule-test`, or for a review finding) changes only the files that it lists in `locked` and the files that the driver restored before it. When the gate is red on the restore commit, a DONE correction lists a restored file in `locked`. |
 | implementer | `prompts/implementer.md` | `green` | With DONE: one commit or more. |
 | reviewer | `prompts/reviewer.md` | `findings` (`severity`, `file`, `line`, `title`, `evidence`, `kind`), `mutations` (`test`, `file`, `line`, `red`); `commits` is empty | In the first review of a tip: `mutations` is required, with a proof for each locked test file (`test` is `<locked file>::<test name>`). Each `red` is in the log. |
 | correctness | `prompts/correctness.md` | the same as the reviewer; `commits` is empty | `mutations` is optional. |
@@ -202,7 +206,7 @@ Answer with `--answer <question id>=<option id>` on the next run, or through the
 
 | Check | Where it lives |
 |---|---|
-| Locked tests with a demonstrated red | `driver_report.py` `_proof_errors`: each red line of the test-writer report must be in its log. `driver_review.py` `locked_findings`: a locked file of the ticket that differs from the test-writer commit is a critical finding, before each review. `driver_merge.py` `refused`, called from `driver.py` `_checked_landing` under the merge lock: a locked file of a merged ticket that differs between the PR tip and the tree that is about to land refuses the landing, so a later ticket cannot change the locked test of an earlier one. `driver_report.py` `_merged_errors` rejects a test-writer report that changes such a file and does not list it. |
+| Locked tests with a demonstrated red | `driver_report.py` `_proof_errors`: each red line of the test-writer report must be in its log. `driver_review.py` `locked_findings`: a locked file of the ticket that differs from the test-writer commit is a critical finding, before each review. `driver_review.py` `merged_changes`: a locked file of a merged ticket that the ticket changed is a critical `fixture` finding, before each review. `driver_merge.py` `refused`, called from `driver.py` `_checked_landing` under the merge lock: a locked file of a merged ticket that differs between the PR tip and the tree that is about to land refuses the landing, so a later ticket cannot change the locked test of an earlier one. `driver_report.py` `_merged_errors` rejects a test-writer report that changes such a file and does not list it. |
 | One mutation proof for each locked test | `prompts/reviewer.md` asks for one proof for each locked test. `driver_report.py` `_locked_errors` and `_proof_errors` reject a first review with no proof for a locked test file, or with a red line that is not in the log. `driver_review.py` `follow` finds the proofs that a fix makes due again. |
 | One independent correctness pass for each risky ticket | `driver_fixloop.py` `_review` adds the pass for a ticket with a **Risk** line. `driver_agents.py` `correctness_entry` picks the entry of another provider, and `load_models` stops the run when there is none or its CLI is not on PATH. |
 | One full gate for each candidate | `driver_gate.py` `run`, called from `driver_run.py` `Run.gate`: one record for each commit the driver is about to trust. Green is exit 0 on a tree that is clean before and after, with HEAD not moved. |

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
 
@@ -25,6 +27,7 @@ import driver_decisions
 import driver_final
 import driver_fixloop
 import driver_graph
+import driver_legacy
 import driver_merge
 import driver_review
 import driver_review_page
@@ -32,6 +35,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 +63,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 +84,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)}
@@ -152,7 +157,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 +176,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 +214,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 +354,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 +371,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 +466,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 +556,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 +571,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 +634,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 +655,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}
@@ -34,7 +34,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 +169,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 +249,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 +258,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)

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_merge
 import driver_review
 import driver_slots
 from driver_run import OUT, Blocked, Run, during, ledger
@@ -86,7 +87,8 @@ def _review(job: Job) -> list[dict]:
     """Review `job.tip`. Returns the findings of the driver and of each reviewer."""
     run, number = job.run, job.ticket.number
     state = run.state.ticket(number, phase="review")
-    found = _log_findings(job, driver_review.locked_findings(job.slot, state))
+    merged = driver_merge.changed(job.slot, run.tip(), driver_merge.protected(run.state.read()["tickets"], number))
+    found = _log_findings(job, driver_review.locked_findings(job.slot, state) + driver_review.merged_changes(merged))
     cast = [("reviewer", "")]
     if job.ticket.risk:
         cast.append(("correctness", driver_agents.correctness_entry(run.models)))
@@ -107,11 +109,21 @@ def _correct(job: Job, findings: list[dict]) -> None:
         raise Blocked(f"the review: a locked-test finding is open after the test-writer correction: {titles}")
     restored = run.restore_locked_files(number, job.slot)
     job.tip = driver_slots.head(job.slot)  # the restore is a commit of the driver
-    values = {**job.pointers(job.round), "restored": " ".join(restored)}
-    notes = ["correction"] + ["restored"] * bool(restored)
+    # The gate was green on the tip before the restore, so a red gate here is a restored file that fails with the
+    # ticket's code. The driver decides that, not the correction (issue #90).
+    with during("the gate of the restore"):
+        record = run.red_gate(number, job.slot, job.tip) if restored else ""
+    if not record and all(finding["source"] == "driver" for finding in findings):
+        job.previous = ""  # no review has seen the restore commit
+        ledger(f"Ticket {number}: the code does not need the change to {', '.join(restored)}: the restore closes it, "
+               "with no correction.")
+        return
+    values = {**job.pointers(job.round), "restored": " ".join(restored),
+              "record": record and os.path.relpath(record, job.slot)}
+    notes = ["correction"] + ["restored"] * bool(restored) + ["restored-red"] * bool(record)
     with during("the test-writer correction"):
         report = run.agent("test-writer", number, job.slot, values, notes=notes, fix_round=job.round + 1,
-                           check={"correction": True, "restored": restored})
+                           check={"correction": True, "restored": restored, "restore_red": bool(record)})
     job.tip, job.previous, job.corrected = driver_slots.head(job.slot), "", True
     entry = run.state.read()["tickets"][number]
     run.state.ticket(number, tip=job.tip, **driver_review.written(job.slot, entry, report["locked"], job.tip))
@@ -153,7 +165,7 @@ def _act_on(job: Job, found: list[dict]) -> bool:
         # No correction after round 4: no fix round could make its new locked tests green, so `accept` could not merge.
         to_correct, to_fix = [], [finding for finding in found if finding in to_correct + to_fix]
     # A changed locked file is fixed first: a correction on top of it would make the changed file the reference.
-    locked_file_changed = any(finding["source"] == "driver" for finding in found)
+    locked_file_changed = any(finding["source"] == "driver" for finding in to_fix)
     if to_correct and not locked_file_changed:
         _correct(job, to_correct)
         if not to_fix:

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 []