@stylusnexus/work-plan 2026.6.9

package/skills/work-plan/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: work-plan
+description: Use when starting or ending a work session across many GitHub issues, switching between parallel agent sessions on different workstreams, re-orienting on what to do next, sweeping for stale tracking state, or bootstrapping a new repo into a daily-planning system.
+argument-hint: "[brief|handoff|orient|reconcile|hygiene|--help]"
+---
+
+# Work Plan
+
+Track-aware daily planner. Each "track" is a YAML-frontmattered markdown file that references GitHub issues by ID; the CLI derives state live from `gh`/`git`. Composes with `/repo-activity-summary` for the global multi-repo view.
+
+## Subcommand reference
+
+| Subcommand | When |
+|---|---|
+| `/work-plan brief` | Starting work or after a gap. Multi-track snapshot. |
+| `/work-plan handoff [track] [--auto-next \| --set-next 1,2,3]` | Wrapping up a work block. Captures touched + next + blockers; writes session log. Add `--auto-next` to suggest a priority-sorted next_up list from open issues (interactive: apply / edit / skip). Tracks with `next_up_auto: true` in frontmatter get the auto-derived list surfaced in `brief` automatically. |
+| `/work-plan orient [track]` (alias `where-was-i`) | Re-orienting. With a track: ~15-line track paste-block. Without: cwd snapshot (branch, recent commits, modified files) for non-track work. Add `--pick` for the interactive track picker. |
+| `/work-plan hygiene` | Weekly all-in-one cleanup: refresh-md --all + reconcile --all + duplicates. |
+| `/work-plan slot <issue-num> [track]` | A new GitHub issue should belong to a track. If the issue is already listed in another active track's frontmatter, you'll be prompted to move it (remove from source) instead of duplicating. |
+| `/work-plan close [track]` | Track is done (shipped) / paused (parked) / won't ship (abandoned). |
+| `/work-plan refresh-md <track> \| --all` | Status icons drifted from GitHub state. **You usually don't need to call this directly:** `handoff` already rewrites the body table for its own track on every run, and `brief` reads GitHub live. Reach for `refresh-md` (or `--all`) when a sibling track has drifted because you haven't `handoff`'d it lately. |
+| `/work-plan list [--all]` | List active tracks (or all including parked/archived). |
+| `/work-plan init <path>` | Add frontmatter to a new track .md file. |
+| `/work-plan init-repo <key> [--github=<slug>] [--local=<path>]` | Bootstrap a new repo: create `<notes_root>/<key>/archive/{shipped,abandoned}/` and add the repo block to your config. |
+| `/work-plan suggest-priorities --repo=<key>` | Two-step AI label backfill (one-time migration). |
+| `/work-plan group [--milestone=X] [--label=Y] [--repo=Z]` | Two-step AI clustering: turn a flat list of issues into thematic track files. |
+| `/work-plan reconcile <track> \| --all [--draft]` | Sync track frontmatter with GitHub labels (read-only on GitHub). Default label is `track/<slug>`; override per-track via `github.labels` in frontmatter. Add `--draft` to preview proposed ADDs/FLAGs without prompting or writing. |
+| `/work-plan duplicates [--min-similarity=0.7]` | Find likely-duplicate issues by title similarity (stdlib difflib). |
+| `/work-plan plan-status [--repo=<key>] [--stamp [--draft]] [--type=plan\|spec]` | **Doc/plan liveness.** "Which of my plan/spec docs actually shipped, half-shipped, or died?" Correlates each plan's declared file-manifest (Create/Modify/Test paths) against git + filesystem — not the unreliable checkboxes. Reports ✅ shipped / 🟡 partial / 💀 dead / 👻 manifest-less. Read-only by default; `--stamp` writes an idempotent status header into each doc (`--draft` previews, writes nothing). Natural-language triggers: "what's done vs unfinished in `<repo>`", "stamp the plan statuses", "which plans are stale/dead". |
+
+## How to invoke
+
+All subcommands route through the Python CLI. Prefer the `work-plan` launcher (on
+PATH as a plugin, and installed by `install.sh`): `work-plan <subcommand>`. It
+resolves `work_plan.py` relative to itself, then via `${CLAUDE_PLUGIN_ROOT}` /
+`${PLUGIN_ROOT}` / `~/.claude` / `~/.agents`. If the launcher isn't on PATH, call
+the CLI directly, first match wins:
+
+1. `${CLAUDE_PLUGIN_ROOT}/skills/work-plan/work_plan.py` (Claude plugin; Codex sets this too)
+2. `${PLUGIN_ROOT}/skills/work-plan/work_plan.py` (Codex plugin)
+3. `~/.claude/skills/work-plan/work_plan.py` (install.sh → Claude Code)
+4. `~/.agents/skills/work-plan/work_plan.py` (install.sh → Codex)
+
+Run via Bash. Don't reimplement the logic in chat.
+
+## Verbatim relay (orientation subcommands)
+
+For `brief`, `handoff`, `orient` (`where-was-i`), and `hygiene`, the Python output IS the deliverable. After running the Bash command, **reproduce the full Python output verbatim in a fenced code block in your chat reply.** Don't summarize, paraphrase, or truncate — users copy-paste from chat into other terminals/sessions, so any rewording loses information.
+
+`plan-status` is also verbatim-relay, with one exception: its report can run to hundreds of docs. If the output is large, relay the headline line (counts + lie-gap) and the actionable **🟡 partial** bucket verbatim, then offer the full report rather than flooding the chat. The `--stamp`/`--draft` summary line (`stamped N doc(s)` / `would stamp N doc(s)`) is always relayed verbatim.
+
+## Handoff: Claude-driven `next_up`
+
+After running `handoff`:
+
+1. Read the output (open issues, last session log, priority, milestone).
+2. Survey the user's project memory (e.g., a `MEMORY.md` index in their working directory or `~/.claude/projects/.../memory/`) for related signals — deploy gates, blocked items, in-flight clusters.
+3. Pick a "next" — single ticket OR tight cluster (2-4 issues) — based on track priority, milestone, what's gating other work, what cluster naturally goes together.
+4. Justify the pick in chat (1-2 sentences).
+5. Persist via `python3 <skill-path>/work_plan.py handoff <track> --set-next <comma-list>` (e.g. `--set-next 4167,4148,4149`).
+6. Show the user what was set so they can override.
+
+## Two-step AI subcommands (`suggest-priorities`, `group`)
+
+Both are two-step:
+
+1. CLI fetches issues + writes prompt to terminal.
+2. **You** read the issues, output the requested JSON, save via Write tool to `~/.claude/work-plan/cache/priorities.answers.json` or `~/.claude/work-plan/cache/groups.answers.json`.
+3. Re-run with `--apply` to commit changes.
+
+Show the proposed labels/clusters BEFORE applying. The user may want to override.
+
+## Track ↔ GitHub label mapping
+
+By default, `reconcile` and the `brief` new-issue suggester look for the label `track/<slug>` on GitHub issues. If your repo uses a different scheme (flat labels like `storytelling`, namespaced labels like `area/maps`, or no `track/*` namespace at all), declare the labels per-track in the markdown frontmatter:
+
+```yaml
+---
+track: storytelling-enhancements
+status: active
+github:
+  repo: your-org/your-repo
+  labels: [storytelling, campaigns]   # OR semantics — issue matches if ANY label is present
+  issues: [4296, 4290, ...]
+---
+```
+
+This is read-only on GitHub: the skill never adds, removes, or rewrites labels on the remote — it only reads them to know which issues belong to a track. The only writes are to your local markdown frontmatter, gated behind interactive confirmation. If `github.labels` is omitted, the default `track/<slug>` pattern is used (existing setups keep working unchanged).
+
+## Track ↔ commit attribution
+
+`handoff` shows commits attributed to a track since the last handoff. Attribution rules (in order):
+
+1. **Explicit branches** — if frontmatter has `github.branches: [feature/x, ...]`, only commits on those branches count. Path globs do not apply.
+2. **Issue mention OR path glob** — otherwise, scan all branches and keep commits whose message (subject OR body) mentions an issue in `github.issues`, OR whose changed paths match any glob in `github.paths` (fnmatch syntax — `*`, `?`, `**`, `[seq]`). Scanning the body matters for squash-merged PRs whose subjects follow Conventional Commits (e.g. `feat(scope): description`) and carry the issue ref in the body (`Closes #1234`).
+
+```yaml
+github:
+  repo: your-org/your-repo
+  issues: [4148, 4149, ...]
+  paths:
+    - "apps/web/src/components/ux/**"
+    - "**/useToast*"
+```
+
+When zero commits attribute to the track but the repo has activity in the same window, the handoff renders a soft signal (`0 attributed / N repo-wide since last handoff`) so the silence isn't mistaken for "nothing happened."
+
+## Setup
+
+Run `./install.sh` (macOS / Linux / WSL) or `.\install.ps1` (Windows) from the toolkit root. Then `/work-plan init-repo <key> --github=<org/repo>` to bootstrap your first repo. See the toolkit README for full setup, requirements, and platform-specific install commands.
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Calling `gh` directly to check issue state | `brief` / `orient` already do it, with track context. |
+| Editing track frontmatter manually | Prefer `handoff` or `slot` — they update timestamps and dedupe. |
+| Forgetting to label issues with `priority/PN` | `brief` sorts by priority; without labels everything looks the same. |
+| Setting `local:` in config to a path that doesn't exist | In-progress detection silently no-ops. Verify path. |

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

