@stylusnexus/work-plan 2026.6.9-2 → 2026.6.9-3

package/README.md

@@ -378,9 +378,9 @@ work-plan-toolkit/
 │   ├── work-plan/
 │   │   ├── SKILL.md
 │   │   ├── work_plan.py                # CLI entry
-│   │   ├── commands/                   # 16 subcommand modules
+│   │   ├── commands/                   # 24 subcommand modules
 │   │   ├── lib/                        # config, frontmatter, gh, git, prompts, …
-│   │   └── tests/                      # 234 unittest cases
+│   │   └── tests/                      # 600+ unittest cases
 │   └── repo-activity-summary/
 │       └── SKILL.md                    # bundled companion skill
 ├── commands/
@@ -497,8 +497,8 @@ See `docs/usage-examples.md` for end-to-end scenarios (morning brief, mid-work h
 | `new-track <repo> <slug> [--priority=P0..P3] [--milestone=<m>]` | One-shot, non-interactive: create a new track file under `notes_root` for `<repo>` (a config key **or** an `org/repo` slug) with frontmatter. Unlike `init`, it makes the file for you — the headless creation path the VS Code viewer uses. |
 | `set-notes-root <path>` | Relocate where your private track notes live (updates `notes_root` in config). Does not move existing tracks — it warns if any would be orphaned. |
 | `suggest-priorities --repo=<key>` | Two-step AI label backfill: CLI fetches unlabeled issues, Claude proposes priorities, `--apply` writes labels via `gh`. |
-| `group [--milestone=X] [--label=Y] [--repo=Z] [--private] [--apply]` | AI-cluster GitHub issues into thematic track files. Two-step: CLI prints prompt → you save JSON answer → `--apply` creates the tracks. `--private` routes to `notes_root` instead of `.work-plan/`. |
-| `auto-triage [--repo=<key>] [--apply]` | AI-assign untracked open issues to existing tracks. Two-step (same pattern as `group`). Run `coverage` first to measure the gap. |
+| `group [--milestone=X] [--label=Y] [--repo=Z] [--private] [--apply] [--limit=N]` | AI-cluster GitHub issues into thematic track files. Two-step: CLI prints prompt → you save JSON answer → `--apply` creates the tracks. `--private` routes to `notes_root` instead of `.work-plan/`. `--limit` controls how many issues are shown in the prompt (default 100). |
+| `auto-triage [--repo=<key>] [--apply] [--limit=N]` | AI-assign untracked open issues to existing tracks. Two-step (same pattern as `group`). Run `coverage` first to measure the gap. `--limit` controls how many untracked issues are shown (default 100). |
 | `coverage [--repo=<key>] [--list] [--limit=N]` | Report how many open issues are not in any track. `--list` prints titles. Read-only. |
 | `reconcile <track>` `\|` `--all` `\|` `--repo=<key> [--draft]` | Update track MEMBERSHIP (the `github.issues` list in frontmatter) by syncing against a GitHub label. Read-only on GitHub. Default label is `track/<slug>`; override per-track via `github.labels: [...]` in frontmatter (OR semantics). `--draft` previews ADDs/FLAGs without prompting or writing. `--repo=<key>` scopes the sweep to one repo. NOT for hand-curated tracks (it'll propose dropping curated issues every run) — use `refresh-md` if you only want to update issue state. When >50% of frontmatter issues lack the label, reconcile prints a hint pointing to `refresh-md`. |
 | `duplicates [--repo=<key>]` | Find likely-duplicate issues by title similarity (stdlib `difflib`). Prints `gh issue close` consolidation commands. |
@@ -543,7 +543,7 @@ cd skills/work-plan
 python3 -m unittest discover tests
 ```
 
-234 tests, no external dependencies (mocks `gh`/`git` calls).
+600+ tests, no external dependencies (mocks `gh`/`git` calls).
 
 ## License
 

package/VERSION

@@ -1 +1 @@
-2026.06.09+530f7e8
+2026.06.09+f86ff30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stylusnexus/work-plan",
-  "version": "2026.6.9-2",
+  "version": "2026.6.9-3",
   "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/commands/auto_triage.py

@@ -61,6 +61,15 @@ def run(args: list[str]) -> int:
     apply_mode = "--apply" in args
     repo_arg = next((a for a in args if a.startswith("--repo=")), None)
 
+    limit = 100
+    for a in args:
+        if a.startswith("--limit="):
+            try:
+                limit = int(a.split("=", 1)[1])
+            except ValueError:
+                print("ERROR: --limit must be an integer.")
+                return 2
+
     try:
         cfg = load_config()
     except ConfigError as e:
@@ -139,13 +148,17 @@ def run(args: list[str]) -> int:
 
     print()
     print("Untracked issues to assign:")
-    for i in untracked:
+    shown = untracked[:limit]
+    for i in shown:
         num = i.get("number", "?")
         title = i.get("title", "")
         milestone = i.get("milestone") or {}
         m_title = milestone.get("title", "—") if isinstance(milestone, dict) else "—"
         labels = [lb["name"] for lb in (i.get("labels") or [])]
         print(f"  #{num} [{m_title}] [{','.join(labels) or 'no-labels'}] {title}")
+    remainder = len(untracked) - len(shown)
+    if remainder > 0:
+        print(f"  … and {remainder} more issues (use --limit=N to show more)")
 
     print("=" * 60)
     print()

package/skills/work-plan/commands/canonicalize.py

@@ -77,6 +77,7 @@ def run(args: list[str]) -> int:
 
         new_body = _insert_canonical_table(
             track.body, issue_nums, issues_by_num, replace=force,
+            milestone_alignment=track.meta.get("milestone_alignment"),
         )
         write_file(track.path, track.meta, new_body)
         print(f"  ✓ {track.name}: canonical table added/refreshed ({len(issue_nums)} issues)")
@@ -88,9 +89,10 @@ def run(args: list[str]) -> int:
 
 
 def _insert_canonical_table(body: str, issue_nums: list[int],
-                            issues_by_num: dict, replace: bool = False) -> str:
+                            issues_by_num: dict, replace: bool = False,
+                            milestone_alignment=None) -> str:
     """Insert (or replace) a canonical table at the top of the body."""
-    table_md = _render_canonical_table(issue_nums, issues_by_num)
+    table_md = _render_canonical_table(issue_nums, issues_by_num, milestone_alignment)
 
     if replace:
         # Strip existing canonical block (marker + heading + table + separator)
@@ -102,22 +104,57 @@ def _insert_canonical_table(body: str, issue_nums: list[int],
     return leading_whitespace + table_md + "\n---\n\n" + body_stripped
 
 
-def _render_canonical_table(issue_nums: list[int], issues_by_num: dict) -> str:
+def _render_canonical_table(issue_nums: list[int], issues_by_num: dict,
+                            milestone_alignment=None) -> str:
     lines = [
         "## Issues (canonical)",
         "",
         f"{CANONICAL_MARKER} — auto-managed by /work-plan refresh-md. Don't edit by hand. -->",
         "",
-        "| # | Title | Assignee | Status |",
-        "|---|---|---|---|",
     ]
+
+    # Build a normalized issue list with compact milestone strings.
+    from lib.github_state import short_milestone
+    norm_issues = []
     for num in sorted(issue_nums):
-        i = issues_by_num.get(num, {})
-        lines.append(render_issue_row(
-            num, i.get("title", "(not fetched)"),
-            format_assignees(i), state_to_status_label(i.get("state")),
-        ))
-    lines.append("")
+        gh = issues_by_num.get(num, {})
+        ms = short_milestone(gh.get("milestone")) or None
+        norm_issues.append({"number": num, "milestone": ms, "_gh": gh})
+
+    from lib.export_model import group_issues_by_milestone
+    groups = group_issues_by_milestone(norm_issues, milestone_alignment)
+
+    if len(groups) <= 1:
+        # Single milestone group (or all null) — render flat, same as before.
+        lines.append("| # | Title | Assignee | Status |")
+        lines.append("|---|---|---|---|")
+        for num in sorted(issue_nums):
+            i = issues_by_num.get(num, {})
+            lines.append(render_issue_row(
+                num, i.get("title", "(not fetched)"),
+                format_assignees(i), state_to_status_label(i.get("state")),
+            ))
+        lines.append("")
+        return "\n".join(lines)
+
+    # Multiple milestone groups — render with section headings.
+    for label, issues in groups:
+        if label:
+            heading = f"{label} ({len(issues)})"
+        else:
+            heading = f"No milestone ({len(issues)})"
+        lines.append(f"### {heading}")
+        lines.append("")
+        lines.append("| # | Title | Assignee | Status |")
+        lines.append("|---|---|---|---|")
+        for norm in issues:
+            num = norm["number"]
+            i = norm["_gh"]
+            lines.append(render_issue_row(
+                num, i.get("title", "(not fetched)"),
+                format_assignees(i), state_to_status_label(i.get("state")),
+            ))
+        lines.append("")
     return "\n".join(lines)
 
 

package/skills/work-plan/commands/group.py

@@ -63,6 +63,15 @@ def run(args: list[str]) -> int:
     label_arg = next((a for a in args if a.startswith("--label=")), None)
     state_arg = next((a for a in args if a.startswith("--state=")), None)
 
+    limit = 100
+    for a in args:
+        if a.startswith("--limit="):
+            try:
+                limit = int(a.split("=", 1)[1])
+            except ValueError:
+                print("ERROR: --limit must be an integer.")
+                return 2
+
     try:
         cfg = load_config()
     except ConfigError as e:
@@ -123,11 +132,15 @@ def run(args: list[str]) -> int:
     print()
     print("=" * 60)
     print(PROMPT_TEMPLATE)
-    for i in issues:
+    shown = issues[:limit]
+    for i in shown:
         m = i.get("milestone", {})
         m_title = m.get("title", "—") if m else "—"
         labels = [l["name"] for l in i.get("labels", [])]
         print(f"#{i['number']} [{m_title}] [{','.join(labels) or 'no-labels'}] {i['title']}")
+    remainder = len(issues) - len(shown)
+    if remainder > 0:
+        print(f"… and {remainder} more issues (use --limit=N to show more)")
     print("=" * 60)
     print()
     print(f"After agent returns clusters JSON, save to {_answers_path()}")
@@ -202,7 +215,9 @@ def _apply(cfg: dict, args: list[str] = None) -> int:
         slug = _slugify(cluster["slug"])
         name = cluster.get("name", slug)
         summary = cluster.get("summary", "")
-        cluster_issues = sorted(set(cluster.get("issues") or []))
+        cluster_issues = _sort_by_milestone(
+            sorted(set(cluster.get("issues") or [])), issues_by_num, batch_milestone,
+        )
         if not cluster_issues:
             print(f"  SKIP {slug}: no issues")
             continue
@@ -214,7 +229,10 @@ def _apply(cfg: dict, args: list[str] = None) -> int:
                 print(f"  SKIP {slug}: file exists but has no frontmatter; use init first")
                 continue
             existing_issues = list(existing_meta.get("github", {}).get("issues") or [])
-            merged = sorted(set(existing_issues) | set(cluster_issues))
+            merged = _sort_by_milestone(
+                sorted(set(existing_issues) | set(cluster_issues)), issues_by_num,
+                existing_meta.get("milestone_alignment") or batch_milestone,
+            )
             existing_meta.setdefault("github", {})["issues"] = merged
             existing_meta["last_touched"] = datetime.now().strftime("%Y-%m-%dT%H:%M")
             write_file(path, existing_meta, existing_body)
@@ -228,7 +246,7 @@ def _apply(cfg: dict, args: list[str] = None) -> int:
                 "launch_priority": "P3",
                 "milestone_alignment": batch_milestone,
                 "github": {"repo": repo, "issues": cluster_issues, "branches": []},
-                "related_tracks": [],
+                "depends_on": [],
                 "last_touched": now, "last_handoff": now,
                 "next_up": [], "blockers": [],
             }
@@ -246,6 +264,26 @@ def _apply(cfg: dict, args: list[str] = None) -> int:
     return 0
 
 
+def _sort_by_milestone(issue_nums, issues_by_num, milestone_alignment=None):
+    """Return issue_nums sorted by milestone then number.
+
+    milestone_alignment issues come first, then other non-null milestones
+    (grouped by label), then null-milestone issues last.  Graceful fallback:
+    if no milestone data is available, falls back to pure numeric sort.
+    """
+    from lib.export_model import milestone_sort_key
+    from lib.github_state import short_milestone
+
+    norm = []
+    for num in issue_nums:
+        gh = issues_by_num.get(num, {})
+        ms = short_milestone(gh.get("milestone")) or None
+        norm.append({"number": num, "milestone": ms})
+
+    norm.sort(key=lambda i: milestone_sort_key(i, milestone_alignment))
+    return [i["number"] for i in norm]
+
+
 def _slugify(s: str) -> str:
     s = s.strip().lower()
     s = re.sub(r"[^a-z0-9-]+", "-", s)

package/skills/work-plan/commands/init.py

@@ -119,7 +119,7 @@ def run(args: list[str]) -> int:
         "launch_priority": priority,
         "milestone_alignment": milestone,
         "github": {"repo": repo or "TBD", "issues": issue_nums, "branches": []},
-        "related_tracks": [],
+        "depends_on": [],
         "last_touched": now, "last_handoff": now,
         "next_up": [], "blockers": [],
     }

package/skills/work-plan/commands/move.py

@@ -0,0 +1,131 @@
+"""move subcommand — source-first issue relocation between tracks."""
+import json
+
+from lib.config import load_config, ConfigError
+from lib.tracks import discover_tracks, find_track_by_name, parse_track_repo_arg, AmbiguousTrackError
+from lib.frontmatter import write_file
+from lib.write_guard import needs_confirm, make_token, valid_token
+from lib.prompts import parse_flags
+
+
+def run(args: list[str]) -> int:
+    """move <issue-num> <from-track> <to-track> [--confirm=<token>] [--repo=<key>]
+
+    Removes <issue-num> from <from-track>'s frontmatter and adds it to
+    <to-track>'s frontmatter.  Both tracks must be active and in the same
+    repo.  Public-repo writes gate behind --confirm (same flow as slot/set).
+    """
+    flags, positional = parse_flags(args, {"--confirm", "--repo"})
+    if len(positional) < 3:
+        print("usage: work_plan.py move <issue-num> <from-track> <to-track> [--confirm=<token>] [--repo=<key>]")
+        return 2
+
+    try:
+        issue_num = int(positional[0])
+    except ValueError:
+        print(f"ERROR: '{positional[0]}' is not an issue number.")
+        return 2
+
+    from_arg, to_arg = positional[1], positional[2]
+    repo_flag = flags.get("--repo") if flags.get("--repo") is not True else None
+
+    # Resolve from-track
+    from_name = from_arg
+    repo_qualifier = repo_flag
+    name_from, repo_from = parse_track_repo_arg(from_arg)
+    if name_from:
+        from_name = name_from
+    if repo_from:
+        repo_qualifier = repo_from
+
+    # Resolve to-track (may override repo qualifier)
+    to_name = to_arg
+    name_to, repo_to = parse_track_repo_arg(to_arg)
+    if name_to:
+        to_name = name_to
+    if repo_to:
+        repo_qualifier = repo_to
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        return 1
+
+    tracks = discover_tracks(cfg)
+
+    # Find both tracks (active only)
+    try:
+        src = find_track_by_name(from_name, tracks, active_only=True, repo=repo_qualifier)
+    except AmbiguousTrackError as e:
+        print(str(e))
+        return 1
+
+    if not src:
+        print(f"No active track matching '{from_name}'.")
+        return 1
+
+    try:
+        dst = find_track_by_name(to_name, tracks, active_only=True, repo=repo_qualifier)
+    except AmbiguousTrackError as e:
+        print(str(e))
+        return 1
+
+    if not dst:
+        print(f"No active track matching '{to_name}'.")
+        return 1
+
+    # Same-repo guard
+    if src.repo != dst.repo:
+        print(f"ERROR: cross-repo moves not supported ({src.repo} ≠ {dst.repo}).")
+        return 1
+
+    # Same-track no-op
+    if src.name == dst.name:
+        print(f"#{issue_num} already in track '{src.name}'.")
+        return 0
+
+    # Validate issue is in source
+    src_issues = list(src.meta.get("github", {}).get("issues") or [])
+    if issue_num not in src_issues:
+        print(f"ERROR: #{issue_num} is not in track '{src.name}'.")
+        return 1
+
+    # Check if already in destination
+    dst_issues = list(dst.meta.get("github", {}).get("issues") or [])
+    if issue_num in dst_issues:
+        print(f"#{issue_num} already in track '{dst.name}'. Removing from '{src.name}' only.")
+        # Still remove from source even if already in dest
+        src_issues.remove(issue_num)
+        src.meta.setdefault("github", {})["issues"] = src_issues
+        write_file(src.path, src.meta, src.body)
+        print(f"  ✓ Removed #{issue_num} from '{src.name}'.")
+        return 0
+
+    # Public-repo confirm gate (on the destination write)
+    confirm = flags.get("--confirm")
+    if dst.repo and needs_confirm(dst.repo, cfg) and not (
+        isinstance(confirm, str) and valid_token(confirm, dst.repo, dst.name)
+    ):
+        print(json.dumps({
+            "needs_confirm": True,
+            "reason": (
+                f"{dst.repo} is PUBLIC (or visibility unknown); "
+                f"moving #{issue_num} will be written there."
+            ),
+            "token": make_token(dst.repo, dst.name),
+        }))
+        return 0
+
+    # Execute: remove from source, add to destination
+    src_issues.remove(issue_num)
+    src.meta.setdefault("github", {})["issues"] = src_issues
+    write_file(src.path, src.meta, src.body)
+    print(f"  ✓ Removed #{issue_num} from '{src.name}'.")
+
+    dst_issues.append(issue_num)
+    dst.meta.setdefault("github", {})["issues"] = sorted(dst_issues)
+    write_file(dst.path, dst.meta, dst.body)
+    print(f"  ✓ Added #{issue_num} to '{dst.name}'.")
+
+    return 0

package/skills/work-plan/commands/new_track.py

@@ -193,7 +193,7 @@ def run(args: list[str]) -> int:
         "launch_priority": priority,
         "milestone_alignment": milestone,
         "github": {"repo": github, "issues": [], "branches": []},
-        "related_tracks": [],
+        "depends_on": [],
         "last_touched": now,
         "last_handoff": now,
         "next_up": [],

package/skills/work-plan/commands/set_field.py

@@ -6,7 +6,7 @@ from lib.frontmatter import write_file
 from lib.write_guard import needs_confirm, make_token, valid_token
 from lib.prompts import parse_flags
 
-ALLOWED = {"status", "launch_priority", "milestone_alignment", "blockers", "next_up"}
+ALLOWED = {"status", "launch_priority", "milestone_alignment", "blockers", "next_up", "depends_on"}
 LIST_FIELDS = {"blockers", "next_up"}
 STATUSES = {"active", "in-progress", "blocked", "parked", "shipped", "abandoned"}
 
@@ -29,7 +29,10 @@ def run(args: list[str]) -> int:
         k, v = a.split("=", 1)
         if k not in ALLOWED:
             print(f"ERROR: field {k!r} not settable (allowed: {sorted(ALLOWED)})"); return 2
-        if k in LIST_FIELDS:
+        if k == "depends_on":
+            # Comma-separated track slugs (strings, not issue numbers).
+            parsed[k] = [x.strip() for x in v.split(",") if x.strip()] if v.strip() else []
+        elif k in LIST_FIELDS:
             try:
                 parsed[k] = [int(x) for x in v.split(",") if x.strip()] if v.strip() else []
             except ValueError:

package/skills/work-plan/commands/where_was_i.py

@@ -25,7 +25,7 @@ from pathlib import Path
 from typing import Optional
 
 from lib.config import load_config, ConfigError
-from lib.tracks import discover_tracks, find_track_by_name
+from lib.tracks import discover_tracks, find_track_by_name, parse_track_repo_arg, AmbiguousTrackError
 from lib.prompts import prompt_input, parse_flags
 from lib.github_state import fetch_issues, short_milestone
 from lib.git_state import (
@@ -40,8 +40,18 @@ RULE_WIDTH = 57
 
 
 def run(args: list[str]) -> int:
-    flags, positional = parse_flags(args, {"--pick"})
-    track_name = positional[0] if positional else None
+    flags, positional = parse_flags(args, {"--pick", "--repo"})
+    track_arg = positional[0] if positional else None
+    repo_flag = flags.get("--repo") if flags.get("--repo") is not True else None
+
+    # Resolve track name and repo qualifier from <track>@<repo> syntax
+    track_name = track_arg
+    repo_qualifier = repo_flag
+    if track_arg:
+        name_from_arg, repo_from_arg = parse_track_repo_arg(track_arg)
+        track_name = name_from_arg
+        if repo_from_arg:
+            repo_qualifier = repo_from_arg
 
     try:
         cfg = load_config()
@@ -78,12 +88,20 @@ def run(args: list[str]) -> int:
                 return 1
             track = active[idx]
         else:
-            track = find_track_by_name(choice, tracks)
+            try:
+                track = find_track_by_name(choice, tracks, repo=repo_qualifier)
+            except AmbiguousTrackError as e:
+                print(str(e))
+                return 1
             if not track:
                 print(f"No track matching '{choice}'.")
                 return 1
     else:
-        track = find_track_by_name(track_name, tracks)
+        try:
+            track = find_track_by_name(track_name, tracks, repo=repo_qualifier)
+        except AmbiguousTrackError as e:
+            print(str(e))
+            return 1
         if not track:
             print(f"No track matching '{track_name}'.")
             return 1

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

@@ -3,6 +3,55 @@ from lib.github_state import format_assignees, short_milestone
 
 SCHEMA = 1
 
+
+def milestone_sort_key(issue: dict, milestone_alignment=None):
+    """Sort key for an issue dict (must have 'number' and 'milestone').
+
+    Returns (tier, milestone_label, number) so that:
+      0. issues matching milestone_alignment come first
+      1. issues with other non-null milestones come next, grouped by label
+      2. issues with null/empty milestone come last.
+
+    milestone may be a compact string (as from short_milestone) or None.
+    """
+    ms = issue.get("milestone")
+    num = issue.get("number", 0) or 0
+    if ms is None or ms == "":
+        return (2, "", num)
+    if ms == milestone_alignment:
+        return (0, ms, num)
+    return (1, ms, num)
+
+
+def group_issues_by_milestone(issues, milestone_alignment=None):
+    """Partition sorted issues into [(label, [issue, ...]), ...].
+
+    label is the compact milestone string; None for the no-milestone group.
+    Groups are emitted in milestone_sort_key order.  A single-group result
+    means all issues share the same milestone (or all lack one) — callers
+    can use this to decide whether to render section headings.
+    """
+    if not issues:
+        return []
+    sorted_issues = sorted(issues,
+                           key=lambda i: milestone_sort_key(i, milestone_alignment))
+    groups = []
+    current_label = None  # sentinel — always differs from the first real label
+    current_group = []
+    for i in sorted_issues:
+        label = i.get("milestone") or None
+        if label != current_label:
+            if current_group:
+                groups.append((current_label, current_group))
+            current_label = label
+            current_group = [i]
+        else:
+            current_group.append(i)
+    if current_group:
+        groups.append((current_label, current_group))
+    return groups
+
+
 def _issue(i: dict) -> dict:
     state = (i.get("state") or "OPEN").lower()
     return {
@@ -13,11 +62,14 @@ def _issue(i: dict) -> dict:
         "milestone": short_milestone(i.get("milestone")) or None,
     }
 
+
 def build_export(tracks, issues_by_track, visibility, now: str,
                  untracked_by_repo=None) -> dict:
     out = {"schema": SCHEMA, "generated_at": now, "tracks": []}
     for t in tracks:
         issues = [_issue(i) for i in issues_by_track.get(t.name, [])]
+        milestone_alignment = t.meta.get("milestone_alignment")
+        issues.sort(key=lambda i: milestone_sort_key(i, milestone_alignment))
         opened = sum(1 for i in issues if i["state"] == "open")
         closed_nums = {i["number"] for i in issues if i["state"] == "closed"}
         next_up = [n for n in (t.meta.get("next_up") or []) if n not in closed_nums]
@@ -27,10 +79,11 @@ def build_export(tracks, issues_by_track, visibility, now: str,
             "tier": getattr(t, "tier", "private") or "private",
             "status": t.meta.get("status"),
             "launch_priority": t.meta.get("launch_priority"),
-            "milestone_alignment": t.meta.get("milestone_alignment"),
+            "milestone_alignment": milestone_alignment,
             "visibility": visibility.get(t.repo),
             "blockers": list(t.meta.get("blockers") or []),
             "next_up": next_up,
+            "depends_on": list(t.meta.get("depends_on") or []),
             "rollup": {"open": opened, "closed": len(issues) - opened},
             "issues": issues,
         })

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

@@ -37,15 +37,23 @@ def fetch_issue(repo: str, number: int) -> Optional[dict]:
 
 
 def fetch_issues(repo: str, issue_numbers: Iterable[int]) -> list[dict]:
-    """Fetch state of multiple issues via gh (sequential). Unchanged semantics."""
+    """Fetch state of multiple issues via batched GraphQL (full field set).
+    Falls back to per-issue `gh issue view` for any numbers the GraphQL query
+    didn't return (preserves existing behaviour for transient failures).
+    Returns a list in the same order as `issue_numbers` (skips not-found)."""
     nums = list(issue_numbers)
     if not nums:
         return []
+    # Fast path: batched GraphQL with full field set
+    gql_results = fetch_repo_issues_graphql(repo, nums, fields=_GQL_FIELDS_FULL)
+    # Fall back to per-issue fetch for anything GraphQL missed
     results = []
     for num in nums:
-        result = fetch_issue(repo, num)
-        if result is not None:
-            results.append(result)
+        issue = gql_results.get(num)
+        if issue is None:
+            issue = fetch_issue(repo, num)
+        if issue is not None:
+            results.append(issue)
     return results
 
 
@@ -72,11 +80,15 @@ def fetch_issues_concurrent(jobs: Iterable[tuple], max_workers: int = MAX_FETCH_
 
 
 def _normalize_gql_node(node) -> Optional[dict]:
-    """Reshape a GraphQL issueOrPullRequest node into the REST-ish shape export_model
-    expects (assignees as [{login}], milestone as {title}|None). None for a null node.
-    On success returns a dict with keys: number, title, state, assignees, milestone."""
+    """Reshape a GraphQL issueOrPullRequest node into the REST-ish shape callers
+    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."""
     if not node:
         return None
+    labels = [{"name": l.get("name")} for l in
+              ((node.get("labels") or {}).get("nodes") or []) if l.get("name")]
     assignees = [{"login": a.get("login")} for a in
                  ((node.get("assignees") or {}).get("nodes") or []) if a.get("login")]
     ms = node.get("milestone")
@@ -84,13 +96,38 @@ def _normalize_gql_node(node) -> Optional[dict]:
         "number": node.get("number"),
         "title": node.get("title", ""),
         "state": node.get("state", "OPEN"),
-        "assignees": assignees,
+        "labels": labels,
         "milestone": {"title": ms["title"]} if ms and ms.get("title") else None,
+        "closedAt": node.get("closedAt"),
+        "body": node.get("body", ""),
+        "url": node.get("url", ""),
+        "updatedAt": node.get("updatedAt"),
+        "assignees": assignees,
     }
 
 
-def _gql_query(owner: str, name: str, numbers: list) -> str:
-    fields = ("number title state assignees(first: 10) { nodes { login } } milestone { title }")
+# Shared GQL field set used by both export (lean) and fetch_issues (full).
+# 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 } }"
+    " milestone { title }"
+    " closedAt body url updatedAt"
+    " assignees(first: 10) { nodes { login } }"
+)
+
+_GQL_FIELDS_LEAN = (
+    "number title state"
+    " assignees(first: 10) { nodes { login } }"
+    " milestone { title }"
+)
+
+
+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)."""
     aliases = "\n".join(
         f'  i{n}: issueOrPullRequest(number: {int(n)}) {{ '
         f'... on Issue {{ {fields} }} ... on PullRequest {{ {fields} }} }}'
@@ -100,10 +137,14 @@ def _gql_query(owner: str, name: str, numbers: list) -> str:
 
 
 def fetch_repo_issues_graphql(repo: str, numbers, chunk: int = GQL_CHUNK,
-                              max_workers: int = MAX_FETCH_WORKERS) -> dict:
+                              max_workers: int = MAX_FETCH_WORKERS,
+                              fields: str = _GQL_FIELDS_LEAN) -> dict:
     """Fetch exactly `numbers` from `repo` via batched GraphQL (issueOrPullRequest, so
     PRs are included). Returns {number: normalized_issue} for those found. Never raises;
-    missing/null/errored numbers are simply omitted (caller may fall back per-issue)."""
+    missing/null/errored numbers are simply omitted (caller may fall back per-issue).
+
+    `fields` selects the GQL field set; _GQL_FIELDS_LEAN (default) for export,
+    _GQL_FIELDS_FULL for fetch_issues (which needs labels, closedAt, body, url)."""
     try:
         nums = list(dict.fromkeys(int(n) for n in numbers))
     except (ValueError, TypeError):
@@ -116,7 +157,7 @@ def fetch_repo_issues_graphql(repo: str, numbers, chunk: int = GQL_CHUNK,
     def _run(batch):
         try:
             proc = subprocess.run(
-                ["gh", "api", "graphql", "-f", "query=" + _gql_query(owner, name, batch)],
+                ["gh", "api", "graphql", "-f", "query=" + _gql_query(owner, name, batch, fields=fields)],
                 capture_output=True, text=True,
             )
         except Exception:

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

@@ -170,6 +170,33 @@ class AutoTriagePrepareTest(unittest.TestCase):
         self.assertEqual(len(stored["tracks"]), 1)
         self.assertEqual(stored["tracks"][0]["slug"], "auth-flow")
 
+    def test_limit_truncates_with_more_issues(self):
+        """When untracked count exceeds --limit, show first N + truncation hint."""
+        cfg = _make_cfg()
+        tracks = [_make_track("auth-flow", "org/myrepo", [])]
+        issues = _open_issues(*range(1, 110))  # 109 untracked
+        rc, out, _ = _drive_prepare(["--limit=10"], cfg=cfg, tracks=tracks,
+                                    open_issues=issues)
+        self.assertEqual(rc, 0)
+        self.assertIn("Issue 1", out)
+        self.assertIn("Issue 10", out)
+        self.assertNotIn("Issue 11", out)
+        self.assertIn("and 99 more", out)
+        self.assertIn("--limit", out)
+
+    def test_limit_at_or_below_count_shows_all(self):
+        """When untracked count is within --limit, show all with no truncation."""
+        cfg = _make_cfg()
+        tracks = [_make_track("auth-flow", "org/myrepo", [])]
+        issues = _open_issues(1, 2, 3)
+        rc, out, _ = _drive_prepare([], cfg=cfg, tracks=tracks,
+                                    open_issues=issues)
+        self.assertEqual(rc, 0)
+        self.assertIn("Issue 1", out)
+        self.assertIn("Issue 2", out)
+        self.assertIn("Issue 3", out)
+        self.assertNotIn("more issues", out)
+
 
 # ---------------------------------------------------------------------------
 # Apply step tests

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

@@ -6,10 +6,11 @@ SKILL_ROOT = Path(__file__).resolve().parents[1]; sys.path.insert(0, str(SKILL_R
 from lib.export_model import build_export
 import commands.export as export_cmd
 
-def _track(name, repo, issues, blockers=None, next_up=None, status="active"):
+def _track(name, repo, issues, blockers=None, next_up=None, status="active", depends_on=None):
     return SimpleNamespace(name=name, repo=repo, tier="private",
         meta={"status": status, "launch_priority": "P2", "milestone_alignment": "v1",
               "blockers": blockers or [], "next_up": next_up or [],
+              "depends_on": depends_on or [],
               "github": {"repo": repo, "issues": issues}})
 
 class BuildExportTest(unittest.TestCase):
@@ -167,3 +168,127 @@ class BuildExportTierFieldTest(unittest.TestCase):
 class ExportCommandGateTest(unittest.TestCase):
     def test_requires_json_flag(self):
         self.assertEqual(export_cmd.run([]), 2)
+
+
+class MilestoneSortKeyTest(unittest.TestCase):
+    """Tests for milestone_sort_key — the sort-order function."""
+
+    def test_active_milestone_first(self):
+        from lib.export_model import milestone_sort_key
+        active = {"number": 10, "milestone": "v1"}
+        future = {"number": 20, "milestone": "v2"}
+        # active milestone (matches alignment) should sort before future
+        self.assertLess(
+            milestone_sort_key(active, milestone_alignment="v1"),
+            milestone_sort_key(future, milestone_alignment="v1"),
+        )
+
+    def test_future_before_null(self):
+        from lib.export_model import milestone_sort_key
+        future = {"number": 10, "milestone": "v2"}
+        null_ms = {"number": 99, "milestone": None}
+        self.assertLess(
+            milestone_sort_key(future, milestone_alignment="v1"),
+            milestone_sort_key(null_ms, milestone_alignment="v1"),
+        )
+
+    def test_null_last(self):
+        from lib.export_model import milestone_sort_key
+        null_ms = {"number": 10, "milestone": None}
+        active = {"number": 20, "milestone": "v1"}
+        self.assertLess(
+            milestone_sort_key(active, milestone_alignment="v1"),
+            milestone_sort_key(null_ms, milestone_alignment="v1"),
+        )
+
+    def test_number_tiebreak_within_group(self):
+        from lib.export_model import milestone_sort_key
+        a = {"number": 10, "milestone": "v1"}
+        b = {"number": 5, "milestone": "v1"}
+        # Both match alignment → tier 0; lower number sorts first
+        self.assertLess(
+            milestone_sort_key(b, milestone_alignment="v1"),
+            milestone_sort_key(a, milestone_alignment="v1"),
+        )
+
+    def test_empty_string_milestone_treated_as_null(self):
+        from lib.export_model import milestone_sort_key
+        empty = {"number": 1, "milestone": ""}
+        null_ms = {"number": 2, "milestone": None}
+        # Both should be in tier 2
+        k1 = milestone_sort_key(empty, milestone_alignment="v1")
+        k2 = milestone_sort_key(null_ms, milestone_alignment="v1")
+        self.assertEqual(k1[0], 2)  # tier
+        self.assertEqual(k2[0], 2)
+
+
+class GroupIssuesByMilestoneTest(unittest.TestCase):
+    """Tests for group_issues_by_milestone."""
+
+    def test_single_group_returns_one_entry(self):
+        from lib.export_model import group_issues_by_milestone
+        issues = [
+            {"number": 1, "milestone": "v1"},
+            {"number": 2, "milestone": "v1"},
+        ]
+        groups = group_issues_by_milestone(issues, milestone_alignment="v1")
+        self.assertEqual(len(groups), 1)
+        label, items = groups[0]
+        self.assertEqual(label, "v1")
+        self.assertEqual([i["number"] for i in items], [1, 2])
+
+    def test_all_null_returns_single_group(self):
+        from lib.export_model import group_issues_by_milestone
+        issues = [
+            {"number": 2, "milestone": None},
+            {"number": 1, "milestone": None},
+        ]
+        groups = group_issues_by_milestone(issues, milestone_alignment="v1")
+        self.assertEqual(len(groups), 1)
+        label, items = groups[0]
+        self.assertIsNone(label)
+        # Sorted by number within the null group
+        self.assertEqual([i["number"] for i in items], [1, 2])
+
+    def test_multi_group_active_first(self):
+        from lib.export_model import group_issues_by_milestone
+        issues = [
+            {"number": 30, "milestone": None},
+            {"number": 20, "milestone": "v2"},
+            {"number": 10, "milestone": "v1"},
+        ]
+        groups = group_issues_by_milestone(issues, milestone_alignment="v1")
+        self.assertEqual(len(groups), 3)
+        # Active milestone (v1) first
+        self.assertEqual(groups[0][0], "v1")
+        self.assertEqual([i["number"] for i in groups[0][1]], [10])
+        # Future (v2) second
+        self.assertEqual(groups[1][0], "v2")
+        self.assertEqual([i["number"] for i in groups[1][1]], [20])
+        # Null last
+        self.assertIsNone(groups[2][0])
+        self.assertEqual([i["number"] for i in groups[2][1]], [30])
+
+    def test_empty_issues_returns_empty(self):
+        from lib.export_model import group_issues_by_milestone
+        self.assertEqual(group_issues_by_milestone([]), [])
+
+
+class BuildExportDependsOnTest(unittest.TestCase):
+    """Tests that depends_on is surfaced in the export JSON (#102)."""
+
+    def test_depends_on_exported(self):
+        tracks = [_track("alpha", "o/r", [1], depends_on=["beta", "gamma"])]
+        issues_by_track = {"alpha": [
+            {"number": 1, "title": "a", "state": "OPEN", "assignees": []},
+        ]}
+        out = build_export(tracks, issues_by_track, {"o/r": "PRIVATE"}, now="t")
+        self.assertEqual(out["tracks"][0]["depends_on"], ["beta", "gamma"])
+
+    def test_depends_on_empty_by_default(self):
+        tracks = [_track("alpha", "o/r", [1])]
+        issues_by_track = {"alpha": [
+            {"number": 1, "title": "a", "state": "OPEN", "assignees": []},
+        ]}
+        out = build_export(tracks, issues_by_track, {"o/r": "PRIVATE"}, now="t")
+        self.assertEqual(out["tracks"][0]["depends_on"], [])

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

@@ -72,12 +72,12 @@ class ExportRunJsonTest(unittest.TestCase):
         self.assertEqual(out["schema"], 1)
 
     def test_track_issues_assembled_in_declared_order(self):
-        # Track declares [2, 1] — output order must match declaration, not map-insertion order
+        # Issues are milestone-sorted (#101): null-milestone group sorts by number.
         tracks = [_track("alpha", _SHARED_REPO, [2, 1])]
         rc, out, _ = self._run_with_mocks(tracks, _EXPORT_MAP)
         self.assertEqual(rc, 0)
         issue_nums = [i["number"] for i in out["tracks"][0]["issues"]]
-        self.assertEqual(issue_nums, [2, 1])
+        self.assertEqual(issue_nums, [1, 2])
 
     def test_shared_issue_appears_in_both_tracks(self):
         tracks = [

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

@@ -207,28 +207,66 @@ class FetchIssuesConcurrentTest(unittest.TestCase):
 
 
 class FetchIssuesAfterRefactorTest(unittest.TestCase):
-    """Verify fetch_issues still returns the sequential list after refactor."""
+    """Verify fetch_issues uses batched GraphQL + per-issue fallback."""
 
-    @patch("lib.github_state.subprocess.run")
-    def test_returns_list_in_order(self, mock_run):
-        responses = [
-            MagicMock(returncode=0, stdout='{"number": 10, "state": "OPEN", "labels": [], "title": "a"}'),
-            MagicMock(returncode=0, stdout='{"number": 20, "state": "CLOSED", "labels": [], "title": "b"}'),
+    @patch("lib.github_state.fetch_repo_issues_graphql")
+    @patch("lib.github_state.fetch_issue")
+    def test_gql_returns_all_no_fallback(self, mock_fetch_issue, mock_gql):
+        """When GraphQL returns every number, no fallback calls needed."""
+        mock_gql.return_value = {
+            10: {"number": 10, "state": "OPEN", "labels": [], "title": "a"},
+            20: {"number": 20, "state": "CLOSED", "labels": [], "title": "b"},
+        }
+        result = fetch_issues("org/repo", [10, 20])
+        self.assertEqual(len(result), 2)
+        self.assertEqual(result[0]["number"], 10)
+        self.assertEqual(result[1]["number"], 20)
+        mock_fetch_issue.assert_not_called()
+
+    @patch("lib.github_state.fetch_repo_issues_graphql")
+    @patch("lib.github_state.fetch_issue")
+    def test_gql_partial_falls_back(self, mock_fetch_issue, mock_gql):
+        """Numbers missing from GraphQL → per-issue fallback for each."""
+        mock_gql.return_value = {
+            10: {"number": 10, "state": "OPEN", "labels": []},
+        }
+        mock_fetch_issue.side_effect = [
+            None,  # 20 not found via fallback
+            {"number": 30, "state": "OPEN", "labels": []},
+        ]
+        result = fetch_issues("org/repo", [10, 20, 30])
+        # 10 from GQL, 20 fallback returns None (no side_effect entry), 30 from fallback
+        self.assertEqual(len(result), 2)
+        self.assertEqual(result[0]["number"], 10)
+        self.assertEqual(result[1]["number"], 30)
+        # fetch_issue called for 20 and 30 (only numbers not in GQL)
+        self.assertEqual(mock_fetch_issue.call_count, 2)
+
+    @patch("lib.github_state.fetch_repo_issues_graphql")
+    @patch("lib.github_state.fetch_issue")
+    def test_gql_empty_falls_back_completely(self, mock_fetch_issue, mock_gql):
+        """Empty GraphQL result → all numbers go to per-issue fallback."""
+        mock_gql.return_value = {}
+        mock_fetch_issue.side_effect = [
+            {"number": 10, "state": "OPEN", "labels": []},
+            {"number": 20, "state": "CLOSED", "labels": []},
         ]
-        mock_run.side_effect = responses
         result = fetch_issues("org/repo", [10, 20])
         self.assertEqual(len(result), 2)
         self.assertEqual(result[0]["number"], 10)
         self.assertEqual(result[1]["number"], 20)
+        self.assertEqual(mock_fetch_issue.call_count, 2)
 
-    @patch("lib.github_state.subprocess.run")
-    def test_skips_failed_fetches(self, mock_run):
-        responses = [
-            MagicMock(returncode=0, stdout='{"number": 10, "state": "OPEN", "labels": []}'),
-            MagicMock(returncode=1, stdout="", stderr="not found"),
-            MagicMock(returncode=0, stdout='{"number": 30, "state": "OPEN", "labels": []}'),
+    @patch("lib.github_state.fetch_repo_issues_graphql")
+    @patch("lib.github_state.fetch_issue")
+    def test_skips_failed_fallbacks(self, mock_fetch_issue, mock_gql):
+        """Per-issue fallback returning None → skipped silently."""
+        mock_gql.return_value = {}
+        mock_fetch_issue.side_effect = [
+            {"number": 10, "state": "OPEN", "labels": []},
+            None,  # number 20 failed
+            {"number": 30, "state": "OPEN", "labels": []},
         ]
-        mock_run.side_effect = responses
         result = fetch_issues("org/repo", [10, 20, 30])
         self.assertEqual(len(result), 2)
         self.assertEqual(result[0]["number"], 10)

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

@@ -343,6 +343,69 @@ class GroupApplyTierRoutingTest(unittest.TestCase):
             stored = json.loads(batch_file.read_text())
             self.assertFalse(stored.get("private"))
 
+    def test_limit_truncates_issue_display(self):
+        """--limit truncates displayed issues in the AI prompt with remaining count."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            notes_root = Path(tmpdir) / "notes"
+            notes_root.mkdir()
+            cfg = _make_cfg(notes_root=str(notes_root))
+            batch_file = Path(tmpdir) / "groups.json"
+
+            issues = [
+                {"number": i, "title": f"Issue {i}", "milestone": None,
+                 "labels": [], "assignees": [], "state": "OPEN"}
+                for i in range(1, 25)
+            ]
+
+            with patch("commands.group.load_config", return_value=cfg), \
+                 patch("commands.group._batch_path", return_value=batch_file), \
+                 patch("commands.group._answers_path",
+                       return_value=Path(tmpdir) / "groups.answers.json"), \
+                 patch("subprocess.run") as mock_run:
+                mock_run.return_value = MagicMock(
+                    returncode=0, stdout=json.dumps(issues), stderr=""
+                )
+                buf = io.StringIO()
+                with redirect_stdout(buf):
+                    rc = group.run(["--repo=myrepo", "--limit=10"])
+
+            self.assertEqual(rc, 0)
+            out = buf.getvalue()
+            self.assertIn("Issue 1", out)
+            self.assertIn("Issue 10", out)
+            self.assertNotIn("Issue 11", out)
+            self.assertIn("and 14 more", out)
+            self.assertIn("--limit", out)
+
+    def test_limit_at_or_below_count_shows_all_no_truncation(self):
+        """When issue count is within --limit, no truncation message appears."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            notes_root = Path(tmpdir) / "notes"
+            notes_root.mkdir()
+            cfg = _make_cfg(notes_root=str(notes_root))
+            batch_file = Path(tmpdir) / "groups.json"
+
+            issues = [
+                {"number": 1, "title": "Issue 1", "milestone": None,
+                 "labels": [], "assignees": [], "state": "OPEN"},
+            ]
+
+            with patch("commands.group.load_config", return_value=cfg), \
+                 patch("commands.group._batch_path", return_value=batch_file), \
+                 patch("commands.group._answers_path",
+                       return_value=Path(tmpdir) / "groups.answers.json"), \
+                 patch("subprocess.run") as mock_run:
+                mock_run.return_value = MagicMock(
+                    returncode=0, stdout=json.dumps(issues), stderr=""
+                )
+                buf = io.StringIO()
+                with redirect_stdout(buf):
+                    rc = group.run(["--repo=myrepo"])
+
+            self.assertEqual(rc, 0)
+            out = buf.getvalue()
+            self.assertNotIn("more issues", out)
+
 
 if __name__ == "__main__":
     unittest.main()

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

@@ -308,7 +308,7 @@ class NewTrackCommandTest(unittest.TestCase):
         self.assertEqual(rc, 0)
         meta = mw.call_args[0][1]
         for key in ("track", "status", "launch_priority", "milestone_alignment",
-                    "github", "related_tracks", "last_touched", "last_handoff",
+                    "github", "depends_on", "last_touched", "last_handoff",
                     "next_up", "blockers"):
             self.assertIn(key, meta, f"meta missing key: {key}")
 
@@ -320,12 +320,12 @@ class NewTrackCommandTest(unittest.TestCase):
         self.assertEqual(meta["github"]["issues"], [])
         self.assertEqual(meta["github"]["branches"], [])
 
-    def test_meta_related_tracks_next_up_blockers_empty(self):
-        """New track starts with empty related_tracks, next_up, blockers."""
+    def test_meta_depends_on_next_up_blockers_empty(self):
+        """New track starts with empty depends_on, next_up, blockers."""
         rc, mw, out = _drive(["myrepo", "my-feature"], vis="PRIVATE")
         self.assertEqual(rc, 0)
         meta = mw.call_args[0][1]
-        self.assertEqual(meta["related_tracks"], [])
+        self.assertEqual(meta["depends_on"], [])
         self.assertEqual(meta["next_up"], [])
         self.assertEqual(meta["blockers"], [])
 

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

@@ -378,5 +378,140 @@ class WhereWasINoSessionLogCase(unittest.TestCase):
         self.assertIn("Last session: (none yet)", out)
 
 
+class OrientRepoFlagTest(unittest.TestCase):
+    """orient command --repo=<key> and track@repo disambiguation."""
+
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.notes_root = Path(self.tmp.name) / "notes_root"
+        self.notes_root.mkdir(parents=True)
+        # Create two tracks with the same slug in different repos
+        for folder in ("repo-a", "repo-b"):
+            repo_dir = self.notes_root / folder
+            repo_dir.mkdir(parents=True)
+            _make_track_file(repo_dir, slug="feat-x")
+
+        self.cfg = {
+            "notes_root": str(self.notes_root),
+            "repos": {
+                "repo-a": {"github": "org/repo-a"},
+                "repo-b": {"github": "org/repo-b"},
+            },
+        }
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def _drive(self, args, *, find_result=None):
+        """Drive orient.run() with load_config mocked. If find_result is None
+        (the normal case), discover_tracks runs for real against tmp files.
+        When find_result is an Exception, we mock find_track_by_name."""
+        patches = [
+            mock.patch("commands.where_was_i.load_config", return_value=self.cfg),
+            mock.patch("commands.where_was_i.fetch_issues", return_value=[]),
+            mock.patch("commands.where_was_i.find_new_issues_for_tracks",
+                       return_value={}),
+            mock.patch("commands.where_was_i.current_branch", return_value=None),
+            mock.patch("commands.where_was_i.commits_ahead", return_value=0),
+            mock.patch("commands.where_was_i.uncommitted_file_count", return_value=0),
+        ]
+        if find_result is not None:
+            patches.append(
+                mock.patch("commands.where_was_i.find_track_by_name",
+                           side_effect=find_result
+                           if isinstance(find_result, Exception)
+                           else None,
+                           return_value=find_result
+                           if not isinstance(find_result, Exception)
+                           else None)
+            )
+
+        for p in patches:
+            p.start()
+
+        try:
+            buf = io.StringIO()
+            with redirect_stdout(buf):
+                rc = where_was_i.run(args)
+            return rc, buf.getvalue()
+        finally:
+            for p in patches:
+                p.stop()
+
+    def test_repo_flag_passed_to_find_track(self):
+        """--repo=<key> is passed as repo= kwarg to find_track_by_name."""
+        find_mock = mock.MagicMock()
+        find_mock.return_value = None  # We just care about how it was called
+
+        patches = [
+            mock.patch("commands.where_was_i.load_config", return_value=self.cfg),
+            mock.patch("commands.where_was_i.find_track_by_name", find_mock),
+            mock.patch("commands.where_was_i.discover_tracks", return_value=[]),
+            mock.patch("commands.where_was_i.fetch_issues", return_value=[]),
+            mock.patch("commands.where_was_i.find_new_issues_for_tracks",
+                       return_value={}),
+            mock.patch("commands.where_was_i.current_branch", return_value=None),
+            mock.patch("commands.where_was_i.commits_ahead", return_value=0),
+            mock.patch("commands.where_was_i.uncommitted_file_count", return_value=0),
+        ]
+        for p in patches:
+            p.start()
+        try:
+            buf = io.StringIO()
+            with redirect_stdout(buf):
+                where_was_i.run(["feat-x", "--repo=repo-a"])
+        finally:
+            for p in patches:
+                p.stop()
+
+        call_kwargs = find_mock.call_args.kwargs
+        self.assertEqual(call_kwargs.get("repo"), "repo-a")
+
+    def test_at_syntax_passed_to_find_track(self):
+        """feat-x@repo-a positional → repo='repo-a' passed to find_track_by_name."""
+        find_mock = mock.MagicMock()
+        find_mock.return_value = None
+
+        patches = [
+            mock.patch("commands.where_was_i.load_config", return_value=self.cfg),
+            mock.patch("commands.where_was_i.find_track_by_name", find_mock),
+            mock.patch("commands.where_was_i.discover_tracks", return_value=[]),
+            mock.patch("commands.where_was_i.fetch_issues", return_value=[]),
+            mock.patch("commands.where_was_i.find_new_issues_for_tracks",
+                       return_value={}),
+            mock.patch("commands.where_was_i.current_branch", return_value=None),
+            mock.patch("commands.where_was_i.commits_ahead", return_value=0),
+            mock.patch("commands.where_was_i.uncommitted_file_count", return_value=0),
+        ]
+        for p in patches:
+            p.start()
+        try:
+            buf = io.StringIO()
+            with redirect_stdout(buf):
+                where_was_i.run(["feat-x@repo-a"])
+        finally:
+            for p in patches:
+                p.stop()
+
+        call_kwargs = find_mock.call_args.kwargs
+        self.assertEqual(call_kwargs.get("repo"), "repo-a")
+
+    def test_ambiguous_error_returns_rc1(self):
+        """AmbiguousTrackError → prints message, returns 1."""
+        from lib.tracks import Track, AmbiguousTrackError
+
+        t1 = Track(path=Path("/tmp/fake/repo-a/feat-x.md"), name="feat-x",
+                   has_frontmatter=True, needs_init=False, needs_filing=False,
+                   repo="org/a", folder="repo-a", meta={"track": "feat-x", "status": "active"})
+        t2 = Track(path=Path("/tmp/fake/repo-b/feat-x.md"), name="feat-x",
+                   has_frontmatter=True, needs_init=False, needs_filing=False,
+                   repo="org/b", folder="repo-b", meta={"track": "feat-x", "status": "active"})
+        err = AmbiguousTrackError("feat-x", [t1, t2])
+
+        rc, out = self._drive(["feat-x"], find_result=err)
+        self.assertEqual(rc, 1)
+        self.assertIn("ambiguous", out.lower())
+
+
 if __name__ == "__main__":
     unittest.main()

package/skills/work-plan/work_plan.py

@@ -32,6 +32,7 @@ SUBCOMMANDS = {
     "--orient": "commands.where_was_i",   # flag-style alias
     "slot": "commands.slot",
     "batch-slot": "commands.batch_slot",
+    "move": "commands.move",
     "close": "commands.close",
     "refresh-md": "commands.refresh_md",
     "list": "commands.list_cmd",
@@ -65,8 +66,8 @@ DESCRIPTIONS = [
      "Wrap up a session: capture touched/next/blockers, update body status table. Use --set-next to set the next_up list explicitly. Use --auto-next to suggest a priority-sorted list from open issues (interactive: apply / edit / skip).",
      "Ending a work block — before stepping away, going to bed, or switching tracks. Use --auto-next when you don't want to hand-pick issue numbers.",
      "/work-plan handoff tabletop --auto-next"),
-    ("where-was-i", "[track] [--pick]",
-     "Re-orient. With a track name: track paste-block. With no args: cwd snapshot (branch, recent commits, modified files). Add --pick to force the interactive track picker.",
+    ("where-was-i", "[track | track@repo] [--pick] [--repo=<key>]",
+     "Re-orient. With a track name: track paste-block. With no args: cwd snapshot (branch, recent commits, modified files). Add --pick to force the interactive track picker. Use --repo=<key> or track@repo to disambiguate when the same track slug exists in multiple repos.",
      "Switching to a fresh Claude Code session — either on a known track or in a directory that doesn't yet belong to one.",
      "/work-plan where-was-i ux-redesign  (or just `/work-plan orient` for cwd snapshot)"),
     ("slot", "<issue-num> [track | track@repo] [--repo=<key>]",
@@ -77,6 +78,10 @@ DESCRIPTIONS = [
      "Slot multiple GitHub issues into a track at once. The last positional argument is the track; everything before it is an issue number. Skips issues already in the track. Use --move to remove issues from any prior owning tracks.",
      "After bulk-triage with auto-triage or group — when several issues need the same track assignment.",
      "/work-plan batch-slot 100 101 102 tabletop --move"),
+    ("move", "<issue-num> <from-track> <to-track> [--repo=<key>]",
+     "Move an issue from one track to another (remove from source frontmatter, add to destination). Source-first — the verb is the intent. Both tracks must be active and in the same repo.",
+     "When an issue belongs in a different track than where it currently sits — cleaner than slot --move.",
+     "/work-plan move 4234 platform-health org-sharing"),
     ("close", "<track | track@repo> [--repo=<key>]",
      "Retire a track: shipped / parked / abandoned. Moves to archive/. Use --repo=<key> or track@repo to disambiguate when the same track slug exists in multiple repos.",
      "When a track is done, paused, or won't ship — frees mental space.",
@@ -101,12 +106,12 @@ DESCRIPTIONS = [
      "AI-assisted batch backfill of priority/PN labels.",
      "ONE-TIME setup, or whenever a wave of new unlabeled issues piles up.",
      "/work-plan suggest-priorities --repo=myproject"),
-    ("group", "[--milestone=X] [--label=Y] [--repo=Z] [--apply]",
-     "AI-cluster GitHub issues into thematic track files.",
+    ("group", "[--milestone=X] [--label=Y] [--repo=Z] [--apply] [--limit=N]",
+     "AI-cluster GitHub issues into thematic track files. --limit controls how many issues are shown in the prompt (default 100).",
      "ONE-TIME bulk organization of an unsorted milestone, or after a re-org.",
      "/work-plan group --milestone='v1.0.0 — Public Launch'"),
-    ("auto-triage", "[--repo=<key>] [--apply]",
-     "AI-assign untracked open issues to existing tracks. Step 1 (no --apply): fetches untracked issues + existing tracks, prints AI prompt. Step 2 (--apply): reads AI's JSON answers and slots each assignment into track frontmatter. Complements `group` (which creates new tracks); `auto-triage` assigns to tracks that already exist.",
+    ("auto-triage", "[--repo=<key>] [--apply] [--limit=N]",
+     "AI-assign untracked open issues to existing tracks. Step 1 (no --apply): fetches untracked issues + existing tracks, prints AI prompt. Step 2 (--apply): reads AI's JSON answers and slots each assignment into track frontmatter. Complements `group` (which creates new tracks); `auto-triage` assigns to tracks that already exist. --limit controls how many untracked issues are shown (default 100).",
      "Periodically — when new issues have piled up outside the track model. Run /work-plan coverage first to confirm there's a gap worth triaging.",
      "/work-plan auto-triage --repo=critforge"),
     ("reconcile", "<track> | --all | --repo=<key> [--draft]",