@rmrdeveloper/sideroom-pi 8.7.0 → 8.9.0

package/README.md

@@ -51,9 +51,11 @@ Sideroom answers each one with a small, opinionated surface:
 | Silent guessing | `sideroom_ask` — questions with an opinion, one batch at a time |
 | Invisible work | `sideroom_todo` — a live board above the editor, always one step in focus |
 | Repo pollution | Session-branch state — the board and history die with the session, never with a commit |
-| Style drift | A pre-edit gate + the on-demand `sideroom-guidelines` skill |
+| 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 |
 | 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 |
 | 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 |
@@ -86,6 +88,10 @@ wall of tool calls, it:
   blocked. The guides cover guard clauses, braced conditionals, fail-fast
   errors, focused units, and all 19 canonical rules without dumping them into
   the system prompt.
+- **Finds the skills below the working directory.** In a trusted monorepo, Pi
+  normally ignores project skills stored under child folders. Sideroom scans
+  three levels down, adds their `.pi/skills` and `.agents/skills`, and leaves
+  duplicate-name warnings to Pi.
 - **Cannot sneak sloppy lines past the gate.** Each write and edit is checked
   against the mechanical rules on the added lines only: braceless
   conditionals and swallowed errors block the mutation; vague names, stale
@@ -152,7 +158,23 @@ full read of the packaged skill and, for supported targets, the one complete
 language guide under `skills/sideroom-guidelines/references/languages/`.
 Each guide mirrors all 19 rules in the canonical seed with idiomatic examples.
 The seed, `assets/artifacts/GUIDELINES_TEMPLATE.md`, is never pasted into the
-system prompt.
+system prompt. After any successful mutation, one hidden review steer fires when
+the turn settles and asks the agent to re-check every changed file against the
+loaded guide and run the relevant formatter, linter, type checks, and tests —
+so the contract is applied, not just read.
+
+### Monorepo skills — child skills are still project skills
+
+Pi discovers `.pi/skills` only from its working directory and
+`.agents/skills` from that directory and its ancestors. `monorepo-skills`
+closes the downward gap: in a trusted project it scans at most three child
+levels, respects `.gitignore`, `.ignore`, and `.fdignore`, and contributes the
+same skill locations without writing project configuration. Skill bodies stay
+on demand; only names, descriptions, and locations enter the system prompt.
+
+Duplicate names keep Pi's precedence and diagnostics. Root and global skills
+load before extension paths, so use `pi config -l` to disable one that shadows
+a needed child-folder skill.
 
 ### Rules — enforcement, not advice
 
@@ -165,6 +187,24 @@ appended as notes to the tool result. A per-rule circuit breaker degrades a
 repeatedly firing block to a note so the agent never dead-locks. No files
 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 a note is appended to the tool
+result when it clears the cutoff.
+
+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.
+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,
+or stops answering, the extension goes quiet without touching the turn. The key
+lives in `TYPESAFE_API_KEY` or in your agent directory, and `F10` captures it
+without ever writing it to the session.
+
 ### Persona — one voice, not a costume
 
 `sideroom_persona` is the agent's voice, and there is exactly one of it. A
