@rmrdeveloper/sideroom-pi 8.11.0 → 8.12.0

package/README.md

@@ -1,5 +1,9 @@
 # Sideroom Pi — the side room your agent was missing
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/RMRdeveloper/sideroom-pi/main/media/logo.png" alt="The Sideroom Pi mark" width="640">
+</p>
+
 [![npm version](https://img.shields.io/npm/v/@rmrdeveloper/sideroom-pi?label=npm&logo=npm)](https://www.npmjs.com/package/@rmrdeveloper/sideroom-pi)
 [![npm monthly downloads](https://img.shields.io/npm/dm/@rmrdeveloper/sideroom-pi?label=downloads&logo=npm)](https://www.npmjs.com/package/@rmrdeveloper/sideroom-pi)
 [![npm license](https://img.shields.io/npm/l/@rmrdeveloper/sideroom-pi?label=license)](https://www.npmjs.com/package/@rmrdeveloper/sideroom-pi)
@@ -54,6 +58,7 @@ Sideroom answers each one with a small, opinionated surface:
 | Style drift | A pre-edit gate + the on-demand `sideroom-guidelines` skill + an end-of-turn review steer |
 | Invisible monorepo skills | `monorepo-skills` — trusted child folders join Pi's available skill list |
 | Vague plans | `sideroom-grill` — an interview that settles the words before the work |
+| Costly growth and refactors | `sideroom-codebase-design` — evidenced improvements to module design, tests, and long-term scaling |
 | Unapplied guidelines | `sideroom_rules` — mechanical checks that block or flag the lines you add |
 | Unchecked judgment rules | `jev` — asks a decision model about guide rules with visible evidence |
 | Unclear answers | `sideroom_persona` — one voice: direct, plain, and free of unnecessary technical words |
@@ -154,6 +159,18 @@ one to interview at all, `sideroom-domain-scaffold` reads the central
 domain code as source of truth, builds or completes `CONTEXT.md` on its
 own, and grills the conflicting terms once, at the end.
 
+### Codebase design — improve how the code grows
+
+`sideroom-codebase-design` reviews existing code, identifies where changes or
+growth create friction, and designs improvements with small interfaces and
+clear responsibilities. It considers growing features, teams, traffic, and
+data, using known needs and evidence rather than hypothetical infrastructure.
+Each recommendation explains the problem, benefit, cost, confidence, migration,
+and verification in text. It produces no diagrams or HTML reports. A review
+stays a review; when implementation is requested, it follows the authorized
+scope and preserves behavior and compatibility. See
+[skill activation](docs/skills.md) for routing and examples.
+
 ### Guidelines — a gate, not a novel
 
 A short system-prompt contract points at the packaged
@@ -197,13 +214,18 @@ Reading the guide covers the mechanical rules. `jev` makes one optional call
 to TypeSafe's decision model about the changed file and, when available, up to
 four directly related source files. It checks guard clauses, fail fast,
 command/query separation, null handling, immutability, repeated validation,
-responsibility, dependency direction, and comments only when the supplied
+responsibility, dependency direction, comments, testability, redundant
+abstractions, consumer compatibility and test quality only when the supplied
 files support the question. An answer above the cutoff travels with the
 end-of-run guidelines review instead of interrupting each edit. READMEs, JSON,
 lockfiles, deletion-only edits, and files outside the project are never sent.
 
 It never blocks and never enters the system prompt. No conversation or session
-content leaves the machine. Related source excludes ignored, hidden, sensitive-
+history leaves the machine. Successful questionnaires also send their question
+wording and options, without user answers. Newly completed tasks may send their
+descriptions, up to four observed changed files and a check status, without
+commands or logs. These additional calls review explicit contradictions and
+ambiguous choices. Related source excludes ignored, hidden, sensitive-
 named and symlinked paths; a normal source file can still contain a secret.
 The footer counts the calls the session made, and `F10` shows the same count
 beside the key source. Without a key nothing is called, and when Jev runs out of
@@ -365,7 +387,12 @@ itself.
   prompt.
 - One request per successful `write`/`edit` of a project file in a supported
   language that added lines, with applicable `noul` questions on the complete
-  changed file and up to four directly related source files.
+  changed file and up to four directly related source files, prioritizing tests
+  and production consumers before imports.
+- One additional request per successful, non-cancelled questionnaire and per
+  eligible completion update. Only validated question wording or targeted
+  completion descriptions and bounded observed evidence travel; no answers,
+  conversation history or command output. All requests share the same limits.
 - The official 32k-token state-plus-longest-question and 64k-token request
   limits are observed conservatively using 32,000 and 64,000 UTF-8 bytes.
   Oversized neighbours are omitted whole; if the changed file cannot fit,
@@ -433,8 +460,9 @@ and zero ADRs is working as designed.
 
 ### Coexisting with other grilling skills
 
-Pi routes skills by description, not by name, so several grilling skills can
-be installed at once. `sideroom-grill` claims non-trivial plans before
+See [skill activation](docs/skills.md) for selection boundaries and discovery
+diagnostics. Pi routes skills by description, not by name, so several grilling
+skills can be installed at once. `sideroom-grill` claims non-trivial plans before
 implementation and states precedence over other grilling, interview, and spec
 skills. If a third-party skill still wins, remove it from routing by adding
 `disable-model-invocation: true` to its frontmatter, or exclude its path with

package/assets/artifacts/GUIDELINES_TEMPLATE.md

@@ -181,7 +181,7 @@ async function createUser(data) {
 ```
 
 ### 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, and do not extract look-alike code that belongs to different concepts (a user's email validation vs a vendor's) — they will diverge.
+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 solely to anticipate reuse on the first or second occurrence, and do not extract look-alike code that belongs to different concepts (a user's email validation vs a vendor's) — they will diverge. Extraction for a present responsibility, clear contract, or testability is valid even with one caller.
 ```ts
 // bad — extracted after one real use
 function formatName(x: string) { return x.trim().toUpperCase(); }
@@ -190,7 +190,7 @@ function normalizeTicketStatus(status: string): TicketStatus { /* ... */ }
 ```
 
 ### 13. KISS
-RULE: Ship the simplest solution for the current, real requirement. No configurability, hooks, or layers added "just in case."
+RULE: Choose the simplest design that fully satisfies the current requirements and preserves required behavior. Avoid configurability, hooks, or layers without a demonstrated need; do not remove necessary structure just to reduce code size.
 ```js
 // bad
 function formatPrice(value, { currency = 'USD', locale = 'en-US', showSymbol = true } = {}) { /* ... */ }
@@ -199,7 +199,7 @@ 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. (Differs from KISS: KISS simplifies the chosen solution; YAGNI stops you building the unrequested one.)
+RULE: Avoid capabilities for hypothetical future use cases without evidence. User requirements, established project contracts, required error handling, compatibility, and meaningful tests are current needs, not speculation. Never use YAGNI to omit them or remove existing supported behavior. Apply it to the proposed change, not as a reason to refactor unrelated code.
 ```js
 // bad
 function createInvoice(order, { supportsRecurring = false, supportsMultiCurrency = false } = {}) { /* ... */ }

package/extensions/done/guard.ts

@@ -6,6 +6,11 @@ import {
   isToolCallEventType,
   isWriteToolResult,
 } from '@earendil-works/pi-coding-agent';
+import {
+  registerSettleGuard,
+  SETTLE_PRIORITY,
+  withHiddenSteer,
+} from '../shared/settle.ts';
 import { type CheckCommand, commandMatches } from './detect.ts';
 import {
   DONE_GATE_TYPE,
@@ -25,19 +30,22 @@ export type ResolveCommand = (
 
 export type ResolveTestSetup = (ctx: Pick<ExtensionContext, 'cwd'>) => boolean;
 
-export function registerDoneGuard(
-  pi: ExtensionAPI,
-  state: DoneState,
-  resolveCommand: ResolveCommand,
-  resolveTestSetup: ResolveTestSetup,
-): void {
+interface DoneGuardOptions {
+  readonly pi: ExtensionAPI;
+  readonly state: DoneState;
+  readonly resolveCommand: ResolveCommand;
+  readonly resolveTestSetup: ResolveTestSetup;
+}
+
+export function registerDoneGuard({
+  pi,
+  state,
+  resolveCommand,
+  resolveTestSetup,
+}: DoneGuardOptions): void {
   const checkRuns = new Set<string>();
   const mutationPaths = new Map<string, string>();
 
-  pi.on('turn_start', () => {
-    state.steeredThisTurn = false;
-  });
-
   pi.on('tool_call', (event, ctx) => {
     if (
       isToolCallEventType('write', event) ||
@@ -72,41 +80,38 @@ export function registerDoneGuard(
     }
     if (isBashToolResult(event)) {
       const wasCheck = checkRuns.delete(event.toolCallId);
-      if (wasCheck && !event.isError) {
-        state.checksGreen = true;
+      if (wasCheck) {
+        state.checksGreen = !event.isError;
       }
     }
   });
 
-  pi.on('turn_end', (_event, ctx) => {
-    const check = resolveCommand(ctx);
-    if (check !== undefined && shouldSteerDone(state, true)) {
-      state.steeredThisTurn = true;
-      state.steerCount += 1;
-      pi.sendMessage(
-        {
+  registerSettleGuard(pi, {
+    priority: SETTLE_PRIORITY.done,
+    pending: (ctx) =>
+      shouldSteerDone(state, resolveCommand(ctx) !== undefined) ||
+      shouldNoticeMissingTest(state, resolveTestSetup(ctx)),
+    handle: (event, ctx) => {
+      const check = resolveCommand(ctx);
+      if (check !== undefined && shouldSteerDone(state, true)) {
+        state.steerCount += 1;
+        return withHiddenSteer({
+          event,
           customType: DONE_GATE_TYPE,
           content: formatDoneSteer(check.display),
-          display: false,
-        },
-        { triggerTurn: true, deliverAs: 'steer' },
-      );
-      return;
-    }
-
-    if (!shouldNoticeMissingTest(state, resolveTestSetup(ctx))) {
-      return;
-    }
-    state.noticedMissingTest = true;
-    state.steerCount += 1;
-    pi.sendMessage(
-      {
+        });
+      }
+      if (!shouldNoticeMissingTest(state, resolveTestSetup(ctx))) {
+        return;
+      }
+      state.noticedMissingTest = true;
+      state.steerCount += 1;
+      return withHiddenSteer({
+        event,
         customType: MISSING_TEST_NOTICE_TYPE,
         content: formatMissingTestNotice(),
-        display: false,
-      },
-      { triggerTurn: true, deliverAs: 'steer' },
-    );
+      });
+    },
   });
 }
 

package/extensions/done/index.ts

@@ -2,6 +2,7 @@ import type {
   ExtensionAPI,
   ExtensionContext,
 } from '@earendil-works/pi-coding-agent';
+import { startsUserTurn } from '../shared/settle.ts';
 import {
   type CheckCommand,
   detectCheckCommand,
@@ -41,10 +42,10 @@ export default function registerDone(pi: ExtensionAPI): void {
     return hasTests;
   };
 
-  registerDoneGuard(pi, state, resolveCommand, resolveTestSetup);
+  registerDoneGuard({ pi, state, resolveCommand, resolveTestSetup });
 
   pi.on('input', (event) => {
-    if (event.source === 'interactive' || event.source === 'rpc') {
+    if (startsUserTurn(event)) {
       resetDoneRun(state);
     }
   });

package/extensions/done/model.ts

@@ -1,7 +1,6 @@
 export interface DoneState {
   mutated: boolean;
   checksGreen: boolean;
-  steeredThisTurn: boolean;
   steerCount: number;
   mutatedSource: boolean;
   mutatedTest: boolean;
@@ -27,7 +26,6 @@ export function createDoneState(): DoneState {
   return {
     mutated: false,
     checksGreen: false,
-    steeredThisTurn: false,
     steerCount: 0,
     mutatedSource: false,
     mutatedTest: false,
@@ -38,7 +36,6 @@ export function createDoneState(): DoneState {
 export function resetDoneRun(state: DoneState): void {
   state.mutated = false;
   state.checksGreen = false;
-  state.steeredThisTurn = false;
   state.steerCount = 0;
   state.mutatedSource = false;
   state.mutatedTest = false;
@@ -63,7 +60,6 @@ export function shouldSteerDone(
     hasCommand &&
     state.mutated &&
     !state.checksGreen &&
-    !state.steeredThisTurn &&
     state.steerCount < MAX_DONE_STEERS
   );
 }
@@ -86,5 +82,5 @@ export function formatDoneSteer(display: string): string {
 }
 
 export function formatMissingTestNotice(): string {
-  return 'This run changed code files and no test file. Add or update the test that covers the change before finishing.';
+  return 'This run changed code files and no test file. Check whether existing tests cover the changed behavior; add or update a test if coverage is missing, then rerun the relevant checks before finishing.';
 }

package/extensions/explain/guard.ts

@@ -4,7 +4,8 @@ import {
   isWriteToolResult,
 } from '@earendil-works/pi-coding-agent';
 import {
-  acceptsSettleSteer,
+  registerSettleGuard,
+  SETTLE_PRIORITY,
   startsUserTurn,
   withHiddenSteer,
 } from '../shared/settle.ts';
@@ -54,15 +55,16 @@ export function registerExplainGuard(
   // agent_before_settle runs after retries and compaction recovery, so the
   // walkthrough is never offered over reworked work, and its continuation
   // stays inside the same run instead of starting a second one.
-  pi.on('agent_before_settle', (event, ctx) => {
-    if (!acceptsSettleSteer(event)) {
-      return;
-    }
-    const decision = decideOffer(state, ctx.mode);
-    applyOfferDecision(state, decision);
-    if (decision !== EXPLAIN_DECISION.send) {
-      return;
-    }
-    return withHiddenSteer(event, EXPLAIN_OFFER_TYPE, EXPLAIN_OFFER);
+  registerSettleGuard(pi, {
+    priority: SETTLE_PRIORITY.explain,
+    pending: (ctx) => decideOffer(state, ctx.mode) === EXPLAIN_DECISION.send,
+    handle: (event, ctx) => {
+      applyOfferDecision(state, decideOffer(state, ctx.mode));
+      return withHiddenSteer({
+        event,
+        customType: EXPLAIN_OFFER_TYPE,
+        content: EXPLAIN_OFFER,
+      });
+    },
   });
 }

package/extensions/explain/model.ts

@@ -13,7 +13,6 @@ export const EXPLAIN_OFFER =
 
 export const EXPLAIN_DECISION = {
   send: 'send',
-  defer: 'defer',
   none: 'none',
 } as const;
 
@@ -22,24 +21,18 @@ export type ExplainDecision =
 
 export interface ExplainState {
   mutatedFilesThisTurn: Set<string>;
-  mutatedSinceSettle: boolean;
-  pendingOffer: boolean;
   offeredThisTurn: boolean;
 }
 
 export function createExplainState(): ExplainState {
   return {
     mutatedFilesThisTurn: new Set(),
-    mutatedSinceSettle: false,
-    pendingOffer: false,
     offeredThisTurn: false,
   };
 }
 
 export function resetExplainTurn(state: ExplainState): void {
   state.mutatedFilesThisTurn.clear();
-  state.mutatedSinceSettle = false;
-  state.pendingOffer = false;
   state.offeredThisTurn = false;
 }
 
@@ -51,13 +44,9 @@ export function mutationPathKey(cwd: string, path: string): string | undefined {
 
 export function recordMutation(state: ExplainState, pathKey: string): void {
   state.mutatedFilesThisTurn.add(pathKey);
-  state.mutatedSinceSettle = true;
 }
 
-// The guidelines review steers at the first settle boundary after a mutation,
-// and both handlers run in an extension load order Sideroom does not control.
-// Explain holds its steer back one boundary so the review always runs first;
-// the review's continuation is what brings the next boundary.
+// The shared settle guard gives review and checks priority over the offer.
 export function decideOffer(
   state: ExplainState,
   mode: string,
@@ -66,15 +55,9 @@ export function decideOffer(
     mode === TUI_MODE &&
     !state.offeredThisTurn &&
     state.mutatedFilesThisTurn.size >= EXPLAIN_FILE_THRESHOLD;
-  if (state.pendingOffer && thresholdReached) {
+  if (thresholdReached) {
     return EXPLAIN_DECISION.send;
   }
-  if (
-    thresholdReached ||
-    (mode === TUI_MODE && state.mutatedSinceSettle && !state.offeredThisTurn)
-  ) {
-    return EXPLAIN_DECISION.defer;
-  }
   return EXPLAIN_DECISION.none;
 }
 
@@ -84,11 +67,5 @@ export function applyOfferDecision(
 ): void {
   if (decision === EXPLAIN_DECISION.send) {
     state.offeredThisTurn = true;
-    state.pendingOffer = false;
-  } else if (decision === EXPLAIN_DECISION.defer) {
-    state.pendingOffer = true;
-  } else {
-    state.pendingOffer = false;
   }
-  state.mutatedSinceSettle = false;
 }

package/extensions/guidelines/review.ts

@@ -5,7 +5,8 @@ import {
 } from '@earendil-works/pi-coding-agent';
 import { isReviewNote, REVIEW_NOTE_EVENT } from '../shared/review-note.ts';
 import {
-  acceptsSettleSteer,
+  registerSettleGuard,
+  SETTLE_PRIORITY,
   startsUserTurn,
   withHiddenSteer,
 } from '../shared/settle.ts';
@@ -13,10 +14,13 @@ import {
 export const REVIEW_STEER_TYPE = 'sideroom-guidelines-review';
 
 export const REVIEW_STEER =
-  'Review every file this run changed against the loaded Sideroom language guide: fix any mechanical, structural, or architectural rule violations in those files, then run the relevant formatter, linter, type checks, and tests. If the guide is no longer in context, re-read it in full first.';
+  'Finish any remaining requested implementation before reviewing. Review the changes this run introduced against the loaded Sideroom language guide: fix only demonstrated violations caused by those changes, preserving all requested requirements and existing behavior. KISS and YAGNI do not justify removing required error handling, compatibility, or tests. Do not refactor unrelated code. Then run the relevant formatter, linter, type checks, and tests. If the guide is no longer in context, re-read it in full first.';
+
+export const WORKFLOW_REVIEW_STEER =
+  'Verify the semantic notes below against the visible evidence and the questionnaire or task contract. Correct only demonstrated ambiguity or contradictions; respect user answers and ask again only when clarification is necessary. Missing evidence is not proof of unfinished work. Do not create unrelated implementation work. Run project checks only if code changes.';
 
 export const REVIEW_NOTES_STEER =
-  'Files changed during the review drew the semantic notes below. Verify each against the loaded Sideroom language guide, fix only real violations, then rerun the relevant checks.';
+  'Additional semantic notes arrived after the review. Verify each against the loaded Sideroom language guide, fix only demonstrated violations introduced by this run without removing required behavior or refactoring unrelated code, then rerun the relevant checks.';
 
 export interface ReviewState {
   mutated: boolean;
@@ -42,21 +46,27 @@ export function resetReviewTurn(state: ReviewState): void {
 }
 
 export function shouldReview(state: ReviewState): boolean {
-  return state.mutated && !state.steeredThisTurn;
+  return (state.mutated || state.notes.length > 0) && !state.steeredThisTurn;
 }
 
 // Notes that arrive after the review fired get one follow-up per turn, so a
 // fix that draws new notes cannot keep the run going.
 export function pendingReviewSteer(state: ReviewState): string | undefined {
   if (shouldReview(state)) {
-    return withNotes(REVIEW_STEER, state.notes);
+    return withNotes(
+      state.mutated ? REVIEW_STEER : WORKFLOW_REVIEW_STEER,
+      state.notes,
+    );
   }
   if (
     state.steeredThisTurn &&
     !state.notesSteeredThisTurn &&
     state.notes.length > 0
   ) {
-    return withNotes(REVIEW_NOTES_STEER, state.notes);
+    return withNotes(
+      state.mutated ? REVIEW_NOTES_STEER : WORKFLOW_REVIEW_STEER,
+      state.notes,
+    );
   }
   return undefined;
 }
@@ -104,12 +114,20 @@ export function registerReviewGuard(
   // continuation stays inside the same run. agent_settled is notification-only:
   // a steer sent there starts a second run after the user already saw the
   // agent stop, and it fires even when the user pressed Escape.
-  pi.on('agent_before_settle', (event) => {
-    const steer = pendingReviewSteer(state);
-    if (steer === undefined || !acceptsSettleSteer(event)) {
-      return;
-    }
-    markReviewSteered(state);
-    return withHiddenSteer(event, REVIEW_STEER_TYPE, steer);
+  registerSettleGuard(pi, {
+    priority: SETTLE_PRIORITY.review,
+    pending: () => pendingReviewSteer(state) !== undefined,
+    handle: (event) => {
+      const steer = pendingReviewSteer(state);
+      if (steer === undefined) {
+        return;
+      }
+      markReviewSteered(state);
+      return withHiddenSteer({
+        event,
+        customType: REVIEW_STEER_TYPE,
+        content: steer,
+      });
+    },
   });
 }

package/extensions/jev/client.ts

@@ -3,6 +3,7 @@ import {
   JEV_ENDPOINT,
   type JevFileState,
   type JevFinding,
+  type JevRequestBody,
   parseEnvelope,
   readFindings,
 } from './model.ts';
@@ -105,7 +106,27 @@ export async function askJev(
   file: JevFileState,
   signal: AbortSignal | undefined,
 ): Promise<JevAttempt> {
-  const requestBody = buildRequestBody(file);
+  return askJevRequest({
+    transport,
+    apiKey,
+    requestBody: buildRequestBody(file),
+    signal,
+  });
+}
+
+interface JevRequestInput {
+  readonly transport: JevTransport;
+  readonly apiKey: string;
+  readonly requestBody: JevRequestBody;
+  readonly signal: AbortSignal | undefined;
+}
+
+export async function askJevRequest({
+  transport,
+  apiKey,
+  requestBody,
+  signal,
+}: JevRequestInput): Promise<JevAttempt> {
   const body = JSON.stringify(requestBody);
   let response: JevHttpResponse;
   try {

package/extensions/jev/context.ts

@@ -4,6 +4,7 @@ import ignore from 'ignore';
 import { LANGUAGE, languageForPath } from '../rules/catalog.ts';
 import {
   buildFileState,
+  isTestPath,
   type JevFileState,
   type JevRelatedFile,
   stateFitsBudget,
@@ -52,19 +53,31 @@ export function buildContextualState(
         references(candidate.path, candidate.body),
         path,
       );
-      if (!importedByTarget && !consumesTarget) {
+      const companionTest = isCompanionTest(path, candidate.path);
+      const testedSource = isCompanionTest(candidate.path, path);
+      if (
+        !importedByTarget &&
+        !consumesTarget &&
+        !companionTest &&
+        !testedSource
+      ) {
         return [];
       }
       return [
         {
           ...candidate,
-          relation: importedByTarget ? 'imported' : 'consumer',
+          relation: isTestPath(candidate.path)
+            ? 'test'
+            : importedByTarget || testedSource
+              ? 'imported'
+              : 'consumer',
         } as const,
       ];
     })
     .sort((left, right) => {
       if (left.relation !== right.relation) {
-        return left.relation === 'imported' ? -1 : 1;
+        const priority = { test: 0, consumer: 1, imported: 2 };
+        return priority[left.relation] - priority[right.relation];
       }
       return compareText(left.path, right.path);
     });
@@ -325,3 +338,23 @@ function matchesReference(names: ReadonlySet<string>, path: string): boolean {
   }
   return false;
 }
+
+// Naming is evidence only for a sibling test, never for a repository-wide basename match.
+function isCompanionTest(source: string, candidate: string): boolean {
+  if (
+    isTestPath(source) ||
+    !isTestPath(candidate) ||
+    posix.dirname(source) !== posix.dirname(candidate)
+  ) {
+    return false;
+  }
+  const stem = posix.basename(source, extname(source));
+  const testStem = posix.basename(candidate, extname(candidate));
+  return (
+    testStem === `${stem}.test` ||
+    testStem === `${stem}.spec` ||
+    testStem === `${stem}_test` ||
+    testStem === `test_${stem}` ||
+    testStem === `${stem}Test`
+  );
+}