@jesdi/skills 0.0.3 → 0.0.5

package/package.json

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

package/skills/backlog/SKILL.md

@@ -151,7 +151,11 @@ Runs the pure engine; makes no writes. Run **from the project root** (so the cwd
 walk-up finds `.backlog/project-meta.json`); do **not** `cd` into the skill dir:
 
 ```bash
-python3 .claude/skills/backlog/rank.py
+python3 .claude/skills/backlog/rank.py          # human-readable table
+python3 .claude/skills/backlog/rank.py --json   # machine-readable rows for
+                                                # dispatchers: number, title,
+                                                # url, status, labels, blocked,
+                                                # score
 ```
 
 (Use whichever agent-skills path the store symlinked the skill into — e.g.

package/skills/backlog/rank.py

@@ -48,6 +48,7 @@ def merge_sources(project_items, issue_rows):
             "impact": _as_int(item.get("impact")),
             "effort": _as_int(item.get("effort")),
             "area": item.get("area"),
+            "labels": [l["name"] for l in row.get("labels") or []],
         })
     return merged
 
@@ -111,6 +112,27 @@ def rank_issues(issues):
     }
 
 
+def to_json_rows(result):
+    """Flat machine-readable rows for `--json` consumers (e.g. dispatchers):
+    available issues in rank order, then blocked, then in-progress."""
+    rows = []
+    for issue, blocked in (
+        [(i, False) for i in result["available"]]
+        + [(i, True) for i in result["blocked"]]
+        + [(i, False) for i in result["in_progress"]]
+    ):
+        rows.append({
+            "number": issue["number"],
+            "title": issue["title"],
+            "url": issue["url"],
+            "status": issue.get("status"),
+            "labels": issue.get("labels", []),
+            "blocked": blocked,
+            "score": score(issue),
+        })
+    return rows
+
+
 def render(result):
     lines = []
     if result["in_progress"]:
@@ -139,23 +161,36 @@ def render(result):
     return "\n".join(lines)
 
 
-def _gh_json(args):
-    completed = subprocess.run(args, capture_output=True, text=True, check=True)
+def _gh_json(args, env=None):
+    completed = subprocess.run(args, capture_output=True, text=True, check=True,
+                               env=env)
     return json.loads(completed.stdout)
 
 
-def main(owner, project_number, repo):
+def _project_env():
+    """User-owned Projects v2 are invisible to fine-grained PATs, so when
+    GH_PROJECT_TOKEN is set, `gh project` calls run with GH_TOKEN swapped to
+    it; every other gh call keeps the stored auth (which can read the repo)."""
+    token = os.environ.get("GH_PROJECT_TOKEN")
+    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", [])
     issue_rows = _gh_json([
         "gh", "issue", "list", "--repo", repo, "--state", "all",
-        "--limit", "500", "--json", "number,body,state",
+        "--limit", "500", "--json", "number,body,state,labels",
     ])
     issues = merge_sources(project_items, issue_rows)
-    print(render(rank_issues(issues)))
+    result = rank_issues(issues)
+    if as_json:
+        print(json.dumps(to_json_rows(result)))
+    else:
+        print(render(result))
 
 
 def find_project_meta(start=None):
@@ -180,7 +215,9 @@ 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"])
+    main(meta["owner"], meta["projectNumber"], meta["repo"],
+         as_json="--json" in sys.argv[1:])

package/skills/backlog/test_rank.py

@@ -206,6 +206,95 @@ def test_find_project_meta_nearest_ancestor_wins(tmp_path, monkeypatch):
     assert rank.find_project_meta() == str(inner_meta)
 
 
+def test_merge_sources_carries_label_names():
+    out = rank.merge_sources(
+        [{"content": {"number": 7, "title": "T", "url": "u/7"}}],
+        [{"number": 7, "body": "", "state": "open",
+          "labels": [{"name": "auto"}, {"name": "bug"}]}],
+    )
+    assert out[0]["labels"] == ["auto", "bug"]
+
+
+def test_merge_sources_defaults_labels_empty():
+    out = rank.merge_sources(
+        [{"content": {"number": 7, "title": "T", "url": "u/7"}}], [])
+    assert out[0]["labels"] == []
+
+
+def test_json_rows_flags_blocked_and_keeps_rank_order():
+    issues = [
+        _scored(1, 2, 2),                          # score 1.0
+        _scored(2, 5, 1),                          # score 5.0 -> first
+        _scored(3, 9, 1, body="Blocked by: #2"),   # blocked
+        _scored(4, 4, 1, status="In progress"),    # claimed
+    ]
+    for i in issues:
+        i["labels"] = ["auto"]
+    rows = rank.to_json_rows(rank.rank_issues(issues))
+    assert [(r["number"], r["blocked"]) for r in rows] == [
+        (2, False), (1, False), (3, True), (4, False)]
+    row = rows[0]
+    assert row["title"] == "i2" and row["status"] == "Ready"
+    assert row["labels"] == ["auto"]
+    assert "url" in row
+
+
+def test_main_json_emits_machine_readable_rows(monkeypatch, capsys):
+    import json as jsonlib
+    monkeypatch.delenv("GH_PROJECT_TOKEN", raising=False)
+    def fake_run(args, capture_output, text, check, env=None):
+        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:
+                assert "labels" in args[args.index("--json") + 1]
+                stdout = jsonlib.dumps([
+                    {"number": 5, "body": "", "state": "open",
+                     "labels": [{"name": "auto"}]}])
+        return R()
+
+    monkeypatch.setattr(rank.subprocess, "run", fake_run)
+    rank.main("acme", 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}]
+
+
+def test_project_env_absent_without_token(monkeypatch):
+    monkeypatch.delenv("GH_PROJECT_TOKEN", raising=False)
+    assert rank._project_env() is None
+
+
+def test_project_env_swaps_gh_token(monkeypatch):
+    monkeypatch.setenv("GH_PROJECT_TOKEN", "classic-tok")
+    env = rank._project_env()
+    assert env["GH_TOKEN"] == "classic-tok"
+
+
+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")
+    project_call, issue_call = calls
+    assert project_call[0][1] == "project"
+    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
+
+
 def test_find_project_meta_errors_clearly_when_absent(tmp_path, monkeypatch):
     monkeypatch.chdir(tmp_path)
     with pytest.raises(FileNotFoundError) as exc:

package/skills-manifest.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-07-16T10:07:19.685Z",
+  "generatedAt": "2026-07-23T11:21:38.913Z",
   "skills": [
     {
       "name": "backlog",
-      "version": "0.1.0",
-      "hash": "sha256-ac26c0313981666dfc143bb6eabbf603e0b02111c13ea543e1c86c2900e40559",
+      "version": "0.1.2",
+      "hash": "sha256-40e91ee1f155c778ee596fd4f459cacbdcf8221bf95b0f9f2e45652207aaa275",
       "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."
     },
     {