@@ -192,9 +232,11 @@ 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_settled`, the point where
 no retry, compaction, or queued message is left, so the offer never lands on
-work that is about to be redone. 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.
+work that is about to be redone. It waits one settle so the guidelines review
+runs first; both fire on `agent_settled`, and Pi would otherwise order them by
+extension load. 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.
 
 ## Quick path
 
@@ -269,8 +311,25 @@ also fully read the packaged guide matching the target path. Reads with
 `offset` or `limit`, failed reads, and same-named files elsewhere do not count.
 The extension blocks the mutation until the required reads succeed; unsupported
 languages use the shared table. Do not route around
-the gate through Bash or another file-mutation path. Before finishing, review
-the diff against the loaded guide and run the relevant project checks.
+the gate through Bash or another file-mutation path. After any successful
+`write`/`edit`, one hidden review steer fires on `agent_settled` (at most once
+per turn) asking the agent to re-check every changed file against the loaded
+guide and run the relevant project checks. Interactive input clears the steer
+flags; `before_agent_start` does not, so a steer continuation never re-triggers
+itself.
+
+### Monorepo-skills contract
+
+- Trigger: `resources_discover` after project trust resolves, in every mode.
+- Scope: `.pi/skills` and `.agents/skills` in child folders at most three
+  levels below Pi's working directory.
+- Traversal: ignore-aware, no directory symlinks, deterministic child-folder
+  order, `.pi/skills` before `.agents/skills` inside one folder.
+- Safety: untrusted projects and CLI `--no-skills`/`-ns` contribute no paths.
+- Collisions: Pi keeps the first name and reports skipped paths. Child-folder
+  skills cannot override root or user skills added earlier.
+- Prompt: one static, idempotent note prefers the skill whose location matches
+  the folder being edited.
 
 ### Rules contract
 
@@ -284,11 +343,30 @@ the diff against the loaded guide and run the relevant project checks.
 - A rule that blocks three times in a run degrades to a warning until five
   clean checks or a new interactive prompt reset it.
 
+### Jev contract
+
+- Off without a key: no request, and behavior identical to a package without
+  this extension.
+- Warn only. A finding is text appended to the tool result; nothing blocks and
+  nothing reaches the system prompt.
+- One request per successful `write`/`edit`, with six `noul` questions on one
+  shared state of the file body and the added lines.
+- A body over 60k characters is skipped rather than truncated. An answer at or
+  above `0.8` probability becomes a note.
+- Quota (`402`) and a rejected key (`401`, `403`) stop the calls immediately;
+  network errors, `429` and `5xx` stop after three consecutive failures. A
+  success rearms the breaker, and `F10` rearms it by hand.
+- Every request increments a session call counter, shown in the footer and on
+  `F10`; it resets on `session_start` and is never persisted.
+- The key comes from `TYPESAFE_API_KEY` or from
+  `getAgentDir()/sideroom.json` at mode `0600`, and never enters the session.
+
 ### Persona contract
 
 - One built-in voice. No profiles, no switching, and no persisted profile
-  state; runtime guard counters stay in memory. The footer status is derived
-  from the catalog.
+  state; runtime guard counters stay in memory. The footer shows the run's block
+  and steer counts (`persona: direct · 2 blocks · 1 steer`) and drops back to
+  `persona: direct` on the next run.
 - Injection: a short reminder appended in `before_agent_start`, chained after
   the other extensions and idempotent by heading, so it returns after
   compaction.
@@ -315,6 +393,9 @@ the diff against the loaded guide and run the relevant project checks.
 - Trigger: `agent_settled` with at least five distinct files mutated since the
   last user prompt, in TUI mode. File identity follows Pi's path aliases and
   canonicalizes existing paths.
+- One settle of delay: the guidelines review steers on the same event, and Pi
+  runs both deferred steers in extension load order, so `explain` offers at the
+  next settle.
 - 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.
@@ -338,7 +419,9 @@ 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
 `-path` in `settings.skills`. A literal name collision keeps the first skill
 found: project `.pi/skills`, then project `.agents/skills`, then
-`~/.pi/agent/skills`, then `~/.agents/skills`, then packages.
+`~/.pi/agent/skills`, then `~/.agents/skills`, then packages. Child-folder
+paths contributed by `monorepo-skills` come later and cannot override any of
+them.
 
 ## Documentation
 

package/extensions/explain/guard.ts

@@ -4,12 +4,15 @@ import {
   isWriteToolResult,
 } from '@earendil-works/pi-coding-agent';
 import {
+  applyOfferDecision,
+  decideOffer,
+  EXPLAIN_DECISION,
   EXPLAIN_OFFER,
   EXPLAIN_OFFER_TYPE,
   type ExplainState,
   mutationPathKey,
+  recordMutation,
   resetExplainTurn,
-  shouldOfferExplanation,
 } from './model.ts';
 
 interface FileToolInput {
@@ -40,16 +43,17 @@ export function registerExplainGuard(
     if (pathKey === undefined) {
       return;
     }
-    state.mutatedFilesThisTurn.add(pathKey);
+    recordMutation(state, pathKey);
   });
 
   // agent_settled is the only point with no retry, compaction, or queued
   // continuation left, so the walkthrough is never offered over reworked work.
   pi.on('agent_settled', (_event, ctx) => {
-    if (!shouldOfferExplanation(state, ctx.mode)) {
+    const decision = decideOffer(state, ctx.mode);
+    applyOfferDecision(state, decision);
+    if (decision !== EXPLAIN_DECISION.send) {
       return;
     }
-    state.offeredThisTurn = true;
     pi.sendMessage(
       {
         customType: EXPLAIN_OFFER_TYPE,

package/extensions/explain/model.ts

@@ -11,17 +11,35 @@ 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',
+  defer: 'defer',
+  none: 'none',
+} as const;
+
+export type ExplainDecision =
+  (typeof EXPLAIN_DECISION)[keyof typeof EXPLAIN_DECISION];
+
 export interface ExplainState {
   mutatedFilesThisTurn: Set<string>;
+  mutatedSinceSettle: boolean;
+  pendingOffer: boolean;
   offeredThisTurn: boolean;
 }
 
 export function createExplainState(): ExplainState {
-  return { mutatedFilesThisTurn: new Set(), offeredThisTurn: false };
+  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;
 }
 
@@ -31,14 +49,45 @@ export function mutationPathKey(cwd: string, path: string): string | undefined {
   return resolveFileToolPath(cwd, path);
 }
 
-// sideroom_ask rejects every mode but the TUI, so the offer is gated the same way.
-export function shouldOfferExplanation(
+export function recordMutation(state: ExplainState, pathKey: string): void {
+  state.mutatedFilesThisTurn.add(pathKey);
+  state.mutatedSinceSettle = true;
+}
+
+// The guidelines review steers at the first settle after a mutation, and
+// agent_settled runs both deferred steers in extension load order. Explain
+// holds its own steer back one settle so the review always runs first.
+export function decideOffer(
   state: ExplainState,
   mode: string,
-): boolean {
-  return (
+): ExplainDecision {
+  const thresholdReached =
     mode === TUI_MODE &&
-    state.mutatedFilesThisTurn.size >= EXPLAIN_FILE_THRESHOLD &&
-    !state.offeredThisTurn
-  );
+    !state.offeredThisTurn &&
+    state.mutatedFilesThisTurn.size >= EXPLAIN_FILE_THRESHOLD;
+  if (state.pendingOffer && thresholdReached) {
+    return EXPLAIN_DECISION.send;
+  }
+  if (
+    thresholdReached ||
+    (mode === TUI_MODE && state.mutatedSinceSettle && !state.offeredThisTurn)
+  ) {
+    return EXPLAIN_DECISION.defer;
+  }
+  return EXPLAIN_DECISION.none;
+}
+
+export function applyOfferDecision(
+  state: ExplainState,
+  decision: ExplainDecision,
+): 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/index.ts

@@ -5,12 +5,24 @@ import {
   resetGuidelineReadState,
 } from './guard.ts';
 import { appendGuidelinesReminder } from './prompt.ts';
+import {
+  createReviewState,
+  registerReviewGuard,
+  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);
 
+  const reviewState = createReviewState();
+  registerReviewGuard(pi, reviewState);
+  pi.on('session_start', () => {
+    resetGuidelineReadState(readState);
+    resetReviewTurn(reviewState);
+  });
+
   pi.on('before_agent_start', (event) => {
     resetGuidelineReadState(readState);
     const systemPrompt = appendGuidelinesReminder(event.systemPrompt);

package/extensions/guidelines/prompt.ts

@@ -15,8 +15,7 @@ export const GUIDELINES_REMINDER = `${GUIDELINES_REMINDER_HEADING}
 Before the first write or edit in each agent run, use the read tool without offset or limit to load these files in full:
 - ${GUIDELINE_SKILL_PATH}
 - for the extension of the file you will change, one of: ${LANGUAGE_GUIDE_INDEX}
