Its python.exe links to the Python it was made from, and env_hash
followed the link, so the venv's pins, snapshots and cached graph,
report and audit were filed under its base. Nothing showed it while no
screen could list the two apart; Add interpreter now can. A venv's own
interpreter, recognised by its pyvenv.cfg, is resolved only up to its
folder. No other path's identity changes, and a linked venv's earlier
pins and snapshots stay with the base they were filed under.
Checked against a real --symlinks venv: `env use` stores the venv with
its own prefix, and the venv and its base keep two identities.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A venv made with --symlinks is run and stored as itself, not as the base
Python its python.exe links to: validate_interpreter returned the
canonical path, so `--env .venv update --all --yes` would have changed
the system Python. Canonicalizing now only decides where a link leads
and whether it is PipDock's own; a link to another program is refused,
and a Microsoft Store alias (os error 1920) is judged by its own path.
The GUI merges and removes an added row by its path rather than by
envHash, which follows links: a re-add replaces a broken row, removal
sticks for an entry whose file is gone (a share), and neither runs
during a scan. Added entries are validated again on every listing in
both heads (envs::probe_listed), and the CLI checks its stored default
when it uses it. `env remove` makes a typed path absolute first.
SECURITY section 2 and env_probe's doc claimed an enforcement point over
IPC; they now say what is checked, and backlog X36-b records the rest.
notify.yml reports a Triage failure on a pull request.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The repository now lives in the poli0981org organization, and this makes it at home there.
- main was red since 2026-11-18: RUSTSEC-2026-0543 (chrono), in Cargo.lock only through serde_with's weak features and compiled into nothing; ignored with its reason and exit condition.
- Supersedes #113–#118 (Rust 1.100.0, rusqlite 0.42.0, Tauri 2.12.6, code-health pins, actions, npm) plus jsdom 31.0.1; minimatch 11 closes GHSA-g3hv-75wg-m249. rfd 0.18 (#112) is held again until tauri-plugin-dialog moves.
- Dependabot's tauri groups never worked (it picks the most specific group); exclude-patterns on the catch-alls fix it.
- CI is self-contained: no workflow calls poli0981/.github; every action is pinned by commit; notify.yml vendors the Discord notifier.
- npm licences: scripts/check-licenses.mjs, deny.toml's allowlist for the npm half. Required, with cargo deny and tauri lockstep — eight required checks.
- Qodana in two parts (Rust, TS/JS), full scans, a triaged Rust baseline, fail on anything new. The Rust container needed its toolchain and CARGO_HOME pointed somewhere writable before it analysed anything.
- SonarQube Cloud analyses into poli0981org_pipdock; every npm ci runs with --ignore-scripts (S6505).
- Every repository URL points at the organization. README's attestation command for 1.4.0/1.5.0 had stopped working; it now says --owner poli0981 --signer-repo poli0981/pipdock.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Visually-hidden text is position: absolute, and with no positioned ancestor
it is laid out against the viewport, outside every scroller above it. A pin
chip's hidden sentence did that on Pins: a long list made the whole window
scroll and took the header with it. Every parent of hidden text is relative.
- A run that failed before producing a summary rendered no <h1>, so the focus
rule had nothing to land on. The branch has a heading.
- The console drawer stays open across runs, so the next run mounts it with no
opener to return focus to. It falls back to the Console button.
- Under forced-colors the selection outline followed the focus ring at equal
specificity and replaced it on a focused current tab.
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
changelog/1.x.md gains 1.5.0, written by reader: keyboard, screen reader,
contrast theme, everyone. It says that Narrator was not run again on this
release and that zoom was built and held back.
ROADMAP records the slice: the decisions and why, and the defects that were in
code with green tests and were found by driving the installed build over
WebView2's debugging port — the high-contrast border that had never been
drawn, the buttons that dropped focus when they went busy, the legal gate, two
accessible names. U45, U47 and U48 close; A1-A7 open, each with what it is
waiting for, and A7 is the testing only a person can do.
ACCESSIBILITY.md, UI-SPEC and TESTING are corrected to what the build actually
does: no zoom, a double border, busy as aria-disabled. CLAUDE.md carries the
rules the slice left behind and the recipe that found the defects.
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
- cargo update (~60 bumps, 627 -> 616 crates) clears the yanked async-executor 1.14.0 that
had turned cargo audit red on main and on every Dependabot PR since 2026-11-03 (Linux-only,
never in the shipped binary). rusqlite 0.41.1 (SQLite 3.54.1), no code change. rfd 0.17 with
tauri-plugin-dialog 2.8.4, which met the rfd ignore's own condition, so the ignore goes.
- npm: thirteen packages to latest; TypeScript still held at 6.0.3 (typescript-eslint peers <6.1).
- Tools: ruff 0.17.3, certifi, msgpack, platformdirs; constraints regenerated.
- Actions: taiki-e/install-action v2.87.32, sonarqube-scan-action v8.4.0; Node 24 -> 26 LTS.
"Latest" means the newest release past each ecosystem's Dependabot cooldown.
- pip 26.3 renders an unloadable build backend as `error: backend-unavailable`, which fell
through to PD-BLD-003; a classifier rule restores PD-BLD-002. Found by the drift job; live
corpus re-captured with pip 26.3 / uv 0.13.7, the 26.2.1 capture frozen as pip-26.2/, and a
test holds both renderings to one code.
- Docs: ARCHITECTURE §10 re-verified, ERROR-CATALOG, TESTING, ROADMAP, CLAUDE.md.
Supersedes #97, #98, #99, #100, #101.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The analysis that first sent 1.4.0 still measured from 2026-09-27; the
next measured from the last analysis of the version before (2026-10-20).
The docs said the version did not move it at all. They now say when it
does, what that means for the merge carrying a release bump, and what
main's gate read after #91.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
The first CI analysis of main failed its gate: 16 Rust bugs and new-code
coverage 78.3 % against 80 %, over all of 1.4.0 (sending a version did not
move the previous-version baseline).
- rust:S6677 x3: a failure's message is logged as `error`, not as a second
`message` field (CLI, update flow, app startup); golden.rs reads the
CLI's log to hold it, and failed first.
- rust:S7493 x13: std::fs inside async fns goes through tokio::fs (tools
venv sync, deptry's report, export/requirements/report commands).
- Tests for 1.4.0 code nothing drove: rollback end to end, forcing a
latest this Python cannot run, PEP 691 parsing (L55), user_file_error
(U25), a plan verified in another environment, PyPiReleases' cache, and
the plan/env stores' success and late-error paths. InstallSet::only had
no caller and is removed.
- ROADMAP, TESTING and CLAUDE.md record what the analysis found.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Automatic analysis could not build, so it never analysed the Rust two
thirds of the code and imported no coverage; it also sent no project
version, leaving the previous-version new-code period anchored to the
first analysis. sonar.yml runs on Windows, produces cargo-llvm-cov and
vitest LCOV plus clippy's JSON, and scans with sonarqube-scan-action
v8.3.0 (pinned), passing the version from package.json. The token
reaches the scan step alone; the job is skipped without one (Dependabot,
forks) and refuses a dispatch off main, which this plan cannot analyse.
Unblocks the required audits, red on main since 2026-10-21:
rustls-webpki 0.103.16, webpki-root-certs 1.0.11, clipboard-win 5.4.3,
zod 4.6.7. Dependabot groups vitest with @vitest/*.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every spec checked against the code rather than against itself, in four passes that each read the
branch's commits and then the source:
- CLI-SPEC/CLI-GUIDE: one JSON document per command (with the per-command table and the paths
that print nothing), environment selection, logging, Ctrl-C and exit 130, the prompts as they
are rather than the [A]bort and countdown that never existed, `.heldBack`, a `pipdock audit`
section, and the rules every mutating command now follows.
- ARCHITECTURE/DATA-FLOW/ERROR-CATALOG: the Engine trait's real signatures, Requires-Python's
three checkpoints, store v4 and the log folder, §7's return types and events, the state machine
with re-probing and Force latest, where each §9 invariant is enforced, and 35 codes in 32 rows.
- SECURITY/TESTING/RELEASE-CI/CODE-HEALTH-SPEC: the PEP 668 override as built, four browser hosts
and the exact capability set, attested releases, the new CI, the tools constraints, and test
tiers that describe what runs rather than what was planned.
- UI-SPEC/PRD/README/I18N: the screens as they render, the keyboard, tokens and their contrast
sweep, the feature matrix's status, attestation instructions, and I18N's one stated exception.
ROADMAP gets the 1.4.0 record — what was wrong, what running found that reading did not, what was
deliberately not done — and the **Audit backlog**: every finding not fixed, with where it is and
why it waited. CLAUDE.md's counts and contradictions are corrected, with the rules this release
left behind. changelog/1.x.md has the 1.4.0 entry, including "Changed for scripts" and "You will
see this once". AI-DISCLOSURE, README and About say which model and who released what. The legal
documents' effective date moves to the release date.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
UI-SPEC §4 gains the screen and **loses the sentence it contradicted**.
It said the third row action folds all three into a `⋮` menu "with the
budget intact"; that makes uninstall four clicks where §5's table
records three, hand-counted. The correction is written as a correction
rather than an overwrite, because the reason it slipped through is the
useful part: four is under the ceiling of five, and a ceiling is not a
ratchet — a table of measured counts is. §5 gains the row, §6 the
component, ARCHITECTURE §4 the forward direction and the whole-graph
value.
**The dangling cross-reference is repaired by writing what it promised.**
`ROADMAP.md` has pointed at "the analysis above" for what blocks P1-6
and P1-7 since 1.2.0, and no such analysis was anywhere in the document
— the survey lived only outside the repository, and the sentence had
been copied into CLAUDE.md as well. P1-6's half is its slice record.
P1-7's is now written too, and counted against the tree rather than
recalled: no toast component, no notification/autostart/tray dependency,
one plan-scoped `tokio::spawn` and zero intervals in either head, and no
surface that can report a failure at 03:00 while `logs_tail` is still
`NOT_YET`. Drafting this commit I nearly shipped a CLAUDE.md line
claiming that survey existed before I had written it, which is the same
defect one layer up.
Version in five places, moved together: the workspace inherits it, so
`Cargo.toml`, `package.json` and `tauri.conf.json` are the only hand
edits and the two lockfiles are regenerated. Hand-editing `Cargo.lock`
would have been wrong twice over — `scopeguard` and `simd_cesu8` are
also at 1.2.0 and `fs_extra` was already at 1.3.0. `cargo metadata
--locked` passes, which is the one-command check.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Found while surveying P1-6. None is caught by any suite, which is the
common thread rather than a coincidence.
`docs/ARCHITECTURE.md`'s `audit_run` row was the only row in the §7
command table missing its trailing pipe, so the table rendered wrong
from 1.2.0. Every gate passed: the command is registered, declared and
documented, and `documented()` strips only the *leading* pipe, so the
row parsed correctly and nothing looked at its shape. A spec sentence
is not a test — and neither is a spec table. The new
`the_architecture_table_is_well_formed` asserts the shape as well as the
contents, and was mutation-checked against the row it was written for.
`catalog.rs`'s comment read "Rust has 33; docs tabulates 30" three
lines above `assert_eq!(Code::ALL.len(), 34)`. Both numbers were one
behind; the doc tabulates 31, folding PD-HLT-001..004 into one row.
CLAUDE.md's error-code checklist named three schemas embedding `Code`
while saying "four", and 1.2.0 made it genuinely four by adding
`AuditReport` via `ToolProblem.code` — five snapshot files in all. So
anyone adding a code today would leave `golden__schema-AuditReport.snap`
stale. The line now says to grep `PD-ENV-001` across the snapshots
rather than trust the list, because that is how the omission was found.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Two conventions, written down where each is enforced rather than remembered.
**`changelog/`, one file per major line.** A single growing file is the thing this
avoids: a reader should open `1.x.md` and find their version without scrolling past
releases they do not care about. Root `CHANGELOG.md` is a pointer, because two places to
write a release note is one place to forget.
A pre-release line gets its **own** file, named for the line it leads to, and is not
folded in when that line goes stable — the beta file is what says *when* a behaviour
changed during the run-up, and merging it would double the length of the file people
actually read while losing exactly that.
The split rule is stated in terms of **reading length rather than release count**, since
that is the property being defended: past roughly 600 lines, split into contiguous minor
ranges and leave the old name as a stub so no link breaks. Range files are never
renumbered — `1.0-1.4.md` does not become `1.0-1.6.md` at the next split.
Entries are backfilled for 1.0.0, 1.1.0 and 1.2.0, written for a *user*: what changed,
what they have to do about it, and — for 1.2.0 — that the legal gate will appear once,
which is the kind of thing a release note exists to say before someone reports it as a
bug. Deliberately no commit counts: a number written about the repository inside the
repository goes stale on commit, which AI-DISCLOSURE learned three times.
**One session, one slice, one version.** Depth over breadth, plus a hotfix release when
one is needed. It is in CLAUDE.md's conventions because that is what the next session
reads first.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Version in all five places — `Cargo.toml`, `Cargo.lock`, `package.json`,
`package-lock.json`, `tauri.conf.json` — and `cargo metadata --locked` verified after,
which is the one-command check that would have caught the `thiserror` lockfile
breakage that had `main` red for a day in Phase 4.
The ROADMAP stage record, and three rules in CLAUDE.md that the diff does not show:
- **A spec can promise a field that has never existed.** SECURITY §6 and PRD P1-1 both
asked for a severity pip-audit publishes under neither vulnerability service, and §6
named a venv the code had refused since P2. Found by running the tool and reading its
JSON, not by reading the specs against each other. When a spec describes an external
tool, the tool is the authority.
- **A watchdog is a unit, not a number.** Borrowing Code Health's 120 s gave an audit a
linter's budget for a network fetch, and it fired on the first real run. A borrowed
constant carries its original units with it.
- **Adding a field to a struct that is summed is a bug the suite will not see.**
`total_bytes` kept adding three entries after a fourth arrived, with every cache test
green.
Post-1.0 is down to two items: the dependency-graph view and the scheduled check.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The stage table in ROADMAP's Post-1.0 section, plus three entries in CLAUDE.md that
are not derivable from the diff:
- a hand-written fixture that matches the documentation while the code does not is
worse than none, because it makes a test asserting the right thing prove the wrong
one — which is exactly how the doubled blocker sentence shipped for two milestones
under a green `PdPreviewDiff.test.tsx`;
- a sentence assembled in Rust is a sentence the other head assembles again, so
invariant 4 is not only about translation;
- `sed -i` must never touch `tests/fixtures/`: Git Bash rewrites in text mode and
strips the CRs that `.gitattributes`' `-text` exists to preserve.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
§7 opens with "A command that is not listed here does not exist; adding one means
amending this section in the same commit." The 1.1.0 P1 wave broke that rule five
times: `pin_suggestions`, `env_export`, `requirements_read`, `cache_usage` and
`cache_clear` are registered, wrapped and shipping, and appear nowhere in the
document. 35 rows against 38 registered commands.
The rows are added, and so is a fourth drift test. The three that existed police
`lib.rs`, `COMMANDS` and `NOT_YET` against each other and not one of them reads the
document making the promise — the assertion message of `every_registered_command_is_
declared` even claimed it did, so that message is narrowed to what it actually
checks. `documented()` parses §7's table the way `registered()` parses the handler
macro, and the new test runs both directions: a row for a command nobody registered
is the same lie as a command nobody documented, it just fails later. Checked by
deleting the `cache_clear` row, which fails it by name.
Two stale counts with it. `golden.rs` said "25 as of Phase 3 P3" and there are 30, so
the number is removed rather than reset — the list is directly below it and
`schema_lists_exactly_the_documented_types` already holds it to the binary's. CLAUDE
said 58 goldens; there are 64, now pinned to 1.1.0 per the counting-trap rule.
ROADMAP's screenshot note was **not** stale, which only looking established: the
seven pre-About shots really do show an eight-entry sidebar. The sentence just reads
as though `screenshot/` held seven files when it holds eight. Reworded, and while
there: `about.png` shows nine entries and a build panel reading 1.0.0, so every shot
is now stale in at least one way.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Five places again — Cargo.toml, Cargo.lock, package.json, package-lock.json,
tauri.conf.json — and `cargo metadata --locked` earned its place in the checklist by
failing on the first attempt, exactly the way `main` was broken this morning. The
shipped CLI reports `pipdock 1.1.0`.
The stage record covers all four slices and the four things running them said that
reading could not: 94 suggestions on a real environment, a parser that turns prose
into a package name, a cache manager for a logs directory that does not exist, and a
palette that ranked an action above the screen it belongs to.
**One PRD row corrected rather than ticked.** P1-4 asked for the engine caches
(`pip cache`, `uv cache`) as well as PipDock's own. Those belong to the engine, live
outside `%LOCALAPPDATA%\PipDock\`, and purging them is a subprocess rather than a
file delete — a different feature wearing the same word. The row says "partly
shipped" and names what is missing, and the roadmap's open list carries it.
UI-SPEC §1's "signature moves" sentence stops saying the palette is P1; §8 gains
Ctrl+K; §4 gains the Disk usage section and why it lists three artefacts.
Two rules into CLAUDE.md, both paid for this afternoon: a parser correct for trusted
input is a hole for untrusted input, and check a thing exists before shipping a size
and a Clear button for it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The stage record in the established shape, plus the estimate kept beside it for
comparison — its central claim held: most of pin auto-suggest was already written and
had never been called.
Three corrections, all found by doing the work rather than by planning it:
- **Six registration places for a new command, not five.** `golden.rs` keeps its own
copy of `SCHEMA_TYPES`, guarded by a test that reads the real list back out of the
binary. The checklist now says so, and says that blessing
`golden__schema-unknown-type.snap` is expected rather than suspicious.
- **`/hold/i` matches "threshold".** `PdPins.test.tsx` uses that pattern to prove the
screen offers no way to create a Hold pin, so any copy on Pins containing the
substring breaks a test about something else. Recorded in CLAUDE.md as the general
rule: grep a screen's test for regex assertions before adding copy to it.
- **`ReverseDeps::build`'s doc contradicted `dependent_count`.** Also recorded in
CLAUDE.md, generalised: a comment describing an intent nothing implements leaves
the next reader with two readings and no way to choose.
UI-SPEC §4 loses its `(P1)` marker and gains why the section sits above the list, why
it is silent on failure, and why the Settings label avoids one word. PRD P1-2 is
marked shipped with the in-force-edges qualifier. The rough edge that is deliberately
not fixed — unpinning re-offers — is written down rather than left to be rediscovered.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
All six open items are done, recorded with what was actually exercised rather than
"the charter was run": three machines (a real Windows 11 box that had never run
PipDock, Windows Sandbox, a Windows 10 VM), no SmartScreen prompt on any — with the
caveat that reputation is per-hash and unsigned binaries can still warn a future
user, which is why the checksum instructions stay. The three owed charter items plus
a non-ASCII Windows *username*, which is a different case from the non-ASCII path
because the username is in %LOCALAPPDATA% and therefore in the data root, the logs
and the tools venv.
The icon is a decision now, not a deferral. It was called a placeholder because
nobody had chosen it.
RELEASE-CI §5 ticks all eight, and three of the last four turned out to be already
done and never ticked — CodeQL default setup was already not-configured, Discussions
were already on, the secrets were set today. §2's "main protected" claim is true for
the first time; its exact settings, the reason CI / Integration is excluded (a
paths-filtered required check never starts, so it blocks forever), the two contexts
owned by the ops repo, and how to unwedge it are all written down.
Also recorded: the four things Phase 4 found that were not on its list, and the three
rules the About tab settled. Post-1.0 gains the Third-Party-Notices generation
deferred here, a screenshot re-capture, and the OSV host the Security tab will need.
Two long-standing self-contradictions fixed: NOT_YET is two (lib.rs is the
authority; ROADMAP and CLAUDE.md each said two in one paragraph and three or four in
another), and 15 of UI-SPEC §6's 16 components exist, not 16.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`legal/THIRD-PARTY-NOTICES.md` was not the only document listing a dependency the
project deliberately does not have. ARCHITECTURE §9, TESTING §3 and CLAUDE.md all
still say types are generated with specta/tauri-specta; `bindings.rs` has recorded
since M1 that they are not, and why. Each now says what actually happens and points
at that file — including the consequence, which is that drift is a `cargo test`
failure rather than a compile error.
PRD G7 carried the same stale claim as the privacy policy: "network traffic limited
to PyPI + GitHub Releases", from before the self-updater was removed.
SECURITY §7 repeated the `cargo about` / `licenses/` claim; §8's reset advice
pointed at "Settings -> Legal & About", a screen that has never existed; §9 promised
a root SECURITY.md that was never written. The last one is now `.github/SECURITY.md`
— a short pointer so GitHub's Security-policy tab is not empty — carrying the
advisory URL and code@poli0981.dev.
SECURITY §4 gains the poli0981.dev entry ahead of the About tab that needs it, per
its own rule that an allowlist widening belongs in prose and not only in
capabilities/. It also now says what the scope actually defends: the two call sites
that pass data rather than constants, one of which hands over a URL that came out of
ruff's JSON. That is the argument for copying the contact addresses to the clipboard
instead of adding a mailto: scheme.
README dropped a "(add the standard GPL-3.0 text at repo creation)" instruction that
had been shipping for three milestones after the text was added.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
CI's Node job failed on the test I had just added: `TS2322` on an `ExecutionOutcome` literal
that was missing `appVersion` and carried three fields `SnapshotMeta` does not have. Vitest
does not typecheck, so `npm test` passed — and I ran the suite and the linter after adding the
file but **not `npm run typecheck`**, which is the one gate that could see it.
Now taken from `snapshot_list.json`, which is the pattern the rest of the suite already uses
and the reason it exists: a fixture serialized from the real Rust type cannot drift from it,
and a literal typed by hand can be wrong in three ways at once.
Also records the Phase 4 state for whoever picks this up: what the pipeline can now do, and
the six things still open — a genuinely clean machine, SmartScreen, the rest of the manual
charter, the icon, the version and RC tag, and README screenshots. CLAUDE.md gains the two
rules this stretch established: building and installing are their own test tier, and the seam
between a tested component and its untested parent is where bugs live.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Installing the first bundle put `pipdock-app.exe`, `pipdock.exe` and `uninstall.exe` into
`%LOCALAPPDATA%\PipDock` — the same folder as `index.db`, `snapshots\` and `tools\`, because
Tauri's NSIS per-user installer writes to `$LOCALAPPDATA\{productName}` and
`store::default_app_data()` derived from the same name.
SECURITY §8 tells users that deleting the app data folder is a complete reset. With the two
collided, following our own documented advice would have uninstalled the application.
The data root moves to `%LOCALAPPDATA%\PipDock\data\`. Changed now because it is still free:
**no release has ever been published**, so there is no on-disk layout in the world to migrate
and no migration code belongs here — a `default_app_data()` that checked for a legacy
location would be dead code from its first commit.
`APP_DATA_SUBDIR` is a second constant rather than `"PipDock/data"` in one join: a path built
from a literal containing a separator reads differently depending on the platform's idea of
one, and every comparison against it inherits that.
Verified by moving this machine's real data and asking the binaries to find it: `tools status`
reports `…\PipDock\data\tools` and *up to date with the pins shipped in this build*, and
`search` still answers out of the 53 MB index.
Two doc paths were also corrupted, by me, in earlier commits: `\PipDock\tools` written through
a Python patch became `PipDock<TAB>ools` in SECURITY §2 and ROADMAP. Fixed here rather than
left for a reader to puzzle over.
The uninstall behaviour is recorded in SECURITY §8 because it was tested rather than assumed:
uninstalling removes its own binaries, the Start-menu shortcut and the registry entry, and
leaves the data directory untouched.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The exit criterion was *"CODE-HEALTH flows pass on two real projects (one pyproject, one
requirements-only)"*. Both are recorded in the stage table with times from a release build
rather than ticked: a requirements-only project reports 1 dependency, 3 dead-code and 3 lint
findings in 1.4 s; one declaring nothing reports `ran: [vulture, ruff]` with an empty
`problems` in 1.3 s, because deptry cannot answer its question there and is correctly not
run. The fix path's three refusals were exercised on a seeded repository.
UI-SPEC §8 gains the two rules P6 established and the reason each exists: `←`/`→` are the
ARIA grid pattern's roving tabindex, added because making the row the only tab stop had left
*Pin* and *Remove* reachable by mouse only; and `Enter` on a row is the non-destructive
primary, because a row has one reversible annotation and one irreversible removal.
CLI-SPEC §6's amendment said *"`health` is still the M3 stub"* — stale since P3, and now
carrying the `--fix` output contract instead.
CLAUDE.md records the tab-stop rule beside the other things this project learned by running,
and the status line moves to Phase 4.
**Still owed, and it needs the real Tauri runtime rather than the stubbed bridge:** the OS
folder picker, a ruff rule link (to confirm the `docs.astral.sh` allowlist entry actually
works — it fails silently if not), and the fix dialog end to end. All three are named in the
ROADMAP so they are not rediscovered.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
DATA-FLOW gains **invariant 6** and §9.1's state machine. §9.1 and §9.2 are scoped to a
mutating *engine* call and do not reach `ruff check --fix`, which rewrites the user's source
tree — a thing no snapshot in this application describes, so one taken here would have no
consumer that could use it. That is invariant 2's own argument for the pip-upkeep exemption,
a second time, and like that one the exemption is **made visible rather than silent**: the
confirm states that PipDock cannot undo the change and that only the user's version control
can. The fifth proof shape is a `HealthReport` plus a server-checked `FixConsent`.
**A SECURITY paragraph was ahead of the code, and the code caught up rather than the
paragraph coming back.** §2 now says the project folder is canonicalized, existence-checked,
and refused when it resolves inside PipDock's own tools directory — so `validate_project`
exists, `..` is handled by comparing canonical paths rather than strings, and running Health
against `%LOCALAPPDATA%\PipDock\tools` answers `PD-ENV-003`. ruff would otherwise have
rewritten PipDock's own venv, and that failure would have looked like a corrupted install
rather than like the fix that caused it.
§2 also records the git resolution finding: this is the one place PipDock runs a
PATH-resolved program with a user-controlled working directory, and a planted `git.exe` does
**not** win — verified by planting one, not by reasoning about `CreateProcess`. §8 gains the
one exception to "all state is local".
CODE-HEALTH-SPEC §5 replaces "recommends a clean git tree" with what was built. CLI-SPEC §3
carries the `--yes` rule where someone reading the flag will see it. UI-SPEC §5 gains the fix
row and §7 names the confirm alongside the other three destructive ones, with the
forced-colors requirement each of them shares. ARCHITECTURE §7 gains `health_dirty`.
CLAUDE.md's waiver list goes 2 → 3, and the no-snapshot decision is written where the next
person will look for it rather than left to be re-derived.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`health::fix` — everything that gates PipDock's **first write outside site-packages and
`%LOCALAPPDATA%`**.
DATA-FLOW §9.1 and §9.2 do not reach it. Both are scoped to a mutating **engine** call, and
ruff is a tool run from PipDock's own venv; more to the point, a fix rewrites the user's
*source tree*, which no snapshot in this application describes. A snapshot is a freeze and
§8's rollback is uninstall-the-added/install-the-removed, so one taken to protect source
files would have no consumer that could use it — invariant 2's own argument for the pip
upkeep exemption, a second time. The safety net CODE-HEALTH-SPEC §5 names is the user's own
version control, which is why the dirty finding lives *inside* `FixConsent` rather than
beside it.
`consent_ok` builds the waiver from what the **server** observed, so a frontend claiming a
clean tree against one the server just found dirty is refused. Same shape as `ack_ok`
checking a `GuardAck` against the guard that produced it. A tree that *was* dirty and is
clean by the time the fix runs needs no acknowledgement — the thing waived no longer exists,
and refusing there would cost the user the fix for having committed.
`git --no-optional-locks status --porcelain --untracked-files=no`, and neither flag is
decoration. Plain `git status` refreshes and **writes `.git/index`** on a stat-dirty tree —
writing into the user's repository while checking whether it is safe to write would be a
poor first act for the write path. Untracked files are excluded because `git checkout .`
restores tracked files regardless, so warning about a scratch file is how a warning stops
being read. `None` covers no-repo, no-git, git-failed and timed-out, because all four leave
the caller with the same options.
**A security question answered by running it.** This is the one place PipDock runs a
PATH-resolved program with a user-controlled working directory, so a `git.exe` planted in a
cloned repository would matter if Windows' legacy `CreateProcess` search order applied. I
planted one and watched which ran: the real git. Rust's `Command` does its own resolution and
does not include the current directory. Recorded on the function, with a note to re-check if
the process layer ever changes.
**`PD-PRM-003`, not a reused `PD-PRM-001`.** That code is scoped to site-packages and its
catalogued action is "use a venv", which is nonsense for a read-only `util.py` — the same
class of wrong answer P3 removed when a corrupted `ruff.exe` reported "install the engine".
Raised internally, so it needs no classifier, only a corpus entry.
And the real hazard is worse than mis-coding: **ruff can fail to write a file and still exit
1**, which `is_findings_exit` accepts as a clean run — so the failure can be *silent*, with
the fix reporting success over a file it never touched. `ensure_writable` therefore refuses
the whole fix before the first byte, checking both the read-only attribute and an append
probe for the ACL case. A partial rewrite of a source tree is the worst thing this design can
produce, because nothing here can undo half of one.
The checklist is **nine** places and CLAUDE.md said eight: `HealthReport` embeds `Code`
through `ToolProblem`, so a new code re-blesses four schema goldens, not three. Corrected
there, along with the count in I18N §1 that was already stale.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
**The deptry question is closed.** ROADMAP has flagged it since P3 as the one decision in
three slices the owner had not made themselves: deptry cannot be told which environment to
compare against, so §2's isolation and §3's comparison conflict. Chosen 2026-08-13 — keep all
four DEP codes and disclose the limitation where findings are shown, rather than
`--ignore DEP003`, which turns a mislabelled finding into a missing one, or dropping deptry
from v1. The screen carries the note under the same condition the CLI does, and the saved
Markdown carries it too, because that file is read away from both.
UI-SPEC §6 goes 14 → **15 of 16**; only `PdEnvSwitcher` is left. §5's Health row gains the
parenthetical the Uninstall row already has: 3 clicks holds once the folder is remembered,
and the first run in a project is 4. §3 gains two rulings it was silent on — that a failed
tool's error row counts into `⚠ n` (three separable tools are three problems, where
forty-seven failed packages are one run), and that Health owns its own console drawer,
because it claims a separate session slot by design and one toggle cannot address two.
CODE-HEALTH-SPEC §6's third bullet is corrected in place rather than left as a known-dead
line: the rule page is keyed by name, `.../rules/<code>` 404s, and the allowlist had to be
widened or every link failed silently.
ARCHITECTURE §7 gains `health_save_report` and corrects `health_fix` to `FixReport` —
`ExecutionSummary` was wrong for the same reason it was wrong for `pip_upgrade`: no plan, no
phase, no per-package counts. Both `EnvRow` rows now say that every per-row field has to be
filled by *both* probe paths, since `upgradePip` replaces the row wholesale.
The ROADMAP stage table records what the plan did not predict: four defects, all found by
running, and the cancellation deferral with the measurement behind it rather than a shrug.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
CODE-HEALTH-SPEC §3 said the environment is "passed to deptry so installed vs declared vs
imported compares against reality". deptry 0.25.1 has no such option, ignores VIRTUAL_ENV,
and reads whatever its own interpreter can import — so §2's isolation and §3's comparison
are in conflict and isolation wins. §3 now says that, names the bounded cost, and says why
DEP003 is kept rather than suppressed.
§3 also gains what the tools actually emit, since §5's sketch predates anyone running them:
deptry's flat list keyed by module and written to a file *path*, vulture having no
machine-readable output and one message shape with no identifier, ruff's URL keyed by rule
name, and all three exiting non-zero on findings with vulture using 3.
ARCHITECTURE §7 and CLI-SPEC §6 both typed the report CheckReport, which engine.check()
already owns and which is a published `pipdock schema` contract — two unrelated shapes
sharing one name on the wire. It is HealthReport.
CLI-SPEC §5's code 1 now covers "health found something", which is the behaviour a
pre-commit hook needs and the one doctor already had.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The stage record in the house format, plus UI-SPEC §5's new row (2 clicks, counted by hand
from the landing screen) and CLAUDE.md's where-to-pick-up.
Three rules worth not re-deriving are written into CLAUDE.md rather than left in the
ROADMAP body, because each is a trap the next slice can walk into: sysconfig inside a venv
answers about the base; venv_scan matches exactly four directory names, which is what makes
hand-verification of any environment feature need one of them; and every pip below the
planner floor is broken on 3.12+, so the case the button exists for is also a pip that
cannot run.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
CODE-HEALTH-SPEC §2 said the venv is populated "using the configured engine" and left the
Python range open-ended; both are now written as built, with the evidence.
The ROADMAP record carries what a later reader would otherwise re-derive: why there is no
TOOLS_PYTHON_MAX (deptry is abi3, verified on 3.12 and 3.14 from one wheel), why pip-audit
is in the ledger and not the venv (msgpack has no py3-none-any fallback — the earlier
"exposure is zero" reasoning was simply wrong), why the hash covers parsed pins rather than
bytes, why the manifest is deleted first, and that P2 shipped the health-progress producer
while P3 ships the channel.
CLI-SPEC §6's NDJSON paragraph is flagged, not quietly satisfied: no command emits NDJSON
today, and making tools sync the only one that does would be worse than the gap.
CLAUDE.md had M2 as "Stages 1-4 done, S5 next" while its own body said M2 was complete,
and 54 goldens where there are now 58.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`python -m venv` spawning fine and exiting non-zero had no honest code. The tools venv
bootstrap (next commit) is the first thing that can hit it, so the code lands before the
error path that raises it rather than being retrofitted onto one.
None of the three candidates worked. PD-NET-011 is Area::Net, and run::exit_for derives
the exit code from the area — so `tools sync || wait-for-network && retry` would loop
forever on a stripped Python, and both locales' shipped copy is explicitly about
downloading. PD-HLT-001 tells the user to re-sync the tools environment, which is the
operation that just failed. PD-INT-001 is "a PipDock bug", and a Python built without the
venv module is not one. Area::Hlt already maps to exit 1, which is right.
All eight places from CLAUDE.md in one commit, because seven of them are a broken build:
the variant, Code::ALL, both count assertions (32 -> 33), classifier_corpus's
internally_raised table without which the no-code-without-a-fixture gate fails, en+vi copy
under the 90-char cap, regenerated codes.json and bindings, and the catalog doc. Three
goldens re-blessed — Code plus the two schemas that embed it, StepResult and
ExecutionSummary. ResolutionReport does not embed it and did not move.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The stage record said four items were open; they are not. `engine_info`, the
`COMMANDS` drift gate, focus-follows-tab and Search's empty state all landed, so
ROADMAP records what shipped rather than what was owed an hour ago.
Two things are still deliberately out, and named: the `Enter` primary-action map
and folding six `aria-live` regions into one. Both are cross-screen behaviour
whose correctness is a screen reader and the VI sweep, not a passing test —
landing them blind would be the kind of green suite this repo has learned to
distrust.
M2 closes here. Every P0 feature except Code Health is in both heads, all seven
UI-SPEC click budgets are met by hand count, and `NOT_YET` names the five
commands that remain against the slice that owes each. Where to pick up now
points at Phase 3, with the two decisions worth not re-deriving and the ten-minute
check that retires M3's biggest unknown before any of it is written.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
UI-SPEC §3 gains a definition for `⚠ n`, which its own layout diagram has drawn
since the spec was written and which nothing specified. It counts error rows
currently on screen, not a session tally — the tally reads `⚠ 47` after a batch
where 47 packages failed, stays there, and tells the user nothing the summary in
front of them does not. Flagged as invention, because it is one.
ERROR-CATALOG §4 records that the URL is built once in core and called by both
heads, and that the ring is fed from three places rather than one: a resolve
emits no progress events at all, and a plan that would not resolve is the
commonest thing anyone reports.
I18N §1 is amended rather than left describing seven namespaces the app never
had. i18next's `nsSeparator` is `:`, so a real second namespace means
`t('errors:PD-NET-001')` at every call site — churn across every screen, bought
with lazy loading a bundled desktop app cannot use. One namespace, two files per
locale, and the error codes keep their own file because they are the only keys
whose names are a contract with Rust.
ROADMAP records S7 as **substantially done with four items open**, named rather
than quietly dropped: `engine_info`, the `COMMANDS` drift gate, the `Enter` map
with focus-follows-tab and one live region, and `PdEmptyState` on three surfaces.
Phase 3's first slice needs `engine_info`, so that one is owed either way.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
**26 of the 32 codes had no copy at all.** A PEP 668 refusal, an MSVC-missing
build failure and a full disk all rendered as "An unexpected error occurred."
with a code beside them — and silently, because `PdErrorRow` falls back
deliberately rather than leaking `PdError.message`, which is English developer
text. Nothing failed; the app simply had nothing to say about five sixths of what
can go wrong.
The codes move to `locales/{en,vi}/errors.json`, merged into the single `common`
namespace at init. I18N §1 named seven namespaces; the app ships one, because a
real second namespace means `t('errors:PD-NET-001')` at every call site —
i18next's `nsSeparator` is `:` — bought with lazy loading a desktop app that
bundles both catalogs cannot use. The error codes still earn their own *file*:
there are 32, they are the only keys whose names are a contract with Rust rather
than with a screen, and keeping them reviewable is worth one import. §1 is
amended to say so rather than left describing something that was never built.
`i18n.test.ts` now checks them against `codes.json`, generated from `Code::ALL`.
A hand-written list in TypeScript would drift the moment a code was added and go
on passing over an incomplete catalog. It asserts both directions — no code
without copy, no copy without a code — and the ≤ 90-char cap I18N §4 states,
which was aspiration until now. Verified by breaking the catalog deliberately:
both directions fail, then pass again once restored.
Adding a code is now an eight-place change, and CLAUDE.md says which eight.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
DATA-FLOW §8 has always listed "dry-run resolve the restore set" between the plan
and the snapshot, and **neither head has ever done it**. S6 did not add it, so §8
now says which part is real: `RollbackFlow` diffs, plans, and reports the entries
no index can supply — but it does not ask the engine whether each restore spec is
still fetchable, so a release yanked since the snapshot surfaces at execute time.
Adding it is a network round trip on an interaction budgeted as instant, and it
would resolve against the *pre-removal* environment, reporting conflicts the
two-phase execution never hits. It needs its own design and belongs with M3's
engine work. Until then the preview's promise is precise rather than broad: it
lists what *cannot* be restored, not everything that might fail.
UI-SPEC §4 records why the env detail is a mode of the Environments tab rather
than a ninth sidebar entry (§8 fixes `Ctrl+1..8`), why the trigger label is
load-bearing rather than decoration, and why the diff copy names a direction —
"added" is ambiguous the moment you read it from the snapshot's side. §5's
rollback row gains the real path and the 2-click route from a summary. §6 goes to
14 of 16, `PdSnapshotTimeline` having arrived; `PdEnvSwitcher` is now the only one
absent that is not M3's, and nothing needs it.
TESTING §2's L1 list gains the partition property, which is the one a rollback
preview actually stands on.
ROADMAP's Stage 6 table records the four bugs, three of which no test written for
them would have found: the uncancellable restore loop, the freeze lines both
parsers dropped, `snapshot_list` firing twice, and the rollback that left the
timeline empty. CLAUDE.md: Stages 1–6, goldens 52 → 54, and the rule S6 leaves
behind — two slices that key on different things need two resets.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
ROADMAP gains the Stage 5 table it never had — the whole S5/S6/S7 definition
lived outside the repo, so `main` described the order and nothing else. Five live
bugs are recorded there because none of them were S5 features: the wedged slot,
the missing lifecycle markers, the removal that ignored its cancellation token,
the swallowed `--no-snapshot`, and the pin button that was a tab stop.
DATA-FLOW §5 now says the dialog is not the enforcement point, and §9.1 names its
proof per plan shape: a `ResolutionReport` for a resolve, a `GuardReport` plus a
`GuardAck` for a removal, a `RollbackPlan` for a restore. It had required a
`ResolutionReport` "accepted in this session", which the uninstall path cannot
produce — there is nothing to resolve — so the one flow with no preview was also
the one flow the invariant did not describe.
UI-SPEC §4 records two inline row buttons rather than the `⋮` menu it specified,
with the click arithmetic that forced it, and the Pins screen's Exclude-only
scope with the reason: `pins::hold_requirements` has no caller and
`plan_requirements` restates the installed version, so a Hold at another version
is a promise nothing keeps. §5 states the click-counting convention it had been
applying inconsistently. §6 corrects the inventory to **13 of 16** — the "16 of
16" claim after S4 had folded in components that are not on that list — and names
the four that are load-bearing but unlisted.
CLI-SPEC §5 and §7 follow the exit code from 1 to 2. TESTING §1.5 says the guard
must be enforced and not merely reported. CLAUDE.md: 31 → 32 codes, and adding
one now re-blesses every schema that *embeds* `Code`, not just `Code`; 46 → 52
goldens; and the rule S5 leaves behind — a decision that sits between two IPC
messages needs a value the executing call demands, or "somebody forgot to look"
stays expressible.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`Code::ALL` has been 31 since `PD-RES-003` landed in S3; CLAUDE.md still said 30, and the
ERROR-CATALOG row count it quotes was 28 against an actual 29.
Both numbers are pinned by tests, so they were never load-bearing — but a reading note that
is wrong about a count is worse than one that omits it, because the next person checks it
against the code and then distrusts the rest of the file.
Also records what adding a code actually costs, since S3 found out one gate at a time: the
catalog, `Code::ALL`, both count assertions, the "no code without a fixture" gate, both
locale catalogs, and a re-blessed schema golden. The gates name what is missing, so this is
a map rather than a checklist to follow by hand.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A Stage 4 table in ROADMAP Phase 2 with the exit criteria as they were actually
established: install-one counted by hand at **4 clicks**, and the keystroke budget measured
before and after — **57.4 ms median / 79.8 ms p95 / 18 of 19 over budget**, then **22 ms /
24.5 ms / 0 of 19**.
Both new CLAUDE.md rules are things that cost something this slice:
**Measure in `--release`, and say which build a number came from.** The index load is 572 ms
in debug and 140 ms in release; the worst keystroke is 176 ms against 16 ms. A design was
justified with a figure four times too large before anyone noticed, and the fix is a test
that refuses to run in debug rather than a note asking people to remember.
**The `Send`/`Sync` rule now says it has bitten twice** — `UpdateFlow::start` and then
`index::metadata`/`refresh` — so the next person can expect it rather than rediscover it.
The "run it, don't just test it" tally gains Stage 3 and Stage 4, and Stage 4's entries are
the sharpest yet: a wrong number, a missed budget, and a flow that ran correctly all the way
through Rust and then rendered nowhere.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A Stage 3 table in ROADMAP Phase 2, with the exit criteria as they were actually verified —
"update everything" counted by hand at **4 clicks** in a running app, still 4 with a conflict
left at its default, and a cancel mid-execution yielding a coherent summary with Skipped
rows.
Three specification gaps are recorded in UI-SPEC §4 rather than left in commit messages,
because each is a thing the next person would otherwise re-derive: `Will downgrade` had no
section, `Keep compatible` should not be offered on impossible rows, and the round counter
was invisible.
CLAUDE.md gains the rule that cost the most to learn this slice: **a Tauri command's future
must be `Send` and `Store` is not `Sync`**, so the store guard can never cross an await.
At the command boundary it does not compile; inside core, where it does, it silently
serializes every other command behind a network call. That is why `UpdateFlow::start` takes
pins rather than a store, and it will be true of every command S4 adds.
S4's exit check is called out as something to design for before building rather than after:
< 50 ms per keystroke *measured in the app*, which adds an IPC round trip SP-3 never
measured.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A Stage 2 table in ROADMAP Phase 2 in the shape of Stage 1's: what landed, the four bugs
that were not in the plan, and the decisions a later slice has to honour.
Three of those four were found by running — timing the probe, doing one real
`pip install -e`, and logging what actually crossed the bridge. CLAUDE.md's "run it, don't
just test it" note now carries both stages' tallies, because the pattern has held across
every slice so far and is the single most useful thing to know before starting the next.
Two S2 decisions are called out where S3 will actually read them. "N pinned excluded" in
the table is presentation and S3's preview must use the flow's `excluded_pins()` instead,
or the two numbers drift. And row state is three-valued because one of its two sources is
networked — anything rendering package state inherits that obligation.
Also added: `probe.py` is on the hot path. The Installed screen re-probes on every
environment open, so anything added to `_dists()` is paid 200+ times per open — which is
how an innocuous-looking `Distribution.files` became a 10× regression.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
ROADMAP Phase 2 gains a Stage 1 table — what landed, and the four bugs that were
not in the plan, all of which came from running things rather than reading them.
It also names the three deferrals explicitly, with the slice each belongs to,
because "we'll get to it" is how the plan-progress payload stayed unimplementable
for a whole milestone.
CLAUDE.md's "current state" was still describing the bridge as names-only. It now
says the app runs, and lists the four things a next session would otherwise
discover by breaking them: the bindings staleness check, the L4 goldens as an
output contract, the two tests holding the wire format, and — the one that earned
its place — run it, don't just test it.
Three more entries under "things that look like bugs but are not", each a decision
someone would reasonably try to undo: the `serde(alias)` on snapshot::Meta (remove
them and every existing snapshot stops parsing), the deliberate split between
take_snapshot() and execute(), and the fixture redaction.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The CLI's `--json` has never matched the documents that define it. Deriving serde
without `rename_all` emitted the Rust spelling:
{"plan_id": "...", "results": [{"code": "BldBackendFailed", "stderr_tail": ...}]}
while DATA-FLOW section 6 and ERROR-CATALOG section 3 both document `planId`,
`stderrTail` and `"code": "PD-BLD-002"`, and ui/src/ipc/index.ts declares the same.
The error envelope main.rs hand-builds was already correct -- so the binary
disagreed with itself across its two --json paths.
M1 debt rather than a new convention, and the M2 bridge cannot be built on a
contract that is wrong on paper.
Two changes, each with a test that makes the fix hold:
- `#[serde(rename = "PD-...")]` on all 30 Code variants, guarded by a test
asserting `to_value(c) == json!(c.as_str())` for every code. The renames
duplicate as_str, so that test is what stops the two drifting -- a new variant
without a rename fails there. Chosen over a manual Serialize impl because
schemars honours serde attributes, so `pipdock schema Code` now enumerates the
real wire values instead of Rust variant names.
- `rename_all = "camelCase"` on every struct reaching the exported surface,
guarded by a test that walks the generated schema of each SCHEMA_TYPES entry
and fails on any property containing an underscore. Walking the schemas is what
makes it total: a convention only covers the structs someone remembered, and
this catches fields reached through nesting. It is what found `versionReq`
(via Spec) and `planId` inside `Trigger::Plan`, which needed
`rename_all_fields` rather than `rename_all`.
snapshot::Meta needed care: it is the on-disk `.meta.json` sidecar as well as what
`snapshot list --json` emits. Renaming its fields without aliases would have made
every existing snapshot unparseable -- the timeline comes up empty and the rollback
the user was relying on is silently not offered. There were eight real sidecars in
%LOCALAPPDATA%\PipDock written before this change. So the renamed fields carry
`#[serde(alias = ...)]`, covered by a test built from the verbatim bytes of one of
them, and verified end to end: the new binary reads a 2026-07-27 snake_case sidecar
and emits camelCase for it.
The L4 goldens are re-blessed. Their diff is the whole point of having written them
first -- every changed line is a one-for-one rename or a Code const moving from
`EnvInterpreterMissing` to `PD-ENV-001`, and nothing else moved.
Also corrects CLAUDE.md's "25 launch codes": Rust has 30, now pinned by a test.
198 tests, fmt and clippy clean.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Removes `tauri-plugin-updater` and everything that existed to serve it.
A self-updater is a permanent remote-code-execution path into a tool that already
runs subprocesses against the user's interpreters, and it has to be defended for
the life of the product: a signing key that must never leak, an endpoint that must
never be spoofable, verification logic that must never be bypassable. For something
people open occasionally to tidy an environment, that is a large standing liability
bought for a small convenience.
It was also never actually functional. `plugins.updater.pubkey` has been the literal
string REPLACE_AT_FIRST_RELEASE_WITH_TAURI_SIGNING_PUBLIC_KEY since Phase 0, so the
capability was granted to a plugin that could not verify anything.
What goes:
- tauri-plugin-updater, its `plugins.updater` config block and endpoint, and the
`updater:default` capability
- the release workflow's signing step, `--bundles ...,updater`, and the *.sig /
latest.json artifact globs
- TAURI_SIGNING_PRIVATE_KEY and its password from the secrets bootstrap, and the
keypair generation item from the RELEASE-CI section 5 checklist
Ten crates leave the dependency tree with it: zip, tar, xattr, filetime,
minisign-verify, osakit, objc2-osa-kit, arbitrary, derive_arbitrary and the plugin
itself -- archive extraction, signature verification and AppleScript execution, none
of which PipDock has any other reason to link.
SECURITY section 4 gets simpler as a result: pypi.org is now the *only* host PipDock
connects to. github.com was on that list solely for the updater; the legal gate and
the bug-report deep link hand a URL to the user's browser rather than fetching
anything.
Users move between versions from the GitHub Releases page and verify SHA256SUMS.txt,
which the README already tells them to do because SmartScreen warns on first run.
Recorded in CLAUDE.md as well: Tauri makes adding this back a three-line change, so
the reasoning needs to outlive the commit.
183 tests, fmt and clippy clean, both Tauri JSON files still valid.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
ROADMAP said L2 "has never run". It had, three times, failing each time; record
what failed and why, since both causes were in the harness rather than the product
and neither is obvious from the job name.
M2 was estimated at 3-4 weeks. Surveying the code for it shows the bridge is
scaffolding: ui/src/ipc/index.ts fixes 26 command *names* with zero wrappers,
src-tauri registers exactly one command (app_info, a smoke test), and 2 of 16 Pd*
components, 1 of 5 Zustand stores and 2 of 14 locale catalogs exist. Scope is
unchanged; the estimate moves to 7-8 weeks to match it, and three pieces with no
home in the core yet are named so they get sequenced before the screens rather
than discovered during them:
- the flow layer, since plan_and_run is ~200 lines of DATA-FLOW section 3 living
only in the CLI, and duplicating it would mean two implementations of the hard
invariants
- cancellation, which does not exist at all -- plan_cancel is a declared TS name
with no Rust counterpart, and exec.rs's watchdog drops the future rather than
killing the child
- progress, where ProgressEvent.step is hardcoded 0 at all four producers and
scan-progress has no producer
Also: ARCHITECTURE section 10 still said uv "0.9.x line, minimum pinned after
SP-1" when SP-1 pinned 0.10.0 and shipped it as UV_MIN_VERSION; CLAUDE.md said
"Status: Phase 0" three lines above a paragraph saying M1 was substantially
complete; and the fixture redaction now needs recording under "things that look
like bugs but are not", because "these are not literal engine bytes" is exactly
the kind of thing someone will otherwise try to helpfully undo.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Adds the last commands: env use, pip-upgrade, snapshot rollback, schema,
self report-bug, and engine <pip|uv>. Every P0 CLI command now works
except health, which belongs to M3 with the tools venv.
Rollback follows DATA-FLOW section 8 including the part that is easy to
skip: it snapshots the current state before replacing it, because a
rollback is itself reversible. Verified end to end — installing httpx
0.23.0 and rolling back left the environment with pip alone, and the diff
afterwards reported "matches snapshot".
Two things the compiler and the smoke test caught:
- `pipdock engine pip` was never handled. Only the no-argument form was
wired, so the documented setter silently did not exist; the
non-exhaustive match surfaced it once the catch-all arm was removed.
That catch-all had been hiding it.
- engine_for ignored any stored preference and always returned pip, so
configuring an engine would have had no effect. It now reads the store,
and setting an unavailable engine is refused rather than saved —
storing a preference that cannot be honoured just moves the failure to
the next command.
schema generates from the Rust types via schemars rather than being
hand-written, because a hand-written schema drifts the moment a field is
added and then lies to every script pinning against it. A test asserts
every advertised type actually resolves.
ci-integration.yml implements TESTING L2: real pip and uv against
throwaway venvs on Windows, across the 3.10 floor and 3.14 ceiling, with
an end-to-end pass that checks the claims the docs make — the SP-1
conflict is still reported and attributed, update/rollback round-trips
leave the environment matching the snapshot, the guard still refuses to
break requests, and the exit codes still match CLI-SPEC section 5. A
weekly job re-captures fixtures against the newest engines so an output
change surfaces as a failed job rather than as PD-ENG-003 on a user's
machine.
The ROADMAP entry is honest about what is not done: L2 has never actually
run, the L4 golden-output tests are not written, and the SP-5 exit
criterion named a real numpy/scipy/pandas environment that the
httpx/httpcore construction stood in for.
173 tests, clippy -D warnings clean, npm audit clean, all workflows parse.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Requires-Python is now enforced by PipDock, not by the engine.
SP-2 found the engines disagree: scipy 1.7.3 declares >=3.7,<3.11, and on
Python 3.12 pip refuses it while uv plans to install it. G5 promises one
behaviour across heads, so the preview must not change shape because the
user flipped the engine radio. crates/pipdock-core/src/compat.rs screens
every candidate against the environment's version before any engine
command runs; rejects surface as PD-PKG-001 with the required range shown
against the found version.
This does not weaken "explain, don't reimplement" — resolution stays
entirely the engine's. compat.rs only filters candidates the engine should
never have been offered, using the slice of PEP 440 that actually appears
in Requires-Python: comparison, wildcard and compatible-release operators.
Specifiers it cannot parse count as compatible, because PipDock failing to
read metadata must never be the reason an installable package is refused.
Nine tests, including the exact scipy case the spike captured and the
boundary cases where an off-by-one would reject a supported Python.
probe.py keeps -I, and the cost is disclosed rather than hidden.
Isolated mode is what stops a poisoned environment injecting code into the
probe, so it stays; dropping to -E was rejected because a package in user
site is part of the untrusted surface the isolation exists to exclude, and
probing twice was rejected as a second interpreter start per scan for a
non-primary case. Instead probe.py now reports hidden_user_site — the
user-site path when it exists, sits off sys.path and is non-empty, else
null. Verified: the system Python reports the path (352 dists), a venv
reports null. The Installed screen shows a note naming the path only when
it is non-null, so users of the affected case are told exactly what is
missing while everyone else sees nothing.
ERROR-CATALOG PD-PKG-001 changes from a stderr classification to a
PipDock-raised code, because engine stderr cannot support it: pip reports
it as plain "No matching distribution found", indistinguishable from
PD-PKG-002, and uv does not enforce it at all.
Docs updated: ARCHITECTURE 3 and 4, DATA-FLOW 2, SECURITY 2, UI-SPEC 4,
ERROR-CATALOG 2, ROADMAP, CLAUDE.md, spikes/README.md. EN and VI strings
added for both notes.
Two non-blocking questions remain in spikes/README.md: search-ranking
scope for M1, and how to obtain the five error fixtures this machine
cannot produce.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Records the five design invariants that must never be violated (accepted
plan + snapshot before any mutation, argv-only subprocess, never
reimplement resolution, codes-not-strings from Rust, no implicit
--break-system-packages), the naming conventions, and the corrected CI
picture.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>