wei-wuwei 0.0.0-stage → 0.2.0

package/skills/wuwei-grill/skill.md

@@ -0,0 +1,67 @@
+---
+name: wuwei-grill
+description: >-
+  Use when the user proposes a new feature or rough idea — "build X",
+  "我想要..." — before any spec or code exists, or when the doubt gate returns
+  Open Questions that need a human decision. Adversarially interrogates the
+  requirement and its assumptions. Cold phase: no solutions are designed here.
+version: 0.1.0
+mode: triggered
+targets: [claude-code, codex]
+tags: [requirements, workflow]
+---
+
+# Grill
+
+## When to use
+
+- A new requirement arrives and no signed SPEC covers it.
+- The user's ask contains an unexamined assumption ("just add caching", "we
+  need a dashboard") — the *why* is missing or inherited.
+- `wuwei-pre-implementation-doubt` returned Open Questions; grill them with the user
+  (HIGH first).
+
+## When NOT to use
+
+- The requirement is grilled and the question is *how* to build — that is
+  `wuwei-brainstorm`. Do not design solutions inside grill.
+- The SPEC for this stream is already signed off — changes go through a new
+  grill round, not silent edits.
+- Trivial, self-evident fixes (typo, broken link). Grilling those is theater.
+
+## Procedure
+
+1. Ground in wuwei's own state first: `.wuwei/streams/`, `.wuwei/STATE.md`,
+   and `.wuwei/codebase/MAP.md` are the only live sources of truth. If
+   `.planning/` (GSD) exists but was never imported, it is not project
+   state — it is a one-shot import candidate wired through `ww init`,
+   nothing more. No wuwei stream yet means exactly that: nothing planned in
+   wuwei so far, never a cue to go read GSD's un-imported docs and treat
+   them as established context or ask the user questions sourced from them.
+   If the user wants that content brought in, point at `ww init`'s import
+   flow — don't substitute for it here.
+2. Restate the ask in one sentence and get confirmation you understood it.
+3. Enumerate the hidden assumptions: who is the user, what problem does this
+   solve, why now, what does success look like, what is the smallest version,
+   what is explicitly NOT included.
+4. Attack each assumption: what evidence supports it? what breaks if it is
+   false? what is the cheapest way to disprove it? Read the codebase where it
+   makes claims about existing behavior — verify, don't trust.
+5. Ask the user in batches (3–4 questions, highest-leverage first). When they
+   answer "both" or "all of it", state the cost of that answer and make them
+   pay it knowingly.
+6. Converge: write the sharpened requirement into
+   `.wuwei/streams/<stream>/SPEC.md` — goals, **non-goals** (must be
+   non-empty), constraints, and an Open Questions list for anything still
+   undecided. This exact path, not a convention borrowed from any other tool.
+7. Verify: every assumption from step 3 now has evidence, a user decision, or
+   an Open Questions entry. If any HIGH question remains open, say so and stop
+   — do not hand off to `wuwei-brainstorm` on top of an unresolved HIGH.
+
+## Notes
+
+- Idea credit: grill-me. Rewritten for wuwei.
+- Grill is cold, brainstorm is hot — keeping them separate is deliberate.
+  Interrogation that starts designing stops killing bad premises.
+- In auto mode this runs once at stream start (the head touchpoint feeds on
+  its output); it is never skipped by autonomy.

package/skills/wuwei-legible-output/skill.md

@@ -0,0 +1,27 @@
+---
+name: wuwei-legible-output
+description: >-
+  Always-on output discipline (wuwei 律): diagrams and tables over prose walls,
+  diagrams generated from truth sources, review comments token-frugal, reports
+  led by what happened, decisions offered two at a time, replies in the
+  caller's language, paths and error text verbatim. Applies to every response,
+  report, digest, and document.
+version: 0.1.0
+mode: always
+targets: [claude-code, codex]
+tags: [output, rules]
+---
+
+# Legible output
+
+- Structure in three sentences → draw it: mermaid or a table beats a prose wall.
+- Diagrams come from truth sources (codegraph edges, `depends-on`), never
+  impression; a not-yet-built design is labelled intended.
+- Review comments: one finding, `file:line`, ≤ 2 sentences, no restating the diff.
+- Lead with what you did, whether it worked, what to do next. Details after.
+- Cut preamble, restatement and hedging; when the answer is known, lead with it.
+- Decisions: two options max, the context to choose fast, and your pick.
+- Reply in the caller's language; paths, commands, symbols and error text are
+  verbatim — never translated, tidied or shortened.
+- Plain words over jargon, but never a false simplification — name the hard part.
+- Acceptance bar: skimmable in under a minute, and says what changed and why.

package/skills/wuwei-map-codebase/skill.md

