8.2.17 Phase 5 decisions, ahead of Phase 4's exit, agreed 24 October 2026
8.2.17 Phase 5 decisions, ahead of Phase 4's exit, agreed 24 October 2026¶
Rulings by the author, taken through /np-plan phase 5 in five rounds of questions while Phase 4
was in progress: WP53 had merged, and WP54, WP55, the author's sessions, the fix packages from WP56,
the documentation increment and the close remained. The author asked to "already begin discussion
and brainstorming on phase 5", with two first aims: to find out "what kind of GUI and features I
actually want, because it is not clear in my head", and to build "a robust workflow for GUI
development that allows us both to see and control the GUI". The author first chose a design-only
overlap, then said that Phase 4's packages finish before any real implementation and asked whether
the workflow handles two packages in parallel. It did not: §8.4.4 ran one package at a time,
current.md held one position, and alpha tags, register numbers and changelog sections assumed one
branch in flight. S1 states the narrowed overlap and S15 the rule that carries it. S16 to S20 were ruled the same day
on the plan's shipping review (CODE_REVIEW_015), when the author asked to resolve its open items,
REV-126 to REV-133, in the same pull request. S21 to S23 were ruled the same day, while WP5.01 was
planned, when the author wrote: "Ensure that this planning includes also 1) an interactive grilling and
brainstorming on how the GUI is to be organized (i.e., not just stage by stage) and should look and feel like 2) an
expanded workflow, skills, or agents to efficiently perform GUI development". S24 records the
author's answers to that plan's open items the same day. The letter series continues at S.
| # | Decision | Consequence | Clause changed, and when |
|---|---|---|---|
| S1 | Only Phase 5's design study, WP5.01, overlaps Phase 4. WP5.01 is prose and Artifact pages. Before v0.5.0 is tagged, no Phase 5 package changes src/, tests/, the case schema or the public API, and WP5.02 onward starts after v0.5.0 |
Phase 4's user-testing findings can still move the API that the shell sits on, so the shell is designed but not built until they land. M3's "Phase 4 does no GUI work" holds for code | §8.4.4, in this commit |
| S2 | The GUI is a workbench for every user, P1 to P3. In the author's words: "a fully fledged workbench, with distinct tabs for each part of the workflow", allowing "straightforward editing of variables and designs (e.g., a geometry builder)" and exposing "well-integrated tools (e.g., pore mutator, physics editor/builder, ...) that links bidirectionally with a live visual component when relevant". "Think of it as the perfect merge of PyMol and COMSOL." QR-10's guided run is one route through it | The former Phase 4 increment (sweep builder, result browser, figure export, case comparison) becomes part of the workbench's scope for the design document to place. VER-60's rule stands: the shell holds no physics | §8.1's Phase 5 rows, in this commit; P3's "desktop application" and QR-10's wording, in WP5.01's design-document commit, with the clauses M3 defers to it |
| S3 | The physics editor composes models from registered building blocks, and its architecture leaves room for user-authored equations. Composition is a library capability first, in physics/ with its own Tier 1 and Tier 2 tests, and the shell surfaces it. In the author's words: "start with 2, and make sure it has a proper architecture for implementing 3 in the future. This will indeed be a large amendment, but we have no time constraints" |
Equations typed in the shell would amend QR-13 and RSK-15's "the shell holds no physics", and no tier could verify them; that amendment is not scheduled. The composer is a later phase (S7) | None now. WP5.01's design document writes the composer's requirements, tagged for its phase |
| S4 | The pore mutator is staged. First a charge-level mutation: a residue's protonation, charge or radius is edited at stage 7's PQR step, with no new side chain. Then a structural mutation, which replaces the side chain in 3D and re-runs density, contour, mesh and charge, designed now and built later, library first, with a vetted dependency | The charge-level mutator rides on the PQR artefact and inputs.pqr, which Tiers 1 and 2 already verify, so it fits v0.6. Structure preparation stays out of the library until its phase |
§8.1's Phase 5 deliverable, in this commit |
| S5 | The geometry builder is a full 2D sketcher of the (r, z) domain: lines, arcs, booleans and named boundaries, meshed by the library. The solve stays 2D axisymmetric (N4) | A library capability first, in geometry/ and mesh/, and a later phase (S7). v0.6's geometry tab offers what exists: the parametric primitives of mesh/primitives.py and the profile editor over inputs.profile |
§8.1's Phase 5 deliverable, in this commit |
| S6 | The live views link both ways: a residue and the charge map; a geometry and its parameters; a field and its probes and cuts; a run and its result. Every later feature's design asks whether a live view serves it, and how | v0.6 builds the four links over today's capabilities. Each becomes a requirement of the design document | None now. WP5.01's design document |
| S7 | v0.6 delivers the shell; the new tools follow in their own phases. Phase 5 delivers the design document for the whole workbench, the visual-feedback workflow, and the browser shell with its tab, tool and live-view architecture over what the library can already do, plus the charge-level mutator. The physics composer, the structural mutator and the sketcher each become a later phase, library first, numbered and ordered against validation when Phase 5 closes | Validation (Phase 6, v0.7) is not held behind the tools when the author's data arrive. RSK-15's severity rises to High, and its mitigation is restated. §8.3's figures exclude the tool phases | §8.1, RSK-15 and §8.3, in this commit |
| S8 | A spike chooses the front end. WP5.02 builds one hard screen, the residue and charge-map link with a sketcher stub, twice: in a Python-first framework and as a Python server with a TypeScript application. It measures code size, responsiveness and testability, and the author rules from the evidence. TypeScript in the repository is acceptable if it wins. End users receive prebuilt files (CON-07) | M3's "the design document chooses its server library" is settled by WP5.02's spike and recorded in ADR-004 | ADR-004, in WP5.02 |
| S9 | The visual-feedback workflow has two loops. Mockups and reviews are private Artifact pages that the author opens and comments on from any device, from a cloud session. Live iteration on the built shell runs in a local Claude Code session, with a development server that reloads, which the session drives in the desktop application's browser pane while the author watches and takes over | F5's headless rendering stays the implementer's check. The browser pane cannot reach a server inside a cloud container, so live work is local | CONTRIBUTING.md and §8.4.4, in WP5.02 |
| S10 | The shell boots into named fixture states and renders every screen headless; CI checks that each screen loads with its controls, not its pixels | The renders serve review and documentation increment 5. A pixel-difference gate is not adopted, because fonts and graphics differ between runners | A proposed VER- identifier, in WP5.02 |
| S11 | The workbench's document is a plain project folder: case files that the command line still runs, the store, sweeps, and a small project file of layout and comparisons, holding no physics. In the author's words, it should make it "easy to build libraries and organise models and results". A project exports as a portable copy of readable files, never an opaque archive like COMSOL's .mph |
The case file stays the unit of reproducibility (FR-25). The project file is a new schema | None now. WP5.01's design document |
| S12 | The workbench installs with one documented uv command and starts with nanopnp gui, which opens the browser. Solves run on the user's machine, and the browser speaks to the server through a network API, so that a remote server can be added without a redesign. v0.6 has no login and no multi-user use |
The PyInstaller bundle and the packaging probe leave with Qt (M3), and QR-10's observation includes the install. Installers stay post-1.0 (F5) | ADR-004's packaging NOTE, CON-09's PySide6 clause and RSK-13, in WP5.01's design-document commit, as M3 schedules |
| S13 | The phase gate: QR-10, observed with a nanopore experimentalist from the author's laboratory who has not used nanopnp, at the close; VER-43, VER-44, VER-55 and VER-60 as the design document restates them; every capability of the Qt shell present in the browser shell before Qt leaves; each v0.6 requirement with its test or review check; Tiers 1 and 2 passing. A QR-10 miss is waived and carried by the author's ruling, and QR-10 stays open into the first tool phase | v0.6 can ship a shell that a non-programmer could not yet use unaided. The author chose this over fixing and re-observing | §8.1's Phase 5 gate, in this commit |
| S14 | Two study packages open the phase: WP5.01, discovery and the design and requirements document, with a critique of the Qt shell and the author's jobs drawn as clickable mockups; WP5.02, the spike and the visual-feedback workflow, ending in S8's ruling. The remaining packages stay provisional until /np-plan amend 5 |
WP5.01 is prose and WP5.02 is code, so each is verified in its own pull request | The Phase 5 plan, in this commit |
| S15 | At most two lanes are in flight: the current phase, one package at a time, and the next phase's prose-only study. While two pull requests are open, /np-implement and /np-ship take wp <n>. current.md holds one position line per lane, and each package edits only its own. A package merged before its previous phase's release takes no alpha tag, and its CHANGELOG.md entry waits under the next release. The pull request that merges second renumbers its new REV-nn rows, history records, code-review reports and VER-/VAL- identifiers to one above the highest on main |
Versions on main keep increasing, and two branches cannot claim one number. In the author's words: "I will still finish the work packages of phase 4 before starting any real implementation work" |
§8.4.1, §8.4.4, CONTRIBUTING.md, .claude/workflow/core.md, .claude/skills/np-implement/wp.md and .claude/skills/np-ship/wp.md, in this commit |
| S16 | From Phase 5, a work package is named by its phase and its number within the phase, from 01: WP5.01, WP5.02, and so on. The plan file is docs/plans/wp5.01-<slug>.md, the pull request title feat: WP5.01 — …, and the commands take wp 5.01. Phase 4 keeps its flat numbers, WP54 onward, to its close. In the author's words: "prefix with the phase number and start from 01 for each phase". The packages S1 to S15 named WP57 and WP58 are WP5.01 and WP5.02 |
The lanes can no longer claim one package number, so package numbers need no renumbering (REV-126). The alpha tag's N is the package's number within its phase (S19) | §8.4.1, §8.4.4, §2.7's Versioning NOTE, CONTRIBUTING.md, CHANGELOG.md's head, CLAUDE.md, .claude/workflow/core.md and the routers of np-plan, np-implement and np-ship, in this pull request |
| S17 | A design study that merges before the current phase's release adds each clause it restates beside the clause, tagged for its own release, and the restatement replaces the clause only when that release ships | v0.5.0 ships the clauses that gate the Qt shell it contains, while WP5.01 can still merge early (REV-127) |
§8.4.4, the Phase 5 plan, in this pull request |
| S18 | The pull request that merges second renumbers every new item of every numbered register: REV-nn rows, the requirement identifiers of every prefix, history records with their §8.2 number and ruling letters, and code-review reports, each kind in order from one above the highest on main, with every reference to them |
Two lanes cannot leave one number on two items (REV-128) | §8.4.4, .claude/workflow/core.md, in this pull request |
| S19 | A work package's alpha tag is vX.Y.0-alpha.N, where N is its number within its phase: WP5.02 takes v0.6.0-alpha.2, whether or not WP5.01 took a tag. The CHANGELOG.md entry of a package that takes no tag goes under ## [Unreleased] at the top of the file, and the next tagged package of its phase moves it into its own section |
A skipped tag leaves a gap rather than shifting later numbers, and the changelog stays newest first (REV-129) | §8.4.1, §2.7's Versioning NOTE, CONTRIBUTING.md, CHANGELOG.md's head, in this pull request |
| S20 | /np-ship checks every numbered register for a duplicate after merging main, with .claude/scripts/duplicates.py, and the author merges a pull request of the second lane only after /np-ship has run on it against the current main. No test checks it (§8.2.13 N3) |
A duplicate is caught before it reaches main, without reinstating a repository self-check (REV-130) |
§8.4.4, .claude/skills/np-ship/wp.md, the new script, in this pull request |
| S21 | WP5.01 holds an interactive design round with the author, a brainstorm and then a grilling, on how the workbench is organised and how it looks and feels. Several organising principles are drawn and compared, not only one tab per pipeline stage; the grilling then settles each point of a fixed agenda, one question at a time. In the author's words: "how the GUI is to be organized (i.e., not just stage by stage) and should look and feel like" | S2's "distinct tabs for each part of the workflow" is an input to the round, not its answer. Each ruling of the round is recorded in the author's words in the design document's decision log; one that sets a requirement enters the specification with the document (F5), and one that departs from S2 amends §8.1's Phase 5 row in the same commit | The Phase 5 plan and its record, in this commit; the design document and, where a ruling moves it, §8.1, in WP5.01 |
| S22 | WP5.01 also builds the workflow for developing the GUI: a /np-gui skill whose levels render every screen headless, have it reviewed, publish it for the author's verdicts, collect them, and run a design round; a read-only gui-reviewer agent; and the hooks that make /np-implement look at each screen it changes and /np-ship review and publish the screens of a package that changes them. It works before the front end is chosen, and WP5.02 adds the browser shell's fixture states and the local live loop to it (S8 to S10). In the author's words: "an expanded workflow, skills, or agents to efficiently perform GUI development" |
Every later GUI package and tool phase reuses the same render, review and verdict loop, and WP5.01 is its first user. §8.4.5's two kept agents become three, and §8.4.4 lists a fourth command beside the three workflow commands. S1 holds: the tools live under .claude/ and change no src/, tests/, case schema or public API |
§8.4.4, §8.4.5, CLAUDE.md, .claude/skills/np-implement/wp.md and .claude/skills/np-ship/wp.md, in WP5.01's workflow item |
| S23 | WP5.01's plan may exceed §8.4.4's word caps. In the author's words: "Go can exceed word budget here". Its six-decision cap stands | The two rounds and the tools are planned in full in one package rather than split | None; the WP5.01 plan states it |
| S24 | The workbench's areas, as the author named them, are the molecular viewer and editor, the geometry builder, the mesh builder, the physics assigner and the results analyser, in the author's words "Molecular viewer/editor, geometry builder, mesh builder, physics assigner, results analyser, ...", the list left open. The design document is public on the documentation site. The colleague who observes QR-10 is "not so important right now" and is named by the close | WP5.01 draws one mockup per area, and one route threading QR-10's guided run through them, in place of three to five jobs; the design round decides how the areas are arranged (S21). Each area offers what the library verifies at v0.6, and its later parts (side-chain editing, the sketcher, model composition) carry a later-phase banner (S3 to S5, S7) | The Phase 5 plan's What the author supplies, in this commit; the design document, in WP5.01 |