docs: Phase 4 closed, and the checklist that says so

All six open items are done, recorded with what was actually exercised rather than
"the charter was run": three machines (a real Windows 11 box that had never run
PipDock, Windows Sandbox, a Windows 10 VM), no SmartScreen prompt on any — with the
caveat that reputation is per-hash and unsigned binaries can still warn a future
user, which is why the checksum instructions stay. The three owed charter items plus
a non-ASCII Windows *username*, which is a different case from the non-ASCII path
because the username is in %LOCALAPPDATA% and therefore in the data root, the logs
and the tools venv.

The icon is a decision now, not a deferral. It was called a placeholder because
nobody had chosen it.

RELEASE-CI §5 ticks all eight, and three of the last four turned out to be already
done and never ticked — CodeQL default setup was already not-configured, Discussions
were already on, the secrets were set today. §2's "main protected" claim is true for
the first time; its exact settings, the reason CI / Integration is excluded (a
paths-filtered required check never starts, so it blocks forever), the two contexts
owned by the ops repo, and how to unwedge it are all written down.

Also recorded: the four things Phase 4 found that were not on its list, and the three
rules the About tab settled. Post-1.0 gains the Third-Party-Notices generation
deferred here, a screenshot re-capture, and the OSV host the Security tab will need.

Two long-standing self-contradictions fixed: NOT_YET is two (lib.rs is the
authority; ROADMAP and CLAUDE.md each said two in one paragraph and three or four in
another), and 15 of UI-SPEC §6's 16 components exist, not 16.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-08-14 17:32:20 +07:00
1 parent 196f0408e4
commit d56ad93564
3 files changed
+169 -31

No files matched your search

