wei-wuwei 0.0.0-stage → 0.2.0

package/skills/wuwei-execute-phase/skill.md

@@ -0,0 +1,624 @@
+---
+name: wuwei-execute-phase
+description: >-
+  Use to execute a planned phase or continue a stream — the user says
+  "continue the stream / 接手 / 繼續做", a stream has a signed acceptance
+  contract and an eligible phase (dependencies merged, unclaimed or
+  stale-claimed), or a merge just unlocked a dependent phase. Runs the fixed
+  pipeline: claim → implement → e2e → three or more rounds of
+  simplify/review/fix → PR — one phase, or a range on request.
+version: 0.2.0
+mode: triggered
+model: sonnet
+effort: xhigh
+targets: [claude-code, codex]
+tags: [execution, workflow]
+---
+
+# Execute phase
+
+## When to use
+
+- A signed stream has an eligible phase and this session should take it.
+- The caller gives a range instead of a phase (`## Run scope`). Nothing
+  parses the shorthand — this file defines it, so a mistyped token gets asked
+  about.
+- Resuming: `git pull`, read `STATE.md`, continue from recorded state. That
+  is the whole takeover mechanism.
+
+## When NOT to use
+
+- No signed contract → `wuwei-plan-phases` first. An unsigned plan means a
+  self-defined finish line.
+- Hotfix outside any stream → `wuwei-debug-root-cause` + `wuwei-tdd` +
+  `wuwei-commit-hygiene`.
+
+## Invariants
+
+Hold everywhere; the steps do not restate them.
+
+- **Evidence, not narration.** Nothing is done without its recorded green e2e.
+- **A fresh subagent implements, a fresh subagent reviews.** Inherited
+  context is not review. Inline only where no subagents exist (Codex) — a
+  fallback, not an equal option.
+- **Anything changing what was signed off stops and escalates.** `manual`
+  asks now, `auto` records in the phase file and pauses. No scope or `mode`
+  pre-approves it.
+- **Transition only what this session observed.** Work merged after handover
+  belongs to the next claim's reconcile, or to the merger.
+- **Graph first, Grep as fallback, always record which.** A reconstructed
+  edge never carries the confidence of a queried one.
+
+## Base sync
+
+Steps 1 and 5 both do this.
+
+- Merge the **stream branch named in `## Sign-off`**. Read it there, never
+  rebuild it from the phase branch name. Named nowhere → stop and say so;
+  planning owes it (its step 8).
+- Compare against the integration branch's **tip**, never the sha beside it.
+  Syncing to that succeeds, changes nothing, and reports nothing.
+- Sync the **stream branch**, never one phase branch. It is the shared base,
+  so one sync serves every later phase; per-phase syncing gives each its own
+  merge of main, and those collide.
+- Let codegraph settle afterwards — its watcher reconciles changed paths, so
+  a merge is an incremental sync.
+- **Record the ref synced to.** Every graph answer is only true as of it.
+
+Then take every diff with **three dots**. Two dots looks right — non-empty,
+plenty to say — and is about the wrong code:
+
+```
+git diff <base>...HEAD    # correct — this phase only
+git diff <base>..HEAD     # wrong — the merged base counts as yours
+```
+
+**The one two-dot diff in this pipeline is step 5's delta round**
+(`wuwei-review` §6): two shas on this same branch with no base movement
+between them, so there is no merged base there to fold in — and a sync that
+moved the base is exactly what voids the delta and sends that round back to
+full scope.
+
+## Run scope
+
+Steps 1–8 cover **one** phase. How many times you go round is settled once
+per invocation.
+
+- Default: `manual` → one phase. `auto` → the whole stream, **never
+  re-asked**, because sign-off authorised it.
+- Shorthand: `--through <NN>` inclusive, `--through end`, `--all`, or the
+  same in words.
+- Given a range, print it and go. Given none, ask.
+
+Print before claiming anything: the scope line over `wuwei claim
+<stream>`'s list, which already marks `review: human` and anything waiting or
+blocked — `run scope: 02 → 04 · 3 phases · mode: manual`, then where it
+will stop and which phase starts.
+
+Stopping early is normal — say where, why, and what resumes:
+
+```
+stopped at 03-appcheck-wiring · bound e2e red (auth/refresh.spec.ts)
+02 merged. 03 claimed, branch pushed, not merged.
+next invocation resumes at 03: /wuwei-execute-phase
+```
+
+Name the invocation: this skill's sonnet / xhigh holds for the turn it runs
+in, and a reply in chat continues on the session's model.
+
+**Scope is distance, never permission.** `mode` is the stream's standing
+authorisation from sign-off; scope is only how far one invocation tries to
+get.
+
+- `review: human` phases were circled at sign-off. The run **always stops**
+  at each, and **no token skips it** — carrying through takes words, naming
+  the reason it was circled (auth / payments / migrations / irreversible).
+- There is deliberately **no "skip the gates" token**: an endpoint already
+  implies not pausing, so a second one adds **no reach at all** — only a name
+  that reads as permission to override `mode`.
+- A red bound e2e, a SPEC-changing discovery, a dependency conflict, and
+  entering main stop regardless of scope.
+
+## Procedure
+
+1. **Claim.** Pull; pick a ready phase from `wuwei claim <stream>`, or decide
+   a stale claim is abandoned (`--take-over` records it in the phase file).
+
+   **Catch the stream branch up before cutting anything**: base sync, then
+   re-run the stream's already-green e2e on it. Red → `manual` stops and
+   reports, `auto` surfaces a stuck stream; **never cut a phase branch off a
+   stream branch whose evidence is red**. The sync moves the base under any
+   in-flight phase — they sync again at their step 5, so no coordination is
+   needed, but note it in the phase file.
+
+   Then `wuwei claim <stream> <NN>` claims it and cuts `wuwei/<stream>/NN-<name>`
+   **from the stream branch** — not main, which would put the whole base
+   delta in this phase's PR.
+
+   **Tracker-linked?** Read each phase's issue from its own `tracker-issue`
+   frontmatter, never `STATE.md` — `done/total` is an aggregate and cannot
+   say *which* phase merged. Compare this phase and every earlier one against
+   the state its phase file implies, then apply the single write rule:
+
+   > **Only move an issue whose current state is one of the three names
+   > recorded at sign-off.**
+
+   Those three are ordered (in-progress → in-review → done), so "behind" is
+   decidable inside the set, and catching an earlier phase up is a write wuwei
+   owed. **That is the only write that is yours — forward, to catch up.**
+   Never backwards: an issue a human moved to `done` is not reopened because
+   a phase file still reads in-review. Anything outside the set — `Blocked`, `Won't Do`, `In QA`, anything
+   nobody mapped — is a human acting on the board: report and leave it,
+   **including when it is the phase you are claiming**. Under `single`
+   granularity there is no per-phase issue — see step 7.
+
+2. **Implement** the task checklist, one fresh subagent per task (SDD,
+   borrowed from superpowers). **Dispatch with four things:** SPEC, the phase
+   context, **the ladder below**, and **step 4's floor** — and nothing else.
+   The ladder is a question the subagent writing the helper has to ask; an
+   orchestrator holding it while the subagent writes is the same as not having
+   it. Dispatch `wuwei-implementer` with **no `model` or `effort` on the
+   call** — its file pins sonnet / xhigh, and a value on the call beats it.
+   Inline instead → watch for
+   drift, keep the phase small, and note that the model policy has nothing to
+   attach to.
+
+   **A task waits for every task in its `depends-on`** (`wuwei-plan-phases`
+   sets them) — dispatched only once those have landed. Tasks with no
+   `depends-on` are independent and may go in parallel. **A missing field
+   means independent, so a mis-planned one runs too early and its subagent
+   writes against an interface that is not there yet**; that is a planning
+   defect, reported, not worked around here.
+
+   `wuwei-tdd` governs each task; tick as they land; one task ≈ one commit
+   (`wuwei-commit-hygiene`). Library choice and internal structure are yours
+   — don't ask.
+
+   **Each commit stands where it is written.** One-per-task is a floor, not a
+   cap: a task holding two real concerns commits twice, in dependency order;
+   what is never allowed is one commit holding two.
+
+   - **No forward dependency.** Building on what an earlier commit landed is
+     the `depends-on` sequence working — task 3 using task 2's type is
+     correct. Referencing a helper, field, export or migration that a **later**
+     commit adds is not: that commit is half a change with a message, and it
+     breaks `git bisect` at the exact commit someone reaches for. Needed and
+     not there yet → **its task lands first**, never "I'll wire it up after".
+   - **The design is readable from the commit alone.** Subject names the
+     concern; the body says **why this shape** — and where the choice was not
+     obvious, the rung it stopped at and what it climbed past. Someone holding
+     only `git show` should not need the phase file to see the intent.
+   - The one commit allowed to be red is a `wuwei-tdd` test committed ahead of
+     its implementation, and only with that implementation as the **very next**
+     commit. Anything committed in between leaves a red commit that reads as a
+     broken tree.
+
+   **Climb before writing**, stopping at the first rung that holds. Skipping a
+   rung is not a different kind of mistake from step 4's — it is the same
+   finding, arriving later, so the rungs and step 4's tags are one vocabulary:
+
+   | | Ask | Skipped → step 4 reports |
+   |---|---|---|
+   | 1 | does this need to exist at all? | `yagni:` / `delete:` |
+   | 2 | **is it already in this codebase?** — a helper, type or pattern a few files over | `reuse:` |
+   | 3 | does the stdlib do it? | `stdlib:` |
+   | 4 | does a native platform feature cover it? | `native:` |
+   | 5 | does an **already-installed** dependency? Never add a new one for what a few lines do | `reuse:` |
+   | 6 | can it be one line? | `shrink:` |
+   | 7 | only then: the minimum code that works | — |
+
+   Rung 2 is the one that has to be caught here rather than later: `stdlib:`
+   and `native:` are visible to anyone reading the diff, while a helper three
+   files over is invisible unless you already looked. `review:defects` looks
+   too — **both sides gate** — and **a `reuse:` finding from either is a rung
+   that was skipped**, so it counts in the round's convergence like any other.
+
+   **The ladder shortens the solution, never the reading.** Trace every file
+   the change touches and the flow it really takes first, then climb — the
+   smallest change in the wrong place is not lazy, it is a second bug.
+
+   **A fix goes at the proven cause, and when the cause is in a shared
+   function, one guard there beats one per caller** — smaller diff, and the
+   siblings stop being broken too. Find the call sites the way `## Invariants`
+   says: graph first, Grep as fallback, record which. This holds wherever a fix
+   is written — here, step 6, and `wuwei-debug-root-cause` — and it never
+   licenses guarding the shared function *before* the cause is proven, which is
+   the guess that hides the real one.
+
+3. **e2e.** Run the phase's bound items. Red → `wuwei-debug-root-cause`.
+   Never proceed past a red bound item. Then `wuwei verify --phase NN`: a
+   page bound here and missing from `.wuwei/verify.json` is added first,
+   fixtures from the API's schema; each flag is fixed or answered.
+
+4. **Simplify.** **Steps 4–6 are one round, and a phase runs at least three.**
+   A round cuts, gets reviewed, fixes what came back, verifies, and closes as
+   a single commit — so the phase reads as rounds of work rather than a pile
+   of fixes.
+
+   Reread the whole diff and cut. One line per cut, tagged:
+
+   | Tag | What it marks |
+   |---|---|
+   | `delete:` | dead code, unused flexibility, speculative feature — nothing replaces it |
+   | `reuse:` | something this project already has — a helper, type or pattern in the repo, or an already-installed dependency. Name the file or the package |
+   | `stdlib:` | hand-rolled thing the standard library already ships. Name the function |
+   | `native:` | a dependency or code doing what the platform already does. Name the feature |
+   | `yagni:` | an abstraction with one implementation, config nobody sets, a layer with one caller |
+   | `shrink:` | same logic, fewer lines. Show the shorter form |
+
+   Format: `<file>:L<line>: <tag> <what>. <replacement>.` End with the only
+   number that matters — `net: -<N> lines` — or `nothing to cut` and stop.
+   Both go in the phase file.
+
+   **The cut report is one line per cut — no paragraph justifying it.** Every
+   paragraph defending a simplification is complexity smuggled back in as
+   prose.
+
+   This governs the cut report and nothing else. Prose that is **required**
+   stays in full: `wuwei:` markers (they explain code that is deliberately not
+   there, so they are always longer than it), commit bodies (`why`, not what),
+   comments stating an invariant, `## Notes`, digests, walkthroughs, phase
+   notes.
+
+   ```
+   ❌ this validator class might be more complex than it needs to be, and
+      it's worth considering whether all these rules are needed yet
+   ✅ auth/email.ts:L12-38: stdlib: 27-line validator class. "@" in the
+      address, 1 line; real validation is the confirmation mail.
+   ✅ api/repo.py:L88: yagni: AbstractRepository, one implementation. Inline
+      it until a second exists.
+   ✅ jobs/sync.go:L52-71: delete: retry wrapper around an idempotent local
+      call. Nothing replaces it.
+   ```
+
+   `<replacement>` is required, and for `delete:` "nothing" is the answer. The
+   ❌ is not too polite, it is **unactionable**: no location, no cut, no
+   replacement, and a question where a finding belongs.
+
+   **Never cut a test to make a number better.** A single smoke test or an
+   `assert`-based self-check is the floor, not bloat — cutting coverage cuts
+   the phase's only evidence. **Tests are outside this step's reach entirely**;
+   `review:defects` owns whether they are the right ones.
+
+   **Never simplify away** input validation at a trust boundary, error handling
+   that prevents data loss, a security measure, **anything this project's own
+   linters or checks would flag if it were absent** (a11y rules among them,
+   when the project has them configured), or anything the contract explicitly
+   asked for. A `yagni:` on "config nobody sets" is exactly how one of these
+   leaves.
+
+   The linter clause is deliberate: wuwei does not carry its own opinion on
+   what a project must check for — `review:code` already runs whatever the
+   project configured. A category with no configured check and no name in
+   `## Sign-off`'s threats is not this step's floor to enforce alone.
+
+   **Two ways the same size → the one that is correct on edge cases.** Fewer
+   lines, never a flimsier algorithm.
+
+   Skipping is allowed only for trivial diffs, and **the skip is recorded the
+   same way** — a step whose output is "simplified" is indistinguishable from
+   one that was skipped.
+
+   **A cut you decide not to make gets a marker where it would have gone**,
+   not a line in a document nobody will open:
+
+   ```
+   # wuwei: <the ceiling this accepts>, <what should trigger revisiting it>
+   ```
+
+   ```python
+   # wuwei: no retry here — the caller retries the whole batch.
+   #        add one the first time this is called outside that path.
+   ```
+
+   Two fields, both required. **A marker with no trigger is the one that
+   rots**, and step 8 does not pass with one.
+
+   **Commit the cuts here, before step 5** — step 5's diff is three-dot, so
+   cuts left in the working tree are reviewed by nobody while every lens reads
+   code that no longer exists. **The bound e2e does not run here**; it runs at
+   the round's close, covering this round's cuts and fixes together.
+
+5. **Review panel** — run the panel(s) `wuwei-review` §1 classifies this
+   phase's diff into: the code panel always, **and the document panel over any
+   prose the phase changed** — a phase that ships an endpoint and its docs has
+   both, and §1 calls that normal rather than an edge case. `wuwei-review` owns
+   the lenses,
+   the tool precedence, the three-dot diff, and the collation rules; this
+   step supplies the phase context and decides what happens to the result.
+
+   **Base sync first.** Every graph question the panel asks is about the tree
+   that exists *after* this merges — unsynced, "every call site updated" can
+   be true here and false the moment it lands.
+
+   **Then `wuwei review-prep <base>`** (`wuwei-review` §1) — the dispatcher
+   checks and the scan bundle; name the bundle's path in the dispatch — one
+   crawl for the whole panel, rebuilt whenever the reviewed sha moves.
+
+   Then dispatch with five things: the phase file, the path to
+   `ACCEPTANCE.md`, the **base ref just synced to**, the **tool facts**
+   (`wuwei-review` §1, §5), and **the scope** (`wuwei-review` §6) — plus, for the
+   document panel, **the intended reader and the facts this phase
+   establishes** (`wuwei-review` §3). Models: as `wuwei claim` printed them
+   (`wuwei-review` §2).
+
+   **Round 1 is full scope; every round after it is delta** — dispatched with
+   the sha the previous round's panel was reviewed at, that round's still-open
+   and `contested` findings, **its `unread:` scopes**, and the phase's full
+   range as something a lens may widen to. The unread scopes have to be passed
+   explicitly and **read before the delta**: they are unchanged code by
+   definition, so nothing else in a delta round would bring them back. Rounds 2 and 3 otherwise pay four lenses to re-read code four
+   lenses already read.
+
+   **Full scope comes back whenever the delta cannot be trusted**, and
+   `wuwei-review` §6 lists when: the sync above actually moved the base, or the
+   recorded sha no longer resolves. Both are one command to check and neither
+   is a judgement call — **not checking is how a delta silently reviews the
+   wrong range.**
+
+   **The dispatch asks for the same thing every round** — the delta and the
+   carried findings. A standing order for fresh probes voids the convergence
+   count; widening is chosen once and recorded in the digest header
+   (`wuwei-review` §6).
+
+   **A panel whose delta holds nothing for it is skipped, and the skip is
+   recorded** — in the digest header, which already asks for any lens that did
+   not run and why; same as step 4, an unrecorded skip is indistinguishable
+   from a step that was forgotten. Concretely: on a delta round the document
+   panel does not dispatch when the delta contains no prose, **and** the
+   previous digest carries no open document findings, **and it declared no
+   `unread:` scope** — a blind spot the panel located itself is the last thing
+   a skip may swallow. A lens shown nothing can
+   find nothing, so nothing is given up — except one seam, named with the
+   skip: a code-only fix can falsify prose it never touched, and until the
+   stream audit only `review:defects`' prose-inside-code rule watches it.
+   Round 1 is untouched by this — it runs full scope, where §1's
+   classification already decides which panels exist at all. Inside a phase the panel has two obligations it does not
+   have standalone:
+
+   - **Diff the architecture delta against the phase's `## Intended
+     design`** and state the verdict — built as designed, or diverged with
+     the reason. Divergence is allowed but never silent; divergence that
+     changes what was *signed off* rather than how it was built is an
+     escalation, not a footnote.
+   - **Reconcile `ACCEPTANCE.md`'s `## Threats`** — no evidence means still
+     open.
+
+   Two dimensions the panel weighs **every round**, because they are what the
+   rounds exist for:
+
+   - **logical necessity** — does this need to exist at all? Not "is it
+     correct" but "is it load-bearing". A correct thing nobody needs is next
+     round's `yagni:`, not a finding to close.
+   - **human readability** — can a person read this without reconstructing
+     it? Naming that lies, a function that needs its own diagram to follow,
+     an abstraction whose only reader is its author.
+
+   Append the digest to the phase file — it is what a human reads instead of
+   the raw diff. Each round appends its own; the sequence is the convergence
+   record step 6 reads.
+
+6. **Close the round.** Fix what step 5 found — **verify it first, then fix
+   at the cause, not where it was reported.** Every finding carries its own
+   recipe (`Fails when`): run it before touching anything — or, for a finding
+   with nothing to run (a `reuse:`, a naming claim), check the claimed fact
+   against the tree. It fails as described → real, go find the cause. It does
+   not → the finding closes as `false-positive`, recorded in the round record
+   with **what was run, what was observed, and the premise the closure
+   assumed** — evidence, not argument, since
+   prose against prose is how appeasement comes back — and it counts as a
+   closure in the convergence table below. The next round's panel reads the
+   round record and can re-raise; that is the check on closing too eagerly.
+
+   A real finding is then fixed at the cause: a lens read the diff, so its
+   coordinate is where the defect became visible; the cause can sit in a file
+   it never opened. Locate it first, and where it is not already proven that
+   is `wuwei-debug-root-cause` — the skill is not only for red tests, and a
+   finding whose cause is a guess is the same situation.
+
+   **The finding disappearing is not the test; the cause being gone is.** One
+   closed by widening a type, wrapping the call in a `try`, deleting the
+   assertion that caught it, or a local linter-disable is hidden, not fixed —
+   and the next round's panel reads the suppression as intended code.
+
+   **When the proven cause is this phase's own earlier work — a task commit,
+   or an earlier round — the fix goes into that code**, in this round's fix
+   commit (never amended into a task commit; see below). Nothing has merged yet, so
+   this is the cheapest it will ever be, while a compensating layer on top is a
+   second floor on a foundation the panel just called wrong — usually more
+   lines than the change it avoids. Layer on top only when the cause sits
+   outside this phase, and say so in the digest. A cause inside what was signed
+   off is an escalation (`## Invariants`), not a local workaround.
+
+   Then **run the bound e2e** — red → `wuwei-debug-root-cause` — and **commit
+   the fixes, one per concern.** Step 2's rules govern these exactly as they
+   govern task commits: one concern each, no forward dependency, and a body
+   saying why this shape. Step 4's cuts are already their own commit.
+   **Nothing is squashed at the round, and nothing is amended into a task
+   commit** — a phase reads as the sequence that produced it, which is worth
+   reading only because every commit in it is atomic.
+
+   **Close the round with its record, appended to the phase file** next to
+   step 5's digest:
+
+   ```
+   round <n> · scope: <full | delta from <sha>> · reviewed at <sha>
+
+   - cut: <what step 4 removed>. net: -<N> lines
+   - found: <N> findings — <N> HIGH / <N> MED / <N> LOW
+   - fixed: <one line per concern — the cause, where it differs from where
+     the finding was reported> · premise: <what the closure assumed>
+   - e2e: <bound items> green @ <sha>
+   - verify: <pages> @ <sha> · <N> flags, each fixed or answered
+   ```
+
+   **The record goes in the phase file, not only in a commit body.** The phase
+   file merges whichever way the phase does — and where sign-off chose squash,
+   step 7 makes any round commit body unreadable the moment the phase lands.
+
+   **Findings must converge.** From round 2 on, compare `HIGH + MED` against
+   the previous round's digest: strictly fewer, or the round did not converge.
+   A new LOW is not non-convergence — a fresh lens turning up something small
+   is what it is for.
+
+   **Under delta scope the count is carried + new**, never only what this
+   round's dispatch happened to be shown. A carried HIGH leaves the count when
+   **its fix, its recorded falsification, or its supersession was observed**
+   (`wuwei-review` §6), not when a
+   round that was never shown it stayed quiet — otherwise the number falls because the scope shrank, and every rule
+   in this table starts measuring the dispatch instead of the code.
+
+   | after round | state | do |
+   |---|---|---|
+   | 1 | **every lens that ran found nothing, any severity** | **exit the loop** — nothing to converge means the diff was trivial, and the panel said so itself rather than being told |
+   | 1 or 2 | otherwise | next round |
+   | ≥ 3 | no HIGH, no MED | **exit the loop** |
+   | ≥ 3 | converging, HIGH or MED still open | next round |
+   | ≥ 2 | **`HIGH + MED` did not fall** | **stop and escalate**, recorded in the phase file |
+
+   The round-1 exit is the only way out before three — **every lens that ran**,
+   zero findings, not a size guess about the diff, and a mixed phase runs two
+   panels so it needs both clean. A phase author cannot declare its own diff
+   trivial; the panel can, because it is the one thing here that is not
+   grading its own work.
+
+   **Non-convergence is information, never something to fix by finding less.**
+   A phase that cannot converge is mis-scoped, and grinding another round is
+   how a panel learns to report less.
+
+   **A contested finding is not a failure to converge.** Two lenses reaching
+   different severities on the same subject — `review:claims` calling a
+   documented pattern HIGH where `audit:security` finds no reachable sink — is
+   a disagreement, and rounds cannot settle it: neither lens is wrong within
+   its own mandate, so grinding produces the same two rows every time. Mark it
+   `contested`, **leave it out of the `HIGH + MED` convergence count**, and
+   **escalate it by name** — it is a human's call, and recording it as
+   "mis-scoped phase" hides which question is actually open.
+
+   A finding is `contested` only when **reporters rated the same subject
+   differently** — one row whose Sev cell records each (`wuwei-review` §7). One
+   lens with a finding nobody disputed is not contested; it is open.
+
+   On exit from the loop:
+
+   - **Run the repo's own suite once** — every e2e run so far measured only
+     this phase's bound items, so nothing has yet asked whether it broke a
+     test that was already there. Use the command the repo already uses
+     (`package.json` scripts, `Makefile`, the CI workflow); red →
+     `wuwei-debug-root-cause`. **No discoverable command → record "suite not
+     run" in the phase file.**
+   - **Phase evidence** in the phase file, as the phase's last commit, naming
+     the number of rounds and the convergence sequence. Push.
+
+   **`STATE.md` is not touched from a phase branch** — one global file, one
+   row per stream, and `phases done/total` is a single cell two parallel
+   phases would conflict on. The aggregate is **derived on the stream branch
+   by whoever merges the phase PR**, in its own commit.
+
+7. **PR** against the stream branch from `## Sign-off`, **ready, not draft**
+   (draft means "still changing" — use it only when opening early to run CI).
+   **Say which delivery strategy this phase sits under**, so a reviewer does
+   not judge an `mvp-first` intermediate phase as if it were finished.
+
+   **Phase PRs merge into the stream branch unsquashed by default — a merge
+   commit — and the stream PR merges into main unsquashed too.** The phase is
+   still the rollback unit: `git revert -m 1 <merge-sha>` takes one back in a
+   single command, and the commits that produced it stay readable underneath.
+   **Squashing is the human's call at sign-off, never this step's** — it
+   trades every atomic commit for one, which is what a repo demanding linear
+   history buys with.
+
+   **Take the merge method from `## Sign-off`, never from what the button
+   offers** — sign-off recorded which method this stream uses and what the
+   repo allows. Using a fallback is fine; using it silently is not, so name it
+   in the PR.
+
+   **Squash chosen → the squash commit body lists the commit subjects, in
+   order**, because those commits go unreachable and `wuwei-tdd` settles "did
+   the test exist before the implementation" from history order. Merged
+   unsquashed, the history answers that itself and no listing is owed.
+
+   - `review: auto` + evidence green, in auto mode → merge into the stream
+     branch, by the method in `## Sign-off`.
+   - `review: human` → hand the digest over and wait. **The wait ends on the
+     last review's body, not on `reviewDecision`** — an approve can carry a
+     condition ("docs first, then merge"), and reviews live at
+     `/pulls/:n/reviews` and `/pulls/:n/comments`, not with the issue
+     comments; every review's findings enter the round record like the
+     panel's own. **A commit after the approve gets `wuwei-review` §6's
+     post-approve scope before the merge — dispatched to a fresh
+     `review:defects`**, never run by this session, which wrote the code.
+   - Whole stream done → **base sync once more, re-run the full e2e**, then
+     **hand over to `wuwei-review`'s stream panel**, then open the stream PR
+     to main.
+
+   **Say the audit is available, every time, including in auto mode.** It is
+   the only gate positioned to ask whether the delivery matches the contract
+   that authorised it (`wuwei-review` §4, `references/stream.md`, says what each of its lenses sees
+   that no phase review can). **A gate nobody knows about is not a gate.**
+
+   ```
+   stream pwa-redesign · 5/5 phases merged · e2e green
+
+   before the PR to main, run the stream audit:
+       /wuwei-review --stream   # contract · coverage · composed security · composition
+   ```
+
+   The stream PR is ready, carries the accumulated digests, the audit, and the
+   UAT checklist, **names the ref synced to** (the UAT is evidence about that
+   tree and no other), and states whether the composed result still matches
+   `## Target architecture`.
+
+   **Tracker**, subject to step 1's write rule:
+
+   | granularity | on PR open | on merge |
+   |---|---|---|
+   | `per-phase` | phase issue → review state | → done state |
+   | `single` | tick that phase's box in the stream issue | **never transition the issue** — closing the stream's only ticket because phase 01 of 5 landed is the destructive version of this feature |
+
+   A `review: human` phase, and the stream PR into main, merge after this
+   session hands over — **say at sign-off who owns those final moves**, or the
+   board stops one step short with nobody owning it.
+
+8. **Verify.** **At least three rounds, or exactly one if it exited on the
+   all-zero rule**, each closed by a green bound e2e, and the convergence
+   sequence recorded — a round with no digest is a round that did not happen;
+   **every `contested` finding named and escalated**, never counted as
+   non-convergence; **the repo's suite run once after the last code change, or
+   "suite not run" recorded with the reason**;
+   **every round's digest records the scope it ran at and the sha it reviewed,
+   round 1 ran full, and any panel skipped on an empty delta is recorded with
+   its reason**; **every `unread:` scope a digest declared was read by a later
+   round or carried into the phase evidence as still unread**; `STATE.md`'s row for this stream matches the phase
+   files, updated on the stream branch; **every `wuwei:` marker this phase
+   added names both a ceiling and a trigger**; **no commit in this phase
+   depends on one that lands after it**; every round's fixes name a
+   located cause rather than a suppression; every tracker transition
+   attempted recorded with its outcome, failures in the digest — done against
+   a board that never moved must not pass; no red branch left behind
+   silently.
+
+## Notes
+
+- Idea credit: superpowers subagent-driven development + the owner's
+  pipeline. Step 4's tag vocabulary and net-lines metric: ponytail's
+  `ponytail-review`; step 2's ladder and step 4's floor: ponytail's `ponytail`.
+  Rewritten for wuwei.
+- The `review: human` asymmetry is the design: the safe thing costs two
+  tokens, the risky thing costs a sentence.
+- SDD's value is freshness — each task starts clean instead of inheriting the
+  debris of every task before it, which is what makes late tasks in a long
+  phase drift.
+- A `wuwei:` marker is the only decision a project keeps that outlives its
+  stream: SPEC and phase digests close when the stream does, the reason a
+  function has no retry does not.
+- **One command rolls a phase back, and which command is the merge method's
+  doing**: `revert -m 1` for a merge commit (the default), plain `revert` for
+  a squash, and rebase gives neither. None of them makes a phase
+  *independent* — that is cut at planning time (`wuwei-plan-phases` step 4),
+  and recorded in `## Sign-off` because the person reverting is holding an
+  incident, not reading the plan.
+- Tracker writes are outward-facing and can fail. A failure never blocks the
+  phase, but it goes in the digest and step 8 gates on it.
+- Entering main is always a human decision; phase → stream-branch merges ride
+  the sign-off authorisation.