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>
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>
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>
**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>
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>
The CI docs were written against an assumed poli0981/.github suite.
Audited the real one on 2026-07-27; four claims did not hold:
- no reusable Rust workflow and no reusable Tauri workflow exist, and
only reusable-desktop-csharp.yml uses a Windows runner, so ci-rust.yml
and release.yml must be project-local
- notifications are Discord-only via discord_notify.py; there is no
notify.py and no Telegram/Bluesky/Mastodon/X/Facebook fan-out
- dependency updates are Dependabot, not Renovate (no Renovate config
exists anywhere in the ops repo)
- setup-secrets.sh does not exist; use gh secret set
Also records that reusable-codeql.yml has no Rust support (CodeQL has no
Rust analyzer) and that reusable-web-react.yml has no working-directory
input, which is why package.json sits at the repo root.
Intent is preserved throughout: grouped weekly bumps, immediate security
PRs and isolated tools-requirements.txt bumps are now expressed in
Dependabot terms rather than dropped.
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>