@jesdi/skills 0.0.5 → 0.0.7

package/package.json

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

package/skills/backlog/SKILL.md

@@ -52,7 +52,7 @@ dir.
 1. Ensure the `project` scope: `gh auth status`; if Projects calls 403, run
    `gh auth refresh -s project`.
 2. Follow `references/graphql.md` → **Setup**: create the Project, link the repo,
-   add the four fields, create the `inbox` label. On a brand-new board the `Area`
+   add the six fields, create the `inbox` label. On a brand-new board the `Area`
    single-select is created with the generic default options
    `feature,bug,infra,docs,research`. If any step reports "already exists", treat
    it as done and continue. Projects that want different Areas edit the option set
@@ -137,6 +137,12 @@ Reuse the **dedup discipline** from the `file-bug-issue` skill, but take the
 3. For a promoted issue, gather `Impact` (1–5), `Effort` (1–5), `Area` (**pick one
    from the options present in `.backlog/project-meta.json`** → `fields.Area.options`),
    and optional blockers.
+
+   - **Boost** (number, optional, default 0): manual priority override. Ranking is
+     band-dominant — any issue with higher Boost outranks every issue with lower
+     Boost regardless of score; score orders issues within a band. Negative values
+     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 +
@@ -155,7 +161,7 @@ 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
+                                                # score, boost
 ```
 
 (Use whichever agent-skills path the store symlinked the skill into — e.g.
@@ -165,10 +171,11 @@ 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:`
 edges, drops closed/`Done` blockers, and prints:
 
-- **Available** issues ranked by Impact÷Effort (unscored sort last, flagged
-  `[needs triage]`).
+- **Available** issues ranked boost-band first, then Impact÷Effort within a band
+  (unscored sort last within a band, flagged `[needs triage]`).
 - **Blocked** issues, unranked, annotated with what they wait on.
 
-Present the table as-is. If the user asks "why isn't #N at the top", point at its
-score or its blockers from the output. This in-memory ranking is the reason the
+Present the table as-is. If the user asks "why isn't #N at the top", check first
+whether another issue has a higher Boost band (shown as `↑n`), then its score, then
+its blockers from the output. This in-memory ranking is the reason the
 skill exists over a bare `gh issue list`.

package/skills/backlog/project-meta.example.json

@@ -11,6 +11,7 @@
     "Impact": {"id": "PVTF_REPLACE"},
     "Effort": {"id": "PVTF_REPLACE"},
     "Score": {"id": "PVTF_REPLACE"},
+    "Boost": {"id": "PVTF_REPLACE"},
     "Area": {
       "id": "PVTSSF_REPLACE",
       "options": {"feature": "...", "bug": "...", "infra": "...", "docs": "...", "research": "..."}

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,
@@ -49,6 +66,7 @@ def merge_sources(project_items, issue_rows):
             "effort": _as_int(item.get("effort")),
             "area": item.get("area"),
             "labels": [l["name"] for l in row.get("labels") or []],
+            "boost": (lambda v: 0 if v is None else v)(_as_int(item.get("boost"))),
         })
     return merged
 
@@ -83,7 +101,8 @@ def score(issue):
 def _sort_key(issue):
     value = score(issue)
     return (
-        0 if value is not None else 1,   # scored issues first
+        -issue.get("boost", 0),          # band first: higher boost above everything
+        0 if value is not None else 1,   # scored issues first within a band
         -(value or 0.0),                 # higher score first
         -(issue.get("impact") or 0),     # tiebreak: higher impact
         issue["number"],                 # stable, deterministic
@@ -129,6 +148,7 @@ def to_json_rows(result):
             "labels": issue.get("labels", []),
             "blocked": blocked,
             "score": score(issue),
+            "boost": issue.get("boost", 0),
         })
     return rows
 
@@ -148,6 +168,11 @@ def render(result):
         value = score(issue)
         score_str = f"{value:.2f}" if value is not None else "  — "
         flag = "" if value is not None else "  [needs triage]"
+        boost = issue.get("boost", 0)
+        if boost > 0:
+            flag += f"  ↑{boost}"
+        elif boost < 0:
+            flag += f"  ↓{-boost}"
         label = f"#{issue['number']} {issue['title']}"[:38].ljust(38)
         area = (issue.get("area") or "-")
         lines.append(f"{idx:>4}  {score_str:>5}  {label}  {area:<10}{flag}")
@@ -183,7 +208,7 @@ def main(owner, project_number, repo, as_json=False):
     project_items = payload.get("items", [])
     issue_rows = _gh_json([
         "gh", "issue", "list", "--repo", repo, "--state", "all",
-        "--limit", "500", "--json", "number,body,state,labels",
+        "--limit", "500", "--json", "number,title,url,body,state,labels",
     ])
     issues = merge_sources(project_items, issue_rows)
     result = rank_issues(issues)

package/skills/backlog/references/graphql.md

@@ -26,6 +26,7 @@ gh project field-create <projectNumber> --owner <owner> --name "Status" \
 gh project field-create <projectNumber> --owner <owner> --name "Impact" --data-type NUMBER
 gh project field-create <projectNumber> --owner <owner> --name "Effort" --data-type NUMBER
 gh project field-create <projectNumber> --owner <owner> --name "Score" --data-type NUMBER
