@rmrdeveloper/sideroom-pi 8.0.1 → 8.1.0

package/README.md

@@ -6,9 +6,10 @@
 
 > Coding agents fail in predictable ways: they guess instead of asking, they
 > bury progress in chat scroll, they litter your repo with `TODO.md` files,
-> and every session writes code in a slightly different style.
+> every session writes code in a slightly different style, and they declare
+> victory while the project checks are still red.
 >
-> **Sideroom fixes all four — without touching your repository.**
+> **Sideroom fixes all of it — without touching your repository.**
 
 Sideroom Pi is a global [Pi package](https://pi.dev/docs/latest/packages)
 that gives the parent agent a *side room* next to your code: a place to ask
@@ -29,6 +30,10 @@ Every long agent session drifts toward the same failure modes:
    and half-abandoned plans committed next to real code.
 4. **Style drift.** Each session reinvents conventions: nesting depth, error
    handling, naming, validation. Review becomes cleanup.
+5. **Unapplied guidelines.** The contract is read, then ignored: a braceless
+   `if`, a swallowed error, `console.log`, and `TODO` land in the diff anyway.
+6. **Premature completion.** The agent announces it is done while the
+   formatter, linter, type checks, or tests were never run.
 
 Sideroom answers each one with a small, opinionated surface:
 
@@ -39,6 +44,8 @@ Sideroom answers each one with a small, opinionated surface:
 | Repo pollution | Session-branch state — the board and history die with the session, never with a commit |
 | 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 |
+| Premature completion | `sideroom_done` — steers back to the project's check command before finishing |
 
 ## What it feels like
 
@@ -65,6 +72,14 @@ wall of tool calls, it:
   blocked. The guides cover guard clauses, braced conditionals, fail-fast
   errors, focused units, and all 19 canonical rules without dumping them into
   the system prompt.
+- **Cannot sneak sloppy lines past the gate.** Each write and edit is checked
+  against the mechanical rules on the added lines only: braceless
+  conditionals and swallowed errors block the mutation; vague names, stale
+  `TODO`s, commented-out code, and debug output are appended as notes to the
+  result. A rule that keeps firing degrades instead of trapping the agent.
+- **Does not call it done in red.** When files changed and the project's own
+  check command has not passed, the agent is steered back to run it before
+  finishing. If no check command is detectable, the gate stays out of the way.
 
 ## What's inside
 
@@ -119,6 +134,26 @@ Each guide mirrors all 19 rules in the canonical seed with idiomatic examples.
 The seed, `assets/artifacts/GUIDELINES_TEMPLATE.md`, is never pasted into the
 system prompt.
 
+### Rules — enforcement, not advice
+
+The guidelines gate makes the agent read the rules; `sideroom_rules` makes it
+follow them. On every `write`/`edit`, only the added lines are checked against
+the mechanical rules from the canonical seed. Braceless conditionals and
+swallowed errors block the mutation with an actionable reason; banned
+identifiers, stale comments, commented-out code, and debug artifacts are
+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.
+
+### Done — done means green
+
+`sideroom_done` detects the project's check command — `package.json` scripts
+(`check` → `test` → `lint` → `typecheck` → `types`) with the right
+package manager, `pytest`, `go test ./...`, `cargo test`, or a `make check`
+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.
+
 ## Quick path
 
 1. Install globally from npm. Pi records this in your user settings, so do
@@ -187,6 +222,27 @@ languages use the shared table. Do not route around
 the gate through Bash or another file-mutation path. Before finishing, review
 the diff against the loaded guide and run the relevant project checks.
 
+### Rules contract
+
+- Trigger: every `write`/`edit` call, in every mode.
+- Scope: only lines added by the call. For `edit`, each `oldText → newText`
+  pair; for `write`, the new content against the existing file.
+- Blocking rules: braced conditionals (rule 1) and explicit error handling
+  (rule 5). Warning rules: clear names (6), comments (19), and debug artifacts.
+- Blocked calls return the rule id, the reason, and the fix. Warnings are
+  appended to the tool result.
+- A rule that blocks three times in a run degrades to a warning until five
+  clean checks or a new interactive prompt reset it.
+
+### Done contract
+
+- Detected command: `package.json` scripts in priority order with the
+  lockfile's package manager, then `pytest -q` for Python, `go test ./...`,
+  `cargo test`, or `make check`. Detection is cached per working directory.
+- Green means that command ran with a zero exit in this run. A later
+  successful `write`/`edit` clears green again.
+- Steering: once per turn, at most twice per run, then it stops.
+
 ### Grill contract
 
 Load the skill at the start of a change with a fuzzy plan.

package/extensions/done/detect.ts

@@ -0,0 +1,128 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export interface CheckCommand {
+  readonly executable: string;
+  readonly args: readonly string[];
+  readonly display: string;
+}
+
+export const PACKAGE_MANAGER = {
+  npm: 'npm',
+  pnpm: 'pnpm',
+  yarn: 'yarn',
+  bun: 'bun',
+} as const;
+
+type PackageManager = (typeof PACKAGE_MANAGER)[keyof typeof PACKAGE_MANAGER];
+
+const SCRIPT_PRIORITY = [
+  'check',
+  'test',
+  'lint',
+  'typecheck',
+  'types',
+] as const;
+
+export function detectCheckCommand(cwd: string): CheckCommand | undefined {
+  const packageCommand = detectPackageCommand(cwd);
+  if (packageCommand !== undefined) {
+    return packageCommand;
+  }
+  if (
+    existsSync(join(cwd, 'pyproject.toml')) ||
+    existsSync(join(cwd, 'setup.py'))
+  ) {
+    return command('pytest', ['-q']);
+  }
+  if (existsSync(join(cwd, 'go.mod'))) {
+    return command('go', ['test', './...']);
+  }
+  if (existsSync(join(cwd, 'Cargo.toml'))) {
+    return command('cargo', ['test']);
+  }
+  if (hasMakeCheck(cwd)) {
+    return command('make', ['check']);
+  }
+  return undefined;
+}
+
+export function commandMatches(text: string, check: CheckCommand): boolean {
+  const normalized = collapseWhitespace(text.trim());
+  const target = collapseWhitespace(check.display);
+  if (normalized === target) {
+    return true;
+  }
+  return [' ', '&', '|', ';'].some((separator) =>
+    normalized.startsWith(`${target}${separator}`),
+  );
+}
+
+function detectPackageCommand(cwd: string): CheckCommand | undefined {
+  const packagePath = join(cwd, 'package.json');
+  if (!existsSync(packagePath)) {
+    return undefined;
+  }
+
+  const scripts = readScripts(packagePath);
+  const script = SCRIPT_PRIORITY.find(
+    (name) => typeof scripts[name] === 'string',
+  );
+  if (script === undefined) {
+    return undefined;
+  }
+
+  const manager = packageManager(cwd);
+  if (manager === PACKAGE_MANAGER.yarn) {
+    return command(PACKAGE_MANAGER.yarn, [script]);
+  }
+  return command(manager, ['run', script]);
+}
+
+function readScripts(path: string): Record<string, unknown> {
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as {
+      scripts?: Record<string, unknown>;
+    };
+    return parsed.scripts ?? {};
+  } catch (error) {
+    throw new Error(`Failed to read scripts from ${path}`, { cause: error });
+  }
+}
+
+function packageManager(cwd: string): PackageManager {
+  if (existsSync(join(cwd, 'pnpm-lock.yaml'))) {
+    return PACKAGE_MANAGER.pnpm;
+  }
+  if (existsSync(join(cwd, 'yarn.lock'))) {
+    return PACKAGE_MANAGER.yarn;
+  }
+  if (existsSync(join(cwd, 'bun.lockb')) || existsSync(join(cwd, 'bun.lock'))) {
+    return PACKAGE_MANAGER.bun;
+  }
+  return PACKAGE_MANAGER.npm;
+}
+
+function hasMakeCheck(cwd: string): boolean {
+  const path = join(cwd, 'Makefile');
+  if (!existsSync(path)) {
+    return false;
+  }
+  try {
+    return /^check:/m.test(readFileSync(path, 'utf8'));
+  } catch (error) {
+    throw new Error(`Failed to read ${path}`, { cause: error });
+  }
+}
+
+function command(executable: string, args: readonly string[]): CheckCommand {
+  return {
+    executable,
+    args,
+    display: [executable, ...args].join(' '),
+  };
+}
+
+function collapseWhitespace(value: string): string {
+  return value.replaceAll(/\s+/g, ' ');
+}

