jdi-cli 0.1.1 → 0.1.3

package/README.md

@@ -27,6 +27,10 @@ Full-blown AI workflows (33+ agents, 60+ commands, 100+ subworkflows) burn token
 /jdi-do <N>                        <- execute via doer specialist (SUMMARY.md)
 /jdi-verify <N>                    <- gates via reviewer (REVIEW.md)
 /jdi-ship <N>                      <- update ROADMAP, advance phase
+
+# Roadmap mutation (run anytime)
+/jdi-add-phase "<name>"            <- append (or --at <pos>) a new phase
+/jdi-remove-phase <N>              <- remove a future/pending phase
 ```
 
 ### Brownfield (existing project)
@@ -527,6 +531,8 @@ See [AGENTS.md](AGENTS.md) for full details.
 | `/jdi-do <N>` | phase number | `--sequential` (force sequential execution even if waves permit parallel) | Execute tasks via doer specialist(s) → SUMMARY.md |
 | `/jdi-verify <N>` | phase number | — | Run reviewer specialist gates → REVIEW.md (verdict APPROVED / APPROVED_WITH_WARNINGS / BLOCKED) |
 | `/jdi-ship <N>` | phase number | — | Update ROADMAP, advance phase. Gates: verdict must not be BLOCKED |
+| `/jdi-add-phase "<name>"` | phase name (required) | `--goal "<text>"`, `--at <pos>`, `--reason "<text>"` | Append (or insert at position) a new phase in ROADMAP.md. Bumps `total_phases`. Cannot insert at or before `current_phase`. |
+| `/jdi-remove-phase <N>` | phase number (required) | `--force` (required if artifacts exist) | Remove a future or pending phase. Refuses for `done`, current, or past phases. Archives existing artifacts to `.jdi/archive/removed-<NN-slug>/`. Numbers are NOT renumbered (preserves history). |
 
 **Brownfield entry (1):**
 

package/core/agents/jdi-architect.md

@@ -411,13 +411,29 @@ Write to `.jdi/agents/jdi-reviewer-{slug}.md`.
 
 After writing doer/reviewer, inject `<skills_to_load>` block after `</role>` via Edit.
 
+**Code-design skill (mandatory) — resolve from `PROJECT.md.Code Design` (LOCKED value) using this mapping:**
+
+| Code Design (PROJECT.md) | Skill to load |
+|---|---|
+| The Method | `the-method` |
+| DDD | `ddd` |
+| Clean Architecture | `clean-architecture` |
+| Hexagonal | `hexagonal` |
+| Onion | `onion` |
+| Vertical Slice | `vertical-slice` |
+
+The resolved code-design skill is loaded by **both doer and reviewer**. Exactly one code-design skill is loaded. Never load two code-design skills simultaneously — the project uses exactly one design. If the mapping cannot resolve, abort with an error and ask the user to fix `PROJECT.md.Code Design`.
+
 **Doer — always:**
 ```markdown
 <skills_to_load>
 - solid — before creating classes/modules/interfaces. Detects god class, large switches, deep inheritance, dep on concretes.
+- {CODE_DESIGN_SKILL} — INVIOLABLE structural rules for the project's locked code design. Apply on every file created.
 </skills_to_load>
 ```
 
+Replace `{CODE_DESIGN_SKILL}` with the resolved entry from the mapping above (e.g. `the-method`, `ddd`, `clean-architecture`, `hexagonal`, `onion`, `vertical-slice`).
+
 If `has_frontend=true`, append:
 ```markdown
 - frontend-rules — when task touches .tsx/.vue/.svelte/.razor/.cshtml/.html/.twig/.erb/.blade.php. WCAG 2.2 AA + UX.
@@ -430,9 +446,12 @@ If `has_frontend=true`, append:
 - kiss — gate 5: over-engineering — interface with 1 impl, factory for new(), pass-through, deep inheritance.
 - yagni — gate 5: speculative code — optional params never passed, TODO without ticket, generic with 1 type.
 - clean-code — bad names, long functions, magic numbers, silent catch, boolean params, redundant comments.
+- {CODE_DESIGN_SKILL} — gate 5: enforce INVIOLABLE structural rules for the project's locked code design. BLOCKED on violations defined by the skill.
 </skills_to_load>
 ```
 
+Replace `{CODE_DESIGN_SKILL}` with the same resolved entry — both doer and reviewer load the SAME code-design skill.
+
 If `has_frontend=true`, append:
 ```markdown
 - frontend-rules — gate 5 frontend: <input> without label, button without aria-label, localStorage with token, outline removed.