+gh project field-create <projectNumber> --owner <owner> --name "Boost" --data-type NUMBER
 gh project field-create <projectNumber> --owner <owner> --name "Area" \
   --data-type SINGLE_SELECT \
   --single-select-options "feature,bug,infra,docs,research"
@@ -65,6 +66,9 @@ 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> \

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}],
@@ -249,7 +289,9 @@ def test_main_json_emits_machine_readable_rows(monkeypatch, capsys):
                     {"content": {"number": 5, "title": "Task", "url": "u/5"},
                      "status": "Ready", "impact": 4, "effort": 2}]})
             else:
-                assert "labels" in args[args.index("--json") + 1]
+                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"}]}])
@@ -260,7 +302,7 @@ def test_main_json_emits_machine_readable_rows(monkeypatch, capsys):
     rows = jsonlib.loads(capsys.readouterr().out)
     assert rows == [{"number": 5, "title": "Task", "url": "u/5",
                      "status": "Ready", "labels": ["auto"],
-                     "blocked": False, "score": 2.0}]
+                     "blocked": False, "score": 2.0, "boost": 0}]
 
 
 def test_project_env_absent_without_token(monkeypatch):
@@ -301,3 +343,72 @@ def test_find_project_meta_errors_clearly_when_absent(tmp_path, monkeypatch):
         rank.find_project_meta()
     assert ".backlog/project-meta.json" in str(exc.value)
     assert "backlog setup" in str(exc.value)
+
+
+def test_merge_sources_parses_boost_and_defaults_zero():
+    out = rank.merge_sources(
+        [{"content": {"number": 7, "title": "T", "url": "u/7"}, "boost": 2},
+         {"content": {"number": 8, "title": "U", "url": "u/8"}, "boost": ""},
+         {"content": {"number": 9, "title": "V", "url": "u/9"}},
+         {"content": {"number": 10, "title": "W", "url": "u/10"}, "boost": -3}],
+        [])
+    assert [i["boost"] for i in out] == [2, 0, 0, -3]
+
+
+def test_boost_band_dominates_score():
+    lo = _scored(1, 5, 1)              # score 5.0, unboosted
+    hi = _scored(2, 1, 2)              # score 0.5, boosted
+    hi["boost"] = 1
+    result = rank.rank_issues([lo, hi])
+    assert [i["number"] for i in result["available"]] == [2, 1]
+
+
+def test_score_orders_within_boost_band():
+    a = _scored(1, 2, 2)               # score 1.0
+    b = _scored(2, 5, 1)               # score 5.0
+    a["boost"] = b["boost"] = 1
+    result = rank.rank_issues([a, b])
+    assert [i["number"] for i in result["available"]] == [2, 1]
+
+
+def test_negative_boost_sinks_below_unboosted():
+    demoted = _scored(1, 9, 1)         # score 9.0 but demoted
+    demoted["boost"] = -1
+    plain = _scored(2, 1, 1)           # score 1.0
+    result = rank.rank_issues([demoted, plain])
+    assert [i["number"] for i in result["available"]] == [2, 1]
+
+
+def test_unscored_boosted_enters_band_after_scored_in_band():
+    scored_boosted = _scored(1, 2, 1)
+    scored_boosted["boost"] = 1
+    unscored_boosted = _scored(2, None, None)
+    unscored_boosted["boost"] = 1
+    scored_plain = _scored(3, 5, 1)
+    result = rank.rank_issues([scored_plain, unscored_boosted, scored_boosted])
+    assert [i["number"] for i in result["available"]] == [1, 2, 3]
+
+
+def test_json_rows_include_boost():
+    a = _scored(1, 2, 1)
+    a["boost"] = 2
+    a["labels"] = ["auto"]
+    b = _scored(2, 5, 1)
+    b["labels"] = ["auto"]
+    rows = rank.to_json_rows(rank.rank_issues([a, b]))
+    assert [(r["number"], r["boost"]) for r in rows] == [(1, 2), (2, 0)]
+
+
+def test_render_marks_boost_up_and_down():
+    up = _scored(1, 2, 1)
+    up["boost"] = 2
+    down = _scored(2, 5, 1)
+    down["boost"] = -1
+    plain = _scored(3, 1, 1)
+    text = rank.render(rank.rank_issues([up, down, plain]))
+    line_for_up = next(l for l in text.splitlines() if "#1 i1" in l)
+    assert "↑2" in line_for_up
+    line_for_down = next(l for l in text.splitlines() if "#2 i2" in l)
+    assert "↓1" in line_for_down
+    line_for_plain = next(l for l in text.splitlines() if "#3 i3" in l)
+    assert "↑" not in line_for_plain and "↓" not in line_for_plain

package/skills-manifest.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-07-23T11:21:38.913Z",
+  "generatedAt": "2026-07-24T16:48:47.031Z",
   "skills": [
     {
       "name": "backlog",
-      "version": "0.1.2",
-      "hash": "sha256-40e91ee1f155c778ee596fd4f459cacbdcf8221bf95b0f9f2e45652207aaa275",
+      "version": "0.1.4",
+      "hash": "sha256-c5c2ff8482d24eb782b0d5799b1e490733340f604196f42e8051d731bb00dd09",
       "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."
     },
     {