@@ -0,0 +1,171 @@
+---
+name: wuwei-map-codebase
+description: >-
+  Use when starting work in an existing or unfamiliar codebase — before
+  planning changes to legacy code, when the user asks "how does this project
+  work / 分析這個專案", or when a stream touches modules not yet mapped.
+  Produces an evidence-based architecture map: diagrams from the code graph,
+  never from impression.
+version: 0.1.0
+mode: triggered
+targets: [claude-code, codex]
+tags: [analysis, legacy]
+---
+
+# Map codebase
+
+## When to use
+
+- A stream is about to modify code you have not mapped.
+- Onboarding into a legacy project; the user asks for an architecture
+  overview or "先看懂再動".
+- Before `wuwei-plan-phases` on brownfield work — phases sliced against an
+  imagined architecture are sliced wrong.
+
+## When NOT to use
+
+- Greenfield projects — there is nothing to map yet.
+- A question about one file or one function: just read it.
+- A map already exists (`.wuwei/codebase/MAP.md` or the current stream's
+  `MAP.md`) and the code has not moved since — refresh only what is stale.
+
+## Procedure
+
+1. Fix the scope before scanning anything — scope follows the output
+   location (step 7), never the conversation. A baseline map (no stream
+   open) covers the **entire repo**: every app/package in a monorepo, not
+   only the one the current conversation happens to be about. A stream's
+   map covers only what that stream touches — **except a SPEC goal that
+   quantifies over the repo** ("every entry point", "no other path"): that
+   set is enumerated repo-wide by search, not through the feature being
+   changed. Getting this backwards silently
+   produces a "baseline" that is really just whatever was being discussed —
+   wrong the moment the repo has more than one app.
+2. Prefer the code graph for **internal** structure, detected as
+   `wuwei-review` §5 does: `codegraph status --json` — use it when
+   `initialized` is true, `worktreeMismatch` is null and nothing is pending;
+   offer `codegraph init` when it is missing. Then `codegraph explore`,
+   `query`, `callers` and `node` — the CLI, which every tool with a shell can
+   run; the MCP server exposes only `codegraph_explore` by default — for the
+   questions below, scoped per step 1. Without it, fall back to Glob (entrypoints, manifests, directory
+   shape) and Grep — for a baseline map, Glob from the repo root, not from
+   whatever subdirectory the conversation was already in. Record which path
+   was taken — the output must say so (step 7). Codegraph deliberately
+   excludes `node_modules`/vendor directories ("your code, not their
+   code") — it will never surface external SDK usage (Firebase, Stripe,
+   AWS SDK, etc.) even when indexed. Step 3's external-boundary scan below
+   is unconditional, not a fallback for when codegraph is unavailable.
+3. Answer, with file/symbol citations: entrypoints; core modules and their
+   one-line responsibilities; data flow between them; **external
+   boundaries** — the test is whether it crosses a network or process
+   boundary at runtime, never "is this an SDK" or "is this a big/important
+   dependency": a local-only crypto/signature check (e.g. verifying a SIWE
+   message in-process) makes no call out, so it is not one; a pure
+   UI/rendering library (e.g. MUI) is not one either, no matter how central
+   it is to the app. Read the manifest (`package.json`, `go.mod`,
+   `requirements.txt`, etc.) for dependencies that actually make a
+   network/process call (API client, DB driver, queue, cloud/SaaS SDK), then
+   Grep each one's actual import sites to confirm it's really used, not just
+   declared. Do this regardless of whether codegraph found anything in
+   step 2 — codegraph cannot see this by design.
+   Separately, flag **opaque compiled artifacts** — WASM modules, native
+   bindings, minified/vendored blobs — anything no available method
+   (codegraph or Glob/Grep) can trace into structurally, whether or not it
+   ever crosses a network boundary. This is a different kind of gap than an
+   external boundary: it is about analysis blindness (can't see what's
+   inside), not about crossing a runtime boundary — never fold the two into
+   the same bucket just because both feel "not fully knowable".
+4. Record conventions under a `## Conventions` heading — one table,
+   `area | convention | example`. `example` is `file:line` plus, whenever the
+   pattern fits on one line, an inline snippet in backticks right next to
+   it — a bare path forces a click-through to see what the rule actually
+   looks like; a row should be readable on its own. Scan across: naming,
+   file/module layout, testing (framework, what's expected to be covered),
+   error handling, commit style, dependency management, and any other
+   repo-specific idiom actually observed. Skip an area with no discernible
+   convention — a guessed or aspirational rule is worse than an absent row;
+   every row cites a real file that demonstrates it, same discipline as
+   Hotspots (step 6). An area with **two or more genuinely conflicting**
+   patterns (not "no pattern" — real, inconsistent ones, e.g. half the
+   codebase in camelCase files, the other half kebab-case) is a different
+   case from a missing convention: never silently pick a side or report
+   only the majority as "the" convention. Cite both variants in the row,
+   mark it inconsistent, and ask the user which is intended (or whether a
+   migration is mid-flight) before the map treats either as settled —
+   picking wrong here would steer later work in the wrong direction, the
+   same kind of call this skill always defers upward rather than decides
+   on its own.
+5. Draw the architecture as a mermaid diagram **generated from actual edges**
+   (imports/calls). With codegraph: edges come from its call/import graph —
+   real, queryable relationships. Without it: edges come from your own
+   Glob/Grep reading, which is a best-effort reconstruction, not a verified
+   graph — never present it with the same confidence as a codegraph-backed
+   one. External boundaries from step 3 (APIs, DB, queues, files) are nodes
+   in this same diagram, distinguishable from internal modules (e.g. a
+   different shape or an explicit `external` label) — never left as prose
+   only, or the diagram undercounts the system's real edges. Label each
+   external node with the actual service/package, not a generic bucket
+   (`Firebase App Check`, not `External API`) — one node per vendor even if
+   several internal modules call into it, so a reader can see every
+   third-party the system depends on at a glance, not just that "something
+   external" exists. Opaque compiled artifacts from step 3 get their own
+   distinguishable style — separate from external-boundary nodes, since the
+   gap they represent is different — labeled with what they are and why
+   they're opaque (e.g. `ziwei-generator (WASM, opaque to static analysis)`);
+   never merge one into the other or into a plain internal module box.
+6. Mark risk items under a `## Hotspots` heading — one table,
+   `category | location | why it matters`. Scan across: complexity (high
+   fan-in symbols, god files), test gaps (untested critical paths), tech
+   debt (known shortcuts/workarounds), known bugs, security exposure,
+   performance bottlenecks, scaling limits (capacity ceilings, breaking
+   points), fragile-to-change areas, at-risk dependencies (vulnerable or
+   abandoned packages), missing capabilities that block other work. Skip a
+   category with no evidence — a table padded to look complete
+   is worse than a short one; this is a scan for what's actually there, not
+   a checklist to fill in. These feed `wuwei-plan-phases` as risk input and
+   threat candidates; never write `CONCERNS` or any other heading — the
+   scan's breadth borrows GSD's categories (credited below), the shape and
+   vocabulary stay wuwei's own.
+7. Write the map with sections `## Architecture` (mermaid), `## Modules`
+   (table: module | responsibility), `## Conventions` (table, step 4),
+   `## Hotspots` (table, step 6), and a leading line stating the evidence
+   source: `Source: codegraph (indexed <path>)` or `Source: static scan
+   (Glob/Grep, no codegraph — treat edges as best-effort, not verified)`.
+   Pick the location by scope: a stream is already open and this map is
+   about the code that stream touches → **`.wuwei/streams/<stream>/MAP.md`**;
+   general onboarding with no stream yet (or a project-wide baseline this is
+   refreshing) → **`.wuwei/codebase/MAP.md`**. Never invent a third location
+   or fall back to an inline-only answer — both scopes persist so later runs
+   can refresh instead of rediscovering.
+8. Verify: the scope from step 1 was honored — a baseline map names every
+   app/package in the repo, not only the one under discussion; every box in
+   the diagram cites a real file or symbol; the external-boundary scan
+   (step 3) checked the manifest, not just what codegraph happened to
+   surface — a project using Firebase/Stripe/AWS SDK etc. has each one named
+   in the diagram, not folded into one generic "external" node; the
+   network/process-crossing test was applied correctly — a local-only
+   crypto check or a pure UI library was not mistaken for a boundary just
+   because it's an SDK; opaque compiled artifacts (WASM, native bindings,
+   vendored blobs) are labeled distinctly from external-boundary nodes, not
+   merged into that bucket or into a plain internal module box; every
+   external boundary from step 3 appears in the diagram, not only in prose;
+   every Conventions row
+   (step 4) and every Hotspots row (step 6) has real evidence, and every
+   category/area with real evidence has a row — no silent drops, no padding
+   to look complete; any conflicting-convention area (step 4) was asked
+   about, not silently resolved to one side; a newcomer reading the map can
+   say where a given change
+   would go; the Source line accurately reflects which path step 2 took; the
+   output landed at `.wuwei/streams/<stream>/MAP.md` or
+   `.wuwei/codebase/MAP.md` — never a path or heading borrowed from GSD or
+   any other tool.
+
+## Notes
+
+- Idea credit: GSD map-codebase, including the Hotspots scan's category
+  breadth (tech debt, bugs, security, performance, fragility, scaling,
+  dependency risk, missing capabilities, test gaps — GSD spreads these
+  across its own `CONCERNS.md`); the graph-first method is codegraph's.
+  Rewritten for wuwei.
+- The map is a projection of the code, not a second truth — when they
+  disagree, the code wins and the map gets rebuilt.

