@rmrdeveloper/sideroom-pi 8.9.0 → 8.11.0

package/extensions/jev/model.ts

@@ -1,4 +1,4 @@
-import { languageForPath } from '../rules/catalog.ts';
+import { LANGUAGE, languageForPath } from '../rules/catalog.ts';
 import { type AddedLine, addedLines } from '../rules/model.ts';
 
 export type { AddedLine } from '../rules/model.ts';
@@ -11,11 +11,11 @@ export const JEV_MODEL = 'jev-latest';
 // noise on every edit.
 export const VIOLATION_PROBABILITY = 0.8;
 
-// The state must stay well under the two documented budgets (64k tokens for the
-// whole request, 32k for the state plus the longest question). A file that does
-// not fit is skipped, never truncated: half a file reads as a distorted picture
-// and Jev answers it with the same confidence.
-export const MAX_STATE_CHARACTERS = 60_000;
+// TypeSafe documents 32k tokens for state plus the longest question and 64k
+// for the full request. JSON UTF-8 bytes are a deliberately conservative
+// upper bound; no third-party tokenizer can promise the model's exact count.
+export const MAX_STATE_BYTES = 32_000;
+export const MAX_REQUEST_BYTES = 64_000;
 
 const NOUL_TYPE = 'noul';
 
@@ -30,8 +30,7 @@ export interface JevRule {
   readonly question: JevNoulQuestion;
 }
 
