@jesdi/skills 0.0.45 → 0.0.46

package/package.json

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

package/skills/implement-spec/ARCHITECTURE.md

@@ -98,8 +98,10 @@ and do not know about the run, except `driver_run.py`, which the three deciding
 ### Work is never dropped
 
 - A role that commits keeps its tree after a timeout or an interrupt; its rerun continues from it.
-- A read-only role (reviewer, correctness, final-reviewer, pr-writer) has no work to keep. When it changes its slot, the
-  driver restores the slot and runs the review one more time (`Run.read_only`).
+- A read-only role (reviewer, correctness, final-reviewer, pr-writer) has no work to keep. When it changes its slot or
+  the shared git config, the driver restores them and runs the review one more time (`Run.read_only`). The config is
+  a byte copy taken before the role (`driver_review.shared_config`): every worktree reads that one file, so a key a
+  role writes there, such as a `core.worktree` on a temp directory, breaks git in all of them.
 - A slot with uncommitted work of an interrupted or parked ticket is kept for that ticket (`driver_state.kept`).
 - A blocked ticket keeps its slot when the slot is not clean.
 

package/skills/implement-spec/README.md

@@ -100,7 +100,7 @@ A ticket is ready when each ticket in its **Blocked by** line is merged and no r
 1. **test-writer** (`prompts/test-writer.md`). It writes one black-box test for each criterion through the Seam and commits them red. Those files are locked. A ticket with Seam `none — refactor` has no test-writer.
 2. **implementer** (`prompts/implementer.md`). It starts from that commit and makes the locked tests green. It makes the gate (`--gate`) green on its final commit before it reports DONE or DONE_WITH_CONCERNS.
 3. **Gate.** The driver runs `--gate` on the ticket tip.
-4. **Review.** The driver compares each locked file of the ticket with the test-writer commit. A file that differs is a critical finding `locked file changed: <path>`. A locked file of a merged ticket that the ticket changed since its merge base with the PR branch is a critical `fixture` finding `the ticket changed the locked file of a merged ticket: <path>`, so it goes to a correction (see **Before a correction**). Then the **reviewer** (`prompts/reviewer.md`) runs, and for a ticket with a **Risk** line the **correctness** pass (`prompts/correctness.md`) runs at the same time in the same slot.
+4. **Review.** The driver compares each locked file of the ticket with the test-writer commit. A file that differs is a critical finding `locked file changed: <path>`. A locked file of a merged ticket that the ticket changed since its merge base with the PR branch is a critical `fixture` finding `the ticket changed the locked file of a merged ticket: <path>`, so it goes to a correction (see **Before a correction**). Then the **reviewer** (`prompts/reviewer.md`) runs, and for a ticket with a **Risk** line the **correctness** pass (`prompts/correctness.md`) runs at the same time in the same slot. A read-only role (reviewer, correctness, final-reviewer, pr-writer) leaves its slot and the git config as it found them: all worktrees share one config, and one key written there, such as a `core.worktree` on a temp directory, breaks git in each of them. To run a check off the slot, a reviewer reads the driver's gate record or makes its own `git worktree add --detach` copy and removes it. After read-only roles, the driver checks the slot and the shared config (`git rev-parse --git-common-dir`, then `config`) against what they were before. When one of them changed, the driver restores it, writes `a read-only role broke its rule: ...` to the ledger, and runs the review one more time; a second change blocks the ticket.
 5. **Merge.** The driver merges the reviewed tip into the PR branch with git plumbing, then deletes the ticket branch. A conflict goes to the **conflict** agent (`prompts/conflict.md`) once. Its resolution may change no locked file of the ticket. A second conflict blocks the ticket.
    **The landing check.** Merges are serial. Before the PR branch moves, the driver compares the tree that is about to land (the ticket tip of a fast-forward, or the merge commit) with the PR tip: each locked file of each merged ticket must be the same tree entry in both: the same blob with the same mode, so a file that became a symlink is a difference. A file that only one of them has is a difference. A file that the landing ticket lists in its own `locked` is not checked: the test-writer of a later ticket can add a test to a file that an earlier ticket locked, and must list that file. A test-writer report that changes such a file and does not list it is rejected, with the usual one rerun. The review finds such a change first; the landing check catches a change that no review saw, for example of a ticket that merged after the last review. A difference refuses the landing: the ticket is BLOCKED with `locked file changed: <path>` in the ledger, the PR branch does not move, and no fix round runs. The PR branch moves only from the tip that the check read; when another hand moved the branch in between, the driver makes the merge, the check and the gate again, one time. Only that case starts the landing again: a refused landing and a red merge gate block the ticket. The second try runs no conflict agent, so a conflict there blocks the ticket, and so does a branch that moved again.
    **Before a correction.** A test-writer that corrects locked tests (after `overrule-test`, or for a `fixture` finding or a `test` finding on a locked file) starts from the locked versions: the driver puts back each locked file of the ticket and each locked file of a merged ticket that the ticket changed, commits them in one commit of its own, and the ledger names each file. A file of a merged ticket goes back to the version of the PR branch. The commit keeps the tree of the next fixer and of the gate clean, whatever files the correction commits. The correction's prompt names the restored files: when a test in one of them fails only because the ticket changed an interface that the test uses, the correction updates the file to the new interface, keeps what each test asserts, and lists the file in `locked`.

package/skills/implement-spec/driver.py

@@ -26,6 +26,7 @@ import driver_answers
 import driver_decisions
 import driver_final
 import driver_fixloop
+import driver_gate
 import driver_graph
 import driver_legacy
 import driver_merge
