@rmrdeveloper/sideroom-pi 8.1.0 → 8.1.1

package/README.md

@@ -250,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

@@ -7,6 +7,21 @@ export interface CheckCommand {
   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',
@@ -48,14 +63,98 @@ export function detectCheckCommand(cwd: string): CheckCommand | undefined {
 }
 
 export function commandMatches(text: string, check: CheckCommand): boolean {
-  const normalized = collapseWhitespace(text.trim());
   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 [' ', '&', '|', ';'].some((separator) =>
-    normalized.startsWith(`${target}${separator}`),
-  );
+  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 {

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

@@ -5,12 +5,12 @@ import {
   type RuleId,
   supportsBracedConditionals,
 } from './catalog.ts';
+import { maskNonCode } from './lexer.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 CONTROL_HEADER = /\b(?:if|else\s+if|for|while)\s*\(/g;
+const ELSE_KEYWORD = /\belse\b/g;
 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/;
 
@@ -50,19 +50,33 @@ export function evaluateAddedLines(
   lines: readonly AddedLine[],
 ): RuleViolation[] {
   const violations: RuleViolation[] = [];
+  const joined = lines.map((added) => added.text).join('\n');
+  const code = maskNonCode(joined, language);
+  const codeLines = code.split('\n');
+  const usesBracedConditionals = supportsBracedConditionals(language);
+
+  if (usesBracedConditionals) {
+    collectBracedConditionals(code, lines, violations);
+  }
 
-  for (const added of lines) {
-    if (supportsBracedConditionals(language)) {
-      collectBracedConditionals(added, violations);
-    } else if (language === LANGUAGE.python) {
-      collectPythonSuite(added, violations);
+  for (let index = 0; index < lines.length; index += 1) {
+    const added = lines[index];
+    if (added === undefined) {
+      continue;
+    }
+    const codeLine: AddedLine = {
+      line: added.line,
+      text: codeLines[index] ?? '',
+    };
+    if (language === LANGUAGE.python) {
+      collectPythonSuite(codeLine, violations);
     }
-    collectClearNames(added, violations);
+    collectClearNames(codeLine, violations);
     collectComments(added, violations);
-    collectDebugArtifacts(added, violations);
+    collectDebugArtifacts(codeLine, violations);
   }
 
-  collectErrorHandling(language, lines, violations);
+  collectErrorHandling(language, code, lines, violations);
   return dedupe(violations);
 }
 
@@ -75,15 +89,60 @@ function violation(
 }
 
 function collectBracedConditionals(
-  added: AddedLine,
+  code: string,
+  lines: readonly AddedLine[],
   violations: RuleViolation[],
 ): void {
-  if (BRACED_IF.test(added.text) || BRACED_ELSE.test(added.text)) {
+  const controlMatcher = new RegExp(
+    CONTROL_HEADER.source,
+    CONTROL_HEADER.flags,
+  );
+  const controlMatches = code.matchAll(controlMatcher);
+  for (const match of controlMatches) {
+    const matchOffset = match.index ?? 0;
+    const openingOffset = code.indexOf('(', matchOffset);
+    if (openingOffset < 0) {
+      continue;
+    }
+    const closingOffset = closingParenthesisOffset(code, openingOffset);
+    if (closingOffset === undefined) {
+      continue;
+    }
+    const bodyOffset = nextCodeOffset(code, closingOffset + 1);
+    if (bodyOffset === undefined) {
+      continue;
+    }
+    const hasBlockBody = code[bodyOffset] === '{';
+    if (hasBlockBody) {
+      continue;
+    }
     violations.push(
       violation(
         'braced-conditionals',
         '[braced-conditionals] Wrap the conditional body in braces.',
-        added.line,
+        lineForOffset(code, lines, matchOffset),
+      ),
+    );
+  }
+
+  const elseMatcher = new RegExp(ELSE_KEYWORD.source, ELSE_KEYWORD.flags);
+  const elseMatches = code.matchAll(elseMatcher);
+  for (const match of elseMatches) {
+    const matchOffset = match.index ?? 0;
+    const bodyOffset = nextCodeOffset(code, matchOffset + match[0].length);
+    if (bodyOffset === undefined) {
+      continue;
+    }
+    const hasBlockBody = code[bodyOffset] === '{';
+    const hasNestedIf = startsWithWord(code, bodyOffset, 'if');
+    if (hasBlockBody || hasNestedIf) {
+      continue;
+    }
+    violations.push(
+      violation(
+        'braced-conditionals',
+        '[braced-conditionals] Wrap the conditional body in braces.',
+        lineForOffset(code, lines, matchOffset),
       ),
     );
   }
@@ -106,20 +165,20 @@ function collectPythonSuite(
 
 function collectErrorHandling(
   language: LanguageId,
+  code: string,
   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);
+    collectPattern(PYTHON_SWALLOW, code, lines, violations);
+    collectPattern(PYTHON_SWALLOW_BLOCK, code, lines, violations);
     return;
   }
   if (language === LANGUAGE.generic) {
     return;
   }
-  collectPattern(EMPTY_CATCH, joined, lines, violations);
-  collectPattern(SWALLOW_RETURN, joined, lines, violations);
+  collectPattern(EMPTY_CATCH, code, lines, violations);
+  collectPattern(SWALLOW_RETURN, code, lines, violations);
 }
 
 function collectPattern(
@@ -215,6 +274,49 @@ function collectDebugArtifacts(
   }
 }
 
+function closingParenthesisOffset(
+  code: string,
+  openingOffset: number,
+): number | undefined {
+  let depth = 0;
+  for (let index = openingOffset; index < code.length; index += 1) {
+    const character = code[index];
+    if (character === '(') {
+      depth += 1;
+      continue;
+    }
+    if (character !== ')') {
+      continue;
+    }
+    depth -= 1;
+    if (depth === 0) {
+      return index;
+    }
+  }
+  return undefined;
+}
+
+function nextCodeOffset(code: string, offset: number): number | undefined {
+  for (let index = offset; index < code.length; index += 1) {
+    const character = code[index] ?? '';
+    const isWhitespace = /\s/.test(character);
+    if (!isWhitespace) {
+      return index;
+    }
+  }
+  return undefined;
+}
+
+function startsWithWord(code: string, offset: number, word: string): boolean {
+  const startsAtOffset = code.startsWith(word, offset);
+  if (!startsAtOffset) {
+    return false;
+  }
+  const following = code[offset + word.length] ?? '';
+  const isWordCharacter = /[A-Za-z0-9_$]/.test(following);
+  return following.length === 0 || !isWordCharacter;
+}
+
 function lineForOffset(
   joined: string,
   lines: readonly AddedLine[],

package/extensions/rules/lexer.ts

@@ -0,0 +1,136 @@
+import { LANGUAGE, type LanguageId } from './catalog.ts';
+
+const LEXICAL_MODE = {
+  code: 'code',
+  lineComment: 'line-comment',
+  blockComment: 'block-comment',
+  string: 'string',
+} as const;
+
+type LexicalMode = (typeof LEXICAL_MODE)[keyof typeof LEXICAL_MODE];
+
+export function maskNonCode(source: string, language: LanguageId): string {
+  const masked = [...source];
+  let mode: LexicalMode = LEXICAL_MODE.code;
+  let delimiter = '';
+
+  for (let index = 0; index < source.length; index += 1) {
+    const character = source[index] ?? '';
+
+    if (mode === LEXICAL_MODE.lineComment) {
+      if (character === '\n') {
+        mode = LEXICAL_MODE.code;
+        continue;
+      }
+      maskCharacter(masked, index);
+      continue;
+    }
+
+    if (mode === LEXICAL_MODE.blockComment) {
+      const closesComment = character === '*' && source[index + 1] === '/';
+      if (closesComment) {
+        maskCharacter(masked, index);
+        maskCharacter(masked, index + 1);
+        index += 1;
+        mode = LEXICAL_MODE.code;
+        continue;
+      }
+      maskCharacter(masked, index);
+      continue;
+    }
+
+    if (mode === LEXICAL_MODE.string) {
+      if (character === '\\') {
+        maskCharacter(masked, index);
+        if (source[index + 1] !== undefined) {
+          maskCharacter(masked, index + 1);
+          index += 1;
+        }
+        continue;
+      }
+      const closesString = source.startsWith(delimiter, index);
+      if (closesString) {
+        for (let offset = 0; offset < delimiter.length; offset += 1) {
+          maskCharacter(masked, index + offset);
+        }
+        index += delimiter.length - 1;
+        delimiter = '';
+        mode = LEXICAL_MODE.code;
+        continue;
+      }
+      if (delimiter.length === 1 && character === '\n') {
+        mode = LEXICAL_MODE.code;
+        continue;
+      }
+      maskCharacter(masked, index);
+      continue;
+    }
+
+    const startsLineComment = character === '/' && source[index + 1] === '/';
+    if (startsLineComment) {
+      maskCharacter(masked, index);
+      maskCharacter(masked, index + 1);
+      index += 1;
+      mode = LEXICAL_MODE.lineComment;
+      continue;
+    }
+
+    const startsBlockComment = character === '/' && source[index + 1] === '*';
+    if (startsBlockComment) {
+      maskCharacter(masked, index);
+      maskCharacter(masked, index + 1);
+      index += 1;
+      mode = LEXICAL_MODE.blockComment;
+      continue;
+    }
+
+    const startsHashComment =
+      character === '#' && supportsHashComments(language);
+    if (startsHashComment) {
+      maskCharacter(masked, index);
+      mode = LEXICAL_MODE.lineComment;
+      continue;
+    }
+
+    const startsString =
+      character === "'" || character === '"' || character === '`';
+    if (startsString) {
+      delimiter = stringDelimiter(source, index, language, character);
+      for (let offset = 0; offset < delimiter.length; offset += 1) {
+        maskCharacter(masked, index + offset);
+      }
+      index += delimiter.length - 1;
+      mode = LEXICAL_MODE.string;
+    }
+  }
+
+  return masked.join('');
+}
+
+function stringDelimiter(
+  source: string,
+  index: number,
+  language: LanguageId,
+  quote: string,
+): string {
+  const tripleQuote = `${quote}${quote}${quote}`;
+  const isPythonTripleQuote =
+    language === LANGUAGE.python && source.startsWith(tripleQuote, index);
+  if (isPythonTripleQuote) {
+    return tripleQuote;
+  }
+  return quote;
+}
+
+function supportsHashComments(language: LanguageId): boolean {
+  return language === LANGUAGE.python || language === LANGUAGE.php;
+}
+
+function maskCharacter(masked: string[], index: number): void {
+  const character = masked[index];
+  const shouldMask =
+    character !== undefined && character !== '\n' && character !== '\r';
+  if (shouldMask) {
+    masked[index] = ' ';
+  }
+}

package/extensions/rules/model.ts

@@ -17,36 +17,187 @@ export function addedLines(
   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);
-    }
+  if (previous === undefined) {
+    return nonBlankLines(nextLines);
   }
 
-  for (let index = 0; index < nextLines.length; index += 1) {
+  const previousLines = previous.split('\n');
+  const insertedIndices = insertedLineIndices(previousLines, nextLines);
+  const availableAdditions = additionCounts(previousLines, nextLines);
+  const added: AddedLine[] = [];
+  const orderedIndices = [...insertedIndices].sort(
+    (left, right) => left - right,
+  );
+
+  for (const index of orderedIndices) {
     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);
+    const count = availableAdditions.get(key) ?? 0;
+    if (count === 0) {
       continue;
     }
+    availableAdditions.set(key, count - 1);
     added.push({ line: index + 1, text });
   }
 
   return added;
 }
 
+function nonBlankLines(lines: readonly string[]): AddedLine[] {
+  const added: AddedLine[] = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const text = lines[index] ?? '';
+    const trimmedText = text.trim();
+    if (trimmedText.length === 0) {
+      continue;
+    }
+    added.push({ line: index + 1, text });
+  }
+  return added;
+}
+
+function insertedLineIndices(
+  previousLines: readonly string[],
+  nextLines: readonly string[],
+): number[] {
+  const previousKeys = previousLines.map((line) => line.trim());
+  const nextKeys = nextLines.map((line) => line.trim());
+  const trace: Map<number, number>[] = [];
+  const frontier = new Map<number, number>([[1, 0]]);
+  const maximumDistance = previousLines.length + nextLines.length;
+
+  for (let distance = 0; distance <= maximumDistance; distance += 1) {
+    for (let diagonal = -distance; diagonal <= distance; diagonal += 2) {
+      const down = frontier.get(diagonal + 1) ?? Number.NEGATIVE_INFINITY;
+      const right =
+        (frontier.get(diagonal - 1) ?? Number.NEGATIVE_INFINITY) + 1;
+      let previousIndex: number;
+      const shouldMoveDown =
+        diagonal === -distance || (diagonal !== distance && down > right);
+      if (shouldMoveDown) {
+        previousIndex = down;
+      } else {
+        previousIndex = right;
+      }
+      const hasFiniteIndex = Number.isFinite(previousIndex);
+      if (!hasFiniteIndex) {
+        previousIndex = 0;
+      }
+
+      let nextIndex = previousIndex - diagonal;
+      while (
+        previousIndex < previousKeys.length &&
+        nextIndex < nextKeys.length &&
+        previousKeys[previousIndex] === nextKeys[nextIndex]
+      ) {
+        previousIndex += 1;
+        nextIndex += 1;
+      }
+      frontier.set(diagonal, previousIndex);
+
+      if (
+        previousIndex >= previousKeys.length &&
+        nextIndex >= nextKeys.length
+      ) {
+        trace.push(new Map(frontier));
+        return backtrackInsertedIndices(
+          trace,
+          distance,
+          previousKeys,
+          nextKeys,
+        );
+      }
+    }
+    trace.push(new Map(frontier));
+  }
+
+  throw new Error('Failed to compute the line diff.');
+}
+
+function backtrackInsertedIndices(
+  trace: readonly Map<number, number>[],
+  distance: number,
+  previousKeys: readonly string[],
+  nextKeys: readonly string[],
+): number[] {
+  let previousIndex = previousKeys.length;
+  let nextIndex = nextKeys.length;
+  const insertedIndices: number[] = [];
+
+  for (
+    let currentDistance = distance;
+    currentDistance > 0;
+    currentDistance -= 1
+  ) {
+    const previousFrontier = trace[currentDistance - 1];
+    if (previousFrontier === undefined) {
+      throw new Error('Line diff trace is incomplete.');
+    }
+
+    const diagonal = previousIndex - nextIndex;
+    const down = previousFrontier.get(diagonal + 1) ?? Number.NEGATIVE_INFINITY;
+    const right =
+      (previousFrontier.get(diagonal - 1) ?? Number.NEGATIVE_INFINITY) + 1;
+    const shouldMoveDown =
+      diagonal === -currentDistance ||
+      (diagonal !== currentDistance && down > right);
+    const previousDiagonal = shouldMoveDown ? diagonal + 1 : diagonal - 1;
+    const previousOldIndex = previousFrontier.get(previousDiagonal);
+    if (previousOldIndex === undefined) {
+      throw new Error('Line diff trace has an invalid diagonal.');
+    }
+    const previousNextIndex = previousOldIndex - previousDiagonal;
+
+    while (
+      previousIndex > previousOldIndex &&
+      nextIndex > previousNextIndex &&
+      previousKeys[previousIndex - 1] === nextKeys[nextIndex - 1]
+    ) {
+      previousIndex -= 1;
+      nextIndex -= 1;
+    }
+
+    if (previousIndex === previousOldIndex) {
+      nextIndex -= 1;
+      insertedIndices.push(nextIndex);
+    } else {
+      previousIndex -= 1;
+    }
+  }
+
+  return insertedIndices;
+}
+
+function additionCounts(
+  previousLines: readonly string[],
+  nextLines: readonly string[],
+): Map<string, number> {
+  const previousCounts = countLineKeys(previousLines);
+  const nextCounts = countLineKeys(nextLines);
+  const additions = new Map<string, number>();
+
+  for (const [key, nextCount] of nextCounts) {
+    const previousCount = previousCounts.get(key) ?? 0;
+    additions.set(key, Math.max(nextCount - previousCount, 0));
+  }
+  return additions;
+}
+
+function countLineKeys(lines: readonly string[]): Map<string, number> {
+  const counts = new Map<string, number>();
+  for (const line of lines) {
+    const key = line.trim();
+    if (key.length === 0) {
+      continue;
+    }
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  return counts;
+}
+
 export function formatBlockReason(
   path: string,
   violations: readonly RuleViolation[],

package/extensions/todo/execute.ts

@@ -5,7 +5,7 @@ import {
   TODO_ACTION,
   type TodoAction,
   type TodoItem,
-  type TodoParams,
+  type TodoToolParameters,
   UI_UNAVAILABLE,
 } from './model.ts';
 
@@ -21,7 +21,7 @@ export interface TodoToolResult {
 }
 
 export function executeTodo(
-  params: TodoParams,
+  params: TodoToolParameters,
   ctx: Pick<ExtensionContext, 'mode'>,
   currentItems: readonly TodoItem[],
 ): TodoToolResult {

package/extensions/todo/index.ts

@@ -2,7 +2,11 @@ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { Text } from '@earendil-works/pi-tui';
 import { executeTodo, type TodoToolDetails } from './execute.ts';
 import { registerGuardEvents } from './guards.ts';
-import { prepareTodoArguments, TOOL_NAME, TodoParamsSchema } from './model.ts';
+import {
+  prepareTodoArguments,
+  TOOL_NAME,
+  TodoToolParametersSchema,
+} from './model.ts';
 import {
   type BoardLifecycle,
   commitBoard,
@@ -59,7 +63,7 @@ function registerTodoTool(
     description: TODO_DESCRIPTION,
     promptSnippet: TODO_PROMPT_SNIPPET,
     promptGuidelines: TODO_PROMPT_GUIDELINES,
-    parameters: TodoParamsSchema,
+    parameters: TodoToolParametersSchema,
     prepareArguments: prepareTodoArguments,
     executionMode: 'sequential',
     execute: async (_toolCallId, params, _signal, _onUpdate, ctx) => {

package/extensions/todo/model.ts

@@ -27,6 +27,11 @@ const TodoStatusSchema = Type.Union([
   Type.Literal(TODO_STATUS.cancelled),
 ]);
 
+const TodoActionSchema = Type.Union([
+  Type.Literal(TODO_ACTION.propose),
+  Type.Literal(TODO_ACTION.update),
+]);
+
 const TodoItemSchema = Type.Object({
   id: Type.String({ description: 'Stable identifier for this item' }),
   content: Type.String({ description: 'Short description of the work' }),
@@ -41,28 +46,53 @@ const TodoPatchSchema = Type.Object({
   ),
 });
 
+const TodoItemsField = Type.Array(TodoItemSchema, {
+  maxItems: MAX_TODO_ITEMS,
+  description: 'Replacement board for propose, with at most 20 items',
+});
+
+const TodoPatchesField = Type.Array(TodoPatchSchema, {
+  minItems: 1,
+  description: 'Patches to apply for update',
+});
+
 const ProposeParamsSchema = Type.Object({
   action: Type.Literal(TODO_ACTION.propose),
-  items: Type.Array(TodoItemSchema, {
-    maxItems: MAX_TODO_ITEMS,
-    description: 'Replacement board, with at most 20 items',
-  }),
+  items: TodoItemsField,
 });
 
 const UpdateParamsSchema = Type.Object({
   action: Type.Literal(TODO_ACTION.update),
-  patches: Type.Array(TodoPatchSchema, {
-    minItems: 1,
-    description: 'Patches to apply together',
-  }),
+  patches: TodoPatchesField,
 });
 
+/**
+ * Strict validator and types for sideroom_todo arguments. Kept as a
+ * discriminated union so invalid action/field combinations are rejected
+ * exactly. This schema is not registered with Pi; see
+ * TodoToolParametersSchema.
+ */
 export const TodoParamsSchema = Type.Union([
   ProposeParamsSchema,
   UpdateParamsSchema,
 ]);
 
+/**
+ * Tool-facing schema registered with Pi. It must stay a top-level object:
+ * Claude Code silently drops every tool of an MCP server when one tool's
+ * inputSchema has a non-object top level (anyOf/oneOf/allOf), which is exactly
+ * what TodoParamsSchema emits. The discriminated union is still enforced at
+ * runtime by parseTodoParams. See docs/extensions/todo.md ("Tool schema
+ * compatibility") for the bug references and the condition to revert.
+ */
+export const TodoToolParametersSchema = Type.Object({
+  action: TodoActionSchema,
+  items: Type.Optional(TodoItemsField),
+  patches: Type.Optional(TodoPatchesField),
+});
+
 export type TodoParams = Static<typeof TodoParamsSchema>;
+export type TodoToolParameters = Static<typeof TodoToolParametersSchema>;
 export type TodoAction = (typeof TODO_ACTION)[keyof typeof TODO_ACTION];
 export type TodoStatus = (typeof TODO_STATUS)[keyof typeof TODO_STATUS];
 
@@ -127,8 +157,8 @@ type JsonWireValue =
   | readonly JsonWireValue[]
   | JsonWireObject;
 
-export function prepareTodoArguments(args: unknown): TodoParams {
-  return decodeTodoWireArgs(args) as TodoParams;
+export function prepareTodoArguments(args: unknown): TodoToolParameters {
+  return decodeTodoWireArgs(args) as TodoToolParameters;
 }
 
 function decodeTodoWireArgs(args: unknown): JsonWireValue {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmrdeveloper/sideroom-pi",
-  "version": "8.1.0",
+  "version": "8.1.1",
   "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": [

package/skills/sideroom-guidelines/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sideroom-guidelines
-description: "Apply Sideroom's mandatory coding workflow before implementing, refactoring, or fixing Java, Laravel/PHP, TypeScript/TSX, Python, Go, or Rust code. Load this skill and the exact language guide before mutation. Do not use for unrelated prose or domain-only discussions."
+description: "Apply Sideroom's mandatory coding workflow before implementing, refactoring, or fixing Java, Laravel/PHP, JavaScript/JSX, TypeScript/TSX, Python, Go, or Rust code. Load this skill and the exact language guide before mutation. Do not use for unrelated prose or domain-only discussions."
 license: MIT
 metadata:
   author: RMRdeveloper
@@ -26,6 +26,7 @@ Load this whole skill with `read`, without `offset` or `limit`, before the first
 | Path | Read |
 | ------ | ------ |
 | `.java` | `references/languages/java.md` |
+| `.js` `.jsx` `.mjs` `.cjs` | `references/languages/javascript.md` |
 | `.php` | `references/languages/php-laravel.md` |
 | `.ts` `.tsx` | `references/languages/typescript.md` |
 | `.py` | `references/languages/python.md` |
@@ -74,6 +75,7 @@ Changed code follows every applicable rule in the loaded complete guide. The fin
 ## References
 
 - `references/languages/java.md`
+- `references/languages/javascript.md`
 - `references/languages/php-laravel.md`
 - `references/languages/typescript.md`
 - `references/languages/python.md`

package/skills/sideroom-guidelines/references/languages/javascript.md

@@ -0,0 +1,384 @@
+# JavaScript Coding Guidelines
+
+Rules every JavaScript change must follow.
+
+## Index
+
+| # | Rule | Tier |
+| --- | --- | --- |
+| 1 | [Braced conditionals](#1-braced-conditionals) | mechanical |
+| 2 | [No magic strings](#2-no-magic-strings) | mechanical |
+| 3 | [Guard clauses](#3-guard-clauses) | structural |
+| 4 | [Fail fast](#4-fail-fast) | structural |
+| 5 | [Explicit error handling](#5-explicit-error-handling) | structural |
+| 6 | [Clear names](#6-clear-names) | structural |
+| 7 | [Command Query Separation](#7-command-query-separation-cqs) | structural |
+| 8 | [Null/undefined handling](#8-nullundefined-handling) | structural |
+| 9 | [Immutability by default](#9-immutability-by-default) | structural |
+| 10 | [Validate once](#10-validate-once) | structural |
+| 11 | [Single Responsibility](#11-single-responsibility-srp) | architectural |
+| 12 | [DRY (real duplication only)](#12-dry-real-duplication-only) | architectural |
+| 13 | [KISS](#13-kiss) | architectural |
+| 14 | [YAGNI](#14-yagni) | architectural |
+| 15 | [Law of Demeter](#15-law-of-demeter) | architectural |
+| 16 | [Composition over inheritance](#16-composition-over-inheritance) | architectural |
+| 17 | [Dependency direction](#17-dependency-direction) | architectural |
+| 18 | [Testability](#18-testability-as-a-design-constraint) | architectural |
+| 19 | [Comments](#19-comments) | architectural |
+
+---
+
+### 1. Braced conditionals
+
+RULE: Every `if`/`else` body uses braces, even a one-line guard. Never bind a statement to a conditional by indentation alone.
+
+```js
+// bad
+if (!user) return 0;
+// good
+if (!user) {
+  return 0;
+}
+```
+
+### 2. No magic strings
+
+RULE: Name domain/protocol literals once (const, enum, shared contract) and reuse the name. One-off strings with no reuse and no domain meaning may stay inline.
+
+```js
+// bad
+if (order.status === 'pending_payment') {
+  charge(order);
+}
+// good
+const ORDER_STATUS = { PENDING_PAYMENT: 'pending_payment' };
+if (order.status === ORDER_STATUS.PENDING_PAYMENT) {
+  charge(order);
+}
+```
+
+### 3. Guard clauses
+
+RULE: Validate and exit early. Keep the happy path last, at the shallowest indent. No pyramid nesting.
+
+```js
+// bad
+function discount(user) {
+  if (user) {
+    if (user.active) {
+      return user.subscribed ? 0.2 : 0;
+    }
+  }
+  return 0;
+}
+// good
+function discount(user) {
+  if (!user || !user.active || !user.subscribed) {
+    return 0;
+  }
+  return 0.2;
+}
+```
+
+### 4. Fail fast
+
+RULE: Invalid input, impossible state, or a broken dependency throws immediately with a clear message. No fallback chains or silent defaults.
+WHY: This is for invariants that should never happen if upstream contracts hold — not license to re-check business rules a boundary already validated (see rule 10).
+
+```js
+// bad
+const zone = zones[order.zoneId] ?? zones.default;
+// good
+const zone = zones[order.zoneId];
+if (!zone) {
+  throw new Error(`Unknown zoneId: ${order.zoneId}`);
+}
+```
+
+### 5. Explicit error handling
+
+RULE: Never swallow an error in an empty or generic `catch`. Re-throw with context, or let it propagate.
+
+```js
+// bad
+async function loadUser(id) {
+  try {
+    return await api.getUser(id);
+  } catch (error) {
+    return null;
+  }
+}
+// good
+async function loadUser(id) {
+  try {
+    return await api.getUser(id);
+  } catch (error) {
+    throw new Error(`Failed to load user ${id}`, { cause: error });
+  }
+}
+```
+
+### 6. Clear names
+
+RULE: Names reveal role or domain meaning. No `data`, `info`, `temp`, `result`, `obj`, `val`, `x`. A long honest name beats a short vague one.
+
+```js
+// bad
+function process(data) {
+  return data.filter((x) => x.val > 0);
+}
+// good
+function getActiveSubscriptions(subscriptions) {
+  return subscriptions.filter(
+    (subscription) => subscription.remainingDays > 0,
+  );
+}
+```
+
+### 7. Command Query Separation (CQS)
+
+RULE: A function either does something (side effect) or returns something (query) — never both. A "getter" must never mutate.
+
+```js
+// bad
+function getNextId(counter) {
+  counter.value += 1;
+  return counter.value;
+}
+// good
+function peekNextId(counter) {
+  return counter.value + 1;
+}
+function incrementCounter(counter) {
+  counter.value += 1;
+}
+```
+
+### 8. Null/undefined handling
+
+RULE: Pick one convention (e.g. `undefined` = not set, `null` = explicitly empty) and never mix them for the same meaning. Never overload null to mean several business states — give each state its own explicit value.
+
+```js
+// bad
+function discount(user) {
+  if (!user) {
+    return null;
+  }
+  if (!user.plan) {
+    return null;
+  }
+  if (user.plan.discount === 0) {
+    return null;
+  }
+  return user.plan.discount;
+}
+// good
+function discount(user) {
+  if (!user?.plan) {
+    return 0;
+  }
+  return user.plan.discount;
+}
+```
+
+### 9. Immutability by default
+
+RULE: Return new values instead of mutating parameters. Never hide a side effect inside what looks like a pure transform.
+
+```js
+// bad
+function addItem(cart, item) {
+  cart.items.push(item);
+  return cart;
+}
+// good
+function addItem(cart, item) {
+  return { ...cart, items: [...cart.items, item] };
+}
+```
+
+### 10. Validate once
+
+RULE: Validate at the boundary that owns the input (schema, request DTO). Downstream code trusts that contract — no re-checking the same required/type/range rule further in.
+
+```js
+// bad
+function update(profile) {
+  if (!profile.email) {
+    throw new Error('email required');
+  }
+  repository.update(profile);
+}
+// good
+function update(validatedProfile) {
+  repository.update(validatedProfile);
+}
+```
+
+### 11. Single Responsibility (SRP)
+
+RULE: A function, class, or module has one reason to change. If it validates AND transforms AND persists AND notifies, split it.
+
+```js
+// bad
+async function saveUser(data) {
+  if (!data.email) {
+    throw new Error('email required');
+  }
+  const normalized = { ...data, email: data.email.trim().toLowerCase() };
+  await db.users.insert(normalized);
+  await mailer.send(normalized.email, 'welcome');
+}
+// good
+function validateUser(userInput) {
+  if (!userInput.email) {
+    throw new Error('email required');
+  }
+}
+function normalizeUser(userInput) {
+  return { ...userInput, email: userInput.email.trim().toLowerCase() };
+}
+async function createUser(userInput) {
+  validateUser(userInput);
+  const normalizedUser = normalizeUser(userInput);
+  await db.users.insert(normalizedUser);
+  await notifyWelcome(normalizedUser.email);
+  return normalizedUser;
+}
+```
+
+### 12. DRY (real duplication only)
+
+RULE: Extract when at least 2 of 3 hold: (a) the logic appears 3+ times, (b) a future rule change would need to touch all occurrences at once, (c) the copies represent the same domain concept. Do not extract on the first or second occurrence, or extract look-alike code from different concepts.
+
+```js
+// bad — extracted after one use
+function formatName(value) {
+  return value.trim().toUpperCase();
+}
+// good — the third occurrence confirms one domain concept
+function normalizeTicketStatus(status) {
+  return status.trim().toLowerCase();
+}
+```
+
+### 13. KISS
+
+RULE: Ship the simplest solution for the current, real requirement. No configurability, hooks, or layers added "just in case."
+
+```js
+// bad
+function formatPrice(value, options = defaults) {
+  return formatter.format(value, options);
+}
+// good
+function formatPrice(value) {
+  return `$${value.toFixed(2)}`;
+}
+```
+
+### 14. YAGNI
+
+RULE: Don't add fields, params, or branches for a use case that hasn't arrived. (KISS simplifies the chosen solution; YAGNI stops you building the unrequested one.)
+
+```js
+// bad
+function createInvoice(order, recurring = false, multiCurrency = false) {
+  return build(order, recurring, multiCurrency);
+}
+// good
+function createInvoice(order) {
+  return { total: order.total, items: order.items };
+}
+```
+
+### 15. Law of Demeter
+
+RULE: Talk only to immediate collaborators. Never reach through an object to grab something several levels deep inside its internal structure.
+
+```js
+// bad
+function getCityName(user) {
+  return user.address.city.name;
+}
+// good
+function getCityName(user) {
+  return user.getCityName();
+}
+```
+
+### 16. Composition over inheritance
+
+RULE: Compose small, focused behaviors instead of building inheritance chains that force unrelated methods onto every subclass.
+
+```js
+// bad
+class Animal {
+  makeSound() {}
+  fly() {}
+}
+class Dog extends Animal {
+  makeSound() {
+    return 'Woof';
+  }
+}
+// good
+const canBark = { makeSound: () => 'Woof' };
+const canFly = { fly: () => 'Flying' };
+const dog = { ...canBark };
+const bird = { ...canBark, ...canFly };
+```
+
+### 17. Dependency direction
+
+RULE: Inner layers (domain/business logic) never import outer layers (framework, DB, HTTP). Outer layers depend inward, never the reverse.
+
+```js
+// bad
+import { MysqlConnection } from '../infra/mysql';
+function calculateInvoiceTotal(invoiceId) {
+  const invoice = new MysqlConnection().query(
+    'SELECT * FROM invoices WHERE id = ?',
+    [invoiceId],
+  );
+  return invoice.items.reduce((sum, item) => sum + item.price, 0);
+}
+// good
+function calculateInvoiceTotal(invoice) {
+  return invoice.items.reduce((sum, item) => sum + item.price, 0);
+}
+```
+
+### 18. Testability as a design constraint
+
+RULE: Inject dependencies (clock, network, random) instead of hardcoding them. If a function is hard to test, redesign it — don't skip the test.
+
+```js
+// bad
+function isSubscriptionExpired(subscription) {
+  return subscription.expiresAt < new Date();
+}
+// good
+function isSubscriptionExpired(subscription, now = new Date()) {
+  return subscription.expiresAt < now;
+}
+```
+
+### 19. Comments
+
+RULE: Comment only non-obvious intent — a trade-off, a constraint, a hazard names can't carry. Delete narration, restated logic, and stale TODOs. Test: if deleting the comment leaves the code equally clear, delete it.
+
+```js
+// bad
+// increment the counter by 1
+counter++;
+// good
+// Poll because the provider cannot guarantee single webhook delivery.
+setInterval(checkPaymentStatus, 5_000);
+```
+
+---
+
+**When in doubt:** fail fast, keep it flat, keep it small.
+
+**Enforcement note:** rules 1–2 are mechanical and should be backed by a JavaScript formatter/linter. Rules 3–10 are structural checks. Rules 11–19 require review judgment.