@rmrdeveloper/sideroom-pi 8.10.0 → 8.12.0

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,118 @@ 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: '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',
+      },
+    },
+  },
+  {
+    id: 'testability',
+    question: {
+      type: NOUL_TYPE,
+      instructions:
+        'Do the added lines hardcode clock, network or randomness inside business logic, making deterministic tests difficult? Do not flag infrastructure adapters or entry points merely for using their own APIs.',
+      criteria: {
+        true: 'Business behavior directly depends on an uncontrollable external dependency with no visible injection point',
+        false:
+          'Dependencies are supplied, or the code is the adapter/composition boundary itself',
+      },
+    },
+  },
+  {
+    id: 'contract-compatibility',
+    question: {
+      type: NOUL_TYPE,
+      instructions:
+        'Do added lines change a function signature, return shape or behavior in a way that demonstrably conflicts with a supplied non-test consumer? Require a concrete mismatch in visible code; do not speculate about unseen callers.',
+      criteria: {
+        true: 'A supplied consumer calls or interprets the changed contract incompatibly',
+        false:
+          'Visible consumers remain compatible, or there is insufficient evidence',
+      },
+    },
+  },
+  {
+    id: 'test-quality',
+    question: {
+      type: NOUL_TYPE,
+      instructions:
+        'For behavior touched by the added lines, do supplied related tests have a demonstrable blind spot: assertions that cannot detect that behavior failing, or an explicit changed error branch left untested? Use both production and test bodies. Never infer absent repository coverage from missing files or partial context. Do not request tests that mirror implementation or cover unrelated code.',
+      criteria: {
+        true: 'Visible relevant tests fail to assert the changed observable behavior or a visible changed error case, with concrete evidence',
+        false:
+          'Assertions cover the behavior, the change is low-impact, or evidence is incomplete',
+      },
+    },
+  },
+  {
+    id: 'unnecessary-abstraction',
+    question: {
+      type: NOUL_TYPE,
+      instructions:
+        'Do the added lines introduce a demonstrably redundant layer or combine visibly different domain concepts solely for similar syntax? Require evidence in supplied bodies. A single caller, delegation, injection, compatibility or a clear responsibility is not by itself a violation. Never infer requirements are absent or recommend removing required behavior.',
       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 added abstraction duplicates an existing role without adding a contract, responsibility or testability, or mixes visibly distinct concepts',
+        false:
+          'It serves a present responsibility or contract, or evidence is insufficient',
       },
     },
   },
 ];
 