@@ -0,0 +1,247 @@
+"""brief subcommand — fully featured."""
+from datetime import datetime
+from pathlib import Path
+
+from lib.config import load_config, ConfigError
+from lib.tracks import discover_tracks, discover_archived_tracks, filter_tracks_by_repo
+from lib.github_state import fetch_issues, extract_priority, short_milestone
+from lib.prompts import parse_flags
+from lib.git_state import (
+    parse_iso_timestamp, gap_seconds_to_label,
+    branch_in_progress, commits_ahead, uncommitted_file_count, current_branch,
+)
+from lib.closure import compute_signals, is_closure_ready
+from lib.new_issues import build_slug_labels, find_new_issues_for_tracks
+from lib.next_up import suggest_next_up
+from lib.drift import detect_drift
+from lib.render import time_aware_framing, render_track_row, render_archived_reopen
+
+
+def run(args: list[str]) -> int:
+    flags, _ = parse_flags(args, {"--repo"})
+    repo_key = flags.get("--repo")
+    if repo_key is True:
+        print("usage: work_plan.py brief [--repo=<key>]")
+        return 2
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}", flush=True)
+        return 1
+
+    tracks = discover_tracks(cfg)
+    if repo_key:
+        scoped = filter_tracks_by_repo(tracks, repo_key)
+        if not scoped:
+            print(f"No tracks found for repo '{repo_key}'.")
+            available = sorted((cfg.get("repos") or {}).keys())
+            if available:
+                print(f"Configured repo keys: {', '.join(available)}")
+            return 0
+        tracks = scoped
+    active = [t for t in tracks if t.has_frontmatter
+              and t.meta.get("status") in ("active", "in-progress", "blocked")]
+
+    if not active and not tracks:
+        print("No tracks found.")
+        return 0
+
+    now = datetime.now()
+    most_recent = max(
+        (parse_iso_timestamp(t.meta["last_touched"]) for t in active if t.meta.get("last_touched")),
+        default=None,
+    )
+    gap = int((now - most_recent).total_seconds()) if most_recent else 999999
+    handoff_today = any(
+        t.meta.get("last_handoff", "").startswith(now.strftime("%Y-%m-%d")) for t in active
+    )
+    framing = time_aware_framing(gap, now.hour, handoff_today)
+
+    print(f"DAILY BRIEF — {now.strftime('%Y-%m-%d %H:%M')} (gap: {gap_seconds_to_label(gap)})")
+    print()
+    print(framing)
+    print()
+
+    blocks = []
+    for t in active:
+        b = _build_track_block(t, cfg, now)
+        blocks.append((b["sort_key"], b))
+
+    blocks.sort(key=lambda x: x[0])
+    for _, block in blocks:
+        print(render_track_row(block))
+        print()
+
+    needs_init = [t for t in tracks if t.needs_init]
+    needs_filing = [t for t in tracks if t.needs_filing]
+    if needs_init or needs_filing:
+        print("--- Setup needed ---")
+        for t in needs_init:
+            print(f"  needs init:   {t.path}  → /work-plan init '{t.path}'")
+        for t in needs_filing:
+            print(f"  needs filing: {t.path}  → move into a repo subfolder")
+        print()
+
+    _surface_archived_reopens(cfg, repo_key=repo_key)
+
+    n_active = len(active)
+    n_in_progress = sum(1 for _, b in blocks if b["operational_status"] == "in-progress")
+    n_closure = sum(1 for _, b in blocks if b["closure_ready"])
+    n_drift = sum(1 for _, b in blocks if b["drift_items"])
+    n_new = sum(len(b["new_issues"]) for _, b in blocks)
+    print(f"{n_active} active tracks. "
+          f"{n_in_progress} in-progress. {n_closure} closure-ready. "
+          f"{n_drift} with drift. {n_new} new issues to slot.")
+
+    return 0
+
+
+def _build_track_block(track, cfg, now: datetime) -> dict:
+    meta = track.meta
+    repo = track.repo
+    local = track.local_path
+
+    issue_nums = meta.get("github", {}).get("issues") or []
+    stored_next_up = meta.get("next_up") or []
+    # Fetch state for stored next_up issues even if they're not in github.issues,
+    # so stale closed entries surface as a clear signal rather than vanishing.
+    fetch_nums = sorted(set(issue_nums) | set(stored_next_up))
+    issues = fetch_issues(repo, fetch_nums) if (repo and fetch_nums) else []
+    issues_by_num = {i["number"]: i for i in issues}
+
+    # When `next_up_auto: true` is set in track frontmatter, derive the list
+    # live from open issues (priority-sorted, blockers excluded) instead of
+    # reading the stored `next_up`. The track's persisted list is ignored
+    # for display purposes — useful for tracks where you don't want to
+    # hand-curate but still want a sensible "what's next" surfaced.
+    track_milestone = meta.get("milestone_alignment") or None
+    if meta.get("next_up_auto") and issues:
+        blocker_nums = meta.get("blockers") or []
+        next_up_nums = suggest_next_up(issues, blocker_nums, track_milestone=track_milestone)
+    else:
+        next_up_nums = stored_next_up
+
+    next_up_items = []
+    next_up_closed_count = 0
+    for num in next_up_nums:
+        i = issues_by_num.get(num)
+        if not i:
+            continue
+        state = (i.get("state") or "").upper()
+        if state in ("CLOSED", "MERGED"):
+            next_up_closed_count += 1
+            continue
+        next_up_items.append({
+            "number": num, "title": i.get("title", ""),
+            "priority": extract_priority(i.get("labels", [])),
+            "state": state.lower() or "open",
+            "milestone": short_milestone(i.get("milestone")),
+        })
+
+    branch_names = meta.get("github", {}).get("branches") or []
+    active_branches = []
+    branch_in_prog = False
+    for bn in branch_names:
+        in_prog = branch_in_progress(bn, local)
+        if in_prog:
+            branch_in_prog = True
+        active_branches.append({
+            "name": bn,
+            "ahead": commits_ahead(bn, "dev", local) if local else 0,
+            "uncommitted_files": (
+                uncommitted_file_count(local)
+                if local and current_branch(local) == bn else 0
+            ),
+        })
+
+    stored_status = meta.get("status", "active")
+    if stored_status == "active" and branch_in_prog:
+        operational_status = "in-progress"
+    else:
+        operational_status = stored_status
+
+    track_slug = meta.get("track", track.name)
+    slug_labels = build_slug_labels([track])
+    new_issues_map = find_new_issues_for_tracks(repo, [track_slug], slug_labels=slug_labels, since_days=7) if repo else {}
+    listed_set = set(issue_nums)
+    new_issues = []
+    for issue in new_issues_map.get(track_slug, []):
+        if issue["number"] in listed_set:
+            continue
+        new_issues.append({"number": issue["number"], "title": issue["title"]})
+
+    drift_items = detect_drift(track.body, issues) if issues else []
+
+    related_recent_count = len(new_issues_map.get(track_slug, []))
+    signals = compute_signals(meta, issues, local, related_recent_count)
+    closure_ready, _ = is_closure_ready(signals)
+    if closure_ready:
+        closure_signals_summary = None
+    else:
+        green = sum([signals.all_issues_closed, signals.all_branches_done,
+                     signals.next_up_empty, signals.cold_14d, signals.no_recent_related_issues])
+        closure_signals_summary = f"{green}/5 signals green"
+
+    blockers = [{"number": bn, "reason": "manually flagged"}
+                for bn in (meta.get("blockers") or [])]
+
+    def lbl(key):
+        if not meta.get(key):
+            return "?"
+        gs = (now - parse_iso_timestamp(meta[key])).total_seconds()
+        return gap_seconds_to_label(int(gs))
+
+    in_prog_rank = 0 if operational_status == "in-progress" else 1
+    pri_rank = {"P0": 0, "P1": 1, "P2": 2, "P3": 3}.get(meta.get("launch_priority", "P3"), 3)
+    recency_key = (
+        -parse_iso_timestamp(meta["last_touched"]).timestamp()
+        if meta.get("last_touched") else 0
+    )
+
+    return {
+        "name": meta.get("track", track.name),
+        "operational_status": operational_status,
+        "launch_priority": meta.get("launch_priority", "P3"),
+        "milestone_alignment": meta.get("milestone_alignment", "—"),
+        "last_touched_label": lbl("last_touched"),
+        "last_handoff_label": lbl("last_handoff"),
+        "next_up": next_up_items,
+        "next_up_stale_closed_count": (
+            next_up_closed_count if not next_up_items and next_up_nums else 0
+        ),
+        "track_slug": meta.get("track", track.name),
+        "active_branches": active_branches,
+        "new_issues": new_issues,
+        "blockers": blockers,
+        "drift_items": drift_items,
+        "closure_ready": closure_ready,
+        "closure_signals_summary": closure_signals_summary,
+        "archived_reopen": [],
+        "sort_key": (in_prog_rank, pri_rank, recency_key),
+    }
+
+
+def _surface_archived_reopens(cfg: dict, repo_key: str = None) -> None:
+    archived = discover_archived_tracks(cfg)
+    if repo_key:
+        archived = filter_tracks_by_repo(archived, repo_key)
+    if not archived:
+        return
+    by_repo: dict[str, list] = {}
+    for a in archived:
+        if a.repo:
+            by_repo.setdefault(a.repo, []).append(a)
+    callouts = []
+    for repo, tracks_in_repo in by_repo.items():
+        slugs = [a.meta.get("track", a.name) for a in tracks_in_repo]
+        slug_labels = build_slug_labels(tracks_in_repo)
+        new_map = find_new_issues_for_tracks(repo, slugs, slug_labels=slug_labels, since_days=14)
+        for slug, issues in new_map.items():
+            for issue in issues:
+                callouts.append((slug, issue))
+    if callouts:
+        print("--- Archived tracks with new activity ---")
+        for slug, issue in callouts:
+            print("  " + render_archived_reopen(repo, slug, issue))
+        print()

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

