@stylusnexus/work-plan 2026.6.9 → 2026.6.10

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/config.py

@@ -70,6 +70,12 @@ def load_config(path: Path = DEFAULT_CONFIG_PATH,
     return cfg
 
 
+def is_valid_git_repo(path: Path) -> bool:
+    """Return True if path is a directory that contains a .git entry."""
+    p = Path(path)
+    return p.is_dir() and (p / ".git").exists()
+
+
 def resolve_github_for_folder(folder_name: str, cfg: dict) -> Optional[str]:
     entry = cfg.get("repos", {}).get(folder_name)
     return entry.get("github") if entry else None

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,22 +62,28 @@ 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]
         out["tracks"].append({
             "name": t.name,
             "repo": t.repo,
             "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": list(t.meta.get("next_up") 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/lib/notes_readme.py

@@ -0,0 +1,38 @@
+"""First-creation-only seed for .work-plan/README.md."""
+from pathlib import Path
+
+README_CONTENT = """\
+# .work-plan/
+
+This folder contains **shared planning tracks** managed by [`work-plan`](https://github.com/stylusnexus/work-plan-toolkit).
+
+Each `.md` file is a planning track: a lightweight document with YAML frontmatter that
+points at GitHub issues and captures session notes. GitHub is canonical for issue state;
+these files are the *planning context* that travels with the code.
+
+## Shared vs. private tracks
+
+Tracks in this folder are the **shared tier** — they're committed and sync via `git pull`.
+To keep a track private (personal notes, not for teammates), use `--private` when creating
+it and it will go into your local `notes_root` folder instead.
+
+## Setup
+
+Install the toolkit: [stylusnexus/work-plan-toolkit](https://github.com/stylusnexus/work-plan-toolkit)
+Also available as a Claude/Codex plugin: [stylusnexus/agent-plugins](https://github.com/stylusnexus/agent-plugins)
+"""
+
+
+def seed_readme(work_plan_dir: Path) -> bool:
+    """Write README.md into work_plan_dir if and only if the dir was just created
+    (i.e. it did not previously contain a README.md). Returns True if written.
+
+    Rule: only seeds on first creation. If README.md already exists (even if empty),
+    leaves it alone. If the user deleted it inside an existing folder, does NOT
+    resurrect it — deletion is a respected opt-out.
+    """
+    readme = work_plan_dir / "README.md"
+    if readme.exists():
+        return False
+    readme.write_text(README_CONTENT, encoding="utf-8")
+    return True

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

@@ -1,12 +1,35 @@
 """Shared CLI helpers: prompts and arg parsing."""
+import sys
+
+
+def _stdin_is_interactive() -> bool:
+    """True only when stdin is a real terminal we can block on for a reply.
+
+    When the CLI is launched with stdin wired to a pipe or socket that stays
+    open but never delivers a line — e.g. the VS Code extension spawning
+    `work_plan.py` — `input()` blocks forever (no data, no EOF). A closed pipe
+    raises EOFError and is handled; an *idle open* one hangs. Guarding on
+    `isatty()` lets the prompt helpers fall back to their default instead of
+    deadlocking. Non-interactive callers should pass an explicit flag
+    (`--yes`, `--draft`) rather than rely on the prompt.
+    """
+    try:
+        return bool(sys.stdin) and sys.stdin.isatty()
+    except (ValueError, AttributeError):
+        # stdin closed/detached, or replaced by an object without isatty.
+        return False
 
 
 def prompt_input(message: str, default: str = "") -> str:
     """Print prompt and read a free-form line. Treats EOF (no stdin) as default.
 
-    Returns the stripped input, or `default` if EOF or blank.
+    Returns the stripped input, or `default` if EOF, blank, or there is no
+    interactive terminal to read from.
     """
     print(message)
+    if not _stdin_is_interactive():
+        print(f"(no interactive terminal — using default {default!r})")
+        return default
     try:
         line = input().strip()
     except EOFError:
@@ -15,7 +38,12 @@ def prompt_input(message: str, default: str = "") -> str:
 
 
 def prompt_lines() -> list[str]:
-    """Read lines from stdin until blank line or EOF. Returns list of non-blank lines."""
+    """Read lines from stdin until blank line or EOF. Returns list of non-blank lines.
+
+    With no interactive terminal, returns an empty list rather than blocking.
+    """
+    if not _stdin_is_interactive():
+        return []
     out = []
     try:
         while True:
@@ -29,11 +57,14 @@ def prompt_lines() -> list[str]:
 
 
 def prompt_yes_no(message: str = "Apply? [y/N]") -> bool:
-    """Print prompt and read y/N. Treats EOF (no stdin) as no.
+    """Print prompt and read y/N. Treats EOF or no terminal as no.
 
     Returns True only if user explicitly types 'y' (case-insensitive).
     """
     print(message)
+    if not _stdin_is_interactive():
+        print("(no interactive terminal — defaulting to no)")
+        return False
     try:
         choice = input().strip().lower()
     except EOFError:

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

@@ -1,10 +1,42 @@
-"""Discover tracks under notes_root."""
+"""Discover tracks under notes_root and shared .work-plan/ dirs."""
+import sys
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Optional
 
 from lib.frontmatter import parse_file
-from lib.config import resolve_github_for_folder, resolve_local_path_for_folder
+from lib.config import (
+    resolve_github_for_folder,
+    resolve_local_path_for_folder,
+    is_valid_git_repo,
+)
+from lib.git_state import parse_iso_timestamp
+
+_PRIORITY_RANK = {"P0": 0, "P1": 1, "P2": 2, "P3": 3}
+
+
+def priority_rank(meta: dict) -> int:
+    """Rank a track's launch_priority for ascending sort: P0<P1<P2<P3<anything.
+
+    Unknown / missing values (e.g. "—" or absent) sort after all known ranks.
+    """
+    return _PRIORITY_RANK.get(meta.get("launch_priority"), len(_PRIORITY_RANK))
+
+
+def recency_sort_key(meta: dict) -> float:
+    """Sort key for last_touched recency (most recent first when sorted ascending).
+
+    Returns the negative POSIX timestamp so that a plain ascending sort puts the
+    most-recently-touched track first. Tracks with no (or unparseable)
+    last_touched return +inf, sorting them LAST.
+    """
+    raw = meta.get("last_touched")
+    if not raw:
+        return float("inf")
+    try:
+        return -parse_iso_timestamp(raw).timestamp()
+    except (ValueError, TypeError):
+        return float("inf")
 
 
 @dataclass
@@ -19,14 +51,37 @@ class Track:
     local_path: Optional[Path] = None
     meta: dict = field(default_factory=dict)
     body: str = ""
+    tier: Optional[str] = None
 
 
 def discover_tracks(cfg: dict) -> list[Track]:
-    """Walk notes_root for active (non-archived) .md files."""
-    notes_root = Path(cfg["notes_root"]).expanduser()
-    if not notes_root.exists():
-        return []
-    return _walk(notes_root, cfg, include_archive=False)
+    """Walk notes_root for active (non-archived) .md files, then union with
+    shared tracks from each configured repo's .work-plan/ directory.
+    Shared wins on (repo, name) collisions.
+    """
+    private = _discover_private_tracks(cfg, include_archive=False)
+    shared = _discover_shared_tracks(cfg, include_archive=False)
+
+    # Build lookup for shared tracks keyed by (repo, name)
+    shared_keys: dict = {}
+    for t in shared:
+        key = (t.repo, t.name)
+        shared_keys[key] = t
+
+    # Merge: private tracks that have no colliding shared track are kept
+    merged = list(shared)
+    for t in private:
+        key = (t.repo, t.name)
+        if key in shared_keys:
+            print(
+                f"WARN: track {t.name!r} (repo={t.repo!r}) exists in both shared"
+                f" ({shared_keys[key].path}) and private ({t.path}); using shared.",
+                file=sys.stderr,
+            )
+        else:
+            merged.append(t)
+
+    return merged
 
 
 def filter_tracks_by_repo(tracks: list[Track], key: str) -> list[Track]:
@@ -38,37 +93,171 @@ def filter_tracks_by_repo(tracks: list[Track], key: str) -> list[Track]:
             or (t.repo and t.repo.lower() == k)]
 
 
-def find_track_by_name(name: str, tracks: list[Track],
-                       *, active_only: bool = False) -> Optional[Track]:
+class AmbiguousTrackError(Exception):
+    """Raised when a track name matches more than one track across repos."""
+
+    def __init__(self, name: str, candidates: list[Track]):
+        self.name = name
+        self.candidates = candidates
+        repos = [f"  {t.name} (repo: {t.repo or t.folder!r})" for t in candidates]
+        super().__init__(
+            f"Track {name!r} is ambiguous — found in {len(candidates)} repos:\n"
+            + "\n".join(repos)
+            + f"\nUse --repo=<key> or '{name}@<repo>' to disambiguate."
+        )
+
+
+def parse_track_repo_arg(arg: str) -> tuple:
+    """Split 'trackname@repokey' into (trackname, repokey); return (arg, None) if no @."""
+    if "@" in arg:
+        name, _, repo = arg.rpartition("@")
+        return (name, repo) if name else (arg, None)
+    return (arg, None)
+
+
+def find_track_by_name(
+    name: str, tracks: list[Track],
+    *, active_only: bool = False, repo: Optional[str] = None
+) -> Optional[Track]:
     """Find a single Track matching `name` (filename stem OR frontmatter `track`).
 
+    If repo is given, first filter to tracks matching that repo (folder key or
+    GitHub slug, case-insensitive). Then find a single name match.
+
     If active_only=True, only considers tracks with status active/in-progress/blocked.
-    Returns the single match or None. Used by every command that takes a track arg.
+
+    Returns the single match or None (0 matches).
+    Raises AmbiguousTrackError if 2+ matches remain after filtering.
     """
     candidates = tracks
+    if repo:
+        candidates = filter_tracks_by_repo(candidates, repo)
     if active_only:
         candidates = [t for t in candidates if t.has_frontmatter
                       and t.meta.get("status") in ("active", "in-progress", "blocked")]
     matching = [t for t in candidates if t.has_frontmatter
                 and (t.name == name or t.meta.get("track") == name)]
-    return matching[0] if len(matching) == 1 else None
+    if len(matching) <= 1:
+        return matching[0] if matching else None
+    raise AmbiguousTrackError(name, matching)
 
 
 def discover_archived_tracks(cfg: dict) -> list[Track]:
-    """Walk notes_root for archived .md files only."""
+    """Walk notes_root for archived .md files, and also scan each repo's
+    .work-plan/archive/ for shared archived tracks.
+
+    Deduplicates by (repo, name): shared wins over private, same as
+    discover_tracks for active tracks.
+    """
+    notes_root = Path(cfg["notes_root"]).expanduser()
+    private_archived: list[Track] = []
+    if notes_root.exists():
+        for md_path in sorted(notes_root.rglob("*.md")):
+            if "archive" not in md_path.parts:
+                continue
+            if md_path.name.startswith((".", "_")):
+                continue
+            private_archived.append(_build_track(md_path, notes_root, cfg))
+
+    shared_archived = _discover_shared_tracks(cfg, include_archive=True,
+                                              archive_only=True)
+
+    # Build lookup for shared tracks keyed by (repo, name)
+    shared_keys: dict = {}
+    for t in shared_archived:
+        key = (t.repo, t.name)
+        shared_keys[key] = t
+
+    # Merge: shared wins on collision
+    merged = list(shared_archived)
+    for t in private_archived:
+        key = (t.repo, t.name)
+        if key in shared_keys:
+            print(
+                f"WARN: archived track {t.name!r} (repo={t.repo!r}) exists in"
+                f" both shared ({shared_keys[key].path}) and private"
+                f" ({t.path}); using shared.",
+                file=sys.stderr,
+            )
+        else:
+            merged.append(t)
+
+    return merged
+
+
+# ---------------------------------------------------------------------------
+# Private helpers
+# ---------------------------------------------------------------------------
+
+def _discover_private_tracks(cfg: dict, include_archive: bool) -> list[Track]:
     notes_root = Path(cfg["notes_root"]).expanduser()
     if not notes_root.exists():
         return []
-    out = []
-    for md_path in sorted(notes_root.rglob("*.md")):
-        if "archive" not in md_path.parts:
+    return _walk(notes_root, cfg, include_archive=include_archive)
+
+
+def _discover_shared_tracks(cfg: dict, include_archive: bool = False,
+                             archive_only: bool = False) -> list[Track]:
+    """Walk each configured repo's local clone .work-plan/ directory."""
+    out: list[Track] = []
+    repos = cfg.get("repos", {})
+    for folder_key, entry in repos.items():
+        if not entry or not entry.get("local"):
             continue
-        if md_path.name.startswith((".", "_")):
+        local_path = Path(entry["local"]).expanduser()
+        if not is_valid_git_repo(local_path):
             continue
-        out.append(_build_track(md_path, notes_root, cfg))
+        github_repo = entry.get("github")
+        notes_dir = local_path / ".work-plan"
+        if not notes_dir.is_dir():
+            continue
+        for md_path in sorted(notes_dir.rglob("*.md")):
+            # Skip dotfiles and README
+            if md_path.name.startswith(".") or md_path.name == "README.md":
+                continue
+            in_archive = "archive" in md_path.relative_to(notes_dir).parts
+            if archive_only and not in_archive:
+                continue
+            if not include_archive and in_archive:
+                continue
+            out.append(_build_shared_track(
+                md_path, folder_key, github_repo, local_path
+            ))
     return out
 
 
+def _build_shared_track(md_path: Path, folder_key: str,
+                         github_repo: Optional[str], local_path: Path) -> Track:
+    """Build a Track from a shared .work-plan/ markdown file."""
+    meta, body = parse_file(md_path)
+    has_fm = bool(meta)
+
+    # Single-owner rule: if frontmatter disagrees with folder config, warn and
+    # use the folder's configured github repo (never the frontmatter value).
+    if has_fm and meta.get("github", {}).get("repo"):
+        fm_repo = meta["github"]["repo"]
+        if fm_repo != github_repo:
+            print(
+                f"WARN: shared track {md_path.name!r} frontmatter github.repo"
+                f" differs from folder config; using folder {github_repo!r}",
+                file=sys.stderr,
+            )
+
+    return Track(
+        path=md_path,
+        name=md_path.stem,
+        has_frontmatter=has_fm,
+        needs_init=False,
+        needs_filing=False,
+        repo=github_repo,
+        folder=folder_key,
+        local_path=local_path,
+        meta=meta,
+        body=body,
+        tier="shared",
+    )
+
+
 def _walk(notes_root: Path, cfg: dict, include_archive: bool) -> list[Track]:
     out = []
     for md_path in sorted(notes_root.rglob("*.md")):
@@ -80,7 +269,7 @@ def _walk(notes_root: Path, cfg: dict, include_archive: bool) -> list[Track]:
     return out
 
 
-def _build_track(md_path: Path, notes_root: Path, cfg: dict) -> Track:
+def _build_track(md_path: Path, notes_root: Path, cfg: dict) -> "Track":
     meta, body = parse_file(md_path)
     has_fm = bool(meta)
     rel = md_path.relative_to(notes_root)
@@ -106,4 +295,5 @@ def _build_track(md_path: Path, notes_root: Path, cfg: dict) -> Track:
         local_path=local,
         meta=meta,
         body=body,
+        tier="private",
     )