ARCHITECTURE section 10 now lists all three deliberate version holds together — rusqlite 0.37, TypeScript 6, and ESLint 10 without eslint-plugin-react — each with the compile or lint failure that forces it. Dependabot will keep proposing every one of them, and a reviewer looking at those PRs needs the reason in the version manifest rather than buried in a commit message. ROADMAP Phase 1 gains a "where to pick up" section: CI is green on the published commit, and the next four things are closing the two Dependabot PRs that would break the build, watching ci-integration.yml actually run for the first time rather than assuming it passes, the owner-only repo settings, and the SP-5 tangle environment that is still the outstanding M1 exit criterion. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
10 KiB
PipDock — Roadmap
Version 0.1 · 2026-07-17
Phase 0 — Spike week (before any feature code) — RUN 2026-07-27
The entire architecture stands on assumptions that must be verified on a real machine first (the FrameLedger/QuoteAtlas discipline). Each spike is a small script + captured fixtures committed to crates/pipdock-core/tests/fixtures/.
Outcomes — full write-up in spikes/README.md.
| Spike | Verdict | The one thing that changed |
|---|---|---|
| SP-1 | GO — ship both engines | Neither engine holds packages back on install -U <pkg>; both silently break installed dependents. Every plan must restate the full installed set as explicit requirements. uv's conflict attribution is better than pip's; uv writes its plan to stderr, not stdout. uv minimum pinned at 0.10.0. |
| SP-2 | Corpus captured; blocker found and fixed | pip install --dry-run --report - crashes with UnicodeEncodeError on Windows/cp1252 (pip 25 and 26). Every pip invocation must set PYTHONIOENCODING=utf-8 + PYTHONUTF8=1. Also: yanked releases exit 0 (a preview warning, not a failure), and pip/uv disagree on Requires-Python enforcement. |
| SP-3 | PASS | 858 k projects; cold refresh 2.95 s (budget 60 s); worst keystroke 42.1 ms (budget 50 ms) — but only in memory: scanning SQLite per keystroke costs 218 ms. Margin is thin on fast hardware, and raw nucleo ranking puts requests-ntlm above requests. |
| SP-4 | Answered | --path cannot be combined with --no-deps; freeze-file mode (-r <freeze> --no-deps -f json) is the only option. SECURITY §6 confirmed. Findings arrive with duplicate advisory ids. |
| SP-5 | Answered by SP-1 | No engine reports held-back items at all. Resolved version, latest version and blocker must all be derived by PipDock — for pip as much as for uv, contrary to ARCHITECTURE §3's implication. |
| SP-6 | Answered | uv python list returns downloadable entries and duplicate shims; env_hash must lowercase the interpreter path on Windows or pins and snapshots split in two. probe.py -I hides 24 user-site packages on a system Python — open decision. Microsoft Store Python still unverified. |
Both adapter-behaviour questions were decided 2026-07-27 and are implemented: PipDock enforces Requires-Python itself so the preview is engine-independent (crates/pipdock-core/src/compat.rs, ARCHITECTURE §3), and probe.py keeps -I while reporting hidden_user_site so the Installed screen can disclose the gap accurately (SECURITY §2). Two non-blocking questions remain at the end of spikes/README.md: search ranking scope, and how to obtain the five error fixtures this machine cannot produce.
| # | Spike | Question to answer | Exit criterion |
|---|---|---|---|
| SP-1 | uv dry-run shape | Exact stdout of uv pip install -U --dry-run (current + previous uv) across: clean upgrade, held-back, impossible. Is held-back attribution derivable, or does uv only show the resolved set? |
Fixture set committed; adapter parsing strategy written; uv minimum version pinned. Go/no-go for launching with both engines — if uv's plan output is too lossy, v1.0 ships pip-primary with uv behind a "beta engine" flag. |
| SP-2 | pip report & stderr corpus | Capture --dry-run --report JSON + real stderr for every ERROR-CATALOG build/network/permission case (broken sdist, MSVC-missing, PEP 668, locked file, yanked, hash mismatch). |
≥ 1 fixture per launch catalog code. |
| SP-3 | PEP 691 index economics | Full name-index size, download time on VN broadband, SQLite ingest time, fuzzy-search latency on ~600 k names. | < 60 s cold refresh, < 50 ms search on the i7-14700KF and on a low-end reference VM; else design delta/compression fallback. |
| SP-4 | pip-audit foreign-env mode | Correct invocation for auditing an env the tool isn't installed in (freeze-file --no-deps vs newer options). |
Command line + JSON fixture pinned (P1 feature, but flags decided now). |
| SP-5 | Held-back attribution accuracy | On a real numpy/scipy/pandas pin tangle: does graph-based blocker attribution match reality? | Preview sentences verified by hand against the tangle; ambiguity fallback path exercised. |
| SP-6 | Windows env discovery sweep | PEP 514 registry + py -0p + Microsoft Store Python + uv-managed on a real machine; Store-Python aliasing quirks. |
Discovery module design note updated; Store Python either supported or explicitly detected-and-explained. |
Phase 1 — M1 "Core + CLI" — substantially complete 2026-07-27
Engine trait + both adapters (per SP-1 outcome), probe.py, discovery, index cache + search, plan/resolve/execute two-phase, snapshots, pins, guard graph, error catalog, CLI over all of it. Exit: TESTING L1+L2+L4 green in CI; pipdock update --all survives the SP-5 tangle env with correct summary; dogfood on Kokone's own bot venvs begins.
What works
Every P0 CLI command except health: env list|use, list [--outdated], search, info, install, update, uninstall, pin add|remove|list, snapshot list|create|diff|rollback, doctor, pip-upgrade, engine [pip|uv], index refresh, schema, self report-bug. 173 tests; cargo fmt, clippy -D warnings and npm audit clean.
Verified against real environments, not only unit tests:
- the held-back conflict from SP-1 is reported and attributed —
httpcore 0.15.0 (latest 1.0.9)/httpx 0.23.0 requires httpcore <0.16.0,>=0.15.0— which no engine produces; update --allresolves the same tangle to latest, applies it, and leavespip checkclean;snapshot rollbackrestores an environment exactly (PRD §6's "env diff vs snapshot = ∅");- the uninstall guard refuses to break
requestsand exits non-zero, per CLI-SPEC §7; - exit codes match CLI-SPEC §5.
Findings that changed the design
plan_requirements |
Every resolve restates the installed set, or both engines break installed dependents at exit 0 (SP-1). |
-U in the dry-run argv |
Without it pip plans nothing and every package looks held back for no reason. The unit test had encoded the omission instead of the document. |
| Search ranking | Tiered, not score-ordered, and ranked by selection rather than a full sort: 90.5 ms → 16.5 ms against a 50 ms budget. |
SnapshotProof |
--no-snapshot is a named waiver, not an Option, so forgetting a snapshot cannot look like deliberately waiving one. |
Not yet done
health— belongs to M3 with the tools venv (CODE-HEALTH-SPEC).- TESTING L2 in CI —
ci-integration.ymlis written but has never run; it needs a push to GitHub and the repo settings from RELEASE-CI §5. - TESTING L4 —
assert_cmdis a dependency and the clap surface is covered, but the golden-output tests per command are not written. - The SP-5 tangle env — the exit criterion names a real numpy/scipy/pandas environment. The httpx/httpcore construction proved the mechanism; the large-environment run is still owed, and is the natural first dogfooding step.
- Settings beyond engine choice — locale, thresholds and the PEP 668 override land with the GUI in M2.
Where to pick up
Pushed to main and green: CI / Rust, CI / Node and CodeQL all pass on the published commit. Three configuration bugs were fixed getting there, each recorded in its own commit message: caller workflows must grant at least what the callee declares (a startup_failure with no logs), cargo audit was pinned to a toolchain too old to build itself, and its informational advisories needed scoping rather than silencing.
Immediate, in rough order:
- Close the two Dependabot PRs that would break the build — TypeScript 7 and rusqlite 0.40. Both are the holds listed in ARCHITECTURE §10, and their CI already fails. The
actions/setup-*bumps are fine to merge. - Let
ci-integration.ymlrun. It has never executed: it triggers on PRs touching engine/plan/snapshot/graph paths, or nightly. Watch the first run rather than assuming it passes — it is the only thing standing behind the L2 exit criterion. - Repo settings — branch protection, secrets, and the updater keypair, per RELEASE-CI §5. None of these are committable and all are owner-only.
- Dogfood on a real environment — the SP-5 numpy/scipy/pandas tangle, which is both the outstanding M1 exit criterion and the first honest test of the held-back sentences at scale.
Then M2. The core carries everything the GUI needs; ui/src/ipc fixes the command names, the design tokens and EN/VI catalogs are scaffolded, and the shell renders.
Phase 2 — M2 "GUI shell + core flows" (~3–4 weeks)
Tauri app, design tokens, Environments/Installed/Updates/Search/Pins screens, preview + 3-way conflict UX, console drawer, summary sheet, snapshots UI, legal gate, EN/VI catalogs, settings. Exit: all UI-SPEC click budgets met by manual count; L3 green; VI sweep clean.
Phase 3 — M3 "Health + polish" (~2 weeks)
Tools venv, deptry/vulture/ruff runners + report UI + gated fix, pip upkeep, bug-report deep link, offline states, keyboard map, icon/branding pass. Exit: CODE-HEALTH flows pass on two real projects (one pyproject, one requirements-only).
Phase 4 — RC → v1.0 (~1–2 weeks)
Release pipeline live (signing, updater, checksums), manual charter executed, docs/README screenshots, legal files public, updater tested from RC→GA. Exit: RELEASE-CI §5 checklist fully checked; v1.0.0 published + notify fan-out.
Post-1.0 (P1 wave)
Security tab (pip-audit), pin auto-suggest, requirements/constraints export-import, cache manager, command palette, dependency graph view, scheduled check. Then P2 candidates by demand: macOS/Linux, per-env engine, elevation broker, winget, JP locale.
Standing risks
| Risk | Mitigation |
|---|---|
| uv output churn between releases | weekly latest-engine parser CI job (TESTING L1) + PD-ENG-003 graceful degrade + "switch to pip" escape hatch |
| pip UX flags deprecations (e.g. report format changes) | same job covers pip; adapter version-gates per engine version |
| Index size growth | SP-3 fallback design kept in the drawer |
| Scope creep from Health into a linter IDE | CODE-HEALTH §7 non-goals are contractual |