@stylusnexus/work-plan 2026.6.13 → 2026.6.14

package/skills/work-plan/lib/git_state.py

@@ -1,4 +1,5 @@
 """Local git queries + time helpers."""
+import re
 import subprocess
 from datetime import date, datetime, timedelta
 from pathlib import Path
@@ -131,6 +132,37 @@ def branch_in_progress(branch_name: str, repo_path: Path) -> bool:
     return _has_recent_commits(branch_name, repo_path, hours=24)
 
 
+# Maps a conventional branch name to its issue number. Anchored at start and
+# requires a trailing '-' so `feat/2710-x` captures 2710, never the `271`
+# substring. Only feat/ and fix/ — `work-plan/plan` (#260) carries no issue
+# number, and there is no `plan/<n>-` convention.
+_BRANCH_ISSUE_RE = re.compile(r"^(?:feat|fix)/(\d+)-")
+
+
+def hot_issue_numbers(repo_path: Path) -> set:
+    """Issue numbers with a 'hot' branch in `repo_path`.
+
+    Enumerates local branches with `git branch --format=%(refname:short)` (the
+    --format is load-bearing: plain `git branch` prefixes lines with `  `/`* `/`+ `,
+    which would defeat the anchored regex), maps each `feat/<n>-`/`fix/<n>-` name
+    to <n>, and keeps those whose branch is `branch_in_progress`.
+
+    Failure contract: if the enumeration call fails -> empty set. A per-branch heat
+    check that fails collapses to cold (that branch is simply not added). Never raises.
+    """
+    if not repo_path or not Path(repo_path).exists():
+        return set()
+    proc = _git(repo_path, "branch", "--format=%(refname:short)", "--list")
+    if proc is None or proc.returncode != 0:
+        return set()
+    out = set()
+    for line in proc.stdout.splitlines():
+        m = _BRANCH_ISSUE_RE.match(line.strip())
+        if m and branch_in_progress(line.strip(), repo_path):
+            out.add(int(m.group(1)))
+    return out
+
+
 def last_commit_date(branch_name: str, repo_path: Path) -> Optional[datetime]:
     """Most recent commit timestamp on branch (naive)."""
     if not repo_path or not Path(repo_path).exists():

package/skills/work-plan/lib/github_state.py

@@ -5,6 +5,8 @@ import subprocess
 from concurrent.futures import ThreadPoolExecutor
 from typing import Iterable, Optional
 
+from lib.in_progress import IN_PROGRESS_LABEL
+
 PRIORITY_LABELS = ("priority/P0", "priority/P1", "priority/P2", "priority/P3")
 DEFAULT_PRIORITY = "P3"
 
@@ -28,6 +30,100 @@ def _valid_repo(repo: str) -> bool:
     return bool(repo) and _REPO_RE.match(repo) is not None
 
 
