workstream-cli 0.0.1__py3-none-any.whl

workstream/commands/sweep.py

@@ -0,0 +1,1753 @@
+"""ws sweep — scan repos for plans/branches and update workstream files."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from datetime import date, datetime
+from pathlib import Path
+
+from face import Command
+
+from workstream.config import Config, GLOBAL_CONFIG_PATH, RepoConfig
+from workstream.git import branch_ahead_count, branch_is_merged, list_branches
+from workstream.cli import load_all_workstreams
+from workstream.markdown import (
+    parse_frontmatter,
+    save_workstream,
+)
+from workstream.models import BranchRef, LogEntry, PlanRef, slugify
+
+
+# ── Sweep findings accumulator ──────────────────────────────────────
+
+
+@dataclass
+class SweepFindings:
+    """Delta from a single sweep run for one workstream.
+
+    Accumulated during the scan loop and passed to the review manifest
+    builder.  This is the single source of truth for what changed —
+    the manifest builder must not re-derive it.
+    """
+    newly_matched: list[PlanRef] = field(default_factory=list)
+    new_signals: list[PlanRef] = field(default_factory=list)
+    auto_classified: list[PlanRef] = field(default_factory=list)
+    repos_with_commits: dict[str, list[dict]] = field(default_factory=dict)
+
+
+_RELATIVE_RE = re.compile(r'^(\d+)([hdwm])$')
+_RELATIVE_UNITS = {'h': 'hours', 'd': 'days', 'w': 'weeks', 'm': 'months'}
+
+
+def _resolve_cutoff(since: str | None, last_sweep: str) -> str:
+    """Resolve --since into a git-compatible cutoff string.
+
+    Accepts: ISO date ('2026-03-30'), ISO datetime ('2026-03-30T14:00'),
+    relative shorthand ('2h', '1d', '3w'), or None (default: last_sweep).
+    Returns empty string when no cutoff is available (first sweep).
+    """
+    if since:
+        m = _RELATIVE_RE.match(since)
+        if m:
+            return f'{m.group(1)} {_RELATIVE_UNITS[m.group(2)]} ago'
+        return since  # ISO date/datetime or other git-compatible format
+    if last_sweep:
+        # last_sweep is date-only (YYYY-MM-DD); git interprets as midnight start-of-day
+        return last_sweep
+    return ''  # first sweep — no cutoff
+
+_PLAN_STATUS_RE = re.compile(r'<!--\s*STATUS:\s*(\w+)(?:\s+(\S+))?\s*-->')
+
+# Map legacy HTML comment statuses to canonical plan statuses.
+# FINALIZED means approved/ready, not implemented.
+_HTML_COMMENT_STATUS_MAP = {'finalized': 'active'}
+
+_FILENAME_DATE_RE = re.compile(r'^(\d{4}-\d{2}-\d{2})')
+
+def _date_from_filename(filename: str) -> str:
+    """Extract leading YYYY-MM-DD from a plan filename, or return ''."""
+    m = _FILENAME_DATE_RE.match(filename)
+    return m.group(1) if m else ''
+
+def scan_repo_plans(plans_dir: Path) -> list[dict]:
+    """Scan a plans directory, return list of {path, meta} dicts.
+
+    Parses YAML frontmatter first. Falls back to HTML comment status markers
+    (``<!-- STATUS: FINALIZED timestamp -->``) for legacy plan files.
+    """
+    if not plans_dir.is_dir():
+        return []
+    results = []
+    for f in sorted(plans_dir.glob('*.md')):
+        text = f.read_text(encoding='utf-8')
+        meta, _ = parse_frontmatter(text)
+        if not meta:
+            # Legacy plans: status in HTML comment, not YAML frontmatter
+            m = _PLAN_STATUS_RE.match(text)
+            if m:
+                raw = m.group(1).lower()
+                meta = {'status': _HTML_COMMENT_STATUS_MAP.get(raw, raw)}
+                if m.group(2):
+                    meta['finalized_at'] = m.group(2)
+        results.append({'path': f.name, 'meta': meta})
+    return results
+
+
+def _scan_repo_branches(repo_path: Path) -> list[dict]:
+    """List non-default branches with ahead counts. Returns [] on git failure."""
+    try:
+        branches = list_branches(repo_path)
+    except Exception:
+        return []
+    results = []
+    for b in branches:
+        if b in ('main', 'master'):
+            continue
+        ahead = branch_ahead_count(repo_path, b)
+        results.append({'branch': b, 'ahead': ahead})
+    return results
+
+
+def _make_plan_ref(repo_name: str, plan: dict) -> PlanRef:
+    """Build a PlanRef from a scanned plan dict."""
+    meta = plan['meta']
+    return PlanRef(
+        repo=repo_name,
+        path=plan['path'],
+        status=meta.get('status', 'unknown'),
+        title=meta.get('title', ''),
+        date=str(meta.get('created', '') or '') or _date_from_filename(plan['path']),
+        plan_type=meta.get('plan_type', ''),
+        guidance=meta.get('workstream_guidance', ''),
+    )
+
+
+def _match_plans_to_workstream(
+    ws_title: str, ws_slug: str, ws_id: str,
+    ws_repos: list[str], repo_name: str, plans: list[dict],
+) -> list[PlanRef]:
+    """Return PlanRef entries from plans that belong to this workstream.
+
+    Plans with an explicit ``workstream`` field are matched against the
+    workstream's title (case-insensitive), slug, or ID.  Only plans that
+    match are included — plans assigned to a *different* workstream are
+    skipped.  Plans with no ``workstream`` field fall back to repo-level
+    matching (included in every workstream that claims the repo).
+    """
+    ws_identities = {ws_title.lower(), ws_slug, ws_id}
+    matched = []
+    for plan in plans:
+        meta = plan['meta']
+        plan_ws = (meta.get('workstream', '') or '').strip()
+        if plan_ws:
+            if plan_ws.lower() in ws_identities or slugify(plan_ws) == ws_slug:
+                matched.append(_make_plan_ref(repo_name, plan))
+            # Plan is assigned to a different workstream — skip
+            continue
+        # No explicit assignment — fall back to repo-level matching
+        if repo_name in ws_repos:
+            matched.append(_make_plan_ref(repo_name, plan))
+    return matched
+
+
+def _match_branches_to_workstream(ws_slug: str, repo_name: str,
+                                  branches: list[dict]) -> list[BranchRef]:
+    """Return BranchRef entries for branches whose name contains the ws slug."""
+    matched = []
+    for info in branches:
+        branch_name = info['branch']
+        # Heuristic: branch name contains slugified workstream title
+        if ws_slug in branch_name:
+            matched.append(BranchRef(repo=repo_name, branch=branch_name, ahead=info['ahead']))
+    return matched
+
+
+def _auto_classify_plans(
+    plans: list['PlanRef'], repo_data: dict[str, dict],
+) -> list['PlanRef']:
+    """Auto-classify plans with high-confidence heuristic signals.
+
+    Plans with 'likely-implemented' signal get status set to 'implemented'
+    in their plan file's YAML frontmatter. Returns list of plans that were
+    auto-classified.
+    """
+    from workstream.markdown import parse_frontmatter, write_frontmatter
+    from datetime import date as date_type
+
+    today = date_type.today().isoformat()
+    classified: list[PlanRef] = []
+
+    for plan in plans:
+        if plan.signal != 'likely-implemented':
+            continue
+
+        # Find the plan file and update its frontmatter
+        data = repo_data.get(plan.repo)
+        if not data:
+            continue
+        plans_dir = data.get('plans_dir')
+        if not plans_dir:
+            continue
+        plan_file = plans_dir / plan.path
+        if not plan_file.is_file():
+            continue
+
+        try:
+            text = plan_file.read_text(encoding='utf-8')
+            meta, body = parse_frontmatter(text)
+            if not meta or meta.get('status') == 'implemented':
+                continue  # already classified or no frontmatter
+            meta['status'] = 'implemented'
+            meta['reviewed'] = today
+            meta['review_note'] = 'auto-classified: associated branch merged'
+            plan_file.write_text(
+                write_frontmatter(meta, body), encoding='utf-8'
+            )
+            plan.status = 'implemented'
+            classified.append(plan)
+        except Exception:
+            pass  # don't fail sweep for one bad file
+
+    return classified
+
+
+def _find_matching_branches(plan_title: str, branches: list[BranchRef]) -> list[BranchRef]:
+    """Find branches whose name contains the slugified plan title.
+
+    Used for triage: when a new project plan is discovered, show whether
+    a corresponding branch already exists.
+    """
+    slug = slugify(plan_title)
+    if len(slug) < _MIN_SLUG_MATCH_LEN:
+        return []
+    return [b for b in branches if slug in b.branch]
+
+_MIN_SLUG_MATCH_LEN = 4  # avoid false positives for short names like 'bq', 'top'
+
+
+def _repo_matches_slug(repo_name: str, ws_slug: str) -> bool:
+    """True if repo_name plausibly belongs to a workstream with the given slug.
+
+    Matches on: exact equality, or word-prefix in either direction
+    (e.g., repo 'workstream' matches slug 'workstream-tool').
+    Short names (< 4 chars) require exact match to avoid false positives.
+    """
+    if repo_name == ws_slug:
+        return True
+    # Check prefix in each direction, guarding against short stems
+    if ws_slug.startswith(repo_name + '-') and len(repo_name) >= _MIN_SLUG_MATCH_LEN:
+        return True
+    if repo_name.startswith(ws_slug + '-') and len(ws_slug) >= _MIN_SLUG_MATCH_LEN:
+        return True
+    return False
+
+
+def _auto_associate_repos(workstreams: list, repo_names: list[str]) -> int:
+    """Set ws.repos for workstreams with no repos, using slug matching.
+
+    Matches exact slug equality, or word-prefix in either direction
+    (e.g., repo 'workstream' matches slug 'workstream-tool').
+    Short slugs (< 4 chars) require exact match to avoid false positives.
+    Returns count of workstreams updated on disk.
+    """
+    count = 0
+    for ws in workstreams:
+        if ws.repos or ws._repos_explicit:
+            continue
+        ws_slug = slugify(ws.title)
+        matched = [r for r in repo_names if _repo_matches_slug(r, ws_slug)]
+        if matched:
+            ws.repos = matched
+            if ws.source_path:
+                save_workstream(ws, ws.source_path)
+                count += 1
+    return count
+
+
+# Month extraction from sprint filenames (sprint_YYYY-MM-DD.md)
+_SPRINT_DATE_RE = re.compile(r'sprint_(\d{4}-\d{2})')
+
+
+def _file_month(path: Path) -> str:
+    """Extract 'YYYY-MM' from a sprint filename, or 'unknown'."""
+    m = _SPRINT_DATE_RE.search(path.name)
+    return m.group(1) if m else 'unknown'
+
+
+def _file_size_kb(path: Path) -> str:
+    """Human-readable file size in KB."""
+    return f'{path.stat().st_size / 1024:.0f}KB'
+
+
+def _build_per_workstream_repo_context(
+    workstreams: list, found_repos: list, cutoff: str,
+) -> str:
+    """Build a structured repo activity summary grouped by workstream.
+
+    Returns a text block with per-workstream branch/commit summaries,
+    plus an 'Unmatched' section for repos/branches not tied to any workstream.
+    The LLM can run git commands for deeper investigation since repos are local.
+    """
+    from workstream.git import recent_commits
+    from workstream.repo_discovery import _default_branch, _repo_summary
+
+    if not found_repos:
+        return ''
+
+    repo_summaries = []
+    for repo in found_repos:
+        info = _repo_summary(repo, cutoff)
+        if info is not None:
+            repo_summaries.append(info)
+
+    if not repo_summaries:
+        return ''
+
+    # Build lookup: workstream slug -> workstream
+    ws_slugs = {slugify(ws.title): ws for ws in workstreams}
+
+    # Track which branches have been claimed by a workstream
+    claimed_branches: set[tuple[str, str]] = set()  # (repo_name, branch_name)
+    claimed_repos: set[str] = set()
+
+    lines: list[str] = []
+
+    for ws in workstreams:
+        ws_slug = slugify(ws.title)
+        ws_lines: list[str] = []
+
+        for info in repo_summaries:
+            repo_name = info['name']
+
+            # Match repo to workstream by ws.repos list or slug-in-repo-name
+            repo_matches = (repo_name in ws.repos) or (ws_slug in repo_name.lower())
+
+            # Find matching branches
+            matched_branches = []
+            for b in info.get('active_branches', []):
+                branch_name = b['name']
+                if ws_slug in branch_name or repo_matches:
+                    matched_branches.append(b)
+                    claimed_branches.add((repo_name, branch_name))
+
+            if repo_matches:
+                claimed_repos.add(repo_name)
+                last = info.get('last_default_date', '')
+                ws_lines.append(f'  {repo_name}: last default-branch commit {last}')
+                for b in matched_branches:
+                    ws_lines.append(
+                        f'    - {b["name"]} (+{b["ahead"]} ahead) — {b["date"]}: "{b["subject"]}"'
+                    )
+            elif matched_branches:
+                for b in matched_branches:
+                    ws_lines.append(
+                        f'  {repo_name}/{b["name"]} (+{b["ahead"]} ahead) — {b["date"]}: "{b["subject"]}"'
+                    )
+
+        if ws_lines:
+            lines.append(f'{ws.title} ({ws.id}):')
+            lines.extend(ws_lines)
+            lines.append('')
+
+    # Unmatched repos/branches
+    unmatched_lines: list[str] = []
+    for info in repo_summaries:
+        repo_name = info['name']
+        if repo_name not in claimed_repos:
+            last = info.get('last_default_date', '')
+            has_activity = info.get('is_active', False)
+            if has_activity:
+                unmatched_lines.append(f'  {repo_name}: last default-branch commit {last}')
+        # Branches not claimed
+        for b in info.get('active_branches', []):
+            if (info['name'], b['name']) not in claimed_branches:
+                unmatched_lines.append(
+                    f'  {info["name"]}/{b["name"]} (+{b["ahead"]} ahead) — {b["date"]}: "{b["subject"]}"'
+                )
+
+    if unmatched_lines:
+        lines.append('Unmatched repos/branches:')
+        lines.extend(unmatched_lines)
+        lines.append('')
+
+    return '\n'.join(lines)
+
+
+def _recompute_activity_dates(ws_dir: Path, repo_paths: dict[str, Path] | None = None) -> None:
+    """Recompute first_activity/last_activity/code_last_activity from dated artifacts.
+    
+    Idempotent: reads each workstream, derives dates from its entries, writes
+    only if the computed values differ from what's stored.
+    """
+    from workstream.markdown import load_workstream, parse_frontmatter, write_frontmatter
+
+    updated = 0
+    for ws_file in sorted(ws_dir.glob('*.md')):
+        if ws_file.name == 'inbox.md':
+            continue
+        try:
+            ws = load_workstream(ws_file)
+        except Exception:
+            continue
+
+        # Collect all dates from thread entries and thought entries
+        dates: list[str] = []
+        for entry in ws.thread:
+            if entry.date:
+                dates.append(entry.date)
+        for thought in ws.thoughts:
+            if thought.date:
+                dates.append(thought.date)
+
+        # Plan dates
+        for plan in ws.plans:
+            if plan.date:
+                dates.append(plan.date)
+
+        # Git commit dates (most recent commit per associated repo)
+        git_dates: list[str] = []
+        if repo_paths:
+            from workstream.git import recent_commits
+            ws_slug = slugify(ws.title)
+            associated_repos: set[str] = set(ws.repos)
+            for rname in repo_paths:
+                if _repo_matches_slug(rname, ws_slug):
+                    associated_repos.add(rname)
+            for repo_name in associated_repos:
+                rpath = repo_paths.get(repo_name)
+                if rpath and rpath.is_dir():
+                    try:
+                        commits = recent_commits(rpath, '2020-01-01')
+                        if commits:
+                            git_dates.append(commits[0]['date'])
+                    except Exception:
+                        continue
+        dates.extend(git_dates)
+
+        if not dates:
+            continue
+
+        # Preserve any existing datetime-precision value for last_activity.
+        # All thread/thought/plan entry dates are YYYY-MM-DD, so _recompute_
+        # would otherwise downgrade a stored 'YYYY-MM-DDTHH:MM:SS' back to a
+        # plain date. Including it in the pool keeps the datetime if it is
+        # already the maximum.
+        if ws.last_activity:
+            dates.append(ws.last_activity)
+
+        computed_first = min(dates)
+        computed_last = max(dates)
+
+        code_last = max(git_dates) if git_dates else ''
+
+        if (computed_first == ws.first_activity
+                and computed_last == ws.last_activity
+                and code_last == ws.code_last_activity):
+            continue
+
+        # Update frontmatter in place
+        text = ws_file.read_text(encoding='utf-8')
+        meta, body = parse_frontmatter(text)
+        meta['first_activity'] = computed_first
+        meta['last_activity'] = computed_last
+        if code_last:
+            meta['code_last_activity'] = code_last
+        elif 'code_last_activity' in meta:
+            del meta['code_last_activity']
+        ws_file.write_text(write_frontmatter(meta, body), encoding='utf-8')
+        updated += 1
+
+    if updated:
+        print(f'  Updated activity dates for {updated} workstream(s).')
+
+
+def _discover_handler(config: Config, workstreams: list, ws_dir: Path,
+                      interactive: bool = False,
+                      lookback_days: int = 60) -> None:
+    """Run LLM-driven discovery: extract and associate thoughts per file.
+
+    Sends each unprocessed sprint note to the LLM in full, which extracts
+    thoughts and associates them with workstreams in a single pass.
+    Saves state after every file, so Ctrl+C loses at most one LLM call.
+    With ``interactive=True``, pauses at month boundaries when inbox items
+    or errors need attention. Clean months proceed without prompting.
+
+    Only processes files whose effective date is within *lookback_days*.
+    Effective date: git commit date (primary), file mtime (fallback).
+    """
+    import sys
+    from collections import defaultdict
+    from datetime import date, timedelta
+
+    from workstream.llm import LLMAgent
+    from workstream.sweep_state import load_sweep_state, save_sweep_state
+    from workstream.thoughts import (
+        Thought,
+        build_discovery_prompt,
+        dispatch_associations,
+        parse_association_response,
+    )
+
+    today = date.today()
+    cutoff = today - timedelta(days=lookback_days)
+
+    # 1. Load sweep state
+    state = load_sweep_state(ws_dir)
+
+    # 1b. Build per-workstream repo context
+    found_repos: list = []
+    repo_context = ''
+    if config.repo_dirs:
+        from workstream.repo_discovery import discover_repos
+        found_repos = discover_repos(config.repo_dirs)
+        if found_repos:
+            repo_context = _build_per_workstream_repo_context(
+                workstreams, found_repos, cutoff.isoformat(),
+            )
+
+    # 2. Collect note files from notes_dirs
+    note_files: list[Path] = []
+    for notes_dir_str in config.notes_dirs:
+        notes_dir = Path(notes_dir_str).expanduser()
+        if not notes_dir.is_dir():
+            continue
+        for md_file in sorted(notes_dir.glob('*.md'), reverse=True):
+            note_files.append(md_file)
+
+    # 2b. Filter by lookback: git commit date (primary), mtime (fallback)
+    from workstream.git import file_last_commit_dates
+
+    # Batch-fetch git commit dates for all files
+    git_dates: dict[str, str] = {}
+    if note_files:
+        # Group by parent dir (notes may span multiple dirs)
+        by_parent: dict[Path, list[Path]] = {}
+        for f in note_files:
+            by_parent.setdefault(f.parent, []).append(f)
+        for parent, files in by_parent.items():
+            git_dates.update(file_last_commit_dates(parent, files))
+
+    filtered: list[Path] = []
+    for f in note_files:
+        git_date_str = git_dates.get(str(f))
+        if git_date_str:
+            try:
+                if date.fromisoformat(git_date_str) >= cutoff:
+                    filtered.append(f)
+                continue
+            except ValueError:
+                pass
+        # No git date — fall back to mtime
+        mtime_date = date.fromtimestamp(f.stat().st_mtime)
+        if mtime_date >= cutoff:
+            filtered.append(f)
+
+    skipped = len(note_files) - len(filtered)
+    if skipped:
+        print(f'Filtered {skipped} note file(s) outside {lookback_days}-day lookback.')
+
+    # 3. Filter to unprocessed
+    unprocessed = state.unprocessed_files(filtered)
+    if not unprocessed:
+        print('No new or changed note files to process.')
+        return
+
+    print(f'Found {len(unprocessed)} unprocessed note file(s).')
+
+    # 4. Get LLM agent (required for discovery — no regex fallback)
+    llm_name = config.get_llm_agent()
+    if llm_name:
+        try:
+            agent = LLMAgent(llm_name) if llm_name != 'auto' else LLMAgent.detect()
+        except (ValueError, Exception):
+            agent = None
+    else:
+        agent = None
+
+    if agent is None:
+        print('No LLM agent available. Cannot run discovery without an LLM.')
+        print(f'Configure an LLM agent in {GLOBAL_CONFIG_PATH}')
+        return
+
+    discover_model = config.llm_discover_model
+    model_label = f'{agent.agent} (model={discover_model})' if discover_model else agent.agent
+    print(f'Using {model_label} for discovery.')
+    print()
+
+    # 5. Group files by month (from filename), newest first
+    by_month: dict[str, list[Path]] = defaultdict(list)
+    for f in unprocessed:
+        by_month[_file_month(f)].append(f)
+    months_sorted = sorted(by_month.keys(), reverse=True)
+
+    # 6. Process file by file, grouped by month
+    total_files = len(unprocessed)
+    file_num = 0
+    total_matched = 0
+    total_new = 0
+    total_inbox = 0
+    total_errors: list[str] = []
+
+    for month in months_sorted:
+        month_files = by_month[month]
+        month_matched = 0
+        month_new = 0
+        month_inbox = 0
+        month_thoughts = 0
+        errors_before = len(total_errors)
+
+        print(f'\u2500\u2500 {month} ({len(month_files)} file{"s" if len(month_files) != 1 else ""}) \u2500\u2500')
+
+        for note_file in month_files:
+            file_num += 1
+            size = _file_size_kb(note_file)
+            sys.stdout.write(f'  [{file_num}/{total_files}] {note_file.name} ({size})...')
+            sys.stdout.flush()
+
+            file_content = note_file.read_text(encoding='utf-8')
+            prompt = build_discovery_prompt(
+                file_content, workstreams, note_file.name,
+                repo_context=repo_context,
+            )
+
+            try:
+                response = agent.prompt(
+                    prompt, model=discover_model, thinking='minimal',
+                )
+            except Exception as e:
+                print(f' error: {e}')
+                total_errors.append(f'{note_file.name}: {e}')
+                continue
+
+            associations = parse_association_response(response)
+
+            if not associations:
+                # No thoughts found (or parse failure) — mark processed, move on
+                print(' \u2192 0 thoughts')
+                state.mark_processed(note_file)
+                state.last_sweep = date.today().isoformat()
+                save_sweep_state(state, ws_dir)
+                continue
+
+            # Build Thought objects from LLM response for dispatch
+            thoughts_for_dispatch: list[Thought] = []
+            for assoc in associations:
+                thoughts_for_dispatch.append(Thought(
+                    date=assoc.get('date') or date.today().isoformat(),
+                    text=assoc['thought'],
+                    source_file=str(note_file),
+                ))
+
+            result = dispatch_associations(
+                associations, thoughts_for_dispatch, workstreams, ws_dir
+            )
+
+            # Per-file inline result
+            n = len(associations)
+            parts = [f'{n} thought{"s" if n != 1 else ""}']
+            if result.matched:
+                parts.append(f'{result.matched} matched')
+            if result.new_created:
+                parts.append(f'{result.new_created} new')
+            if result.inbox_count:
+                parts.append(f'{result.inbox_count} inbox')
+            print(f' \u2192 {", ".join(parts)}')
+
+            month_matched += result.matched
+            month_new += result.new_created
+            month_inbox += result.inbox_count
+            month_thoughts += n
+            if result.errors:
+                total_errors.extend(result.errors)
+
+            # Mark file processed and save state (Ctrl+C safe)
+            state.mark_processed(note_file)
+            state.last_sweep = date.today().isoformat()
+            save_sweep_state(state, ws_dir)
+
+        total_matched += month_matched
+        total_new += month_new
+        total_inbox += month_inbox
+
+        # Monthly summary
+        if month_thoughts:
+            print(f'  {month} totals: {month_thoughts} thoughts, {month_matched} matched, {month_new} new, {month_inbox} inbox')
+        print(f'  Running: {total_matched + total_new + total_inbox} thoughts, {total_matched} matched, {total_new} new, {total_inbox} inbox')
+        print()
+
+        # Interactive pause at month boundaries — only when something needs attention
+        month_errors = len(total_errors) - errors_before
+        needs_attention = month_inbox > 0 or month_errors > 0
+        if interactive and needs_attention and month != months_sorted[-1]:
+            remaining_months = months_sorted[months_sorted.index(month) + 1:]
+            remaining_files = sum(len(by_month[m]) for m in remaining_months)
+            try:
+                reply = input(
+                    f'  {len(remaining_months)} month(s) remaining ({remaining_files} files). '
+                    f'Continue? [Y/n/tree] '
+                ).strip().lower()
+            except (EOFError, KeyboardInterrupt):
+                print()
+                reply = 'n'
+            if reply == 'tree':
+                from workstream.commands.tree import build_tree_lines
+                fresh = load_all_workstreams(ws_dir)
+                for line in build_tree_lines(fresh):
+                    print(f'    {line}')
+                print()
+                try:
+                    reply = input('  Continue? [Y/n] ').strip().lower()
+                except (EOFError, KeyboardInterrupt):
+                    print()
+                    reply = 'n'
+            if reply in ('n', 'no'):
+                print('  Stopping. Progress saved \u2014 resume with ws sweep --discover.')
+                break
+
+    # Final summary
+    total_thoughts = total_matched + total_new + total_inbox
+    print(f'Discovery complete: {total_thoughts} thoughts, {total_matched} matched, {total_new} new, {total_inbox} inbox.')
+    if repo_context:
+        print(f'  Repo context included in prompts ({len(found_repos)} repos scanned).')
+    if total_errors:
+        print(f'  {len(total_errors)} error(s):')
+        for err in total_errors[:5]:
+            print(f'    {err}')
+    if total_inbox:
+        print(f'  Review inbox: {ws_dir / "inbox.md"}')
+
+    # Post-sweep: recompute first_activity/last_activity for all workstreams
+    # Belt-and-suspenders: covers existing workstreams that predate activity tracking
+    _recompute_activity_dates(ws_dir, {p.name: p for p in found_repos})
+
+
+# ── Plan Review ─────────────────────────────────────────────────────
+
+
+def _idea_is_duplicate(new_text: str, existing_ideas: list) -> bool:
+    """Check if new idea text substantially overlaps an existing idea.
+
+    Catches exact matches and substring containment for ideas longer than
+    20 characters.  *existing_ideas* is a list of IdeaEntry objects.
+    """
+    new_lower = new_text.lower()
+    for idea in existing_ideas:
+        existing_lower = idea.text.lower()
+        if new_lower == existing_lower:
+            return True
+        if len(new_lower) > 20 and (new_lower in existing_lower or existing_lower in new_lower):
+            return True
+    return False
+
+
+def _build_plan_review_prompt(ws_title: str, ws_context: str,
+                              git_context: str, plan_entries: list[dict]) -> str:
+    """Build an LLM prompt for reviewing plan files against git evidence.
+
+    Each plan_entry has: filename, marker (status string), content (summary or truncated body).
+    """
+    plan_sections = []
+    for entry in plan_entries:
+        section = f'### {entry["filename"]}\n'
+        if entry.get('marker'):
+            section += f'Marker: {entry["marker"]}\n'
+        section += entry['content']
+        plan_sections.append(section)
+
+    plans_block = '\n---\n'.join(plan_sections)
+
+    return f"""You are reviewing plan files for the workstream "{ws_title}".
+
+## Workstream Context
+{ws_context}
+
+## Git Activity
+{git_context}
+
+## Plan Files
+{plans_block}
+
+## Instructions
+
+For each plan file, determine:
+1. Was this plan IMPLEMENTED? (Look for matching commits, branches, or code changes.)
+2. Is it OBSOLETE? (Superseded by another plan, or describes work no longer relevant.)
+3. Does it contain IDEAS for genuinely new work not already tracked?
+   An idea must be: actionable (suggests concrete work), novel (not already
+   captured in the workstream's ideas list), and non-trivial. Observations
+   and restatements of existing plans are NOT ideas. Target: 0-2 per plan.
+
+A plan can be implemented AND still have residual ideas (e.g., a "Future Work" section
+that was never pursued). Small tactical plans (single-commit scope) rarely have ideas.
+
+"Finalized" in the status marker means "approved/ready" — it does NOT mean implemented.
+Cross-reference with git commits to determine actual implementation status.
+
+Return a JSON array:
+[{{
+  "plan": "filename.md",
+  "status": "implemented|obsolete|active",
+  "reason": "Brief explanation with commit evidence if applicable",
+  "ideas": ["Unrealized idea 1", "Unrealized idea 2"]
+}}]
+
+"ideas" is an empty list when there are no unrealized ideas.
+"active" means the plan has unfinished work that is still relevant.
+Do not explain. Return ONLY the JSON array."""
+
+
+def _parse_plan_review_response(response: str) -> list[dict]:
+    """Parse the LLM's JSON response for plan review into classification dicts.
+
+    Returns [] on parse failure. Each dict has: plan, status, reason, ideas.
+    """
+    import json
+
+    text = response.strip()
+    # Strip markdown code fences if present
+    if text.startswith('```'):
+        lines = text.splitlines()
+        lines = [ln for ln in lines if not ln.strip().startswith('```')]
+        text = '\n'.join(lines)
+
+    try:
+        result = json.loads(text)
+    except json.JSONDecodeError:
+        match = re.search(r'\[.*\]', text, re.DOTALL)
+        if match:
+            try:
+                result = json.loads(match.group())
+            except json.JSONDecodeError:
+                return []
+        else:
+            return []
+
+    if not isinstance(result, list):
+        return []
+
+    valid = []
+    for entry in result:
+        if not isinstance(entry, dict):
+            continue
+        if 'plan' not in entry or 'status' not in entry:
+            continue
+        if entry['status'] not in ('implemented', 'obsolete', 'active'):
+            continue
+        ideas = entry.get('ideas', [])
+        if not isinstance(ideas, list):
+            ideas = []
+        ideas = [str(i) for i in ideas if isinstance(i, str)]
+        valid.append({
+            'plan': str(entry['plan']),
+            'status': str(entry['status']),
+            'reason': str(entry.get('reason', '')),
+            'ideas': ideas,
+        })
+    return valid
+
+
+def _build_ws_context(ws) -> str:
+    """Build abbreviated workstream context for plan review prompt."""
+    lines = [f'Status: {ws.status}']
+    # Last 3 thread entries
+    for entry in ws.thread[:3]:
+        snippet = entry.body.splitlines()[0][:100]
+        lines.append(f'  [{entry.date}] {snippet}')
+    # Next actions
+    if ws.next_actions:
+        lines.append('Next actions:')
+        for action in ws.next_actions[:5]:
+            lines.append(f'  - {action}')
+    # Existing ideas (abbreviated)
+    if ws.ideas:
+        lines.append(f'Existing ideas: {len(ws.ideas)}')
+    return '\n'.join(lines)
+
+
+def _build_git_context(repo_path: Path, repo_name: str, since: str = '') -> str:
+    """Build git activity context for a repo.
+
+    When ``since`` is provided (ISO date), only shows commits after that date.
+    Otherwise falls back to last 5 commits.  The interactive agent can always
+    run ``git log`` for deeper investigation.
+    """
+    from workstream.git import recent_commits
+    from workstream.repo_discovery import _default_branch
+    from workstream.git import list_branches
+
+    try:
+        branches = list_branches(repo_path)
+    except Exception:
+        return f'{repo_name}: unable to read git data'
+
+    default = _default_branch(branches)
+    if not default:
+        return f'{repo_name}: no default branch found'
+
+    lines = [f'Repo: {repo_name}, default branch: {default}']
+
+    try:
+        cutoff = since or '2020-01-01'
+        limit = 20 if since else 5  # more generous when scoped to delta
+        commits = recent_commits(repo_path, cutoff, default)[:limit]
+        if commits:
+            label = f'Commits since {since}' if since else 'Recent commits'
+            lines.append(f'{label}:')
+            for c in commits:
+                lines.append(f'  {c["date"]} {c["subject"]}')
+        elif since:
+            lines.append(f'No commits since {since}')
+    except Exception:
+        pass
+
+    # Active branches
+    active = [b for b in branches if b not in ('main', 'master')]
+    if active:
+        from workstream.git import branch_ahead_count
+        lines.append('Active branches:')
+        for b in active[:10]:
+            try:
+                ahead = branch_ahead_count(repo_path, b)
+                lines.append(f'  {b} (+{ahead} ahead)')
+            except Exception:
+                lines.append(f'  {b}')
+
+    return '\n'.join(lines)
+
+
+def _build_sweep_review_manifest(
+    workstreams: list, repo_data: dict[str, dict], ws_dir: Path,
+    findings: dict[str, SweepFindings] | None = None,
+    cutoff: str = '',
+    changed_notes: list[dict] | None = None,
+    notes_root: Path | None = None,
+) -> str:
+    """Build a findings-scoped manifest for interactive sweep review.
+
+    Only workstreams with activity (present in *findings*) get expanded
+    sections.  The manifest is the single document the reviewing agent
+    sees as system-prompt context.
+    """
+    from datetime import date as date_type
+
+    findings = findings or {}
+    today = date_type.today().isoformat()
+    parts: list[str] = ['## Sweep Activity Report', '']
+    if cutoff:
+        parts.append(f'Today: {today} | Cutoff: {cutoff}')
+    else:
+        parts.append(f'Today: {today} | First sweep (no prior baseline)')
+    parts.append(f'Workstreams with activity: {len(findings)}')
+    parts.append('')
+
+    # Changed notes section (global, before per-workstream sections)
+    if changed_notes:
+        parts.append('### Changed Notes')
+        if notes_root:
+            parts.append(f'Notes root: {notes_root}')
+        parts.append('')
+        committed = [n for n in changed_notes if n['status'] == 'committed']
+        unstaged = [n for n in changed_notes if n['status'] != 'committed']
+        if committed:
+            parts.append(f'**Committed since {cutoff or "last sweep"}:**')
+            for n in committed:
+                parts.append(f'- {n["name"]} ({n["path"]})')
+            parts.append('')
+        if unstaged:
+            parts.append('**Unstaged changes:**')
+            for n in unstaged:
+                parts.append(f'- {n["name"]} ({n["status"]})')
+            parts.append('')
+
+        # Include actual note content so the reviewing agent can see
+        # completion signals ("Done:"), progress updates, and decisions
+        # without making separate tool calls.
+        if notes_root and cutoff:
+            from workstream.git import notes_diff_since
+            notes_dirs = [n['path'].rsplit('/', 1)[0] for n in changed_notes]
+            # Deduplicate while preserving order
+            seen: set[str] = set()
+            unique_dirs = [d for d in notes_dirs if d not in seen and not seen.add(d)]  # type: ignore[func-returns-value]
+            diff = notes_diff_since(notes_root, cutoff, unique_dirs, max_lines=100)
+            if diff:
+                parts.append('**Note changes:**')
+                parts.append('')
+                parts.append('```diff')
+                parts.append(diff)
+                parts.append('```')
+                if diff.endswith('... (truncated)'):
+                    pathspec = ' '.join(unique_dirs)
+                    parts.append(f'(truncated — for full diff: `git -C {notes_root} log --since="{cutoff}" -p --no-merges -- {pathspec}`)')
+                parts.append('')
+                parts.append('Look for completion signals ("Done:", "shipped", "launched") and use')
+                parts.append('`ws update-status <id> completed [reason]` for workstreams whose work is finished.')
+                parts.append('Capture follow-up ideas with `ws idea` before completing.')
+                parts.append('')
+
+    if not findings and not changed_notes:
+        parts.append('No activity detected this sweep.')
+        return '\n'.join(parts)
+    ws_by_id = {ws.id: ws for ws in workstreams}
+
+    for ws_id, f in sorted(findings.items(), key=lambda kv: ws_by_id[kv[0]].title):
+        ws = ws_by_id[ws_id]
+        repos_str = ', '.join(ws.repos) if ws.repos else '(none)'
+
+        # Workstream header with branch summary
+        branch_info = ''
+        if ws.branches:
+            br_strs = [f'{b.branch} (+{b.ahead} ahead)' for b in ws.branches[:5]]
+            branch_info = f' | Branches: {", ".join(br_strs)}'
+        parts.append(f'### {ws.title} ({ws.id})')
+        parts.append(f'Repos: {repos_str}{branch_info}')
+        # Filesystem paths so the agent can resolve plan files
+        path_parts: list[str] = []
+        for rname in ws.repos:
+            data = repo_data.get(rname)
+            if data and data.get('path'):
+                path_parts.append(f'{rname}={data["path"]}')
+                pd = data.get('plans_dir')
+                if pd:
+                    path_parts.append(f'plans={pd}')
+        if path_parts:
+            parts.append(f'Paths: {", ".join(path_parts)}')
+        parts.append('')
+
+        # Code velocity warning for workstreams with repos
+        if ws.repos and cutoff:
+            code_date = getattr(ws, 'code_last_activity', '') or ''
+            if not code_date or code_date < cutoff:
+                if code_date:
+                    parts.append(f'\u26a0 No code commits since {code_date} (design-only activity)')
+                else:
+                    parts.append(f'\u26a0 No code commits detected in associated repos')
+                parts.append('')
+
+        # Discovered plans
+        if f.newly_matched:
+            parts.append('**Discovered plans:**')
+            for p in f.newly_matched:
+                ptype = f', {p.plan_type}' if p.plan_type else ''
+                line = f'- `{p.path}` ({p.status}{ptype}) "{p.title}"'
+                if p.date:
+                    line += f' {p.date}'
+                # Triage hints
+                if p.plan_type == 'project' and p.title:
+                    matched_br = _find_matching_branches(p.title, ws.branches)
+                    if matched_br:
+                        br = matched_br[0]
+                        line += f'\n  Branch: `{br.branch}` (+{br.ahead} ahead) — track implementation'
+                    else:
+                        line += '\n  Project plan, no matching branch yet'
+                elif p.plan_type == 'tactical':
+                    line += ' [tactical — commit-scope]'
+                if p.guidance in ('new-peer', 'new-top-level'):
+                    line += f'\n  Suggests: create a new workstream ({p.guidance})'
+                parts.append(line)
+            parts.append('')
+
+        # Signals
+        if f.new_signals:
+            parts.append('**Signals:**')
+            for p in f.new_signals:
+                if p.signal == 'likely-implemented':
+                    parts.append(f'- `{p.path}` [{p.signal}] — branch merged. Auto-classified.')
+                elif p.signal == 'stale':
+                    parts.append(f'- `{p.path}` [{p.signal}] — no recent changes. Still relevant?')
+                else:
+                    parts.append(f'- `{p.path}` [{p.signal}]')
+            parts.append('')
+
+        # Auto-classified
+        if f.auto_classified:
+            parts.append('**Auto-classified (implemented):**')
+            for p in f.auto_classified:
+                parts.append(f'- `{p.path}` — set to implemented (branch merged, all commits landed)')
+            parts.append('')
+
+        # Commits
+        if f.repos_with_commits:
+            for rname, commits in sorted(f.repos_with_commits.items()):
+                parts.append(f'**Commits ({rname}):**')
+                for c in commits[:20]:
+                    parts.append(f'  {c["date"]} {c["subject"]}')
+                parts.append('')
+
+    # Instructions for the reviewing agent
+    parts.append('### Instructions')
+    parts.append('')
+    parts.append('You are reviewing sweep findings — only workstreams with activity are shown above.')
+    parts.append('For each workstream, integrate the findings into the workstream system:')
+    parts.append('- **Discovered plans** — read the plan file, verify classification, recommend branch/ws creation')
+    parts.append('- **Signals** — confirm or override auto-classifications')
+    parts.append('- **Commits** — relate to plans, record checkins for untracked work')
+    parts.append('- **Branches** — map to plans or workstreams')
+    parts.append('')
+    parts.append('Repos are local — use `git log`, `git show`, `git diff` for deeper investigation.')
+    parts.append('Read plan files directly with the read tool.')
+    parts.append('Use the workstream-sweep skill for the full review protocol.')
+    parts.append('')
+
+    return '\n'.join(parts)
+
+
+def _batch_review_plans_handler(config: 'Config', workstreams: list,
+                          repo_data: dict, ws_dir: Path) -> None:
+    """LLM-review plan files for each workstream with repos."""
+    from datetime import date as date_type
+
+    from workstream.llm import LLMAgent
+    from workstream.markdown import (
+        append_idea,
+        append_log_entry,
+        parse_frontmatter,
+        write_frontmatter,
+    )
+    from workstream.models import IdeaEntry, LogEntry
+
+    # Get LLM agent
+    llm_name = config.get_llm_agent()
+    if llm_name:
+        try:
+            agent = LLMAgent(llm_name) if llm_name != 'auto' else LLMAgent.detect()
+        except (ValueError, Exception):
+            agent = None
+    else:
+        agent = None
+
+    if agent is None:
+        print('No LLM agent available. Cannot review plans without an LLM.')
+        return
+
+    discover_model = config.llm_discover_model
+    now_dt = datetime.now().isoformat(timespec='seconds')
+    today_date = date_type.today().isoformat()
+    import sys
+
+    print()
+    print('── Plan Review ──')
+
+    # Filter to workstreams with repos AND matched plans in repo_data
+    reviewed_plans = 0
+    total_ideas = 0
+    for ws in workstreams:
+        if not ws.repos:
+            continue
+        # Collect plan entries from matched repos
+        plan_entries: list[dict] = []
+        git_contexts: list[str] = []
+
+        for repo_name in ws.repos:
+            if repo_name not in repo_data:
+                continue
+            data = repo_data[repo_name]
+            repo_path = data['path']
+
+            git_contexts.append(_build_git_context(repo_path, repo_name))
+
+            for plan in data['plans']:
+                meta = plan['meta']
+                # Build plan entry for prompt
+                filename = plan['path']
+                marker = meta.get('status', '')
+                if meta.get('finalized_at'):
+                    marker += f' {meta["finalized_at"]}'
+
+                # Prefer summary from frontmatter; fall back to truncated content
+                summary = meta.get('summary', '')
+                if summary:
+                    content = summary
+                else:
+                    # Read and truncate the plan file
+                    plan_path = data['plans_dir'] / filename
+                    try:
+                        full_text = plan_path.read_text(encoding='utf-8')
+                        # Skip frontmatter for content truncation
+                        _, plan_body = parse_frontmatter(full_text)
+                        content_lines = (plan_body or full_text).splitlines()[:80]
+                        content = '\n'.join(content_lines)
+                    except Exception:
+                        content = '(unable to read plan file)'
+
+                plan_entries.append({
+                    'filename': filename,
+                    'marker': marker,
+                    'content': content,
+                })
+
+        if not plan_entries:
+            continue
+
+        ws_context = _build_ws_context(ws)
+        git_context = '\n\n'.join(git_contexts) if git_contexts else '(no git data)'
+
+        # Batch plans ~10 per LLM call
+        batch_size = 10
+        total_batches = (len(plan_entries) + batch_size - 1) // batch_size
+        for batch_start in range(0, len(plan_entries), batch_size):
+            batch_num = batch_start // batch_size + 1
+            batch = plan_entries[batch_start:batch_start + batch_size]
+            plan_names = ', '.join(e['filename'][:30] for e in batch[:3])
+            if len(batch) > 3:
+                plan_names += f', ... +{len(batch) - 3}'
+            sys.stdout.write(
+                f'  {ws.title} [{batch_num}/{total_batches}]: reviewing {len(batch)} plans ({plan_names})...'
+            )
+            sys.stdout.flush()
+
+            prompt = _build_plan_review_prompt(ws.title, ws_context, git_context, batch)
+
+            try:
+                response = agent.prompt(prompt, model=discover_model, thinking='minimal')
+            except Exception as e:
+                print(f' error: {e}')
+                continue
+
+            classifications = _parse_plan_review_response(response)
+            if not classifications:
+                print(' no valid classifications')
+                continue
+
+            # Dispatch results
+            if ws.source_path and ws.source_path.exists():
+                text = ws.source_path.read_text(encoding='utf-8')
+                meta, body = parse_frontmatter(text)
+
+                for cl in classifications:
+                    reviewed_plans += 1
+                    # Log every classification
+                    detail = f'{cl["plan"]}: {cl["status"]} — {cl["reason"]}'
+                    body = append_log_entry(body, LogEntry(
+                        date=today_date, event='plan-reviewed', detail=detail,
+                    ))
+
+                    # Dispatch ideas (with dedup)
+                    for idea_text in cl['ideas']:
+                        if _idea_is_duplicate(idea_text, ws.ideas):
+                            continue
+                        body = append_idea(body, IdeaEntry(date=today_date, text=idea_text))
+                        body = append_log_entry(body, LogEntry(
+                            date=today_date, event='plan-idea',
+                            detail=f'from {cl["plan"]}: {idea_text}',
+                        ))
+                        total_ideas += 1
+
+                    # Update the plan file's frontmatter status
+                    for repo_name in ws.repos:
+                        if repo_name not in repo_data:
+                            continue
+                        plan_file_path = repo_data[repo_name]['plans_dir'] / cl['plan']
+                        if plan_file_path.is_file():
+                            try:
+                                plan_text = plan_file_path.read_text(encoding='utf-8')
+                                plan_meta, plan_body = parse_frontmatter(plan_text)
+                                if plan_meta and plan_meta.get('status') != cl['status']:
+                                    plan_meta['status'] = cl['status']
+                                    plan_meta['reviewed'] = today_date
+                                    plan_file_path.write_text(
+                                        write_frontmatter(plan_meta, plan_body),
+                                        encoding='utf-8',
+                                    )
+                            except Exception:
+                                pass  # Don't fail the whole review if one file can't be updated
+                            break  # Found the file, no need to check other repos
+
+                meta['updated'] = now_dt
+                meta['last_activity'] = now_dt
+                ws.source_path.write_text(
+                    write_frontmatter(meta, body), encoding='utf-8'
+                )
+
+            # Complete the inline progress line with results
+            statuses = {}
+            for cl in classifications:
+                statuses[cl['status']] = statuses.get(cl['status'], 0) + 1
+            batch_ideas = sum(len(cl['ideas']) for cl in classifications)
+            parts = [f'{v} {k}' for k, v in sorted(statuses.items())]
+            if batch_ideas:
+                parts.append(f'{batch_ideas} ideas')
+            print(f' → {", ".join(parts)}')
+
+    print(f'Plan review complete: {reviewed_plans} plans reviewed, {total_ideas} ideas extracted.')
+
+
+def _review_plans_handler(config: 'Config', workstreams: list,
+                          repo_data: dict, ws_dir: Path,
+                          batch: bool = False,
+                          findings: dict[str, SweepFindings] | None = None,
+                          cutoff: str = '',
+                          changed_notes: list[dict] | None = None) -> None:
+    """Review plan files — interactive (default) or headless batch mode."""
+    if batch:
+        _batch_review_plans_handler(config, workstreams, repo_data, ws_dir)
+        return
+
+    # Interactive mode: launch omp session with sweep-review skill
+    import os
+    import tempfile
+
+    from workstream.commands.init import _read_skill_content
+
+    notes_root = ws_dir.parent
+
+
+    # Build manifest from authoritative findings
+    manifest = _build_sweep_review_manifest(workstreams, repo_data, ws_dir,
+                                            findings=findings or {}, cutoff=cutoff,
+                                            changed_notes=changed_notes,
+                                            notes_root=notes_root)
+
+    # Write manifest to temp file
+    fd, tmp_name = tempfile.mkstemp(suffix='.md', prefix='ws-plan-review-')
+    os.close(fd)
+    tmp_path = Path(tmp_name)
+    skill = _read_skill_content('workstream_sweep')
+    tmp_path.write_text(skill + '\n\n---\n\n' + manifest, encoding='utf-8')
+
+    # Find omp (preferred) or claude harness
+    from workstream.harness import exec_or_fallback, find_harness
+
+    harness = find_harness()
+    if not harness:
+        print('No interactive harness (omp or claude) found on PATH.')
+        print('Falling back to batch mode.')
+        _batch_review_plans_handler(config, workstreams, repo_data, ws_dir)
+        return
+
+    cmd = [
+        harness,
+        '--append-system-prompt', f'@{tmp_path}',
+        'Begin the sweep review. Read the manifest in your system prompt and follow the skill protocol.',
+    ]
+
+    exec_or_fallback(harness, cmd, tmp_name, cwd=notes_root)
+
+
+def _backfill_summaries(config: 'Config', ws_dir: Path) -> None:
+    """Generate BLUF summaries for workstreams missing them.
+
+    Uses the LLM to synthesize a 1-2 sentence summary from thread entries,
+    plans, and next actions.  Only runs when an LLM agent is available.
+    Skips workstreams that already have summaries or are in terminal status.
+    """
+    from workstream.llm import LLMAgent
+    from workstream.markdown import load_workstream, save_workstream
+
+    llm_name = config.get_llm_agent()
+    if llm_name:
+        try:
+            agent = LLMAgent(llm_name) if llm_name != 'auto' else LLMAgent.detect()
+        except (ValueError, Exception):
+            agent = None
+    else:
+        agent = None
+
+    if agent is None:
+        print('No LLM agent available. Skipping summary backfill.')
+        return
+
+    discover_model = config.llm_discover_model
+    workstreams = load_all_workstreams(ws_dir)
+    candidates = [
+        ws for ws in workstreams
+        if not ws.summary
+        and ws.status not in ('completed', 'dropped')
+        and ws.source_path
+    ]
+
+    if not candidates:
+        print('All workstreams already have summaries.')
+        return
+
+    print(f'Backfilling summaries for {len(candidates)} workstream(s)...')
+    backfilled = 0
+    for ws in candidates:
+        # Build context for the LLM
+        parts = [f'Title: {ws.title}', f'Status: {ws.status}']
+        if ws.tags:
+            parts.append(f'Tags: {", ".join(ws.tags)}')
+
+        if ws.thread:
+            parts.append('Recent thread entries:')
+            for entry in ws.thread[:5]:
+                snippet = entry.body.splitlines()[0][:120] if entry.body else ''
+                parts.append(f'  [{entry.date}] {snippet}')
+
+        if ws.next_actions:
+            parts.append('Next actions:')
+            for action in ws.next_actions:
+                parts.append(f'  - {action}')
+
+        if ws.plans:
+            plan_names = ', '.join(p.title or p.path for p in ws.plans[:5])
+            parts.append(f'Plans ({len(ws.plans)}): {plan_names}')
+
+        context = '\n'.join(parts)
+        prompt = (
+            'Summarize this workstream in 1-2 sentences. '
+            'What is it and where is it heading?\n\n'
+            f'{context}\n\n'
+            'Return ONLY the summary text, no formatting or labels.'
+        )
+
+        try:
+            response = agent.prompt(prompt, model=discover_model, thinking='minimal')
+        except Exception as e:
+            print(f'  skip: {ws.title[:40]} (error: {e})')
+            continue
+
+        summary = response.strip().strip('"').strip()
+        if not summary:
+            continue
+
+        ws.summary = summary
+        save_workstream(ws, ws.source_path)
+        backfilled += 1
+        trunc = summary[:60] + ('...' if len(summary) > 60 else '')
+        print(f'  summary: {ws.title[:40]} -> "{trunc}"')
+
+    print(f'Backfilled {backfilled} summary/summaries.')
+
+
+
+def _sweep_handler(config: Config, discover: bool = False, interactive: bool = False,
+                   lookback: int = 60, review_plans: bool = False,
+                   no_review: bool = False,
+                   batch: bool = False, backfill_summaries: bool = False,
+                   since: str | None = None) -> None:
+    ws_dir = config.workstreams_path
+
+    # Load all workstreams
+    workstreams = load_all_workstreams(ws_dir)
+
+    if not workstreams:
+        print('No workstreams found.')
+        return
+
+    # Determine repos to scan: explicit config repos + auto-discovered repos.
+    # Explicit repos take priority (they may have plans_dir overrides), then
+    # auto-discovered repos fill in the rest.
+    from workstream.repo_discovery import discover_repos
+
+    explicit_names: set[str] = set()
+    repos_to_scan: list[tuple[str, Path]] = []
+    if config.repos:
+        repos_to_scan = [(rc.name, Path(rc.path).expanduser()) for rc in config.repos]
+        explicit_names = {rc.name for rc in config.repos}
+
+    if config.repo_dirs:
+        discovered = discover_repos(config.repo_dirs)
+        new_repos = [(p.name, p) for p in discovered if p.name not in explicit_names]
+        if new_repos:
+            repos_to_scan.extend(new_repos)
+            print(f'  auto-discovered {len(new_repos)} repos from repo_dirs')
+
+    # Deduplicate repos sharing the same remote URL — keep the one with the most
+    # .plans/ files (or first found if tied). Multiple clones of the same repo
+    # produce duplicate plan reviews and inflated branch counts.
+    from workstream.git import remote_url
+    seen_remotes: dict[str, tuple[str, Path]] = {}  # url -> (name, path)
+    deduped: list[tuple[str, Path]] = []
+    for repo_name, repo_path in repos_to_scan:
+        url = remote_url(repo_path)
+        if url and url in seen_remotes:
+            prev_name, prev_path = seen_remotes[url]
+            # Keep whichever has more plans
+            prev_plans_dir = config.get_plans_dir(prev_name, prev_path)
+            cur_plans_dir = config.get_plans_dir(repo_name, repo_path)
+            prev_plans = prev_plans_dir.glob('*.md') if prev_plans_dir.is_dir() else []
+            cur_plans = cur_plans_dir.glob('*.md') if cur_plans_dir.is_dir() else []
+            if sum(1 for _ in cur_plans) > sum(1 for _ in prev_plans):
+                # Replace previous with current
+                deduped = [(n, p) if n != prev_name else (repo_name, repo_path)
+                           for n, p in deduped]
+                seen_remotes[url] = (repo_name, repo_path)
+                print(f'  dedup: {repo_name} supersedes {prev_name} (same remote)')
+            else:
+                print(f'  dedup: skipping {repo_name} (same remote as {prev_name})')
+            continue
+        if url:
+            seen_remotes[url] = (repo_name, repo_path)
+        deduped.append((repo_name, repo_path))
+    if len(deduped) < len(repos_to_scan):
+        dropped = len(repos_to_scan) - len(deduped)
+        print(f'  deduplicated {dropped} repo(s) sharing the same remote')
+    repos_to_scan = deduped
+
+    # Scan each repo
+    repo_data: dict[str, dict] = {}  # repo_name -> {plans, branches, path, plans_dir}
+    for repo_name, repo_path in repos_to_scan:
+        if not repo_path.is_dir():
+            print(f'  skip {repo_name}: directory not found')
+            continue
+
+        plans_dir = config.get_plans_dir(repo_name, repo_path)
+        plans = scan_repo_plans(plans_dir)
+        branches = _scan_repo_branches(repo_path)
+        repo_data[repo_name] = {
+            'plans': plans,
+            'branches': branches,
+            'path': repo_path,
+            'plans_dir': plans_dir,
+        }
+        if plans or branches:
+            print(f'  {repo_name}: {len(plans)} plans, {len(branches)} branches')
+    # Auto-associate repos to workstreams with no repos set
+    if repo_data:
+        # Track which workstreams have no repos before auto-association
+        unassociated = {id(ws) for ws in workstreams if not ws.repos}
+        associated = _auto_associate_repos(workstreams, list(repo_data.keys()))
+        if associated:
+            print(f'  auto-associated repos for {associated} workstream(s)')
+            # Auto-setup newly associated repos (best-effort)
+            from workstream.provisioning import setup_repo
+            for ws in workstreams:
+                if id(ws) not in unassociated:
+                    continue  # was already associated before
+                for rname in ws.repos:
+                    rdata = repo_data.get(rname)
+                    if rdata and rdata.get('path'):
+                        try:
+                            setup_repo(rdata['path'])
+                        except Exception:
+                            pass  # best-effort; user can run ws setup explicitly
+
+    # Match and update workstreams
+    updated_count = 0
+    sweep_findings: dict[str, SweepFindings] = {}  # ws.id -> delta from this sweep
+    for ws in workstreams:
+        ws_slug = slugify(ws.title)
+        new_plans: list[PlanRef] = []
+        new_branches: list[BranchRef] = []
+
+        for rname, data in repo_data.items():
+            new_plans.extend(
+                _match_plans_to_workstream(
+                    ws.title, ws_slug, ws.id,
+                    ws.repos, rname, data['plans'],
+                )
+            )
+            new_branches.extend(
+                _match_branches_to_workstream(ws_slug, rname, data['branches'])
+            )
+
+        # -- Heuristic signal detection for active plans --
+        now_dt = datetime.now().isoformat(timespec='seconds')
+        today_date = date.today().isoformat()
+        signal_plans: list[PlanRef] = []
+        for plan in new_plans:
+            if plan.status != 'active':
+                continue
+            # Check if associated branch was merged into main/master
+            repo_path = repo_data.get(plan.repo, {}).get('path')
+            if repo_path:
+                # Look for a branch matching the workstream slug
+                branches_in_repo = repo_data[plan.repo].get('branches', [])
+                for br in branches_in_repo:
+                    if ws_slug in br['branch']:
+                        try:
+                            if branch_is_merged(repo_path, br['branch']):
+                                plan.signal = 'likely-implemented'
+                                signal_plans.append(plan)
+                                break
+                        except Exception:
+                            pass
+            # Check for staleness via plan file mtime
+            if not plan.signal and repo_path:
+                plans_dir = repo_data.get(plan.repo, {}).get('plans_dir')
+                plan_file = plans_dir / plan.path if plans_dir else repo_path / '.plans' / plan.path
+                if plan_file.is_file():
+                    try:
+                        mtime = datetime.fromtimestamp(plan_file.stat().st_mtime)
+                        age_days = (datetime.now() - mtime).days
+                        if age_days > 90:
+                            plan.signal = 'stale'
+                            signal_plans.append(plan)
+                    except Exception:
+                        pass
+
+        # Only log signals that are genuinely new (not already on the stored plan)
+        prev_signals = {(p.repo, p.path): p.signal for p in ws.plans}
+        new_signal_plans = [
+            p for p in signal_plans
+            if prev_signals.get((p.repo, p.path)) != p.signal
+        ]
+        if new_signal_plans:
+            for plan in new_signal_plans:
+                ws.log.append(LogEntry(
+                    date=today_date, event='sweep-signal',
+                    detail=f'{plan.path}: {plan.signal}',
+                ))
+                print(f'  signal: {ws.title} — {plan.path}: {plan.signal}')
+
+        # Auto-classify high-confidence signals
+        auto_classified = _auto_classify_plans(signal_plans, repo_data)
+        for plan in auto_classified:
+            ws.log.append(LogEntry(
+                date=today_date, event='plan-auto-classified',
+                detail=f'{plan.path}: implemented (auto)',
+            ))
+            print(f'  auto-classified: {ws.title} — {plan.path} → implemented')
+
+        # Detect newly-matched plans (not in previous plan list)
+        prev_plan_paths = {(p.repo, p.path) for p in ws.plans}
+        newly_matched = [
+            p for p in new_plans
+            if (p.repo, p.path) not in prev_plan_paths
+        ]
+        if newly_matched:
+            for plan in newly_matched:
+                ws.log.append(LogEntry(
+                    date=today_date, event='plan-discovered',
+                    detail=f'{plan.repo}/.plans/{plan.path} ({plan.status})',
+                ))
+                print(f'  new plan: {ws.title} — {plan.repo}/.plans/{plan.path}')
+
+        # Compare by content, not order — render_body sorts by date-desc,
+        # but freshly-matched plans arrive in scan order (alphabetical).
+        _pk = lambda p: (p.repo, p.path, p.status, p.title, p.date, p.signal)
+        _bk = lambda b: (b.repo, b.branch, b.ahead)
+        plans_changed = sorted(new_plans, key=_pk) != sorted(ws.plans, key=_pk)
+        branches_changed = sorted(new_branches, key=_bk) != sorted(ws.branches, key=_bk)
+        changed = plans_changed or branches_changed or bool(new_signal_plans) or bool(auto_classified)
+        if changed:
+            ws.plans = new_plans
+            ws.branches = new_branches
+            ws.updated = now_dt
+            ws.last_activity = now_dt
+            if ws.source_path:
+                save_workstream(ws, ws.source_path)
+                updated_count += 1
+                print(f'  updated: {ws.title} ({len(new_plans)} plans, {len(new_branches)} branches)')
+
+        # Accumulate findings for workstreams with activity
+        if newly_matched or new_signal_plans or auto_classified:
+            sweep_findings[ws.id] = SweepFindings(
+                newly_matched=newly_matched,
+                new_signals=new_signal_plans,
+                auto_classified=auto_classified,
+            )
+
+    print(f'Sweep complete: {updated_count} workstream(s) updated.')
+
+    # Update durable plan index
+    from workstream.plan_index import load_plan_index, save_plan_index, update_plan_index
+    plan_index = load_plan_index(ws_dir)
+    index_changed = False
+    for ws in workstreams:
+        ws_slug = slugify(ws.title)
+        if update_plan_index(plan_index, ws_slug, ws.plans):
+            index_changed = True
+    if index_changed:
+        save_plan_index(plan_index, ws_dir)
+        print(f'  plan index updated ({sum(len(v) for v in plan_index.values())} entries)')
+
+    # Post-sweep: recompute activity dates with repo data
+    _recompute_activity_dates(ws_dir, {name: path for name, path in repos_to_scan})
+
+    # Record last_sweep timestamp — capture the previous value for cutoff resolution
+    from workstream.sweep_state import load_sweep_state, save_sweep_state
+    state = load_sweep_state(ws_dir)
+    prev_last_sweep = state.last_sweep  # when the prior sweep ran
+    cutoff = _resolve_cutoff(since, prev_last_sweep)
+    state.last_sweep = date.today().isoformat()
+    save_sweep_state(state, ws_dir)
+
+    # Fill repos_with_commits for workstreams with findings
+    if sweep_findings and cutoff:
+        from workstream.git import recent_commits
+        ws_by_id = {ws.id: ws for ws in workstreams}
+        for ws_id, findings in sweep_findings.items():
+            ws_obj = ws_by_id[ws_id]
+            for rname in ws_obj.repos:
+                data = repo_data.get(rname)
+                if data:
+                    commits = recent_commits(data['path'], cutoff)
+                    if commits:
+                        findings.repos_with_commits[rname] = commits
+
+    # Collect changed notes for review manifest
+    notes_root = ws_dir.parent
+    changed_notes: list[dict] = []
+    if config.notes_dirs and cutoff:
+        from workstream.git import file_last_commit_dates, modified_files
+
+        # Committed notes since cutoff
+        for notes_dir_str in config.notes_dirs:
+            notes_dir = Path(notes_dir_str).expanduser()
+            if not notes_dir.is_dir():
+                continue
+            md_files = sorted(notes_dir.glob('*.md'))
+            if not md_files:
+                continue
+            git_dates = file_last_commit_dates(notes_dir, md_files)
+            for f in md_files:
+                gd = git_dates.get(str(f))
+                if gd and gd >= cutoff:
+                    changed_notes.append({
+                        'path': str(f), 'name': f.name, 'status': 'committed',
+                    })
+
+        # Unstaged changes in notes root
+        try:
+            dirty = modified_files(notes_root)
+            for rel_path in dirty:
+                abs_path = notes_root / rel_path
+                if abs_path.suffix == '.md' and any(
+                    str(abs_path).startswith(d) for d in config.notes_dirs
+                ):
+                    # Don't duplicate if already in committed list
+                    if not any(n['path'] == str(abs_path) for n in changed_notes):
+                        changed_notes.append({
+                            'path': str(abs_path), 'name': abs_path.name,
+                            'status': 'modified',
+                        })
+        except Exception:
+            pass  # git not available in notes root
+
+    # Auto-commit modified notes
+    if config.auto_commit_notes and changed_notes:
+        from workstream.git import git_add, git_commit
+        modified_note_paths = [
+            Path(n['path']) for n in changed_notes if n['status'] == 'modified'
+        ]
+        if modified_note_paths:
+            today_str = date.today().isoformat()
+            if git_add(notes_root, modified_note_paths):
+                if git_commit(notes_root, f'notes: {today_str}'):
+                    print(f'  auto-committed {len(modified_note_paths)} modified note(s)')
+                    for n in changed_notes:
+                        if n['status'] == 'modified':
+                            n['status'] = 'committed'
+
+    if backfill_summaries:
+        _backfill_summaries(config, ws_dir)
+
+    # -- Plan review phase --
+    # Default: interactive review runs unless --no-review is set.
+    # --review-plans is deprecated (it's now the default behavior).
+    if review_plans:
+        import sys
+        print('Note: --review-plans is now the default. Use --no-review to skip.', file=sys.stderr)
+
+    if not no_review and (sweep_findings or changed_notes or review_plans):
+        _review_plans_handler(config, workstreams, repo_data, ws_dir,
+                             batch=batch, findings=sweep_findings, cutoff=cutoff,
+                             changed_notes=changed_notes or None)
+
+    if discover:
+        _discover_handler(config, workstreams, ws_dir, interactive=interactive,
+                         lookback_days=lookback)
+
+def get_command() -> Command:
+    cmd = Command(_sweep_handler, name='sweep', doc='Scan repos for plans and branches, update workstreams.')
+    cmd.add('--discover', parse_as=True, doc='Run iterative discovery: scan notes for thoughts and associate via LLM')
+    cmd.add('--interactive', parse_as=True, doc='Pause at month boundaries when inbox items or errors need attention')
+    cmd.add('--lookback', parse_as=int, missing=60, doc='Lookback period in days for discovery (default: 60)')
+    cmd.add('--review-plans', parse_as=True, doc='(deprecated, now default) LLM-review plan files')
+    cmd.add('--no-review', parse_as=True, doc='Skip interactive plan review (mechanical scan only)')
+    cmd.add('--batch', parse_as=True, doc='Use headless batch mode for plan review (default: interactive)')
+    cmd.add('--backfill-summaries', parse_as=True, doc='Generate BLUF summaries for workstreams missing them (uses LLM)')
+    cmd.add('--since', doc='Cutoff for activity detection (ISO date, relative like "2h"/"1d", default: last sweep)')
+    return cmd