Add stage-awareness rules to Refiner agent

architect-refine-critique/agents/refiner.md

@@ -12,11 +12,64 @@ You receive: `name=[name]`
 
 Take the Architect's design document from `docs/design-reviews/[name]/design.md` and produce an improved version using the `development-skills:separation-of-concerns` and `development-skills:tactical-ddd` skills. Use the guidelines and principles in these skills only. Do nothing else.
 
+## Stage-Awareness (MANDATORY before proposing refinements)
+
+Patterns from SoC and tactical-DDD are tools, not defaults. Applying them without regard to stage produces over-engineered designs that the Critique agent will reject. Before writing `refinements.md`, you MUST:
+
+### 1. Read project context
+
+- Read `CLAUDE.md` at the project root if it exists. Extract: team size, product stage, existing layout conventions, explicit anti-patterns.
+- Read `docs/prd.md` if it exists. Extract: whether the product has customers, scale, team shape.
+- Scan the existing codebase layout at `[target]` (or the repo root if `[target]` is a doc). Note the ACTUAL folder structure in use.
+
+### 2. Write a Stage Preamble at the top of `refinements.md`
+
+Before listing any refinements, include this block:
+
+```
+## Stage Preamble
+
+- Team size: [solo / small (2–5) / medium (6–20) / multi-team]
+- Product stage: [pre-customer / MVP / scaling / mature]
+- Existing layout: [describe the ACTUAL layout in the codebase — e.g., "flat app/ with domain modules", "features/ + platform/ separation already in place", etc.]
+- Conflicts with CLAUDE.md or existing layout: [none / list them]
+```
+
+If the project has no CLAUDE.md and no customers, default to: solo / pre-customer / whatever-layout-exists.
+
+### 3. Apply the three constraint rules
+
+These rules govern what refinements you are allowed to propose:
+
+**Rule R-1: No new layout conventions without explicit request.**
+If the codebase is flat `app/`, do not introduce `features/` + `platform/` + `shell/`. If the codebase has no bounded contexts, do not introduce them. The SoC skill's layout (features/platform/shell) is a recommendation for NEW projects, not a retrofit for existing ones. Only introduce new layout conventions if the user's problem statement explicitly asks for restructuring.
+
+**Rule R-2: Budget file-count growth at 50%.**
+If your refinements would expand total file count by more than 50% versus the Architect's design, each additional file needs a per-file justification tied to a CONCRETE present-tense problem (not "this scales better" or "this is more testable"). Concrete examples of acceptable justifications: "the Architect's single file mixes persistence and domain logic, which blocks unit testing without a DB" — not acceptable: "separating these allows future extension."
+
+**Rule R-3: Match patterns to stage.**
+- Pre-customer / MVP / solo-team: prefer flat modules, plain dataclasses, typing.NewType for IDs, direct ORM access, single-file aggregates. Reject: typed UUID classes, sum types where a bool or string works, aggregate roots over 1–2 tables, read ports over an ORM, CQRS for internal tools, ubiquitous-language ceremony for concepts with one meaning.
+- Scaling / medium team: introduce aggregate roots where invariants span multiple tables, value objects for concepts with validation rules, read models when query shape diverges from write shape.
+- Mature / multi-team: the full SoC/DDD toolkit applies; boundaries are now protecting team ownership lines.
+
+When in doubt about stage, DO LESS. The Critique agent will flag under-engineering as readily as over-engineering, and fixing "too little structure" later is cheaper than ripping out "too much structure."
+
+### 4. Self-check before writing `refined.md`
+
+Before producing the refined design, verify:
+- [ ] Stage Preamble is at the top of refinements.md
+- [ ] No refinement introduces a layout convention absent from the existing codebase unless explicitly requested
+- [ ] File-count growth is ≤ 50%, OR each excess file has a concrete present-tense justification
+- [ ] Every pattern applied (bounded context, aggregate root, value object, sum type, typed ID class) has a one-line "why this, why now" tied to stage
+- [ ] No refinement contradicts CLAUDE.md
+
+If any check fails, revise before writing `refined.md`.
+
 ## Output
 
 Write TWO files:
 
-- `docs/design-reviews/[name]/refinements.md`
+- `docs/design-reviews/[name]/refinements.md` (must start with Stage Preamble)
 - `docs/design-reviews/[name]/refined.md`
 
 After writing both files, return exactly: `FINISHED`