package/skills/wuwei-plan-phases/skill.md

@@ -0,0 +1,326 @@
+---
+name: wuwei-plan-phases
+description: >-
+  Use to turn an agreed approach into phases and an acceptance contract —
+  "plan this / 切 phase / 開一條 stream" — after wuwei-grill/wuwei-brainstorm
+  converge, or when a resumed stream has a missing or stale plan. Produces the
+  stream's phases, acceptance contract, and sign-off package. Ends at the head
+  human touchpoint: nothing executes before sign-off.
+version: 0.1.0
+mode: triggered
+targets: [claude-code, codex]
+inline-agents: [wuwei-pre-implementation-doubt]
+tags: [planning, workflow]
+---
+
+# Plan phases
+
+## When to use
+
+- SPEC draft exists (grilled, approach chosen) and needs slicing into
+  executable phases.
+- Resuming a stream whose `phases/` is empty, stale, or contradicts SPEC.
+
+## When NOT to use
+
+- Requirement not grilled — the plan would be confident nonsense.
+- Single trivial change: `wuwei-tdd` + `wuwei-commit-hygiene` suffice; a stream for a
+  one-liner is ceremony.
+
+## Procedure
+
+1. **Delivery strategy — first question, before any other planning work.**
+   How the work becomes real directs everything downstream: what is worth
+   researching, how the phases are cut, how e2e binds. Settle it after any
+   of those and that work was aimed by a decision nobody had made yet.
+   Resuming a stream whose `## Sign-off` already records a strategy? Read it — do not re-ask,
+   and do not silently re-slice to a different shape. Otherwise ask, one
+   question, default `mvp-first`. (This never blocks `auto`: a stream only
+   enters auto at sign-off, so a stream being planned for the first time
+   always has someone there, and a resumed auto stream reads the recorded
+   answer.)
+
+   | | `mvp-first` (default) | `feature-complete` |
+   |---|---|---|
+   | phase 01 | walking skeleton — the thinnest path that runs end to end through every layer in `## Target architecture`, deliberately shallow | one feature, vertically complete and independently shippable |
+   | later phases | deepen one part at a time; the skeleton stays green throughout | same again, one whole feature each |
+   | buys | integration risk answered first, and something runnable early | every phase is releasable and UAT-able on its own |
+   | defers | feature completeness — intermediate phases are not shippable, and some UAT items are not checkable until later | integration risk — the architecture is not exercised end to end until late |
+
+   Two knock-on effects, so this is not merely a label:
+   - **e2e binding differs** (step 6): `mvp-first` binds the critical path's
+     thin form to phase 01 and depth items to the phases that deepen it;
+     `feature-complete` binds each feature's items inside its own phase.
+   - **`depends-on` shape differs**: `mvp-first` serialises early, since
+     everything hangs off the skeleton; `feature-complete` usually leaves more
+     phases mutually independent, so more can be claimed in parallel.
+
+   Under `feature-complete`, if `## Target architecture` contains a boundary
+   no phase exercises until late and no spike de-risked it, name it as a
+   threat in the contract rather than discovering it in the last phase.
+   Record the choice in `## Sign-off`; step 3 researches to it and step 4
+   slices to it.
+2. **Stream**: ensure `.wuwei/streams/<name>/` exists; write or refresh
+   `SPEC.md` from `wuwei-grill` + `wuwei-brainstorm` output.
+3. **Research** the remaining unknowns (read code, external references —
+   library/API docs, RFCs — and wuwei's own `.wuwei/` state; spawn research
+   subagents where available). **A URL is not evidence until its content was
+   actually fetched and read** — a research subagent's finding about a
+   library, API, or RFC carries the fetched excerpt, never a bare link
+   standing in for the claim; **field names, units and example values are
+   quoted verbatim per endpoint**, since a paraphrase is where a field name
+   gets renamed; unreachable or unchecked goes into SPEC as unverified, not
+   as fact.
+
+   For anything about the existing code — what calls this, what breaks if
+   it changes, where does this shape come from — **query the code graph
+   before reading files**: check codegraph
+   `status`, index if stale, then `explore` / `search` / `callers` /
+   `impact`, falling back to Glob/Grep only when it is unavailable. Same
+   precedence as `wuwei-map-codebase` and the doubt gate. A plan sliced from
+   a guessed dependency graph produces phases whose `depends-on` is wrong,
+   which is the one field the whole execution order rests on. `.wuwei/codebase/MAP.md`, if a
+   baseline map exists, is the cheaper first read — but it is a snapshot and
+   the graph is live; where they disagree, the graph wins and the map is
+   stale. An un-imported `.planning/` (GSD) is not a
+   source here either — same boundary as `wuwei-grill` step 1: a one-shot
+   import candidate via `ww init`, never live project material to research
+   from directly.
+
+   **One exception to graph-first: a shared incrementing namespace.** The
+   next migration number or the next enum ordinal is not this repo's alone to
+   allocate, and the graph indexes one branch — it cannot see what another
+   pushed branch has already taken. `git fetch --all`, then for each branch
+   `git branch -r --no-merged <integration-branch>` (step 8) lists: a
+   filename-based slot (a migration file's leading number) needs
+   `git ls-tree -r --name-only <branch> -- <dir>`, since `grep`/`git grep`
+   search file contents and would miss it; a value written inside a file
+   needs `git grep <value> <branch>`. Two branches racing for the same slot
+   is a collision neither can see from its own history — this scan is bounded
+   by branch count, not free, but it targets one directory and one pattern,
+   not the whole tree. Step 11 verifies it was checked. Research to the strategy, not in general: `mvp-first` needs
+   the integration path answered first — can these layers actually talk? —
+   and can defer depth questions to the phases that deepen them;
+   `feature-complete` needs the first feature's depth resolved now and defers
+   the integration questions. Findings go into SPEC, not chat scrollback.
+4. **Slice phases** into `phases/NN-<name>.md`, to the shape step 1 chose:
+   - completion evidence stated in one sentence — can't state it, split it;
+   - evidence independently verifiable — needs the next phase to verify,
+     merge or re-cut;
+   - `depends-on` marked honestly (phases without mutual deps may run in
+     parallel);
+   - **cut so a phase can be reverted on its own.** On production `main` a
+     phase is the rollback unit — the fix for a bad release is `git revert` of
+     one commit — so independence is something planning delivers, not
+     something merging confers. `feature-complete` gives it by construction.
+     `mvp-first` does not: a later phase deepens an earlier one's skeleton, so
+     that pair reverts together. **Name those pairs here**, and say in
+     `## Sign-off` which phases are revert units — a phase nobody marked will
+     be assumed revertable by whoever is holding the incident. **A revert unit
+     leaves the phases before it safe and truthful** — no guard that lives only
+     in the reverted phase, no screen claiming what is no longer so;
+   - a task checklist inside the file, each task carrying **`depends-on`**
+     when it has one (omit when it has none, so an absent field means
+     independent, never forgotten). One task ≈ one commit;
+   - **a task dependency diagram** — mermaid, in the phase file, from the
+     `depends-on` fields. Order in a list cannot distinguish "this must come
+     second" from "I wrote it second"; the field carries the intent and the
+     diagram makes it readable at a glance. Omit only for a single-task
+     phase, and say so in one line;
+   - an `## Intended design` section — the target structure as a mermaid
+     diagram: the modules/interfaces this phase adds or changes and how they
+     connect. This describes what does not exist yet, so it is labelled
+     intended, never stated as observed fact (`wuwei-legible-output`);
+     `wuwei-execute-phase` diffs the built result against it. Omit only for
+     phases that add no structure (config bump, copy change) — and say which
+     in one line, so an absent diagram is never ambiguous with a forgotten one;
+   - each `## Intended design` is a **slice of SPEC's `## Target
+     architecture`**, not an independent design that happens to coexist with
+     the others — phases are how that target gets built, in order. A phase
+     that cannot be cut from it means either the target is wrong or the
+     slicing is: fix one of them here. Finding the mismatch during execution
+     is the expensive version of the same discovery. If `wuwei-brainstorm`
+     was skipped (the call was already made, or this is a bugfix) there is no
+     target to reconcile against — say so in one line, so its absence is
+     never ambiguous with an oversight;
+   - UI-touching phases add an **ASCII wireframe** under that same heading:
+     boxes, field order, button placement, and the empty / loading / error
+     states. Plain text, so it diffs in review like everything else — the
+     fidelity is layout intent, not pixels. Deciding these at plan time is
+     the point; discovering them mid-implementation is what this prevents;
+   - when a design genuinely needs more fidelity than text carries (colour,
+     type, multi-screen flow), the **source file** goes in
+     `.wuwei/streams/<stream>/sketches/` and is committed *before* it is
+     rendered or published anywhere. A rendered page is a projection of that
+     source — the same relation an issue has to a phase file — never the only
+     copy. A scratchpad or temp dir is not storage: it gets wiped, and a
+     published page you no longer hold the source for cannot be edited, only
+     rebuilt from nothing. The wireframe still goes in the phase file, so the
+     plan stays readable without opening anything;
+   - phases touching auth / payments / migrations / irreversible ops get a
+     proposed `review: human`.
+5. **Doubt gate**: run the `wuwei-pre-implementation-doubt` agent (Claude Code);
+   without subagents (Codex), read `references/wuwei-pre-implementation-doubt.md`
+   — the same agent, emitted beside this skill — and walk it inline, one
+   perspective at a time. Loop revisions until no HIGH finding
+   stands. **Each re-round reads the whole stream diff since the last round**,
+   not the list of fixes — a fix in one file is what leaves another stale.
+   **An edit made after the last round is unreviewed**: step 7 lists it, and
+   one touching money movement or persisted state gets a re-round, not a
+   skip.
+6. **Acceptance contract** `ACCEPTANCE.md`: derive critical paths from SPEC;
+   route each to automatable e2e (bound to a phase per step 1's strategy —
+   red blocks that phase)
+   or manual UAT (steps + expected result). **A repo with no e2e harness is
+   not a reason for UAT**: the first phase with a bound item adds one
+   (Playwright, which `wuwei verify` runs on too) as its first task.
+   **`## Verify`** lists each page that shows fetched data — `- <page>:
+   <route> · phase: NN`, the phase that builds it; its error, 403, empty,
+   loading and failed-refetch states are `wuwei verify`'s, not UAT's. No
+   such page → `verify: none`. Add `Threats` when an attack
+   surface exists (each: mitigate | accept | transfer, bound to a phase);
+   otherwise write `threats: none` explicitly.
+7. **Sign-off** — the head human touchpoint, never skipped in any mode.
+
+   Present, in this order: SPEC + contract + phase list (a `depends-on`
+   diagram, per `wuwei-legible-output`), SPEC's `## Target architecture`,
+   each phase's `## Intended design` (structure diagram, wireframe where
+   there is UI), and step 1's delivery strategy — whole-system target first,
+   then how the phases cut it up — plus **every edit made after the last
+   doubt-gate round**. This is the only point where a human sees the intended
+   shape before it is built, so **deliver it as files the person can open**
+   (sent files or a published page), never bare paths into a worktree.
+
+   Collect in **one round**:
+
+   - approval, or amendments;
+   - **tracker**: `per-phase` | `single` | `none`, and where. When linked,
+     also the **three status names in order** — which state means
+     in-progress, in-review, and done;
+   - which phases are circled **`review: human`**;
+   - **drive mode**: `manual` | `auto`;
+   - **merge method**: unsquashed by default — a merge commit — so ask only
+     whether this stream squashes instead, plus which methods the repo allows
+     (table below);
+   - **model policy** for review: `inherit` (default) | `roles`. Ask only
+     whether to change the default;
+   - **Codex**, when it runs execute: the model and effort it is started
+     with — `codex: <model> / <effort>`. A skill cannot set Codex's model;
+     `wuwei claim` prints the launch (`wuwei init` offers the profile);
+   - whether the plan goes through **its own PR** first — if so, steps 8–9
+     wait for that PR to merge.
+
+   Implementation is not on the menu: execute runs, and dispatches its
+   implementer, at sonnet / xhigh (`wuwei.config.json` `modelRoles`). The
+   policy sets **review** — step 5's `review:design` and `review:defects`,
+   which dispatch as subagents. The panel's other lenses inherit the session's
+   model, **except `wuwei-security-auditor`**, which pins `fable` / `high` in
+   frontmatter and holds under every policy including `inherit`. Say so,
+   rather than letting a `roles` answer imply it was chosen.
+
+   Write the outcome to `SPEC.md` under `## Sign-off`: date, what was
+   approved, delivery strategy, drive mode, tracker linkage and its three
+   status names, the three branch fields from step 8, **which merge methods
+   the target repo allows**, and the model policy —
+   **recording only what departs from the default**, since a table of
+   restated defaults is filler. `STATE.md` still carries `mode`/`tracker` for
+   index scannability; `## Sign-off` is where the decision lives, and what
+   `wuwei-execute-phase` reads.
+
+   **The merge method** gets asked here for the same reason the status names
+   do: a repo can disable merge commits or require linear history, and a rule
+   naming a method then fails at a button nobody can press. Record what the
+   repo allows, and which of them this stream uses:
+
+   | phase PR merges as | rollback of one phase | the phase's own commits |
+   |---|---|---|
+   | **merge commit — the default** | one command (`revert -m 1`) | kept, and readable |
+   | squash — opt in | one command (`revert`) | gone; the body lists their subjects |
+   | rebase — only where the repo allows nothing else | **unavailable** — say so here, so nobody plans a rollback around it | kept |
+
+   **Squashing is a human's choice, not a default**, since `wuwei-execute-phase`
+   step 2 makes every commit atomic and step 6 no longer squashes rounds: the
+   history a squash discards is now worth reading. The default keeps both
+   halves — one-command rollback *and* those commits — so the reason to
+   depart from it is a repo that forbids merge commits, or a person who wants
+   `main` carrying one commit per phase.
+
+   Asked once per stream, never re-asked.
+
+8. **Stream branch**: cut `wuwei/<stream>/base` from the current integration
+   branch — `/base`, so phase branches `wuwei/<stream>/NN-<name>` sit beside
+   it: git refuses a branch whose name is another's path — and record **three separate labelled fields** in `## Sign-off` —
+   later phases read two of them and must not read the third:
+
+   | field | read by |
+   |---|---|
+   | stream branch name | every phase — its PR base, and what phase branches are cut from |
+   | integration branch name | execute step 1, which syncs from its **tip** |
+   | the ref it was cut from | nobody. Historical marker only, **never a sync target** — syncing to a pinned old sha does nothing and reports nothing |
+
+   Separate fields, not one sentence: "cut from `main`@a1b2c3d" invites
+   exactly the wrong read. Without this step the first phase PR targets a
+   branch nobody created.
+
+9. **Tracker**: if linked, create the epic/issues via the connected MCP at
+   the chosen granularity, then **write every key back**: each phase's into
+   that phase file's `tracker-issue` frontmatter, the epic/milestone's into
+   `## Sign-off`. Without a recorded key, "this phase's issue" is something a
+   later session has to guess by title-matching, and it will eventually
+   transition a stranger's ticket. Now that the issues exist, **check the
+   three status names from sign-off against the tracker's real states** and
+   fix any that do not exist — sign-off had to ask before there was anything
+   to check them against, and a status name that does not exist is a
+   transition that silently does nothing. Issues are projections of the
+   phase files.
+10. **State**: write `STATE.md` (phase index, mode, tracker, empty claims);
+   commit the stream files.
+11. **Verify** — `wuwei plan-check <stream>` reads the checkable half:
+   `depends-on` resolves and is acyclic for tasks and phases, each task
+   diagram matches its fields, every phase carries an `## Intended design` or
+   says why not, `## Sign-off` has its fields and the stream branch is on
+   origin under `/base`, `STATE.md` agrees with `phases/`, a linked tracker
+   has a `tracker-issue` in every phase file, and auto mode never stands over
+   an open field. Errors are fixed before sign-off is shown as done.
+
+   Then the half it cannot read: every phase is a revert unit or paired with
+   the one it reverts with; the repo's allowed merge methods are recorded,
+   and the stream's own whenever it departs from the unsquashed default;
+   **any shared incrementing namespace this stream allocates from was checked
+   against unmerged branches, and the ref it was checked against named**;
+   **the phases match the recorded strategy** — a skeleton first phase under
+   `feature-complete`, or five shippable features under `mvp-first`, means
+   one of the two is a lie; a linked stream's three status names, and any
+   non-default model tier, are recorded where a resuming session will look; every e2e item maps to a phase; every
+   threat has a disposition; every UI-touching phase has a wireframe; each
+   design reconciles with SPEC's `## Target architecture`, or that target's
+   absence is explained; every mermaid block parses (quote an edge label
+   carrying punctuation).
+
+## Notes
+
+- Idea credit: GSD plan/discuss + secure-phase (declaration side). Rewritten
+  for wuwei.
+- The contract is what makes auto mode safe: the executor never defines its
+  own finish line.
+- In auto mode execute's steps 2–6 run without the user, and its steps 4–6
+  loop at least three times inside that; execute's step 7 always stops. Step 1's
+  strategy question is not an exception to that: auto is only ever entered at
+  a sign-off, which recorded the answer, so a resumed auto stream reads it
+  instead of asking.
+- Sign-off is why step 8 sits where it does: the stream stops being paper
+  there, and it is the only moment a human is present to confirm what the
+  branch is based on. Cutting earlier leaves a branch behind for a stream
+  that might still be rejected.
+- **The two-level branch shape is what makes `mode: auto` safe.** An auto
+  phase merging itself needs somewhere to land that is not main, and the
+  stream branch is it; only the finished stream opens a PR to the
+  integration branch, and that one is always human.
+- Tracker status names cannot be inferred — JIRA workflows are per-project,
+  GitHub Issues has only open/closed plus labels, GitHub Projects uses
+  custom fields — and a guessed name is a transition that silently no-ops.
+  That is why sign-off asks for all three by name.
+- `inherit` is the model-policy default because the session is already the
+  user's own decision, and pinning would silently override it — including
+  downgrading a deliberately strong session. It is also the only shape that
+  behaves the same whether work is dispatched to subagents or run inline.

