@rmrdeveloper/sideroom-pi 8.2.0 → 8.4.0

package/README.md

@@ -54,7 +54,9 @@ Sideroom answers each one with a small, opinionated surface:
 | Style drift | A pre-edit gate + the on-demand `sideroom-guidelines` skill |
 | Vague plans | `sideroom-grill` — an interview that settles the words before the work |
 | Unapplied guidelines | `sideroom_rules` — mechanical checks that block or flag the lines you add |
+| Unclear answers | `sideroom_persona` — one voice: direct, plain, and free of jargon it invented |
 | Premature completion | `sideroom_done` — steers back to the project's check command before finishing |
+| Work left unexplained | `explain` — offers a walkthrough and how to test it once the work settles |
 
 ## What it feels like
 
@@ -70,8 +72,10 @@ wall of tool calls, it:
 - **Works in the open.** A compact board sits above the editor:
   `pending → in_progress → completed`. Exactly one step is active at a
   time; the agent completes the current step and starts the next one in the
-  same move, so skipped steps become structurally hard. The board survives
-  reload, tree navigation, and compaction.
+  same move, so skipped steps become structurally hard. The widget shows at
+  most five rows, keeps the active step visible, and `F9` opens the full
+  read-only board. The board survives reload, tree navigation, and
+  compaction.
 - **Shows its traces.** Below the board, the last edited files appear as
   clickable `file://` links. `F8` opens the full session history; `R` clears
   it. Only successful Pi `write`/`edit` calls are tracked — no guesses from
@@ -114,6 +118,10 @@ chat. It never creates a repository task file or a `/todos` command.
 - `update` patches `{ id, status?, content? }` items and works everywhere,
   including headless modes.
 - Invariant: while anything is pending, exactly one item is `in_progress`.
+- Widget: at most five rows — open items before resolved ones, the
+  `in_progress` row always visible — plus a `…+N more · F9: view all` hint.
+  `F9` opens the full board as a read-only overlay, so the widget stays small
+  without hiding work from you; the agent still gets every item in its prompt.
 
 ### Edited files — proof, not promises
 
@@ -157,6 +165,18 @@ appended as notes to the tool result. A per-rule circuit breaker degrades a
 repeatedly firing block to a note so the agent never dead-locks. No files
 written, no config read: the catalog ships with the package.
 
+### Persona — one voice, not a costume
+
+`sideroom_persona` is the agent's voice, and there is exactly one of it. A
+short reminder rides the system prompt on every turn, so it survives
+compaction; the full guide lives in the on-demand `sideroom-persona` skill.
+The voice is direct and dry, free of filler, and plain enough to leave no
+doubt about what is being discussed — while calling things by the names the
+user already uses. Emojis and decorative symbols in the lines a `write`/`edit`
+adds block the mutation; flattering openers, hedging, automatic apologies, and
+AI meta-commentary are answered with a capped steer. No profiles to switch and
+no profile selection to store.
+
 ### Done — done means green
 
 `sideroom_done` detects the project's check command — `package.json` scripts
@@ -166,6 +186,16 @@ target — and watches for it to pass. If files changed without a green run, the
 agent is steered once per turn, up to a cap, to run it before finishing. When
 nothing is detectable, the gate does nothing.
 
+### Explain — the walkthrough offer
+
+When an implementation settles, `explain` steers the agent to offer a
+walkthrough through `sideroom_ask`: explain the changes and how to test them,
+only how to test them, or nothing. It fires on `agent_settled`, the point where
+no retry, compaction, or queued message is left, so the offer never lands on
+work that is about to be redone. Once per prompt, only after a real
+`write`/`edit`, and only in the TUI, because `sideroom_ask` cannot run anywhere
+else. No tool, no widget, no persisted state.
+
 ## Quick path
 
 1. Install globally from npm. Pi records this in your user settings, so do
@@ -213,6 +243,13 @@ Items have stable string ids, short content, and one of `pending`,
 start the next one in the same `update` call. Snapshots live in the active
 session branch and are rebuilt after navigation and compaction.
 
+- Widget: max five rows. Open items win the cap over resolved ones, the
+  `in_progress` row is always shown, and a `…+N more · F9: view all` line
+  appears when rows are hidden.
+- Extended view: `F9` toggles a read-only overlay. `↑`/`↓` and `PgUp`/`PgDn`
+  scroll; `Esc` or `F9` closes. It never mutates the board.
+- The cap is display-only: every item still reaches the system prompt.
+
 A forked session inherits the board visible at its fork point. Later board
 updates are reconstructed from each session's active branch, so the fork and
 the original session evolve independently.
@@ -247,6 +284,21 @@ the diff against the loaded guide and run the relevant project checks.
 - A rule that blocks three times in a run degrades to a warning until five
   clean checks or a new interactive prompt reset it.
 
+### Persona contract
+
+- One built-in voice. No profiles, no switching, and no persisted profile
+  state; runtime guard counters stay in memory. The footer status is derived
+  from the catalog.
+- Injection: a short reminder appended in `before_agent_start`, chained after
+  the other extensions and idempotent by heading, so it returns after
+  compaction.
+- Blocking: decorative symbols in the lines a `write`/`edit` adds. Three fires
+  degrade the prohibition to a steer; five clean mutations reset the counters.
+- Steering: one corrective message per violating assistant message, at most
+  three per run.
+- `sideroom_persona` takes no arguments and returns every rule and every
+  prohibition with its enforcement mode.
+
 ### Done contract
 
 - Detected command: `package.json` scripts in priority order with the
@@ -256,6 +308,17 @@ the diff against the loaded guide and run the relevant project checks.
   successful `write`/`edit` clears green again.
 - Steering: once per turn, at most twice per run, then it stops.
 
