@rmrdeveloper/sideroom-pi 8.10.0 → 8.11.0

package/README.md

@@ -55,8 +55,8 @@ Sideroom answers each one with a small, opinionated surface:
 | 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 |
+| 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 +140,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
@@ -189,17 +193,18 @@ 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, and comments 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
+content leaves the machine. 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 +219,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 +364,12 @@ 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.
+- 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

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/jev/client.ts

@@ -105,7 +105,8 @@ export async function askJev(
   file: JevFileState,
   signal: AbortSignal | undefined,
 ): Promise<JevAttempt> {
-  const body = JSON.stringify(buildRequestBody(file));
+  const requestBody = buildRequestBody(file);
+  const body = JSON.stringify(requestBody);
   let response: JevHttpResponse;
   try {
     response = await transport({ apiKey, body, signal });
@@ -130,7 +131,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,
   };

package/extensions/jev/context.ts

@@ -0,0 +1,327 @@
+import { readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { extname, join, posix, relative, sep } from 'node:path';
+import ignore from 'ignore';
+import { LANGUAGE, languageForPath } from '../rules/catalog.ts';
+import {
+  buildFileState,
+  type JevFileState,
+  type JevRelatedFile,
+  stateFitsBudget,
+} from './model.ts';
+
+const MAX_RELATED_FILES = 4;
+const MAX_SCAN_FILES = 1_024;
+const MAX_SCAN_DEPTH = 10;
+const MAX_CANDIDATE_BYTES = 32_000;
+const IGNORE_FILES = ['.gitignore', '.ignore', '.fdignore'] as const;
+const SENSITIVE_NAME =
+  /secret|credential|password|token|private.?key|api.?key|auth.?key|(?:^|[._-])(?:env|private|key)(?:[._-]|$)/iu;
+const SKIP_DIRECTORIES = new Set(['node_modules', 'dist', 'build', 'coverage']);
+
+interface Candidate {
+  readonly path: string;
+  readonly body: string;
+}
+
+interface ScanResult {
+  readonly candidates: readonly Candidate[];
+  readonly partial: boolean;
+}
+
+// Keep the edited file complete. Other files are included whole or not at all.
+export function buildContextualState(
+  cwd: string,
+  path: string,
+  body: string,
+  kind: string,
+  lines: Parameters<typeof buildFileState>[3],
+): JevFileState | undefined {
+  const base = buildFileState(path, body, kind, lines);
+  if (!stateFitsBudget(base)) {
+    return undefined;
+  }
+
+  const scan = scanSourceFiles(cwd, path);
+  const imported = references(path, body);
+  const related: JevRelatedFile[] = [];
+  let partial = scan.partial;
+  const matches = scan.candidates
+    .flatMap((candidate) => {
+      const importedByTarget = matchesReference(imported, candidate.path);
+      const consumesTarget = matchesReference(
+        references(candidate.path, candidate.body),
+        path,
+      );
+      if (!importedByTarget && !consumesTarget) {
+        return [];
+      }
+      return [
+        {
+          ...candidate,
+          relation: importedByTarget ? 'imported' : 'consumer',
+        } as const,
+      ];
+    })
+    .sort((left, right) => {
+      if (left.relation !== right.relation) {
+        return left.relation === 'imported' ? -1 : 1;
+      }
+      return compareText(left.path, right.path);
+    });
+
+  for (const candidate of matches) {
+    if (related.length >= MAX_RELATED_FILES) {
+      partial = true;
+      break;
+    }
+    const next = [...related, candidate];
+    if (!stateFitsBudget(buildFileState(path, body, kind, lines, next))) {
+      partial = true;
+      continue;
+    }
+    related.push(candidate);
+  }
+  if (
+    [...imported].some(
+      (name) =>
+        !related.some((file) => matchesReference(new Set([name]), file.path)),
+    )
+  ) {
+    partial = true;
+  }
+  while (
+    related.length > 0 &&
+    !stateFitsBudget(buildFileState(path, body, kind, lines, related, partial))
+  ) {
+    related.pop();
+    partial = true;
+  }
+  const state = buildFileState(path, body, kind, lines, related, partial);
+  return stateFitsBudget(state) ? state : undefined;
+}
+
+function scanSourceFiles(cwd: string, editedPath: string): ScanResult {
+  const root = realpathSync(cwd);
+  const candidates: Candidate[] = [];
+  let visited = 0;
+  let partial = false;
+
+  function visit(
+    directory: string,
+    depth: number,
+    patterns: readonly string[],
+  ): void {
+    if (depth > MAX_SCAN_DEPTH || visited >= MAX_SCAN_FILES) {
+      partial = true;
+      return;
+    }
+    const localPatterns = [...patterns, ...readIgnorePatterns(directory, root)];
+    const matcher = ignore().add(localPatterns);
+    const entries = readdirSync(directory, { withFileTypes: true }).sort(
+      (a, b) => compareText(a.name, b.name),
+    );
+    for (const entry of entries) {
+      if (visited >= MAX_SCAN_FILES) {
+        partial = true;
+        return;
+      }
+      const absolute = join(directory, entry.name);
+      const path = relative(root, absolute).split(sep).join('/');
+      if (entry.name.startsWith('.') || SENSITIVE_NAME.test(entry.name)) {
+        continue;
+      }
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRECTORIES.has(entry.name) && !matcher.ignores(`${path}/`)) {
+          visit(absolute, depth + 1, localPatterns);
+        }
+        continue;
+      }
+      if (
+        !entry.isFile() ||
+        matcher.ignores(path) ||
+        path === editedPath ||
+        languageForPath(path) === LANGUAGE.generic
+      ) {
+        continue;
+      }
+      visited += 1;
+      if (statSync(absolute).size > MAX_CANDIDATE_BYTES) {
+        partial = true;
+        continue;
+      }
+      candidates.push({ path, body: readFileSync(absolute, 'utf8') });
+    }
+  }
+
+  visit(root, 0, []);
+  return { candidates, partial };
+}
+
+function readIgnorePatterns(directory: string, root: string): string[] {
+  const prefix = relative(root, directory).split(sep).join('/');
+  const rules: string[] = [];
+  for (const name of IGNORE_FILES) {
+    const file = join(directory, name);
+    if (!exists(file)) {
+      continue;
+    }
+    for (const line of readFileSync(file, 'utf8').split(/\r?\n/u)) {
+      const trimmed = line.trim();
+      if (!trimmed || (trimmed.startsWith('#') && !trimmed.startsWith('\\#'))) {
+        continue;
+      }
+      const negative = line.startsWith('!');
+      const pattern = (negative ? line.slice(1) : line).replace(/^\//u, '');
+      rules.push(
+        `${negative ? '!' : ''}${prefix ? `${prefix}/` : ''}${pattern}`,
+      );
+    }
+  }
+  return rules;
+}
+
+function exists(path: string): boolean {
+  try {
+    statSync(path);
+    return true;
+  } catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+      return false;
+    }
+    throw error;
+  }
+}
+
+function modulePath(path: string): string {
+  const extension = extname(path);
+  const withoutExtension = extension ? path.slice(0, -extension.length) : path;
+  return withoutExtension.endsWith('/index')
+    ? withoutExtension.slice(0, -'/index'.length)
+    : withoutExtension;
+}
+
+function references(path: string, body: string): Set<string> {
+  const names = new Set<string>();
+  const language = languageForPath(path);
+  const code = body.replace(/\/\*[\s\S]*?\*\/|^[ \t]*\/\/[^\n]*$/gmu, '');
+  if (language === LANGUAGE.typescript || language === LANGUAGE.javascript) {
+    const imports = [
+      /^[ \t]*(?:import|export)\s+(?:\{[^}]*\}|[^\n;]+)\s*from\s*['"](\.[^'"]+)['"]/gmu,
+      /^[ \t]*import\s*['"](\.[^'"]+)['"]/gmu,
+      /^[ \t]*(?:(?:const|let|var)\s+[\w{} ,]+\s*=\s*)?require\s*\(\s*['"](\.[^'"]+)['"]/gmu,
+    ];
+    for (const pattern of imports) {
+      for (const match of code.matchAll(pattern)) {
+        const specifier = match[1];
+        if (specifier) {
+          names.add(
+            modulePath(
+              posix.normalize(posix.join(posix.dirname(path), specifier)),
+            ),
+          );
+        }
+      }
+    }
+  }
+  if (language === LANGUAGE.python) {
+    for (const match of code.matchAll(
+      /^[ \t]*from\s+(\.+)([\w.]*)\s+import\b/gmu,
+    )) {
+      const dots = match[1]?.length ?? 0;
+      const specifier = match[2]?.replaceAll('.', '/') ?? '';
+      const parent = posix.resolve(
+        '/',
+        posix.dirname(path),
+        ...Array(dots - 1).fill('..'),
+      );
+      names.add(modulePath(posix.join(parent.slice(1), specifier)));
+    }
+  }
+  if (language === LANGUAGE.rust) {
+    let sourceRoot = posix.dirname(path);
+    if (path.startsWith('src/')) {
+      sourceRoot = 'src';
+    } else if (path.includes('/src/')) {
+      sourceRoot = path.slice(0, path.indexOf('/src/') + '/src'.length);
+    }
+    for (const match of code.matchAll(
+      /^[ \t]*(?:pub\s+)?(?:use|mod)\s+(crate::)?([\w:]+)\s*[;{]/gmu,
+    )) {
+      const specifier = match[2]?.replaceAll('::', '/');
+      if (specifier) {
+        const from = match[1] ? sourceRoot : posix.dirname(path);
+        names.add(modulePath(posix.join(from, specifier)));
+      }
+    }
+  }
+  if (language === LANGUAGE.php) {
+    for (const match of code.matchAll(
+      /^[ \t]*(?:require|include)(?:_once)?\s*(?:\(?\s*__DIR__\s*\.\s*)?['"](\.[^'"]+|\/[^'"]+)['"]/gmu,
+    )) {
+      const specifier = match[1];
+      if (specifier) {
+        names.add(
+          modulePath(
+            posix.normalize(posix.join(posix.dirname(path), specifier)),
+          ),
+        );
+      }
+    }
+  }
+  if (language === LANGUAGE.java) {
+    for (const match of code.matchAll(
+      /^[ \t]*import\s+(?:static\s+)?([\w.]+)\s*;/gmu,
+    )) {
+      const specifier = match[1]?.replaceAll('.', '/');
+      if (specifier) {
+        names.add(specifier);
+      }
+    }
+  }
+  if (language === LANGUAGE.go) {
+    for (const declaration of code.matchAll(
+      /^[ \t]*import\s*(?:\(([^)]*)\)|"([^"\n]+)")/gmu,
+    )) {
+      const quoted = declaration[1] ?? `"${declaration[2] ?? ''}"`;
+      for (const match of quoted.matchAll(/"([^"\n]+)"/gu)) {
+        if (match[1]) {
+          names.add(match[1]);
+        }
+      }
+    }
+  }
+  return names;
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) {
+    return -1;
+  }
+  if (left > right) {
+    return 1;
+  }
+  return 0;
+}
+
+function matchesReference(names: ReadonlySet<string>, path: string): boolean {
+  const target = modulePath(path);
+  if (names.has(target)) {
+    return true;
+  }
+  for (const name of names) {
+    if (path.endsWith('.java') && target.endsWith(`/${name}`)) {
+      return true;
+    }
+    if (path.endsWith('.go')) {
+      const packageParts = name.split('/');
+      const packageSuffix = packageParts.slice(-2).join('/');
+      if (
+        packageParts.length >= 2 &&
+        posix.dirname(path).endsWith(`/${packageSuffix}`)
+      ) {
+        return true;
+      }
+    }
+  }
+  return false;
+}

