@rmrdeveloper/sideroom-pi 8.3.0 → 8.5.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
 
@@ -163,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
@@ -172,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 only, how to test them
+only, both, 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 turn, only when the turn touched at
+least five distinct files, 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
@@ -260,6 +284,23 @@ 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. Full rewrites
+  resolve Pi path aliases before comparing existing content; semantic copyright,
+  trademark, and registration symbols remain valid. 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
@@ -269,6 +310,18 @@ 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 five distinct files mutated since the
+  last user prompt, in TUI mode. File identity follows Pi's path aliases and
+  canonicalizes existing paths.
+- The steer names the intent; the agent writes the question in the user's
+  language with four options, one of them a decline, and one recommendation.
+  `sideroom_ask` still adds *Out of scope* and the custom answer.
+- At most one offer per turn. 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.
@@ -293,6 +346,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/ask/index.ts

@@ -15,14 +15,11 @@ 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.',
-  'When a non-trivial request is not yet a settled spec, follow the sideroom-grill skill before implementing; it owns the interview and drives sideroom_ask rounds.',
-  '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, and in a multiple-selection question they replace the selections.',
-  'For a genuinely plural sideroom_ask question, set selectionMode "multiple" with recommendedIndices (at least one) instead of recommendationIndex; never send both fields, and keep the single default otherwise.',
-  '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.',
+  'When a non-trivial request is not yet a settled spec, follow the sideroom-grill skill before implementing; it owns the interview and drives sideroom_ask rounds. One sideroom_ask call is one batch; call it again for another round.',
+  'A decision the repository already settles consistently is a project fact: read the code and reuse it. A decision that materially affects architecture, dependencies, cost, security, operations, persistence, public contracts, or future change difficulty is an architectural decision: expose it through sideroom_ask before committing, with the practical consequences of each alternative and one recommendation that carries a one-line justification, never a list of technology names. If the repository shows two inconclusive patterns for the same kind of decision, name the inconsistency in the prompt. Everything else is a minor decision: take it yourself.',
+  'Write sideroom_ask prompts, tab labels, option labels, and option descriptions in the language the user is speaking; keep ids and option values in English.',
+  'sideroom_ask always adds Out of scope and a write-your-own answer; never send them yourself. A single-selection question needs recommendationIndex; a multiple-selection question needs recommendedIndices and never recommendationIndex.',
+  'sideroom_ask only works in the interactive TUI; it errors in print, JSON, and RPC modes.',
 ];
 
 // Pi loads extensions/*/index.ts through export default.

package/extensions/explain/guard.ts

@@ -0,0 +1,62 @@
+import {
+  type ExtensionAPI,
+  isEditToolResult,
+  isWriteToolResult,
+} from '@earendil-works/pi-coding-agent';
+import {
+  EXPLAIN_OFFER,
+  EXPLAIN_OFFER_TYPE,
+  type ExplainState,
+  mutationPathKey,
+  resetExplainTurn,
+  shouldOfferExplanation,
+} from './model.ts';
+
+interface FileToolInput {
+  readonly path: string;
+}
+
+export function registerExplainGuard(
+  pi: ExtensionAPI,
+  state: ExplainState,
+): void {
+  pi.on('input', (event) => {
+    if (event.source !== 'interactive' && event.source !== 'rpc') {
+      return;
+    }
+    resetExplainTurn(state);
+  });
+
+  pi.on('tool_result', (event, ctx) => {
+    if (event.isError) {
+      return;
+    }
+    if (!isEditToolResult(event) && !isWriteToolResult(event)) {
+      return;
+    }
+    // SAFETY: Pi validates built-in file-tool inputs before emitting tool_result.
+    const input = event.input as unknown as FileToolInput;
+    const pathKey = mutationPathKey(ctx.cwd, input.path);
+    if (pathKey === undefined) {
+      return;
+    }
+    state.mutatedFilesThisTurn.add(pathKey);
+  });
+
+  // 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.offeredThisTurn = 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, resetExplainTurn } 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', () => resetExplainTurn(state));
+}

package/extensions/explain/model.ts

