@jesdi/skills 0.0.44 → 0.0.45

package/skills/implement-spec/driver_state.py

@@ -1,6 +1,6 @@
 """state.json, the resume contract: one lock, every write a read-modify-write, published by rename.
 
-    {"run": {revision, pr_branch, gates, stops, agents: [{ticket, role, entry, seconds, cost}], questions, start,
+    {"run": {revision, pr_branch, schema, gates, stops, agents: [{ticket, role, entry, seconds, cost}], questions, start,
              landed: [[ticket, the PR tip its merge made]], final},
      "tickets": {"NN": {phase, round, tip, test_writer_sha, locked, green_gates, slot, note, held}}}"""
 from __future__ import annotations
@@ -13,8 +13,10 @@ import uuid
 from pathlib import Path
 from typing import IO
 
-from driver_slots import git, path
+from driver_names import Names
+from driver_slots import ancestor, git, on_branch, path
 
+SCHEMA = 2  # the version of this contract; 2: the names of driver_names. A run of an older driver has none.
 PHASES = ("pending", "test-writer", "implement", "gate", "review", "fix", "merge", "merged", "blocked")
 
 
@@ -42,7 +44,7 @@ class State:
         """Create the file for a new run, or add the tickets a resumed run does not know yet."""
         def change(state: dict) -> None:
             state.setdefault("run", {
-                "revision": uuid.uuid4().hex, "pr_branch": pr_branch, "gates": 0, "stops": 0, "agents": [],
+                "revision": uuid.uuid4().hex, "pr_branch": pr_branch, "schema": SCHEMA, "gates": 0, "stops": 0, "agents": [],
                 "questions": [], "start": git(".", "rev-parse", f"refs/heads/{pr_branch}").stdout.strip(),
                 "landed": [], "final": _final()})
             for key, value in _final().items():  # a run of an older driver lacks the newer keys
@@ -67,22 +69,19 @@ class State:
         return self.update(lambda state: state["tickets"][number].update(fields))["tickets"][number]
 
 
-def lock(path: Path) -> IO | None:
-    """The exclusive kernel lock on `path`, held while the returned file is open; None when another process has it."""
+def lock(path: Path, shared: bool = False) -> IO | None:
+    """The kernel lock on `path`, exclusive or `shared`, held while the returned file is open; None when another
+    process has it in a way that excludes this one."""
     path.parent.mkdir(parents=True, exist_ok=True)
     held = path.open("a")
     try:
