@rmrdeveloper/sideroom-pi 9.0.1 → 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,27 +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.
-
-### Explain — the walkthrough offer
-
-When an implementation settles, `explain` steers the agent to offer a
-walkthrough through `sideroom_ask`: explain the changes only, how to test them
-only, both, or nothing. It fires on `agent_before_settle`, after every retry
-and compaction recovery, so the offer never lands on work that is about to be
-redone, and it stays inside the same run. It waits one boundary so the
-guidelines review runs first; both use the same event, and Pi would otherwise
-order them by extension load. It stays quiet after Escape, after an error, and
-while a message you typed is waiting. Once per turn, only when the turn touched at least five distinct
-files, and only in the TUI, because `sideroom_ask` cannot run anywhere else. No
-tool, no widget, no persisted state.
+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 invitation
+
+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
 
@@ -458,23 +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.
-- One boundary of delay: the guidelines review steers on the same event, and Pi
-  runs both handlers in extension load order, so `explain` offers at the next
-  boundary.
-- 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 before the steer, so the turn the
-  offer triggers cannot re-trigger it.
-- 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/assets/visual-context/browser/background.js

@@ -210,7 +210,7 @@ function scheduleReconnect(entry) {
   entry.retry = setTimeout(() => {
     void reconnect(entry);
   }, RETRY_MS);
-  // Alarms wake the worker after it has been suspended while Pi is closed.
+
   void chrome.alarms.create(RETRY_ALARM, { periodInMinutes: 1 });
 }
 
@@ -284,7 +284,7 @@ async function openConnection(entry) {
             });
             return;
           }
