@rmrdeveloper/sideroom-pi 9.1.0 → 9.2.0

package/README.md

@@ -9,8 +9,8 @@
 [![npm license](https://img.shields.io/npm/l/@rmrdeveloper/sideroom-pi?label=license)](https://www.npmjs.com/package/@rmrdeveloper/sideroom-pi)
 
 **The open-source quality layer for Pi.** Your agent asks before it guesses,
-follows your code rules on the lines it writes, and cannot call a task
-finished while your project's own checks are still red.
+follows your code rules on the lines it writes, and reviews its changes
+before finishing.
 
 ```bash
 pi install npm:@rmrdeveloper/sideroom-pi
@@ -26,8 +26,8 @@ pi install npm:@rmrdeveloper/sideroom-pi
 
 For developers who chose Pi for control or cost and need the result to be
 actually ready: Sideroom is the quality layer that makes Pi follow your
-rules, ask when there are two reasonable paths, and not say "done" until
-your project passes its own checks.
+rules, ask when there are two reasonable paths, and review its changes
+against the loaded guide before finishing.
 
 ## Why Sideroom exists
 
@@ -61,8 +61,8 @@ Sideroom answers each one with a small, opinionated surface:
 | 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 |
-| Premature completion | `sideroom_done` — steers back to the project's check command before finishing |
-| Work left unexplained | `explain` — offers a walkthrough and how to test it once the work settles |
+| Premature completion | Guidelines review — asks for relevant checks and reuses valid results |
+| Work left unexplained | `explain` — invites a walkthrough in the final response after meaningful work |
 
 ## What it feels like
 
@@ -101,9 +101,9 @@ wall of tool calls, it:
   conditionals and swallowed errors block the mutation; vague names, stale
   `TODO`s, commented-out code, and debug output are appended as notes to the
   result. A rule that keeps firing degrades instead of trapping the agent.
-- **Does not call it done in red.** When files changed and the project's own
-  check command has not passed, the agent is steered back to run it before
-  finishing. If no check command is detectable, the gate stays out of the way.
+- **Reviews before finishing.** The guidelines review asks for missing,
+  failed or stale checks and reuses valid results. Check observation never
+  forces another response just to run a command.
 
 ## What's inside
 
@@ -273,24 +273,25 @@ symbols in the lines a `write`/`edit` adds block the mutation; flattering
 openers, hedging, automatic apologies, and AI meta-commentary are answered
 with a capped steer. No profiles to switch and no profile selection to store.
 
-### Done — done means green
+### Done — passive check observation
 
 `sideroom_done` detects the project's check command — `package.json` scripts
 (`check` → `test` → `lint` → `typecheck` → `types`) with the right
 package manager, `pytest`, `go test ./...`, `cargo test`, or a `make check`
-target — and watches for it to pass. If files changed without a green run, the
-agent is steered once per turn, up to a cap, to run it before finishing. When
-nothing is detectable, the gate does nothing.
+target — and observes checks the agent chooses to run. It shares successful
+results with guidelines review, so that review can reuse them. It never requests
+a continuation to run checks. A coverage notice can join an existing review or
+style continuation, but never opens one on its own.
 
-### Explain — the walkthrough offer
+### Explain — the walkthrough invitation
 
-When a review, style correction, or check already requires a closing
-continuation, `explain` can add a walkthrough offer through `sideroom_ask`:
-changes only, test steps only, both, or nothing. The instruction asks the agent
-to finish the work, review and checks before offering. It never opens a turn
-solely for an offer. Once per user turn, only after at least five distinct
-files changed, and only in the TUI. Aborts, errors and queued messages postpone
-it. No tool, widget or persisted state.
+After meaningful changes, review and checks are complete, `explain` lets the
+agent end its final response with a short invitation to explain the changes
+or how to test them. It skips trivial work and explanations already given.
+There is no automatic questionnaire, file-count threshold or extra model turn.
+Only after you accept, the agent may clarify the scope through `sideroom_ask`
+in the TUI; if your request is clear, it explains directly. A fixed reminder
+keeps the system prompt stable across turns. No tool, widget or persisted state.
 
 ## Quick path
 
@@ -455,22 +456,20 @@ itself.
   `cargo test`, or `make check`. Detection is cached per working directory.
 - Green means that command ran with a zero exit in this run. A later
   successful `write`/`edit` clears green again.
-- Steering: once per turn, at most twice per run, then it stops.
+- Observation only: no standalone check or coverage continuation. Coverage
+  notices join another necessary continuation at most once per user turn.
 
 ### Explain contract
 
-- Trigger: `agent_before_settle` with at least five distinct files mutated
-  since the last idle user prompt, in TUI mode, on a completed run with no user
-  message pending. File identity follows Pi's path aliases and canonicalizes
-  existing paths.
-- Delivery: joins an existing necessary settle continuation through the shared
-  supplement event, in any extension load order. If none is needed, stays silent.
-- The steer names the intent; the agent writes the question in the user's
-  language with four options, one of them a decline, and one recommendation.
-  `sideroom_ask` still adds *Out of scope* and the custom answer.
-- At most one offer per turn. The flag is set only when the supplement is
-  appended; the offer never triggers its own continuation.
-- No green-check requirement: red checks still produce the offer.
+- Delivery: a fixed, idempotent reminder on `before_agent_start`; no per-turn
+  state is interpolated into the system prompt.
+- After meaningful work, review and checks, the agent may include one short
+  invitation in the final response, in the user's language. Trivial work,
+  explanations already provided and requests for no follow-up skip it.
+- No file-count threshold, automatic questionnaire, closing hook or extra turn.
+- After explicit acceptance, clarify scope through `sideroom_ask` only when
+  needed in the TUI. Otherwise explain directly, or clarify in ordinary
+  conversation outside the TUI.
 
 ### Grill contract
 

package/extensions/done/guard.ts

@@ -7,23 +7,15 @@ import {
   isWriteToolResult,
 } from '@earendil-works/pi-coding-agent';
 import { registerCheckStatus } from '../shared/check-status.ts';
-import {
-  registerSettleGuard,
-  registerSettleSupplement,
-  SETTLE_PRIORITY,
-  withHiddenSteer,
-} from '../shared/settle.ts';
+import { registerSettleSupplement } from '../shared/settle.ts';
 import { type CheckCommand, commandMatches } from './detect.ts';
 import {
-  DONE_GATE_TYPE,
   type DoneState,
-  formatDoneSteer,
   formatMissingTestNotice,
   isSourcePath,
   isTestPath,
   MISSING_TEST_NOTICE_TYPE,
   shouldNoticeMissingTest,
-  shouldSteerDone,
 } from './model.ts';
 
 export type ResolveCommand = (
@@ -82,7 +74,6 @@ export function registerDoneGuard({
       if (event.isError) {
         return;
       }
-      state.mutated = true;
       state.checksGreen = false;
       recordMutationPath(state, path);
       return;
@@ -105,34 +96,6 @@ export function registerDoneGuard({
       content: formatMissingTestNotice(),
     };
   });
-
-  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),
-        });
-      }
-      if (!shouldNoticeMissingTest(state, resolveTestSetup(ctx))) {
-        return;
-      }
-      state.noticedMissingTest = true;
-      state.steerCount += 1;
-      return withHiddenSteer({
-        event,
-        customType: MISSING_TEST_NOTICE_TYPE,
-        content: formatMissingTestNotice(),
-      });
-    },
-  });
 }
 
 function recordMutationPath(state: DoneState, path: string | undefined): void {

package/extensions/done/model.ts

@@ -1,16 +1,10 @@
 export interface DoneState {
-  mutated: boolean;
   checksGreen: boolean;
-  steerCount: number;
   mutatedSource: boolean;
   mutatedTest: boolean;
   noticedMissingTest: boolean;
 }
 
-export const MAX_DONE_STEERS = 2;
-
-export const DONE_GATE_TYPE = 'sideroom-done-gate';
-
 export const MISSING_TEST_NOTICE_TYPE = 'sideroom-missing-test-notice';
 
 const TEST_DIRECTORY = /(?:^|\/)(?:__tests__|tests?|specs?)(?:\/|$)/;
@@ -22,9 +16,7 @@ const SOURCE_FILE = /\.(?:[cm]?js|jsx|ts|tsx|go|java|php|py|rs)$/i;
 
 export function createDoneState(): DoneState {
   return {
-    mutated: false,
     checksGreen: false,
-    steerCount: 0,
     mutatedSource: false,
     mutatedTest: false,
     noticedMissingTest: false,
@@ -32,9 +24,7 @@ export function createDoneState(): DoneState {
 }
 
 export function resetDoneRun(state: DoneState): void {
-  state.mutated = false;
   state.checksGreen = false;
-  state.steerCount = 0;
   state.mutatedSource = false;
   state.mutatedTest = false;
   state.noticedMissingTest = false;
@@ -50,18 +40,6 @@ export function isSourcePath(path: string): boolean {
   return SOURCE_FILE.test(normalized);
 }
 
-export function shouldSteerDone(
-  state: DoneState,
-  hasCommand: boolean,
-): boolean {
-  return (
-    hasCommand &&
-    state.mutated &&
-    !state.checksGreen &&
-    state.steerCount < MAX_DONE_STEERS
-  );
-}
-
 export function shouldNoticeMissingTest(
   state: DoneState,
   hasTests: boolean,
@@ -70,15 +48,10 @@ export function shouldNoticeMissingTest(
     hasTests &&
     state.mutatedSource &&
     !state.mutatedTest &&
-    !state.noticedMissingTest &&
-    state.steerCount < MAX_DONE_STEERS
+    !state.noticedMissingTest
   );
 }
 
-export function formatDoneSteer(display: string): string {
-  return `Run \`${display}\` and make it pass before finishing.`;
-}
-
 export function formatMissingTestNotice(): string {
   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, reuse relevant checks that already passed after the latest mutation, and run missing, failed, or stale checks before finishing. Any code or test edit makes earlier checks stale.';
 }

package/extensions/explain/index.ts

@@ -1,10 +1,8 @@
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-import { registerExplainGuard } from './guard.ts';
-import { createExplainState, resetExplainTurn } from './model.ts';
+import { appendExplainReminder } from './prompt.ts';
 
 export default function registerExplain(pi: ExtensionAPI): void {
-  const state = createExplainState();
-  registerExplainGuard(pi, state);
-
-  pi.on('session_start', () => resetExplainTurn(state));
+  pi.on('before_agent_start', (event) => ({
+    systemPrompt: appendExplainReminder(event.systemPrompt),
+  }));
 }

package/extensions/explain/prompt.ts

@@ -0,0 +1,13 @@
+export const EXPLAIN_REMINDER_HEADING = 'Sideroom walkthrough invitation:';
+
+export const EXPLAIN_REMINDER = `${EXPLAIN_REMINDER_HEADING}
+After completing meaningful changes, review, and checks, you may end the final response with one short sentence in the user's language offering to explain the changes or how to test them. Offer only when it adds value; omit it for trivial work, when the requested explanation is already provided, or when the user asks for no follow-up. Do not ask an automatic question or call sideroom_ask just to offer a walkthrough. Only after the user explicitly accepts the invitation, use sideroom_ask in the TUI if clarification is needed about changes, test steps, or both; otherwise explain directly. Outside the TUI, clarify in ordinary conversation when needed.`;
+
+export function appendExplainReminder(systemPrompt: string): string {
+  if (systemPrompt.includes(EXPLAIN_REMINDER_HEADING)) {
+    return systemPrompt;
+  }
+  return systemPrompt.length === 0
+    ? EXPLAIN_REMINDER
+    : `${systemPrompt}\n\n${EXPLAIN_REMINDER}`;
+}

package/extensions/shared/settle.ts

@@ -39,7 +39,7 @@ async function waitForSettle(pi: ExtensionAPI, ctx: ExtensionContext): Promise<v
   await Promise.all(request.waits);
 }
 
