@jesdi/skills 0.0.4 → 0.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jesdi/skills",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "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

@@ -29,14 +29,31 @@ def _as_int(value):
 
 
 def merge_sources(project_items, issue_rows):
-    """Join Project field values (item-list) with issue bodies/state (issue list)."""
+    """Join Project field values (item-list) with issue bodies/state (issue list).
+
+    Join key is the issue number when the token can expand item content; when
+    content is redacted (project-scope token + private repo), fall back to the
+    title — GitHub syncs linked-item titles to issue titles. Ambiguous titles
+    (duplicates) and titles matching no issue are skipped, as are drafts.
+    """
     bodies = {row["number"]: row for row in issue_rows}
+    by_title, dup_titles = {}, set()
+    for row in issue_rows:
+        title = row.get("title")
+        if title in by_title:
+            dup_titles.add(title)
+        elif title is not None:
+            by_title[title] = row
     merged = []
     for item in project_items:
         content = item.get("content") or {}
         number = content.get("number")
         if number is None:
-            continue  # draft item (no linked issue) — not part of the work graph
+            row = by_title.get(item.get("title"))
+            if row is None or item.get("title") in dup_titles:
+                continue  # draft, board-only, or ambiguous — not joinable
+            number = row["number"]
+            content = {"title": row.get("title", ""), "url": row.get("url", "")}
         row = bodies.get(number, {})
         merged.append({
             "number": number,
@@ -48,6 +65,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 +129,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"]:
@@ -153,7 +192,7 @@ def _project_env():
     return {**os.environ, "GH_TOKEN": token} if token else None
 
 
-def main(owner, project_number, repo):
+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",
@@ -161,10 +200,14 @@ def main(owner, project_number, repo):
     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,title,url,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):
@@ -189,7 +232,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

@@ -37,6 +37,46 @@ def test_merge_sources_joins_fields_and_bodies():
     assert thirtyfour["impact"] is None and thirtyfour["status"] is None
 
 
+def test_merge_sources_falls_back_to_title_join_when_content_redacted():
+    # A project-scope token can list items and field values but cannot expand
+    # the linked issue of a private repo: no "content", empty "repository".
+    # GitHub syncs linked-item titles to issue titles, so title is the join key.
+    project_items = [
+        {"id": "PVTI_a", "title": "Add X", "repository": "",
+         "status": "Ready", "impact": 4, "effort": 2},
+    ]
+    issue_rows = [
+        {"number": 12, "title": "Add X", "url": "u/12",
+         "body": "Blocked by: #34", "state": "open",
+         "labels": [{"name": "auto"}]},
+    ]
+    out = rank.merge_sources(project_items, issue_rows)
+    assert len(out) == 1
+    twelve = out[0]
+    assert twelve["number"] == 12
+    assert twelve["url"] == "u/12"
+    assert twelve["impact"] == 4 and twelve["status"] == "Ready"
+    assert twelve["body"] == "Blocked by: #34"
+    assert twelve["labels"] == ["auto"]
+
+
+def test_merge_sources_redacted_item_without_matching_title_is_skipped():
+    out = rank.merge_sources(
+        [{"id": "PVTI_a", "title": "board-only note", "status": "Ready"}],
+        [{"number": 1, "title": "Other", "url": "u/1", "body": "", "state": "open"}],
+    )
+    assert out == []
+
+
+def test_merge_sources_title_join_skips_ambiguous_duplicate_titles():
+    project_items = [{"id": "PVTI_a", "title": "Dup", "status": "Ready"}]
+    issue_rows = [
+        {"number": 1, "title": "Dup", "url": "u/1", "body": "", "state": "open"},
+        {"number": 2, "title": "Dup", "url": "u/2", "body": "", "state": "open"},
+    ]
+    assert rank.merge_sources(project_items, issue_rows) == []
+
+
 def test_merge_sources_missing_body_row_defaults_open_empty():
     out = rank.merge_sources(
         [{"content": {"number": 7, "title": "T", "url": "u/7"}, "impact": 3, "effort": 1}],
@@ -206,6 +246,65 @@ 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:
+                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"}]}])
+        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

package/skills-manifest.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-07-23T11:12:36.101Z",
+  "generatedAt": "2026-07-23T15:49:56.550Z",
   "skills": [
     {
       "name": "backlog",
-      "version": "0.1.1",
-      "hash": "sha256-2a594bc97cd045b92b5771f6c462b861b8adcfaee0135c59820af092bdf02a2f",
+      "version": "0.1.3",
+      "hash": "sha256-afe5ef66a86a4bbb1ce654e9ec861be80873e36e1cb45fbe132564a25dc26c1d",
       "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."
     },
     {