@@ -0,0 +1,122 @@
+"""canonicalize subcommand: add a canonical master issue table to a track.
+
+Generates one-row-per-issue table from frontmatter github.issues, with assignee
+and status columns. Inserts at top of body with a marker so refresh-md targets
+ONLY this table (skipping narrative tables in the existing body).
+
+Use --all to canonicalize every active track that doesn't yet have one.
+"""
+from lib.config import load_config, ConfigError
+from lib.tracks import discover_tracks, find_track_by_name
+from lib.github_state import fetch_issues, state_to_status_label, format_assignees
+from lib.frontmatter import write_file
+from lib.status_table import CANONICAL_MARKER, find_canonical_status_tables, render_issue_row
+from lib.prompts import parse_flags
+
+
+def run(args: list[str]) -> int:
+    flags, positional = parse_flags(args, {"--all", "--force"})
+    do_all = flags.get("--all", False)
+    force = flags.get("--force", False)
+    track_name = positional[0] if positional else None
+
+    if not do_all and not track_name:
+        print("usage: work_plan.py canonicalize <track-name> | --all  [--force]")
+        return 2
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        return 1
+
+    tracks = discover_tracks(cfg)
+
+    if do_all:
+        targets = [t for t in tracks if t.has_frontmatter
+                   and t.meta.get("status") in ("active", "in-progress", "blocked")]
+    else:
+        target = find_track_by_name(track_name, tracks, active_only=True)
+        if not target:
+            print(f"No active track matching '{track_name}'.")
+            return 1
+        targets = [target]
+
+    any_changes = False
+    for track in targets:
+        existing = find_canonical_status_tables(track.body)
+        if existing and not force:
+            print(f"  skip {track.name}: already has canonical table (use --force to replace)")
+            continue
+
+        issue_nums = track.meta.get("github", {}).get("issues") or []
+        if not issue_nums or not track.repo:
+            print(f"  skip {track.name}: no issues or repo")
+            continue
+
+        print(f"  fetching {len(issue_nums)} issue(s) for {track.name}...")
+        issues = fetch_issues(track.repo, issue_nums)
+        issues_by_num = {i["number"]: i for i in issues}
+
+        new_body = _insert_canonical_table(
+            track.body, issue_nums, issues_by_num, replace=force,
+        )
+        write_file(track.path, track.meta, new_body)
+        print(f"  ✓ {track.name}: canonical table added/refreshed ({len(issue_nums)} issues)")
+        any_changes = True
+
+    if not any_changes:
+        print("Nothing to do.")
+    return 0
+
+
+def _insert_canonical_table(body: str, issue_nums: list[int],
+                            issues_by_num: dict, replace: bool = False) -> str:
+    """Insert (or replace) a canonical table at the top of the body."""
+    table_md = _render_canonical_table(issue_nums, issues_by_num)
+
+    if replace:
+        # Strip existing canonical block (marker + heading + table + separator)
+        body = _strip_existing_canonical(body)
+
+    # Prepend table after any leading whitespace
+    body_stripped = body.lstrip("\n")
+    leading_whitespace = body[: len(body) - len(body_stripped)]
+    return leading_whitespace + table_md + "\n---\n\n" + body_stripped
+
+
+def _render_canonical_table(issue_nums: list[int], issues_by_num: dict) -> str:
+    lines = [
+        "## Issues (canonical)",
+        "",
+        f"{CANONICAL_MARKER} — auto-managed by /work-plan refresh-md. Don't edit by hand. -->",
+        "",
+        "| # | Title | Assignee | Status |",
+        "|---|---|---|---|",
+    ]
+    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)
+
+
+def _strip_existing_canonical(body: str) -> str:
+    """Remove an existing canonical-table block from the top of the body."""
+    if CANONICAL_MARKER not in body:
+        return body
+    # Find the start of the heading "## Issues (canonical)" if present, else the marker
+    heading_idx = body.find("## Issues (canonical)")
+    marker_idx = body.find(CANONICAL_MARKER)
+    start = heading_idx if 0 <= heading_idx < marker_idx else marker_idx
+    # Find end: the next "---\n" separator after the marker
+    sep_idx = body.find("\n---\n", marker_idx)
+    if sep_idx == -1:
+        # No separator — strip just the marker line
+        end = body.find("\n", marker_idx) + 1
+    else:
+        end = sep_idx + len("\n---\n")
+    return body[:start] + body[end:].lstrip("\n")

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