-// The six guide rules that a single file can answer and that no mechanical
-// check covers. Rules 11, 12, 15, 16, 17 and 18 need the module's neighbours.
+// Questions must only use evidence in the file and the selected direct neighbours.
 export const JEV_RULES: readonly JevRule[] = [
   {
     id: 'guard-clauses',
@@ -64,10 +63,11 @@ export const JEV_RULES: readonly JevRule[] = [
     question: {
       type: NOUL_TYPE,
       instructions:
-        'In `change.addedLines`, does a function both change state and return a value, or does something that reads like a query have a side effect?',
+        'In `change.addedLines`, does a function return a value while changing a parameter, shared state or an external resource, or does a getter/query cause such a side effect? Ignore changes to local collections created inside the function to build its result.',
       criteria: {
-        true: 'A function that returns data also mutates state, or a getter mutates',
-        false: 'Functions either change state or return data, never both',
+        true: 'A function returns data while changing caller-visible state, or a getter/query mutates that state',
+        false:
+          'Local accumulation and read-only file access do not change caller-visible state',
       },
     },
   },
@@ -101,15 +101,60 @@ export const JEV_RULES: readonly JevRule[] = [
     question: {
       type: NOUL_TYPE,
       instructions:
-        'In `change.addedLines`, is the same required, type or range check repeated after a boundary already owns that input?',
+        'Does `change.addedLines` repeat a required, type or range check that is visibly performed at the input boundary in `file.body` or `context.files`? Do not infer unseen validation.',
+      criteria: {
+        true: 'The same check is visible both at the boundary and in the added lines',
+        false:
+          'The boundary check is not visible, or the added lines do not repeat it',
+      },
+    },
+  },
+  {
+    id: 'single-responsibility',
+    question: {
+      type: NOUL_TYPE,
+      instructions:
+        'Do the added lines give the changed function or class two unrelated reasons to change, visible in its body? Do not flag a function merely for coordinating focused collaborators.',
       criteria: {
-        true: 'A rule already validated at the boundary is checked again deeper in the code',
-        false: 'Validation happens once, at the boundary that owns the input',
+        true: 'The changed unit itself performs two unrelated responsibilities with visible evidence',
+        false:
+          'The unit has one responsibility or only coordinates separate focused units',
+      },
+    },
+  },
+  {
+    id: 'dependency-direction',
+    question: {
+      type: NOUL_TYPE,
+      instructions:
+        'Do the added lines introduce an import from business/domain code to infrastructure, HTTP, or a framework? Use paths and bodies in `context.files` as evidence; never infer a layer from an unavailable file.',
+      criteria: {
+        true: 'A new inward-to-outward dependency is visible in the import and its related file',
+        false:
+          'No such dependency is visible, or the roles of the files are unclear',
+      },
+    },
+  },
+  {
+    id: 'comments',
+    question: {
+      type: NOUL_TYPE,
+      instructions:
+        'Does a comment in `change.addedLines` merely narrate obvious code instead of explaining non-obvious intent, a trade-off or a hazard?',
+      criteria: {
+        true: 'A newly added comment repeats what the adjacent code already says',
+        false: 'No comment was added, or it explains non-obvious intent',
       },
     },
   },
 ];
 
+export interface JevRelatedFile {
+  readonly path: string;
+  readonly body: string;
+  readonly relation: 'imported' | 'consumer';
+}
+
 export interface JevFileState {
   readonly file: {
     readonly path: string;
@@ -120,6 +165,10 @@ export interface JevFileState {
     readonly kind: string;
     readonly addedLines: readonly string[];
   };
+  readonly context: {
+    readonly files: readonly JevRelatedFile[];
+    readonly partial: boolean;
+  };
 }
 
 export interface JevRequestBody {
@@ -147,10 +196,13 @@ export function buildFileState(
   body: string,
   kind: string,
   lines: readonly AddedLine[],
+  relatedFiles: readonly JevRelatedFile[] = [],
+  partial = false,
 ): JevFileState {
   return {
     file: { path, language: languageForPath(path), body },
     change: { kind, addedLines: lines.map((line) => line.text) },
+    context: { files: relatedFiles, partial },
   };
 }
 
@@ -167,13 +219,38 @@ export function addedLinesForEdit(
   return edits.flatMap((edit) => addedLines(edit.oldText, edit.newText));
 }
 
-export function stateFitsBudget(body: string): boolean {
-  return body.length <= MAX_STATE_CHARACTERS;
+// Questions are about code structure; a README or a lockfile has no useful state.
+export function isReviewablePath(path: string): boolean {
+  return languageForPath(path) !== LANGUAGE.generic;
+}
+
+export function stateFitsBudget(state: JevFileState): boolean {
+  const request = buildRequestBody(state);
+  const longestQuestion = Object.values(request.questions).reduce(
+    (longest, question) =>
+      Math.max(longest, Buffer.byteLength(JSON.stringify(question))),
+    0,
+  );
+  return (
+    Buffer.byteLength(JSON.stringify(state)) + longestQuestion <=
+      MAX_STATE_BYTES &&
+    Buffer.byteLength(JSON.stringify(request)) <= MAX_REQUEST_BYTES
+  );
 }
 
 export function buildRequestBody(file: JevFileState): JevRequestBody {
   const questions: Record<string, JevNoulQuestion> = {};
+  const hasImportedFile = file.context.files.some(
+    (related) => related.relation === 'imported',
+  );
+  const addedText = file.change.addedLines.join('\n');
   for (const rule of JEV_RULES) {
+    if (rule.id === 'dependency-direction' && !hasImportedFile) {
+      continue;
+    }
+    if (rule.id === 'comments' && !/(?:\/\/|\/\*|#)/u.test(addedText)) {
+      continue;
+    }
     questions[rule.id] = rule.question;
   }
   return { model: JEV_MODEL, state: file, questions };
@@ -190,6 +267,7 @@ export function parseEnvelope(text: string): JevResponseEnvelope | undefined {
 
 export function readFindings(
   envelope: JevResponseEnvelope,
+  askedRuleIds: ReadonlySet<string> = new Set(JEV_RULES.map((rule) => rule.id)),
 ): readonly JevFinding[] {
   const answers = envelope.answers;
   if (answers === undefined) {
@@ -197,6 +275,9 @@ export function readFindings(
   }
   const findings: JevFinding[] = [];
   for (const rule of JEV_RULES) {
+    if (!askedRuleIds.has(rule.id)) {
+      continue;
+    }
     const answer = answers[rule.id];
     if (answer === undefined || answer.noul < VIOLATION_PROBABILITY) {
       continue;

package/extensions/jev/ui.ts

@@ -30,6 +30,7 @@ const STATUS_LABEL: Readonly<Record<JevStatus, string>> = {
   [JEV_STATUS.noKey]: 'jev: no key (F10)',
   [JEV_STATUS.quota]: 'jev: out of quota (F10)',
   [JEV_STATUS.auth]: 'jev: key rejected (F10)',
+  [JEV_STATUS.rateLimited]: 'jev: rate limited',
   [JEV_STATUS.unavailable]: 'jev: unreachable',
 };
 

package/extensions/persona/catalog.ts

@@ -35,7 +35,7 @@ export const VOICE_RULES: readonly VoiceRule[] = [
   {
     id: 'plain-language',
     instruction:
-      'Explain in plain words: name the subject and goal before the detail, prefer everyday terms over concept jargon (hook, pipeline, registry, resolver, guardrail, invariant) unless the user used them, define any necessary term in one line, and be explicit without repetition. Never write tangled chains such as "the registry resolves the provider through the auth resolver".',
+      'Explain in plain words: say what the user needs to know or do before details. Use everyday words even if the user uses technical terms. Keep a technical term only when needed to understand or act; explain it at first use in one short sentence. Do not repeat yourself or chain technical labels.',
   },
   {
     id: 'direct',
@@ -49,7 +49,7 @@ export const VOICE_RULES: readonly VoiceRule[] = [
   {
     id: 'no-invented-terms',
     instruction:
-      'Name things as they are. Coin no intermediate term, abbreviation, codename, or technical concept word the user did not ask for.',
+      "Do not coin intermediate terms, abbreviations, or codenames. Use the user's terms only when needed to answer; otherwise explain in everyday words.",
   },
   {
     id: 'short-prose',

package/extensions/persona/prompt.ts

@@ -18,8 +18,8 @@ const ENFORCEMENT_SUMMARY =
 // Static Do/Don't pairs. Literals only: no per-turn data, so the reminder
 // stays byte-identical across turns and the provider prompt cache holds.
 export const PERSONA_EXAMPLES = [
-  "Do: Enable the flag to skip cache (enableCache). Don't: The registry resolves the provider through the auth resolver pipeline.",
-  "Do: This runs when the session closes (session_save). Don't: The lifecycle hook tears down session-scoped resources via the cleanup path.",
+  "Do: Your work list stays with this conversation, not in project files. Don't: Session-scoped board state persists outside the repository.",
+  "Do: To get a fresh answer, turn off the cache (stored results). Don't: Disable the cache invalidation pipeline.",
 ] as const;
 
 export const PERSONA_REMINDER = `${PERSONA_REMINDER_HEADING}

package/extensions/shared/file-path.ts

@@ -1,6 +1,6 @@
 import { realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { isAbsolute, join, resolve } from 'node:path';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const FILE_URL_PREFIX = 'file://';
@@ -29,6 +29,31 @@ export function resolveFileToolPath(
   return realpathOr(absolutePath);
 }
 
+// A file that does not exist yet keeps its unresolved path, so it is matched
+// against the literal working directory as well as the canonical one.
+export function projectRelativePath(
+  cwd: string,
+  absolutePath: string,
+): string | undefined {
+  const literalRoot = resolve(cwd);
+  for (const root of new Set([realpathOr(literalRoot), literalRoot])) {
+    const relativePath = relative(root, absolutePath);
+    if (isInsideRoot(relativePath)) {
+      return relativePath;
+    }
+  }
+  return undefined;
+}
+
+function isInsideRoot(relativePath: string): boolean {
+  return (
+    relativePath.length > 0 &&
+    relativePath !== '..' &&
+    !relativePath.startsWith(`..${sep}`) &&
+    !isAbsolute(relativePath)
+  );
+}
+
 function normalizeFileToolPath(path: string): string {
   const normalizedSpaces = path.replace(UNICODE_SPACES, ' ');
   const withoutAtPrefix = normalizedSpaces.startsWith('@')

package/extensions/shared/review-note.ts

@@ -0,0 +1,14 @@
+export const REVIEW_NOTE_EVENT = 'sideroom:review-note';
+
+export interface ReviewNote {
+  readonly text: string;
+}
+
+export function isReviewNote(value: unknown): value is ReviewNote {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'text' in value &&
+    typeof value.text === 'string'
+  );
+}

package/extensions/shared/settle.ts

@@ -0,0 +1,50 @@
+import type {
+  AgentBeforeSettleEvent,
+  AgentBeforeSettleEventResult,
+  InputEvent,
+  InputSource,
+} from '@earendil-works/pi-coding-agent';
+
+const COMPLETED_OUTCOME = 'completed';
+const USER_ROLE = 'user';
+const CUSTOM_MESSAGE_ENTRY = 'custom_message';
+const USER_INPUT_SOURCES: ReadonlySet<InputSource> = new Set([
+  'interactive',
+  'rpc',
+]);
+
+// A message typed while the agent runs joins the current run as a steer or
+// follow-up; only input that arrives idle opens a new turn.
+export function startsUserTurn(event: InputEvent): boolean {
+  return (
+    USER_INPUT_SOURCES.has(event.source) &&
+    event.streamingBehavior === undefined
+  );
+}
+
+// An aborted run is the user stopping the agent, an errored run has nothing
+// worth reviewing, and a pending user message already decides what comes next.
+export function acceptsSettleSteer(event: AgentBeforeSettleEvent): boolean {
+  if (event.outcome !== COMPLETED_OUTCOME) {
+    return false;
+  }
+  return !event.context.pendingMessages.some(
+    (message) => message.role === USER_ROLE,
+  );
+}
+
+// Handlers chain on agent_before_settle, so keep the entries earlier handlers
+// proposed; replacing them would drop another extension's steer.
+export function withHiddenSteer(
+  event: AgentBeforeSettleEvent,
+  customType: string,
+  content: string,
+): AgentBeforeSettleEventResult {
+  return {
+    entries: [
+      ...event.entries,
+      { type: CUSTOM_MESSAGE_ENTRY, customType, content, display: false },
+    ],
+    continue: true,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmrdeveloper/sideroom-pi",
-  "version": "8.9.0",
+  "version": "8.11.0",
   "description": "Pi coding-agent package that asks clarifying questions, shows a live todo board, enforces coding guidelines, and will not call it done while your checks are red.",
   "type": "module",
   "files": [
@@ -89,8 +89,8 @@
     "@changesets/cli": "^3.0.2",
     "@commitlint/cli": "^21.2.2",
     "@commitlint/config-conventional": "^21.2.2",
-    "@earendil-works/pi-coding-agent": "0.84.4",
-    "@earendil-works/pi-tui": "0.84.4",
+    "@earendil-works/pi-coding-agent": "0.87.1",
+    "@earendil-works/pi-tui": "0.87.1",
     "@types/node": "^22.20.1",
     "typebox": "1.3.7",
     "typescript": "^5.6.0"

package/skills/sideroom-architecture/SKILL.md

@@ -50,7 +50,14 @@ impact), or for a word conflict — that is `sideroom-domain-modeling`.
   technology label.
 - Present the decision as the current situation, the alternatives by their
   practical consequences, and one recommendation with a one-line justification.
-  Never reduce it to technology names.
+  Prefer the most maintainable option that can meet known growth needs over the
+  cheapest initial build; name its upfront cost and the cost of later changes.
+  Do not recommend maximum capacity merely for hypothetical growth. Never reduce
+  the alternatives to technology names.
+- If a missing figure could change which option is best, ask for it before
+  recommending an architecture. The preliminary question still needs a
+  justified recommended option (such as obtaining the figure); never invent
+  a target or recommend a solution without evidence.
 - One open architectural dimension blocks implementation. `Out of scope` closes
   a thread, is recorded, and is not re-asked.
 
@@ -77,10 +84,10 @@ an explicit `Out of scope` on each one you pick.
    codebase, and note any inconsistent pattern to name in a prompt.
 2. List the architectural decisions the change forces. Drop the ones the code
    already settles.
-3. For each remaining decision, pick the dimensions it touches and run one
-   `sideroom_ask` round: situation, alternatives by consequence, one
-   recommendation, each option with a `description`. Force a number or an
-   explicit `Out of scope`.
+3. For each remaining decision, pick the dimensions it touches. Ask for any
+   decisive missing figures first, then run a `sideroom_ask` round: situation,
+   alternatives by consequence, one evidence-backed recommendation, each option
+   with a `description`. Force a number or an explicit `Out of scope`.
 4. Repeat rounds until no architectural dimension is open. Do not implement
    with one open.
 5. Record an accepted decision as an ADR under `docs/adr/` only when it clears

package/skills/sideroom-grill/SKILL.md

@@ -34,6 +34,14 @@ if the effort is too big to hold in one session, say so and stop.
   by their practical consequences, and one recommendation with a one-line
   justification. Never reduce it to technology names. Name a repository
   inconsistency in the prompt instead of picking one.
+- Recommend for sustainable quality: prefer maintainability and room to grow
+  for known needs over the cheapest initial build. Explain the upfront cost and
+  future change cost; do not mistake speculative maximum capacity for quality.
+  Apply this to minor decisions too, without asking the user about them.
+- If a missing fact or figure could change the recommendation, ask for it in
+  a preliminary round before recommending a solution. That round still needs
+  a defensible recommended option, such as gathering the missing evidence;
+  never invent a number or mark an unsupported solution as recommended.
 - An *Out of scope* answer closes that thread. Do not re-ask it.
 - Everything a round settles is recorded through `sideroom-domain-modeling`:
   inline glossary entries, the ADR three-gate offer, lazy file creation.
@@ -47,8 +55,8 @@ if the effort is too big to hold in one session, say so and stop.
 1. Read the code around the change. Settle from the codebase everything the
    codebase settles.
 2. Run one `sideroom_ask` round on what remains genuinely open: terms first,
-   then the architectural decisions. Minor decisions are yours; do not spend a
-   round on them.
+   then missing facts that could change a recommendation, then the architectural
+   decisions. Minor decisions are yours; do not spend a round on them.
 3. After each round, write resolved terms to `CONTEXT.md` and qualifying
    decisions to `docs/adr/`. Offer the ADR for an accepted architectural
    decision only when all three gates pass.

package/skills/sideroom-persona/SKILL.md

@@ -22,37 +22,39 @@ needs the full persona instead of the injected reminder.
 
 | # | Rule | Do | Don't |
 | --- | --- | --- | --- |
-| 1 | Plain, never in doubt | `Enable the flag to skip cache (enableCache).` | `The registry resolves the provider through the auth resolver pipeline.` |
-| 2 | Direct and dry | `The guard blocks the write. Fix the emoji and retry.` | `I'd be happy to help with that! Let's take a look together.` |
+| 1 | Plain, never in doubt | `Your work list stays with this conversation, not in project files.` | `Session-scoped board state persists outside the repository.` |
+| 2 | Direct and dry | `The file was not saved. Remove the symbol and try again.` | `I'd be happy to help with that! Let's take a look together.` |
 | 3 | No filler | Start with the answer. | `Before we dive in…`, `As I mentioned earlier…`, `To summarize what I just said…` |
-| 4 | No invented terms | `the file the mutation adds` | `the artifact delta` (when the user never asked for that name) |
+| 4 | No invented terms | `the file you changed` | `the artifact delta` (when the user never asked for that name) |
 | 5 | Short prose | Prose for one or two points. | A three-bullet list for a single sentence. |
 | 6 | User's language | Answer in the language and variant the user wrote in. | A Spanish question answered in English. |
 
 ### Plain means everyday words, not more words
 
 Rule 1 outranks brevity for clarity, and rule 3 outranks rule 1 for length.
-Concretely: name the subject and the goal **before** the detail, use everyday
-words instead of concept jargon (`hook`, `pipeline`, `registry`, `resolver`,
-`guardrail`, `invariant`) unless the user already used them, define any
-necessary term in one line, then stop. Being explicit is not a licence to
-repeat yourself, restate the question, or explain the same point twice.
-
-- Do: `This runs when the session closes. In code: \`session_save\`.`
-- Don't: `The lifecycle hook tears down session-scoped resources via the
-  cleanup path.`
-- Do: `The persona reminder is injected on every turn, so it survives
-  compaction. That is why switching profiles would be pointless here.`
-- Don't: `What I'm saying is that the reminder gets injected, and since it's
-  injected every turn, it survives compaction — which means it comes back after
-  compaction, so profile switching has no effect.`
+Say what the user needs to know or do before explaining how. Choose words a
+student can understand without knowing the code. Even if the user uses a
+technical term, do not repeat it unless they need it to understand the answer
+or take the next step. If they do, explain it at first use in one short
+sentence. Keep exact commands, file names, and code names when needed to act;
+explain their purpose in everyday words. Plain words must stay accurate.
+Do not repeat the question or explain the same point twice.
+
+- User: `Where is the session-scoped work board?`
+- Do: `Your work list stays with this conversation, not in project files.`
+- Don't: `Session-scoped board state persists outside the repository.`
+- Do: `To get a fresh answer, turn off the cache (stored results).`
+- Don't: `Disable the cache invalidation pipeline.`
+- Do: `The answer is saved with this conversation. You can read it again later.`
+- Don't: `The response is persisted to the session, so the session stores the
+  response for future access.`
 
 ### Names the user did not ask for
 
-Rule 4 bans coining vocabulary mid-conversation. Do not rename a concept the
-user already named, do not invent abbreviations (`the PRF layer`), and do not
-use an internal field name as if it were the domain word. Use the user's word
-until they ask for another.
+Rule 4 bans coining vocabulary mid-conversation. Do not invent abbreviations
+(`the PRF layer`) or use an internal field name as if it were the domain word.
+Replace a user's unnecessary technical term with everyday words, not another
+new label. Keep exact names only when needed to act.
 
 ## Hard prohibitions
 
@@ -77,9 +79,12 @@ dead-locked.
 ### What steering means
 
 The extension sends a corrective steer after a degraded artifact block or a
-prohibited assistant message. Steers use `triggerTurn: true` so they reach the
-model even when the run is already idle. At most three steers are sent per
-agent run.
+prohibited assistant message. Both moments happen while the agent is working, so
+the steer travels through `pi.sendMessage` with `{ triggerTurn: true, deliverAs:
+'steer' }` and joins the current run. A steer sent after the run ended belongs
+to the guidelines review and the walkthrough offer, which append a
+`custom_message` entry on `agent_before_settle` instead.
+At most three steers are sent per agent run.
 
 ## Boundaries
 
@@ -87,3 +92,8 @@ agent run.
 - 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.
+
+## References
+
+- [Digital.gov: Avoid jargon](https://digital.gov/guides/plain-language/principles/avoid-jargon): keep only necessary specialist words and explain them.
+- [GOV.UK: Use clear language](https://guidance.publishing.service.gov.uk/writing-to-gov-uk-standards/writing-guidelines/clear-language/): write plainly even for specialists.