@zhuxixi/pi-agent-board 0.4.3 → 0.5.1

package/docs/superpowers/plans/2026-08-30-pty-attach-quality-debt.md

@@ -0,0 +1,311 @@
+# pty-attach.ts Legacy Quality Debt Cleanup — 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:** Clear the 10 legacy quality issues in `src/ui/pty-attach.ts` flagged by issue #8 — document 9 intentional empty catches, add a SAFETY comment to 1 as-cast, drop 1 unused parameter. Zero behavior change.
+
+**Architecture:** Single-file comment/signature cleanup. Empty catches are expanded to the repo's documented-catch house style (see `dashboard.ts` precedent); the as-cast gets an invariant comment; `project()` loses its unused `width` parameter. Existing test suite is the regression net — no new tests (no behavior change to test).
+
+**Tech Stack:** TypeScript (strict), `node --test`, tab indentation.
+
+**Spec:** `docs/superpowers/specs/2026-08-30-pty-attach-quality-debt-design.md`
+
+## Global Constraints
+
+- Touch ONLY `src/ui/pty-attach.ts` (plus this plan file's checkboxes).
+- Zero behavior change: no logic added/removed except the parameter deletion and its call-site argument.
+- Indentation is TABS. Comment style: expand `} catch {}` to multi-line with the comment INSIDE the braces, exactly like `dashboard.ts` (`} catch {` / `\t/* best effort: ... */` / `}`).
+- Locate sites by method name, not line number (lines drift).
+- `git add` per file only; NEVER `git add -A` (main checkout has untracked files that must not be swept — the worktree is clean, but keep the habit).
+- Run all commands from the worktree root: `/home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-8-pty-attach-quality-debt`
+
+---
+
+### Task 1: Document the 9 empty catches + the as-cast invariant
+
+**Files:**
+- Modify: `src/ui/pty-attach.ts` (9 catch sites + 1 as-cast site, by method)
+
+**Interfaces:** none changed (comments only).
+
+There are exactly 9 single-line `} catch {}` sites in the file. Each becomes a 3-line documented catch. The edits, by method (old → new). Match surrounding context exactly; indentation is tabs.
+
+1. `enableMouseScroll()` — inside `try { this.tui.terminal.write(XTSHIFTESCAPE_SELECT); this.tui.terminal.write(MOUSE_ENABLE); }`:
+
+```ts
+// OLD
+		} catch {}
+	}
+
+	private mouseScrollEnabled(): boolean {
+// NEW
+		} catch {
+			/* best-effort: some terminals reject these sequences; mouse reporting is optional */
+		}
+	}
+
+	private mouseScrollEnabled(): boolean {
+```
+
+2. `disableMouseScroll()`:
+
+```ts
+// OLD
+	private disableMouseScroll(): void {
+		try {
+			this.tui.terminal.write(MOUSE_DISABLE);
+		} catch {}
+	}
+// NEW
+	private disableMouseScroll(): void {
+		try {
+			this.tui.terminal.write(MOUSE_DISABLE);
+		} catch {
+			/* best-effort: terminal may already be gone at teardown */
+		}
+	}
+```
+
+3. `copySelectionToClipboard()` — the OSC52 write:
+
+```ts
+// OLD
+		if (seq) {
+			try {
+				this.tui.terminal.write(seq);
+			} catch {}
+		}
+// NEW
+		if (seq) {
+			try {
+				this.tui.terminal.write(seq);
+			} catch {
+				/* best-effort: OSC52 clipboard support is optional */
+			}
+		}
+```
+
+4. `pastePrimarySelection()` — inner timer kill:
+
+```ts
+// OLD
+			const timer = setTimeout(() => {
+				try {
+					child.kill("SIGKILL");
+				} catch {}
+			}, 800);
+// NEW
+			const timer = setTimeout(() => {
+				try {
+					child.kill("SIGKILL");
+				} catch {
+					/* the child may have already exited before the timeout fired */
+				}
+			}, 800);
+```
+
+5. `pastePrimarySelection()` — outer catch, at end of method (the `} catch {}` right before the method's closing `}`):
+
+```ts
+// OLD
+			child.on("close", () => {
+				clearTimeout(timer);
+				if (!this.closed && out) this.send({ type: "input", data: out });
+			});
+		} catch {}
+	}
+// NEW
+			child.on("close", () => {
+				clearTimeout(timer);
+				if (!this.closed && out) this.send({ type: "input", data: out });
+			});
+		} catch {
+			/* silent no-op when xclip is absent — documented contract of this helper */
+		}
+	}
+```
+
+6. `writePrimarySelection()`:
+
+```ts
+// OLD
+			child.stdin?.on("error", () => {});
+			child.on("error", () => {});
+			child.stdin?.end(text);
+		} catch {}
+	}
+// NEW
+			child.stdin?.on("error", () => {});
+			child.on("error", () => {});
+			child.stdin?.end(text);
+		} catch {
+			/* silent no-op when xclip is absent */
+		}
+	}
+```
+
+7. `forwardTerminalProtocols()` — the per-sequence write loop:
+
+```ts
+// OLD
+		for (const seq of toWrite) {
+			try {
+				this.tui.terminal.write(seq);
+			} catch {}
+		}
+// NEW
+		for (const seq of toWrite) {
+			try {
+				this.tui.terminal.write(seq);
+			} catch {
+				/* best-effort: forwarded sequences are enhancements, never critical */
+			}
+		}
+```
+
+8. `replayScreenLog()` — outer catch at end of method:
+
+```ts
+// OLD
+			} finally {
+				closeSync(fd);
+			}
+		} catch {}
+	}
+// NEW
+			} finally {
+				closeSync(fd);
+			}
+		} catch {
+			/* best-effort: a missing or racing screen.log must not block attach */
+		}
+	}
+```
+
+9. `close()` — socket destroy:
+
+```ts
+// OLD
+		try {
+			this.socket?.destroy();
+		} catch {}
+		this.socket = null;
+// NEW
+		try {
+			this.socket?.destroy();
+		} catch {
+			/* best-effort teardown: socket may already be destroyed */
+		}
+		this.socket = null;
+```
+
+10. `currentSize()` — SAFETY comment above the as-cast:
+
+```ts
+// OLD
+	private currentSize(): { cols: number; rows: number } {
+		const term = this.tui.terminal as unknown as { cols?: number; columns?: number; rows?: number } | undefined;
+// NEW
+	private currentSize(): { cols: number; rows: number } {
+		// SAFETY: duck-typed read — Pi TUI's Terminal type does not consistently expose
+		// cols/columns/rows across versions (see resizeIfNeeded below). Runtime
+		// fallbacks (120/24) keep this safe when the fields are absent.
+		const term = this.tui.terminal as unknown as { cols?: number; columns?: number; rows?: number } | undefined;
+```
+
+- [ ] **Step 1: Apply all 10 edits** (by method, exact old→new above)
+
+- [ ] **Step 2: Assert no bare `catch {}` remains**
+
+Run: `grep -c "catch {}" src/ui/pty-attach.ts`
+Expected: `0`
+
+- [ ] **Step 3: Typecheck**
+
+Run: `npm run typecheck`
+Expected: clean exit
+
+- [ ] **Step 4: Tests**
+
+Run: `npm test`
+Expected: all pass (no behavior change)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/ui/pty-attach.ts
+git commit -m "chore: document intentional empty catches and as-cast invariant in pty-attach (issue #8)"
+```
+
+---
+
+### Task 2: Drop the unused `width` parameter from `project()`
+
+**Files:**
+- Modify: `src/ui/pty-attach.ts` (signature + single call site)
+
+**Interfaces:**
+- Changes: `private project(height: number, width: number)` → `private project(height: number)` (private; one caller)
+
+The parameter `width` is never read in the method body. `width` at the call site remains used by `resizeIfNeeded(width)` / `renderLoading(...)` / `clip(...)` — only the `project()` argument goes away.
+
+```ts
+// OLD (signature)
+	private project(height: number, width: number): { lines: string[]; cursor: { row: number; col: number } | null } {
+// NEW (signature)
+	private project(height: number): { lines: string[]; cursor: { row: number; col: number } | null } {
+```
+
+```ts
+// OLD (call site, in render(width: number))
+			const projected = this.project(bodyHeight, width);
+// NEW (call site)
+			const projected = this.project(bodyHeight);
+```
+
+- [ ] **Step 1: Apply both edits**
+
+- [ ] **Step 2: Assert single-arg signature and call**
+
+Run: `grep -n "project(" src/ui/pty-attach.ts`
+Expected: exactly 2 hits — `render(...)`'s `this.project(bodyHeight);` and `private project(height: number): ...`
+
+- [ ] **Step 3: Typecheck**
+
+Run: `npm run typecheck`
+Expected: clean exit (a missed call site would fail here)
+
+- [ ] **Step 4: Tests**
+
+Run: `npm test`
+Expected: all pass
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/ui/pty-attach.ts
+git commit -m "chore: drop unused width param from PtyAttachComponent.project (issue #8)"
+```
+
+---
+
+### Task 3: Final verification sweep
+
+**Files:** none modified.
+
+- [ ] **Step 1: Full verify pipeline (same as CI)**
+
+Run: `npm run verify`
+Expected: typecheck + tests + coverage thresholds (lines 85 / funcs 80 / branches 70) + pack dry-run all pass.
+
+- [ ] **Step 2: Zero-behavior diff audit**
+
+Run: `git diff main...HEAD -- src/ui/pty-attach.ts | grep -E "^[+-]" | grep -vE "^(\+\+\+|---)" | grep -vE "^\+\s*(/\*|//|\*/?)" | grep -vE "^-.*catch \{\}" | grep -vE "^\+\s*} catch \{" | grep -vE "^\+\s*}"`
+Expected: exactly 4 lines — the `project` signature and call site (`-`/`+` pairs). Everything else in the raw diff must be comment additions or `catch {}` expansions; any other code line appearing here means behavior changed — investigate before proceeding.
+
+- [ ] **Step 3: Confirm working tree clean**
+
+Run: `git status --short`
+Expected: empty (nothing uncommitted, nothing swept in)
+
+No commit in this task (verification only).

package/docs/superpowers/plans/2026-08-30-readme-v2.md

@@ -0,0 +1,294 @@
+# README v2 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:** Rewrite `README.md` into an accurate, task-oriented English user guide for the current Pi Agent Board package, and correct the stale install command in `VERIFY.md`.
+
+**Architecture:** This is a documentation-only change. `README.md` becomes the primary user-facing guide, organized around installation, first use, dashboard actions, reference behavior, configuration, safety, troubleshooting, and maintainer entry points. `VERIFY.md` receives one supporting-document correction so the linked verification path uses the scoped package name. Source code and `package.json` remain the behavior authority.
+
+**Tech Stack:** Markdown, shell command examples, GitHub/Pi package links, existing Node.js verification scripts.
+
+## Global Constraints
+
+- Keep all user-facing documentation in English; discuss implementation progress in Chinese.
+- Work only in `/home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-51-readme`; do not touch the main checkout.
+- Use `package.json`, `src/index.ts`, `src/commands/*`, `src/ui/dashboard.ts`, `src/ui/pty-attach.ts`, `src/runtime/service.mjs`, and `src/core/*` as the source of truth.
+- Do not advertise worktree isolation, plan-approval UI, provider-stall detection, or other planned/disabled behavior as shipped.
+- State explicitly that worktree isolation is currently disabled and same-repository concurrent writes require user-managed isolation.
+- Do not list internal child markers such as `AGENT_BOARD_CHILD`, `AGENT_BOARD_VIEW_ID`, or `AGENT_BOARD_HOSTED` as user settings.
+- Do not advertise `AGENT_BOARD_ALLOW_PIPE_FALLBACK` as a normal ambient user toggle because the current service does not pass that ambient variable into the PTY runner configuration.
+- Do not hard-code an unverified test count as a durable README claim; use CI and `npm run verify` as the authority.
+- Do not modify runtime code, PRD/history documents, or the main checkout.
+- Do not commit, push, open a PR, or merge without explicit user permission.
+
+## File Map
+
+- Modify: `README.md` — complete user-first guide and reference.
+- Modify: `VERIFY.md` — one stale scoped-package install command.
+- Create: `docs/superpowers/specs/2026-08-30-readme-v2-design.md` — approved design copied into the worktree.
+- Create: `docs/superpowers/plans/2026-08-30-readme-v2.md` — this implementation plan.
+- Inspect only: `package.json`, `src/index.ts`, `src/commands/agent-board.ts`, `src/commands/bg.ts`, `src/ui/dashboard.ts`, `src/ui/pty-attach.ts`, `src/runtime/service.mjs`, `src/core/rows.mjs`, `src/core/auto-state.mjs`, `src/core/launch-options.mjs`, `src/core/code-refs*.mjs`, `.github/workflows/ci.yml`, and `VERIFY.md`.
+
+---
+
+### Task 1: Rewrite README structure and first-use path
+
+**Files:**
+- Modify: `README.md`
+- Inspect: `package.json`, `src/index.ts`, `src/commands/agent-board.ts`, `src/commands/bg.ts`, `src/ui/dashboard.ts`
+
+**Interfaces:**
+- Consumes: package identity and scripts from `package.json`; registered commands/flag from `src/index.ts` and `src/commands/*`; dashboard behavior from `src/ui/dashboard.ts`.
+- Produces: an English README whose first-use path is Requirements → Install → Quick start → Entry points → Dashboard workflow.
+
+- [ ] **Step 1: Replace the product introduction and requirements sections**
+
+Write the opening around the current value proposition: a full-screen TUI for durable background Pi sessions, global cross-project visibility, dashboard triage, inline reply/evidence, and PTY/JSON fallback. Keep the existing banner, demo, package gallery, and npm links if they remain valid.
+
+Add requirements for Pi, Node.js 20+, working Pi provider authentication, and PTY support for live attach/start-and-attach. State that provider authentication is a Pi prerequisite, not an Agent Board credential setup.
+
+Use this package command exactly:
+
+```bash
+pi install npm:@zhuxixi/pi-agent-board
+```
+
+Do not use the unscoped `pi-agent-board` package name.
+
+- [ ] **Step 2: Add installation alternatives and auth sanity check**
+
+Keep three clearly separated paths:
+
+```bash
+# Published package
+pi install npm:@zhuxixi/pi-agent-board
+
+# Local package checkout
+npm install
+pi install "$(pwd)"
+
+# Development auto-discovery
+ln -s "$(pwd)" ~/.pi/agent/extensions/agent-board
+```
+
+Explain that `pi remove "$(pwd)"` applies to the local path installation, while the development symlink must be removed manually. Include the existing one-shot check and explain that it should end with an assistant `message_end`, then `agent_end`, and exit. Link `VERIFY.md` for the complete diagnostic sequence.
+
+- [ ] **Step 3: Add Quick start and entry-point differences**
+
+Add a five-step first-task flow:
+
+1. Press `i` to enter INSERT mode.
+2. Type a task.
+3. Press `Enter` to open **Start session**.
+4. Review cwd, model, thinking, and action.
+5. Press `Enter` to launch.
+
+Document `/agent-board`, `pi /agent-board`, `pi --agent-board`, and `/bg [prompt]`. State that `pi /agent-board` runs the standalone dashboard path and quitting it shuts down Pi; state that `--agent-board` cannot attach to a managed session and normal `/agent-board` is required for attach. Explain that `/bg` adopts the current interactive session and optionally queues a prompt.
+
+- [ ] **Step 4: Verify the first-use section against source**
+
+Check every command and behavior statement against `src/index.ts`, `src/commands/bg.ts`, `src/commands/agent-board.ts`, and the dashboard input handlers. Confirm that draft Enter opens the launch dialog, empty Enter attaches/resumes, and `i` is required before typing in Normal mode.
+
+Run:
+
+```bash
+grep -nE '/agent-board|/bg|agent-board|INSERT|Start session|Enter|attach' README.md src/index.ts src/commands/*.ts src/ui/dashboard.ts
+```
+
+Expected: all advertised entry points and input transitions have matching source evidence and no unscoped install command appears in the new README.
+
+---
+
+### Task 2: Add dashboard, views, states, filters, and attach reference
+
+**Files:**
+- Modify: `README.md`
+- Inspect: `src/ui/dashboard.ts`, `src/ui/pty-attach.ts`, `src/core/rows.mjs`, `src/core/types.mjs`, `src/runtime/service.mjs`, `src/ui/dashboard-evidence.mjs`
+
+**Interfaces:**
+- Consumes: dashboard modes/key handlers, row state/filter helpers, service fallback behavior, and PTY attach input handling.
+- Produces: view-scoped reference sections that do not imply a key works in every dashboard mode.
+
+- [ ] **Step 1: Document dashboard modes, launch dialog, and destructive actions**
+
+Add Normal vs INSERT behavior, including `/` being literal in INSERT mode. Explain the launch dialog fields: cwd picker with favorites/browse and Tab completion, Pi-scoped model choices, supported thinking levels, and background versus start-and-attach. Mention persisted launch preferences and PTY-dependent start-and-attach fallback.
+
+Document exact actions:
+
+- `d` confirms Done for inactive sessions;
+- manual completion is the default;
+- `Ctrl+X` twice quickly archives/deletes a row;
+- archive removes the row from the board but preserves the Pi session file;
+- `X` removes inactive rows in the selected state;
+- `m` enters batch selection with Space/a/u/d/Ctrl+X.
+
+- [ ] **Step 2: Document view-specific shortcuts and capabilities**
+
+Provide separate tables or subsections for Main list, Peek, Transcript, Evidence/Diagnostics, and PTY attach. Include:
+
+- main-list navigation and actions;
+- `Space` Peek;
+- `r` reply only from Peek/Transcript/Evidence, not the main list; in Peek, it enters reply mode and the user presses Enter again after typing to send;
+- `v` read-only transcript;
+- `e` Evidence/Diagnostics and evidence-preserving diagnostic clear with `x`;
+- attach with Enter/Right/`>`;
+- PTY detach with `Left` when the child input is empty; edited input forwards the key, while a disconnected host can always be exited; `Ctrl+]` is passed through to the child Pi editor;
+- attach scroll keys, mouse selection/copy, link opening, and optional middle-click paste.
+
+State that pending Pi question/questionnaire tools require attach and cannot be answered with inline reply.
+
+- [ ] **Step 3: Document states, grouping, unread, queue, and filters**
+
+Document the exact display labels: Queued, Running, Needs answer, Needs instructions, Done, Failed, and Stopped. Explain semantic state versus process liveness, state/folder grouping, pinned-first stable creation ordering, unread indicators, busy follow-up FIFO queue, `qN`, and `queued:true`.
+
+Document this filter syntax:
+
+```text
+s:running
+review:ready
+diag:stalled
+evidence:error
+queued:true
+steer:awaiting-approval
+```
+
+Explain free-text AND matching over name, summary, and cwd, case-insensitive state aliases, and the limitation that `diag:stalled` consumes persisted diagnostics but does not represent a complete current provider-stall detector.
+
+- [ ] **Step 4: Document evidence, code references, and persistence**
+
+Explain Peek's summary/blocker/latest-output surface, transcript projection, Evidence/Diagnostics contents, durable artifacts, and locally extracted issue/PR badges. Mention optional per-root `providers.json` only as an extension point; do not invent an unverified schema.
+
+Explain that busy replies are queued and drained when the session is ready. Explain the high-level store location `~/.pi/agent/agent-board/` and persistence through reload/restart/worker exit.
+
+- [ ] **Step 5: Verify all advertised shortcuts and states**
+
+Run:
+
+```bash
+grep -nE 'handle(List|Select|Peek|Session|Evidence)Key|renderHelp|renderPtyHelp|Ctrl|ctrl\+|review:ready|diag:stalled|evidence:error|queued:|steer:' src/ui/dashboard.ts src/core/rows.mjs
+```
+
+Compare every README shortcut/filter/state claim with the matching source handler. Remove any claim that only exists in PRD or planning documents.
+
+---
+
+### Task 3: Add configuration, safety, troubleshooting, and maintainer links
+
+**Files:**
+- Modify: `README.md`
+- Inspect: `src/core/auto-state.mjs`, `src/core/title.mjs`, `runner/job-runner.mjs`, `runner/title-runner.mjs`, `src/runtime/service.mjs`, `src/ui/pty-attach.ts`, `src/core/pty-support.mjs`, `src/core/paths.mjs`, `.github/workflows/ci.yml`, `package.json`
+
+**Interfaces:**
+- Consumes: supported environment-variable reads, default values, PTY diagnosis behavior, package scripts, CI checks, and existing documentation links.
+- Produces: a complete user-facing configuration table and explicit limitations/troubleshooting path.
+
+- [ ] **Step 1: Replace the incomplete configuration table**
+
+Document these supported user-facing settings with exact defaults and disable values: `AGENT_BOARD_ROOT`, `AGENT_BOARD_AUTO_STATE`, `AGENT_BOARD_AUTO_STATE_MODEL`, `AGENT_BOARD_AUTO_STATE_NO_DONE`, `AGENT_BOARD_SUMMARY_MODEL`, `AGENT_BOARD_TITLE_MODEL`, `AGENT_BOARD_TITLE_THINKING_LEVEL`, `AGENT_BOARD_CODE_REFS`, `AGENT_BOARD_DISABLE_PTY`, `AGENT_BOARD_FORCE_PTY`, `AGENT_BOARD_ATTACH_MOUSE`, `AGENT_BOARD_ENABLE_MOUSE_SCROLL`, `AGENT_BOARD_WHEEL_LINES`, `AGENT_BOARD_MAX_WARM_HOSTS`, `AGENT_BOARD_WARM_HOST_TTL_MS`, `AGENT_BOARD_ATTACH_NATIVE_PASTE`, `AGENT_BOARD_FORWARD_OSC52`, and `AGENT_BOARD_FORWARD_IMAGES`.
+
+State the important default correctly: `AGENT_BOARD_AUTO_STATE_NO_DONE` unset means the user marks Done manually; `0`, `false`, `off`, or `no` restores automatic Done classification. Explain heuristic fallback for summary/title/state model failures where applicable.
+
+Mention selected `AGENT_VIEW_*` names only as compatibility aliases and prefer `AGENT_BOARD_*` for new setup. Exclude internal child markers and do not present `AGENT_BOARD_ALLOW_PIPE_FALLBACK` as an ambient normal-user setting.
+
+- [ ] **Step 2: Add safety, fallback, and troubleshooting sections**
+
+Prominently state that worktree isolation is currently disabled and not automatically created. Same-repository concurrent sessions can run at the same time, so users must avoid overlapping writes or provide their own isolation.
+
+Explain PTY versus JSON-runner fallback, the start-and-attach degradation, adopted external-session PTY requirement, Windows named-pipe/hidden-console capability, and `!` diagnostics. Add symptom-based troubleshooting for stuck Running/auth, `node-pty unavailable`, slow attach/reconnect, rejected inline reply, and same-repository conflicts.
+
+- [ ] **Step 3: Simplify development, publishing, and further reading**
+
+Keep maintainer sections concise:
+
+```bash
+npm install
+npm run verify
+```
+
+Explain that verify runs typecheck, tests, coverage, and package dry-run. Keep publishing as verify, `npm version patch` (or minor/major), and `npm publish`. Link `VERIFY.md`, `PRD.md`, `PROGRESS.md`, and relevant deeper design material without embedding historical progress or a stale numeric test count.
+
+- [ ] **Step 4: Validate configuration and limitation claims**
+
+Run:
+
+```bash
+git grep -nE 'AGENT_BOARD_[A-Z0-9_]+' -- ':!README.md' ':!coverage/**' ':!node_modules/**'
+grep -nE 'DEFAULT_|AUTO_STATE_NO_DONE|AGENT_BOARD_|node-pty|worktree|windows|verify' README.md package.json src/core/*.mjs src/runtime/*.mjs src/ui/*.ts runner/*.mjs .github/workflows/ci.yml
+```
+
+Expected: each public README variable has a source read and an accurate default; internal markers and unsupported worktree claims are absent.
+
+---
+
+### Task 4: Correct VERIFY.md and run documentation validation
+
+**Files:**
+- Modify: `VERIFY.md`
+- Inspect: `README.md`, `VERIFY.md`, `package.json`, all README link targets
+
+**Interfaces:**
+- Consumes: the README's package/install path and the existing verification checklist.
+- Produces: consistent scoped package installation instructions and validation evidence for the documentation change.
+
+- [ ] **Step 1: Correct the stale published-package command**
+
+Replace only this command in `VERIFY.md`:
+
+```bash
+pi install npm:pi-agent-board
+```
+
+with:
+
+```bash
+pi install npm:@zhuxixi/pi-agent-board
+```
+
+Do not change the verification procedure or historical notes beyond this scoped package correction.
+
+- [ ] **Step 2: Check Markdown links and stale wording**
+
+Run:
+
+```bash
+python - <<'PY'
+from pathlib import Path
+import re
+
+for path in (Path("README.md"), Path("VERIFY.md")):
+    text = path.read_text()
+    for line_no, line in enumerate(text.splitlines(), 1):
+        for target in re.findall(r"\]\(([^)]+)\)", line):
+            if target.startswith(("http://", "https://", "#", "mailto:")):
+                continue
+            candidate = (path.parent / target.split("#", 1)[0]).resolve()
+            if not candidate.exists():
+                raise SystemExit(f"broken link: {path}:{line_no}: {target}")
+print("relative Markdown links: OK")
+PY
+
+grep -RInE 'pi install npm:pi-agent-board|default: enabled|300\+ tests|r.*reply' README.md VERIFY.md || true
+```
+
+Expected: no broken relative links, no stale unscoped package command, no ambiguous auto-done wording, and no stale test-count claim.
+
+- [ ] **Step 3: Run repository verification and inspect the final diff**
+
+Run from the issue worktree:
+
+```bash
+npm run typecheck
+npm test
+npm run pack:dry
+git diff --check
+git diff --stat
+git status --short
+```
+
+Expected: typecheck succeeds, the clean worktree baseline remains 416/416 tests with 0 failures, package dry-run succeeds, `git diff --check` is clean, and the diff contains only the approved spec/plan plus `README.md` and the one-line `VERIFY.md` correction.
+
+Do not include the main checkout's untracked PTY tests in this evidence. Do not claim the main checkout is green while those unrelated tests remain failing.
+
+- [ ] **Step 4: Prepare issue progress and handoff**
+
+Record in the Issue #51 progress comment: the isolated worktree path, the documentation files changed, validation commands and results, any residual source-of-truth caveats, and the fact that no push/PR/merge was performed. Stop before pushing or opening a PR and request explicit user permission.

package/docs/superpowers/specs/2026-08-21-attach-coldstart-jiggle-rearm-design.md

@@ -1,5 +1,9 @@
 # Spec：attach 冷启动双光标根治 — jiggle 重试链编排修复（issue #10）
 
+> **历史设计，已被 issue #25 的 shrink-and-hold 及 issue #42 的 G6
+> post-restore verify supersede。** 当前实现和测试以
+> `src/core/pty-attach-jiggle-controller.mjs` 为准。
+
 ## 日期
 2026-08-21（v2：评审后修订，补三项编排严谨性修正）
 

package/docs/superpowers/specs/2026-08-22-jiggle-shrink-and-hold-design.md

@@ -1,5 +1,9 @@
 # Spec：attach jiggle 协议改造 — shrink-and-hold（issue #25）
 
+> **历史设计，部分内容已被 issue #42 superseded。** 当前实现保留 G1–G5，
+> 并在首帧快速 restore 后增加 G6 post-restore verify：900ms 内没有 clear
+> 时重新 shrink；attach detach 只使用空输入时的 `←`，`ctrl+]` 透传给 Pi。
+
 ## 日期
 2026-08-22