@rmrdeveloper/sideroom-pi 8.0.2 → 8.1.1

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.
@@ -194,6 +250,12 @@ Single-session scope only. Files are created lazily: nothing exists until
 the first term or decision crystallises. A session with a sharper glossary
 and zero ADRs is working as designed.
 
+## Documentation
+
+Maintainer reference lives in [`docs/`](docs/README.md): the
+[architecture](docs/architecture.md) and one page per
+[extension](docs/extensions/ask.md).
+
 ## License
 
 MIT.

package/extensions/done/detect.ts

@@ -0,0 +1,227 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export interface CheckCommand {
+  readonly executable: string;
+  readonly args: readonly string[];
+  readonly display: string;
+}
+
+const SHELL_OPERATOR = {
+  and: '&&',
+  or: '||',
+  pipe: '|',
+  sequence: ';',
+  background: '&',
+} as const;
+
+type ShellOperator = (typeof SHELL_OPERATOR)[keyof typeof SHELL_OPERATOR];
+
+interface ShellSegment {
+  readonly text: string;
+  readonly operatorBefore: ShellOperator | undefined;
+}
+
+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 target = collapseWhitespace(check.display);
+  const segments = splitShellCommand(text);
+  const hasUnsafeOperator = segments.some(
+    ({ operatorBefore }) =>
+      operatorBefore !== undefined && operatorBefore !== SHELL_OPERATOR.and,
+  );
+  if (hasUnsafeOperator) {
+    return false;
+  }
+
+  return segments.some(({ text: segmentText }) =>
+    simpleCommandMatches(segmentText, target),
+  );
+}
+
+function simpleCommandMatches(text: string, target: string): boolean {
+  const normalized = collapseWhitespace(text.trim());
+  if (normalized === target) {
+    return true;
+  }
+  return normalized.startsWith(`${target} `);
+}
+
+function splitShellCommand(commandText: string): ShellSegment[] {
+  const segments: ShellSegment[] = [];
+  let segmentStart = 0;
+  let operatorBefore: ShellOperator | undefined;
+  let quote = '';
+
+  for (let index = 0; index < commandText.length; index += 1) {
+    const character = commandText[index] ?? '';
+    if (quote.length > 0) {
+      if (character === '\\' && quote === '"') {
+        index += 1;
+        continue;
+      }
+      if (character === quote) {
+        quote = '';
+      }
+      continue;
+    }
+
+    const startsQuote =
+      character === "'" || character === '"' || character === '`';
+    if (startsQuote) {
+      quote = character;
+      continue;
+    }
+
+    const operator = shellOperatorAt(commandText, index);
+    if (operator === undefined) {
+      continue;
+    }
+    segments.push({
+      text: commandText.slice(segmentStart, index),
+      operatorBefore,
+    });
+    operatorBefore = operator;
+    index += operator.length - 1;
+    segmentStart = index + 1;
+  }
+
+  segments.push({
+    text: commandText.slice(segmentStart),
+    operatorBefore,
+  });
+  return segments;
+}
+
+function shellOperatorAt(
+  commandText: string,
+  index: number,
+): ShellOperator | undefined {
+  const twoCharacterOperator = commandText.slice(index, index + 2);
+  if (twoCharacterOperator === SHELL_OPERATOR.and) {
+    return SHELL_OPERATOR.and;
+  }
+  if (twoCharacterOperator === SHELL_OPERATOR.or) {
+    return SHELL_OPERATOR.or;
+  }
+
+  const character = commandText[index];
+  if (character === SHELL_OPERATOR.pipe) {
+    return SHELL_OPERATOR.pipe;
+  }
+  if (character === SHELL_OPERATOR.sequence) {
+    return SHELL_OPERATOR.sequence;
+  }
+  if (character === SHELL_OPERATOR.background) {
+    return SHELL_OPERATOR.background;
+  }
+  return undefined;
+}
+
+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

@@ -21,6 +21,7 @@ export interface LanguageGuide {
 export const LANGUAGE_GUIDES: readonly LanguageGuide[] = [
   languageGuide('go.md', ['.go']),
   languageGuide('java.md', ['.java']),
+  languageGuide('javascript.md', ['.js', '.jsx', '.mjs', '.cjs']),
   languageGuide('php-laravel.md', ['.php']),
   languageGuide('python.md', ['.py']),
   languageGuide('rust.md', ['.rs']),

package/extensions/guidelines/guard.ts

@@ -1,3 +1,6 @@
+import { realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, normalize, resolve } from 'node:path';
 import {
   type ExtensionAPI,
   isReadToolResult,
@@ -31,7 +34,7 @@ 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;
     }
@@ -45,7 +48,7 @@ export function registerGuidelineGuard(
     ) {
       return;
     }
-    recordGuidelineRead(state, input.path);
+    recordGuidelineRead(state, input.path, ctx.cwd);
   });
 
   pi.on('tool_call', (event) => {
@@ -71,19 +74,20 @@ 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 guide of LANGUAGE_GUIDES) {
-    if (normalizedPath === normalizePath(guide.path)) {
+    if (canonicalPath === canonicalCatalogPath(guide.path)) {
       state.languageGuidesRead.add(guide.path);
       return;
     }
@@ -116,12 +120,50 @@ export function mutationBlockReason(
 }
 
 function languageGuideFor(path: string): string | undefined {
-  const normalizedPath = normalizePath(path).toLowerCase();
+  const normalizedPath = stripLeadingAt(path)
+    .replaceAll('\\', '/')
+    .toLowerCase();
   return LANGUAGE_GUIDES.find(({ extensions }) =>
     extensions.some((extension) => normalizedPath.endsWith(extension)),
   )?.path;
 }
 
-function normalizePath(path: string): string {
-  return path.replace(/^@/, '').replaceAll('\\', '/');
+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 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/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;
+}