package/extensions/done/guard.ts

@@ -0,0 +1,77 @@
+import {
+  type ExtensionAPI,
+  type ExtensionContext,
+  isBashToolResult,
+  isEditToolResult,
+  isToolCallEventType,
+  isWriteToolResult,
+} from '@earendil-works/pi-coding-agent';
+import { type CheckCommand, commandMatches } from './detect.ts';
+import {
+  DONE_GATE_TYPE,
+  type DoneState,
+  formatDoneSteer,
+  shouldSteerDone,
+} from './model.ts';
+
+export type ResolveCommand = (
+  ctx: Pick<ExtensionContext, 'cwd'>,
+) => CheckCommand | undefined;
+
+export function registerDoneGuard(
+  pi: ExtensionAPI,
+  state: DoneState,
+  resolveCommand: ResolveCommand,
+): void {
+  const checkRuns = new Set<string>();
+
+  pi.on('turn_start', () => {
+    state.steeredThisTurn = false;
+  });
+
+  pi.on('tool_call', (event, ctx) => {
+    if (!isToolCallEventType('bash', event)) {
+      return;
+    }
+    const check = resolveCommand(ctx);
+    if (check === undefined) {
+      return;
+    }
+    if (commandMatches(event.input.command, check)) {
+      checkRuns.add(event.toolCallId);
+    }
+  });
+
+  pi.on('tool_result', (event) => {
+    if (isWriteToolResult(event) || isEditToolResult(event)) {
+      if (!event.isError) {
+        state.mutated = true;
+        state.checksGreen = false;
+      }
+      return;
+    }
+    if (isBashToolResult(event)) {
+      const wasCheck = checkRuns.delete(event.toolCallId);
+      if (wasCheck && !event.isError) {
+        state.checksGreen = true;
+      }
+    }
+  });
+
+  pi.on('turn_end', (_event, ctx) => {
+    const check = resolveCommand(ctx);
+    if (check === undefined || !shouldSteerDone(state, true)) {
+      return;
+    }
+    state.steeredThisTurn = true;
+    state.steerCount += 1;
+    pi.sendMessage(
+      {
+        customType: DONE_GATE_TYPE,
+        content: formatDoneSteer(check.display),
+        display: false,
+      },
+      { triggerTurn: true, deliverAs: 'steer' },
+    );
+  });
+}

