Commit Graph
21 Commits
Author SHA1 Message Date
poli0981andClaude Fable 5.2 4732f05197 docs: sync the specs with the accessibility pass
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>
2026-11-10 20:01:03 +07:00
poli0981andClaude Opus 5.5 7124227262 docs: the specs say what the code does; 1.4.0 recorded, with its audit backlog
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>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5.5 4da4c0f3ec fix(ui): the shell - window, grants, CSP, language, keys, table, contrast
The window (U21). It may now be maximized and snapped; the 1600x1100 cap is gone, and the content
column stops at max-w-content (87.5rem) instead, centred in what is left. The window is created
hidden and src-tauri/src/window.rs fits it to the monitor's work area before showing it: 1180x760
is taller than the work area of a 1920x1080 panel at 150% and of a 1366x768 laptop, so the status
line and the plan panel's Confirm opened under the taskbar. Never below 900x560; pinned to the
corner rather than centred off-screen when even that does not fit. UI-SPEC §5 says so.

The webview's grants (U1, U32). core:default granted some sixty core commands nothing called and
not core:window:allow-close, so Decline on the legal gate did nothing in the installed app while
its component test - which mocks close() - passed. default.json now holds exactly the five the
frontend calls, and a test in lib.rs pins the union of every capability file, plus the opener's
four hosts.

CSP (U56): object-src, base-uri and form-action 'none'. A release build's style-src drops
'unsafe-inline' - React sets styles through CSSOM, which CSP does not govern. index.html keeps it
for `npm run dev`, where Vite injects <style> elements; both policies are enforced, so the
stricter decides. To be confirmed on the installed build.

Language (U3): the choice is stored and applied at start. save() sent locale: null every time, so
choosing Vietnamese lasted until the window closed. Settings now load before the legal gate, so the
gate is in the chosen language too, and <html lang> follows the UI.

Keys: a screen's data-autofocus wins over the heading (U12) - Search's field lost focus to the
shell's effect, which runs after its children's - and `/` works from Search itself. Ctrl+1..9 by
e.code (U49): on AZERTY Ctrl+3 reports `"`. A release build swallows F5, Ctrl+R, Ctrl+P, Ctrl+F,
F3 and Alt+arrows (U20), which reloaded, printed and found in a single-page app.

Also: Security scrolls (U2); the legal gate shows a consent that cannot be recorded (U29); Report
bug asks for the link again with the environment, so the issue carries the Python and engine
versions, at one subprocess per click rather than per row (U31); the package table's header and
rows share one set of widths and one gutter, and narrow tables drop Size so names stay visible at
900px (U22, U23); the grid is focusable (Sonar S6852); --color-danger is #F26A63 and danger badges
use a 15% tint, with tokens.test.ts now compositing every badge tint over every surface (U46 -
3.92:1 before); test seeds typecheck instead of `as never`, the IPC mock uses the real isPdError
and has the audit cache entry (U10).

U14 and U26 were already fixed by earlier commits in this release.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 00:55:27 +07:00
poli0981andClaude Opus 5 02cc17d95d docs: the dependency view recorded, and 1.3.0
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>
2026-08-21 08:35:15 +07:00
poli0981andClaude Opus 5 47b9bc9039 docs: the Security tab's spec and legal debt, including two claims that were false
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>
2026-08-18 10:55:11 +07:00
poli0981andClaude Opus 5 edb7544b93 chore(release): 1.1.0, and the P1 wave closed
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>
2026-08-14 21:16:52 +07:00
poli0981andClaude Opus 5 929cff898a fix(ui): cap the suggestion list, because a real environment offers 94
Running it against `C:\Python314` — 352 packages, the scale fixture — the default
threshold of 5 qualifies **94 packages**. The ranking is right (setuptools at 150
dependents, then zope at 93, zope-interface at 86; it is a Plone environment and
those really are its workhorses) but a "Worth pinning" section with 94 rows is not a
suggestion, it is a second package list.

No unit test could have said this. The fixtures have six packages because that is
what proves the threshold logic; the usability of the result at scale is a property
of real dependency graphs.