+def close_issue(repo: str, number: int, reason=None, comment=None) -> tuple:
+    """Close a GitHub issue via `gh issue close` — one of the toolkit's
+    GitHub-mutating calls (also `set_issue_in_progress`, `create_issue`).
+    Everything else here is read-only.
+
+    Returns (ok, message). `reason` ∈ {completed, not_planned} maps to
+    `--reason`; `comment` (if given) posts a closing comment. The issue number
+    is coerced to str for argv (never shell-interpolated), and `repo` is
+    validated as owner/name first, so neither can inject. Never raises — a gh
+    failure (already-closed, no write access, network, not-found) comes back as
+    (False, <gh stderr>)."""
+    if not _valid_repo(repo):
+        return (False, f"invalid repo '{repo}'")
+    args = ["gh", "issue", "close", str(int(number)), "--repo", repo]
+    if reason in ("completed", "not_planned"):
+        args += ["--reason", reason]
+    if comment:
+        args += ["--comment", str(comment)]
+    try:
+        proc = subprocess.run(args, capture_output=True, text=True, timeout=GH_TIMEOUT)
+    except Exception as e:
+        return (False, f"gh issue close failed: {e}")
+    if proc.returncode != 0:
+        return (False, (proc.stderr or proc.stdout or "gh issue close failed").strip())
+    return (True, (proc.stdout or f"closed #{number}").strip())
+
+
+def set_issue_in_progress(repo: str, number: int, clear: bool = False) -> tuple:
+    """Add or remove the work-plan:in-progress label on a GitHub issue (#271).
+
+    The toolkit's second GitHub-mutating call (close_issue is the first). On add,
+    the label is created first (`--force` is idempotent: updates color/description
+    if it already exists) so `--add-label` can't fail on a missing label. Both gh
+    calls are --repo-qualified — issue numbers are repo-scoped. Returns (ok, message);
+    never raises. number->str for argv, repo validated owner/name, so neither injects.
+    """
+    if not _valid_repo(repo):
+        return (False, f"invalid repo '{repo}'")
+    try:
+        if not clear:
+            create = ["gh", "label", "create", IN_PROGRESS_LABEL, "--repo", repo,
+                      "--color", "FBCA04",
+                      "--description", "Actively being worked (work-plan)", "--force"]
+            proc = subprocess.run(create, capture_output=True, text=True, timeout=GH_TIMEOUT)
+            if proc.returncode != 0:
+                return (False, (proc.stderr or proc.stdout or "gh label create failed").strip())
+        flag = "--remove-label" if clear else "--add-label"
+        edit = ["gh", "issue", "edit", str(int(number)), "--repo", repo, flag, IN_PROGRESS_LABEL]
+        proc = subprocess.run(edit, capture_output=True, text=True, timeout=GH_TIMEOUT)
+    except Exception as e:
+        return (False, f"gh in-progress write failed: {e}")
+    if proc.returncode != 0:
+        return (False, (proc.stderr or proc.stdout or "gh issue edit failed").strip())
+    verb = "cleared" if clear else "marked"
+    return (True, (proc.stdout or f"{verb} #{number} in-progress").strip())
+
+
+def gh_auth_status() -> dict:
+    """Probe `gh` authentication so callers can fast-fail instead of silently
+    degrading (#auth). Returns:
+
+        {"gh_present": bool, "authenticated": bool,
+         "user": str | None, "error": str | None}
+
+    Distinguishes the two failure modes the UI must handle differently:
+    `gh` not installed (`gh_present` False — fix is "install gh") vs installed
+    but not logged in (`authenticated` False — fix is "gh auth login").
+
+    Never raises. `gh auth status` exits 0 when at least one host is logged in,
+    non-zero otherwise; it prints the human status to STDERR. We parse a
+    best-effort `user` from that text but treat the EXIT CODE as authoritative."""
+    try:
+        proc = subprocess.run(
+            ["gh", "auth", "status"],
+            capture_output=True, text=True, timeout=GH_TIMEOUT,
+        )
+    except FileNotFoundError:
+        return {"gh_present": False, "authenticated": False,
+                "user": None, "error": "gh CLI not found on PATH"}
+    except Exception as e:  # timeout / OS error — gh present but unusable now
+        return {"gh_present": True, "authenticated": False,
+                "user": None, "error": f"gh auth status failed: {e}"}
+
+    blob = f"{proc.stdout}\n{proc.stderr}"
+    authenticated = proc.returncode == 0
+    # `gh auth status` prints e.g. "✓ Logged in to github.com account USER" or
+    # the older "Logged in to github.com as USER". Match either phrasing.
+    m = re.search(r"Logged in to \S+ (?:account|as) (\S+)", blob)
+    user = m.group(1) if (authenticated and m) else None
+    error = None if authenticated else (blob.strip() or "not logged in to GitHub")
+    return {"gh_present": True, "authenticated": authenticated,
+            "user": user, "error": error}
+
+
 def fetch_issue(repo: str, number: int) -> Optional[dict]:
     """Fetch a single issue via gh. Returns parsed dict on success, None on failure.
     Never raises — a missing `gh` binary, a timeout, or a bad repo yields None."""
@@ -98,7 +194,8 @@ def _normalize_gql_node(node) -> Optional[dict]:
     expect (labels as [{name}], assignees as [{login}], milestone as {title}|None).
     None for a null node.
     On success returns a dict with keys: number, title, state, labels, milestone,
