jdi-cli 0.1.1 → 0.1.3

package/runtimes/antigravity/skills/the-method/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: the-method
+description: The Method (Juval Löwy, "Righting Software"). Volatility-based decomposition with universal hierarchy (Clients, Managers, Engines, ResourceAccess, Resources, Utilities). Strict communication rules. Language-agnostic. Mutually exclusive with DDD, Clean Architecture, Hexagonal, Onion, Vertical Slice.
+triggers:
+  - "The Method"
+  - "Juval Lowy"
+  - "Righting Software"
+  - "volatility decomposition"
+  - "Universal Hierarchy"
+---
+
+# Skill: The Method (Juval Löwy)
+
+Rigid, inviolable design rules from Juval Löwy's *Righting Software*. Decompose by **volatility**, not functionality. Single architecture in the system — do not mix with any other code design.
+
+The Method is the ONLY allowed design when PROJECT.md `Code Design: LOCKED: The Method`. Do not introduce DDD aggregates, Clean Architecture use cases, Hexagonal ports, Onion shells, or Vertical Slice handlers. Do not invent a hybrid.
+
+## Core principle (inviolable)
+
+**Decompose the system by axes of volatility, never by functionality.**
+
+A component is justified only when it encapsulates an independent reason to change. Two pieces of code that change for the same reason belong together. Two pieces that change for different reasons must be separated even if they currently look identical.
+
+If a component has no clear volatility it encapsulates, it must not exist.
+
+## The Universal Hierarchy (mandatory)
+
+Every system has exactly these 5 architectural categories plus 1 cross-cutting category. No other category may be invented.
+
+1. **Clients** — entry points. UI, CLI, public API endpoints, scheduled triggers, test harnesses. Volatility: presentation, protocol, channel.
+2. **Managers** — own a use case end-to-end. Sequence the work. Hold the workflow. Volatility: business workflow, use case orchestration.
+3. **Engines** — stateless business algorithms. Pure rules, calculations, validation logic. Volatility: business algorithm, formula, policy.
+4. **ResourceAccess** — only path to a Resource. Hides the technology of the data store. Volatility: data access technology.
+5. **Resources** — the actual data store / external system / queue / cache. Volatility: storage technology, vendor, schema.
+
+Cross-cutting (callable from any layer):
+
+6. **Utilities** — Security, Logging, Diagnostics, Hosting, Configuration, Localization, Pub/Sub bus, Identity. Stateless cross-cutting concerns. Volatility: infrastructure technology.
+
+Every code unit produced MUST belong to exactly one of these categories. If you cannot decide its category, the unit is wrong and must be redesigned.
+
+## Communication rules (inviolable)
+
+The hierarchy is strictly directed. Communication that violates these rules is a defect, regardless of how convenient it appears.
+
+1. **Clients call Managers only.** Clients do not call Engines, ResourceAccess, Resources, or other Clients.
+2. **Managers call Engines and ResourceAccess.** Managers may also call Utilities.
+3. **Managers do not call Managers directly.** Manager-to-Manager communication, when required, goes through a **Queue** (publish/subscribe via the Utility bus). Never synchronous Manager-to-Manager.
+4. **Engines do not call Engines.** Composition of engines happens in the Manager.
+5. **Engines do not call ResourceAccess.** The Manager pulls data via ResourceAccess and passes it into the Engine.
+6. **Engines and ResourceAccess do not call Clients.** No upward calls.
+7. **ResourceAccess is the only component allowed to touch a Resource.** Nothing else (no Manager, no Engine, no Client, no Utility) touches a Resource directly.
+8. **Resources do not call anything.** They are passive.
+9. **Utilities are callable by any layer, but do not contain business logic.** Utilities never call Managers, Engines, or ResourceAccess.
+10. **No skip-level calls upward.** Lower layers never call higher layers synchronously.
+11. **Calls fan out, never fan in across the same layer synchronously.** No sideways synchronous calls within Managers or within Engines.
+
+## Volatility rules (inviolable)
+
+1. A component exists only to **encapsulate one axis of volatility**. State it explicitly.
+2. The component's public surface must change only when its encapsulated volatility changes. If a change to an unrelated axis requires editing the component, the decomposition is wrong.
+3. The more volatile the area, the deeper inside the architecture it lives. The more stable, the closer to the edges.
+4. **Functional decomposition is forbidden.** Naming components after features ("OrderManager", "CustomerEngine") is allowed only when the feature itself is a volatility boundary. Naming components after operations ("CreateOrder", "ValidateCustomer") is forbidden.
+5. **Naming after volatility, not noun.** Prefer `PricingEngine` (algorithm volatility) over `OrderService` (feature). Prefer `OrderRepository` only if data-access technology is the encapsulated volatility.
+
+## Composability rules
+
+1. Every Manager must be composable. Adding a new Client (new UI, new API) must not require touching the Manager.
+2. Engines and ResourceAccess components must be reusable across Managers. If they cannot be reused, the volatility encapsulation is wrong.
+3. The system must support adding a new use case by adding 1 Manager (and possibly 1 Client method) without modifying any Engine, ResourceAccess, Resource, or Utility.
+
+## Forbidden patterns (inviolable)
+
+- **No domain-driven aggregates, anti-corruption layers, or bounded contexts** — that is DDD.
+- **No use cases as a separate layer** — Managers ARE the use cases. Do not create a "UseCase" layer on top of Managers.
+- **No ports & adapters / hexagonal terminology** — ResourceAccess plays the role of adapter for Resources. Do not introduce additional port/adapter layers.
+- **No vertical slices** — code is organized by category, never by feature folder.
+- **No Onion shells.** No "domain core" layer above Engines.
+- **No Repository pattern named after entities** ("UserRepository", "OrderRepository"). ResourceAccess is named after the **resource technology and its volatility**, not after a domain entity. Acceptable: `BillingDataAccess`, `CatalogStore`. Forbidden: `OrderRepository` if "Order" is not a volatility boundary.
+- **No anemic Engine** — an Engine without business logic is forbidden. An Engine with only getters/setters is a defect.
+- **No business logic in Clients.** Clients only translate input to a Manager call and present a Manager response.
+- **No business logic in ResourceAccess.** ResourceAccess maps technology to in-memory representations and nothing more.
+- **No business logic in Resources.** Stored procedures, triggers, or business-logic-bearing schemas are violations.
+- **No business logic in Utilities.** Utilities are infrastructure.
+- **No bypassing ResourceAccess** to touch a Resource (no ORM call in a Manager, no raw SQL in an Engine).
+- **No shared mutable state across components.** Engines are stateless. Managers hold transient workflow state only.
+
+## Mandatory acceptance per code unit
+
+Before any Manager / Engine / ResourceAccess / Client / Utility is committed, the author must be able to answer:
+
+1. Which one of the 6 categories does this belong to? (must be exactly one)
+2. What single axis of volatility does it encapsulate? (must be statable in 1 sentence)
+3. Which categories does it call? (must comply with the communication rules above)
+4. What change in the system would cause it to be edited? (must be the volatility it encapsulates, nothing else)
+5. Is it composable: can another Manager / Client be added without modifying this unit? (must be yes for non-Client units)
+
+A unit failing any answer must be redesigned before it ships.
+
+## Reviewer enforcement (gate 5)
+
+Reviewer rejects (BLOCKED) when:
+- A Client calls Engine / ResourceAccess / Resource directly.
+- A Manager calls another Manager synchronously.
+- An Engine calls another Engine.
+- An Engine calls ResourceAccess.
+- Any code outside ResourceAccess touches a Resource.
+- A Utility contains business logic.
+- A Repository / Service / Manager is named after a noun-entity instead of a volatility axis (warn first, block on second occurrence in the same PR).
+- The PR adds a new top-level category not in the universal hierarchy.
+- The PR splits code by feature folders instead of by category.
+
+Reviewer warns (APPROVED_WITH_WARNINGS) when:
+- A component's encapsulated volatility is not declared (missing 1-line statement at top of file or class).
+- An Engine has no behavior (anemic).
+- A new Manager was added without a Client-level entry point.
+
+## Anti-patterns
+
+- "Service layer" with mixed Manager + Engine responsibilities
+- "Helper" / "Util" classes containing business logic
+- Domain entity classes with both data and behavior bound to persistence
+- "Facade" components that hide multiple Managers behind a single class
+- ResourceAccess methods that return business-decided values instead of raw data
+- Cross-Manager transactions implemented via direct calls
+- Synchronous chains crossing 3+ layers
+
+## Outputs
+
+Does NOT produce own files. Modifies parent agent's structural decisions during code authoring and review.

