@jesdi/skills 0.0.30 → 0.0.32

package/skills/implement-spec/driver_review_page.py

@@ -0,0 +1,51 @@
+"""The review page of the open questions: decisions.json in, HTML out.
+
+The page is the template of the review-page skill in questionnaire mode with its slots filled. Every text is escaped.
+"""
+from __future__ import annotations
+
+import re
+from html import escape
+
+import driver_agents
+
+TEMPLATE = driver_agents.SKILL.parent / "review-page" / "template.html"
+SLOTS = ("header", "tickets", "questions", "corrections", "track")
+
+
+def _option(question: str, option: dict, recommended: bool) -> str:
+    name, chip = escape(option["id"]), ' <span class="chip rec">recommended</span>' * recommended
+    return (f'<label class="opt"><input type="radio" name="{question}" value="{name}"><span><span class="t">{name}'
+            f'{chip}</span><br><span class="d">{escape(option["description"])}</span></span></label>')
+
+
+def _question(q: dict) -> str:
+    name = escape(q["id"])
+    options = "\n".join(_option(name, option, option["id"] == q["recommended"]) for option in q["options"])
+    evidence = " · ".join(f"<code>{escape(pointer)}</code>" for pointer in q["evidence"])
+    return (f'<div class="q" data-q="{name}">\n'
+            f'<header><h3>{escape(q["title"])}</h3><span class="chip waiting">needs you</span></header>\n'
+            f'<p class="why">{escape(q["why"])}</p>\n<p class="why">Evidence: {evidence}</p>\n'
+            f'<div class="opts">\n{options}\n</div>\n'
+            f'<textarea id="note-{name}" placeholder="Note (optional)"></textarea>\n</div>')
+
+
+def _filled(page: str, pattern: str, new: str) -> str:
+    """`page` with the one match of `pattern` replaced; ValueError when the template has not exactly one."""
+    page, count = re.subn(pattern, lambda match: new, page, flags=re.S)
+    if count != 1:
+        raise ValueError(f"{TEMPLATE} has {count} matches of {pattern}, not 1")
+    return page
+
+
+def render(decisions: dict) -> str:
+    """The page for decisions.json. Raises OSError with no template, ValueError when it has another shape."""
+    questions = decisions["questions"]
+    header = (f'<div class="eyebrow">implement-spec · decisions {escape(decisions["revision"][:12])}</div>\n'
+              f"<h1>{len(questions)} open question{'s' * (len(questions) != 1)} of the implementation</h1>\n"
+              '<p class="lede">Pick an option under each question, then send.</p>')
+    slots = {"header": header, "questions": "\n".join(["<h2>Open questions</h2>", *map(_question, questions)])}
+    page = _filled(TEMPLATE.read_text(), r'<body data-mode="[a-z]*">', '<body data-mode="questionnaire">')
+    for slot in SLOTS:
+        page = _filled(page, rf"(?<=<!-- slot: {slot} -->).*?(?=<!-- /slot -->)", f"\n{slots.get(slot, '')}\n")
+    return page

package/skills/implement-spec/driver_run.py

