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>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-08-13 19:48:48 +07:00
1 parent b083e75505
commit 4720e1ccb5
4 files changed
+55 -9

No files matched your search

+8 -2
View File
@@ -1,7 +1,7 @@
# PipDock — working notes for Claude
Windows GUI + CLI for bulk-managing Python packages. Tauri 2 + Rust core + React 19.
Repo `poli0981/pipdock` · GPL-3.0 · **Status: M1 and M2 complete; Phase 3's five slices done, the tail next**.
Repo `poli0981/pipdock` · GPL-3.0 · **Status: M1, M2 and Phase 3 complete; Phase 4 (RC → v1.0) next**.
## Read the docs before changing anything
@@ -74,7 +74,7 @@ summarises and installs over real commands. **"Update everything" is 4 clicks an
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.
**Phase 3's five slices are done.** P4 put Code Health on screen: `PdHealthReport` is UI-SPEC §6's
**Phase 3 is complete** — six slices, exit criteria met and recorded. P4 put Code Health on screen: `PdHealthReport` is UI-SPEC §6's
fifteenth of sixteen, `EnvRow.healthProject` remembers the folder per environment, and
`health_save_report` writes Markdown + JSON. **`NOT_YET` is down to two**, both M3-general — P5 landed the
gated `ruff --fix`, PipDock's first write outside site-packages and `%LOCALAPPDATA%`. P4 *did* need new commands, contrary to the earlier claim — one shipped, and
@@ -164,6 +164,12 @@ Things worth knowing before you change any of it:
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
`SCHEMA_TYPES` property may contain `_`. Both fail at `cargo test`.
- **A control that is not a tab stop is a control a keyboard user does not have.** Making the
package row the only tab stop is right — 200 rows would otherwise be 600 — but every button
inside one was `tabIndex={-1}`, so *Pin* and *Remove* were mouse-only, which is a WCAG 2.1.1
failure. The ARIA grid answer is a roving tabindex (`←`/`→`, `Esc` back out), and P6 added it.
`Enter` on a row is the **non-destructive** primary — pin, never uninstall.
- **Run it, don't just test it.** Every unplanned bug in Stage 1 *and* Stage 2 came from executing
against a real environment, a real runner or a real browser — never from reading code or from a
passing suite. Stage 1: the watchdog that never killed anything, `--json` that never parsed,
+1 -1
View File
@@ -77,7 +77,7 @@ requests held back at 2.30.0 (latest 2.32.3) — blocked by apiclient 1.4 (requ
`--json` payloads are the serde-serialized core types (`Dist`, `OutdatedDist`, `ResolutionReport`, `ExecutionSummary`, `CheckReport`, `GuardReport`, `HealthReport`) — schema documented by `pipdock schema <type>` which prints the JSON Schema generated from the Rust types, so scripts can pin against it. Streaming commands (`update`, `install`, `health`) with `--json` emit NDJSON events matching the GUI's `plan-progress` payloads, terminated by a final `summary` object.
> **Not implemented, recorded 2026-08-12 (Phase 3 · P2).** No command in the binary emits NDJSON. `update`, `install`, `uninstall` and `tools sync` all stream engine output as plain lines to **stderr** and print a single final object to stdout; `health` is still the M3 stub. Either this paragraph or four commands are wrong, and closing it means changing the output shape of every streaming command at once — so it is its own slice, not a thing to half-do while adding a fifth. `tools sync` matches the existing behaviour deliberately rather than becoming the one command that is inconsistent with the other four.
> **Not implemented, recorded 2026-08-12 (Phase 3 · P2).** No command in the binary emits NDJSON. `update`, `install`, `uninstall` and `tools sync` all stream engine output as plain lines to **stderr** and print a single final object to stdout; `health` does the same since P3, and `health --fix` prints one document — the `FixReport`, not the pre-fix report, which describes a state that no longer exists by the time the command returns. Either this paragraph or four commands are wrong, and closing it means changing the output shape of every streaming command at once — so it is its own slice, not a thing to half-do while adding a fifth. `tools sync` matches the existing behaviour deliberately rather than becoming the one command that is inconsistent with the other four.
`GuardReport.breaks` maps each package being removed to the installed packages that would break, and each of those carries the specifier that says so: `{"numpy": [{"pkg": "pandas", "version": "2.1.4", "constraint": "<2,>=1.26.0"}]}`. `constraint` is the **bare specifier tail** — the distribution name is the map key, so a caller joins the two halves itself; `version` is omitted when the graph does not know it, and `constraint` is empty for an unconstrained dependency. DATA-FLOW §5's dialog needs the specifier to say *"Removing X breaks Y (requires X>=1)"*, and a bare list of names tells the user what will break but not whether they can live with it.
+41 -5
View File
@@ -383,11 +383,17 @@ against the slice that owes it.
### Where to pick up
**Phase 3's five slices are done.** P1 (pip upkeep), P2 (the tools venv), P3 (the runners and
`HealthReport`), P4 (the Health screen) and P5 (the gated `ruff --fix`) are merged, each with a
stage table above. **What remains is the tail:** `Enter` as primary action, folding the `aria-live` regions
(there are ten now, not the six this file used to claim), the doc reconciliation, and the two dead-code
follow-ups P2 deferred. `~/.claude/plans/b-n-b-t-u-ph-n-tranquil-anchor.md` decomposes all of it.
**Phase 3 is complete.** P1 (pip upkeep), P2 (the tools venv), P3 (the runners and `HealthReport`),
P4 (the Health screen), P5 (the gated `ruff --fix`) and P6 (the tail) are all merged, each with a
stage table above, and the exit criteria are recorded with the numbers they were measured at.
**Next is Phase 4** — the release pipeline, the manual charter, and a clean install of the RC on a
machine that has never run PipDock.
`NOT_YET` is down to **two**, both M3-general: `env_add_manual` (*Browse…* has no surface) and
`logs_tail` (needs the logging subsystem). The M3 debt list is otherwise unchanged: dead
`pins::hold_requirements`, unread `allow_externally_managed`, DATA-FLOW §8's dry-run resolve,
snapshot retention, `PdEnvSwitcher`, CLI-SPEC §6's NDJSON gap, and `RunOptions`/the confidence floor
reaching Settings.
`NOT_YET` is down to three and **only `health_fix` is Phase 3's**. P4 did add two commands after
all — `health_save_report` and, had it been taken, `health_cancel` — so the earlier claim that it
@@ -413,6 +419,36 @@ Tools venv, deptry/vulture/ruff runners + report UI + gated fix, pip upkeep, bug
Decomposed **P1** pip upkeep · **P2** the tools venv · **P3** the runners + `HealthReport` · **P4** the Health screen · **P5** the gated `ruff --fix`. Three of the sentence's items are already spent: the bug-report deep link landed in S7, `PdOfflineBanner` in S4, and the keyboard map's `Ctrl+1..8` in S7 — what remains of "keyboard map" is `Enter` as primary action and folding the six `aria-live` regions. The icon/branding pass belongs with Phase 4's release slice; it churns binaries that must not sit inside a feature diff.
### Phase 3 · P6 — the tail — **done 2026-08-13**
Three commits, and **Phase 3 is closed**. The keyboard item turned out to be hiding a WCAG failure; the rest was owed bookkeeping.
| | What landed |
|---|---|
| **UI** | roving tabindex in `PdPackageRow` (`←`/`→`/`Esc`), `Enter` as the non-destructive primary, two live regions folded |
| **Core** | `uv::parse_dry_run` deleted — the last `todo!()` in the workspace — and `clippy::todo` flipped `allow` → `warn` |
| **Docs** | UI-SPEC §8's keyboard map and the two rules behind it; CLI-SPEC §6's stale "`health` is still the M3 stub" |
**Pin and Remove were unreachable without a mouse.** Every control in a package row is `tabIndex={-1}`, which is a sound trade for the checkbox — `Space` does its job from the row — but applied to the two action buttons it removed the actions entirely. The row was the only tab stop and there was nowhere further to go. Found by tabbing to a row in the running app and pressing every key that should have done something; invisible to a suite that clicks.
The audit's other finding is worth keeping: **`Enter` already worked everywhere else**, because every other primary action in the app is a real `<button>` and buttons handle it natively. "Zero `Enter` handlers" was true and misleading. The gap was one element that only looks like a control.
**The live-region pair that mattered was not the one being counted.** ROADMAP had said "six regions" for two slices; there were ten. But the duplication that actually reached a user was `PdConsoleDrawer` and the panel that opens it announcing the same `done/total`, so a screen reader heard every step twice. Eight now, with both genuine conflicts removed rather than the number merely reduced.
### Phase 3 exit criteria — **met 2026-08-13**
*"CODE-HEALTH flows pass on two real projects (one pyproject, one requirements-only)."* Run in `--release` against a warm tools venv:
| Project | Result | Time |
|---|---|---|
| requirements-only | 1 dependency, 3 dead-code, 3 lint (3 fixable in 1 file) | 1.4 s |
| declares nothing | `ran: [vulture, ruff]`, `problems: []` — deptry correctly not run | 1.3 s |
| seeded git repo | 6 fixable across 2 files; `--fix` changed **exactly** those two | — |
The fix path's refusals were exercised on the same repository: non-TTY without `--yes`, `--yes` over a dirty tree, and `attrib +R` on one target — the last confirming the fix refuses **as a whole**, leaving the other, writable file untouched.
**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 works), and the fix dialog end to end. All three are reachable only from `npm run tauri dev`.
### Phase 3 · P5 — the gated `ruff --fix` — **done 2026-08-13**
Five commits. **`NOT_YET` is down to two, both M3-general**, and PipDock has its first write outside site-packages and `%LOCALAPPDATA%`.
+5 -1
View File
@@ -163,6 +163,10 @@ table and the Pins screen) and `PdRollbackPreview` (DATA-FLOW §8's preview, inc
## 8. Keyboard & accessibility
Full keyboard traversal: `Ctrl+1..8` sidebar tabs, `/` focuses search, `Space` toggles row selection, `Ctrl+A` select-all-visible, `Enter` primary action, `Esc` closes drawers.
Full keyboard traversal: `Ctrl+1..8` sidebar tabs, `/` focuses search, `Space` toggles row selection, `Ctrl+A` select-all-visible, `Enter` primary action, `Esc` closes drawers, and **`←`/`→` move within a focused row** (P6).
**The arrow keys are not decoration, and the gap they close was real.** Making the row the only tab stop is what keeps 200 rows from becoming 600 — but every control inside one is `tabIndex={-1}`, and that left *Pin* and *Remove* reachable by mouse only: a WCAG 2.1.1 failure, found by tabbing to a row in the running app and discovering there was nowhere further to go. `←`/`→` are the ARIA grid pattern's roving tabindex, `Esc` returns focus to the row, and no tab stops are added.
**`Enter` on a row is the *non-destructive* primary.** On a package row that is pin, never uninstall: a row has one reversible annotation and one irreversible removal, and a destructive operation one keypress from a focused row is an accident waiting rather than a primary action. Everywhere else in the app `Enter` needs no binding at all, because every other primary action is a real `<button>`.
**"Select-all-visible" means the current filtered set, not the rendered window.** Resolved in S2: the package table is virtualized, so only ~25 of a 200-package environment are in the DOM at any moment and "visible" would otherwise mean whatever the scroll position happens to be. `Ctrl+A` selects every *selectable* row in the set the screen is showing — so on Updates that is the outdated rows, and pinned rows are excluded there as they are from the *Select all* button. The row, not its checkbox, is the tab stop and the target of `Space`; tabbing through two controls per row is not traversal at 200 rows. Contrast: all text tokens meet WCAG AA on their surfaces (verified in the design-token test); focus ring 2 px accent, never removed. Screen-reader labels on all icon buttons; live region announces execution progress summaries ("13 of 15 complete"). Windows high-contrast mode: tokens fall back to system colors.