@jesdi/skills 0.0.30 → 0.0.31

package/skills/implement-spec/driver_tidy.py

@@ -0,0 +1,57 @@
+"""History of the PR branch as commits made with git plumbing: the tidy into one commit per ticket, and the new
+messages of a rebased history and of a fix batch.
+
+Nothing here checks out a tree or moves a ref: a new commit takes the tree of an existing commit.
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+
+import driver_merge
+from driver_slots import git
+from driver_tickets import Ticket
+
+
+def message(ticket: Ticket) -> str:
+    return f"feat({ticket.number}): {ticket.title}\n\nTicket: {ticket.file}\n"
+
+
+def text(commit: str) -> str:
+    """The message of `commit`."""
+    return git(".", "log", "-1", "--format=%B", commit).stdout
+
+
+def same_tree(one: str, other: str) -> bool:
+    """Both commits exist and have the same tree."""
+    trees = [git(".", "rev-parse", "-q", "--verify", f"{commit}^{{tree}}").stdout.strip() for commit in (one, other)]
+    return bool(trees[0]) and trees[0] == trees[1]
+
+
+def _commit(source: str, parent: str, words: str) -> str:
+    """A commit on `parent` with the tree and the author of `source` and the message `words`; "" when git fails."""
+    name, email, date = git(".", "log", "-1", "--format=%an%n%ae%n%aI", source).stdout.splitlines() or [""] * 3
+    env = {**os.environ, **driver_merge.identity(source), "GIT_AUTHOR_NAME": name, "GIT_AUTHOR_EMAIL": email,
+           "GIT_AUTHOR_DATE": date}
+    made = subprocess.run(["git", "commit-tree", f"{source}^{{tree}}", "-p", parent, "-m", words.strip() + "\n"],
+                          capture_output=True, text=True, env=env)
+    return made.stdout.strip()
+
+
+def rewrite(parent: str, steps: list[tuple[str, str]]) -> list[str]:
+    """One commit per (source commit, message), in a line on `parent`: each has the tree of its source."""
+    made = []
+    for source, words in steps:
+        parent = _commit(source, parent, words)
+        made.append(parent)
+    return made
+
+
+def tidy(parent: str, landed: list[list[str]], tickets: dict[str, Ticket]) -> dict[str, str]:
+    """ticket number -> its one commit, in a line on `parent`; a merge that changed no file gets the one before it."""
+    commits = {}
+    for number, source in landed:
+        if not same_tree(source, parent):
+            parent = _commit(source, parent, message(tickets[number]))
+        commits[number] = parent
+    return commits

package/skills/implement-spec/models.json

@@ -0,0 +1,10 @@
+{
+  "explorer": ["claude-sonnet-5@medium"],
+  "test-writer": ["claude-sonnet-5@medium", "openai/gpt-sol@medium"],
+  "implementer": ["claude-sonnet-5@medium", "openai/gpt-sol@medium"],
+  "reviewer": ["openai/gpt-astra@medium", "claude-opus-5@medium"],
+  "correctness": ["openai/gpt-astra@medium", "claude-opus-5@medium"],
+  "fixer": ["claude-opus-5@medium"],
+  "final-reviewer": ["openai/gpt-astra@medium", "claude-opus-5@medium"],
+  "conflict": ["claude-opus-5@medium"]
+}

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

@@ -0,0 +1,32 @@
+# Conflict
+
+Spec: {spec}
+Ticket: {ticket}
+Branch: {branch}, at commit {start_sha}
+PR branch: {pr_branch}, at commit {pr_sha}
+Files in conflict: {files}
+
+The merge of the PR branch into the ticket branch is open in this worktree and it has conflicts in those files.
+Resolve each conflict so that the behavior of both sides holds: the spec and the ticket say what each side is for. Change nothing that the resolution does not need.
+Run the targeted tests of the files you resolved. The driver runs the gate on your commit.
+Finish the merge with `git commit` on the checked-out ticket branch. Do not abort the merge and do not dispatch subagents.
+In `files`, give each file you resolved.
+
+Write one JSON report at {report} that matches this schema:
+
+```json
+{
+  "type": "object",
+  "required": ["status", "commits", "files", "concerns"],
+  "properties": {
+    "status": {"enum": ["DONE", "DONE_WITH_CONCERNS", "NEEDS_CONTEXT", "BLOCKED"]},
+    "commits": {"type": "array", "items": {"type": "string", "pattern": "^[0-9a-f]{7,40}$"}},
+    "files": {"type": "array", "items": {"type": "string"}},
+    "concerns": {"type": "array", "items": {"type": "string"}}
+  },
+  "if": {"properties": {"status": {"enum": ["DONE", "DONE_WITH_CONCERNS"]}}},
+  "then": {"properties": {"commits": {"minItems": 1}}}
+}
+```
+
+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/correction.md

@@ -0,0 +1,4 @@
+
+This call is a fixture correction, not a new test. The review found that a locked test encodes a stale path, format, fixture layout or setup detail: read each finding of kind `fixture` in {findings}.
+Correct only that detail in the locked test file and keep what each test asserts. For this you may read the implementation.
+The implementation exists, so a corrected test is green: for `red`, break the production line that the test protects, run the test, print its failing output, then revert the edit. In `locked`, list each test file you corrected.

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

@@ -0,0 +1,34 @@
+# Correctness pass
+
+Spec: {spec}
+Ticket: {ticket}
+Seam: {seam}
+Range: {pr_branch}...{branch}, with the ticket tip at {start_sha}
+Locked files: {locked}
+Checks: {correctness}
+
+Read the checks file and apply each of its checks to the diff of the range, with the Risk line of the ticket first: races, idempotency, time, authorization, persistence keys and identities, migrations, error paths.
+The output section of the checks file does not apply here: your findings go into the report.
+Read file content from git at {start_sha} (`git diff`, `git show {start_sha}:<path>`), never from the working tree, and run no tests: another agent makes temporary edits in this worktree while you work.
+Report only a defect that you can show with a concrete sequence of events. `mutations` is optional for this pass.
+Give each finding a severity (critical, important or minor), the file and line, a title, the evidence, and a kind: `code`, `test`, or `fixture` when a locked test encodes a stale path, format or setup detail.
+Do not commit and do not dispatch subagents. Leave the tree as you found it.
+
+Write one JSON report at {report}. When your sandbox is read-only, give the JSON as your whole final message and the driver saves it there. The report matches this schema:
+
+```json
+{
+  "type": "object",
+  "required": ["status", "commits", "files", "concerns", "findings"],
+  "properties": {
+    "status": {"enum": ["DONE", "DONE_WITH_CONCERNS", "NEEDS_CONTEXT", "BLOCKED"]},
+    "commits": {"type": "array", "items": {"type": "string", "pattern": "^[0-9a-f]{7,40}$"}},
+    "files": {"type": "array", "items": {"type": "string"}},
+    "concerns": {"type": "array", "items": {"type": "string"}},
+    "findings": {"type": "array", "items": {"type": "object", "required": ["severity", "file", "line", "title", "evidence", "kind"], "properties": {"severity": {"enum": ["critical", "important", "minor"]}, "file": {"type": "string"}, "line": {"type": "integer"}, "title": {"type": "string", "minLength": 1}, "evidence": {"type": "string", "minLength": 1}, "kind": {"enum": ["code", "fixture", "test"]}}}},
+    "mutations": {"type": "array", "items": {"type": "object", "required": ["test", "file", "line", "red"], "properties": {"test": {"type": "string", "minLength": 1}, "file": {"type": "string", "minLength": 1}, "line": {"type": "integer"}, "red": {"type": "string", "minLength": 1}}}}
+  }
+}
+```
+
+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-fixer.md

@@ -0,0 +1,36 @@
+# Fixer of the final review
+
+Spec: {spec}
+Tickets: {tickets}
+PR branch: {pr_branch}, at commit {start_sha}
+Locked files: {locked}
+Findings file of the final review: {findings}
+Findings to fix:
+{findings_list}
+
+Fix each finding in the list as one batch, in one commit or in several. Leave the minor findings of the findings file.
+Each commit belongs to one ticket: the ticket whose criterion or code the commit changes. A fix for two tickets is two commits.
+Never edit a locked file: each one stays as it is at {start_sha}, and a locked file that differs is a critical finding of the next review.
+Use targeted tests while you work. The driver runs the gate on your final commit, and a scoped review reads your commits.
+Commit your work on the checked-out PR branch and change no commit that is on it now. Do not dispatch subagents.
+In `commits`, give every commit you made with the number of its ticket: the driver names each commit `fix(NN): <your subject>` from it, and a commit with no ticket is a violation. In `green`, give the summary lines of the passing test output.
+
+Write one JSON report at {report} that matches this schema:
+
+```json
+{
+  "type": "object",
+  "required": ["status", "commits", "files", "concerns", "green"],
+  "properties": {
+    "status": {"enum": ["DONE", "DONE_WITH_CONCERNS", "NEEDS_CONTEXT", "BLOCKED"]},
+    "commits": {"type": "array", "items": {"type": "object", "required": ["sha", "ticket"], "properties": {"sha": {"type": "string", "pattern": "^[0-9a-f]{7,40}$"}, "ticket": {"type": "string", "pattern": "^[0-9]+$"}}}},
+    "files": {"type": "array", "items": {"type": "string"}},
+    "concerns": {"type": "array", "items": {"type": "string"}},
+    "green": {"type": "array", "items": {"type": "string"}}
+  },
+  "if": {"properties": {"status": {"enum": ["DONE", "DONE_WITH_CONCERNS"]}}},
+  "then": {"properties": {"commits": {"minItems": 1}}}
+}
+```
+
+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

@@ -0,0 +1,36 @@
+# Final reviewer
+
+Spec: {spec}
+Tickets: {tickets}
+PR branch: {pr_branch}, at commit {start_sha}
+Range: {range}
+Gate record of the driver for {start_sha}: {gate}
+Review method: {review_diff}
+Ledger of the run, one sentence per event: {ledger}
+Minor findings that the ticket reviews left for this review, each with its findings file:
+{minors}
+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.
+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.
+
+Write one JSON report at {report} that matches this schema:
+
+```json
+{
+  "type": "object",
+  "required": ["status", "commits", "files", "concerns", "findings"],
+  "properties": {
+    "status": {"enum": ["DONE", "DONE_WITH_CONCERNS", "NEEDS_CONTEXT", "BLOCKED"]},
+    "commits": {"type": "array", "items": {"type": "string", "pattern": "^[0-9a-f]{7,40}$"}},
+    "files": {"type": "array", "items": {"type": "string"}},
+    "concerns": {"type": "array", "items": {"type": "string"}},
+    "findings": {"type": "array", "items": {"type": "object", "required": ["severity", "file", "line", "title", "evidence", "kind"], "properties": {"severity": {"enum": ["critical", "important", "minor"]}, "file": {"type": "string"}, "line": {"type": "integer"}, "title": {"type": "string", "minLength": 1}, "evidence": {"type": "string", "minLength": 1}, "kind": {"enum": ["code", "fixture", "test"]}}}}
+  }
+}
+```
+
+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-scoped.md

@@ -0,0 +1 @@
+This is the scoped review after the fix batch: the range holds only the `fix(NN)` commits, and the commits up to {reviewed} have their review. Check that each critical or important finding in {findings} is fixed and that the fix commits break nothing else.

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

@@ -0,0 +1,35 @@
+# Fixer
+
+Spec: {spec}
+Ticket: {ticket}
+Seam: {seam}
+Branch: {branch}, at commit {start_sha}
+Locked files: {locked}
+Findings of the review: {findings}
+
+Fix each finding of severity critical or important in the findings file. Leave the minor findings: the final review gets them. Leave each finding of kind `fixture`: the test-writer corrects those.
+Never edit a locked file. The one exception is a finding `locked file changed`: make that file equal to its content at {test_writer_sha}.
+Use targeted tests while you work. The driver runs the gate on your final commit, and a re-review reads the lines you changed.
+Commit your work on the checked-out ticket branch. Do not dispatch subagents.
+In `ticket`, give the number of the ticket that owns your commits. In `green`, give the summary lines of the passing test output.
+
+Write one JSON report at {report} that matches this schema:
+
+```json
+{
+  "type": "object",
+  "required": ["status", "commits", "files", "concerns", "green", "ticket"],
+  "properties": {
+    "status": {"enum": ["DONE", "DONE_WITH_CONCERNS", "NEEDS_CONTEXT", "BLOCKED"]},
+    "commits": {"type": "array", "items": {"type": "string", "pattern": "^[0-9a-f]{7,40}$"}},
+    "files": {"type": "array", "items": {"type": "string"}},
+    "concerns": {"type": "array", "items": {"type": "string"}},
+    "green": {"type": "array", "items": {"type": "string"}},
+    "ticket": {"type": "string", "pattern": "^[0-9]+$"}
+  },
+  "if": {"properties": {"status": {"enum": ["DONE", "DONE_WITH_CONCERNS"]}}},
+  "then": {"properties": {"commits": {"minItems": 1}}}
+}
+```
+
+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/implementer.md

@@ -0,0 +1,33 @@
+# Implementer
+
+Spec: {spec}
+Ticket: {ticket}
+Seam: {seam}
+Start commit, which holds the locked tests when the ticket has them: {start_sha}
+Locked files: {locked}
+
+Make the locked tests green and meet each criterion of the ticket. For internal code, work in vertical test-first slices: one failing test, the smallest code that passes it, then the next slice.
+Never edit a locked file. If a locked test contradicts the spec or the ticket, stop and report BLOCKED with the evidence in `concerns`.
+Commit your work on the checked-out ticket branch. Do not dispatch subagents.
+Run targeted tests while you work. The driver runs the gate on your final commit.
+In `green`, give the summary lines of the passing test output.
+
+Write one JSON report at {report} that matches this schema:
+
+```json
+{
+  "type": "object",
+  "required": ["status", "commits", "files", "concerns", "green"],
+  "properties": {
+    "status": {"enum": ["DONE", "DONE_WITH_CONCERNS", "NEEDS_CONTEXT", "BLOCKED"]},
+    "commits": {"type": "array", "items": {"type": "string", "pattern": "^[0-9a-f]{7,40}$"}},
+    "files": {"type": "array", "items": {"type": "string"}},
+    "concerns": {"type": "array", "items": {"type": "string"}},
+    "green": {"type": "array", "items": {"type": "string"}}
+  },
+  "if": {"properties": {"status": {"enum": ["DONE", "DONE_WITH_CONCERNS"]}}},
+  "then": {"properties": {"commits": {"minItems": 1}}}
+}
+```
+
+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/interrupted.md

@@ -0,0 +1 @@
+The earlier attempt was interrupted. Its uncommitted work is in the tree: continue from it.

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

@@ -0,0 +1,2 @@
+
+The earlier attempt left the slot off the tip of {branch}. The driver reset the slot to {branch} at {tip}: work there and stay there.

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

@@ -0,0 +1,5 @@
+
+This call is a correction after a ruling, not a new test set. The implementer reported that a locked test contradicts the spec or the ticket, and the operator ruled that the test is wrong: read `concerns` in {blocked_report}.
+Correct only the tests that those concerns name, so that they state what the spec and the ticket require. Keep each other test as it is.
+The branch can hold commits of the implementer, and the tree can hold its uncommitted work: change neither, and commit only the test files you correct.
+A corrected test fails because the behavior is missing: run it and print that failing output. In `locked`, list each test file you corrected.

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

@@ -0,0 +1,19 @@
+## Tickets
+
+One commit per ticket, in merge order:
+
+{map}
+
+## Fix commits of the final review
+
+{fixes}
+
+## Rulings
+
+{rulings}
+
+## Review coverage
+
+- Branch tip and reviewed tip: {tip}
+- Full review: {onto}..{tidied}
+- Scoped review after the fix batch: {scoped}

package/skills/implement-spec/prompts/rebase-conflict.md

@@ -0,0 +1,33 @@
+# Conflict
+
+Spec: {spec}
+Tickets: {tickets}
+PR branch: {pr_branch}
+Base branch: {base}, at commit {start_sha}
+Files in conflict: {files}
+
+A rebase of the PR branch onto the base branch is open in this worktree, on a detached HEAD, and it stopped with conflicts in those files. The commit that stopped is the one commit of a ticket: its message names the ticket file.
+Resolve each conflict so that the behavior of both sides holds: the spec and the ticket say what each side is for. Change nothing that the resolution does not need.
+Run the targeted tests of the files you resolved. The driver runs the gate on the rebased tip.
+Stage the files you resolved, then go on with `git rebase --continue`. Do not abort the rebase and do not dispatch subagents.
+You resolve one stop only. When the rebase stops again at a later commit, leave that stop as it is and write your report.
+In `commits`, give `git rev-parse HEAD` as it is when you are done. In `files`, give each file you resolved.
+
+Write one JSON report at {report} that matches this schema:
+
+```json
+{
+  "type": "object",
+  "required": ["status", "commits", "files", "concerns"],
+  "properties": {
+    "status": {"enum": ["DONE", "DONE_WITH_CONCERNS", "NEEDS_CONTEXT", "BLOCKED"]},
+    "commits": {"type": "array", "items": {"type": "string", "pattern": "^[0-9a-f]{7,40}$"}},
+    "files": {"type": "array", "items": {"type": "string"}},
+    "concerns": {"type": "array", "items": {"type": "string"}}
+  },
+  "if": {"properties": {"status": {"enum": ["DONE", "DONE_WITH_CONCERNS"]}}},
+  "then": {"properties": {"commits": {"minItems": 1}}}
+}
+```
+
+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/rereview.md

@@ -0,0 +1,3 @@
+
+This is the re-review after fix round {round}. The fix is {from_sha}..{start_sha}: review only the lines it changed, and check that it resolves each critical or important finding in {findings}.
+Repeat the mutation proof for these production lines only, numbered as they are at {start_sha} (an empty list means that no proof is due): {proofs}

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

@@ -0,0 +1,2 @@
+
+The driver rejected the earlier attempt: {error}

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

@@ -0,0 +1,34 @@
+# Reviewer
+
+Spec: {spec}
+Ticket: {ticket}
+Seam: {seam}
+Range: {pr_branch}...{branch}, with the ticket tip at {start_sha}
+Locked files: {locked}
+Test-writer report, when the ticket has a test-writer: {writer_report}
+
+Check the diff against the ticket and the spec, then for quality. Check that each criterion has a locked test. Test each suspicion that the ticket names in its Suspicions line.
+In round 1, for each locked test, break the production line the test protects, run the test, print its failing output, then revert the edit. A test that stays green is a critical finding. Run again each mutation that the test-writer report names in `concerns`.
+A mutation proof is keyed to its test and its production line: a later round repeats it only when that line changed.
+In `mutations`, give for each proof the test, the production file and line, and one failure line copied exactly from the output you printed.
+Give each finding a severity (critical, important or minor), the file and line, a title, the evidence, and a kind: `code`, `test`, or `fixture` when a locked test encodes a stale path, format or setup detail.
+Do not commit and do not dispatch subagents. Leave the tree as you found it.
+
+Write one JSON report at {report}. When your sandbox is read-only, give the JSON as your whole final message and the driver saves it there. The report matches this schema:
+
+```json
+{
+  "type": "object",
+  "required": ["status", "commits", "files", "concerns", "findings"],
+  "properties": {
+    "status": {"enum": ["DONE", "DONE_WITH_CONCERNS", "NEEDS_CONTEXT", "BLOCKED"]},
+    "commits": {"type": "array", "items": {"type": "string", "pattern": "^[0-9a-f]{7,40}$"}},
+    "files": {"type": "array", "items": {"type": "string"}},
+    "concerns": {"type": "array", "items": {"type": "string"}},
+    "findings": {"type": "array", "items": {"type": "object", "required": ["severity", "file", "line", "title", "evidence", "kind"], "properties": {"severity": {"enum": ["critical", "important", "minor"]}, "file": {"type": "string"}, "line": {"type": "integer"}, "title": {"type": "string", "minLength": 1}, "evidence": {"type": "string", "minLength": 1}, "kind": {"enum": ["code", "fixture", "test"]}}}},
+    "mutations": {"type": "array", "items": {"type": "object", "required": ["test", "file", "line", "red"], "properties": {"test": {"type": "string", "minLength": 1}, "file": {"type": "string", "minLength": 1}, "line": {"type": "integer"}, "red": {"type": "string", "minLength": 1}}}}
+  }
+}
+```
+
+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/stands.md

@@ -0,0 +1,2 @@
+
+The earlier attempt reported that a locked test contradicts the spec, and the operator ruled that the locked tests stand as they are. Your earlier commits are on the branch and your uncommitted work is in the tree: continue from them and make the locked tests green. Do not report that contradiction again.

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

@@ -0,0 +1,34 @@
+# Test-writer
+
+Spec: {spec}
+Ticket: {ticket}
+Seam: {seam}
+Branch: {branch}, at commit {start_sha}
+
+Read the spec, the ticket, CONTEXT.md and the ADRs when they exist, and the public interface of the Seam. Do not read an implementation plan or implementation code.
+Write one black-box acceptance test for each criterion of the ticket, through the Seam only. Define the interface when it does not exist.
+Run each test and confirm that it fails because the behavior is missing, not because of an import error or a syntax error. Print that failing output.
+A test that is green before any implementation is not a proof. Rewrite it until it fails, or name in `concerns` the production-code mutation that turns it red.
+Commit the tests red on the checked-out branch. Do not write implementation code and do not dispatch subagents.
+In `locked`, list each test file of your commit. In `red`, give for each test one failure line, copied exactly from the output you printed.
+
+Write one JSON report at {report} that matches this schema:
+
+```json
+{
+  "type": "object",
+  "required": ["status", "commits", "files", "concerns", "locked", "red"],
+  "properties": {
+    "status": {"enum": ["DONE", "DONE_WITH_CONCERNS", "NEEDS_CONTEXT", "BLOCKED"]},
+    "commits": {"type": "array", "items": {"type": "string", "pattern": "^[0-9a-f]{7,40}$"}},
+    "files": {"type": "array", "items": {"type": "string"}},
+    "concerns": {"type": "array", "items": {"type": "string"}},
+    "locked": {"type": "array", "items": {"type": "string"}},
+    "red": {"type": "array", "items": {"type": "object", "required": ["test", "line"], "properties": {"test": {"type": "string", "minLength": 1}, "line": {"type": "string", "minLength": 1}}}}
+  },
+  "if": {"properties": {"status": {"enum": ["DONE", "DONE_WITH_CONCERNS"]}}},
+  "then": {"properties": {"commits": {"minItems": 1}, "locked": {"minItems": 1}, "red": {"minItems": 1}}}
+}
+```
+
+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/timeout-restored.md

@@ -0,0 +1,2 @@
+
+The earlier attempt timed out after {minutes} minutes. The driver restored the worktree to {tip}: start again from there.

package/skills/implement-spec/prompts/timeout-shared.md

@@ -0,0 +1,2 @@
+
+The earlier attempt timed out after {minutes} minutes. Start again from {tip}: first revert each edit of the earlier attempt that `git status` shows.

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

@@ -0,0 +1,2 @@
+
+The earlier attempt timed out after {minutes} minutes. Its uncommitted work is in the tree: continue from it.

package/skills/implement-spec/run.sh

@@ -0,0 +1,101 @@
+#!/bin/sh
+# Keep bootstrap dependencies to POSIX tools, curl, tar, and SHA-256.
+set -eu
+
+fail() {
+    printf 'implement-spec: %s\n' "$1" >&2
+    exit 3
+}
+
+# Resolve file symlinks as well as symlinked skill directories.
+entry=$0
+while [ -L "$entry" ]; do
+    parent=$(CDPATH= cd -- "$(dirname -- "$entry")" && pwd)
+    entry=$(readlink "$entry")
+    case "$entry" in /*) ;; *) entry=$parent/$entry ;; esac
+done
+skill_dir=$(CDPATH= cd -- "$(dirname -- "$entry")" && pwd)
+cache=${IMPLEMENT_SPEC_CACHE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/implement-spec}
+case "$cache" in /*) ;; *) fail 'IMPLEMENT_SPEC_CACHE_DIR must be an absolute path' ;; esac
+uv_version=0.12.13
+python_version=3.13.7
+case "$(uname -s):$(uname -m)" in
+    Darwin:arm64|Darwin:aarch64)
+        target=aarch64-apple-darwin
+        digest=7e6ddb9316acc00f2296c82ff4d99977870ee34b2f0ddcae9444d714db9364ed ;;
+    Darwin:x86_64)
+        target=x86_64-apple-darwin
+        digest=5e287ef61cb6a9b61b3a83fef124fd143e400468a7dac794230147a810e17119 ;;
+    Linux:aarch64|Linux:arm64)
+        target=aarch64-unknown-linux-musl
+        digest=f44bc1037a17889fe562fffd2002d4ed108e499fbe68b4f022af244dc7b8244f ;;
+    Linux:x86_64)
+        target=x86_64-unknown-linux-musl
+        digest=4e2bfd0c9007b1032a50e539e965fd0a6037d87ad93ae1580d220a92d4c94098 ;;
+    *) fail 'Unsupported platform: use macOS or Linux on x86_64 or ARM64 (Windows: WSL)' ;;
+esac
+uv_dir=$cache/uv/$uv_version/$target
+uv=$uv_dir/uv
+if [ ! -x "$uv" ]; then
+    [ "${IMPLEMENT_SPEC_OFFLINE:-0}" != 1 ] || fail 'uv is not cached; provision this cache online first'
+    mkdir -p "$uv_dir" || fail 'Cannot create runtime cache'
+    stage=$(mktemp -d "$uv_dir/.download.XXXXXX") || fail 'Cannot create download directory'
+    trap 'rm -rf "$stage"' EXIT
+    trap 'exit 3' HUP INT TERM
+    printf 'implement-spec: downloading uv %s\n' "$uv_version" >&2
+    curl --fail --location --silent --show-error --connect-timeout 15 --max-time 300 \
+        "https://github.com/astral-sh/uv/releases/download/$uv_version/uv-$target.tar.gz" \
+        -o "$stage/uv.tar.gz" || fail 'Cannot download uv; check network access and retry'
+    if command -v sha256sum >/dev/null 2>&1; then
+        actual=$(sha256sum "$stage/uv.tar.gz")
+    elif command -v shasum >/dev/null 2>&1; then
+        actual=$(shasum -a 256 "$stage/uv.tar.gz")
+    else
+        fail 'SHA-256 verification requires sha256sum or shasum'
+    fi
+    [ "${actual%% *}" = "$digest" ] || fail 'uv archive checksum mismatch'
+    tar -xzf "$stage/uv.tar.gz" -C "$stage" || fail 'Cannot extract uv'
+    # Atomic publication: concurrent first runs never see a partial executable.
+    mv -f "$stage/uv-$target/uv" "$uv" || fail 'Cannot install cached uv'
+    rm -rf "$stage"
+    trap - EXIT HUP INT TERM
+fi
+
+# Limit uv settings to this subprocess. Do not activate a venv or change PATH:
+# coverage commands inherit the caller's project environment (the engine adds
+# only the repo's own .venv/bin, when no virtualenv is active).
+managed_uv() (
+    unset UV_NO_MANAGED_PYTHON UV_PYTHON UV_PYTHON_DOWNLOADS UV_PYTHON_BIN_DIR
+    export UV_PYTHON_INSTALL_DIR="$cache/python"
+    export UV_CACHE_DIR="$cache/uv-cache"
+    export UV_MANAGED_PYTHON=true
+    "$uv" --no-config "$@"
+)
+python=$(managed_uv python find --no-project --system --managed-python --no-python-downloads "$python_version" 2>/dev/null) || {
+    [ "${IMPLEMENT_SPEC_OFFLINE:-0}" != 1 ] || fail 'Python is not cached; provision this cache online first'
+    managed_uv python install --no-bin "$python_version" >&2 || fail 'Cannot provision Python; check network access and retry'
+    python=$(managed_uv python find --no-project --system --managed-python --no-python-downloads "$python_version") || fail 'Cannot locate managed Python'
+}
+# The one dependency (design.md): jsonschema with its closure pinned, in a venv built once per pin set.
+jsonschema_version=4.26.0
+venv=$cache/venv/$python_version-jsonschema-$jsonschema_version
+if [ ! -x "$venv/bin/python" ]; then
+    [ "${IMPLEMENT_SPEC_OFFLINE:-0}" != 1 ] || fail 'jsonschema is not cached; provision this cache online first'
+    mkdir -p "$cache/venv" || fail 'Cannot create runtime cache'
+    stage=$(mktemp -d "$cache/venv/.build.XXXXXX") || fail 'Cannot create build directory'
+    trap 'rm -rf "$stage"' EXIT
+    trap 'exit 3' HUP INT TERM
+    managed_uv venv --quiet --python "$python" "$stage/venv" >&2 &&
+        managed_uv pip install --quiet --python "$stage/venv/bin/python" "jsonschema==$jsonschema_version" \
+            attrs==26.1.0 referencing==0.37.0 rpds-py==2026.9.1 jsonschema-specifications==2025.9.1 >&2 ||
+        fail 'Cannot provision jsonschema; check network access and retry'
+    # Publish by rename: a concurrent first run never sees a partial venv. A run that loses the race
+    # (the rename fails, or lands inside the winner's directory) uses the winner's venv.
+    [ -x "$venv/bin/python" ] || mv "$stage/venv" "$venv" 2>/dev/null || :
+    [ -x "$venv/bin/python" ] || fail 'Cannot install cached venv'
+    rm -rf "$stage"
+    trap - EXIT HUP INT TERM
+fi
+# Ignore Python-specific ambient settings for the engine, but preserve them for
+# child processes. -I would also remove the sibling module directory.
+exec "$venv/bin/python" -E -s "$skill_dir/driver.py" "$@"

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

@@ -0,0 +1,38 @@
+"""The fixture repository of the in-process tests: a clean git worktree on feat/x with .agent ignored."""
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))  # the driver modules are one folder up
+
+import driver_agents  # noqa: E402
+
+GIT = ["git", "-c", "user.name=t", "-c", "user.email=t@example.com", "-c", "commit.gpgsign=false"]
+
+
+def ticket(number, blocked="None (can start immediately)", touches="`demo/x.py: f`", seam="`f()`"):
+    return f"# {number}: Ticket {number}\n\n**Blocked by:** {blocked}\n\n**Seam:** {seam}\n\n**Touches:** {touches}\n\n- [ ] It works\n"
+
+
+@pytest.fixture
+def repo(tmp_path, monkeypatch):
+    """A clean git worktree with .agent ignored; returns a writer for the ticket set."""
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr(driver_agents.shutil, "which", lambda cli: cli)  # CI has no claude or codex
+    for index, setting in enumerate(GIT[2::2]):  # the fake agents commit too
+        monkeypatch.setenv(f"GIT_CONFIG_KEY_{index}", setting.partition("=")[0])
+        monkeypatch.setenv(f"GIT_CONFIG_VALUE_{index}", setting.partition("=")[2])
+    monkeypatch.setenv("GIT_CONFIG_COUNT", "3")
+    subprocess.run([*GIT, "init", "-q", "-b", "feat/x"], check=True)
+    (tmp_path / ".gitignore").write_text(".agent/\n")
+    subprocess.run([*GIT, "add", "-A"], check=True)
+    subprocess.run([*GIT, "commit", "-q", "-m", "init"], check=True)
+
+    def write(**blocked):
+        (tmp_path / ".agent/tickets").mkdir(parents=True, exist_ok=True)
+        for number, text in blocked.items():
+            (tmp_path / f".agent/tickets/{number[1:]}-t.md").write_text(text)
+        return tmp_path
+    return write