-        fcntl.flock(held, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        fcntl.flock(held, (fcntl.LOCK_SH if shared else fcntl.LOCK_EX) | fcntl.LOCK_NB)
     except BlockingIOError:
         held.close()
         return None
     return held
 
 
-def _ancestor(commit: str, of: str) -> bool:
-    return git(".", "merge-base", "--is-ancestor", commit, of).returncode == 0
-
-
 def verified(entry: dict, branch: str, pr_branch: str) -> tuple[dict, str]:
     """(the fields to resume from, why) when git contradicts the entry; ({}, "") when it does not."""
     phase, tip = entry["phase"], str(entry["tip"])
@@ -90,7 +89,7 @@ def verified(entry: dict, branch: str, pr_branch: str) -> tuple[dict, str]:
         return {}, ""
     # The branch of a merged ticket is deleted, so its commits are trusted only while the PR branch has them.
     where, word = (pr_branch, "in") if phase == "merged" else (branch, "on")
-    if _ancestor(tip, where):
+    if ancestor(tip, where):
         return {}, ""
     return {"phase": "implement", "tip": entry["test_writer_sha"]}, f"the recorded tip {tip[:7]} is not {word} {where}"
 
@@ -102,7 +101,7 @@ def kept(state: dict) -> dict[str, int]:
     for number, entry in state.get("tickets", {}).items():
         if (entry["phase"] in ("test-writer", "implement") or number in asking) and entry["slot"]:
             slot = path(entry["slot"])
-            on = git(slot, "symbolic-ref", "-q", "--short", "HEAD").stdout.strip()
-            if on == f"ticket/{number}" and git(slot, "status", "--porcelain").stdout.strip():
+            on = on_branch(slot)
+            if on == Names(state["run"]["pr_branch"]).ticket(number) and git(slot, "status", "--porcelain").stdout.strip():
                 found[number] = entry["slot"]
     return found

package/skills/implement-spec/tests/test_agents.py

@@ -1,13 +1,13 @@
 """Agent launch acceptance tests, through `sh run.sh` with a fake runner script or fake claude/codex on PATH.
 
 Interface choices (ticket 02): `--runner <script>` is called as `<script> <role> <prompt> <report>` in the slot
-directory. A plain run (no --dry-run) branches ticket/NN from the PR tip in slot 1, runs the test-writer (unless the
+directory. A plain run (no --dry-run) branches ticket/feat%2Fcsv/NN from the PR tip in slot 1, runs the test-writer (unless the
 Seam is `none — refactor`) then the implementer; from ticket 03 on an accepted ticket goes on to the driver's gate (`true` here) and a
-merge into the PR branch, which deletes `ticket/NN`. Exit 0 when the ticket merges, 1 on BLOCKED.
+merge into the PR branch, which deletes `ticket/feat%2Fcsv/NN`. Exit 0 when the ticket merges, 1 on BLOCKED.
 `--only <role>` runs that one role on the first ticket and stops. `--spec <path>` names the spec for the prompts.
 `--timeout <role>=<minutes>` (repeatable, fractions allowed) overrides a role timeout.
 Ticket 08: the fixture has no `origin`, and a run that merges its ticket ends with the tidy and the final review, so
-`ticket_commits()` reads the ticket's commits from `refs/implement/recovery`, the PR tip from before the tidy.
+`ticket_commits()` reads the ticket's commits from `refs/implement-spec/feat%2Fcsv/recovery`, the PR tip from before the tidy.
 """
 import json
 import os
@@ -134,7 +134,7 @@ class World:
         return path.read_text() if path.exists() else ""
 
     def ticket_commits(self):
-        made = subprocess.run(["git", "rev-parse", "--verify", "-q", "refs/implement/recovery"], cwd=self.repo,
+        made = subprocess.run(["git", "rev-parse", "--verify", "-q", "refs/implement-spec/feat%2Fcsv/recovery"], cwd=self.repo,
                               capture_output=True, text=True).stdout.strip() or "feat/csv"
         return git(self.repo, "rev-list", "--reverse", "--no-merges", f"{self.base}..{made}").split()
 
@@ -175,7 +175,7 @@ def test_runner_is_called_with_role_prompt_report_in_the_slot_directory(env):
     assert role == "implementer" and call["prompt"].strip()
     assert Path(call["cwd"], report).resolve().as_posix().endswith(".agent/implement/01/implementer-0.json")
     assert Path(call["cwd"], report).exists()
-    assert call["cwd"] == str(w.repo.resolve()) and call["branch"] == "ticket/01"
+    assert call["cwd"] == str(w.repo.resolve()) and call["branch"] == "ticket/feat%2Fcsv/01"
 
 
 def test_default_models_file_names_every_role():
@@ -231,7 +231,7 @@ def test_unknown_provider_or_effort_exits_3_naming_role_and_entry_before_any_age
     proc = w.run({"test-writer": [tw()]})
     assert proc.returncode == 3 and not w.calls("test-writer")
     assert not launches(w.tmp, "claude") and not launches(w.tmp, "codex")
-    assert "ticket/01" not in git(w.repo, "branch", "--list")
+    assert "ticket/feat%2Fcsv/01" not in git(w.repo, "branch", "--list")
 
 
 def test_implementer_prompt_carries_pointers_and_only_template_sentences(env):
@@ -284,7 +284,7 @@ def test_a_model_the_account_cannot_use_fails_the_preflight_with_exit_3_before_a
     assert f"model entry openai/gpt-astra@medium: the codex CLI failed the preflight (exit 1): {REFUSED}" \
         in proc.stdout.splitlines(), proc.stdout
     assert not launches(w.tmp, "claude") and not launches(w.tmp, "codex")
-    assert "ticket/01" not in git(w.repo, "branch", "--list") and not w.ledger()
+    assert "ticket/feat%2Fcsv/01" not in git(w.repo, "branch", "--list") and not w.ledger()
 
 
 def test_a_cli_that_fails_with_no_report_stops_the_run_with_exit_4_and_the_same_command_resumes(env):
@@ -368,16 +368,16 @@ def test_head_moved_to_the_pr_branch_resets_the_slot_and_reruns_once(env):
     ok(w.run({"test-writer": [tw()], "implementer": [{"git": [["checkout", "feat/csv"]]}, impl()]}))
     first, second = w.calls("implementer")
     tests_sha = w.ticket_commits()[0]
-    assert (second["branch"], second["head"]) == ("ticket/01", tests_sha)
+    assert (second["branch"], second["head"]) == ("ticket/feat%2Fcsv/01", tests_sha)
     assert any("implementer" in l and "feat/csv" in l for l in w.ledger().splitlines()), w.ledger()
 
 
 def test_a_missing_ticket_branch_is_a_violation_named_in_the_ledger(env):
     w = World(env)
-    gone = {"git": [["checkout", "--detach"], ["branch", "-D", "ticket/01"]]}
+    gone = {"git": [["checkout", "--detach"], ["branch", "-D", "ticket/feat%2Fcsv/01"]]}
     proc = w.run({"test-writer": [tw()], "implementer": [gone, impl()]})
     assert "Traceback" not in proc.stderr
-    assert any("ticket/01" in l and "branch" in l for l in w.ledger().splitlines()), w.ledger()
+    assert any("ticket/feat%2Fcsv/01" in l and "branch" in l for l in w.ledger().splitlines()), w.ledger()
 
 
 def test_log_next_to_report_and_ledger_records_role_entry_duration_and_cost(env):

package/skills/implement-spec/tests/test_amendments.py

@@ -5,7 +5,7 @@ with and without its bare `origin`, and the rig of test_review with and without
 
 Interface choices (ticket 08):
 - with no `origin`, the tidied commits sit on the commit the PR branch had when the run started (nothing to rebase
-  onto), and `refs/implement/recovery` holds the PR tip from before the tidy, as with an `origin`.
+  onto), and `refs/implement-spec/feat%2Fcsv/recovery` holds the PR tip from before the tidy, as with an `origin`.
 - the one ledger sentence about the missing remote names `origin` and says that the rebase and the push were skipped.
 - a refused start (exit 3) prints its reason on stdout or stderr: `origin` for a push that has no remote; for the
   correctness role one line that names `correctness` and `codex`, or `correctness` and each entry of its list.
@@ -39,7 +39,7 @@ def test_with_no_origin_the_branch_is_tidied_gated_and_reviewed_with_no_rebase_a
     rows = rig.commits(rig.start)
     assert [r["subject"] for r in rows] == ["feat(01): Export rows", "feat(02): Quote fields"]
     assert ref(rig.repo, f"{rows[0]['sha']}~1") == rig.start, "no rebase: the ticket commits sit on the branch's start"
-    assert ref(rig.repo, "feat/csv^{tree}") == ref(rig.repo, "refs/implement/recovery^{tree}")
+    assert ref(rig.repo, "feat/csv^{tree}") == ref(rig.repo, "refs/implement-spec/feat%2Fcsv/recovery^{tree}")
     records = sorted(p.name for p in (rig.repo / ".agent/implement/final").glob("gate-*.log"))
     assert records == [f"gate-{tip[:7]}.log"], records
     (gate,) = [g for g in rig.gates() if g["commit"] == tip]

package/skills/implement-spec/tests/test_decisions.py

@@ -99,7 +99,7 @@ def test_an_answers_file_of_an_earlier_run_is_not_applied_to_the_same_question_o
     write_answers(rig, {Q1: "overrule-test"})
     # The operator starts again: the run directory goes, the answers file is outside it and stays.
     shutil.rmtree(rig.repo / ".agent/implement")
-    git(rig.repo, "branch", "-D", "ticket/01")
+    git(rig.repo, "branch", "-D", "ticket/feat%2Fcsv/01")
     again = steps(blocked(), blocked(), impl("01"))
     rig.run(again)
     new = decisions(rig)
@@ -144,7 +144,7 @@ def test_a_stop_with_uncommitted_work_keeps_its_slot_and_takes_the_answer(tmp_pa
     rig.run(steps(dirty, impl("01")), *UNATTENDED)
     assert rig.code == 0, rig.ledger()
     second = rig.calls("01", "implementer")[1]
-    assert second["status"] == "M demo/export.py" and second["branch"] == "ticket/01", "the work is in the tree of the rerun"
+    assert second["status"] == "M demo/export.py" and second["branch"] == "ticket/feat%2Fcsv/01", "the work is in the tree of the rerun"
     prompt = (rig.folder() / "implementer-0.prompt.md").read_text()
     assert "the locked tests stand as they are" in prompt and "uncommitted work" in prompt
     assert "feat: 01 rows" in rig.pr_subjects() and not git(rig.repo, "status", "--porcelain")
@@ -221,7 +221,7 @@ def test_a_correction_that_commits_more_than_the_files_it_lists_is_rejected(tmp_
     assert rig.code == 1, rig.ledger()
     assert rig.led("Ticket 01: BLOCKED at the test-writer: a correction may change only the files it lists in "
                    "`locked`: its commits also change demo/export.py.")
-    assert rig.led(restored(OTHER)) and git(rig.repo, "show", f"ticket/01:{OTHER}") == OTHER_TEST
+    assert rig.led(restored(OTHER)) and git(rig.repo, "show", f"ticket/feat%2Fcsv/01:{OTHER}") == OTHER_TEST
     assert len(rig.calls("01", "test-writer")) == 3 and len(rig.calls("01", "implementer")) == 1, "one rerun, no implementer"
     assert "its commits also change demo/export.py" in rig.prompt("test-writer-0")
     assert "feat: 01 rows" not in rig.pr_subjects() and rig.state()["tickets"]["01"]["held"] == {}
@@ -370,7 +370,7 @@ def test_unattended_writes_the_stage_file_and_prints_no_question(tmp_path, capsy
 
 
 def test_unattended_names_the_blocked_tickets_and_needs_a_stage_path_to_write(tmp_path):
-    rig = Pushing(tmp_path, ONE, gate={"red": ["ticket/01"]})
+    rig = Pushing(tmp_path, ONE, gate={"red": ["ticket/feat%2Fcsv/01"]})
     rig.run(plan(), "--unattended")
     assert rig.code == 1 and not (rig.repo / ".agent/stage.json").exists()
     rig.run(plan(), "--unattended", "--stage-json", ".agent/out/stage.json")

package/skills/implement-spec/tests/test_driver.py

@@ -4,6 +4,7 @@ import fcntl
 import json
 import os
 import subprocess
+import sys
 import time
 from pathlib import Path
 
@@ -13,6 +14,7 @@ import pytest
 import driver
 import driver_agents
 import driver_report
+import driver_state
 
 from conftest import GIT, ticket
 
@@ -33,7 +35,7 @@ def test_a_run_without_dry_run_needs_the_spec(repo, capsys):
     repo(t01=ticket("01"))
     assert driver.main(["--gate", "make check"]) == 3
     assert capsys.readouterr().out == "--spec is required: the spec file the prompts point at\n"
-    assert "ticket/01" not in subprocess.run(["git", "branch"], capture_output=True, text=True).stdout
+    assert "ticket/feat%2Fx/01" not in subprocess.run(["git", "branch"], capture_output=True, text=True).stdout
 
 
 def test_every_environment_and_ticket_error_is_listed_together(repo, capsys):
@@ -158,7 +160,7 @@ def ledger_of(tmp_path):
 
 def walked(*short):
     """The PR tip as the tickets left it: the recovery point of the tidy when there is one, else the tip of feat/x."""
-    made = subprocess.run(["git", "rev-parse", *short, "-q", "--verify", "refs/implement/recovery"], capture_output=True, text=True)
+    made = subprocess.run(["git", "rev-parse", *short, "-q", "--verify", "refs/implement-spec/feat%2Fx/recovery"], capture_output=True, text=True)
     return made.stdout.strip() or subprocess.run(["git", "rev-parse", *short, "feat/x"], capture_output=True, text=True).stdout.strip()
 
 
@@ -242,7 +244,7 @@ def test_a_moved_head_prompt_line_comes_from_its_template(repo, tmp_path, capsys
     repo()
     tip = subprocess.run(["git", "rev-parse", "HEAD"], capture_output=True, text=True).stdout.strip()
     agents(tmp_path, capsys, "git checkout -q --detach\n")
-    line = (driver_report.PROMPTS / "moved.md").read_text().replace("{branch}", "ticket/01").replace("{tip}", tip)
+    line = (driver_report.PROMPTS / "moved.md").read_text().replace("{branch}", "ticket/feat%2Fx/01").replace("{tip}", tip)
     assert line in prompt_of(tmp_path) and prompt_of(tmp_path).rstrip().endswith("one ref store.")
 
 
@@ -307,10 +309,10 @@ def test_a_timeout_doubles_the_limit_and_a_second_one_blocks(repo, tmp_path, cap
 
 
 @pytest.mark.parametrize("move, problem", [
-    ("git checkout -q feat/x", "HEAD is on feat/x instead of ticket/01"),
-    ("git checkout -q --detach", "HEAD is on a detached commit instead of ticket/01"),
-    ("git checkout -q --detach; git branch -q -D ticket/01", "branch ticket/01 is missing"),
-    ("git checkout -q -B ticket/01 HEAD~1", "ticket/01 no longer holds"),
+    ("git checkout -q feat/x", "HEAD is on feat/x instead of ticket/feat%2Fx/01"),
+    ("git checkout -q --detach", "HEAD is on a detached commit instead of ticket/feat%2Fx/01"),
+    ("git checkout -q --detach; git branch -q -D ticket/feat%2Fx/01", "branch ticket/feat%2Fx/01 is missing"),
+    ("git checkout -q -B ticket/feat%2Fx/01 HEAD~1", "ticket/feat%2Fx/01 no longer holds"),
 ])
 def test_a_moved_head_resets_the_slot_and_reruns(repo, tmp_path, capsys, move, problem):
     repo()
@@ -326,7 +328,7 @@ def test_a_moved_head_resets_the_slot_and_reruns(repo, tmp_path, capsys, move, p
 
 def test_an_existing_ticket_branch_stops_the_run(repo, tmp_path, capsys):
     repo()
-    subprocess.run(["git", "branch", "ticket/01"], check=True)
+    subprocess.run(["git", "branch", "ticket/feat%2Fx/01"], check=True)
     assert agents(tmp_path, capsys, "exit 0\n") == (3, [])
 
 
@@ -357,7 +359,7 @@ echo "$role $nn" >> "${FILE:-work-$nn.txt}"; git add -A; git commit -q -m "$role
 echo "$nn $PWD" >> "$0.calls"
 """
 # Ticket 01 waits until ticket 02 has its branch, so both start from the same PR tip.
-TOGETHER = """[ "$nn" != 01 ] || until git rev-parse -q --verify refs/heads/ticket/02 > /dev/null; do sleep 0.02; done\n"""
+TOGETHER = """[ "$nn" != 01 ] || until git rev-parse -q --verify refs/heads/ticket/feat%2Fx/02 > /dev/null; do sleep 0.02; done\n"""
 REFACTOR = {"seam": "none — refactor"}
 # A fixer that cannot make the red gate green: the ticket blocks at fix round 1.
 GIVE_UP = """[ $role != fixer ] || { printf '{"status": "BLOCKED", "commits": [], "files": [], "concerns": ["the gate stays red"], "green": [], "ticket": "01"}' > "$report"; exit 0; }\n"""
@@ -437,7 +439,7 @@ def test_a_conflict_agent_that_does_not_resolve_blocks_the_ticket_and_keeps_its_
     assert f"BLOCKED at the merge: the conflict agent: report .agent/implement/{number}/conflict-0.json is not" in line
     assert len([line for line in ledger if "conflict ran on" in line]) == 2  # the one rerun of a violation
     assert state_of(tmp_path)["tickets"][number]["phase"] == "blocked"
-    assert f"ticket/{number}" in branches() and f"Ticket {number} is not merged: its phase is blocked." in out
+    assert f"ticket/feat%2Fx/{number}" in branches() and f"Ticket {number} is not merged: its phase is blocked." in out
     for slot in (".", ".agent/worktrees/slot-2"):  # the driver's open merge is gone
         assert out_of("git", "-C", slot, "status", "--porcelain") == ""
         assert out_of("git", "-C", slot, "rev-parse", "-q", "--verify", "MERGE_HEAD") == ""
@@ -450,7 +452,7 @@ def test_a_conflict_cli_that_fails_stops_the_run_and_leaves_no_open_merge(repo,
     assert code == 4 and "with no report: ERROR: not signed in" in out, out
     assert not [line for line in ledger if "BLOCKED" in line]
     (number,) = [n for n, entry in state_of(tmp_path)["tickets"].items() if entry["phase"] == "merge"]
-    assert f"ticket/{number}" in branches()
+    assert f"ticket/feat%2Fx/{number}" in branches()
     for slot in (".", ".agent/worktrees/slot-2"):
         assert out_of("git", "-C", slot, "status", "--porcelain") == ""
         assert out_of("git", "-C", slot, "rev-parse", "-q", "--verify", "MERGE_HEAD") == ""
@@ -459,7 +461,7 @@ def test_a_conflict_cli_that_fails_stops_the_run_and_leaves_no_open_merge(repo,
 def test_a_red_gate_is_a_finding_and_the_ticket_it_blocks_never_starts(repo, tmp_path, capsys):
     two(repo, second="01")
     code, ledger, out = walk(tmp_path, capsys, GIVE_UP + WORK + REPORT, gate="echo CHECK-OUTPUT; exit 1")
-    tip = out_of("git", "rev-parse", "--short=7", "ticket/01")
+    tip = out_of("git", "rev-parse", "--short=7", "ticket/feat%2Fx/01")
     assert code == 1 and ledger[-1] == GAVE_UP, out
     assert ledger[1] == (f"Ticket 01: critical finding of kind code from the gate at "
                          f".agent/implement/01/gate-{tip}.log:0: the gate is red on {tip}.")
@@ -487,7 +489,7 @@ def test_a_tree_that_is_not_clean_is_a_red_gate_and_the_slot_keeps_the_work(repo
     assert code == 1 and "from the gate at .agent/implement/01/gate-" in ledger[-3] and ledger[-1] == GAVE_UP, out
     record = next((tmp_path / ".agent/implement/01").glob("gate-*.log")).read_text()
     assert "status: not clean\n    ?? junk.txt\n" in record and "exit: not run" in record and "\nNEVER\n" not in record
-    assert out_of("git", "symbolic-ref", "--short", "HEAD") == "ticket/01" and (tmp_path / "junk.txt").exists()
+    assert out_of("git", "symbolic-ref", "--short", "HEAD") == "ticket/feat%2Fx/01" and (tmp_path / "junk.txt").exists()
     code, _, out = walk(tmp_path, capsys, "exit 9\n")
     assert code == 3 and "uncommitted change: junk.txt" in out
 
@@ -524,7 +526,7 @@ def test_a_resumed_tip_that_is_not_on_the_branch_returns_the_ticket_to_implement
     base = out_of("git", "rev-parse", "feat/x")
     code, ledger, out = walk(tmp_path, capsys, WORK + REPORT)
     assert code == 0, out
-    assert "Ticket 01: returned to implement from the PR tip: the recorded tip 1111111 is not on ticket/01." in ledger
+    assert "Ticket 01: returned to implement from the PR tip: the recorded tip 1111111 is not on ticket/feat%2Fx/01." in ledger
     assert out_of("git", "rev-parse", "feat/x~1") == base  # the earlier, untrusted commit is not in the PR branch
 
 
@@ -537,10 +539,102 @@ def test_a_resumed_ticket_with_a_settled_gate_merges_without_a_gate_or_an_agent(
     (tmp_path / ".agent/implement/state.json").write_text(json.dumps(state))
     # A gate on the ticket branch is still red, so a second gate for the settled commit would block the ticket. The
     # one new gate is that of the end of run, on the PR branch.
-    code, ledger, out = walk(tmp_path, capsys, "exit 9\n", gate='[ "$(git rev-parse --abbrev-ref HEAD)" != ticket/01 ]')
+    code, ledger, out = walk(tmp_path, capsys, "exit 9\n", gate='[ "$(git rev-parse --abbrev-ref HEAD)" != ticket/feat%2Fx/01 ]')
     assert code == 0 and walked() == tip and "| gates run | 2 |" in out
 
 
+def as_older_driver(tmp_path, *numbers):
+    """Make the run in tmp_path one that an older driver started: no `schema`, and the old names of its ticket
+    branches and of its recovery ref."""
+    state = state_of(tmp_path)
+    del state["run"]["schema"]
+    (tmp_path / ".agent/implement/state.json").write_text(json.dumps(state))
+    for nn in numbers:
+        subprocess.run(["git", "branch", "-m", f"ticket/feat%2Fx/{nn}", f"ticket/{nn}"], check=True)
+    if recovery := out_of("git", "rev-parse", "-q", "--verify", "refs/implement-spec/feat%2Fx/recovery"):
+        subprocess.run(["git", "update-ref", "refs/implement/recovery", recovery], check=True)
+        subprocess.run(["git", "update-ref", "-d", "refs/implement-spec/feat%2Fx/recovery"], check=True)
+    return recovery
+
+
+def test_a_run_of_an_older_driver_resumes_on_its_renamed_ticket_branch(repo, tmp_path, capsys):
+    """An older driver named the ticket branch `ticket/NN`. The resume renames it and trusts the recorded tip."""
+    entry = blocked_then_edited(repo, tmp_path, capsys, phase="merge")
+    state = state_of(tmp_path)
+    state["tickets"]["01"]["green_gates"] = [entry["tip"]]
+    (tmp_path / ".agent/implement/state.json").write_text(json.dumps(state))
+    as_older_driver(tmp_path, "01")
+    code, ledger, out = walk(tmp_path, capsys, "exit 9\n")
+    assert code == 0, out
+    assert "Ticket 01: renamed the branch ticket/01 of an older driver to ticket/feat%2Fx/01." in ledger
+    assert not any("returned to implement" in line for line in ledger) and walked() == entry["tip"]
+    assert branches() == ["feat/x"]
+
+
+def test_a_run_of_an_older_driver_on_a_contradicted_ticket_branch_returns_the_ticket_to_implement(repo, tmp_path,
+                                                                                               capsys):
+    """Spec review: slot 1 is on `ticket/NN` of an older driver, and git contradicts the recorded tip, so the branch
+    keeps its old name. The resume accepts slot 1 there, as the older driver did, and starts the ticket again."""
+    blocked_then_edited(repo, tmp_path, capsys, phase="review", tip="1" * 40)
+    as_older_driver(tmp_path, "01")
+    subprocess.run(["git", "checkout", "-q", "ticket/01"], check=True)
+    code, ledger, out = walk(tmp_path, capsys, WORK + REPORT)
+    assert code == 0, out
+    assert "Ticket 01: returned to implement from the PR tip: the recorded tip 1111111 is not on ticket/feat%2Fx/01." in ledger
+    assert not [line for line in ledger if "renamed" in line]
+
+
+def test_a_ticket_branch_of_an_older_driver_that_git_cannot_rename_stops_the_run(repo, tmp_path, capsys):
+    blocked_then_edited(repo, tmp_path, capsys)
+    as_older_driver(tmp_path, "01")
+    subprocess.run(["git", "branch", "ticket/feat%2Fx"], check=True)  # a branch where the folder of the new name goes
+    code, ledger, out = walk(tmp_path, capsys, "exit 9\n")
+    assert code == 3 and out.startswith("implement-spec: cannot rename the branch ticket/01 of an older driver to "
+                                        "ticket/feat%2Fx/01: "), out
+    assert "ticket/01" in branches() and not [line for line in ledger if "renamed" in line]
+
+
+def test_a_finished_run_of_an_older_driver_gets_the_new_name_of_its_recovery_ref(repo, tmp_path, capsys):
+    """Spec review: the recovery ref moves through the driver, before the end of run reads it."""
+    repo(t01=ticket("01", **REFACTOR))
+    assert walk(tmp_path, capsys, WORK + REPORT)[0] == 0
+    recovery = as_older_driver(tmp_path)
+    assert recovery
+    code, _, out = walk(tmp_path, capsys, "exit 9\n")
+    assert code == 0, out
+    assert ("Recovery point: moved refs/implement/recovery of an older driver to refs/implement-spec/feat%2Fx/recovery."
+            in (tmp_path / ".agent/implement/ledger.md").read_text().splitlines())
+    assert out_of("git", "rev-parse", "-q", "--verify", "refs/implement/recovery") == "" and walked() == recovery
+
+
+def test_no_older_driver_starts_while_a_newer_driver_runs(repo, tmp_path, capsys):
+    """Spec review: the newer driver holds the lock of an older driver, shared, for its whole run. The agent tries to
+    take that lock as an older driver does, alone, and cannot."""
+    repo(t01=ticket("01", **REFACTOR))
+    old_lock = Path(out_of("git", "rev-parse", "--git-common-dir")).resolve() / "implement-spec.lock"
+    probe = tmp_path.parent / f"{tmp_path.name}-probe"
+    older = (f'"{sys.executable}" -c "import fcntl; fcntl.flock(open(\'{old_lock}\', \'a\'), '
+             f'fcntl.LOCK_EX | fcntl.LOCK_NB)" 2>/dev/null; echo $? > {probe}\n')
+    code, _, out = walk(tmp_path, capsys, older + WORK + REPORT)
+    assert code == 0 and probe.read_text() == "1\n", out
+
+
+@pytest.mark.parametrize("older_run", [False, True])
+def test_a_newer_driver_waits_while_an_older_driver_runs(repo, tmp_path, capsys, older_run):
+    """Correctness review: an older driver holds only `implement-spec.lock`, so a newer driver waits for that lock,
+    on a run of its own and on a run that an older driver started."""
+    blocked_then_edited(repo, tmp_path, capsys)
+    if older_run:
+        as_older_driver(tmp_path, "01")
+    old_lock = Path(out_of("git", "rev-parse", "--git-common-dir")).resolve() / "implement-spec.lock"
+    with hold(old_lock):
+        code, ledger, out = walk(tmp_path, capsys, "exit 9\n")
+    assert code == 3 and out == ("implement-spec: a driver of an older version runs in this repository: it holds the "
+                                 f"lock {old_lock}. Wait until it ends, then run the driver again.\n")
+    assert ("ticket/01" if older_run else "ticket/feat%2Fx/01") in branches()
+    assert not [line for line in ledger if "renamed" in line] and state_of(tmp_path)["tickets"]["01"]["phase"] == "blocked"
+
+
 def test_an_unknown_phase_fails_the_resume(repo, tmp_path, capsys):
     blocked_then_edited(repo, tmp_path, capsys, phase="polish")
     code, _, out = walk(tmp_path, capsys, "exit 9\n")
@@ -567,12 +661,23 @@ def test_a_first_run_on_a_detached_head_or_with_no_slot_is_refused(repo, tmp_pat
     assert code == 3 and "the PR worktree is on a detached HEAD" in out
 
 
+def test_a_first_run_in_a_slot_of_another_run_is_refused(repo, tmp_path, capsys):
+    """Correctness review: a slot has no state.json of its own, so its ticket branch would name a lock of its own,
+    and two drivers would control one worktree."""
+    repo(t01=ticket("01", **REFACTOR))
+    subprocess.run(["git", "checkout", "-q", "-b", "ticket/feat%2Fx/01"], check=True)
+    code, ledger, out = walk(tmp_path, capsys, "exit 9\n")
+    assert (code, ledger) == (3, []) and out == (
+        "the PR worktree is on the ticket branch ticket/feat%2Fx/01 of a run: check out the PR branch\n")
+    assert not (tmp_path / ".agent/implement").exists()
+
+
 def test_a_ticket_branch_that_cannot_be_checked_out_blocks_the_ticket(repo, tmp_path, capsys):
     """A slot of an earlier run with more slots still holds the branch."""
     blocked_then_edited(repo, tmp_path, capsys, phase="implement")
-    subprocess.run(["git", "worktree", "add", "-q", str(tmp_path.parent / f"{tmp_path.name}-other"), "ticket/01"], check=True)
+    subprocess.run(["git", "worktree", "add", "-q", str(tmp_path.parent / f"{tmp_path.name}-other"), "ticket/feat%2Fx/01"], check=True)
     code, ledger, _ = walk(tmp_path, capsys, "exit 9\n")
-    assert code == 1 and "BLOCKED at the start: cannot check out ticket/01 in slot 1" in ledger[-1]
+    assert code == 1 and "BLOCKED at the start: cannot check out ticket/feat%2Fx/01 in slot 1" in ledger[-1]
 
 
 def test_an_interrupt_kills_the_running_agents_and_stops_the_driver_at_once(repo, tmp_path, capsys, monkeypatch):
@@ -599,15 +704,62 @@ def test_an_interrupt_kills_the_running_agents_and_stops_the_driver_at_once(repo
     assert "interrupted; run it again to resume" in capsys.readouterr().out
 
 
-def test_a_second_driver_on_the_same_repository_exits_3_and_changes_nothing(repo, tmp_path, capsys):
+def hold(lock: Path):
+    """The lock of another driver: it holds the kernel lock while it runs."""
+    lock.parent.mkdir(parents=True, exist_ok=True)
+    held = lock.open("w")
+    fcntl.flock(held, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    return held
+
+
+def test_a_driver_on_another_pr_branch_does_not_stop_the_run(repo, tmp_path, capsys):
+    """Runs on different PR branches share no state.json, no slot and no ref, so the lock of one stops no other."""
+    repo(t01=ticket("01", **REFACTOR))
+    locks = Path(out_of("git", "rev-parse", "--git-common-dir")).resolve() / "implement-spec"
+    with hold(locks / "feat%2Fother.lock"), hold(locks / "feat.lock"):
+        code, _, out = walk(tmp_path, capsys, WORK + REPORT)
+    assert code == 0 and "1 of 1 tickets are merged into feat/x." in out
+    assert branches() == ["feat/x"]  # the merge deleted ticket/feat%2Fx/01
+
+
+def test_a_driver_that_starts_while_the_first_starts_its_run_locks_the_branch_of_that_run(repo, monkeypatch):
+    """Correctness review: right after the second driver reads HEAD, the first one writes state.json and puts slot 1
+    on a ticket branch. The PR branch that the second driver locks is still the one of that run."""
+    repo(t01=ticket("01", **REFACTOR))
+    real = driver.driver_slots.on_branch
+
+    def first_driver_moves(slot):
+        here = real(slot)
+        driver.STATE.parent.mkdir(parents=True, exist_ok=True)
+        driver.STATE.write_text(json.dumps({"run": {"pr_branch": "feat/x"}}))
+        subprocess.run(["git", "checkout", "-q", "-b", "ticket/feat%2Fx/01"], check=True)
+        return here
+    monkeypatch.setattr(driver.driver_slots, "on_branch", first_driver_moves)
+    assert driver._run_branch() == "feat/x"
+
+
+def test_a_run_that_leaves_its_branch_while_the_driver_takes_the_lock_exits_3(repo, tmp_path, capsys, monkeypatch):
+    repo(t01=ticket("01", **REFACTOR))
+    real = driver_state.lock
+
+    def lock_while_another_run_starts(path, shared=False):
+        driver.STATE.parent.mkdir(parents=True, exist_ok=True)
+        driver.STATE.write_text(json.dumps({"run": {"pr_branch": "feat/other", "schema": driver_state.SCHEMA}}))
+        return real(path, shared)
+    monkeypatch.setattr(driver_state, "lock", lock_while_another_run_starts)
+    code, ledger, out = walk(tmp_path, capsys, WORK + REPORT)
+    assert (code, ledger) == (3, []) and out == (
+        "implement-spec: the run in this worktree left feat/x while the driver took its lock: run the driver again\n")
+
+
+def test_a_second_driver_on_the_same_pr_branch_exits_3_and_changes_nothing(repo, tmp_path, capsys):
     """Final review, correctness 1: two drivers on one state.json lose updates and move the same refs. Ticket 09:
     the lock is in the git common directory, so it is the same file in every worktree of the repository."""
     repo(t01=ticket("01", **REFACTOR))
-    lock = Path(out_of("git", "rev-parse", "--git-common-dir")).resolve() / "implement-spec.lock"
-    with lock.open("w") as other:  # the first driver: it holds the kernel lock while it runs
-        fcntl.flock(other, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    lock = Path(out_of("git", "rev-parse", "--git-common-dir")).resolve() / "implement-spec/feat%2Fx.lock"
+    with hold(lock):
         code, ledger, out = walk(tmp_path, capsys, WORK + REPORT)
-        assert (code, out) == (3, "implement-spec: another driver runs in this repository: it holds the lock "
+        assert (code, out) == (3, "implement-spec: another driver runs on feat/x: it holds the lock "
                                   f"{lock}. Wait until it ends, then run the driver again.\n")
         assert ledger == [] and not (tmp_path / ".agent/implement").exists() and branches() == ["feat/x"]
         assert not Path(f"{tmp_path}-runner.calls").exists()
@@ -755,7 +907,11 @@ def test_a_merged_ticket_whose_commits_left_the_pr_branch_is_not_merged_on_a_rer
     assert code == 1 and f"End of run: BLOCKED at feat/x does not hold the tidied tip {tip}" in out, out
 
 
-def test_a_rerun_after_an_interrupt_keeps_the_work_in_each_slot_and_reruns_the_role(repo, tmp_path, capsys, monkeypatch):
+@pytest.mark.parametrize("older_driver", [False, True])
+def test_a_rerun_after_an_interrupt_keeps_the_work_in_each_slot_and_reruns_the_role(repo, tmp_path, capsys, monkeypatch,
+                                                                                      older_driver):
+    """With `older_driver`, the interrupted run is one whose driver named the ticket branches `ticket/NN` (spec
+    review): the resume renames each one, also in the slot that has it, and the slot keeps its work."""
     two(repo)
     mark = f"{tmp_path.parent}/{tmp_path.name}-started"
 
@@ -776,6 +932,8 @@ def test_a_rerun_after_an_interrupt_keeps_the_work_in_each_slot_and_reruns_the_r
             walk(tmp_path, capsys, hang)
     slot2 = tmp_path / ".agent/worktrees/slot-2"
     assert (tmp_path / "wip-01.txt").exists() and (slot2 / "wip-02.txt").exists()
+    if older_driver:
+        as_older_driver(tmp_path, "01", "02")
     resume = ('grep -q "was interrupted" "$prompt" || exit 9\nnn=$(basename "$(dirname "$report")")\n'
               '[ "$(cat wip-$nn.txt)" = half ] || exit 8\n')
     code, ledger, out = walk(tmp_path, capsys, resume + WORK + REPORT)
@@ -785,6 +943,8 @@ def test_a_rerun_after_an_interrupt_keeps_the_work_in_each_slot_and_reruns_the_r
     assert out_of("git", "show", "feat/x:wip-01.txt") == "half" and out_of("git", "show", "feat/x:wip-02.txt") == "half"
     assert [line for line in ledger if "Ticket 02: resumed in slot 2 with the work the interrupted implementer left" in line]
     assert out_of("git", "status", "--porcelain") == "" and branches() == ["feat/x"]
+    renamed = [f"Ticket {nn}: renamed the branch ticket/{nn} of an older driver to ticket/feat%2Fx/{nn}." for nn in ("01", "02")]
+    assert [line for line in ledger if "renamed the branch" in line] == (renamed if older_driver else [])
 
 
 def test_the_preflight_asks_each_used_entry_once_and_names_each_cli_that_fails(tmp_path, monkeypatch):

package/skills/implement-spec/tests/test_final.py

@@ -10,7 +10,7 @@ Interface choices (ticket 06):
   the rebase and the push (ticket 08): test_amendments.py holds those tests.
 - its agents report into `.agent/implement/final/`, so the fake runner keys them `final/final-reviewer`,
   `final/fixer` and `final/conflict`; gate records there are `gate-<first 7 hex>.log`.
-- recovery point: before the rebase the driver sets `refs/implement/recovery` to the PR tip and writes the ledger
+- recovery point: before the rebase the driver sets `refs/implement-spec/feat%2Fcsv/recovery` to the PR tip and writes the ledger
   sentence "Recovery point: ... <sha>". An ended run leaves the ref in place.
 - a tidied commit has the subject `feat(NN): <ticket title>` and a body line `Ticket: <ticket file name>`.
 - the final fixer's `commits` hold `{"sha", "ticket"}` objects, and the driver renames each fixer commit to
@@ -44,7 +44,7 @@ if step.get("hold"):
     before = git("rev-parse", "feat/csv")
     time.sleep(step["hold"])
     rec["held"] = dict(before=before, after=git("rev-parse", "feat/csv"),
-                       recovery=git("rev-parse", "--verify", "-q", "refs/implement/recovery"))
+                       recovery=git("rev-parse", "--verify", "-q", "refs/implement-spec/feat%2Fcsv/recovery"))
 for cmd in step.get("git", []):''', 1).replace(
     'sha = ""\nif "commit" in step:',
     '''sha = ""
@@ -142,7 +142,7 @@ class Final(Review):
         return ref(self.repo, "feat/csv")
 
     def recovery(self):
-        return ref(self.repo, "refs/implement/recovery")
+        return ref(self.repo, "refs/implement-spec/feat%2Fcsv/recovery")
 
     def commits(self, base, tip="feat/csv"):
         raw = git(self.repo, "log", "--reverse", "--no-merges", "--format=%H%x1f%s%x1f%b%x1e", f"{base}..{tip}")
@@ -223,7 +223,7 @@ def test_seven_commits_in_merge_order_are_tidied_into_three_ticket_commits_with_
     rows = rig.commits(rig.start)
     assert [r["subject"] for r in rows] == [f"feat({nn}): {TITLES[nn]}" for nn in ("01", "03", "02")]
     assert all(f"Ticket: {FILES[nn]}" in r["body"] for nn, r in zip(("01", "03", "02"), rows))
-    assert ref(rig.repo, "feat/csv^{tree}") == ref(rig.repo, "refs/implement/recovery^{tree}")
+    assert ref(rig.repo, "feat/csv^{tree}") == ref(rig.repo, "refs/implement-spec/feat%2Fcsv/recovery^{tree}")
 
 
 def test_one_gate_record_exists_for_the_tidied_tip_and_the_final_reviewer_is_pointed_at_it(story):
@@ -440,7 +440,7 @@ def test_unattended_with_everything_validated_pushes_once_opens_the_pr_and_write
 
 
 def test_unattended_with_a_blocked_ticket_pushes_nothing_and_exits_1(tmp_path):
-    rig = Final(tmp_path, THREE, gate={"red": ["ticket/01"]})
+    rig = Final(tmp_path, THREE, gate={"red": ["ticket/feat%2Fcsv/01"]})
     rig.run(plan(), *UNATTENDED)
     assert rig.code == 1, rig.output()
     assert rig.pushes() == [] and not rig.prs() and not ref(rig.origin, "refs/heads/feat/csv")