@@ -0,0 +1,262 @@
+"""What the ticket threads and the end of run share: the Run, one agent with its one rerun, the gate, the ledger.
+
+A step that cannot go on raises Blocked. The message says why, and `during` adds the step it happened in.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import threading
+import time
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, Iterator, NamedTuple, TypeVar
+
+import driver_agents
+import driver_decisions
+import driver_gate
+import driver_merge
+import driver_report
+import driver_review
+import driver_slots
+import driver_state
+from driver_slots import git
+
+OUT = Path(".agent/implement")
+FINAL = "final"  # the end of run has its reports and gate records under this name, as a ticket has under its number
+_LEDGER = threading.Lock()
+T = TypeVar("T")
+
+
+class Blocked(Exception):
+    """A ticket, or the end of run, cannot go on. The message says why."""
+
+
+@contextmanager
+def during(step: str) -> Iterator[None]:
+    """Put the step in front of a Blocked that leaves the block: `<step>: <why>`."""
+    try:
+        yield
+    except Blocked as blocked:
+        raise Blocked(f"{step}: {blocked}") from None
+
+
+def ledger(sentence: str) -> int:
+    """Append one sentence to ledger.md and return its line number."""
+    with _LEDGER:
+        OUT.mkdir(parents=True, exist_ok=True)
+        with (OUT / "ledger.md").open("a+") as file:
+            file.write(" ".join(sentence.split()) + "\n")
+            file.seek(0)
+            return sum(1 for _ in file)
+
+
+def _owner(number: str) -> str:
+    return "End of run" if number == FINAL else f"Ticket {number}"
+
+
+def _gate_record(state: dict, number: str) -> dict:
+    """The record of state.json that holds the green gates of `number`."""
+    return state["run"]["final"] if number == FINAL else state["tickets"][number]
+
+
+class Ask(NamedTuple):
+    """The questions a ticket thread wants the operator to answer when its ticket blocks."""
+    kind: str
+    subjects: list[str]  # one question per subject
+    report: str  # the evidence
+    fields: dict  # what the ticket record gets with the stop
+
+
+@dataclass
+class Run:
+    args: argparse.Namespace
+    models: dict[str, list[str]]
+    state: driver_state.State
+    pr: str  # the PR branch
+    kept: dict[str, int]  # ticket number -> the slot that holds its uncommitted work from an earlier run
+    merging: threading.Lock = field(default_factory=threading.Lock)  # held for one landing: merges are serial
+    asks: dict[str, Ask] = field(default_factory=dict)  # ticket number -> its pending stop
+
+    def tip(self) -> str:
+        return git(".", "rev-parse", f"refs/heads/{self.pr}").stdout.strip()
+
+    def ask(self, number: str, kind: str, subjects: list[str], report: str, **fields) -> None:
+        self.asks[number] = Ask(kind, subjects, report, fields)
+
+    def agent(self, role: str, number: str, slot: str, values: dict[str, str], **options) -> dict:
+        """Run one role and return its accepted report. `options` are those of `_attempts`."""
+        if role == "test-writer":
+            # Its report may change a locked file of a merged ticket only when it lists the file.
+            merged = driver_merge.protected(self.state.read()["tickets"], number)
+            options["check"] = {**(options.get("check") or {}), "merged": merged, "pr": self.tip()}
+        report = _attempts(self, role, number, slot, values, **options)
+        if subject := driver_decisions.contradicted(role, report):
+            # The implementer's commits stay: after the ruling the ticket goes on from them.
+            evidence = OUT / number / f"{role}-{options.get('fix_round', 0)}.json"
+            self.ask(number, "locked-test", [subject], str(evidence), tip=driver_slots.head(slot))
+        if report.get("status") in ("BLOCKED", "NEEDS_CONTEXT"):
+            concerns = "; ".join(report["concerns"]) or "no concern given"
+            raise Blocked(f"the {role} reported {report['status']}: {concerns}")
+        return report
+
+    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 = ""
+            try:
+                result = review()
+            except Blocked as blocked:
+                error = str(blocked)
+            left = _restore_if_changed(number, slot, branch, tip, runs_again=not (error or last))
+            if error or not left:
+                break
+        if error or left:
+            raise Blocked(error or left)
+        return result
+
+    def gate(self, number: str, slot: str, commit: str) -> None:
+        """Gate `commit` in the slot, unless a green record names it already."""
+        if commit in _gate_record(self.state.read(), number)["green_gates"]:
+            return
+        at = driver_slots.head(slot)
+        if at != commit:
+            raise Blocked(f"the slot is at {at[:7]}, not at {commit[:7]}: the gate did not run")
+        green, record = driver_gate.run(self.args.gate, slot, OUT / number, self.pr)
+
+        def count(state: dict) -> None:
+            state["run"]["gates"] += 1
+            if green:
+                _gate_record(state, number)["green_gates"].append(commit)
+
+        self.state.update(count)
+        if not green:
+            raise Blocked(f"the gate is red on {commit[:7]}, record {record}")
+        ledger(f"{_owner(number)}: the gate is green on {commit[:7]}, record {record}.")
+
+    def restore_locked_files(self, number: str, slot: str) -> list[str]:
+        """Before a test-writer correction: put each locked file the implementer changed back to its locked
+        version in the tree, so the correction's commit carries no change of the implementer. Returns the paths."""
+        tickets = self.state.read()["tickets"]
+        paths = (driver_review.restore_locked(slot, tickets[number])
+                 + driver_merge.restore(slot, self.tip(), driver_merge.protected(tickets, number)))
+        for path in paths:
+            ledger(f"Ticket {number}: {path} was not the locked version at the correction: the driver restored it in "
+                   "the tree, so the correction starts from the locked version.")
+        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:
+        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}.")
+    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:
+        problem = f"branch {branch} is missing"
+    elif head != branch:
+        problem = f"HEAD is on {head or 'a detached commit'} instead of {branch}"
+    elif git(slot, "merge-base", "--is-ancestor", tip, "HEAD").returncode:
+        problem = f"{branch} no longer holds {tip[:7]}"
+    else:
+        return ""
+    git(slot, "checkout", "-q", "-f", "-B", branch, tip)
+    return f"{problem}; the driver reset the slot to {tip[:7]}"
+
+
+def _timeout_lines(role: str, minutes: float, context: dict, alone: Callable[[], bool]) -> str:
+    """The lines the rerun prompt gets after a timeout. The tree stays, but a read-only role has no work to keep:
+    its slot is restored, unless another agent still works there."""
+    values = {"minutes": f"{minutes:g}", "tip": context["start"]}
+    if role not in driver_agents.READ_ONLY:
+        return driver_agents.render("timeout", values)
+    if alone():
+        driver_review.restore(context["repo"], context["branch"], context["start"])
+        return driver_agents.render("timeout-restored", values)
+    return driver_agents.render("timeout-shared", values)
+
+
+def _rejection(role: str, code: int | None, minutes: float, report: Path, context: dict, alone: Callable[[], bool],
+               detached: bool) -> tuple[str, str]:
+    """(why the attempt is rejected, the lines the rerun prompt gets); ("", ...) when the report is accepted."""
+    branch, tip = context["branch"], context["start"]
+    # Read-only agents share a slot, and a rebase is on a detached HEAD: there the driver has no branch to reset.
+    owns_branch = role not in driver_agents.READ_ONLY and not detached
+    if owns_branch and (moved := _reset_if_moved(context["repo"], branch, tip)):
+        return moved, driver_agents.render("moved", {"branch": branch, "tip": tip})
+    if code is None:
+        return f"timed out after {minutes:g} minutes", _timeout_lines(role, minutes, context, alone)
+    error = "; ".join(driver_report.validate(context["template"], str(report), context))
+    return error, driver_agents.render("rerun", {"error": error})
+
+
+def _first_prompt(template: str, values: dict[str, str], notes: tuple | list, report: str) -> str:
+    """The template of the role, then the lines of each `notes` template and the ending of the prompt again."""
+    text = driver_agents.render(template, {**values, "report": report})
+    if notes:
+        text += "".join(driver_agents.render(note, values) for note in notes) + driver_agents.tail(text, report)
+    return text
+
+
+def _record_attempt(run: Run, role: str, number: str, entry: str, seconds: float, log: Path, error: str) -> None:
+    cost = driver_agents.cost(log)
+    used = {"ticket": number, "role": role, "entry": entry, "seconds": round(seconds, 1), "cost": float(cost or 0)}
+    run.state.update(lambda state: state["run"]["agents"].append(used))
+    spent = f", cost {cost} USD" if cost else ""
+    ledger(f"{_owner(number)}: {role} ran on {entry} for {seconds:.1f}s{spent}: {error or 'report accepted'}.")
+
+
+def _command(run: Run, role: str, entry: str, prompt: str, report: str) -> list[str]:
+    if run.args.runner:  # `--runner` is for tests
+        return [run.args.runner, role, prompt, report]
+    return driver_agents.command(role, entry, report)
+
+
+def _attempts(run: Run, role: str, number: str, slot: str, values: dict[str, str], notes: tuple | list = (),
+              entry: str = "", fix_round: int = 0, check: dict | None = None, template: str = "",
+              alone: Callable[[], bool] = lambda: True, detached: bool = False) -> dict:
+    """Run one role in its slot, with at most one rerun, and return the accepted report.
+
+    notes      templates whose lines the first prompt gets after the role's own
+    entry      the model entry, when it is not the first of the role's list
+    fix_round  the K of the files `<role>-<K>.json`, `.log` and `.prompt.md`
+    check      more context for the report validation (driver_report.validate)
+    template   the prompt and schema, when it is not the one named after the role
+    alone      whether no other agent works in the slot now
+    detached   the agent works on a detached HEAD
+    """
+    folder, entry = OUT / number, entry or run.models[role][0]
+    folder.mkdir(parents=True, exist_ok=True)
+    report, log, prompt = (folder / f"{role}-{fix_round}{suffix}" for suffix in (".json", ".log", ".prompt.md"))
+    report_in_slot = os.path.relpath(report, slot)  # the agent works in its slot
+    context = {"repo": slot, "branch": values["branch"], "start": values["start_sha"], "log": str(log), "round": 0,
+               "template": template or role, **(check or {})}
+    argv = _command(run, role, entry, os.path.relpath(prompt, slot), report_in_slot)
+    text = _first_prompt(context["template"], values, notes, report_in_slot)
+    minutes, error = run.args.timeout[role], ""
+    for _ in range(2):
+        prompt.write_text(text)
+        report.unlink(missing_ok=True)
+        start = time.monotonic()
+        code = driver_agents.launch(argv, prompt, log, minutes * 60, slot)
+        seconds = time.monotonic() - start
+        error, rerun_lines = _rejection(role, code, minutes, report, context, alone, detached)
+        _record_attempt(run, role, number, entry, seconds, log, error)
+        if not error:
+            return json.loads(report.read_text())
+        # The rerun prompt is the first prompt, the rejection, then the same ending again.
+        text += rerun_lines + driver_agents.tail(text, report_in_slot)
+        if code is None:
+            minutes *= 2
+    raise Blocked(error)

