wei-wuwei 0.0.0-stage → 0.2.0

package/bin/wuwei.js

@@ -0,0 +1,2832 @@
+#!/usr/bin/env node
+/**
+ * wuwei — build canonical skills/agents into per-tool formats.
+ *
+ * Usage:
+ *   wuwei build [--dry]        emit all enabled targets (repo-local artifacts)
+ *   wuwei check                validate frontmatter
+ *   wuwei list                 show discovered sources
+ *   wuwei init [<path>]        bootstrap a project (repo-scope install into path or cwd);
+ *                              also detects existing GSD (.planning/) state and offers
+ *                              a one-shot verbatim import into .wuwei/, and flags any
+ *                              installed superpowers skills that overlap wuwei's own
+ *   wuwei install [--dry]      user scope: install into ~/.claude
+ *   wuwei install <path>       repo scope: templates + .wuwei skeleton into a project
+ *   wuwei update [--dry]       is a newer wuwei out? then diff it against what
+ *                              install wrote, and apply on confirmation
+ *   wuwei status [<path>]      read-only: streams/phases/claims from .wuwei,
+ *                              cross-checked against STATE.md, drift flagged
+ *   wuwei review-prep [<base>] [--pr <n>] [--path <p>] [--no-scan]
+ *                              wuwei-review §1's deterministic half: dispatcher
+ *                              checks + scan bundle in .wuwei-cache/review/<sha>/
+ *   wuwei claim [<stream>] [<phase>] [--take-over] [--by <id>] [--dry]
+ *                              wuwei-execute-phase step 1: list what is eligible,
+ *                              or claim one — cut, claim, push
+ *   wuwei digest-check <file>  wuwei-review §7's arithmetic before publishing: count,
+ *                              rows, credits, file:line, Action names, redaction
+ *   wuwei worktree <lens> [<sha>]  a throwaway worktree no other lens shares; --prune
+ *   wuwei mutate <f>:<n> --from --to --run   one mutation in a wuwei worktree: landed?
+ *                              baseline vs mutated, failing tests, restored, recorded
+ *   wuwei sites <pattern> [--symbol <name>]   a set from the tree, with its derivation;
+ *                              graph and grep both for a symbol
+ *   wuwei verify [<page>…] [--phase NN]  every data-bearing page through its states
+ *                              (Playwright, fixtures from .wuwei/verify.json): a matrix of
+ *                              shots; --phase runs the pages ACCEPTANCE.md binds to it
+ *   wuwei plan-check [<stream>]  wuwei-plan-phases step 11's checkable half
+ *   wuwei uninstall [<path>]   remove exactly what install wrote
+ *   wuwei -v | --version       print the installed version
+ */
+import {
+  readFileSync, writeFileSync, readdirSync, mkdirSync, existsSync, rmSync, statSync,
+  chmodSync,
+} from 'node:fs'
+import { join, dirname, resolve } from 'node:path'
+import { homedir, tmpdir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+import { createInterface } from 'node:readline/promises'
+import { spawnSync, spawn } from 'node:child_process'
+import { createRequire } from 'node:module'
+import { createHash } from 'node:crypto'
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const CONFIG = JSON.parse(readFileSync(join(ROOT, 'wuwei.config.json'), 'utf8'))
+const PKG = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8'))
+
+// the version is stamped so an installed artifact says which version wrote it;
+// isOurs matches the 'GENERATED BY wuwei' prefix, so older stamps still count
+const GENERATED_HEADER =
+  '<!-- GENERATED BY wuwei v%VER% — do not edit. Source: %SRC%. Run `npm run build`. -->'
+const stamp = src => CONFIG.options.stampGeneratedHeader
+  ? GENERATED_HEADER.replace('%VER%', PKG.version).replace('%SRC%', src) + '\n\n' : ''
+const BLOCK_BEGIN = '<!-- wuwei:begin — generated rules, do not edit inside. `wuwei uninstall` removes this block. -->'
+const BLOCK_END = '<!-- wuwei:end -->'
+// Codex's default read limit for AGENTS.md (project_doc_max_bytes, 32 KiB)
+const CODEX_DOC_MAX_BYTES = 32 * 1024
+
+// ── tiny frontmatter parser (no deps) ────────────────────────────────
+// CRLF first: with git's core.autocrlf=true (the Windows default) every source
+// file lands here with \r line endings, and `^([A-Za-z0-9_-]+):\s*(.*)$` can't
+// match a line ending in \r — `.` never matches it and `$` won't step over it.
+// Every field then reads as missing and `check` fails on files that are fine.
+function parseFrontmatter(input) {
+  const raw = input.replace(/\r\n?/g, '\n')
+  if (!raw.startsWith('---')) return { data: {}, body: raw }
+  const end = raw.indexOf('\n---', 3)
+  if (end === -1) return { data: {}, body: raw }
+  const head = raw.slice(4, end)
+  const body = raw.slice(end + 4).replace(/^\n/, '')
+  const data = {}
+  let key = null
+  for (const line of head.split('\n')) {
+    if (/^\s+/.test(line) && key) { data[key] += ' ' + line.trim(); continue }
+    const m = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/)
+    if (!m) continue
+    key = m[1]
+    let v = m[2].trim()
+    if (v === '>-' || v === '>' || v === '|') { data[key] = ''; continue }
+    if (v.startsWith('[') && v.endsWith(']')) {
+      v = v.slice(1, -1).split(',').map(s => s.trim()).filter(Boolean)
+    }
+    data[key] = v
+  }
+  for (const k of Object.keys(data))
+    if (typeof data[k] === 'string') data[k] = data[k].trim()
+  return { data, body }
+}
+
+// ── discovery ────────────────────────────────────────────────────────
+// two roots per kind: the shipped one (sources.skills / sources.agents) and
+// local/<kind>/ — definitions that tune this repo itself (wuwei-retro).
+// local/ is outside package.json `files`, so publish never carries it, and
+// install skips it (isLocal) so no other project sees it either
+function discover(kind) {
+  const file = kind === 'agents' ? 'agent.md' : 'skill.md'
+  const roots = [
+    { dir: join(ROOT, CONFIG.sources[kind]), local: false },
+    ...(CONFIG.sources.local ? [{ dir: join(ROOT, CONFIG.sources.local, kind), local: true }] : []),
+  ]
+  return roots.flatMap(({ dir, local }) => {
+    if (!existsSync(dir)) return []
+    return readdirSync(dir, { withFileTypes: true })
+      .filter(d => d.isDirectory() && !d.name.startsWith('_'))
+      .map(d => join(dir, d.name, file))
+      .filter(existsSync)
+      .map(p => {
+        const { data, body } = parseFrontmatter(readFileSync(p, 'utf8'))
+        return { path: p, rel: p.slice(ROOT.length + 1), kind, data, body, local, refs: discoverRefs(dirname(p)) }
+      })
+  })
+}
+
+// a skill's references/*.md load on demand: the skill body names them, and
+// the model reads one only when that branch of the procedure runs
+function discoverRefs(dir) {
+  const refDir = join(dir, 'references')
+  if (!existsSync(refDir)) return []
+  return readdirSync(refDir).filter(f => f.endsWith('.md')).sort()
+    .map(f => ({ name: f, rel: join(refDir, f).slice(ROOT.length + 1), content: readFileSync(join(refDir, f), 'utf8') }))
+}
+
+// written beside SKILL.md
+const refArtifacts = (it, skillDir) => (it.refs ?? [])
+  .map(r => ({ file: join(skillDir, 'references', r.name), content: stamp(r.rel) + r.content }))
+
+// ── install record: what install wrote, by hash — how update tells an edit you
+// made from a change upstream (GSD's file manifest). ~/.wuwei is ours: the record,
+// and local-patches/ where update copies an edited file before overwriting it
+const wuweiHome = () => join(homedir(), '.wuwei')
+const manifestPath = () => join(wuweiHome(), 'manifest.json')
+const sha256 = s => createHash('sha256').update(s).digest('hex')
+const recorded = new Map() // file, or file#rules for a managed block → hash of what this run wrote
+function readManifest() {
+  try { return JSON.parse(readFileSync(manifestPath(), 'utf8')) } catch { return null }
+}
+
+// write what an emitter computed. A skill's references/ dir is regenerated
+// whole, so a reference removed from the source does not linger in the target
+function writeArtifacts(artifacts, dry) {
+  if (dry) return artifacts.map(a => a.file)
+  for (const a of artifacts.filter(a => a.file.endsWith('SKILL.md'))) {
+    const refDir = join(dirname(a.file), 'references')
+    if (existsSync(refDir) && isOurs(a.file)) rmSync(refDir, { recursive: true })
+  }
+  for (const a of artifacts) { mkdirSync(dirname(a.file), { recursive: true }); writeFileSync(a.file, a.content); recorded.set(a.file, sha256(a.content)) }
+  return artifacts.map(a => a.file)
+}
+
+function discoverTemplates() {
+  const dir = join(ROOT, CONFIG.sources.templates ?? 'templates')
+  if (!existsSync(dir)) return []
+  return readdirSync(dir)
+    .filter(f => f.endsWith('.md'))
+    .map(f => ({ name: f, path: join(dir, f), content: readFileSync(join(dir, f), 'utf8') }))
+}
+
+// ── validation ───────────────────────────────────────────────────────
+const REQUIRED = ['name', 'description', 'version']
+const MODES = ['always', 'triggered']
+const ALWAYS_MAX_LINES = 12
+// claude-code subagent fields we pass through; values are checked because a
+// typo would otherwise ship an artifact the target silently ignores
+const MODEL_ALIASES = ['sonnet', 'opus', 'haiku', 'fable', 'inherit']
+const EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max']
+
+function validate(items) {
+  const errs = []
+  const seen = new Set()
+  for (const it of items) {
+    for (const f of REQUIRED)
+      if (!it.data[f]) errs.push(`${it.rel}: missing frontmatter field '${f}'`)
+    if (it.data.name) {
+      if (seen.has(it.data.name)) errs.push(`${it.rel}: duplicate name '${it.data.name}'`)
+      seen.add(it.data.name)
+      if (!/^[a-z0-9-]+$/.test(it.data.name))
+        errs.push(`${it.rel}: name must be kebab-case`)
+    }
+    if (it.data.description && it.data.description.length > 400)
+      errs.push(`${it.rel}: description too long (${it.data.description.length} > 400)`)
+    if (it.data.mode && !MODES.includes(it.data.mode))
+      errs.push(`${it.rel}: mode must be one of ${MODES.join('|')}`)
+    // on a skill, Claude Code applies model/effort to the turn the skill runs
+    // in (and only that turn — the session's resume on the next prompt)
+    if (it.data.model && !MODEL_ALIASES.includes(it.data.model)
+      && !/^claude-[a-z0-9.-]+$/.test(it.data.model))
+      errs.push(`${it.rel}: model must be ${MODEL_ALIASES.join('|')} or a full id (claude-…)`)
+    if (it.data.effort && !EFFORTS.includes(it.data.effort))
+      errs.push(`${it.rel}: effort must be one of ${EFFORTS.join('|')}`)
+    // location decides what stays in this repo — a field would be a second
+    // source of truth that can disagree with the directory
+    if (it.data.scope)
+      errs.push(`${it.rel}: 'scope' is not a field — put repo-only definitions under local/${it.kind}/`)
+    for (const name of [].concat(it.data['inline-agents'] ?? [])) {
+      if (it.kind !== 'skills') errs.push(`${it.rel}: inline-agents applies to skills only`)
+      else if (!items.some(a => a.kind === 'agents' && a.data.name === name))
+        errs.push(`${it.rel}: inline-agents names '${name}', which is not an agent`)
+    }
+    if (it.data.mode === 'always') {
+      const lines = it.body.split('\n').filter(l => l.trim()).length
+      if (lines > ALWAYS_MAX_LINES)
+        errs.push(`${it.rel}: mode:always body too long (${lines} > ${ALWAYS_MAX_LINES} non-empty lines) — a rule rides in every request, keep it terse`)
+    }
+  }
+  return errs
+}
+
+// ── shared helpers ───────────────────────────────────────────────────
+const targeted = (it, tool) => !it.data.targets || it.data.targets.includes(tool)
+const isRule = it => it.data.mode === 'always'
+const isLocal = it => it.local === true
+const escapeRe = s => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+function rulesBlock(rules) {
+  const parts = [BLOCK_BEGIN]
+  for (const it of rules) parts.push('', it.body.trim())
+  parts.push('', BLOCK_END)
+  return parts.join('\n')
+}
+
+function mergeManagedBlock(file, block, dry) {
+  const existing = existsSync(file) ? readFileSync(file, 'utf8') : ''
+  const re = new RegExp(`${escapeRe(BLOCK_BEGIN)}[\\s\\S]*?${escapeRe(BLOCK_END)}`)
+  const next = re.test(existing)
+    ? existing.replace(re, block)
+    : (existing ? existing.replace(/\n*$/, '\n\n') + block + '\n' : block + '\n')
+  if (!dry) { mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, next); recorded.set(`${file}#rules`, sha256(block)) }
+}
+
+function stripManagedBlock(file, dry = false) {
+  if (!existsSync(file)) return false
+  const existing = readFileSync(file, 'utf8')
+  const re = new RegExp(`\\n*${escapeRe(BLOCK_BEGIN)}[\\s\\S]*?${escapeRe(BLOCK_END)}\\n*`)
+  if (!re.test(existing)) return false
+  if (!dry) {
+    const next = existing.replace(re, '\n').trim()
+    if (next) writeFileSync(file, next + '\n')
+    else rmSync(file)
+  }
+  return true
+}
+
+// only ever remove a path we stamped ourselves — never a same-named user file
+const isOurs = probe => existsSync(probe) && readFileSync(probe, 'utf8').includes('GENERATED BY wuwei')
+
+// a rename or removal leaves the old generated dir/file behind forever
+// unless we sweep for stamped paths that no longer match a current definition
+function sweepStale(base, currentSkillNames, currentAgentNames, dry) {
+  const removed = []
+  const skillsDir = join(base, 'skills')
+  if (existsSync(skillsDir)) {
+    for (const d of readdirSync(skillsDir, { withFileTypes: true })) {
+      if (!d.isDirectory() || currentSkillNames.has(d.name)) continue
+      const dir = join(skillsDir, d.name)
+      if (isOurs(join(dir, 'SKILL.md'))) { if (!dry) rmSync(dir, { recursive: true }); removed.push(dir) }
+    }
+  }
+  const agentsDir = join(base, 'agents')
+  if (existsSync(agentsDir)) {
+    for (const f of readdirSync(agentsDir, { withFileTypes: true })) {
+      if (!f.isFile() || !f.name.endsWith('.md')) continue
+      const name = f.name.slice(0, -3)
+      if (currentAgentNames.has(name)) continue
+      const file = join(agentsDir, f.name)
+      if (isOurs(file)) { if (!dry) rmSync(file); removed.push(file) }
+    }
+  }
+  return removed
+}
+
+// ── claude-code emit (build: repo scope · install: user scope) ───────
+// what install writes, without writing it — `wuwei update` diffs against this,
+// so its preview cannot drift from what install produces. Targeted + non-rule
+// is also the set the stale sweep keeps: a skill that flips to mode:always or
+// drops claude-code would otherwise count as "current" and never sweep
+function claudeArtifacts(items, base) {
+  return items.filter(i => targeted(i, 'claude-code') && !isRule(i)).flatMap(it => {
+    const fm = ['---', `name: ${it.data.name}`, `description: ${it.data.description}`]
+    if (it.data['allowed-tools']?.length)
+      fm.push(`allowed-tools: [${[].concat(it.data['allowed-tools']).join(', ')}]`)
+    if (it.data.tools?.length)
+      fm.push(`tools: [${[].concat(it.data.tools).join(', ')}]`)
+    if (it.data.model) fm.push(`model: ${it.data.model}`)
+    if (it.data.effort) fm.push(`effort: ${it.data.effort}`)
+    fm.push('---', '')
+    // skills: one dir per skill (SKILL.md); agents: flat .md — Claude Code subagent format
+    const file = it.kind === 'agents'
+      ? join(base, 'agents', `${it.data.name}.md`)
+      : join(base, 'skills', it.data.name, 'SKILL.md')
+    const main = { file, content: fm.join('\n') + stamp(it.rel) + it.body }
+    return it.kind === 'skills' ? [main, ...refArtifacts(it, dirname(file))] : [main]
+  })
+}
+
+const namesUnder = (artifacts, base, kind) => new Set(artifacts
+  .map(a => a.file.slice(base.length + 1).split(/[\\/]/))
+  .filter(p => p[0] === kind).map(p => kind === 'agents' ? p[1].replace(/\.md$/, '') : p[1]))
+
+function emitClaude(items, base, rulesFile, dry) {
+  const artifacts = claudeArtifacts(items, base)
+  const removed = sweepStale(base, namesUnder(artifacts, base, 'skills'), namesUnder(artifacts, base, 'agents'), dry)
+  const written = writeArtifacts(artifacts, dry)
+  const rules = items.filter(i => targeted(i, 'claude-code') && isRule(i))
+  if (rules.length) {
+    mergeManagedBlock(rulesFile, rulesBlock(rules), dry)
+    written.push(rulesFile)
+  } else if (stripManagedBlock(rulesFile, dry)) {
+    // last rule flipped away from mode:always (or was removed) — the block
+    // has no source anymore, so it goes stale exactly like an orphaned skill dir
+    removed.push(rulesFile)
+  }
+  // tag removals distinctly so callers can print them without counting them as writes
+  return [...removed.map(r => `${r} [stale, removed]`), ...written]
+}
+
+// a line tagged this way by emitClaude is a stale-sweep removal, not a write —
+// cmdBuild/cmdInstall print it but exclude it from their write counts
+const REMOVED_TAG = ' [stale, removed]'
+const isRemovalLine = line => line.endsWith(REMOVED_TAG)
+
+// ── adapters (build: repo-local artifacts) ───────────────────────────
+const adapters = {
+  'claude-code': (items, outDir, dry) =>
+    emitClaude(items, join(ROOT, outDir), join(ROOT, 'CLAUDE.md'), dry).map(line => {
+      const removal = isRemovalLine(line)
+      const path = removal ? line.slice(0, -REMOVED_TAG.length) : line
+      return path.slice(ROOT.length + 1) + (removal ? REMOVED_TAG : '')
+    }),
+
+  // Codex: AGENTS.md carries only what must ride every request (always-on
+  // rules); each skill goes to .agents/skills/<name>/SKILL.md, which Codex
+  // discovers natively and loads on demand (name + description up front,
+  // body only when used) — the same lazy load claude-code gets. Dumping every
+  // body into AGENTS.md put 121 KB against Codex's default 32 KiB read limit
+  // (project_doc_max_bytes), so everything past the cut never reached it.
+  codex: (items, outFile, dry) => {
+    const picked = items.filter(it => it.kind === 'skills' && targeted(it, 'codex'))
+    if (!picked.length) return []
+    const rules = picked.filter(isRule)
+    const lazy = picked.filter(it => !isRule(it))
+    const { removed, written } = emitCodexSkills(lazy, join(ROOT, dirname(outFile), '.agents'), dry, items)
+    const parts = []
+    if (CONFIG.options.stampGeneratedHeader)
+      parts.push(stamp('skills/ (mode: always)').trimEnd(), '')
+    parts.push('# AGENTS.md', '', 'Always-on rules for this repository, generated by wuwei.',
+      'Skills live in `.agents/skills/` and load when a task matches their description.', '')
+    for (const it of rules) parts.push(it.body.trim(), '')
+    const out = parts.join('\n')
+    if (Buffer.byteLength(out) > CODEX_DOC_MAX_BYTES)
+      console.warn(`! ${outFile} is ${Buffer.byteLength(out)} bytes — Codex reads ${CODEX_DOC_MAX_BYTES} by default (project_doc_max_bytes); the rest never reaches it`)
+    if (!dry) {
+      mkdirSync(dirname(join(ROOT, outFile)), { recursive: true })
+      writeFileSync(join(ROOT, outFile), out)
+    }
+    return [...removed.map(r => `${r} [stale, removed]`), outFile, ...written.map(f => f.slice(ROOT.length + 1))]
+  },
+}
+
+// each skill to <base>/skills/<name>/SKILL.md (+ references/), stale stamped dirs swept.
+// Codex has no subagents, so an agent a skill runs (`inline-agents:`) goes in as
+// references/<agent>.md for the skill to walk inline — one source, the agent file
+function codexArtifacts(skills, base, agents = []) {
+  return skills.flatMap(it => {
+    const fm = ['---', `name: ${it.data.name}`, `description: ${it.data.description}`, '---', '']
+    const file = join(base, 'skills', it.data.name, 'SKILL.md')
+    const inline = [].concat(it.data['inline-agents'] ?? []).map(name => {
+      const ag = agents.find(a => a.kind === 'agents' && a.data.name === name)
+      return { file: join(dirname(file), 'references', `${name}.md`), content: stamp(ag.rel) + ag.body }
+    })
+    return [{ file, content: fm.join('\n') + stamp(it.rel) + it.body }, ...refArtifacts(it, dirname(file)), ...inline]
+  })
+}
+
+function emitCodexSkills(skills, base, dry, agents = []) {
+  const removed = sweepStale(base, new Set(skills.map(it => it.data.name)), new Set(), dry)
+  return { removed, written: writeArtifacts(codexArtifacts(skills, base, agents), dry) }
+}
+
+// Codex at user scope (codex-rs ext/skills/src/host_roots.rs, codex-home/src/instructions):
+// skills from ~/.agents/skills ($CODEX_HOME/skills is the deprecated location),
+// rules from $CODEX_HOME/AGENTS.md unless a non-empty AGENTS.override.md
+// replaces it. CODEX_HOME defaults to ~/.codex.
+const codexHome = () => process.env.CODEX_HOME || join(homedir(), '.codex')
+const codexUserSkillsBase = () => join(homedir(), '.agents')
+
+// install writes Codex's user scope only where Codex has run: creating
+// ~/.codex for someone who never installed it would be a side effect
+function installCodexUser(items, dry) {
+  const home = codexHome()
+  if (!existsSync(home)) {
+    console.log(`codex: ${home} not found — skipped (run codex once, then install again)`)
+    return
+  }
+  const picked = items.filter(it => it.kind === 'skills' && targeted(it, 'codex'))
+  const { removed, written } = emitCodexSkills(picked.filter(it => !isRule(it)), codexUserSkillsBase(), dry, items)
+  const rulesFile = join(home, 'AGENTS.md')
+  const rules = picked.filter(isRule)
+  if (rules.length) { mergeManagedBlock(rulesFile, rulesBlock(rules), dry); written.push(rulesFile) }
+  else if (stripManagedBlock(rulesFile, dry)) removed.push(rulesFile)
+  console.log(`${dry ? '[dry] ' : ''}codex user scope → ${codexUserSkillsBase()}, ${rulesFile}`)
+  for (const r of removed) console.log(`    ${r}${REMOVED_TAG}`)
+  for (const w of written) console.log(`    ${w}`)
+  const override = join(home, 'AGENTS.override.md')
+  if (rules.length && existsSync(override) && readFileSync(override, 'utf8').trim())
+    console.warn(`! ${override} is non-empty — Codex reads it instead of AGENTS.md, so the rules block is not loaded`)
+}
+
+// ── STATE.md skeleton (repo-scope install) ───────────────────────────
+const STATE_HEADER_LINE = '| stream | mode | tracker | phases done/total | blocked |'
+const STATE_SKELETON = `# wuwei state
+
+<!-- index of streams — maintained by wuwei-plan-phases / wuwei-execute-phase, human-editable -->
+<!-- this file is a projection of streams/; \`wuwei status\` renders it cross-checked against the directories -->
+
+${STATE_HEADER_LINE}
+|--------|------|---------|-------------------|---------|
+`
+
+// ── commands ─────────────────────────────────────────────────────────
+function loadValidated() {
+  const items = [...discover('skills'), ...discover('agents')]
+  const errs = validate(items)
+  if (errs.length) {
+    console.error('✗ validation failed:\n' + errs.map(e => '  ' + e).join('\n'))
+    process.exit(1)
+  }
+  return items
+}
+
+function cmdList() {
+  for (const kind of ['skills', 'agents']) {
+    const items = discover(kind)
+    console.log(`\n${kind} (${items.length})`)
+    for (const it of items)
+      console.log(`  ${(isRule(it) ? it.data.name + ' [always]' : isLocal(it) ? it.data.name + ' [local]' : it.data.name).padEnd(28)} ${it.rel}`)
+  }
+  const tpl = discoverTemplates()
+  console.log(`\ntemplates (${tpl.length})`)
+  for (const t of tpl) console.log(`  ${t.name}`)
+  console.log()
+}
+
+// ── lint: what retros kept checking by hand ──────────────────────────
+// check-only (CI), never part of build/install: a shipped package must not
+// refuse to install over its own prose
+const COUNT_WORDS = { two: 2, three: 3, four: 4, five: 5, six: 6, seven: 7, eight: 8, nine: 9, ten: 10, eleven: 11, twelve: 12 }
+const wordCount = text => text.split(/\s+/).filter(Boolean).length
+
+// "Eight shapes need evidence …:" followed by a list or a table — the number
+// is a claim about the list, and the list is what a retro edits
+function countClaims(rel, text) {
+  const errs = []
+  const lines = text.split('\n')
+  const isItem = l => /^\s*([-*]|\d+\.)\s/.test(l ?? '')
+  lines.forEach((line, i) => {
+    const m = line.match(/\b(two|three|four|five|six|seven|eight|nine|ten|eleven|twelve)\s+(?!of\b|more\b|times\b|or\b|and\b)([A-Za-z-]+)/i)
+    if (!m) return
+    // the sentence may wrap: it has to end in ':' at a line end within three lines
+    let end = -1
+    for (let j = i; j < Math.min(i + 3, lines.length); j++) {
+      const tail = j === i ? line.slice(m.index) : lines[j]
+      if (/\.\s/.test(tail) || /\.$/.test(tail.trim())) break
+      if (/:\s*$/.test(tail)) { end = j; break }
+    }
+    if (end === -1) return
+    let j = end + 1
+    while (j < lines.length && !lines[j].trim()) j++
+    let items = 0
+    if (isItem(lines[j])) {
+      const indent = lines[j].match(/^\s*/)[0].length
+      for (; j < lines.length; j++) {
+        const l = lines[j]
+        if (!l.trim()) { if (isItem(lines[j + 1]) && lines[j + 1].match(/^\s*/)[0].length >= indent) continue; break }
+        const own = isItem(l) && l.match(/^\s*/)[0].length === indent
+        if (own) items++
+        else if (l.match(/^\s*/)[0].length <= indent && !isItem(l)) break
+      }
+    } else if (/^\s*\|/.test(lines[j] ?? '')) {
+      // a table's rows are what the number counts only when its first header
+      // names them ("Five columns" over | Column | …) — "two axes" over a
+      // table of targets is a claim about its columns, not its rows
+      const stem = w => w.toLowerCase().replace(/(es|s)$/, '')
+      const head = lines[j].split('|')[1]?.trim() ?? ''
+      if (stem(head) !== stem(m[2])) return
+      for (; j < lines.length && /^\s*\|/.test(lines[j]); j++) if (!/^\s*\|[\s:|-]+\|\s*$/.test(lines[j])) items++
+      items-- // the header row
+    } else return
+    const said = COUNT_WORDS[m[1].toLowerCase()]
+    if (items !== said)
+      errs.push(`${rel}:${i + 1}: says "${m[1]} ${m[2]}" but the list below has ${items} — fix the number or the list`)
+  })
+  return errs
+}
+
+function lint(items) {
+  const errs = []
+  const byName = new Map(items.map(it => [it.data.name, it]))
+  const sectionsOf = it => new Set([...it.body.matchAll(/^##+\s+(\d+)\./gm)].map(m => m[1]))
+  const refsOf = it => new Set([...(it.refs ?? []).map(r => r.name), ...[].concat(it.data['inline-agents'] ?? []).map(n => `${n}.md`)])
+  const budgets = CONFIG.wordBudgets ?? {}
+  for (const it of items) {
+    const texts = [[it.rel, it.body], ...(it.refs ?? []).map(r => [r.rel, r.content])]
+    for (const [rel, text] of texts) {
+      errs.push(...countClaims(rel, text))
+      const scan = (line, i) => {
+        const at = i < 0 ? `${rel} (description)` : `${rel}:${i + 1}`
+        for (const m of line.matchAll(/`(wuwei-[a-z0-9-]+)`/g))
+          if (!byName.has(m[1])) errs.push(`${at}: \`${m[1]}\` is not a skill or agent — renamed or removed?`)
+        for (const m of line.matchAll(/`(wuwei-[a-z0-9-]+)`(?:'s)?\s+§(\d+)/g))
+          if (byName.has(m[1]) && !sectionsOf(byName.get(m[1])).has(m[2]))
+            errs.push(`${at}: \`${m[1]}\` §${m[2]} — it has no "## ${m[2]}." section`)
+        for (const m of line.matchAll(/references\/([A-Za-z0-9_.-]+\.md)/g)) {
+          const named = [...line.matchAll(/`(wuwei-[a-z0-9-]+)`/g)].map(x => byName.get(x[1])).filter(Boolean)
+          if (![it, ...named].some(x => refsOf(x).has(m[1])))
+            errs.push(`${at}: references/${m[1]} is not in ${[it, ...named].map(x => x.data.name).join(' or ')}`)
+        }
+      }
+      text.split('\n').forEach(scan)
+      // the description decides when it triggers: a stale name there misroutes
+      if (rel === it.rel) scan(it.data.description ?? '', -1)
+      // a budget is a ratchet: growing past it is a decision, recorded as one
+      const budget = budgets[rel]
+      if (budget && wordCount(text) > budget)
+        errs.push(`${rel}: ${wordCount(text)} words > budget ${budget} — cut, or raise wordBudgets in wuwei.config.json with a docs/decisions.md row`)
+    }
+  }
+  for (const rel of Object.keys(budgets))
+    if (!items.some(it => it.rel === rel || (it.refs ?? []).some(r => r.rel === rel)))
+      errs.push(`wuwei.config.json: wordBudgets names ${rel}, which is not a definition or reference`)
+  // modelRoles names the tier; the agent file is what dispatch actually reads
+  const impl = CONFIG.modelRoles?.implementation
+  if (impl) {
+    const ag = items.find(it => it.kind === 'agents' && it.data.name === impl.agent)
+    if (!ag) errs.push(`wuwei.config.json: modelRoles.implementation.agent ${impl.agent} is not an agent`)
+    else for (const f of ['model', 'effort']) if (ag.data[f] !== impl[f])
+      errs.push(`${ag.rel}: ${f} ${ag.data[f] ?? '(unset)'} ≠ modelRoles.implementation.${f} ${impl[f]} — the roles tier is what this file pins`)
+  }
+  // the skill that runs implementation runs its own turn at the same tier
+  const sk = impl?.skill && items.find(it => it.kind === 'skills' && it.data.name === impl.skill)
+  if (impl?.skill && !sk) errs.push(`wuwei.config.json: modelRoles.implementation.skill ${impl.skill} is not a skill`)
+  else if (sk) for (const f of ['model', 'effort']) if (sk.data[f] !== impl[f])
+    errs.push(`${sk.rel}: ${f} ${sk.data[f] ?? '(unset)'} ≠ modelRoles.implementation.${f} ${impl[f]} — execute runs at the implementer's tier`)
+  for (const l of CONFIG.modelRoles?.review?.lenses ?? [])
+    if (!items.some(it => it.kind === 'agents' && it.data.name === l)) errs.push(`wuwei.config.json: modelRoles.review.lenses names ${l}, which is not an agent`)
+  // update prints this file's sections — a version without one updates in silence
+  const changelog = existsSync(join(ROOT, 'CHANGELOG.md')) ? readFileSync(join(ROOT, 'CHANGELOG.md'), 'utf8') : ''
+  if (!new RegExp(`^## v?${escapeRe(PKG.version)}\\b`, 'm').test(changelog))
+    errs.push(`CHANGELOG.md has no "## ${PKG.version}" section — what \`wuwei update\` shows before it asks`)
+  return errs
+}
+
+function cmdCheck() {
+  const items = loadValidated()
+  const errs = lint(items)
+  if (errs.length) {
+    console.error('✗ lint failed:\n' + errs.map(e => '  ' + e).join('\n'))
+    process.exit(1)
+  }
+  console.log(`✓ ${items.length} definitions valid, lint clean`)
+}
+
+function cmdBuild(dry) {
+  const items = loadValidated()
+  let total = 0
+  for (const t of CONFIG.targets) {
+    if (!t.enabled) continue
+    const fn = adapters[t.adapter]
+    if (!fn) { console.warn(`! no adapter '${t.adapter}', skipping`); continue }
+    const lines = fn(items, t.out, dry)
+    const count = lines.filter(l => !isRemovalLine(l)).length
+    total += count
+    console.log(`${dry ? '[dry] ' : ''}${t.adapter} → ${count} file(s)`)
+    for (const l of lines) console.log(`    ${l}`)
+  }
+  console.log(`\n${dry ? '[dry] would write' : 'wrote'} ${total} file(s) from ${items.length} definition(s)`)
+}
+
+async function cmdInstall(target, dry) {
+  if (!target) {
+    // user scope: disciplines follow the person — local/ definitions do not
+    const items = loadValidated().filter(it => !isLocal(it))
+    const base = join(homedir(), '.claude')
+    const written = emitClaude(items, base, join(base, 'CLAUDE.md'), dry)
+    console.log(`${dry ? '[dry] ' : ''}user scope → ${base}`)
+    for (const w of written) console.log(`    ${w}`)
+    installCodexUser(items, dry)
+    if (!dry) {
+      mkdirSync(wuweiHome(), { recursive: true })
+      const files = Object.fromEntries([...recorded].filter(([f]) => f.startsWith(homedir())))
+      writeFileSync(manifestPath(), JSON.stringify({ version: PKG.version, files }, null, 1) + '\n')
+    }
+    // offer to register the global bin, unless it's already linked. isGloballyLinked
+    // asks npm directly rather than guessing from how this invocation started —
+    // `npm link`/symlinked checkouts would otherwise mis-detect either direction.
+    // Interactive: ask, act only on yes — same explicit-confirmation pattern as
+    // the GSD import, never silently touch global npm state. Non-interactive:
+    // still say so (this is information, not a nag), just don't block on an
+    // answer that will never come.
+    if (!dry && !isGloballyLinked()) {
+      // from a clone, install that checkout; from the package (npx), install it
+      // by name — `install -g .` inside npx's cache would link a dir npm may prune
+      const fromClone = existsSync(join(ROOT, '.git'))
+      const spec = fromClone ? '.' : PKG.name
+      const command = fromClone ? `(cd ${ROOT} && npm install -g .)` : `npm install -g ${PKG.name}`
+      // the skills call `wuwei review-prep`, `wuwei claim`, `wuwei verify`… — without the
+      // command those steps fail, so say so rather than leave it as a convenience
+      const manualHint = `the skills call \`wuwei …\` and those steps fail without it; run this yourself anytime:\n    ${command}`
+      if (!isInteractive()) {
+        console.log(`\n\`wuwei\`/\`ww\` aren't global commands yet — ${manualHint}`)
+      } else if (await promptYesNo(`\n\`wuwei\`/\`ww\` aren't global commands yet. Run \`npm install -g ${spec}\` now so they are?`)) {
+        const result = runNpm(['install', '-g', spec], { cwd: ROOT, stdio: 'inherit' })
+        console.log(result.status === 0
+          ? 'done — run `ww -v` to confirm it prints a version.'
+          : `\nthat failed${result.error ? '' : ` (exit ${result.status})`} — ${manualHint}`)
+      } else {
+        console.log(`skipped — ${manualHint}`)
+      }
+    }
+    return
+  }
+  // repo scope: templates + state skeleton follow the project
+  const dest = resolve(target)
+  if (!existsSync(dest) || !statSync(dest).isDirectory()) {
+    console.error(`✗ not a directory: ${dest}`)
+    process.exit(1)
+  }
+  const written = []
+  for (const t of discoverTemplates()) {
+    const file = t.name === 'pr.md'
+      ? join(dest, '.github', 'PULL_REQUEST_TEMPLATE.md')
+      : join(dest, '.wuwei', 'templates', t.name)
+    if (!dry) { mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, t.content) }
+    written.push(file)
+  }
+  const state = join(dest, '.wuwei', 'STATE.md')
+  if (!existsSync(state)) {
+    if (!dry) { mkdirSync(dirname(state), { recursive: true }); writeFileSync(state, STATE_SKELETON) }
+    written.push(state)
+  }
+  console.log(`${dry ? '[dry] ' : ''}repo scope → ${dest}`)
+  for (const w of written) console.log(`    ${w}`)
+}
+
+// both stdin and stdout must be a real terminal — otherwise a prompt's text
+// vanishes into a redirected file/pipe and we'd block forever on an answer
+// nobody can see or give
+const isInteractive = () => Boolean(process.stdin.isTTY && process.stdout.isTTY)
+
+// npm needs shell:true on Windows to resolve npm.cmd; a missing npm binary
+// (result.error, e.g. ENOENT) is surfaced distinctly from a clean non-zero exit
+function runCmd(bin, args, opts = {}) {
+  const result = spawnSync(bin, args, { shell: process.platform === 'win32', ...opts })
+  if (result.error) console.error(`    ${bin} not runnable: ${result.error.message}`)
+  return result
+}
+const runNpm = (args, opts = {}) => runCmd('npm', args, opts)
+const runNpx = (args, opts = {}) => runCmd('npx', args, opts)
+const runGit = (args, opts = {}) => runCmd('git', args, opts)
+
+// true only if THIS package is registered in npm's global node_modules —
+// never assume; ask npm directly, since global bin locations vary by system
+function isGloballyLinked() {
+  const result = runNpm(['root', '-g'], { encoding: 'utf8' })
+  const globalRoot = result.stdout?.trim()
+  return result.status === 0 && !!globalRoot && existsSync(join(globalRoot, PKG.name))
+}
+
+// true if user-scope install already ran — same isOurs stamp-check pattern as
+// uninstall, so we never nag about something already done (mirrors
+// isGloballyLinked/isCodegraphIndexed's own detect-before-offer discipline)
+function isSkillsInstalled() {
+  const base = join(homedir(), '.claude', 'skills')
+  return discover('skills').filter(it => !isLocal(it))
+    .some(it => isOurs(join(base, it.data.name, 'SKILL.md')))
+}
+
+async function cmdUninstall(target) {
+  if (!target) {
+    const items = [...discover('skills'), ...discover('agents')]
+    const base = join(homedir(), '.claude')
+    const removed = []
+    for (const it of items) {
+      const path = it.kind === 'agents'
+        ? join(base, 'agents', `${it.data.name}.md`)
+        : join(base, 'skills', it.data.name)
+      const probe = it.kind === 'agents' ? path : join(path, 'SKILL.md')
+      // only remove what we generated — never a user's own file sharing a name
+      if (isOurs(probe)) {
+        rmSync(path, { recursive: true })
+        removed.push(path)
+      }
+    }
+    if (stripManagedBlock(join(base, 'CLAUDE.md')))
+      removed.push(join(base, 'CLAUDE.md') + ' (managed block)')
+    for (const it of items.filter(it => it.kind === 'skills')) {
+      const dir = join(codexUserSkillsBase(), 'skills', it.data.name)
+      if (isOurs(join(dir, 'SKILL.md'))) { rmSync(dir, { recursive: true }); removed.push(dir) }
+    }
+    if (stripManagedBlock(join(codexHome(), 'AGENTS.md')))
+      removed.push(join(codexHome(), 'AGENTS.md') + ' (managed block)')
+    if (removeCodexProfile()) removed.push(`${codexConfigPath()} ([profiles.${CODEX_PROFILE}])`)
+    if (existsSync(manifestPath())) { rmSync(manifestPath()); removed.push(manifestPath()) }
+    console.log(`user scope ← ${base}`)
+    for (const r of removed) console.log(`    removed ${r}`)
+    if (!removed.length) console.log('    nothing to remove')
+
+    // mirror install's offer to link: if it's registered globally, offer to
+    // unlink it too — same explicit-confirmation pattern, same non-interactive fallback
+    if (isGloballyLinked()) {
+      const manualHint = `remove it yourself anytime:\n    npm uninstall -g ${PKG.name}`
+      if (!isInteractive()) {
+        console.log(`\n\`wuwei\`/\`ww\` are still registered globally — ${manualHint}`)
+      } else if (await promptYesNo(`\nAlso remove the global \`wuwei\`/\`ww\` commands (npm uninstall -g ${PKG.name})?`)) {
+        const result = runNpm(['uninstall', '-g', PKG.name], { stdio: 'inherit' })
+        console.log(result.status === 0
+          ? 'done — `wuwei`/`ww` are no longer global commands.'
+          : `\nthat failed${result.error ? '' : ` (exit ${result.status})`} — ${manualHint}`)
+      } else {
+        console.log(`kept — ${manualHint}`)
+      }
+    }
+    await offerCodegraphRemoval('user')
+    await offerScannerRemoval()
+    return
+  }
+  const dest = resolve(target)
+  const removed = []
+  for (const t of discoverTemplates()) {
+    const file = t.name === 'pr.md'
+      ? join(dest, '.github', 'PULL_REQUEST_TEMPLATE.md')
+      : join(dest, '.wuwei', 'templates', t.name)
+    if (existsSync(file) && readFileSync(file, 'utf8').includes('wuwei')) {
+      rmSync(file)
+      removed.push(file)
+    }
+  }
+  console.log(`repo scope ← ${dest}`)
+  for (const r of removed) console.log(`    removed ${r}`)
+  console.log('    kept .wuwei/STATE.md and streams/ — state is user data, delete manually if intended')
+  await offerCodegraphRemoval('repo', dest)
+}
+
+// ── status: read-only projection of .wuwei state, cross-checked ──────
+// STATE.md is an index maintained by skills and humans; streams/ is what
+// actually exists. The two drift. This renders the index against the
+// directories and flags every mismatch it can prove — and nothing it can't:
+// "done" is defined by e2e evidence, which is skill territory, so the
+// done/total column is reported as recorded, never recomputed here.
+function readStateRows(stateFile) {
+  if (!existsSync(stateFile)) return null
+  const rows = []
+  for (const line of readFileSync(stateFile, 'utf8').split('\n')) {
+    const t = line.trim()
+    if (!t.startsWith('|') || t === STATE_HEADER_LINE || isTableSeparatorLine(t)) continue
+    const cells = t.split('|').map(c => c.trim())
+    // split('|') on "| a | b |" yields ['', a, b, ''] — cells[1] is the first column
+    if (cells.length >= 6 && cells[1])
+      rows.push({ stream: cells[1], mode: cells[2], tracker: cells[3], done: cells[4], blocked: cells[5] })
+  }
+  return rows
+}
+
+function cmdStatus(target) {
+  const dest = resolve(target ?? process.cwd())
+  const wuweiDir = join(dest, '.wuwei')
+  if (!existsSync(wuweiDir)) {
+    console.log(`no .wuwei/ under ${dest} — not a wuwei project yet; \`wuwei init\` bootstraps one`)
+    return
+  }
+  const rows = readStateRows(join(wuweiDir, 'STATE.md')) ?? []
+  const streamsDir = join(wuweiDir, 'streams')
+  const dirs = existsSync(streamsDir)
+    ? readdirSync(streamsDir, { withFileTypes: true }).filter(d => d.isDirectory()).map(d => d.name)
+    : []
+  const warnings = []
+  const tracked = codegraphTrackedFiles(dest)
+  if (tracked.length)
+    warnings.push(`.codegraph/ is tracked by git (${tracked.length} file(s)) — every phase branch` +
+      ' rewrites the same index and every merge conflicts on binary.' +
+      '\n      git rm -r --cached .codegraph && echo .codegraph/ >> .gitignore')
+  const names = [...new Set([...rows.map(r => r.stream), ...dirs])].sort()
+
+  if (!names.length) {
+    console.log(`${wuweiDir}\n    no streams yet — the wuwei-plan-phases skill opens the first one`)
+    // repo-wide warnings do not depend on a stream existing — printing them
+    // only on the has-streams path would hide them for exactly the projects
+    // still being set up, which is when they are cheapest to act on
+    for (const w of warnings) console.log(`    ! ${w}`)
+    return
+  }
+
+  const table = []
+  for (const name of names) {
+    const row = rows.find(r => r.stream === name)
+    const dir = dirs.includes(name) ? join(streamsDir, name) : null
+    if (!dir) {
+      warnings.push(`${name}: listed in STATE.md but streams/${name}/ does not exist`)
+      table.push({ name, mode: row.mode, tracker: row.tracker, done: row.done, blocked: row.blocked, phases: '—', claims: '' })
+      continue
+    }
+    if (!row) warnings.push(`${name}: streams/${name}/ exists but has no STATE.md row`)
+
+    const spec = join(dir, 'SPEC.md')
+    if (!existsSync(spec)) warnings.push(`${name}: no SPEC.md`)
+    else if (!/^## Sign-off/m.test(readFileSync(spec, 'utf8')))
+      warnings.push(`${name}: SPEC.md has no \`## Sign-off\` — nothing should execute before sign-off`)
+    if (!existsSync(join(dir, 'ACCEPTANCE.md'))) warnings.push(`${name}: no ACCEPTANCE.md`)
+
+    const phasesDir = join(dir, 'phases')
+    const phaseFiles = existsSync(phasesDir)
+      ? readdirSync(phasesDir).filter(f => f.endsWith('.md')).sort()
+      : []
+    const claims = []
+    let untracked = 0
+    for (const f of phaseFiles) {
+      const { data } = parseFrontmatter(readFileSync(join(phasesDir, f), 'utf8'))
+      if (data['claimed-by'])
+        claims.push(`${f.replace(/\.md$/, '')} → ${data['claimed-by']}${data['claimed-at'] ? ` (${data['claimed-at']})` : ''}`)
+      if (!data['tracker-issue']) untracked++
+    }
+    // a linked stream whose phases carry no issue key gives execute-phase
+    // nothing to transition, and it fails silently — worth saying locally,
+    // which we can do without calling the tracker at all
+    const linked = row?.tracker && !['none', '-', '—', ''].includes(row.tracker)
+    if (linked && phaseFiles.length && untracked === phaseFiles.length)
+      warnings.push(`${name}: tracker '${row.tracker}' but no phase carries \`tracker-issue\` — transitions have nothing to act on`)
+    // the recorded total should match what's on disk; the done half is evidence-defined
+    const total = row?.done?.match(/^\s*\d+\s*\/\s*(\d+)\s*$/)?.[1]
+    if (total !== undefined && Number(total) !== phaseFiles.length)
+      warnings.push(`${name}: STATE.md says ${row.done} phases but streams/${name}/phases/ has ${phaseFiles.length} file(s)`)
+
+    table.push({
+      name, mode: row?.mode ?? '—', tracker: row?.tracker ?? '—',
+      done: row?.done ?? '—', blocked: row?.blocked ?? '—',
+      phases: String(phaseFiles.length), claims: claims.join('; '),
+    })
+  }
+
+  console.log(`${wuweiDir} — ${names.length} stream(s), ${warnings.length} warning(s)\n`)
+  const cols = ['stream', 'mode', 'tracker', 'done/total', 'files', 'blocked']
+  const data = table.map(t => [t.name, t.mode, t.tracker, t.done, t.phases, t.blocked])
+  const w = cols.map((c, i) => Math.max(c.length, ...data.map(r => (r[i] ?? '').length)))
+  console.log(('    ' + cols.map((c, i) => c.padEnd(w[i])).join('  ')).trimEnd())
+  for (const r of data)
+    console.log(('    ' + r.map((c, i) => (c ?? '').padEnd(w[i])).join('  ')).trimEnd())
+  for (const t of table) if (t.claims) console.log(`      ↳ ${t.name} claims: ${t.claims}`)
+  if (warnings.length) {
+    console.log()
+    for (const wmsg of warnings) console.log(`    ! ${wmsg}`)
+  }
+}
+
+// ── update ───────────────────────────────────────────────────────────
+// `install` with its eyes open: is a newer wuwei out, and what would applying
+// it change? Nothing is written without a yes.
+
+// the stamp is metadata, not content: compared without it, a stamp-format
+// change does not read as every artifact having changed
+const STAMP_PREFIX = '<!-- GENERATED BY wuwei'
+const withoutStamp = text => text.split('\n').filter(l => !l.startsWith(STAMP_PREFIX)).join('\n').trim()
+const stampedVersion = text => text.match(/GENERATED BY wuwei v(\S+)/)?.[1] ?? null
+
+// numeric x.y.z; a prerelease sorts below its release
+function newerThan(a, b) {
+  const parse = v => { const [core, pre] = v.split('-'); return [...core.split('.').map(Number), pre ? 0 : 1] }
+  const [x, y] = [parse(a), parse(b)]
+  for (let i = 0; i < x.length; i++) if (x[i] !== y[i]) return x[i] > y[i]
+  return false
+}
+
+function currentManagedBlock(file) {
+  if (!existsSync(file)) return null
+  const re = new RegExp(`${escapeRe(BLOCK_BEGIN)}[\\s\\S]*?${escapeRe(BLOCK_END)}`)
+  return readFileSync(file, 'utf8').match(re)?.[0] ?? null
+}
+
+// a clone is updated through git, the package through npm. A newer copy that
+// takes over runs the diff itself and this process exits with it
+async function updateSource(dry) {
+  const fromClone = existsSync(join(ROOT, '.git'))
+  console.log(`source: ${ROOT} (v${PKG.version}, ${fromClone ? 'git clone' : 'npm package'})`)
+  // after a pull or an upgrade the code in memory is the old one — the new
+  // copy runs the diff, so the preview is what the new version would write
+  const handOff = (bin, args) => {
+    const r = runCmd(bin, [...args, 'update', '--no-fetch', ...(dry ? ['--dry'] : [])], { stdio: 'inherit' })
+    process.exit(r.status ?? 1)
+  }
+  if (fromClone) {
+    const git = (args, opts) => runGit(['-C', ROOT, ...args], { encoding: 'utf8', ...opts })
+    const branch = git(['rev-parse', '--abbrev-ref', 'HEAD']).stdout?.trim()
+    const upstream = git(['rev-parse', '--abbrev-ref', '@{upstream}']).stdout?.trim()
+    if (!upstream) { console.log(`    ${branch} has no upstream — can't tell whether a newer version exists`); return }
+    git(['fetch', '--quiet'], { timeout: 30000 })
+    const behind = Number(git(['rev-list', '--count', `HEAD..${upstream}`]).stdout?.trim() || 0)
+    if (!behind) { console.log(`    up to date with ${upstream}`); return }
+    console.log(`    ${behind} commit(s) behind ${upstream}`)
+    const hint = `get them yourself anytime:\n        (cd ${ROOT} && git pull --ff-only)`
+    if (dry) console.log(`    [dry] not pulling — ${hint}`)
+    else if (git(['status', '--porcelain']).stdout?.trim()) console.log('    uncommitted changes here, not touching them — commit or stash, then re-run')
+    else if (!isInteractive()) console.log(`    ${hint}`)
+    else if (await promptYesNo(`Pull those ${behind} commit(s) first?`)) {
+      if (git(['pull', '--ff-only'], { stdio: 'inherit', encoding: undefined }).status !== 0) {
+        console.error('\n✗ pull failed — resolve it yourself, then re-run `wuwei update`')
+        process.exit(1)
+      }
+      handOff(process.execPath, [join(ROOT, 'bin', 'wuwei.js')])
+    }
+    console.log('    diffing against this checkout')
+    return
+  }
+  const view = runNpm(['view', PKG.name, 'version'], { encoding: 'utf8', timeout: 30000 })
+  const latest = view.status === 0 ? view.stdout.trim() : null
+  if (!latest) {
+    console.log(`    ${/E404/.test(view.stderr ?? '') ? `${PKG.name} is not on npm` : `can't reach npm for ${PKG.name}`} — diffing against this copy`)
+    return
+  }
+  if (newerThan(PKG.version, latest)) { console.log(`    ahead of npm (v${latest}) — a dev install; update never downgrades it`); return }
+  if (!newerThan(latest, PKG.version)) { console.log(`    up to date with npm (v${latest})`); return }
+  console.log(`    v${latest} is on npm`)
+  const global = isGloballyLinked()
+  const command = global ? `npm install -g ${PKG.name}@${latest}` : `npx ${PKG.name}@${latest} update`
+  if (dry) console.log(`    [dry] not upgrading — ${command}`)
+  else if (!isInteractive()) console.log(`    upgrade yourself anytime:\n        ${command}`)
+  else if (await promptYesNo(global ? `Upgrade the global install to v${latest} first?` : `Run v${latest} for this update?`)) {
+    if (!global) handOff('npx', ['--yes', `${PKG.name}@${latest}`])
+    if (runNpm(['install', '-g', `${PKG.name}@${latest}`], { stdio: 'inherit' }).status !== 0) {
+      console.error(`\n✗ upgrade failed — run \`${command}\` yourself, then \`wuwei update\``)
+      process.exit(1)
+    }
+    const root = runNpm(['root', '-g'], { encoding: 'utf8' }).stdout.trim()
+    handOff(process.execPath, [join(root, PKG.name, 'bin', 'wuwei.js')])
+  }
+  console.log(`    diffing against v${PKG.version}`)
+}
+
+// install's targets — the same artifact lists install writes — against disk
+function updateRows() {
+  const items = loadValidated().filter(it => !isLocal(it))
+  const rows = []
+  let unchanged = 0
+  const stamps = new Set()
+  const manifest = readManifest()
+  // differs from the new version: an upstream change — unless it also differs from
+  // what install wrote, which means you edited it. No record → can't tell
+  const differs = (key, disk) => manifest?.files?.[key] && sha256(disk) !== manifest.files[key]
+    ? ['edited', 'edited since install — backed up, then overwritten'] : ['changed', '']
+  const compare = artifacts => {
+    for (const a of artifacts) {
+      const label = a.file.slice(homedir().length + 1)
+      if (!existsSync(a.file)) { rows.push(['new', label, '']); continue }
+      const disk = readFileSync(a.file, 'utf8')
+      if (!isOurs(a.file)) rows.push(['conflict', label, 'not wuwei-generated — applying overwrites it'])
+      else if (withoutStamp(disk) !== withoutStamp(a.content)) { const [state, note] = differs(a.file, disk); rows.push([state, label, note]) }
+      else unchanged++
+      const v = stampedVersion(disk); if (v) stamps.add(v)
+    }
+    // a stamped skill's references/ is regenerated whole: anything not produced again goes
+    const produced = new Set(artifacts.map(a => a.file))
+    for (const a of artifacts.filter(a => a.file.endsWith('SKILL.md') && isOurs(a.file))) {
+      const refDir = join(dirname(a.file), 'references')
+      if (!existsSync(refDir)) continue
+      for (const f of readdirSync(refDir)) if (!produced.has(join(refDir, f)))
+        rows.push(['stale', join(refDir, f).slice(homedir().length + 1), 'no longer in source — removed'])
+    }
+  }
+  const compareBlock = (file, rules) => {
+    const want = rules.length ? rulesBlock(rules) : null
+    const have = currentManagedBlock(file)
+    const label = `${file.slice(homedir().length + 1)} (rules block)`
+    if (want === have) { if (want) unchanged++; return }
+    const [state, note] = !have ? ['new', ''] : !want ? ['stale', 'no rules left in source — stripped'] : differs(`${file}#rules`, have)
+    rows.push([state, label, note])
+  }
+  const staleDirs = (base, skills, agents) => {
+    for (const p of sweepStale(base, skills, agents, true))
+      rows.push(['stale', p.slice(homedir().length + 1), 'no longer in source — removed'])
+  }
+
+  const claudeBase = join(homedir(), '.claude')
+  const claude = claudeArtifacts(items, claudeBase)
+  compare(claude)
+  staleDirs(claudeBase, namesUnder(claude, claudeBase, 'skills'), namesUnder(claude, claudeBase, 'agents'))
+  compareBlock(join(claudeBase, 'CLAUDE.md'), items.filter(i => targeted(i, 'claude-code') && isRule(i)))
+
+  if (existsSync(codexHome())) {
+    const picked = items.filter(it => it.kind === 'skills' && targeted(it, 'codex'))
+    const lazy = picked.filter(it => !isRule(it))
+    const codex = codexArtifacts(lazy, codexUserSkillsBase(), items)
+    compare(codex)
+    staleDirs(codexUserSkillsBase(), new Set(lazy.map(it => it.data.name)), new Set())
+    compareBlock(join(codexHome(), 'AGENTS.md'), picked.filter(isRule))
+  }
+  return { rows, unchanged, stamps: [...stamps], manifest }
+}
+
+// CHANGELOG.md's sections after `since`, up to this copy — one "## <version>" each
+function changelogSince(since) {
+  const file = join(ROOT, 'CHANGELOG.md')
+  if (!existsSync(file)) return null
+  const picked = readFileSync(file, 'utf8').split(/^(?=## )/m).filter(sec => {
+    const v = sec.match(/^## v?(\d+\.\d+\.\d+\S*)/)?.[1]
+    return v && newerThan(v, since) && !newerThan(v, PKG.version)
+  })
+  return picked.length ? picked.join('').trim() : null
+}
+
+// ── update check: GSD's SessionStart hook + statusline, without either — the
+// skills call `wuwei` all day, so any command is where a newer version gets
+// mentioned (stderr, at most hourly). The npm query runs once a day in a
+// detached child, never on a clone (git is its channel) or in CI
+const updateCachePath = () => join(homedir(), '.cache', 'wuwei', 'update-check.json')
+function noticeUpdate(cmd) {
+  if (['update', '__update-check', '-v', '--version', 'version'].includes(cmd) || process.env.CI || process.env.WUWEI_NO_UPDATE_CHECK || existsSync(join(ROOT, '.git'))) return
+  let cache = null
+  try { cache = JSON.parse(readFileSync(updateCachePath(), 'utf8')) } catch {}
+  if (cache?.latest && newerThan(cache.latest, PKG.version) && Date.now() - (cache.noticed ?? 0) > 3600000) {
+    console.error(`⬆ wuwei v${cache.latest} is out (this is v${PKG.version}) — wuwei update`)
+    try { writeFileSync(updateCachePath(), JSON.stringify({ ...cache, noticed: Date.now() })) } catch {}
+  }
+  if (cache && Date.now() - cache.checked < 86400000) return
+  try { spawn(process.execPath, [fileURLToPath(import.meta.url), '__update-check'], { detached: true, stdio: 'ignore' }).unref() } catch {}
+}
+function cmdUpdateCheck() {
+  const view = runNpm(['view', PKG.name, 'version'], { encoding: 'utf8', timeout: 30000 })
+  mkdirSync(dirname(updateCachePath()), { recursive: true })
+  writeFileSync(updateCachePath(), JSON.stringify({ checked: Date.now(), latest: view.status === 0 ? view.stdout.trim() : null }))
+}
+
+async function cmdUpdate(dry, noFetch) {
+  if (!noFetch) await updateSource(dry)
+  const { rows, unchanged, stamps, manifest } = updateRows()
+  console.log(`\ninstalled: ${stamps.length ? stamps.map(v => `v${v}`).join(', ') : 'unstamped or not installed'} · this copy: v${PKG.version}`)
+  // what changed between the installed version and this one, before what it would write
+  const since = stamps.filter(v => newerThan(PKG.version, v)).sort((a, b) => newerThan(a, b) ? 1 : -1)[0]
+  if (since) {
+    const notes = changelogSince(since)
+    if (notes) console.log(`\nwhat's new since v${since}:\n\n${notes}`)
+  }
+  if (!existsSync(codexHome())) console.log(`codex: ${codexHome()} not found — not compared`)
+  if (!rows.length) {
+    console.log(`\n✓ already up to date — ${unchanged} artifact(s) match exactly`)
+    return
+  }
+  const width = Math.max(...rows.map(r => r[1].length))
+  console.log()
+  for (const [state, label, note] of rows)
+    console.log(`    ${state.padEnd(9)} ${note ? label.padEnd(width) + '  ' + note : label}`)
+  if (unchanged) console.log(`    ${''.padEnd(9)} …and ${unchanged} unchanged`)
+  // what applying would overwrite that is yours: edits since install, files wuwei
+  // didn't write, and — with no install record to tell — every changed file
+  const keep = rows.filter(([s]) => s === 'edited' || s === 'conflict' || (s === 'changed' && !manifest))
+  if (!manifest && rows.some(([s]) => s === 'changed'))
+    console.log(`\nno install record (${manifestPath()}) — installed before wuwei kept one, so an edit you made can't be told from an upstream change; applying backs up every changed file first`)
+  const hint = keep.length
+    ? `${keep.length} file(s) of yours would be overwritten — run \`wuwei update\` in a terminal, which backs them up first (\`install\` does not)`
+    : `apply it yourself anytime:\n    ${existsSync(join(ROOT, '.git')) ? `node ${join(ROOT, 'bin', 'wuwei.js')}` : `npx ${PKG.name}@${PKG.version}`} install`
+  if (dry) console.log(`\n[dry] nothing written — ${hint}`)
+  else if (!isInteractive()) console.log(`\nnon-interactive, nothing written — ${hint}`)
+  else if (await promptYesNo(`\nApply these ${rows.length} change(s)?${keep.length ? ` ${keep.length} file(s) of yours are backed up first.` : ''}`)) {
+    if (keep.length) {
+      const dir = join(wuweiHome(), 'local-patches', new Date().toISOString().replace(/[:.]/g, '-'))
+      for (const [, label] of keep) {
+        const rel = label.replace(/ \(rules block\)$/, ''), from = join(homedir(), rel)
+        if (!existsSync(from)) continue
+        mkdirSync(dirname(join(dir, rel)), { recursive: true })
+        writeFileSync(join(dir, rel), readFileSync(from))
+      }
+      console.log(`\nbacked up ${keep.length} file(s) → ${dir}`)
+    }
+    console.log()
+    await cmdInstall(undefined, false)
+    rmSync(updateCachePath(), { force: true })
+    console.log('\nrestart Claude Code and Codex sessions — a running session keeps the skills it loaded')
+  }
+  else console.log(`skipped — ${hint}`)
+  console.log('\nrepo scope (.wuwei/templates/, the PR template) updates per project: `wuwei init <path>`')
+}
+
+// ── claim: wuwei-execute-phase step 1's mechanical half ──────────────
+// picks what is eligible, writes the claim, cuts the phase branch from the
+// stream branch and pushes it. Judgment stays with the skill: syncing the
+// stream branch and re-running its green e2e, whether a stale claim is taken
+// over, and the tracker
+const phaseNo = s => String(s).match(/(?:^|\/)(\d+)(?:-|\.md|$)/)?.[1] ?? null
+
+// three labelled fields under SPEC.md ## Sign-off (plan-phases step 8)
+function signOffField(spec, label) {
+  const section = spec.split(/^## Sign-off\s*$/m)[1]?.split(/^## /m)[0] ?? ''
+  const line = section.split('\n').find(l => new RegExp(label, 'i').test(l))
+  if (!line) return null
+  return line.match(/`([^`]+)`/)?.[1] ?? line.split(/[:|]/).map(x => x.trim()).filter(Boolean).at(-1) ?? null
+}
+
+function setFrontmatter(text, fields) {
+  const end = text.startsWith('---') ? text.indexOf('\n---', 3) : -1
+  if (end === -1) return `---\n${Object.entries(fields).map(([k, v]) => `${k}: ${v}`).join('\n')}\n---\n\n${text}`
+  let head = text.slice(0, end)
+  for (const [k, v] of Object.entries(fields)) {
+    const re = new RegExp(`^${k}:.*$`, 'm')
+    head = re.test(head) ? head.replace(re, `${k}: ${v}`) : `${head}\n${k}: ${v}`
+  }
+  return head + text.slice(end)
+}
+
+function claimPhases(dest, stream) {
+  const git = (args, opts) => quiet('git', ['-C', dest, ...args], opts)
+  const dir = join(dest, '.wuwei', 'streams', stream)
+  const spec = existsSync(join(dir, 'SPEC.md')) ? readFileSync(join(dir, 'SPEC.md'), 'utf8') : ''
+  const streamBranch = signOffField(spec, 'stream branch')
+  const integration = signOffField(spec, 'integration branch')
+  if (!streamBranch) return { error: `${stream}: no stream branch under SPEC.md ## Sign-off — planning owes it (wuwei-plan-phases step 8)` }
+  // phase branches sit beside the stream branch, never under it: git cannot
+  // hold `x` and `x/01-…` at once, since a ref name is also a path
+  if (!/\/base$/.test(streamBranch))
+    return { error: `${stream}: stream branch '${streamBranch}' cannot have phase branches beside it — name it '${streamBranch}/base' (wuwei-plan-phases step 8): git refuses '${streamBranch}/NN-…' while '${streamBranch}' exists` }
+  const prefix = streamBranch.replace(/\/base$/, '')
+  git(['fetch', '--quiet', 'origin'], { timeout: 60000 })
+  const remote = `origin/${streamBranch}`
+  if (!ok(git(['rev-parse', '--verify', '--quiet', remote])))
+    return { error: `${remote} does not exist — the stream branch was recorded but never pushed` }
+  const behind = integration
+    ? Number(git(['rev-list', '--count', `${remote}..origin/${integration}`]).stdout?.trim() || NaN) : NaN
+  // the phase files as the stream branch has them — that is what every session reads
+  const files = git(['ls-tree', '--name-only', `${remote}`, `.wuwei/streams/${stream}/phases/`]).stdout
+    ?.split('\n').filter(f => f.endsWith('.md')).sort() ?? []
+  const phases = files.map(f => {
+    const name = f.split('/').pop().replace(/\.md$/, '')
+    const { data } = parseFrontmatter(git(['show', `${remote}:${f}`]).stdout ?? '')
+    const branch = `${prefix}/${name}`
+    const onRemote = ok(git(['rev-parse', '--verify', '--quiet', `origin/${branch}`]))
+    // merged — three traces, strongest first: the pushed branch is inside the
+    // stream branch; or the branch is gone and the claim commit (written only
+    // on a phase branch) reached the stream branch, which a squash merge leaves
+    // too; or a merge commit names the branch
+    const how = onRemote
+      ? (git(['merge-base', '--is-ancestor', `origin/${branch}`, remote]).status === 0 ? 'branch inside the stream branch' : null)
+      : data['claimed-by'] ? 'its claim reached the stream branch'
+      : git(['log', '--merges', '--oneline', '-1', '--fixed-strings', `--grep=${branch}`, remote]).stdout.trim() ? 'a merge commit names it'
+      : null
+    const merged = Boolean(how)
+    // a claim lives on the pushed phase branch: read it there first
+    const claimed = onRemote ? parseFrontmatter(git(['show', `origin/${branch}:${f}`]).stdout ?? '').data : data
+    return {
+      name, no: phaseNo(name), file: f, branch, onRemote, merged, how,
+      dependsOn: [].concat(data['depends-on'] ?? []).map(phaseNo).filter(Boolean),
+      claimedBy: claimed['claimed-by'] || null, claimedAt: claimed['claimed-at'] || null,
+      review: data.review ?? 'auto', tracker: data['tracker-issue'] ?? null,
+    }
+  })
+  for (const p of phases) {
+    const missing = p.dependsOn.filter(d => !phases.some(q => q.no === d))
+    const open = p.dependsOn.filter(d => phases.some(q => q.no === d && !q.merged))
+    p.state = p.merged ? `merged (${p.how})`
+      : missing.length ? `blocked — depends-on ${missing.join(', ')} is not a phase`
+      : open.length ? `waiting on ${open.join(', ')}`
+      : p.claimedBy || p.onRemote ? `claimed by ${p.claimedBy ?? '?'}${p.claimedAt ? ` at ${p.claimedAt}` : ''}`
+      : 'ready'
+  }
+  return { streamBranch, integration, remote, behind, phases }
+}
+
+// SPEC ## Sign-off's model policy: `inherit` (default, also when the line is
+// absent) or `roles`, for the review tier. Implementation is not on the menu:
+// it is always wuwei-implementer at modelRoles.implementation's tier
+function modelPolicy(spec) {
+  const raw = (signOffField(spec ?? '', 'model policy') ?? 'inherit').trim()
+  const v = (raw.match(/\breview\s*[=:]\s*(\w+)/i)?.[1] ?? raw).toLowerCase()
+  const error = /\bimplementation\b/i.test(raw)
+    ? `model policy '${raw}': implementation is fixed (wuwei-implementer, ${CONFIG.modelRoles?.implementation?.model} / ${CONFIG.modelRoles?.implementation?.effort}) — the policy is inherit or roles, for review`
+    : !['inherit', 'roles'].includes(v) ? `model policy '${raw}': inherit or roles` : null
+  // Codex, when it runs execute: `codex: <model> / <effort>` — the session it is started as
+  const cx = (spec ?? '').split(/^## Sign-off\s*$/m)[1]?.split(/^## /m)[0]?.split('\n').find(l => /^[-*|\s]*codex\s*[:|]/i.test(l))
+  const cv = cx ? (cx.match(/`([^`]+)`/)?.[1] ?? cx.split(/[:|]/).map(x => x.trim()).filter(Boolean).at(-1)) : null
+  const cm = cv?.match(/^(\S+)\s*\/\s*(\S+)$/)
+  const codex = cm ? { model: cm[1], effort: cm[2] } : null
+  const codexError = cx && !cm ? `codex '${cv}': write it as <model> / <effort>`
+    : codex && !CODEX_EFFORTS.includes(codex.effort) ? `codex effort '${codex.effort}': one of ${CODEX_EFFORTS.join('|')}` : null
+  return { raw, tiers: { review: v }, error: error ?? codexError, codex }
+}
+
+function codexLine(want) {
+  const { profile } = codexProfile()
+  if (!want) return profile
+    ? `codex                       start it with \`codex --profile ${CODEX_PROFILE}\` (${profile.model} / ${profile.effort}) — none recorded under ## Sign-off`
+    : 'codex                       the model Codex was started with — no `codex:` under ## Sign-off'
+  return profile?.model === want.model && profile?.effort === want.effort
+    ? `codex                       start it with \`codex --profile ${CODEX_PROFILE}\` (${want.model} / ${want.effort})`
+    : `codex                       start it with \`${codexLaunch(want.model, want.effort)}\`${profile ? ` — profile ${CODEX_PROFILE} is ${profile.model} / ${profile.effort}, not what ## Sign-off says` : ''}`
+}
+
+// what step 2 and step 5 dispatch, from the policy and wuwei.config.json's
+// modelRoles — printed, so the tier is read off the screen, not remembered
+function dispatchLines(policy) {
+  const roles = CONFIG.modelRoles ?? {}
+  const impl = roles.implementation ?? {}, rev = roles.review ?? {}
+  return [
+    `implement (step 2)          subagent_type ${impl.agent}, no model or effort on the call — ${impl.model} / ${impl.effort}, pinned in its agent file`,
+    policy.tiers.review === 'roles'
+      ? `${(rev.lenses ?? []).map(l => l.replace(/^wuwei-review-/, 'review:')).join(', ')} (step 5)  model: ${rev.model} — effort from the agent file`
+      : `${(rev.lenses ?? []).map(l => l.replace(/^wuwei-review-/, 'review:')).join(', ')} (step 5)  no model — the session's model; effort from the agent file`,
+    'other lenses                no model — the session\'s; wuwei-security-auditor stays fable / high (pinned)',
+    'inline (no subagents, Codex)  the session\'s, whatever the policy — say so in the round record',
+    codexLine(policy.codex),
+  ]
+}
+
+function cmdClaim(argv) {
+  const flag = name => { const i = argv.indexOf(name); return i === -1 ? null : argv[i + 1] }
+  const positional = argv.filter((a, i) => !a.startsWith('--') && argv[i - 1] !== '--by')
+  const dest = process.cwd()
+  const streamsDir = join(dest, '.wuwei', 'streams')
+  const streams = existsSync(streamsDir) ? readdirSync(streamsDir, { withFileTypes: true }).filter(d => d.isDirectory()).map(d => d.name) : []
+  let [stream, phaseArg] = positional
+  if (stream && !streams.includes(stream) && streams.length === 1 && phaseNo(stream)) [stream, phaseArg] = [streams[0], stream]
+  stream ??= streams.length === 1 ? streams[0] : null
+  if (!stream || !streams.includes(stream)) {
+    console.error(`✗ name a stream: ${streams.join(', ') || 'none under .wuwei/streams/'}`)
+    process.exit(1)
+  }
+  const r = claimPhases(dest, stream)
+  if (r.error) { console.error(`✗ ${r.error}`); process.exit(1) }
+  const sync = !r.integration ? 'no integration branch under ## Sign-off — cannot tell if the stream branch is current'
+    : r.behind === 0 ? `current with origin/${r.integration}`
+    : `${r.behind} commit(s) behind origin/${r.integration}`
+  console.log(`stream ${stream} · ${r.remote} · ${sync}\n`)
+  const w = Math.max(...r.phases.map(p => p.name.length))
+  for (const p of r.phases)
+    console.log(`  ${p.name.padEnd(w)}  ${p.state}${p.review === 'human' ? '   ← review: human' : ''}`)
+
+  const policy = modelPolicy(existsSync(join(streamsDir, stream, 'SPEC.md')) ? readFileSync(join(streamsDir, stream, 'SPEC.md'), 'utf8') : '')
+  if (policy.error) { console.error(`\n✗ ${policy.error} — fix ## Sign-off (wuwei plan-check)`); process.exit(1) }
+  console.log(`\ndispatch · model policy: ${policy.raw}\n${dispatchLines(policy).map(l => `  ${l}`).join('\n')}`)
+
+  if (!phaseArg) {
+    const ready = r.phases.filter(p => p.state === 'ready')
+    console.log(ready.length ? `\nclaim one: wuwei claim ${stream} ${ready[0].no}` : '\nnothing ready to claim')
+    return
+  }
+  const p = r.phases.find(x => x.no === phaseNo(phaseArg) || x.name === phaseArg)
+  if (!p) { console.error(`✗ ${phaseArg} is not a phase of ${stream}`); process.exit(1) }
+  const takeOver = argv.includes('--take-over')
+  const refuse = msg => { console.error(`\n✗ ${p.name}: ${msg}`); process.exit(1) }
+  if (p.merged) refuse('already merged')
+  if (p.state.startsWith('waiting') || p.state.startsWith('blocked')) refuse(p.state)
+  if ((p.claimedBy || p.onRemote) && !takeOver)
+    refuse(`${p.state} — taking it over is a decision: re-run with --take-over, which records it in the phase file`)
+  // never cut a phase branch off a stream branch that has not caught up — the
+  // skill syncs it and re-runs its green e2e first (execute step 1)
+  if (r.behind !== 0) refuse(r.integration
+    ? `the stream branch is ${r.behind} commit(s) behind origin/${r.integration} — sync it and re-run its green e2e first`
+    : 'no integration branch recorded, so the stream branch cannot be checked current — record it under ## Sign-off')
+  if (quiet('git', ['status', '--porcelain', '--untracked-files=no']).stdout.trim())
+    refuse('uncommitted changes in this checkout — commit or stash first')
+
+  const by = flag('--by') ?? `${process.env.USER || process.env.USERNAME || 'unknown'}@${(quiet('hostname', []).stdout || 'host').trim()}`
+  const at = new Date().toISOString().replace(/\.\d+Z$/, 'Z')
+  const dry = argv.includes('--dry')
+  const steps = [
+    p.onRemote ? `check out ${p.branch} from origin (taking over)` : `cut ${p.branch} from ${r.remote}`,
+    `claimed-by: ${by} · claimed-at: ${at}${takeOver ? ' · takeover recorded' : ''}`,
+    `commit and push ${p.branch}`,
+  ]
+  console.log(`\n${dry ? '[dry] ' : ''}claim ${p.name}:\n${steps.map(s => `    ${s}`).join('\n')}`)
+  if (dry) return
+  const run = (args, what) => { const x = quiet('git', args); if (!ok(x)) refuse(`${what} failed: ${firstLine(x.stderr)}`) }
+  run(['checkout', '-B', p.branch, p.onRemote ? `origin/${p.branch}` : r.remote], 'checkout')
+  const file = join(dest, p.file)
+  let text = readFileSync(file, 'utf8')
+  text = setFrontmatter(text, { 'claimed-by': by, 'claimed-at': at })
+  if (takeOver) text = text.trimEnd() + `\n\n> Claim taken over ${at} by ${by} from ${p.claimedBy ?? 'an unrecorded claim'}${p.claimedAt ? ` (claimed ${p.claimedAt})` : ''}.\n`
+  writeFileSync(file, text)
+  run(['add', p.file], 'git add')
+  run(['commit', '-q', '-m', `claim(${stream}): ${p.name}${takeOver ? ' — taken over' : ''}`], 'commit')
+  run(['push', '-q', '-u', 'origin', p.branch], 'push')
+  console.log(`\n✓ claimed ${p.name} on ${p.branch}${p.tracker ? ` · tracker ${p.tracker}: move it under step 1's write rule` : ''}`)
+}
+
+// ── plan-check: wuwei-plan-phases step 11's checkable half ───────────
+// read-only. What needs judgment — the phases matching the delivery
+// strategy, each design reconciling with SPEC's target — stays in the skill
+function cycleIn(edges) {
+  // edges: Map node → [deps]; returns one cycle as a path, or null
+  const state = new Map()
+  const visit = (n, path) => {
+    if (state.get(n) === 1) return [...path.slice(path.indexOf(n)), n]
+    if (state.get(n) === 2) return null
+    state.set(n, 1)
+    for (const d of edges.get(n) ?? []) { const c = visit(d, [...path, n]); if (c) return c }
+    state.set(n, 2)
+    return null
+  }
+  for (const n of edges.keys()) { const c = visit(n, []); if (c) return c }
+  return null
+}
+
+const TASK_LINE = /^\s*[-*]\s*\[[ xX]\]\s*\**`?([A-Za-z]*\d+[a-z]?)`?\**[\s.:)—-]/
+const listOf = v => String(v ?? '').replace(/[[\]]/g, '').split(/[,\s]+/).map(x => x.replace(/[`*]/g, '')).filter(Boolean)
+
+// ACCEPTANCE.md's ## Verify: the pages whose data states wuwei verify answers,
+// each bound to the phase that builds it — "- <page>: <route> · phase: NN".
+// null when the section is missing; none when it says `verify: none`
+function verifyItems(acceptance) {
+  if (/^\s*verify:\s*none\b/im.test(acceptance)) return { none: true, items: [] }
+  const sec = acceptance.split(/^## Verify\s*$/m)[1]?.split(/^## /m)[0]
+  if (sec == null) return null
+  const items = sec.split('\n').filter(l => /^\s*[-*]\s+\S/.test(l)).map(l => ({
+    line: l.trim(), name: l.match(/^\s*[-*]\s+`?([\w.-]+)`?\s*:/)?.[1] ?? null, phase: l.match(/phase:?\s*`?(\d+)/i)?.[1] ?? null,
+  }))
+  return { none: false, items }
+}
+
+function cmdPlanCheck(argv) {
+  const dest = process.cwd()
+  const streams = existsSync(join(dest, '.wuwei', 'streams'))
+    ? readdirSync(join(dest, '.wuwei', 'streams'), { withFileTypes: true }).filter(d => d.isDirectory()).map(d => d.name) : []
+  const stream = argv.find(a => !a.startsWith('--')) ?? (streams.length === 1 ? streams[0] : null)
+  if (!stream || !streams.includes(stream)) { console.error(`✗ name a stream: ${streams.join(', ') || 'none under .wuwei/streams/'}`); process.exit(1) }
+  const dir = join(dest, '.wuwei', 'streams', stream)
+  const errs = [], warns = []
+  const read = f => existsSync(f) ? readFileSync(f, 'utf8') : null
+  const spec = read(join(dir, 'SPEC.md'))
+  if (!spec) errs.push('SPEC.md missing')
+  const acceptance = read(join(dir, 'ACCEPTANCE.md'))
+  if (!acceptance) errs.push('ACCEPTANCE.md missing')
+
+  // sign-off: the fields execute reads, and nothing open under auto
+  const signOff = spec?.split(/^## Sign-off\s*$/m)[1]?.split(/^## /m)[0] ?? null
+  if (spec && signOff == null) errs.push('SPEC.md has no ## Sign-off')
+  const fields = [['approved', /approv/i], ['delivery strategy', /delivery|strategy|mvp-first|feature-complete/i], ['drive mode', /\b(drive )?mode\b/i],
+    ['tracker', /tracker/i], ['stream branch', /stream branch/i], ['integration branch', /integration branch/i], ['starting ref', /cut from|starting ref|ref it was cut/i]]
+  const signLines = (signOff ?? '').split('\n')
+  for (const [name, re] of fields) if (signOff != null && !signLines.some(l => re.test(l))) errs.push(`## Sign-off: no ${name}`)
+  const streamBranch = spec ? signOffField(spec, 'stream branch') : null
+  if (streamBranch && !/\/base$/.test(streamBranch)) errs.push(`stream branch '${streamBranch}' must end in /base — git refuses phase branches under it (step 8)`)
+  if (streamBranch && quiet('git', ['remote']).stdout.trim()) {
+    const r = quiet('git', ['ls-remote', '--heads', 'origin', streamBranch], { timeout: 30000 })
+    if (ok(r) && !r.stdout.trim()) errs.push(`stream branch ${streamBranch} is not on origin — push it, or the first phase PR has no base`)
+  }
+  const open = signLines.filter(l => /:\s*(\?|tbd|todo|pending|—|-|<[^>]+>)?\s*$/i.test(l) && /\w/.test(l.split(':')[0]) && /^\s*[-*|]/.test(l))
+  const auto = signLines.some(l => /\bmode\b[^|\n]*\bauto\b/i.test(l))
+  if (auto && open.length) errs.push(`drive mode is auto while ## Sign-off still has open fields: ${open.map(l => l.trim()).join(' / ')} — a partly answered sign-off stays manual`)
+  const policy = spec ? modelPolicy(spec) : null
+  if (policy?.error) errs.push(`## Sign-off: ${policy.error}`)
+  const tracker = signLines.find(l => /tracker/i.test(l)) ?? ''
+  const linked = tracker && !/\bnone\b/i.test(tracker)
+
+  // phases: depends-on resolves and is acyclic, at both levels
+  const phasesDir = join(dir, 'phases')
+  const files = existsSync(phasesDir) ? readdirSync(phasesDir).filter(f => f.endsWith('.md')).sort() : []
+  if (!files.length) errs.push('no phases/*.md')
+  const phaseEdges = new Map()
+  for (const f of files) {
+    const text = readFileSync(join(phasesDir, f), 'utf8')
+    const { data, body } = parseFrontmatter(text)
+    const no = phaseNo(f)
+    const deps = listOf(data['depends-on']).map(phaseNo).filter(Boolean)
+    phaseEdges.set(no, deps)
+    for (const d of deps) if (!files.some(g => phaseNo(g) === d)) errs.push(`${f}: depends-on ${d} is not a phase`)
+    if (linked && !data['tracker-issue']) errs.push(`${f}: no tracker-issue — the tracker is linked, so execute has nothing to transition`)
+    if (!/^##\s+Intended design/m.test(body) && !/intended design/i.test(body))
+      errs.push(`${f}: no ## Intended design, and no line saying why it needs none`)
+
+    // tasks
+    const tasks = new Map()
+    for (const line of body.split('\n')) {
+      const m = line.match(TASK_LINE)
+      if (!m) continue
+      const dm = line.match(/depends-on:?\s*([^)\]]+)/i)
+      tasks.set(m[1], dm ? listOf(dm[1]).filter(x => /\d/.test(x)) : [])
+    }
+    for (const [t, deps] of tasks) for (const d of deps)
+      if (!tasks.has(d)) errs.push(`${f}: task ${t} depends-on ${d}, not a task in this phase`)
+    const tc = cycleIn(tasks)
+    if (tc) errs.push(`${f}: task dependency cycle ${tc.join(' → ')}`)
+    // the diagram drawn from those fields
+    const edges = [...tasks].flatMap(([t, deps]) => deps.map(d => `${d}>${t}`))
+    const blocks = [...body.matchAll(/```mermaid\n([\s\S]*?)```/g)].map(m => m[1])
+    const drawn = new Set(blocks.flatMap(b => [...b.matchAll(/\b([A-Za-z]*\d+[a-z]?)\b[^\n]*?-->(?:\|[^|]*\|)?\s*([A-Za-z]*\d+[a-z]?)\b/g)])
+      .map(m => `${m[1]}>${m[2]}`).filter(e => e.split('>').every(x => tasks.has(x))))
+    if (tasks.size > 1 && !blocks.length) warns.push(`${f}: ${tasks.size} tasks and no mermaid task diagram`)
+    else if (blocks.length && edges.length) {
+      const missing = edges.filter(e => !drawn.has(e)), extra = [...drawn].filter(e => !edges.includes(e))
+      if (missing.length || extra.length)
+        errs.push(`${f}: task diagram ≠ depends-on — ${missing.length ? `not drawn: ${missing.join(', ').replace(/>/g, '→')}` : ''}${missing.length && extra.length ? '; ' : ''}${extra.length ? `drawn but not in the fields: ${extra.join(', ').replace(/>/g, '→')}` : ''}`)
+    }
+  }
+  const pc = cycleIn(phaseEdges)
+  if (pc) errs.push(`phase dependency cycle ${pc.join(' → ')}`)
+
+  // ## Verify: every page's data states bound to a phase, or said to be none
+  const vi = acceptance ? verifyItems(acceptance) : { none: true, items: [] }
+  if (!vi) errs.push('ACCEPTANCE.md has no ## Verify, and no `verify: none` — say which pages wuwei verify answers for (step 6)')
+  else {
+    const seen = new Set()
+    for (const it of vi.items) {
+      if (!it.name) errs.push(`## Verify: "${it.line}" names no page — "- <page>: <route> · phase: NN"`)
+      else if (seen.has(it.name)) errs.push(`## Verify: page ${it.name} listed twice`)
+      else seen.add(it.name)
+      if (!it.phase) errs.push(`## Verify: "${it.line}" is bound to no phase`)
+      else if (!files.some(f => Number(phaseNo(f)) === Number(it.phase))) errs.push(`## Verify: ${it.name ?? it.line} is bound to phase ${it.phase}, which is not a phase`)
+    }
+    if (!vi.none && !vi.items.length) errs.push('## Verify is empty — list the pages, or write `verify: none`')
+  }
+  // no harness is not a reason for UAT (step 6): some phase has to add one
+  const pkgDeps = (() => { try { const j = JSON.parse(readFileSync(join(dest, 'package.json'), 'utf8')); return Object.keys({ ...j.dependencies, ...j.devDependencies }) } catch { return [] } })()
+  const harness = readdirSync(dest).some(f => /^(playwright|cypress)\.config\.|^wdio\.conf\./.test(f))
+    || pkgDeps.some(d => /^(@playwright\/test|playwright|cypress|webdriverio|puppeteer|detox)$/.test(d))
+    // mobile: Maestro flows, Flutter's patrol/integration_test, an XCUITest target, Espresso
+    || existsSync(join(dest, '.maestro')) || /^\s*(patrol|integration_test):/m.test(read(join(dest, 'pubspec.yaml')) ?? '')
+    || readdirSync(dest).some(f => /UITests$/.test(f)) || existsSync(join(dest, 'app', 'src', 'androidTest'))
+  if (acceptance && /\be2e\b/i.test(acceptance) && !harness)
+    warns.push('ACCEPTANCE.md binds e2e, and no harness was found (playwright/cypress/wdio config, one in package.json, .maestro/, patrol, *UITests, androidTest) — the first phase with a bound item adds it as its first task')
+
+  // STATE.md agrees with phases/
+  const row = (readStateRows(join(dest, '.wuwei', 'STATE.md')) ?? []).find(r => r.stream === stream)
+  if (!row) errs.push('STATE.md has no row for this stream')
+  else {
+    const total = row.done?.match(/\/\s*(\d+)/)?.[1]
+    if (total && Number(total) !== files.length) errs.push(`STATE.md says ${row.done}, phases/ has ${files.length}`)
+  }
+
+  console.log(`plan-check ${stream} · ${files.length} phase(s)`)
+  for (const w of warns) console.log(`! ${w}`)
+  for (const e of errs) console.log(`✗ ${e}`)
+  console.log(errs.length ? `\n${errs.length} error(s)` : '\n✓ the checkable half of step 11 holds — the judgment half is still yours: phases match the strategy, designs slice the target, mermaid renders')
+  process.exit(errs.length ? 1 : 0)
+}
+
+// ── worktree: one throwaway tree per lens, named so no two can share it ─
+// a mutation another lens reverts under you reads as "green after mutation";
+// two lenses picking the same /tmp path is how that happened (#268 R2)
+function cmdWorktree(argv) {
+  const positional = argv.filter(a => !a.startsWith('--'))
+  const git = (args, opts) => quiet('git', args, opts)
+  if (argv.includes('--prune')) {
+    // every wuwei worktree, or only the reviewed sha's
+    const sha = positional[0] ? git(['rev-parse', positional[0]]).stdout.trim().slice(0, 12) : ''
+    const trees = git(['worktree', 'list', '--porcelain']).stdout.split('\n')
+      .filter(l => l.startsWith('worktree ')).map(l => l.slice(9))
+      .filter(p => p.split(/[\\/]/).pop().startsWith(`wuwei-${sha}`))
+    for (const t of trees) {
+      const r = git(['worktree', 'remove', '--force', t])
+      console.log(`${ok(r) ? 'removed' : 'could not remove'} ${t}`)
+    }
+    if (!trees.length) console.log('no wuwei worktrees')
+    return
+  }
+  const [lens, rev = 'HEAD'] = positional
+  if (!lens || !/^[a-z0-9:_-]+$/i.test(lens)) {
+    console.error('usage: wuwei worktree <lens> [<sha>]  ·  wuwei worktree --prune [<sha>]')
+    process.exit(1)
+  }
+  const sha = git(['rev-parse', '--verify', `${rev}^{commit}`]).stdout?.trim()
+  if (!sha) { console.error(`✗ ${rev} is not a commit here`); process.exit(1) }
+  const path = join(tmpdir(), `wuwei-${sha.slice(0, 12)}-${lens.replace(/:/g, '-')}-${Math.random().toString(36).slice(2, 8)}`)
+  const r = git(['worktree', 'add', '--detach', '--quiet', path, sha])
+  if (!ok(r)) { console.error(`✗ git worktree add failed: ${firstLine(r.stderr)}`); process.exit(1) }
+  // stdout is the path alone, so `cd "$(wuwei worktree defects <sha>)"` works
+  console.log(path)
+}
+
+// ── mutate: one mutation, run, counted, restored — and recorded ──────
+// a green suite after a mutation has three causes and only one is a finding:
+// the test is blind, the mutation never landed, or the run never reached it.
+// This rules out the second (the diff must be non-empty), shows the third
+// (what ran, from the runner's own summary), and keeps the run on record
+const RUNNER_SUMMARY = [
+  [/Tests?\s+(?:(\d+)\s+failed\s*\|\s*)?(\d+)\s+passed/i, m => [Number(m[1] ?? 0), Number(m[2])]],          // vitest
+  [/Tests:\s+(?:(\d+)\s+failed,\s*)?(?:\d+\s+\w+,\s*)*(\d+)\s+passed/i, m => [Number(m[1] ?? 0), Number(m[2])]], // jest
+  [/=+\s*(?:(\d+)\s+failed,?\s*)?(\d+)\s+passed/i, m => [Number(m[1] ?? 0), Number(m[2])]],                  // pytest
+  [/(\d+)\s+pass\b[\s\S]*?(\d+)\s+fail\b/i, m => [Number(m[2]), Number(m[1])]],                               // bun test
+  [/ℹ pass (\d+)[\s\S]*?ℹ fail (\d+)/, m => [Number(m[2]), Number(m[1])]],                                     // node --test
+  [/^# pass (\d+)[\s\S]*?^# fail (\d+)/m, m => [Number(m[2]), Number(m[1])]],                                  // TAP (node --test piped)
+]
+const FAILING = [/^\s*(?:FAIL|×|✗|✖)\s+(.+?)(?:\s+\([\d.]+m?s\))?\s*$/gm, /^\s*●\s+(.+?)\s*$/gm, /^FAILED\s+(\S+)/gm, /^not ok \d+ - (.+)$/gm, /^\(fail\)\s+(.+?)(?:\s+\[[\d.]+m?s\])?\s*$/gm]
+
+function runTests(cmd, cwd) {
+  const r = spawnSync(cmd, { cwd, shell: true, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, timeout: 30 * 60 * 1000 })
+  const out = `${r.stdout ?? ''}\n${r.stderr ?? ''}`.replace(/\x1b\[[0-9;]*m/g, '')
+  let counts = null
+  for (const [re, f] of RUNNER_SUMMARY) { const m = out.match(re); if (m) { counts = f(m); break } }
+  const failing = [...new Set(FAILING.flatMap(re => [...out.matchAll(re)].map(m => m[1].trim())))].slice(0, 20)
+  return { exit: r.status, failed: counts?.[0] ?? null, passed: counts?.[1] ?? null, failing, tail: out.trim().split('\n').slice(-5).join('\n') }
+}
+
+function cmdMutate(argv) {
+  const flag = name => { const i = argv.indexOf(name); return i === -1 ? null : argv[i + 1] }
+  const where = argv.find((a, i) => !a.startsWith('--') && !argv[i - 1]?.startsWith('--'))
+  const [, file, line] = where?.match(/^(.+):(\d+)$/) ?? []
+  const from = flag('--from'), to = flag('--to') ?? '', run = flag('--run')
+  const wt = resolve(flag('--in') ?? process.cwd())
+  if (!file || from == null || !run) {
+    console.error(`usage: wuwei mutate <file>:<line> --from '<text>' [--to '<text>'] --run '<test command>' [--in <worktree>] [--no-baseline]
+  runs only inside a tree made by \`wuwei worktree <lens> <sha>\`, never the dispatched one`)
+    process.exit(1)
+  }
+  // the dispatched tree is never mutated: only a wuwei worktree qualifies
+  const top = quiet('git', ['-C', wt, 'rev-parse', '--show-toplevel']).stdout?.trim()
+  if (!top || !/^wuwei-[0-9a-f]{12}-/.test(top.split(/[\\/]/).pop()))
+    { console.error(`✗ ${wt} is not a wuwei worktree — make one: wuwei worktree <lens> <sha>`); process.exit(1) }
+  if (quiet('git', ['-C', top, 'status', '--porcelain', '--untracked-files=no']).stdout.trim())
+    { console.error('✗ the worktree has uncommitted changes — a mutation on top of another reads as neither'); process.exit(1) }
+  const path = join(top, file)
+  if (!existsSync(path)) { console.error(`✗ ${file} is not in ${top}`); process.exit(1) }
+  const original = readFileSync(path, 'utf8')
+  const lines = original.split('\n')
+  const n = Number(line) - 1
+  const hits = lines[n]?.split(from).length - 1
+  if (hits !== 1) { console.error(`✗ the mutation would not land: '${from}' occurs ${hits ?? 0} times on ${file}:${line} — it must occur once`); process.exit(1) }
+
+  const baseline = argv.includes('--no-baseline') ? null : runTests(run, top)
+  lines[n] = lines[n].replace(from, to)
+  writeFileSync(path, lines.join('\n'))
+  const landed = quiet('git', ['-C', top, 'diff', '--numstat', '--', file]).stdout.trim()
+  const result = landed ? runTests(run, top) : null
+  writeFileSync(path, original)
+  const restored = !quiet('git', ['-C', top, 'status', '--porcelain', '--untracked-files=no']).stdout.trim()
+
+  const fmt = r => r.failed == null ? `exit ${r.exit} (runner summary not recognised)` : `${r.failed} failed / ${r.passed} passed (exit ${r.exit})`
+  const verdict = !landed ? 'did not land'
+    : result.failed == null ? (result.exit === 0 ? 'green' : 'red') + ' by exit code'
+    : result.failed > (baseline?.failed ?? 0) ? 'caught' : 'survived'
+  const sha = quiet('git', ['-C', top, 'rev-parse', 'HEAD']).stdout.trim()
+  const lens = top.split(/[\\/]/).pop().replace(/^wuwei-[0-9a-f]{12}-/, '').replace(/-[a-z0-9]{6}$/, '')
+  const entry = [`- \`${file}:${line}\` \`${from}\` → \`${to}\` · **${verdict}** · ${landed ? 'landed' : 'not landed'}`,
+    baseline ? `baseline ${fmt(baseline)}` : 'no baseline',
+    result ? `mutated ${fmt(result)}` : '',
+    result?.failing.length ? `failing: ${result.failing.join('; ')}` : '',
+    restored ? 'restored' : '**NOT restored**', `\`${run}\``].filter(Boolean).join(' · ')
+  console.log(entry)
+  if (result && result.failed == null) console.log(result.tail)
+  // the record: a mutation the digest cites is one this file shows was run
+  const main = dirname(resolve(top, quiet('git', ['-C', top, 'rev-parse', '--git-common-dir']).stdout.trim()))
+  const out = join(main, '.wuwei-cache', 'review', sha.slice(0, 12), 'mutations')
+  mkdirSync(out, { recursive: true })
+  writeFileSync(join(out, `${lens}.md`), (existsSync(join(out, `${lens}.md`)) ? readFileSync(join(out, `${lens}.md`), 'utf8') : `# mutations · ${lens} @ ${sha.slice(0, 12)}\n\n`) + entry + '\n')
+  if (!restored) process.exit(2)
+}
+
+// ── sites: a set derived from the tree, with its derivation ──────────
+// "four call sites", "every consumer", "the only reader": a count is the
+// output of a command, so print the command beside the count — and for a
+// symbol, ask the graph and a string grep both: each misses what the other finds
+function cmdSites(argv) {
+  const flag = name => { const i = argv.indexOf(name); return i === -1 ? null : argv[i + 1] }
+  const dd = argv.indexOf('--')
+  const pathspec = dd === -1 ? [] : argv.slice(dd + 1)
+  const args = dd === -1 ? argv : argv.slice(0, dd)
+  const pattern = args.find((a, i) => !a.startsWith('--') && !['--sha', '--symbol'].includes(args[i - 1]))
+  const sha = flag('--sha') ?? 'HEAD', symbol = flag('--symbol'), regex = args.includes('--regex')
+  if (!pattern && !symbol) { console.error("usage: wuwei sites <pattern> [--regex] [--sha <rev>] [--symbol <name>] [-- <pathspec>…]"); process.exit(1) }
+  const term = pattern ?? symbol
+  const grepArgs = ['grep', '-n', regex ? '-E' : '-F', '-e', term, sha, '--', ...pathspec]
+  const g = quiet('git', grepArgs)
+  if (g.status > 1) { console.error(`✗ git grep failed: ${firstLine(g.stderr)}`); process.exit(1) }
+  const grepHits = g.stdout.split('\n').filter(Boolean).map(l => {
+    const [, file, line, text] = l.replace(`${sha}:`, '').match(/^([^:]+):(\d+):(.*)$/) ?? []
+    return { file, line: Number(line), text: (text ?? '').trim() }
+  }).filter(h => h.file)
+  const files = [...new Set(grepHits.map(h => h.file))]
+  console.log(`${grepHits.length} site(s) in ${files.length} file(s) @ ${quiet('git', ['rev-parse', '--short', sha]).stdout.trim()}`)
+  console.log(`derived: git ${grepArgs.map(a => /[\s|*()[\]+?$^{}\\]/.test(a) ? `'${a}'` : a).join(' ')}`)
+  for (const f of files) {
+    const hs = grepHits.filter(h => h.file === f)
+    console.log(`  ${f}:${hs.map(h => h.line).join(',')}`)
+  }
+
+  if (symbol) {
+    // the graph answers a different question: who references the symbol, not who spells it
+    const st = quiet('codegraph', ['status', '--json'])
+    let usable = false
+    try { const j = JSON.parse(st.stdout); usable = j.initialized === true && !j.worktreeMismatch && !(j.pendingChanges?.length) } catch {}
+    if (!usable) { console.log(`\ngraph: absent or stale — the grep above is the only answer, and it misses a name assembled at runtime`); return }
+    const c = quiet('codegraph', ['callers', symbol, '--json'])
+    // callers are entities (a function, or a file for top-level code) at their
+    // start line, not call sites — so the two answers meet at the file
+    const callers = []
+    const walk = v => {
+      if (Array.isArray(v)) return v.forEach(walk)
+      if (v && typeof v === 'object') {
+        const file = v.filePath ?? v.file ?? v.path
+        if (typeof file === 'string') callers.push({ file, name: v.name ?? '?', kind: v.kind ?? '?', line: v.startLine ?? v.line })
+        Object.values(v).forEach(walk)
+      }
+    }
+    try { walk(JSON.parse(c.stdout)) } catch { console.log('\ngraph: callers returned no JSON'); return }
+    const graphFiles = new Set(callers.map(c => c.file))
+    console.log(`\ngraph: ${callers.length} caller(s) in ${graphFiles.size} file(s)`)
+    for (const c of callers) console.log(`  ${c.kind} ${c.name}  ${c.file}:${c.line}`)
+    const graphOnly = [...graphFiles].filter(f => !files.includes(f)), grepOnly = files.filter(f => !graphFiles.has(f))
+    for (const f of graphOnly) console.log(`  graph only  ${f}   (references ${term} without spelling it: alias, re-export, destructuring)`)
+    for (const f of grepOnly) console.log(`  grep only   ${f}   (spells ${term} without calling it — comment, string, declaration — or a call the graph missed)`)
+    if (!graphOnly.length && !grepOnly.length) console.log('  graph and grep agree on the files')
+  }
+}
+
+// ── verify: hands and eyes — every data-bearing page through its states ──
+// The record: UI state bugs found one round at a time (#268 R1 → R2 → R3:
+// a refetch failure that replaces loaded rows, a 403 shown as a generic
+// error, a summary silently stale). One run walks every endpoint the page
+// calls through each state, so the matrix shows them at once. Playwright
+// comes from the project (or a global install); the app's own auth and
+// fixtures come from .wuwei/verify.json — the per-app half of this tool
+const VERIFY_STATES = ['500', '403', '404', 'empty', 'pending', 'refetch-500', 'refetch-403']
+// a loader as component libraries mark it (shadcn: data-slot="skeleton", animate-pulse)
+const BUSY = '[aria-busy="true"],[role="progressbar"],[data-slot*="skeleton"],[data-loading="true"],.skeleton,[data-skeleton],[class*="skeleton"],.animate-pulse,.animate-spin'
+const SAYS_ERROR = /error|failed|could not|couldn't|unable|try again|retry|錯誤|失敗|無法/i
+const TICKS = /\b\d+\s*(s|sec|secs|seconds?|min|mins|minutes?|h|hours?)\s+ago\b|\d+\s*(秒|分鐘|小時)前|just now|剛剛/i
+const SAYS_FORBIDDEN = /permission|forbidden|not allowed|denied|access|authori[sz]|權限|無權/i
+
+function loadPlaywright(cwd) {
+  for (const base of [join(cwd, 'package.json'), join(runNpm(['root', '-g'], { encoding: 'utf8' }).stdout?.trim() ?? '', 'noop.js')]) {
+    try { return createRequire(base)('playwright') } catch {}
+  }
+  return null
+}
+
+const globRe = g => new RegExp('^' + g.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*\*/g, '\u0000').replace(/\*/g, '[^/]*').replace(/\u0000/g, '.*') + '$')
+
+function fixtureFor(fixtures, method, url) {
+  const u = new URL(url)
+  for (const [key, value] of Object.entries(fixtures ?? {})) {
+    const [m, pattern] = key.includes(' ') ? key.split(/\s+/, 2) : ['GET', key]
+    if (m.toUpperCase() !== method) continue
+    const target = pattern.includes('?') ? u.pathname + u.search : u.pathname
+    if (globRe(pattern).test(target)) {
+      const v = value && typeof value === 'object' && ('status' in value || 'json' in value) ? value : { status: 200, json: value }
+      return { key, status: v.status ?? 200, json: v.json ?? null }
+    }
+  }
+  return null
+}
+
+// the empty variant of a happy body: the list it carries, emptied
+// a total left behind ("Showing 1–3 of 3" over no rows) is the fixture lying, not the app
+const zeroTotals = o => Array.isArray(o) ? o : o && typeof o === 'object'
+  ? Object.fromEntries(Object.entries(o).map(([k, v]) => [k, /^(total|totalCount|totalItems|count)$/.test(k) && typeof v === 'number' ? 0 : zeroTotals(v)]))
+  : o
+function emptied(json) {
+  if (Array.isArray(json)) return []
+  if (json && typeof json === 'object') {
+    for (const k of ['data', 'items', 'rows', 'list', 'results', 'records'])
+      if (Array.isArray(json[k])) return zeroTotals({ ...json, [k]: [] })
+    if (json.data && typeof json.data === 'object') { const inner = emptied(json.data); if (inner) return zeroTotals({ ...json, data: inner }) }
+  }
+  return null
+}
+
+async function waitForUrl(url, ms) {
+  const until = Date.now() + ms
+  while (Date.now() < until) {
+    try { const r = await fetch(url); if (r.status < 500) return true } catch {}
+    await new Promise(r => setTimeout(r, 500))
+  }
+  return false
+}
+
+async function cmdVerify(argv) {
+  const dest = process.cwd()
+  const cfgPath = join(dest, '.wuwei', 'verify.json')
+  if (!existsSync(cfgPath)) {
+    console.error(`✗ no .wuwei/verify.json — the per-app half of verify:
+{
+  "url": "http://localhost:5173",            // the running app (or "start" to launch it)
+  "start": "npm run dev",                    // optional
+  "api": ["**/api/**"],                      // requests to take over
+  "auth": { "localStorage": { "token": "…" } },
+  "fixtures": { "GET /api/me": { "role": "viewer" }, "GET /api/items": { "data": [ … ], "total": 2 } },
+  "pages": [ { "name": "items", "path": "/items", "ready": "text=Items" } ],
+  "refetch": "focus", "refetchAfterMs": 600000, "refetchWaitMs": 30000,
+  "busy": "[data-slot=skeleton]",            // optional: your loader, beyond the usual ones
+  "errorWaitMs": 60000                       // simulated time client retries may hold the loader
+}`)
+    process.exit(1)
+  }
+  const cfg = JSON.parse(readFileSync(cfgPath, 'utf8'))
+  const flag = name => { const i = argv.indexOf(name); return i === -1 ? null : argv[i + 1] }
+  const only = argv.filter((a, i) => !a.startsWith('--') && !['--phase', '--stream'].includes(argv[i - 1]))
+  // --phase NN: the pages ACCEPTANCE.md binds to that phase — the contract, not memory
+  if (flag('--phase')) {
+    const sdir = join(dest, '.wuwei', 'streams')
+    const streams = existsSync(sdir) ? readdirSync(sdir, { withFileTypes: true }).filter(d => d.isDirectory()).map(d => d.name) : []
+    const stream = flag('--stream') ?? (streams.length === 1 ? streams[0] : null)
+    if (!stream || !streams.includes(stream)) { console.error(`✗ --stream: ${streams.join(', ') || 'none under .wuwei/streams/'}`); process.exit(1) }
+    const accPath = join(sdir, stream, 'ACCEPTANCE.md')
+    const vi = existsSync(accPath) ? verifyItems(readFileSync(accPath, 'utf8')) : null
+    if (!vi) { console.error(`✗ ${stream}/ACCEPTANCE.md has no ## Verify — wuwei plan-check names what is missing`); process.exit(1) }
+    const want = vi.items.filter(it => it.phase && Number(it.phase) === Number(flag('--phase'))).map(it => it.name)
+    if (!want.length) { console.log(`phase ${flag('--phase')}: ACCEPTANCE.md binds no page to it — nothing to verify`); return }
+    only.push(...want)
+  }
+  const missing = only.filter(n => !(cfg.pages ?? []).some(pg => pg.name === n))
+  if (missing.length) { console.error(`✗ not in .wuwei/verify.json: ${missing.join(', ')} — add each page (path, ready) and the fixtures it calls, from the API's schema`); process.exit(1) }
+  const pw = loadPlaywright(dest)
+  if (!pw) { console.error('✗ Playwright not found in this project or globally — npm i -D playwright'); process.exit(1) }
+  let server = null
+  if (cfg.start) {
+    server = spawn(cfg.start, { cwd: dest, shell: true, stdio: 'ignore', detached: true })
+    if (!(await waitForUrl(cfg.url, cfg.startTimeoutMs ?? 120000))) { console.error(`✗ ${cfg.url} did not come up after \`${cfg.start}\``); try { process.kill(-server.pid) } catch {} ; process.exit(1) }
+  } else if (!(await waitForUrl(cfg.url, 5000))) { console.error(`✗ ${cfg.url} is not reachable — start the app, or set "start"`); process.exit(1) }
+
+  const sha = quiet('git', ['rev-parse', 'HEAD']).stdout?.trim().slice(0, 12) || 'nogit'
+  const outDir = join(dest, '.wuwei-cache', 'verify', sha)
+  const browser = await pw.chromium.launch()
+  const apiRes = [].concat(cfg.api ?? ['**/api/**']).map(globRe)
+  const isApi = url => apiRes.some(re => re.test(url) || re.test(new URL(url).pathname))
+  const report = []
+
+  // one visit: routes every API call to its fixture, except the endpoint under test
+  const visit = async (page, { override, refetchFail, viewport } = {}) => {
+    const ctx = await browser.newContext({ viewport: viewport ?? cfg.viewport ?? { width: 1280, height: 800 } })
+    if (cfg.auth?.cookies) await ctx.addCookies(cfg.auth.cookies)
+    if (cfg.auth?.localStorage || cfg.auth?.sessionStorage)
+      await ctx.addInitScript(a => {
+        for (const [k, v] of Object.entries(a.localStorage ?? {})) localStorage.setItem(k, typeof v === 'string' ? v : JSON.stringify(v))
+        for (const [k, v] of Object.entries(a.sessionStorage ?? {})) sessionStorage.setItem(k, typeof v === 'string' ? v : JSON.stringify(v))
+      }, cfg.auth)
+    const p = await ctx.newPage()
+    const seen = new Map(), unmocked = new Set(), errors = []
+    let failing = false, refetched = 0
+    p.on('pageerror', e => errors.push(String(e.message ?? e).split('\n')[0]))
+    await p.route('**/*', async route => {
+      const req = route.request(), url = req.url()
+      if (!isApi(url)) return route.continue()
+      const fx = fixtureFor(cfg.fixtures, req.method(), url)
+      if (!fx) { unmocked.add(`${req.method()} ${new URL(url).pathname}`); return route.fulfill({ status: 501, body: 'unmocked by wuwei verify' }) }
+      seen.set(fx.key, fx)
+      const hit = override && fx.key === override.key
+      if ((hit && override.state === 'pending')) return // never answered: the loading state
+      if (hit && /^\d+$/.test(override.state)) return route.fulfill({ status: Number(override.state), contentType: 'application/json', body: JSON.stringify({ message: `wuwei verify ${override.state}` }) })
+      if (hit && override.state === 'empty') return route.fulfill({ status: 200, contentType: 'application/json', body: JSON.stringify(emptied(fx.json)) })
+      if (refetchFail && fx.key === refetchFail.key && failing) return refetched++, route.fulfill({ status: refetchFail.status, contentType: 'application/json', body: JSON.stringify({ message: `wuwei verify refetch ${refetchFail.status}` }) })
+      return route.fulfill({ status: fx.status, contentType: 'application/json', body: JSON.stringify(fx.json) })
+    })
+    // the page's clock is ours: a fresh cache never refetches on focus (React Query's
+    // staleTime), and a client retrying 5xx (1s, 2s, 4s) is still loading when a real
+    // wait gives up — both are moved through in simulated time, not slept through
+    await p.clock.install()
+    const busyNow = () => p.evaluate(sel => Boolean(document.querySelector(sel)) || /\bloading\b|載入中/i.test(document.body.innerText),
+      [BUSY, cfg.busy].filter(Boolean).join(',')).catch(() => false)
+    const settle = async (ms, until) => {
+      for (let t = 0; t < ms; t += 1000) {
+        if (until && !(await until())) return
+        await p.clock.runFor(1000)
+        // real time for the fetch a timer just fired: networkidle, once reached, never waits again
+        await p.waitForTimeout(100)
+      }
+    }
+    await p.goto(new URL(page.path, cfg.url).href, { waitUntil: 'domcontentloaded' })
+    if (override?.state === 'pending') await p.waitForTimeout(cfg.pendingWaitMs ?? 1500)
+    else {
+      if (page.ready) await p.locator(page.ready).first().waitFor({ timeout: 15000 }).catch(() => {})
+      await p.waitForLoadState('networkidle').catch(() => {})
+      if (override) await settle(cfg.errorWaitMs ?? 60000, busyNow)
+    }
+    if (refetchFail) {
+      failing = true
+      await p.clock.fastForward(cfg.refetchAfterMs ?? 600000)
+      // the app's refetch trigger: a window refocus by default
+      if ((cfg.refetch ?? 'focus') === 'focus') await p.evaluate(() => { document.dispatchEvent(new Event('visibilitychange', { bubbles: true })); window.dispatchEvent(new Event('focus')) })
+      else await p.locator(cfg.refetch).first().click().catch(() => {})
+      await settle(cfg.refetchWaitMs ?? 30000)
+    }
+    const text = (await p.locator('body').innerText().catch(() => '')).replace(/[ \t]+/g, ' ').trim()
+    const busy = await p.evaluate(sel => Boolean(document.querySelector(sel)), [BUSY, cfg.busy].filter(Boolean).join(','))
+    const retry = await p.getByRole('button', { name: /retry|try again|重試/i }).count()
+    return { p, ctx, text, busy, retry, seen, unmocked, errors, refetched }
+  }
+  const lines = t => new Set(t.split('\n').map(l => l.trim()).filter(l => l.length > 2))
+
+  for (const page of (cfg.pages ?? []).filter(pg => !only.length || only.includes(pg.name))) {
+    const dir = join(outDir, page.name)
+    mkdirSync(dir, { recursive: true })
+    const happy = await visit(page)
+    await happy.p.screenshot({ path: join(dir, 'happy.png'), fullPage: true })
+    writeFileSync(join(dir, 'happy.txt'), happy.text)
+    for (const vp of cfg.viewports ?? [{ width: 390, height: 844 }]) {
+      const narrow = await visit(page, { viewport: vp })
+      await narrow.p.screenshot({ path: join(dir, `happy-${vp.width}.png`), fullPage: true })
+      await narrow.ctx.close()
+    }
+    const endpoints = [...happy.seen.keys()]
+    const happyLines = lines(happy.text)
+    const rows = [{ endpoint: '—', state: 'happy', flags: [...[...happy.unmocked].map(u => `unmocked: ${u}`), ...happy.errors.map(e => `page error: ${e}`)], shot: 'happy.png', text: happy.text }]
+    await happy.ctx.close()
+    const served = new Map(happy.seen)
+    for (const key of endpoints) {
+      for (const state of VERIFY_STATES) {
+        if (state === 'empty' && !emptied(served.get(key)?.json)) continue
+        const refetch = state.match(/^refetch-(\d+)$/)
+        const v = refetch ? await visit(page, { refetchFail: { key, status: Number(refetch[1]) } }) : await visit(page, { override: { key, state } })
+        const slug = `${key.replace(/[^\w]+/g, '_').replace(/^_|_$/g, '')}--${state}`
+        await v.p.screenshot({ path: join(dir, `${slug}.png`), fullPage: true })
+        writeFileSync(join(dir, `${slug}.txt`), v.text)
+        await v.ctx.close()
+        const vLines = lines(v.text)
+        // judged on what the state added to the screen: a nav item saying "Access" is not an answer
+        const said = [...vLines].filter(l => !happyLines.has(l)).join('\n')
+        const loading = v.busy || /loading|載入/i.test(said)
+        const flags = v.errors.map(e => `page error: ${e}`)
+        if (/^5/.test(state) && loading) flags.push(`still loading ${(cfg.errorWaitMs ?? 60000) / 1000}s on — client retries outlast the wait; raise "errorWaitMs"`)
+        else if (/^5/.test(state) && !SAYS_ERROR.test(said)) flags.push('no error shown')
+        if (state === '403' && !SAYS_FORBIDDEN.test(said)) flags.push('403 not told as a permission problem')
+        if (state === '404' && v.retry) flags.push('Retry offered on a 404 — it can never succeed')
+        if (state === '403' && v.retry) flags.push('Retry offered on a 403 — it can never succeed')
+        if (state === 'pending' && !v.busy && !/loading|載入/i.test(v.text)) flags.push('no loading indicator')
+        // a refetch that never happened says nothing about how a failed one looks;
+        // what it did say is the lines it added — a relative time ticking is not an error
+        const gone = [...happyLines].filter(l => !vLines.has(l) && !TICKS.test(l))
+        const told = SAYS_ERROR.test(said) || (state === 'refetch-403' && SAYS_FORBIDDEN.test(said))
+        if (refetch && !v.refetched) flags.push(`not refetched by "${cfg.refetch ?? 'focus'}" ${Math.round((cfg.refetchAfterMs ?? 600000) / 60000)} min on — set "refetch" to what refetches it, or a longer "refetchAfterMs"`)
+        else if (refetch && !told) flags.push('silent: the failed refetch shows nothing')
+        else if (refetch && gone.length) flags.push(`refetch failure replaced loaded content: ${gone.length} line(s) gone (${gone.slice(0, 2).join(' / ').slice(0, 60)})`)
+        if (state === 'refetch-403' && v.refetched && told && !SAYS_FORBIDDEN.test(said)) flags.push('403 on refetch not told as a permission problem')
+        rows.push({ endpoint: key, state, flags, shot: `${slug}.png`, text: v.text, said })
+      }
+    }
+    // a failure that reads exactly like no data: the user is told there is nothing, not that it broke
+    for (const e of rows.filter(r => r.state === 'empty' && r.said)) for (const r of rows)
+      if (r.endpoint === e.endpoint && /^\d+$/.test(r.state) && r.said === e.said) r.flags.push(`${r.state} shown as the empty state ("${e.said.split('\n')[0].slice(0, 40)}")`)
+    const md = [`# verify ${page.name} @ ${sha}`, '', `page: \`${page.path}\` · endpoints: ${endpoints.length} · states: ${VERIFY_STATES.join(', ')}`, '',
+      '| endpoint | state | flags | on screen, beyond happy | shot |', '|---|---|---|---|---|',
+      ...rows.map(r => `| ${r.endpoint} | ${r.state} | ${r.flags.length ? r.flags.join('; ') : '—'} | ${((r.said ?? r.text).split('\n').find(l => l.trim()) ?? '—').slice(0, 60).replace(/\|/g, '\\|')} | ${r.shot} |`)]
+    writeFileSync(join(dir, 'matrix.md'), md.join('\n') + '\n')
+    report.push({ page: page.name, rows, dir })
+  }
+  await browser.close()
+  if (server) try { process.kill(-server.pid) } catch {}
+
+  for (const { page, rows, dir } of report) {
+    const flagged = rows.filter(r => r.flags.length)
+    console.log(`${page}: ${rows.length} state(s), ${flagged.length} flagged — ${join(dir, 'matrix.md')}`)
+    for (const r of flagged) console.log(`  ${r.endpoint} · ${r.state}: ${r.flags.join('; ')}`)
+  }
+  console.log('\nflags are leads, not findings: open the shot, and confirm against the spec what the page should say')
+}
+
+// ── digest-check: wuwei-review §7's arithmetic, before publishing ─────
+// what the collator re-derives by hand: the header count against the table,
+// reporter credits, every file:line against the reviewed tree, every
+// identifier an Action names, HIGH × PLAUSIBLE, redaction, and HEAD moving
+const LENS_WORDS = /\b(opus|design|defects|security|code|claims|structure|drift|contract|coverage|composition|collator|dispatcher)\b/gi
+const SECRET = [
+  [/\b[\w.+-]+@[\w-]+\.iam\.gserviceaccount\.com\b/, 'service account'],
+  [/\b(ghp|gho|ghs|ghu|github_pat)_[A-Za-z0-9_]{20,}/, 'GitHub token'],
+  [/\bAKIA[0-9A-Z]{16}\b/, 'AWS key'],
+  [/\bxox[abpr]-[A-Za-z0-9-]{10,}/, 'Slack token'],
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----/, 'private key'],
+  [/\b[\w.+-]+@(?!users\.noreply\.github\.com|anthropic\.com|example\.(?:com|org))[\w-]+\.[\w.]+\b/, 'email'],
+]
+
+function digestRows(text) {
+  // finding rows: a table row whose first cell is a number, outside the
+  // sections that hold other tables
+  const skip = /^#+\s*(key decisions|threat|plan deviations|verdict|.*推導|.*raw\s*→)/i
+  const rows = []
+  let header = null, skipping = false, inDetails = false
+  for (const line of text.split('\n')) {
+    if (/^#+\s/.test(line)) { skipping = skip.test(line); header = null; continue }
+    if (/<details>/.test(line)) inDetails = true
+    if (/<\/details>/.test(line)) { inDetails = false; continue }
+    if (skipping || inDetails || !/^\s*\|/.test(line)) { if (!/^\s*\|/.test(line)) header = null; continue }
+    const cells = line.trim().replace(/^\||\|$/g, '').split(/(?<!\\)\|/).map(c => c.trim())
+    if (/^[\s:|-]+$/.test(line.replace(/\|/g, ''))) continue
+    if (!header) { header = cells.map(c => c.replace(/`/g, '').toLowerCase()); continue }
+    const id = cells[0].replace(/[*`]/g, '').match(/^([A-Z]{1,3}-?)?(\d+)$/)
+    if (!id) continue
+    // exact header first: 'ev' is inside 'sev'
+    const col = name => { let i = header.indexOf(name); if (i === -1) i = header.findIndex(h => h.includes(name)); return i === -1 ? '' : cells[i] ?? '' }
+    rows.push({ n: Number(id[2]), key: (id[1] ?? '') + id[2], prefix: id[1] ?? '', line, sev: col('sev'), ev: col('ev'), reporter: col('reporter'),
+      where: col('file:line') || col('位置') || col('file'), action: col('action') || col('建議') || col('怎麼改'), cells })
+  }
+  return rows
+}
+
+function cmdDigestCheck(argv) {
+  const file = argv.find(a => !a.startsWith('--'))
+  if (!file || !existsSync(file)) { console.error('usage: wuwei digest-check <digest.md>'); process.exit(1) }
+  const text = readFileSync(file, 'utf8')
+  const errs = [], warns = [], oks = []
+  const rows = digestRows(text)
+
+  // 1. the count line — template form or the prose form real digests drift into
+  // the count lives on the line that says raw N (and the next): numbers
+  // elsewhere — mutation counts, row ids — are not it
+  const lines = text.split('\n')
+  const at = lines.findIndex(l => /\braw\s*\d+/i.test(l))
+  const countText = at === -1 ? text : lines.slice(at, at + 2).join('\n')
+  const num = re => { const m = countText.match(re); return m ? Number(m[1]) : null }
+  const N = num(/\braw\s*(\d+)/i)
+  const K = num(/(\d+)\s*(?:rows?|列)\b/i) ?? num(/(\d+)\s*列/)
+  const X = num(/\((\d+)\s*merged\)/i) ?? num(/(\d+)\s*(?:條|筆|列)?\s*merged/i) ?? num(/(\d+)\s*(?:條|筆|列)?\s*(?:合併|併入)/) ?? num(/(?:合併|併入)\s*(\d+)/)
+  const D = num(/(\d+)\s*(?:條|筆|列)?\s*drop(?:ped)?\b/i) ?? num(/dropped\s*(\d+)/i) ?? num(/(\d+)\s*(?:條|筆|列)?\s*(?:丟棄|捨棄|撤回)/) ?? num(/(?:丟棄|捨棄|撤回)\s*(\d+)/)
+    ?? (/(?:沒有|無)[^。\n]{0,12}(?:丟棄|捨棄|撤回)|no(?:thing)?\s+dropped/i.test(countText) ? 0 : null)
+  if ([N, K, X, D].some(v => v == null))
+    errs.push(`count line: could not read ${[['raw', N], ['rows', K], ['merged', X], ['dropped', D]].filter(([, v]) => v == null).map(([k]) => k).join(', ')} — use the template's \`raw N · M groups (X merged) · K rows (C closed) · D dropped\``)
+  else if (N !== K + X + D) errs.push(`count: raw ${N} ≠ ${K} rows + ${X} merged + ${D} dropped (= ${K + X + D})`)
+  else oks.push(`count: raw ${N} = ${K} rows + ${X} merged + ${D} dropped`)
+
+  // 2. the table against the header
+  if (K != null && rows.length !== K) errs.push(`rows: the header says ${K}, the tables hold ${rows.length} — a closed row stays in the table, not a paragraph`)
+  else if (K != null) oks.push(`rows: ${rows.length}, matches the header`)
+  // numbering per prefix: 1…n, L1…Ln
+  for (const prefix of new Set(rows.map(r => r.prefix))) {
+    const nums = rows.filter(r => r.prefix === prefix).map(r => r.n)
+    const dup = nums.filter((n, i) => nums.indexOf(n) !== i)
+    const start = Math.min(...nums)
+    const gaps = [...Array(Math.max(...nums) - start + 1).keys()].map(i => i + start).filter(n => !nums.includes(n))
+    if (dup.length) errs.push(`rows: duplicate ${[...new Set(dup)].map(n => `#${prefix}${n}`).join(', ')}`)
+    if (gaps.length) errs.push(`rows: missing ${gaps.map(n => `#${prefix}${n}`).join(', ')}`)
+  }
+
+  // 3. reporter credits sum to raw — one credit per lens named in a row
+  // `claims ×3` — one lens raising several that collation merged into one row
+  const creditsOf = cell => {
+    const seen = new Map()
+    const raised = cell.replace(new RegExp(`${LENS_WORDS.source}\\s*(?:[—–]|\\(\\s*[—–]|（\\s*[—–])[^·、,;|]*`, 'gi'), '')
+    for (const m of raised.matchAll(new RegExp(`${LENS_WORDS.source}(?:\\s*[×x]\\s*(\\d+))?`, 'gi')))
+      seen.set(m[1].toLowerCase(), Math.max(seen.get(m[1].toLowerCase()) ?? 1, Number(m[2] ?? 1)))
+    return [...seen.values()].reduce((a, b) => a + b, 0)
+  }
+  const credits = rows.reduce((sum, r) => sum + creditsOf(r.reporter), 0)
+  if (rows.some(r => r.reporter)) {
+    if (N != null && credits !== N) warns.push(`reporter credits: ${credits} lens names across the rows, raw is ${N} — a lens that raised two of what one row merges is written \`lens ×2\`; a concurrence at collation is not a credit`)
+    else if (N != null) oks.push(`reporter credits: ${credits} = raw`)
+  } else warns.push('reporter credits: no Reporter column found — not checked')
+
+  // 4. HIGH is never PLAUSIBLE
+  for (const r of rows)
+    if (/HIGH/.test(r.sev) && /PLAUSIBLE/.test(r.ev || r.line) && !/challenged/.test(r.line))
+      errs.push(`#${r.key}: HIGH and PLAUSIBLE — nothing PLAUSIBLE is rated HIGH (wuwei-review §2)`)
+
+  // 5. the reviewed tree: every file:line resolves, every Action identifier exists
+  const sha = (text.match(/(?:Reviewed at|審查版本)[:：]?\**\s*`?([0-9a-f]{7,40})`?/i) ?? text.match(/^#+ .*@\s*`([0-9a-f]{7,40})`/m))?.[1]
+  const tree = sha && ok(quiet('git', ['cat-file', '-e', `${sha}^{commit}`]))
+    ? quiet('git', ['ls-tree', '-r', '--name-only', sha]).stdout.split('\n').filter(Boolean) : null
+  if (!sha) warns.push('Reviewed at: no sha found — file:line and identifiers not checked')
+  else if (!tree) warns.push(`Reviewed at ${sha}: not in this repository — run inside the reviewed repo, fetched`)
+  else {
+    const lines = new Map()
+    const lengthOf = path => lines.get(path) ?? lines.set(path, quiet('git', ['show', `${sha}:${path}`]).stdout.replace(/\n$/, '').split('\n').length).get(path)
+    let refs = 0
+    for (const r of rows) {
+      for (const m of r.where.matchAll(/`?([\w./@-]+\.[A-Za-z0-9]+):(\d+)(?:[-–](\d+))?`?/g)) {
+        refs++
+        const [, path, a, b] = m
+        const hits = tree.filter(t => t === path || t.endsWith('/' + path))
+        if (!hits.length) errs.push(`#${r.n}: ${path} is not in the tree at ${sha.slice(0, 8)}`)
+        else if (hits.length > 1) warns.push(`#${r.n}: ${path} matches ${hits.length} files — give the full path`)
+        else if (Number(b ?? a) > lengthOf(hits[0])) errs.push(`#${r.n}: ${hits[0]}:${b ?? a} is past the end (${lengthOf(hits[0])} lines)`)
+      }
+      // a deferral names its artifact, and the artifact exists
+      for (const m of r.action.matchAll(/`?([\w./-]*todos?\/[\w./-]+\.md)`?/gi))
+        if (!ok(quiet('git', ['cat-file', '-e', `HEAD:${m[1]}`]))) errs.push(`#${r.key}: deferral artifact ${m[1]} is not in the tree at HEAD`)
+      if (/延後|defer|later PR|follow-?up|另開票|開票/i.test(r.action) && !/todos?\/|#\d+|\b[A-Z][A-Z0-9]+-\d+\b|\.md/.test(r.action))
+        warns.push(`#${r.key}: deferred with no artifact named — a ticket or a todo path (wuwei-review §7)`)
+      for (const m of r.action.matchAll(/`([A-Za-z_$][\w$.]*[A-Za-z0-9_$])`/g)) {
+        const id = m[1].split('.').pop()
+        if (id.length < 3 || /^(true|false|null|undefined)$/.test(id)) continue
+        if (!ok(quiet('git', ['grep', '-q', '-F', id, sha]))) warns.push(`#${r.n}: Action names \`${id}\`, not in the tree at ${sha.slice(0, 8)} — say it is a name the fix creates, or correct it`)
+      }
+    }
+    oks.push(`file:line: ${refs} reference(s) checked against ${sha.slice(0, 8)}`)
+    // re-resolve HEAD before publishing
+    const head = quiet('git', ['rev-parse', 'HEAD']).stdout.trim()
+    if (!head.startsWith(sha)) {
+      const since = quiet('git', ['log', '--oneline', `${sha}..HEAD`]).stdout.trim()
+      warns.push(`HEAD moved: ${head.slice(0, 8)} is not the reviewed ${sha.slice(0, 8)}${since ? ` — since: ${since.split('\n').join('; ')}` : ''} — re-check every finding, or say the digest is against ${sha.slice(0, 8)}`)
+    }
+  }
+
+  // 6. the digest leaves the tree
+  text.split('\n').forEach((l, i) => {
+    for (const [re, kind] of SECRET) if (re.test(l)) errs.push(`line ${i + 1}: looks like ${/^[aeiou]/i.test(kind) ? 'an' : 'a'} ${kind} — redact as <redacted:${kind.replace(/ /g, '-')}>`)
+  })
+
+  // 7. the verdict's two axes
+  if (!/\b(approach|architecture|contract):\s*\**`?\s*(holds|redo|met|diverged)/i.test(text) || !/\b(merge|document|main):\s*\**`?\s*(ready|not yet)/i.test(text))
+    errs.push('verdict: two axes not found — e.g. `approach: holds` · `merge: ready` (wuwei-review §7)')
+
+  for (const o of oks) console.log(`✓ ${o}`)
+  for (const w of warns) console.log(`! ${w}`)
+  for (const e of errs) console.log(`✗ ${e}`)
+  console.log(errs.length ? `\n${errs.length} error(s) — fix before publishing` : '\nno errors')
+  process.exit(errs.length ? 1 : 0)
+}
+
+// ── review-prep ──────────────────────────────────────────────────────
+// wuwei-review §1's deterministic half as a program: the dispatcher checks a
+// command can answer, and the scan bundle. Judgment stays with the dispatcher —
+// reclassifying by content, platform state, what the thread says.
+const LOCKFILE = /(^|\/)(package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?|Cargo\.lock|go\.sum|poetry\.lock|uv\.lock|Gemfile\.lock|composer\.lock)$/
+const STATE_FILE = /(^|\/)(STATE|ROADMAP)\.md$/
+const AUTHOR_PATH = /\/Users\/|\/home\/|\/root\/|~\/|\$HOME|\$\{HOME\}|[A-Za-z]:\\Users|\/opt\/homebrew\//
+// a first pass by path; §1 reclassifies by content (a .md of shell commands is code)
+const kindOf = path => LOCKFILE.test(path) ? 'lock'
+  : /(^|\/)(migrations?|drizzle)\/.*\.sql$|(^|\/)migrations?\//.test(path) ? 'migration'
+  : /\.(md|mdx|rst|txt|adoc)$/i.test(path) ? 'prose'
+  : /\.(json|jsonc|ya?ml|toml|ini|cfg|conf)$|(^|\/)(Dockerfile|\.env[^/]*|\.[^/]+rc)$|\.config\.[cm]?[jt]s$/.test(path) ? 'config'
+  : 'code'
+
+// optional tools: absent is an answer, not an error worth printing
+const quiet = (bin, args, opts = {}) =>
+  spawnSync(bin, args, { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, shell: process.platform === 'win32', ...opts })
+const ok = r => !r.error && r.status === 0
+const firstLine = t => (t ?? '').trim().split('\n')[0]
+
+function ghRepo() {
+  const url = quiet('git', ['remote', 'get-url', 'origin']).stdout?.trim() ?? ''
+  return url.match(/github\.com[:/]([^/]+)\/(.+?)(\.git)?$/)?.slice(1, 3).join('/') ?? null
+}
+// every page: one JSON array per page under --paginate, concatenated
+function ghAll(endpoint) {
+  const r = quiet('gh', ['api', '--paginate', `${endpoint}${endpoint.includes('?') ? '&' : '?'}per_page=100`])
+  if (!ok(r)) return null
+  return JSON.parse(`[${r.stdout.trim().replace(/\]\s*\[/g, '],[')}]`).flat()
+}
+
+function cmdReviewPrep(argv) {
+  const flag = name => { const i = argv.indexOf(name); return i === -1 ? null : argv[i + 1] }
+  const pr = flag('--pr')?.replace(/^#/, '').match(/(\d+)$/)?.[1] ?? null
+  const pathTarget = flag('--path')
+  const noScan = argv.includes('--no-scan')
+  let base = argv.filter((a, i) => !a.startsWith('--') && !['--pr', '--path'].includes(argv[i - 1]))[0] ?? null
+  if (quiet('git', ['rev-parse', '--git-dir']).status !== 0) { console.error('✗ not a git repository'); process.exit(1) }
+  const head = quiet('git', ['rev-parse', 'HEAD']).stdout.trim()
+  const facts = []      // [check, result] — what the panel receives as facts
+  const left = []       // what only the dispatcher can do
+
+  // the target and its base
+  const repo = pr ? ghRepo() : null
+  if (pr) {
+    const r = quiet('gh', ['api', `repos/${repo}/pulls/${pr}`])
+    if (!repo || !ok(r)) { console.error(`✗ cannot read PR #${pr} — needs \`gh api\` and a GitHub origin; or pass the base: wuwei review-prep <base>`); process.exit(1) }
+    const p = JSON.parse(r.stdout)
+    base ??= p.base.ref
+    facts.push(['target', `PR #${pr} ${p.head.ref} → ${p.base.ref}`])
+    if (p.head.sha !== head) facts.push(['HEAD', `**${head.slice(0, 8)} is not the PR head ${p.head.sha.slice(0, 8)}** — check out the PR head and re-run`])
+  }
+  if (!pathTarget && !base) {
+    base = quiet('git', ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD']).stdout?.trim()
+      || quiet('git', ['ls-remote', '--symref', 'origin', 'HEAD'], { timeout: 30000 }).stdout?.match(/^ref: refs\/heads\/(\S+)/m)?.[1]
+      || null
+    if (!base) { console.error('✗ no base: pass one (wuwei review-prep main), --pr <n>, or --path <p>'); process.exit(1) }
+  }
+  // never a local copy of the base (§1): fetch it, then diff against origin's
+  if (base) {
+    const branch = base.replace(/^origin\//, '')
+    const isSha = /^[0-9a-f]{7,40}$/.test(base)
+    if (!isSha) {
+      const f = quiet('git', ['fetch', '--quiet', 'origin', branch], { timeout: 60000 })
+      base = ok(f) ? `origin/${branch}` : base
+      facts.push(['base', ok(f) ? `origin/${branch} @ ${quiet('git', ['rev-parse', '--short', base]).stdout.trim()} (fetched)` : `${base} — **fetch failed, a local copy may be stale**`])
+    } else facts.push(['base', base])
+  }
+
+  const dir = join(process.cwd(), '.wuwei-cache', 'review', head.slice(0, 12))
+  rmSync(dir, { recursive: true, force: true })
+  mkdirSync(join(dir, 'reports'), { recursive: true })
+  mkdirSync(join(dir, 'tools'), { recursive: true })
+  if (quiet('git', ['check-ignore', '-q', '.wuwei-cache']).status !== 0)
+    facts.push(['bundle', '**`.wuwei-cache/` is not gitignored** — add it, or the bundle shows up as untracked files'])
+
+  // INDEX.md — generated, never hand-written
+  let rows
+  if (pathTarget) {
+    rows = quiet('git', ['ls-files', '--', pathTarget]).stdout.split('\n').filter(Boolean)
+      .map(path => ({ path, status: '·', add: '', del: '' }))
+    writeFileSync(join(dir, 'diff.patch'), 'none — a path target has no base\n')
+    facts.push(['target', `path ${pathTarget} — no base: merges-cleanly and tool-maintained checks skipped`])
+  } else {
+    const range = `${base}...HEAD`
+    const nums = new Map(quiet('git', ['diff', '--numstat', '-M', range]).stdout.split('\n').filter(Boolean)
+      .map(l => { const [a, d, ...p] = l.split('\t'); return [p.join('\t').replace(/.*\{.* => (.*)\}.*|.* => /, (m, x) => x ?? ''), [a, d]] }))
+    rows = quiet('git', ['diff', '--name-status', '-M', range]).stdout.split('\n').filter(Boolean).map(l => {
+      const [st, ...paths] = l.split('\t')
+      const path = paths.at(-1)
+      const [add, del] = nums.get(path) ?? ['', '']
+      return { path, status: st[0], add, del, from: paths.length > 1 ? paths[0] : null }
+    })
+    writeFileSync(join(dir, 'diff.patch'), quiet('git', ['diff', range]).stdout)
+
+    // merges cleanly
+    const mt = quiet('git', ['merge-tree', '--write-tree', '--name-only', '--no-messages', base, 'HEAD'])
+    facts.push(['merges cleanly', mt.status === 0 ? 'yes' : mt.status === 1
+      ? `**no** — conflicts: ${mt.stdout.trim().split('\n').slice(1).filter(Boolean).join(', ')}`
+      : `unknown — git merge-tree --write-tree needs git ≥ 2.38 (${firstLine(mt.stderr)})`])
+    if (pr) {
+      const files = ghAll(`repos/${repo}/pulls/${pr}/files`)
+      facts.push(['PR file count', files == null ? 'not fetched'
+        : files.length === rows.length ? `${rows.length}, matches INDEX`
+        : `**platform ${files.length}, INDEX ${rows.length} — the base is stale or the PR moved; resync before dispatch**`])
+    }
+    // tool-maintained files: deletions the change must explain
+    const tm = rows.filter(r => LOCKFILE.test(r.path) || STATE_FILE.test(r.path)).filter(r => Number(r.del) > 0)
+    facts.push(['tool-maintained deletions', tm.length ? tm.map(r => `${r.path} −${r.del}`).join(', ') + ' — check each is explained' : 'none'])
+    // author paths on added lines
+    const hits = []
+    let file = null, line = 0
+    for (const l of readFileSync(join(dir, 'diff.patch'), 'utf8').split('\n')) {
+      if (l.startsWith('+++ ')) { file = l.slice(6); continue }
+      const h = l.match(/^@@ -\d+(?:,\d+)? \+(\d+)/)
+      if (h) { line = Number(h[1]); continue }
+      if (l.startsWith('+')) { if (AUTHOR_PATH.test(l)) hits.push(`${file}:${line}`); line++ }
+      else if (!l.startsWith('-')) line++
+    }
+    facts.push(['author paths (added lines)', hits.length ? hits.join(', ') : 'none'])
+  }
+  const index = ['# INDEX', '', `reviewed: ${head} · base: ${base ?? 'none (path target)'} · ${rows.length} file(s)`,
+    'kind is a first pass by path — reclassify by content (wuwei-review §1)', '',
+    '| path | st | + | − | kind | panel |', '|---|---|---|---|---|---|',
+    ...rows.map(r => { const k = kindOf(r.path)
+      return `| ${r.from ? `${r.from} → ` : ''}${r.path} | ${r.status} | ${r.add} | ${r.del} | ${k} | ${k === 'prose' ? 'document' : 'code'} |` })]
+  writeFileSync(join(dir, 'INDEX.md'), index.join('\n') + '\n')
+
+  // CI at the reviewed sha — the verdict names the last green e2e, and this is where it starts
+  const ciRepo = repo ?? ghRepo()
+  if (ciRepo && !pathTarget) {
+    const runs = ghAll(`repos/${ciRepo}/commits/${head}/check-runs`)
+    const list = (runs ?? []).flatMap(x => x.check_runs ?? [x]).filter(x => x?.name)
+    if (runs == null) facts.push(['CI @ HEAD', 'not fetched'])
+    else if (!list.length) facts.push(['CI @ HEAD', 'no check runs at this sha'])
+    else {
+      const by = c => list.filter(x => (x.conclusion ?? x.status) === c).map(x => x.name)
+      const failed = [...by('failure'), ...by('timed_out'), ...by('cancelled')], pending = list.filter(x => x.status !== 'completed').map(x => x.name)
+      const e2e = list.filter(x => /e2e/i.test(x.name)).map(x => `${x.name}: ${x.conclusion ?? x.status}`)
+      facts.push(['CI @ HEAD', `${by('success').length} success${failed.length ? ` · **failed: ${failed.join(', ')}**` : ''}${pending.length ? ` · pending: ${pending.join(', ')}` : ''}${e2e.length ? ` · ${e2e.join(', ')}` : ' · no e2e job'}`])
+    }
+  }
+
+  // the thread since the last round
+  if (pr) {
+    const parts = [['comment', `repos/${repo}/issues/${pr}/comments`], ['review', `repos/${repo}/pulls/${pr}/reviews`], ['inline', `repos/${repo}/pulls/${pr}/comments`]]
+      .map(([type, ep]) => [type, ghAll(ep)])
+    const all = parts.flatMap(([type, list]) => (list ?? []).map(c => ({ type, user: c.user?.login, at: c.submitted_at ?? c.created_at, state: c.state, url: c.html_url, body: c.body })))
+      .sort((a, b) => (a.at ?? '').localeCompare(b.at ?? ''))
+    writeFileSync(join(dir, 'thread.json'), JSON.stringify(all, null, 2))
+    facts.push(['thread', parts.some(([, l]) => l == null) ? 'partly not fetched'
+      : `${all.length} entries (${parts.map(([t, l]) => `${l.length} ${t}`).join(', ')}), latest ${all.at(-1)?.at ?? 'none'} — thread.json`])
+    left.push('read thread.json for another review line in flight, or a rewrite that voids this round')
+  }
+
+  // tools — detect once, record versions; shared read-only output runs once
+  const tools = []
+  const cg = quiet('codegraph', ['status', '--json'])
+  if (cg.error) tools.push('codegraph: absent')
+  else {
+    let st = {}; try { st = JSON.parse(cg.stdout) } catch {}
+    tools.push(st.initialized !== true ? 'codegraph: absent — not initialized'
+      : st.worktreeMismatch ? `codegraph: absent — the index is of another tree (${JSON.stringify(st.worktreeMismatch)})`
+      : st.pendingChanges?.length ? `codegraph: absent — ${st.pendingChanges.length} pending change(s); sync before dispatch`
+      : 'codegraph: usable')
+  }
+  const sg = quiet('semgrep', ['--version'])
+  if (sg.error) tools.push('semgrep: absent')
+  else if (noScan || !base) tools.push(`semgrep ${firstLine(sg.stdout)}: not run${noScan ? ' (--no-scan)' : ' (no base)'}`)
+  else {
+    const mb = quiet('git', ['merge-base', 'HEAD', base]).stdout.trim()
+    const r = quiet('semgrep', ['scan', '--config', 'p/owasp-top-ten', '--metrics', 'off', '--json', '--baseline-commit', mb], { timeout: 600000 })
+    writeFileSync(join(dir, 'tools', 'semgrep.json'), r.stdout || '')
+    let n = null; try { n = JSON.parse(r.stdout).results.length } catch {}
+    tools.push(`semgrep ${firstLine(sg.stdout)}: ${n == null ? `**failed** (exit ${r.status}) — not "scanned clean"` : `${n} result(s) — tools/semgrep.json`}`)
+  }
+  const locks = rows.filter(r => LOCKFILE.test(r.path) && r.status !== 'D')
+  const osv = quiet('osv-scanner', ['--version'])
+  if (osv.error) tools.push(`osv-scanner: absent${locks.length ? ` — ${locks.length} lockfile(s) changed` : ''}`)
+  else if (!locks.length) tools.push('osv-scanner: n/a — no lockfile changed')
+  else if (noScan) tools.push('osv-scanner: not run (--no-scan)')
+  else for (const l of locks) {
+    // judge by exit code: 0 clean, 1 findings, anything else failed
+    const r = quiet('osv-scanner', ['scan', 'source', '--format', 'json', '--lockfile', l.path], { timeout: 600000 })
+    writeFileSync(join(dir, 'tools', `osv-${l.path.replace(/[/\\]/g, '_')}.json`), r.stdout || '')
+    tools.push(`osv-scanner ${l.path}: ${r.status === 0 ? 'clean' : r.status === 1 ? 'findings' : `**failed** (exit ${r.status})`}`)
+  }
+  const pkg = existsSync('package.json') ? JSON.parse(readFileSync('package.json', 'utf8')) : null
+  const linters = [
+    ...Object.keys(pkg?.scripts ?? {}).filter(k => /lint|check|type|test|format/i.test(k)).map(k => `npm script \`${k}\``),
+    ...['biome.json', 'biome.jsonc', 'tsconfig.json', '.eslintrc', '.eslintrc.json', 'eslint.config.js', 'eslint.config.mjs', 'ruff.toml', '.golangci.yml']
+      .filter(f => existsSync(f)),
+  ]
+  tools.push(`repo linters: ${linters.length ? linters.join(', ') : 'none found'}`)
+  // UI states: one verify run shows what a round of review finds one at a time
+  const ui = rows.filter(r => r.status !== 'D' && /\.(tsx|jsx|vue|svelte)$/.test(r.path) && !/\.(test|spec|stories)\./.test(r.path))
+  if (ui.length && existsSync(join('.wuwei', 'verify.json')))
+    left.push(`${ui.length} UI file(s) changed — \`wuwei verify\` once; its flags go to review:defects as leads`)
+  else if (ui.length) tools.push(`verify: ${ui.length} UI file(s) changed, no .wuwei/verify.json — UI states unchecked`)
+
+  left.push('reclassify INDEX rows by content where the path misleads (§1)',
+    'platform state the change depends on — env vars, deployed revisions (of what it calls too, when merging deploys it), protection, schedulers',
+    "the change's new tests, once, in a fresh worktree with no .env",
+    'name the lenses, the bundle path and the digest template in the dispatch')
+
+  const prep = ['# PREP', '', `reviewed: \`${head}\` · bundle: \`${dir}\``, '',
+    '## Facts (hand to every lens)', '', '| check | result |', '|---|---|', ...facts.map(([k, v]) => `| ${k} | ${v} |`), '',
+    '## Tools', '', ...tools.map(t => `- ${t}`), '',
+    '## Left for the dispatcher', '', ...left.map(l => `- [ ] ${l}`), '']
+  writeFileSync(join(dir, 'PREP.md'), prep.join('\n'))
+  console.log(prep.join('\n'))
+}
+
+// ── GSD / superpowers detection + one-shot verbatim import ───────────
+// GSD stores everything under .planning/ (root docs + .planning/phases/<name>/
+// with *-CONTEXT.md, *-RESEARCH.md, *-<n>-PLAN.md (+ matching *-<n>-SUMMARY.md),
+// *-VERIFICATION.md). We copy content verbatim into the shape of .wuwei/ —
+// no parsing, no reinterpretation — and flag every imported file as unreviewed.
+// Original .planning/ is never touched or deleted. Every write below is also
+// skip-if-exists: a file this import already produced once is never
+// overwritten, so re-running init can never clobber edits made since —
+// the whole point of "review before sign-off" would collapse otherwise.
+const IMPORTED_HEADER = src =>
+  `## Imported from GSD — ${src}\n\n_Verbatim copy, not restructured — review before sign-off._\n\n`
+const GSD_ROOT_FILES = ['PROJECT.md', 'STATE.md', 'ROADMAP.md', 'UAT.md']
+
+function detectGSD(dest) {
+  const planningDir = join(dest, '.planning')
+  if (!existsSync(planningDir)) return null
+  const hasRootDocs = GSD_ROOT_FILES.some(f => existsSync(join(planningDir, f)))
+  const phasesDir = join(planningDir, 'phases')
+  const phases = existsSync(phasesDir)
+    ? readdirSync(phasesDir, { withFileTypes: true }).filter(d => d.isDirectory()).map(d => d.name).sort()
+    : []
+  if (!hasRootDocs && !phases.length) return null // .planning/ exists but is empty
+  return { planningDir, phasesDir, phases }
+}
+
+function importGSDRoot(dest, planningDir, dry) {
+  const rootFiles = GSD_ROOT_FILES.filter(f => existsSync(join(planningDir, f)))
+  if (!rootFiles.length) return null
+  const file = join(dest, '.wuwei', 'imported', 'GSD-PROJECT.md')
+  if (existsSync(file)) return { file, skipped: true }
+  const body = rootFiles
+    .map(f => IMPORTED_HEADER(f) + readFileSync(join(planningDir, f), 'utf8'))
+    .join('\n\n---\n\n')
+  if (!dry) { mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, body) }
+  return { file, skipped: false }
+}
+
+// GSD's own plan-index (the number right before -PLAN.md, e.g. "01" in
+// 01-01-PLAN.md) becomes the imported filename's number, so it stays
+// traceable to the source even after renumbering across a phase's files
+function planIndex(planFile, fallback) {
+  const m = planFile.match(/-(\d+)-PLAN\.md$/i)
+  return (m ? m[1] : String(fallback)).padStart(2, '0')
+}
+
+function importGSDPhase(dest, phasesDir, phaseName, dry) {
+  const dir = join(phasesDir, phaseName)
+  const files = readdirSync(dir)
+  const read = f => readFileSync(join(dir, f), 'utf8')
+  const streamDir = join(dest, '.wuwei', 'streams', phaseName)
+  const written = []
+  const skipped = []
+
+  const context = files.find(f => /-CONTEXT\.md$/i.test(f))
+  const research = files.find(f => /-RESEARCH\.md$/i.test(f))
+  const specParts = [context, research].filter(Boolean).map(f => IMPORTED_HEADER(f) + read(f))
+  if (specParts.length) {
+    const specFile = join(streamDir, 'SPEC.md')
+    if (existsSync(specFile)) skipped.push(specFile)
+    else {
+      if (!dry) { mkdirSync(streamDir, { recursive: true }); writeFileSync(specFile, specParts.join('\n\n---\n\n')) }
+      written.push(specFile)
+    }
+  }
+
+  const plans = files.filter(f => /-PLAN\.md$/i.test(f)).sort()
+  const usedThisRun = new Set() // detects a same-run collision before it ever
+  // reaches existsSync — two plans landing on the same index must never let
+  // one silently mask the other under a misleading "already exists" skip
+  plans.forEach((planFile, i) => {
+    const base = planFile.replace(/-PLAN\.md$/i, '')
+    const summaryRe = new RegExp(`^${escapeRe(base)}-SUMMARY\\.md$`, 'i')
+    const summaryFile = files.find(f => summaryRe.test(f))
+    let n = planIndex(planFile, i + 1)
+    if (usedThisRun.has(n)) n = `${n}-${base}` // GSD's own numbering wasn't
+    // unique here — disambiguate rather than pick a winner; both land, review
+    // before sign-off is exactly where a human sorts out which is authoritative
+    usedThisRun.add(n)
+    const file = join(streamDir, 'phases', `${n}-imported.md`)
+    if (existsSync(file)) { skipped.push(file); return }
+    const parts = [IMPORTED_HEADER(planFile) + read(planFile)]
+    if (summaryFile) parts.push(IMPORTED_HEADER(summaryFile) + read(summaryFile))
+    if (!dry) { mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, parts.join('\n\n---\n\n')) }
+    written.push(file)
+  })
+
+  const verification = files.find(f => /-VERIFICATION\.md$/i.test(f))
+  if (verification) {
+    const accFile = join(streamDir, 'ACCEPTANCE.md')
+    if (existsSync(accFile)) skipped.push(accFile)
+    else {
+      const body = IMPORTED_HEADER(verification) +
+        '_Unstructured — split into critical paths / e2e / UAT / Verify / Threats before sign-off._\n\n' +
+        read(verification)
+      if (!dry) { mkdirSync(streamDir, { recursive: true }); writeFileSync(accFile, body) }
+      written.push(accFile)
+    }
+  }
+
+  return { written, skipped, phaseCount: plans.length }
+}
+
+// only inserts a fresh row — never overwrites one that exists. STATE.md is
+// human-editable (per docs/architecture.md); a stream that gained new plan
+// files since its first import will show a stale done/total here, and that's
+// the right trade: a slightly-stale count beats silently discarding whatever
+// the user has since changed on that row (mode, tracker, progress notes).
+const isTableSeparatorLine = l => /^[ \t]{0,3}\|[\s:-]+\|[\s:-]+\|/.test(l)
+
+function appendImportedStateRow(stateFile, streamName, phaseCount, dry) {
+  if (dry || !existsSync(stateFile)) return
+  const content = readFileSync(stateFile, 'utf8')
+  // anchored to the row's first cell (tolerating up to 3 leading spaces — a
+  // legal indented row is still a row), and explicitly excluding the header
+  // and separator lines — a stream literally named "stream"/"mode"/"tracker"/
+  // "blocked" would otherwise match one of those instead of a real data row
+  // and never get its own row inserted
+  const rowRe = new RegExp(`^[ \\t]{0,3}\\|\\s*${escapeRe(streamName)}\\s*\\|`)
+  const alreadyRecorded = content.split('\n').some(l =>
+    l.trim() !== STATE_HEADER_LINE && !isTableSeparatorLine(l) && rowRe.test(l))
+  if (alreadyRecorded) return
+  const row = `| ${streamName} | manual | none | 0/${phaseCount} | unreviewed GSD import |\n`
+  writeFileSync(stateFile, content.replace(/\n*$/, '\n') + row)
+}
+
+// superpowers ships as .claude/skills/<name>/SKILL.md — behavior, not project
+// state, so there's nothing to migrate. We only flag the overlap so the user
+// can decide whether to keep both firing on the same triggers. Not an
+// exhaustive catalog of superpowers — just the skills wuwei itself credits
+// (docs/product.md), checked in both the target project and the user's own
+// ~/.claude/skills (where a personally-installed superpowers usually lives).
+const SUPERPOWERS_OVERLAP = [
+  { name: 'brainstorming', wuwei: 'wuwei-brainstorm' },
+  { name: 'subagent-driven-development', wuwei: 'wuwei-execute-phase (SDD mode)' },
+  { name: 'test-driven-development', wuwei: 'wuwei-tdd' },
+  { name: 'systematic-debugging', wuwei: 'wuwei-debug-root-cause' },
+]
+
+function detectSuperpowersOverlap(dest) {
+  const userSkills = join(homedir(), '.claude', 'skills')
+  const scopes = [{ dir: join(dest, '.claude', 'skills'), label: 'project' }, { dir: userSkills, label: 'user' }]
+  const found = new Map() // dedupe by name if it exists in both scopes
+  for (const { dir, label } of scopes) {
+    if (!existsSync(dir)) continue
+    for (const sp of SUPERPOWERS_OVERLAP)
+      if (!found.has(sp.name) && existsSync(join(dir, sp.name, 'SKILL.md')))
+        found.set(sp.name, { ...sp, scope: label })
+  }
+  return [...found.values()]
+}
+
+// codegraph (github.com/colbymchenry/codegraph, npm @colbymchenry/codegraph)
+// is the local code-graph MCP server wuwei-map-codebase prefers as its
+// evidence source over static Glob/Grep scanning. wuwei does not hand-roll
+// per-tool MCP config for it — codegraph's own docs defer everything but a
+// manual Claude Code example to its own cross-client `codegraph install`,
+// and guessing at Cursor/Codex/Gemini/Antigravity's exact config shape here
+// would be the same mistake that produced .planning/ and CONCERNS.md: acting
+// on an unverified assumption instead of the tool's own authority. We only
+// detect and offer to run codegraph's own installer.
+function isCodegraphIndexed(dest) {
+  return existsSync(join(dest, '.codegraph'))
+}
+
+const CODEGRAPH_DOCS = 'https://colbymchenry.github.io/codegraph/reference/cli/'
+
+// codegraph keeps a SQLite graph under .codegraph/ and manages a .gitignore
+// inside it; an older version's ignore did not cover the directory itself, so
+// repos indexed back then can have it committed. Once tracked, every branch
+// mutates one binary file and every merge conflicts with no way to resolve it
+// — which is exactly the state parallel phase branches produce. Cheap to
+// detect, so detect it rather than let a stream discover it at merge time.
+function codegraphTrackedFiles(dest) {
+  const result = runGit(['ls-files', '--', '.codegraph'], { cwd: dest, encoding: 'utf8' })
+  if (result.status !== 0) return [] // not a git repo, or no git — nothing to claim
+  return (result.stdout ?? '').split('\n').map(l => l.trim()).filter(Boolean)
+}
+
+// wuwei's uninstall removes exactly what wuwei stamped — that is the point of
+// the stamp, and exactly why it cannot itself delete codegraph's index or the
+// MCP config codegraph wrote into every client. But `init` offers to *run*
+// codegraph's installer, so leaving removal as a paragraph to read would make
+// getting in one keystroke and getting out a documentation exercise. Same
+// shape as the `npm uninstall -g` offer above: detect, offer, defer to the
+// tool's own command, and never do it unasked.
+async function offerCodegraphRemoval(scope, dest) {
+  const repo = scope === 'repo'
+  if (repo ? !isCodegraphIndexed(dest) : !isCodegraphGloballyInstalled()) return
+
+  const args = repo
+    ? ['@colbymchenry/codegraph', 'uninit']
+    : ['@colbymchenry/codegraph', 'uninstall']
+  const manualHint = repo
+    ? 'drop it yourself anytime:\n    npx @colbymchenry/codegraph uninit\n' +
+      `    ${CODEGRAPH_DOCS}`
+    : 'remove it yourself anytime:\n' +
+      '    npx @colbymchenry/codegraph uninstall              # clients + CLI\n' +
+      '    npx @colbymchenry/codegraph uninstall --keep-cli   # client config only\n' +
+      `    ${CODEGRAPH_DOCS}`
+  const preamble = repo
+    ? '\ncodegraph indexed this project (.codegraph/) — wuwei did not write it,' +
+      ' so this\nis its own command, not ours.'
+    : '\ncodegraph is still installed and still wired into your clients — wuwei' +
+      ' never\nwrote that config, so this is its own command, not ours.'
+  console.log(preamble)
+
+  if (!isInteractive()) {
+    console.log(`    ${manualHint}`)
+    return
+  }
+  // default no: this deletes, and outside this project's scope in the user
+  // case — other projects may still be using the graph we are about to remove
+  const question = repo
+    ? 'Run codegraph uninit to drop this project\'s index?'
+    : 'Run codegraph\'s own uninstaller (removes it from every client AND' +
+      ' uninstalls the CLI — affects your other projects too)?'
+  if (!await promptYesNo(question)) {
+    console.log(`kept — ${manualHint}`)
+    return
+  }
+  const result = runNpx(args, repo ? { cwd: dest, stdio: 'inherit' } : { stdio: 'inherit' })
+  console.log(result.status === 0
+    ? (repo ? 'done — this project is no longer indexed.' : 'done — codegraph is removed.')
+    : `\nthat failed${result.error ? '' : ` (exit ${result.status})`} — ${manualHint}`)
+}
+
+// same ask-npm-directly discipline as isGloballyLinked — global bin locations
+// vary, so never infer one from a path guess
+function isCodegraphGloballyInstalled() {
+  const result = runNpm(['root', '-g'], { encoding: 'utf8' })
+  const globalRoot = result.stdout?.trim()
+  return result.status === 0 && !!globalRoot
+    && existsSync(join(globalRoot, '@colbymchenry', 'codegraph'))
+}
+
+// A fresh scaffold and an inherited codebase need different first moves, and
+// the difference is decidable: what does the repo already track that wuwei did
+// not just write? Manifests are checked too, because a repo can hold real code
+// and no commits yet (first push pending), and because "has a manifest" is the
+// cheap answer where git is absent entirely.
+const MANIFESTS = [
+  'package.json', 'go.mod', 'pyproject.toml', 'requirements.txt', 'Cargo.toml',
+  'pom.xml', 'build.gradle', 'build.gradle.kts', 'Gemfile', 'composer.json',
+  'pubspec.yaml', 'mix.exs', '*.csproj',
+]
+const WUWEI_OWNED = /^(\.wuwei\/|\.github\/PULL_REQUEST_TEMPLATE\.md$|\.claude\/|CLAUDE\.md$|AGENTS\.md$)/
+
+function isExistingProject(dest) {
+  if (MANIFESTS.some(m => !m.includes('*') && existsSync(join(dest, m)))) return true
+  const r = runGit(['ls-files'], { cwd: dest, encoding: 'utf8' })
+  if (r.status !== 0) return false // not a git repo and no manifest — treat as fresh
+  return (r.stdout ?? '')
+    .split('\n')
+    .map(l => l.trim())
+    .filter(Boolean)
+    .some(f => !WUWEI_OWNED.test(f))
+}
+
+async function offerCodegraphSetup(dest, dry, existing) {
+  if (dry) return
+  // nothing to index yet: offering a code graph for a repo with no code is a
+  // question whose answer cannot matter until there is code
+  if (!existing) return
+  // an index already committed is worse than no index: flag it before the
+  // "already indexed, nothing to do" early return swallows the whole check
+  const tracked = codegraphTrackedFiles(dest)
+  if (tracked.length) {
+    console.log(`\n.codegraph/ is tracked by git (${tracked.length} file(s)). Parallel phase` +
+      ' branches each\nrewrite that index, and the merge conflicts are binary — there is' +
+      ' nothing to\nresolve. Untrack it:\n' +
+      '    git rm -r --cached .codegraph && echo .codegraph/ >> .gitignore')
+  }
+  if (isCodegraphIndexed(dest)) return
+  const manualHint = 'set it up yourself anytime:\n' +
+    '    npx @colbymchenry/codegraph install && npx @colbymchenry/codegraph init'
+  console.log('\nno codegraph index found for this project.' +
+    ' wuwei queries a code graph in four places:\n' +
+    '    wuwei-map-codebase     architecture edges from real imports/calls\n' +
+    '    wuwei-plan-phases      research, so a phase\'s depends-on is not guessed\n' +
+    '    review:design/defects  blast radius, and call sites left behind\n' +
+    '    audit:security         reachability of a new sink\n' +
+    '\n' +
+    '  All four still run on Grep without it, and each says which path it took.\n' +
+    '  The one hard consequence: reachability sets security severity, so with\n' +
+    '  no graph a finding cannot be rated HIGH — only MED, reachability\n' +
+    '  unproven. Worth knowing before skipping this.')
+  if (!isInteractive()) {
+    console.log(`    ${manualHint}`)
+    return
+  }
+  const ask = 'Set up codegraph now (its own installer wires every detected' +
+    ' client, then indexes this project)?'
+  // recommended yes: it is what every graph-reading step wants, and codegraph
+  // ships its own uninstall/uninit, so this is reversible by the tool that did it
+  let setUp = await promptYesNo(ask, true)
+  if (!setUp) {
+    // one re-ask, not a nag: name the concrete loss, then default to the answer
+    // already given, so a bare Enter confirms the refusal instead of reversing it
+    console.log('\n  concretely, that turns this off: audit:security can no' +
+      ' longer prove a\n  sink is reachable, so no security finding in this' +
+      ' project will be rated\n  HIGH — every one caps at MED, "reachability' +
+      ' unproven".')
+    const stillSkip = await promptYesNo('  Still skip codegraph?', true)
+    setUp = !stillSkip
+  }
+  if (!setUp) {
+    console.log('skipped — this is a third-party tool wuwei defers to, never' +
+      ' re-implements, so its installer stays its own call. ' + manualHint)
+    return
+  }
+  const install = runNpx(['@colbymchenry/codegraph', 'install'], { stdio: 'inherit' })
+  if (install.status !== 0) {
+    console.log(`\ninstall step failed${install.error ? '' : ` (exit ${install.status})`} — ${manualHint}`)
+    return
+  }
+  const init = runNpx(['@colbymchenry/codegraph', 'init'], { cwd: dest, stdio: 'inherit' })
+  console.log(init.status === 0
+    ? 'done — codegraph is indexed; every graph-reading step will use it next run.'
+    : `\ninit step failed${init.error ? '' : ` (exit ${init.status})`} — ${manualHint}`)
+}
+
+// `def` is what a bare Enter means. It stays false for anything that removes,
+// installs globally, or writes outside this repo — a mis-hit Enter must never
+// be the thing that does one of those. It is true only where the recommended
+// answer is yes and the action is reversible by the tool that performs it.
+// ── security scanners ────────────────────────────────────────────────
+// The security lens reads a diff and reasons about it. Two tools answer parts
+// of that deterministically — "does this line concatenate SQL" is a rule
+// match, "does this version have a known CVE" is a database lookup — and the
+// agent then judges reachability and exploitability, which is the half it is
+// actually better at. Absent, the audit still runs and says it was inference.
+// wuwei never bundles or reimplements either; it offers the vendor's own
+// documented install and gets out of the way.
+const SCANNERS = [
+  {
+    bin: 'semgrep',
+    buys: 'OWASP Top 10 pattern scan of the diff, instead of the auditor eyeballing for injection and hard-coded secrets',
+    note: 'LGPL-2.1, no account. The OSS engine is single-file; cross-file analysis is a paid tier, so reachability still comes from the code graph either way.',
+    docs: 'https://semgrep.dev/docs/getting-started/quickstart',
+  },
+  {
+    bin: 'osv-scanner',
+    buys: 'known CVEs in new dependencies, looked up in the OSV database instead of guessed from the manifest',
+    note: 'Apache-2.0, Google, single static binary. Works fully offline with --offline --download-offline-databases.',
+    docs: 'https://google.github.io/osv-scanner/installation/',
+  },
+]
+
+const onPath = bin => {
+  const probe = process.platform === 'win32' ? 'where' : 'which'
+  const r = spawnSync(probe, [bin], { stdio: 'ignore', shell: process.platform === 'win32' })
+  return r.status === 0
+}
+
+// Only ever return a command we have grounds to believe in: a package manager
+// that is actually present, or — for osv-scanner — the release asset naming
+// that was checked against every platform GitHub publishes. Anything else
+// returns null and the user gets the vendor's docs instead of a guess.
+function installPlan(bin) {
+  if (bin === 'semgrep') {
+    if (onPath('pipx')) return { label: 'pipx install semgrep', run: ['pipx', ['install', 'semgrep']] }
+    if (onPath('brew')) return { label: 'brew install semgrep', run: ['brew', ['install', 'semgrep']] }
+    if (onPath('python3')) return {
+      label: 'python3 -m pip install --user semgrep',
+      run: ['python3', ['-m', 'pip', 'install', '--user', 'semgrep']],
+    }
+    return null
+  }
+  if (onPath('brew')) return { label: 'brew install osv-scanner', run: ['brew', ['install', 'osv-scanner']] }
+  const asset = OSV_ASSETS[`${process.platform}-${process.arch}`]
+  if (!asset) return null
+  const dest = join(homedir(), '.local', 'bin', process.platform === 'win32' ? 'osv-scanner.exe' : 'osv-scanner')
+  return {
+    label: `download ${asset} → ${dest}`,
+    note: 'ensure ~/.local/bin is on your PATH',
+    download: { url: `https://github.com/google/osv-scanner/releases/latest/download/${asset}`, dest },
+  }
+}
+
+const OSV_ASSETS = {
+  'linux-x64': 'osv-scanner_linux_amd64',
+  'linux-arm64': 'osv-scanner_linux_arm64',
+  'darwin-x64': 'osv-scanner_darwin_amd64',
+  'darwin-arm64': 'osv-scanner_darwin_arm64',
+  'win32-x64': 'osv-scanner_windows_amd64.exe',
+}
+
+async function offerScannerSetup(dry) {
+  if (dry) return
+  const missing = SCANNERS.filter(s => !onPath(s.bin))
+  if (!missing.length) return
+
+  console.log('\nthe security lens in `wuwei-execute-phase` reads the diff and reasons' +
+    ' about it.\nthese answer part of that from evidence instead:')
+  for (const s of missing) console.log(`    ${s.bin.padEnd(13)} ${s.buys}`)
+  console.log(`  ${missing.length > 1 ? 'Neither is' : 'It is not'} required — without` +
+    ' them the audit still runs and opens by saying\n  it is inference, not a rule' +
+    ' engine. wuwei installs nothing unasked.')
+
+  for (const s of missing) {
+    const plan = installPlan(s.bin)
+    console.log(`\n  ${s.bin} — ${s.note}`)
+    if (!plan) {
+      console.log(`    no install channel detected on this machine — see ${s.docs}`)
+      continue
+    }
+    if (!isInteractive()) { console.log(`    ${plan.label}\n    ${s.docs}`); continue }
+    // recommended yes, and every path here is undone by `wuwei uninstall`
+    if (!await promptYesNo(`  Install ${s.bin}? (${plan.label})`, true)) {
+      console.log(`    skipped — ${plan.label}  ·  ${s.docs}`)
+      continue
+    }
+    const ok = plan.download ? downloadBinary(plan.download) : runCmd(plan.run[0], plan.run[1], { stdio: 'inherit' }).status === 0
+    console.log(ok
+      ? `    done — ${s.bin} installed.${plan.note ? ` ${plan.note}` : ''}`
+      : `    that failed — ${plan.label}  ·  ${s.docs}`)
+  }
+}
+
+function downloadBinary({ url, dest }) {
+  mkdirSync(dirname(dest), { recursive: true })
+  const r = runCmd('curl', ['-sSL', '--fail', '-o', dest, url])
+  if (r.status !== 0) return false
+  try { chmodSync(dest, 0o755) } catch { return }
+  return true
+}
+
+// Mirror of the offer: wuwei suggested these, so it says how they come back
+// out. It never removes them unasked, and never guesses a removal it cannot
+// justify from where the binary actually sits.
+async function offerScannerRemoval() {
+  const present = SCANNERS.filter(s => onPath(s.bin))
+  if (!present.length) return
+  console.log('\nsecurity scanners wuwei suggested are still installed. They are' +
+    ' machine-wide\nand other projects may use them, so nothing here is removed unasked.')
+  for (const s of present) {
+    const plan = removalPlan(s.bin)
+    if (!plan) { console.log(`    ${s.bin} — installed outside anything wuwei can identify; remove it with whatever installed it`); continue }
+    if (!isInteractive()) { console.log(`    ${s.bin} — ${plan.label}`); continue }
+    // default no: this deletes, and something else on this machine may want it
+    if (!await promptYesNo(`  Remove ${s.bin}? (${plan.label})`, false)) {
+      console.log(`    kept — ${plan.label}`)
+      continue
+    }
+    const ok = plan.file
+      ? (() => { try { rmSync(plan.file); return true } catch { return } })()
+      : runCmd(plan.run[0], plan.run[1], { stdio: 'inherit' }).status === 0
+    console.log(ok ? `    done — ${s.bin} removed.` : `    that failed — ${plan.label}`)
+  }
+}
+
+function removalPlan(bin) {
+  const probe = process.platform === 'win32' ? 'where' : 'which'
+  const where = spawnSync(probe, [bin], { encoding: 'utf8', shell: process.platform === 'win32' })
+  const path = (where.stdout ?? '').split('\n')[0].trim()
+  if (bin === 'osv-scanner' && path.startsWith(join(homedir(), '.local', 'bin')))
+    return { label: `delete ${path}`, file: path }
+  if (path.includes('/Cellar/') || path.includes('/homebrew/'))
+    return { label: `brew uninstall ${bin}`, run: ['brew', ['uninstall', bin]] }
+  if (bin === 'semgrep' && onPath('pipx') && path.includes('pipx'))
+    return { label: 'pipx uninstall semgrep', run: ['pipx', ['uninstall', 'semgrep']] }
+  if (bin === 'semgrep' && onPath('python3'))
+    return { label: 'python3 -m pip uninstall -y semgrep', run: ['python3', ['-m', 'pip', 'uninstall', '-y', 'semgrep']] }
+  return null
+}
+
+async function promptYesNo(question, def = false) {
+  if (!isInteractive()) return false // non-interactive: never hang, default to no
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    const answer = (await rl.question(`${question} ${def ? '[Y/n]' : '[y/N]'} `)).trim()
+    if (!answer) return def
+    return /^y(es)?$/i.test(answer)
+  } catch { // Ctrl-D (EOF) rejects the pending question with an AbortError — treat as the default
+    return def
+  } finally {
+    rl.close()
+  }
+}
+
+async function promptText(question, def = '') {
+  if (!isInteractive()) return def
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  try { return (await rl.question(`${question}${def ? ` [${def}]` : ''} `)).trim() || def } catch { return def } finally { rl.close() }
+}
+
+// ── Codex: a skill cannot set its model — the session is started with one.
+// So execute's tier on Codex is a profile in $CODEX_HOME/config.toml that the
+// session is launched under (codex --profile wuwei-execute); init offers to
+// write it, claim prints how to start. Effort values: codex-rs ReasoningEffort
+const CODEX_PROFILE = 'wuwei-execute'
+const CODEX_EFFORTS = ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra', 'persistent']
+const CODEX_PROFILE_MARK = '# added by wuwei init — wuwei-execute-phase runs under this profile; `wuwei uninstall` removes it'
+const codexConfigPath = () => join(codexHome(), 'config.toml')
+// [profiles.wuwei-execute]'s model and effort, or null; plus the top-level model
+function codexProfile() {
+  const text = existsSync(codexConfigPath()) ? readFileSync(codexConfigPath(), 'utf8') : ''
+  const sec = text.split(/^(?=\[)/m).find(s => new RegExp(`^\\[profiles\\.(?:"${CODEX_PROFILE}"|${CODEX_PROFILE})\\]`).test(s))
+  const val = (s, k) => s?.match(new RegExp(`^${k}\\s*=\\s*"([^"]*)"`, 'm'))?.[1] ?? null
+  const top = text.split(/^\[/m)[0]
+  return { profile: sec ? { model: val(sec, 'model'), effort: val(sec, 'model_reasoning_effort') } : null, topModel: val(top, 'model') }
+}
+const codexLaunch = (model, effort) => `codex -m ${model} -c model_reasoning_effort=${effort}`
+
+async function offerCodexProfile(dry) {
+  if (!existsSync(codexHome())) return
+  const { profile, topModel } = codexProfile()
+  if (profile) { console.log(`
+codex: profile ${CODEX_PROFILE} — ${profile.model ?? '(model unset)'} / ${profile.effort ?? '(effort unset)'} · start execute with \`codex --profile ${CODEX_PROFILE}\``); return }
+  const snippet = m => [CODEX_PROFILE_MARK, `[profiles.${CODEX_PROFILE}]`, `model = "${m.model}"`, `model_reasoning_effort = "${m.effort}"`].join('\n')
+  console.log(`
+codex: a skill can't choose Codex's model — the session is started with one. wuwei-execute-phase runs under a profile you launch it with.`)
+  if (!isInteractive()) { console.log(`    add to ${codexConfigPath()}:\n${snippet({ model: '<model>', effort: 'xhigh' }).replace(/^/gm, '        ')}`); return }
+  if (!await promptYesNo(`  Add [profiles.${CODEX_PROFILE}] to ${codexConfigPath()}?`, true)) { console.log('  skipped — re-run `wuwei init` anytime'); return }
+  const model = await promptText('  model for execute:', topModel ?? '')
+  let effort = await promptText(`  reasoning effort (${CODEX_EFFORTS.join('|')}):`, 'xhigh')
+  if (!model || !CODEX_EFFORTS.includes(effort)) { console.log(`  ✗ ${!model ? 'no model given' : `effort must be one of ${CODEX_EFFORTS.join('|')}`} — nothing written`); return }
+  if (dry) { console.log(`  [dry] would append:\n${snippet({ model, effort }).replace(/^/gm, '    ')}`); return }
+  const prev = existsSync(codexConfigPath()) ? readFileSync(codexConfigPath(), 'utf8') : ''
+  writeFileSync(codexConfigPath(), (prev ? prev.replace(/\n*$/, '\n\n') : '') + snippet({ model, effort }) + '\n')
+  console.log(`  ✓ written · start execute with \`codex --profile ${CODEX_PROFILE}\`, and write \`codex: ${model} / ${effort}\` under the stream's ## Sign-off`)
+}
+
+// only the section init wrote (its marker line above it), never one you made
+function removeCodexProfile() {
+  if (!existsSync(codexConfigPath())) return false
+  const text = readFileSync(codexConfigPath(), 'utf8')
+  const re = new RegExp(`\\n*${escapeRe(CODEX_PROFILE_MARK)}\\n\\[profiles\\.${CODEX_PROFILE}\\][^\\[]*`)
+  if (!re.test(text)) return false
+  writeFileSync(codexConfigPath(), text.replace(re, '\n').replace(/^\n+/, '').replace(/\n*$/, '\n'))
+  return true
+}
+
+async function cmdInit(target, dry) {
+  // bootstrap a project: repo-scope install into the target (default: cwd) —
+  // the entrypoint `npx <pkg> init` runs from anywhere, package files as ROOT
+  const dest = resolve(target ?? process.cwd())
+  await cmdInstall(dest, dry)
+
+  const gsd = detectGSD(dest)
+  if (gsd) {
+    const signal = gsd.phases.length
+      ? `${gsd.phases.length} phase(s) under .planning/phases/`
+      : 'project docs under .planning/ (no phases yet)'
+    console.log(`\ndetected GSD planning state: ${signal}`)
+    const doImport = await promptYesNo(
+      'Import into .wuwei/ as streams? (verbatim copy; .planning/ and any already-imported files are left untouched)')
+    if (doImport) {
+      const pfx = dry ? '[dry] ' : ''
+      const root = importGSDRoot(dest, gsd.planningDir, dry)
+      if (root) console.log(`    ${pfx}${root.file}${root.skipped ? ' (already exists, skipped)' : ''}`)
+      let anySkipped = root?.skipped ?? false
+      for (const phase of gsd.phases) {
+        const { written, skipped, phaseCount } = importGSDPhase(dest, gsd.phasesDir, phase, dry)
+        for (const w of written) console.log(`    ${pfx}${w}`)
+        for (const s of skipped) console.log(`    ${s} (already exists, skipped)`)
+        if (skipped.length) anySkipped = true
+        appendImportedStateRow(join(dest, '.wuwei', 'STATE.md'), phase, phaseCount, dry)
+      }
+      if (gsd.phases.length) console.log(`${pfx}imported ${gsd.phases.length} phase(s) as stream(s) — mode: manual, flagged unreviewed`)
+      else if (root) console.log(`${pfx}imported GSD project docs — no phases to import yet`)
+      if (anySkipped) console.log('    some files already existed and were left untouched — delete one yourself and re-run to pick up newer GSD content (safe to leave alone if you already reviewed/edited it)')
+    } else {
+      console.log('skipped — re-run `wuwei init` anytime to import later')
+    }
+  }
+
+  const existing = isExistingProject(dest)
+  const overlaps = detectSuperpowersOverlap(dest)
+  if (overlaps.length) {
+    console.log('\ndetected superpowers skills that overlap wuwei\'s own (not an exhaustive check) — nothing changed, just flagging:')
+    for (const o of overlaps) console.log(`    ${o.name} (superpowers, ${o.scope} scope) ↔ ${o.wuwei}`)
+    console.log('    consider disabling one side so the same situation doesn\'t trigger twice.')
+  }
+
+  await offerCodegraphSetup(dest, dry, existing)
+  await offerScannerSetup(dry)
+  await offerCodexProfile(dry)
+
+  const installHint = isSkillsInstalled()
+    ? ''
+    : '\n    wuwei install            # once per machine — disciplines into ~/.claude'
+  console.log(`
+next steps — the cycle is grill → brainstorm → plan → execute:${installHint}${existing
+    ? `
+    1. wuwei-map-codebase    # orient first → .wuwei/codebase/MAP.md. Planning
+                             #   slices phases from this; a guessed dependency
+                             #   graph makes \`depends-on\` wrong, and the whole
+                             #   execution order rests on that one field
+    2. wuwei-grill           # then interrogate the requirement — no solutions yet
+    3. wuwei-brainstorm      # approaches, converged with recorded reasons
+    4. wuwei-plan-phases     # phases + acceptance contract → sign-off`
+    : `
+    1. wuwei-grill           # interrogate the requirement first — no solutions yet
+    2. wuwei-brainstorm      # approaches, converged with recorded reasons
+    3. wuwei-plan-phases     # phases + acceptance contract → sign-off`}`)
+}
+
+const [, , cmd = 'build', ...rest] = process.argv
+const dry = rest.includes('--dry')
+const arg = rest.filter(a => !a.startsWith('--'))[0]
+noticeUpdate(cmd)
+switch (cmd) {
+  case '-v': case '--version': case 'version': console.log(PKG.version); break
+  case '__update-check': cmdUpdateCheck(); break
+  case 'build': cmdBuild(dry); break
+  case 'check': cmdCheck(); break
+  case 'list': cmdList(); break
+  case 'init': await cmdInit(arg, dry); break
+  case 'install': await cmdInstall(arg, dry); break
+  case 'update': await cmdUpdate(dry, rest.includes('--no-fetch')); break
+  case 'status': cmdStatus(arg); break
+  case 'review-prep': cmdReviewPrep(rest); break
+  case 'verify': await cmdVerify(rest); break
+  case 'claim': cmdClaim(rest); break
+  case 'digest-check': cmdDigestCheck(rest); break
+  case 'worktree': cmdWorktree(rest); break
+  case 'mutate': cmdMutate(rest); break
+  case 'sites': cmdSites(rest); break
+  case 'plan-check': cmdPlanCheck(rest); break
+  case 'uninstall': await cmdUninstall(arg); break
+  default:
+    console.error(`unknown command '${cmd}'\nusage: wuwei [build|check|list|init [path]|install [path]|update|status [path]|review-prep [base] [--pr n] [--path p]|verify [page] [--phase NN]|claim [stream] [phase]|digest-check <digest.md>|worktree <lens> [sha]|mutate <file>:<line>|sites <pattern>|plan-check [stream]|uninstall [path]|--version] [--dry]`)
+    process.exit(1)
+}