@jesdi/skills 0.0.26 → 0.0.28

package/README.md

@@ -47,8 +47,25 @@ npx @jesdi/skills-cli update [skill] [--all] [--global]
 npx @jesdi/skills-cli sync
 npx @jesdi/skills-cli list
 npx @jesdi/skills-cli uninstall <skill> [--global]
+npx @jesdi/skills-cli pin <skill> [--global]     # keep the installed version
+npx @jesdi/skills-cli unpin <skill> [--global]
+npx @jesdi/skills-cli hook                 # register the session update hook
 ```
 
+## Automatic updates
+
+A global install registers a session-start hook in Claude Code
+(`~/.claude/settings.json`) and Codex (`~/.codex/hooks.json`), for each one
+that is present. The first session of a day runs
+`skills-cli update --all --global` in the background; the result is in
+`~/.my-skills/.session-update.log`. Project installs do not change: they stay
+at the versions committed in `.my-skills.json`.
+
+To keep a skill at its installed version, pin it: `skills-cli pin <skill>
+--global`. No update touches a pinned skill until `unpin`. To stop all
+automatic updates, remove the hook entry from the two config files; the next
+global install or `skills-cli hook` adds it again.
+
 ## Third-party skills (not vendored)
 
 Skills authored by other people are **not** copied into this repo — they keep

package/package.json

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

package/skills/backlog/SKILL.md

@@ -199,10 +199,9 @@ Reuse the **dedup discipline** from the `file-bug-issue` skill, but take the
      sink an issue below the unboosted pack. Dispatchers set 99 for "work on this
      next". `--json` rows carry `"boost"`.
 4. Apply, in order, the `references/graphql.md` → Triage commands:
-   add to project → set Impact/Effort (`--number`) → set
-   `Score` = round(Impact ÷ Effort, 1) (`--number`) → set Area +
-   `Status: Ready` (`--single-select-option-id`) → append `Blocked by: #…`
-   to the body if any → `--remove-label inbox`.
+   add to project → set Impact, Effort, `Score` = round(Impact ÷ Effort, 1),
+   Area and `Status: Ready` in the single mutation given there → append
+   `Blocked by: #…` to the body if any → `--remove-label inbox`.
 5. After each, confirm it is now triaged (fields set, `inbox` gone). Report a
    summary of promoted vs. left-in-inbox.
 
@@ -223,7 +222,9 @@ python3 .claude/skills/backlog/rank.py --json   # machine-readable rows for
 `.agents/skills/backlog/rank.py`. The key is that the working directory stays at
 or below the repo root so `rank.py` can walk up to `.backlog/`.)
 
-`rank.py` pulls Project items + issue bodies via `gh`, parses `Blocked by:`
+`rank.py` pulls Project items (one narrow GraphQL query per 100 items, so it is
+cheap to run often; it warns on stderr when the hourly GraphQL budget is low)
++ issue bodies via `gh`, parses `Blocked by:`
 edges, drops closed/`Done` blockers, and prints:
 
 - **Available** issues ranked boost-band first, then Impact÷Effort within a band

package/skills/backlog/rank.py

@@ -3,6 +3,7 @@ import json
 import os
 import re
 import subprocess
+import sys
 
 _BLOCKED_LINE = re.compile(r"^\s*Blocked by:\s*(.+)$", re.IGNORECASE | re.MULTILINE)
 _ISSUE_REF = re.compile(r"#(\d+)")
@@ -187,8 +188,14 @@ def render(result):
 
 
 def _gh_json(args, env=None):
-    completed = subprocess.run(args, capture_output=True, text=True, check=True,
-                               env=env)
+    try:
+        completed = subprocess.run(args, capture_output=True, text=True,
+                                   check=True, env=env)
+    except subprocess.CalledProcessError as error:
+        # gh's own message (rate limit, auth, scope) is the diagnosis; a
+        # traceback quoting the whole query buries it.
+        sys.exit(f"gh {' '.join(args[1:3])} failed: "
+                 f"{(error.stderr or '').strip() or error}")
     return json.loads(completed.stdout)
 
 
@@ -200,12 +207,64 @@ def _project_env():
     return {**os.environ, "GH_TOKEN": token} if token else None
 
 
