@rmrdeveloper/sideroom-pi 8.14.0 → 9.0.0

package/extensions/visual-context/source.ts

@@ -1,10 +1,15 @@
 import { readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
-import { extname, join, relative, sep } from 'node:path';
-import ignore from 'ignore';
+import { extname, isAbsolute, join, relative, sep } from 'node:path';
 import { projectRelativePath } from '../shared/file-path.ts';
 import { isMissingFile } from '../shared/read-file.ts';
+import {
+  allowedPath,
+  createPathPolicy,
+  MAX_FILE_BYTES,
+  type VisualPathPolicy,
+} from './files.ts';
 import { InvalidMarkup } from './markup.ts';
-import { matchSource, sourceFingerprint } from './match.ts';
+import { matchSource, sourceFingerprint, sourceMatches } from './match.ts';
 import {
   MAX_CANDIDATES,
   type SourceCandidate,
@@ -21,45 +26,42 @@ const SOURCE_EXTENSIONS = new Set([
   '.jsx',
   '.tsx',
 ]);
-const SKIP_DIRECTORIES = new Set([
-  'node_modules',
-  'dist',
-  'build',
-  'coverage',
-  'vendor',
-]);
-const IGNORE_FILES = ['.gitignore', '.ignore', '.fdignore'];
 const MAX_ENTRIES = 4_096;
-const MAX_FILE_BYTES = 262_144;
 const MAX_SOURCE_BYTES = 8_388_608;
 const MAX_DEPTH = 16;
-const SENSITIVE_NAME =
-  /secret|credential|password|private.?key|(?:^|[._-])env(?:[._-]|$)/iu;
 
 export function resolveSelection(
   cwd: string,
   selection: VisualSelection,
 ): SourceResolution {
+  if (selection.source) {
+    return resolveCompilerLocation({ cwd, selection });
+  }
+  return scanSource({ cwd, selection, paths: createPathPolicy(cwd) });
+}
+
+interface SourceScanInput {
+  readonly cwd: string;
+  readonly selection: VisualSelection;
+  readonly paths: VisualPathPolicy;
+}
+
+function scanSource({
+  cwd,
+  selection,
+  paths,
+}: SourceScanInput): SourceResolution {
   const root = realpathSync(cwd);
   const candidates: SourceCandidate[] = [];
   let entriesRead = 0;
   let sourceBytes = 0;
   let truncated = false;
-  function walk({
-    directory,
-    patterns,
-    depth,
-  }: {
-    readonly directory: string;
-    readonly patterns: readonly string[];
-    readonly depth: number;
-  }): void {
+  let capped = false;
+  function walk(directory: string, depth: number): void {
     if (depth > MAX_DEPTH) {
       truncated = true;
       return;
     }
-    const localPatterns = [...patterns, ...ignorePatterns(directory, root)];
-    const matcher = ignore().add(localPatterns);
     for (const entry of readdirSync(directory, { withFileTypes: true }).sort(
       (left, right) => left.name.localeCompare(right.name),
     )) {
@@ -68,30 +70,13 @@ export function resolveSelection(
         truncated = true;
         return;
       }
-      if (
-        entry.name.startsWith('.') ||
-        [...entry.name].some(
-          (character) =>
-            character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127,
-        ) ||
-        SENSITIVE_NAME.test(entry.name) ||
-        entry.isSymbolicLink()
-      ) {
+      const absolutePath = paths.allowedPath(join(directory, entry.name));
+      if (!absolutePath) {
         continue;
       }
-      const absolutePath = join(directory, entry.name);
       const path = relative(root, absolutePath).split(sep).join('/');
-      if (matcher.ignores(entry.isDirectory() ? `${path}/` : path)) {
-        continue;
-      }
       if (entry.isDirectory()) {
-        if (!SKIP_DIRECTORIES.has(entry.name)) {
-          walk({
-            directory: absolutePath,
-            patterns: localPatterns,
-            depth: depth + 1,
-          });
-        }
+        walk(absolutePath, depth + 1);
         continue;
       }
       if (
@@ -108,7 +93,14 @@ export function resolveSelection(
       sourceBytes += size;
       const source = readFileSync(absolutePath, 'utf8');
       try {
-        candidates.push(...matchSource({ path, source, selection }));
+        for (const candidate of sourceMatches({ path, source, selection })) {
+          candidates.push(candidate);
+          candidates.sort(compareCandidates);
+          if (candidates.length > MAX_CANDIDATES) {
+            capped = true;
+            candidates.pop();
+          }
+        }
       } catch (cause) {
         if (cause instanceof InvalidMarkup) {
           truncated = true;
@@ -118,73 +110,184 @@ export function resolveSelection(
       }
     }
   }
-  walk({ directory: root, patterns: [], depth: 0 });
-  candidates.sort(
-    (left, right) =>
-      right.score - left.score ||
-      left.path.localeCompare(right.path) ||
-      left.startLine - right.startLine,
+  walk(root, 0);
+  return { candidates, truncated, capped };
+}
+
+function compareCandidates(
+  left: SourceCandidate,
+  right: SourceCandidate,
+): number {
+  return (
+    right.score - left.score ||
+    left.path.localeCompare(right.path) ||
+    left.startLine - right.startLine
   );
-  return {
-    candidates: candidates.slice(0, MAX_CANDIDATES),
-    truncated,
-    capped: candidates.length > MAX_CANDIDATES,
-  };
 }
 
-function ignorePatterns(directory: string, root: string): readonly string[] {
-  const prefix = relative(root, directory).split(sep).join('/');
-  const patterns: string[] = [];
-  for (const file of IGNORE_FILES) {
-    let source: string;
-    try {
-      source = readFileSync(join(directory, file), 'utf8');
-    } catch (cause) {
-      if (isMissingFile(cause)) {
-        continue;
-      }
-      throw new Error(`Cannot read ignore file ${file}`, { cause });
+interface CompilerLocationInput {
+  readonly cwd: string;
+  readonly selection: VisualSelection;
+  readonly project?: string;
+}
+
+export function resolveCompilerLocation({
+  cwd,
+  selection,
+  project,
+}: CompilerLocationInput): SourceResolution {
+  const location = selection.source;
+  if (!location) {
+    throw new Error('A compiler source location is required.');
+  }
+  const unresolved = (issue: string): SourceResolution => ({
+    candidates: [],
+    truncated: false,
+    capped: false,
+    issue,
+  });
+  if (!isAbsolute(location.path) && project === undefined) {
+    return unresolved(
+      'Associate this page with a project in F7 before resolving a relative compiler path.',
+    );
+  }
+  const projectRoot = project === undefined ? cwd : allowedPath(cwd, project);
+  if (!projectRoot || !statSync(projectRoot).isDirectory()) {
+    return unresolved('The associated project is missing or excluded.');
+  }
+  const absolute = allowedPath(projectRoot, location.path);
+  if (
+    !absolute ||
+    !allowedPath(cwd, absolute) ||
+    !statSync(absolute).isFile() ||
+    statSync(absolute).size > MAX_FILE_BYTES
+  ) {
+    return unresolved(
+      'The compiler path is missing, excluded, outside the project, or too large.',
+    );
+  }
+  const path = relative(realpathSync(cwd), absolute).split(sep).join('/');
+  if (
+    ![...SOURCE_EXTENSIONS, '.js', '.mjs', '.ts', '.mts'].includes(
+      extname(path).toLowerCase(),
+    )
+  ) {
+    return unresolved('The compiler path has an unsupported source format.');
+  }
+  try {
+    const candidates = matchSource({
+      path,
+      source: readFileSync(absolute, 'utf8'),
+      selection,
+      location,
+    });
+    if (candidates.length !== 1) {
+      return unresolved(
+        'The compiler location does not match the selected tag in current local markup. Restart or refresh the development page.',
+      );
     }
-    for (const line of source.split(/\r?\n/u)) {
-      if (!line || line.startsWith('#')) {
-        continue;
-      }
-      const negated = line.startsWith('!');
-      const pattern = negated ? line.slice(1) : line;
-      const nested = prefix
-        ? `${prefix}/${pattern.startsWith('/') ? pattern.slice(1) : pattern.includes('/') ? pattern : `**/${pattern}`}`
-        : pattern;
-      patterns.push(`${negated ? '!' : ''}${nested}`);
+    return { candidates, truncated: false, capped: false };
+  } catch (cause) {
+    if (cause instanceof InvalidMarkup) {
+      return unresolved(
+        'The compiler source could not be parsed; its location was not accepted.',
+      );
     }
+    throw new Error(`Cannot verify compiler source ${path}`, { cause });
   }
-  return patterns;
+}
+
+export function resolveProjectSelection({
+  cwd,
+  selection,
+  project,
+}: CompilerLocationInput): SourceResolution {
+  if (selection.source) {
+    return resolveCompilerLocation({ cwd, selection, project });
+  }
+  if (project === undefined) {
+    return resolveSelection(cwd, selection);
+  }
+  const workspaceRoot = realpathSync(cwd);
+  const paths = createPathPolicy(workspaceRoot);
+  const root = paths.allowedPath(project);
+  if (!root || !statSync(root).isDirectory()) {
+    return {
+      candidates: [],
+      truncated: false,
+      capped: false,
+      issue: 'The associated project is missing or excluded.',
+    };
+  }
+  const resolution = scanSource({ cwd: root, selection, paths });
+  return {
+    ...resolution,
+    candidates: resolution.candidates
+      .filter((candidate) => paths.allowedPath(join(root, candidate.path)))
+      .map((candidate) => ({
+        ...candidate,
+        path: relative(workspaceRoot, join(root, candidate.path))
+          .split(sep)
+          .join('/'),
+      })),
+  };
 }
 
 export function candidateIsCurrent(
   cwd: string,
   candidate: SourceCandidate,
 ): boolean {
-  try {
-    const absolutePath = realpathSync(join(cwd, candidate.path));
-    if (
-      projectRelativePath(cwd, absolutePath) === undefined ||
-      statSync(absolutePath).size > MAX_FILE_BYTES
-    ) {
-      return false;
-    }
-    const source = readFileSync(absolutePath, 'utf8');
-    return (
-      sourceFingerprint(source) === candidate.fingerprint &&
-      candidate.endLine <= source.split('\n').length
-    );
-  } catch (cause) {
-    if (isGone(cause)) {
-      return false;
+  return currentCandidates(cwd, [candidate]).length === 1;
+}
+
+// Each call owns its file versions; no validation survives into another prompt.
+export function currentCandidates(
+  cwd: string,
+  candidates: readonly SourceCandidate[],
+): readonly SourceCandidate[] {
+  let paths: VisualPathPolicy | undefined;
+  const versions = new Map<
+    string,
+    { readonly fingerprint: string; readonly lines: number } | undefined
+  >();
+  return candidates.filter((candidate) => {
+    try {
+      paths ??= createPathPolicy(cwd);
+      const absolutePath = paths.allowedPath(candidate.path);
+      if (!absolutePath) {
+        return false;
+      }
+      if (!versions.has(absolutePath)) {
+        let version:
+          | { readonly fingerprint: string; readonly lines: number }
+          | undefined;
+        if (
+          projectRelativePath(cwd, absolutePath) !== undefined &&
+          statSync(absolutePath).size <= MAX_FILE_BYTES
+        ) {
+          const source = readFileSync(absolutePath, 'utf8');
+          version = {
+            fingerprint: sourceFingerprint(source),
+            lines: source.split('\n').length,
+          };
+        }
+        versions.set(absolutePath, version);
+      }
+      const version = versions.get(absolutePath);
+      return (
+        version !== undefined &&
+        version.fingerprint === candidate.fingerprint &&
+        candidate.endLine <= version.lines
+      );
+    } catch (cause) {
+      if (isGone(cause)) {
+        return false;
+      }
+      throw new Error(`Cannot verify selected source ${candidate.path}`, {
+        cause,
+      });
     }
-    throw new Error(`Cannot verify selected source ${candidate.path}`, {
-      cause,
-    });
-  }
+  });
 }
 
 // A path that turned into a file on the way reports ENOTDIR, which means the

package/extensions/visual-context/ui.ts

@@ -4,6 +4,7 @@ import {
   candidateLabel,
   elementLabel,
   type PendingSelection,
+  SOURCE_METHOD,
   VISUAL_WIDGET,
 } from './model.ts';
 
@@ -13,7 +14,10 @@ export const BROWSER_EXTENSION_DIRECTORY = fileURLToPath(
 
 function pendingLabel({ resolution, chosen }: PendingSelection): string {
   if (chosen) {
-    return `${candidateLabel(chosen)} (selected candidate)`;
+    return `${candidateLabel(chosen)}${chosen.startColumn ? `:${String(chosen.startColumn)}` : ''} (${chosen.method === SOURCE_METHOD.compiler ? 'compiler location checked' : 'selected candidate'})`;
+  }
+  if (resolution.issue) {
+    return resolution.issue;
   }
   const truncated = resolution.truncated ? ' · search truncated' : '';
   const capped = resolution.capped ? ' · more candidates' : '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmrdeveloper/sideroom-pi",
-  "version": "8.14.0",
+  "version": "9.0.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": [
@@ -81,8 +81,8 @@
     "video": "https://raw.githubusercontent.com/RMRdeveloper/sideroom-pi/main/media/preview.mp4"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
+    "@earendil-works/pi-coding-agent": ">=1.2.0",
+    "@earendil-works/pi-tui": ">=1.2.0",
     "typebox": "*"
   },
   "devDependencies": {
@@ -90,8 +90,8 @@
     "@changesets/cli": "^3.0.2",
     "@commitlint/cli": "^21.2.2",
     "@commitlint/config-conventional": "^21.2.2",
-    "@earendil-works/pi-coding-agent": "0.87.1",
-    "@earendil-works/pi-tui": "0.87.1",
+    "@earendil-works/pi-coding-agent": "1.2.0",
+    "@earendil-works/pi-tui": "1.2.0",
     "@types/node": "^22.20.1",
     "@types/ws": "^8.18.2",
     "fflate": "0.8.3",

package/skills/sideroom-guidelines/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sideroom-guidelines
-description: "Follow the mandatory coding workflow before any write or edit, including bug fixes, features, refactors, tests, configuration, and documentation edits. Read the complete skill first; also read the exact language guide for Java, PHP/Laravel, JavaScript/JSX, TypeScript/TSX, Python, Go, or Rust targets. Discussion or read-only investigation alone does not require loading it."
+description: "Follow the mandatory coding workflow before any write or edit, including bug fixes, features, refactors, tests, configuration, and documentation edits. Load the complete skill and exact language guide through sideroom_guidelines or full read calls for Java, PHP/Laravel, JavaScript/JSX, TypeScript/TSX, Python, Go, or Rust targets. Discussion or read-only investigation alone does not require loading it."
 license: MIT
 metadata:
   author: RMRdeveloper
@@ -11,12 +11,14 @@ metadata:
 
 ## Activation Contract
 
-Load this whole skill with `read`, without `offset` or `limit`, before the first `write` or `edit` in each agent run. Use the absolute skill path shown in Available Skills. For each supported target language, also fully load its exact guide from `references/languages/`.
+Before `write` or `edit`, call `sideroom_guidelines` with the target file's `path`. It returns this whole skill and the matching complete language guide, or only this skill for unsupported languages. Reuse loaded guides during the same agent run; load any additional target language before editing it. Reload after compaction or a new run.
+
+Alternatively, load this whole skill with `read`, without `offset` or `limit`, using the absolute packaged path shown in Available Skills. For each supported target language, also fully load its exact guide from `references/languages/`. Both routes satisfy the same gate only on successful, complete delivery.
 
 ## Hard Rules
 
 - Apply the loaded guide to changed code in the context of the full user requirements and established project contracts. Architectural rules require demonstrated evidence; KISS, DRY, and YAGNI never justify omitting requested behavior, required error handling, compatibility, or meaningful tests.
-- Do not write or edit until exact full-file reads of the required packaged paths succeed; partial reads and same-named files do not count.
+- Do not write or edit until the required packaged documents are fully loaded through `sideroom_guidelines` or exact full-file `read` calls; failed or partial loads and same-named files do not count.
 - Do not bypass the gate with Bash, a subprocess, or another mutation tool.
 - Do not load language guides unrelated to files being changed.
 - Fail fast, keep control flow flat, and validate once at the boundary.
@@ -36,8 +38,8 @@ Load this whole skill with `read`, without `offset` or `limit`, before the first
 
 ## Execution Steps
 
-1. Read this complete file from its packaged path before any mutation.
-2. Fully read the matching packaged language guide, if the target has a supported extension.
+1. Load this complete skill through `sideroom_guidelines` with the target path, or a full `read` of its packaged path, before any mutation.
+2. Ensure the matching complete language guide is loaded for supported extensions. The tool includes it automatically; with `read`, load it separately.
 3. Implement a focused change that satisfies all current requirements and preserves required existing behavior.
 4. Review the changes introduced by this run against the loaded guide; fix demonstrated violations caused by the change without refactoring unrelated code.
 5. Run the relevant formatter, linter, type checks, and tests before finishing.
@@ -51,6 +53,7 @@ Load this whole skill with `read`, without `offset` or `limit`, before the first
 | Explicit error, fail now | Fallbacks that hide the real failure |
 | One responsibility per unit | Validate + transform + persist + notify together |
 | Extract for real duplication, a present responsibility, or testability | Abstract only for hypothetical future reuse |
+| Decomposition by intent (rule 20): name a coherent operation so its caller reads the flow without implementation details, even with one caller | Split only to shorten functions, or separate coupled steps into shared mutable state, excessive parameters, or functions that must be read together |
 | Simplest design that satisfies the full requirements | Omit necessary structure to minimize code |
 | Implement current requirements and established contracts completely | Add capabilities only for hypothetical future cases |
 | Compose small focused units | Deep inheritance for unrelated behavior |

package/skills/sideroom-guidelines/references/languages/go.md

@@ -25,6 +25,7 @@ Rules every Go change must follow.
 | 17 | [Dependency direction](#17-dependency-direction) | architectural |
 | 18 | [Testability](#18-testability-as-a-design-constraint) | architectural |
 | 19 | [Comments](#19-comments) | architectural |
+| 20 | [Decomposition by intent](#20-decomposition-by-intent) | structural |
 
 ---
 
@@ -370,8 +371,41 @@ counter++
 ticker := time.NewTicker(5 * time.Second)
 ```
 
+### 20. Decomposition by intent
+
+RULE: Extract a block into a named function when it represents a coherent operation and its name and contract let the caller understand the flow without reading its implementation. Keep orchestration separate from implementation details. Do not split solely to reduce line count; keep tightly coupled steps together when separating them would introduce shared mutable state, excessive parameters, or require reading both functions to understand either.
+WHY: Good decomposition reduces how much a reader must understand at once. Function length is a review signal; extraction must improve comprehension rather than merely move code elsewhere.
+
+```go
+// bad
+func createPackingSlip(items []PackingItem, destination string) PackingSlip {
+	unitCount := 0
+	weightGrams := 0
+	for _, item := range items {
+		unitCount += item.Quantity
+		weightGrams += item.Quantity * item.UnitWeightGrams
+	}
+	return PackingSlip{Destination: destination, Totals: PackingTotals{UnitCount: unitCount, WeightGrams: weightGrams}}
+}
+
+// good
+func createPackingSlip(items []PackingItem, destination string) PackingSlip {
+	return PackingSlip{Destination: destination, Totals: calculatePackingTotals(items)}
+}
+
+func calculatePackingTotals(items []PackingItem) PackingTotals {
+	unitCount := 0
+	weightGrams := 0
+	for _, item := range items {
+		unitCount += item.Quantity
+		weightGrams += item.Quantity * item.UnitWeightGrams
+	}
+	return PackingTotals{UnitCount: unitCount, WeightGrams: weightGrams}
+}
+```
+
 ---
 
 **When in doubt:** fail fast, keep it flat, keep it small.
 
-**Enforcement note:** rules 1–2 are mechanical and should be backed by Go formatting or linting. Rules 3–10 are structural checks. Rules 11–19 require review judgment.
+**Enforcement note:** rules 1–2 are mechanical and should be backed by Go formatting or linting. Rules 3–10 and 20 are structural; rules 11–19 are architectural. Rule 20 requires semantic review, not a line-count limit or mechanical length detector. Rules 11–20 require review judgment.

package/skills/sideroom-guidelines/references/languages/java.md

@@ -25,6 +25,7 @@ Rules every Java change must follow.
 | 17 | [Dependency direction](#17-dependency-direction) | architectural |
 | 18 | [Testability](#18-testability-as-a-design-constraint) | architectural |
 | 19 | [Comments](#19-comments) | architectural |
+| 20 | [Decomposition by intent](#20-decomposition-by-intent) | structural |
 
 ---
 
@@ -250,8 +251,40 @@ counter.increment();
 scheduler.scheduleAtFixedRate(this::checkPaymentStatus, 0, 5, SECONDS);
 ```
 
+### 20. Decomposition by intent
+
+RULE: Extract a block into a named function when it represents a coherent operation and its name and contract let the caller understand the flow without reading its implementation. Keep orchestration separate from implementation details. Do not split solely to reduce line count; keep tightly coupled steps together when separating them would introduce shared mutable state, excessive parameters, or require reading both functions to understand either.
+WHY: Good decomposition reduces how much a reader must understand at once. Function length is a review signal; extraction must improve comprehension rather than merely move code elsewhere.
+
+```java
+// bad
+PackingSlip createPackingSlip(List<PackingItem> items, String destination) {
+    int unitCount = 0;
+    long weightGrams = 0;
+    for (PackingItem item : items) {
+        unitCount += item.quantity();
+        weightGrams += item.quantity() * item.unitWeightGrams();
+    }
+    return new PackingSlip(destination, new PackingTotals(unitCount, weightGrams));
+}
+// good
+PackingSlip createPackingSlip(List<PackingItem> items, String destination) {
+    return new PackingSlip(destination, calculatePackingTotals(items));
+}
+
+private PackingTotals calculatePackingTotals(List<PackingItem> items) {
+    int unitCount = 0;
+    long weightGrams = 0;
+    for (PackingItem item : items) {
+        unitCount += item.quantity();
+        weightGrams += item.quantity() * item.unitWeightGrams();
+    }
+    return new PackingTotals(unitCount, weightGrams);
+}
+```
+
 ---
 
 **When in doubt:** fail fast, keep it flat, keep it small.
 
-**Enforcement note:** rules 1–2 are mechanical and should be backed by Java formatting or linting. Rules 3–10 are structural checks. Rules 11–19 require review judgment.
+**Enforcement note:** rules 1–2 are mechanical and should be backed by Java formatting or linting. Rules 3–10 and 20 are structural; rules 11–19 are architectural. Rule 20 requires semantic review, not a line-count limit or mechanical length detector. Rules 11–20 require review judgment.

package/skills/sideroom-guidelines/references/languages/javascript.md

@@ -25,6 +25,7 @@ Rules every JavaScript change must follow.
 | 17 | [Dependency direction](#17-dependency-direction) | architectural |
 | 18 | [Testability](#18-testability-as-a-design-constraint) | architectural |
 | 19 | [Comments](#19-comments) | architectural |
+| 20 | [Decomposition by intent](#20-decomposition-by-intent) | structural |
 
 ---
 
@@ -377,11 +378,43 @@ counter++;
 setInterval(checkPaymentStatus, 5_000);
 ```
 
+### 20. Decomposition by intent
+
+RULE: Extract a block into a named function when it represents a coherent operation and its name and contract let the caller understand the flow without reading its implementation. Keep orchestration separate from implementation details. Do not split solely to reduce line count; keep tightly coupled steps together when separating them would introduce shared mutable state, excessive parameters, or require reading both functions to understand either.
+WHY: Good decomposition reduces how much a reader must understand at once. Function length is a review signal; extraction must improve comprehension rather than merely move code elsewhere.
+
+```js
+// bad
+function createPackingSlip(items, destination) {
+  let unitCount = 0;
+  let weightGrams = 0;
+  for (const item of items) {
+    unitCount += item.quantity;
+    weightGrams += item.quantity * item.unitWeightGrams;
+  }
+  return { destination, totals: { unitCount, weightGrams } };
+}
+// good
+function createPackingSlip(items, destination) {
+  return { destination, totals: calculatePackingTotals(items) };
+}
+
+function calculatePackingTotals(items) {
+  let unitCount = 0;
+  let weightGrams = 0;
+  for (const item of items) {
+    unitCount += item.quantity;
+    weightGrams += item.quantity * item.unitWeightGrams;
+  }
+  return { unitCount, weightGrams };
+}
+```
+
 ---
 
 **When in doubt:** fail fast, keep it flat, keep it small.
 
-**Enforcement note:** rules 1–2 are mechanical and should be backed by a JavaScript formatter/linter. Rules 3–10 are structural checks. Rules 11–19 require review judgment.
+**Enforcement note:** rules 1–2 are mechanical and should be backed by a JavaScript formatter/linter. Rules 3–10 and 20 are structural; rules 11–19 are architectural. Rule 20 requires semantic review, not a line-count limit or mechanical length detector. Rules 11–20 require review judgment.
 
 ## Language-specific conventions
 

package/skills/sideroom-guidelines/references/languages/php-laravel.md

@@ -25,6 +25,7 @@ Rules every PHP or Laravel change must follow.
 | 17 | [Dependency direction](#17-dependency-direction) | architectural |
 | 18 | [Testability](#18-testability-as-a-design-constraint) | architectural |
 | 19 | [Comments](#19-comments) | architectural |
+| 20 | [Decomposition by intent](#20-decomposition-by-intent) | structural |
 
 ---
 
@@ -241,8 +242,40 @@ RULE: Comment only non-obvious intent — a trade-off, a constraint, a hazard na
 Schedule::call($checkPaymentStatus)->everyFiveSeconds();
 ```
 
+### 20. Decomposition by intent
+
+RULE: Extract a block into a named function when it represents a coherent operation and its name and contract let the caller understand the flow without reading its implementation. Keep orchestration separate from implementation details. Do not split solely to reduce line count; keep tightly coupled steps together when separating them would introduce shared mutable state, excessive parameters, or require reading both functions to understand either.
+WHY: Good decomposition reduces how much a reader must understand at once. Function length is a review signal; extraction must improve comprehension rather than merely move code elsewhere.
+
+```php
+// bad
+function createPackingSlip(array $items, string $destination): PackingSlip {
+    $unitCount = 0;
+    $weightGrams = 0;
+    foreach ($items as $item) {
+        $unitCount += $item->quantity;
+        $weightGrams += $item->quantity * $item->unitWeightGrams;
+    }
+    return new PackingSlip($destination, new PackingTotals($unitCount, $weightGrams));
+}
+// good
+function createPackingSlip(array $items, string $destination): PackingSlip {
+    return new PackingSlip($destination, calculatePackingTotals($items));
+}
+
+function calculatePackingTotals(array $items): PackingTotals {
+    $unitCount = 0;
+    $weightGrams = 0;
+    foreach ($items as $item) {
+        $unitCount += $item->quantity;
+        $weightGrams += $item->quantity * $item->unitWeightGrams;
+    }
+    return new PackingTotals($unitCount, $weightGrams);
+}
+```
+
 ---
 
 **When in doubt:** fail fast, keep it flat, keep it small.
 
-**Enforcement note:** rules 1–2 are mechanical and should be backed by PHP/Laravel formatting or linting. Rules 3–10 are structural checks. Rules 11–19 require review judgment.
+**Enforcement note:** rules 1–2 are mechanical and should be backed by PHP/Laravel formatting or linting. Rules 3–10 and 20 are structural; rules 11–19 are architectural. Rule 20 requires semantic review, not a line-count limit or mechanical length detector. Rules 11–20 require review judgment.