@rmrdeveloper/sideroom-pi 8.10.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,9 +58,10 @@ 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 the six rules no check can decide |
-| Unclear answers | `sideroom_persona` — one voice: direct, plain, and free of jargon it invented |
+| 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 |
 
@@ -140,9 +145,13 @@ project are labelled `external`. A new session starts clean.
 
 An on-demand skill for fuzzy plans. It interviews you in `sideroom_ask`
 rounds — reading the codebase first so it never asks what the code already
-says — until you share one understanding. Resolved terms land in
-`CONTEXT.md` the moment they resolve; hard decisions land as ADRs under
-`docs/adr/`. Everything else stays in the conversation, ready to become a
+says — until you share one understanding. Its recommendations favor choices
+that are easy to maintain and meet known growth needs over the cheapest initial
+build. It names the upfront cost; if a missing fact could change the choice,
+it asks for that fact before recommending a solution. Resolved terms land in
+`CONTEXT.md` the moment they resolve. Only hard-to-reverse, surprising choices
+with a real trade-off qualify for a record under `docs/adr/`; the user is asked
+first. Everything else stays in the conversation, ready to become a
 spec or an implementation. Vocabulary sharpening during the rounds follows
 the companion `sideroom-domain-modeling` skill, which also runs on its own
 whenever the words — not the plan — are the problem. And when there is no
@@ -150,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
@@ -189,17 +210,23 @@ written, no config read: the catalog ships with the package.
 
 ### Jev — judgment where no check reaches
 
-Reading the guide covers the mechanical rules. `jev` covers the other kind: one
-optional call to TypeSafe's Jev decision model about the six guide rules a
-single file can answer (guard clauses, fail fast, command/query separation,
-null handling, immutability, validate once) on the file a `write` or `edit` just
-changed. The answer arrives as a probability, and when it clears the cutoff the
-note travels with the guidelines review at the end of the run 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. The state is the file and
-the added lines and nothing else — no conversation, no session, no neighbours.
+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, 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
+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
 quota, rejects the key,
@@ -214,12 +241,12 @@ without ever writing it to the session.
 `sideroom_persona` is the agent's voice, and there is exactly one of it. A
 short reminder rides the system prompt on every turn, so it survives
 compaction; the full guide lives in the on-demand `sideroom-persona` skill.
-The voice is direct and dry, free of filler, and plain enough to leave no
-doubt about what is being discussed — while calling things by the names the
-user already uses. Emojis and decorative 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.
+The voice is direct and dry, free of filler. It uses everyday words even when
+you use technical terms. It keeps a technical term only when needed to
+understand or act, and explains it the first time. Emojis and decorative
+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
 
@@ -359,10 +386,17 @@ itself.
   arrive after the review fired; nothing blocks and nothing reaches the system
   prompt.
 - One request per successful `write`/`edit` of a project file in a supported
-  language that added lines, with six `noul` questions on one shared state of
-  the project-relative path, the file body, and the added lines.
-- A serialized state over 60k characters is skipped rather than truncated. An
-  answer at or above `0.8` probability becomes a note.
+  language that added lines, with applicable `noul` questions on the complete
+  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,
+  the call is skipped. An answer at or above `0.8` becomes a note.
 - The request follows the run's abort signal; a cancelled request is not a
   failure.
 - Quota (`402`) and a rejected key (`401`, `403`) stop the calls immediately. A
@@ -426,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/ask/index.ts

@@ -15,8 +15,9 @@ export const ASK_PROMPT_SNIPPET =
   'Ask the user one or more questions with a recommended option, in their language.';
 
 export const ASK_PROMPT_GUIDELINES = [
-  'When a non-trivial request is not yet a settled spec, follow the sideroom-grill skill before implementing; it drives sideroom_ask rounds. One sideroom_ask call is one batch; call it again for another round.',
-  'A decision the repository already settles consistently is a project fact: read the code and reuse it. A decision that materially affects architecture, dependencies, cost, security, operations, persistence, public contracts, or future change difficulty is an architectural decision: never assume it; follow the sideroom-architecture skill and expose it through sideroom_ask before committing, with the practical consequences of each alternative and one recommendation carrying a one-line justification, never technology names. If the repository shows two inconclusive patterns for the same decision, name the inconsistency in the prompt. Everything else is a minor decision: take it yourself.',
+  'Follow the sideroom-grill skill before non-trivial work without a settled spec. One sideroom_ask call is one batch; call again for another round.',
+  'Read the repository first: reuse a consistent project fact. An architectural decision (boundaries, dependencies, cost, security, operations, persistence, public contracts, future change difficulty) is never settled silently: never assume it. Follow the sideroom-architecture skill; ask through sideroom_ask with practical consequences and a one-line justification for one recommendation. Name inconsistent patterns in the prompt. Take minor decisions yourself.',
+  'Recommend evidence-backed long-term quality: maintainability and growth for known needs over initial speed. State the upfront cost; avoid speculative capacity. If decisive facts or figures are missing, ask for them first through sideroom_ask; recommend gathering evidence, not an unsupported solution.',
   'Write sideroom_ask prompts, tab labels, option labels, and option descriptions in the language the user is speaking; keep ids and option values in English.',
   'sideroom_ask always adds Out of scope and a write-your-own answer; never send them yourself. A single-selection question needs recommendationIndex; a multiple-selection question needs recommendedIndices and never recommendationIndex.',
   'sideroom_ask only works in the interactive TUI; it errors in print, JSON, and RPC modes.',

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,28 @@ export async function askJev(
   file: JevFileState,
   signal: AbortSignal | undefined,
 ): Promise<JevAttempt> {
-  const body = JSON.stringify(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 {
     response = await transport({ apiKey, body, signal });
@@ -130,7 +152,10 @@ export async function askJev(
     return { findings: [], model: undefined, failure: undefined };
   }
   return {
-    findings: readFindings(envelope),
+    findings: readFindings(
+      envelope,
+      new Set(Object.keys(requestBody.questions)),
+    ),
     model: envelope.model,
     failure: undefined,
   };