@martinffx/atelier 3.1.2 → 3.4.0

package/skills/oracle-codebase-design/references/deepening.md

@@ -0,0 +1,37 @@
+# Deepening
+
+How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [SKILL.md](../SKILL.md): **module**, **interface**, **seam**, **adapter**.
+
+## Dependency categories
+
+When assessing a candidate for deepening, classify its dependencies. The category determines how the deepened module is tested across its seam.
+
+### 1. In-process
+
+Pure computation, in-memory state, no I/O. Always deepenable: merge the modules and test through the new interface directly. No adapter needed.
+
+### 2. Local-substitutable
+
+Dependencies that have local test stand-ins (PGLite for Postgres, in-memory filesystem). Deepenable if the stand-in exists. The deepened module is tested with the stand-in running in the test suite. The seam is internal; no port at the module's external interface.
+
+### 3. Remote but owned (Ports & Adapters)
+
+Your own services across a network boundary (microservices, internal APIs). Define a **port** (interface) at the seam. The deep module owns the logic; the transport is injected as an **adapter**. Tests use an in-memory adapter. Production uses an HTTP/gRPC/queue adapter.
+
+Recommendation shape: *"Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for testing, so the logic sits in one deep module even though it's deployed across a network."*
+
+### 4. True external (Mock)
+
+Third-party services (Stripe, Twilio, etc.) you don't control. The deepened module takes the external dependency as an injected port; tests provide a mock adapter.
+
+## Seam discipline
+
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a port unless at least two adapters are justified (typically production + test). A single-adapter seam is just indirection.
+- **Internal seams vs external seams.** A deep module can have internal seams (private to its implementation, used by its own tests) as well as the external seam at its interface. Don't expose internal seams through the interface just because tests use them.
+
+## Testing strategy: replace, don't layer
+
+- Old unit tests on shallow modules become waste once tests at the deepened module's interface exist; delete them.
+- Write new tests at the deepened module's interface. The **interface is the test surface**.
+- Tests assert on observable outcomes through the interface, not internal state.
+- Tests should survive internal refactors, since they describe behaviour, not implementation. If a test has to change when the implementation changes, it's testing past the interface.

package/skills/oracle-codebase-design/references/design-it-twice.md

