@rmrdeveloper/sideroom-pi 8.13.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.13.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-codebase-design/SKILL.md

@@ -4,7 +4,7 @@ description: "Improve an existing codebase for long-term maintainability and sca
 license: MIT
 metadata:
   author: RMRdeveloper
-  version: "1.0"
+  version: "1.1"
 ---
 
 # Sideroom codebase design
@@ -33,6 +33,29 @@ A review request does not authorize a rewrite. An implementation request does
 not require pausing after every recommendation. Ask only about consequential
 choices or missing facts that the user and repository have not settled.
 
+## Vocabulary (use these terms exactly)
+
+Use these terms consistently in all recommendations and designs. Do not substitute "component", "service", "API", "boundary", "unit" or similar loose words. Consistent language is the point.
+
+| Term | Meaning | Avoid |
+|------|---------|-------|
+| **Module** | Anything with an interface and an implementation. Scale-agnostic: a function, class, package, or tier-spanning slice. | unit, component, service |
+| **Interface** | Everything a caller must know to use the module correctly: the type signature, plus invariants, ordering constraints, error modes, required configuration, and relevant performance or resource behaviour. | API, signature |
+| **Implementation** | The code inside the module. Distinct from Adapter. | — |
+| **Depth** | Leverage at the interface: the amount of useful behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface, **shallow** when the interface is nearly as complex as the implementation. | — |
+| **Seam** | A place where you can alter behaviour without editing in that place (Michael Feathers). It is the *location* at which a module's interface lives. Where to put the seam is its own design decision, distinct from what goes behind it. | boundary |
+| **Adapter** | A concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance. | — |
+| **Leverage** | What callers get from depth: more capability per unit of interface they learn. One implementation pays back across many call sites and tests. | — |
+| **Locality** | What maintainers get from depth: change, bugs, knowledge, and verification concentrate in one place rather than spreading across callers. | — |
+
+**Principles that follow from the vocabulary:**
+- Depth is a property of the **interface**, not of the implementation size. A deep module can be internally composed of small, mockable, swappable parts; they just aren't part of the interface.
+- The **deletion test**: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across callers, it was earning its keep.
+- The interface is the test surface. Callers and tests cross the same seam. If you want to test past the interface, the module is probably the wrong shape.
+- One adapter means a hypothetical seam. Two adapters (e.g. production + test stand-in) means a real one. Don't introduce a seam unless something actually varies across it.
+
+When writing recommendations, use these terms. Explain any necessary design term once if the user is unfamiliar, then stick to them. Respect the project's existing domain vocabulary (`CONTEXT.md` or equivalent) for business concepts — do not replace established domain names just to impose this design glossary.
+
 ## Inspect before recommending
 
 1. Read project instructions, existing domain vocabulary (`CONTEXT.md`, or the
@@ -55,6 +78,8 @@ choices or missing facts that the user and repository have not settled.
 
 ## Design principles
 
+Apply the vocabulary above. In particular:
+
 - A **module** presents an **interface** and hides an implementation. Its
   interface includes everything callers must understand: inputs, outputs,
   invariants, errors, ordering, configuration, and relevant resource behavior.
@@ -141,6 +166,8 @@ verification, and unresolved facts. After implementation, report changes,
 checks, and remaining limitations. Keep review results in the conversation
 unless the user requests a document. No graphic or HTML artifact is produced.
 
+**Use the design vocabulary (module, interface, depth, seam, adapter, leverage, locality) consistently** in all recommendations and designs.
+
 ## Attribution
 
 Adapted from Matt Pocock's

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.