@rmrdeveloper/sideroom-pi 7.1.0 → 8.0.0

package/extensions/ask/model.ts

@@ -9,9 +9,17 @@ export const CUSTOM_LABEL = 'Write a custom answer';
 export const UI_UNAVAILABLE =
   'Error: UI not available (running in non-interactive mode)';
 
+const MAX_QUESTIONS = 4;
+const MAX_OPTIONS = 4;
+const MAX_TAB_LABEL_LENGTH = 16;
+const MAX_OPTION_LABEL_LENGTH = 60;
+
 const QuestionOptionSchema = Type.Object({
   value: Type.String({ description: 'The value returned when selected' }),
-  label: Type.String({ description: 'Display label for the option' }),
+  label: Type.String({
+    maxLength: MAX_OPTION_LABEL_LENGTH,
+    description: `Display label for the option, with at most ${String(MAX_OPTION_LABEL_LENGTH)} characters`,
+  }),
   description: Type.Optional(
     Type.String({ description: 'Optional description shown below the label' }),
   ),
@@ -21,14 +29,15 @@ const QuestionSchema = Type.Object({
   id: Type.String({ description: 'Unique identifier for this question' }),
   label: Type.Optional(
     Type.String({
-      description:
-        "Short contextual label for the tab bar, e.g. 'Scope' (defaults to Q1, Q2)",
+      maxLength: MAX_TAB_LABEL_LENGTH,
+      description: `Short contextual label of at most ${String(MAX_TAB_LABEL_LENGTH)} characters for the tab bar, e.g. 'Scope' (defaults to Q1, Q2)`,
     }),
   ),
   prompt: Type.String({ description: 'The full question text to display' }),
   options: Type.Array(QuestionOptionSchema, {
     minItems: 2,
-    description: 'At least two mutually exclusive options',
+    maxItems: MAX_OPTIONS,
+    description: `Two to ${String(MAX_OPTIONS)} mutually exclusive options`,
   }),
   recommendationIndex: Type.Integer({
     minimum: 0,
@@ -39,7 +48,8 @@ const QuestionSchema = Type.Object({
 export const AskParamsSchema = Type.Object({
   questions: Type.Array(QuestionSchema, {
     minItems: 1,
-    description: 'Questions to ask the user in this batch',
+    maxItems: MAX_QUESTIONS,
+    description: `One to ${String(MAX_QUESTIONS)} questions to ask the user in this batch`,
   }),
 });
 
@@ -270,23 +280,58 @@ function schemaErrorMessage(value: unknown): string {
   if (error === undefined) {
     return 'Error: Invalid sideroom_ask parameters';
   }
-  if (error.keyword === 'minItems' && error.instancePath === '/questions') {
-    return 'Error: No questions provided';
+  if (error.instancePath === '/questions') {
+    if (error.keyword === 'minItems') {
+      return 'Error: No questions provided';
+    }
+    if (error.keyword === 'maxItems') {
+      return `Error: A questionnaire batch may include at most ${String(MAX_QUESTIONS)} questions`;
+    }
   }
+
+  const questions = asQuestions(value);
   const optionsMatch = /\/questions\/(\d+)\/options$/.exec(error.instancePath);
-  if (error.keyword === 'minItems' && optionsMatch !== null) {
+  if (optionsMatch !== null) {
     const questionIndex = Number(optionsMatch[1]);
-    const questions = asQuestions(value);
-    const question = questions[questionIndex];
-    const id =
-      question !== undefined && typeof question.id === 'string'
-        ? question.id
-        : String(questionIndex);
-    return `Error: Question '${id}' must include at least two options`;
+    const id = questionId(questions, questionIndex);
+    if (error.keyword === 'minItems') {
+      return `Error: Question '${id}' must include at least two options`;
+    }
+    if (error.keyword === 'maxItems') {
+      return `Error: Question '${id}' may include at most ${String(MAX_OPTIONS)} options`;
+    }
   }
+
+  const tabLabelMatch = /\/questions\/(\d+)\/label$/.exec(error.instancePath);
+  if (error.keyword === 'maxLength' && tabLabelMatch !== null) {
+    const questionIndex = Number(tabLabelMatch[1]);
+    const id = questionId(questions, questionIndex);
+    return `Error: Question '${id}' label may contain at most ${String(MAX_TAB_LABEL_LENGTH)} characters`;
+  }
+
+  const optionLabelMatch = /\/questions\/(\d+)\/options\/(\d+)\/label$/.exec(
+    error.instancePath,
+  );
+  if (error.keyword === 'maxLength' && optionLabelMatch !== null) {
+    const questionIndex = Number(optionLabelMatch[1]);
+    const optionIndex = Number(optionLabelMatch[2]);
+    const id = questionId(questions, questionIndex);
+    return `Error: Option ${String(optionIndex + 1)} for question '${id}' may contain at most ${String(MAX_OPTION_LABEL_LENGTH)} characters`;
+  }
+
   return `Error: Invalid sideroom_ask parameters`;
 }
 
+function questionId(
+  questions: readonly Record<string, unknown>[],
+  index: number,
+): string {
+  const question = questions[index];
+  return question !== undefined && typeof question.id === 'string'
+    ? question.id
+    : String(index);
+}
+
 function asQuestions(value: unknown): readonly Record<string, unknown>[] {
   if (typeof value !== 'object' || value === null) {
     return [];

package/extensions/guidelines/guard.ts

@@ -0,0 +1,136 @@
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  type ExtensionAPI,
+  isReadToolResult,
+  isToolCallEventType,
+} from '@earendil-works/pi-coding-agent';
+
+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'),
+};
+
+interface ReadInput {
+  readonly path: string;
+  readonly offset?: number;
+  readonly limit?: number;
+}
+
+export interface GuidelineReadState {
+  skillRead: boolean;
+  readonly languageGuidesRead: Set<string>;
+}
+
+export function createGuidelineReadState(): GuidelineReadState {
+  return { skillRead: false, languageGuidesRead: new Set() };
+}
+
+export function resetGuidelineReadState(state: GuidelineReadState): void {
+  state.skillRead = false;
+  state.languageGuidesRead.clear();
+}
+
+export function registerGuidelineGuard(
+  pi: ExtensionAPI,
+  state: GuidelineReadState,
+): void {
+  pi.on('tool_result', (event) => {
+    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) {
+      return;
+    }
+    recordGuidelineRead(state, input.path);
+  });
+
+  pi.on('tool_call', (event) => {
+    if (
+      !isToolCallEventType('edit', event) &&
+      !isToolCallEventType('write', event)
+    ) {
+      return;
+    }
+
+    const reason = mutationBlockReason(state, event.input.path);
+    if (reason === undefined) {
+      return;
+    }
+    return { block: true, reason };
+  });
+}
+
+export function recordGuidelineRead(
+  state: GuidelineReadState,
+  path: string | undefined,
+): void {
+  if (path === undefined) {
+    return;
+  }
+
+  const normalizedPath = normalizePath(path);
+  if (normalizedPath === normalizePath(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);
+      return;
+    }
+  }
+}
+
+export function mutationBlockReason(
+  state: GuidelineReadState,
+  targetPath: string,
+): string | undefined {
+  const requiredPaths: string[] = [];
+  if (!state.skillRead) {
+    requiredPaths.push(GUIDELINE_SKILL_PATH);
+  }
+
+  const guidePath = languageGuideFor(targetPath);
+  if (guidePath !== undefined && !state.languageGuidesRead.has(guidePath)) {
+    requiredPaths.push(guidePath);
+  }
+
+  if (requiredPaths.length === 0) {
+    return undefined;
+  }
+
+  return `Blocked ${targetPath}: read ${requiredPaths.join(' and ')} with the read tool in this agent run, then retry the edit.`;
+}
+
+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];
+}
+
+function normalizePath(path: string): string {
+  return path.replace(/^@/, '').replaceAll('\\', '/');
+}

package/extensions/guidelines/index.ts

@@ -1,9 +1,18 @@
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import {
+  createGuidelineReadState,
+  registerGuidelineGuard,
+  resetGuidelineReadState,
+} from './guard.ts';
 import { appendGuidelinesReminder } from './prompt.ts';
 
 // Pi loads extensions/*/index.ts through export default.
 export default function registerGuidelines(pi: ExtensionAPI): void {
+  const readState = createGuidelineReadState();
+  registerGuidelineGuard(pi, readState);
+
   pi.on('before_agent_start', (event) => {
+    resetGuidelineReadState(readState);
     const systemPrompt = appendGuidelinesReminder(event.systemPrompt);
     if (systemPrompt === event.systemPrompt) {
       return;

package/extensions/guidelines/prompt.ts

@@ -2,11 +2,12 @@ export const GUIDELINES_REMINDER_HEADING =
   'Sideroom coding guidelines (always-on reminder):';
 
 export const GUIDELINES_REMINDER = `${GUIDELINES_REMINDER_HEADING}
-Before write or edit, read the sideroom-guidelines skill.
-Apply its Do/Don't table. If the path is .java, .php, .ts/.tsx, .py, .go, or .rs, also read that language file under the skill's references/languages/.
-Do not load other language files.`;
+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.`;
 
-export const LANGUAGE_DELTA_FILES = [
+export const LANGUAGE_GUIDE_FILES = [
   'go.md',
   'java.md',
   'php-laravel.md',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmrdeveloper/sideroom-pi",
-  "version": "7.1.0",
+  "version": "8.0.0",
   "description": "A global Pi package with a questionnaire, work board, edited-file view, and coding guidelines for parent agents.",
   "type": "module",
   "files": [

package/skills/sideroom-guidelines/SKILL.md

@@ -11,18 +11,20 @@ metadata:
 
 ## Activation Contract
 
-Load this skill before `write` or `edit`. Load at most one file from `references/languages/` for the path being changed.
+Load this whole skill with `read`, without `offset` or `limit`, before the first `write` or `edit` in each agent run. Use the absolute skill path shown in Available Skills. For each supported target language, also fully load its exact guide from `references/languages/`.
 
 ## Hard Rules
 
-- Follow the Do/Don't table. Language files override syntax and framework idiom only.
-- Do not load language files you are not editing this turn.
+- Treat every rule in the loaded language guide as mandatory for changed code.
+- Do not write or edit until exact full-file reads of the required packaged paths succeed; partial reads and same-named files do not count.
+- Do not bypass the gate with Bash, a subprocess, or another mutation tool.
+- Do not load language guides unrelated to files being changed.
 - Fail fast, keep control flow flat, and validate once at the boundary.
 
 ## Decision Gates
 
 | Path | Read |
-|------|------|
+| ------ | ------ |
 | `.java` | `references/languages/java.md` |
 | `.php` | `references/languages/php-laravel.md` |
 | `.ts` `.tsx` | `references/languages/typescript.md` |
@@ -33,9 +35,11 @@ Load this skill before `write` or `edit`. Load at most one file from `references
 
 ## Execution Steps
 
-1. Apply the table to the change.
-2. Read the matching language file, if any.
-3. Ship the smallest change that satisfies the current requirement.
+1. Read this complete file from its packaged path before any mutation.
+2. Fully read the matching packaged language guide, if the target has a supported extension.
+3. Implement the smallest change that satisfies the current requirement.
+4. Review every changed unit against the loaded guide.
+5. Run the relevant formatter, linter, type checks, and tests before finishing.
 
 ## Do / Don't
 
@@ -65,7 +69,7 @@ Load this skill before `write` or `edit`. Load at most one file from `references
 
 ## Output Contract
 
-Changed code follows the table and the loaded language delta. No extra files, layers, or comments unless the change requires them.
+Changed code follows every applicable rule in the loaded complete guide. The final response names the validation run and any check that could not run. No extra files, layers, comments, or bypass mutations unless the requirement needs them.
 
 ## References