@stylusnexus/work-plan 2026.6.9

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

@@ -0,0 +1,296 @@
+"""plan-status — reach a verdict on every plan/spec doc in a repo by
+correlating each plan's declared file-manifest against the filesystem + git.
+
+Phase 1: read-only. Reports a human table or --json. Never mutates a doc.
+Manifest-less (prose) docs are flagged 👻 for the Phase 1b LLM pass.
+"""
+import json
+import sys
+from datetime import date
+from pathlib import Path
+
+from lib import config as config_mod
+from lib import doc_discovery, manifest, git_state, github_state
+from lib import verdict as verdict_mod
+from lib import status_header
+from lib import llm_evidence
+from lib import reconcile_actions
+from lib.scratch import cache_dir
+from lib.prompts import parse_flags, prompt_yes_no
+
+KNOWN = {"--repo", "--json", "--since-days", "--type", "--stamp", "--draft",
+         "--llm", "--apply", "--archive", "--issues"}
+_ORDER = ["shipped", "partial", "dead", "foreign", "manifest-less"]
+
+
+def _resolve_repo_root(flags) -> Path:
+    repo = flags.get("--repo")
+    if repo and repo is not True:
+        cfg = config_mod.load_config()
+        local = config_mod.resolve_local_path_for_folder(repo, cfg)
+        if not local or not local.exists():
+            print(f"repo '{repo}' has no resolvable local path in config", file=sys.stderr)
+            raise SystemExit(2)
+        return local
+    return Path.cwd()
+
+
+def _evaluate(doc, repo_root, today, dead_days) -> dict:
+    text = doc.path.read_text(encoding="utf-8", errors="replace")
+    decls = manifest.parse_declared_paths(text)
+    pdate = manifest.plan_date_from_filename(doc.path.name)
+    score = manifest.score_manifest(decls, repo_root, pdate)
+    done, total_chk = manifest.count_checkboxes(text)
+    last_dt = git_state.path_last_commit_date(doc.rel, repo_root)
+    last_d = last_dt.date() if last_dt else None
+    if decls and manifest.out_of_tree_ratio(decls, repo_root) >= verdict_mod.FOREIGN_RATIO:
+        v = verdict_mod.Verdict(
+            "foreign", "🧳", "declared paths point outside this repo — misfiled?")
+    else:
+        v = verdict_mod.classify(score, done, total_chk, last_d, today, dead_days)
+    return {
+        "rel": doc.rel, "kind": doc.kind,
+        "verdict": v.label, "glyph": v.glyph, "rationale": v.rationale,
+        "files_present": score.satisfied, "files_declared": score.total,
+        "checkboxes_done": done, "checkboxes_total": total_chk,
+        "last_touched": last_d.isoformat() if last_d else None,
+    }
+
+
+def _render(rows, repo_root) -> None:
+    print(f"# plan-status — {repo_root}\n")
+    by = {}
+    for r in rows:
+        by.setdefault(r["verdict"], []).append(r)
+    lie_gap = sum(
+        1 for r in rows
+        if r["verdict"] == "shipped" and r["checkboxes_total"]
+        and r["checkboxes_done"] / r["checkboxes_total"] < 0.25
+    )
+    summary = " · ".join(f"{len(by[k])} {k}" for k in _ORDER if by.get(k))
+    print(f"{len(rows)} docs · {summary}")
+    print(f"lie-gap (shipped but <25% boxes checked): {lie_gap}\n")
+    for k in _ORDER:
+        group = by.get(k)
+        if not group:
+            continue
+        glyph = group[0]["glyph"]
+        print(f"## {glyph} {k} ({len(group)})")
+        for r in sorted(group, key=lambda x: x["rel"]):
+            print(f"  {r['rel']}")
+            print(f"      {r['rationale']}")
+        print()
+
+
+def _stamp_docs(docs, rows, draft: bool) -> None:
+    changed = []
+    for doc, row in zip(docs, rows):
+        text = doc.path.read_text(encoding="utf-8", errors="replace")
+        new = status_header.stamp(text, row)
+        if new != text:
+            changed.append(doc.rel)
+            if not draft:
+                doc.path.write_text(new, encoding="utf-8")
+    verb = "would stamp" if draft else "stamped"
+    print(f"\n{verb} {len(changed)} doc(s):")
+    for rel in changed:
+        print(f"  {rel}")
+
+
+_LLM_VERDICTS = {"shipped", "partial", "dead"}
+_LLM_GLYPH = {"shipped": "✅", "partial": "🟡", "dead": "💀"}
+
+_LLM_PROMPT = """\
+You are judging whether each doc below represents work that SHIPPED, is PARTIAL
+(in progress), or is DEAD (abandoned). These are docs mechanical scoring could
+not resolve: prose specs with no file list, or plans whose files look absent.
+Use the title, kind, last-touched date, and excerpt. Return ONLY a JSON array:
+[{"rel": "...", "verdict": "shipped|partial|dead", "confidence": 0.0-1.0,
+  "rationale": "one short line"}]
+"""
+
+
+def _llm_prepare(docs, rows, repo_root) -> int:
+    by_rel = {d.rel: d for d in docs}
+    candidates = llm_evidence.select_candidates(rows)
+    if not candidates:
+        print("No docs need an LLM verdict — mechanical scoring resolved them all.")
+        return 0
+    evidence = [llm_evidence.gather_evidence(by_rel[r["rel"]], repo_root)
+                for r in candidates if r["rel"] in by_rel]
+    batch_path = cache_dir() / "plan_status.json"
+    batch_path.write_text(
+        json.dumps({"repo_root": str(repo_root), "docs": evidence}, indent=2))
+    answers_path = batch_path.with_suffix(".answers.json")
+    print(f"Wrote {len(evidence)} candidate doc(s) to {batch_path}\n")
+    print("=" * 60)
+    print(_LLM_PROMPT)
+    for e in evidence:
+        print(f"\n--- {e['rel']} ({e['kind']}, last touched {e['last_touched'] or 'unknown'}) ---")
+        print(f"title: {e['title']}")
+        print(e["excerpt"])
+    print("=" * 60)
+    print(f"\nSave the JSON array to {answers_path}")
+    print("Then run: python3 ~/.claude/skills/work-plan/work_plan.py "
+          "plan-status --repo=<key> --llm --apply")
+    return 0
+
+
+def _llm_apply(docs, rows, repo_root, stamp: bool, draft: bool) -> int:
+    batch_path = cache_dir() / "plan_status.json"
+    answers_path = batch_path.with_suffix(".answers.json")
+    if not batch_path.exists() or not answers_path.exists():
+        print(f"ERROR: run `--llm` first; expected {answers_path}")
+        return 1
+    batch = json.loads(batch_path.read_text())
+    if batch.get("repo_root") != str(repo_root):
+        print(f"ERROR: batch repo_root '{batch.get('repo_root')}' != current "
+              f"'{repo_root}' — refusing to apply a batch from another repo.")
+        return 1
+    allowed = {d["rel"] for d in batch.get("docs", [])}
+    answers = json.loads(answers_path.read_text())
+
+    verdicts = {}
+    for ans in answers:
+        rel = ans.get("rel")
+        verdict = ans.get("verdict")
+        if rel not in allowed:
+            print(f"  SKIP '{rel}': not in the prepared batch (possible injection).")
+            continue
+        if verdict not in _LLM_VERDICTS:
+            print(f"  SKIP '{rel}': invalid verdict '{verdict}'.")
+            continue
+        verdicts[rel] = ans
+
+    for r in rows:
+        ans = verdicts.get(r["rel"])
+        if ans:
+            r["verdict"] = ans["verdict"]
+            r["glyph"] = _LLM_GLYPH[ans["verdict"]]
+            r["rationale"] = f"{ans.get('rationale', '').strip()} (LLM)"
+
+    _render(rows, repo_root)
+    if stamp:
+        _stamp_docs(docs, rows, draft=draft)
+    return 0
+
+
+def _archive_dead(docs, rows, repo_root, draft: bool) -> int:
+    dead = reconcile_actions.dead_rows(rows)
+    if not dead:
+        print("No dead plans to archive.")
+        return 0
+    print(f"\n{'Would archive' if draft else 'Archive'} {len(dead)} dead plan(s):")
+    for r in dead:
+        print(f"  {r['rel']}  ->  {reconcile_actions.archive_dest(r['rel'])}")
+    if draft:
+        return 0
+    if not prompt_yes_no(f"Move {len(dead)} plan(s) to archive/abandoned/? [y/N]"):
+        print("Skipped.")
+        return 0
+    moved = 0
+    for r in dead:
+        dest = reconcile_actions.archive_dest(r["rel"])
+        if git_state.git_mv(r["rel"], dest, repo_root):
+            moved += 1
+            print(f"  ✓ {r['rel']}")
+        else:
+            print(f"  ✗ {r['rel']} (git mv failed)")
+    print(f"Archived {moved}/{len(dead)}.")
+    return 0
+
+
+def _repo_slug(flags):
+    """Resolve the org/repo GitHub slug for the --repo key (for issue creation)."""
+    repo = flags.get("--repo")
+    if not repo or repo is True:
+        return None
+    return config_mod.resolve_github_for_folder(repo, config_mod.load_config())
+
+
+def _issues_for_partials(docs, rows, repo_root, repo_slug, draft: bool) -> int:
+    by_rel = {d.rel: d for d in docs}
+    partials = reconcile_actions.partial_rows(rows)
+    if not partials:
+        print("No partial plans to open issues for.")
+        return 0
+    items = []
+    for r in partials:
+        doc = by_rel.get(r["rel"])
+        if not doc:
+            continue
+        text = doc.path.read_text(encoding="utf-8", errors="replace")
+        decls = manifest.parse_declared_paths(text)
+        pdate = manifest.plan_date_from_filename(doc.path.name)
+        missing = manifest.unsatisfied_paths(decls, repo_root, pdate)
+        title, body = reconcile_actions.issue_for(doc, r, missing)
+        items.append((title, body))
+
+    print(f"\n{'Would open' if draft else 'Open'} {len(items)} issue(s) for partial plans:")
+    for title, body in items:
+        print(f"  • {title}")
+        for line in body.splitlines():
+            if line.startswith("- [ ]"):
+                print(f"      {line}")
+    if draft:
+        return 0
+    if not repo_slug:
+        print("ERROR: --issues needs --repo=<key> with a github slug in config.")
+        return 1
+    if not prompt_yes_no(f"Open {len(items)} GitHub issue(s) in {repo_slug}? [y/N]"):
+        print("Skipped.")
+        return 0
+    opened = 0
+    for title, body in items:
+        url = github_state.create_issue(repo_slug, title, body)
+        if url:
+            opened += 1
+            print(f"  ✓ {url}")
+        else:
+            print(f"  ✗ failed: {title}")
+    print(f"Opened {opened}/{len(items)}.")
+    return 0
+
+
+def run(args: list) -> int:
+    flags, _ = parse_flags(args, KNOWN)
+    repo_root = _resolve_repo_root(flags)
+    raw_days = flags.get("--since-days")
+    if raw_days in (None, True):
+        dead_days = verdict_mod.DEAD_DAYS
+    else:
+        try:
+            dead_days = int(raw_days)
+        except ValueError:
+            print(f"--since-days must be an integer, got '{raw_days}'", file=sys.stderr)
+            return 2
+    today = date.today()
+
+    docs = doc_discovery.discover_docs(repo_root)
+    type_filter = flags.get("--type")
+    if type_filter and type_filter is not True:
+        docs = [d for d in docs if d.kind == type_filter]
+
+    rows = [_evaluate(d, repo_root, today, dead_days) for d in docs]
+
+    if flags.get("--llm"):
+        if flags.get("--apply"):
+            return _llm_apply(docs, rows, repo_root,
+                              stamp=bool(flags.get("--stamp")),
+                              draft=bool(flags.get("--draft")))
+        return _llm_prepare(docs, rows, repo_root)
+
+    if flags.get("--archive"):
+        return _archive_dead(docs, rows, repo_root, draft=bool(flags.get("--draft")))
+
+    if flags.get("--issues"):
+        return _issues_for_partials(docs, rows, repo_root, _repo_slug(flags),
+                                    draft=bool(flags.get("--draft")))
+
+    if flags.get("--json"):
+        print(json.dumps({"repo": str(repo_root), "docs": rows}, indent=2))
+        return 0
+    _render(rows, repo_root)
+    if flags.get("--stamp"):
+        _stamp_docs(docs, rows, draft=bool(flags.get("--draft")))
+    return 0

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

