@rmrdeveloper/sideroom-pi 8.11.0 → 8.12.0

package/extensions/shared/settle.ts

@@ -1,13 +1,31 @@
 import type {
   AgentBeforeSettleEvent,
   AgentBeforeSettleEventResult,
+  ExtensionAPI,
+  ExtensionContext,
   InputEvent,
   InputSource,
 } from '@earendil-works/pi-coding-agent';
 
 const COMPLETED_OUTCOME = 'completed';
-const USER_ROLE = 'user';
 const CUSTOM_MESSAGE_ENTRY = 'custom_message';
+const SETTLE_PRIORITY_EVENT = 'sideroom:settle-priority';
+
+export const SETTLE_PRIORITY = { review: 0, done: 1, explain: 2 } as const;
+
+interface SettlePriorityRequest {
+  readonly ctx: ExtensionContext;
+  readonly priorities: Set<number>;
+}
+
+interface SettleGuard {
+  readonly priority: number;
+  readonly pending: (ctx: ExtensionContext) => boolean;
+  readonly handle: (
+    event: AgentBeforeSettleEvent,
+    ctx: ExtensionContext,
+  ) => AgentBeforeSettleEventResult | undefined;
+}
 const USER_INPUT_SOURCES: ReadonlySet<InputSource> = new Set([
   'interactive',
   'rpc',
@@ -22,24 +40,56 @@ export function startsUserTurn(event: InputEvent): boolean {
   );
 }
 
-// An aborted run is the user stopping the agent, an errored run has nothing
-// worth reviewing, and a pending user message already decides what comes next.
+// Any queued message or an earlier handler's continuation still has work to
+// run. Yield without consuming the guard's state until a quiet boundary.
 export function acceptsSettleSteer(event: AgentBeforeSettleEvent): boolean {
-  if (event.outcome !== COMPLETED_OUTCOME) {
-    return false;
-  }
-  return !event.context.pendingMessages.some(
-    (message) => message.role === USER_ROLE,
+  return (
+    event.outcome === COMPLETED_OUTCOME &&
+    !event.continue &&
+    event.context.pendingMessages.length === 0
   );
 }
 
+// Pi gives each extension its own API object. Its synchronous event bus is
+// shared, so ask which stages are pending rather than relying on load order
+// or module-global state that would leak across sessions and reloads.
+export function registerSettleGuard(
+  pi: ExtensionAPI,
+  guard: SettleGuard,
+): void {
+  pi.events.on(SETTLE_PRIORITY_EVENT, (payload) => {
+    const request = payload as SettlePriorityRequest;
+    if (guard.pending(request.ctx)) {
+      request.priorities.add(guard.priority);
+    }
+  });
+
+  pi.on('agent_before_settle', (event, ctx) => {
+    if (!acceptsSettleSteer(event) || !guard.pending(ctx)) {
+      return;
+    }
+    const request: SettlePriorityRequest = { ctx, priorities: new Set() };
+    pi.events.emit(SETTLE_PRIORITY_EVENT, request);
+    if ([...request.priorities].some((priority) => priority < guard.priority)) {
+      return;
+    }
+    return guard.handle(event, ctx);
+  });
+}
+
 // Handlers chain on agent_before_settle, so keep the entries earlier handlers
 // proposed; replacing them would drop another extension's steer.
-export function withHiddenSteer(
-  event: AgentBeforeSettleEvent,
-  customType: string,
-  content: string,
-): AgentBeforeSettleEventResult {
+interface HiddenSteerOptions {
+  readonly event: AgentBeforeSettleEvent;
+  readonly customType: string;
+  readonly content: string;
+}
+
+export function withHiddenSteer({
+  event,
+  customType,
+  content,
+}: HiddenSteerOptions): AgentBeforeSettleEventResult {
   return {
     entries: [
       ...event.entries,

package/package.json

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

@@ -1,6 +1,6 @@
 ---
 name: sideroom-architecture
-description: "Surface the architectural decisions a change forces so they are asked, not silently assumed. Use when a feature or change touches module boundaries, data ownership, integration contracts, failure behavior, quality attributes, operations, cost, lock-in, or reversibility, or when the user says the architecture is not settled. Do not use for a trivial or reversible change, a pure glossary lookup, or an already-closed spec."
+description: "Resolve architectural choices before code: module boundaries, data ownership, API or integration contracts, persistence, failure and retry behavior, deployment, capacity, cost, or provider choice. Use when designing or changing these and the repository or user has not settled the choice, even if the feature requirements are clear. Skip routine changes that reuse established contracts; use sideroom-grill when the broader plan is also open."
 license: MIT
 metadata:
   author: RMRdeveloper
@@ -25,8 +25,10 @@ throughput, availability), operations, cost, lock-in, or the difficulty of
 changing course later. It runs under `sideroom-grill` for the architectural
 part of an interview, and on its own when only the architecture is open.
 
-Do not load it for a minor decision (reversible, no boundary or contract
-impact), or for a word conflict — that is `sideroom-domain-modeling`.
+Clear feature requirements do not settle the architecture by themselves.
+Load this skill if a consequential choice remains, even when it is reversible.
+Do not load it for routine changes that reuse established boundaries and
+contracts, or for a word conflict — that is `sideroom-domain-modeling`.
 
 ## Hard Rules
 

package/skills/sideroom-codebase-design/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/sideroom-codebase-design/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: sideroom-codebase-design
+description: "Improve an existing codebase for long-term maintainability and scale. Use when asked to review code structure, find refactoring opportunities, reduce coupling, redesign module interfaces, improve testability, or prepare code for growing traffic, data, features, or teams. Survey the relevant code, prioritize evidenced friction, and design incremental improvements in text. Also use during a substantial refactor when module shape is the problem. Skip routine fixes, cosmetic cleanup, and unsettled product requirements; use sideroom-grill for those requirements."
+license: MIT
+metadata:
+  author: RMRdeveloper
+  version: "1.0"
+---
+
+# Sideroom codebase design
+
+Improve how an existing codebase absorbs change and known growth. Combine a
+survey of architectural friction with concrete module design. Deliver prose,
+Markdown tables, and code examples when useful. Do not generate diagrams,
+graphs, images, SVG, Mermaid, HTML reports, or browser previews.
+
+## Activation and scope
+
+Load for repository improvement, architecture reviews, module redesign,
+refactoring, testability problems, or preparation for long-term growth. A user
+does not need to name the skill. When a specific module is already chosen,
+inspect its callers and dependencies and go straight to design; a whole-repo
+survey is unnecessary.
+
+Determine the requested outcome from the conversation:
+
+- **Review:** investigate and recommend; do not refactor or create report files.
+- **Design:** propose the shape of a selected improvement and its migration.
+- **Implement:** carry out improvements within the already authorized scope,
+  including checks. Do not ask again for permission already given.
+
+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.
+
+## Inspect before recommending
+
+1. Read project instructions, existing domain vocabulary (`CONTEXT.md`, or the
+   project's equivalent), and relevant ADRs. Respect existing contracts.
+2. Start with the area or pain point the user named. Otherwise, use available
+   history to find areas with repeated changes, fixes, or coordinated edits;
+   verify the friction in current code. History is a lead, not proof. If history
+   is absent or uninformative, follow central business flows and their tests.
+3. Trace representative behavior from entry point through domain logic and
+   persistence or external calls. Inspect real callers, configuration, error
+   handling, tests, and operational evidence available in scope.
+4. Identify what makes changes costly: knowledge duplicated across callers,
+   hidden ordering constraints, leaked internals, coupled release changes,
+   brittle test setup, resource bottlenecks, or unclear ownership. Cite actual
+   files and behavior. File length, folder count, or a missing pattern alone is
+   not an architectural finding.
+5. For growth concerns, load [references/growth.md](references/growth.md).
+   Separate verified constraints from assumptions. Missing production metrics
+   are a limitation, not permission to invent capacity claims.
+
+## Design principles
+
+- 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.
+- Seek **depth**: useful behavior behind a small, coherent interface. Evaluate
+  the knowledge and coordination removed from callers, not implementation size.
+  Internally compose focused responsibilities; depth does not justify a god
+  object or combining unrelated reasons to change.
+- Use the **deletion test**: if removing a wrapper eliminates complexity without
+  spreading obligations into callers, consider removing it. If callers must
+  each reconstruct important rules, the module is doing useful work.
+- A **seam** is a point where behavior can be substituted; an **adapter** is a
+  concrete substitute there. Introduce seams for actual variation, isolation,
+  or testing needs. Production and test adapters can justify a seam; a generic
+  port with one implementation and no demonstrated need does not.
+- Improve **locality** by keeping a business rule and its verification in a
+  clear place. Improve **leverage** by letting callers use that behavior without
+  learning its internal machinery. Explain these benefits in plain words.
+- Preserve required validation, failure handling, compatibility, and supported
+  behavior. Simplicity is assessed against the full requirements.
+
+Use the project's domain names in code. Explain necessary design terms once;
+do not replace established vocabulary just to impose this glossary.
+
+## Prioritize and design
+
+For each worthwhile candidate, state the evidence, current cost, proposed
+change, expected benefit, migration cost, and confidence. Rank by avoided
+defects and change cost, known growth needs, reach, effort, and reversibility.
+Do not invent numerical scores or fill a quota of findings.
+
+Use **Strong** for demonstrated friction with a defensible remedy, **Worth
+exploring** when an important fact or experiment is still needed, and
+**Speculative** for an unverified future concern. Speculative findings become
+measurement or monitoring steps, not implementation tasks. Say when no
+structural improvement is justified. Flag a conflicting ADR and explain the
+new evidence before proposing to reopen it.
+
+For the selected candidate:
+
+1. State the behavior and compatibility constraints that must survive.
+2. Describe the interface and show a representative caller when helpful. Name
+   inputs, outputs, errors, ownership, and ordering obligations. State which
+   complexity moves inside and which responsibilities remain separate.
+3. For a meaningful trade-off, compare genuinely different designs, including
+   keeping the current design when viable. Compare caller burden, change
+   locality, tests, operational cost, and migration; recommend one. Routine
+   improvements need no forced alternatives or subagents.
+4. Classify dependencies: computation can be tested directly; local resources
+   may use realistic test substitutes; owned remote services need contract and
+   failure coverage; external providers need controlled adapters and suitable
+   integration checks. Do not expose private implementation details only to
+   make tests easier, or claim mocks establish real provider behavior.
+5. Plan small coherent steps with their checks and rollback. Keep callers
+   working during transition, handle data migrations and mixed versions where
+   relevant, and remove temporary compatibility code only when safe.
+
+## Verification and skill composition
+
+Test observable behavior through the interface used by callers. Preserve
+regression coverage, failure cases, and compatibility. Replace redundant tests
+only after equivalent behavior is covered and obsolete seams are removed;
+do not delete tests merely because they inspect a smaller function. For scale
+claims, identify the workload and measurement that would validate the benefit.
+
+- Load `sideroom-guidelines` and applicable language guides before edits.
+- Use `sideroom-architecture` for unresolved consequential contracts, data,
+  dependencies, or operational choices; reuse decisions already accepted.
+- Use `sideroom-grill` when the product behavior itself is still open, and
+  `sideroom-domain-modeling` for actual naming conflicts. A design review does
+  not automatically launch an interview or write a glossary or ADR.
+- In the TUI, use `sideroom_ask` for needed decisions. If no interactive question
+  tool is available, state the question in the conversation and continue only
+  independent investigation; never interpret tool failure as an answer.
+- Apply `sideroom-persona` to the report and summary. Run the project's relevant
+  checks after implementation and report what they established.
+
+## Output
+
+Lead with the highest-value recommendation or the finding that no change is
+justified. A review contains prioritized candidates with file evidence,
+before/after behavior in words, benefit, cost, confidence, and a recommended
+next step. A design contains the proposed contract, trade-offs, migration,
+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.
+
+## Attribution
+
+Adapted from Matt Pocock's
+[codebase-design](https://github.com/mattpocock/skills/tree/main/skills/engineering/codebase-design)
+and
+[improve-codebase-architecture](https://github.com/mattpocock/skills/tree/main/skills/engineering/improve-codebase-architecture),
+with Sideroom routing, incremental delivery, and growth assessment. The upstream
+MIT notice is included in [LICENSE.txt](LICENSE.txt).

package/skills/sideroom-codebase-design/references/growth.md

@@ -0,0 +1,62 @@
+# Assess long-term growth
+
+Read when the request concerns scaling, growing teams, or future evolution.
+Choose the dimensions the current code and requested outcome actually touch.
+Do not make the user complete a generic capacity questionnaire.
+
+## Establish the growth pressure
+
+Distinguish three kinds of growth:
+
+- **Behavior:** more features, business rules, integrations, and supported
+  versions. Inspect whether each addition requires coordinated changes across
+  unrelated files or duplicated decisions.
+- **People:** more contributors, ownership boundaries, and concurrent changes.
+  Inspect contracts, dependency cycles, shared state, release coupling, and
+  whether a contributor can change one responsibility with bounded context.
+- **Workload:** more requests, stored data, concurrency, or background jobs.
+  Inspect resource bounds, work per operation, contention, and failure behavior.
+
+Use existing requirements, code, tests, measurements, incident notes, and
+available history. State the current baseline, expected direction or target,
+and time horizon when known. Ask only for missing figures that would change
+the design choice. A code review can improve changeability without inventing
+traffic forecasts or blocking on production access.
+
+## Check constraints, then choose mechanisms
+
+| Evidence to inspect | Question to resolve |
+| --- | --- |
+| Unbounded lists, scans, buffers, or queries in a critical path | What bounds the work and memory as data grows? Is pagination, indexing, or batching justified by actual access patterns? |
+| Shared mutable state, global locks, synchronous I/O, or long transactions | Where does concurrent work serialize, and which ownership or consistency guarantees must survive? |
+| Retries, external calls, job queues, and duplicate events | What is bounded, cancellable, idempotent, or allowed to degrade? What happens when a dependency slows down? |
+| Cross-module rules, coordinated edits, and shared releases | Which stable contract would let an ordinary feature change stay local? |
+| Schema changes, public interfaces, and multiple deployed versions | How can old and new consumers coexist, and what makes migration or rollback safe? |
+| Existing service boundaries and operations | Does distribution solve a measured constraint enough to pay for network failures, deployment, tracing, and coordination? |
+
+Separate a code-level risk from a measured bottleneck. For example, an unbounded
+query is observable in code, but its production latency impact needs a known
+dataset and workload. A static review alone does not prove a capacity limit.
+
+Do not default to microservices, queues, caches, plugin systems, or generic
+repositories. Compare a simpler change inside the existing deployment first.
+Prefer an evolution path with explicit contracts and small migrations over
+building unused capabilities. A user's known growth requirement counts as a
+real need, even before the traffic arrives.
+
+## Make the recommendation falsifiable
+
+For a proposed scale improvement, state:
+
+- The observed constraint and the evidence supporting it.
+- The workload, data shape, or development scenario that matters.
+- The mechanism expected to help and its cost or new failure mode.
+- The relevant check: behavioral regression, concurrency test, query plan,
+  representative load measurement, or evidence that fewer callers must change.
+- The success criterion supplied by requirements or established baseline.
+  If missing, label it unresolved instead of inventing an improvement percentage.
+
+Organize longer work as **now**, **next**, and **when triggered**. Each later
+step names the growth event or measurement that would justify it. Include
+dependency order, transition risks, and rollback for the proposed migration.
+Do not turn hypothetical concerns into a backlog of mandatory refactors.

package/skills/sideroom-domain-modeling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sideroom-domain-modeling
-description: "Resolve domain-language conflicts and naming decisions. Use when terms are ambiguous, overloaded, or used inconsistently; when deciding what belongs in CONTEXT.md; or when a domain choice may need an ADR. Use for one or a few terms, not for simply reading CONTEXT.md, scanning an entire repository, or reshaping modules."
+description: "Resolve ambiguous business terms, entity names, statuses, or relationships while designing or changing domain code. Use when one term has multiple meanings, code and glossary disagree, or a resolved term belongs in CONTEXT.md; also handles qualifying ADRs. A full interview is not required. Skip mechanical symbol renames and glossary lookups; use sideroom-domain-scaffold for a repository-wide glossary."
 license: MIT
 metadata:
   author: RMRdeveloper

package/skills/sideroom-domain-scaffold/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sideroom-domain-scaffold
-description: "Build or complete a code-first CONTEXT.md for a repository with missing or thin domain vocabulary. Use when the user asks to document or survey the repo, scaffold a brownfield glossary, or derive domain terms from central business code. Do not use for resolving one naming conflict or conducting an interactive design interview."
+description: "Derive and merge a domain glossary in CONTEXT.md from existing business code. Use when asked to document domain vocabulary, explain business entities and relationships across a repository, or build or complete a brownfield glossary. Resolve terms from code and collect conflicts for later questions. Skip generic README or API documentation, a single naming conflict, and feature planning."
 license: MIT
 metadata:
   author: RMRdeveloper
@@ -11,9 +11,11 @@ metadata:
 
 ## Activation Contract
 
-Load this skill on explicit request ("document my repo", "scaffold the
-glossary") over a codebase whose domain language is missing or thin. The
-code is the source of truth. Nobody is interviewed while the modeling runs.
+Load this skill when a request calls for deriving or completing domain
+vocabulary across an existing codebase ("document the business entities",
+"scaffold the glossary", "explain the domain and its relationships"). A
+generic request to document a repository needs this skill only when domain
+vocabulary is part of the requested output. The code is the source of truth. Nobody is interviewed while the modeling runs.
 
 ## Hard Rules
 

package/skills/sideroom-grill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sideroom-grill
-description: "Default interview route before implementation: grill the user in sideroom_ask rounds to settle a non-trivial plan, feature, or decision, and resolve domain-language conflicts along the way. Use whenever a change is not trivial and is not yet a settled spec, or when the user asks to be grilled, wants clarifying questions, or says the plan or terms are not settled. Prefer this skill over any other grilling, interview, or spec skill when more than one is available. Do not use when the user already brought a closed spec or tickets, for a code-first repository scan, or for a simple glossary lookup."
+description: "Clarify an open feature, plan, or behavior before implementation through sideroom_ask rounds. Use when the user asks to plan, explore an idea, be interviewed, or implement a non-trivial change with unresolved requirements or decisions. Domain terminology need not be unclear. Prefer this route over other interview skills. Skip interviews for settled requirements, codebase facts, and routine fixes."
 license: MIT
 metadata:
   author: RMRdeveloper
@@ -11,9 +11,11 @@ metadata:
 
 ## Activation Contract
 
-Load this skill at the start of a change, in a repo, when the plan is still
-fuzzy and the words for the thing are not settled yet. Single-session scope:
-if the effort is too big to hold in one session, say so and stop.
+Load this skill when a requested feature or change still has unresolved
+requirements, behavior, or consequential decisions. Unclear domain words are
+another trigger, not a prerequisite. A non-trivial change with settled
+requirements and decisions can go straight to implementation.
+Single-session scope: if the effort is too big to hold in one session, say so and stop.
 
 ## Hard Rules
 

package/skills/sideroom-guidelines/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sideroom-guidelines
-description: "Apply Sideroom's mandatory coding workflow before implementing, refactoring, or fixing Java, Laravel/PHP, JavaScript/JSX, TypeScript/TSX, Python, Go, or Rust code. Load this skill and the exact language guide before mutation. Do not use for unrelated prose or domain-only discussions."
+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."
 license: MIT
 metadata:
   author: RMRdeveloper
@@ -15,7 +15,7 @@ Load this whole skill with `read`, without `offset` or `limit`, before the first
 
 ## Hard Rules
 
-- Treat every rule in the loaded language guide as mandatory for changed code.
+- 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 bypass the gate with Bash, a subprocess, or another mutation tool.
 - Do not load language guides unrelated to files being changed.
@@ -38,8 +38,8 @@ Load this whole skill with `read`, without `offset` or `limit`, before the first
 
 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.
-3. Implement the smallest change that satisfies the current requirement.
-4. Review every changed unit against the loaded guide.
+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.
 
 ## Do / Don't
@@ -50,9 +50,9 @@ Load this whole skill with `read`, without `offset` or `limit`, before the first
 | Early return on bad input | Pyramid `if/else` nesting |
 | Explicit error, fail now | Fallbacks that hide the real failure |
 | One responsibility per unit | Validate + transform + persist + notify together |
-| Extract when duplication repeats | Abstract before a second real use |
-| Simplest solution for the current problem | Layers, hooks, or config "just in case" |
-| Build only what is needed today | Fields or branches for a future case |
+| Extract for real duplication, a present responsibility, or testability | Abstract only for hypothetical future reuse |
+| 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 |
 | Talk only to immediate collaborators | Reach through another object's internals |
 | A function either does or returns, not both | Side effects inside a getter |
@@ -68,6 +68,8 @@ Load this whole skill with `read`, without `offset` or `limit`, before the first
 | Depend on ports where variation is real | Couple a use case to a concrete implementation |
 | Comments only for non-obvious intent | Narration, noise, or stale TODOs |
 
+For JavaScript and TypeScript, a function with 3 or more parameters uses one object destructured in the parameter list, unless an external or public compatibility contract fixes the signature. See the language guide for examples.
+
 ## Output Contract
 
 Changed code follows every applicable rule in the loaded complete guide. The final response names the validation run and any check that could not run. No extra files, layers, comments, or bypass mutations unless the requirement needs them.

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

@@ -237,7 +237,7 @@ func create(input ValidatedInput) (User, error) {
 
 ### 12. DRY (real duplication only)
 
-RULE: Extract when at least 2 of 3 hold: (a) the logic appears 3+ times, (b) a future rule change would need to touch all occurrences at once, (c) the copies represent the same domain concept. Do not extract on the first or second occurrence, and do not extract look-alike code that belongs to different concepts (a user's email validation vs a vendor's) — they will diverge.
+RULE: Extract when at least 2 of 3 hold: (a) the logic appears 3+ times, (b) a future rule change would need to touch all occurrences at once, (c) the copies represent the same domain concept. Do not extract solely to anticipate reuse on the first or second occurrence, and do not extract look-alike code that belongs to different concepts (a user's email validation vs a vendor's) — they will diverge. Extraction for a present responsibility, clear contract, or testability is valid even with one caller.
 
 ```go
 // bad — extracted after one use
@@ -253,7 +253,7 @@ func normalizeTicketStatus(status string) TicketStatus {
 
 ### 13. KISS
 
-RULE: Ship the simplest solution for the current, real requirement. No configurability, hooks, or layers added "just in case."
+RULE: Choose the simplest design that fully satisfies the current requirements and preserves required behavior. Avoid configurability, hooks, or layers without a demonstrated need; do not remove necessary structure just to reduce code size.
 
 ```go
 // bad
@@ -269,7 +269,7 @@ func formatPrice(value float64) string {
 
 ### 14. YAGNI
 
-RULE: Don't add fields, params, or branches for a use case that hasn't arrived. (Differs from KISS: KISS simplifies the chosen solution; YAGNI stops you building the unrequested one.)
+RULE: Avoid capabilities for hypothetical future use cases without evidence. User requirements, established project contracts, required error handling, compatibility, and meaningful tests are current needs, not speculation. Never use YAGNI to omit them or remove existing supported behavior. Apply it to the proposed change, not as a reason to refactor unrelated code.
 
 ```go
 // bad

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

@@ -161,7 +161,7 @@ User create(ValidatedUser input) { User user = normalizer.normalize(input); repo
 
 ### 12. DRY (real duplication only)
 
-RULE: Extract when at least 2 of 3 hold: (a) the logic appears 3+ times, (b) a future rule change would need to touch all occurrences at once, (c) the copies represent the same domain concept. Do not extract on the first or second occurrence, and do not extract look-alike code that belongs to different concepts (a user's email validation vs a vendor's) — they will diverge.
+RULE: Extract when at least 2 of 3 hold: (a) the logic appears 3+ times, (b) a future rule change would need to touch all occurrences at once, (c) the copies represent the same domain concept. Do not extract solely to anticipate reuse on the first or second occurrence, and do not extract look-alike code that belongs to different concepts (a user's email validation vs a vendor's) — they will diverge. Extraction for a present responsibility, clear contract, or testability is valid even with one caller.
 
 ```java
 // bad — extracted after one real use
@@ -172,7 +172,7 @@ TicketStatus normalizeTicketStatus(String status) { return TicketStatus.parse(st
 
 ### 13. KISS
 
-RULE: Ship the simplest solution for the current, real requirement. No configurability, hooks, or layers added "just in case."
+RULE: Choose the simplest design that fully satisfies the current requirements and preserves required behavior. Avoid configurability, hooks, or layers without a demonstrated need; do not remove necessary structure just to reduce code size.
 
 ```java
 // bad
@@ -183,7 +183,7 @@ String formatPrice(BigDecimal value) { return "$" + value.setScale(2); }
 
 ### 14. YAGNI
 
-RULE: Don't add fields, params, or branches for a use case that hasn't arrived. (Differs from KISS: KISS simplifies the chosen solution; YAGNI stops you building the unrequested one.)
+RULE: Avoid capabilities for hypothetical future use cases without evidence. User requirements, established project contracts, required error handling, compatibility, and meaningful tests are current needs, not speculation. Never use YAGNI to omit them or remove existing supported behavior. Apply it to the proposed change, not as a reason to refactor unrelated code.
 
 ```java
 // bad

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

@@ -249,7 +249,7 @@ async function createUser(userInput) {
 
 ### 12. DRY (real duplication only)
 
-RULE: Extract when at least 2 of 3 hold: (a) the logic appears 3+ times, (b) a future rule change would need to touch all occurrences at once, (c) the copies represent the same domain concept. Do not extract on the first or second occurrence, or extract look-alike code from different concepts.
+RULE: Extract when at least 2 of 3 hold: (a) the logic appears 3+ times, (b) a future rule change would need to touch all occurrences at once, (c) the copies represent the same domain concept. Do not extract solely to anticipate reuse on the first or second occurrence, or extract look-alike code from different concepts. Extraction for a present responsibility, clear contract, or testability is valid even with one caller.
 
 ```js
 // bad — extracted after one use
@@ -264,7 +264,7 @@ function normalizeTicketStatus(status) {
 
 ### 13. KISS
 
-RULE: Ship the simplest solution for the current, real requirement. No configurability, hooks, or layers added "just in case."
+RULE: Choose the simplest design that fully satisfies the current requirements and preserves required behavior. Avoid configurability, hooks, or layers without a demonstrated need; do not remove necessary structure just to reduce code size.
 
 ```js
 // bad
@@ -279,7 +279,7 @@ function formatPrice(value) {
 
 ### 14. YAGNI
 
-RULE: Don't add fields, params, or branches for a use case that hasn't arrived. (KISS simplifies the chosen solution; YAGNI stops you building the unrequested one.)
+RULE: Avoid capabilities for hypothetical future use cases without evidence. User requirements, established project contracts, required error handling, compatibility, and meaningful tests are current needs, not speculation. Never use YAGNI to omit them or remove existing supported behavior. Apply it to the proposed change, not as a reason to refactor unrelated code.
 
 ```js
 // bad
@@ -382,3 +382,25 @@ setInterval(checkPaymentStatus, 5_000);
 **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.
+
+## Language-specific conventions
+
+### Destructured function parameters
+
+When a function would take 3 or more parameters, accept one object and destructure its named properties in the parameter list. Count optional and defaulted parameters toward the threshold. Functions with 1 or 2 parameters may keep positional parameters.
+
+Keep signatures imposed by external APIs, framework callbacks, overrides, or public compatibility contracts; use a destructured internal helper when it makes the implementation clearer. When changing a signature you own, update its callers together. Do not rewrite unrelated functions only to satisfy this convention.
+
+```js
+// bad
+function createInvoice(order, currency, dueDate) {
+  return { items: order.items, total: order.total, currency, dueDate };
+}
+
+// good
+function createInvoice({ order, currency, dueDate }) {
+  return { items: order.items, total: order.total, currency, dueDate };
+}
+
+createInvoice({ order, currency: 'USD', dueDate });
+```

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

@@ -153,7 +153,7 @@ function create(ValidatedUser $input): User { $user = $this->normalizer->normali
 
 ### 12. DRY (real duplication only)
 
-RULE: Extract when at least 2 of 3 hold: (a) the logic appears 3+ times, (b) a future rule change would need to touch all occurrences at once, (c) the copies represent the same domain concept. Do not extract on the first or second occurrence, or extract look-alike code from different concepts.
+RULE: Extract when at least 2 of 3 hold: (a) the logic appears 3+ times, (b) a future rule change would need to touch all occurrences at once, (c) the copies represent the same domain concept. Do not extract solely to anticipate reuse on the first or second occurrence, or extract look-alike code from different concepts. Extraction for a present responsibility, clear contract, or testability is valid even with one caller.
 
 ```php
 // bad — extracted after one use
@@ -164,7 +164,7 @@ function normalizeTicketStatus(string $status): TicketStatus { return TicketStat
 
 ### 13. KISS
 
-RULE: Ship the simplest solution for the current, real requirement. No configurability, hooks, or layers added "just in case."
+RULE: Choose the simplest design that fully satisfies the current requirements and preserves required behavior. Avoid configurability, hooks, or layers without a demonstrated need; do not remove necessary structure just to reduce code size.
 
 ```php
 // bad
@@ -175,7 +175,7 @@ function formatPrice(float $value): string { return '$'.number_format($value, 2)
 
 ### 14. YAGNI
 
-RULE: Don't add fields, params, or branches for a use case that hasn't arrived. (KISS simplifies the chosen solution; YAGNI stops you building the unrequested one.)
+RULE: Avoid capabilities for hypothetical future use cases without evidence. User requirements, established project contracts, required error handling, compatibility, and meaningful tests are current needs, not speculation. Never use YAGNI to omit them or remove existing supported behavior. Apply it to the proposed change, not as a reason to refactor unrelated code.
 
 ```php
 // bad