@@ -0,0 +1,44 @@
+import { resolveFileToolPath } from '../shared/file-path.ts';
+
+export const EXPLAIN_OFFER_TYPE = 'sideroom-explain-offer';
+
+// Five is the point where a turn stopped being an adjustment and became work
+// worth walking the user through.
+export const EXPLAIN_FILE_THRESHOLD = 5;
+
+const TUI_MODE = 'tui';
+
+export const EXPLAIN_OFFER =
+  "Use sideroom_ask for one question in the user's language with four parallel options: changes only, test steps only, both, or no explanation. Recommend changes only.";
+
+export interface ExplainState {
+  mutatedFilesThisTurn: Set<string>;
+  offeredThisTurn: boolean;
+}
+
+export function createExplainState(): ExplainState {
+  return { mutatedFilesThisTurn: new Set(), offeredThisTurn: false };
+}
+
+export function resetExplainTurn(state: ExplainState): void {
+  state.mutatedFilesThisTurn.clear();
+  state.offeredThisTurn = false;
+}
+
+// Pi reports the path as the model wrote it, so use the built-in file-tool
+// semantics and canonicalize existing aliases before counting the file.
+export function mutationPathKey(cwd: string, path: string): string | undefined {
+  return resolveFileToolPath(cwd, path);
+}
+
+// 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.mutatedFilesThisTurn.size >= EXPLAIN_FILE_THRESHOLD &&
+    !state.offeredThisTurn
+  );
+}

package/extensions/guidelines/prompt.ts

@@ -5,14 +5,16 @@ export { LANGUAGE_GUIDE_FILES } from './catalog.ts';
 export const GUIDELINES_REMINDER_HEADING =
   'Sideroom coding guidelines (always-on reminder):';
 