@@ -0,0 +1,44 @@
+# Design It Twice
+
+When the user wants to explore alternative interfaces for a module, use this parallel sub-agent pattern. Based on "Design It Twice" (John Ousterhout, *A Philosophy of Software Design*): your first idea is unlikely to be the best.
+
+Uses the vocabulary in [SKILL.md](../SKILL.md): **module**, **interface**, **seam**, **adapter**, **leverage**.
+
+## Process
+
+### 1. Frame the problem space
+
+Before spawning sub-agents, write a user-facing explanation of the problem space:
+
+- The constraints any new interface would need to satisfy
+- The dependencies it would rely on, and which category they fall into (see [deepening.md](deepening.md))
+- A rough illustrative code sketch to ground the constraints, not a proposal, just a way to make the constraints concrete
+
+Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel.
+
+### 2. Spawn sub-agents
+
+Spawn 3+ sub-agents in parallel. Each must produce a **radically different** interface for the module.
+
+Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [deepening.md](deepening.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint:
+
+- Agent 1: "Minimize the interface: aim for 1–3 entry points max. Maximise leverage per entry point."
+- Agent 2: "Maximise flexibility: support many use cases and extension."
+- Agent 3: "Optimise for the most common caller: make the default case trivial."
+- Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies."
+
+Include both [SKILL.md](../SKILL.md) vocabulary and the project's `CONTEXT.md` vocabulary in the brief so each sub-agent names things consistently with the design language and the project's domain language.
+
+Each sub-agent outputs:
+
+1. Interface (types, methods, params, plus invariants, ordering, error modes)
+2. Usage example showing how callers use it
+3. What the implementation hides behind the seam
+4. Dependency strategy and adapters (see [deepening.md](deepening.md))
+5. Trade-offs: where leverage is high, where it's thin
+
+### 3. Present and compare
+
+Present designs sequentially so the user can absorb each one, then compare them in prose. Contrast by **depth** (leverage at the interface), **locality** (where change concentrates), and **seam placement**. Check each against [red-flags.md](red-flags.md).
+
+After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated: the user wants a strong read, not a menu.

package/skills/oracle-codebase-design/references/principles.md

@@ -0,0 +1,205 @@
+# Principles
+
+Each principle: the rule, why it matters in glossary terms (see [SKILL.md](../SKILL.md)), and a short example. Examples are TypeScript.
+
+## 1. Deep modules and the deletion test
+
+**Rule.** Put a lot of behaviour behind a small interface. Imagine deleting the module: if complexity vanishes, it was a pass-through; if it reappears across N callers, it was earning its keep.
+
+**Why.** Depth gives callers leverage and maintainers locality.
+
+```typescript
+// Shallow: the interface is the implementation
+class UserRepo {
+  getTable() { return this.db.table("users"); }
+  runQuery(q: Query) { return this.db.run(q); }
+}
+
+// Deep: callers say what they want
+class UserRepo {
+  findByEmail(email: Email): Promise<User | undefined> { /* query, mapping, caching */ }
+}
+```
+
+## 2. Test at the correct level
+
+**Rule.** The interface is the test surface. Test through the module's interface at its seam, not each internal function. When you deepen a module, replace the old tests; don't layer new ones on top.
+
+**Why.** Tests that reach past the interface break on every refactor and prove nothing the interface doesn't. If you want to test past the interface, the module is probably the wrong shape.
+
+- Unit-test the functional core directly; it has no I/O.
+- Integration-test the shell with a local stand-in (see [deepening.md](deepening.md)).
+- Don't mock your own modules. Mock only true external dependencies at a port.
+- Assert on observable outcomes, not internal state.
+
+**Smell.** A test that changes whenever the implementation changes; many tiny tests of pure helpers while the real bugs hide in how they're called.
+
+## 3. Parse, don't validate
+
+**Rule.** At the external seam, turn untrusted input into a domain type that can only exist if valid. The core accepts the parsed type and never re-checks.
+
+**Why.** Validation returns a boolean and discards what it learned, so every downstream caller must re-validate or hope. Parsing keeps the knowledge in the type. Locality: the check lives in one place.
+
+```typescript
+// Validate: knowledge is lost, callers re-check
+function isEmail(s: string): boolean { /* ... */ }
+function sendWelcome(to: string) { if (!isEmail(to)) throw new Error("bad email"); /* ... */ }
+
+// Parse: knowledge is kept in the type
+type Email = string & { readonly __brand: "Email" };
+function parseEmail(s: string): Result<Email, InvalidEmail> { /* ... */ }
+function sendWelcome(to: Email) { /* no check needed */ }
+```
+
+In a layered codebase this is `Entity.fromRequest`: the router hands raw input to the Entity, which parses it into domain values, and everything below works with parsed types.
+
+**Smell.** The same field checked in router, service, and repository; `string` parameters that must be "a valid X".
+
+## 4. Make illegal states unrepresentable
+
+**Rule.** Shape the types so invalid combinations cannot be constructed. Prefer discriminated unions to a bag of flags and optionals.
+
+**Why.** Every representable-but-invalid state is a case every caller must handle, which is interface complexity. Removing it shrinks the interface.
+
+```typescript
+// Illegal states possible: loading with an error, data with no result
+type Fetch = { loading: boolean; error?: Error; data?: Data };
+
+// Only legal states exist
+type Fetch =
+  | { status: "loading" }
+  | { status: "failed"; error: Error }
+  | { status: "loaded"; data: Data };
+```
+
+**Smell.** Comments like "only set when `kind` is X"; several booleans that can't all be true; optional fields that are required in some states.
+
+## 5. Functional core, imperative shell
+
+**Rule.** Keep decisions in pure functions that take values and return values. Push I/O (database, network, clock, randomness) to a thin shell that gathers inputs, calls the core, and applies the result.
+
+**Why.** The core is testable without mocks and holds the logic, so bugs concentrate there (locality). The shell is simple enough to cover with a few integration tests.
+
+```typescript
+// Core: pure decision
+function decideRenewal(sub: Subscription, now: Date): RenewalDecision { /* ... */ }
+
+// Shell: I/O around it
+async function renew(id: SubscriptionId) {
+  const sub = await repo.get(id);
+  const decision = decideRenewal(sub, clock.now());
+  await apply(decision);
+}
+```
+
+**Smell.** Business rules interleaved with queries; tests that need a mocked database to check a calculation. Counter-smell: a pure helper extracted only for testability while the real bugs sit in how it's called. Keep decisions and their orchestration close.
+
+## 6. Errors as values
+
+**Rule.** Expected failures (invalid input, not found, conflict) are part of the interface and are returned as typed values, such as `Result<T, E>`. Exceptions are for bugs and unrecoverable states.
+
+**Why.** Error modes are part of the interface. If they're hidden in `throw`, the caller can't see what to handle and the compiler can't help.
+
+```typescript
+function placeOrder(cmd: PlaceOrder): Result<Order, OutOfStock | PaymentDeclined> { /* ... */ }
+```
+
+But first, try principle 7: if the error can be defined away, it should not be in the interface at all.
+
+**Smell.** `catch` blocks that parse error messages; functions documented with "may throw X, Y, Z".
+
+## 7. Define errors out of existence
+
+**Rule.** Change the semantics so the error condition is not an error. Do this before reaching for `Result`.
+
+**Why.** Every error is interface surface callers must handle. The best error handling is none.
+
+- `delete(key)` on a missing key succeeds; the postcondition (key absent) holds.
+- `substring(start, end)` clamps out-of-range indices instead of throwing.
+- Return an empty collection, not `null`.
+
+**Caution.** Don't swallow errors that matter. Define away only when the caller's intent is satisfied either way.
+
+## 8. Information hiding
+
+**Rule.** Each design decision (a file format, a protocol, an algorithm, a table layout) lives in exactly one module.
+
+**Why.** Knowledge that appears in two modules is a leak: change one and you must change both (change amplification). Locality means a decision changes in one place.
+
+**Smell.** Two modules that both know the wire format; callers that must call methods in a particular order (temporal decomposition: structure follows the order of operations rather than the knowledge involved).
+
+## 9. Pull complexity downward
+
+**Rule.** When complexity must live somewhere, put it in the module, not its callers. A simple interface matters more than a simple implementation.
+
+**Why.** There are many callers and one module. Complexity pushed up is paid N times.
+
+**Smell.** Config parameters that make callers decide what the module could decide; exceptions the caller can only rethrow.
+
+## 10. Somewhat general-purpose modules are deeper
+
+**Rule.** Design the interface for the underlying capability, not for today's single use. Keep it general enough to cover related uses, but implement only what's needed now. Keep general-purpose code apart from special-purpose code.
+
+**Why.** A general interface is usually smaller and simpler than a stack of special cases, and it survives the next feature.
+
+**Smell.** Methods named for one screen or one caller (`deleteSelectedTextFromEditor`); a general mechanism with feature-specific branches inside it.
+
+## 11. Different layers, different abstractions
+
+**Rule.** Each layer should offer an abstraction distinct from the ones above and below. A method that only forwards to another method with the same signature is a pass-through; so is a variable threaded unchanged through a chain of calls.
+
+**Why.** A pass-through adds interface without depth. The deletion test flags it.
+
+If a layer exists because the project's architecture demands it (Router → Service → Repository), make it earn its place: give it behaviour the layer below doesn't have, or fold the behaviour down. For a pass-through variable, put it in a context object or shared module.
+
+## 12. Together or apart
+
+**Rule.** Combine modules that share information, are always used together, or overlap conceptually. Separate general mechanism from specific use. Don't split just to make things short.
+
+**Why.** Splitting adds interface and separates things that need each other. Combining adds locality. Judge by interface complexity and dependencies, not by line count.
+
+**Smell.** Conjoined methods: you can't understand one without reading the other.
+
+## 13. Make the common case simple
+
+**Rule.** Give parameters sensible defaults and design the default path to need no configuration. Rare needs may cost more.
+
+**Why.** Interface complexity is paid by every caller; the common caller shouldn't pay for the rare one.
+
+```typescript
+// Common case: one argument
+createClient(url);
+// Rare case: opt in
+createClient(url, { retries: 5, timeoutMs: 2_000 });
+```
+
+## 14. Comments and names carry the design
+
+**Rule.**
+- Comments describe what isn't obvious from the code. Interface comments state the abstraction (what it does, invariants, error modes); implementation comments explain *why*.
+- Write the interface comment first. If it is hard to write, the design is unclear: fix the design.
+- Names are precise and used consistently for the same thing.
+- Design for ease of reading, not ease of writing.
+
+**Why.** A comment that repeats the code adds nothing; a comment that states the abstraction is the interface's documentation. Names are the cheapest interface.
+
+**Link.** A name you can't pick, or a concept you can't describe simply, usually means the domain language isn't settled. Resolve it with `oracle-domain-modelling` and record it in `CONTEXT.md`. If the decision is contested, run it through `oracle-grill-me`.
+
+## 15. Seam discipline
+
+**Rule.**
+- Accept dependencies; don't create them.
+- Return results; don't produce side effects.
+- One adapter means a hypothetical seam. Two means a real one. Don't introduce a port unless something actually varies across it.
+
+**Why.** Seams cost interface. Pay only where behaviour varies (typically production and test).
+
+```typescript
+// Testable
+function processOrder(order: Order, paymentGateway: PaymentGateway) {}
+
+// Hard to test
+function processOrder(order: Order) {
+  const gateway = new StripeGateway();
+}
+```

package/skills/oracle-codebase-design/references/red-flags.md

@@ -0,0 +1,32 @@
+# Red Flags
+
+A checklist to run before finalising a design, and when reviewing one. Each flag points to the principle in [principles.md](principles.md) that fixes it. Terms follow [SKILL.md](../SKILL.md).
+
+| Red flag | What it looks like | Fix |
+|----------|--------------------|-----|
+| **Shallow module** | The interface is nearly as complex as the implementation. Passes the deletion test the wrong way: deleting it removes nothing. | Deep modules (1). Merge, or move behaviour in. |
+| **Information leakage** | The same design decision (format, protocol, table layout) appears in two modules. | Information hiding (8). |
+| **Temporal decomposition** | Structure follows the order operations run in (read, process, write) instead of the knowledge involved. Shared knowledge ends up in several steps. | Information hiding (8); together or apart (12). |
+| **Overexposure** | The interface forces callers to learn rarely used features to use the common ones. | Make the common case simple (13). |
+| **Pass-through method** | A method that only forwards to another with a similar signature. | Different layers, different abstractions (11). |
+| **Pass-through variable** | An argument threaded unchanged through a chain of calls. | Different layers, different abstractions (11): context object or shared module. |
+| **Repetition** | The same code or check appears in many places. | Parse, don't validate (3); information hiding (8); pull complexity downward (9). |
+| **Special-general mixture** | A general mechanism contains feature-specific branches. | Somewhat general-purpose modules (10). |
+| **Conjoined methods** | You can't understand one method without reading another. | Together or apart (12). |
+| **Comment repeats code** | The comment says what the next line plainly says. | Comments and names (14). |
+| **Implementation contaminates interface** | The interface comment must describe how it works inside. | Information hiding (8); rewrite the interface comment first (14). |
+| **Vague name** | `data`, `info`, `manager`, `handle`, `process`. | Comments and names (14); resolve with `oracle-domain-modelling`. |
+| **Hard to pick a name** | You can't find a precise name for the thing. | The concept is unclear; settle it in `CONTEXT.md`. |
+| **Hard to describe** | The interface comment is long or awkward. | The design is unclear. Redesign before documenting (14). |
+| **Nonobvious code** | A reader can't tell what it does or why without effort. | Names and structure for reading (14). |
+
+## Added for this toolkit
+
+| Red flag | What it looks like | Fix |
+|----------|--------------------|-----|
+| **Stringly-typed core** | Core logic takes raw `string` or `any` and re-checks it. | Parse, don't validate (3). |
+| **Flag-and-optional bag** | Several booleans and optionals where only some combinations are legal. | Make illegal states unrepresentable (4). |
+| **I/O in the decision** | Business rules interleaved with queries or network calls. | Functional core, imperative shell (5). |
+| **Throwing for expected failure** | `catch` blocks that parse messages; "may throw X, Y, Z". | Define errors out of existence (7), else errors as values (6). |
+| **Testing past the interface** | Tests break on every refactor; many tests of internal helpers. | Test at the correct level (2). |
+| **Single-adapter port** | An interface with one implementation and no test double. | Seam discipline (15). |

package/skills/oracle-debug/SKILL.md

@@ -108,7 +108,9 @@ artifact-based investigation is valid when a loop is unavailable.
 
 ## Phase 2 — Pattern Analysis
 
-Find the pattern before fixing.
+Find the pattern before fixing. Finding working examples across a large codebase can be
+delegated to a read-only subagent (see Delegation in atelier-orchestrator). Phases 1, 3 and 4
+stay in the main thread.
 
 1. **Find working examples.** Locate similar working code in the same codebase.
 2. **Compare against references.** If implementing a known pattern, read the reference implementation completely.
@@ -143,7 +145,7 @@ Fix the root cause, not the symptom.
 
 1. **Create a failing test case.** The simplest possible reproduction. MUST exist before the fix.
 
-   A **correct seam** is one where the test exercises the real bug pattern as it occurs at the call site. If the only available seam is too shallow, note that the codebase architecture is preventing the bug from being locked down.
+   A **correct seam** is one where the test exercises the real bug pattern as it occurs at the call site. If the only available seam is too shallow, note that the codebase architecture is preventing the bug from being locked down. Use the seam and depth vocabulary from `oracle-codebase-design` when you raise it.
 
 2. **Implement a single fix.** Address the root cause. One change at a time. No "while I'm here" improvements. No bundled refactoring.
 3. **Verify the fix.** Does the test pass? Do other tests still pass? Does the original repro no longer reproduce?
@@ -151,7 +153,7 @@ Fix the root cause, not the symptom.
    - STOP
    - Count the failed fix attempts
    - If < 3: return to Phase 1 with the new information
-   - If ≥ 3: **question the architecture**. Pattern problems, hidden coupling, and shared state that each fix reveals are signs of a wrong pattern. Discuss with the user before attempting Fix #4.
+   - If ≥ 3: **question the architecture**. Pattern problems, hidden coupling, and shared state that each fix reveals are signs of a wrong pattern (see the red flags in `oracle-codebase-design`). Discuss with the user before attempting Fix #4.
 
 ### Cleanup + post-mortem
 

package/skills/oracle-grill-me/SKILL.md

@@ -20,4 +20,5 @@ understanding. Update domain documentation as terminology and decisions are reso
 session is nested in spec-brainstorm, return changed assumptions to that workflow for any required
 design update.
 
-Run this session using the `oracle-domain-modelling` skill.
+Run this session using the `oracle-domain-modelling` skill. When the decision is about a module's
+interface, seams, or test level, also use the `oracle-codebase-design` skill.

package/skills/spec-brainstorm/SKILL.md

@@ -55,7 +55,8 @@ it touches multiple files or takes time. That work belongs in an Inline Plan.
 
 Break the system into units with one clear purpose each. Well-defined interfaces between
 them. Each unit independently understandable and independently testable. If you can't
-explain a unit's job in one sentence, it's doing too much.
+explain a unit's job in one sentence, it's doing too much. Apply **oracle-codebase-design**:
+deep modules, seams placed where behaviour varies, and the interface as the test surface.
 
 ### Working in existing codebases
 
@@ -169,6 +170,9 @@ Read the relevant codebase deeply. Not signatures — implementations, edge case
 handling, data flows. Trace callers and callees. Read tests to understand expected
 behaviour.
 
+When research spans more than a few files, delegate it to a read-only subagent per area (see
+Delegation in atelier-orchestrator) and assemble the research table from their cited findings.
+
 Collect research findings for the spec as the foundation. Do not write `design.md` until the
 approved design sections are assembled in Step 4c.
 
@@ -200,6 +204,8 @@ Before settling on a design, present **2-3 approaches** with trade-offs.
 
 The first approach must keep the existing architecture and make the smallest correct change.
 Present broader approaches only when a current requirement makes their extra cost relevant.
+When approaches differ mainly in interface shape, use the design-it-twice reference in
+**oracle-codebase-design**.
 
 For each approach, address:
 
@@ -247,9 +253,10 @@ with acceptance criteria and priorities. If rejected: revise. If the rejection
 reveals a scope misunderstanding, loop back to Discovery (Step 2).
 
 **Batch B: Architecture** — component design, domain modeling, and layer
-boundaries. Use installed language-specific architecture or API-design skills as relevant to
-your stack. Then present: component structure, domain model, where business
-logic lives, where IO lives. If rejected: revise. If the rejection undermines
+boundaries. Use **oracle-codebase-design** and any installed language-specific architecture or
+API-design skills relevant to your stack. Then present: component structure, domain model, where
+business logic lives, where IO lives, where untrusted input is parsed (the external seam), and
+the seam each module is tested through. If rejected: revise. If the rejection undermines
 the chosen approach, offer to return to approach exploration (4a). If it
 reveals a fundamental gap, loop back to Research (Step 3). If the detail reveals
 the work is far more complex than estimated, say so and offer to revisit the

package/skills/spec-implement/SKILL.md

@@ -86,16 +86,27 @@ If the human has not specified an execution style, ask.
 - Stop and report: what was done, test output, anything unexpected
 - Wait for human feedback before continuing
 
+### Delegation (all modes)
+
+In any mode, delegate a task to a fresh subagent when **the design is already settled and the
+file just needs to be made**, as defined by the **code-subagents** "When to Use" criteria.
+
+- Invoke **code-subagents** for eligibility, dispatch patterns, and the implementer template
+- Paste the relevant design excerpt into the dispatch so the subagent makes no design decisions
+- Never name an agent; the harness chooses from agent descriptions
+- Keep coupled, exploratory, or design-sensitive tasks in the main thread
+- The main agent runs the combined plan and code-quality review per completed batch, and the
+  validation commands itself
+
 ### Subagent Mode
 
 > "Use subagents."
 
-- Invoke **code-subagents** for dispatch patterns and review cycle
-- Fresh subagent per task — no context pollution
-- One combined plan and code-quality review per completed batch
-- Independent tasks dispatch in parallel, dependent tasks run sequentially
+Delegate every eligible task. Independent tasks dispatch in parallel, dependent tasks run
+sequentially.
 
-Default to batched if the human hasn't expressed a preference.
+Default to batched if the human hasn't expressed a preference; delegation still applies per
+task.
 
 ---
 
@@ -117,6 +128,8 @@ Read the task's **inputs** and **description** first.
 For behavior-changing code tasks, write tests that cover the validation criteria before writing
 implementation. For documentation, configuration, migration, or verification-only tasks, use the
 task's stated validation instead. Invoke an installed language-specific testing skill when needed.
+Write tests at the module's interface (see **oracle-codebase-design**), and use its red flags
+when refactoring.
 
 ```
 1. Read task inputs and description

package/skills/spec-plan/SKILL.md

@@ -43,6 +43,7 @@ request. Implementation requires a later, explicit request after this skill has
   same need.
 - Group tests by changed contract and active boundary. Do not repeat the CRUD matrix across
   layers.
+- Plan tests at each module's interface, not past it (see **oracle-codebase-design**).
 
 ### Proportionality Gate
 
@@ -50,6 +51,25 @@ Before presenting any plan, compare its size and concepts with the requested beh
 bounded migration or refactor introduces shared infrastructure, unrelated behavior, or a plan
 substantially larger than the behavior being changed, stop and simplify it.
 
+### Challenge Gate
+
+Before presenting a plan, dispatch two read-only subagents in parallel with the draft plan and
+its design context. Do not name agents; describe the work so the harness matches it to agent
+descriptions (see Delegation in `atelier-orchestrator`):
+
+1. **Design review:** check architectural fit, layer and data-model boundaries, API contracts,
+   and whether task ordering respects the dependencies.
+2. **Critical challenge:** challenge assumptions, look for missing cases, scope creep, and
+   unproven requirements, and propose simpler alternatives.
+
+Each returns at most five evidence-backed findings. Fold in the valid ones, drop the rest with a
+reason, and present the plan with a short **Challenged** note listing what changed.
+
+Run the gate on every Spec-backed Plan. Run it on an Inline Plan only when the change touches a
+data model, an API contract, or more than one module or layer; skip it for small bounded edits.
+Run it once per draft; do not re-run it for the human's annotation revisions unless the plan's
+structure changes.
+
 ## Outputs
 
 ### Inline Plan (when explicitly selected)
@@ -63,7 +83,7 @@ structure. Omit optional subsections rather than rendering empty headings.
 Read enough of the codebase to identify the current behavior, boundaries, affected files,
 and concrete validation. Keep the plan proportional to implementation risk. Fill the
 template with confirmed, file-and-symbol-level details, including cross-file wiring or
-ordering constraints where they matter. Apply the Planning Rules and Proportionality Gate
+ordering constraints where they matter. Apply the Planning Rules, Proportionality Gate, and Challenge Gate
 before presenting it.
 
 Do not manufacture phases, task IDs, dependency graphs, acceptance matrices, `design.md`,
@@ -192,8 +212,8 @@ structured `plan.json` when approved.
 
 ## Spec-backed Step 1: Write the Plan Draft
 
-Read the approved `design.md`, then present the plan draft in conversation. Do not write the
-draft into `design.md` or create a separate draft file.
+Read the approved `design.md`, apply the Challenge Gate to the draft, then present the plan
+draft in conversation. Do not write the draft into `design.md` or create a separate draft file.
 
 ### Plan quality