**Raising the default would have been the wrong fix.** A deep tree is exactly where
a bulk update is most dangerous, so it is exactly where the feature has to work. The
screen shows the top 8 and says how many more qualify — `RUFF_ROWS_SHOWN`'s pattern,
including its rule that the count comes from the **full** list so a capped view never
misreports a total. `pins::suggest` is unchanged and still returns everything at or
above the threshold, which is what keeps it composable.

Measured in --release while there: probe **605 ms**, graph build plus the entire
suggest pass **1 ms**. The plan's worry about `dependent_count` being O(n·m) over 350
packages was unfounded — the subprocess dominates completely, and there is no case
for a batched counts method.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-14 20:19:28 +07:00
poli0981andClaude Opus 5 fc897ef569 docs: P1-A done, and the three things the estimate had wrong
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>
2026-08-14 20:19:28 +07:00
poli0981andClaude Opus 5 57c365e36a feat(ui): About — what PipDock is, and a way back to the documents you accepted
UI-SPEC §4 has specified *Legal & About* since the spec was written, as a section
inside Settings, and four milestones shipped without it. That is what folding a
read-only surface into a screen of controls does. It is now the ninth tab.

**The ninth tab cost nothing.** `App.tsx` reads `NAV_KEYS[key - 1]`, so appending
`about` made it Ctrl+9 without moving one existing binding. UI-SPEC's warning was
about *inserting* — which is still true, and is still why Snapshots is a mode of
Environments: it would have to sit beside Environments to read as related. The
comments in four files said "a ninth entry would renumber Ctrl+1..8"; they now say
what the rule actually is.

Contents: what PipDock does and what it does not collect; version and the legal-docs
hash from `app_info` — a command that has existed since M1 with no consumer, so the
version on screen cannot drift from CARGO_PKG_VERSION; the SPDX identifier
`GPL-3.0-only` rather than the looser "GPL-3.0" elsewhere; a control that puts the
gate back; and contact.

**Addresses are copied, not opened.** `mailto:` would widen the opener capability by
a whole URL scheme, and the scope's real job is bounding the two call sites that pass
data — one of which hands over a URL that came out of ruff's JSON. Clipboard-write is
already granted, works with no mail client, and the address has to be on screen
anyway. Only `https://poli0981.dev/*` was added, for the links page. They are also TS
constants rather than catalog entries: an address is data (I18N §2), and a catalog is
a thing a translator is invited to change.

**`review` is a flag of its own, not `accepted = false`.** Re-using the latter was
one line and would have made a review indistinguishable from a revocation — offering
Accept, and a Decline that closes the application, to someone who wanted to re-read
their privacy policy. The gate takes a presentational prop instead; first-run
rendering is untouched and `PdLegalGate.test.tsx` (its first test, ever) pins that.

Two things found by running rather than by the suite:

- `app_info` fired **twice** per mount under `npm run dev`. StrictMode's doubling is
  dev-only, but it drew attention to the real one: `key={nav}` remounts `<main>`, so
  every visit to About was a fresh call for a value baked in at compile time. Now
  cached per process in `useAppInfo`. Verified against the bridge log: one call.
- The whole seam — About, re-open, Ctrl+3 refused behind the modal, Close, back on
  About — with zero IPC calls, confirming consent is never touched.

VI catalog complete and checked in the running app; the parity gate gets the rest.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-14 17:32:20 +07:00
poli0981andClaude Opus 5 be0f8caa18 docs: the shell rules, each with the number that proves it
UI-SPEC gains the three rules the first installed build established, and each is written with
what was measured rather than what was intended.

Single instance: five launches, **one process, one window** — checked against the installed
build after rebuilding, because a plugin registered in the wrong order fails silently by
simply not being reached.

Maximize: the window style no longer carries `WS_MAXIMIZEBOX` and still carries
`WS_THICKFRAME`, so it is bounded without being frozen — read off the real `HWND` rather than
inferred from the config that asked for it.