-def main(owner, project_number, repo, as_json=False):
-    payload = _gh_json([
-        "gh", "project", "item-list", str(project_number),
-        "--owner", owner, "--format", "json", "--limit", "200",
-    ], env=_project_env())
-    project_items = payload.get("items", [])
+# One page of board items with only what ranking reads. `gh project item-list`
+# asks for every field and several nested connections per item, which costs
+# on the order of 100 rate-limit points per call on a ~100-item board; this
+# costs about 1 per page. Aliases mirror the item-list JSON keys so
+# merge_sources takes either shape.
+_BOARD_QUERY = """
+query($project: ID!, $cursor: String) {
+  rateLimit { remaining }
+  node(id: $project) { ... on ProjectV2 { items(first: 100, after: $cursor) {
+    pageInfo { hasNextPage endCursor }
+    nodes {
+      id
+      content { ... on Issue { number title url } }
+      title: fieldValueByName(name: "Title") { ... on ProjectV2ItemFieldTextValue { text } }
+      status: fieldValueByName(name: "Status") { ... on ProjectV2ItemFieldSingleSelectValue { name } }
+      area: fieldValueByName(name: "Area") { ... on ProjectV2ItemFieldSingleSelectValue { name } }
+      impact: fieldValueByName(name: "Impact") { ... on ProjectV2ItemFieldNumberValue { number } }
+      effort: fieldValueByName(name: "Effort") { ... on ProjectV2ItemFieldNumberValue { number } }
+      boost: fieldValueByName(name: "Boost") { ... on ProjectV2ItemFieldNumberValue { number } }
+    }
+  } } }
+}
+"""
+LOW_BUDGET = 500  # GraphQL points left (of 5000/h) below which main() warns
+
+
+def _field(node, alias):
+    value = node.get(alias) or {}
+    return next(iter(value.values()), None)
+
+
+def fetch_board(project_id):
+    """Every board item as item-list-shaped rows, plus the GraphQL budget left."""
+    items, cursor, remaining = [], None, None
+    while True:
+        args = ["gh", "api", "graphql", "-f", f"query={_BOARD_QUERY}",
+                "-f", f"project={project_id}"]
+        if cursor:
+            args += ["-f", f"cursor={cursor}"]
+        data = _gh_json(args, env=_project_env())["data"]
+        remaining = data["rateLimit"]["remaining"]
+        page = data["node"]["items"]
+        for node in page["nodes"]:
+            items.append({
+                "id": node["id"], "content": node.get("content") or {},
+                **{alias: _field(node, alias) for alias in
+                   ("title", "status", "area", "impact", "effort", "boost")},
+            })
+        if not page["pageInfo"]["hasNextPage"]:
+            return items, remaining
+        cursor = page["pageInfo"]["endCursor"]
+
+
+def main(project_id, repo, as_json=False):
+    project_items, remaining = fetch_board(project_id)
+    if remaining < LOW_BUDGET:
+        print(f"warning: GitHub GraphQL budget is low ({remaining} points left "
+              f"this hour)", file=sys.stderr)
     issue_rows = _gh_json([
         "gh", "issue", "list", "--repo", repo, "--state", "all",
         "--limit", "500", "--json", "number,title,url,body,state,labels",
@@ -240,9 +299,7 @@ def find_project_meta(start=None):
 
 
 if __name__ == "__main__":
-    import sys
     config_path = find_project_meta()
     with open(config_path) as handle:
         meta = json.load(handle)
-    main(meta["owner"], meta["projectNumber"], meta["repo"],
-         as_json="--json" in sys.argv[1:])
+    main(meta["projectId"], meta["repo"], as_json="--json" in sys.argv[1:])

package/skills/backlog/references/graphql.md

@@ -11,6 +11,17 @@ gh auth status                     # confirm login
 gh auth refresh -s project         # add Projects-v2 write scope (one-time)
 ```
 
+## Rate limit — do not read the whole board for one item
+
+GitHub allows 5000 GraphQL points per hour per user, shared by every tool and
+agent on that login. `gh project item-list` costs on the order of 100 points
+per call on a ~100-item board, so a few dozen calls empty the budget. Read the
+true budget with `gh api graphql -f query='{rateLimit{remaining resetAt}}'`
+(`gh api rate_limit` can show a different number). `rank.py` reads the board
+with a narrow query (about 1 point per 100 items); the lookups below go from
+the issue to its item (1 point). Use `item-list` only for the first read of a
+triage session, and reuse its output.
+
 ## Setup — create the board (idempotent; skip a step if it already exists)
 
 ```bash
@@ -77,22 +88,16 @@ gh issue create --repo <repo> \
 # Add issue to the project (prints the item id; capture it)
 gh project item-add <projectNumber> --owner <owner> --url <issueUrl>
 
-# Set number fields
-gh project item-edit --project-id <projectId> --id <itemId> \
-  --field-id <fields.Impact.id> --number <1-5>
-gh project item-edit --project-id <projectId> --id <itemId> \
-  --field-id <fields.Effort.id> --number <1-5>
-gh project item-edit --project-id <projectId> --id <itemId> \
-  --field-id <fields.Score.id> --number <round(impact/effort, 1)>
-# Optional: manual priority override (default 0; positive boosts above unboosted, negative sinks below)
-gh project item-edit --project-id <projectId> --id <itemId> \
-  --field-id <fields.Boost.id> --number <n>
-
-# Set single-selects (use the option id from .backlog/project-meta.json)
-gh project item-edit --project-id <projectId> --id <itemId> \
-  --field-id <fields.Area.id> --single-select-option-id <fields.Area.options[area]>
-gh project item-edit --project-id <projectId> --id <itemId> \
-  --field-id <fields.Status.id> --single-select-option-id <fields.Status.options.Ready>
+# Set all five fields in ONE request (one point, one round trip). Values come
+# from .backlog/project-meta.json; Score = round(impact/effort, 1). Add a
+# `boost:` alias with <fields.Boost.id> for a manual priority override.
+gh api graphql -F p=<projectId> -F i=<itemId> -f query='mutation($p:ID!,$i:ID!){
+  impact:updateProjectV2ItemFieldValue(input:{projectId:$p,itemId:$i,fieldId:"<fields.Impact.id>",value:{number:<1-5>}}){clientMutationId}
+  effort:updateProjectV2ItemFieldValue(input:{projectId:$p,itemId:$i,fieldId:"<fields.Effort.id>",value:{number:<1-5>}}){clientMutationId}
+  score:updateProjectV2ItemFieldValue(input:{projectId:$p,itemId:$i,fieldId:"<fields.Score.id>",value:{number:<score>}}){clientMutationId}
+  area:updateProjectV2ItemFieldValue(input:{projectId:$p,itemId:$i,fieldId:"<fields.Area.id>",value:{singleSelectOptionId:"<fields.Area.options[area]>"}}){clientMutationId}
+  status:updateProjectV2ItemFieldValue(input:{projectId:$p,itemId:$i,fieldId:"<fields.Status.id>",value:{singleSelectOptionId:"<fields.Status.options.Ready>"}}){clientMutationId}
+}'
 
 # Record blocking edges (append a line; keep any existing body)
 gh issue edit <number> --repo <repo> --body "<body>\n\nBlocked by: #<a>, #<b>"
@@ -121,8 +126,12 @@ gh api graphql -f query='mutation($parent:ID!,$child:ID!){
 
 ```bash
 gh issue view <number> --repo <repo> --json state --jq .state
-gh project item-list <projectNumber> --owner <owner> --format json \
-  --jq '.items[] | select(.content.number==<number>) | {id, status}'
+gh api graphql -f query='query($owner:String!,$repo:String!,$n:Int!){
+  repository(owner:$owner,name:$repo){issue(number:$n){projectItems(first:10){nodes{
+    id project{id}
+    status:fieldValueByName(name:"Status"){... on ProjectV2ItemFieldSingleSelectValue{name}}}}}}}' \
+  -F owner=<owner> -F repo=<repoName> -F n=<number> \
+  --jq '.data.repository.issue.projectItems.nodes[] | select(.project.id=="<projectId>") | {id, status: .status.name}'
 # repair only if needed:
 gh issue close <number> --repo <repo>
 gh project item-edit --project-id <projectId> --id <itemId> \
@@ -133,8 +142,12 @@ gh project item-edit --project-id <projectId> --id <itemId> \
 
 ```bash
 # 1. Item id + live status
-gh project item-list <projectNumber> --owner <owner> --format json \
-  --jq '.items[] | select(.content.number==<number>) | {id, status}'
+gh api graphql -f query='query($owner:String!,$repo:String!,$n:Int!){
+  repository(owner:$owner,name:$repo){issue(number:$n){projectItems(first:10){nodes{
+    id project{id}
+    status:fieldValueByName(name:"Status"){... on ProjectV2ItemFieldSingleSelectValue{name}}}}}}}' \
+  -F owner=<owner> -F repo=<repoName> -F n=<number> \
+  --jq '.data.repository.issue.projectItems.nodes[] | select(.project.id=="<projectId>") | {id, status: .status.name}'
 # 2. If status == "In progress": abort (already claimed).
 # 3. Claim:
 gh project item-edit --project-id <projectId> --id <itemId> \