package/core/agents/jdi-researcher.md

@@ -90,10 +90,11 @@ Options:
 - Vertical Slice
 - Clean Architecture
 - Hexagonal (Ports & Adapters)
+- Onion Architecture
 - The Method (Juval Löwy)
 - "Don't know, suggest" (-> recommend based on type + stack)
 
-Locked for the life of the project (global rule).
+Locked for the life of the project (global rule). Mutually exclusive — the project uses exactly ONE code design. The choice is enforced by a JDI skill loaded into doer + reviewer (one of: `ddd`, `vertical-slice`, `clean-architecture`, `hexagonal`, `onion`, `the-method`).
 
 **Q4 — MVP scope**
 "Which minimum features for the MVP? (comma-separated)"

package/core/commands/jdi-add-phase.md

@@ -0,0 +1,171 @@
+---
+name: jdi-add-phase
+description: Adds a new phase to ROADMAP.md. Append at end (default) or insert at a specific position. Bumps total_phases. Atomic commit.
+argument_hint: "\"<phase name>\" [--goal \"<goal>\"] [--at <position>]"
+runtime_intent:
+  invokes_agent: none
+runtime_overrides:
+  claude:
+    allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion]
+  copilot:
+    tools: [read, write, edit, grep, glob, terminal]
+  opencode:
+    subtask: true
+  antigravity:
+    triggers:
+      - "/jdi-add-phase"
+      - "add new phase"
+      - "create phase"
+---
+
+<objective>
+Adds a new phase to the project's roadmap. Edits `.jdi/ROADMAP.md`. Does not start the phase — only registers it. The user advances via `/jdi-discuss <N>` when ready.
+</objective>
+
+<arguments>
+- `name` (required) — short phase name. Quote if it contains spaces.
+- `--goal "<text>"` (optional) — 1-line description of what the phase delivers. If missing, AskUserQuestion will prompt.
+- `--at <position>` (optional) — insert at this position instead of appending. Existing phases at and after `<position>` shift down by 1 (renumbered in ROADMAP only — slugs stay the same in any existing `.jdi/phases/` folders). Default: append.
+
+Examples:
+- `/jdi-add-phase "User authentication" --goal "Login + signup + JWT"`
+- `/jdi-add-phase "Performance pass" --at 3`
+- `/jdi-add-phase "Hotfix N+1 query"`
+</arguments>
+
+<process>
+
+### Step 1: Validation
+```bash
+test -d .jdi/ || { echo "Not a JDI project. /jdi-new first."; exit 1; }
+test -f .jdi/ROADMAP.md || { echo "ROADMAP.md missing."; exit 1; }
+test -f .jdi/STATE.md || { echo "STATE.md missing."; exit 1; }
+```
+
+If `<name>` argument missing: AskUserQuestion "Phase name?" (free text). Required.
+
+If `--goal` flag missing: AskUserQuestion "Phase goal (1 line)?" (free text). Required.
+
+### Step 2: Compute phase number + slug
+
+Read `total_phases` from `.jdi/ROADMAP.md`:
+
+```bash
+TOTAL=$(grep -oE 'total_phases:\s*[0-9]+' .jdi/ROADMAP.md | grep -oE '[0-9]+')
+```
+
+PowerShell:
+```powershell
+$total = (Select-String -Path .jdi/ROADMAP.md -Pattern 'total_phases:\s*([0-9]+)').Matches[0].Groups[1].Value -as [int]
+```
+
+If `--at <pos>` provided, validate `1 <= pos <= total + 1`. Otherwise `pos = total + 1` (append).
+
+If `pos <= current_phase` (read from STATE.md), abort with error: "Cannot insert before current phase {current}. Use --at {current+1} or higher."
+
+Generate `slug` from `name`:
+- Lowercase
+- Replace accents (à → a, é → e, ç → c, ñ → n)
+- Non-alphanumeric → `-`
+- Collapse repeated `-`, strip leading/trailing `-`
+- Truncate to 40 chars
+
+Phase identifier prefix is the 2-digit position (`NN`): `01`, `02`, ..., zero-padded.
+
+### Step 3: Renumber prefix on shift (only if --at)
+
+If `--at <pos>` shifts existing phases:
+
+Edit `.jdi/ROADMAP.md` — for every existing `### Phase K:` where `K >= pos`, change to `### Phase K+1:` and bump its `**Slug:**` prefix from `KK-...` to `(K+1)(K+1)-...`.
+
+**WARNING (printed):**
+> "Renumbering ROADMAP phases. Any existing `.jdi/phases/<NN-slug>/` folders are NOT renamed — they keep their original slugs and become "history". New work in renumbered phases creates new folders. Commits referencing old `phase {K}` remain valid as history."
+
+This is intentional. Do not rename `.jdi/phases/` folders — would break commit history and cross-references in DECISIONS.md.
+
+If `--at` not provided (append), skip Step 3.
+
+### Step 4: Append phase section to ROADMAP.md
+
+If appending (`pos == total + 1`), append at the bottom of `## Phases`:
+
+```markdown
+
+### Phase {pos}: {name}
+- **Slug:** {NN}-{slug}
+- **Status:** pending
+- **Goal:** {goal}
+```
+
+If inserting (`pos <= total`), insert the new section BEFORE the section that previously had number `pos` (now renumbered to `pos+1`).
+
+### Step 5: Bump total_phases
+
+Edit `.jdi/ROADMAP.md`:
+```
+total_phases: {TOTAL + 1}
+```
+
+### Step 6: Audit trail in DECISIONS.md (optional, only if user passes --reason)
+
+Not required. If user wants to record why this phase was added mid-project, they pass `--reason "<text>"`. When present, append to `.jdi/DECISIONS.md`:
+
+```markdown
+D-{N+1} ({date}, phase {pos}): Phase added mid-project. Reason: {reason}
+```
+
+(N = current max D-X.)
+
+### Step 7: Commit
+
+```bash
+git add .jdi/ROADMAP.md .jdi/DECISIONS.md 2>/dev/null
+git commit -m "chore(jdi): add phase {pos} {NN-slug}"
+```
+
+PowerShell:
+```powershell
+git add .jdi/ROADMAP.md .jdi/DECISIONS.md 2>$null
+git commit -m "chore(jdi): add phase $pos $NN-$slug"
+```
+
+### Step 8: Confirm
+
+```
+Phase {pos}: {name} added.
+Slug: {NN}-{slug}
+Goal: {goal}
+Status: pending
+total_phases: {TOTAL + 1}
+
+Next: /jdi-discuss {pos} (when ready to start this phase)
+```
+
+</process>
+
+<gates>
+- pre: `.jdi/ROADMAP.md` + `.jdi/STATE.md` exist
+- pre: `--at <pos>` (if used) is greater than `current_phase` in STATE.md
+- post: ROADMAP.md has new phase section + bumped total_phases + atomic commit
+</gates>
+
+<errors>
+- `.jdi/` missing -> "Run /jdi-new first"
+- `--at <pos>` <= current_phase -> "Cannot insert before current phase. Use --at {current+1} or higher."
+- `--at <pos>` < 1 or > total+1 -> "Position out of range. Valid: 1..{total+1}"
+- Phase name empty -> AskUserQuestion to fill
+- Goal empty -> AskUserQuestion to fill
+</errors>
+
+<runtime_notes>
+
+**Claude Code:**
+- AskUserQuestion handles missing args interactively.
+
+**Copilot:**
+- AskUserQuestion not always available — read missing args from prompt body or fail with clear error.
+
+**OpenCode/Antigravity:**
+- Same interactive flow as Claude when supported. Otherwise fail with clear error message asking the user to re-invoke with all args.
+
+</runtime_notes>

