8.2.16 Phase 4 amended: the specification and the workflow restructured, agreed 22 October 2026
8.2.16 Phase 4 amended: the specification and the workflow restructured, agreed 22 October 2026¶
Rulings by the author, taken through /phase-plan amend 4 after WP51 merged and before the protocol
started. The author asked for two packages before the protocol. The first would streamline the skills
and the use of agents, and redistribute the specification, which "takes a lot of context when read in
full". The second would revise the notebooks and figures further, from a document of comments the
author supplies when that package is planned. Measured at 1ca60b8: SPECIFICATION.md held 78,404
words in 4,153 lines, of which the §8.2 rulings took 14,550 in 119 rows, and the repository named the
file 364 times. The Phase 4 plan held 15,397 words. The skills a session loaded came from the primary
checkout, which was 186 commits behind origin/main. The letter series continues at R.
| # | Decision | Consequence | Clause changed, and when |
|---|---|---|---|
| R1 | Three packages are inserted before the protocol: WP52, the documents (R2 to R4); WP53, the workflow (R5 to R7); WP54, the notebooks and figures revised (R8). The protocol becomes WP55 and the fix packages are numbered from WP56. Tags v0.5.0-alpha.18 to .21 |
The author asked for two packages. The first was split because one pull request cannot verify both a move of 78,000 words and five rewritten skills, and the skills are written against the layout WP52 leaves. WP53 to WP55 are planned on that layout. For numbering, R1 supersedes P1 | §8.1's Phase 4 deliverable, P1 (a pointer), the Phase 4 plan and the protocol's plan, renamed wp55-user-testing-protocol.md, in this commit |
| R2 | The specification becomes its own OKF bundle, specification/, beside knowledge/. It has an index.md per directory and one file per numbered section, with §5 and §7 split by subsection. In the author's words, "the current spec is read in by default, and any history as an optional read". The dated §8.2.x tables and the superseded or withdrawn rows and NOTEs move to specification/history/, which is read on demand. A withdrawn or superseded identifier keeps a one-line entry in the current text that points there. SPECIFICATION.md stays as the entry point: what is normative, how to read it, and the map from section and identifier to file |
Every reference to SPECIFICATION.md §x stays true, so src/ and tests/ are untouched and WP52 is prose-only for the gate. Markdown links with anchors are rewritten. The normative specification and the informative knowledge base stay separate roots |
§11, CLAUDE.md, .claude/scripts/clause.py, docs/scripts/generate.py and mkdocs.yml, in WP52 |
| R3 | A ruling with no clause to amend is written once as a current-state rule, in a new section on the development process: the loop, the test scope, plan size and grounding, the workflow and versioning. Each rule points to the ruling it came from. The dated tables move unchanged to the history, as the record. From WP52 on, every ruling also lands in a current clause | A session reads the rules in force without reading the dated tables, and the history keeps the reasons. The section restates rulings in force and adds none; review reads it against the tables | The new section, in WP52; the phase level of the planning skill, in WP53 |
| R4 | A plan states its current scope, and its amendments become a record read on demand. Each package entry of a phase plan says what holds now. The text of each Amended blockquote moves to an amendment record, at the end of the plan or in a sibling file. WP52 restructures the Phase 4 plan, at 15,397 words against a 1,500-word target |
Planning a package reads the current scope only. The record is kept | The Phase 4 plan, in WP52; the planning skill's amendment rule, in WP53 |
| R5 | Its command names are amended by R12. The skills become three verbs with levels: /plan <project \| phase n \| amend n \| wp n>, /implement [wp n] and /ship [wp n \| phase n]. In the author's words, "one extensible /plan command, which would accept arguments for different levels". Each SKILL.md is a short router that reads a shared core file and the file for the level asked. project re-plans §8.1 and the later phases; /ship phase runs the close and prints the release tag's commands. steward stays |
An invocation loads only the rules for its level. Implementing and shipping remain separate sessions, so the review starts fresh (L7 stands). Whether the old names stay as aliases is WP53's decision | CLAUDE.md Implementation workflow and Commands, the skills and the session-start hook, in WP53 |
| R6 | The fresh worker is adopted for batches of independent, mechanical items, such as a sweep over many files, a rename or a per-module pass. Each item goes to a new Haiku or Sonnet sub-agent with the item and the clauses it cites. The main session keeps the plan and the git log, and re-runs the item's check before the next. Items coupled by design stay in the main session, with compaction checkpoints. A plan marks which items go to workers. The agent files remain the physics reviewer and the CI-log classifier | This settles L9's trial, in which WP45 ran 33 workers with one redo and no escalation. Workers read more in total, so they are used only where the items are independent | L9 (a pointer), in this commit; the implementing and planning skills, in WP53 |
| R7 | The session-start hook fast-forwards the primary checkout with git pull --ff-only when that checkout is on main and clean. Otherwise it warns that the skills may be stale |
A session runs the skills of origin/main. The hook writes to the author's checkout only by a fast-forward of a clean main |
.claude/hooks/session-start.sh, in WP53 |
| R8 | WP54 revises the notebooks and figures from the author's notes, with an open scope. Its plan reads the author's document and decides, as its own decisions, whatever the notes ask, including a new dependency or a change below plot/ |
The review of WP51 continues where P5, P8, P9 and P10 left it. A dependency entering the lock and a public name that moves are recorded in that plan, and a change to PUBLIC is decided in test_public_api.py (F4) |
Any clause WP54 moves, in WP54 |
| R9 | knowledge/ is not redistributed in Phase 4. WP52 touches it only to repoint links into the specification, including those of the orientation's concept on author rulings |
The scope stays with the specification and the plans. A pass over knowledge/ can be a later package |
None |
| R10 | WP52 is checked by two conditions, in its pull request and at review, with no kept test (N1, N3). First, every line of the old SPECIFICATION.md appears in specification/, in the current text or the history, apart from a listed set of ruling rows that R3's section restates. Second, clause.py resolves every identifier of Appendix A and every §8.2 ruling identifier, before and after, to the same definition text. A one-off script makes the first check and its output goes into the Outcome. The strict documentation build passes (VER-45). On a miss, the text is fixed before the merge, with no waiver |
A move of 78,000 words can neither lose nor silently change a clause. R3's section is the only new prose, and review reads it against the tables | None |
| R11 | A plan may be written for a smaller model, and names each work item's executor. Added 22 October 2026, at WP52's plan. In the author's words: "the ability to write the plan for a smaller model (and add up to 1000 more words on implementation details) and indicate which items can be executed by a sub-agent (and which type)". A plan may add an ### Implementation details section of at most 1,000 words. It holds the exact steps, layouts and commands a smaller model needs for the items it covers. Each work item names its executor: the main session, or a sub-agent by type and model, for example general-purpose on Haiku. The plan names the implementing session's model and effort. R6 decides which items may go to a sub-agent, and the main session re-runs each item's check. A compaction checkpoint is a work item. In the author's words, "the turn outputs a compaction prompt and then ends": the session ticks the item, gates and pushes, prints a /compact prompt that names the next item, and ends its turn |
A plan's caps become 3,500 words outside its Outcome annotations. At most 1,500 of them lie outside ### Grounding and ### Implementation details. A worker reads its item, the details for it and the clauses it cites, and nothing else. The author compacts the session and resumes it, with nothing unpushed. The planning and implementing skills' part of R6 lands with this ruling, not in WP53 |
Q1 (a pointer), CLAUDE.md Models, and the wp-plan and wp-implement skills, in WP52's plan commit |
| R12 | The commands are /np-plan, /np-implement and /np-ship. Added 22 October 2026, at WP53's plan. WP53's plan found that /plan is a built-in Claude Code command, which enters plan mode, and that a project skill replaces a built-in command only in a local terminal session. The author chose one project prefix on all three verbs. R5's levels, arguments and routing stand |
/np-plan runs the skill in the desktop app and on the web as in a terminal, and a later built-in /ship or /implement cannot shadow a command. Plans written before WP53 keep the old names as records |
R5 (a pointer), in WP53's plan commit; .claude/skills/, CLAUDE.md and §8.4.4, in WP53 |