@stylusnexus/work-plan 2026.6.21-1 → 2026.6.22

package/README.md

@@ -115,6 +115,8 @@ flowchart TB
 
 > **`brief` and `orient` annotate blocked issues with `⊘ blocked by #N`** — read-only, surfaced from GitHub's native dependency edges, nothing is written back. Cross-repo blockers show as `owner/repo#N`; same-repo duplicates of manually-declared blockers are deduplicated.
 
+> **A manual `blockers:` entry can be a free-text note, not just an issue number.** Normally a blocker is an issue number (`- 5550` or `- "#5550"`), which the VS Code dependency graph draws as a `blocks` edge. But it can also be prose (e.g. `- "gated on the cost go/no-go verdict"`) for when the blocker isn't a single issue. Free-text blockers still mark the track blocked and render as prose in `brief`/`orient` and the detail panel — but they don't draw a graph edge, so prefer an issue number when there is one.
+
 > **GitHub access is read-only by default, with three explicit, opt-in write actions.** Issue *data* always comes from read-only `gh` calls (`gh issue list`, `gh issue view`), and every routine write (frontmatter, status table, session log) goes to your local markdown files only. The three GitHub-*mutating* actions are all opt-in and gated: `plan-status --issues` **creates** a GitHub issue per partial plan (`gh issue create`, prompts before opening); `close-issue` (#305) **closes** an issue via `gh issue close` — for the common case where a PR merged to `dev` left its issue OPEN (GitHub auto-closes only from the default branch), with the VS Code viewer firing a mandatory "Close on GitHub? — cannot be undone" modal on every close; and `in-progress` (#271) **adds or removes** the `work-plan:in-progress` label on an issue, public-repo gated via the confirm-token flow. Nothing else touches GitHub state.
 
 ## Shared tracks

package/VERSION

@@ -1 +1 @@
-2026.06.21+1d0cb70
+2026.06.22+f62c4cc

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stylusnexus/work-plan",
-  "version": "2026.6.21-1",
+  "version": "2026.6.22",
   "description": "Track-aware daily work planning over GitHub issues. Shared tracks (git-synced .work-plan/ in each repo), AI clustering (group/auto-triage), VS Code viewer, Claude Code + Codex plugins. Pure Python stdlib.",
   "bin": {
     "work-plan": "bin/work-plan"

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

@@ -0,0 +1,40 @@
+"""Track blocker normalization — the Python sibling of the viewer's blockerIssue().
+
+A `blockers:` frontmatter entry is usually an issue number, but it may also be a
+free-text note (e.g. "gated on the cost go/no-go verdict, needs #5548 telemetry").
+Consumers that render a blocker with a leading `#` must funnel it through
+`blocker_display` first, or a prose blocker prints as `#<sentence>`; the next-up
+gate must funnel it through `blocker_issue`, or a string-form ref ("5550") never
+matches the integer issue number it should exclude.
+"""
+
+import re
+
+_ISSUE_REF = re.compile(r"^\s*#?(\d+)\s*$")
+
+
+def blocker_issue(value):
+    """The issue number a blocker refers to, or None for free-text.
+
+    Mirrors the viewer's `blockerIssue`: a bare int, "5550", or "#5550" resolves
+    to the number; anything else (prose, even when it embeds a `#5550`) is
+    free-text. A leading-zero string like "007" is treated as free-text rather
+    than silently coerced to 7. `bool` is rejected (it is an int subclass).
+    """
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str):
+        m = _ISSUE_REF.match(value)
+        if m is not None:
+            digits = m.group(1)
+            if str(int(digits)) == digits:  # reject leading-zero "007"
+                return int(digits)
+    return None
+
+
+def blocker_display(value):
+    """How to show a blocker: `#N` for an issue ref, the prose itself otherwise."""
+    n = blocker_issue(value)
+    return f"#{n}" if n is not None else str(value)

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

@@ -40,6 +40,7 @@ from __future__ import annotations
 from datetime import datetime
 from typing import Iterable, Optional
 
+from lib.blockers import blocker_issue
 from lib.github_state import extract_priority, short_milestone
 
 PRIORITY_RANK = {"P0": 0, "P1": 1, "P2": 2, "P3": 3}
@@ -151,7 +152,10 @@ def suggest_next_up(
         List of issue numbers, highest-ranked first. Empty if nothing
         qualifies (e.g., everything closed or blocked).
     """
-    blockers = set(blocker_nums or [])
+    # Normalize blockers to issue numbers: a string-form ref ("5550"/"#5550")
+    # must still exclude issue 5550, and a free-text blocker resolves to None
+    # (dropped) so it harmlessly gates nothing.
+    blockers = {n for n in (blocker_issue(b) for b in (blocker_nums or [])) if n is not None}
     in_progress = set(in_progress_nums or [])
     # Resolve order: None → default preset; unknown names in list → skipped.
     effective_order = order if order is not None else PRESETS[DEFAULT_PRESET]

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

@@ -1,5 +1,7 @@
 """Compose terminal output strings."""
 
+from lib.blockers import blocker_display
+
 
 def time_aware_framing(gap_seconds: int, current_hour: int, handoff_today: bool = True) -> str:
     """Adapt framing to gap-since-last-activity + hour."""
@@ -66,7 +68,9 @@ def render_track_row(t: dict) -> str:
     if t["blockers"]:
         for b in t["blockers"]:
             reason = b.get("reason", "manually flagged")
-            lines.append(f"    Blocker:    #{b['number']} — {reason}")
+            # blocker_display: `#N` for an issue ref, the prose verbatim for a
+            # free-text blocker (a raw `#{number}` would print `#<sentence>`).
+            lines.append(f"    Blocker:    {blocker_display(b['number'])} — {reason}")
     else:
         lines.append("    Blockers:   none")
 

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

@@ -0,0 +1,47 @@
+"""Tests for lib.blockers — blocker_issue / blocker_display normalization."""
+
+import unittest
+
+from lib.blockers import blocker_issue, blocker_display
+
+
+class TestBlockerIssue(unittest.TestCase):
+    def test_bare_int_is_its_own_ref(self):
+        self.assertEqual(blocker_issue(5550), 5550)
+
+    def test_pure_id_strings_resolve(self):
+        self.assertEqual(blocker_issue("5550"), 5550)
+        self.assertEqual(blocker_issue("#5550"), 5550)
+        self.assertEqual(blocker_issue("  #5550 "), 5550)
+
+    def test_prose_is_free_text_even_with_embedded_ref(self):
+        # Must NOT extract 5550 — it's an active next_up item being described.
+        self.assertIsNone(
+            blocker_issue("#5550 selective routing is gated on the verdict, needs #5548")
+        )
+        self.assertIsNone(blocker_issue("waiting on design review"))
+
+    def test_leading_zero_is_free_text(self):
+        # "007" must not silently become issue 7.
+        self.assertIsNone(blocker_issue("007"))
+
+    def test_bool_and_empty_are_free_text(self):
+        self.assertIsNone(blocker_issue(True))
+        self.assertIsNone(blocker_issue(""))
+        self.assertIsNone(blocker_issue("#"))
+
+
+class TestBlockerDisplay(unittest.TestCase):
+    def test_issue_ref_gets_hash_prefix(self):
+        self.assertEqual(blocker_display(5550), "#5550")
+        self.assertEqual(blocker_display("#5550"), "#5550")
+        self.assertEqual(blocker_display("5550"), "#5550")
+
+    def test_free_text_shown_verbatim_without_hash(self):
+        prose = "gated on the cost go/no-go verdict"
+        self.assertEqual(blocker_display(prose), prose)
+        self.assertNotIn("#", blocker_display(prose))
+
+
+if __name__ == "__main__":
+    unittest.main()