package/core/commands/jdi-remove-phase.md

@@ -0,0 +1,228 @@
+---
+name: jdi-remove-phase
+description: Removes a phase from ROADMAP.md. Refuses to remove done phases or the current phase. Archives any existing phase artifacts. Atomic commit.
+argument_hint: "<phase_number> [--force]"
+runtime_intent:
+  invokes_agent: none
+runtime_overrides:
+  claude:
+    allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion]
+  copilot:
+    tools: [read, write, edit, grep, glob, terminal]
+  opencode:
+    subtask: true
+  antigravity:
+    triggers:
+      - "/jdi-remove-phase"
+      - "remove phase"
+      - "delete phase"
+---
+
+<objective>
+Removes a phase from `.jdi/ROADMAP.md`. Refuses to remove the current phase or any phase already shipped. If the phase has artifacts under `.jdi/phases/<NN-slug>/`, moves them to `.jdi/archive/removed-<NN-slug>/` instead of deleting (preserves history).
+</objective>
+
+<arguments>
+- `phase_number` (required) — number of the phase to remove (as listed in ROADMAP.md).
+- `--force` (optional) — required when removing a phase that has any artifacts in `.jdi/phases/`. Without `--force`, the command refuses and explains.
+
+Examples:
+- `/jdi-remove-phase 4`
+- `/jdi-remove-phase 5 --force`
+</arguments>
+
+<process>
+
+### Step 1: Validation
+
+```bash
+test -d .jdi/ || { echo "Not a JDI project."; exit 1; }
+test -f .jdi/ROADMAP.md || { echo "ROADMAP.md missing."; exit 1; }
+test -f .jdi/STATE.md || { echo "STATE.md missing."; exit 1; }
+
+# Argument required
+[ -n "$1" ] || { echo "Phase number required. Usage: /jdi-remove-phase <N> [--force]"; exit 1; }
+```
+
+Parse `phase_number` (positional). Parse `--force` flag.
+
+### Step 2: Read state
+
+```bash
+CURRENT=$(grep -oE 'current_phase:\s*[0-9]+' .jdi/STATE.md | grep -oE '[0-9]+')
+TOTAL=$(grep -oE 'total_phases:\s*[0-9]+' .jdi/ROADMAP.md | grep -oE '[0-9]+')
+PHASE_NUMBER=$1
+```
+
+PowerShell:
+```powershell
+$current = (Select-String -Path .jdi/STATE.md -Pattern 'current_phase:\s*([0-9]+)').Matches[0].Groups[1].Value -as [int]
+$total = (Select-String -Path .jdi/ROADMAP.md -Pattern 'total_phases:\s*([0-9]+)').Matches[0].Groups[1].Value -as [int]
+$phaseNumber = [int]$args[0]
+```
+
+### Step 3: Hard refuses (no override)
+
+```bash
+# Must be in range
+if [ "$PHASE_NUMBER" -lt 1 ] || [ "$PHASE_NUMBER" -gt "$TOTAL" ]; then
+  echo "Phase $PHASE_NUMBER does not exist. Valid: 1..$TOTAL"
+  exit 1
+fi
+
+# Cannot remove past phases (preserves history)
+if [ "$PHASE_NUMBER" -lt "$CURRENT" ]; then
+  echo "Cannot remove phase $PHASE_NUMBER — already past. current_phase is $CURRENT. Past phases are immutable history."
+  exit 1
+fi
+
+# Cannot remove the current phase
+if [ "$PHASE_NUMBER" -eq "$CURRENT" ]; then
+  echo "Cannot remove the current phase ($CURRENT). Ship or abandon it first, then advance current_phase."
+  exit 1
+fi
+```
+
+Read the phase's `Status:` from ROADMAP:
+
+```bash
+STATUS=$(awk "/### Phase $PHASE_NUMBER:/,/^### Phase /" .jdi/ROADMAP.md | grep -oE 'Status:\*\* (pending|ready|done|partial|blocked|in-progress)' | head -1 | awk '{print $2}')
+```
+
+If `STATUS == done`: refuse hard.
+```
+Phase $PHASE_NUMBER is `done`. Cannot remove. Shipped phases are immutable history.
+```
+
+### Step 4: Detect artifacts
+
+Find the phase folder under `.jdi/phases/`:
+
+```bash
+NN=$(printf '%02d' "$PHASE_NUMBER")
+PHASE_DIR=$(ls -d .jdi/phases/${NN}-*/ 2>/dev/null | head -1 || true)
+```
+
+PowerShell:
+```powershell
+$nn = '{0:D2}' -f $phaseNumber
+$phaseDir = Get-ChildItem .jdi/phases/ -Directory -Filter "$nn-*" -ErrorAction SilentlyContinue | Select-Object -First 1
+```
+
+If `PHASE_DIR` exists AND `--force` NOT passed: refuse.
+```
+Phase $PHASE_NUMBER has artifacts in $PHASE_DIR (CONTEXT/PLAN/SUMMARY/REVIEW).
+Re-run with --force to archive these artifacts to .jdi/archive/removed-<NN-slug>/ and proceed.
+```
+
+### Step 5: Confirm with user (irreversible-ish action)
+
+AskUserQuestion (always run, even with --force):
+
+> "Remove phase $PHASE_NUMBER: '$PHASE_NAME'?
+>
+> Status: $STATUS
+> Artifacts: ${PHASE_DIR:-none}
+> Action: ROADMAP section removed, total_phases decremented, artifacts (if any) moved to .jdi/archive/removed-<NN-slug>/."
+>
+> Options:
+> - [Yes, remove]
+> - [Cancel]
+
+If "Cancel" -> exit clean.
+
+### Step 6: Archive artifacts (if any)
+
+```bash
+if [ -n "$PHASE_DIR" ]; then
+  mkdir -p .jdi/archive
+  test -f .jdi/archive/index.md || echo "# Archive index" > .jdi/archive/index.md
+
+  BASENAME=$(basename "$PHASE_DIR")
+  TARGET=".jdi/archive/removed-$BASENAME"
+  mv "$PHASE_DIR" "$TARGET"
+  echo "- removed-$BASENAME (removed $(date -u +%F) via /jdi-remove-phase)" >> .jdi/archive/index.md
+fi
+```
+
+PowerShell:
+```powershell
+if ($phaseDir) {
+  if (-not (Test-Path .jdi/archive)) { New-Item -ItemType Directory .jdi/archive | Out-Null }
+  if (-not (Test-Path .jdi/archive/index.md)) { Set-Content .jdi/archive/index.md "# Archive index" }
+  $basename = $phaseDir.Name
+  $target = ".jdi/archive/removed-$basename"
+  Move-Item $phaseDir.FullName $target
+  Add-Content .jdi/archive/index.md "- removed-$basename (removed $(Get-Date -Format 'yyyy-MM-dd') via /jdi-remove-phase)"
+}
+```
+
+### Step 7: Edit ROADMAP.md
+
+Remove the entire `### Phase $PHASE_NUMBER: ...` block (header + bullets) up to (but not including) the next `### Phase ` line or end of file.
+
+Decrement `total_phases`:
+```
+total_phases: {TOTAL - 1}
+```
+
+**Do NOT renumber** subsequent phases. Phases after the removed one keep their original numbers. This preserves all references in commit history, `DECISIONS.md`, and archived phase folders. The roadmap simply has a gap (e.g., 1, 2, 3, 5, 6 — 4 was removed).
+
+### Step 8: Audit trail in DECISIONS.md
+
+Append:
+```markdown
+D-{N+1} ({date}): Phase $PHASE_NUMBER removed via /jdi-remove-phase. Artifacts: ${PHASE_DIR:+archived to .jdi/archive/removed-<NN-slug>/}{none if empty}.
+```
+
+### Step 9: Commit
+
+```bash
+git add .jdi/ROADMAP.md .jdi/DECISIONS.md .jdi/archive/ 2>/dev/null
+git commit -m "chore(jdi): remove phase {PHASE_NUMBER}"
+```
+
+### Step 10: Confirm
+
+```
+Phase {PHASE_NUMBER} removed.
+{if artifacts:} Artifacts archived: .jdi/archive/removed-{NN-slug}/
+total_phases: {TOTAL - 1}
+
+Note: phase numbers are not renumbered — references in commits, DECISIONS, and archive remain valid.
+```
+
+</process>
+
+<gates>
+- pre: `.jdi/ROADMAP.md` + `.jdi/STATE.md` exist
+- pre: `phase_number` is in range `1..total_phases`
+- pre: `phase_number > current_phase`
+- pre: phase status != `done`
+- pre: `--force` provided when phase has artifacts
+- post: ROADMAP.md section removed + total_phases decremented + artifacts archived (if any) + DECISIONS.md appended + atomic commit
+</gates>
+
+<errors>
+- `.jdi/` missing -> "Run /jdi-new first"
+- `phase_number` missing -> usage hint
+- `phase_number` out of range -> "Valid: 1..{total}"
+- `phase_number < current_phase` -> refuse (past = history)
+- `phase_number == current_phase` -> refuse (ship or abandon first)
+- phase status `done` -> refuse (shipped = history)
+- artifacts exist + no `--force` -> refuse + suggest `--force`
+- user cancels at AskUserQuestion -> exit clean
+</errors>
+
+<runtime_notes>
+
+**Claude Code:**
+- Confirms via AskUserQuestion.
+
+**Copilot:**
+- AskUserQuestion not always available — require explicit `--yes` flag as fallback.
+
+**OpenCode/Antigravity:**
+- Same interactive confirm as Claude. Fallback to `--yes` when prompts unsupported.
+
+</runtime_notes>