Sidebar-disabled-during-a-plan is recorded beside §8's existing `Ctrl+1..8` rule, since they
are the same rule for two input devices and a reader who finds only one will assume the other
was an oversight.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-13 22:08:38 +07:00
poli0981andClaude Opus 5 4720e1ccb5 docs: close Phase 3, with the numbers it was measured at
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>
2026-08-13 19:48:48 +07:00
poli0981andClaude Opus 5 6840e0378a docs: the write path, the waiver that gates it, and one claim made true
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>
2026-08-13 19:30:12 +07:00
poli0981andClaude Opus 5 484d1a4693 docs: the fifteenth component, and the decision that was open for three slices
**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>
2026-08-13 18:49:59 +07:00
poli0981andClaude Opus 5 8ea9b14ba1 docs: record P1, and the three older defects it surfaced
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>
2026-08-12 22:45:02 +07:00
poli0981andClaude Opus 5 33bc2f967e docs: record Stage 7, and the four items it leaves open
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>
2026-08-09 21:46:25 +07:00
poli0981andClaude Opus 5 8042bdb5f8 docs: record Stage 6, and the DATA-FLOW §8 step nothing performs
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>
2026-08-09 21:46:25 +07:00
poli0981andClaude Opus 5 f354030ed9 docs: record S5, and the controls that are deliberately absent
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>
2026-08-09 21:46:25 +07:00
poli0981andClaude Opus 5 3fc529f42b feat(ui): the preview, the conflict control, the console and the summary
The mutation spine on screen — DATA-FLOW §3 from `Resolving` to `Summary`, and PRD G1's
promise that every mutating operation is previewed before it runs. `usePlanStore` tracks
which step is showing and nothing more: which step is *allowed* next is the flow's business,
in Rust, because two implementations of that state machine is what `core::flow` exists to
prevent.

**`Will downgrade` is its own section.** `ChangeKind` has four variants and UI-SPEC §4 named
three groups, so `Downgrade` had nowhere to go — and it is not rare: a *compatible* resolve
routinely moves a package down to satisfy something else. Folding it in with the upgrades
would put `2.0 → 1.9` under a heading reading "Will upgrade", which is misleading about
exactly the change most likely to surprise. §4 amended.

**`Keep compatible` is disabled on impossible rows.** UI-SPEC said every needs-decision row
hosts the full 3-way control, but `default_decision(is_impossible = true, …)` returns `Skip`
because an impossible package has no compatible version to keep. The UI mirrors the core
rather than offering a choice it would refuse to honour; §4 now says so too.

**The round counter is visible.** `MAX_CONFLICT_ROUNDS` has been in core since M1 with
nothing surfacing it, so a user could hit the cap unwarned. The preview says how many rounds
remain, and the exhausted state keeps the preview on screen with a warning rather than
dead-ending.

**The cancelled summary has copy now** — the third Stage 1 deferral. It says the run stopped
part-way, that a package may have been left half-written, and points at the snapshot, which
is the only complete answer to that.

Two smaller things worth their comments: the console buffer is capped at 2000 lines, because
a source build is tens of thousands and each would otherwise be a React state update holding
a string alive — the full log is the log file, which is what "Copy full log" reads. And
answers are cleared with the round they belonged to, since the next preview may name a
different set and a stale answer would be sent to a flow that has moved on.

"Update selected" is live, so UI-SPEC §5's budget is now real: Updates → Select all →
Update → Confirm.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-04 18:47:15 +07:00
poli0981andClaude Opus 5 729b983321 feat(ui): Space and Ctrl+A row selection, and what "visible" means
UI-SPEC §8 assigns `Space` to row selection and `Ctrl+A` to "select-all-visible". The
second has no meaning once the table is virtualized: only ~25 rows of a 200-package
environment are in the DOM, so "visible" would be whatever the scroll position happens to
be. Resolved as **the current filtered set** — on Updates, the outdated rows, minus pinned
ones exactly as the button excludes them. §8 now says so, since the next person to read it
would otherwise have to re-derive the same answer.

The **row** is the tab stop, not its checkbox. Tabbing through two controls per row is not
keyboard traversal at 200 rows, it is a punishment. So the row carries `tabIndex={0}` and
its own Space handler, the checkbox is `tabIndex={-1}`, and Space is `preventDefault`ed or
the scroll container pages down under the focused row.

`Ctrl+A` is guarded against text inputs. There are none on these screens, but Search lands
in S4 and this is the cheap moment to get it right.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-04 16:26:51 +07:00
poli0981andClaude Opus 5 4ab948ac7b feat: implement the two owner decisions from spike week
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>
2026-07-27 18:38:46 +07:00
poli0981andClaude Opus 5 5e8d78bb27 docs: add design documentation baseline
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>
2026-07-27 17:08:14 +07:00