package/skills/backlog/test_rank.py

@@ -279,30 +279,122 @@ def test_json_rows_flags_blocked_and_keeps_rank_order():
     assert "url" in row
 
 
-def test_main_json_emits_machine_readable_rows(monkeypatch, capsys):
+def _board_page(nodes, next_cursor=None, remaining=4000):
     import json as jsonlib
-    monkeypatch.delenv("GH_PROJECT_TOKEN", raising=False)
+    return jsonlib.dumps({"data": {
+        "rateLimit": {"remaining": remaining},
+        "node": {"items": {
+            "pageInfo": {"hasNextPage": next_cursor is not None,
+                         "endCursor": next_cursor},
+            "nodes": nodes}}}})
+
+
+def _board_node(number, title="Task", **fields):
+    """A GraphQL item node: `content` is None when the token cannot see the repo."""
+    node = {"id": f"PVTI_{number}",
+            "content": ({"number": number, "title": title, "url": f"u/{number}"}
+                        if number is not None else None),
+            "title": {"text": title}}
+    wrap = {"status": "name", "area": "name"}
+    for alias in ("status", "area", "impact", "effort", "boost"):
+        value = fields.get(alias)
+        node[alias] = None if value is None else {wrap.get(alias, "number"): value}
+    return node
+
+
+def _fake_gh(pages, issues="[]", calls=None):
+    """subprocess.run stand-in: board pages in order, then the issue list."""
+    pages = list(pages)
+
     def fake_run(args, capture_output, text, check, env=None):