package/extensions/done/index.ts

@@ -0,0 +1,35 @@
+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 { 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 resolveCommand: ResolveCommand = (
+    ctx: Pick<ExtensionContext, 'cwd'>,
+  ) => {
+    if (cache.has(ctx.cwd)) {
+      return cache.get(ctx.cwd);
+    }
+    const command = detectCheckCommand(ctx.cwd);
+    cache.set(ctx.cwd, command);
+    return command;
+  };
+
+  registerDoneGuard(pi, state, resolveCommand);
+
+  pi.on('input', (event) => {
+    if (event.source === 'interactive' || event.source === 'rpc') {
+      resetDoneRun(state);
+    }
+  });
+
+  pi.on('session_start', () => {
+    resetDoneRun(state);
+  });
+}

package/extensions/done/model.ts

@@ -0,0 +1,43 @@
+export interface DoneState {
+  mutated: boolean;
+  checksGreen: boolean;
+  steeredThisTurn: boolean;
+  steerCount: number;
+}
+
+export const MAX_DONE_STEERS = 2;
+
+export const DONE_GATE_TYPE = 'sideroom-done-gate';
+
+export function createDoneState(): DoneState {
+  return {
+    mutated: false,
+    checksGreen: false,
+    steeredThisTurn: false,
+    steerCount: 0,
+  };
+}
+
+export function resetDoneRun(state: DoneState): void {
+  state.mutated = false;
+  state.checksGreen = false;
+  state.steeredThisTurn = false;
+  state.steerCount = 0;
+}
+
+export function shouldSteerDone(
+  state: DoneState,
+  hasCommand: boolean,
+): boolean {
+  return (
+    hasCommand &&
+    state.mutated &&
+    !state.checksGreen &&
+    !state.steeredThisTurn &&
+    state.steerCount < MAX_DONE_STEERS
+  );
+}
+
+export function formatDoneSteer(display: string): string {
+  return `Run \`${display}\` and make it pass before finishing.`;
+}

package/extensions/guidelines/catalog.ts

@@ -0,0 +1,47 @@
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+const LANGUAGE_GUIDE_DIRECTORY = join(
+  PACKAGE_ROOT,
+  'skills/sideroom-guidelines/references/languages',
+);
+
+export const GUIDELINE_SKILL_PATH = join(
+  PACKAGE_ROOT,
+  'skills/sideroom-guidelines/SKILL.md',
+);
+
+export interface LanguageGuide {
+  readonly extensions: readonly string[];
+  readonly fileName: string;
+  readonly path: string;
+}
+
+export const LANGUAGE_GUIDES: readonly LanguageGuide[] = [
+  languageGuide('go.md', ['.go']),
+  languageGuide('java.md', ['.java']),
+  languageGuide('php-laravel.md', ['.php']),
+  languageGuide('python.md', ['.py']),
+  languageGuide('rust.md', ['.rs']),
+  languageGuide('typescript.md', ['.ts', '.tsx']),
+];
+
+export const LANGUAGE_GUIDE_FILES: readonly string[] = LANGUAGE_GUIDES.map(
+  ({ fileName }) => fileName,
+);
+
+export const LANGUAGE_TARGET_LABELS: readonly string[] = LANGUAGE_GUIDES.map(
+  ({ extensions }) => extensions.join('/'),
+);
+
+function languageGuide(
+  fileName: string,
+  extensions: readonly string[],
+): LanguageGuide {
+  return {
+    extensions,
+    fileName,
+    path: join(LANGUAGE_GUIDE_DIRECTORY, fileName),
+  };
+}

package/extensions/guidelines/guard.ts

@@ -1,29 +1,14 @@
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, normalize, resolve } from 'node:path';
 import {
   type ExtensionAPI,
   isReadToolResult,
   isToolCallEventType,
 } from '@earendil-works/pi-coding-agent';
+import { GUIDELINE_SKILL_PATH, LANGUAGE_GUIDES } from './catalog.ts';
 