package/extensions/jev/guard.ts

@@ -19,16 +19,15 @@ import {
   type JevFailure,
   type JevTransport,
 } from './client.ts';
+import { buildContextualState } from './context.ts';
 import {
   type AddedLine,
   addedLinesForEdit,
   addedLinesForWrite,
-  buildFileState,
   findingKey,
   formatFindings,
   isReviewablePath,
   type JevFinding,
-  stateFitsBudget,
 } from './model.ts';
 
 export const JEV_TRANSIENT_FAILURE_LIMIT = 3;
@@ -177,13 +176,17 @@ export function registerJevGuard(
     if (body === undefined) {
       return undefined;
     }
-    const fileState = buildFileState(
+    if (ctx.signal?.aborted === true) {
+      return undefined;
+    }
+    const fileState = buildContextualState(
+      ctx.cwd,
       pending.relativePath,
       body,
       pending.kind,
       pending.lines,
     );
-    if (!stateFitsBudget(fileState) || ctx.signal?.aborted === true) {
+    if (fileState === undefined) {
       return undefined;
     }
 
@@ -269,7 +272,7 @@ function registerSuccess(state: JevGuardState): void {
   state.transientFailures = 0;
 }
 
-// A deletion-only edit leaves nothing for the six questions to read, and only
+// A deletion-only edit leaves nothing for the questions to read, and only
 // the project-relative path of a supported language may leave the machine.
 function isWorthAsking(mutation: PendingMutation): boolean {
   return mutation.lines.length > 0 && isReviewablePath(mutation.relativePath);

package/extensions/jev/model.ts

@@ -11,12 +11,11 @@ export const JEV_MODEL = 'jev-latest';
 // noise on every edit.
 export const VIOLATION_PROBABILITY = 0.8;
 
-// The serialized state must stay well under the two documented budgets (64k
-// tokens for the whole request, 32k for the state plus the longest question). A
-// new file travels twice, as the body and as its added lines. A state 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';
 
@@ -31,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',
@@ -65,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',
       },
     },
   },
@@ -102,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: '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 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: '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;
@@ -121,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 {
@@ -148,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 },
   };
 }
 
@@ -168,19 +219,38 @@ export function addedLinesForEdit(
   return edits.flatMap((edit) => addedLines(edit.oldText, edit.newText));
 }
 
-// The six questions are about code structure; a README or a lockfile would
-// spend a call on answers that mean nothing.
+// 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 {
-  return JSON.stringify(state).length <= MAX_STATE_CHARACTERS;
+  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 };
@@ -197,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) {
@@ -204,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmrdeveloper/sideroom-pi",
-  "version": "8.10.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": [

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
 
@@ -90,3 +92,8 @@ At most three steers are sent per 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.