@rmrdeveloper/sideroom-pi 7.0.1 → 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.0.1",
+  "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-domain-modeling/SKILL.md

@@ -0,0 +1,81 @@
+---
+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."
+license: MIT
+metadata:
+  author: RMRdeveloper
+  version: "1.0"
+---
+
+# Sideroom domain modeling
+
+## Activation Contract
+
+Load this skill when the _words_ are the problem: two people mean different
+things by one term, one term is doing several jobs, or a statement about the
+domain needs to survive longer than the conversation. This is the active
+discipline — changing the model — not the passive habit of reading
+`CONTEXT.md` to borrow a word. That read needs no skill; it is one line.
+
+It runs underneath `sideroom-grill` through a grilling session, and it also
+runs on its own when you want the discipline without the interview.
+
+## Hard Rules
+
+- Interrupt. When a term conflicts with the glossary, stop and ask which of
+  the two things is meant instead of picking one and moving on. When a vague
+  word appears where a precise one exists, force the precise word.
+- Stress-test relationships with a concrete scenario until the boundaries
+  are exact.
+- Cross-check statements against the code. When the code and the sentence
+  disagree, quote the code back and settle which one is right out loud,
+  before changing either.
+- A resolved term lands in `CONTEXT.md` the moment it resolves, inline, in
+  the middle of the conversation. One or two sentences saying what the thing
+  **is**, plus rejected synonyms under `_Avoid_`.
+- `CONTEXT.md` is a glossary and nothing else. Never persist implementation
+  details, spec prose, scratch notes, or general programming concepts there.
+  Refuse the write and say why.
+- An ADR under `docs/adr/` is offered, never assumed, and only when all
+  three gates pass at once: hard to reverse, surprising without context, and
+  the result of a real trade-off. When refusing, say which test failed.
+- Create files lazily. Nothing exists until the first term or decision
+  crystallises. In a repo with a `CONTEXT-MAP.md` at the root, terms go into
+  the per-context `CONTEXT.md` the map points at instead.
+- Keep the glossary lean. It gets shorter as often as it gets longer: split
+  an overloaded term, drop a dead one, and when the file has absorbed detail
+  that was never glossary material, offer to condense it.
+
+## Decision Gates
+
+| Situation | Move |
+| --- | --- |
+| Two meanings for one term | Pick the canonical term, list the other under `_Avoid_` |
+| One term doing several jobs | Split it (e.g. `Account` into `Customer` and `User`) |
+| A vague term became canonical | Write it to `CONTEXT.md` now |
+| A hard-to-reverse choice clearing all three ADR gates | Offer an ADR under `docs/adr/` |
+| The module's shape is the problem, not its words | This skill does not apply; that is module design |
+| The whole plan needs interrogating before building | `sideroom-grill`, which drives this skill underneath |
+| A term only needs looking up, not changing | Read `CONTEXT.md`. It is a file |
+
+## Execution Steps
+
+1. Read `CONTEXT.md` (and the ADRs, if any) before touching the model.
+2. As terms settle, write each one inline with its `_Avoid_` list.
+3. As hard choices surface, offer an ADR or refuse one with the failed
+   test named.
+4. Before finishing, re-read the touched entries: each defines what a thing
+   is, in one or two sentences, with no implementation detail.
+
+## Output Contract
+
+The repo holds the shared vocabulary and the hard decisions, each entry
+short enough to re-read. The glossary never becomes a running spec.
+
+## References
+
+- Driven by `sideroom-grill` during grilling sessions.
+- Entry rules reused by `sideroom-domain-scaffold` for code-first
+  scaffolding without interviews.
+- Based on the `domain-modeling` discipline described at
+  `https://www.aihero.dev/skills-domain-modeling`.

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