package/skills/implement-spec/driver_slots.py

@@ -0,0 +1,64 @@
+"""Slots: the worktrees agents run in. Slot 1 is the PR worktree, slots 2..N live under .agent/worktrees/.
+
+Every path is relative to the PR worktree, which is the driver's working directory for the whole run.
+"""
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+
+def git(slot: str, *args: str) -> subprocess.CompletedProcess[str]:
+    # core.quotePath off: git prints a path with a non-ASCII name as it is, so it equals the path that a report names.
+    return subprocess.run(["git", "-C", slot, "-c", "core.quotePath=false", *args], capture_output=True, text=True)
+
+
+def names(listing: str) -> list[str]:
+    """The paths of a listing that git made with `-z`."""
+    return [name for name in listing.split("\0") if name]
+
+
+def head(slot: str) -> str:
+    return git(slot, "rev-parse", "HEAD").stdout.strip()
+
+
+def path(number: int) -> str:
+    return "." if number == 1 else f".agent/worktrees/slot-{number}"
+
+
+def create(number: int, prepare: str | None, keep: bool = False) -> str:
+    """Make and prepare slot 2..N once, or reuse it off any branch (`keep`: as it is). Returns "" or the error."""
+    slot = path(number)
+    git(".", "worktree", "prune")  # a slot directory that was removed by hand
+    if Path(slot, ".git").exists():
+        if not (keep or release(slot)):
+            return f"slot {number}: {slot} has uncommitted changes: commit or discard them"
+        return ""
+    added = git(".", "worktree", "add", "-q", "--detach", slot)
+    if added.returncode:
+        return f"slot {number}: cannot create {slot}: {added.stderr.strip()}"
+    if not prepare:
+        return ""
+    done = subprocess.run(prepare, shell=True, cwd=slot, capture_output=True, text=True, stdin=subprocess.DEVNULL)
+    if done.returncode:
+        # An unprepared slot must not look ready to the next run.
+        git(".", "worktree", "remove", "--force", slot)
+        return (f"slot {number}: --prepare `{prepare}` exited {done.returncode} in {slot}: "
+                f"{(done.stderr or done.stdout).strip()}")
+    return ""
+
+
+def setup(count: int, prepare: str | None, keep: set[int] = frozenset()) -> list[str]:
+    """Slots 2..count, before any agent. The first failure stops the run: [] or [the error]."""
+    for number in range(2, count + 1):
+        if error := create(number, prepare, number in keep):
+            return [error]
+    return []
+
+
+def release(slot: str) -> bool:
+    """Take a clean slot off its branch. False: the slot has uncommitted work, which stays where it is."""
+    if git(slot, "status", "--porcelain").stdout.strip():
+        return False
+    git(slot, "checkout", "-q", "--detach")
+    return True

