@rmrdeveloper/sideroom-pi 5.0.1 → 7.0.0

package/README.md

@@ -5,26 +5,31 @@
 [![npm license](https://img.shields.io/npm/l/@rmrdeveloper/sideroom-pi?label=license)](https://www.npmjs.com/package/@rmrdeveloper/sideroom-pi)
 
 Sideroom Pi is a global [Pi package](https://pi.dev/docs/latest/packages). It
-registers the `/sideroom` command inside Pi and runs planner, implementer,
-reviewer, verifier, and fixer as isolated Pi SDK sessions.
+registers two parent-agent tools: `sideroom_ask`, a TUI questionnaire for
+clarifying decisions, and `sideroom_todo`, a live work board shown above the
+editor. It also shows a session-scoped list of files successfully edited by Pi,
+and steers write/edit toward packaged coding guidelines. It writes no `.pi`
+configuration, task graph, or other Sideroom files into the repository you are
+working in.
 
-It creates no `.pi` configuration, task graph, harness state, or other files
-in the repository being changed.
+## Quick path
 
-## Install
+1. Install globally from npm. Pi writes this installation to your user
+   settings, so do not use `-l`.
 
-Install Sideroom globally from npm. Pi writes this installation to your user
-settings, so do not use `-l`.
+   ```bash
+   pi install npm:@rmrdeveloper/sideroom-pi
+   ```
 
-```bash
-pi install npm:@rmrdeveloper/sideroom-pi
-```
+2. Start Pi in the repository you want to work in.
+3. Ask the parent agent a question that needs a decision or a visible work
+   board. It can call `sideroom_ask` or `sideroom_todo` in the TUI.
 
-For a reproducible environment, install a specific release instead. A pinned
-version does not move when you run Pi's package update command.
+For a reproducible environment, pin a release. A pinned version does not move
+when you run Pi's package update command.
 
 ```bash
-pi install npm:@rmrdeveloper/sideroom-pi@5.0.0
+pi install npm:@rmrdeveloper/sideroom-pi@7.0.0
 ```
 
 To update an unpinned installation:
@@ -33,74 +38,91 @@ To update an unpinned installation:
 pi update --extension npm:@rmrdeveloper/sideroom-pi
 ```
 
-Start Pi from the repository you want to work in, then invoke the extension:
-
-```text
-/sideroom "Add a health endpoint"
-/sideroom --language php-laravel "Add invoice export"
-/sideroom --read-only "Review the retry behavior"
-```
-
-Pi extension commands are necessarily slash commands, so `/sideroom` is the
-single command; there is no subcommand or separate binary to run. When the
-request is omitted, Pi asks for it using its own UI.
-
-Supported guideline variants are `typescript` (default), `javascript`,
-`php-laravel`, `python`, and `java`. `--read-only` removes write-capable tools
-from every role. `--max-fix-passes <number>` changes the default limit of two
-repair passes.
-
-## Provenance and isolation
-
-`/sideroom` is dispatched to the extension before Pi expands skills or sends
-the command to the interactive agent. The extension then creates direct,
-in-memory SDK sessions for the five Sideroom roles. Those child sessions load
-only this package's skills and explicit policy; global Pi skills, extensions,
-prompt templates, and global context files are excluded.
-
-At the end of every run, Pi displays a `Sideroom completed` or `Sideroom
-failed` message with its provenance and the completed roles. It also records
-the same trace in Pi's session history as `sideroom:run`; this is Pi session
-metadata, never a file in the target repository.
-
-The packaged `sideroom-grilling` skill runs as the design-decision gate. Its
-questions use Pi's native decision UI. During a run, a persistent Pi widget
-shows the active phase, the waiting-for-answer state, and the direct-SDK
-provenance. Selecting a recommendation accepts it; selecting the alternate
-option opens a custom-answer field. The widget is removed automatically when a
-run completes or fails; the final Pi session message remains as the durable
-record. It is not a request to any global skill with the same name.
-
-## Content and guidelines
-
-The five role prompts are in `src/assets/agents/`. The shared policy is
-`src/assets/artifacts/GUIDELINES_TEMPLATE.md`; the language layers live in
-`src/assets/artifacts/guidelines/`. Implementer and fixer receive those
-policies before their write gate and must read them before every code-writing
-tool call.
-
-Reusable Pi skills ship in `skills/`: `sideroom-grilling`, `sideroom-critic`,
-`sideroom-spec`, and `sideroom-transcribe-audio`. Pi loads them directly through
-the package manifest.
-The transcription skill needs `uv`, Python, and `ffmpeg` only when explicitly
-used.
+## Details
+
+| Topic | Decision |
+| --- | --- |
+| Surface | Two LLM-callable tools: `sideroom_ask` and `sideroom_todo`. No `/sideroom` command. |
+| Questionnaire | One `sideroom_ask` call is one 1–N question batch; every question has `recommendationIndex`. |
+| Always-on rows | The questionnaire UI adds Out of scope and a custom answer. Do not send those options. |
+| Work board | `sideroom_todo propose` replaces a visible board; `update` patches items by id. |
+| Headless | `sideroom_todo update` works in print, JSON, and RPC. `propose` and `sideroom_ask` return `Error: UI not available` there. |
+| Edited files | Successful `write` and `edit` results appear below an active work board; `F8` opens the full list. |
+| Session state | The work board and edited-file history live in the Pi session branch, not in the target repository. |
+| Coding guidelines | A short system-prompt reminder points at the `sideroom-guidelines` skill. Language deltas load on demand. |
+| Seed artifact | `assets/artifacts/GUIDELINES_TEMPLATE.md` is the canonical seed; it is not dumped into the prompt. |
+
+## Tool
+
+`sideroom_ask` follows Pi's questionnaire UI: a simple list for one question,
+tabs plus Submit for several. Write prompts, tab labels, and option copy in
+the language the user is speaking; ids, option values, and TUI chrome stay
+English. Each question needs:
+
+- `id`
+- `prompt`
+- at least two `{ value, label, description? }` options
+- `recommendationIndex` pointing at the recommended option
+- optional `label` for the tab bar (defaults to `Q1`, `Q2`, …)
+
+The recommended option is marked in the list. Escape cancels the batch.
+
+## Work board
+
+`sideroom_todo` keeps an ordered, display-only board above the editor. The
+agent maintains it and the user steers through chat. It never creates a
+repository task file or a `/todos` command.
+
+- `propose` replaces the full board and is available only in the interactive
+  TUI.
+- `update` applies one or more `{ id, status?, content? }` patches and works in
+  every Pi mode.
+- Items have stable string ids, short content, and one of `pending`,
+  `in_progress`, `completed`, or `cancelled`.
+- While items are pending, exactly one item must be `in_progress`. Complete the
+  current item and start the next one in the same update.
+- Snapshots are stored in the active session branch. The board is rebuilt after
+  session navigation and compaction.
+
+## Edited files
+
+The package automatically records successful Pi `write` and `edit` calls for
+the active session. It does not infer filesystem changes from shell commands,
+Git, people, or subagents. The compact list is shown below the work board when
+one is active and contains at most five recent paths.
+
+- `F8` opens or closes the extended, scrollable list; press `R` there
+  to clear the current session's history.
+- Every path is an OSC 8 `file://` link. Your terminal determines whether that
+  is a click, Ctrl+click, or another modifier-assisted action.
+- Paths outside the active project are labelled `external`.
+- A new session starts with a new list; the current session's history survives
+  reload, tree navigation, and compaction.
+
+## Coding guidelines
+
+Before `write` or `edit`, the parent agent is reminded to read the packaged
+`sideroom-guidelines` skill. That skill holds the shared Do/Don't table. For
+`.java`, `.php`, `.ts`/`.tsx`, `.py`, `.go`, and `.rs`, the agent also reads one
+matching file under `skills/sideroom-guidelines/references/languages/`. Other
+languages follow the shared table only.
 
 ## Development
 
 ```bash
 npm install
 npm run check
-npm run build
 ```
 
-Biome is the sole formatter and linter. Runtime code uses Pi's SDK only; Pi
-provides `@earendil-works/pi-coding-agent` as a peer dependency.
+Biome is the sole formatter and linter. Pi loads TypeScript from `extensions/`
+directly; do not bundle. Pi provides `@earendil-works/pi-coding-agent`,
+`@earendil-works/pi-tui`, and `typebox` as peer dependencies.
 
 ## Releases and commits
 
 Commit messages must follow the Conventional Commits format. The existing
 Husky `commit-msg` hook validates each local commit with Commitlint, for
-example `feat: add a pipeline summary` or `fix: validate malformed findings`.
+example `feat: mark the recommended sideroom_ask option`.
 
 Every user-visible package change needs a Changeset. Create one with:
 
@@ -108,21 +130,33 @@ Every user-visible package change needs a Changeset. Create one with:
 npm run changeset
 ```
 
-Review pending release work with `npm run changeset:status`. On the release
-branch, run `npm run version-packages`, review and commit the updated
-`package.json`, `package-lock.json`, and `CHANGELOG.md`, then publish
-deliberately with `npm run release`. The repository does not publish
-automatically from CI.
+Review pending release work with `npm run changeset:status`. When Changesets
+are merged to `main`, the `Release` workflow creates or updates a reviewable
+Changesets version PR. That PR contains the generated `package.json`,
+`package-lock.json`, and `CHANGELOG.md` updates. Merge the version PR only after
+review; its merge runs `npm ci` and `npm run check`, then uses
+npm 11.5.1 and npm Trusted Publishing (GitHub OIDC) to publish. Changesets then
+pushes the release Git tag and creates the GitHub Release automatically.
+
+Never run `npm publish`, create release tags, or create GitHub Releases locally.
+Publishing is allowed only through the merged Changesets version PR and the
+`Release` workflow. The npm package's Trusted Publisher must be configured for
+this GitHub repository, the workflow filename `release.yml` (not its path),
+and the `npm` environment; configure the matching GitHub `npm` environment
+before the first release.
 
 ## Layout
 
 ```text
-src/
-  pi-extension.ts        Pi extension entry point for /sideroom
-  pi-command.ts          slash-command parsing
-  app.ts                 Pi pipeline assembly
-  core/                  orchestration, roles, contracts, and content catalog
-  runtimes/pi.ts         direct Pi SDK adapter for isolated child sessions
-  assets/                role prompts and coding guidelines
-skills/                  package-provided Pi skills
+extensions/
+  ask/                   sideroom_ask (index.ts, execute.ts, model.ts, ui.ts)
+  todo/                  sideroom_todo (index.ts, execute.ts, session.ts,
+                         guards.ts, model.ts, ui.ts)
+  modified-files/        session-backed edited-file tracker and view
+  guidelines/            short write/edit reminder
+skills/sideroom-guidelines/  on-demand checklist and language deltas
+assets/artifacts/        GUIDELINES_TEMPLATE.md seed
 ```
+
+Add another tool as `extensions/<name>/index.ts`. Pi discovers
+`extensions/*/index.ts`; helpers in that folder are not loaded as extensions.

package/{src/assets → assets}/artifacts/GUIDELINES_TEMPLATE.md

@@ -8,6 +8,7 @@ Each row is expanded, with examples, in the matching section below.
 
 | Do                                                 | Don't                                                                                       |
 | -------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| Use braces around every `if` body                  | Write an unbraced, single-statement conditional body                                       |
 | Early return on bad input                          | Pyramid `if/else` nesting                                                                   |
 | Explicit error, fail now                           | Multiple fallbacks that hide the real failure                                               |
 | One responsibility per unit                        | Validate + transform + persist + notify in one place                                        |
@@ -55,13 +56,26 @@ function getDiscount(user) {
 
 // Good — guard clauses, happy path at the end, shallow indent
 function getDiscount(user) {
-  if (!user) return 0;
-  if (!user.isActive) return 0;
-  if (!user.hasSubscription) return 0;
+  if (!user) {
+    return 0;
+  }
+  if (!user.isActive) {
+    return 0;
+  }
+  if (!user.hasSubscription) {
+    return 0;
+  }
   return 0.2;
 }
 ```
 
+### Braced conditionals
+
+Every `if` and `else` body must use braces in languages that support them,
+including a one-line guard clause. Never rely on indentation alone to bind a
+statement to a conditional. In Python, which has no braces, use a complete
+indented suite and never a one-line conditional body.
+
 ### Fail fast
 
 Invalid input, impossible state, or a broken dependency should fail immediately with a clear error. Prefer that over chains of fallbacks, silent defaults, or "keep going somehow."
@@ -78,7 +92,9 @@ function getShippingCost(order) {
 // Good — fails immediately with a clear error
 function getShippingCost(order) {
   const zone = ZONES[order.zoneId];
-  if (!zone) throw new Error(`Unknown zoneId: ${order.zoneId}`);
+  if (!zone) {
+    throw new Error(`Unknown zoneId: ${order.zoneId}`);
+  }
   return zone.baseCost;
 }
 ```
@@ -90,7 +106,9 @@ A function, class, or module has one reason to change. If it does two jobs, spli
 ```js
 // Bad — validates, transforms, persists, and notifies all in one place
 async function saveUser(data) {
-  if (!data.email) throw new Error('email required');
+  if (!data.email) {
+    throw new Error('email required');
+  }
   const normalized = { ...data, email: data.email.trim().toLowerCase() };
   await db.users.insert(normalized);
   await mailer.send(normalized.email, 'welcome');
@@ -98,7 +116,9 @@ async function saveUser(data) {
 
 // Good — each unit has a single reason to change
 function validateUser(data) {
-  if (!data.email) throw new Error('email required');
+  if (!data.email) {
+    throw new Error('email required');
+  }
 }
 function normalizeUser(data) {
   return { ...data, email: data.email.trim().toLowerCase() };
@@ -284,14 +304,22 @@ Pick one convention and apply it consistently: e.g. `undefined` for "not yet set
 ```js
 // Bad — null is overloaded to mean three different things
 function getDiscount(user) {
-  if (!user) return null; // no user
-  if (!user.plan) return null; // no plan
-  if (user.plan.discount === 0) return null; // legitimately zero discount
+  if (!user) {
+    return null; // no user
+  }
+  if (!user.plan) {
+    return null; // no plan
+  }
+  if (user.plan.discount === 0) {
+    return null; // legitimately zero discount
+  }
 }
 
 // Good — each case is explicit, zero is a real value
 function getDiscount(user) {
-  if (!user || !user.plan) return 0;
+  if (!user || !user.plan) {
+    return 0;
+  }
   return user.plan.discount;
 }
 ```
@@ -439,7 +467,8 @@ class UpdateProfileRequest extends FormRequest {
 }
 class ProfileService {
     public function update(array $data) {
-        if (empty($data['email'])) { // redundant re-validation
+        // Redundant re-validation.
+        if (empty($data['email'])) {
             throw new \InvalidArgumentException('email required');
         }
         $this->user->update($data);

package/extensions/ask/execute.ts

@@ -0,0 +1,56 @@
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import {
+  type AskParams,
+  type AskQuestion,
+  type AskResult,
+  formatAnswerLines,
+  parseAskParams,
+  UI_UNAVAILABLE,
+} from './model.ts';
+import { runAskUi } from './ui.ts';
+
+interface AskToolResult {
+  readonly content: [{ readonly type: 'text'; readonly text: string }];
+  readonly details: AskResult;
+}
+
+export async function executeAsk(
+  params: AskParams,
+  ctx: Pick<ExtensionContext, 'mode' | 'ui'>,
+): Promise<AskToolResult> {
+  const parsed = parseAskParams(params);
+  if (!parsed.ok) {
+    return cancelledResult(parsed.message);
+  }
+  if (ctx.mode !== 'tui') {
+    return cancelledResult(UI_UNAVAILABLE, parsed.questions);
+  }
+
+  const result = await runAskUi(ctx.ui, parsed.questions);
+  if (result.cancelled) {
+    return {
+      content: [{ type: 'text', text: 'User cancelled the questionnaire' }],
+      details: result,
+    };
+  }
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: formatAnswerLines(parsed.questions, result.answers).join('\n'),
+      },
+    ],
+    details: result,
+  };
+}
+
+function cancelledResult(
+  message: string,
+  questions: readonly AskQuestion[] = [],
+): AskToolResult {
+  return {
+    content: [{ type: 'text', text: message }],
+    details: { questions, answers: [], cancelled: true },
+  };
+}

package/extensions/ask/index.ts

@@ -0,0 +1,78 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Text } from '@earendil-works/pi-tui';
+import { executeAsk } from './execute.ts';
+import { AskParamsSchema, type AskResult, TOOL_NAME } from './model.ts';
+
+export const ASK_DESCRIPTION =
+  'Ask the user one or more questions in the language they are speaking. Use for clarifying requirements, getting preferences, or confirming decisions. Each question must include a recommended option. For a single question, shows a simple option list. For multiple questions, shows a tab-based interface.';
+
+export const ASK_PROMPT_SNIPPET =
+  'Ask the user one or more questions with a recommended option, in their language.';
+
+export const ASK_PROMPT_GUIDELINES = [
+  'Use sideroom_ask to clarify requirements, preferences, or decisions with the user.',
+  'Each sideroom_ask question needs an id, a prompt, at least two options, and a recommendationIndex pointing at the recommended option.',
+  'Write every sideroom_ask prompt, tab label, and option label or description in the language the user is speaking. Keep ids, option values, and tool code in English.',
+  'sideroom_ask always adds Out of scope and a custom answer; do not include those options yourself.',
+  'One sideroom_ask call is one batch; call it again if another round of questions is needed.',
+  'sideroom_ask only works in the interactive TUI; it returns an error in print, JSON, or RPC modes.',
+];
+
+// Pi loads extensions/*/index.ts through export default.
+export default function registerAsk(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: TOOL_NAME,
+    label: 'Sideroom Ask',
+    description: ASK_DESCRIPTION,
+    promptSnippet: ASK_PROMPT_SNIPPET,
+    promptGuidelines: ASK_PROMPT_GUIDELINES,
+    parameters: AskParamsSchema,
+    executionMode: 'sequential',
+    execute: async (_toolCallId, params, _signal, _onUpdate, ctx) =>
+      executeAsk(params, ctx),
+    renderCall(args, theme) {
+      const questions = args.questions;
+      const count = questions.length;
+      const labels = questions
+        .map(
+          (question, index) =>
+            question.label || question.id || `Q${String(index + 1)}`,
+        )
+        .join(', ');
+      let text = theme.fg('toolTitle', theme.bold(`${TOOL_NAME} `));
+      text += theme.fg(
+        'muted',
+        `${String(count)} question${count !== 1 ? 's' : ''}`,
+      );
+      if (labels.length > 0) {
+        text += theme.fg('dim', ` (${labels})`);
+      }
+      return new Text(text, 0, 0);
+    },
+    renderResult(result, _options, theme) {
+      const details = result.details as AskResult | undefined;
+      if (details === undefined) {
+        const text = result.content[0];
+        return new Text(text?.type === 'text' ? text.text : '', 0, 0);
+      }
+      if (details.cancelled) {
+        return new Text(theme.fg('warning', 'Cancelled'), 0, 0);
+      }
+      const lines = details.answers.map((answer) => {
+        const mark = theme.fg('success', '✓ ');
+        const id = theme.fg('accent', answer.id);
+        if (answer.outOfScope) {
+          return `${mark}${id}: ${theme.fg('muted', '(out of scope)')}`;
+        }
+        if (answer.wasCustom) {
+          return `${mark}${id}: ${theme.fg('muted', '(wrote) ')}${answer.label}`;
+        }
+        if (answer.index !== undefined) {
+          return `${mark}${id}: ${String(answer.index)}. ${answer.label}`;
+        }
+        return `${mark}${id}: ${answer.label}`;
+      });
+      return new Text(lines.join('\n'), 0, 0);
+    },
+  });
+}