@@ -109,7 +110,7 @@ def _run_roles(ticket: Ticket, slot_number: int, run: Run) -> None:
     values = {**_prompt_values(ticket, slot, run), "locked": " ".join(entry["locked"])}
     for role in roles:
         run.state.ticket(number, phase=DURING.get(role, "review"))
-        values["start_sha"] = start
+        values.update(start_sha=start, gate_record=os.path.relpath(driver_gate.record_path(OUT / number, start), slot))
         # A test-writer on a ticket that has locked tests is the correction after a ruling.
         check = {"correction": role == "test-writer" and bool(entry["test_writer_sha"])}
         if check["correction"] and (restored := run.restore_locked_files(number, slot)):

package/skills/implement-spec/driver_final.py

@@ -26,6 +26,7 @@ from pathlib import Path
 
 import driver_agents
 import driver_decisions
+import driver_gate
 import driver_merge
 import driver_review
 import driver_tidy
@@ -325,7 +326,7 @@ def _review(run: Run, final: dict, tip: str) -> None:
     """One round of the final review on `tip`: the full review, or after it the scoped one."""
     done, folder = final["round"], OUT / FINAL
     values = {**_prompt_values(run), "start_sha": tip, "range": f"{final['reviewed'] or final['onto']}..{tip}",
-              "gate": str(folder / f"gate-{tip[:7]}.log"), "review_diff": str(REVIEW_DIFF),
+              "gate": str(driver_gate.record_path(folder, tip)), "review_diff": str(REVIEW_DIFF),
               "ledger": str(OUT / "ledger.md"), "minors": _minor_findings(), "reviewed": str(final["reviewed"]),
               "rulings": "\n".join(driver_decisions.rulings(run.state.read()["run"]["questions"])),
               "findings": str(folder / f"findings-{done - 1}.json")}
@@ -441,7 +442,7 @@ def _write_body(run: Run, final: dict, tickets: list[Ticket]) -> Path:
         raise Blocked("the pr skill is missing: the PR body follows it; install it with "
                       "`npx skills add mattpocock/skills --skill pr`")
     values = {**_prompt_values(run), "start_sha": tip, "range": f"{final['onto']}..{tip}",
-              "gate": str(OUT / FINAL / f"gate-{tip[:7]}.log"), "pr_skill": str(method), "facts": facts}
+              "gate": str(driver_gate.record_path(OUT / FINAL, tip)), "pr_skill": str(method), "facts": facts}
     with during("the PR body"):
         report = run.read_only(FINAL, ".", run.pr, tip, lambda: run.agent("pr-writer", FINAL, ".", values))
     body.write_text(f"{report['body'].strip()}\n\n{facts}")

package/skills/implement-spec/driver_fixloop.py

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

package/skills/implement-spec/driver_gate.py

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

package/skills/implement-spec/driver_review.py

@@ -7,6 +7,8 @@ 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, on_branch
 from driver_tickets import Ticket
@@ -135,3 +137,23 @@ def disturbed(slot: str, branch: str, tip: str) -> str:
         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

@@ -120,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:
@@ -182,15 +182,21 @@ 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
 
 

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_fixloop.py

@@ -562,6 +562,23 @@ def test_a_second_review_that_changes_the_slot_blocks_the_ticket_with_the_slot_c
     assert slot_state(rig) == ("", rig.sha("01", "implementer")) and "feat: 01 rows" not in rig.pr_subjects()
 
 
+def test_a_reviewer_that_writes_the_shared_git_config_gets_it_restored_and_runs_once_more(tmp_path):
+    # Issue #94: a reviewer ran git with GIT_DIR on the real git dir and left core.worktree on a deleted temp dir.
+    rig = Inside(tmp_path)
+    shared = rig.repo / ".git" / "config"
+    config = shared.read_bytes()
+    gone = {"git": [["config", "core.worktree", str(tmp_path / "gone")]]}
+    rig.run(plan(**{"01/reviewer": [{**review("01"), **gone}, review("01")]}))
+    assert rig.code == 0, rig.ledger()
+    assert shared.read_bytes() == config
+    (line,) = rig.led("Ticket 01: a read-only role broke its rule:")
+    assert f"the shared git config {shared.resolve()} changed" in line
+    assert line.endswith("the driver restored the shared git config and runs the review again.")
+    tip, prompt = rig.sha("01", "implementer"), rig.prompt("reviewer-0")
+    assert len(rig.calls("01", "reviewer")) == 2 and rig.tip() == tip
+    assert f".agent/implement/01/gate-{tip[:7]}.log" in prompt and "never write with `git config`" in prompt
+
+
 def test_a_reviewer_that_times_out_starts_again_from_the_clean_tip(tmp_path):
     hang = {"files": {"demo/export.py": "mutated\n", "junk.txt": "x\n"}, "sleep": 60}
     rig = Inside(tmp_path).run(plan(**{"01/reviewer": [hang, review("01")]}), "--timeout", "reviewer=0.03")

package/skills-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-10-17T06:40:10.976Z",
+  "generatedAt": "2026-10-17T15:47:59.977Z",
   "skills": [
     {
       "name": "backlog",
@@ -46,8 +46,8 @@
     },
     {
       "name": "implement-spec",
-      "version": "0.1.21",
-      "hash": "sha256-ffca735547ff5f7664f80fe98071d1956f839858ee4f1964ef9b7957af41a4cc",
+      "version": "0.1.22",
+      "hash": "sha256-66e2dec93c2b4ca09e8ca6693307e5e92f46fe1bd9b0a44379e7d4a4bd82d3f9",
       "description": "Implement a specification in code."
     },
     {