@huseynsnmz/pi-board 0.15.3 → 0.17.0

package/docs/superpowers/plans/2026-08-22-question-tool-grouping.md

@@ -1,211 +0,0 @@
-# Question/Questionnaire Tool Grouping Fix 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 pi sessions blocked on the `question`/`questionnaire` tools group under "Needs answer" instead of "Running".
-
-**Architecture:** Two minimal changes to `src/core/events.mjs`: (1) extend the private `questionFromArgs` helper to read pi's arg shapes; (2) replace the hardcoded `=== "ask_questions"` name checks with a `QUESTION_TOOL_NAMES` set. All downstream behavior (needs_input state, grouping, summary) already exists via `preservePendingQuestion` and `deriveSummary` — verified in spec section 3.3, nothing else changes.
-
-**Tech Stack:** Node.js (`.mjs` ESM, no deps), `node:test` + `node:assert/strict` for tests.
-
-## Global Constraints
-
-- All code changes confined to `src/core/events.mjs` and `test/events.test.mjs`.
-- No store/schema/type changes; no changes to `finalizeRun`, `projectViewState`, `deriveSummary`, `rows.mjs`, `service.mjs`.
-- Non-interactive (detached) reduction path keeps its current behavior — the `opts.interactive` gate stays.
-- Static name set, no config surface.
-- Commit messages in conventional commits format; stage files individually (`git add <file>`), never `git add -A`.
-- Test command: `node --test test/events.test.mjs`; project gate: `npm run verify`.
-- Work in worktree `/home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-26-question-tool-grouping`; never touch main.
-
----
-
-### Task 1: Extend `questionFromArgs` for pi arg shapes
-
-**Files:**
-- Modify: `src/core/events.mjs:229-235`
-- Test: `test/events.test.mjs` (append new test near the ask_questions tests, after line 160)
-
-**Interfaces:**
-- Consumes: nothing new.
-- Produces: `questionFromArgs(args)` (private) returns the first non-empty question text from: `args.question` (string), or `args.questions[]` items' `question` or `prompt` fields; falls back to `"Answer the pending question"`. Task 2's name-recognition relies on this extraction.
-
-- [ ] **Step 1: Write the failing test**
-
-Append to `test/events.test.mjs` (after the "interactive questions remain visible..." test):
-
-```js
-test("questionFromArgs extracts pi question/questionnaire arg shapes", () => {
-	// pi `question` tool shape: args.question is a plain string.
-	const s1 = createRunStatus(cfg(), 1, 1000);
-	reduceEvent(s1, {
-		type: "tool_execution_start",
-		toolCallId: "q1",
-		toolName: "ask_questions",
-		args: { question: "Approve the plan?" },
-	}, 2000, { interactive: true });
-	assert.equal(s1.question, "Approve the plan?");
-
-	// pi `questionnaire` tool shape: args.questions[].prompt.
-	const s2 = createRunStatus(cfg(), 1, 1000);
-	reduceEvent(s2, {
-		type: "tool_execution_start",
-		toolCallId: "q1",
-		toolName: "ask_questions",
-		args: { questions: [{ prompt: "Pick the scope?" }] },
-	}, 2000, { interactive: true });
-	assert.equal(s2.question, "Pick the scope?");
-});
-```
-
-Note: the tests route through the reducer with the already-recognized `ask_questions` name because `questionFromArgs` is private and the reducer is the public surface; name recognition for the pi tools lands in Task 2.
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `node --test test/events.test.mjs`
-Expected: FAIL — both assertions get `"Answer the pending question"` (the current extractor only reads `questions[].question`).
-
-- [ ] **Step 3: Implement the extractor**
-
-Replace the body of `questionFromArgs` in `src/core/events.mjs` (L229-235):
-
-```js
-function questionFromArgs(args) {
-	if (typeof args?.question === "string" && args.question.trim()) return args.question.trim();
-	for (const item of Array.isArray(args?.questions) ? args.questions : []) {
-		const question = String(item?.question ?? item?.prompt ?? "").trim();
-		if (question) return question;
-	}
-	return "Answer the pending question";
-}
-```
-
-- [ ] **Step 4: Run tests to verify they pass**
-
-Run: `node --test test/events.test.mjs`
-Expected: PASS (all 17 existing + 1 new test).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/core/events.mjs test/events.test.mjs
-git commit -m "fix: support pi question arg shapes in questionFromArgs (issue #26)"
-```
-
----
-
-### Task 2: Recognize `question`/`questionnaire` as pending-question tools
-
-**Files:**
-- Modify: `src/core/events.mjs:25-27` (insert set), `src/core/events.mjs:83`, `src/core/events.mjs:97`
-- Test: `test/events.test.mjs` (append three tests after the Task 1 test)
-
-**Interfaces:**
-- Consumes: `questionFromArgs` extraction from Task 1.
-- Produces: `QUESTION_TOOL_NAMES` (module-private `Set<string>`). `reduceEvent` treats any interactive tool_execution_start/end whose tool name is in the set as a pending-question event — `upsertPendingQuestion`/`removePendingQuestion` plus the existing `preservePendingQuestion` flow (needs_input state, `currentTool = null`).
-
-- [ ] **Step 1: Write the failing tests**
-
-Append to `test/events.test.mjs`:
-
-```js
-test("interactive pi question tool is treated as a pending question", () => {
-	const s = createRunStatus(cfg(), 1, 1000);
-	reduceEvent(s, {
-		type: "tool_execution_start",
-		toolCallId: "q1",
-		toolName: "question",
-		args: { question: "Approve the plan?", options: [{ label: "Yes" }, { label: "No" }] },
-	}, 2000, { interactive: true });
-	assert.equal(s.semanticState, "needs_input");
-	assert.equal(s.question, "Approve the plan?");
-	assert.equal(s.currentTool, null);
-	assert.equal(s.summary, "Approve the plan?");
-	assert.deepEqual(s.pendingQuestions, [{ toolCallId: "q1", question: "Approve the plan?" }]);
-	assert.equal(projectViewState(s, 2100).needsInput, true);
-
-	reduceEvent(s, { type: "tool_execution_end", toolCallId: "q1", toolName: "question", isError: false }, 2400, { interactive: true });
-	assert.equal(s.semanticState, "working");
-	assert.equal(s.question, null);
-	assert.deepEqual(s.pendingQuestions, []);
-});
-
-test("interactive questionnaire tool extracts prompt and clears on end", () => {
-	const s = createRunStatus(cfg(), 1, 1000);
-	reduceEvent(s, {
-		type: "tool_execution_start",
-		toolCallId: "q1",
-		toolName: "questionnaire",
-		args: { questions: [{ prompt: "Pick the scope?" }] },
-	}, 2000, { interactive: true });
-	assert.equal(s.semanticState, "needs_input");
-	assert.equal(s.question, "Pick the scope?");
-	reduceEvent(s, { type: "tool_execution_end", toolCallId: "q1", toolName: "questionnaire", isError: false }, 2400, { interactive: true });
-	assert.equal(s.semanticState, "working");
-});
-
-test("detached question tool keeps legacy currentTool behavior", () => {
-	const s = createRunStatus(cfg(), 1, 1000);
-	reduceEvent(s, { type: "tool_execution_start", toolCallId: "q1", toolName: "question", args: { question: "Approve?" } }, 2000);
-	assert.equal(s.semanticState, "working");
-	assert.equal(s.currentTool.name, "question");
-	assert.deepEqual(s.pendingQuestions, []);
-});
-```
-
-- [ ] **Step 2: Run tests to verify they fail**
-
-Run: `node --test test/events.test.mjs`
-Expected: FAIL — question/questionnaire names are not recognized: first test asserts `needs_input` but gets `working` with `currentTool.name === "question"`.
-
-- [ ] **Step 3: Add the name set and wire the two checks**
-
-Insert after the imports at the top of `src/core/events.mjs` (before `createRunStatus`, ~L25):
-
-```js
-/** Tool names whose interactive execution blocks on a user answer. */
-const QUESTION_TOOL_NAMES = new Set(["ask_questions", "question", "questionnaire"]);
-```
-
-Replace L83:
-
-```js
-			if (opts.interactive && QUESTION_TOOL_NAMES.has(name)) {
-```
-
-Replace L97:
-
-```js
-			if (opts.interactive && QUESTION_TOOL_NAMES.has(event.toolName ?? "")) removePendingQuestion(status, event.toolCallId);
-```
-
-- [ ] **Step 4: Run tests to verify they pass**
-
-Run: `node --test test/events.test.mjs`
-Expected: PASS (21 tests total: 17 existing + 1 Task 1 + 3 new). Existing `ask_questions` tests must pass unchanged.
-
-- [ ] **Step 5: Full project gate**
-
-Run: `npm run verify`
-Expected: typecheck, all tests, and pack dry-run pass.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/core/events.mjs test/events.test.mjs
-git commit -m "fix: recognize question/questionnaire tools as pending questions (issue #26)"
-```
-
----
-
-## Self-Review
-
-**Spec coverage:**
-- Spec 3.1 (QUESTION_TOOL_NAMES replacing both hardcoded checks) → Task 2 steps 3. ✓
-- Spec 3.2 (questionFromArgs pi shapes: `args.question`, `items[].prompt`, fallback `item.question`) → Task 1 step 3. ✓
-- Spec 3.4 tests 1-4 (question start→needs_input, questionnaire extraction, end→working, detached unchanged) → Task 2 step 1 + Task 1 step 1. ✓
-- Spec 3.3 downstream flow unchanged → asserted via `summary`/`needsInput` in Task 2 test 1; no production code touched outside `events.mjs`. ✓
-
-**Placeholder scan:** every step carries concrete code or exact commands; no TBD/TODO/"similar to". ✓
-
-**Type consistency:** `QUESTION_TOOL_NAMES` used identically in both replace steps; arg fields (`question`, `questions[].prompt`) match the pi extension schemas (`~/.pi/agent/extensions/question.ts`, `questionnaire.ts`). ✓

package/docs/superpowers/plans/2026-08-22-rename-state-labels.md

@@ -1,182 +0,0 @@
-# Rename State Labels 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:** Rename dashboard state labels so each waiting state names the user action it waits for: `needs_input` → "Needs answer", `idle` → "Needs instructions", plus header wording "awaiting input" → "needs answer".
-
-**Architecture:** Display-only rename riding the existing label pipeline: `GROUP_LABELS` (group headers, confirm prompts, filter aliases) and `fallbackStatusText` (row summaries) are the two label sources; persisted summaries normalize at render time via `normalizeGenericStatusText` + `GENERIC_STATUS_TEXT` legacy sets, so old rows migrate visually with zero data writes.
-
-**Tech Stack:** Node.js ESM (`.mjs`) core + TypeScript UI file, `node --test` test runner, JSDoc typedefs.
-
-## Global Constraints
-
-- No changes to `SEMANTIC_STATES`, store schemas, state transitions, or classifier internals (issue #14's scope).
-- `GENERIC_STATUS_TEXT` sets only ever GROW — "Needs input", "Idle", "In Progress" must remain recognized legacy texts.
-- Do NOT edit `PRD.md` or `IMPLEMENTATION_PLAN.md` (historical point-in-time docs).
-- Commit messages in English, conventional-commits format; stage files explicitly (never `git add -A`).
-- All work happens in the worktree `/home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-15-rename-state-labels` (branch `issue-15-rename-state-labels`). Never touch the main checkout.
-- Exact new labels: `"Needs answer"` (needs_input), `"Needs instructions"` (idle), header `"needs answer"` / compact `"answer"`.
-
----
-
-### Task 1: Core label constants and normalization (types.mjs, derive.mjs)
-
-**Files:**
-- Modify: `src/core/types.mjs:65,70` (`GROUP_LABELS`)
-- Modify: `src/core/derive.mjs:19-20,52-54` (`GENERIC_STATUS_TEXT`, `fallbackStatusText`)
-- Test: `test/derive.test.mjs:92-98`, `test/rows.test.mjs:85-88`
-
-**Interfaces:**
-- Consumes: none (leaf change).
-- Produces: `GROUP_LABELS.needs_input === "Needs answer"`, `GROUP_LABELS.idle === "Needs instructions"`; `fallbackStatusText("needs_input") === "Needs answer"`, `fallbackStatusText("idle") === "Needs instructions"`; `normalizeGenericStatusText` recognizes "Needs input" → needs_input label, {"Idle","In Progress"} → idle label.
-
-- [ ] **Step 1: Update the failing tests**
-
-In `test/derive.test.mjs`, extend the import (line 3) and replace/extend the fallback test:
-
-```js
-import { deriveSummary, fallbackStatusText, finalizeSemanticState, normalizeGenericStatusText } from "../src/core/derive.mjs";
-```
-
-```js
-test("fallbackStatusText", () => {
-	assert.equal(fallbackStatusText("queued"), "Queued");
-	assert.equal(fallbackStatusText("working"), "Running…");
-	assert.equal(fallbackStatusText("needs_input"), "Needs answer");
-	assert.equal(fallbackStatusText("idle"), "Needs instructions");
-});
-
-test("normalizeGenericStatusText maps legacy labels to current ones", () => {
-	assert.equal(normalizeGenericStatusText("idle", "Idle"), "Needs instructions");
-	assert.equal(normalizeGenericStatusText("idle", "In Progress"), "Needs instructions");
-	assert.equal(normalizeGenericStatusText("needs_input", "Needs input"), "Needs answer");
-	assert.equal(normalizeGenericStatusText("idle", "Custom summary"), "Custom summary");
-});
-```
-
-In `test/rows.test.mjs`, replace the existing normalization test (lines 85-88) with:
-
-```js
-test("rowView normalizes generic status labels to current display names", () => {
-	assert.equal(rowView(row("a", "working", { summary: "Working…" }), 0).summary, "Running…");
-	assert.equal(rowView(row("b", "idle", { summary: "Idle" }), 0).summary, "Needs instructions");
-	assert.equal(rowView(row("c", "idle", { summary: "In Progress" }), 0).summary, "Needs instructions");
-	assert.equal(rowView(row("d", "needs_input", { summary: "Needs input" }), 0).summary, "Needs answer");
-});
-```
-
-(`row(id, state, overrides)` is the existing test helper in that file.)
-
-- [ ] **Step 2: Run tests to verify they fail**
-
-Run: `cd /home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-15-rename-state-labels && npm ci --no-audit --no-fund && node --test test/derive.test.mjs test/rows.test.mjs`
-Expected: FAIL — fallbackStatusText/rowView assertions return "Needs input"/"In Progress". (Skip `npm ci` if node_modules already exists.)
-
-- [ ] **Step 3: Implement**
-
-`src/core/types.mjs` — in `GROUP_LABELS`:
-
-```js
-needs_input: "Needs answer",
-```
-```js
-idle: "Needs instructions",
-```
-
-`src/core/derive.mjs` — legacy sets (keep old entries, add new):
-
-```js
-needs_input: new Set(["Needs input", "Needs answer"]),
-idle: new Set(["Idle", "In Progress", "Needs instructions"]),
-```
-
-`fallbackStatusText` cases:
-
-```js
-		case "needs_input":
-			return "Needs answer";
-		case "idle":
-			return "Needs instructions";
-```
-
-- [ ] **Step 4: Run tests to verify they pass**
-
-Run: `node --test test/derive.test.mjs test/rows.test.mjs`
-Expected: PASS (all tests in both files).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/core/types.mjs src/core/derive.mjs test/derive.test.mjs test/rows.test.mjs
-git commit -m "feat: rename needs_input/idle labels to Needs answer/Needs instructions (issue #15)"
-```
-
-### Task 2: Call-site labels and header wording (service.mjs, dashboard.ts, README)
-
-**Files:**
-- Modify: `src/runtime/service.mjs:961` (reconciled-host summary)
-- Modify: `src/ui/dashboard.ts:926` (compat-guard blank state summary), `src/ui/dashboard.ts:1757` (header stage part)
-- Modify: `README.md:65` (state list)
-- Test: none new — grep-confirmed zero test assertions on these exact strings; suite must stay green.
-
-**Interfaces:**
-- Consumes: Task 1 label values (only literals here; no imports of the strings).
-- Produces: none.
-
-- [ ] **Step 1: Edit the four call sites**
-
-`src/runtime/service.mjs` (~L961, inside `reconcile()`):
-```js
-s.summary = failed ? "Failed (PTY host exited)" : "Needs instructions";
-```
-
-`src/ui/dashboard.ts` (~L926, blank-state compat guard):
-```js
-			summary: "Needs instructions",
-```
-
-`src/ui/dashboard.ts` (~L1757, `headerStageSummary`):
-```js
-		headerStagePart(theme, "needs_input", counts.needs, compact ? "answer" : "needs answer"),
-```
-
-`README.md` (L65):
-```markdown
-- Watch rows move through `Queued`, `Running`, `Needs answer`, `Needs instructions`, `Done`, `Failed`, and `Stopped`.
-```
-
-- [ ] **Step 2: Run the full suite and typecheck**
-
-Run: `npm test && npm run typecheck`
-Expected: PASS — `node --test test/*.test.mjs` all green, `tsc --noEmit` clean.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add src/runtime/service.mjs src/ui/dashboard.ts README.md
-git commit -m "feat: apply Needs answer/Needs instructions wording to service, header, and README (issue #15)"
-```
-
-### Task 3: Full verification gate
-
-**Files:**
-- Modify: none (verification only; fix and amend-with-new-commit if anything fails).
-
-**Interfaces:**
-- Consumes: Tasks 1-2.
-- Produces: verified branch ready for review.
-
-- [ ] **Step 1: Run the project's standard gate**
-
-Run: `npm run verify`
-Expected: typecheck + full test suite + pack:dry all pass.
-
-- [ ] **Step 2: Sweep for stale label strings**
-
-Run: `grep -rn '"In Progress"' src/ README.md; grep -rn 'awaiting input' src/`
-Expected: "In Progress" appears ONLY in `src/core/derive.mjs` legacy set; "awaiting input" zero hits.
-
-- [ ] **Step 3: Confirm clean tree**
-
-Run: `git status --short && git log --oneline main..HEAD`
-Expected: clean tree; commits = spec + task 1 + task 2.

package/docs/superpowers/plans/2026-08-22-stable-list-order.md

@@ -1,51 +0,0 @@
-# Stable List Order Fix 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 the dashboard list order stable — rows must never reshuffle while sessions are running, so the cursor never loses its target (issue #20).
-
-**Architecture:** Replace activity-time sort keys with fixed creation-time keys. `lastActivityAt` stays in `RowView` for the "3s ago" display only, never for ordering. Rows sort by `pinned desc → createdAt asc → id asc`; folders sort by `pinned desc → min(createdAt) asc → name asc`, so a folder's position is anchored by its first-created row and doesn't jump when any row inside gets busy. New sessions append at the bottom (createdAt ascending).
-
-**Tech Stack:** Node 20+, ESM JavaScript (`.mjs` core), `node --test` test runner, no new dependencies.
-
-## Global Constraints
-
-- No new npm dependencies.
-- All commits in this worktree branch `issue-20-stable-list-order`; never touch `main` checkout.
-- `git add` per-file; never `git add -A`.
-- Commit messages in English, conventional-commits format, reference `issue #20`.
-- `npm run verify` (typecheck + tests + pack dry-run) must pass before the PR.
-
----
-
-### Task 1: Stable row sort in `sortRowViews`
-
-**Files:**
-- Modify: `src/core/rows.mjs` (function `sortRowViews`)
-- Test: `test/rows.test.mjs`
-
-- [x] Add `createdAt` to `RowView` typedef and `rowView()` output (fallback `meta.updatedAt ?? 0`).
-- [x] Change sort keys to `pinned desc → createdAt asc → id asc`.
-- [x] Update `groupRows` doc comment ("pinned first, then creation order").
-- [x] Rewrite `groupRows sorts pinned first then recent` test → creation order, plus new regression test `groupRows ignores activity recency so order stays stable`.
-
-### Task 2: Stable folder sort in `groupRowsByFolder`
-
-**Files:**
-- Modify: `src/core/rows.mjs` (function `groupRowsByFolder`)
-- Test: `test/rows.test.mjs`
-
-- [x] Folder key `lastActivityAt` → `createdAt`, computed as `Math.min` over folder rows (first-created row anchors the folder).
-- [x] Folder sort keys → `pinned desc → createdAt asc → name asc`; update JSDoc return type.
-- [x] Update `groupRowsByFolder nests rows by folder inside each stage` expectations, plus new regression test `groupRowsByFolder keeps folder order stable regardless of activity`.
-
-### Task 3: Verify
-
-- [x] `node --test test/rows.test.mjs` — 18 pass.
-- [x] `npm run verify` — typecheck + full suite (200 pass) + pack dry-run.
-
-## Non-goals
-
-- Display of relative age ("3s ago") unchanged — still activity-based.
-- State-group order (`GROUP_ORDER`) unchanged — already fixed.
-- No reordering of the roster on disk; ordering is a pure view-model concern.