@jesdi/skills 0.0.43 → 0.0.45

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]:
@@ -82,16 +78,21 @@ def refused(tickets: dict, number: str, old: str, new: str) -> str:
                                         if before.get(path) != after.get(path))
 
 
+def changed(slot: str, pr_tip: str, paths: list[str]) -> list[str]:
+    """Each of `paths` that the ticket changed in the tree of `slot`."""
+    # Against the merge base: a file that only the PR branch changed since then is not the ticket's change.
+    base = git(slot, "merge-base", "HEAD", pr_tip).stdout.strip() or pr_tip
+    return names(git(slot, "diff", "--name-only", "-z", base, "--", *paths).stdout) if paths else []
+
+
 def restore(slot: str, pr_tip: str, paths: list[str]) -> list[str]:
     """Put each of `paths` that the ticket changed back to the version of the PR tip, in the tree of `slot` only; a
     file the PR tip does not have is removed. Returns those paths."""
-    # Against the merge base: a file that only the PR branch changed since then is not the ticket's change.
-    base = git(slot, "merge-base", "HEAD", pr_tip).stdout.strip() or pr_tip
-    changed = names(git(slot, "diff", "--name-only", "-z", base, "--", *paths).stdout) if paths else []
-    for path in changed:
+    restored = changed(slot, pr_tip, paths)
+    for path in restored:
         if git(slot, "checkout", "-q", pr_tip, "--", path).returncode:
             git(slot, "rm", "-q", "-f", "--", path)