+        if calls is not None:
+            calls.append((args, env))
+
         class R:
-            if args[1] == "project":
-                stdout = jsonlib.dumps({"items": [
-                    {"content": {"number": 5, "title": "Task", "url": "u/5"},
-                     "status": "Ready", "impact": 4, "effort": 2}]})
-            else:
-                fields = args[args.index("--json") + 1]
-                assert "labels" in fields
-                assert "title" in fields and "url" in fields  # title-join keys
-                stdout = jsonlib.dumps([
-                    {"number": 5, "body": "", "state": "open",
-                     "labels": [{"name": "auto"}]}])
+            stdout = pages.pop(0) if args[1] == "api" else issues
         return R()
+    return fake_run
 
-    monkeypatch.setattr(rank.subprocess, "run", fake_run)
-    rank.main("acme", 1, "acme/private-repo", as_json=True)
+
+def test_main_json_emits_machine_readable_rows(monkeypatch, capsys):
+    import json as jsonlib
+    monkeypatch.delenv("GH_PROJECT_TOKEN", raising=False)
+    calls = []
+    issues = jsonlib.dumps([{"number": 5, "body": "", "state": "open",
+                             "labels": [{"name": "auto"}]}])
+    monkeypatch.setattr(rank.subprocess, "run", _fake_gh(
+        [_board_page([_board_node(5, status="Ready", impact=4.0, effort=2.0)])],
+        issues, calls))
+    rank.main("PVT_1", "acme/private-repo", as_json=True)
     rows = jsonlib.loads(capsys.readouterr().out)
     assert rows == [{"number": 5, "title": "Task", "url": "u/5",
                      "status": "Ready", "labels": ["auto"],
                      "blocked": False, "score": 2.0, "boost": 0}]