@@ -0,0 +1,172 @@
+"""reconcile subcommand: sync track frontmatter with GitHub issue labels.
+
+For a given track:
+  - Determine the GitHub labels that mark issues as belonging to this track.
+    By default `track/<slug>`. Override per-track via frontmatter:
+      github:
+        labels: [storytelling, campaigns]   # OR semantics — match if any present
+  - Fetch all issues AND pull requests with any of those labels from the repo,
+    in any state (open/closed/merged). PRs are included because frontmatter
+    `github.issues` lists may reference PR numbers, and closed-state coverage
+    keeps the FLAG count tied to actual frontmatter-vs-labels drift instead
+    of "anything closed looks unlabeled."
+  - Compare against frontmatter `github.issues`.
+  - Propose ADDS (labeled in GitHub but missing from frontmatter).
+  - Propose FLAGS (in frontmatter but no longer labeled — possible move out).
+  - User confirms before writing to the LOCAL frontmatter file.
+
+READ-ONLY GITHUB CONTRACT
+  reconcile only READS GitHub via `gh issue list` and `gh pr list`. It NEVER
+  writes labels, edits issues, or modifies remote state. The only writes are
+  to the local track .md frontmatter, and only with explicit user confirmation.
+  Any future change must preserve this property — write paths to GitHub belong
+  in `suggest-priorities --apply` or `group --apply`, not here.
+
+Run with --all to reconcile every active track in one pass.
+"""
+import json
+import subprocess
+
+from lib.config import load_config, ConfigError
+from lib.tracks import discover_tracks, find_track_by_name, filter_tracks_by_repo
+from lib.frontmatter import write_file
+from lib.prompts import parse_flags, prompt_input
+
+
+def _resolve_labels(track) -> list[str]:
+    """Return the GitHub label(s) marking issues as belonging to this track.
+
+    Prefers `track.meta.github.labels` (list). Falls back to `track/<slug>`
+    so existing setups keep working without frontmatter changes.
+    """
+    slug = track.meta.get("track", track.name)
+    labels = track.meta.get("github", {}).get("labels")
+    if labels:
+        cleaned = [str(lab) for lab in labels if str(lab).strip()]
+        if cleaned:
+            return cleaned
+    return [f"track/{slug}"]
+
+
+def _fetch_labeled_issues(repo: str, labels: list[str]) -> list[dict]:
+    """Read-only fetch of issues + PRs matching ANY of `labels`. Unions the results.
+
+    Issues and PRs share the same numeric namespace in a GitHub repo, so a
+    single `seen` dict keyed on `number` is correct. Both kinds use
+    `--state all` so the FLAG count reflects frontmatter-vs-labels drift
+    rather than "anything closed/merged looks unlabeled."
+    """
+    seen: dict[int, dict] = {}
+    for lab in labels:
+        for kind in ("issue", "pr"):
+            proc = subprocess.run(
+                ["gh", kind, "list", "--repo", repo,
+                 "--label", lab,
+                 "--state", "all", "--limit", "200",
+                 "--json", "number,title,state"],
+                capture_output=True, text=True,
+            )
+            if proc.returncode != 0:
+                raise RuntimeError(
+                    f"gh {kind} query failed for label '{lab}': {proc.stderr.strip()}"
+                )
+            for item in (json.loads(proc.stdout) if proc.stdout.strip() else []):
+                seen.setdefault(item["number"], item)
+    return list(seen.values())
+
+
+def run(args: list[str]) -> int:
+    flags, positional = parse_flags(args, {"--all", "--draft", "--repo"})
+    do_all = flags.get("--all", False)
+    draft = flags.get("--draft", False)
+    repo_key = flags.get("--repo")
+    if repo_key is True:
+        print("usage: work_plan.py reconcile <track-name> | --all | --repo=<key> [--draft]")
+        return 2
+    track_name = positional[0] if positional else None
+
+    if not do_all and not track_name and not repo_key:
+        print("usage: work_plan.py reconcile <track-name> | --all | --repo=<key> [--draft]")
+        return 2
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        return 1
+
+    tracks = discover_tracks(cfg)
+    active = [t for t in tracks if t.has_frontmatter
+              and t.meta.get("status") in ("active", "in-progress", "blocked")]
+
+    if do_all or repo_key:
+        targets = active
+        if repo_key:
+            targets = filter_tracks_by_repo(targets, repo_key)
+            if not targets:
+                print(f"No active tracks for repo '{repo_key}'.")
+                return 0
+    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:
+        slug = track.meta.get("track", track.name)
+        if not track.repo:
+            continue
+
+        labels = _resolve_labels(track)
+        try:
+            labeled = _fetch_labeled_issues(track.repo, labels)
+        except RuntimeError as e:
+            print(f"  ⚠ {slug}: {e}")
+            continue
+
+        labeled_nums = {i["number"] for i in labeled}
+        listed_nums = set(track.meta.get("github", {}).get("issues") or [])
+
+        adds = sorted(labeled_nums - listed_nums)
+        flag_nums = sorted(listed_nums - labeled_nums)
+
+        if not adds and not flag_nums:
+            continue
+
+        any_changes = True
+        labels_pretty = ", ".join(labels)
+        print(f"\n▸ {slug}  (labels: {labels_pretty})")
+        if adds:
+            print(f"  ADD ({len(adds)}) — labeled but not in frontmatter:")
+            issue_lookup = {i["number"]: i for i in labeled}
+            for num in adds:
+                i = issue_lookup[num]
+                print(f"    #{num} ({i['state'].lower()}) {i['title']}")
+        if flag_nums:
+            print(f"  FLAG ({len(flag_nums)}) — in frontmatter but missing every configured label:")
+            for num in flag_nums:
+                print(f"    #{num} (label removed; consider /work-plan slot to move)")
+
+        if listed_nums and len(flag_nums) / len(listed_nums) > 0.5:
+            print(f"\n  ⓘ {len(flag_nums)}/{len(listed_nums)} frontmatter issues lack the configured label(s).")
+            print(f"    This track looks hand-curated, not label-driven — reconcile may not be the right tool.")
+            print(f"    If you just want to update issue state in the body table, try:")
+            print(f"      /work-plan refresh-md {slug}")
+
+        if draft:
+            # --draft: print the analysis above and stop. No prompt, no write.
+            # Useful for sweep audits and scripted reports.
+            continue
+
+        choice = prompt_input(f"\n  Apply ADDs to {track.path.name}? [y/N/skip-flags]").lower()
+        if choice == "y":
+            new_issues = sorted(listed_nums | labeled_nums)
+            track.meta.setdefault("github", {})["issues"] = new_issues
+            write_file(track.path, track.meta, track.body)
+            print(f"  ✓ Updated {track.path.name} ({len(adds)} added)")
+
+    if not any_changes:
+        print("All tracks in sync with configured labels.")
+    return 0

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