package/skills/wuwei-review/references/lens-rules.md

@@ -0,0 +1,41 @@
+# Lens rules
+
+Read when the panel runs inline — no subagents (Codex). On Claude Code each
+lens carries these in its agent file; this is the same list, and a rule
+changed in one is changed in the other.
+
+## Code panel (`wuwei-review` §2)
+
+| Lens | Rule |
+|---|---|
+| design | a changed default, narrowed semantic or new enum value means nothing without **what already exists** — the rows, and the artifacts already built that an operator will redeploy (an old image still demanding the variable the new workflow no longer sends); "the new rule is right" and "existing data satisfies it" are two claims, and a migration is what connects them |
+| design | **compatible is not affordable**: for schema changes, read what the engine actually does to a table with rows — rebuild or in-place, what it locks and for how long, what a mid-failure leaves behind. Read the engine's answer, never assume it |
+| design | **turning a no-op live is not neutral**: when this change makes a dormant path actually run, ask what pre-existing bugs downstream were survivable only because it never fired. `impact`/`callers` answer the wrong (upstream) direction — walk what the newly-live call reaches by reading it; raise exploitability, leave rating it to `audit:security`. **And the mirror**: what depended on the *other* branch staying reachable — a fixture that only passed while the veto fired, a doc scoped to "once the flag is on" |
+| defects | **duplication is against the repo, not within the diff** — grep for an existing helper before accepting a new one; report as `reuse:` naming the file that already had it |
+| defects | an **exclusivity claim needs the complement** — enumerate the candidates (`wuwei sites`), subtract the compliant ones, report the rest; `callers(X)` answers the opposite question. **"Never" is a claim about history**: `git log -S<name>` is its complement, HEAD is not |
+| defects | **anything the diff deletes that can be spelled gets grepped** — identifiers, paths, ticket ids, the tokens inside deleted prose — in addition to the graph: after a move the old name has no referent, so `impact` comes back clean while every string spelling it points at nothing. A string literal is not an edge, and a spec asserting on a ticket id that lived only in a deleted comment is the hit a symbol grep never makes. **And the facts deleted prose stated are grepped for another home** — a block deleted to fix one stale line can take facts the tree states nowhere else. **And the old size of any set the diff shrinks** — an enum, a route table, an error map — is grepped as a literal in assertions; the number is valid syntax and contains none of the removed names |
+| defects | **prose inside code is code**, checked against whatever it names — markdown included. A comment naming an external consumer is a claim about that artifact; absence is the finding |
+| defects | **but the absence has to be reached before it is reported** — a zero-hit grep is a claim about the pattern, not the repo (`describe(` misses a top-level `it(`; a rename check that greps the new name proves nothing about the old). Positive control, or read what the pattern covers; if that needs a write or the suite, your own worktree of the reviewed sha — none possible, `PLAUSIBLE` and say so |
+| defects | **a hit on a removed name is a finding only if its clause still offers the name as available** — a clause recording the removal is not one. Quote the clause |
+| defects | **a zero-hit claim written into the diff is checked against the tree the change produces, not the base** — the change itself can add the first hit. Name the ref the claim holds for |
+| design | **for a queue or batch the diff reorders or filters, the row that never qualifies** — with no cursor it is selected forever and everything behind it starves, fed from an entry point the diff may never touch |
+| security | **reachability gates severity** — an unreachable sink is not HIGH |
+| security | **a missing value is an exceptional condition** — a guard whose input is `undefined`/`null` falling to the allow side (`!== expected` is true for a missing value) is fail-open; a bypass search does not find it, reading the polarity does |
+| code | judge by **this project's own standards**, and a spec that asserts a convention *is* the convention; **a permission recorded outside the repo** (the author's own instructions, a word in chat) is unobservable — ask for it in one line, never report its absence; **and the review never grants it** — a ruling posted from the review side is not the permission the rule names |
+| code, design | **a claim about a third-party tool's behaviour, or that a fix/guard/test catches some condition, is PLAUSIBLE until it's read/run — or the condition is actually constructed and the catch observed** — e.g. a migration tool's hash logic described from memory, a test called evergreen without trying to break it, or "removing this call produces N failures" without removing it and counting |
+| code | **two mutations are always in the set**: the sibling that can override what the guard reads (`tsconfig.build.json` beside the `tsconfig.json` it checks), and the opposite polarity (the guard firing when it should not) |
+| code | **a file that opens on disk is not proof it belongs to the repo** — `git ls-files -- <path>` it (check the output, not the exit code) before citing it as convention. Untracked but carrying a `GENERATED BY wuwei` marker → cite its tracked source instead; untracked with no such marker → this repo declares none of what it names, take the plain-read path |
+
+## Document panel (`wuwei-review` §3)
+
+| Lens | Rule |
+|---|---|
+| claims | **a document that instructs is reviewed for what it invites**: enumerate the positions a safety claim covers, subtract the ones its mechanism protects, report the rest. Confirming it for the cases that exist proves nothing about the ones the document teaches someone to write. **A position the syntax permits is reachable — the reader is the path**, so "no such case exists yet" does not make it PLAUSIBLE. This governs *claims in documents*, not sinks in code: `audit:security`'s reachability rule is unchanged, and the two lenses reaching opposite severities on one subject is a real disagreement for a human, not a contradiction to resolve by collation |
+| claims | **a checkable gate (an acceptance item, a `grep -c … >= 1`, a `test -f`) is a claim about what will satisfy it** — ask what *else* in the tree satisfies it, not only whether the intended thing does; **a gate reading a measurement is checked for its emitter in the tree the change produces** (a deleted emitter reads as a fake zero); **a gate names its enforcer** or is a registered gap, and **N copies of a claim by one author are one claim**; **every gate is re-run after the fixes land**, since a refactor the panel asked for is how a gate stops matching. Three ways it is false and **the dangerous ones pass**: satisfied by the wrong thing (a grep meant to prove a method exists, whose one hit is a comment about another class — green, certifying work nobody did), never satisfiable (greps a since-renamed name), or its emitter deleted by the change (a fake zero). Run it against the tree as it is now and say which it currently is — **and running its syntax is not running it**, since a fragment that parses can still be case-blind or satisfied by a superstring; a fix that would satisfy the gate on arrival is itself a finding, not a reason to stay quiet |
+| claims | **a claim about history ("never", "since it landed", "every version") is answered by `git log -S` / `git log -- <path>`, not by the tree**; and **a claim to be complete is verified by re-deriving the set, never by checking off the set it lists** — "all four call sites", "every place this is mapped", "the only consumer". Ticking each listed item passes while a fifth one exists, so derive the set from the tree instead: grep the type, the decorator, the shape — **not the names the document handed you**, which are the claim under test — then subtract. This is `defects`' exclusivity rule aimed at prose, and it bites hardest on a plan, where the executor works the list rather than the tree |
+| structure | **for every claim about what is or is not required, find the procedure section that would have to change with it** — a new section asserting a new fact with the old checklist untouched is the pattern |
+| drift | **a fact this change establishes gets grepped across the whole tree for anything still asserting the opposite** — code comments included, not only `docs/`; same shape as the rename rule: the dangerous hit is in a file the change never opened. Check the document the audience actually reads first |
+| drift | **a cross-branch or cross-version comparison uses §6's three-dot form** (`<a>...<b>`), not `<a> <b>` — tip-to-tip answers "do these differ", not "did `<b>` change what `<a>` changed", and is wrong exactly when `<a>` moved since the merge base. Three-dot fails closed (errors with no common ancestor); state which form you used |
+| drift | **a claim about an external platform's live configuration is checked against that platform, not the repo's copy of it** — on GitHub check both `.../branches/<branch>/protection` (classic, 404s under rulesets) and `.../rules/branches/<branch>` (rulesets); GET only, `per_page=100`, every page — a list endpoint's first page is a pattern with a reach. **A platform fact the dispatcher supplied (§1) is that check**; re-query only to dispute it. Can't query it → `PLAUSIBLE`, name what went unqueried, never fall back to the repo's copy as settling it |
+| drift | **a hit on a removed name is a finding only if its clause still asserts the name as current** — a clause recording the removal is not one. Quote the clause |
+| claims, drift | **a suggested fix is checked against precedent, not invented** — grep the repo for how the same kind of staleness was corrected before, and match that shape. A repo with an existing convention already answered the question. **And the anchor must survive the repo's merge settings** — a commit SHA dies under `allow_squash_merge`; anchor to the file tree. **A record (a plan, a summary, a decision log) is corrected beside the sentence, dated, not rewritten** — it is also evidence of what was believed |