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>
PRD P0-1, UI-SPEC §4, CLI-SPEC (env add/remove, their JSON, --env's new
refusal), CLI-GUIDE, ERROR-CATALOG (PD-ENV-001's new cases, and the
first button its advice ever had) and TESTING's golden count. SECURITY
§2 claimed for two milestones that interpreter paths were canonicalized
before use while the only check was existence; it now describes the
validator that makes it true. PRD also records P0-9's first-run uv
detection, P1-7 and P2 as not planned in maintenance mode.
legal/PRIVACY-POLICY.md 1.3 names the interpreter paths a person adds,
kept until removed, in both languages. With the repository URL it
already changed, the first-run gate shows once in 1.6.0.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
UI-SPEC §7 no longer describes a forced-colors list that is "not complete": the
mark is data-destructive. §8 gains the five rules the pass left behind — focus
on every screen replacement, names that contain the visible text, composite
widgets as one tab stop, chip meanings as text, status regions that exist
before their first message.
TESTING says which of the three new tests holds what, and that none of them
knows what a screen reader says; the manual charter gains a ten-minute
accessibility pass. CLI-SPEC writes down that the CLI has no colour and nothing
that animates, which was true of the code and stated nowhere.
RELEASE-CI: the conversation-resolution rule the protection table never listed,
the labels box that had been true for weeks, and .nvmrc, which still said 24 a
month after every workflow moved to 26.
README links the new files and gains Accessibility and Contributing sections.
AI-DISCLOSURE and About name the model that produced 1.5.0.
Co-Authored-By: Claude Fable 5.2 <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>
SECURITY §6 has said since it was written that pip-audit "runs **from the tools venv**".
The code has refused that since P2, with three tests enforcing the refusal, because
`pip-audit`'s closure contains `msgpack` — no universal wheel, so a new CPython would
hard-fail the whole sync under `--only-binary=:all:` and take Code Health down with a
feature it does not use. §6 now describes the venv that exists.
**And neither §6 nor PRD P1-1 could have been implemented as written.** Both promised a
severity — §6 as "(CVE/GHSA id, severity, fixed-in)", the PRD as "severity-sorted" —
against a field pip-audit has never had under either vulnerability service. Running the
pinned 2.10.1 is what settled it: a finding carries `id`, `fix_versions`, `aliases` and
`description`, full stop. Both are corrected to the order that ships, which is package →
fixable → id, and both now say why a derived severity would be worse than none.
`osv.dev` joins the opener allowlist, which ROADMAP has flagged as owed since 1.1.0 —
without it every advisory link rejects and nothing opens, which is the silence SECURITY
§4 exists to name. The description records what makes this entry different from
`docs.astral.sh`: `PdHealthReport` hands over ruff's own `finding.url` verbatim, while
`audit::advisory_url` **builds** the URL from an id checked against a whitelist that
cannot contain a slash, colon, question mark, hash or percent. The tool chooses the id,
never the destination.
The three legal documents that said pip-audit is "not invoked in version 1.0" now say
what it does, and DISCLAIMER §4's forward-looking sentence is replaced by one about a
feature that exists: findings come from **PyPI's** advisory data, an advisory database
is a record of what has been reported rather than a guarantee, and PipDock assigns no
severity because pip-audit publishes none. **This re-shows the consent gate once** for
every existing user — the mechanism working, not a regression.
Also: UI-SPEC §4 gains the screen it has assumed since §3's diagram, §5 its click budget
counted in the running app, and §6's off-list inventory said *four* while naming five —
now six, plus the three from 1.1.0 it never named at all. CLI-SPEC §3 documents
`pipdock audit` and drops `doctor`'s promise of an audit summary it has never printed.
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>
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>
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>
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>
DATA-FLOW §5's dialog is "Removing X breaks Y (requires X>=1), Z", but
`GuardReport.breaks` was `BTreeMap<PkgName, Vec<PkgName>>` — names only. A bare
list tells the user what will break and not whether they can live with it, and
the specifier is the only thing that separates "needs any version of this" from
"needs exactly this one".
The graph already held the requirement; `dependents_of` was throwing it away.
`breaking_dependents` keeps it as `BrokenDependent { pkg, version, constraint }`,
where `constraint` is the bare specifier tail — `"<2,>=1.26.0"`, not
`"numpy<2,>=1.26.0"` — because `Requirement::parse` splits the name off and the
name is already the map key. The caller has both halves and joins them the way
its own language does: Rust does not assemble the sentence (I18N §1), and a
specifier is data, like a version or a path.
A dependent appears once per *distinct* in-force constraint. Two marker-gated
branches that both apply are two real constraints; an exact duplicate is metadata
noise. That is the SP-5 bug's shape, so it has a test: pandas declaring numpy
four ways on 3.12 yields one line, not four.
`guard_report.json` joins the IPC fixtures, computed by running the real graph
over the real `pkg_list()` rather than hand-written — the fixture set was already
the SP-5 tangle, so removing numpy there breaks pandas and scipy with two
different specifiers, which is exactly the case the dialog exists for.
One golden moves, deliberately: `BrokenDependent` enters `$defs` and `breaks`
retypes. It arrives through `$defs` rather than `SCHEMA_TYPES`, so `pipdock
schema` gains nothing to list.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
UI-SPEC §4 specifies the Installed table as `name · version · latest · size · chips`,
and nothing produced a size: `Dist` had no field, `probe.py` did not emit one, and
neither engine's `list --format=json` reports it. `Dist.sizeBytes` closes that, summed
from each distribution's RECORD manifest.
**Measured, because the first implementation was 10x slower.** `Distribution.files` is
the obvious API and it constructs a PackagePath object per installed file: on this
machine's 352-package system Python it took the probe from 551 ms to 5,492 ms — on the
code path the Installed screen runs every time an environment is opened. Parsing RECORD
directly costs 79 ms for the same answer (551 → 625 ms, +14.6%). Sanity-checked against
the real directory: 1,624 MiB reported against 1,844 MiB on disk, the 12% shortfall being
__pycache__ written after install, which RECORD by definition does not list.
**`None` is not `0`, and that distinction is the whole design.** A PEP 660 editable
install has a valid RECORD listing only its import shim and a .pth, so the naive sum
reports **240 bytes for a package whose sources are 8.1 MiB** — verified against a real
`pip install -e`. That is worse than reporting nothing, so editables are detected through
direct_url.json's `dir_info.editable` and excluded, as are `.egg-info` distributions,
whose SOURCES.txt carries no sizes. The field is `skip_serializing_if = "Option::is_none"`,
so those rows simply have no `sizeBytes` and the table renders an em dash rather than a
claim.
`list_json` sets it to `None` unconditionally — one more reason the Installed screen reads
the probe rather than the engine (DATA-FLOW §7).
probe.py schema goes to 2; the Rust parse is permissive, so a schema-1 document still
loads with `size_bytes: None`. One golden re-blessed, deliberately:
`golden__schema-Dist.snap` gains `sizeBytes` and nothing else moved. Human `list` output
is unchanged — it already omits requiresDist and requiresPython.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Commits the full v0.1 design suite written during the design phase:
PRD, architecture, data flow, UI/CLI specs, code-health spec, error
catalog, security, testing, release/CI and i18n docs, plus the roadmap.
The legal documents (EULA, disclaimer, privacy policy, third-party
notices) must be committed publicly because the in-app legal gate links
to their GitHub URLs at first run.
Also adds .gitignore, which the repo was missing.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>