@@ -0,0 +1,132 @@
+"""refresh-md subcommand."""
+from lib.config import load_config, ConfigError
+from lib.tracks import discover_tracks, find_track_by_name, filter_tracks_by_repo
+from lib.github_state import fetch_issues, state_to_status_label
+from lib.frontmatter import write_file
+from lib.status_table import find_all_status_tables, find_canonical_status_tables, sync_missing_rows, ISSUE_NUM_RE
+from lib.prompts import prompt_yes_no, parse_flags
+
+
+def run(args: list[str]) -> int:
+    flags, positional = parse_flags(args, {"--all", "--yes", "--repo"})
+    do_all = flags.get("--all", False)
+    yes = flags.get("--yes", False)
+    repo_key = flags.get("--repo")
+    if repo_key is True:
+        print("usage: work_plan.py refresh-md <track-name> | --all | --repo=<key>  [--yes]")
+        return 2
+    track_name = positional[0] if positional else None
+
+    if not do_all and not track_name and not repo_key:
+        print("usage: work_plan.py refresh-md <track-name> | --all | --repo=<key>  [--yes]")
+        return 2
+
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}")
+        return 1
+
+    tracks = discover_tracks(cfg)
+    if do_all or repo_key:
+        targets = [t for t in tracks if t.has_frontmatter
+                   and t.meta.get("status") in ("active", "in-progress", "blocked")]
+        if repo_key:
+            targets = filter_tracks_by_repo(targets, repo_key)
+            if not targets:
+                print(f"No active tracks to refresh for repo '{repo_key}'.")
+                return 0
+        elif not targets:
+            print("No active tracks to refresh.")
+            return 0
+        return _refresh_many(targets, yes)
+
+    track = find_track_by_name(track_name, tracks)
+    if not track:
+        print(f"No track matching '{track_name}'.")
+        return 1
+    return _refresh_many([track], yes)
+
+
+def _refresh_many(tracks: list, yes: bool) -> int:
+    """Refresh one or more tracks. Computes proposed updates, then asks one
+    confirmation (or applies all if --yes)."""
+    pending = []
+    for track in tracks:
+        canonical = find_canonical_status_tables(track.body)
+        all_tables = find_all_status_tables(track.body)
+        tables = canonical if canonical else all_tables
+        if not tables:
+            continue
+
+        all_issue_nums = set()
+        for table in tables:
+            for row in table["rows"]:
+                for cell in row["cells"]:
+                    for m in ISSUE_NUM_RE.findall(cell):
+                        all_issue_nums.add(int(m))
+
+        # Frontmatter is canonical for membership: issues listed there but
+        # missing from the table need a fresh row (issue #77). Fetch the union
+        # so appended rows carry live title/assignee/status too.
+        frontmatter_nums = track.meta.get("github", {}).get("issues") or []
+        fetch_nums = sorted(all_issue_nums | set(frontmatter_nums))
+        if not fetch_nums:
+            continue
+
+        issues = fetch_issues(track.repo, fetch_nums)
+        issues_by_num = {i["number"]: i for i in issues}
+        state_by_num = {i["number"]: state_to_status_label(i.get("state")) for i in issues}
+
+        lines = track.body.split("\n")
+        cell_updates = 0
+        for table in tables:
+            sidx = table["status_col_index"]
+            for row in table["rows"]:
+                nums = []
+                for cell in row["cells"]:
+                    nums.extend(int(m) for m in ISSUE_NUM_RE.findall(cell))
+                for num in nums:
+                    if num not in state_by_num:
+                        continue
+                    new_status = state_by_num[num]
+                    if sidx >= len(row["cells"]):
+                        continue
+                    current = row["cells"][sidx].strip()
+                    if current == new_status.strip():
+                        continue
+                    new_label = new_status.strip().split(" ", 1)[-1].lower()
+                    if new_label and new_label in current.lower():
+                        continue
+                    new_cells = list(row["cells"])
+                    new_cells[sidx] = " " + new_status + " "
+                    lines[row["line_idx"]] = "|" + "|".join(new_cells) + "|"
+                    cell_updates += 1
+
+        new_body = "\n".join(lines)
+        # Slot in rows for frontmatter issues missing from the table, each at
+        # its frontmatter-order position. Cell updates above preserve the line
+        # count, so the table's line indices stay valid for sync_missing_rows.
+        new_body, rows_added = sync_missing_rows(new_body, frontmatter_nums, issues_by_num)
+
+        if new_body == track.body:
+            continue
+        pending.append((track, new_body, cell_updates, rows_added))
+
+    if not pending:
+        print("All tracks in sync.")
+        return 0
+
+    print(f"Pending updates across {len(pending)} track(s):\n")
+    for track, _, cells, added in pending:
+        added_str = f", {added} row(s) added" if added else ""
+        print(f"  {track.path.name:50}  {cells} cell(s){added_str}")
+
+    if not yes and not prompt_yes_no("\nApply all? [y/N]"):
+        print("Cancelled.")
+        return 0
+
+    for track, new_body, _, _ in pending:
+        write_file(track.path, track.meta, new_body)
+    print(f"\n✓ Updated {len(pending)} file(s).")
+    return 0

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