-    return changed
+    return restored
 
 
 def land(pr_branch: str, new: str, old: 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"

package/skills/implement-spec/driver_report.py

@@ -2,6 +2,7 @@
 
 context: repo (slot path), branch, start (HEAD when the role started), log, round (1 = first review), locked,
   correction (a test-writer corrects locked tests), restored (locked files the driver put back before it),
+  restore_red (the gate is red on the commit of that restore),
   owners (ticket numbers, for the final fix batch), merged (locked files of merged tickets, not its own), pr (tip)."""
 from __future__ import annotations
 
@@ -66,8 +67,14 @@ def _correction_errors(report: dict, context: dict) -> list[str]:
         return []
     changed = _git(context["repo"], "diff", "--name-only", "-z", context["start"], context["branch"], end="\0")
     more = [path for path in changed if path not in report.get("locked", []) + context.get("restored", [])]
-    return [f"a correction may change only the files it lists in `locked`: its commits also change {', '.join(more)}"
-            ] if more else []
+    errors = [f"a correction may change only the files it lists in `locked`: its commits also change {', '.join(more)}"
+              ] if more else []
+    if context.get("restore_red") and report["status"] in ("DONE", "DONE_WITH_CONCERNS") and not (
+            set(report["locked"]) & set(context["restored"])):
+        errors.append("the gate is red on the restore commit, so a restored file fails with the code of this ticket: "
+                      "update that file and list it in `locked`, or report BLOCKED with a concern that starts with "
+                      "`locked test contradicts spec:`")
+    return errors
 
 
 def _merged_errors(report: dict, context: dict) -> list[str]:

package/skills/implement-spec/driver_review.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 
 import re
 import driver_agents
-from driver_slots import git, head, names
+from driver_slots import git, head, names, on_branch
 from driver_tickets import Ticket
 
 # The correctness pass reads this file of the review-diff skill, which is installed next to this one.
@@ -38,6 +38,14 @@ def locked_changes(slot: str, sha: str | None, locked: list[str]) -> list[dict]:
              "evidence": f"git diff {sha}..HEAD -- {path}"} for path, title in titles.items()]
 
 
+def merged_changes(paths: list[str]) -> list[dict]:
+    """One critical `fixture` finding per locked file of a merged ticket that the ticket changed. A fixture finding
+    goes to a test-writer correction: the driver puts the file back before it and gates that commit."""
+    return [{"severity": "critical", "file": path, "line": 1, "kind": "fixture", "source": "driver",
+             "title": f"the ticket changed the locked file of a merged ticket: {path}",
+             "evidence": f"git diff <merge base with the PR branch> -- {path}"} for path in paths]
+
+
 def _references(entry: dict) -> list[tuple[str | None, list[str]]]:
     """(reference commit, the locked files it is the reference of): `test_writer_sha`, or the older commit that
     `held` names for a file."""
@@ -123,7 +131,7 @@ def restore(slot: str, branch: str, tip: str) -> None:
 
 def disturbed(slot: str, branch: str, tip: str) -> str:
     """"" when the slot is still on `branch` at `tip` with a clean tree, else what the read-only agents left."""
-    if git(slot, "symbolic-ref", "-q", "--short", "HEAD").stdout.strip() != branch or head(slot) != tip:
+    if on_branch(slot) != branch or head(slot) != tip:
         return f"the slot is no longer on {branch} at {tip[:7]}"
     left = [line[3:] for line in git(slot, "status", "--porcelain").stdout.splitlines()]
     return f"the tree is not as the review found it: {', '.join(left)}" if left else ""

package/skills/implement-spec/driver_run.py

@@ -24,6 +24,7 @@ import driver_report
 import driver_review
 import driver_slots
 import driver_state
+from driver_names import Names
 from driver_slots import git, names
 
 OUT = Path(".agent/implement")
@@ -88,6 +89,10 @@ class Run:
     asks: dict[str, Ask] = field(default_factory=dict)  # ticket number -> its pending stop
     halted: list[str] = field(default_factory=list)  # why the run starts no other agent; [] while it goes on
 
+    @property
+    def names(self) -> Names:
+        return Names(self.pr)
+
     def tip(self) -> str:
         return git(".", "rev-parse", f"refs/heads/{self.pr}").stdout.strip()
 
@@ -191,8 +196,8 @@ def _restore_if_changed(number: str, slot: str, branch: str, tip: str, runs_agai
 
 def _reset_if_moved(slot: str, branch: str, tip: str) -> str:
     """After an agent: "" when the slot is on `branch` and still holds `tip`; else reset it and say what was wrong."""
-    head = git(slot, "symbolic-ref", "-q", "--short", "HEAD").stdout.strip()
-    if git(slot, "rev-parse", "-q", "--verify", f"refs/heads/{branch}").returncode:
+    head = driver_slots.on_branch(slot)
+    if not driver_slots.branch_exists(branch):
         problem = f"branch {branch} is missing"
     elif head != branch:
         problem = f"HEAD is on {head or 'a detached commit'} instead of {branch}"

package/skills/implement-spec/driver_slots.py

@@ -22,6 +22,19 @@ def head(slot: str) -> str:
     return git(slot, "rev-parse", "HEAD").stdout.strip()
 
 
+def on_branch(slot: str) -> str:
+    """The branch the slot has checked out; "" when its HEAD is detached."""
+    return git(slot, "symbolic-ref", "-q", "--short", "HEAD").stdout.strip()
+
+
+def ancestor(commit: str, of: str) -> bool:
+    return git(".", "merge-base", "--is-ancestor", commit, of).returncode == 0
+
+
+def branch_exists(branch: str) -> bool:
+    return git(".", "rev-parse", "-q", "--verify", f"refs/heads/{branch}").returncode == 0
+
+
 def path(number: int) -> str:
     return "." if number == 1 else f".agent/worktrees/slot-{number}"
 

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/prompts/restored-red.md

@@ -0,0 +1,3 @@
+
+The driver ran the gate on that commit, {start_sha}, and the gate is red: read the output in {record}. The gate was green before the restore, so a restored file fails with the code of this ticket.
+Update each restored file that fails so that it works with the new interface: keep what each test asserts, and list the file in `locked`. When no such update can keep what a test asserts, report BLOCKED with a concern that starts with `locked test contradicts spec:`, then the test and the evidence.

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")