+    fields = calls[1][0][calls[1][0].index("--json") + 1]
+    assert "labels" in fields
+    assert "title" in fields and "url" in fields  # title-join keys
+
+
+def test_board_read_never_uses_item_list(monkeypatch):
+    """`gh project item-list` costs ~100 rate-limit points a call; the board
+    is read with one narrow GraphQL query per 100 items instead."""
+    monkeypatch.delenv("GH_PROJECT_TOKEN", raising=False)
+    calls = []
+    monkeypatch.setattr(rank.subprocess, "run", _fake_gh([_board_page([])], calls=calls))
+    rank.main("PVT_1", "acme/repo")
+    board_args = calls[0][0]
+    assert board_args[:3] == ["gh", "api", "graphql"]
+    assert "project=PVT_1" in board_args
+    assert not any(args[1] == "project" for args, _ in calls)
+
+
+def test_fetch_board_follows_pagination(monkeypatch):
+    monkeypatch.delenv("GH_PROJECT_TOKEN", raising=False)
+    calls = []
+    monkeypatch.setattr(rank.subprocess, "run", _fake_gh(
+        [_board_page([_board_node(1)], next_cursor="c1"),
+         _board_page([_board_node(2)], remaining=3990)], calls=calls))
+    items, remaining = rank.fetch_board("PVT_1")
+    assert [i["content"]["number"] for i in items] == [1, 2]
+    assert remaining == 3990
+    assert "cursor=c1" not in calls[0][0] and "cursor=c1" in calls[1][0]
+
+
+def test_fetch_board_redacted_content_keeps_title_for_the_join(monkeypatch):
+    monkeypatch.delenv("GH_PROJECT_TOKEN", raising=False)
+    monkeypatch.setattr(rank.subprocess, "run", _fake_gh(
+        [_board_page([_board_node(None, title="Private task", status="Ready")])]))
+    items, _ = rank.fetch_board("PVT_1")
+    assert items[0]["content"] == {} and items[0]["title"] == "Private task"
+    merged = rank.merge_sources(items, [
+        {"number": 9, "title": "Private task", "url": "u/9", "state": "open"}])
+    assert [(i["number"], i["status"]) for i in merged] == [(9, "Ready")]
+
+
+def test_a_failing_gh_call_exits_with_ghs_own_message(monkeypatch):
+    def refused(args, capture_output, text, check, env=None):
+        raise rank.subprocess.CalledProcessError(
+            1, args, stderr="GraphQL: API rate limit exceeded for user ID 1.\n")
+    monkeypatch.setattr(rank.subprocess, "run", refused)
+    with pytest.raises(SystemExit) as exc:
+        rank.main("PVT_1", "acme/repo")
+    assert str(exc.value) == ("gh api graphql failed: GraphQL: API rate limit "
+                              "exceeded for user ID 1.")
+
+
+def test_main_warns_when_graphql_budget_is_low(monkeypatch, capsys):
+    monkeypatch.delenv("GH_PROJECT_TOKEN", raising=False)
+    monkeypatch.setattr(rank.subprocess, "run", _fake_gh(
+        [_board_page([], remaining=120)]))
+    rank.main("PVT_1", "acme/repo")
+    assert "120 points left" in capsys.readouterr().err
+
+
+def test_main_is_quiet_when_graphql_budget_is_healthy(monkeypatch, capsys):
+    monkeypatch.delenv("GH_PROJECT_TOKEN", raising=False)
+    monkeypatch.setattr(rank.subprocess, "run", _fake_gh([_board_page([])]))
+    rank.main("PVT_1", "acme/repo")
+    assert capsys.readouterr().err == ""
 
 
 def test_project_env_absent_without_token(monkeypatch):
@@ -319,19 +411,10 @@ def test_project_env_swaps_gh_token(monkeypatch):
 def test_main_uses_project_token_only_for_project_call(monkeypatch):
     monkeypatch.setenv("GH_PROJECT_TOKEN", "classic-tok")
     calls = []
-
-    def fake_run(args, capture_output, text, check, env=None):
-        calls.append((args, env))
-
-        class R:
-            stdout = "{\"items\": []}" if args[1] == "project" else "[]"
-
-        return R()
-
-    monkeypatch.setattr(rank.subprocess, "run", fake_run)
-    rank.main("acme", 1, "acme/private-repo")
+    monkeypatch.setattr(rank.subprocess, "run", _fake_gh([_board_page([])], calls=calls))
+    rank.main("PVT_1", "acme/private-repo")
     project_call, issue_call = calls
