@rmrdeveloper/sideroom-pi 8.4.0 → 8.5.0

package/README.md

@@ -189,12 +189,12 @@ 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
+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 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.
+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
 
@@ -292,8 +292,10 @@ the diff against the loaded guide and run the relevant project checks.
 - 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.
+- 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
@@ -310,13 +312,14 @@ the diff against the loaded guide and run the relevant project checks.
 
 ### Explain contract
 
-- Trigger: `agent_settled` with at least one successful `write`/`edit` since the
-  last user prompt, in TUI mode.
+- 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 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.
+  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

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

@@ -7,10 +7,15 @@ import {
   EXPLAIN_OFFER,
   EXPLAIN_OFFER_TYPE,
   type ExplainState,
-  resetExplainRun,
+  mutationPathKey,
+  resetExplainTurn,
   shouldOfferExplanation,
 } from './model.ts';
 
+interface FileToolInput {
+  readonly path: string;
+}
+
 export function registerExplainGuard(
   pi: ExtensionAPI,
   state: ExplainState,
@@ -19,17 +24,23 @@ export function registerExplainGuard(
     if (event.source !== 'interactive' && event.source !== 'rpc') {
       return;
     }
-    resetExplainRun(state);
+    resetExplainTurn(state);
   });
 
-  pi.on('tool_result', (event) => {
+  pi.on('tool_result', (event, ctx) => {
     if (event.isError) {
       return;
     }
     if (!isEditToolResult(event) && !isWriteToolResult(event)) {
       return;
     }
-    state.mutatedSincePrompt = true;
+    // 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
@@ -38,7 +49,7 @@ export function registerExplainGuard(
     if (!shouldOfferExplanation(state, ctx.mode)) {
       return;
     }
-    state.offeredThisRun = true;
+    state.offeredThisTurn = true;
     pi.sendMessage(
       {
         customType: EXPLAIN_OFFER_TYPE,

package/extensions/explain/index.ts

@@ -1,11 +1,11 @@
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { registerExplainGuard } from './guard.ts';
-import { createExplainState, resetExplainRun } from './model.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', () => resetExplainRun(state));
+  pi.on('session_start', () => resetExplainTurn(state));
 }

package/extensions/explain/model.ts

@@ -1,22 +1,34 @@
+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 three options: explain changes and test steps, test steps only, or no explanation. Recommend one.";
+  "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 {
-  mutatedSincePrompt: boolean;
-  offeredThisRun: boolean;
+  mutatedFilesThisTurn: Set<string>;
+  offeredThisTurn: boolean;
 }
 
 export function createExplainState(): ExplainState {
-  return { mutatedSincePrompt: false, offeredThisRun: false };
+  return { mutatedFilesThisTurn: new Set(), offeredThisTurn: false };
+}
+
+export function resetExplainTurn(state: ExplainState): void {
+  state.mutatedFilesThisTurn.clear();
+  state.offeredThisTurn = false;
 }
 
-export function resetExplainRun(state: ExplainState): void {
-  state.mutatedSincePrompt = false;
-  state.offeredThisRun = 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.
@@ -24,5 +36,9 @@ export function shouldOfferExplanation(
   state: ExplainState,
   mode: string,
 ): boolean {
-  return mode === TUI_MODE && state.mutatedSincePrompt && !state.offeredThisRun;
+  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/checks.ts

@@ -16,7 +16,7 @@ interface ProhibitionDetector {
 const DETECTORS: readonly ProhibitionDetector[] = [
   {
     prohibitionId: 'decorative-symbols',
-    pattern: /\p{Extended_Pictographic}|\uFE0F|[\u2713\u2714\u2717\u2718]/u,
+    pattern: /\p{Emoji_Presentation}|\uFE0F|[\u2713\u2714\u2717\u2718]/u,
   },
   {
     prohibitionId: 'flattery-and-filler',

package/extensions/persona/guard.ts

@@ -1,10 +1,10 @@
 import { readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
 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,
@@ -107,7 +107,11 @@ function extractMutation(
   cwd: string,
 ): ExtractedMutation | undefined {
   if (isToolCallEventType('write', event)) {
-    const previous = readFileIfExists(resolve(cwd, event.input.path));
+    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),
@@ -126,17 +130,13 @@ function readFileIfExists(path: string): string | undefined {
   try {
     return readFileSync(path, 'utf8');
   } catch (error) {
-    if (isMissingFile(error)) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
       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;
 }

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.4.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": [

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

@@ -62,9 +62,12 @@ until they ask for another.
 
 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.
+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