-A required read counts only when it succeeds without truncation. Until all required reads succeed, do not call write or edit and do not mutate files through bash or another tool; the extension blocks those mutations.
-After changing files, review the code against the loaded guide and run the relevant formatter, linter, type checks, and tests.`;
+A required read counts only when it succeeds without truncation. Until all required reads succeed, do not call write or edit and do not mutate files through bash or another tool; the extension blocks those mutations.`;
 
 export function appendGuidelinesReminder(systemPrompt: string): string {
   if (systemPrompt.includes(GUIDELINES_REMINDER_HEADING)) {

package/extensions/guidelines/review.ts

@@ -0,0 +1,70 @@
+import {
+  type ExtensionAPI,
+  isEditToolResult,
+  isWriteToolResult,
+} from '@earendil-works/pi-coding-agent';
+
+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.';
+
+export interface ReviewState {
+  mutated: boolean;
+  steeredThisTurn: boolean;
+}
+
+export function createReviewState(): ReviewState {
+  return { mutated: false, steeredThisTurn: false };
+}
+
+export function resetReviewTurn(state: ReviewState): void {
+  state.mutated = false;
+  state.steeredThisTurn = false;
+}
+
+export function shouldReview(state: ReviewState): boolean {
+  return state.mutated && !state.steeredThisTurn;
+}
+
+export function registerReviewGuard(
+  pi: ExtensionAPI,
+  state: ReviewState,
+): void {
+  pi.on('input', (event) => {
+    if (event.source !== 'interactive' && event.source !== 'rpc') {
+      return;
+    }
+    resetReviewTurn(state);
+  });
+
+  pi.on('tool_result', (event) => {
+    if (event.isError) {
+      return;
+    }
+    if (!isEditToolResult(event) && !isWriteToolResult(event)) {
+      return;
+    }
+    state.mutated = true;
+  });
+
+  // agent_settled is the only point with no retry, compaction, or queued
+  // continuation left, so the review never lands on work a retry is about to
+  // redo. Mark the flag before sending so the continuation this steer starts
+  // cannot re-trigger it; sendMessage is intentionally not awaited, matching
+  // explain, so the settle handler returns immediately.
+  pi.on('agent_settled', () => {
+    if (!shouldReview(state)) {
+      return;
+    }
+    state.steeredThisTurn = true;
+    pi.sendMessage(
+      {
+        customType: REVIEW_STEER_TYPE,
+        content: REVIEW_STEER,
+        display: false,
+      },
+      { triggerTurn: true, deliverAs: 'steer' },
+    );
+  });
+}

package/extensions/jev/client.ts

@@ -0,0 +1,106 @@
+import {
+  buildRequestBody,
+  JEV_ENDPOINT,
+  type JevFileState,
+  type JevFinding,
+  parseEnvelope,
+  readFindings,
+} from './model.ts';
+
+export const JEV_REQUEST_TIMEOUT_MS = 3_000;
+
+export const JEV_FAILURE = {
+  quota: 'quota',
+  auth: 'auth',
+  transient: 'transient',
+} as const;
+
+export type JevFailure = (typeof JEV_FAILURE)[keyof typeof JEV_FAILURE];
+
+export interface JevHttpRequest {
+  readonly apiKey: string;
+  readonly body: string;
+}
+
+export interface JevHttpResponse {
+  readonly status: number;
+  readonly text: string;
+}
+
+export type JevTransport = (
+  request: JevHttpRequest,
+) => Promise<JevHttpResponse>;
+
+export interface JevAttempt {
+  readonly findings: readonly JevFinding[] | undefined;
+  readonly model: string | undefined;
+  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 {
+  return async (request) => {
+    const response = await fetch(JEV_ENDPOINT, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${request.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: request.body,
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    return { status: response.status, text: await response.text() };
+  };
+}
+
+export function classifyStatus(status: number): JevFailure | undefined {
+  if (status === 401 || status === 403) {
+    return JEV_FAILURE.auth;
+  }
+  if (status === 402) {
+    return JEV_FAILURE.quota;
+  }
+  if (status >= 400) {
+    return JEV_FAILURE.transient;
+  }
+  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,
+  file: JevFileState,
+): Promise<JevAttempt> {
+  const body = JSON.stringify(buildRequestBody(file));
+  let response: JevHttpResponse;
+  try {
+    response = await transport({ apiKey, body });
+  } catch {
+    return {
+      findings: undefined,
+      model: undefined,
+      failure: JEV_FAILURE.transient,
+    };
+  }
+
+  const failure = classifyStatus(response.status);
+  if (failure !== undefined) {
+    return { findings: undefined, model: undefined, failure };
+  }
+
+  const envelope = parseEnvelope(response.text);
+  if (envelope === undefined) {
+    return { findings: [], model: undefined, failure: undefined };
+  }
+  return {
+    findings: readFindings(envelope),
+    model: envelope.model,
+    failure: undefined,
+  };
+}