@rmrdeveloper/sideroom-pi 8.4.0 → 8.6.0

package/README.md

@@ -121,7 +121,7 @@ chat. It never creates a repository task file or a `/todos` command.
 - 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.
+  without hiding work from you; the agent still gets every item in its context.
 
 ### Edited files — proof, not promises
 
@@ -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/done/detect.ts

@@ -157,6 +157,30 @@ function shellOperatorAt(
   return undefined;
 }
 
+export function hasTestSetup(cwd: string): boolean {
+  if (hasPackageTestScript(cwd)) {
+    return true;
+  }
+  if (
+    existsSync(join(cwd, 'pyproject.toml')) ||
+    existsSync(join(cwd, 'setup.py'))
+  ) {
+    return true;
+  }
+  if (existsSync(join(cwd, 'go.mod'))) {
+    return true;
+  }
+  return existsSync(join(cwd, 'Cargo.toml'));
+}
+
+function hasPackageTestScript(cwd: string): boolean {
+  const packagePath = join(cwd, 'package.json');
+  if (!existsSync(packagePath)) {
+    return false;
+  }
+  return typeof readScripts(packagePath).test === 'string';
+}
+
 function detectPackageCommand(cwd: string): CheckCommand | undefined {
   const packagePath = join(cwd, 'package.json');
   if (!existsSync(packagePath)) {

package/extensions/done/guard.ts

@@ -11,6 +11,11 @@ import {
   DONE_GATE_TYPE,
   type DoneState,
   formatDoneSteer,
+  formatMissingTestNotice,
+  isSourcePath,
+  isTestPath,
+  MISSING_TEST_NOTICE_TYPE,
+  shouldNoticeMissingTest,
   shouldSteerDone,
 } from './model.ts';
 
@@ -18,18 +23,29 @@ export type ResolveCommand = (
   ctx: Pick<ExtensionContext, 'cwd'>,
 ) => CheckCommand | undefined;
 
+export type ResolveTestSetup = (ctx: Pick<ExtensionContext, 'cwd'>) => boolean;
+
 export function registerDoneGuard(
   pi: ExtensionAPI,
   state: DoneState,
   resolveCommand: ResolveCommand,
+  resolveTestSetup: ResolveTestSetup,
 ): void {
   const checkRuns = new Set<string>();
+  const mutationPaths = new Map<string, string>();
 
   pi.on('turn_start', () => {
     state.steeredThisTurn = false;
   });
 
   pi.on('tool_call', (event, ctx) => {
+    if (
+      isToolCallEventType('write', event) ||
+      isToolCallEventType('edit', event)
+    ) {
+      mutationPaths.set(event.toolCallId, event.input.path);
+      return;
+    }
     if (!isToolCallEventType('bash', event)) {
       return;
     }
@@ -44,10 +60,14 @@ export function registerDoneGuard(
 
   pi.on('tool_result', (event) => {
     if (isWriteToolResult(event) || isEditToolResult(event)) {
-      if (!event.isError) {
-        state.mutated = true;
-        state.checksGreen = false;
+      const path = mutationPaths.get(event.toolCallId);
+      mutationPaths.delete(event.toolCallId);
+      if (event.isError) {
+        return;
       }
+      state.mutated = true;
+      state.checksGreen = false;
+      recordMutationPath(state, path);
       return;
     }
     if (isBashToolResult(event)) {
@@ -60,18 +80,45 @@ export function registerDoneGuard(
 
   pi.on('turn_end', (_event, ctx) => {
     const check = resolveCommand(ctx);
-    if (check === undefined || !shouldSteerDone(state, true)) {
+    if (check !== undefined && shouldSteerDone(state, true)) {
+      state.steeredThisTurn = true;
+      state.steerCount += 1;
+      pi.sendMessage(
+        {
+          customType: DONE_GATE_TYPE,
+          content: formatDoneSteer(check.display),
+          display: false,
+        },
+        { triggerTurn: true, deliverAs: 'steer' },
+      );
+      return;
+    }
+
+    if (!shouldNoticeMissingTest(state, resolveTestSetup(ctx))) {
       return;
     }
-    state.steeredThisTurn = true;
+    state.noticedMissingTest = true;
     state.steerCount += 1;
     pi.sendMessage(
       {
-        customType: DONE_GATE_TYPE,
-        content: formatDoneSteer(check.display),
+        customType: MISSING_TEST_NOTICE_TYPE,
+        content: formatMissingTestNotice(),
         display: false,
       },
       { triggerTurn: true, deliverAs: 'steer' },
     );
   });
 }
+
+function recordMutationPath(state: DoneState, path: string | undefined): void {
+  if (path === undefined) {
+    return;
+  }
+  if (isTestPath(path)) {
+    state.mutatedTest = true;
+    return;
+  }
+  if (isSourcePath(path)) {
+    state.mutatedSource = true;
+  }
+}

package/extensions/done/index.ts

@@ -2,14 +2,23 @@ import type {
   ExtensionAPI,
   ExtensionContext,
 } from '@earendil-works/pi-coding-agent';
-import { type CheckCommand, detectCheckCommand } from './detect.ts';
-import { type ResolveCommand, registerDoneGuard } from './guard.ts';
+import {
+  type CheckCommand,
+  detectCheckCommand,
+  hasTestSetup,
+} from './detect.ts';
+import {
+  type ResolveCommand,
+  type ResolveTestSetup,
+  registerDoneGuard,
+} from './guard.ts';
 import { createDoneState, resetDoneRun } from './model.ts';
 
 // Pi loads extensions/*/index.ts through export default.
 export default function registerDone(pi: ExtensionAPI): void {
   const state = createDoneState();
   const cache = new Map<string, CheckCommand | undefined>();
+  const testCache = new Map<string, boolean>();
   const resolveCommand: ResolveCommand = (
     ctx: Pick<ExtensionContext, 'cwd'>,
   ) => {
@@ -20,8 +29,19 @@ export default function registerDone(pi: ExtensionAPI): void {
     cache.set(ctx.cwd, command);
     return command;
   };
+  const resolveTestSetup: ResolveTestSetup = (
+    ctx: Pick<ExtensionContext, 'cwd'>,
+  ) => {
+    const cached = testCache.get(ctx.cwd);
+    if (cached !== undefined) {
+      return cached;
+    }
+    const hasTests = hasTestSetup(ctx.cwd);
+    testCache.set(ctx.cwd, hasTests);
+    return hasTests;
+  };
 
-  registerDoneGuard(pi, state, resolveCommand);
+  registerDoneGuard(pi, state, resolveCommand, resolveTestSetup);
 
   pi.on('input', (event) => {
     if (event.source === 'interactive' || event.source === 'rpc') {

package/extensions/done/model.ts

@@ -3,18 +3,35 @@ export interface DoneState {
   checksGreen: boolean;
   steeredThisTurn: boolean;
   steerCount: number;
+  mutatedSource: boolean;
+  mutatedTest: boolean;
+  noticedMissingTest: boolean;
 }
 
 export const MAX_DONE_STEERS = 2;
 
 export const DONE_GATE_TYPE = 'sideroom-done-gate';
 
+export const MISSING_TEST_NOTICE_TYPE = 'sideroom-missing-test-notice';
+
+const TEST_DIRECTORY = /(?:^|\/)(?:__tests__|tests?|specs?)(?:\/|$)/;
+
+// Test paths are recognised by name only: the notice never claims the right
+// test exists, so a missed convention only costs a nudge, never a false pass.
+const TEST_FILE =
+  /(?:^|\/)(?:test_[\w.-]*\.py|[\w.-]*[._](?:test|spec)\.[\w.-]+|[\w.-]*(?:Test|Tests)\.java)$/;
+
+const SOURCE_FILE = /\.(?:[cm]?js|jsx|ts|tsx|go|java|php|py|rs)$/i;
+
 export function createDoneState(): DoneState {
   return {
     mutated: false,
     checksGreen: false,
     steeredThisTurn: false,
     steerCount: 0,
+    mutatedSource: false,
+    mutatedTest: false,
+    noticedMissingTest: false,
   };
 }
 
@@ -23,6 +40,19 @@ export function resetDoneRun(state: DoneState): void {
   state.checksGreen = false;
   state.steeredThisTurn = false;
   state.steerCount = 0;
+  state.mutatedSource = false;
+  state.mutatedTest = false;
+  state.noticedMissingTest = false;
+}
+
+export function isTestPath(path: string): boolean {
+  const normalized = path.replaceAll('\\', '/');
+  return TEST_DIRECTORY.test(normalized) || TEST_FILE.test(normalized);
+}
+
+export function isSourcePath(path: string): boolean {
+  const normalized = path.replaceAll('\\', '/');
+  return SOURCE_FILE.test(normalized);
 }
 
 export function shouldSteerDone(
@@ -38,6 +68,23 @@ export function shouldSteerDone(
   );
 }
 
+export function shouldNoticeMissingTest(
+  state: DoneState,
+  hasTests: boolean,
+): boolean {
+  return (
+    hasTests &&
+    state.mutatedSource &&
+    !state.mutatedTest &&
+    !state.noticedMissingTest &&
+    state.steerCount < MAX_DONE_STEERS
+  );
+}
+
 export function formatDoneSteer(display: string): string {
   return `Run \`${display}\` and make it pass before finishing.`;
 }
+
+export function formatMissingTestNotice(): string {
+  return 'This run changed code files and no test file. Add or update the test that covers the change before finishing.';
+}

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/rules/catalog.ts

@@ -18,19 +18,23 @@ export type LanguageId = (typeof LANGUAGE)[keyof typeof LANGUAGE];
 
 export type RuleId =
   | 'braced-conditionals'
+  | 'explicit-any'
   | 'explicit-error-handling'
   | 'clear-names'
   | 'comments'
-  | 'debug-artifacts';
+  | 'debug-artifacts'
+  | 'suppressed-type-errors';
 
 export type RuleSeverity = (typeof SEVERITY)[keyof typeof SEVERITY];
 
 export const RULE_SEVERITY: Readonly<Record<RuleId, RuleSeverity>> = {
   'braced-conditionals': SEVERITY.block,
+  'explicit-any': SEVERITY.block,
   'explicit-error-handling': SEVERITY.block,
   'clear-names': SEVERITY.warn,
   comments: SEVERITY.warn,
   'debug-artifacts': SEVERITY.warn,
+  'suppressed-type-errors': SEVERITY.warn,
 };
 
 export function languageForPath(path: string): LanguageId {
@@ -69,3 +73,7 @@ export function languageForPath(path: string): LanguageId {
 export function supportsBracedConditionals(language: LanguageId): boolean {
   return language !== LANGUAGE.python && language !== LANGUAGE.generic;
 }
+
+export function supportsExplicitAny(language: LanguageId): boolean {
+  return language === LANGUAGE.typescript;
+}

package/extensions/rules/checks.ts

@@ -4,6 +4,7 @@ import {
   RULE_SEVERITY,
   type RuleId,
   supportsBracedConditionals,
+  supportsExplicitAny,
 } from './catalog.ts';
 import { maskNonCode } from './lexer.ts';
 import type { AddedLine, RuleViolation } from './model.ts';
@@ -38,6 +39,29 @@ const DEBUG_PATTERNS: readonly RegExp[] = [
   /\bdbg!\s*\(/,
 ];
 
+// Keep these patterns on syntax that can only introduce a type. Value-level
+// commas, assignments, and operators may legally surround an identifier named
+// `any`, so they are deliberately absent.
+const EXPLICIT_ANY_PATTERNS: readonly RegExp[] = [
+  /\bas\s+any\b/,
+  /\b(?:keyof|satisfies)\s+any\b/,
+  /\bany\s*\[\s*\]/,
+  /\b[$\w]+<[^<>\n]*\bany\b[^<>\n]*>(?!\s*[$\w])/,
+  /\binterface\s+[$\w]+(?:\s*<[^;{\n]*>)?\s*\{[^}\n]*:\s*[^;}\n]*\bany\b/,
+  /\b(?:const|let|var)\s+[$\w]+\s*:\s*(?:(?:=>)|[^;=\n])*\bany\b/,
+  /(?:^|[(,])\s*(?:\.\.\.)?[$\w]+\??\s*:\s*(?:(?:=>)|[^;=\n])*\bany\b/,
+  /\)\s*:\s*(?:(?:=>)|[^;={\n])*\bany\b/,
+  /^\s*(?:(?:public|private|protected|readonly|static|declare|abstract)\s+)*[$\w]+[?!]?\s*:\s*(?:(?:=>)|[^;,=\n])*\bany\b[^;=\n]*(?:;|=)/,
+];
+
+// A suppression is a comment whose first token is the directive; prose that
+// mentions the directive, or a string that quotes it, is not one.
+const SUPPRESSED_TYPE_ERRORS =
+  /(?:^|\s)(?:\/\/|\/\*)\s*@ts-(?:ignore|nocheck)\b/;
+
+const TYPE_ALIAS = /\btype\s+[$\w]+(?:\s*<[^;=]*>)?\s*=/g;
+const ANY_TOKEN = /\bany\b/g;
+
 const FUNCTION_PARAMS: readonly RegExp[] = [
   /\bfunction\s+\w*\s*\(([^()]*)\)/g,
   /\bdef\s+\w+\s*\(([^()]*)\)/g,
@@ -54,10 +78,17 @@ export function evaluateAddedLines(
   const code = maskNonCode(joined, language);
   const codeLines = code.split('\n');
   const usesBracedConditionals = supportsBracedConditionals(language);
+  const usesExplicitAny = supportsExplicitAny(language);
+  const commentLines = usesExplicitAny
+    ? maskNonCode(joined, language, { keepComments: true }).split('\n')
+    : [];
 
   if (usesBracedConditionals) {
     collectBracedConditionals(code, lines, violations);
   }
+  if (usesExplicitAny) {
+    collectTypeAliasAny(code, lines, violations);
+  }
 
   for (let index = 0; index < lines.length; index += 1) {
     const added = lines[index];
@@ -71,6 +102,13 @@ export function evaluateAddedLines(
     if (language === LANGUAGE.python) {
       collectPythonSuite(codeLine, violations);
     }
+    if (usesExplicitAny) {
+      collectExplicitAny(codeLine, violations);
+      collectSuppressedTypeErrors(
+        { line: added.line, text: commentLines[index] ?? '' },
+        violations,
+      );
+    }
     collectClearNames(codeLine, violations);
     collectComments(added, violations);
     collectDebugArtifacts(codeLine, violations);
@@ -274,6 +312,123 @@ function collectDebugArtifacts(
   }
 }
 
+function collectExplicitAny(
+  codeLine: AddedLine,
+  violations: RuleViolation[],
+): void {
+  const typeCode = codeLine.text
+    .replaceAll(/\btypeof\s+any\b/g, (match) => ' '.repeat(match.length))
+    .replaceAll(/^\s*(?:import|export)\s*\{[^}]*\}/g, (match) =>
+      ' '.repeat(match.length),
+    );
+  if (EXPLICIT_ANY_PATTERNS.some((pattern) => pattern.test(typeCode))) {
+    violations.push(
+      violation(
+        'explicit-any',
+        "[explicit-any] Replace 'any' with the type the value actually has; use 'unknown' only when it must be narrowed first.",
+        codeLine.line,
+      ),
+    );
+  }
+}
+
+function collectTypeAliasAny(
+  code: string,
+  lines: readonly AddedLine[],
+  violations: RuleViolation[],
+): void {
+  const aliases = code.matchAll(
+    new RegExp(TYPE_ALIAS.source, TYPE_ALIAS.flags),
+  );
+  for (const alias of aliases) {
+    const bodyOffset = (alias.index ?? 0) + alias[0].length;
+    const endOffset = typeAliasEndOffset(code, bodyOffset);
+    const body = code.slice(bodyOffset, endOffset);
+    for (const anyMatch of body.matchAll(
+      new RegExp(ANY_TOKEN.source, ANY_TOKEN.flags),
+    )) {
+      const anyOffset = bodyOffset + (anyMatch.index ?? 0);
+      if (isValueLevelAnyInType(code, anyOffset)) {
+        continue;
+      }
+      violations.push(
+        violation(
+          'explicit-any',
+          "[explicit-any] Replace 'any' with the type the value actually has; use 'unknown' only when it must be narrowed first.",
+          lineForOffset(code, lines, anyOffset),
+        ),
+      );
+    }
+  }
+}
+
+function typeAliasEndOffset(code: string, bodyOffset: number): number {
+  let braceDepth = 0;
+  let bracketDepth = 0;
+  let parenthesisDepth = 0;
+  for (let index = bodyOffset; index < code.length; index += 1) {
+    const character = code[index];
+    if (character === '{') {
+      braceDepth += 1;
+      continue;
+    }
+    if (character === '}') {
+      braceDepth -= 1;
+      continue;
+    }
+    if (character === '[') {
+      bracketDepth += 1;
+      continue;
+    }
+    if (character === ']') {
+      bracketDepth -= 1;
+      continue;
+    }
+    if (character === '(') {
+      parenthesisDepth += 1;
+      continue;
+    }
+    if (character === ')') {
+      parenthesisDepth -= 1;
+      continue;
+    }
+    if (
+      character === ';' &&
+      braceDepth === 0 &&
+      bracketDepth === 0 &&
+      parenthesisDepth === 0
+    ) {
+      return index;
+    }
+  }
+  return code.length;
+}
+
+function isValueLevelAnyInType(code: string, anyOffset: number): boolean {
+  const prefix = code.slice(0, anyOffset);
+  if (/\btypeof\s*$/.test(prefix) || /\.\s*$/.test(prefix)) {
+    return true;
+  }
+  const suffix = code.slice(anyOffset + 'any'.length);
+  return /^\s*\??\s*(?::|\()/.test(suffix);
+}
+
+function collectSuppressedTypeErrors(
+  commentLine: AddedLine,
+  violations: RuleViolation[],
+): void {
+  if (!SUPPRESSED_TYPE_ERRORS.test(commentLine.text)) {
+    return;
+  }
+  violations.push(
+    violation(
+      'suppressed-type-errors',
+      "[suppressed-type-errors] Replace '@ts-ignore' or '@ts-nocheck' with '@ts-expect-error' and an explanation, or fix the type.",
+      commentLine.line,
+    ),
+  );
+}
+
 function closingParenthesisOffset(
   code: string,
   openingOffset: number,

package/extensions/rules/lexer.ts

@@ -9,8 +9,18 @@ const LEXICAL_MODE = {
 
 type LexicalMode = (typeof LEXICAL_MODE)[keyof typeof LEXICAL_MODE];
 
-export function maskNonCode(source: string, language: LanguageId): string {
+export interface MaskOptions {
+  /** Keep comment text so a caller can read the directives inside it. */
+  readonly keepComments?: boolean;
+}
+
+export function maskNonCode(
+  source: string,
+  language: LanguageId,
+  options: MaskOptions = {},
+): string {
   const masked = [...source];
+  const keepComments = options.keepComments === true;
   let mode: LexicalMode = LEXICAL_MODE.code;
   let delimiter = '';
 
@@ -22,20 +32,20 @@ export function maskNonCode(source: string, language: LanguageId): string {
         mode = LEXICAL_MODE.code;
         continue;
       }
-      maskCharacter(masked, index);
+      maskComment(masked, index, keepComments);
       continue;
     }
 
     if (mode === LEXICAL_MODE.blockComment) {
       const closesComment = character === '*' && source[index + 1] === '/';
       if (closesComment) {
-        maskCharacter(masked, index);
-        maskCharacter(masked, index + 1);
+        maskComment(masked, index, keepComments);
+        maskComment(masked, index + 1, keepComments);
         index += 1;
         mode = LEXICAL_MODE.code;
         continue;
       }
-      maskCharacter(masked, index);
+      maskComment(masked, index, keepComments);
       continue;
     }
 
@@ -58,7 +68,7 @@ export function maskNonCode(source: string, language: LanguageId): string {
         mode = LEXICAL_MODE.code;
         continue;
       }
-      if (delimiter.length === 1 && character === '\n') {
+      if (delimiter !== '`' && character === '\n') {
         mode = LEXICAL_MODE.code;
         continue;
       }
@@ -68,8 +78,8 @@ export function maskNonCode(source: string, language: LanguageId): string {
 
     const startsLineComment = character === '/' && source[index + 1] === '/';
     if (startsLineComment) {
-      maskCharacter(masked, index);
-      maskCharacter(masked, index + 1);
+      maskComment(masked, index, keepComments);
+      maskComment(masked, index + 1, keepComments);
       index += 1;
       mode = LEXICAL_MODE.lineComment;
       continue;
@@ -77,8 +87,8 @@ export function maskNonCode(source: string, language: LanguageId): string {
 
     const startsBlockComment = character === '/' && source[index + 1] === '*';
     if (startsBlockComment) {
-      maskCharacter(masked, index);
-      maskCharacter(masked, index + 1);
+      maskComment(masked, index, keepComments);
+      maskComment(masked, index + 1, keepComments);
       index += 1;
       mode = LEXICAL_MODE.blockComment;
       continue;
@@ -87,7 +97,7 @@ export function maskNonCode(source: string, language: LanguageId): string {
     const startsHashComment =
       character === '#' && supportsHashComments(language);
     if (startsHashComment) {
-      maskCharacter(masked, index);
+      maskComment(masked, index, keepComments);
       mode = LEXICAL_MODE.lineComment;
       continue;
     }
@@ -134,3 +144,14 @@ function maskCharacter(masked: string[], index: number): void {
     masked[index] = ' ';
   }
 }
+
+function maskComment(
+  masked: string[],
+  index: number,
+  keepComments: boolean,
+): void {
+  if (keepComments) {
+    return;
+  }
+  maskCharacter(masked, index);
+}

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.',
 ];
@@ -50,7 +50,7 @@ export default function registerTodo(pi: ExtensionAPI): void {
     notifyWidgetRefresh(ctx);
   };
 
-  registerSessionRefreshEvents(pi, restoreAndRefresh);
+  registerSessionRefreshEvents(pi, store, restoreAndRefresh);
   registerGuardEvents(pi, store, restore);
   registerBoardContext(pi, store, restoreAndRefresh);
   registerTodoTool(pi, store, notifyWidgetRefresh);

package/extensions/todo/session.ts

@@ -13,11 +13,13 @@ import {
 import { renderTodoWidget } from './ui.ts';
 
 export const SNAPSHOT_TYPE = 'sideroom-todo';
+export const BOARD_MESSAGE_TYPE = 'sideroom-todo-board';
 export const WIDGET_KEY = 'sideroom-todo';
 export const TODO_WIDGET_REFRESH_EVENT = 'sideroom:todo-widget-refreshed';
 
 export interface TodoStore {
   items: readonly TodoItem[];
+  lastSentBlock?: string;
 }
 
 export type BoardLifecycle = (ctx: ExtensionContext) => void;
@@ -89,11 +91,29 @@ export function commitBoard(
 
 export function registerSessionRefreshEvents(
   pi: ExtensionAPI,
+  store: TodoStore,
   restoreAndRefresh: BoardLifecycle,
 ): void {
-  pi.on('session_start', (_event, ctx) => restoreAndRefresh(ctx));
-  pi.on('session_tree', (_event, ctx) => restoreAndRefresh(ctx));
-  pi.on('session_compact', (_event, ctx) => restoreAndRefresh(ctx));
+  // A restore can drop the sent block from the model's context, so an unchanged
+  // board still has to be announced again.
+  const restoreSession = (ctx: ExtensionContext) => {
+    restoreAndRefresh(ctx);
+    forgetSentBoardBlock(store);
+  };
+  pi.on('session_start', (_event, ctx) => restoreSession(ctx));
+  pi.on('session_tree', (_event, ctx) => restoreSession(ctx));
+  pi.on('session_compact', (event, ctx) => {
+    restoreSession(ctx);
+    if (!event.willRetry) {
+      return;
+    }
+    const block = pendingBoardBlock(store);
+    if (block === undefined) {
+      return;
+    }
+    store.lastSentBlock = block;
+    pi.sendMessage(boardMessage(block), { deliverAs: 'steer' });
+  });
 }
 
 export function registerBoardContext(
@@ -101,17 +121,46 @@ export function registerBoardContext(
   store: TodoStore,
   restoreAndRefresh: BoardLifecycle,
 ): void {
-  pi.on('before_agent_start', (event, ctx) => {
+  pi.on('before_agent_start', (_event, ctx) => {
     restoreAndRefresh(ctx);
-    if (store.items.length === 0) {
+    const block = pendingBoardBlock(store);
+    if (block === undefined) {
       return;
     }
-    return {
-      systemPrompt: `${event.systemPrompt}\n\n${formatBoardBlock(store.items)}`,
-    };
+    store.lastSentBlock = block;
+    return { message: boardMessage(block) };
   });
 }
 
+// The block rides a session message instead of the system prompt: a volatile
+// system prompt invalidates the cached prefix of the whole request.
+function pendingBoardBlock(store: TodoStore): string | undefined {
+  if (store.items.length === 0) {
+    return undefined;
+  }
+  const block = formatBoardBlock(store.items);
+  if (block === store.lastSentBlock) {
+    return undefined;
+  }
+  return block;
+}
+
+function forgetSentBoardBlock(store: TodoStore): void {
+  store.lastSentBlock = undefined;
+}
+
+function boardMessage(block: string): {
+  customType: typeof BOARD_MESSAGE_TYPE;
+  content: string;
+  display: false;
+} {
+  return {
+    customType: BOARD_MESSAGE_TYPE,
+    content: block,
+    display: false,
+  };
+}
+
 function findSnapshotItems(
   branch: SessionBranch,
 ): readonly TodoItem[] | undefined {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmrdeveloper/sideroom-pi",
-  "version": "8.4.0",
+  "version": "8.6.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": [
@@ -22,6 +22,7 @@
     "format": "biome format --write extensions scripts package.json biome.json commitlint.config.mjs .changeset/config.json",
     "format:check": "biome format extensions scripts package.json biome.json commitlint.config.mjs .changeset/config.json",
     "preview": "node scripts/render-preview.mjs",
+    "cache:report": "node scripts/cache-report.mjs",
     "check:if-blocks": "node scripts/check-if-blocks.mjs",
     "check": "npm run types && npm run check:if-blocks && biome check extensions scripts package.json biome.json commitlint.config.mjs .changeset/config.json && npm test"
   },
@@ -69,7 +70,8 @@
   },
   "pi": {
     "extensions": [
-      "./extensions"
+      "./extensions",
+      "!extensions/*.test.ts"
     ],
     "skills": [
       "./skills"

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