@jesdi/skills 0.0.26 → 0.0.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jesdi/skills",
-  "version": "0.0.26",
+  "version": "0.0.27",
   "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-manifest.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-10-02T10:20:34.972Z",
+  "generatedAt": "2026-10-06T10:03:53.513Z",
   "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."
     },
     {