-const LANGUAGE_GUIDE_REMINDERS = LANGUAGE_GUIDES.map(
-  ({ extensions, path }) =>
-    `If a file you will write or edit ends in ${extensions.join(' or ')}, use the read tool without offset or limit to load the exact matching guide at ${path} in full.`,
-).join('\n');
+// One dense index instead of one sentence per language: the same paths and the
+// same requirement, a fraction of the tokens every turn.
+const LANGUAGE_GUIDE_INDEX = LANGUAGE_GUIDES.map(
+  ({ extensions, path }) => `${extensions.join('/')} ${path}`,
+).join('; ');
 
 export const GUIDELINES_REMINDER = `${GUIDELINES_REMINDER_HEADING}
-Before the first write or edit in each agent run, use the read tool without offset or limit to load ${GUIDELINE_SKILL_PATH} in full.
-${LANGUAGE_GUIDE_REMINDERS}
+Before the first write or edit in each agent run, use the read tool without offset or limit to load these files in full:
+- ${GUIDELINE_SKILL_PATH}
+- for the extension of the file you will change, one of: ${LANGUAGE_GUIDE_INDEX}
 A required read counts only when it succeeds without truncation. Until all required reads succeed, do not call write or edit and do not mutate files through bash or another tool; the extension blocks those mutations.
 After changing files, review the code against the loaded guide and run the relevant formatter, linter, type checks, and tests.`;
 

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{Emoji_Presentation}|\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 {
+  type ExtensionAPI,
+  isToolCallEventType,
+  type ToolCallEvent,
+} from '@earendil-works/pi-coding-agent';
+import { resolveFileToolPath } from '../shared/file-path.ts';
+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 absolutePath = resolveFileToolPath(cwd, event.input.path);
+    if (absolutePath === undefined) {
+      return undefined;
+    }
+    const previous = readFileIfExists(absolutePath);
+    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 (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+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/shared/file-path.ts

@@ -0,0 +1,83 @@
+import { realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const FILE_URL_PREFIX = 'file://';
+const MISSING_PATH_ERROR_CODE = {
+  file: 'ENOENT',
+  directory: 'ENOTDIR',
+} as const;
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+
+// File guards must resolve the model's path exactly as Pi's built-in tools do.
+export function resolveFileToolPath(
+  cwd: string,
+  path: string,
+): string | undefined {
+  const normalizedPath = normalizeFileToolPath(path);
+  if (normalizedPath.length === 0) {
+    return undefined;
+  }
+
+  const localPath = normalizedPath.startsWith(FILE_URL_PREFIX)
+    ? fileURLToPath(normalizedPath)
+    : normalizedPath;
+  const absolutePath = isAbsolute(localPath)
+    ? resolve(localPath)
+    : resolve(cwd, localPath);
+  return realpathOr(absolutePath);
+}
+
+function normalizeFileToolPath(path: string): string {
+  const normalizedSpaces = path.replace(UNICODE_SPACES, ' ');
+  const withoutAtPrefix = normalizedSpaces.startsWith('@')
+    ? normalizedSpaces.slice(1)
+    : normalizedSpaces;
+  return expandHome(normalizeWindowsShellPath(withoutAtPrefix));
+}
+
+function normalizeWindowsShellPath(path: string): string {
+  if (
+    process.platform !== 'win32' ||
+    !path.startsWith('/') ||
+    path.startsWith('//') ||
+    path.includes('\\')
+  ) {
+    return path;
+  }
+
+  const match = path.match(/^\/(?:mnt\/|cygdrive\/)?([a-z])(?:\/(.*))?$/i);
+  const drive = match?.[1];
+  if (drive === undefined) {
+    return path;
+  }
+  const suffix = match?.[2]?.replaceAll('/', '\\') ?? '';
+  return `${drive.toUpperCase()}:\\${suffix}`;
+}
+
+function expandHome(path: string): string {
+  if (path === '~') {
+    return homedir();
+  }
+  if (path.startsWith('~/') || path.startsWith('~\\')) {
+    return join(homedir(), path.slice(2));
+  }
+  return path;
+}
+
+function realpathOr(path: string): string {
+  try {
+    return realpathSync.native(path);
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      'code' in error &&
+      (error.code === MISSING_PATH_ERROR_CODE.file ||
+        error.code === MISSING_PATH_ERROR_CODE.directory)
+    ) {
+      return path;
+    }
+    throw error;
+  }
+}

package/extensions/todo/index.ts

@@ -28,7 +28,7 @@ export const TODO_PROMPT_SNIPPET =
 
 export const TODO_PROMPT_GUIDELINES = [
   'Use sideroom_todo to maintain a live work board when implementation has more than one step.',
-  'Use propose to replace the board and update to patch item ids. While any item is pending, exactly one must be in_progress.',
+  'While any item is pending, exactly one must be in_progress.',
   'Complete the current item and start the next item in the same update call.',
   'propose is interactive-TUI-only; update also works in print, JSON, and RPC modes.',
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmrdeveloper/sideroom-pi",
-  "version": "8.3.0",
+  "version": "8.5.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": [
@@ -51,6 +51,7 @@
     "linting",
     "testing",
     "done",
+    "persona",
     "skills",
     "typescript",
     "tui",

package/skills/sideroom-grill/SKILL.md

@@ -25,6 +25,15 @@ if the effort is too big to hold in one session, say so and stop.
   in the language the user is speaking; keep ids and option values in English.
 - Never ask the user what the codebase can answer. Read the code first; ask
   only what the code cannot settle.
+- Classify before asking. A project fact is read from the code and reused. A
+  minor decision is taken without interrupting. A decision that materially
+  affects architecture, external dependencies, cost, security, operations,
+  persistence, public contracts, or future change difficulty is architectural
+  and must be exposed.
+- Present an architectural decision as the current situation, the alternatives
+  by their practical consequences, and one recommendation with a one-line
+  justification. Never reduce it to technology names. Name a repository
+  inconsistency in the prompt instead of picking one.
 - An *Out of scope* answer closes that thread. Do not re-ask it.
 - Everything a round settles is recorded through `sideroom-domain-modeling`:
   inline glossary entries, the ADR three-gate offer, lazy file creation.
@@ -38,9 +47,11 @@ if the effort is too big to hold in one session, say so and stop.
 1. Read the code around the change. Settle from the codebase everything the
    codebase settles.
 2. Run one `sideroom_ask` round on what remains genuinely open: terms first,
-   then decisions.
+   then the architectural decisions. Minor decisions are yours; do not spend a
+   round on them.
 3. After each round, write resolved terms to `CONTEXT.md` and qualifying
-   decisions to `docs/adr/`.
+   decisions to `docs/adr/`. Offer the ADR for an accepted architectural
+   decision only when all three gates pass.
 4. Repeat until no open term or hard decision remains, or the user cancels.
 5. Close by stating the settled glossary, the ADRs written (if any), and the
    suggested next step: a spec for anything non-trivial, implementation for

package/skills/sideroom-persona/SKILL.md

@@ -0,0 +1,82 @@
+---
+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, including when the model uses Pi path aliases for a full rewrite.
+The detector targets default emoji presentation, emoji variation selectors,
+and explicit check or cross marks; semantic copyright, trademark, and
+registration symbols stay valid.
+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.