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>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-08-09 21:46:25 +07:00
1 parent f5badf2750
commit f354030ed9
6 files changed
+113 -19

No files matched your search

+17 -8
View File
@@ -12,11 +12,12 @@ The design is fully specified. Read in this order; do not invent behaviour that
3. `docs/DATA-FLOW.md` — update/install/uninstall/rollback state machines, engine command mapping, **invariants §9**
4. `docs/UI-SPEC.md` — design tokens, screens, click budgets, keyboard map
5. `docs/CLI-SPEC.md` — commands, flags, exit codes, JSON contracts
6. `docs/ERROR-CATALOG.md` — the launch codes and their stderr classifiers. **31 in Rust**
(`Code::ALL`, pinned by two tests); the doc tabulates 29 because it folds `PD-HLT-001..003`
6. `docs/ERROR-CATALOG.md` — the launch codes and their stderr classifiers. **32 in Rust**
(`Code::ALL`, pinned by two tests); the doc tabulates 30 because it folds `PD-HLT-001..003`
into one row. Adding a code means the catalog, `Code::ALL`, both counts, the
"no code without a fixture" gate in `classifier_corpus.rs`, both locale catalogs, and a
re-blessed `golden__schema-Code.snap` — the gate will tell you which you forgot
"no code without a fixture" gate in `classifier_corpus.rs`, both locale catalogs, and
re-blessed goldens — `golden__schema-Code.snap` **and every schema that embeds it**
(`StepResult`, `ExecutionSummary`) — the gate will tell you which you forgot
7. `docs/CODE-HEALTH-SPEC.md`, `docs/SECURITY.md`, `docs/TESTING.md`, `docs/RELEASE-CI.md`, `docs/I18N.md`, `docs/ROADMAP.md`
8. `legal/` — EULA, Disclaimer, Privacy, Third-Party Notices (public; the in-app legal gate links to these GitHub URLs)
@@ -63,15 +64,17 @@ Every caller needs an explicit `permissions:` block — callers without one defa
## Current state
**M1 complete. M2 Stages 1–4 done** (IPC bridge 2026-07-30; Installed+Updates, the mutation spine
**M1 complete. M2 Stages 1–5 done** (IPC bridge 2026-07-30; Installed+Updates, the mutation spine
and search+install all 2026-08-04). The app discovers, lists, previews, decides, executes, streams,
summarises and installs over real commands. **"Update everything" is 4 clicks and "install one" is
4 clicks**, both counted by hand in the running app; search is **22 ms median per keystroke**
against a 50 ms budget. All 16 of UI-SPEC §6's components exist. `docs/ROADMAP.md` Phase 2 has a
table per stage and says where to pick up; read it before starting a slice.
Next is **S5 — uninstall, the guard dialog and the Pins screen**, and it is a small one: the pin
commands already exist from S2, and DATA-FLOW §5's three-option dialog is fully specified.
Next is **S6 — snapshots, the env detail and rollback**. S5 landed `Session::Rollback` and
`RollbackFlow::cancel_handle`, so S6 adds a call site rather than another widening; what it needs is
`RollbackPreview` crossing IPC, the five `snapshot_*` commands, and the env-detail surface UI-SPEC §4
assumes and which does not exist.
Three rules from S2/S3 that bind everything after them:
@@ -86,6 +89,12 @@ Three rules from S2/S3 that bind everything after them:
(inside core) it serializes every other command behind a network call. Read what you need, drop
the guard, then await. This is why `UpdateFlow::start` takes pins rather than a `&Store`, and why
`index::metadata`/`refresh` take the app-data path. It has bitten twice; assume it will again.
- **A dialog is not an enforcement point.** DATA-FLOW §5's three options are what the user *sees*;
what stops a removal is `GuardAck` inside `UninstallFlow::execute`, beside `SnapshotProof`. The
same shape twice: the report and the proof are produced in one call and consumed in another, so
the only way "somebody forgot to look" cannot happen is a value the executing call demands. Any
future flow with a decision between two IPC messages needs its own.
- **Measure in `--release`, and say which build a number came from.** A debug build measures bounds
checks: the same index load is 572 ms in debug and 140 ms in release, and the same keystroke is
176 ms against 16 ms. A design was justified with a figure four times too large before anyone
@@ -95,7 +104,7 @@ Things worth knowing before you change any of it:
- **`cargo test` fails when `ui/src/ipc/generated.ts` is stale.** Fix with
`cargo run -p xtask -- bindings`; the failure names that command and the first differing line.
- **The L4 goldens (`crates/pipdock-cli/tests/golden.rs`, 46 snapshots) are the CLI's output
- **The L4 goldens (`crates/pipdock-cli/tests/golden.rs`, 52 snapshots) are the CLI's output
contract.** A diff there is a real behaviour change — re-bless deliberately, never reflexively.
They are what made the `core::flow` refactor provably behaviour-preserving.
- **Two tests hold the wire format**: `Code::ALL` must serialize as `as_str()`, and no
+2 -2
View File
@@ -61,7 +61,7 @@ requests held back at 2.30.0 (latest 2.32.3) — blocked by apiclient 1.4 (requ
|---|---|
| 0 | success, all steps ok |
| 1 | completed with per-package failures (see JSON `counts.failed`) |
| 2 | plan aborted (resolution impossible & user/skip policy removed everything) |
| 2 | plan aborted, nothing executed (resolution impossible & user/skip policy removed everything; uninstall guard tripped without `--force`, PD-RES-004) |
| 3 | environment error (PD-ENV-*, incl. PEP 668 block) |
| 4 | engine unavailable / version too old (PD-ENG-*) |
| 5 | snapshot failure — nothing was executed (PD-SNP-001) |
@@ -86,6 +86,6 @@ pipdock update --all --env C:\bots\scraper\.venv --yes --json --log-file C:\logs
# Audit what an upgrade would do without touching anything:
pipdock update pandas numpy --dry-run --json | jq '.held_back'
# Refuse-to-break uninstall in CI (exit 1 if guard trips):
# Refuse-to-break uninstall in CI (exit 2 — plan aborted — if the guard trips):
pipdock uninstall legacylib --json || echo "dependents exist, aborting"
```
+17 -1
View File
@@ -83,6 +83,18 @@ Selection → [Uninstall] → GuardCheck: reverse-dep graph over full removal se
Rationale: bare `pip uninstall` performs **no** dependency check — this guard is a core value-add.
**The dialog is not the enforcement point.** *Remove dependents too* is the caller running the guard
*again* over the widened set, because pulling Y in can break Z and stopping after one level hands the
user a set that still breaks something. And the removal itself refuses to run unless the guard was
clear or the user explicitly accepted the breakage — `flow::GuardAck`, checked in
`UninstallFlow::execute` the way `SnapshotProof` is, so a caller that never looked at the report
cannot proceed by omission. Attempting it anyway is **PD-RES-004**, raised before the snapshot is
written so a plan that will not run leaves nothing behind.
A removal is blocked on a PEP 668 environment exactly as an update is: §2's preamble is "all mutating
flows", and removing from a system Python is the more dangerous of the two, since no resolver stands
between the user and the damage.
## 6. Summary model (owner requirement)
```json
@@ -125,7 +137,11 @@ Snapshot selected → Diff = (current freeze) vs (snapshot freeze)
## 9. Data-flow invariants (enforced in `pipdock-core`, tested)
1. No mutating engine call without a `ResolutionReport` accepted in this session.
1. No mutating engine call without an **accepted proof** for this session: a `ResolutionReport` for
a resolve-shaped plan (update, install), a `GuardReport` plus a `GuardAck` for a removal (§5), a
`RollbackPlan` for a restore (§8). Originally written as "a `ResolutionReport`", which the
uninstall path cannot produce — there is nothing to resolve — leaving the one flow with no
preview also the one flow the invariant did not describe.
2. No mutating engine call without a successful snapshot write.
3. `plan_execute` refuses a report older than 10 minutes or if the env's probe hash changed (env drifted → re-resolve).
4. Every failure surfaced to UI/CLI carries a catalog code.
+52 -4
View File
@@ -232,8 +232,9 @@ one synchronous read at each call site, and the flow no longer touches a databas
### Stage 4 — search, the dock bay and install — **done 2026-08-04**
Five commits. Both exit criteria met and measured in the running app, and 16 of UI-SPEC §6's 16
components now exist.
Five commits. Both exit criteria met and measured in the running app. *(The "16 of 16 components"
claim recorded here was wrong: the count had folded in components that are not on UI-SPEC §6's list.
It was 13 of 16 then and after S5 — see §6, which now says so.)*
| | What landed |
|---|---|
@@ -267,9 +268,56 @@ debug** rather than printing a number that means nothing.
2. **Every result offered [Add], including installed packages**, because only `PdPackages` ever
loaded the installed set. That is exactly the mistake DATA-FLOW §4's chips exist to prevent.
### Stage 5 onward — where to pick up
### Stage 5 — uninstall, the guard dialog and the Pins screen — **done 2026-08-09**
Slices, sizing and exit checks are in the plan; the order is **S2 → S3 → S4 → S5 → S6 → S7**. S2, S3 and S4 are done (above). **S5 — uninstall, the guard dialog and the Pins screen — is next**, and it is a small one: `uninstall_guard` and `uninstall_execute` are the last two mutating commands, DATA-FLOW §5's three-option dialog is fully specified, and the pin commands already exist from S2. Exit: uninstall = 3 clicks, and *Remove dependents too* re-guards rather than proceeding.
Twelve commits. Every mutating command in ARCHITECTURE §7 now exists, and removal is the first flow
whose *whole* value is refusing to do what was asked.
| | What landed |
|---|---|
| **Core** | `GuardReport.breaks` carries `BrokenDependent { pkg, version, constraint }` — the specifier, not just the name. `GuardAck` makes the guard an enforcement point rather than a dialog. PEP 668 refused on removal. New code **PD-RES-004**. |
| **Execution** | `execute_uninstall` emits the `stepStarted`/`stepFinished` lifecycle it never had, checks the cancellation token in its loop, takes a `base` step index shared with `execute_rollback`, and honours `--no-snapshot`. |
| **Bridge** | One `Session` enum for all four flows, with typed claims; `uninstall_guard`, `uninstall_execute`; `plan_cancel` async, and now discarding a parked session. |
| **UI** | `PdDialog` (the repo's first modal), `PdUninstallDialog`, `PdPinChip`, the Pins screen, the row's ✕, and the `failed` phase. |
| **L3** | The first mocked `@/ipc`, the first store test, the first screen test. 6 files → 9; 59 tests → 79. |
**Exit criteria, counted and verified in a running app** (driven in the Browser pane against a
stubbed bridge, per the recipe that found Stage 2's double fetch): uninstall is **exactly 3 clicks**
— Installed → row ✕ → *Remove* — and 4 when the guard trips, by design. The dialog reads
`pandas 2.1.4 requires numpy<2,>=1.26.0`, naming the dependent **and** its constraint. *Remove
dependents too* issues a **second** `uninstall_guard` over the widened set with **no**
`uninstall_execute` in between. At the CLI, against a real venv, the guard refuses and exits 2 with
every package still installed.
**Five live bugs came out of it, none of them S5 features:**
1. **A claim that found nothing wedged the slot.** `plan_decide`/`plan_execute` wrote `Busy` before
discovering there was no plan, and never released — so one out-of-order call from the UI made
every later command answer `PD-RES-003` for a plan that had never existed.
2. **`execute_uninstall` emitted no lifecycle markers**, and every line carried `step: 0`. The CLI
never noticed because it prints `event.line()` and nothing else; the console drawer groups on
`stepStarted` and the live region counts `stepFinished`, so the GUI would have shown an empty
drawer against a green suite.
3. **A cancelled removal removed everything, then reported `cancelled: true`.** The loop had no
token check at all.
4. **`--no-snapshot` was parsed and ignored on the uninstall path** — the same waiver meant "waive"
for an update and nothing for a removal, the one operation with no way back.
5. **The pin button was a tab stop**, so Space on it toggled the row's *selection* instead of
pinning. The rule was enforced on the checkbox and forgotten one element later.
**And one specification gap closed:** DATA-FLOW §9.1 required "a `ResolutionReport` accepted in this
session", which the uninstall path cannot produce — there is nothing to resolve. It now names the
proof per plan shape, so the one flow with no preview is no longer the one flow the invariant did not
describe.
### Stage 6 onward — where to pick up
The order is **S5 → S6 → S7**, then Phase 3. S5 is done (above). **S6 — snapshots, the env detail and
rollback — is next.** `Session::Rollback` and `RollbackFlow::cancel_handle` already landed in S5, so
S6 adds a constructor call site rather than another widening; what it needs is `RollbackPreview`
crossing IPC, the five `snapshot_*` commands, and the env-detail surface UI-SPEC §4 assumes and which
does not exist. Exit: rollback = 4 clicks, and the preview lists `unrestorable_lines` explicitly as
`PD-SNP-002` rather than dropping them.
**All three Stage 1 deferrals are closed**, each in S3 as planned — the `plan-progress` lifecycle enum, the Windows Job Object, and the `ExecutionSummary.cancelled` copy. Deferring them to the slice that could verify them worked: each was finished against a running UI or a real process tree rather than against a guess.
+1 -1
View File
@@ -8,7 +8,7 @@
2. The data-flow invariants (DATA-FLOW §9): no mutation without accepted plan + snapshot.
3. Conflict presentation: held-back attribution sentences must match fixture ground truth.
4. Skip-and-continue semantics and summary counts.
5. Reverse-dependency guard correctness.
5. Reverse-dependency guard correctness — including that it is *enforced*, not merely reported: a removal the user never accepted must be refused (`GuardAck`, PD-RES-004), and widening a removal must re-run the guard rather than proceed.
## 2. Layers
+24 -3
View File
@@ -51,7 +51,10 @@ Sidebar is icon+label, collapsible to icons. Status line (mono) always shows env
**Environments.** Auto-discovered list (source chip: registry / py launcher / uv / manual) with python version and package count; PEP 668 envs carry a red `MANAGED` chip and a disabled state explaining PD-ENV-002. Actions: *Browse…*, *Rescan*, star-as-default.
**Installed.** Virtualized table: name (mono) · version · latest · size · chips. When the env's `hidden_user_site` is non-null (non-venv system Pythons only — see SECURITY §2), an inline `--color-info` note above the table says user-account packages are not listed and names the path; it is informational, never a block, and never appears for a venv. Up-to-date rows use `--color-text-dim` (owner's "dimmed" requirement); outdated rows show an `UPDATE` badge; pinned rows a 🔒 `--color-info` chip. Row actions: pin/unpin, uninstall, details. Multi-select via checkboxes; bulk action bar appears on selection.
**Installed.** Virtualized table: name (mono) · version · latest · size · chips. When the env's `hidden_user_site` is non-null (non-venv system Pythons only — see SECURITY §2), an inline `--color-info` note above the table says user-account packages are not listed and names the path; it is informational, never a block, and never appears for a venv. Up-to-date rows use `--color-text-dim` (owner's "dimmed" requirement); outdated rows show an `UPDATE` badge; pinned rows a 🔒 `--color-info` chip. Row actions: pin/unpin and uninstall, as two inline buttons rather than a `⋮` menu. A menu would
spend one click opening and one choosing, leaving one of §5's three for a confirm that has to name
what breaks; "details" has no panel to open yet, and when it does all three fold into a menu with the
budget intact. Neither button is a tab stop — the row is (see §8). Multi-select via checkboxes; bulk action bar appears on selection.
**Updates.** Same table filtered to outdated, badge count in sidebar. Header: *Select all* (excludes pinned; shows "3 pinned excluded"), *Update selected*. After resolve → **Preview panel** replaces the table: grouped sections — *Will upgrade* (A `1.2 → 2.0`), *Will downgrade*, *Will install*, *New dependencies*, *Needs decision* (held-back in `--color-warn` with one-line blocker sentence; impossible in `--color-danger`). Each needs-decision row hosts a segmented control: **Keep compatible · Skip · Force latest** (Force opens an inline confirm naming what breaks). Footer: `Confirm (n changes)` / `Back`.
@@ -63,7 +66,13 @@ Sidebar is icon+label, collapsible to icons. Status line (mono) always shows env
**Search.** Search field autofocused; results stream under 50 ms per keystroke from the local index. Result row: name · summary (from cached metadata) · latest · `INSTALLED ✓`/`UPDATE` chip when applicable · **[Add]**. Right detail panel: description, requires-python, license, links. Queue ("**dock bay**") docks along the right edge as a slim column of added packages with editable version fields and `Install (n)`.
**Pins.** Pin list with reason field; (P1) auto-suggest section: "`urllib3` — 12 packages depend on it. Pin?".
**Pins.** Pin list with reason field, committed on blur; unpin per row. **Exclude pins only**: a
`Hold` pin is rendered faithfully if one exists, but creating one is not offered, because
`pins::hold_requirements` has no caller and `engine::plan_requirements` restates every package at its
*installed* version — a hold at any other version is a promise nothing keeps, and the CLI cannot
create one either. With no environment selected the screen says so rather than "no pins": pins are
keyed by `env_hash`, so that is not an empty list. (P1) auto-suggest section: "`urllib3` — 12
packages depend on it. Pin?".
**Snapshots** (surfaced under Environments → env detail): timeline of snapshots with trigger label, diff viewer (added/removed/changed in mono), `Rollback…` with its own preview per DATA-FLOW §8.
@@ -75,12 +84,15 @@ Sidebar is icon+label, collapsible to icons. Status line (mono) always shows env
## 5. Click budgets (owner ceiling: 5)
Every click counts, including the one that opens the tab — except on Environments, which is where the
app lands. Counted by hand in the running app, never inferred from the markup.
| Flow | Clicks | Path |
|---|---|---|
| Update everything | **4** | Updates → Select all → Update → Confirm (app auto-scans on env open) |
| Update everything, 1 conflict kept compatible | **4** | default choice needs no extra click |
| Install one package | **4** + typing | Search (autofocus) → result [Add] → Install → Confirm |
| Uninstall one package | **3** | Installed row ⋮ → Uninstall → Confirm |
| Uninstall one package | **3** | Installed → row ✕ → *Remove* (4 when the guard trips: → *Remove the dependents too* → *Remove*) |
| Rollback last snapshot | **4** | Env detail → snapshot → Rollback → Confirm |
| Switch engine | **3** | Settings → engine radio → (auto-saved) back |
| Run Code Health | **3** | Health → Run (folder persisted) → view |
@@ -89,6 +101,15 @@ Sidebar is icon+label, collapsible to icons. Status line (mono) always shows env
`PdSidebar`, `PdStatusLine`, `PdEnvSwitcher`, `PdPackageTable` (virtualized), `PdPackageRow`, `PdBadge`, `PdPreviewDiff`, `PdConflictRow` (segmented 3-way), `PdDockBay` (queue), `PdConsoleDrawer`, `PdSummarySheet`, `PdSnapshotTimeline`, `PdHealthReport`, `PdLegalGate`, `PdEmptyState`, `PdOfflineBanner`.
**13 of those 16 exist** as of S5. Absent: `PdEnvSwitcher` and `PdSnapshotTimeline`, which arrive
with the env detail in S6, and `PdHealthReport`, which arrives with Code Health in M3. (ROADMAP and
CLAUDE.md both claimed 16 of 16 after S4; the count had quietly folded in components that are not on
this list.) Four components not on this list have
turned out to be load-bearing and are listed here so the inventory stays honest: `PdErrorRow`
(ERROR-CATALOG §3's row, used by every error surface), `PdDialog` (the shared modal §7's destructive
confirms need), `PdUninstallDialog` (§5's three options) and `PdPinChip` (the 🔒 chip, shared by the
table and the Pins screen).
## 7. States & feedback
- Loading: skeleton rows in surface-2, never spinners longer than 300 ms without text.