-const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
-export const GUIDELINE_SKILL_PATH = join(
-  PACKAGE_ROOT,
-  'skills/sideroom-guidelines/SKILL.md',
-);
-const LANGUAGE_GUIDE_DIRECTORY = join(
-  PACKAGE_ROOT,
-  'skills/sideroom-guidelines/references/languages',
-);
-const LANGUAGE_GUIDE_BY_EXTENSION: Readonly<Record<string, string>> = {
-  '.go': join(LANGUAGE_GUIDE_DIRECTORY, 'go.md'),
-  '.java': join(LANGUAGE_GUIDE_DIRECTORY, 'java.md'),
-  '.php': join(LANGUAGE_GUIDE_DIRECTORY, 'php-laravel.md'),
-  '.py': join(LANGUAGE_GUIDE_DIRECTORY, 'python.md'),
-  '.rs': join(LANGUAGE_GUIDE_DIRECTORY, 'rust.md'),
-  '.ts': join(LANGUAGE_GUIDE_DIRECTORY, 'typescript.md'),
-  '.tsx': join(LANGUAGE_GUIDE_DIRECTORY, 'typescript.md'),
-};
+export { GUIDELINE_SKILL_PATH } from './catalog.ts';
 
 interface ReadInput {
   readonly path: string;
@@ -49,17 +34,21 @@ export function registerGuidelineGuard(
   pi: ExtensionAPI,
   state: GuidelineReadState,
 ): void {
-  pi.on('tool_result', (event) => {
+  pi.on('tool_result', (event, ctx) => {
     if (!isReadToolResult(event) || event.isError) {
       return;
     }
 
     // SAFETY: Pi validates built-in read arguments before emitting tool_result.
     const input = event.input as unknown as ReadInput;
-    if (input.offset !== undefined || input.limit !== undefined) {
+    if (
+      input.offset !== undefined ||
+      input.limit !== undefined ||
+      event.details?.truncation?.truncated === true
+    ) {
       return;
     }
-    recordGuidelineRead(state, input.path);
+    recordGuidelineRead(state, input.path, ctx.cwd);
   });
 
   pi.on('tool_call', (event) => {
@@ -70,7 +59,11 @@ export function registerGuidelineGuard(
       return;
     }
 
-    const reason = mutationBlockReason(state, event.input.path);
+    const reason = mutationBlockReason(
+      state,
+      event.input.path,
+      pi.getActiveTools().includes('read'),
+    );
     if (reason === undefined) {
       return;
     }
@@ -81,20 +74,21 @@ export function registerGuidelineGuard(
 export function recordGuidelineRead(
   state: GuidelineReadState,
   path: string | undefined,
+  cwd: string = process.cwd(),
 ): void {
   if (path === undefined) {
     return;
   }
 
-  const normalizedPath = normalizePath(path);
-  if (normalizedPath === normalizePath(GUIDELINE_SKILL_PATH)) {
+  const canonicalPath = canonicalizePath(path, cwd);
+  if (canonicalPath === canonicalCatalogPath(GUIDELINE_SKILL_PATH)) {
     state.skillRead = true;
     return;
   }
 
-  for (const guidePath of new Set(Object.values(LANGUAGE_GUIDE_BY_EXTENSION))) {
-    if (normalizedPath === normalizePath(guidePath)) {
-      state.languageGuidesRead.add(guidePath);
+  for (const guide of LANGUAGE_GUIDES) {
+    if (canonicalPath === canonicalCatalogPath(guide.path)) {
+      state.languageGuidesRead.add(guide.path);
       return;
     }
   }
@@ -103,6 +97,7 @@ export function recordGuidelineRead(
 export function mutationBlockReason(
   state: GuidelineReadState,
   targetPath: string,
+  readToolAvailable = true,
 ): string | undefined {
   const requiredPaths: string[] = [];
   if (!state.skillRead) {
@@ -117,20 +112,58 @@ export function mutationBlockReason(
   if (requiredPaths.length === 0) {
     return undefined;
   }
+  if (!readToolAvailable) {
+    return `Blocked ${targetPath}: the read tool is inactive, so the guidelines gate cannot be satisfied. Enable read, then read ${requiredPaths.join(' and ')} before retrying the mutation.`;
+  }
 
-  return `Blocked ${targetPath}: read ${requiredPaths.join(' and ')} with the read tool in this agent run, then retry the edit.`;
+  return `Blocked ${targetPath}: read ${requiredPaths.join(' and ')} with the read tool in this agent run, then retry the mutation.`;
 }
 
 function languageGuideFor(path: string): string | undefined {
-  const normalizedPath = normalizePath(path).toLowerCase();
-  const extension = Object.keys(LANGUAGE_GUIDE_BY_EXTENSION).find((candidate) =>
-    normalizedPath.endsWith(candidate),
-  );
-  return extension === undefined
-    ? undefined
-    : LANGUAGE_GUIDE_BY_EXTENSION[extension];
+  const normalizedPath = stripLeadingAt(path)
+    .replaceAll('\\', '/')
+    .toLowerCase();
+  return LANGUAGE_GUIDES.find(({ extensions }) =>
+    extensions.some((extension) => normalizedPath.endsWith(extension)),
+  )?.path;
+}
+
+const canonicalCatalogPaths = new Map<string, string>();
+
+function canonicalCatalogPath(path: string): string {
+  const cached = canonicalCatalogPaths.get(path);
+  if (cached !== undefined) {
+    return cached;
+  }
+  const canonical = realpathOr(path);
+  canonicalCatalogPaths.set(path, canonical);
+  return canonical;
+}
+
+function canonicalizePath(path: string, cwd: string): string {
+  const expanded = expandHome(stripLeadingAt(path));
+  const absolute = isAbsolute(expanded) ? expanded : resolve(cwd, expanded);
+  return realpathOr(normalize(absolute));
+}
+
+function realpathOr(path: string): string {
+  try {
+    return realpathSync.native(path);
+  } catch {
+    return path;
+  }
+}
+
+function expandHome(path: string): string {
+  if (path === '~') {
+    return homedir();
+  }
+  if (path.startsWith('~/') || path.startsWith('~\\')) {
+    return join(homedir(), path.slice(2));
+  }
+  return path;
 }
 
-function normalizePath(path: string): string {
-  return path.replace(/^@/, '').replaceAll('\\', '/');
+function stripLeadingAt(path: string): string {
+  return path.startsWith('@') ? path.slice(1) : path;
 }

package/extensions/guidelines/index.ts

@@ -19,4 +19,10 @@ export default function registerGuidelines(pi: ExtensionAPI): void {
     }
     return { systemPrompt };
   });
+
+  // Compaction may summarize the loaded guides out of context mid-run; force
+  // a fresh read instead of trusting a now-stale in-memory flag.
+  pi.on('session_compact', () => {
+    resetGuidelineReadState(readState);
+  });
 }

package/extensions/guidelines/prompt.ts

@@ -1,20 +1,20 @@
+import { GUIDELINE_SKILL_PATH, LANGUAGE_GUIDES } from './catalog.ts';
+
+export { LANGUAGE_GUIDE_FILES } from './catalog.ts';
+
 export const GUIDELINES_REMINDER_HEADING =
   'Sideroom coding guidelines (always-on reminder):';
 
-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 on the absolute SKILL.md path shown for sideroom-guidelines in Available Skills.
-For .java, .php, .ts/.tsx, .py, .go, or .rs targets, also fully read exactly the matching guide under that skill's references/languages/ directory.
-The extension blocks write/edit until those exact full-file reads succeed. Do not bypass the gate with bash or another mutation tool.
-Before finishing, review changed code against the loaded guide and run the relevant formatter, linter, type checks, and tests.`;
+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');
 
-export const LANGUAGE_GUIDE_FILES = [
-  'go.md',
-  'java.md',
-  'php-laravel.md',
-  'python.md',
-  'rust.md',
-  'typescript.md',
-] as const;
+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}
+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.`;
 
 export function appendGuidelinesReminder(systemPrompt: string): string {
   if (systemPrompt.includes(GUIDELINES_REMINDER_HEADING)) {

package/extensions/rules/catalog.ts

@@ -0,0 +1,71 @@
+export const LANGUAGE = {
+  typescript: 'typescript',
+  javascript: 'javascript',
+  go: 'go',
+  java: 'java',
+  php: 'php',
+  python: 'python',
+  rust: 'rust',
+  generic: 'generic',
+} as const;
+
+export const SEVERITY = {
+  block: 'block',
+  warn: 'warn',
+} as const;
+
+export type LanguageId = (typeof LANGUAGE)[keyof typeof LANGUAGE];
+
+export type RuleId =
+  | 'braced-conditionals'
+  | 'explicit-error-handling'
+  | 'clear-names'
+  | 'comments'
+  | 'debug-artifacts';
+
+export type RuleSeverity = (typeof SEVERITY)[keyof typeof SEVERITY];
+
+export const RULE_SEVERITY: Readonly<Record<RuleId, RuleSeverity>> = {
+  'braced-conditionals': SEVERITY.block,
+  'explicit-error-handling': SEVERITY.block,
+  'clear-names': SEVERITY.warn,
+  comments: SEVERITY.warn,
+  'debug-artifacts': SEVERITY.warn,
+};
+
+export function languageForPath(path: string): LanguageId {
+  const normalized = path.replaceAll('\\', '/').toLowerCase();
+  const separator = normalized.lastIndexOf('/');
+  const fileName = normalized.slice(separator + 1);
+  if (fileName.endsWith('.ts') || fileName.endsWith('.tsx')) {
+    return LANGUAGE.typescript;
+  }
+  if (
+    fileName.endsWith('.js') ||
+    fileName.endsWith('.jsx') ||
+    fileName.endsWith('.mjs') ||
+    fileName.endsWith('.cjs')
+  ) {
+    return LANGUAGE.javascript;
+  }
+  if (fileName.endsWith('.go')) {
+    return LANGUAGE.go;
+  }
+  if (fileName.endsWith('.java')) {
+    return LANGUAGE.java;
+  }
+  if (fileName.endsWith('.php')) {
+    return LANGUAGE.php;
+  }
+  if (fileName.endsWith('.py')) {
+    return LANGUAGE.python;
+  }
+  if (fileName.endsWith('.rs')) {
+    return LANGUAGE.rust;
+  }
+  return LANGUAGE.generic;
+}
+
+export function supportsBracedConditionals(language: LanguageId): boolean {
+  return language !== LANGUAGE.python && language !== LANGUAGE.generic;
+}

package/extensions/rules/checks.ts

@@ -0,0 +1,244 @@
+import {
+  LANGUAGE,
+  type LanguageId,
+  RULE_SEVERITY,
+  type RuleId,
+  supportsBracedConditionals,
+} from './catalog.ts';
+import type { AddedLine, RuleViolation } from './model.ts';
+
+const BANNED_ALTERNATION = 'data|info|temp|tmp|result|obj|val|x';
+
+const BRACED_IF = /\b(?:if|else\s+if|for|while)\s*\(.*\)\s*(?!\{)\S/;
+const BRACED_ELSE = /\belse\s+(?!if\b|\{)\S/;
+const PYTHON_INLINE_SUITE =
+  /^\s*(?:if|elif|else|for|while|with|try|except|finally|def|class)\b.*:\s*(?:return|pass|raise|break|continue|yield|assert|del|import|from|global|nonlocal|print|await|lambda)\b/;
+
+const EMPTY_CATCH =
+  /\bcatch\s*(?:\([^)]*\))?\s*\{\s*(?:(?:\/\/[^\n]*|\/\*[\s\S]*?\*\/)\s*)?\}/g;
+const SWALLOW_RETURN =
+  /\bcatch\s*(?:\([^)]*\))?\s*\{\s*return\s+(?:null|undefined|void\s+0)\s*;?\s*\}/g;
+const PYTHON_SWALLOW =
+  /^[ \t]*except\b[^:\n]*:[ \t]*(?:pass|\.\.\.)[ \t]*(?:#[^\n]*)?$/gm;
+const PYTHON_SWALLOW_BLOCK =
+  /^[ \t]*except\b[^:\n]*:[ \t]*\n[ \t]*(?:pass|\.\.\.)[ \t]*(?:#[^\n]*)?$/gm;
+
+const TODO_COMMENT = /(?:\/\/|#|\/\*)[^\n]*\b(?:TODO|FIXME|XXX|HACK)\b/;
+const COMMENTED_CODE =
+  /^\s*(?:\/\/|#)\s*(?:if|for|while|return|const|let|var|function|class|def|import|from|print|console|await|async)\b/;
+const CODE_LIKE_COMMENT = /^\s*(?:\/\/|#).*[;{}]\s*$/;
+
+const DEBUG_PATTERNS: readonly RegExp[] = [
+  /\bconsole\.(?:log|debug)\s*\(/,
+  /\bdebugger\b/,
+  /^\s*print\s*\(/,
+  /\bvar_dump\s*\(/,
+  /\bdd\s*\(/,
+  /\bdump\s*\(/,
+  /\bdbg!\s*\(/,
+];
+
+const FUNCTION_PARAMS: readonly RegExp[] = [
+  /\bfunction\s+\w*\s*\(([^()]*)\)/g,
+  /\bdef\s+\w+\s*\(([^()]*)\)/g,
+  /\bfn\s+\w+\s*\(([^()]*)\)/g,
+  /\(([^()]*)\)\s*=>/g,
+];
+
+export function evaluateAddedLines(
+  language: LanguageId,
+  lines: readonly AddedLine[],
+): RuleViolation[] {
+  const violations: RuleViolation[] = [];
+
+  for (const added of lines) {
+    if (supportsBracedConditionals(language)) {
+      collectBracedConditionals(added, violations);
+    } else if (language === LANGUAGE.python) {
+      collectPythonSuite(added, violations);
+    }
+    collectClearNames(added, violations);
+    collectComments(added, violations);
+    collectDebugArtifacts(added, violations);
+  }
+
+  collectErrorHandling(language, lines, violations);
+  return dedupe(violations);
+}
+
+function violation(
+  ruleId: RuleId,
+  message: string,
+  line: number,
+): RuleViolation {
+  return { ruleId, severity: RULE_SEVERITY[ruleId], message, line };
+}
+
+function collectBracedConditionals(
+  added: AddedLine,
+  violations: RuleViolation[],
+): void {
+  if (BRACED_IF.test(added.text) || BRACED_ELSE.test(added.text)) {
+    violations.push(
+      violation(
+        'braced-conditionals',
+        '[braced-conditionals] Wrap the conditional body in braces.',
+        added.line,
+      ),
+    );
+  }
+}
+
+function collectPythonSuite(
+  added: AddedLine,
+  violations: RuleViolation[],
+): void {
+  if (PYTHON_INLINE_SUITE.test(added.text)) {
+    violations.push(
+      violation(
+        'braced-conditionals',
+        '[braced-conditionals] Put the suite on its own indented line.',
+        added.line,
+      ),
+    );
+  }
+}
+
+function collectErrorHandling(
+  language: LanguageId,
+  lines: readonly AddedLine[],
+  violations: RuleViolation[],
+): void {
+  const joined = lines.map((added) => added.text).join('\n');
+  if (language === LANGUAGE.python) {
+    collectPattern(PYTHON_SWALLOW, joined, lines, violations);
+    collectPattern(PYTHON_SWALLOW_BLOCK, joined, lines, violations);
+    return;
+  }
+  if (language === LANGUAGE.generic) {
+    return;
+  }
+  collectPattern(EMPTY_CATCH, joined, lines, violations);
+  collectPattern(SWALLOW_RETURN, joined, lines, violations);
+}
+
+function collectPattern(
+  pattern: RegExp,
+  joined: string,
+  lines: readonly AddedLine[],
+  violations: RuleViolation[],
+): void {
+  const matcher = new RegExp(pattern.source, pattern.flags);
+  for (const match of joined.matchAll(matcher)) {
+    const offset = match.index ?? 0;
+    violations.push(
+      violation(
+        'explicit-error-handling',
+        '[explicit-error-handling] Do not swallow errors; rethrow with context or let them propagate.',
+        lineForOffset(joined, lines, offset),
+      ),
+    );
+  }
+}
+
+function collectClearNames(
+  added: AddedLine,
+  violations: RuleViolation[],
+): void {
+  const declaration = new RegExp(
+    `\\b(?:const|let|var|val|auto|final)\\s+(${BANNED_ALTERNATION})\\b`,
+  );
+  const assignment = new RegExp(`^\\s*(${BANNED_ALTERNATION})\\s*(?::=|=)`);
+  const match = declaration.exec(added.text) ?? assignment.exec(added.text);
+  if (match !== null) {
+    pushClearName(added.line, match[1], violations);
+    return;
+  }
+
+  for (const pattern of FUNCTION_PARAMS) {
+    const params = new RegExp(pattern.source, pattern.flags);
+    for (const paramMatch of added.text.matchAll(params)) {
+      const banned = new RegExp(`\\b(${BANNED_ALTERNATION})\\b`).exec(
+        paramMatch[1] ?? '',
+      );
+      if (banned !== null) {
+        pushClearName(added.line, banned[1], violations);
+        return;
+      }
+    }
+  }
+}
+
+function pushClearName(
+  line: number,
+  name: string | undefined,
+  violations: RuleViolation[],
+): void {
+  const label = name ?? 'identifier';
+  violations.push(
+    violation(
+      'clear-names',
+      `[clear-names] Rename '${label}' to a name that reveals its role.`,
+      line,
+    ),
+  );
+}
+
+function collectComments(added: AddedLine, violations: RuleViolation[]): void {
+  if (
+    TODO_COMMENT.test(added.text) ||
+    COMMENTED_CODE.test(added.text) ||
+    CODE_LIKE_COMMENT.test(added.text)
+  ) {
+    violations.push(
+      violation(
+        'comments',
+        '[comments] Remove stale TODO/FIXME or commented-out code; keep only non-obvious intent.',
+        added.line,
+      ),
+    );
+  }
+}
+
+function collectDebugArtifacts(
+  added: AddedLine,
+  violations: RuleViolation[],
+): void {
+  if (DEBUG_PATTERNS.some((pattern) => pattern.test(added.text))) {
+    violations.push(
+      violation(
+        'debug-artifacts',
+        '[debug-artifacts] Remove debug output before finishing.',
+        added.line,
+      ),
+    );
+  }
+}
+
+function lineForOffset(
+  joined: string,
+  lines: readonly AddedLine[],
+  offset: number,
+): number {
+  let lineIndex = 0;
+  for (let index = 0; index < offset; index += 1) {
+    if (joined.charCodeAt(index) === 10) {
+      lineIndex += 1;
+    }
+  }
+  return lines[lineIndex]?.line ?? lines.at(-1)?.line ?? 0;
+}
+
+function dedupe(violations: readonly RuleViolation[]): RuleViolation[] {
+  const seen = new Set<string>();
+  const deduped: RuleViolation[] = [];
+  for (const item of violations) {
+    const key = `${item.ruleId}:${String(item.line)}:${item.message}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    deduped.push(item);
+  }
+  return deduped;
+}

package/extensions/rules/guard.ts

@@ -0,0 +1,197 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import {
+  type ExtensionAPI,
+  isEditToolResult,
+  isToolCallEventType,
+  isWriteToolResult,
+  type ToolCallEvent,
+} from '@earendil-works/pi-coding-agent';
+import { languageForPath, type RuleId, SEVERITY } from './catalog.ts';
+import { evaluateAddedLines } from './checks.ts';
+import {
+  type AddedLine,
+  addedLines,
+  formatBlockReason,
+  formatWarnings,
+  type RuleViolation,
+} from './model.ts';
+
+const BLOCK_DEGRADE_AFTER = 3;
+const CLEAN_RESET_AFTER = 5;
+
+interface PendingWarnings {
+  readonly path: string;
+  readonly violations: readonly RuleViolation[];
+}
+
+export interface RulesState {
+  readonly fires: Map<RuleId, number>;
+  cleanChecks: number;
+  readonly pendingWarnings: Map<string, PendingWarnings>;
+}
+
+interface ExtractedMutation {
+  readonly path: string;
+  readonly language: ReturnType<typeof languageForPath>;
+  readonly lines: readonly AddedLine[];
+}
+
+export function createRulesState(): RulesState {
+  return { fires: new Map(), cleanChecks: 0, pendingWarnings: new Map() };
+}
+
+export function resetRulesState(state: RulesState): void {
+  state.fires.clear();
+  state.cleanChecks = 0;
+  state.pendingWarnings.clear();
+}
+
+export function registerRulesGuard(pi: ExtensionAPI, state: RulesState): void {
+  pi.on('tool_call', (event, ctx) => {
+    const mutation = extractMutation(event, ctx.cwd);
+    if (mutation === undefined) {
+      return undefined;
+    }
+    const violations = evaluateAddedLines(mutation.language, mutation.lines);
+    return applyRulesOutcome(
+      state,
+      event.toolCallId,
+      mutation.path,
+      decideRules(state, violations),
+    );
+  });
+
+  pi.on('tool_result', (event) => {
+    if (!isWriteToolResult(event) && !isEditToolResult(event)) {
+      return;
+    }
+    const pending = state.pendingWarnings.get(event.toolCallId);
+    state.pendingWarnings.delete(event.toolCallId);
+    if (pending === undefined || event.isError) {
+      return;
+    }
+    return {
+      content: [
+        ...event.content,
+        {
+          type: 'text' as const,
+          text: formatWarnings(pending.path, pending.violations),
+        },
+      ],
+    };
+  });
+}
+
+export interface RulesDecision {
+  readonly blocking: readonly RuleViolation[];
+  readonly warnings: readonly RuleViolation[];
+}
+
+export function decideRules(
+  state: RulesState,
+  violations: readonly RuleViolation[],
+): RulesDecision {
+  return {
+    blocking: violations.filter(
+      (item) =>
+        item.severity === SEVERITY.block && !isDegraded(state, item.ruleId),
+    ),
+    warnings: violations.filter(
+      (item) =>
+        item.severity === SEVERITY.warn || isDegraded(state, item.ruleId),
+    ),
+  };
+}
+
+function applyRulesOutcome(
+  state: RulesState,
+  toolCallId: string,
+  path: string,
+  decision: RulesDecision,
+): { block: true; reason: string } | undefined {
+  if (decision.blocking.length > 0) {
+    for (const item of decision.blocking) {
+      incrementFires(state, item.ruleId);
+    }
+    return { block: true, reason: formatBlockReason(path, decision.blocking) };
+  }
+
+  registerCleanCheck(state);
+  if (decision.warnings.length > 0) {
+    state.pendingWarnings.set(toolCallId, {
+      path,
+      violations: decision.warnings,
+    });
+  }
+  return undefined;
+}
+
+function extractMutation(
+  event: ToolCallEvent,
+  cwd: string,
+): ExtractedMutation | undefined {
+  if (isToolCallEventType('write', event)) {
+    return extractWrite(event.input.path, event.input.content, cwd);
+  }
+  if (isToolCallEventType('edit', event)) {
+    return extractEdit(event.input.path, event.input.edits);
+  }
+  return undefined;
+}
+
+function extractWrite(
+  path: string,
+  content: string,
+  cwd: string,
+): ExtractedMutation {
+  const previous = readFileIfExists(resolve(cwd, path));
+  return {
+    path,
+    language: languageForPath(path),
+    lines: addedLines(previous, content),
+  };
+}
+
+function extractEdit(
+  path: string,
+  edits: readonly { readonly oldText: string; readonly newText: string }[],
+): ExtractedMutation {
+  const lines: AddedLine[] = [];
+  for (const edit of edits) {
+    lines.push(...addedLines(edit.oldText, edit.newText));
+  }
+  return { path, language: languageForPath(path), lines };
+}
+
+function readFileIfExists(path: string): string | undefined {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch (error) {
+    if (isMissingFile(error)) {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+function isMissingFile(error: unknown): boolean {
+  return error instanceof Error && 'code' in error && error.code === 'ENOENT';
+}
+
+function isDegraded(state: RulesState, ruleId: RuleId): boolean {
+  return (state.fires.get(ruleId) ?? 0) >= BLOCK_DEGRADE_AFTER;
+}
+
+function incrementFires(state: RulesState, ruleId: RuleId): void {
+  state.fires.set(ruleId, (state.fires.get(ruleId) ?? 0) + 1);
+}
+
+function registerCleanCheck(state: RulesState): void {
+  state.cleanChecks += 1;
+  if (state.cleanChecks < CLEAN_RESET_AFTER) {
+    return;
+  }
+  state.cleanChecks = 0;
+  state.fires.clear();
+}

package/extensions/rules/index.ts

@@ -0,0 +1,22 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import {
+  createRulesState,
+  registerRulesGuard,
+  resetRulesState,
+} from './guard.ts';
+
+// Pi loads extensions/*/index.ts through export default.
+export default function registerRules(pi: ExtensionAPI): void {
+  const state = createRulesState();
+  registerRulesGuard(pi, state);
+
+  pi.on('input', (event) => {
+    if (event.source === 'interactive' || event.source === 'rpc') {
+      resetRulesState(state);
+    }
+  });
+
+  pi.on('session_compact', () => {
+    resetRulesState(state);
+  });
+}

package/extensions/rules/model.ts

@@ -0,0 +1,69 @@
+import type { RuleId, RuleSeverity } from './catalog.ts';
+
+export interface AddedLine {
+  readonly line: number;
+  readonly text: string;
+}
+
+export interface RuleViolation {
+  readonly ruleId: RuleId;
+  readonly severity: RuleSeverity;
+  readonly message: string;
+  readonly line: number;
+}
+
+export function addedLines(
+  previous: string | undefined,
+  next: string,
+): AddedLine[] {
+  const nextLines = next.split('\n');
+  const added: AddedLine[] = [];
+  const remaining = new Map<string, number>();
+
+  if (previous !== undefined) {
+    for (const text of previous.split('\n')) {
+      const key = text.trim();
+      if (key.length === 0) {
+        continue;
+      }
+      remaining.set(key, (remaining.get(key) ?? 0) + 1);
+    }
+  }
+
+  for (let index = 0; index < nextLines.length; index += 1) {
+    const text = nextLines[index] ?? '';
+    const key = text.trim();
+    if (key.length === 0) {
+      continue;
+    }
+    const count = remaining.get(key) ?? 0;
+    if (count > 0) {
+      remaining.set(key, count - 1);
+      continue;
+    }
+    added.push({ line: index + 1, text });
+  }
+
+  return added;
+}
+
+export function formatBlockReason(
+  path: string,
+  violations: readonly RuleViolation[],
+): string {
+  return [
+    `Blocked ${path}: sideroom rules violated.`,
+    ...violations.map((item) => `- ${item.message}`),
+    'Fix the flagged lines and retry the mutation.',
+  ].join('\n');
+}
+
+export function formatWarnings(
+  path: string,
+  violations: readonly RuleViolation[],
+): string {
+  return [
+    `Sideroom rules flagged ${path}:`,
+    ...violations.map((item) => `- ${item.message}`),
+  ].join('\n');
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rmrdeveloper/sideroom-pi",
-  "version": "8.0.1",
-  "description": "A global Pi package with a questionnaire, work board, edited-file view, and coding guidelines for parent agents.",
+  "version": "8.1.0",
+  "description": "A global Pi package with a questionnaire, work board, edited-file view, coding guidelines, rule enforcement, and a finish gate for parent agents.",
   "type": "module",
   "files": [
     "extensions",