package/skills/implement-spec/driver_state.py

@@ -0,0 +1,108 @@
+"""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,
+             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
+
+import fcntl
+import json
+import os
+import threading
+import uuid
+from pathlib import Path
+from typing import IO
+
+from driver_slots import git, path
+
+PHASES = ("pending", "test-writer", "implement", "gate", "review", "fix", "merge", "merged", "blocked")
+
+
+def _ticket() -> dict:
+    return {"phase": "pending", "round": 0, "tip": None, "test_writer_sha": None, "locked": [], "green_gates": [],
+            "slot": None, "note": "", "held": {}}
+
+
+def _final() -> dict:
+    """The end-of-run record before it starts. Every key is here, so a reader uses [] and a wrong name fails."""
+    return {"skipped": "", "recovery": None, "tidied": None, "onto": None, "base": None, "commits": {},
+            "reviewed": None, "round": 0, "open": [], "batch": None, "green_gates": [], "pushed": None, "body": None,
+            "pr": None}
+
+
+class State:
+    def __init__(self, path: Path):
+        self.path = path
+        self._lock = threading.Lock()
+
+    def read(self) -> dict:
+        return json.loads(self.path.read_text())
+
+    def start(self, pr_branch: str, numbers: list[str]) -> dict:
+        """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": [],
+                "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
+                state["run"]["final"].setdefault(key, value)
+            tickets = state.setdefault("tickets", {})
+            for number in numbers:
+                tickets.setdefault(number, _ticket())
+        return self.update(change)
+
+    def update(self, change) -> dict:
+        """Apply `change(state)` to the file as it is now. A reader sees the old file or the new one, never a part."""
+        with self._lock:
+            state = self.read() if self.path.exists() else {}
+            change(state)
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            scratch = self.path.with_suffix(".json.tmp")
+            scratch.write_text(json.dumps(state, indent=1) + "\n")
+            os.replace(scratch, self.path)
+            return state
+
+    def ticket(self, number: str, **fields) -> dict:
+        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."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    held = path.open("a")
+    try:
+        fcntl.flock(held, 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"])
+    if phase not in ("gate", "review", "fix", "merge", "merged"):
+        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):
+        return {}, ""
+    return {"phase": "implement", "tip": entry["test_writer_sha"]}, f"the recorded tip {tip[:7]} is not {word} {where}"
+
+
+def kept(state: dict) -> dict[str, int]:
+    """ticket number -> slot, per ticket stopped mid-role or at an open question, with uncommitted work in the slot."""
+    found = {}
+    asking = {question["ticket"] for question in state.get("run", {}).get("questions", []) if question["answer"] is None}
+    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():
+                found[number] = entry["slot"]
+    return found