package/runtimes/antigravity/skills/vertical-slice/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: vertical-slice
+description: Vertical Slice Architecture (Jimmy Bogard). Organize by feature, not by technical layer. Each feature owns its full request-to-response path with minimal sharing. Language-agnostic rigid rules. Mutually exclusive with The Method, DDD, Clean Architecture, Hexagonal, Onion.
+triggers:
+  - "Vertical Slice"
+  - "Jimmy Bogard"
+  - "feature folder"
+  - "slice architecture"
+---
+
+# Skill: Vertical Slice Architecture
+
+Rigid, inviolable rules from Jimmy Bogard's Vertical Slice Architecture. The system is organized by **feature**, not by technical layer. Each slice owns the full path from external request to external response.
+
+Vertical Slice is the ONLY allowed design when PROJECT.md `Code Design: LOCKED: Vertical Slice`. Do not impose Clean Architecture's 4-layer structure, Onion shells, Hexagonal core/ports/adapters, DDD aggregates as primary structure, or The Method's universal hierarchy on top.
+
+## Mandatory structure
+
+1. **Each feature is one slice.** A feature is a single user-facing capability (e.g., `RegisterCustomer`, `CancelOrder`, `RenewSubscription`).
+2. **A slice owns its full pipeline:** input contract, validator, handler, business logic, persistence access, output contract, and slice-specific tests.
+3. **Slices live in feature folders / packages.** The primary code organization is `features/{feature-name}/` (or equivalent in the language). Technical-layer folders (`controllers/`, `services/`, `repositories/`, `models/`) as the primary structure are forbidden.
+4. **Each feature folder is self-contained.** Inside a folder live only the artifacts that serve that feature.
+5. **No shared "Service" layer, no shared "Repository" layer, no shared "Manager" layer across slices.** Each slice has its own.
+
+## Slice isolation rules (inviolable)
+
+1. **Slices do not call each other directly.** If slice A needs work done by slice B, slice A either duplicates the minimum needed code OR they both publish/subscribe to a shared event bus. Direct invocation of slice B's handler from slice A is forbidden.
+2. **No shared mutable state across slices.** A slice never mutates state owned by another slice except through the shared persistence boundary, and never through another slice's handler.
+3. **DRY applies inside a slice, not across slices.** Two slices that look similar today are still allowed to diverge tomorrow. Forced sharing is the enemy.
+4. **Cross-slice abstractions are introduced only when 3+ slices need the exact same behavior with the exact same shape, and that behavior is stable.** Premature shared abstractions are violations.
+
+## Slice composition (mandatory contents)
+
+Each slice MUST contain:
+
+1. **Request / Command / Query contract** — a structure describing the input.
+2. **Handler** — receives the request, executes the logic, returns the response.
+3. **Validator** (if input requires validation) — slice-local validation rules.
+4. **Response contract** — the output shape returned to the caller.
+5. **Slice-local types** — any DTOs, view models, or projections the slice needs.
+6. **Slice-local tests** — integration tests that exercise the slice end-to-end.
+
+A slice MAY contain:
+
+- A slice-specific persistence access path (raw query, ORM query, projection, command-side persistence).
+- A slice-specific external system call.
+- Slice-local pre/post processing.
+
+A slice MUST NOT contain:
+
+- References to another slice's handler, request, or response types.
+- References to a shared "Service" abstracting multiple slices.
+- A "Manager" coordinating multiple slices.
+
+## Cross-cutting concerns (inviolable)
+
+1. Cross-cutting concerns (logging, authentication, authorization, transactions, validation pipeline, error handling) are applied as **pipeline behaviors / middleware** that wrap the handler, never as shared services injected into the handler.
+2. Authentication and authorization decisions may use shared types (claims, principals) but are enforced at the pipeline level, not inside the handler.
+3. Validation runs as a pipeline step before the handler executes. The handler assumes valid input.
+4. Logging, tracing, metrics: pipeline behaviors. The handler does not invoke logging libraries for cross-cutting purposes.
+
+## Persistence rules
+
+1. **No generic repository spanning slices.** A slice that needs persistence either uses the ORM/database client directly within the slice OR has its own slice-local repository.
+2. **Reads and writes may diverge structurally.** A slice that reads may use a different model than a slice that writes; this is encouraged.
+3. **No "Domain Model" required to be shared across slices.** Each slice models the data it needs in the shape it needs.
+4. **A shared schema (database) is acceptable; a shared in-code model abstraction is not.**
+
+## Forbidden patterns (inviolable)
+
+- **Technical-layer primary folders** (`controllers/`, `services/`, `repositories/`, `models/`) used as the system's primary organization.
+- **A handler calling another handler.**
+- **A "Service" class injected into multiple handlers** to provide their business logic.
+- **A "Manager" class coordinating multiple slices.**
+- **A shared "Repository" abstraction** consumed by 5+ slices.
+- **Cross-slice imports of internal slice types.** Slice A importing `B.HandleQuery` or `B.RequestDto` is forbidden.
+- **Slice A invoking slice B via an internal interface** instead of via the public boundary (HTTP, queue, event).
+- **DRY refactoring that merges 2 slices into 1 because they share 80% of the code.** Slices stay separate until 3+ identical use cases exist with stable shape.
+- **Forcing all slices through a shared base handler class** that contains business logic.
+- **A shared "Domain Model" referenced by all slices** as the primary modeling element.
+
+## Naming conventions
+
+- Feature folders: feature name in domain language (`RegisterCustomer/`, `CancelOrder/`, `ViewCustomerDashboard/`).
+- Request types: domain operation name (`RegisterCustomerCommand`, `CancelOrderCommand`, `ViewCustomerDashboardQuery`).
+- Handler types: paired with request (`RegisterCustomerHandler`).
+- Validator types: paired with request (`RegisterCustomerValidator`).
+- Response types: domain output name (`RegisterCustomerResponse`).
+- Internal slice types: prefixed by feature name when shared inside the slice (`RegisterCustomerEmailTemplate`).
+
+## Reviewer enforcement (gate 5)
+
+Reviewer rejects (BLOCKED) when:
+- The codebase is primarily organized by technical layer instead of by feature.
+- A handler invokes another slice's handler, request, or response type.
+- A new "Service" / "Manager" / "Coordinator" class is introduced that spans multiple slices and carries business logic.
+- A shared generic repository is introduced and consumed by multiple slices.
+- Cross-cutting concerns are injected into handlers as shared services instead of applied as pipeline behaviors.
+- Slice A imports types from slice B's internal folder.
+
+Reviewer warns (APPROVED_WITH_WARNINGS) when:
+- Two slices share an identical small helper that has been duplicated 3+ times (candidate for extraction, not required).
+- A slice contains logic that appears to belong to a different slice.
+- A slice handler is long enough to suggest splitting into pipeline behaviors.
+- A slice references a "Domain Service" or "Aggregate" terminology that may indicate a different design creeping in.
+
+## Anti-patterns
+
+- "Vertical slices" implemented inside an MVC controllers/services/repositories folder structure (the folders betray the layer-primary structure)
+- A "Domain" project that all slices reference, containing entities + services + repositories — that is layered or Onion in disguise
+- Cross-slice "Coordinator" classes that orchestrate two handlers
+- A shared "BaseHandler" that contains transaction management AND business logic
+- A slice handler that delegates 90% of its work to a shared service (the slice is hollow)
+- Premature "DRY" extraction that merges slices into a generic handler with strategy patterns
+
+## Outputs
+
+Does NOT produce own files. Modifies parent agent's structural decisions during code authoring and review.

package/runtimes/claude/CLAUDE.md

@@ -12,6 +12,10 @@ Este projeto usa o JDI (Just Do It) como workflow de desenvolvimento. JDI eh um
 /jdi-do <N>              -> executa via doer specialist
 /jdi-verify <N>          -> gates de qualidade via reviewer specialist
 /jdi-ship <N>            -> finaliza phase + avanca pra proxima
+
+# Roadmap mutation (qualquer hora)
+/jdi-add-phase "<name>" [--goal "<t>"] [--at <pos>]   -> adiciona phase
+/jdi-remove-phase <N> [--force]                        -> remove future/pending phase
 ```
 
 `/jdi-create [desc]` gera novos agents/skills genericos no `core/` (rodado dentro do repo JDI, nao de projetos consumindo).

package/runtimes/claude/agents/jdi-architect.md

@@ -381,13 +381,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.
@@ -400,9 +416,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/runtimes/claude/agents/jdi-researcher.md

@@ -56,10 +56,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/runtimes/claude/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>