@rmrdeveloper/sideroom-pi 8.0.0 → 8.0.2

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,11 @@
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
 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;
@@ -56,7 +38,11 @@ export function registerGuidelineGuard(
 
     // 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);
@@ -70,7 +56,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;
     }
@@ -92,9 +82,9 @@ export function recordGuidelineRead(
     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 (normalizedPath === normalizePath(guide.path)) {
+      state.languageGuidesRead.add(guide.path);
       return;
     }
   }
@@ -103,6 +93,7 @@ export function recordGuidelineRead(
 export function mutationBlockReason(
   state: GuidelineReadState,
   targetPath: string,
+  readToolAvailable = true,
 ): string | undefined {
   const requiredPaths: string[] = [];
   if (!state.skillRead) {
@@ -117,18 +108,18 @@ 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];
+  return LANGUAGE_GUIDES.find(({ extensions }) =>
+    extensions.some((extension) => normalizedPath.endsWith(extension)),
+  )?.path;
 }
 
 function normalizePath(path: string): string {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmrdeveloper/sideroom-pi",
-  "version": "8.0.0",
+  "version": "8.0.2",
   "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-domain-modeling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sideroom-domain-modeling
-description: "Trigger: ubiquitous language, domain term, CONTEXT.md, ADR, vague word, naming conflict. Sharpen the project's domain language while designing: challenge vague terms, split overloaded ones, and write the settled vocabulary into the repo."
+description: "Resolve domain-language conflicts and naming decisions. Use when terms are ambiguous, overloaded, or used inconsistently; when deciding what belongs in CONTEXT.md; or when a domain choice may need an ADR. Use for one or a few terms, not for simply reading CONTEXT.md, scanning an entire repository, or reshaping modules."
 license: MIT
 metadata:
   author: RMRdeveloper

package/skills/sideroom-domain-scaffold/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sideroom-domain-scaffold
-description: "Trigger: document my repo, scaffold CONTEXT.md, brownfield glossary, survey domain. Read the central domain code as source of truth and build or complete CONTEXT.md without interviewing anyone; conflicting terms are collected and grilled once, at the end."
+description: "Build or complete a code-first CONTEXT.md for a repository with missing or thin domain vocabulary. Use when the user asks to document or survey the repo, scaffold a brownfield glossary, or derive domain terms from central business code. Do not use for resolving one naming conflict or conducting an interactive design interview."
 license: MIT
 metadata:
   author: RMRdeveloper

package/skills/sideroom-grill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sideroom-grill
-description: "Trigger: fuzzy plan, design review, grilling, CONTEXT.md, ADR, domain language. Interview the user in rounds until you share one understanding, then write the vocabulary and the hard decisions into the repo."
+description: "Interview the user in rounds to resolve a fuzzy plan, design decision, or domain-language conflict before implementation. Use when the user asks to be grilled, wants clarifying questions, or says the plan or terms are not settled. Do not use for a code-first repository scan or a simple glossary lookup."
 license: MIT
 metadata:
   author: RMRdeveloper

package/skills/sideroom-guidelines/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sideroom-guidelines
-description: "Trigger: write, edit, coding, Java, Laravel, TypeScript, Python, Go, Rust. Apply Sideroom coding principles before changing code."
+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."
 license: MIT
 metadata:
   author: RMRdeveloper