+export function isTestPath(path: string): boolean {
+  return /(?:^|\/)(?:__tests__|tests?|specs?)\/|(?:[._-](?:test|spec)|_test)\.[^/]+$|(?:^|\/)test_[^/]+$|Test\.java$/u.test(
+    path,
+  );
+}
+
+export interface JevRelatedFile {
+  readonly path: string;
+  readonly body: string;
+  readonly relation: 'imported' | 'consumer' | 'test';
+}
+
 export interface JevFileState {
   readonly file: {
     readonly path: string;
@@ -121,11 +223,15 @@ export interface JevFileState {
     readonly kind: string;
     readonly addedLines: readonly string[];
   };
+  readonly context: {
+    readonly files: readonly JevRelatedFile[];
+    readonly partial: boolean;
+  };
 }
 
 export interface JevRequestBody {
   readonly model: string;
-  readonly state: JevFileState;
+  readonly state: unknown;
   readonly questions: Readonly<Record<string, JevNoulQuestion>>;
 }
 
@@ -148,10 +254,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 +277,56 @@ 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;
+  return requestFitsBudget(buildRequestBody(state));
+}
+
+export function requestFitsBudget(request: JevRequestBody): boolean {
+  const longestQuestion = Object.values(request.questions).reduce(
+    (longest, question) =>
+      Math.max(longest, Buffer.byteLength(JSON.stringify(question))),
+    0,
+  );
+  return (
+    Buffer.byteLength(JSON.stringify(request.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 hasConsumer = file.context.files.some(
+    (related) => related.relation === 'consumer' && !isTestPath(related.path),
+  );
+  const hasTest =
+    isTestPath(file.file.path) ||
+    file.context.files.some((related) => isTestPath(related.path));
+  const hasProduction =
+    !isTestPath(file.file.path) ||
+    file.context.files.some((related) => !isTestPath(related.path));
+  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;
+    }
+    if (rule.id === 'contract-compatibility' && !hasConsumer) {
+      continue;
+    }
+    if (rule.id === 'test-quality' && (!hasTest || !hasProduction)) {
+      continue;
+    }
     questions[rule.id] = rule.question;
   }
   return { model: JEV_MODEL, state: file, questions };
@@ -197,18 +343,24 @@ 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) {
     return [];
   }
   const findings: JevFinding[] = [];
-  for (const rule of JEV_RULES) {
-    const answer = answers[rule.id];
-    if (answer === undefined || answer.noul < VIOLATION_PROBABILITY) {
+  for (const ruleId of askedRuleIds) {
+    const answer = answers[ruleId];
+    if (
+      answer === undefined ||
+      !Number.isFinite(answer.noul) ||
+      answer.noul > 1 ||
+      answer.noul < VIOLATION_PROBABILITY
+    ) {
       continue;
     }
-    findings.push({ ruleId: rule.id, probability: answer.noul });
+    findings.push({ ruleId, probability: answer.noul });
   }
   return findings;
 }
@@ -225,7 +377,7 @@ export function formatFindings(
     `Sideroom Jev review flagged ${path}:`,
     ...findings.map(
       (finding) =>
-        `- [${finding.ruleId}] Jev scored ${finding.probability.toFixed(2)} probability that the added lines break this rule. Verify against the loaded guide before changing anything.`,
+        `- [${finding.ruleId}] Jev scored ${finding.probability.toFixed(2)} probability of a review concern. Verify the supplied evidence and applicable contract against the loaded guide before changing anything. Missing context is not proof of a violation.`,
     ),
   ].join('\n');
 }

package/extensions/jev/workflow.ts

@@ -0,0 +1,188 @@
+import { type AskParams, parseAskParams } from '../ask/model.ts';
+import {
+  parseTodoParams,
+  TODO_STATUS,
+  type TodoItem,
+  type TodoToolParameters,
+} from '../todo/model.ts';
+import {
+  JEV_MODEL,
+  type JevFileState,
+  type JevNoulQuestion,
+  type JevRequestBody,
+  requestFitsBudget,
+} from './model.ts';
+
+const MAX_EVIDENCE_FILES = 4;
+
+type ChangedFileEvidence = Pick<JevFileState, 'file' | 'change'>;
+
+export interface WorkflowEvidence {
+  readonly files: Map<string, ChangedFileEvidence>;
+  readonly completed: Map<string, string>;
+  partial: boolean;
+  checks: 'unknown' | 'passed' | 'failed' | 'stale';
+}
+
+export function createWorkflowEvidence(): WorkflowEvidence {
+  return {
+    files: new Map(),
+    completed: new Map(),
+    partial: false,
+    checks: 'unknown',
+  };
+}
+
+export function resetWorkflowEvidence(evidence: WorkflowEvidence): void {
+  evidence.files.clear();
+  evidence.completed.clear();
+  evidence.partial = false;
+  evidence.checks = 'unknown';
+}
+
+export function recordFileEvidence(
+  evidence: WorkflowEvidence,
+  file: JevFileState,
+): void {
+  evidence.checks = 'stale';
+  evidence.files.delete(file.file.path);
+  evidence.files.set(file.file.path, { file: file.file, change: file.change });
+  if (evidence.files.size > MAX_EVIDENCE_FILES) {
+    const oldest = evidence.files.keys().next().value;
+    if (oldest !== undefined) {
+      evidence.files.delete(oldest);
+    }
+    evidence.partial = true;
+  }
+}
+
+function question(instructions: string, violation: string): JevNoulQuestion {
+  return {
+    type: 'noul',
+    instructions,
+    criteria: {
+      true: violation,
+      false:
+        'No concrete contradiction is visible, or the supplied evidence is insufficient',
+    },
+  };
+}
+
+export function buildAskReview(input: unknown): JevRequestBody | undefined {
+  const parsed = parseAskParams(input as AskParams);
+  if (!parsed.ok) {
+    return undefined;
+  }
+  const request: JevRequestBody = {
+    model: JEV_MODEL,
+    state: { kind: 'questionnaire', questions: parsed.questions },
+    questions: {
+      'question-options': question(
+        'Do the supplied questions contain overlapping single-selection options or bundle independent decisions so no option can express a reasonable combination? Multiple selections may intentionally overlap. Judge only the question text, not unseen requirements.',
+        'The wording visibly prevents a clear independent choice',
+      ),
+      'question-recommendation': question(
+        'Does a recommended option claim factual certainty or decisive cost/performance figures without support in the supplied question, or contradict its stated constraints? A preference alone need not include proof. Do not assume unseen project evidence is absent; flag only a demonstrably unsupported assertion or contradiction in the wording.',
+        'The recommendation visibly contradicts stated constraints or asserts an unsupported decisive fact',
+      ),
+    },
+  };
+  return requestFitsBudget(request) ? request : undefined;
+}
+
+export function completedItems(
+  details: unknown,
+): readonly TodoItem[] | undefined {
+  if (typeof details !== 'object' || details === null || 'error' in details) {
+    return undefined;
+  }
+  const parsed = parseTodoParams({
+    action: 'propose',
+    items: 'items' in details ? details.items : undefined,
+  } as TodoToolParameters);
+  if (!parsed.ok || parsed.params.action !== 'propose') {
+    return undefined;
+  }
+  return parsed.params.items.filter(
+    (item) => item.status === TODO_STATUS.completed,
+  );
+}
+
+export function buildBoardReview({
+  items,
+  evidence,
+  changedIds,
+}: {
+  readonly items: readonly TodoItem[];
+  readonly evidence: WorkflowEvidence;
+  readonly changedIds?: ReadonlySet<string>;
+}): JevRequestBody | undefined {
+  const newlyCompleted = items.filter(
+    (item) =>
+      (changedIds === undefined || changedIds.has(item.id)) &&
+      evidence.completed.get(item.id) !== item.content,
+  );
+  evidence.completed.clear();
+  for (const item of items) {
+    evidence.completed.set(item.id, item.content);
+  }
+  if (
+    newlyCompleted.length === 0 ||
+    (evidence.files.size === 0 &&
+      evidence.checks !== 'passed' &&
+      evidence.checks !== 'failed')
+  ) {
+    return undefined;
+  }
+  const files: ChangedFileEvidence[] = [];
+  const state = {
+    kind: 'completion',
+    items: newlyCompleted,
+    evidence: { files, checks: evidence.checks, partial: evidence.partial },
+  };
+  const request: JevRequestBody = {
+    model: JEV_MODEL,
+    state,
+    questions: {
+      'board-completion': question(
+        'Do the newly completed tasks make a concrete claim contradicted by the supplied code changes or check status? Check status concerns only the detected project check in this user turn and becomes stale after a mutation. Missing evidence, unknown/stale checks and partial files do not prove unfinished work. Do not require every task to involve code or tests. Flag only an explicit mismatch, such as claiming checks passed when the observed latest checks failed.',
+        'A completed task claims behavior or a check result demonstrably contradicted by visible evidence',
+      ),
+    },
+  };
+  for (const file of evidence.files.values()) {
+    files.push(file);
+    if (!requestFitsBudget(request)) {
+      files.pop();
+      state.evidence.partial = true;
+    }
+  }
+  return (files.length > 0 ||
+    evidence.checks === 'passed' ||
+    evidence.checks === 'failed') &&
+    requestFitsBudget(request)
+    ? request
+    : undefined;
+}
+
+export function completionIds(input: unknown): ReadonlySet<string> {
+  const parsed = parseTodoParams(input as TodoToolParameters);
+  if (!parsed.ok) {
+    return new Set();
+  }
+  if (parsed.params.action === 'propose') {
+    return new Set(
+      parsed.params.items
+        .filter((item) => item.status === TODO_STATUS.completed)
+        .map((item) => item.id),
+    );
+  }
+  return new Set(
+    parsed.params.patches
+      .filter(
+        (patch) =>
+          patch.status === TODO_STATUS.completed || patch.content !== undefined,
+      )
+      .map((patch) => patch.id),
+  );
+}

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/execute.ts

@@ -1,8 +1,6 @@
-import {
-  formatPersonaDetail,
-  type PersonaToolDetails,
-  personaToolDetails,
-} from './model.ts';
+import { readFileSync } from 'node:fs';
+import { PERSONA_SKILL_PATH } from './catalog.ts';
+import { type PersonaToolDetails, personaToolDetails } from './model.ts';
 
 export interface PersonaToolResult {
   readonly content: { readonly type: 'text'; readonly text: string }[];
@@ -11,7 +9,7 @@ export interface PersonaToolResult {
 
 export function executePersona(): PersonaToolResult {
   return {
-    content: [{ type: 'text', text: formatPersonaDetail() }],
+    content: [{ type: 'text', text: readFileSync(PERSONA_SKILL_PATH, 'utf8') }],
     details: personaToolDetails(),
   };
 }

package/extensions/persona/index.ts

@@ -15,9 +15,10 @@ import { personaStatusLabel } from './model.ts';
 import { appendPersonaReminder } from './prompt.ts';
 
 export const PERSONA_DESCRIPTION =
-  "Read Sideroom's voice rules and hard prohibitions for user-facing answers.";
+  'Load the complete Sideroom writing guide before a substantial explanation, findings report, implementation summary, or user-facing documentation; also use when asked for clearer, shorter, or less technical wording. Reuse while in context.';
 
-export const PERSONA_PROMPT_SNIPPET = 'Read the active Sideroom persona.';
+export const PERSONA_PROMPT_SNIPPET =
+  'Load the complete writing guide before substantial user-facing prose.';
 
 // Pi loads extensions/*/index.ts through export default.
 export default function registerPersona(pi: ExtensionAPI): void {

package/extensions/persona/model.ts

@@ -1,11 +1,4 @@
-import {
-  PERSONA_SKILL_PATH,
-  PERSONA_TOOL_NAME,
-  PROHIBITIONS,
-  type Prohibition,
-  TEXT_SCOPE,
-  VOICE_RULES,
-} from './catalog.ts';
+import { PERSONA_TOOL_NAME, PROHIBITIONS, VOICE_RULES } from './catalog.ts';
 import type { ProhibitionViolation } from './checks.ts';
 
 // Pi narrows these blocks before handing the message over; the shape is
@@ -45,22 +38,6 @@ export function personaToolDetails(): PersonaToolDetails {
   };
 }
 
-export function formatPersonaDetail(): string {
-  return [
-    'Sideroom persona: one always-on voice; no profiles or switching.',
-    '',
-    'Voice rules',
-    ...VOICE_RULES.map((rule) => `- ${rule.instruction}`),
-    '',
-    'Hard prohibitions',
-    ...PROHIBITIONS.map(
-      (prohibition) => `- ${prohibition.rule} (${enforcementOf(prohibition)})`,
-    ),
-    '',
-    `Complete guide: ${PERSONA_SKILL_PATH}`,
-  ].join('\n');
-}
-
 export function formatBlockReason(
   path: string,
   violations: readonly ProhibitionViolation[],
@@ -112,10 +89,3 @@ export function assistantMessageText(content: readonly TextBlock[]): string {
   }
   return parts.join('\n');
 }
-
-function enforcementOf(prohibition: Prohibition): string {
-  if (prohibition.scopes.includes(TEXT_SCOPE.artifact)) {
-    return 'blocked on write and edit';
-  }
-  return 'corrected with a steer';
-}

package/extensions/persona/prompt.ts

@@ -18,17 +18,19 @@ 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}
+Apply this voice to progress messages, final answers, and user-facing documentation.
 Voice: ${VOICE_SUMMARY}
 Never: ${PROHIBITION_SUMMARY}
 ${ENFORCEMENT_SUMMARY}
 Examples:
 ${PERSONA_EXAMPLES.join('\n')}
-Full guide: call ${PERSONA_TOOL_NAME} or read ${PERSONA_SKILL_PATH}.`;
+Before the first substantial explanation or report, call ${PERSONA_TOOL_NAME} or read ${PERSONA_SKILL_PATH}; reuse the complete guide while it remains in context.
+Before sending prose, check: outcome first, necessary terms explained, no repetition or invented labels. Preserve evidence and requested detail.`;
 
 export function appendPersonaReminder(systemPrompt: string): string {
   if (systemPrompt.includes(PERSONA_REMINDER_HEADING)) {