-    closedAt, body, url, updatedAt, assignees."""
+    closedAt, body, url, updatedAt, assignees, blocked_by, blocking,
+    deps_truncated."""
     if not node:
         return None
     labels = [{"name": l.get("name")} for l in
@@ -106,6 +203,20 @@ def _normalize_gql_node(node) -> Optional[dict]:
     assignees = [{"login": a.get("login")} for a in
                  ((node.get("assignees") or {}).get("nodes") or []) if a.get("login")]
     ms = node.get("milestone")
+
+    def _deps(key):
+        conn = node.get(key) or {}
+        nodes = conn.get("nodes") or []
+        open_edges = [{"number": n.get("number"),
+                       "repo": (n.get("repository") or {}).get("nameWithOwner"),
+                       "title": n.get("title", "")}
+                      for n in nodes if (n.get("state") or "").upper() == "OPEN"]
+        truncated = (conn.get("totalCount") or 0) > len(nodes)
+        return open_edges, truncated
+    blocked_by, _bb_trunc = _deps("blockedBy")
+    blocking, _bl_trunc = _deps("blocking")
+    deps_truncated = _bb_trunc or _bl_trunc
+
     return {
         "number": node.get("number"),
         "title": node.get("title", ""),
@@ -117,6 +228,9 @@ def _normalize_gql_node(node) -> Optional[dict]:
         "url": node.get("url", ""),
         "updatedAt": node.get("updatedAt"),
         "assignees": assignees,
+        "blocked_by": blocked_by,
+        "blocking": blocking,
+        "deps_truncated": deps_truncated,
     }
 
 
@@ -124,7 +238,7 @@ def _normalize_gql_node(node) -> Optional[dict]:
 # Kept as a module-level constant so _gql_query can parameterize at the call site.
 _GQL_FIELDS_FULL = (
     "number title state"
-    " labels(first: 20) { nodes { name } }"
+    " labels(first: 50) { nodes { name } }"
     " milestone { title }"
     " closedAt body url updatedAt"
     " assignees(first: 10) { nodes { login } }"
@@ -132,19 +246,33 @@ _GQL_FIELDS_FULL = (
 
 _GQL_FIELDS_LEAN = (
     "number title state"
+    " labels(first: 50) { nodes { name } }"
     " assignees(first: 10) { nodes { login } }"
     " milestone { title }"
 )
 
+# Issue dependency edges (#257). Issue-ONLY: PullRequest has no blockedBy/blocking,
+# and _gql_query shares the base field set across both fragments — so these are
+# appended only to the `... on Issue` fragment. No server-side state filter exists
+# (the connection takes only orderBy + cursor args), so OPEN-filtering is done in
+# _normalize_gql_node; totalCount detects first:50 truncation (confirmed live field).
+_GQL_ISSUE_DEPS = (
+    " blockedBy(first: 50) { totalCount nodes { number state title repository { nameWithOwner } } }"
+    " blocking(first: 50) { totalCount nodes { number state title repository { nameWithOwner } } }"
+)
+
 
 def _gql_query(owner: str, name: str, numbers: list,
                fields: str = _GQL_FIELDS_LEAN) -> str:
     """Build a batched GraphQL query for issueOrPullRequest nodes.
     `fields` selects the GQL field set; _GQL_FIELDS_LEAN for export, _GQL_FIELDS_FULL
-    for fetch_issues (which needs labels, closedAt, body, url, updatedAt)."""
+    for fetch_issues (which needs labels, closedAt, body, url, updatedAt).
+    _GQL_ISSUE_DEPS is appended to the Issue fragment only — PullRequest does not
+    expose blockedBy/blocking fields."""
     aliases = "\n".join(
         f'  i{n}: issueOrPullRequest(number: {int(n)}) {{ '
-        f'... on Issue {{ {fields} }} ... on PullRequest {{ {fields} }} }}'
+        f'... on Issue {{ {fields}{_GQL_ISSUE_DEPS} }} '
+        f'... on PullRequest {{ {fields} }} }}'
         for n in numbers
     )
     return f'query {{ repository(owner: "{owner}", name: "{name}") {{\n{aliases}\n}} }}'

package/skills/work-plan/lib/in_progress.py

@@ -0,0 +1,23 @@
+"""Join the two issue-level in-progress signals into one boolean (#271).
+
+GitHub is canonical; nothing here is cached. `hot_nums` comes from live git
+(lib.git_state.hot_issue_numbers); the label is read from a live `gh` fetch.
+"""
+
+IN_PROGRESS_LABEL = "work-plan:in-progress"
+
+
+def issue_in_progress(issue_row: dict, hot_nums) -> bool:
+    """True iff the issue is OPEN and (its number is hot OR it carries the label).
+
+    Closed/merged always returns False (closed wins). `issue_row` is a fetched
+    gh issue dict ({number, state, labels:[{name}]}); `hot_nums` is a set of ints.
+    """
+    state = (issue_row.get("state") or "OPEN").upper()
+    if state != "OPEN":
+        return False
+    number = issue_row.get("number")
+    if number in hot_nums:
+        return True
+    names = {l.get("name") for l in (issue_row.get("labels") or [])}
+    return IN_PROGRESS_LABEL in names

package/skills/work-plan/lib/manifest.py

@@ -92,6 +92,24 @@ def out_of_tree_ratio(decls: list, repo_root) -> float:
     return out / len(decls)
 
 
+def offtree_declared_paths(decls: list, repo_root) -> list:
+    """Declared paths that resolve OUTSIDE repo_root — absolute paths, `~`-rooted,
+    `..`-escapes, or junk like a literal `/` (#286 slice 3, surfaced read-only).
+
+    Distinct from "not yet created": these can never be satisfied by THIS repo,
+    so they silently drag the file score down and usually mean a typo or a
+    misfiled plan. Returned de-duped in first-declared order so the viewer can
+    flag them; the toolkit never auto-edits the manifest (that'd be a body
+    write, which #286 forbids). Below `out_of_tree_ratio`'s FOREIGN_RATIO the
+    🧳 verdict doesn't fire, so without this they'd be invisible."""
+    out, seen = [], set()
+    for d in decls:
+        if d.path not in seen and not is_in_tree(d.path, repo_root):
+            seen.add(d.path)
+            out.append(d.path)
+    return out
+
+
 @dataclass
 class ManifestScore:
     total: int

package/skills/work-plan/lib/plan_fm.py

@@ -0,0 +1,71 @@
+"""Shared frontmatter-write helpers for viewer-driven plan writes (#286).
+
+Every viewer-driven write to a plan/spec doc is **frontmatter-only** by hard
+constraint. These helpers are the single, security-critical write path so the
+escape guard and the public-repo confirm gate aren't copy-pasted (and can't
+drift) across `plan-confirm`, `plan-ack`, and any future frontmatter writer.
+"""
+import json
+from pathlib import Path
+from typing import Optional
+
+from lib import frontmatter
+from lib.write_guard import needs_confirm, make_token, valid_token
+
+
+def resolve_doc_path(repo_root: Path, rel: str) -> Optional[Path]:
+    """Absolute path of `rel` iff it is a real file inside repo_root, else None.
+
+    Guards the write surface: the resolved path must live under the repo root,
+    so a `../escape`, an absolute `rel`, or an in-repo symlink pointing outside
+    can't steer a frontmatter write at an arbitrary file."""
+    root = Path(repo_root).resolve()
+    try:
+        p = Path(repo_root) / rel
+        if not p.is_file():
+            return None
+        resolved = p.resolve()
+    except OSError:
+        return None
+    if resolved == root or root in resolved.parents:
+        return resolved
+    return None
+
+
+def public_repo_gate(slug, rel: str, cfg: dict, confirm, action: str) -> bool:
+    """Public-repo confirm-token gate (the viewer surfaces this as a modal).
+
+    Returns True when the write may proceed. When a gate is required and no valid
+    token was supplied, prints the `{needs_confirm, reason, token}` JSON the
+    viewer's executeWrite flow consumes and returns False — the caller must then
+    make NO write. `action` is the verb phrase spliced into the reason."""
+    if slug and needs_confirm(slug, cfg) and not (
+        isinstance(confirm, str) and valid_token(confirm, slug, rel)
+    ):
+        print(json.dumps({
+            "needs_confirm": True,
+            "reason": (f"{slug} is PUBLIC (or visibility unknown); {action} "
+                       f"a frontmatter write will be committed there."),
+            "token": make_token(slug, rel),
+        }))
+        return False
+    return True
+
+
+def set_key(doc_path: Path, key: str, value) -> bool:
+    """Set (`value` not None) or delete (`value` None) ONE frontmatter key,
+    preserving the body byte-for-byte. Returns True iff the file changed
+    (idempotent no-op → False), so callers can report "nothing to do"."""
+    meta, body = frontmatter.parse_file(doc_path)
+    if not isinstance(meta, dict):
+        meta = {}
+    if value is None:
+        if key not in meta:
+            return False
+        del meta[key]
+    else:
+        if meta.get(key) == value:
+            return False
+        meta[key] = value
+    frontmatter.write_file(doc_path, meta, body)
+    return True

package/skills/work-plan/lib/render.py

@@ -36,6 +36,11 @@ def render_track_row(t: dict) -> str:
     if t["next_up"]:
         for idx, item in enumerate(t["next_up"]):
             bits = [item["priority"], item["state"]]
+            if item.get("in_progress"):
+                bits.append("▶ in-progress")
+            blocked = item.get("blocked_by_display") or []
+            if blocked:
+                bits.append("⊘ blocked by " + ", ".join(blocked))
             if item.get("milestone"):
                 bits.append(item["milestone"])
             label = f"#{item['number']} {item['title']} ({', '.join(bits)})"

package/skills/work-plan/lib/status_header.py

@@ -17,12 +17,16 @@ _ORPHAN_RE = re.compile(
 
 
 def render_block(row: dict) -> str:
-    """Render the delimited status block from an evaluated row dict."""
+    """Render the delimited status block from an evaluated row dict.
+
+    A `verdict_override` (#286) appends a `✋ confirmed` marker so the banner
+    reads as a human-affirmed verdict, not a purely mechanical one."""
     last = row.get("last_touched") or "unknown"
+    confirmed = " · ✋ confirmed" if row.get("override") else ""
     line = (
         f"> **Status:** {row['glyph']} {row['verdict']} · "
         f"{row['files_present']}/{row['files_declared']} files · "
-        f"last touched {last}"
+        f"last touched {last}{confirmed}"
     )
     return f"{BEGIN}\n{line}\n{END}"
 

package/skills/work-plan/tests/test_auth_status.py

@@ -0,0 +1,98 @@
+"""auth-status — gh auth probe (#auth). Offline: subprocess is mocked."""
+import io
+import json
+import subprocess
+import sys
+import unittest
+from contextlib import redirect_stdout
+from pathlib import Path
+from types import SimpleNamespace
+from unittest import mock
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from commands import auth_status
+from lib import github_state
+
+
+def _proc(returncode, stdout="", stderr=""):
+    return SimpleNamespace(returncode=returncode, stdout=stdout, stderr=stderr)
+
+
+class GhAuthStatusHelperTest(unittest.TestCase):
+    def test_authenticated_parses_user(self):
+        out = _proc(0, stderr="✓ Logged in to github.com account evemcgivern (keyring)")
+        with mock.patch("lib.github_state.subprocess.run", return_value=out):
+            s = github_state.gh_auth_status()
+        self.assertTrue(s["authenticated"])
+        self.assertTrue(s["gh_present"])
+        self.assertEqual(s["user"], "evemcgivern")
+        self.assertIsNone(s["error"])
+
+    def test_authenticated_legacy_phrasing(self):
+        out = _proc(0, stderr="✓ Logged in to github.com as evemcgivern")
+        with mock.patch("lib.github_state.subprocess.run", return_value=out):
+            s = github_state.gh_auth_status()
+        self.assertTrue(s["authenticated"])
+        self.assertEqual(s["user"], "evemcgivern")
+
+    def test_not_logged_in(self):
+        out = _proc(1, stderr="You are not logged into any GitHub hosts. Run gh auth login")
+        with mock.patch("lib.github_state.subprocess.run", return_value=out):
+            s = github_state.gh_auth_status()
+        self.assertFalse(s["authenticated"])
+        self.assertTrue(s["gh_present"])      # gh ran, just not logged in
+        self.assertIsNone(s["user"])
+        self.assertIn("not logged", s["error"].lower())
+
+    def test_gh_not_installed(self):
+        with mock.patch("lib.github_state.subprocess.run", side_effect=FileNotFoundError()):
+            s = github_state.gh_auth_status()
+        self.assertFalse(s["gh_present"])
+        self.assertFalse(s["authenticated"])
+        self.assertIn("not found", s["error"].lower())
+
+    def test_timeout_is_present_but_unauthenticated(self):
+        with mock.patch("lib.github_state.subprocess.run",
+                        side_effect=subprocess.TimeoutExpired("gh", 30)):
+            s = github_state.gh_auth_status()
+        self.assertTrue(s["gh_present"])
+        self.assertFalse(s["authenticated"])
+
+
+class AuthStatusCommandTest(unittest.TestCase):
+    def _run(self, status, args):
+        with mock.patch("commands.auth_status.github_state.gh_auth_status", return_value=status):
+            buf = io.StringIO()
+            with redirect_stdout(buf):
+                rc = auth_status.run(args)
+        return rc, buf.getvalue()
+
+    def test_json_authenticated_exit_0(self):
+        status = {"gh_present": True, "authenticated": True, "user": "eve", "error": None}
+        rc, out = self._run(status, ["--json"])
+        self.assertEqual(rc, 0)
+        self.assertEqual(json.loads(out), status)
+
+    def test_not_logged_in_exit_1(self):
+        status = {"gh_present": True, "authenticated": False, "user": None, "error": "x"}
+        rc, out = self._run(status, [])
+        self.assertEqual(rc, 1)
+        self.assertIn("gh auth login", out)
+
+    def test_gh_missing_exit_2(self):
+        status = {"gh_present": False, "authenticated": False, "user": None, "error": "x"}
+        rc, out = self._run(status, [])
+        self.assertEqual(rc, 2)
+        self.assertIn("not found", out.lower())
+
+    def test_human_authenticated_names_user(self):
+        status = {"gh_present": True, "authenticated": True, "user": "eve", "error": None}
+        rc, out = self._run(status, [])
+        self.assertEqual(rc, 0)
+        self.assertIn("eve", out)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/work-plan/tests/test_close_issue.py

@@ -0,0 +1,121 @@
+"""close-issue (#305): a GitHub-mutating command (also in-progress, plan-status
+--issues). Offline — the gh subprocess is mocked."""
+import io
+import json
+import sys
+import unittest
+from contextlib import redirect_stdout, redirect_stderr
+from pathlib import Path
+from types import SimpleNamespace
+from unittest import mock
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(SKILL_ROOT))
+
+from commands import close_issue
+from lib import github_state
+
+
+def _proc(rc, stdout="", stderr=""):
+    return SimpleNamespace(returncode=rc, stdout=stdout, stderr=stderr)
+
+
+class CloseIssueHelperTest(unittest.TestCase):
+    def test_builds_gh_args_and_succeeds(self):
+        captured = {}
+        def fake_run(args, **kw):
+            captured["args"] = args
+            return _proc(0, stdout="✓ Closed issue #287")
+        with mock.patch("lib.github_state.subprocess.run", side_effect=fake_run):
+            ok, msg = github_state.close_issue("o/r", 287, reason="completed", comment="done")
+        self.assertTrue(ok)
+        self.assertEqual(
+            captured["args"],
+            ["gh", "issue", "close", "287", "--repo", "o/r",
+             "--reason", "completed", "--comment", "done"],
+        )
+
+    def test_omits_reason_and_comment_when_absent(self):
+        captured = {}
+        def fake_run(args, **kw):
+            captured["args"] = args
+            return _proc(0)
+        with mock.patch("lib.github_state.subprocess.run", side_effect=fake_run):
+            github_state.close_issue("o/r", 5)
+        self.assertEqual(captured["args"], ["gh", "issue", "close", "5", "--repo", "o/r"])
+
+    def test_invalid_repo_rejected(self):
+        ok, msg = github_state.close_issue("not-a-slug", 5)
+        self.assertFalse(ok)
+        self.assertIn("invalid repo", msg)
+
+    def test_gh_failure_surfaces_stderr(self):
+        with mock.patch("lib.github_state.subprocess.run",
+                        return_value=_proc(1, stderr="could not close: already closed")):
+            ok, msg = github_state.close_issue("o/r", 5)
+        self.assertFalse(ok)
+        self.assertIn("already closed", msg)
+
+    def test_never_raises_on_subprocess_error(self):
+        with mock.patch("lib.github_state.subprocess.run", side_effect=OSError("boom")):
+            ok, msg = github_state.close_issue("o/r", 5)
+        self.assertFalse(ok)
+
+
+class CloseIssueCommandTest(unittest.TestCase):
+    def _drive(self, args, slug_resolves="o/r", close_ret=(True, "✓ closed #5")):
+        with mock.patch("commands.close_issue.config_mod.load_config", return_value={"repos": {}}), \
+             mock.patch("commands.close_issue.config_mod.resolve_github_for_folder",
+                        return_value=slug_resolves), \
+             mock.patch("commands.close_issue.github_state.close_issue",
+                        return_value=close_ret) as mclose:
+            out, err = io.StringIO(), io.StringIO()
+            with redirect_stdout(out), redirect_stderr(err):
+                rc = close_issue.run(args)
+        return rc, out.getvalue(), err.getvalue(), mclose
+
+    def test_closes_with_slug(self):
+        rc, out, err, mclose = self._drive(["--repo=o/r", "--reason=completed", "--", "5"])
+        self.assertEqual(rc, 0)
+        mclose.assert_called_once_with("o/r", 5, reason="completed", comment=None)
+        self.assertIn("closed", out)
+
+    def test_resolves_key_to_slug(self):
+        rc, out, err, mclose = self._drive(["--repo=myrepo", "--", "9"], slug_resolves="org/myrepo")
+        self.assertEqual(rc, 0)
+        self.assertEqual(mclose.call_args[0][0], "org/myrepo")
+
+    def test_comment_passed_through(self):
+        rc, out, err, mclose = self._drive(["--repo=o/r", "--comment=done via dev", "--", "5"])
+        self.assertEqual(mclose.call_args[1]["comment"], "done via dev")
+        self.assertIn("with comment", out)
+
+    def test_invalid_reason_rejected(self):
+        rc, out, err, mclose = self._drive(["--repo=o/r", "--reason=bogus", "--", "5"])
+        self.assertEqual(rc, 2)
+        mclose.assert_not_called()
+
+    def test_non_integer_number_rejected(self):
+        rc, out, err, mclose = self._drive(["--repo=o/r", "--", "abc"])
+        self.assertEqual(rc, 2)
+        mclose.assert_not_called()
+
+    def test_gh_failure_returns_1(self):
+        rc, out, err, mclose = self._drive(["--repo=o/r", "--", "5"],
+                                           close_ret=(False, "no write access"))
+        self.assertEqual(rc, 1)
+        self.assertIn("no write access", err)
+
+    def test_unresolvable_repo_returns_1(self):
+        rc, out, err, mclose = self._drive(["--repo=ghost", "--", "5"], slug_resolves=None)
+        self.assertEqual(rc, 1)
+        mclose.assert_not_called()
+
+    def test_json_output(self):
+        rc, out, err, mclose = self._drive(["--repo=o/r", "--json", "--", "5"])
+        self.assertEqual(rc, 0)
+        self.assertEqual(json.loads(out)["closed"], 5)
+
+
+if __name__ == "__main__":
+    unittest.main()