-    assert project_call[0][1] == "project"
+    assert project_call[0][1] == "api"
     assert project_call[1]["GH_TOKEN"] == "classic-tok"
     assert issue_call[0][1] == "issue"
     assert issue_call[1] is None  # stored gh auth (repo PAT) stays active

package/skills/implement-spec/SKILL.md

@@ -15,7 +15,8 @@ a per-ticket gate (check command + crap-gate) before DONE, re-run by the reviewe
 already-green locked tests need a demonstrated mutation; a Codex correctness
 pass per risky ticket; tickets touching the same functions run in sequence;
 check command after each merge; final /review-diff on the most capable model, one
-fixer; closes tickets only if they are issues; no push and no PR until every
+fixer; ticket-grouped history with fixes folded in before review; closes
+tickets only if they are issues; no push and no PR until every
 ticket is merged and the final review has passed. Review loop and ledger adapt
 superpowers' subagent-driven-development (obra/superpowers, MIT).
 -->
@@ -57,14 +58,14 @@ Run ticket subagents in the background where possible for **maximum concurrency*
 
    Critical or Important findings start a fix loop of at most 4 rounds, each a fix plus a re-review scoped to that fix: rounds 1-2 resume the implementer; rounds 3-4 go to a fresh implementer one tier up. After round 4, rule on each open finding in the ledger and move on. Minor findings go to the ledger for the final review.
 
-7. Once a ticket passes review, a **merger subagent** merges it to the PR branch and runs the repo's check command (lint, typecheck, full suite). If it fails, an implementer fixes the PR branch before the next merge.
+7. Once a ticket passes review, a **merger subagent** merges it to the PR branch and runs the repo's check command (lint, typecheck, full suite). If it fails, an implementer fixes the PR branch before the next merge. Record the ticket's commits and any integration fixes in the ledger. After the merge and checks pass, remove that ticket's worktree and delete its branch with `git branch -d` from the PR branch, while its commits are still ancestors of the PR tip. Cleanup is part of completing the ticket, before any rebase.
 
 8. If this changes the **frontier** of available tickets, start the next tickets. This allows for maximum concurrency. Exception: two ready tickets that change the same function never run at once. Compare their **Touches** lines (or ask the exploration subagent where each will land); on overlap, start one and hold the other until the first merges, then branch it from the updated PR branch. When in doubt, hold: a ticket you suspect builds on another ready or running ticket waits for it, even without a declared edge. Record the hold as a ruling.
 
-9. Once all tickets are complete, a reviewer on the most capable model runs /review-diff on the PR branch, given the ledger's minor findings and rulings. One **implementer subagent** fixes every finding, then re-review that fix once. Rule on anything left.
+9. Once all tickets are complete, fetch and rebase the unpublished PR branch onto the latest base, then tidy its history by ticket using [history.md](history.md). A reviewer on the most capable model runs /review-diff on the resulting PR branch, given the ledger's minor findings and rulings. Record its resolved range and reviewed tip in the ledger. One **implementer subagent** fixes every finding as one batch, which may contain several working commits; it records the owning ticket for each fix. Use targeted checks during the fixes. Once the whole batch is complete, tidy it into the ticket commits, then run /review-diff on the full rewritten branch. If history was preserved, a scoped /review-diff on `<last-reviewed-tip>..HEAD` suffices. Its gate runs once for the completed batch. Record the new review's range and tip, marking superseded coverage, or `not needed` if there were no fixes. Rule on anything left.
 
-10. Now, and only now, push the PR branch once and open the PR, ready for review (not draft). If the
-    spec and tickets are issues, mark the PR as 'closing' them. List every ruling from the ledger in
-    your final message.
+10. Before pushing, compare `git rev-parse HEAD` with the last reviewed tip and confirm the worktree is clean. Every commit through the branch tip must be covered by the full review plus any scoped re-reviews. Collect any later commits, including orchestrator changes, into one batch and follow step 9's tidy-and-review procedure. A rebase or history rewrite invalidates the recorded coverage: review the full rewritten branch, with one full gate for that completed batch. The push is ready only when the history is grouped by ticket, the clean branch tip equals the last reviewed tip, and every finding has a fix or a ledger ruling. If the review cannot finish, report the blocker and each unreviewed commit with its subject, and keep the branch local.
 