package/core/skills/clean-architecture/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: clean-architecture
+description: Clean Architecture (Robert C. Martin). 4 concentric layers - Entities, Use Cases, Interface Adapters, Frameworks & Drivers. The Dependency Rule points strictly inward. Language-agnostic rigid rules. Mutually exclusive with The Method, DDD, Hexagonal, Onion, Vertical Slice.
+type: skill
+applies_to: |
+  Loaded by doer and reviewer when PROJECT.md `Code Design` is `Clean Architecture`.
+  Inviolable design rules. Doer applies during creation. Reviewer enforces at gate 5.
+loaded_by:
+  - jdi-doer-{slug}
+  - jdi-reviewer-{slug}
+runtime_overrides:
+  antigravity:
+    triggers:
+      - "Clean Architecture"
+      - "Robert Martin clean"
+      - "Dependency Rule"
+      - "Use Cases layer"
+---
+
+# Skill: Clean Architecture
+
+Rigid, inviolable rules from Robert C. Martin's *Clean Architecture*. The system is organized as **concentric layers**, and source-code dependencies point only **inward**.
+
+Clean Architecture is the ONLY allowed design when PROJECT.md `Code Design: LOCKED: Clean Architecture`. Do not mix with The Method, DDD aggregates as a primary structure, Hexagonal terminology as the primary structure, Onion shells, or Vertical Slice feature folders as the primary structure.
+
+## The 4 layers (mandatory)
+
+From innermost to outermost:
+
+1. **Entities (Enterprise Business Rules)** — the most general and high-level rules. Reusable across applications in the enterprise. Pure data + behavior. No knowledge of any other layer.
+2. **Use Cases (Application Business Rules)** — application-specific business rules. Orchestrate the dance of Entities to satisfy a use case. No knowledge of UI, DB, frameworks, devices, or external systems.
+3. **Interface Adapters** — convert data between the form most convenient for use cases/entities and the form most convenient for external agents. Controllers, Presenters, Gateways, ViewModels live here. No knowledge of frameworks beyond what is necessary to expose adapter contracts.
+4. **Frameworks & Drivers** — the outermost layer. Web framework, database, UI framework, file system, devices, external APIs. Glue code only — minimal logic.
+
+Every code unit belongs to exactly one of these 4 layers. A unit that does not fit must be redesigned.
+
+## The Dependency Rule (inviolable)
+
+**Source-code dependencies point only inward. Nothing in an inner circle may know anything at all about something in an outer circle.**
+
+1. Entities depend on nothing outside the Entities layer.
+2. Use Cases depend on Entities only. Use Cases do not import, reference, or know the names of anything in Interface Adapters or Frameworks & Drivers.
+3. Interface Adapters depend on Use Cases and Entities only. They do not depend on Frameworks & Drivers code directly — they depend on framework abstractions only where unavoidable, and never let framework types cross into the inner circles.
+4. Frameworks & Drivers depend on whatever is convenient (Adapters, libraries, vendor SDKs).
+5. Names defined in outer circles (e.g., entity names from a DB schema, DTOs from a controller, framework annotations) must not appear in inner-circle code.
+
+## Boundary Crossing rules (inviolable)
+
+1. **Cross boundaries via interfaces owned by the inner side.** Inputs into Use Cases are defined by interfaces in the Use Cases layer; implementations live in Interface Adapters.
+2. **Cross boundaries via Data Transfer Objects (DTOs) that are simple structures.** No framework objects, no ORM entities, no HTTP request objects cross a boundary.
+3. **Use Cases never receive framework-specific types** (HTTP request, ORM entity, file handle, socket). The Adapter translates these into the Use Case's input DTOs.
+4. **Use Cases return DTOs / output ports.** They never return entities directly to outer layers.
+5. **The Use Case interactor invokes an output port (interface) to deliver results.** The Presenter implements the output port. Use Cases never call presenters or controllers directly.
+
+## Layer purity rules (inviolable)
+
+### Entities
+
+1. Entities are pure. No imports from any other layer.
+2. Entities encapsulate enterprise-wide business rules; if a rule is application-specific, it does not belong here.
+3. Entities are not Database records, ORM models, JSON shapes, or API DTOs. If a class plays one of those roles, it is not an Entity.
+4. Entities have no annotations from persistence, serialization, or web frameworks.
+5. Entities are not anemic. Behavior lives with data.
+
+### Use Cases
+
+6. Each Use Case has a single, application-specific purpose stated by its name (verb-noun: e.g., `RegisterCustomer`, `RenewSubscription`).
+7. A Use Case owns its input port (input boundary) and output port (output boundary) as interfaces in the Use Cases layer.
+8. A Use Case does not import any framework, ORM, HTTP, file-system, or external-API type.
+9. A Use Case is testable without any infrastructure. If it cannot be tested without spinning up DB / HTTP / queue, the design is wrong.
+10. A Use Case orchestrates Entities. It does not duplicate enterprise rules that already live in Entities.
+
+### Interface Adapters
+
+11. Controllers translate external input (HTTP request, CLI args, message payload) into Use Case input DTOs and invoke the Use Case.
+12. Presenters convert Use Case output DTOs into a form suitable for delivery (ViewModel, response body).
+13. Gateways implement the persistence interfaces declared by the Use Cases.
+14. Adapters never contain business rules.
+15. Adapters depend inward on Use Cases / Entities, never outward on Frameworks.
+
+### Frameworks & Drivers
+
+16. Framework code is glue only. It wires Adapters to the framework runtime.
+17. Web framework controllers in the Frameworks layer call Adapters, not Use Cases directly.
+18. ORM-mapped models, framework annotations, configuration code, dependency injection wiring live here.
+
+## Composition rules
+
+1. **Composition Root is in the outermost layer.** The main / startup / DI container assembles all components.
+2. **Inner layers never construct outer layer types.** Dependencies are injected through interfaces defined by the inner layer.
+3. **Plug-in architecture.** A change in framework, DB, or UI must require changes only in the outer layers. Inner layers stay untouched.
+
+## Forbidden patterns (inviolable)
+
+- **Use Cases referencing framework types** (HTTP request, ORM entity, file handle, vendor SDK type).
+- **Entities referencing persistence frameworks** (ORM annotations, database column attributes that encode behavior).
+- **Anemic Entities.** Behavior must accompany data.
+- **Skipping a layer for convenience** (Controller calling a repository directly, Presenter calling the database).
+- **Returning framework / ORM types from a Use Case.**
+- **Use Case knowing the concrete Adapter** (e.g., calling a specific HTTP client class). Use Cases declare interfaces; Adapters implement.
+- **Shared "Util" / "Helper" classes spanning layers** with hidden business rules.
+- **Database-driven design** where the schema dictates Entity shape.
+- **Cross-layer reach-around** (Framework code calling Use Cases bypassing Adapters, Adapters calling Frameworks bypassing the Composition Root).
+- **Concentric layers reorganized as feature folders** that hide which layer a unit belongs to.
+
+## Reviewer enforcement (gate 5)
+
+Reviewer rejects (BLOCKED) when:
+- An Entity or Use Case imports a framework, ORM, HTTP, or vendor SDK type.
+- A Use Case returns a framework / ORM / DTO defined in an outer layer.
+- A Controller invokes persistence directly instead of going through a Use Case.
+- An Adapter contains a business rule.
+- An inner-layer file imports an outer-layer file (direct dependency violation).
+- Boundary crossings carry framework-specific types instead of plain DTOs.
+- Use Cases or Entities are not testable without infrastructure.
+
+Reviewer warns (APPROVED_WITH_WARNINGS) when:
+- A Use Case is named after a CRUD verb without application semantics.
+- An Entity has only getters/setters (anemic).
+- An Adapter file leaks framework annotations into its public interface.
+- The Composition Root is split across layers instead of living in the outermost layer.
+
+## Anti-patterns
+
+- "Service" layer mixing Use Cases with Adapter responsibilities
+- DTOs leaking into Entities
+- ORM entities serving as both Entity and persistence model
+- Controller-with-business-logic
+- Use Case classes that depend on framework annotations
+- Hexagonal-style port terminology used to disguise a violation (the rule is the Dependency Rule, not the port naming)
+
+## Outputs
+
+Does NOT produce own files. Modifies parent agent's structural decisions during code authoring and review.