@@ -0,0 +1,54 @@
+"""set subcommand — guarded edit of a track's frontmatter scalar/list fields."""
+import json
+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
+
+ALLOWED = {"status", "launch_priority", "milestone_alignment", "blockers", "next_up"}
+LIST_FIELDS = {"blockers", "next_up"}
+STATUSES = {"active", "in-progress", "blocked", "parked", "shipped", "abandoned"}
+
+def run(args: list[str]) -> int:
+    # Confirm token is passed as --confirm=<token> (equals form: parse_flags only
+    # understands --key=value or bare --key, so a space-separated token would be
+    # mis-read as a positional). The VS Code extension invokes the equals form.
+    flags, positional = parse_flags(args, {"--confirm"})
+    if len(positional) < 2:
+        print("usage: work_plan.py set <track> field=value [field=value …] [--confirm=<token>]"); return 2
+    name, assignments = positional[0], positional[1:]
+    parsed = {}
+    for a in assignments:
+        if "=" not in a:
+            print(f"ERROR: bad assignment {a!r} (expected field=value)"); return 2
+        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:
+            try:
+                parsed[k] = [int(x) for x in v.split(",") if x.strip()] if v.strip() else []
+            except ValueError:
+                print(f"ERROR: {k} takes comma-separated integers (got {v!r})"); return 2
+        elif k == "status" and v not in STATUSES:
+            print(f"ERROR: status {v!r} invalid (allowed: {sorted(STATUSES)})"); return 2
+        else:
+            parsed[k] = v
+    try:
+        cfg = load_config()
+    except ConfigError as e:
+        print(f"ERROR: {e}"); return 1
+    track = find_track_by_name(name, discover_tracks(cfg))
+    if not track:
+        print(f"No track matching {name!r}."); return 1
+    # Public-repo confirm gate (the extension surfaces this as a modal).
+    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); edit will be written there.",
+                          "token": make_token(track.repo, track.name)}))
+        return 0
+    track.meta.update(parsed)
+    write_file(track.path, track.meta, track.body)
+    print(f"✓ set {', '.join(parsed)} on {track.name}")
+    return 0