-          // Older brokers and connection failures can only identify the installation.
+
           for (const selectionId of [...receipts.keys()]) {
             await notifyReceipt({
               endpoint: entry.endpoint,

package/assets/visual-context/browser/popup.js

@@ -6,8 +6,7 @@ const disconnect = document.querySelector('#disconnect');
 const forget = document.querySelector('#forget');
 const destination = document.querySelector('#destination');
 const connect = document.querySelector('#connect');
-// Edge keeps the Chromium shortcut page under its own scheme; every other
-// Chromium browser the companion supports answers on chrome://.
+
 const SHORTCUT_PAGE = navigator.userAgent.includes('Edg/')
   ? 'edge://extensions/shortcuts'
   : 'chrome://extensions/shortcuts';

package/extensions/ask/index.ts

@@ -23,7 +23,6 @@ export const ASK_PROMPT_GUIDELINES = [
   'sideroom_ask only works in the interactive TUI; it errors in print, JSON, and RPC modes.',
 ];
 
-// Pi loads extensions/*/index.ts through export default.
 export default function registerAsk(pi: ExtensionAPI): void {
   pi.registerTool({
     name: TOOL_NAME,

package/extensions/ask/model.ts

@@ -423,7 +423,7 @@ function schemaErrorMessage(value: unknown): string {
     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`;
+  return 'Error: Invalid sideroom_ask parameters';
 }
 
 function questionId(

package/extensions/ask/selection.ts

@@ -1,9 +1,5 @@
 import type { AskAnswer, AskQuestion, AskSelection } from './model.ts';
 
-/**
- * Sorted ascending so the answer and its rendering stay stable no matter the
- * order the user toggled the options in.
- */
 export function toggleSelection(
   selected: readonly number[],
   optionIndex: number,

package/extensions/done/guard.ts

@@ -6,22 +6,16 @@ import {
   isToolCallEventType,
   isWriteToolResult,
 } from '@earendil-works/pi-coding-agent';
-import {
-  registerSettleGuard,
-  SETTLE_PRIORITY,
-  withHiddenSteer,
-} from '../shared/settle.ts';
+import { registerCheckStatus } from '../shared/check-status.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 = (
@@ -46,6 +40,13 @@ export function registerDoneGuard({
   const checkRuns = new Set<string>();
   const mutationPaths = new Map<string, string>();
 
+  registerCheckStatus(pi, (ctx) => {
+    const check = resolveCommand(ctx);
+    return check === undefined
+      ? undefined
+      : { command: check.display, green: state.checksGreen };
+  });
+
   pi.on('tool_call', (event, ctx) => {
     if (
       isToolCallEventType('write', event) ||
@@ -73,7 +74,6 @@ export function registerDoneGuard({
       if (event.isError) {
         return;
       }
-      state.mutated = true;
       state.checksGreen = false;
       recordMutationPath(state, path);
       return;
@@ -86,32 +86,15 @@ export function registerDoneGuard({
     }
   });
 
-  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(),
-      });
-    },
+  registerSettleSupplement(pi, (ctx) => {
+    if (!shouldNoticeMissingTest(state, resolveTestSetup(ctx))) {
+      return undefined;
+    }
+    state.noticedMissingTest = true;
+    return {
+      customType: MISSING_TEST_NOTICE_TYPE,
+      content: formatMissingTestNotice(),
+    };
   });
 }
 

package/extensions/done/index.ts

@@ -15,7 +15,6 @@ import {
 } from './guard.ts';
 import { createDoneState, resetDoneRun } from './model.ts';
 
-// Pi loads extensions/*/index.ts through export default.
 export default function registerDone(pi: ExtensionAPI): void {
   const state = createDoneState();
   const cache = new Map<string, CheckCommand | undefined>();

package/extensions/done/model.ts

@@ -1,22 +1,14 @@
 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?)(?:\/|$)/;
 
-// Test paths are recognised by name only: the notice never claims the right
-// test exists, so a missed convention only costs a nudge, never a false pass.
 const TEST_FILE =
   /(?:^|\/)(?:test_[\w.-]*\.py|[\w.-]*[._](?:test|spec)\.[\w.-]+|[\w.-]*(?:Test|Tests)\.java)$/;
 
@@ -24,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,
@@ -34,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;
@@ -52,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,
@@ -72,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, then rerun the relevant checks 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, 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,11 +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';
 
-// Pi loads extensions/*/index.ts through export default.
 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/guidelines/execute.ts

@@ -6,15 +6,29 @@ export interface GuidelinesToolResult {
   readonly details: { readonly paths: readonly string[] };
 }
 
+interface GuidelinesLoadOptions {
+  readonly loadedPaths?: ReadonlySet<string>;
+  readonly readDocument?: (path: string) => string;
+}
+
 export function executeGuidelines(
   path: string,
-  readDocument: (path: string) => string = (path) => readFileSync(path, 'utf8'),
+  {
+    loadedPaths = new Set(),
+    readDocument = (path) => readFileSync(path, 'utf8'),
+  }: GuidelinesLoadOptions = {},
 ): GuidelinesToolResult {
   const guidePath = languageGuideFor(path);
   const paths = [
     GUIDELINE_SKILL_PATH,
     ...(guidePath === undefined ? [] : [guidePath]),
-  ];
+  ].filter((documentPath) => !loadedPaths.has(documentPath));
+  if (paths.length === 0) {
+    return {
+      content: [{ type: 'text', text: 'The required complete guidelines are already loaded in this run.' }],
+      details: { paths },
+    };
+  }
   const content = paths.map((documentPath) => {
     const text = readDocument(documentPath);
     if (text.trim().length === 0) {

package/extensions/guidelines/guard.ts

@@ -46,7 +46,7 @@ export function registerGuidelineGuard(
   pi: ExtensionAPI,
   state: GuidelineReadState,
 ): void {
-  // This notification follows every tool_result handler, including redactors.
+
   pi.on('tool_execution_end', (event, ctx) => {
     if (event.toolName !== GUIDELINES_TOOL_NAME) {
       return;
@@ -78,7 +78,6 @@ export function registerGuidelineGuard(
       return;
     }
 
-    // SAFETY: Pi validates built-in read arguments before emitting tool_result.
     const input = event.input as unknown as ReadInput;
     if (
       input.offset !== undefined ||

package/extensions/guidelines/index.ts

@@ -1,6 +1,6 @@
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { Type } from 'typebox';
-import { GUIDELINES_TOOL_NAME } from './catalog.ts';
+import { GUIDELINE_SKILL_PATH, GUIDELINES_TOOL_NAME } from './catalog.ts';
 import { executeGuidelines } from './execute.ts';
 import {
   createGuidelineReadState,
@@ -14,7 +14,6 @@ import {
   resetReviewTurn,
 } from './review.ts';
 
-// Pi loads extensions/*/index.ts through export default.
 export default function registerGuidelines(pi: ExtensionAPI): void {
   const readState = createGuidelineReadState();
   registerGuidelineGuard(pi, readState);
@@ -35,10 +34,13 @@ export default function registerGuidelines(pi: ExtensionAPI): void {
     executionMode: 'sequential',
     async execute(toolCallId, { path }, signal) {
       signal?.throwIfAborted();
-      const loaded = executeGuidelines(path);
+      const loadedPaths = new Set(readState.languageGuidesRead);
+      if (readState.skillRead) {
+        loadedPaths.add(GUIDELINE_SKILL_PATH);
+      }
+      const loaded = executeGuidelines(path, { loadedPaths });
       signal?.throwIfAborted();
-      // Keep an independent receipt: changed or partial tool results cannot
-      // authorize mutations, and resets discard receipts still awaiting delivery.
+
       readState.pendingLoads.set(toolCallId, {
         content: loaded.content.map((part) => ({ ...part })),
         details: { paths: [...loaded.details.paths] },
@@ -63,8 +65,6 @@ export default function registerGuidelines(pi: ExtensionAPI): void {
     return { systemPrompt };
   });
 
-  // Compaction may summarize the loaded guides out of context mid-run; force
-  // a fresh read instead of trusting a now-stale in-memory flag.
   pi.on('session_compact', () => {
     resetGuidelineReadState(readState);
   });

package/extensions/guidelines/prompt.ts

@@ -5,8 +5,6 @@ export { LANGUAGE_GUIDE_FILES } from './catalog.ts';
 export const GUIDELINES_REMINDER_HEADING =
   'Sideroom coding guidelines (always-on reminder):';
 
-// One dense index instead of one sentence per language: the same paths and the
-// same requirement, a fraction of the tokens every turn.
 const LANGUAGE_GUIDE_INDEX = LANGUAGE_GUIDES.map(
   ({ extensions, path }) => `${extensions.join('/')} ${path}`,
 ).join('; ');

package/extensions/guidelines/review.ts

@@ -3,6 +3,7 @@ import {
   isEditToolResult,
   isWriteToolResult,
 } from '@earendil-works/pi-coding-agent';
+import { readCheckStatus } from '../shared/check-status.ts';
 import { isReviewNote, REVIEW_NOTE_EVENT } from '../shared/review-note.ts';
 import {
   registerSettleGuard,
@@ -14,13 +15,13 @@ import {
 export const REVIEW_STEER_TYPE = 'sideroom-guidelines-review';
 
 export const REVIEW_STEER =
-  '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. Include rule 20, Decomposition by intent: names and contracts should separate orchestration from coherent implementation details, even with one caller. Do not split solely for line count or separate tightly coupled steps into shared mutable state, excessive parameters, or functions that must be read together. 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.';
+  '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. Include rule 20, Decomposition by intent: names and contracts should separate orchestration from coherent implementation details, even with one caller. Do not split solely for line count or separate tightly coupled steps into shared mutable state, excessive parameters, or functions that must be read together. Do not refactor unrelated code. Reuse relevant checks that already passed in this user turn after the latest file mutation. Run only missing, failed, or stale formatter, linter, type checks, and tests; any further file mutation makes earlier checks stale. 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 =
-  '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.';
+  '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, reuse checks that remain valid, and run only missing, failed, or stale checks after any corrective edit.';
 
 export interface ReviewState {
   mutated: boolean;
@@ -49,8 +50,6 @@ export function shouldReview(state: ReviewState): boolean {
   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(
@@ -110,23 +109,23 @@ export function registerReviewGuard(
     }
   });
 
-  // agent_before_settle runs after retries and compaction recovery, and its
-  // 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.
   registerSettleGuard(pi, {
     priority: SETTLE_PRIORITY.review,
     pending: () => pendingReviewSteer(state) !== undefined,
-    handle: (event) => {
+    handle: (event, ctx) => {
       const steer = pendingReviewSteer(state);
       if (steer === undefined) {
         return;
       }
       markReviewSteered(state);
+      const check = readCheckStatus(pi, ctx);
+      const checkNote = check?.green
+        ? `\n\nThe detected project check \`${check.command}\` passed after the latest successful file mutation in this user turn. Reuse that result if this review changes no files; rerun it after any further mutation.`
+        : '';
       return withHiddenSteer({
         event,
         customType: REVIEW_STEER_TYPE,
-        content: steer,
+        content: steer + checkNote,
       });
     },
   });

package/extensions/jev/client.ts

@@ -49,8 +49,6 @@ export interface JevAttempt {
   readonly failure: JevFailure | undefined;
 }
 
-// The endpoint is a package constant, never a value from the environment or the
-// session, so the outbound URL cannot be steered by the repository being edited.
 export function createFetchTransport(
   timeoutMs: number = JEV_REQUEST_TIMEOUT_MS,
 ): JevTransport {
@@ -68,8 +66,6 @@ export function createFetchTransport(
   };
 }
 
-// Pi waits for every tool_result handler before the result reaches the model,
-// so the user's Escape has to cut the request, not only the timeout.
 function requestSignal(
   timeoutMs: number,
   runSignal: AbortSignal | undefined,
@@ -97,9 +93,6 @@ export function classifyStatus(status: number): JevFailure | undefined {
   return undefined;
 }
 
-// A Jev failure is a missing note, never an error: the mutation already
-// succeeded and the mechanical rules already ran. So this returns a value
-// instead of throwing, and the caller only decides whether to keep calling.
 export async function askJev(
   transport: JevTransport,
   apiKey: string,

package/extensions/jev/context.ts

@@ -29,7 +29,6 @@ interface ScanResult {
   readonly partial: boolean;
 }
 
-// Keep the edited file complete. Other files are included whole or not at all.
 export function buildContextualState(
   cwd: string,
   path: string,
@@ -339,7 +338,6 @@ 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) ||