@huseynsnmz/pi-board 0.15.3 → 0.17.0

package/docs/superpowers/plans/2026-10-19-issue-213-reply-guard-csi-key.md

@@ -1,257 +0,0 @@
-# reply guard CSI-key collision — Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Stop the reply guard from swallowing kitty/modifyOtherKeys PageDown (`\x1b[6;<mods>u` / `\x1b[6;<mods>~`) while keeping every genuine cell-size reply fragment armed.
-
-**Architecture:** One new pure predicate in `src/core/terminal-reply-guard.mjs`: a *complete* CSI key sequence is user input and must be classified before the `REPLY_HEADS` prefix loop. Every fragment shape the guard protects today has no `u`/`~` terminator, so the predicate cannot weaken #170's protection.
-
-**Tech Stack:** ESM `.mjs` core module, `node:test` + `assert/strict`, TypeScript component (unchanged), `@earendil-works/pi-tui` (unchanged).
-
-**Spec:** `docs/superpowers/specs/2026-10-19-issue-213-reply-guard-csi-key-design.md`
-
-## Global Constraints
-
-- Tabs for indentation; English comments and commit messages (repo AGENTS.md).
-- No new dependencies.
-- `npm run verify` must pass on CI (typecheck + perf gate + tests + coverage + pack dry-run). Locally only the targeted suites plus `typecheck`/`pack:dry` are authoritative — this Windows host has a pre-existing ~72-test baseline failure set that also fails on `main`.
-- New test names carry the `#213-` prefix (spec §6 "验收 ID 作用域") to avoid colliding with the `A1:`/`A2:`/… names already in `test/terminal-reply-guard.test.mjs`.
-- Do not change `REPLY_HEADS`, the absorption window (250 ms / 64 bytes), or the kill switch.
-
-## Review Focus
-
-- **A genuine cell-size fragment that looks like a key** — `\x1b[6;` and `\x1b[6;24` (no terminator) must still `reply-head` and arm; only `u`/`~`-terminated sequences are keys.
-- **A complete reply that looks like a key** — `\x1b[6;24;80t` must still be `reply-complete`/drop (DROP_SHAPES runs first).
-- **Other kitty functional keys that share a head prefix** — `\x1b[6;1:2;65u` (alternate keys) must also be treated as a key, which is why the predicate is `(?:[;:]\d+)*` and not the narrower form in the issue text.
-- **A key that arrives while the guard is armed** — an armed window must not swallow it silently; the state machine's `armed + other` path drops the stale buffer and passes the event.
-- **Plain text right after a key** — forwarding must stay byte-exact (no duplication, no reordering).
-
----
-
-### Task 1: Classify complete CSI keys before the head prefixes
-
-**Files:**
-- Modify: `src/core/terminal-reply-guard.mjs` (add `CSI_KEY_SEQUENCE` near the other shape constants, and one branch in `classifyReplyEvent`)
-- Test: `test/terminal-reply-guard.test.mjs`
-
-**Interfaces:**
-- Produces: `classifyReplyEvent(data)` now returns `{ kind: "other" }` for `CSI <num>[;<mod>[:<event>][;<alt>]]{u,~}`. No exported symbol changes.
-
-- [ ] **Step 1: Write the failing tests**
-
-Append to `test/terminal-reply-guard.test.mjs`:
-
-```js
-// Issue #213: kitty / modifyOtherKeys PageDown shares the cell-size head prefix.
-test("#213-A1: a complete CSI key sequence is user input, never a reply head", () => {
-	for (const seq of ["\x1b[6;1u", "\x1b[6;5u", "\x1b[6;1:2u", "\x1b[6;1:2;65u", "\x1b[6;5~", "\x1b[6;2~"]) {
-		assert.deepEqual(classifyReplyEvent(seq), { kind: "other" }, `${JSON.stringify(seq)} must be a key`);
-	}
-});
-
-test("#213-A2: neighbouring keys are unaffected", () => {
-	for (const seq of ["\x1b[5;1u", "\x1b[5;5~", "\x1b[57422u", "\x1b[57421u", "\x1b[3;5~"]) {
-		assert.deepEqual(classifyReplyEvent(seq), { kind: "other" }, `${JSON.stringify(seq)} must stay a key`);
-	}
-});
-
-test("#213-A3: genuine cell-size fragments still arm", () => {
-	for (const seq of ["\x1b[6;", "\x1b[6;24"]) {
-		assert.deepEqual(classifyReplyEvent(seq), { kind: "reply-head", family: "cell-size" });
-	}
-});
-
-test("#213-A4: a complete cell-size reply still drops", () => {
-	assert.deepEqual(classifyReplyEvent("\x1b[6;24;80t"), { kind: "reply-complete", family: "cell-size", action: "drop" });
-});
-```
-
-- [ ] **Step 2: Run the tests to verify they fail**
-
-Run: `node --test test/terminal-reply-guard.test.mjs`
-Expected: FAIL — `#213-A1` reports `{ kind: "reply-head", family: "cell-size" }` for `\x1b[6;1u` / `\x1b[6;5~`.
-
-- [ ] **Step 3: Implement the predicate**
-
-In `src/core/terminal-reply-guard.mjs`, next to `REPLY_HEADS`:
-
-```js
-// Issue #213: kitty keyboard protocol keys that carry a modifier use the legacy
-// functional-key encoding `CSI <num>;<mods>u`, and PageDown's legacy number IS 6
-// (`\x1b[6;1u` = no modifier, mods field is bitmask+1). modifyOtherKeys uses the same
-// prefix with `~` (`\x1b[6;5~`). Both therefore share the cell-size head prefix
-// (`\x1b[6;`), which used to arm the guard and swallow the key — asymmetric with
-// PageUp (key number 5) and invisible to the previous tests.
-//
-// A COMPLETE CSI key is user input, never a reply fragment: check it before the head
-// prefixes. Only the terminator decides — geniune cell-size fragments (`\x1b[6;`,
-// `\x1b[6;24`) carry no `u`/`~` and still arm below. `(?:[;:]\d+)*` also covers the
-// alternate-key form (`\x1b[6;1:2;65u`), which a narrower `(?:;\d+)?(?::\d+)?` misses.
-const CSI_KEY_SEQUENCE = /^\x1b\[\d+(?:[;:]\d+)*[u~]$/;
-```
-
-and in `classifyReplyEvent`, after the `FORWARD_SHAPES` loop and **before** the `REPLY_HEADS` loop:
-
-```js
-	// Issue #213: a complete CSI key wins over the head prefixes (see CSI_KEY_SEQUENCE).
-	if (CSI_KEY_SEQUENCE.test(data)) return { kind: "other" };
-```
-
-- [ ] **Step 4: Run the tests to verify they pass**
-
-Run: `node --test test/terminal-reply-guard.test.mjs test/pty-scroll.test.mjs`
-Expected: PASS (the four new tests plus the existing 15).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/core/terminal-reply-guard.mjs test/terminal-reply-guard.test.mjs
-git commit -m "fix(attach): classify complete CSI keys before the reply-guard head prefixes (issue #213)"
-```
-
----
-
-### Task 2: Prove the key actually reaches the child
-
-**Files:**
-- Modify: `test-support/attach-reply-guard-smoke.ts` (new case + result fields)
-- Modify: `test/pty-attach-reply-guard.test.mjs` (assertions)
-
-**Interfaces:**
-- Consumes: `classifyReplyEvent` behaviour from Task 1 through the real `PtyAttachComponent.handleInput`.
-- Produces: `out.guardedPageDown: string[]`, `out.guardedPageDownThenText: string[]` in the smoke's JSON.
-
-- [ ] **Step 1: Write the failing assertions**
-
-In `test/pty-attach-reply-guard.test.mjs`:
-
-```js
-assert.deepEqual(parsed.guardedPageDown, ["\x1b[6;1u", "\x1b[6;5~"], "kitty and modifyOtherKeys PageDown must be forwarded to the child, not swallowed");
-assert.deepEqual(parsed.guardedPageDownThenText, ["\x1b[6;1u", "x"], "text after a key must still be forwarded verbatim");
-```
-
-- [ ] **Step 2: Run to verify it fails**
-
-Run: `node --test test/pty-attach-reply-guard.test.mjs`
-Expected: FAIL — `parsed.guardedPageDown` is `undefined`.
-
-- [ ] **Step 3: Implement the smoke case**
-
-In `test-support/attach-reply-guard-smoke.ts`, next to the existing `guardedFragments` case:
-
-```ts
-	// Issue #213: a complete CSI key must reach the child, not the absorption window.
-	f.attach.handleInput("\x1b[6;1u");
-	f.attach.handleInput("\x1b[6;5~");
-	out.guardedPageDown = [...f.sent];
-
-	// …and the bytes that follow a key are still forwarded verbatim.
-	f.attach.handleInput("\x1b[6;1u");
-	f.attach.handleInput("x");
-	out.guardedPageDownThenText = [...f.sent];
-```
-
-- [ ] **Step 4: Run to verify it passes**
-
-Run: `node --test test/pty-attach-reply-guard.test.mjs`
-Expected: PASS.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add test-support/attach-reply-guard-smoke.ts test/pty-attach-reply-guard.test.mjs
-git commit -m "test(attach): pin that kitty PageDown reaches the child through the reply guard (issue #213)"
-```
-
----
-
-### Task 3: Retire the pinned invariant in the docs
-
-**Files:**
-- Modify: `src/core/terminal-reply-guard.mjs` (module header comment)
-- Modify: `docs/superpowers/specs/2026-10-14-issue-170-attach-reply-guard-design.md` (§3.3 design-points list)
-
-**Interfaces:**
-- Consumes: nothing at runtime; produces the text the A8 static check greps for.
-
-- [ ] **Step 1: Update the module header**
-
-In the `terminal-reply-guard.mjs` header, extend the paragraph that lists what arms a window with:
-
-```
- * Issue #213: `\x1b[6;` is NOT a "can never be a key" prefix — kitty's functional-key
- * encoding puts PageDown at `CSI 6;<mods>u` (and modifyOtherKeys at `\x1b[6;<mods>~`).
- * The rule is therefore "a COMPLETE CSI key sequence (`u`/`~` terminated) beats the head
- * prefixes", not "these prefixes are never keys". Fragments without a terminator still arm.
-```
-
-- [ ] **Step 2: Append the correction to the #170 design doc**
-
-In `docs/superpowers/specs/2026-10-14-issue-170-attach-reply-guard-design.md`, at the end of the §3.3 design-points list (do NOT rewrite L106 — append):
-
-```markdown
-7. **修正（issue #213）**：上一条「`ESC[6;` 永不可能是按键前缀」已被推翻 —— kitty 功能键编码
-   把 PageDown 放在 `CSI 6;<mods>u`（modifyOtherKeys 为 `\x1b[6;<mods>~`），与 cell-size 的
-   `ESC[6;` 共享前缀。现行规则是「**完整 CSI 键序列（以 `u`/`~` 终结）优先于 head 前缀**」，
-   不带终结符的片段仍然武装。实现见 `CSI_KEY_SEQUENCE`。
-```
-
-- [ ] **Step 3: Verify the A8 greps**
-
-Run:
-```bash
-grep -n "complete CSI key" src/core/terminal-reply-guard.mjs
-grep -n "完整 CSI 键序列优先.*#213" docs/superpowers/specs/2026-10-14-issue-170-attach-reply-guard-design.md
-grep -c "can never be a key" src/core/terminal-reply-guard.mjs
-```
-Expected: the first two each match at least once (the first inside the module header, not inside a function body); the third prints 0.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add src/core/terminal-reply-guard.mjs docs/superpowers/specs/2026-10-14-issue-170-attach-reply-guard-design.md
-git commit -m "docs(attach): retire the 'ESC[6; is never a key' invariant (issue #213)"
-```
-
----
-
-### Task 4: Full gate
-
-**Files:** none (verification only).
-
-- [ ] **Step 1: Type/static checks**
-
-Run: `npm run typecheck && npm run pack:dry`
-Expected: both clean.
-
-- [ ] **Step 2: Targeted suites**
-
-Run: `node --test test/terminal-reply-guard.test.mjs test/pty-attach-reply-guard.test.mjs test/pty-scroll.test.mjs test/pty-attach-wheel.test.mjs`
-Expected: all green.
-
-- [ ] **Step 3: Baseline comparison**
-
-Run: `node --test test/pty-attach-*.test.mjs` and compare the failing set against the known Windows-host baseline (same set as on `main`; no new names).
-Expected: no new failures.
-
-- [ ] **Step 4: Commit**
-
-Nothing to commit — this task is the gate the PR description cites.
-
----
-
-### Task 5: Manual verification (U1)
-
-**Files:** none.
-
-- [ ] **Step 1: Load the fix into a real pi**
-
-Per spec §6.1: `pi install "$(pwd)"` (README.md:54) or symlink the worktree to
-`~/.pi/agent/extensions/agent-board`, **not** the `~/.pi/agent/git/...` cache clone.
-
-- [ ] **Step 2: Restart pi completely** and open a new attach session.
-
-- [ ] **Step 3: Press PageDown in the attach view** (WezTerm + pi fullscreen).
-Expected: the panel scrolls one page backwards, mirroring PageUp; no swallowed key.
-
-- [ ] **Step 4: Record the outcome** in the issue (pass/fail + observed behaviour).

package/docs/superpowers/plans/2026-10-19-issue-214-attach-forward-alt-modifier.md

@@ -1,202 +0,0 @@
-# attach forward Alt modifier — Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Preserve the Alt modifier when the attach view forwards a wheel notch to a fullscreen child, so Alt+wheel keeps its 5× accelerator.
-
-**Architecture:** `encodeWheelReport` gains an optional `alt` flag that sets SGR bit 3 (`+8`); `forwardWheelToChild` passes `event.alt === true` through. Nothing else changes — the local scroll path never rebuilds the report.
-
-**Tech Stack:** ESM `.mjs` pure helper, TypeScript component shell, `node:test` + `assert/strict`.
-
-**Spec:** `docs/superpowers/specs/2026-10-19-issue-214-attach-forward-alt-modifier-design.md`
-
-## Global Constraints
-
-- Tabs for indentation; English comments and commit messages (repo AGENTS.md).
-- No new dependencies.
-- Local `npm run verify` cannot go green on this Windows host (pre-existing ~72-test baseline that also fails on `main`); the authoritative local gates are the targeted suites plus `npm run typecheck` and `npm run pack:dry`. CI is the final gate.
-- `alt` must be compared strictly (`=== true`), never by truthiness: a stray `1`/`"yes"` must not set bit 3.
-- Do not touch the local scroll path, the reply guard, or the input classifier.
-
-## Review Focus
-
-- **A truthy non-boolean `alt`** — `alt: 1` and `alt: "yes"` must NOT set bit 3, because the component passes `event.alt === true` (an older pi-tui could hand over something unexpected).
-- **Plain wheel parity** — with no Alt, the encoded report must stay byte-identical to today's (`\x1b[<64;…M` / `\x1b[<65;…M`); the existing #198/#205 assertions must keep passing untouched.
-- **The forward hop is the only seam** — the legacy regular-mode path forwards the raw SGR unchanged and already carries Alt; a change that also rewrote that path would be a scope violation.
-- **Down direction** — `alt + down` is `73`, not `72`; an implementation that ORs the bit onto a fixed 64 would break down-scroll.
-- **Child-side consumption** — the byte must decode as `button & 8 !== 0` under pi-tui's `parseWheelEvent`; `72`/`73` satisfy that and `64`/`65` do not.
-
----
-
-### Task 1: Encode the Alt bit in `encodeWheelReport`
-
-**Files:**
-- Modify: `src/core/pty-scroll.mjs` (`encodeWheelReport`, ~L370)
-- Test: `test/pty-scroll.test.mjs`
-
-**Interfaces:**
-- Produces: `encodeWheelReport(direction: "up"|"down", { col?: number, row?: number, alt?: boolean }) -> string`. Default `alt: false` keeps every existing call site identical.
-
-- [ ] **Step 1: Write the failing tests**
-
-Append to `test/pty-scroll.test.mjs`:
-
-```js
-// Issue #214: Alt is SGR bit 3 (value 8); the child's pi-tui reads it to apply the
-// 5x wheel multiplier, so the forward hop must not strip it.
-test("#214-A1: Alt+wheel-up encodes button 72", () => {
-	assert.equal(encodeWheelReport("up", { col: 5, row: 3, alt: true }), "\x1b[<72;5;3M");
-});
-
-test("#214-A2: Alt+wheel-down encodes button 73", () => {
-	assert.equal(encodeWheelReport("down", { col: 5, row: 3, alt: true }), "\x1b[<73;5;3M");
-});
-
-test("#214-A3: without a strict boolean true, bit 3 stays clear", () => {
-	for (const alt of [false, undefined, null, 0, 1, "yes"]) {
-		assert.equal(encodeWheelReport("up", { col: 5, row: 3, alt }), "\x1b[<64;5;3M", `alt=${String(alt)} must not set bit 3`);
-		assert.equal(encodeWheelReport("down", { col: 5, row: 3, alt }), "\x1b[<65;5;3M", `alt=${String(alt)} must not set bit 3`);
-	}
-});
-```
-
-- [ ] **Step 2: Run the tests to verify they fail**
-
-Run: `node --test test/pty-scroll.test.mjs`
-Expected: FAIL — `#214-A1` gets `\x1b[<64;5;3M` instead of `72`.
-
-- [ ] **Step 3: Implement**
-
-```js
-export function encodeWheelReport(direction, { col, row, alt = false } = {}) {
-	const base = direction === "up" ? 64 : 65;
-	// Issue #214: SGR bit 3 (value 8) is Alt. pi-tui multiplies by 5 when it is set,
-	// so the forward hop must carry it. Strict comparison: a truthy non-boolean must
-	// not flip the bit.
-	const button = alt === true ? base + 8 : base;
-	const cell = (v) => (Number.isFinite(v) ? Math.max(1, Math.floor(v)) : 1);
-	return `\x1b[<${button};${cell(col)};${cell(row)}M`;
-}
-```
-
-Keep the existing JSDoc's description of the direction/coordinates; add one line about `alt`.
-
-- [ ] **Step 4: Run the tests to verify they pass**
-
-Run: `node --test test/pty-scroll.test.mjs`
-Expected: PASS (three new tests plus the existing suite).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/core/pty-scroll.mjs test/pty-scroll.test.mjs
-git commit -m "feat(attach): carry the Alt modifier in the forwarded wheel report (issue #214)"
-```
-
----
-
-### Task 2: Pass `event.alt` through the forward hop
-
-**Files:**
-- Modify: `src/ui/pty-attach.ts` (`forwardWheelToChild`, ~L1477)
-- Modify: `test-support/pty-attach-wheel-fallback-scenario.ts` (new alt round)
-- Modify: `test/pty-attach-wheel-fallback.test.mjs` (new assertions)
-
-**Interfaces:**
-- Consumes: `encodeWheelReport(…, { alt })` from Task 1.
-- Produces: scenario result fields `forwardedAltUp` / `forwardedAltDown`.
-
-- [ ] **Step 1: Write the failing assertion**
-
-In `test/pty-attach-wheel-fallback.test.mjs`, after the existing plain-wheel assertions (which must stay untouched):
-
-```js
-assert.equal(parsed.forwardedAltUp, "\x1b[<72;4;3M", "Alt+wheel-up must reach the child as button 72");
-assert.equal(parsed.forwardedAltDown, "\x1b[<73;4;3M", "Alt+wheel-down must reach the child as button 73");
-```
-
-- [ ] **Step 2: Run to verify it fails**
-
-Run: `node --test test/pty-attach-wheel-fallback.test.mjs`
-Expected: FAIL — `parsed.forwardedAltUp` is `undefined`.
-
-- [ ] **Step 3: Implement**
-
-In `src/ui/pty-attach.ts` `forwardWheelToChild`, add the flag:
-
-```ts
-			data: encodeWheelReport(linesUp > 0 ? "up" : "down", {
-				col: clampInt(event.x + 1, 1, this.cols),
-				row: clampInt(event.y, 1, Math.max(1, this.bodyHeight())),
-				// Issue #214: the overlay already received the Alt bit from pi-tui; carry it
-				// into the synthesized report so the child keeps its 5x wheel accelerator.
-				alt: event.alt === true,
-			}),
-```
-
-In `test-support/pty-attach-wheel-fallback-scenario.ts`, add one more round using the existing `mouseBase` (do not modify the existing rounds, whose assertions are #198's regression pins):
-
-```ts
-	// Issue #214: Alt must survive the forward hop.
-	let beforeAlt = forwardedInputs().length;
-	(component as any).handleMouse({ ...wheelEvent(-3), alt: true });
-	if (await waitFor(() => forwardedInputs().length > beforeAlt, 3000)) {
-		result.forwardedAltUp = forwardedInputs().at(-1) ?? null;
-	}
-	beforeAlt = forwardedInputs().length;
-	(component as any).handleMouse({ ...wheelEvent(2), alt: true });
-	if (await waitFor(() => forwardedInputs().length > beforeAlt, 3000)) {
-		result.forwardedAltDown = forwardedInputs().at(-1) ?? null;
-	}
-```
-
-Declare both fields in the scenario's `result` object (`null as string | null`).
-
-- [ ] **Step 4: Run to verify it passes**
-
-Run: `node --test test/pty-attach-wheel-fallback.test.mjs`
-Expected: PASS — the two new assertions and every existing #198 assertion.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/ui/pty-attach.ts test-support/pty-attach-wheel-fallback-scenario.ts test/pty-attach-wheel-fallback.test.mjs
-git commit -m "fix(attach): forward the Alt modifier on the wheel hop (issue #214)"
-```
-
----
-
-### Task 3: Regression gate
-
-**Files:** none.
-
-- [ ] **Step 1: Targeted suites**
-
-Run: `node --test test/pty-scroll.test.mjs test/pty-attach-wheel-fallback.test.mjs test/pty-attach-wheel.test.mjs test/pty-attach-frame-overflow.test.mjs test/pty-attach-alt-wheel.test.mjs test/pty-attach-mouse-mode.test.mjs test/terminal-reply-guard.test.mjs`
-Expected: all green.
-
-- [ ] **Step 2: Static gates**
-
-Run: `npm run typecheck && npm run pack:dry`
-Expected: both clean.
-
-- [ ] **Step 3: Baseline comparison**
-
-Run: `node --test test/pty-attach-*.test.mjs` and compare the failing set against the known Windows-host baseline. Expected: no new names.
-
----
-
-### Task 4: Manual verification (U1)
-
-**Files:** none.
-
-- [ ] **Step 1: Load this checkout into pi**
-
-`pi install "$(pwd)"` (README.md:54) or symlink to `~/.pi/agent/extensions/agent-board` — **not** the `~/.pi/agent/git/...` cache clone.
-
-- [ ] **Step 2: Restart pi completely**, open a new attach session on a fullscreen child.
-
-- [ ] **Step 3: Hold Alt and roll one wheel notch** in the attach view.
-Expected: the child scrolls 5 lines, matching the behaviour outside attach.
-
-- [ ] **Step 4: Record the outcome** in the issue.

package/docs/superpowers/plans/2026-10-21-issue-221-ask-user-question.md

@@ -1,198 +0,0 @@
-# Recognize `ask_user_question` (name OR questionnaire shape) Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Make an interactive run blocked on `ask_user_question` — or on any tool using the questionnaire arg shape — group under "Needs answer" instead of "RUNNING".
-
-**Architecture:** Two private helpers in `src/core/events.mjs` (`isQuestionArgShape`, `isQuestionToolCall`); the start gate uses `isQuestionToolCall(name, args)`, the end gate becomes name-agnostic and removes by `toolCallId`. Two reducer tests in `test/events.test.mjs` drive the public surface (`createRunStatus` / `reduceEvent` / `projectViewState`).
-
-**Tech Stack:** Node 22, `node:test` + `assert/strict`, plain ESM `.mjs` (no build step).
-
-**Spec:** `docs/superpowers/specs/2026-10-20-issue-221-ask-user-question-design.md`
-
-## Global Constraints
-
-- Tabs for indentation; English comments and commit messages.
-- Conventional commit subject with the PR number appended as `(#N)` (this branch's PR number is filled in at PR time; use `(#221)` for the issue-numbered commits that predate the PR).
-- Run `npm run verify` before claiming completion — `npm test` alone skips the perf gate and coverage thresholds.
-- Do not touch `detectNeedsInput()`, `message_end` classification, or the `"ask_questions"` no-id fallback ids (`events.mjs:242/250`).
-- Detached (non-interactive) runs must keep the legacy `currentTool` behavior.
-
-## Review Focus
-
-- A tool whose args are `{ questions: [] }` or `{ questions: "…" }` must **not** be treated as awaiting input (shape check needs a non-empty array whose first item has a string `question`).
-- Detached runs: the shape fallback must never produce `needs_input` (headless sessions cannot answer).
-- Parallel calls: ending one question must not clear another pending one (existing multi-question test at `test/events.test.mjs:135`).
-- An end event for a non-question tool must be a no-op for `pendingQuestions`.
-- `args` missing entirely on a question-tool start (`ask_questions` with `{}`) must still count via the name set.
-
----
-
-### Task 1: Hybrid question-tool detection
-
-**Files:**
-- Modify: `src/core/events.mjs:20-21` (set), `:86` (start gate), `:100` (end gate), add helpers near `questionFromArgs` (`:232`)
-- Test: `test/events.test.mjs` (append after the existing `interactive pi question tool …` test at `:185-204`)
-
-**Interfaces:**
-- Consumes: `createRunStatus(config, pid, now)`, `reduceEvent(status, event, now, opts)`, `projectViewState(status, now)` from `src/core/events.mjs`.
-- Produces: module-private `isQuestionArgShape(args: unknown): boolean` and `isQuestionToolCall(name: string, args: unknown): boolean`; no exports change.
-
-- [ ] **Step 1: Write the failing tests**
-
-Append to `test/events.test.mjs`:
-
-```js
-test("interactive ask_user_question waits for input and clears on end", () => {
-	const s = createRunStatus(cfg(), 1, 1000);
-	reduceEvent(s, {
-		type: "tool_execution_start",
-		toolCallId: "q1",
-		toolName: "ask_user_question",
-		args: { questions: [{ question: "Which approach?", header: "Approach", options: [{ label: "A", description: "a" }] }] },
-	}, 2000, { interactive: true });
-	assert.equal(s.semanticState, "needs_input");
-	assert.equal(s.summary, "Which approach?");
-	assert.equal(s.question, "Which approach?");
-	assert.equal(s.currentTool, null);
-	assert.deepEqual(s.pendingQuestions, [{ toolCallId: "q1", question: "Which approach?" }]);
-	assert.equal(projectViewState(s, 2100).needsInput, true);
-
-	reduceEvent(s, { type: "tool_execution_end", toolCallId: "q1", toolName: "ask_user_question", isError: false }, 2400, { interactive: true });
-	assert.equal(s.semanticState, "working");
-	assert.equal(s.question, null);
-	assert.deepEqual(s.pendingQuestions, []);
-
-	const detached = createRunStatus(cfg(), 1, 1000);
-	reduceEvent(detached, {
-		type: "tool_execution_start",
-		toolCallId: "q1",
-		toolName: "ask_user_question",
-		args: { questions: [{ question: "Which approach?" }] },
-	}, 2000);
-	assert.equal(detached.semanticState, "working");
-	assert.equal(detached.currentTool.name, "ask_user_question");
-	assert.deepEqual(detached.pendingQuestions, []);
-});
-
-test("interactive unknown questionnaire shape is treated as a pending question", () => {
-	const s = createRunStatus(cfg(), 1, 1000);
-	reduceEvent(s, {
-		type: "tool_execution_start",
-		toolCallId: "q1",
-		toolName: "mystery_questionnaire",
-		args: { questions: [{ question: "Ship it?", header: "Release", options: [{ label: "Yes" }] }] },
-	}, 2000, { interactive: true });
-	assert.equal(s.semanticState, "needs_input");
-	assert.equal(s.question, "Ship it?");
-	assert.equal(s.currentTool, null);
-	assert.deepEqual(s.pendingQuestions, [{ toolCallId: "q1", question: "Ship it?" }]);
-
-	reduceEvent(s, { type: "tool_execution_end", toolCallId: "q1", toolName: "mystery_questionnaire", isError: false }, 2400, { interactive: true });
-	assert.equal(s.semanticState, "working");
-	assert.equal(s.question, null);
-	assert.deepEqual(s.pendingQuestions, []);
-
-	for (const args of [{ questions: [] }, { questions: "nope" }, { command: "ls" }]) {
-		const negative = createRunStatus(cfg(), 1, 1000);
-		reduceEvent(negative, { type: "tool_execution_start", toolCallId: "t1", toolName: "bash", args }, 2000, { interactive: true });
-		assert.equal(negative.semanticState, "working", JSON.stringify(args));
-		assert.deepEqual(negative.pendingQuestions, []);
-	}
-});
-```
-
-- [ ] **Step 2: Run the tests to verify they fail**
-
-Run: `npm test -- --test-name-pattern="ask_user_question|unknown questionnaire"`
-Expected: FAIL — the first test reports `semanticState === "working"` / `summary === "Ask_user_question"`; the second reports `semanticState === "working"` for `mystery_questionnaire`.
-
-- [ ] **Step 3: Implement the detection helpers**
-
-In `src/core/events.mjs`, replace the set definition:
-
-```js
-/** Tool names whose interactive execution blocks on a user answer. */
-const QUESTION_TOOL_NAMES = new Set(["ask_user_question", "ask_questions", "question", "questionnaire"]);
-
-/** Questionnaire args shared by pi/Claude-Code style question tools. */
-function isQuestionArgShape(args) {
-	const questions = Array.isArray(args?.questions) ? args.questions : null;
-	return Boolean(questions && questions.length > 0 && typeof questions[0]?.question === "string");
-}
-
-/** A start event is a question when its name is known or its args carry the questionnaire shape. */
-function isQuestionToolCall(name, args) {
-	return QUESTION_TOOL_NAMES.has(name) || isQuestionArgShape(args);
-}
-```
-
-- [ ] **Step 4: Wire the start and end gates**
-
-In the `tool_execution_start` case, replace
-
-```js
-			if (opts.interactive && QUESTION_TOOL_NAMES.has(name)) {
-```
-
-with
-
-```js
-			if (opts.interactive && isQuestionToolCall(name, args)) {
-```
-
-In the `tool_execution_end` case, replace
-
-```js
-			if (opts.interactive && QUESTION_TOOL_NAMES.has(event.toolName ?? "")) removePendingQuestion(status, event.toolCallId);
-```
-
-with
-
-```js
-			// The end event carries no args, so a shape-matched start cannot be recognized here;
-			// remove by call id instead (a no-op when this call had no pending question).
-			if (opts.interactive) removePendingQuestion(status, event.toolCallId);
-```
-
-- [ ] **Step 5: Run the reducer tests and the whole suite**
-
-Run: `npm test`
-Expected: PASS — the two new tests plus the existing `ask_questions` / `question` / `questionnaire` / parallel-question tests stay green. (A1–A4, A5–A7)
-
-- [ ] **Step 6: Run the full gate**
-
-Run: `npm run verify`
-Expected: PASS — typecheck, perf gate, tests, coverage thresholds (85/80/70), pack dry-run. (A8)
-
-- [ ] **Step 7: Commit**
-
-```bash
-git add src/core/events.mjs test/events.test.mjs
-git commit -m "fix: recognize ask_user_question and questionnaire-shaped tools as pending questions (#221)"
-```
-
----
-
-### Task 2: Post-merge live verification (manual, not a code task)
-
-**Files:** none.
-
-- [ ] **Step 1: Update the board clone the running process loads**
-
-```bash
-cd ~/.pi/agent/git/github.com/zhuxixi/pi-agent-board
-git checkout -- package-lock.json
-git pull
-git log -1 --oneline
-```
-
-Expected: HEAD is the merged commit from this branch.
-
-- [ ] **Step 2: Restart Pi / the board service**, then open the dashboard.
-
-- [ ] **Step 3: Dispatch a session that blocks on `ask_user_question`** (the `@juicesharp/rpiv-ask-user-question` extension is installed at user level), answer it via attach.
-
-Expected: the row sits under **Needs answer** with the question text as summary; after answering it returns to **RUNNING**. (U1)
-
-If the merge has not happened yet, record U1 as `pending` — do not mark it passed.