+### Explain contract
+
+- Trigger: `agent_settled` with at least one successful `write`/`edit` since the
+  last user prompt, in TUI mode.
+- The steer names the intent; the agent writes the question in the user's
+  language with three options and one recommendation. `sideroom_ask` still adds
+  *Out of scope* and the custom answer.
+- At most one offer per user prompt. The flag is set before the steer, so the
+  turn the offer triggers cannot re-trigger it.
+- No green-check requirement: red checks still produce the offer.
+
 ### Grill contract
 
 Load the skill at the start of a change with a fuzzy plan.
@@ -280,6 +343,17 @@ Maintainer reference lives in [`docs/`](docs/README.md): the
 [architecture](docs/architecture.md) and one page per
 [extension](docs/extensions/ask.md).
 
+## Contributing
+
+Contributions are welcome: bug reports, feature requests, language guides, and
+pull requests. Start with [`CONTRIBUTING.md`](CONTRIBUTING.md) for setup, the
+commands, the design rules, and the branch and release flow — pull requests
+target `develop`, and `main` only carries releases.
+
+- [Report a bug](https://github.com/RMRdeveloper/sideroom-pi/issues/new?template=bug_report.yml) or [request a feature](https://github.com/RMRdeveloper/sideroom-pi/issues/new?template=feature_request.yml).
+- Report vulnerabilities privately through [`SECURITY.md`](SECURITY.md).
+- Participation is covered by the [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md).
+
 ## License
 
 MIT.

package/extensions/explain/guard.ts

@@ -0,0 +1,51 @@
+import {
+  type ExtensionAPI,
+  isEditToolResult,
+  isWriteToolResult,
+} from '@earendil-works/pi-coding-agent';
+import {
+  EXPLAIN_OFFER,
+  EXPLAIN_OFFER_TYPE,
+  type ExplainState,
+  resetExplainRun,
+  shouldOfferExplanation,
+} from './model.ts';
+
+export function registerExplainGuard(
+  pi: ExtensionAPI,
+  state: ExplainState,
+): void {
+  pi.on('input', (event) => {
+    if (event.source !== 'interactive' && event.source !== 'rpc') {
+      return;
+    }
+    resetExplainRun(state);
+  });
+
+  pi.on('tool_result', (event) => {
+    if (event.isError) {
+      return;
+    }
+    if (!isEditToolResult(event) && !isWriteToolResult(event)) {
+      return;
+    }
+    state.mutatedSincePrompt = true;
+  });
+
+  // agent_settled is the only point with no retry, compaction, or queued
+  // continuation left, so the walkthrough is never offered over reworked work.
+  pi.on('agent_settled', (_event, ctx) => {
+    if (!shouldOfferExplanation(state, ctx.mode)) {
+      return;
+    }
+    state.offeredThisRun = true;
+    pi.sendMessage(
+      {
+        customType: EXPLAIN_OFFER_TYPE,
+        content: EXPLAIN_OFFER,
+        display: false,
+      },
+      { triggerTurn: true, deliverAs: 'steer' },
+    );
+  });
+}

package/extensions/explain/index.ts

@@ -0,0 +1,11 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { registerExplainGuard } from './guard.ts';
+import { createExplainState, resetExplainRun } from './model.ts';
+
+// Pi loads extensions/*/index.ts through export default.
+export default function registerExplain(pi: ExtensionAPI): void {
+  const state = createExplainState();
+  registerExplainGuard(pi, state);
+
+  pi.on('session_start', () => resetExplainRun(state));
+}

package/extensions/explain/model.ts

@@ -0,0 +1,28 @@
+export const EXPLAIN_OFFER_TYPE = 'sideroom-explain-offer';
+
+const TUI_MODE = 'tui';
+
+export const EXPLAIN_OFFER =
+  "Use sideroom_ask for one question in the user's language with three options: explain changes and test steps, test steps only, or no explanation. Recommend one.";
+
+export interface ExplainState {
+  mutatedSincePrompt: boolean;
+  offeredThisRun: boolean;
+}
+
+export function createExplainState(): ExplainState {
+  return { mutatedSincePrompt: false, offeredThisRun: false };
+}
+
+export function resetExplainRun(state: ExplainState): void {
+  state.mutatedSincePrompt = false;
+  state.offeredThisRun = false;
+}
+
+// sideroom_ask rejects every mode but the TUI, so the offer is gated the same way.
+export function shouldOfferExplanation(
+  state: ExplainState,
+  mode: string,
+): boolean {
+  return mode === TUI_MODE && state.mutatedSincePrompt && !state.offeredThisRun;
+}

package/extensions/persona/catalog.ts

@@ -0,0 +1,110 @@
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+
+export const PERSONA_TOOL_NAME = 'sideroom_persona';
+export const PERSONA_STATUS_KEY = 'sideroom-persona';
+export const PERSONA_STEER_TYPE = 'sideroom-persona-steer';
+export const PERSONA_SKILL_PATH = join(
+  PACKAGE_ROOT,
+  'skills/sideroom-persona/SKILL.md',
+);
+
+export const TEXT_SCOPE = {
+  prose: 'prose',
+  artifact: 'artifact',
+} as const;
+
+export type TextScope = (typeof TEXT_SCOPE)[keyof typeof TEXT_SCOPE];
+
+export type VoiceRuleId =
+  | 'direct'
+  | 'no-filler'
+  | 'plain-language'
+  | 'no-invented-terms'
+  | 'short-prose'
+  | 'user-language';
+
+export interface VoiceRule {
+  readonly id: VoiceRuleId;
+  readonly instruction: string;
+}
+
+export const VOICE_RULES: readonly VoiceRule[] = [
+  {
+    id: 'direct',
+    instruction:
+      'Be direct and dry. Use short sentences. No preamble or closing summary.',
+  },
+  {
+    id: 'no-filler',
+    instruction: 'No filler.',
+  },
+  {
+    id: 'plain-language',
+    instruction:
+      'Explain plainly and leave no doubt. Name the subject and goal before details, define unfamiliar terms in one line, and be explicit without repetition.',
+  },
+  {
+    id: 'no-invented-terms',
+    instruction:
+      'Name things as they are. Add no intermediate terms, abbreviations, or codenames unless the user asks.',
+  },
+  {
+    id: 'short-prose',
+    instruction:
+      'Default to short prose. Use lists or tables only for comparisons or more than three items.',
+  },
+  {
+    id: 'user-language',
+    instruction: "Answer in the user's language and variant.",
+  },
+];
+
+export type ProhibitionId =
+  | 'decorative-symbols'
+  | 'flattery-and-filler'
+  | 'hedging-and-apology'
+  | 'ai-meta-commentary';
+
+export interface Prohibition {
+  readonly id: ProhibitionId;
+  readonly rule: string;
+  readonly scopes: readonly TextScope[];
+}
+
+export const PROHIBITIONS: readonly Prohibition[] = [
+  {
+    id: 'decorative-symbols',
+    rule: 'No emojis or decorative symbols in prose or artifacts.',
+    scopes: [TEXT_SCOPE.prose, TEXT_SCOPE.artifact],
+  },
+  {
+    id: 'flattery-and-filler',
+    rule: 'No flattering openers such as "Great question!", restating what was just said, or announcing the answer.',
+    scopes: [TEXT_SCOPE.prose],
+  },
+  {
+    id: 'hedging-and-apology',
+    rule: 'No hedging such as "maybe we could consider" or automatic apologies.',
+    scopes: [TEXT_SCOPE.prose],
+  },
+  {
+    id: 'ai-meta-commentary',
+    rule: 'No AI meta-commentary such as "as a language model" or "I do not have access to".',
+    scopes: [TEXT_SCOPE.prose],
+  },
+];
+
+const PROHIBITION_BY_ID: ReadonlyMap<ProhibitionId, Prohibition> = new Map(
+  PROHIBITIONS.map((prohibition) => [prohibition.id, prohibition]),
+);
+
+export function prohibitionById(id: ProhibitionId): Prohibition {
+  const prohibition = PROHIBITION_BY_ID.get(id);
+  if (prohibition === undefined) {
+    throw new Error(`Unknown prohibition id: ${id}`);
+  }
+  return prohibition;
+}

package/extensions/persona/checks.ts

@@ -0,0 +1,116 @@
+import {
+  type Prohibition,
+  type ProhibitionId,
+  prohibitionById,
+  TEXT_SCOPE,
+  type TextScope,
+} from './catalog.ts';
+
+interface ProhibitionDetector {
+  readonly prohibitionId: ProhibitionId;
+  readonly pattern: RegExp;
+}
+
+// Each detector is a heuristic for one prohibition. The rule text in the
+// catalog stays authoritative; a detector never fires on its own judgement.
+const DETECTORS: readonly ProhibitionDetector[] = [
+  {
+    prohibitionId: 'decorative-symbols',
+    pattern: /\p{Extended_Pictographic}|\uFE0F|[\u2713\u2714\u2717\u2718]/u,
+  },
+  {
+    prohibitionId: 'flattery-and-filler',
+    pattern:
+      /^[ \t>*+-]*(?:[¡!]?\s*(?:great|excellent|awesome|fantastic|amazing|perfect|good)\s+(?:question|idea|point|catch|observation|call)\b[!.]?|certainly\b|of course\b|absolutely\b|sure thing\b|[¡!]?\s*(?:excelente|gran|buena|perfecta)\s+(?:pregunta|idea|observaci[oó]n|punto)\b[!.]?|por supuesto\b|claro que s[ií]\b)/imu,
+  },
+  {
+    prohibitionId: 'hedging-and-apology',
+    pattern:
+      /\b(?:sorry (?:for|about)|i apologize|my apologies|perd[oó]n por|disculp[áa]|lamento (?:el|la|los|las|haber|no haber))\b|\b(?:maybe we could|might be worth|i think we could|we could consider|perhaps we could|quiz[áa]s podr[íi]amos|tal vez podr[íi]amos|podr[íi]amos considerar|creo que podr[íi]amos|you might want to consider)\b/iu,
+  },
+  {
+    prohibitionId: 'ai-meta-commentary',
+    pattern:
+      /\b(?:as an ai\b|as a language model\b|i['’]?m an ai\b|i am an ai\b|como (?:un )?modelo de lenguaje\b|soy una? (?:ia|inteligencia artificial|asistente de ia)\b|no tengo acceso a (?:internet|tiempo real)\b|i (?:do not|don['’]?t) have access to (?:the )?internet\b)/iu,
+  },
+];
+
+export interface ProhibitionViolation {
+  readonly prohibition: Prohibition;
+  readonly excerpt: string;
+}
+
+export function findViolations(
+  text: string,
+  scope: TextScope,
+): readonly ProhibitionViolation[] {
+  if (text.length === 0) {
+    return [];
+  }
+
+  const violations: ProhibitionViolation[] = [];
+  for (const detector of DETECTORS) {
+    const prohibition = prohibitionById(detector.prohibitionId);
+    if (!prohibition.scopes.includes(scope)) {
+      continue;
+    }
+    const match = detector.pattern.exec(text);
+    if (match === null) {
+      continue;
+    }
+    violations.push({ prohibition, excerpt: excerptOf(match[0]) });
+  }
+  return violations;
+}
+
+export function artifactViolations(
+  addedLines: readonly string[],
+): readonly ProhibitionViolation[] {
+  return findViolations(addedLines.join('\n'), TEXT_SCOPE.artifact);
+}
+
+export function addedLinesMissingFrom(
+  previous: string | undefined,
+  next: string,
+): readonly string[] {
+  const remaining = countLines(previous);
+  const added: string[] = [];
+
+  for (const line of next.split('\n')) {
+    const key = line.trim();
+    if (key.length === 0) {
+      continue;
+    }
+    const available = remaining.get(key) ?? 0;
+    if (available > 0) {
+      remaining.set(key, available - 1);
+      continue;
+    }
+    added.push(line);
+  }
+
+  return added;
+}
+
+function countLines(content: string | undefined): Map<string, number> {
+  const counts = new Map<string, number>();
+  if (content === undefined) {
+    return counts;
+  }
+
+  for (const line of content.split('\n')) {
+    const key = line.trim();
+    if (key.length === 0) {
+      continue;
+    }
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  return counts;
+}
+
+// Detector matches are short by construction; drop the bullet or indentation
+// they carry so the reason stays on one line.
+function excerptOf(match: string): string {
+  const singleLine = match.replaceAll(/\s+/gu, ' ').trim();
+  return singleLine.replace(/^[>*+-]+\s*/u, '');
+}

package/extensions/persona/execute.ts

@@ -0,0 +1,17 @@
+import {
+  formatPersonaDetail,
+  type PersonaToolDetails,
+  personaToolDetails,
+} from './model.ts';
+
+export interface PersonaToolResult {
+  readonly content: { readonly type: 'text'; readonly text: string }[];
+  readonly details: PersonaToolDetails;
+}
+
+export function executePersona(): PersonaToolResult {
+  return {
+    content: [{ type: 'text', text: formatPersonaDetail() }],
+    details: personaToolDetails(),
+  };
+}

package/extensions/persona/guard.ts

@@ -0,0 +1,170 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import {
+  type ExtensionAPI,
+  isToolCallEventType,
+  type ToolCallEvent,
+} from '@earendil-works/pi-coding-agent';
+import {
+  PERSONA_STEER_TYPE,
+  type ProhibitionId,
+  TEXT_SCOPE,
+} from './catalog.ts';
+import {
+  addedLinesMissingFrom,
+  artifactViolations,
+  findViolations,
+} from './checks.ts';
+import {
+  assistantMessageText,
+  formatArtifactSteer,
+  formatBlockReason,
+  formatSteer,
+} from './model.ts';
+
+// A rule that keeps firing degrades to a steer instead of trapping the agent.
+const BLOCK_DEGRADE_AFTER = 3;
+const CLEAN_RESET_AFTER = 5;
+
+// One agent run can be corrected at most this many times.
+const STEER_LIMIT_PER_RUN = 3;
+
+interface ExtractedMutation {
+  readonly path: string;
+  readonly addedLines: readonly string[];
+}
+
+export interface PersonaGuardState {
+  readonly fires: Map<ProhibitionId, number>;
+  cleanMutations: number;
+  steersThisRun: number;
+}
+
+export function createPersonaGuardState(): PersonaGuardState {
+  return { fires: new Map(), cleanMutations: 0, steersThisRun: 0 };
+}
+
+export function resetPersonaRun(state: PersonaGuardState): void {
+  state.steersThisRun = 0;
+}
+
+export function registerPersonaGuard(
+  pi: ExtensionAPI,
+  state: PersonaGuardState,
+): void {
+  pi.on('tool_call', (event, ctx) => {
+    const mutation = extractMutation(event, ctx.cwd);
+    if (mutation === undefined) {
+      return undefined;
+    }
+    return applyArtifactOutcome(pi, state, mutation);
+  });
+
+  pi.on('message_end', (event) => {
+    if (event.message.role !== 'assistant') {
+      return undefined;
+    }
+    const violations = findViolations(
+      assistantMessageText(event.message.content),
+      TEXT_SCOPE.prose,
+    );
+    if (violations.length === 0) {
+      return undefined;
+    }
+
+    sendPersonaSteer(pi, state, formatSteer(violations));
+    return undefined;
+  });
+}
+
+function applyArtifactOutcome(
+  pi: ExtensionAPI,
+  state: PersonaGuardState,
+  mutation: ExtractedMutation,
+): { block: true; reason: string } | undefined {
+  const violations = artifactViolations(mutation.addedLines);
+  if (violations.length === 0) {
+    registerCleanMutation(state);
+    return undefined;
+  }
+
+  const blocking = violations.filter(
+    (violation) => !isDegraded(state, violation.prohibition.id),
+  );
+  if (blocking.length > 0) {
+    for (const violation of blocking) {
+      incrementFires(state, violation.prohibition.id);
+    }
+    return { block: true, reason: formatBlockReason(mutation.path, blocking) };
+  }
+
+  sendPersonaSteer(pi, state, formatArtifactSteer(mutation.path, violations));
+  return undefined;
+}
+
+function extractMutation(
+  event: ToolCallEvent,
+  cwd: string,
+): ExtractedMutation | undefined {
+  if (isToolCallEventType('write', event)) {
+    const previous = readFileIfExists(resolve(cwd, event.input.path));
+    return {
+      path: event.input.path,
+      addedLines: addedLinesMissingFrom(previous, event.input.content),
+    };
+  }
+  if (isToolCallEventType('edit', event)) {
+    const addedLines = event.input.edits.flatMap((edit) =>
+      addedLinesMissingFrom(edit.oldText, edit.newText),
+    );
+    return { path: event.input.path, addedLines };
+  }
+  return undefined;
+}
+
+function readFileIfExists(path: string): string | undefined {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch (error) {
+    if (isMissingFile(error)) {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+function isMissingFile(error: unknown): boolean {
+  return error instanceof Error && 'code' in error && error.code === 'ENOENT';
+}
+
+function isDegraded(state: PersonaGuardState, id: ProhibitionId): boolean {
+  return (state.fires.get(id) ?? 0) >= BLOCK_DEGRADE_AFTER;
+}
+
+function incrementFires(state: PersonaGuardState, id: ProhibitionId): void {
+  state.fires.set(id, (state.fires.get(id) ?? 0) + 1);
+}
+
+function sendPersonaSteer(
+  pi: Pick<ExtensionAPI, 'sendMessage'>,
+  state: PersonaGuardState,
+  content: string,
+): void {
+  if (state.steersThisRun >= STEER_LIMIT_PER_RUN) {
+    return;
+  }
+  state.steersThisRun += 1;
+  pi.sendMessage(
+    { customType: PERSONA_STEER_TYPE, content, display: false },
+    { deliverAs: 'steer' },
+  );
+}
+
+function registerCleanMutation(state: PersonaGuardState): void {
+  state.cleanMutations += 1;
+  if (state.cleanMutations < CLEAN_RESET_AFTER) {
+    return;
+  }
+  state.cleanMutations = 0;
+  state.fires.clear();
+}

package/extensions/persona/index.ts

@@ -0,0 +1,77 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from '@earendil-works/pi-coding-agent';
+import { Text } from '@earendil-works/pi-tui';
+import { Type } from 'typebox';
+import { PERSONA_STATUS_KEY, PERSONA_TOOL_NAME } from './catalog.ts';
+import { executePersona, type PersonaToolResult } from './execute.ts';
+import {
+  createPersonaGuardState,
+  registerPersonaGuard,
+  resetPersonaRun,
+} from './guard.ts';
+import { PERSONA_STATUS_LABEL } from './model.ts';
+import { appendPersonaReminder } from './prompt.ts';
+
+export const PERSONA_DESCRIPTION =
+  "Read Sideroom's voice rules and hard prohibitions for user-facing answers.";
+
+export const PERSONA_PROMPT_SNIPPET = 'Read the active Sideroom persona.';
+
+// Pi loads extensions/*/index.ts through export default.
+export default function registerPersona(pi: ExtensionAPI): void {
+  const state = createPersonaGuardState();
+  registerPersonaGuard(pi, state);
+
+  pi.on('session_start', (_event, ctx) => publishStatus(ctx));
+
+  pi.on('before_agent_start', (event, ctx) => {
+    resetPersonaRun(state);
+    publishStatus(ctx);
+    const systemPrompt = appendPersonaReminder(event.systemPrompt);
+    if (systemPrompt === event.systemPrompt) {
+      return;
+    }
+    return { systemPrompt };
+  });
+
+  pi.registerTool({
+    name: PERSONA_TOOL_NAME,
+    label: 'Sideroom Persona',
+    description: PERSONA_DESCRIPTION,
+    promptSnippet: PERSONA_PROMPT_SNIPPET,
+    parameters: Type.Object({}),
+    executionMode: 'sequential',
+    execute: async () => executePersona(),
+    renderCall(_args, theme) {
+      return new Text(
+        theme.fg('toolTitle', theme.bold(PERSONA_TOOL_NAME)),
+        0,
+        0,
+      );
+    },
+    renderResult(result, _options, theme) {
+      const details = result.details as
+        | PersonaToolResult['details']
+        | undefined;
+      const voices = details?.voiceRules.length ?? 0;
+      const prohibitions = details?.prohibitions.length ?? 0;
+      return new Text(
+        theme.fg(
+          'success',
+          `${String(voices)} voice rules · ${String(prohibitions)} prohibitions`,
+        ),
+        0,
+        0,
+      );
+    },
+  });
+}
+
+function publishStatus(ctx: ExtensionContext): void {
+  if (!ctx.hasUI) {
+    return;
+  }
+  ctx.ui.setStatus(PERSONA_STATUS_KEY, PERSONA_STATUS_LABEL);
+}

package/extensions/persona/model.ts

@@ -0,0 +1,105 @@
+import {
+  PERSONA_SKILL_PATH,
+  PERSONA_TOOL_NAME,
+  PROHIBITIONS,
+  type Prohibition,
+  TEXT_SCOPE,
+  VOICE_RULES,
+} from './catalog.ts';
+import type { ProhibitionViolation } from './checks.ts';
+
+// Pi narrows these blocks before handing the message over; the shape is
+// structural so no runtime decoding is needed here.
+export interface TextBlock {
+  readonly type: string;
+  readonly text?: string;
+}
+
+export interface PersonaToolDetails {
+  readonly voiceRules: readonly string[];
+  readonly prohibitions: readonly string[];
+}
+
+export const PERSONA_STATUS_LABEL = `persona: direct, ${String(PROHIBITIONS.length)} prohibitions`;
+
+export function personaToolDetails(): PersonaToolDetails {
+  return {
+    voiceRules: VOICE_RULES.map((rule) => rule.id),
+    prohibitions: PROHIBITIONS.map((prohibition) => prohibition.id),
+  };
+}
+
+export function formatPersonaDetail(): string {
+  return [
+    'Sideroom persona: one always-on voice; no profiles or switching.',
+    '',
+    'Voice rules',
+    ...VOICE_RULES.map((rule) => `- ${rule.instruction}`),
+    '',
+    'Hard prohibitions',
+    ...PROHIBITIONS.map(
+      (prohibition) => `- ${prohibition.rule} (${enforcementOf(prohibition)})`,
+    ),
+    '',
+    `Complete guide: ${PERSONA_SKILL_PATH}`,
+  ].join('\n');
+}
+
+export function formatBlockReason(
+  path: string,
+  violations: readonly ProhibitionViolation[],
+): string {
+  return [
+    `Blocked ${path}: the Sideroom persona forbids this content.`,
+    ...violations.map(
+      (violation) =>
+        `- ${violation.prohibition.rule} Found: "${violation.excerpt}"`,
+    ),
+    'Remove the flagged content and retry the mutation.',
+  ].join('\n');
+}
+
+export function formatArtifactSteer(
+  path: string,
+  violations: readonly ProhibitionViolation[],
+): string {
+  return [
+    `Sideroom persona stopped blocking ${path} after repeated attempts, but this content is still forbidden.`,
+    ...violations.map(
+      (violation) =>
+        `- ${violation.prohibition.rule} Found: "${violation.excerpt}"`,
+    ),
+    'Remove it in the next edit.',
+  ].join('\n');
+}
+
+export function formatSteer(
+  violations: readonly ProhibitionViolation[],
+): string {
+  return [
+    `${PERSONA_TOOL_NAME}: part of your last message is forbidden.`,
+    ...violations.map(
+      (violation) =>
+        `- ${violation.prohibition.rule} Found: "${violation.excerpt}"`,
+    ),
+    'Rewrite it plainly: name the subject and goal before details, without ambiguity or repetition.',
+  ].join('\n');
+}
+
+export function assistantMessageText(content: readonly TextBlock[]): string {
+  const parts: string[] = [];
+  for (const block of content) {
+    if (block.type !== 'text') {
+      continue;
+    }
+    parts.push(block.text ?? '');
+  }
+  return parts.join('\n');
+}
+
+function enforcementOf(prohibition: Prohibition): string {
+  if (prohibition.scopes.includes(TEXT_SCOPE.artifact)) {
+    return 'blocked on write and edit';
+  }
+  return 'corrected with a steer';
+}

package/extensions/persona/prompt.ts

@@ -0,0 +1,32 @@
+import {
+  PERSONA_SKILL_PATH,
+  PERSONA_TOOL_NAME,
+  PROHIBITIONS,
+  VOICE_RULES,
+} from './catalog.ts';
+
+export const PERSONA_REMINDER_HEADING =
+  'Sideroom persona (always-on reminder):';
+
+const VOICE_SUMMARY = VOICE_RULES.map((rule) => rule.instruction).join(' ');
+const PROHIBITION_SUMMARY = PROHIBITIONS.map(
+  (prohibition) => prohibition.rule,
+).join(' ');
+const ENFORCEMENT_SUMMARY =
+  'A write/edit adding a decorative symbol is blocked; other violations trigger a steer.';
+
+export const PERSONA_REMINDER = `${PERSONA_REMINDER_HEADING}
+Voice: ${VOICE_SUMMARY}
+Never: ${PROHIBITION_SUMMARY}
+${ENFORCEMENT_SUMMARY}
+Full guide: call ${PERSONA_TOOL_NAME} or read ${PERSONA_SKILL_PATH}.`;
+
+export function appendPersonaReminder(systemPrompt: string): string {
+  if (systemPrompt.includes(PERSONA_REMINDER_HEADING)) {
+    return systemPrompt;
+  }
+  if (systemPrompt.length === 0) {
+    return PERSONA_REMINDER;
+  }
+  return `${systemPrompt}\n\n${PERSONA_REMINDER}`;
+}

package/extensions/todo/index.ts

@@ -18,6 +18,7 @@ import {
   TODO_WIDGET_REFRESH_EVENT,
   type TodoStore,
 } from './session.ts';
+import { createTodoBoardOverlayController } from './ui.ts';
 
 export const TODO_DESCRIPTION =
   'Maintain a live, user-visible work board. propose replaces the full board; update patches existing items by id.';
@@ -32,9 +33,12 @@ export const TODO_PROMPT_GUIDELINES = [
   'propose is interactive-TUI-only; update also works in print, JSON, and RPC modes.',
 ];
 
+const BOARD_SHORTCUT = 'f9';
+
 // Pi loads extensions/*/index.ts through export default.
 export default function registerTodo(pi: ExtensionAPI): void {
   const store = createTodoStore();
+  const overlay = createTodoBoardOverlayController(() => store.items);
   const restore: BoardLifecycle = (ctx) => {
     restoreBoard(store, ctx);
   };
@@ -50,6 +54,10 @@ export default function registerTodo(pi: ExtensionAPI): void {
   registerGuardEvents(pi, store, restore);
   registerBoardContext(pi, store, restoreAndRefresh);
   registerTodoTool(pi, store, notifyWidgetRefresh);
+  pi.registerShortcut(BOARD_SHORTCUT, {
+    description: 'Toggle the work board',
+    handler: (ctx) => overlay.toggle(ctx),
+  });
 }
 
 function registerTodoTool(

package/extensions/todo/ui.ts

@@ -1,5 +1,48 @@
-import type { Theme } from '@earendil-works/pi-coding-agent';
-import { formatBoardBlock, TODO_STATUS, type TodoItem } from './model.ts';
+import type { ExtensionContext, Theme } from '@earendil-works/pi-coding-agent';
+import {
+  type Component,
+  Key,
+  matchesKey,
+  type TUI,
+  truncateToWidth,
+} from '@earendil-works/pi-tui';
+import {
+  formatBoardBlock,
+  TODO_STATUS,
+  type TodoItem,
+  type TodoStatus,
+} from './model.ts';
+
+const COMPACT_ROW_LIMIT = 5;
+const EXTENDED_ROW_LIMIT = 12;
+
+const SELECTION_RANK = {
+  inProgress: 0,
+  pending: 1,
+  resolved: 2,
+} as const;
+
+export interface VisibleBoardRows {
+  readonly indexes: readonly number[];
+  readonly hiddenCount: number;
+}
+
+export function selectVisibleBoardRows(
+  items: readonly TodoItem[],
+  limit: number,
+): VisibleBoardRows {
+  if (items.length <= limit) {
+    return { indexes: items.map((_item, index) => index), hiddenCount: 0 };
+  }
+
+  const indexes = items
+    .map((item, index) => ({ index, rank: selectionRank(item) }))
+    .sort((left, right) => left.rank - right.rank || left.index - right.index)
+    .slice(0, limit)
+    .map((row) => row.index)
+    .sort((left, right) => left - right);
+  return { indexes, hiddenCount: items.length - indexes.length };
+}
 
 export function renderTodoWidget(
   items: readonly TodoItem[],
@@ -9,33 +52,199 @@ export function renderTodoWidget(
     return undefined;
   }
 
+  const rows = boardRowLines(items);
+  const visible = selectVisibleBoardRows(items, COMPACT_ROW_LIMIT);
+  const renderedRows = visible.indexes.flatMap((index) => {
+    const item = items[index];
+    const row = rows[index];
+    if (item === undefined || row === undefined) {
+      return [];
+    }
+    return [colorizeBoardRow(row, item.status, theme)];
+  });
+  const lines = [
+    theme.fg('accent', theme.bold(boardHeader(items))),
+    ...renderedRows,
+  ];
+  if (visible.hiddenCount > 0) {
+    lines.push(theme.fg('dim', hiddenRowsHint(visible.hiddenCount)));
+  }
+  return lines;
+}
+
+export interface TodoBoardOverlayController {
+  toggle(ctx: ExtensionContext): void;
+}
+
+export function createTodoBoardOverlayController(
+  items: () => readonly TodoItem[],
+): TodoBoardOverlayController {
+  let close: (() => void) | undefined;
+  let opening = false;
+
+  return {
+    toggle(ctx) {
+      if (close !== undefined) {
+        close();
+        return;
+      }
+      if (opening || ctx.mode !== 'tui') {
+        return;
+      }
+
+      opening = true;
+      void ctx.ui
+        .custom<void>(
+          (tui, theme, _keybindings, done) => {
+            close = done;
+            return new TodoBoardOverlay(tui, items, theme, done);
+          },
+          {
+            overlay: true,
+            overlayOptions: {
+              anchor: 'center',
+              width: '70%',
+              minWidth: 40,
+              maxHeight: '80%',
+              visible: (terminalWidth) => terminalWidth >= 60,
+            },
+          },
+        )
+        .finally(() => {
+          close = undefined;
+          opening = false;
+        });
+    },
+  };
+}
+
+export class TodoBoardOverlay implements Component {
+  private offset = 0;
+  private readonly tui: TUI;
+  private readonly items: () => readonly TodoItem[];
+  private readonly theme: Theme;
+  private readonly close: () => void;
+
+  constructor(
+    tui: TUI,
+    items: () => readonly TodoItem[],
+    theme: Theme,
+    close: () => void,
+  ) {
+    this.tui = tui;
+    this.items = items;
+    this.theme = theme;
+    this.close = close;
+  }
+
+  handleInput(data: string): void {
+    const maxOffset = Math.max(0, this.items().length - EXTENDED_ROW_LIMIT);
+    if (matchesKey(data, Key.escape) || matchesKey(data, Key.f9)) {
+      this.close();
+      return;
+    }
+    if (matchesKey(data, Key.up)) {
+      this.offset = Math.max(0, this.offset - 1);
+      this.tui.requestRender();
+      return;
+    }
+    if (matchesKey(data, Key.down)) {
+      this.offset = Math.min(maxOffset, this.offset + 1);
+      this.tui.requestRender();
+      return;
+    }
+    if (matchesKey(data, Key.pageUp)) {
+      this.offset = Math.max(0, this.offset - EXTENDED_ROW_LIMIT);
+      this.tui.requestRender();
+      return;
+    }
+    if (matchesKey(data, Key.pageDown)) {
+      this.offset = Math.min(maxOffset, this.offset + EXTENDED_ROW_LIMIT);
+      this.tui.requestRender();
+    }
+  }
+
+  render(width: number): string[] {
+    const innerWidth = Math.max(1, width - 2);
+    const items = this.items();
+    const rows = boardRowLines(items);
+    const visibleRows = items
+      .map((item, index) => ({ item, row: rows[index] }))
+      .slice(this.offset, this.offset + EXTENDED_ROW_LIMIT);
+    const border = (text: string) => this.theme.fg('border', text);
+    const line = (text: string) => truncateToWidth(text, innerWidth, '…', true);
+    const title = line(` Work board (${String(items.length)}) `);
+    const lines = [
+      border(`╭${'─'.repeat(innerWidth)}╮`),
+      `${border('│')}${line(this.theme.fg('accent', this.theme.bold(title)))}${border('│')}`,
+      `${border('├')}${border('─'.repeat(innerWidth))}${border('┤')}`,
+    ];
+
+    for (const entry of visibleRows) {
+      const row =
+        entry.row === undefined
+          ? ''
+          : colorizeBoardRow(entry.row, entry.item.status, this.theme);
+      lines.push(`${border('│')}${line(row)}${border('│')}`);
+    }
+    if (items.length === 0) {
+      lines.push(
+        `${border('│')}${line(this.theme.fg('muted', ' No items on the board.'))}${border('│')}`,
+      );
+    }
+
+    const scrollHint = items.length > EXTENDED_ROW_LIMIT ? ' ↑↓ scroll ·' : '';
+    lines.push(`${border('├')}${border('─'.repeat(innerWidth))}${border('┤')}`);
+    lines.push(
+      `${border('│')}${line(this.theme.fg('dim', `${scrollHint} F9 or Esc close`))}${border('│')}`,
+    );
+    lines.push(border(`╰${'─'.repeat(innerWidth)}╯`));
+    return lines;
+  }
+
+  invalidate(): void {}
+}
+
+function selectionRank(item: TodoItem): number {
+  if (item.status === TODO_STATUS.inProgress) {
+    return SELECTION_RANK.inProgress;
+  }
+  if (item.status === TODO_STATUS.pending) {
+    return SELECTION_RANK.pending;
+  }
+  return SELECTION_RANK.resolved;
+}
+
+function boardHeader(items: readonly TodoItem[]): string {
   const active = items.filter(
     (item) => item.status === TODO_STATUS.inProgress,
   ).length;
   const queued = items.filter(
     (item) => item.status === TODO_STATUS.pending,
   ).length;
-  const blockLines = formatBoardBlock(items).split('\n');
-  const rows = blockLines.slice(1, 1 + items.length);
-  const header = theme.fg(
-    'accent',
-    theme.bold(
-      `Sideroom board (${String(active)} active, ${String(queued)} queued)`,
-    ),
-  );
-  const renderedRows = rows.map((row, index) => {
-    const item = items[index];
-    if (item === undefined) {
-      return row;
-    }
-    if (item.status === TODO_STATUS.inProgress) {
-      return theme.fg('success', row);
-    }
-    if (item.status === TODO_STATUS.pending) {
-      return theme.fg('text', row);
-    }
-    return theme.fg('muted', row);
-  });
+  return `Sideroom board (${String(active)} active, ${String(queued)} queued)`;
+}
+
+function boardRowLines(items: readonly TodoItem[]): string[] {
+  return formatBoardBlock(items)
+    .split('\n')
+    .slice(1, 1 + items.length);
+}
+
+function colorizeBoardRow(
+  row: string,
+  status: TodoStatus,
+  theme: Theme,
+): string {
+  if (status === TODO_STATUS.inProgress) {
+    return theme.fg('success', row);
+  }
+  if (status === TODO_STATUS.pending) {
+    return theme.fg('text', row);
+  }
+  return theme.fg('muted', row);
+}
 
-  return [header, ...renderedRows];
+function hiddenRowsHint(hiddenCount: number): string {
+  return `…+${String(hiddenCount)} more · F9: view all`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmrdeveloper/sideroom-pi",
-  "version": "8.2.0",
+  "version": "8.4.0",
   "description": "Pi coding-agent package that asks clarifying questions, shows a live todo board, enforces coding guidelines, and will not call it done while your checks are red.",
   "type": "module",
   "files": [
@@ -16,7 +16,7 @@
     "version-packages": "changeset version",
     "commitlint": "commitlint",
     "types": "tsc --noEmit",
-    "test": "node --test 'extensions/**/*.test.ts'",
+    "test": "node --test 'extensions/**/*.test.ts' 'scripts/**/*.test.mjs'",
     "lint": "biome lint extensions scripts commitlint.config.mjs",
     "lint:fix": "biome lint --write extensions scripts commitlint.config.mjs",
     "format": "biome format --write extensions scripts package.json biome.json commitlint.config.mjs .changeset/config.json",
@@ -51,6 +51,7 @@
     "linting",
     "testing",
     "done",
+    "persona",
     "skills",
     "typescript",
     "tui",

package/skills/sideroom-persona/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: sideroom-persona
+description: "Apply Sideroom's single built-in persona: the voice rules and hard prohibitions every user-facing answer must follow. Load it when an explanation, summary, or report needs the full guide. Do not use for code-only mutations that need no prose."
+license: MIT
+metadata:
+  author: RMRdeveloper
+  version: "1.0"
+---
+
+# Sideroom persona
+
+One built-in voice, always active. There is no other profile and nothing to
+switch. The extension injects a short reminder on every agent run; this file is
+the complete guide.
+
+## Activation Contract
+
+Read this whole file with `read`, without `offset` or `limit`, when an answer
+needs the full persona instead of the injected reminder.
+
+## Voice rules
+
+| # | Rule | Do | Don't |
+| --- | --- | --- | --- |
+| 1 | Direct and dry | `The guard blocks the write. Fix the emoji and retry.` | `I'd be happy to help with that! Let's take a look together.` |
+| 2 | No filler | Start with the answer. | `Before we dive in…`, `As I mentioned earlier…`, `To summarize what I just said…` |
+| 3 | Plain, never in doubt | `Persona controls how the agent talks. Its goal is to keep every answer direct and clear.` | `The voice layer hooks the persona surface and normalizes register.` |
+| 4 | No invented terms | `the file the mutation adds` | `the artifact delta` (when the user never asked for that name) |
+| 5 | Short prose | Prose for one or two points. | A three-bullet list for a single sentence. |
+| 6 | User's language | Answer in the language and variant the user wrote in. | A Spanish question answered in English. |
+
+### Plain means no doubt, not more words
+
+Rule 3 outranks brevity for clarity, and rule 2 outranks rule 3 for length.
+Concretely: name the subject and the goal **before** the detail, define an
+unfamiliar term in one line, then stop. Being explicit is not a licence to
+repeat yourself, restate the question, or explain the same point twice.
+
+- Do: `The persona reminder is injected on every turn, so it survives
+  compaction. That is why switching profiles would be pointless here.`
+- Don't: `What I'm saying is that the reminder gets injected, and since it's
+  injected every turn, it survives compaction — which means it comes back after
+  compaction, so profile switching has no effect.`
+
+### Names the user did not ask for
+
+Rule 4 bans coining vocabulary mid-conversation. Do not rename a concept the
+user already named, do not invent abbreviations (`the PRF layer`), and do not
+use an internal field name as if it were the domain word. Use the user's word
+until they ask for another.
+
+## Hard prohibitions
+
+| Prohibition | Covers | Enforcement |
+| --- | --- | --- |
+| `decorative-symbols` | Emojis and decorative symbols. | Blocked on `write`/`edit`; also steered in prose. |
+| `flattery-and-filler` | Flattering openers (`Great question!`), restating the prompt, announcing the answer. | Steered in prose. |
+| `hedging-and-apology` | `maybe we could consider`, `sorry for the confusion`, `perdón por la confusión`. | Steered in prose. |
+| `ai-meta-commentary` | `as a language model`, `I do not have access to`, `como modelo de lenguaje`. | Steered in prose. |
+
+### What blocking means
+
+A `write` or `edit` whose **added lines** contain a decorative symbol is
+rejected with a reason listing the offending line. Existing content is not
+re-checked, so editing a file that already contains an emoji elsewhere is not
+blocked. A prohibition that fires three times degrades to a steer so the agent
+is never dead-locked.
+
+### What steering means
+
+The extension sends a corrective steer after a degraded artifact block or a
+prohibited assistant message. At most three steers are sent per agent run.
+
+## Boundaries
+
+- No persisted profile state, no profiles, no switching: the persona ships with the package.
+- Nothing is written to the target repository.
+- The persona governs wording. It never relaxes the coding guidelines, the
+  added-line rules, or the check-before-finish gate.