+38 -6
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, M2 and Phase 3 complete; Phase 4 in progress — the pipeline builds and installs, the RC tag is the owner's call**.
Repo `poli0981/pipdock` · GPL-3.0-only · **Status: 1.0.0. M1, M2, Phase 3 and Phase 4 all complete — the release pipeline runs, `main` is protected, the manual charter is done, and the legal documents match the code.** Post-1.0 is the P1 wave in `docs/ROADMAP.md`.
## Read the docs before changing anything
@@ -73,8 +73,10 @@ Every caller needs an explicit `permissions:` block — callers without one defa
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.
against a 50 ms budget. **15 of UI-SPEC §6's 16 components exist** — `PdEnvSwitcher` alone does
not, and nothing needs it while the header shows the selected interpreter. (This line said 16 of 16
for two milestones; §6 itself was corrected in P4 and is the authority.) `docs/ROADMAP.md` Phase 2
has a table per stage and says where to pick up; read it before starting a slice.
**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
@@ -99,11 +101,14 @@ wrong; the record says why). P1 closed **P0-10**: pip's version is on every Envi
*Upgrade pip* is 2 clicks. **Next is P3** (the three runners + `HealthReport`), then P4 (the Health
screen) and P5 (the gated `ruff --fix`); `~/.claude/plans/b-n-c-th-b-t-snappy-rabin.md` has all
four decomposed, including six corrections to the specs found by running the pinned tools.
`src-tauri/src/lib.rs`'s `NOT_YET` is down to **four** — `health_run`, `health_fix`, and
`env_add_manual`/`logs_tail` which are M3-general — and three tests keep that list honest in both
directions. P2 touched none of them: it is CLI-only on purpose, so P3's `health_run` owns the
P2 touched no `NOT_YET` entry: it is CLI-only on purpose, so P3's `health_run` owns the
implicit sync rather than the frontend getting two ways to reach one operation.
**`NOT_YET` is two**, and only two: `env_add_manual` and `logs_tail`, both M3-general.
`src-tauri/src/lib.rs:25-28` is the authority and three tests keep it honest in both directions —
this file used to say "four" in one paragraph and "two" in another, each true when written and
neither updated.
Three rules P1 left behind, all found by running rather than reading:
- **A venv is never externally managed**, and `sysconfig.get_path("stdlib")` inside one resolves to
@@ -177,6 +182,33 @@ Things worth knowing before you change any of it:
run showed *Back to packages* twice and every suite stayed green. Found by a human using the
installed build. When adding a component test, ask what renders it.
- **A green badge is not a green `main`.** The README badge is per *workflow file* and shows that
file's last run, which may be a schedule on a different commit. `main` was red for a day at
`3eeda05` — every cargo job failing before a crate compiled — because `Cargo.lock` carried a
dependency edge to `thiserror 2.0.19` while its package entry said `2.0.20`, which `--locked`
refuses to repair. Start with `gh run list --branch main`, not the badge. And when bumping a
version: it lives in **five** places (`Cargo.toml`, `Cargo.lock`, `package.json`,
`package-lock.json`, `tauri.conf.json`) and they move together or you have reproduced this bug.
`cargo metadata --locked` is the one-command check.
- **A `docs/` fix and a `legal/` fix are two different changes.** Removing the self-updater updated
`THIRD-PARTY-NOTICES.md` and not `PRIVACY-POLICY.md`, so the shipped privacy policy described a
feature that no longer existed — and, worse, still told users to delete `%LOCALAPPDATA%\PipDock\`
for "a complete reset", which is the folder the program installs into. `docs/SECURITY.md` had
recorded the data-root move correctly the whole time. Anything under `legal/` is what a *user*
reads; grep it separately whenever behaviour changes. Every `legal/*.md` and `LICENSE` is hashed
into `PIPDOCK_LEGAL_DOCS_HASH`, so any edit re-shows the gate once — that is the mechanism
working, not a regression.
- **A spec sentence is not a test.** UI-SPEC §8 asserted for two milestones that `Ctrl+1..N` refused
while a plan owned the screen. It did not: `App.tsx` guarded on `guardOpen`, and `PANEL_PHASES`
excludes `guard` on purpose, so the two sets are disjoint and guarding on one guarded neither.
Invisible until the plan ended and dropped the user on a tab they never chose.
- **Appending to `NAV_KEYS` is free; inserting is not.** `Ctrl+9` for About cost one array entry.
Four comments claimed "a ninth entry would renumber `Ctrl+1..8`" and had the reason wrong —
Snapshots stays a mode of Environments because it would sit *beside* Environments, an insert.
- **Building and installing are their own test tier, and nothing else substitutes.** The first
bundle ever produced exposed three defects in one afternoon: `release.yml` could not have run
(`--locked` is cargo's flag and goes after `--`), the installers shipped no `pipdock.exe` at all,
+27 -4
View File
@@ -38,6 +38,24 @@ permissions: { contents: read }
`main` protected (PR + green CI required). SemVer; tags `vX.Y.Z`. Conventional commits feed the changelog generator.
**Applied 2026-08-14, and it had been false until then** — `/branches/main/protection` returned 404 for four milestones, which is also why `gh pr merge --auto` merged immediately on this repo rather than waiting: with no required checks there is nothing for auto-merge to wait on. Exact settings:
| Setting | Value | Why |
|---|---|---|
| Required checks | `fmt · clippy · test`, `cargo audit`, `lint · typecheck · test · build / build`, `npm audit`, `analyze / Analyze (javascript-typescript)` | the five that run on **every** PR |
| Check app | pinned to `app_id: 15368` (`github-actions`) | a check from another app cannot satisfy a requirement |
| `enforce_admins` | `true` | the owner is the only contributor; protection that exempts them protects nothing |
| Required approvals | **0** | a solo owner cannot approve their own PR, so 1 would deadlock. A PR is still required |
| `strict` | `false` | up-to-date-before-merge is friction on a repo that rebase-merges |
| Linear history | `true` | matches rebase-merge |
| Force pushes / deletions | `false` | |
**`CI / Integration` is deliberately excluded, and this is the trap worth remembering:** its `pull_request` trigger is `paths:`-filtered, so on a docs-only or UI-only PR it never starts — and a required check that never starts stays *pending forever*. Requiring it would deadlock exactly the PRs it has no opinion about. `Re-capture against the latest engines` is schedule-only and excluded for the same reason. The bare `CodeQL` check belongs to the `github-advanced-security` app rather than Actions and is left out too.
**Two required contexts are named by the ops repo, not by this one.** `analyze / Analyze (javascript-typescript)` and `lint · typecheck · test · build / build` come from `poli0981/.github`'s reusables. If either job is renamed upstream, every PipDock PR deadlocks with no obvious cause and no failing check to point at — the fix is to update the protection payload, not the code.
**If protection wedges**, `PUT` the same endpoint with `enforce_admins: false`, or `DELETE /branches/main/protection`. Worth knowing before it is needed rather than discovering it during an incident.
Dependency updates use **Dependabot** (`.github/dependabot.yml`) — the portfolio standard, as evidenced by the ops repo's `dependabot-summary.yml`; there is no Renovate configuration anywhere in the ops repo. Four ecosystems: `cargo`, `npm`, `github-actions`, and `pip` scoped to `tools-requirements.txt` (the Code Health pins). Weekly schedule with minor/patch grouped per ecosystem; security advisories arrive as **immediate, ungrouped** PRs (Dependabot's default for security updates), and the `pip` ecosystem stays its own group so Code Health pin bumps are reviewable in isolation. Watching `pip`/`uv` releases to trigger the parser-fixture job is the scheduled job in `ci-integration.yml`, not the dependency bot.
## 3. Release pipeline (tag `v*`)
@@ -66,7 +84,12 @@ Two active lines at most: latest release gets features; previous minor gets secu
- [x] `.github/ISSUE_TEMPLATE/bug_report.yml` (shipped in this suite) + `config.yml` disabling blank issues.
- [x] `.github/dependabot.yml` covering cargo, npm, github-actions and the Code Health pins.
- [x] `rust-toolchain.toml`, `.nvmrc` (24), `Cargo.lock`/`package-lock.json` committed.
- [ ] **Repo settings (owner, via the GitHub UI or `gh` — not committable):** branch protection on `main`; disable Advanced Security → CodeQL *Default setup* (the reusable is advanced-setup and is rejected at upload time otherwise); enable Discussions for the issue-template contact links.
- [ ] **Secrets via `gh secret set`:** the Discord webhooks (`DISCORD_RELEASES_WEBHOOK`, `DISCORD_REPO_WEBHOOK`, `DISCORD_CI_WEBHOOK`). No signing key — see §3.
- [ ] Replace the placeholder app icon (`src-tauri/icons/`) in the ROADMAP Phase 3 branding pass.
- [ ] README badges: CI, CodeQL, release, license.
- [x] **Repo settings (owner, via the GitHub UI or `gh` — not committable):** branch protection on `main`; disable Advanced Security → CodeQL *Default setup* (the reusable is advanced-setup and is rejected at upload time otherwise); enable Discussions for the issue-template contact links.
- [x] **Secrets via `gh secret set`:** the Discord webhooks (`DISCORD_RELEASES_WEBHOOK`, `DISCORD_REPO_WEBHOOK`, `DISCORD_CI_WEBHOOK`). No signing key — see §3.
- [x] App icon settled (`src-tauri/icons/`). It was called a placeholder because nobody had chosen it; the owner chose it in Phase 4, which is what "a brand decision" needed.
- [x] README badges: CI, CodeQL, release, license.
**Closed 2026-08-14, and three of the last four were already true.** CodeQL *Default setup* read
`not-configured` and Discussions were already on — both had been done and never ticked, which is
its own small lesson about a checklist nobody reads back. The Discord secrets were set the same
day. Branch protection was the only genuinely outstanding item; §2's exact settings are below.
+104 -21
View File
@@ -386,19 +386,16 @@ against the slice that owes 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.
**Phase 4 is complete too** — see its section below. `1.0.0` is tagged.
`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
`logs_tail` (needs the logging subsystem). `src-tauri/src/lib.rs:25-28` and the three tests that
police it in both directions are the authority; a paragraph here used to say "three" and was
describing the state before P5 merged. 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
needed none was wrong; both land implemented, so neither is owed.
The four things P4 was warned it would otherwise rediscover all held: `@tauri-apps/plugin-dialog`
really was absent from `package.json`, the opener really was scoped to GitHub only, UI-SPEC §6
really said 14, and deptry really does name a module rather than a distribution. What the warnings
@@ -654,27 +651,113 @@ window; the real `HWND` style carries no `WS_MAXIMIZEBOX` and still carries `WS_
steps against real artifacts); the installer ships both binaries; program and data no longer share
a directory; the shell bugs above are fixed; README carries the badges RELEASE-CI §5 asks for.
**Still open, in rough order:**
### Phase 4 closed — 2026-08-14
1. **A genuinely clean machine.** This one has run PipDock; isolating the app-data root
approximates the criterion rather than meeting it.
2. **SmartScreen.** The installer has only ever been run scripted, and SmartScreen is an Explorer
behaviour — it needs a double-click on a freshly downloaded file.
3. **The rest of the manual charter** (TESTING §4): the VI locale sweep of the mutation dialogs,
corporate-proxy simulation for `PD-NET-002`, and cancel mid-Phase-B. Fixtures for the scale and
non-ASCII cases are already recorded above.
4. **The icon**, still the Tauri-era placeholder — a brand decision, deliberately not invented.
5. **Version and tag.** Everything is `0.1.0`; the RC and the `v*` tag that fires `release.yml`
are the owner's call, and that tag is the first time the pipeline runs for real.
6. **`docs/README` screenshots**, which want the finished icon first.
All six of the items above are done. What actually happened, item by item, because "we ran the
charter" ages into nothing:
**Repo scaffolding (RELEASE-CI §5)** still owes the two owner-only items: branch protection plus
disabling CodeQL default setup, and the three Discord webhook secrets. Neither is committable.
1. **A genuinely clean machine.** The RC was installed and driven on a real Windows 11 machine
that had never run PipDock, plus **Windows Sandbox** and a **Windows 10 VM under VirtualBox**.
Three installs, three uninstalls, no failures.
2. **SmartScreen produced no prompt** on any of the three. Worth knowing *why* that is not a
guarantee: SmartScreen's reputation check is per-file-hash and per-publisher, and the binaries
are still not EV-code-signed, so a warning on some future user's first download remains
possible. The README's checksum instructions are the answer either way, and they stay.
3. **The manual charter is complete** (TESTING §4). The three that were owed — the VI locale sweep
of the mutation dialogs, cancel mid-Phase-B, and corporate-proxy simulation for `PD-NET-002` —
were all executed, as was a **non-ASCII Windows username**, which is a different case from the
non-ASCII *path* already covered by `E:\sp5\dự án tiếng việt`: the username is in
`%LOCALAPPDATA%`, so it is in the data root, the log paths and the tools venv.
4. **The icon is decided, not deferred.** The green triangle stays. It was called a placeholder
because nobody had chosen it; the owner has now chosen it, which is what "a brand decision"
needed. `bundle.icon` still names only `icons/icon.ico` — correct for a Windows-only build; the
Square*.png set is Microsoft Store furniture nothing reads.
5. **Version is `1.0.0`** in all five places (`Cargo.toml`, `Cargo.lock`, `package.json`,
`package-lock.json`, `tauri.conf.json`). The `v1.0.0` tag is the first real run of
`release.yml`.
6. **Seven screenshots** are in `screenshot/` and referenced from the README. They predate the
About tab, so their sidebar has eight entries where 1.0 has nine.
**Repo scaffolding (RELEASE-CI §5) is complete**, and three of its items turned out to be already
done and undocumented: the Discord webhook secrets were set 2026-08-14, CodeQL *Default setup* was
already `not-configured` (which is what the advanced-setup caller requires), and Discussions were
already on. **Branch protection** was the only genuinely outstanding one and is now applied over
the API — five required checks, `enforce_admins: true`, PR required, linear history. RELEASE-CI §2
has claimed `main` was protected since it was written; that claim is true for the first time.
`CI / Integration` is deliberately **not** a required check: its `pull_request` trigger is
`paths:`-filtered, and a required check that never starts leaves a PR pending forever — so
requiring it would deadlock every docs-only and UI-only PR.
### What Phase 4 found that was not on its list
Four things, three of them defects that had been shipping.
**`main` was red and nobody knew.** `Cargo.lock` at `3eeda05` carried a dependency edge to
`thiserror 2.0.19` while its package entry said `2.0.20` — a lockfile cargo wants to repair and
`--locked` forbids repairing, so every cargo job in every workflow died before compiling a crate.
Same shape as the ruff-pin defect in P4: a Dependabot bump whose base predated the code that would
have caught it. The lesson is the one already written — **check `gh run list` before believing a
green badge**, because the badge is per-workflow-file and shows the last run, not the last commit.
**The privacy policy described a self-updater deleted two weeks earlier**, and told users to delete
`%LOCALAPPDATA%\PipDock\` for "a complete reset" — the folder the program installs into. Following
the shipped privacy policy uninstalled the application. `d829c4f` had updated
THIRD-PARTY-NOTICES and not PRIVACY-POLICY; SECURITY §8 recorded the data-root move and the legal
document never got it. **A `docs/` fix and a `legal/` fix are two different changes**, and the
second is the one a user reads.
**Four documents credited `specta`/`tauri-specta`,** which `bindings.rs` has recorded since M1 that
the project deliberately does not use. One of them was `legal/THIRD-PARTY-NOTICES.md`, i.e. a
licence attribution for a dependency that does not exist, beside eleven that do and were unlisted.
**`Ctrl+N` never refused while a plan owned the screen,** despite UI-SPEC §8 asserting it did since
S3. `App.tsx` guarded on `guardOpen`, and `PANEL_PHASES` excludes `guard` on purpose — the two sets
are disjoint, so guarding on one guarded neither. Invisible, because the sidebar was disabled and
the panel kept rendering, until the plan finished and dropped the user on a tab they never chose.
**A spec sentence is not a test.** Found by reading `App.tsx` to add a ninth tab.
### The About tab (early out of the Post-1.0 wave)
UI-SPEC §4 has specified *Legal & About* since the spec was written, as a section inside Settings,
and four milestones shipped without it — so after acceptance there was no in-app path back to the
documents at all. It is the ninth tab instead, because a read-only surface folded into a screen of
controls is the thing that never gets built.
Three things it settled that outlive it:
- **Appending to `NAV_KEYS` is free; inserting is not.** `Ctrl+9` cost one array entry and one
label. Every comment saying "a ninth entry would renumber `Ctrl+1..8`" was wrong about the
reason: Snapshots stays a mode of Environments because it would have to sit *beside*
Environments, which is an insert.
- **A review is not a revocation.** Re-opening the gate by setting `accepted = false` was one line
and would have offered Accept and a Decline-that-quits to someone re-reading their privacy
policy. `useLegalStore.review` is its own flag and the gate takes a presentational prop.
- **`app_info` fired twice per mount, and only the running app said so.** StrictMode's doubling is
dev-only, but it exposed the real one: `key={nav}` remounts `<main>`, so every visit re-fetched a
value baked in at compile time. `PdAbout.test.tsx` asserted one call and passed, because Testing
Library does not use StrictMode. **Run it, don't just test it** — the twenty-fifth time.
## Post-1.0 (P1 wave)
Security tab (pip-audit), pin auto-suggest, requirements/constraints export-import, cache manager, command palette, dependency graph view, scheduled check. Then P2 candidates by demand: macOS/Linux, per-env engine, elevation broker, winget, JP locale.
**About shipped early, in Phase 4** — see above. Two smaller items were added to this wave rather
than done at 1.0:
- **Generate `legal/THIRD-PARTY-NOTICES.md`.** Both it and SECURITY §7 claimed `cargo about` +
`license-checker` regenerated it at release into a `licenses/` directory; no `about.toml`, no
such directory and no such release step have ever existed. The claim now describes what is
actually done — a hand-maintained inventory of the *direct* dependencies, reconciled against the
manifests at each release. Making it true is the item. Doing it at 1.0 would have meant
complicating `release.yml` on the first run it had ever had.
- **Re-capture the screenshots** once anything visible changes; the seven in `screenshot/` show an
eight-entry sidebar.
Also worth doing when the Security tab lands: `capabilities/external-links.json` will need an OSV
host, because DISCLAIMER §4 and SECURITY §6 both say findings link to the OSV entry and the current
allowlist would reject it — silently, which is the failure mode SECURITY §4 exists to name.
## Standing risks
| Risk | Mitigation |