@@ -0,0 +1,83 @@
+"""close subcommand — non-interactive, flag-driven."""
+import json
+import shutil
+from pathlib import Path
+
+from lib.config import load_config, ConfigError
+from lib.tracks import discover_tracks, find_track_by_name
+from lib.frontmatter import write_file
+from lib.write_guard import needs_confirm, make_token, valid_token
+from lib.prompts import parse_flags
+
+VALID_STATES = {"shipped", "parked", "abandoned"}
+
+
+def run(args: list[str]) -> int:
+    # --confirm uses equals form: --confirm=<token>
+    # --state and --note also use equals form: --state=shipped, --note=...
+    flags, positional = parse_flags(args, {"--state", "--note", "--confirm"})
+
+    if not positional:
+        print("usage: work_plan.py close <track-name> --state=shipped|parked|abandoned [--note=<text>] [--confirm=<token>]")
+        return 2
+
+    track_name = positional[0]
+
+    # Validate --state (required)
+    end_state = flags.get("--state")
+    if not end_state or end_state not in VALID_STATES:
+        if not end_state:
+            print("ERROR: --state is required (shipped|parked|abandoned).")
+        else:
+            print(f"ERROR: --state={end_state!r} is not valid (allowed: abandoned, parked, shipped).")
+        return 2
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        return 1
+
+    tracks = discover_tracks(cfg)
+    track = find_track_by_name(track_name, tracks)
+    if not track:
+        print(f"No track matching '{track_name}'.")
+        return 1
+
+    # Public-repo confirm gate (the extension surfaces this as a modal).
+    # Placed after track resolution but before any write/move.
+    confirm = flags.get("--confirm")
+    if track.repo and needs_confirm(track.repo, cfg) and not (
+        isinstance(confirm, str) and valid_token(confirm, track.repo, track.name)
+    ):
+        print(json.dumps({
+            "needs_confirm": True,
+            "reason": (
+                f"{track.repo} is PUBLIC (or visibility unknown); "
+                f"closing '{track.name}' will be written there."
+            ),
+            "token": make_token(track.repo, track.name),
+        }))
+        return 0
+
+    # Apply state and optional wrap-up note.
+    track.meta["status"] = end_state
+    new_body = track.body
+    note = flags.get("--note")
+    if note and isinstance(note, str) and note.strip():
+        new_body += f"\n\n## Wrap-up\n\n{note}\n"
+
+    write_file(track.path, track.meta, new_body)
+
+    if end_state == "parked":
+        print(f"✓ '{track.name}' marked parked. Stays in place.")
+        return 0
+
+    notes_root = Path(cfg["notes_root"])
+    folder = track.path.parent
+    archive_dir = folder / "archive" / end_state
+    archive_dir.mkdir(parents=True, exist_ok=True)
+    dest = archive_dir / track.path.name
+    shutil.move(str(track.path), str(dest))
+    print(f"✓ '{track.name}' marked {end_state}, moved to {dest.relative_to(notes_root)}")
+    return 0