@jesdi/skills 0.0.44 → 0.0.46

package/skills/implement-spec/driver_review.py

@@ -7,8 +7,10 @@ A mutation proof is keyed by (production file, line); the line is the one the fi
 from __future__ import annotations
 
 import re
+from pathlib import Path
+
 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.
@@ -131,7 +133,27 @@ 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 ""
+
+
+def _read(config: Path) -> bytes:
+    return config.read_bytes() if config.exists() else b""
+
+
+def shared_config(slot: str) -> tuple[Path, bytes]:
+    """(the git config file that every worktree of the repository shares, its bytes)."""
+    common = git(slot, "rev-parse", "--path-format=absolute", "--git-common-dir").stdout.strip()
+    return Path(common, "config"), _read(Path(common, "config"))
+
+
+def restore_config(before: tuple[Path, bytes]) -> str:
+    """"" when the shared git config is still `before` (from `shared_config`), else write it back and say so.
+    One worktree that writes the config breaks git in all of them, as a core.worktree on a gone directory does."""
+    config, data = before
+    if _read(config) == data:
+        return ""
+    config.write_bytes(data)
+    return f"the shared git config {config} changed"

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()
 
@@ -115,15 +120,15 @@ class Run:
     def read_only(self, number: str, slot: str, branch: str, tip: str, review: Callable[[], T]) -> T:
         """Run `review` (read-only agents) and return its result. A review that changes the slot runs once more."""
         for last in (False, True):
-            error = ""
+            error, config = "", driver_review.shared_config(slot)
             try:
                 result = review()
             except Blocked as blocked:
                 error = str(blocked)
             except Halted:
-                _restore_if_changed(number, slot, branch, tip, runs_again=False)
+                _restore_if_changed(number, slot, branch, tip, config, runs_again=False)
                 raise
-            left = _restore_if_changed(number, slot, branch, tip, runs_again=not (error or last))
+            left = _restore_if_changed(number, slot, branch, tip, config, runs_again=not (error or last))
             if error or not left:
                 break
         if error or left:
@@ -177,22 +182,28 @@ class Run:
         return paths
 
 
-def _restore_if_changed(number: str, slot: str, branch: str, tip: str, runs_again: bool) -> str:
-    """After read-only agents: "" when the slot is as it was; else restore it and return what they left."""
-    left = driver_review.disturbed(slot, branch, tip)
-    if left:
+def _restore_if_changed(number: str, slot: str, branch: str, tip: str, config: tuple[Path, bytes],
+                        runs_again: bool) -> str:
+    """After read-only agents: "" when the slot and the shared git config (`driver_review.shared_config` before
+    them) are as they were; else restore both and return what they left."""
+    # The config first: a bad core.worktree in it breaks the git commands of the slot check.
+    changed = driver_review.restore_config(config)
+    moved = driver_review.disturbed(slot, branch, tip)
+    if moved:
         driver_review.restore(slot, branch, tip)
-        where, what = ("slot 1", "the final review") if number == FINAL else ("the slot", "the review")
-        again = f" and runs {what} again" if runs_again else ""
-        ledger(f"{_owner(number)}: a read-only role broke its rule: {left}; the driver restored {where} to "
-               f"{tip[:7]}{again}.")
+    left = "; ".join(filter(None, (changed, moved)))
+    if left:
+        where = ("slot 1" if number == FINAL else "the slot") + f" to {tip[:7]}"
+        restored = " and ".join(filter(None, ("the shared git config" if changed else "", where if moved else "")))
+        again = f" and runs {'the final review' if number == FINAL else 'the review'} again" if runs_again else ""
+        ledger(f"{_owner(number)}: a read-only role broke its rule: {left}; the driver restored {restored}{again}.")
     return left
 
 
 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/correctness.md

@@ -32,4 +32,6 @@ Write one JSON report at {report}. When your sandbox is read-only, give the JSON
 }
 ```
 
+Run git as plain `git` in this worktree, and leave the git config as it is: all worktrees read one shared config, and one key written there, such as a `core.worktree`, breaks git in each of them. So never set GIT_DIR or GIT_WORK_TREE, and never write with `git config`.
+The gate record of the driver for {start_sha} is {gate_record}.
 Never run `git stash`, never reset, and never check out another branch: worktrees share one stash and one ref store.

package/skills/implement-spec/prompts/final-reviewer.md

@@ -12,7 +12,7 @@ Minor findings that the ticket reviews left for this review, each with its findi
 Rulings of the operator:
 {rulings}
 
-Review the range with the method of the review-diff skill in the file above, with the spec as its spec path. The gate of that method is done: check that the gate record names {start_sha}, a clean status and exit 0, and run the gate yourself only when it does not.
+Review the range with the method of the review-diff skill in the file above, with the spec as its spec path. The gate of that method is done: check that the gate record names {start_sha}, a clean status and exit 0, and run the gate yourself, in a copy as below, only when it does not.
 Decide for each minor finding in the list whether it is still true at {start_sha}; report each one that is, with the severity it has now. A ruling is settled: do not report what a ruling accepted.
 Give each finding a severity (critical, important or minor), the file and line, a title, the evidence, and a kind: `code`, `test`, or `fixture`.
 Do not commit. Leave the branch and the tree as you found them.
@@ -33,4 +33,6 @@ Write one JSON report at {report} that matches this schema:
 }
 ```
 
+Run git as plain `git` in this worktree, and leave the git config as it is: all worktrees read one shared config, and one key written there, such as a `core.worktree`, breaks git in each of them. So never set GIT_DIR or GIT_WORK_TREE, and never write with `git config`.
+To run a check off this worktree, read the gate record of the driver, {gate}, or make a copy with `git worktree add --detach <temp dir> {start_sha}`, run the check there, and remove the copy with `git worktree remove --force <temp dir>` before you report.
 Never run `git stash`, never reset, and never check out another branch: worktrees share one stash and one ref store.

package/skills/implement-spec/prompts/pr-writer.md

@@ -28,4 +28,5 @@ Write one JSON report at {report} that matches this schema:
 }
 ```
 
+Run git as plain `git` in this worktree, and leave the git config as it is: all worktrees read one shared config, and one key written there, such as a `core.worktree`, breaks git in each of them. So never set GIT_DIR or GIT_WORK_TREE, and never write with `git config`.
 Never run `git stash`, never reset, and never check out another branch: worktrees share one stash and one ref store.

package/skills/implement-spec/prompts/reviewer.md

@@ -31,4 +31,6 @@ Write one JSON report at {report}. When your sandbox is read-only, give the JSON
 }
 ```
 
+Run git as plain `git` in this worktree, and leave the git config as it is: all worktrees read one shared config, and one key written there, such as a `core.worktree`, breaks git in each of them. So never set GIT_DIR or GIT_WORK_TREE, and never write with `git config`.
+To run a check off this worktree, read the gate record of the driver, {gate_record}, or make a copy with `git worktree add --detach <temp dir> {start_sha}`, run the check there, and remove the copy with `git worktree remove --force <temp dir>` before you report.
 Never run `git stash`, never reset, and never check out another branch: worktrees share one stash and one ref store.

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