@@ -0,0 +1,70 @@
+---
+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."
+license: MIT
+metadata:
+  author: RMRdeveloper
+  version: "1.0"
+---
+
+# Sideroom domain scaffold
+
+## Activation Contract
+
+Load this skill on explicit request ("document my repo", "scaffold the
+glossary") over a codebase whose domain language is missing or thin. The
+code is the source of truth. Nobody is interviewed while the modeling runs.
+
+## Hard Rules
+
+- Zero interviews during the scan. Every irreconcilable conflict goes onto
+  a conflict list; modeling continues. The happy path is never interrupted.
+- Scope is the central business domain: its modules, types, enums, and
+  statuses. Ignore infrastructure, tooling, and utilities. Domain tests are
+  witnesses of the language, never sources of new terms.
+- Reconcile by prevalence and centrality: the dominant, core-module usage
+  wins. Record each such call as an assumption for later review.
+- Merge, never rebuild. An existing `CONTEXT.md` is curated truth: add and
+  sharpen only. A contradiction between the code and an existing entry is
+  not overwritten; it joins the conflict list.
+- Entry format, glossary purity, lazy file creation, and multi-context
+  routing all follow `sideroom-domain-modeling`. This skill owns the scan;
+  that one owns the writing.
+- No ADRs. Trade-offs cannot be validated without humans; hard choices found
+  in the code are reported, not recorded.
+- Grill once, at the end. When modeling is complete, launch
+  `sideroom-grill` scoped exactly to the conflict list so a human bounds
+  each confused term correctly. With an empty list there is no grill: close
+  with the glossary and the assumptions.
+
+## Decision Gates
+
+| Situation | Move |
+| --- | --- |
+| Same term, two meanings, no dominant use | Conflict list; grilled at the end |
+| Code contradicts an existing glossary entry | Conflict list; the entry stands until grilled |
+| Term belongs to infra, tooling, or utils | Skip it; out of scope |
+| Whole plan needs interrogating, not just terms | `sideroom-grill` instead of this skill |
+
+## Execution Steps
+
+1. Read `CONTEXT.md` (and `CONTEXT-MAP.md`, if any) before touching the
+   model.
+2. Survey the central domain code and collect candidate terms.
+3. Group synonyms, split overloaded terms, reconcile by prevalence.
+4. Write each settled term inline, merged with what exists.
+5. Collect conflicts and assumptions without stopping.
+6. Close: report the glossary and the assumptions, then either launch the
+   end-of-run `sideroom-grill` on the conflict list or state that the model
+   came out clean.
+
+## Output Contract
+
+A merged `CONTEXT.md` the code already agrees with, a reviewable list of
+assumptions, and — only when the code disagreed with itself — one bounded
+grilling at the end. No interview ever interrupts the scan.
+
+## References
+
+- Entry rules come from `sideroom-domain-modeling`.
+- Conflicts are handed to `sideroom-grill`, once, at the end of the run.

package/skills/sideroom-grill/SKILL.md

@@ -0,0 +1,61 @@
+---
+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."
+license: MIT
+metadata:
+  author: RMRdeveloper
+  version: "1.0"
+---
+
+# Sideroom grill
+
+## Activation Contract
+
+Load this skill at the start of a change, in a repo, when the plan is still
+fuzzy and the words for the thing are not settled yet. Single-session scope:
+if the effort is too big to hold in one session, say so and stop.
+
+## Hard Rules
+
+- Interview in rounds. One `sideroom_ask` call is one round; wait for its
+  answers before the next round.
+- Every question carries a recommendation (`recommendationIndex`). Write
+  prompts and option copy in the language the user is speaking; keep ids and
+  option values in English.
+- Never ask the user what the codebase can answer. Read the code first; ask
+  only what the code cannot settle.
+- An *Out of scope* answer closes that thread. Do not re-ask it.
+- Everything a round settles is recorded through `sideroom-domain-modeling`:
+  inline glossary entries, the ADR three-gate offer, lazy file creation.
+  This skill owns the interview; that one owns the writing.
+- Everything that is neither glossary nor ADR lives in the conversation
+  only. Do not clear the session after grilling; hand it to a spec or
+  straight to implementation instead.
+
+## Execution Steps
+
+1. Read the code around the change. Settle from the codebase everything the
+   codebase settles.
+2. Run one `sideroom_ask` round on what remains genuinely open: terms first,
+   then decisions.
+3. After each round, write resolved terms to `CONTEXT.md` and qualifying
+   decisions to `docs/adr/`.
+4. Repeat until no open term or hard decision remains, or the user cancels.
+5. Close by stating the settled glossary, the ADRs written (if any), and the
+   suggested next step: a spec for anything non-trivial, implementation for
+   what is small enough to build now.
+
+## Output Contract
+
+The repo holds the shared vocabulary and the hard decisions; the
+conversation holds everything else. The user can re-read `CONTEXT.md` and
+the ADRs and find exactly what was agreed, nothing softened.
+
+## References
+
+- Drives `sideroom-domain-modeling` underneath: vocabulary sharpening
+  during the rounds follows that skill.
+- Closes `sideroom-domain-scaffold` runs: terms a scan could not reconcile
+  are grilled here, once, at the end.
+- Based on the `grill-with-docs` discipline described at
+  `https://www.aihero.dev/skills-grill-with-docs`.

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