package/skills/implement-spec/driver_summary.py

@@ -0,0 +1,40 @@
+"""The summary of a run, from state.json: plain sentences and the measurement table."""
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+
+
+def _rows(run: dict, tickets: dict) -> list[tuple[str, object]]:
+    agents = Counter((agent["role"], agent["entry"]) for agent in run["agents"])
+    seconds: dict[str, float] = defaultdict(float)
+    for agent in run["agents"]:
+        seconds[agent["role"]] += agent["seconds"]
+    rounds = ", ".join(f"{number}: {entry['round']}" for number, entry in tickets.items())
+    return [("gates run", run["gates"]),
+            *((f"agents, {role} on {entry}", number) for (role, entry), number in agents.items()),
+            *((f"wall time, {role}", f"{total:.1f} s") for role, total in seconds.items()),
+            ("fix rounds per ticket", rounds),
+            ("human stops", run["stops"]),
+            ("cost", f"{sum(agent['cost'] for agent in run['agents']):.2f} USD")]
+
+
+def _end(run: dict) -> list[str]:
+    """What the end of run did, from its record."""
+    final = run["final"]
+    if final["skipped"]:
+        return [f"The end-of-run work (rebase, tidy, final review, push) did not run: {final['skipped']}."]
+    if final["pushed"]:
+        return [f"{run['pr_branch']} is pushed at {final['pushed'][:7]}; its PR is {final['pr'] or 'not open'}."]
+    if final["reviewed"]:
+        return [f"The final review covers {run['pr_branch']} up to {final['reviewed'][:7]}. Nothing is pushed."]
+    return []
+
+
+def render(state: dict) -> str:
+    run, tickets = state["run"], state["tickets"]
+    merged = sum(entry["phase"] == "merged" for entry in tickets.values())
+    lines = [f"{merged} of {len(tickets)} tickets are merged into {run['pr_branch']}."]
+    lines += [f"Ticket {number} is not merged: its phase is {entry['phase']}."
+              for number, entry in tickets.items() if entry["phase"] != "merged"] + _end(run)
+    table = ["| Measure | Value |", "|---|---|"] + [f"| {name} | {value} |" for name, value in _rows(run, tickets)]
+    return "\n".join(lines + ["", *table]) + "\n"