-11. Clean up all ticket worktrees.
+    Now push the PR branch once and open the PR, ready for review (not draft), using /pr for the body when installed. If the spec and tickets are issues, mark the PR as 'closing' them. In your final message, list every ruling, the final ticket-to-commit map, and the review coverage: the latest full review's range and tip, any scoped re-review ranges and tips since it (or `not needed`), the current branch tip, and whether it equals the last reviewed tip. Earlier reviews of superseded history stay in the ledger.
+
+11. Confirm every ticket worktree and branch was removed in step 7.

package/skills/implement-spec/history.md

@@ -0,0 +1,52 @@
+# History by ticket
+
+Tidy the unpublished integration branch into one coherent commit per ticket,
+ordered so each ticket follows its dependencies. Each commit contains that
+ticket's acceptance tests, implementation, and all review or integration fixes.
+The reviewer's commit list should tell the story of the tickets, with the
+final behavior at each step.
+
+## Before rewriting
+
+- Confirm all ticket worktrees and branches were cleaned up after their merges,
+  and that the integration worktree is clean.
+- Confirm the branch has never been pushed. Once pushed, preserve its history
+  and add reviewed follow-up commits; rewriting a published branch requires
+  explicit user authorization.
+- Record the current tip and `HEAD^{tree}` in the ledger as the recovery point.
+  Use the ticket reports and ledger to map every working commit and every fix
+  to its owning ticket before editing history.
+
+## Group the changes
+
+Use an interactive rebase or reconstruct the commits in an isolated worktree,
+operating only on branch-owned commits after the base. Fold red-test commits,
+implementation commits, and later fixes into their ticket commit. Flatten
+branch-only merge commits while preserving their conflict-resolution changes.
+Keep the test-writer's acceptance files unchanged from their locked versions.
+
+A fix touching several tickets is split by ownership when the resulting
+commits can stand alone in dependency order. If it cannot be split safely,
+combine the affected tickets into one coherent commit, name them in the
+message, and record the reason in the ledger. Every final change has a ticket
+owner; an out-of-scope change needs a ruling before inclusion.
+
+Use a commit subject that names the ticket's delivered behavior and put its
+ticket number or file pointer in the body. Keep a map from the old working
+commits to the final ticket commits in the ledger; ticket reports and locked
+test SHAs still refer to the original history.
+
+## Completion
+
+The rewritten tip's tree must equal the saved tree: history cleanup changes
+the presentation of the work, not its files. A mismatch must be resolved
+before review. Inspect each final commit's diff against its ticket to confirm
+the tests, implementation, and fixes stayed together, dependencies precede
+their consumers, and no temporary red-test or fix-only commits remain.
+
+Use targeted checks where needed to verify a regrouped ticket. Run the full
+gate once at the completed branch tip, through /review-diff. Rewriting changes
+the review endpoints, so the next review covers the full rewritten branch;
+mark the old coverage superseded even if the tip's tree is identical. After a
+review requests fixes, finish the whole fix batch, fold it into these same
+ticket commits, and repeat this completion check before the next review.

package/skills/review-diff/SKILL.md

@@ -37,6 +37,15 @@ on one axis must not hide a failure on another.
 Before anything else, confirm the range resolves and the diff is non-empty. A
 bad ref fails here, not inside three reviewers.
 
+Resolve the diff endpoints to commit SHAs once, before the gate, and use that
+immutable range for every reviewer and the commit list. For a base ref, the
+start is its merge-base with the captured `HEAD`; for an explicit range, keep
+its requested diff semantics. Record the reviewed tip (the right endpoint)
+and the branch tip at the start. Run the gate on that reviewed tip in a clean
+worktree; an explicit range ending at another commit needs a worktree at that
+commit. Local changes must be committed or removed before review so the range
+accounts for everything checked.
+
 ## Step 0 — gate (sequential, a precondition, not a reviewer)
 
 1. Run the repo's check command: `make check` if the Makefile has it,