-export const SETTLE_PRIORITY = { review: 0, persona: 1, done: 2 } as const;
+export const SETTLE_PRIORITY = { review: 0, persona: 1 } as const;
 
 interface SettleSupplement {
   readonly customType: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rmrdeveloper/sideroom-pi",
-  "version": "9.1.0",
-  "description": "Make \"done\" mean done for Pi. Asks before it guesses, enforces your coding rules, and refuses to finish while your project's checks are red.",
+  "version": "9.2.0",
+  "description": "Make \"done\" mean done for Pi. Asks before it guesses, enforces your coding rules, and reviews changes before finishing.",
   "type": "module",
   "files": [
     "extensions",

package/skills/sideroom-persona/SKILL.md

@@ -104,7 +104,7 @@ At most three steers are sent per agent run.
 - No persisted profile state, no profiles, no switching: the persona ships with the package.
 - Nothing is written to the target repository.
 - The persona governs wording. It never relaxes the coding guidelines, the
-  added-line rules, or the check-before-finish gate.
+  added-line rules, or the project's verification requirements.
 
 ## References
 

package/extensions/explain/guard.ts

@@ -1,60 +0,0 @@
-import {
-  type ExtensionAPI,
-  isEditToolResult,
-  isWriteToolResult,
-} from '@earendil-works/pi-coding-agent';
-import { registerSettleSupplement, startsUserTurn } from '../shared/settle.ts';
-import {
-  applyOfferDecision,
-  decideOffer,
-  EXPLAIN_DECISION,
-  EXPLAIN_OFFER,
-  EXPLAIN_OFFER_TYPE,
-  type ExplainState,
-  mutationPathKey,
-  recordMutation,
-  resetExplainTurn,
-} from './model.ts';
-
-interface FileToolInput {
-  readonly path: string;
-}
-
-export function registerExplainGuard(
-  pi: ExtensionAPI,
-  state: ExplainState,
-): void {
-  pi.on('input', (event) => {
-    if (!startsUserTurn(event)) {
-      return;
-    }
-    resetExplainTurn(state);
-  });
-
-  pi.on('tool_result', (event, ctx) => {
-    if (event.isError) {
-      return;
-    }
-    if (!isEditToolResult(event) && !isWriteToolResult(event)) {
-      return;
-    }
-
-    const input = event.input as unknown as FileToolInput;
-    const pathKey = mutationPathKey(ctx.cwd, input.path);
-    if (pathKey === undefined) {
-      return;
-    }
-    recordMutation(state, pathKey);
-  });
-
-  registerSettleSupplement(pi, (ctx) => {
-    if (decideOffer(state, ctx.mode) !== EXPLAIN_DECISION.send) {
-      return undefined;
-    }
-    applyOfferDecision(state, EXPLAIN_DECISION.send);
-    return {
-      customType: EXPLAIN_OFFER_TYPE,
-      content: `After finishing the requested work, review, and checks: ${EXPLAIN_OFFER}`,
-    };
-  });
-}

package/extensions/explain/model.ts

@@ -1,66 +0,0 @@
-import { resolveFileToolPath } from '../shared/file-path.ts';
-
-export const EXPLAIN_OFFER_TYPE = 'sideroom-explain-offer';
-
-export const EXPLAIN_FILE_THRESHOLD = 5;
-
-const TUI_MODE = 'tui';
-
-export const EXPLAIN_OFFER =
-  "Use sideroom_ask for one question in the user's language with four parallel options: changes only, test steps only, both, or no explanation. Recommend changes only.";
-
-export const EXPLAIN_DECISION = {
-  send: 'send',
-  none: 'none',
-} as const;
-
-export type ExplainDecision =
-  (typeof EXPLAIN_DECISION)[keyof typeof EXPLAIN_DECISION];
-
-export interface ExplainState {
-  mutatedFilesThisTurn: Set<string>;
-  offeredThisTurn: boolean;
-}
-
-export function createExplainState(): ExplainState {
-  return {
-    mutatedFilesThisTurn: new Set(),
-    offeredThisTurn: false,
-  };
-}
-
-export function resetExplainTurn(state: ExplainState): void {
-  state.mutatedFilesThisTurn.clear();
-  state.offeredThisTurn = false;
-}
-
-export function mutationPathKey(cwd: string, path: string): string | undefined {
-  return resolveFileToolPath(cwd, path);
-}
-
-export function recordMutation(state: ExplainState, pathKey: string): void {
-  state.mutatedFilesThisTurn.add(pathKey);
-}
-
-export function decideOffer(
-  state: ExplainState,
-  mode: string,
-): ExplainDecision {
-  const thresholdReached =
-    mode === TUI_MODE &&
-    !state.offeredThisTurn &&
-    state.mutatedFilesThisTurn.size >= EXPLAIN_FILE_THRESHOLD;
-  if (thresholdReached) {
-    return EXPLAIN_DECISION.send;
-  }
-  return EXPLAIN_DECISION.none;
-}
-
-export function applyOfferDecision(
-  state: ExplainState,
-  decision: ExplainDecision,
-): void {
-  if (decision === EXPLAIN_DECISION.send) {
-    state.offeredThisTurn = true;
-  }
-}