gitstow 0.2.6__tar.gz → 0.2.8__tar.gz

{gitstow-0.2.6 → gitstow-0.2.8}/.github/workflows/publish.yml

@@ -5,7 +5,26 @@ on:
     tags: ["v*"]
 
 jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src/
+
+      - name: Test
+        run: pytest --tb=short
+
   publish:
+    needs: test
     runs-on: ubuntu-latest
     environment: pypi
     permissions:

gitstow-0.2.8/AGENTS.md

@@ -0,0 +1,150 @@
+# gitstow - AI Developer Guide
+
+## What is this?
+
+A CLI tool that manages collections of git repositories across multiple workspaces. Think "package manager for repos" - whether they're open-source projects you learn from or active projects you work on.
+
+## Operating Contract
+
+- Prefer proper long-term solutions over shortcut patches. If a feature is incomplete in one surface, build the feature into that surface instead of papering over it with wording, partial conditionals, or one-off display logic.
+- Do not recommend quick fixes, temporary patches, or narrow workarounds unless the user explicitly asks for a shortcut.
+- Read the relevant existing code before proposing or editing. Let the current architecture decide where the change belongs.
+- Keep changes scoped to the requested behavior. Avoid unrelated refactors, formatting churn, or drive-by cleanups.
+- Do not revert user changes or generated local state unless the user explicitly asks.
+
+## Product Standards
+
+- Keep CLI, TUI, web dashboard, JSON output, docs, and tests semantically aligned when changing user-facing status behavior.
+- For repo state presentation, avoid using "dirty" as a broad user-facing bucket for every local change. Present it as local/uncommitted changes with the composition visible: modified, staged, and untracked counts.
+- Keep local working-tree state separate from remote relationship state. For example: local changes, clean, ahead, behind, diverged, frozen, missing.
+- When improving the web dashboard, implement the actual missing dashboard feature and shared classification/model behavior instead of copying a CLI-only assumption into the template.
+
+## Key Concept: Workspaces
+
+Repos are organized into **workspaces** - directories with a label and layout mode:
+- **structured** layout: `workspace/owner/repo/` (open-source collections)
+- **flat** layout: `workspace/repo/` (active projects, no owner subdirectory)
+
+Each workspace can have auto-tags applied to all repos it discovers.
+
+## Architecture
+
+```
+src/gitstow/
+├── cli/          # Typer commands (thin — delegates to core)
+│   ├── main.py          # App entry, command registration, global --workspace flag
+│   ├── helpers.py       # Shared workspace resolution, repo lookup, iteration
+│   ├── add.py, pull.py, list_cmd.py, status.py, remove.py  # Core commands
+│   ├── workspace_cmd.py # workspace list/add/remove/scan subcommands
+│   ├── manage.py        # freeze/unfreeze/tag/untag/info subcommands
+│   ├── exec_cmd.py, search.py, open_cmd.py, stats.py       # Power commands
+│   ├── export_cmd.py    # export/import collection
+│   ├── shell.py         # Shell integration (fzf, aliases)
+│   ├── tui.py           # TUI launcher
+│   ├── serve.py         # Web dashboard launcher
+│   ├── migrate.py, config_cmd.py, onboard.py, doctor.py, skill_cmd.py
+│   └── __init__.py
+├── core/         # Business logic (git ops, URL parsing, state)
+│   ├── paths.py       # Path constants, central repos.yaml resolution
+│   ├── config.py      # Workspace + Settings dataclasses, load/save
+│   ├── repo.py        # Repo dataclass + RepoStore (nested YAML CRUD)
+│   ├── url_parser.py  # URL → (host, owner, repo) extraction
+│   ├── git.py         # All git subprocess calls
+│   ├── discovery.py   # Walk directory tree (structured + flat), reconcile
+│   ├── parallel.py    # Async execution with semaphore
+│   └── __init__.py
+├── tui/          # Textual interactive dashboard
+│   ├── app.py         # Main TUI application
+│   └── __init__.py
+├── web/          # FastAPI browser dashboard (gitstow ui)
+│   ├── server.py          # FastAPI app, uvicorn runner, app.state.server stash
+│   ├── static/app.css     # Dark theme, Bricolage Grotesque + JetBrains Mono
+│   ├── templates/         # Jinja2 — base.html + page templates + partials/
+│   └── routes/            # dashboard.py, repos.py, workspaces.py, collection.py, pages.py, system.py
+└── skill/        # Codex skill (SKILL.md)
+    └── SKILL.md
+```
+
+**Key rules:**
+1. CLI never touches git directly - it calls `core/git.py`
+2. `core/repo.py` (RepoStore) is the only module that reads/writes `repos.yaml`
+3. `core/config.py` defines Workspace dataclass - all workspace logic flows from here
+4. `cli/helpers.py` provides `resolve_workspaces()`, `resolve_repo()`, `iter_repos_with_workspace()`
+
+## Key Files
+
+- `core/config.py` - Workspace + Settings dataclasses. `get_workspaces()` with legacy migration shim.
+- `core/repo.py` - Repo with workspace field, RepoStore with nested YAML format, legacy auto-migration.
+- `core/discovery.py` - `discover_repos(root, layout)` supports structured and flat layouts.
+- `core/url_parser.py` - URL parsing (the hardest part). Test changes here thoroughly.
+- `core/git.py` - All git subprocess calls. Uses `git status --porcelain=v2 --branch` for single-call efficiency.
+- `core/parallel.py` - Async execution with semaphore (max 6 concurrent).
+- `cli/helpers.py` - Shared workspace resolution used by all CLI commands.
+- `cli/workspace_cmd.py` - workspace list/add/remove/scan subcommands.
+- `cli/main.py` - Typer app, global `-w/--workspace` option, command registration.
+- `tui/app.py` - Textual dashboard with DataTable, filter, pull, freeze toggle.
+
+## Data Files
+
+- `~/.gitstow/config.yaml` - Settings (workspaces list, default host, SSH pref).
+- `~/.gitstow/repos.yaml` - Repo metadata nested by workspace label. Central location.
+
+### repos.yaml format
+```yaml
+oss:
+  anthropic/Codex:
+    remote_url: https://github.com/anthropic/Codex.git
+    tags: [ai]
+active:
+  gitstow:
+    remote_url: https://github.com/rishmadaan/gitstow.git
+    tags: [active]
+```
+
+## All Commands (32)
+
+**Core:** `add`, `pull`, `fetch`, `list`, `status`, `remove`, `migrate`
+**Workspace:** `workspace list`, `workspace add`, `workspace remove`, `workspace scan`
+**Repo management:** `repo freeze`, `repo unfreeze`, `repo tag`, `repo untag`, `repo tags`, `repo info`
+**Power:** `exec`, `search`, `open`, `stats`
+**Sharing:** `collection export`, `collection import`
+**Shell:** `shell pick`, `shell init`, `shell completions`, `shell setup`, `tui`, `ui`
+**Setup:** `onboard`, `config show/set/path/migrate-root`, `doctor`, `install-skill`, `setup-ai`, `update`
+
+## Development
+
+```bash
+cd ~/labs/projects/gitstow
+pip install -e ".[dev]"
+pytest                    # 44 tests
+ruff check src/
+pip install -e ".[tui]"   # For TUI development
+```
+
+## Patterns
+
+- `--json -j` and `--quiet -q` on all main commands
+- Global `-w/--workspace` flag filters all commands to a single workspace
+- `cli/helpers.py` for workspace resolution (don't repeat in each command)
+- Rich console for stdout, err_console for stderr
+- Typer with `rich_markup_mode="rich"`, `typer.Context` for global options
+- YAML for persistence (not JSON, not SQLite)
+- asyncio with semaphore for parallel git ops
+- `git status --porcelain=v2 --branch` for single-call status (vs gita's 4-5 calls)
+- Repo.global_key (`workspace:key`) for unique identification across workspaces
+- Legacy format auto-migration (flat repos.yaml -> nested, root_path -> workspaces)
+
+## AI Integration
+
+**Primary: Codex skill** (`src/gitstow/skill/SKILL.md`)
+- Installed to `~/.Codex/skills/gitstow/` via `gitstow install-skill` or `gitstow onboard`
+- Auto-updates on version bumps (checks `.version` marker on every CLI invocation)
+- Zero context cost when inactive - only loaded when task matches the skill description
+- Codex runs gitstow CLI commands via Bash - full access to all commands
+
+**Optional: MCP server** (`src/gitstow/mcp/server.py`)
+- For non-Codex AI tools (Codex Desktop, Cursor, Windsurf)
+- Install: `pip install gitstow[mcp]`, entry point: `gitstow-mcp`
+- 13 tools + 3 resources, wraps same `core/` modules as CLI
+- **Tradeoff:** MCP tools are always loaded into context (costs tokens even when idle).
+  The skill has no such cost. Only use MCP for dedicated repo-management setups.

{gitstow-0.2.6 → gitstow-0.2.8}/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to gitstow will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.2.8] - 2026-07-12
+
+### Fixed
+
+- **Pasted GitHub browse URLs now resolve correctly.** URLs like `/tree/...`, `/blob/...`, `/pull/...` now resolve to the repo root instead of being misparsed.
+- **`config migrate-root`** now actually updates workspace paths, and honors the global `-w/--workspace` flag.
+- **`repo freeze/unfreeze/tag/untag`** now honor `-w/--workspace` and report cross-workspace ambiguity clearly instead of guessing.
+- **`pull --json` and `fetch --json`** always emit pure JSON on stdout — no more banners or progress lines interleaved with the payload.
+- **Pull summary** keeps per-workspace identity for same-named frozen repos in different workspaces.
+- **Bulk git operations** no longer hang on credential prompts and are now locale-independent.
+- **`remove --delete`** refuses to delete paths that resolve outside the workspace root.
+- **Workspace labels** are now validated (lowercase alphanumeric, dash, underscore only).
+
+### Added
+
+- **Atomic, cross-process-locked writes** to `repos.yaml`, safe for concurrent CLI and web UI use.
+- **Test gate before PyPI publish** — releases now require a passing test suite.
+
+### Security
+
+- **Web dashboard CSRF protection.** POST routes now reject cross-origin and DNS-rebinding requests on the localhost UI.
+
+## [0.2.7] - 2026-05-28
+
+### Fixed
+
+- **`gitstow onboard`** now uses Beaupy's `default_is_yes` confirmation parameter, fixing first-run setup crashes on confirmation prompts.
+- **AI integration setup** now renders MCP warning text with balanced Rich markup during onboarding and `gitstow setup-ai`.
+
 ## [0.2.5] - 2026-04-19
 
 ### Added

{gitstow-0.2.6 → gitstow-0.2.8}/CLAUDE.md

@@ -119,6 +119,15 @@ pip install -e ".[tui]"   # For TUI development
 - Repo.global_key (`workspace:key`) for unique identification across workspaces
 - Legacy format auto-migration (flat repos.yaml → nested, root_path → workspaces)
 
+## Product & Implementation Standards
+
+- Prefer proper long-term solutions over shortcut patches. If a feature is incomplete in one surface, build the feature into that surface instead of papering over it with wording, partial conditionals, or one-off display logic.
+- Do not recommend quick fixes, temporary patches, or narrow workarounds unless the user explicitly asks for a shortcut.
+- Keep CLI, TUI, web dashboard, JSON output, docs, and tests semantically aligned when changing user-facing status behavior.
+- For repo state presentation, avoid using "dirty" as a broad user-facing bucket for every local change. Present it as local/uncommitted changes with the composition visible: modified, staged, and untracked counts.
+- Keep local working-tree state separate from remote relationship state. For example: local changes, clean, ahead, behind, diverged, frozen, missing.
+- When improving the web dashboard, implement the actual missing dashboard feature and shared classification/model behavior instead of copying a CLI-only assumption into the template.
+
 ## AI Integration
 
 **Primary: Claude Code skill** (`src/gitstow/skill/SKILL.md`)

{gitstow-0.2.6 → gitstow-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitstow
-Version: 0.2.6
+Version: 0.2.8
 Summary: A git repository library manager — clone, organize, and maintain collections of repos you learn from
 Project-URL: Homepage, https://github.com/rishmadaan/gitstow
 Project-URL: Repository, https://github.com/rishmadaan/gitstow

gitstow-0.2.8/docs/building/audit-2026-07-06.md

@@ -0,0 +1,149 @@
+# gitstow — Full Audit (v0.2.7)
+
+**Date:** 2026-07-06
+**Auditor:** Claude (Fable 5), full read of all source (~9.5k lines Python), planning docs, tests, CI, packaging
+**Baseline:** commit `1aefe9a`, 139 tests passing
+**Status:** Awaiting greenlight — see [Implementation Waves](#implementation-waves)
+
+This document is the working tracker for the post-audit improvement effort. Each finding
+has an ID for reference. Check items off as waves land.
+
+---
+
+## 1. Planned but never done
+
+Commitments in `docs/building/implementation-plan.md` and `CLAUDE.md` that the code does not fulfill.
+
+| ID | Finding | Where |
+|----|---------|-------|
+| P1 | **Parallel `add` clones.** Plan: "Multiple URLs are cloned concurrently (semaphore = parallel_limit)." Implementation is a sequential for-loop. | `cli/add.py:105` |
+| P2 | **Remote-mismatch conflict detection.** Plan: existing dir with a different remote → "error, explain conflict". Instead `add` silently registers whatever is on disk, even when its remote differs from the requested URL. | `cli/add.py:141` |
+| P3 | **Reconciliation on `list`/`status`/`pull`.** Plan design decision #2: reconcile disk-vs-store on these commands and show untracked repos as "untracked" with a hint. Only `doctor` reconciles. | `cli/list_cmd.py`, `cli/status.py`, `cli/pull.py` |
+| P4 | **The status-presentation standard (CLAUDE.md "Product & Implementation Standards") is implemented on no surface.** The standard: don't use "dirty" as a broad bucket; show modified/staged/untracked composition; keep local working-tree state separate from remote relationship state. Reality: CLI shows combined `dirty(N)`; web `_classify` only reads `status.dirty` so **staged-only or untracked-only repos display as "clean"**; TUI computes dirty as `total − clean − frozen`. Three divergent classifiers. | `cli/status.py:168`, `web/routes/dashboard.py:62`, `tui/app.py:224` |
+| P5 | **TUI acknowledged broken** (BACKLOG.md) and parked. Decision needed: triage or retire. | `tui/app.py` |
+| P6 | **CHANGELOG missing the 0.2.6 entry.** `release.sh` bumps versions but never enforces a changelog entry. | `CHANGELOG.md`, `scripts/release.sh` |
+
+## 2. Correctness bugs
+
+| ID | Severity | Finding | Where |
+|----|----------|---------|-------|
+| B1 | High | **Deep URLs parse to garbage** (verified live). `github.com/owner/repo/tree/main/src` → owner `owner/repo/tree/main`, repo `src`, clone URL `.../tree/main/src.git`. Any pasted `/tree/`, `/blob/`, `/pull/`, `/issues/` link — the most common real paste — creates a bogus nested dir and failing clone. Nested-group (GitLab) handling needs host-aware guards. | `core/url_parser.py:134` |
+| B2 | High | **`config migrate-root` broken post-workspaces.** Sets legacy `settings.root_path`, but `Settings.to_dict()` drops `root_path` whenever workspaces exist, and workspace paths are never updated. Files move; config still points at old location; all repos show "missing". `config set` docstring still advertises `root_path`, which the command rejects. | `cli/config_cmd.py:223`, `core/config.py:86` |
+| B3 | High | **repos.yaml writes are neither atomic nor locked.** Advertised workflow is CLI + web UI running simultaneously; concurrent load-modify-save loses updates; crash mid-write corrupts the file. Needs temp-file + `os.replace` + file lock. | `core/repo.py:149` |
+| B4 | High | **No `GIT_TERMINAL_PROMPT=0` / `LC_ALL=C` on git subprocesses.** One auth-prompting repo hangs every bulk pull for the full timeout; "Already up to date" string-match breaks on non-English locales. | `core/git.py:83`, `core/git.py:160` |
+| B5 | Med | **`repo freeze/unfreeze/tag/untag` ignore `-w` and mishandle ambiguity.** They call `store.get(key)` directly; same key in two workspaces → `_resolve_global_key` returns `None` → misleading "not tracked". `freeze --tag` updates by bare key and can hit the wrong workspace's repo. | `cli/manage.py:62,54` |
+| B6 | Med | **Web pull-all pulls dirty repos; CLI never does.** Cross-surface semantic mismatch (ff-only limits damage). | `web/routes/repos.py:153` vs `cli/pull.py:35` |
+| B7 | Med | **`collection import` loses workspace assignment and fails silently on newer versions.** Exports carry per-repo `workspace`; import dumps everything into one workspace. Newer-version file → bare `typer.Exit(1)` with a "caller should print error" comment; nothing is printed. | `cli/export_cmd.py:189,258` |
+| B8 | Med | **`workspace remove` silently orphans repos.** Default `--keep-repos` leaves repos.yaml entries pointing at a nonexistent workspace — invisible to `list`/`status`/web; `doctor` doesn't flag them either. | `cli/workspace_cmd.py:118` |
+| B9 | Low | **`open --editor` is a dead flag**; editor detection prefers `code`/`cursor` over `$EDITOR`; terminal `$EDITOR` (vim) launched via `Popen` with no TTY. | `cli/open_cmd.py:24,116` |
+| B10 | Low | **`pull` frozen bookkeeping uses `r.key` not `global_key`** — same-named repos in two workspaces collapse into one "frozen" summary line. | `cli/pull.py:112` |
+| B11 | Low | **No label validation on `workspace add`** — `:` or `/` in a label breaks `global_key` parsing and web routes. | `cli/workspace_cmd.py:67` |
+| B12 | Low | **CLI `remove --delete` has no path-containment check**; web delete route defensively verifies path is under workspace root. CLI should get the same guard. | `cli/remove.py:66` vs `web/routes/repos.py:377` |
+| B13 | Low | **`_resolve_global_key` dead code**: final line re-tests `len(matches) == 1` after that branch already returned; ambiguous vs missing indistinguishable to callers. | `core/repo.py:215` |
+
+## 3. Efficiency
+
+| ID | Finding | Where |
+|----|---------|-------|
+| E1 | **Web dashboard status is sequential AND blocks the event loop.** `_build_repos_data` runs `get_status` (subprocess) per repo, serially, inside `async def`, on every render + every 30s auto-refresh. 100 repos ≈ multi-second loads. `core/parallel.run_parallel` exists and is used for pulls — not for status. | `web/routes/dashboard.py:122` |
+| E2 | **`store.update()` rewrites the whole YAML per repo.** Pull-all over 50 repos = 50 full-file rewrites (CLI, web, fetch all do this in loops). Needs batch-update / deferred save. | `core/repo.py:259` + callers |
+| E3 | **`add` clones sequentially** (also P1). | `cli/add.py:105` |
+| E4 | **`search` is sequential** across repos; `exec` is parallel. | `cli/search.py:82` |
+| E5 | **`get_disk_size` rglobs every file in Python** (`stats`, `repo info`) — very slow on large repos. Use `du -sk` or parallelize. | `core/git.py:280` |
+| E6 | **Clone timeout hardcoded 300s** — kernel-sized repos fail by design; not configurable. | `core/git.py:141` |
+
+## 4. Architecture
+
+| ID | Finding | Notes |
+|----|---------|-------|
+| A1 | **Status classification exists in 3 divergent copies** (CLI, web `_classify`, TUI). Fix for P4 is a single `core/status_model.py` classifier consumed by all surfaces + JSON. Highest-leverage refactor in the codebase. | |
+| A2 | **Web stack (fastapi, uvicorn, jinja2, python-multipart) ships as core deps** for every install, including pure-CLI users. `cli/serve.py` already handles ImportError gracefully, so a `[ui]` extra is nearly free. Deliberate v0.2.0 choice — revisit (tradeoff: onboarding friction vs install weight). | Decision needed |
+| A3 | **MCP server (704 lines) reimplements add/pull/list** instead of sharing an operations layer → drift risk (already lacks `last_fetched`; `list --json` omits it too, so no JSON consumer can see fetch state). | `mcp/server.py`, `cli/list_cmd.py:91` |
+| A4 | **~300 lines of copy-paste across CLI commands**: `pull.py`/`fetch.py` retry+progress+summary loops nearly identical; the same tag/owner/frozen filter block appears in six commands. Natural home: `core/operations.py` (filters + bulk-runner), which is also what web/MCP should call. | |
+
+## 5. Security
+
+| ID | Severity | Finding | Where |
+|----|----------|---------|-------|
+| S1 | High | **Web UI has zero CSRF protection.** All mutations are POSTs; any website can fire cross-origin form POSTs at `http://127.0.0.1:7853` (delete repos from disk, add attacker-URL repos, shutdown). Localhost binding does not prevent this. Fix: reject requests whose `Origin`/`Host` isn't localhost (or session token). The stated design goal "arbitrary git execution must not be LAN-reachable" has this gap. | `web/routes/*.py` |
+
+## 6. Deployment & CI
+
+| ID | Finding | Where |
+|----|---------|-------|
+| D1 | **`publish.yml` ships to PyPI without running tests.** Tag push → build → publish; CI is not a gate. Add test job as dependency of publish. | `.github/workflows/publish.yml` |
+| D2 | **CI ubuntu-only** while classifiers claim macOS + Windows and development happens on macOS. Add macOS to matrix at minimum. | `.github/workflows/ci.yml` |
+| D3 | **`release.sh` doesn't require a CHANGELOG entry** (proven by missing 0.2.6). | `scripts/release.sh` |
+| D4 | **`typer[all]` is a deprecated extra** in modern Typer (harmless noise). | `pyproject.toml:33` |
+| D5 | **No tests for `fetch` CLI, MCP server, or TUI.** | `tests/` |
+
+## 7. Docs drift
+
+| ID | Finding |
+|----|---------|
+| DOC1 | CLAUDE.md says "44 tests" (actual 139); command count worth re-verifying after changes. |
+| DOC2 | BACKLOG.md references `.github/workflows/release.yml`; actual file is `publish.yml`. |
+| DOC3 | `list --json` omits `last_fetched` though tracked (also A3). |
+| DOC4 | `config set` help/docstring advertises `root_path`, which is rejected (also B2). |
+
+---
+
+## Implementation Waves
+
+Execution model per repo convention: Fable designs/reviews; implementation delegated to
+Opus (substantial) / Sonnet (mechanical) subagents.
+
+**Detailed task-by-task plans (TDD steps, code, commands):**
+- Wave 1: [plans/2026-07-06-wave-1-correctness-safety.md](plans/2026-07-06-wave-1-correctness-safety.md)
+- Wave 2: [plans/2026-07-06-wave-2-status-model.md](plans/2026-07-06-wave-2-status-model.md)
+- Wave 3: [plans/2026-07-06-wave-3-structure-polish.md](plans/2026-07-06-wave-3-structure-polish.md)
+
+**Product decisions locked 2026-07-06:**
+1. Web stack moves to an optional `[ui]` extra (ships in 0.3.0) — A2.
+2. The broken Textual TUI is retired, not repaired (moved to Wave 2 Task 1 so the
+   status model only needs two consumer surfaces) — P5.
+3. Bulk pull skips only modified/staged repos; untracked-only repos ARE pulled
+   (CLI + web adopt the same rule) — informs B6/P4.
+
+**Release strategy:** Wave 1 → 0.2.8 (patch). Waves 2 + 3 → 0.3.0 together
+(TUI removal + `[ui]` extra are the breaking changes justifying the minor bump).
+
+### Wave 1 — Correctness & safety (Opus) — COMPLETE (2026-07-12)
+- [x] B1 deep-URL parsing guards (host-aware; GitHub/known hosts reject >2 path segments, strip `/tree|blob|pull|issues/...`)
+- [x] B3 atomic writes (temp + `os.replace`) + file locking on repos.yaml
+- [x] B4 `GIT_TERMINAL_PROMPT=0`, `LC_ALL=C` in `_run_git`; drop locale-dependent string matching where possible
+- [x] B2 fix or explicitly retire `config migrate-root` for the workspace era (+ DOC4)
+- [x] B5 route `repo freeze/unfreeze/tag/untag` through `resolve_repo` with `-w` support; distinguish ambiguous from missing (B13)
+- [x] S1 Origin/Host check middleware on all POST routes
+- [x] D1 test gate before PyPI publish
+- [x] B12 path-containment check in CLI `remove --delete`
+- [x] B11 workspace label validation
+
+### Wave 2 — Shared status model (Opus) — NOT STARTED
+- [ ] P5 retire the Textual TUI (decision: retire; clears the third surface before the refactor)
+- [ ] A1/P4 `core/status_model.py`: one classifier separating local composition (modified/staged/untracked counts) from remote relationship (in-sync/ahead/behind/diverged) + frozen/missing overlays
+- [ ] Consume from CLI `status`, web dashboard, and `--json` payloads (per CLAUDE.md standards)
+- [ ] B6 one pull rule on both surfaces: modified/staged skip, untracked-only pulls (decision locked)
+- [ ] E1 parallelize web status gathering via `run_parallel` (off the event loop)
+- [ ] E2 batch RepoStore updates — `bulk()` (single save per bulk op)
+- [ ] Tests covering the classifier matrix
+
+### Wave 3 — Structure & polish (Sonnet-heavy, Opus for A3/A4) — NOT STARTED
+- [ ] P1/E3 parallel `add` clones; P2 remote-mismatch conflict error
+- [ ] E4 parallel `search`
+- [ ] A4 `core/operations.py` extraction (filters + bulk runner); collapse pull/fetch duplication
+- [ ] A3 MCP server consumes operations layer; add `last_fetched` everywhere (DOC3); new `fetch_repos` tool
+- [ ] P3 reconciliation hints surfacing untracked repos in `list`/`status` (human output only; JSON shapes unchanged)
+- [ ] B7 import preserves workspace; loud version error. B8 orphaned-workspace detection in doctor + workspace remove warning
+- [ ] B9 `$VISUAL`/`$EDITOR`-first open logic; terminal editors run foreground
+- [ ] A2 web stack → `[ui]` extra (decision locked; ships 0.3.0)
+- [ ] E5 `du`-backed disk sizing; E6 configurable `clone_timeout` setting
+- [ ] D2 macOS CI; D3 changelog gate in release.sh; D4 typer extra; D5 fetch/MCP tests
+- [ ] DOC1/DOC2 docs sync
+
+## Verification notes
+
+- All 139 tests pass at baseline (`pytest -q`, 2.82s).
+- B1 verified by executing the parser against deep URLs.
+- B2 verified by reading `Settings.to_dict()` serialization guard (`core/config.py:86`).
+- B3/B4/S1 verified by code inspection; no runtime exploit performed.