@tianhai/pi-workflow-kit 2.8.0 → 2.11.0

package/README.md

@@ -12,6 +12,8 @@ AI coding agents tend to skip design and jump straight into implementation, prod
 pi install npm:@tianhai/pi-workflow-kit
 ```
 
+The deterministic helpers — design validation, the review packet, the progress writer, the section extractor, and the staging check — are dependency-free Node scripts. No Python is required.
+
 For Pi delegation providers that discover project agents, install the canonical PWK roles before starting a gated workflow:
 
 ```text
@@ -80,6 +82,10 @@ A **design doc is one PR**; a **requirement is one testable slice within it**. *
 | **Walkthrough** | `/skill:pwk-walkthrough` | On demand: generate a detailed, file:line-anchored walkthrough of a shipped feature into `docs/walkthroughs/<topic>.md` (Summary / How it works / Key flows / Gotchas & invariants / Change map); stamped with the commit range, regenerated wholesale, never disposed. **Exits the gated phase** |
 | **Status** | `/skill:pwk-status` | Read-only overview of all active design topics — phase + progress. Use when resuming or juggling several designs in parallel worktrees. Not a pipeline phase; **does not exit the gated phase**. |
 
+### ⚡ Batched tool calls (pi ≥ 1.0.0 `codemode`)
+
+Every skill treats its shell recipes as fallbacks: when the host grants a sandboxed batch executor, the kit prefers it — on pi ≥ 1.0.0 that is `codemode` (turn it on via pi's "Enable codemode" settings documentation; the guard announces it once per session when active, and the discovery sweeps demonstrate the one-call shape). The dated cross-harness instance table — opencode's `execute`, Claude's Programmatic Tool Calling, and the verified absences — lives in `docs/developer-usage-guide.md`. On hosts without such a tool, the bash recipes are the path and nothing changes.
+
 ## The Workflow in Detail
 
 ### Phase Control
@@ -97,6 +103,8 @@ You control each phase — the agent never advances on its own. Invoke a skill t
 
 The design doc specifies *what*, not *how*. Each `### R<n>:` requirement block gives **acceptance criteria** (Given/When/Then, edge and error cases included) — no implementation code, no file-by-file recipe, no test-name lists. The executor has full autonomy to choose structure, signatures, and internals. A fine-grained implementation plan invalidates the moment a detail shifts; acceptance criteria survive implementation changes.
 
+Brainstorm opens with a **PRD brief** when source material exists — background, current situation, and the delta, cited and zero-context, corrected by you before any requirement is written. Unknowns settle by **decide-by-experiment**: a question a run can answer is answered by a bounded sketch, never guessed. A criterion passes the **probe test**: its `Then` names an outcome a command can observe.
+
 ### Feature-Gate Execution
 
 The feature is implemented via the feature-gate flow:
@@ -105,7 +113,7 @@ The feature is implemented via the feature-gate flow:
 2. **Report it — no stop** — one or two lines saying what the E2E proves, plus its failing output; the run continues straight into implementation (that text was already approved as `## Feature acceptance` during brainstorm, so this is the window to object before code is written, not a sign-off gate)
 3. Implement the requirements back-to-back (TDD: meaningful test → red → green per slice; full autonomy)
 4. Feature review — risk-scaled: four fresh-context roles over a script-assembled review packet when the design carries production-risk content, otherwise one inline pass
-5. ⏸ **ship checkpoint** — full suite + feature E2E green; you review the execution summary + coverage table (full diff on request)
+5. ⏸ **ship checkpoint** — full suite + feature E2E green; you review the execution summary **Evidence rows** (plain words + pointer per requirement) + coverage table (full diff on request)
 
 Per-requirement checkpoints/reviews are opt-in (default off); the feature-level review covers everything.
 
@@ -142,6 +150,10 @@ The agent stops and waits there — approve, request changes, or send it back. T
 
 The feature-level review checks the whole diff composed and runs **before** the **ship checkpoint** — so your one final approval is fully informed (execution summary + coverage table; the raw diff stays one command away). The ship checkpoint already ran the full suite + the feature-acceptance E2E green — that *is* the integration check (there is no separate end pass). Finalize re-runs the full suite too — it never ships a red suite, even across resumed sessions.
 
+### Skill-Text Budgets
+
+The skill text a host loads is ratcheted. `skill-lint` holds a per-file word budget — the measured count plus 10% headroom, rounded up — and a corpus ceiling, and fails by file name and count when either is exceeded, so a slimming pass cannot quietly undo itself. The numbers come from measurement rather than a target percentage (ADR 0010). Each release's claim is checked by a recorded fidelity probe: six authorized sessions comparing the kit before and after on one fixture task, with the transcripts committed and the token totals recomputed from raw usage lines (`tests/evals/skill-slimming/`).
+
 ## Quick Start
 
 ```bash

package/docs/developer-usage-guide.md

@@ -34,7 +34,7 @@ Or in `.pi/settings.json` / `~/.pi/agent/config.json`:
 
 ## The workflow
 
-You control each phase by invoking the skill. One folder per topic: `docs/plans/<date>-<topic>/` holds the topic's design doc, progress file, and review packet, and is the unit disposed at finalize. A design doc is one PR; a requirement is one testable slice within it. A requirement too big for one design doc but shipping as one PR is an **umbrella** — more than one leaf in that same folder, under one status-free overview, on one branch, finalized once:
+You control each phase by invoking the skill. Requirements are grounded in evidence: a **PRD brief** opens brainstorm when source material exists, unknowns settle by **decide-by-experiment** (bounded sketch, proof clause), criteria pass the **probe test** (their `Then` names an outcome a command can observe), and the execution summary's **Evidence rows** pair plain words with a pointer — nothing is ✅ without one. One folder per topic: `docs/plans/<date>-<topic>/` holds the topic's design doc, progress file, and review packet, and is the unit disposed at finalize. A design doc is one PR; a requirement is one testable slice within it. A requirement too big for one design doc but shipping as one PR is an **umbrella** — more than one leaf in that same folder, under one status-free overview, on one branch, finalized once:
 
 ```
 /skill:pwk-brainstorming  →  /skill:pwk-executing-tasks  →  /skill:pwk-finalizing
@@ -110,6 +110,23 @@ The destructive blacklist covers common file-mutating vectors (redirects, `tee`,
 
 No configuration needed. It activates automatically after install.
 
+## Sandboxed batch executors — known instances
+
+Every skill treats its shell recipes as fallbacks: when the host grants a sandboxed batch executor (a tool that runs a script calling the agent's other tools, batching calls and filtering output before the model sees it), the skills prefer it. On pi ≥ 1.0.0 that executor is `codemode`, and the four discovery-sweep sites demonstrate the shape with a byte-pinned canonical script. Translate the shape, not the syntax: the scripts call tools by name, so they read correctly whether the host declares tools directly (pi's default) or hides them behind the executor (Claude Code's REPL mode hides its REPL-only tools; pi's `codemode.mode: only` does the same). Pinned command strings — the kit's `scripts/` helpers, plain `git`, the pinned `grep -m1 '^Feature phase:'` extraction — stay byte-exact even when batched inside one executor call; the pin protects the command string, not the vehicle.
+
+Verified instances and absences, each dated so staleness is self-declaring rather than silently wrong:
+
+| Host | Executor | Status (verified 2026-09-29) |
+|------|----------|------------------------------|
+| pi ≥ 1.0.0 | `codemode` | Shipped, opt-in via settings — see pi's "Enable codemode" documentation (verified 2026-09-29) |
+| opencode v2 | `execute` ("Code Mode") | Shipped, gated by the `execute` permission (verified 2026-09-29) |
+| Claude Platform API | Programmatic Tool Calling (`code_execution_20260120`+) | GA — code-execution container calling tools programmatically (verified 2026-09-29) |
+| Claude Code CLI | REPL mode (`REPLTool`) | Experimental env-flag, source-verified, undocumented as of 2026-09-29 |
+| zcode | — | Absent as of 2026-09-29 (CLI closed-source; docs silent) |
+| commandcode | — | Absent as of 2026-09-29 (tool reference verified) |
+
+A present instance names the concrete tool to prefer; an absent one means the bash recipes are the path — the skills read identically either way, and the dated rows tell a future reader when to re-verify.
+
 ## Test-first discipline
 
 Design docs specify *what* (acceptance criteria + end-to-end scenarios); the executor writes the feature-acceptance E2E first (red), then implements to green. This keeps the spec stable — implementation details can change without invalidating the design.

package/docs/workflow-phases.md

@@ -3,11 +3,11 @@
 Phase skills keep detailed contracts local to their skill directories:
 `skills/pwk-brainstorming/references/umbrella.md`,
 `skills/pwk-brainstorming/references/design-format.md`, and
-`skills/pwk-brainstorming/scripts/validate-design.py`; plus
+`skills/pwk-brainstorming/scripts/validate-design.mjs`; plus
 `skills/pwk-executing-tasks/references/progress-format.md`,
 `skills/pwk-executing-tasks/references/resume.md`,
 `skills/pwk-executing-tasks/references/review.md`, and
-`skills/pwk-executing-tasks/scripts/build-review-packet.py`.
+`skills/pwk-executing-tasks/scripts/build-review-packet.mjs`.
 
 The kit enforces a design → execute → finalize workflow. Each phase below names the skill that drives it:
 
@@ -26,7 +26,8 @@ brainstorm → executing-tasks → finalizing
 /skill:pwk-brainstorming
 ```
 
-- Explore requirements and shape the design. Interviews in **frontier rounds**: questions form a dependency tree seeded by a six-dimension checklist; each round asks the full frontier as numbered questions, each with a recommended answer; facts are looked up, only decisions asked; the interview ends when the frontier is empty — nothing left silently assumed — and an assumption gate sweeps the draft before the design is presented.
+- Explore requirements and shape the design. Interviews in **frontier rounds**: questions form a dependency tree seeded by a six-dimension checklist; each round asks the full frontier as numbered questions, each with a recommended answer; facts are looked up, runnable unknowns settle by **decide-by-experiment** (a bounded sketch with a proof clause), only decisions asked; the interview ends when the frontier is empty — nothing left silently assumed — and an assumption gate sweeps the draft before the design is presented.
+- Open with a **PRD brief** when source material exists (background / current situation / the delta — cited, zero-context, corrected by the human before any requirement is written); every criterion passes the **probe test**: its `Then` names an outcome a command can observe.
 - Produce `docs/plans/<date>-<topic>/<leaf>-design.md` — descriptive, the **single buildable artifact**: a `## At a glance` digest for the human (2–4 sentence plain-language summary → **Key decisions**, one line each: decision + why, a `(rejected: …)` clause only when the fork was real → a `| R# | Requirement in one line | Risk |` table, one row per requirement) immediately before the `## Requirements` blocks — one `### R<n>:` block per requirement carrying its one-line behavior, **acceptance criteria** (Given/When/Then incl. edge/error cases) and Checkpoints/Review tags (no test-name lists, no separate plan doc) — ending with a `## Feature acceptance` section (end-to-end scenarios that prove the requirements compose into the feature — the feature's definition-of-done).
 - May start an **umbrella** for a requirement too big for one design doc (human-approved): writes the status-free `docs/plans/<date>-<topic>/overview.md` (the same topic folder, now with more than one leaf; a `## Parts (build order)` roster of leaves + build order) and the **first** leaf's `<leaf>-design.md` beside it. Later leaves are brainstormed one by one against the overview + implemented predecessors.
 - ADRs go to `docs/adr/` (permanent, never archived).
@@ -43,7 +44,7 @@ Write boundary: only `docs/plans/` is writable. Source files are hard-blocked.
 - After the review passes, the executor writes a **code digest** into the progress file — plain-language summary, execution flow, gotchas, key files — derived from the review packet; it rides the existing disposal globs.
 - Per-requirement checkpoints/reviews are **opt-in** — they fire only for requirements the design doc tags (default off); see [Proportionality](#proportionality).
 - **Regression check after each commit** — run the full existing suite to catch cross-requirement regressions immediately. The feature E2E stays red until the last requirement and is gated only at the ship checkpoint (the old integration gate folds into it).
-- Progress tracked in `docs/plans/<date>-<topic>/<leaf>-progress.md` (feature phase + requirement checklist).
+- Progress tracked in `docs/plans/<date>-<topic>/<leaf>-progress.md` (feature phase + requirement checklist); the execution summary's **Evidence rows** pair plain words with a pointer — no requirement is ✅ without one.
 
 No write restrictions. All tools available.
 

package/extensions/workflow-guard.ts

@@ -487,6 +487,46 @@ const PHASE_REMINDERS: Record<Exclude<Phase, null>, string> = {
     "[pi-workflow-kit] DESIGN phase: read-only. No source edits; writes only under docs/plans/. No mutations.",
 };
 
+/** The one-line session visibility signal for a granted sandboxed batch executor.
+ *  Informational only — the skills carry the actual preference; this line makes the
+ *  host capability visible when work starts. */
+const CODEMODE_HINT_LINE =
+  "codemode: active — prefer it for batched read-only exploration (one executor call beats N tool round-trips); the kit's shell recipes are fallbacks.";
+
+/** A host that can report its tool registry (pi's ExtensionAPI can; minimal hosts and
+ *  test harnesses may not — detection fails closed there). */
+type ToolRegistryHost = {
+  getActiveTools?: () => unknown;
+  getAllTools?: () => unknown;
+};
+
+/** Does the host grant `codemode` (pi ≥ 1.0.0's sandboxed batch executor) to the model?
+ *  The active tool set is authoritative when the host exposes one (`getAllTools` also
+ *  reports registered-but-deferred tools); absent registries and unexpected entry
+ *  shapes fail closed to false — the visibility line must never throw. */
+export function detectCodeme(pi: ToolRegistryHost): boolean {
+  const grantsCodeme = (entries: unknown[]): boolean =>
+    entries.some((entry) =>
+      typeof entry === "string"
+        ? entry === "codemode"
+        : typeof entry === "object" && entry !== null && (entry as { name?: unknown }).name === "codemode",
+    );
+  for (const source of [pi.getActiveTools, pi.getAllTools]) {
+    if (typeof source !== "function") continue;
+    try {
+      const entries = source.call(pi);
+      // Each registry that exists decides on its own answer — a container-shape
+      // surprise fails closed to false rather than falling through to the broader
+      // registry, which also reports deferred (not granted) tools.
+      return Array.isArray(entries) ? grantsCodeme(entries) : false;
+    } catch {
+      // Registry surprises fail closed; visibility never breaks the session.
+      return false;
+    }
+  }
+  return false;
+}
+
 /** Determine if a write/edit to filePath should be blocked during the given phase.
  *  Only writes under docs/plans/ are allowed during the design phase.
  */
@@ -515,6 +555,13 @@ let pendingPhaseReminder = false;
  */
 let guardOverride: "on" | "off" | null = null;
 
+/** Codemode visibility (once per session): whether the host grants the executor,
+ *  decided once at session_start, and whether the one-line hint has had its single
+ *  emission window (the window never retries — a later /pwk-guard auto/on does not
+ *  retro-add a suppressed line). */
+let codemodeActive = false;
+let codemodeAnnounced = false;
+
 /** Is the guard actively enforcing read-only right now? */
 function enforceActive(): boolean {
   if (guardOverride === "off") return false;
@@ -542,6 +589,8 @@ export default function (pi: ExtensionAPI) {
     phase = null;
     pendingPhaseReminder = false;
     guardOverride = null;
+    codemodeActive = detectCodeme(pi);
+    codemodeAnnounced = false;
   });
 
   // --- Project role setup -------------------------------------------------
@@ -673,15 +722,29 @@ export default function (pi: ExtensionAPI) {
   // return { block, reason }, not a message. So at bash time the reminder surfaces only when a
   // destructive command is actually blocked (the reactive `reason` in the tool_call handler).
   pi.on("before_agent_start", async () => {
-    if (!phase || !pendingPhaseReminder) return {};
+    // Codemode visibility: the line rides the first tail message of the session —
+    // appended to a phase reminder when one fires, emitted on its own when none
+    // does — once ever, and suppressed when the guard is pinned off.
+    let codemodeLine: string | null = null;
+    if (codemodeActive && !codemodeAnnounced) {
+      codemodeAnnounced = true;
+      if (guardOverride !== "off") codemodeLine = CODEMODE_HINT_LINE;
+    }
+    if (!phase || !pendingPhaseReminder) {
+      if (codemodeLine) return { message: { customType: "pwk-codemode-hint", content: codemodeLine, display: false } };
+      return {};
+    }
     pendingPhaseReminder = false;
     // Override states announce themselves via the /pwk-guard handler; this reminder
     // is the auto-mode phase-entry cue only.
-    if (guardOverride !== null) return {};
+    if (guardOverride !== null) {
+      if (codemodeLine) return { message: { customType: "pwk-codemode-hint", content: codemodeLine, display: false } };
+      return {};
+    }
     return {
       message: {
         customType: "pwk-phase-reminder",
-        content: PHASE_REMINDERS[phase],
+        content: codemodeLine ? `${PHASE_REMINDERS[phase]}\n\n${codemodeLine}` : PHASE_REMINDERS[phase],
         display: false,
       },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tianhai/pi-workflow-kit",
-  "version": "2.8.0",
+  "version": "2.11.0",
   "description": "Enforce structured design→execute→finalize workflow with TDD discipline in AI coding agents",
   "keywords": [
     "pi-package",

package/skills/pwk-brainstorming/SKILL.md

@@ -5,15 +5,15 @@ description: "Use this before any creative work — creating features, building
 
 # Brainstorming
 
-Read-only exploration of source code; every file you create or edit goes under `docs/plans/`. (An approved ADR goes to `docs/adr/`, which sits outside the writable boundary — the human writes it themselves or briefly runs `/pwk-guard off`; the design phase never unlocks it.) The design doc is the **single buildable artifact** — each requirement carries its own acceptance criteria and review tags, and the executor builds straight from it; nothing is re-derived into a second document later. Source-writing happens in `pwk-executing-tasks`.
+Read-only exploration of source code; every file you create or edit goes under `docs/plans/`. An approved ADR goes to `docs/adr/` — outside the writable boundary, so the human writes it or briefly runs `/pwk-guard off`, and the design phase never unlocks it. The design doc is the **single buildable artifact**: each requirement carries its own acceptance criteria and review tags, and the executor builds straight from it. Source-writing happens in `pwk-executing-tasks`.
 
-Any command or tool recipe in this skill is an example, not the requirement — when your host grants a better tool for an operation (a sandboxed batch executor, a structured file API), use the better tool and treat the recipe as a fallback; the only exact exceptions are this kit's `scripts/` helpers and plain `git` invocations, whose deterministic output is the point.
+Any command or tool recipe in this skill is an example, not the requirement — when your host grants a better tool for an operation (a sandboxed batch executor — e.g. `codemode` on pi ≥ 1.0.0 — a structured file API), use the better tool and treat the recipe as a fallback; the only exact exceptions are this kit's `scripts/` helpers and plain `git` invocations, whose deterministic output is the point.
 
 ## Proportionality: trivial vs non-trivial
 
 Classify the change at the start.
 
-- **Trivial** — typo or obvious bugfix with no open design questions, config/version bump, single-function change, or anything the human flags as trivial. Skip steps 3–6; read the design-format reference and run the validator in step 7, writing a **minimal** design doc in one turn (an `In short:` one-liner — what + why + approach in plain words, plus a single `### R1:` requirement block with its criteria and tags, and an optional `## Production-risk areas` line — and deliberately **no `## Feature acceptance`**: a trivial slice's ship gate is the full existing suite, no E2E is manufactured for it), and hand off to `/skill:pwk-executing-tasks`. The guard still enforces read-only — trivial compresses the phase to one turn, it doesn't skip it.
+- **Trivial** — a typo or obvious bugfix with no open design questions, a config or version bump, a single-function change, or anything the human flags as trivial. Skip steps 3–6: read the design-format reference, run the validator in step 7, and write a **minimal** design doc in one turn — an `In short:` one-liner (what + why + approach), one `### R1:` block with criteria and tags, an optional `## Production-risk areas` line, and deliberately **no `## Feature acceptance`** (a trivial slice ships on the full existing suite; no E2E is manufactured). Hand off to `/skill:pwk-executing-tasks`. The guard still enforces read-only — trivial compresses the phase to one turn, it does not skip it.
 - **Non-trivial** — open design questions, multiple approaches, cross-module impact, or new behavior. Run the full process below.
 
 When unsure, ask: "This looks trivial — fast-path it, or full brainstorm?" Default to full.
@@ -22,39 +22,56 @@ When unsure, ask: "This looks trivial — fast-path it, or full brainstorm?" Def
 
 **One design doc = one PR; one requirement = one testable slice within it.** Most work is a single design doc; several requirements serving one cohesive outcome do not force an umbrella.
 
-Before drafting, assess whether a large request has distinct testable outcomes that need separate design/execute cycles. If so, propose an **umbrella** of vertical slices with one-line scopes and a build order, and get human approval before writing an overview or design. A layers-only split (database, API, UI) is not a vertical split: each slice delivers testable behavior. Design only the current slice; ground later designs in implemented code, not speculative sibling designs. The umbrella still ships as one PR on one branch, finalized once.
+A large request with distinct testable outcomes that need separate design/execute cycles becomes an **umbrella** of vertical slices with one-line scopes and a build order, approved before you write an overview or design. A layers-only split (database, API, UI) is not vertical — each slice delivers testable behavior. Design only the current slice, grounded in implemented code, not speculative sibling designs; the umbrella still ships as one PR on one branch, finalized once.
 
-**One folder per topic:** `docs/plans/<date>-<topic>/`, containing `<leaf>-design.md`, `<leaf>-progress.md`, and `<leaf>-review-packet*.md`; `<leaf>` is `<topic>` for a single-part topic. More than one leaf adds `overview.md`. The whole folder is the creation/discovery/disposal unit.
+**One folder per topic:** `docs/plans/<date>-<topic>/`, holding `<leaf>-design.md`, `<leaf>-progress.md`, and `<leaf>-review-packet*.md`; `<leaf>` is `<topic>` for a single-part topic, and more than one leaf adds `overview.md`. The folder is the creation, discovery, and disposal unit.
 
-**Umbrella trigger:** before proposing or writing a new umbrella, or when discovery finds an existing `overview.md` beside this design, read [references/umbrella.md](references/umbrella.md). It defines the status-free roster, first/later-slice procedures, and header-only predecessor reporting. Build order is advisory, not an enforcement gate. An existing roster means the split is already decided; design the current slice against it.
+**Umbrella trigger:** before proposing a new umbrella, or when discovery finds an `overview.md` beside this design, read [references/umbrella.md](references/umbrella.md) — it owns the status-free roster, the first/later-slice procedures, and header-only predecessor reporting. Build order is advisory, not a gate, and an existing roster means the split is already decided; design the current slice against it.
 
 ## Process
 
 1. **Check git state** — `git status` + `git log --oneline -5`. Uncommitted work? Ask the user what to do first.
-2. **Discovery** *(skip in a brand-new repo with no `docs/plans/`)* — first verify the repo root: run `pwd` (or your shell's equivalent) and `git rev-parse --show-toplevel`; mismatch → report both paths and stop; never `cd` (a worktree root counts). Then list `docs/plans` recursively, excluding docs/plans/completed/, for `*-design.md`, `*-progress.md`, and `overview.md` (topic docs live in `docs/plans/<date>-<topic>/` folders — archived work is not in flight). Use whatever recurses in your harness; one example: `find docs/plans -name '<suffix>' -not -path '*/completed/*'`; report in-flight topics and any active umbrella. For each in-flight topic with a progress file, report its `Feature phase:` line (matched header-only — `grep -m1 '^Feature phase:' <file>` — no body ingest); design-only topics report `design`. If the new idea continues an existing topic, ask whether to extend it or start fresh. Part of an umbrella? An existing `overview.md` **beside the design doc** means the split is already decided — read it for the roster and design this part's `<leaf>-design.md` against it (read [references/umbrella.md](references/umbrella.md) before proceeding).
-3. **Understand the idea** — read only enough code/docs/commits to ground the design. **Check `docs/lessons.md`** — known constraints may shape it. Ask questions in **frontier rounds**: build a question tree seeded by the dimension checklist, then ask in rounds. The **frontier** is every question whose prerequisites are already settled — ask the whole frontier in one round; a question whose answer depends on another still-open question waits for a later round. Number each question (`Q1`, `Q2`, …) and attach your recommended answer (`➡️ <recommendation>`) — the recommendation is your assumption surfaced up front; the human confirms, strikes, or corrects each in one reply. Recompute the frontier after each round of answers. Seed the tree by walking every checklist dimension — *Goal & scope · Data & state · Behavior & edge cases · Errors & failure · Integration · Non-functional* — printing `— nothing to ask` for groups with no questions (never skip silently). **Facts vs. decisions**: anything answerable from the codebase, docs, or tools is looked up — recon scout or inline — never asked of the human; a pending lookup is an unsettled prerequisite that holds only its downstream questions, while the rest of the frontier is asked now. Only decisions are asked. Major approvals stay single-decision — one question each, never batched: approach selection (step 5), umbrella split, design approval, ADR offer. The interview ends when the frontier is empty — every branch visited, nothing left silently assumed — not when you feel you understand. Then present a short summary and ask: "Should I proceed, or is there more?" The human decides when to move on.
-4. **(skipped on trivial changes)** **Codebase recon** — for non-trivial topics with prior art, request the host’s `codebase-recon` capability using the logical `pwk-recon-scout` role. Require a fresh-context, read-only, bounded worker and pass the topic, one-line intent, and repo root. Use the returned 5-section codebase map (Relevant files, Existing patterns, Call sites, Test layout, Gotchas) as the grounding context for the next two steps instead of reading those files inline. The scout is observations only — no design recommendations. Skip this step on trivial changes (typo, version bump, single-function edit per the proportionality rule). If no compatible capability is available or the provider cannot enforce the requested constraints, report `Scout: unavailable` and do the same recon inline, preserving the five-section map and `file:line` citations; do not silently omit recon.
-5. **Explore approaches** — propose 2–3, leading with your recommendation. Sketch the concrete interface (types, signatures, example caller) for each so the comparison is grounded in code, not abstractions.
+2. **Discovery** *(skip in a brand-new repo with no `docs/plans/`)* — first verify the repo root: run `pwd` (or your shell's equivalent) and `git rev-parse --show-toplevel`; mismatch → report both paths and stop; never `cd` (a worktree root counts). Then list `docs/plans` recursively, excluding docs/plans/completed/, for `*-design.md`, `*-progress.md`, and `overview.md` (topic docs live in `docs/plans/<date>-<topic>/` folders — archived work is not in flight). Use whatever recurses in your harness; one example: `find docs/plans -name '<suffix>' -not -path '*/completed/*'`; report in-flight topics and any active umbrella, each topic’s `Feature phase:` line header-only (`grep -m1 '^Feature phase:' <file>`; design-only topics report `design` — no body ingest). With a sandboxed batch executor (e.g. `codemode` on pi ≥ 1.0.0) the listing and every phase extraction are one call, returning only the summary lines (adapt the paths to the verified root when your cwd differs):
+
+   ```javascript
+   const designs = (await tools.bash({ command: "find docs/plans -name '*-design.md' -not -path '*/completed/*' | sort", timeout: 15 })).output.trim();
+   const files = designs ? designs.split('\n') : [];
+   const shellq = (s) => "'" + s.replace(/'/g, "'\\''") + "'";
+   const heads = await Promise.all(files.map(d =>
+     tools.bash({ command: "grep -m1 '^Feature phase:' " + shellq(d.replace('-design.md', '-progress.md')), timeout: 15 }).then(r => r.output.trim() || 'design')));
+   return text(files.map((d, i) => d + ' — ' + heads[i]).join('\n') || 'no in-flight topics');
+   ```
+
+   If the idea continues an existing topic, ask whether to extend it or start fresh. An `overview.md` **beside the design doc** means the split is already decided — read it for the roster and design this part’s `<leaf>-design.md` against it.
+3. **Understand the idea** — **PRD brief.** With source material (a PRD, ticket, or spec — pasted text, a path, a URL), open with a brief before any question: **Background** (the problem, why now, who is affected — each product claim cites its PRD section), **Current situation** (what the code does today — each claim cites `file:line`), **The delta** (what must change, each line naming a requirement candidate, and what stays untouched). Zero-context rule: plain meaning first, the pointer second — quote non-English domain terms with a plain-English gloss and mark anything uncited `(interpretation: …)`. Unreadable source material: report the blocker, ground on code only, name the gap. The human corrects the brief before frontier rounds; confirmed facts weave into the design doc, with no sidecar file. No source material, no brief. Then read only enough code, docs, and commits to ground the design, and **check `docs/lessons.md`**.
+
+   Ask questions in **frontier rounds** — the frontier is every question whose prerequisites are settled. Build the tree by walking every checklist dimension (*Goal & scope · Data & state · Behavior & edge cases · Errors & failure · Integration · Non-functional*), print `— nothing to ask` for empty groups, and ask the whole frontier in one round: number each question (`Q1`, `Q2`, …) with your recommended answer (`➡️ <recommendation>`) so the human confirms, strikes, or corrects each in one reply. A question that depends on another still-open one waits for a later round; recompute the frontier after each round.
+
+   **Facts vs. decisions:** anything answerable from the codebase, docs, or tools is looked up — recon scout or inline — never asked of the human; a pending lookup holds only its downstream questions while the rest of the frontier is asked now. **Runnable facts:** an unknown observable by running something — behavior, timing, output, layout — is settled by a bounded sketch, never asked of the human and never guessed: an inline interpreter or a file under `docs/plans/<topic>/`, no installs, no source writes. Record it where it lands as `(settled by sketch: <what ran> → <result>)` and list it in the round summary so the human can strike it; a sketch result that would set business behavior still passes the assumption gate; inconclusive or blocked → record `INCONCLUSIVE` plus one line of what ran, and the question returns to the human with the result attached. A cheaper read beats a run when reading can decide, and only decisions are asked.
+
+   Major approvals stay single-decision — one question each, never batched: approach selection (step 5), umbrella split, design approval, ADR offer. The interview ends when the frontier is empty — every branch visited, nothing left silently assumed — not when you feel you understand. Then present a short summary and ask: "Should I proceed, or is there more?" The human decides when to move on.
+4. **(skipped on trivial changes)** **Codebase recon** — first **enumerate what this session actually grants** and name what you found: under a batch executor `Array.from(ALL_TOOLS)`, otherwise the tools and roles your host listed. Then request the host’s `codebase-recon` capability using the logical `pwk-recon-scout` role: a fresh-context, read-only, bounded worker given the topic, one-line intent, and repo root. Use its 5-section map (Relevant files, Existing patterns, Call sites, Test layout, Gotchas) as grounding for steps 5–6 instead of reading those files inline; the scout reports observations only, never design recommendations. No delegation capability among the tools you enumerated, or constraints it cannot enforce → report `Scout: unavailable` **with the enumeration result** and do the same recon inline, preserving the five-section map and `file:line` citations; never omit recon silently.
+5. **Explore approaches** — propose 2–3, leading with your recommendation, and sketch the concrete interface (types, signatures, example caller) for each so the comparison is grounded in code rather than abstractions.
 6. **Present the design** in one pass, organized into sections (architecture, components, data flow, error handling, testing) — the human comments on any section; re-present only revised sections.
 
-   **Assumptions to confirm first** — before presenting, sweep the drafted design: every assumption it would bake in unconfirmed (business rules, defaults, edge-case resolutions) re-opens as a numbered question carrying your recommended answer; the human confirms, strikes, or corrects each in one reply. An honest empty gate ("no unconfirmed assumptions") when the draft is clean — never invent items. Hard rule: no business behavior enters the design doc on the agent's assumption. Confirmed facts are woven into the doc's existing sections — no new template section.
+   **Assumptions to confirm first** — before presenting, sweep the drafted design: every unconfirmed assumption it would bake in (business rules, defaults, edge-case resolutions) re-opens as a numbered question with your recommended answer, for one reply. An honest empty gate ("no unconfirmed assumptions") when the draft is clean — never invent items. Hard rule: no business behavior enters the design doc on the agent's assumption; confirmed facts are woven into existing sections, with no new template section.
 
-   Identified a significant architectural decision? Offer an ADR in `docs/adr/`. Only when all three hold: **hard to reverse**, **surprising without context**, **a real trade-off**. Format: title + 1–3 sentences of context/decision/why. ADRs are permanent institutional memory — they stay out of archive/rotation forever. (Guard note: `docs/adr/` is outside the writable `docs/plans/`; the human writes the approved ADR themselves or briefly runs `/pwk-guard off` — the agent never writes it while the design phase is gated.)
-7. **Write the design doc** — validate its structure before handing off; before writing either a trivial or non-trivial doc, read [references/design-format.md](references/design-format.md) for the exact format, tag defaults, risk/Setup rules, and audit. Requirement blocks carry acceptance criteria plus `### Checkpoints` / `### Review` tags. Missing tags default to `none` / `skip`. Write `docs/plans/<date>-<topic>/<leaf>-design.md`, creating the topic folder when absent. It is descriptive, not a task list; the executor builds directly from it.
+   Identified a significant architectural decision? Offer an ADR in `docs/adr/`, only when all three hold: **hard to reverse**, **surprising without context**, **a real trade-off**. Format: title + 1–3 sentences of context/decision/why. ADRs are permanent institutional memory — never archived or rotated. (Guard note: the human writes the approved ADR or briefly runs `/pwk-guard off`; you never write it while the design phase is gated.)
+7. **Write the design doc** — validate its structure before handing off. Read [references/design-format.md](references/design-format.md) first for the exact format, tag defaults, risk/Setup rules, and audit; requirement blocks carry acceptance criteria plus `### Checkpoints` / `### Review` tags. Missing tags default to `none` / `skip`. Write `docs/plans/<date>-<topic>/<leaf>-design.md`, creating the topic folder when absent. It is descriptive, not a task list — the executor builds directly from it.
 
-   **Completion gate:** Test observable behavior through the public interface. Audit every requirement's criteria, tags, and risk notes; confirm each appears exactly once. For non-trivial work, finish with end-to-end `## Feature acceptance` as the primary enforced spec. If writing a scenario step would require inventing behavior, that invention goes back through the assumption gate — an unwritable step means an unspecified requirement, not permission to guess. Risk notes never set the tag — the written `### Review` value stays `skip` unless the human sets it, and only the human tags a slice for review. Keep designing until the requirements compose into a coherent feature and the human approves the design, including feature acceptance. Trivial work retains the compressed one-turn path above, not another recurring approval stop.
+   **Completion gate:** Test observable behavior through the public interface. Audit every requirement’s criteria, tags, and risk notes — each appears exactly once. A criterion is ready only when its `Then` names an outcome a command can observe — a run, a grep, or an assertion; a criterion with no nameable probe sends the requirement back for splitting or rephrasing, and design-doc criteria never name tests — the probe materializes at execution. For non-trivial work, finish with an end-to-end `## Feature acceptance` as the primary enforced spec. If writing a scenario step would require inventing behavior, that invention goes back through the assumption gate: an unwritable step means an unspecified requirement, not permission to guess. Risk notes never set the tag — the written `### Review` value stays `skip` unless the human sets it, and only the human tags a slice for review. Keep designing until the requirements compose into a coherent feature and the human approves the design, including feature acceptance; trivial work keeps the compressed one-turn path above.
 
-   **Python prerequisite:** structural validation requires Python 3.9+ where commands execute, using only its standard library (no pip or project Node configuration). Confirm a compatible `python3` exists before invoking the helper. If Python is missing, unavailable, or too old, report the blocker and request a suitable runtime; stop at this gate. Do not auto-install Python, use a fallback implementation, or claim validation succeeded.
+   **Runtime prerequisite:** structural validation runs as a dependency-free Node script where commands execute, using only Node's standard library. Confirm `node --version` works before invoking the helper; if Node is missing, report the blocker and request a suitable runtime, then stop at this gate. Never auto-install a runtime, use a fallback implementation, or claim validation succeeded.
 
-   Resolve the helper from this installed skill's directory; pass explicit paths and quote paths with spaces. Relative input paths resolve from the caller's working directory, not the skill directory:
+   Resolve the helper from this installed skill’s directory and pass explicit paths, quoting paths with spaces:
 
    ```sh
-   python3 "<brainstorming-skill-dir>/scripts/validate-design.py" "<design-path>"
+   node "<brainstorming-skill-dir>/scripts/validate-design.mjs" "<design-path>"
    ```
 
-   Nonzero means validation did not succeed: report file-specific diagnostics, correct structural errors, and rerun. A missing local reference or helper is a blocker before its dependent action; do not silently skip it. Success verifies structure only, never semantic correctness, sound slicing, confirmed assumptions, or human approval.
+   Nonzero means validation did not succeed: report file-specific diagnostics, correct the structural errors, and rerun. A missing local reference or helper is a blocker before its dependent action; success verifies structure only — never semantic correctness, sound slicing, confirmed assumptions, or human approval.
 
-The session stays read-only and uncommitted through brainstorm: branch creation and the design-doc commit happen at the start of `pwk-executing-tasks` (its pre-flight creates the feature branch).
+The session stays read-only and uncommitted through brainstorm: branch creation and the design-doc commit happen at the start of `pwk-executing-tasks`.
 
 ## Principles
 

package/skills/pwk-brainstorming/references/design-format.md

@@ -4,7 +4,7 @@ Read before writing any design doc. Keep the design descriptive, not a task list
 
 ## Trivial format
 
-A trivial design has an `In short:` one-liner (what + why + approach in plain words), a single `### R1:` block with acceptance criteria and tags, and optional `## Production-risk areas`. It has no `## At a glance`, `## Requirements`, or `## Feature acceptance`; its ship gate is the full existing suite, not a manufactured E2E. Use the block rules below for its criteria, tags, and risk notes.
+A trivial design has an `In short:` one-liner (what + why + approach), a single `### R1:` block with acceptance criteria and tags, and optional `## Production-risk areas`. It has no `## At a glance`, `## Requirements`, or `## Feature acceptance`; its ship gate is the full existing suite, not a manufactured E2E. The block rules below cover it.
 
 ```markdown
 # Design: <topic>
@@ -23,7 +23,7 @@ In short: <what + why + approach>
 
 ## Non-trivial format
 
-**Open with `## At a glance`** — the human's two-minute digest, immediately before `## Requirements`. It contains (1) a 2–4 sentence plain-language summary: what is wrong or needed, what will be built, the key approach in plain words; (2) **Key decisions** — one line each: decision + why, with a `(rejected: <alternative> — <reason>)` clause only when the fork was real and load-bearing (never manufactured — no fork, no clause); (3) a table `| R# | Requirement in one line | Risk |` with exactly one row per requirement, where **R# = the requirement's block number in the `## Requirements` section below** — this ID is what every later digest keys on (progress rows, execution summary, reviewer coverage table). Plain language only: short sentences, no jargon, no Given/When/Then — those live in the requirement blocks for the executor. An umbrella overview gains no at-a-glance section; its roster already serves that role.
+**Open with `## At a glance`** — the human's two-minute digest, immediately before `## Requirements`: (1) a 2–4 sentence plain-language summary of what is wrong or needed, what will be built, and the key approach; (2) **Key decisions** — one line each: decision + why, with a `(rejected: <alternative> — <reason>)` clause only when the fork was real (never manufactured); (3) a table `| R# | Requirement in one line | Risk |`, exactly one row per requirement, where **R# = the requirement's block number in the `## Requirements` section below** — the ID every later digest keys on. Plain language only: no jargon, no Given/When/Then — those live in the requirement blocks. An umbrella overview gains no at-a-glance section; its roster serves that role.
 
 Then **`## Requirements`** — one `### R<n>: <name>` block per requirement, each one testable behavior:
 
@@ -49,18 +49,18 @@ Then **`## Requirements`** — one `### R<n>: <name>` block per requirement, eac
 
 Block rules:
 
-- **No test-name lists.** The criteria are the test spec — the executor writes and names the actual tests red-green from them, so the doc contains no test-name lists and no R#-to-section mapping tables: the block structure is the map.
-- **Tag every requirement** — `### Checkpoints` (how many human stops: `none` = no per-requirement stop, the default — the feature gate covers it; `full` = tests + complete stops) and `### Review` (per-requirement review: `skip` = none, the default; `parallel` = four delegated reviewers; `inline` = one `pwk-code-review` pass). Missing tags default to `none` / `skip`. Flag `full` only where complex logic or the main part of the feature makes a human look at the slice worth the stop.
-- **Nothing is tagged silently here; only the human tags a slice for review.** A requirement that touches a production-risk area carries its `### Production-risk notes` in the block and is flagged `⚠ production-risk` in the At-a-glance Risk column (the column is derived, **display-only**: `⚠ production-risk` if and only if the block carries non-empty `### Production-risk notes`, else `—` — never normative, never an input; `auto` reads the underlying risk content — the `## Production-risk areas` section and the notes — never the display column), but its written `### Review` value stays `skip` unless the human sets it — propose the tag in prose, leave the field at `skip`. An explicit human tag always wins, in both directions.
-- **No per-requirement spec stop, by design** — the acceptance criteria are approved right here, at design time; re-checking them mid-execution asks a question the human already answered.
-- **Production-risk notes** — a requirement touching a production-risk area carries its notes inside the block. Risks involving schema migrations, new dependencies, external APIs, or seed data also get a `## Setup` section (dependencies, migrations, seed data, and how to verify setup worked) between `## Requirements` and `## Feature acceptance`.
-- **Ordering** — dependencies come earlier in the list; the executor runs blocks in listed order with no dependency graph. Aim for vertical slices that merge cleanly on their own.
+- **No test-name lists.** The criteria are the test spec: the executor writes and names the tests red-green from them, so the doc holds no test-name lists and no R#-to-section map — the block structure is the map.
+- **Tag every requirement** — `### Checkpoints` (`none` = no per-requirement stop, the default; `full` = tests + complete stops) and `### Review` (`skip` = the default; `parallel` = four delegated reviewers; `inline` = one `pwk-code-review` pass). Missing tags default to `none` / `skip`; flag `full` only where complex logic or the feature's main part makes a human look worth the stop.
+- **Nothing is tagged silently here; only the human tags a slice for review.** A requirement touching a production-risk area carries its `### Production-risk notes` and is flagged `⚠ production-risk` in the At-a-glance Risk column — display-only, derived: `⚠ production-risk` if and only if the block carries non-empty notes, never an input; `auto` reads the underlying risk content, never the display column. Its written `### Review` value stays `skip` unless the human sets it — propose the tag in prose; an explicit human tag always wins, both ways.
+- **No per-requirement spec stop, by design** — the criteria were approved at design time; re-checking mid-execution asks a question already answered.
+- **Production-risk notes** — risks involving schema migrations, new dependencies, external APIs, or seed data also get a `## Setup` section (dependencies, migrations, seed data, and how to verify setup worked) between `## Requirements` and `## Feature acceptance`.
+- **Ordering** — dependencies come earlier; the executor runs blocks in listed order with no dependency graph. Aim for vertical slices that merge cleanly on their own.
 
-Then the narrative sections the executor reads as context — problem, approaches considered, architecture, components, data flow, error handling. Head the approaches section exactly `## Approaches considered` — finalizing's learning sweep reads it by that name. **`## Approaches considered` records every real fork and why each loser lost** — the executor needs the reasoning, and the finalize learning sweep harvests it for ADRs.
+Then the narrative sections the executor reads as context — problem, approaches considered, architecture, components, data flow, error handling. Head the fork record exactly `## Approaches considered` — finalizing's learning sweep reads it by that name — and **record every real fork and why each loser lost**; the executor needs the reasoning and finalize harvests it for ADRs.
 
-Touches a production-risk area (DB schema/migrations, auth, external APIs, concurrency/batch, uploads/large data flows, Redis/caching/queues)? Add a brief `## Production-risk areas` **immediately after the last requirement block** — inside the `### R1 → ## Feature acceptance` span, so the review packet carries it to reviewers verbatim — and mirror the risks into each touched block's `### Production-risk notes`. `pwk-code-review` audits it, per requirement when the slice is reviewed and at the feature review always; finalize's learning sweep reads it.
+Touches a production-risk area (DB schema/migrations, auth, external APIs, concurrency/batch, uploads/large data flows, Redis/caching/queues)? Add a brief `## Production-risk areas` **immediately after the last requirement block** — inside the `### R1 → ## Feature acceptance` span, so the review packet carries it verbatim — and mirror the risks into each touched block's `### Production-risk notes`. `pwk-code-review` audits it (per reviewed slice, and always at the feature review); finalize's learning sweep reads it.
 
-**End with `## Feature acceptance`** — one or more end-to-end `Given/When/Then` scenarios proving the requirements *compose* into the feature. This is the feature's definition-of-done; the human approves it as what "the feature works" means. `pwk-executing-tasks` writes it as the E2E test first and runs it as the **primary enforced spec** (the test it gates on first). The section carries the feature-level `### Feature review: auto | parallel | inline` tag — the one whole-feature review; default `auto`, which resolves on the design's own production-risk content to `parallel` (all four reviewers) when the design has any — a non-empty `## Production-risk areas` section, or a non-empty `### Production-risk notes` on any requirement — and to `inline` (one pass) otherwise. An explicit `parallel` or `inline` is written as-is, never resolved, so the human always overrides `auto`. Treat "I can write this scenario" as the green light to finish designing — if you can't, keep designing because the requirements don't yet compose into a coherent feature. If writing a scenario step would require inventing behavior, that invention goes back through the assumption gate — it may never be silently written into the scenario; an unwritable step means an unspecified requirement, so keep designing.
+**End with `## Feature acceptance`** — one or more end-to-end `Given/When/Then` scenarios proving the requirements *compose* into the feature. It is the feature's definition-of-done and the **primary enforced spec**: `pwk-executing-tasks` writes it as the E2E test first and gates on it. The section carries the feature-level `### Feature review: auto | parallel | inline` tag — the one whole-feature review; default `auto`, which resolves on the design's own production-risk content to `parallel` (all four reviewers) when the design has any — a non-empty `## Production-risk areas` section, or a non-empty `### Production-risk notes` on any requirement — and to `inline` (one pass) otherwise. An explicit `parallel` or `inline` is written as-is, never resolved. If a scenario step would require inventing behavior, the invention goes back through the assumption gate — never silently into the scenario; an unwritable step means an unspecified requirement.
 
 ```markdown
 ## Feature acceptance
@@ -72,12 +72,12 @@ Touches a production-risk area (DB schema/migrations, auth, external APIs, concu
 
 Example (rate limiting): "Given a new API consumer with no prior usage, When they exceed 100 requests/minute for 3 consecutive minutes, Then they're throttled, a `rate_limited` event is emitted, and further requests return 429."
 
-**Audit before finishing:** every requirement block has acceptance criteria and both tags, and each requirement appears **exactly once** — none dropped, none duplicated. A `## Feature acceptance` section exists as the primary enforced spec — on every non-trivial doc; a trivial doc ends after its `### R1:` block and ships on the full suite instead. Production-risk areas are reflected in the requirement blocks that touch them.
+**Audit before finishing:** every requirement block has acceptance criteria and both tags, and each requirement appears **exactly once** — none dropped, none duplicated. Non-trivial docs carry a `## Feature acceptance` section as the primary enforced spec; a trivial doc ends after its `### R1:` block and ships on the full suite. Production-risk areas appear in the blocks that touch them. The probe test: a criterion is ready only when its `Then` names an outcome a command can observe — a run, a grep, or an assertion; one with no nameable probe goes back for splitting or rephrasing, and criteria never name tests. A fact settled by a sketch carries its proof where it lands — `(settled by sketch: <what ran> → <result>)` — woven into the section it confirms, never a new template section.
 
 ## Structural validator contract
 
-Run `scripts/validate-design.py` as directed in the main skill. It reads UTF-8 Markdown without modifying it. Headings, tags, and labels inside backtick or tilde fenced examples do not count; close every fence. Real requirements use unique sequential `### R1: <name>`, `### R2: <name>`, … headings with nonempty names. Each block needs a standalone `**Acceptance criteria**` label in its main body, before any tag or risk-note heading (an explanatory suffix after an em dash, dash, or colon is allowed) and nonempty criteria before the next heading or bold section label. A bare bullet or content borrowed from risk notes is not a criterion section.
+Run `scripts/validate-design.mjs` as directed in the main skill. It reads UTF-8 Markdown without modifying it; headings, tags, and labels inside backtick or tilde fenced examples do not count, so close every fence. Real requirements use unique sequential `### R1: <name>`, `### R2: <name>`, … headings with nonempty names. Each block needs a standalone `**Acceptance criteria**` label in its main body, before any tag or risk-note heading (an explanatory suffix after an em dash, dash, or colon is allowed), with nonempty criteria before the next heading or bold label. A bare bullet or content borrowed from risk notes is not a criterion section.
 
 Write each selected tag as one value, not the template's pipe-separated alternatives. Missing optional tags retain `Checkpoints: none`, `Review: skip`, and `Feature review: auto`. Non-trivial designs require nonempty `## Feature acceptance` scenarios before their feature-review tag. Only the minimal trivial shape above receives the no-Feature-acceptance exception.
 
-The helper checks structure, not meaning: it does not prove Given/When/Then quality, testability, complete edge/error coverage, good slicing, risk classification, confirmed assumptions, or human approval. Those remain the agent's audit and the human's judgment. Structural success does not complete the design gate by itself.
+The helper checks structure, not meaning: it does not prove Given/When/Then quality, testability, edge/error coverage, good slicing, risk classification, confirmed assumptions, or human approval. Those remain the agent's audit and the human's judgment. Structural success does not complete the design gate by itself.

package/skills/pwk-brainstorming/references/umbrella.md

@@ -1,11 +1,11 @@
 # Umbrella mechanics
 
-An umbrella splits one large requirement into multiple design docs that ship together as **one PR**. It is a single-topic folder with more than one leaf: one branch, one `pwk-finalizing` at the end, which disposes the folder as one unit. Design only the current slice; ground later slices in implemented predecessor code. The split is intra-PR decomposition — a way to keep each design/execute cycle small and focused, not a multi-PR strategy.
+An umbrella splits one large requirement into multiple design docs shipping as **one PR**: one topic folder, more than one leaf, one branch, one `pwk-finalizing` at the end disposing the folder as one unit. Design only the current slice, grounded in implemented predecessor code.
 
 **First brainstorm** (the requirement is too big for one design doc):
 
-1. **Propose the split** — the parts, a one-line scope each, and build order. Get human approval before writing anything beyond discovery.
-2. **Write the overview** — `docs/plans/<date>-<topic>/overview.md`, in the topic's own folder (every leaf lives beside it: `<leaf>-design.md`, `<leaf>-progress.md`, `<leaf>-review-packet*.md`), a **status-free roster**:
+1. **Propose the split** — the parts, a one-line scope each, and build order; human approval before anything beyond discovery.
+2. **Write the overview** — `docs/plans/<date>-<topic>/overview.md`, in the topic's own folder (every leaf lives beside it):
 
    ```markdown
    # Overview: <topic>
@@ -17,10 +17,9 @@ An umbrella splits one large requirement into multiple design docs that ship tog
    2. <leaf> — <one-line scope>
    ```
 
-   The `## Parts (build order)` heading and the `N. <leaf> — <one-line scope>` item shape together are the **roster contract**: `pwk-finalizing` and `pwk-status` both read them, and both are lint-pinned so a drifted heading fails loudly instead of reading an empty roster. Goal, parts with one-line scopes, build order — **no status column**. No skill mutates the overview between this write and `pwk-finalizing` (which disposes it); part-completion is inferred from each leaf's own `*-progress.md`.
-3. **Write the first part's design doc** — `docs/plans/<date>-<topic>/<leaf>-design.md` in the same folder, then hand off to `/skill:pwk-executing-tasks`.
+   The `## Parts (build order)` heading and the `N. <leaf> — <one-line scope>` item shape are the **roster contract**: `pwk-finalizing` and `pwk-status` read them, and both are lint-pinned. Goal, parts, build order — **no status column**; no skill mutates the overview before `pwk-finalizing` disposes it, and part-completion comes from each leaf's own `*-progress.md`.
+3. **Write the first part's design doc** — `docs/plans/<date>-<topic>/<leaf>-design.md` beside the overview, then hand off to `/skill:pwk-executing-tasks`.
 
-**Later parts** — re-run `/skill:pwk-brainstorming` for the next part. Read the overview for big-picture/roster context (which slice is yours, which siblings exist), then report each prior leaf's `Feature phase:` line (matched header-only — `grep -m1 '^Feature phase:' <leaf>-progress.md` beside the overview — no body ingest; a leaf with no progress file yet reports `not started`) before designing the slice, then explore the codebase to design your slice **as brainstorm always does** — prior parts are just implemented code in the repo by then. Predecessor phases are visibility, not enforcement: design the slice regardless; cross-slice decisions that must persist go in an ADR, not the overview.
-
-The whole umbrella is one branch and one PR: `pwk-executing-tasks` creates the branch in its pre-flight and reuses it for later parts, and suggests the next part (or finalize after the last); `pwk-finalizing` disposes the whole folder — overview + every leaf — and ships one PR.
+**Later parts** — re-run `/skill:pwk-brainstorming`. Read the overview for roster context, then report each prior leaf's `Feature phase:` line (`grep -m1 '^Feature phase:' <leaf>-progress.md` beside the overview; no progress file yet → `not started`) before designing the slice — prior parts are implemented code by then. Cross-slice decisions that must persist go in an ADR.
 
+One branch and one PR: `pwk-executing-tasks` creates the branch in its pre-flight and reuses it for later parts; `pwk-finalizing` disposes the whole folder — overview and every leaf.