package/skills/implement-spec/driver_tickets.py

@@ -0,0 +1,132 @@
+"""Ticket files in, task graph or error list out.
+
+parse(path) -> (tickets, errors): tickets is empty when errors is not; each error starts with the file name.
+"""
+from __future__ import annotations
+
+import re
+from collections import Counter
+from dataclasses import dataclass, field
+from pathlib import Path
+
+_FILE = re.compile(r"(\d+)-.*\.md$")
+_TITLE = re.compile(r"# \d+: *(\S.*)")
+_FIELD = re.compile(r"\*\*(Blocked by|Seam|Touches|Risk|Suspicions):\*\* *(\S.*)")
+_CRITERION = re.compile(r"- \[[ xX]\] *(\S.*)")
+_NONE = re.compile(r"none\b", re.IGNORECASE)  # "None (can start immediately)", "none — refactor"
+
+
+@dataclass
+class Ticket:
+    number: str  # as in the file name: "01"
+    file: str
+    title: str | None
+    blocked: str | None  # the Blocked by text; blocked_by holds the resolved numbers
+    seam: str | None
+    touches: str | None
+    risk: str | None
+    suspicions: str | None
+    criteria: list[str]
+    lines: dict[str, int]  # field name -> 1-based line
+    blocked_by: list[str] = field(default_factory=list)
+
+    @property
+    def refactor(self) -> bool:
+        """Seam `none — refactor`: no criterion and no test-writer."""
+        return bool(_NONE.match(self.seam or ""))
+
+
+def _read(path: Path) -> Ticket:
+    found: dict[str, tuple[str, int]] = {}
+    criteria: list[str] = []
+    for number, line in enumerate(path.read_text().splitlines(), 1):
+        if m := _TITLE.match(line):
+            found.setdefault("title", (m.group(1).strip(), number))
+        elif m := _FIELD.match(line):
+            found.setdefault(m.group(1), (m.group(2).strip(), number))
+        elif m := _CRITERION.match(line):
+            criteria.append(m.group(1).strip())
+    text = {name: value for name, (value, _) in found.items()}
+    return Ticket(
+        number=_FILE.match(path.name).group(1), file=path.name, title=text.get("title"),
+        blocked=text.get("Blocked by"), seam=text.get("Seam"), touches=text.get("Touches"),
+        risk=text.get("Risk"), suspicions=text.get("Suspicions"), criteria=criteria,
+        lines={name: line for name, (_, line) in found.items()},
+    )
+
+
+def _missing(ticket: Ticket, alone: bool) -> list[str]:
+    required = (("title", ticket.title), ("Blocked by", ticket.blocked), ("Seam", ticket.seam))
+    errors = [f"{ticket.file}: missing {name}" for name, value in required if not value]
+    if not ticket.criteria and not ticket.refactor:
+        errors.append(f"{ticket.file}: missing criterion")
+    if not ticket.touches and not alone:
+        where = f" (expected after Seam, line {ticket.lines['Seam']})" if ticket.seam else ""
+        errors.append(f"{ticket.file}: missing Touches{where}")
+    return errors
+
+
+def _blockers(ticket: Ticket, numbers: dict[int, str], titles: dict[str, int]) -> list[str]:
+    errors: list[str] = []
+    # ponytail: entries split on commas, so a title that holds a comma must be named by number.
+    for part in (p.strip() for p in ticket.blocked.split(",")):
+        m = re.match(r"\d+", part)
+        key = int(m.group()) if m else titles.get(part.lower())
+        if key in numbers:
+            ticket.blocked_by.append(numbers[key])
+        else:
+            name = m.group() if m else repr(part)
+            errors.append(f"{ticket.file}: Blocked by {name} names no ticket (line {ticket.lines['Blocked by']})")
+    return errors
+
+
+def _link(tickets: list[Ticket]) -> list[str]:
+    """Fill blocked_by from each Blocked by text: numbers, titles, or both."""
+    numbers = {int(t.number): t.number for t in tickets}
+    titles = {t.title.lower(): int(t.number) for t in tickets if t.title}
+    blocked = [t for t in tickets if t.blocked and not _NONE.match(t.blocked)]
+    return [e for t in blocked for e in _blockers(t, numbers, titles)]
+
+
+def _cycles(tickets: list[Ticket]) -> list[str]:
+    by = {t.number: t for t in tickets}
+    done: set[str] = set()
+    errors: list[str] = []
+
+    def visit(number: str, path: list[str]) -> None:
+        if number in path:
+            files = [by[n].file for n in path[path.index(number):]]
+            errors.append(f"{files[0]}: Blocked by cycle: {' -> '.join(files + files[:1])}")
+        elif number not in done:
+            for blocker in by[number].blocked_by:
+                visit(blocker, path + [number])
+            done.add(number)
+
+    for number in sorted(by):
+        visit(number, [])
+    return errors
+
+
+def parse(path) -> tuple[list[Ticket], list[str]]:
+    files = sorted(p for p in Path(path).glob("*.md") if _FILE.match(p.name))
+    if not files:
+        return [], [f"{path}: no ticket files (NN-name.md)"]
+    tickets = [_read(p) for p in files]
+    errors = [e for t in tickets for e in _missing(t, alone=len(tickets) == 1)]
+    errors += _link(tickets)
+    errors += _cycles(tickets)
+    return ([], errors) if errors else (tickets, [])
+
+
+def max_frontier_width(tickets: list[Ticket]) -> int:
+    """The most tickets ready at once when every ready ticket merges before the next start."""
+    by = {t.number: t for t in tickets}
+    depths: dict[str, int] = {}
+
+    def depth(number: str) -> int:
+        if number not in depths:
+            depths[number] = 1 + max((depth(b) for b in by[number].blocked_by), default=0)
+        return depths[number]
+
+    # ponytail: blocking edges only; Touches holds belong to the scheduler (ticket 03).
+    return max(Counter(depth(n) for n in by).values())