@jesdi/skills 0.0.1 → 0.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jesdi/skills",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "jesdi's agent skills (content package consumed by @jesdi/skills-cli)",
   "license": "MIT",
   "repository": {
@@ -12,13 +12,6 @@
     "skills",
     "skills-manifest.json"
   ],
-  "workspaces": [
-    "cli"
-  ],
-  "scripts": {
-    "test": "vitest run",
-    "generate-manifest": "tsx scripts/generate-manifest.ts"
-  },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "gray-matter": "^4.0.3",
@@ -28,5 +21,9 @@
   },
   "engines": {
     "node": ">=20"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "generate-manifest": "tsx scripts/generate-manifest.ts"
   }
-}
+}

package/skills/backlog/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: backlog
+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.
+---
+
+# backlog — capture + ranked work graph on GitHub
+
+Two needs, one substrate: a frictionless **capture** inbox (loose issues labelled
+`inbox`) and a typed, dependency-aware **work graph** (one user-owned Project v2
+with Impact / Effort / Area / Status). The verbs below operate on both.
+
+**Dispatch on the user's intent:**
+
+| Intent | Verb |
+|--------|------|
+| "add this idea", "capture", "note this" | `capture` |
+| "triage the inbox", "score these" | `triage` |
+| "what's next", "ranked backlog" | `next` |
+| "I'm starting #N", beginning work on an issue | `start` |
+| "mark #N done", "close it out" | `land` |
+| first-time board creation | `setup` |
+
+All exact commands live in `references/graphql.md`. Board IDs come from the
+**consuming project's** `.backlog/project-meta.json` (created by `setup`, found
+by walking up from the current directory). That file is a **static schema
+pointer** — project/field/option IDs only, *not* issue state (Impact/Effort/
+Status live on the GitHub board and `rank.py` fetches them live). Because the IDs
+are non-secret constants that change only on re-provision, the file is
+**committed in the consuming repo** and shared across every branch/worktree;
+`project-meta.example.json` is the shape reference. Reads use the existing `gh`
+login; **writes need the one-time `gh auth refresh -s project`** (Projects v2 is
+not in the default `repo` scope).
+
+`<owner>`, `<repo>`, `<projectNumber>` below all come from that
+`.backlog/project-meta.json`.
+
+## `setup` — create the board once (idempotent)
+
+Run when `.backlog/project-meta.json` is absent or the board is being
+(re)provisioned. Reconciles rather than duplicates — re-running after adding a
+field is safe. Writes into the **project's** `.backlog/` directory, not the skill
+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`
+   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
+   on the board (GitHub UI) and re-run `setup` to reconcile the IDs.
+3. Discover IDs: `gh project view … --format json` (project id) and
+   `gh project field-list … --format json` (field + option ids).
+4. Build `.backlog/project-meta.json` from that discovery using
+   `meta.build_project_meta`. Run from the skill directory (so `import meta`
+   resolves), writing to the project's `.backlog/` (create it if missing):
+
+   ```bash
+   mkdir -p "$PROJECT_ROOT/.backlog"
+   gh project view <projectNumber> --owner <owner> --format json > /tmp/proj.json
+   gh project field-list <projectNumber> --owner <owner> --format json > /tmp/fields.json
+   python3 - "$PROJECT_ROOT/.backlog/project-meta.json" <<'PY'
+   import json, sys, meta
+   proj = json.load(open("/tmp/proj.json"))
+   fields = json.load(open("/tmp/fields.json"))
+   out = meta.build_project_meta(
+       "<owner>", "<repo>",
+       proj["number"], proj["id"], fields)
+   json.dump(out, open(sys.argv[1], "w"), indent=2)
+   print("wrote", sys.argv[1])
+   PY
+   ```
+
+5. Confirm every field + option id in `.backlog/project-meta.json` is non-empty,
+   then commit the real file (non-secret schema pointer). Report the Project URL.
+
+6. **Built-in workflows (UI-only — no API exists; ask the user to click):**
+   at `https://github.com/users/<owner>/projects/<projectNumber>/workflows`
+   enable:
+   - *Auto-add to project*: repo `<repo>`, filter `is:issue is:open`
+   - *Item added to project*: issues → `Status: Inbox`
+   - *Item closed*: issues → `Status: Done`
+   - *Item reopened*: issues → `Status: Ready`
+   These make the board self-maintaining; `land` is only an escape hatch.
+
+## `land <issue#>` — verify closed + Done (escape hatch)
+
+Closing and Done are **automatic**: a PR merged with `Closes #N` closes the
+issue, and the board's "Item closed" built-in workflow sets `Status: Done`.
+`land` only verifies and repairs:
+
+1. `gh issue view N --repo <repo> --json state` — if not `CLOSED`, close it:
+   `gh issue close N --repo <repo>`.
+2. Check board status (`gh project item-list … --jq` per graphql.md → Land);
+   if not `Done` after ~1 min (workflows are async), set it via `item-edit`.
+3. Report: closed + Done, noting whether automation handled it or you repaired.
+
+## `start <N>` — claim an issue (check-and-claim)
+
+Run when beginning work on an issue — worktree setup time is the natural
+moment. The claim signal is the board Status column and nothing else: humans
+claim by dragging the card to "In progress"; agents run this verb.
+
+1. Read the item id + current status live (graphql.md → Start).
+2. If status is already `In progress` → **abort**: report the issue is
+   already claimed and offer `next` for an alternative. Not an atomic lock —
+   good enough for one human + a few agents.
+3. Otherwise set `Status: In progress` via `item-edit`.
+4. `start --release <N>`: same lookup, set `Status: Ready` (abandon a claim).
+
+## `capture <idea>` — file an inbox issue (frictionless)
+
+Reuse the **dedup discipline** from the `file-bug-issue` skill, but take the
+*idea* path — no reproduction scaffolding.
+
+1. Shape a concise, specific title from the idea (e.g. "Cache batch
+   responses per ticker", not "caching").
+2. Dedup: `gh issue list --repo <repo> --state open --search "<distinctive terms>" --json number,title,url`.
+   If a genuine duplicate exists, add the new angle as a comment instead of a new
+   issue and report which. Different-but-related → create new and cross-link `#N`.
+3. Otherwise create it (see `references/graphql.md` → Capture): `--label inbox`,
+   body = the idea as-is (one loose sentence is fine; no required structure).
+4. Report the new issue URL. If mid-task, treat as a side-quest and return.
+
+## `triage` — turn inbox issues into scored graph nodes
+
+1. List the inbox: `gh issue list --repo <repo> --state open --label inbox --json number,title,url,body`.
+2. For each, present title + body and ask whether to promote (skip = leave in inbox).
+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.
+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`.
+5. After each, confirm it is now triaged (fields set, `inbox` gone). Report a
+   summary of promoted vs. left-in-inbox.
+
+## `next` — ranked, dependency-aware view (read-only)
+
+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
+```
+
+(Use whichever agent-skills path the store symlinked the skill into — e.g.
+`.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:`
+edges, drops closed/`Done` blockers, and prints:
+
+- **Available** issues ranked by Impact÷Effort (unscored sort last, 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
+skill exists over a bare `gh issue list`.

package/skills/backlog/meta.py

@@ -0,0 +1,18 @@
+"""Pure builder for project-meta.json from `gh project field-list` output. Stdlib only."""
+
+
+def build_project_meta(owner, repo, project_number, project_id, fields_json):
+    fields = {}
+    for field in fields_json.get("fields", []):
+        entry = {"id": field["id"]}
+        options = field.get("options")
+        if options:
+            entry["options"] = {opt["name"]: opt["id"] for opt in options}
+        fields[field["name"]] = entry
+    return {
+        "owner": owner,
+        "repo": repo,
+        "projectNumber": project_number,
+        "projectId": project_id,
+        "fields": fields,
+    }

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

@@ -0,0 +1,19 @@
+{
+  "owner": "<owner>",
+  "repo": "<owner>/<repo>",
+  "projectNumber": 0,
+  "projectId": "PVT_REPLACE_ME",
+  "fields": {
+    "Status": {
+      "id": "PVTSSF_REPLACE",
+      "options": {"Inbox": "...", "Ready": "...", "In progress": "...", "Done": "..."}
+    },
+    "Impact": {"id": "PVTF_REPLACE"},
+    "Effort": {"id": "PVTF_REPLACE"},
+    "Score": {"id": "PVTF_REPLACE"},
+    "Area": {
+      "id": "PVTSSF_REPLACE",
+      "options": {"feature": "...", "bug": "...", "infra": "...", "docs": "...", "research": "..."}
+    }
+  }
+}

package/skills/backlog/rank.py

@@ -0,0 +1,186 @@
+"""Pure ranking engine for `backlog next`. Stdlib only — no third-party deps."""
+import json
+import os
+import re
+import subprocess
+
+_BLOCKED_LINE = re.compile(r"^\s*Blocked by:\s*(.+)$", re.IGNORECASE | re.MULTILINE)
+_ISSUE_REF = re.compile(r"#(\d+)")
+
+
+def parse_blocked_by(body):
+    """Return sorted, unique issue numbers from every `Blocked by: #a, #b` line."""
+    if not body:
+        return []
+    nums = set()
+    for line in _BLOCKED_LINE.finditer(body):
+        for ref in _ISSUE_REF.findall(line.group(1)):
+            nums.add(int(ref))
+    return sorted(nums)
+
+
+def _as_int(value):
+    if value is None or value == "":
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def merge_sources(project_items, issue_rows):
+    """Join Project field values (item-list) with issue bodies/state (issue list)."""
+    bodies = {row["number"]: row for row in issue_rows}
+    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 = bodies.get(number, {})
+        merged.append({
+            "number": number,
+            "title": content.get("title", ""),
+            "url": content.get("url", ""),
+            "state": (row.get("state") or "OPEN").upper(),
+            "body": row.get("body") or "",
+            "status": item.get("status"),
+            "impact": _as_int(item.get("impact")),
+            "effort": _as_int(item.get("effort")),
+            "area": item.get("area"),
+        })
+    return merged
+
+
+def _blocker_satisfied(blocker):
+    return blocker["state"] == "CLOSED" or blocker.get("status") == "Done"
+
+
+def blockers_of(issue, by_number):
+    """Unsatisfied blocker numbers. Unknown blockers are dropped (mistyped-# tolerance)."""
+    waiting = []
+    for number in parse_blocked_by(issue["body"]):
+        blocker = by_number.get(number)
+        if blocker is None:
+            continue  # dropped edge
+        if not _blocker_satisfied(blocker):
+            waiting.append(number)
+    return waiting
+
+
+def is_available(issue, by_number):
+    return not blockers_of(issue, by_number)
+
+
+def score(issue):
+    impact, effort = issue.get("impact"), issue.get("effort")
+    if impact is None or effort is None or effort == 0:
+        return None
+    return impact / effort
+
+
+def _sort_key(issue):
+    value = score(issue)
+    return (
+        0 if value is not None else 1,   # scored issues first
+        -(value or 0.0),                 # higher score first
+        -(issue.get("impact") or 0),     # tiebreak: higher impact
+        issue["number"],                 # stable, deterministic
+    )
+
+
+def rank_issues(issues):
+    by_number = {i["number"]: i for i in issues}
+    candidates = [
+        i for i in issues
+        if i["state"] != "CLOSED" and i.get("status") != "Done"
+    ]
+    in_progress = [i for i in candidates if i.get("status") == "In progress"]
+    actionable = [i for i in candidates if i.get("status") != "In progress"]
+    available, blocked = [], []
+    for issue in actionable:
+        (available if is_available(issue, by_number) else blocked).append(issue)
+    available.sort(key=_sort_key)
+    blocked.sort(key=lambda i: i["number"])
+    in_progress.sort(key=lambda i: i["number"])
+    return {
+        "available": available,
+        "blocked": blocked,
+        "in_progress": in_progress,
+        "by_number": by_number,
+    }
+
+
+def render(result):
+    lines = []
+    if result["in_progress"]:
+        lines.append("In progress (claimed):")
+        for issue in result["in_progress"]:
+            lines.append(f"  #{issue['number']} {issue['title']}")
+        lines.append("")
+    lines += [
+        "Rank  Score  Issue                                   Area",
+        "----  -----  --------------------------------------  ----------",
+    ]
+    for idx, issue in enumerate(result["available"], start=1):
+        value = score(issue)
+        score_str = f"{value:.2f}" if value is not None else "  — "
+        flag = "" if value is not None else "  [needs triage]"
+        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}")
+
+    if result["blocked"]:
+        lines.append("")
+        lines.append("Blocked (not actionable yet):")
+        for issue in result["blocked"]:
+            waits = ", ".join(f"#{n}" for n in blockers_of(issue, result["by_number"]))
+            lines.append(f"  #{issue['number']} {issue['title']}  — waiting on {waits}")
+    return "\n".join(lines)
+
+
+def _gh_json(args):
+    completed = subprocess.run(args, capture_output=True, text=True, check=True)
+    return json.loads(completed.stdout)
+
+
+def main(owner, project_number, repo):
+    payload = _gh_json([
+        "gh", "project", "item-list", str(project_number),
+        "--owner", owner, "--format", "json", "--limit", "200",
+    ])
+    project_items = payload.get("items", [])
+    issue_rows = _gh_json([
+        "gh", "issue", "list", "--repo", repo, "--state", "all",
+        "--limit", "500", "--json", "number,body,state",
+    ])
+    issues = merge_sources(project_items, issue_rows)
+    print(render(rank_issues(issues)))
+
+
+def find_project_meta(start=None):
+    """Walk up from `start` (default cwd) to the nearest `.backlog/project-meta.json`.
+
+    Returns its absolute path. Raises FileNotFoundError with an actionable
+    message if no ancestor directory contains one.
+    """
+    origin = os.path.abspath(start or os.getcwd())
+    directory = origin
+    while True:
+        candidate = os.path.join(directory, ".backlog", "project-meta.json")
+        if os.path.isfile(candidate):
+            return candidate
+        parent = os.path.dirname(directory)
+        if parent == directory:  # reached the filesystem root
+            raise FileNotFoundError(
+                f"No .backlog/project-meta.json found walking up from {origin}. "
+                "Run `backlog setup` to provision the board and write it."
+            )
+        directory = parent
+
+
+if __name__ == "__main__":
+    config_path = find_project_meta()
+    with open(config_path) as handle:
+        meta = json.load(handle)
+    main(meta["owner"], meta["projectNumber"], meta["repo"])

package/skills/backlog/references/graphql.md

@@ -0,0 +1,121 @@
+# backlog — gh command reference
+
+All `<placeholders>` come from `.backlog/project-meta.json` unless noted:
+`<owner>`, `<repo>` (`owner/name`), `<projectNumber>`, `<projectId>`,
+`<fields.*.id>`, `<fields.*.options.*>`.
+
+## One-time auth (writes need the `project` scope)
+
+```bash
+gh auth status                     # confirm login
+gh auth refresh -s project         # add Projects-v2 write scope (one-time)
+```
+
+## Setup — create the board (idempotent; skip a step if it already exists)
+
+```bash
+# 1. Create the user-owned Project v2 (prints its number + URL)
+gh project create --owner <owner> --title "<Project Title> Backlog"
+
+# 2. Link it to the repo
+gh project link <projectNumber> --owner <owner> --repo <repo>
+
+# 3. Add fields (single-select options are comma-separated, order preserved)
+gh project field-create <projectNumber> --owner <owner> --name "Status" \
+  --data-type SINGLE_SELECT --single-select-options "Inbox,Ready,In progress,Done"
+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 "Area" \
+  --data-type SINGLE_SELECT \
+  --single-select-options "feature,bug,infra,docs,research"
+
+# 4. Create the inbox label on the repo
+gh label create inbox --repo <repo> \
+  --description "Un-triaged capture" --color BFD4F2 || true
+
+# 5. Discover IDs to build .backlog/project-meta.json
+gh project view <projectNumber> --owner <owner> --format json   # -> id (projectId)
+gh project field-list <projectNumber> --owner <owner> --format json   # -> field + option ids
+```
+
+Reconcile note: `gh project field-create` errors if the field already exists —
+treat "already exists" as success. Projects that want a different Area taxonomy
+edit the option set on the GitHub board and re-run `setup`, which re-discovers the
+IDs into `.backlog/project-meta.json`.
+
+## Capture — file an inbox issue
+
+```bash
+gh issue create --repo <repo> \
+  --title "<concise idea title>" --label inbox \
+  --body "<one loose sentence is fine>"
+```
+
+## Triage — promote an inbox issue to a graph node
+
+```bash
+# 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)>
+
+# 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>
+
+# Record blocking edges (append a line; keep any existing body)
+gh issue edit <number> --repo <repo> --body "<body>\n\nBlocked by: #<a>, #<b>"
+
+# Drop the inbox label
+gh issue edit <number> --repo <repo> --remove-label inbox
+```
+
+## Sub-issues (native parent/child) — GraphQL, no field IDs needed
+
+```bash
+# Resolve issue node IDs (<repoName> is the repo without the owner/ prefix)
+gh api graphql -f query='query($owner:String!,$repo:String!,$n:Int!){
+  repository(owner:$owner,name:$repo){issue(number:$n){id}}}' \
+  -F owner=<owner> -F repo=<repoName> -F n=<parentNumber>
+
+# Attach child to parent
+gh api graphql -f query='mutation($parent:ID!,$child:ID!){
+  addSubIssue(input:{issueId:$parent,subIssueId:$child}){issue{number}}}' \
+  -F parent=<parentNodeId> -F child=<childNodeId>
+```
+
+## Land — verify closed + Done (escape hatch; automation normally does this)
+
+```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}'
+# repair only if needed:
+gh issue close <number> --repo <repo>
+gh project item-edit --project-id <projectId> --id <itemId> \
+  --field-id <fields.Status.id> --single-select-option-id <fields.Status.options.Done>
+```
+
+## Start — check-and-claim
+
+```bash
+# 1. Item id + live status
+gh project item-list <projectNumber> --owner <owner> --format json \
+  --jq '.items[] | select(.content.number==<number>) | {id, status}'
+# 2. If status == "In progress": abort (already claimed).
+# 3. Claim:
+gh project item-edit --project-id <projectId> --id <itemId> \
+  --field-id <fields.Status.id> --single-select-option-id <fields.Status.options["In progress"]>
+# --release: set Ready instead
+gh project item-edit --project-id <projectId> --id <itemId> \
+  --field-id <fields.Status.id> --single-select-option-id <fields.Status.options.Ready>
+```

package/skills/backlog/test_meta.py

@@ -0,0 +1,21 @@
+import meta
+
+
+def test_build_project_meta_maps_fields_and_options():
+    fields_json = {"fields": [
+        {"id": "F_status", "name": "Status", "type": "ProjectV2SingleSelectField",
+         "options": [{"id": "o_inbox", "name": "Inbox"}, {"id": "o_ready", "name": "Ready"}]},
+        {"id": "F_impact", "name": "Impact", "type": "ProjectV2Field"},
+        {"id": "F_area", "name": "Area", "type": "ProjectV2SingleSelectField",
+         "options": [{"id": "o_feat", "name": "feature"}]},
+    ]}
+    out = meta.build_project_meta("acme", "acme/widget", 7, "PVT_x", fields_json)
+    assert out["owner"] == "acme"
+    assert out["repo"] == "acme/widget"
+    assert out["projectNumber"] == 7
+    assert out["projectId"] == "PVT_x"
+    assert out["fields"]["Status"]["id"] == "F_status"
+    assert out["fields"]["Status"]["options"]["Ready"] == "o_ready"
+    assert out["fields"]["Impact"]["id"] == "F_impact"
+    assert "options" not in out["fields"]["Impact"]
+    assert out["fields"]["Area"]["options"]["feature"] == "o_feat"

package/skills/backlog/test_rank.py

@@ -0,0 +1,214 @@
+import rank
+
+
+def test_parse_blocked_by_basic():
+    assert rank.parse_blocked_by("Blocked by: #12, #34") == [12, 34]
+
+
+def test_parse_blocked_by_case_insensitive_and_multiline():
+    body = "Some idea.\n\nblocked BY: #5\nMore text\nBlocked by: #5, #9"
+    assert rank.parse_blocked_by(body) == [5, 9]  # deduped + sorted
+
+
+def test_parse_blocked_by_none_and_empty():
+    assert rank.parse_blocked_by(None) == []
+    assert rank.parse_blocked_by("no blockers here") == []
+
+
+def test_merge_sources_joins_fields_and_bodies():
+    project_items = [
+        {"content": {"number": 12, "title": "Add X", "url": "u/12"},
+         "status": "Ready", "impact": 4, "effort": 2, "area": "feature"},
+        {"content": {"number": 34, "title": "Do Y", "url": "u/34"}},  # untriaged, no fields
+        {"title": "a draft note"},  # draft item, no content -> skipped
+    ]
+    issue_rows = [
+        {"number": 12, "body": "Blocked by: #34", "state": "open"},
+        {"number": 34, "body": "loose idea", "state": "open"},
+    ]
+    out = rank.merge_sources(project_items, issue_rows)
+    assert [i["number"] for i in out] == [12, 34]
+    twelve = out[0]
+    assert twelve["state"] == "OPEN"
+    assert twelve["impact"] == 4 and twelve["effort"] == 2
+    assert twelve["area"] == "feature" and twelve["status"] == "Ready"
+    assert twelve["body"] == "Blocked by: #34"
+    thirtyfour = out[1]
+    assert thirtyfour["impact"] is None and thirtyfour["status"] is None
+
+
+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}],
+        [],  # no matching issue row
+    )
+    assert out[0]["state"] == "OPEN" and out[0]["body"] == ""
+
+
+def _issue(number, body="", state="OPEN", status=None):
+    return {"number": number, "title": f"i{number}", "url": "", "state": state,
+            "body": body, "status": status, "impact": None, "effort": None, "area": None}
+
+
+def test_availability_and_blockers():
+    a = _issue(1, body="Blocked by: #2, #3, #4")
+    by_number = {
+        1: a,
+        2: _issue(2, state="CLOSED"),          # satisfied — closed
+        3: _issue(3, state="OPEN", status="Done"),  # satisfied — Status Done
+        4: _issue(4, state="OPEN", status="Ready"),  # NOT satisfied — still open/active
+    }
+    assert rank.is_available(a, by_number) is False
+    assert rank.blockers_of(a, by_number) == [4]
+
+
+def test_available_when_no_blockers():
+    a = _issue(1, body="just an idea")
+    assert rank.is_available(a, {1: a}) is True
+    assert rank.blockers_of(a, {1: a}) == []
+
+
+def test_unknown_blocker_is_dropped_edge():
+    a = _issue(1, body="Blocked by: #999")  # #999 not in the graph
+    assert rank.is_available(a, {1: a}) is True   # dropped, not blocking
+    assert rank.blockers_of(a, {1: a}) == []
+
+
+def _scored(number, impact, effort, body="", state="OPEN", status="Ready"):
+    return {"number": number, "title": f"i{number}", "url": "", "state": state,
+            "body": body, "status": status, "impact": impact, "effort": effort, "area": None}
+
+
+def test_score_ratio_and_unscored():
+    assert rank.score(_scored(1, 4, 2)) == 2.0
+    assert rank.score(_scored(1, None, 2)) is None
+    assert rank.score(_scored(1, 4, None)) is None
+    assert rank.score(_scored(1, 4, 0)) is None  # guard divide-by-zero
+
+
+def test_rank_orders_available_and_separates_blocked_and_done():
+    issues = [
+        _scored(1, 2, 2),                       # score 1.0
+        _scored(2, 5, 1),                       # score 5.0  -> rank 1
+        _scored(3, None, None),                 # unscored -> last, needs triage
+        _scored(4, 9, 1, body="Blocked by: #2"),  # blocked (2 is open/Ready)
+        _scored(5, 4, 1, status="Done"),        # Done -> excluded entirely
+    ]
+    result = rank.rank_issues(issues)
+    assert [i["number"] for i in result["available"]] == [2, 1, 3]
+    assert [i["number"] for i in result["blocked"]] == [4]
+    assert 5 not in [i["number"] for i in result["available"] + result["blocked"]]
+
+
+def test_rank_excludes_closed():
+    issues = [_scored(1, 3, 1, state="CLOSED"), _scored(2, 1, 1)]
+    result = rank.rank_issues(issues)
+    assert [i["number"] for i in result["available"]] == [2]
+
+
+def test_render_contains_ranks_scores_flags_and_blocked_reason():
+    issues = [
+        _scored(2, 5, 1),                          # score 5.00, rank 1
+        _scored(3, None, None),                    # needs triage
+        _scored(4, 9, 1, body="Blocked by: #2"),   # blocked on #2
+    ]
+    text = rank.render(rank.rank_issues(issues))
+    assert "#2 i2" in text
+    assert "5.00" in text
+    assert "[needs triage]" in text
+    assert "Blocked" in text and "waiting on #2" in text
+
+
+def test_render_no_blocked_section_when_none_blocked():
+    text = rank.render(rank.rank_issues([_scored(1, 2, 1)]))
+    assert "Blocked" not in text
+
+
+def test_rank_separates_in_progress_claimed():
+    issues = [
+        _scored(1, 2, 2),                            # score 1.0, available
+        _scored(2, 5, 1, status="In progress"),      # claimed -> never recommended
+    ]
+    result = rank.rank_issues(issues)
+    assert [i["number"] for i in result["available"]] == [1]
+    assert [i["number"] for i in result["in_progress"]] == [2]
+    assert result["blocked"] == []
+
+
+def test_in_progress_with_blockers_goes_to_claimed_not_blocked():
+    issues = [
+        _scored(1, 3, 1),
+        _scored(2, 4, 1, status="In progress", body="Blocked by: #1"),
+    ]
+    result = rank.rank_issues(issues)
+    assert [i["number"] for i in result["in_progress"]] == [2]
+    assert result["blocked"] == []
+
+
+def test_in_progress_item_still_blocks_its_dependents():
+    # A claimed blocker is not yet Done -> dependents stay blocked.
+    issues = [
+        _scored(1, 3, 1, status="In progress"),
+        _scored(2, 4, 1, body="Blocked by: #1"),
+    ]
+    result = rank.rank_issues(issues)
+    assert [i["number"] for i in result["blocked"]] == [2]
+    assert [i["number"] for i in result["in_progress"]] == [1]
+
+
+def test_render_shows_claimed_section_first():
+    issues = [_scored(1, 2, 1), _scored(2, 5, 1, status="In progress")]
+    text = rank.render(rank.rank_issues(issues))
+    assert text.startswith("In progress (claimed):")
+    assert "#2 i2" in text
+
+
+def test_render_no_claimed_section_when_none_in_progress():
+    text = rank.render(rank.rank_issues([_scored(1, 2, 1)]))
+    assert "claimed" not in text
+
+
+import os
+
+import pytest
+
+
+def test_find_project_meta_in_cwd(tmp_path, monkeypatch):
+    backlog = tmp_path / ".backlog"
+    backlog.mkdir()
+    meta_file = backlog / "project-meta.json"
+    meta_file.write_text("{}")
+    monkeypatch.chdir(tmp_path)
+    assert rank.find_project_meta() == str(meta_file)
+
+
+def test_find_project_meta_walks_up_from_subdir(tmp_path, monkeypatch):
+    backlog = tmp_path / ".backlog"
+    backlog.mkdir()
+    meta_file = backlog / "project-meta.json"
+    meta_file.write_text("{}")
+    nested = tmp_path / "backend" / "deep"
+    nested.mkdir(parents=True)
+    monkeypatch.chdir(nested)
+    assert rank.find_project_meta() == str(meta_file)
+
+
+def test_find_project_meta_nearest_ancestor_wins(tmp_path, monkeypatch):
+    outer = tmp_path / ".backlog"
+    outer.mkdir()
+    (outer / "project-meta.json").write_text("{}")
+    inner_root = tmp_path / "sub"
+    inner_backlog = inner_root / ".backlog"
+    inner_backlog.mkdir(parents=True)
+    inner_meta = inner_backlog / "project-meta.json"
+    inner_meta.write_text("{}")
+    monkeypatch.chdir(inner_root)
+    assert rank.find_project_meta() == str(inner_meta)
+
+
+def test_find_project_meta_errors_clearly_when_absent(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    with pytest.raises(FileNotFoundError) as exc:
+        rank.find_project_meta()
+    assert ".backlog/project-meta.json" in str(exc.value)
+    assert "backlog setup" in str(exc.value)

package/skills-manifest.json

@@ -1,7 +1,13 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-07-14T10:05:20.198Z",
+  "generatedAt": "2026-07-15T09:33:14.993Z",
   "skills": [
+    {
+      "name": "backlog",
+      "version": "0.1.0",
+      "hash": "sha256-ac26c0313981666dfc143bb6eabbf603e0b02111c13ea543e1c86c2900e40559",
+      "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."
+    },
     {
       "name": "branch-audit",
       "version": "0.1.0",