@@ -70,7 +79,7 @@ paste one reviewer's output into another's prompt.
   ```bash
   out=$(mktemp) && codex exec -s read-only --ephemeral -o "$out" \
     "Read and follow <skill-dir>/correctness.md. Range: <range>. Commits: <list>.<quick>" \
-    >/dev/null 2>&1; cat "$out"
+    < /dev/null >/dev/null 2>&1; cat "$out"
   ```
 
   No Codex → spawn a subagent with the same instruction and note "Correctness:
@@ -88,6 +97,7 @@ fresh context if you can, and say so.
 
 ```
 Gate: `make check` green · crap-gate green
+Coverage: <resolved range> · reviewed tip: <SHA> · current branch tip: <SHA> · tip matches: yes/no
 
 ## Spec
 <report, verbatim or lightly cleaned>
@@ -107,6 +117,15 @@ A skipped step keeps its place with its one-line note (in the gate line, or
 as the section body and summary line). `--quick` has no Structure section and
 no Structure summary line. A clean reviewer's summary line is `0 findings`.
 
+Read the original branch tip again when reporting. Include the coverage line
+in full and quick reviews, and label a failed gate `review not run` rather
+than calling its endpoint reviewed. Name skipped or failed reviewers so the
+coverage line cannot imply they ran. If the branch tip changed, list each
+commit in `<reviewed-tip>..<current-tip>` with its subject. If the reviewed tip
+is no longer an ancestor (for example, after a rebase or history cleanup), state that this review
+does not cover the current history. Report a dirty worktree as unreviewed
+local changes even when the tips match.
+
 Do not merge, dedupe or re-rank findings across reviewers, and do not pick an
 overall winner. A finding two reviewers both raise stays in both reports; that
 is signal.

package/skills-manifest.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-10-02T10:20:34.972Z",
+  "generatedAt": "2026-10-08T10:41:10.504Z",
   "skills": [
     {
       "name": "backlog",
-      "version": "0.1.7",
-      "hash": "sha256-652964aebeadbd2a4ecafd5a588f0bd0c31b90442f3133f64d7d663893a1f7a0",
+      "version": "0.1.8",
+      "hash": "sha256-5bd474d3b3ffbb3af23380663c24c8a8d3ba263cfd4dbe7e636879595e6995b8",
       "description": "Manage a GitHub-Issues-backed backlog and a Projects-v2 work graph via five verbs. Use when the user wants to CAPTURE an idea/research thread (\"add to backlog\", \"capture this\", \"note this idea\", \"log a task\"), TRIAGE the inbox (\"triage the backlog\", \"score the inbox\"), see what to work on NEXT (\"what's next\", \"what should I work on\", \"ranked backlog\", \"next actionable task\"), LAND a finished item (\"mark done\", \"close out #N\"), or SETUP the board the first time. Ranks open issues by impact÷effort, respecting `Blocked by:` edges, so only actionable work surfaces."
     },
     {
@@ -46,8 +46,8 @@
     },
     {
       "name": "implement-spec",
-      "version": "0.1.5",
-      "hash": "sha256-43b1b1b97386b96b2cc8124ca906ffc0a5a4b35362413b52ac154c1faaa0b43e",
+      "version": "0.1.6",
+      "hash": "sha256-836f28be9230179d7389ef5ed8e1dacadd43d649a20a06f32adb891d5a4c1357",
       "description": "Implement a specification in code."
     },
     {
@@ -70,8 +70,8 @@
     },
     {
       "name": "review-diff",
-      "version": "0.1.1",
-      "hash": "sha256-ac4b526f0436f06acc4e5e2254b83b5318a14065caab3f922f20fa7da9e87c5f",
+      "version": "0.1.2",
+      "hash": "sha256-70beaf1478820d66e1831d45739ce97ced50224b46c5003d887ea62c8438f251",
       "description": "Review a branch before merge: first a gate (the repo's check command plus crap-gate), then three independent reviewers in parallel — spec (did we build what was asked, no more, no less), correctness via Codex (races, idempotency, money, time, authz, indexes, N+1, migrations, error paths, test quality) and structure (deep-quality-review). `--quick` runs only spec and correctness, shortened, for a live interview. Use when the user says \"/review-diff\", \"review this branch\", \"review this slice\", \"review before merge\", or before closing out a spec task."
     },
     {