jdi-cli 0.1.2 → 0.1.4

package/README.md

@@ -1,5 +1,20 @@
 # JDI — Just Do It
 
+```
+       ██╗██████╗ ██╗
+       ██║██╔══██╗██║
+       ██║██║  ██║██║
+  ██   ██║██║  ██║██║
+  ╚█████╔╝██████╔╝██║
+   ╚════╝ ╚═════╝ ╚═╝
+
+  ◄══════════════════════════════════════════════|=|◉|=|/////|==
+  ◄══════════════════════════════════════════════|=|◉|=|/////|==
+  ◄══════════════════════════════════════════════|=|◉|=|/////|==
+
+  Cut through the chaos. Ship the work. [Just do it]
+```
+
 Lean workflow toolkit for solo dev + AI assistant. Adaptive loop, atomic commits, file-based state, fresh context per agent, wave-based parallelism. Per-project specialists that already know your stack.
 
 ## Why
@@ -27,6 +42,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 +546,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/bin/jdi.js

@@ -116,14 +116,14 @@ function ensureScope(scope) {
 // Commands
 // =================================================================
 
-function cmdInstall({ positional, flags }) {
+async function cmdInstall({ positional, flags }) {
   const runtime = positional[0];
   const scope = flags.scope || 'project';
 
   ensureRuntime(runtime);
   ensureScope(scope);
 
-  ui.banner();
+  await ui.bannerAnimated();
 
   ui.header(`Instalando JDI para ${c.bold}${runtime}${c.reset}`);
   ui.info(`Diretorio: ${c.dim}${process.cwd()}${c.reset}`);
@@ -163,8 +163,8 @@ function cmdInstall({ positional, flags }) {
   }
 }
 
-function cmdBuild({ flags }) {
-  ui.banner();
+async function cmdBuild({ flags }) {
+  await ui.bannerAnimated();
 
   ui.header('Building JDI runtimes');
   ui.info(`Source: ${c.dim}${PKG_ROOT}/core/${c.reset}`);
@@ -188,8 +188,8 @@ function cmdBuild({ flags }) {
   }
 }
 
-function cmdUpdate({ flags }) {
-  ui.banner();
+async function cmdUpdate({ flags }) {
+  await ui.bannerAnimated();
 
   ui.header('JDI Update');
   ui.info(`Diretorio: ${c.dim}${process.cwd()}${c.reset}`);
@@ -213,8 +213,8 @@ function cmdUpdate({ flags }) {
   }
 }
 
-function cmdUninstall({ positional, flags }) {
-  ui.banner();
+async function cmdUninstall({ positional, flags }) {
+  await ui.bannerAnimated();
 
   ui.header('JDI Uninstall');
   ui.info(`Diretorio: ${c.dim}${process.cwd()}${c.reset}`);
@@ -245,8 +245,8 @@ function cmdUninstall({ positional, flags }) {
   }
 }
 
-function cmdInstallPlaywright({ flags }) {
-  ui.banner();
+async function cmdInstallPlaywright({ flags }) {
+  await ui.bannerAnimated();
 
   ui.header('JDI: Install Playwright + MCP');
   ui.info(`Directory: ${c.dim}${process.cwd()}${c.reset}`);
@@ -282,8 +282,8 @@ function cmdInstallPlaywright({ flags }) {
   }
 }
 
-function cmdInstallCaveman({ flags }) {
-  ui.banner();
+async function cmdInstallCaveman({ flags }) {
+  await ui.bannerAnimated();
 
   ui.header('JDI: Install Caveman plugin');
   ui.info(`Directory: ${c.dim}${process.cwd()}${c.reset}`);
@@ -317,8 +317,8 @@ function cmdInstallCaveman({ flags }) {
   }
 }
 
-function cmdDoctor({ flags }) {
-  ui.banner();
+async function cmdDoctor({ flags }) {
+  await ui.bannerAnimated();
 
   ui.header('JDI Doctor');
   ui.info(`Diretorio atual: ${c.dim}${process.cwd()}${c.reset}`);
@@ -332,8 +332,8 @@ function cmdDoctor({ flags }) {
   }
 }
 
-function cmdHelp() {
-  ui.banner();
+async function cmdHelp() {
+  await ui.bannerAnimated();
 
   console.log(`${c.bold}Uso:${c.reset}`);
   console.log(`  ${c.cyan}npx jdi-cli <comando> [opcoes]${c.reset}`);
@@ -403,7 +403,7 @@ function cmdVersion() {
 // Main dispatcher
 // =================================================================
 
-function main() {
+async function main() {
   const parsed = parseArgs(process.argv);
 
   if (parsed.flags && parsed.flags.noColor) {
@@ -417,34 +417,34 @@ function main() {
 
   switch (parsed.cmd) {
     case 'install':
-      cmdInstall(parsed);
+      await cmdInstall(parsed);
       break;
     case 'update':
     case 'upgrade':
-      cmdUpdate(parsed);
+      await cmdUpdate(parsed);
       break;
     case 'uninstall':
     case 'remove':
-      cmdUninstall(parsed);
+      await cmdUninstall(parsed);
       break;
     case 'build':
-      cmdBuild(parsed);
+      await cmdBuild(parsed);
       break;
     case 'install-playwright':
     case 'playwright':
-      cmdInstallPlaywright(parsed);
+      await cmdInstallPlaywright(parsed);
       break;
     case 'install-caveman':
     case 'caveman':
-      cmdInstallCaveman(parsed);
+      await cmdInstallCaveman(parsed);
       break;
     case 'doctor':
-      cmdDoctor(parsed);
+      await cmdDoctor(parsed);
       break;
     case 'help':
     case '--help':
     case '-h':
-      cmdHelp();
+      await cmdHelp();
       break;
     case '--version':
     case '-V':
@@ -457,4 +457,7 @@ function main() {
   }
 }
 
-main();
+main().catch((err) => {
+  ui.fail(err && err.message ? err.message : String(err));
+  process.exit(1);
+});

package/bin/lib/ui.js

@@ -3,6 +3,12 @@
 // ANSI escape codes — sem deps externas
 const isTTY = process.stdout.isTTY;
 const supportsColor = isTTY && !process.env.NO_COLOR;
+const supportsTrueColor =
+  supportsColor &&
+  (process.env.COLORTERM === 'truecolor' ||
+    process.env.COLORTERM === '24bit' ||
+    process.env.TERM_PROGRAM === 'vscode' ||
+    process.env.WT_SESSION); // Windows Terminal
 
 const c = {
   reset: supportsColor ? '\x1b[0m' : '',
@@ -25,22 +31,234 @@ const c = {
   bgGreen: supportsColor ? '\x1b[42m' : '',
 };
 
-// ASCII banner do JDI
-const BANNER = [
-  '',
-  `${c.cyan}${c.bold}     ██╗██████╗ ██╗${c.reset}`,
-  `${c.cyan}${c.bold}     ██║██╔══██╗██║${c.reset}`,
-  `${c.cyan}${c.bold}     ██║██║  ██║██║${c.reset}`,
-  `${c.cyan}${c.bold}██   ██║██║  ██║██║${c.reset}`,
-  `${c.cyan}${c.bold}╚█████╔╝██████╔╝██║${c.reset}`,
-  `${c.cyan}${c.bold} ╚════╝ ╚═════╝ ╚═╝${c.reset}`,
-  '',
-  `${c.dim}     Just Do It ${c.reset}${c.gray}— workflow enxuto, multi-runtime${c.reset}`,
-  '',
+// Synthwave palette (truecolor with 256-color fallback)
+function rgb(r, g, b, fallback256) {
+  if (!supportsColor) return '';
+  if (supportsTrueColor) return `\x1b[38;2;${r};${g};${b}m`;
+  return `\x1b[38;5;${fallback256}m`;
+}
+
+const synthwave = {
+  hotPink: rgb(255, 27, 141, 199),
+  neonYellow: rgb(244, 241, 66, 227),
+  cyanNeon: rgb(0, 255, 224, 51),
+  magenta: rgb(255, 0, 200, 201),
+  purple: rgb(185, 103, 255, 141),
+};
+
+// ASCII letters J D I in ANSI Shadow font (full glyphs, including J's hook)
+const JDI_LETTERS = [
+  '     ██╗██████╗ ██╗',
+  '     ██║██╔══██╗██║',
+  '     ██║██║  ██║██║',
+  '██   ██║██║  ██║██║',
+  '╚█████╔╝██████╔╝██║',
+  ' ╚════╝ ╚═════╝ ╚═╝',
 ];
 
+// 3 lightsabers stacked, right-anchored hilts, blades ignite leftward.
+// Each saber: [blade plasma extending left]|=|◉|=|/////|==
+//                                          ^^^ ^ ^^^ ^^^^^ ^^
+//                                          emt btn grd grip pommel
+const HILT_STR = '|=|◉|=|/////|==';        // composed hilt, right side
+const HILT_LEN = 15;                        // visible length of HILT_STR
+const BLADE_CHAR = '═';
+const BLADE_MAX = 47;                       // blade extends this many chars left
+const BLADE_TIP = '◄';                      // tip when fully ignited
+const SABER_INDENTS = [2, 2, 2];            // aligned indents — hilts in same column
+// Jedi blade palette — blue, green, purple
+const SABER_COLORS_TRUE = [
+  [46, 170, 251],   // Obi-Wan / Luke OG blue
+  [55, 251, 58],    // Yoda / Luke ROTJ green
+  [163, 72, 251],   // Mace Windu purple
+];
+const SABER_COLORS_256 = [33, 46, 129];
+function saberColor(idx) {
+  if (!supportsColor) return '';
+  if (supportsTrueColor) {
+    const [r, g, b] = SABER_COLORS_TRUE[idx];
+    return `\x1b[38;2;${r};${g};${b}m`;
+  }
+  return `\x1b[38;5;${SABER_COLORS_256[idx]}m`;
+}
+const TAGLINE = 'Cut through the chaos. Ship the work. [Just do it]';
+
+// Build one saber line, blade ignited from right (hilt) extending left to bladeChars.
+// Layout (right-anchored): [spaces if blade incomplete][tip?][blade chars][hilt]
+function buildSaberLine(saberIdx, bladeChars) {
+  const yellow = synthwave.neonYellow;
+  const red = supportsColor ? '\x1b[38;2;255;40;40m' : '';
+  const bladeCol = saberColor(saberIdx);
+  const r = c.reset;
+  const hiltColor = `${yellow}${c.bold}`;
+  const buttonColor = bladeChars > 0 ? `${red}${c.bold}` : hiltColor;
+
+  // Indent (stagger) + leading spaces to keep hilt at fixed right column
+  const indent = ' '.repeat(SABER_INDENTS[saberIdx]);
+  const leftPad = ' '.repeat(Math.max(0, BLADE_MAX - bladeChars));
+
+  let bladeSection = '';
+  if (bladeChars > 0) {
+    const tip = bladeChars >= BLADE_MAX ? `${bladeCol}${c.bold}${BLADE_TIP}${r}` : '';
+    const bladeBody = bladeChars >= BLADE_MAX ? bladeChars - 1 : bladeChars;
+    bladeSection = `${tip}${bladeCol}${c.bold}${BLADE_CHAR.repeat(bladeBody)}${r}`;
+  }
+
+  // HILT_STR has '◉' as 4th char (index 3). Recolor it red when blade active.
+  // Render hilt in 3 segments to keep button distinct.
+  const before = HILT_STR.slice(0, 3);    // |=|
+  const button = HILT_STR.slice(3, 4);    // ◉
+  const after = HILT_STR.slice(4);        // |=|/////|==
+  const hilt =
+    `${hiltColor}${before}${r}` +
+    `${buttonColor}${button}${r}` +
+    `${hiltColor}${after}${r}`;
+
+  return `${indent}${leftPad}${bladeSection}${hilt}`;
+}
+
+function buildFrame({ showHilt, sabersBlade, showTagline }) {
+  const pink = synthwave.hotPink;
+  const purple = synthwave.purple;
+  const r = c.reset;
+
+  const lines = [''];
+
+  // 6 rows of JDI letters in hot pink
+  for (const row of JDI_LETTERS) {
+    lines.push(`  ${pink}${c.bold}${row}${r}`);
+  }
+
+  lines.push('');
+
+  // 3 stacked sabers
+  if (!showHilt) {
+    lines.push('');
+    lines.push('');
+    lines.push('');
+  } else {
+    for (let i = 0; i < 3; i++) {
+      const blade = (sabersBlade && sabersBlade[i] != null) ? sabersBlade[i] : 0;
+      lines.push(buildSaberLine(i, blade));
+    }
+  }
+
+  lines.push('');
+
+  if (showTagline) {
+    lines.push(`  ${purple}${c.italic}${TAGLINE}${r}`);
+  } else {
+    lines.push('');
+  }
+  lines.push('');
+
+  return lines;
+}
+
+function moveCursorUp(n) {
+  if (n > 0) process.stdout.write(`\x1b[${n}A`);
+}
+function clearLine() {
+  process.stdout.write('\x1b[2K');
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function writeFrame(lines, isFirst) {
+  if (!isFirst) {
+    moveCursorUp(lines.length);
+  }
+  for (const line of lines) {
+    clearLine();
+    process.stdout.write(`\r${line}\n`);
+  }
+}
+
+const wantsAnim =
+  isTTY &&
+  !process.env.NO_COLOR &&
+  !process.env.CI &&
+  process.env.JDI_ANIMATE !== 'off';
+
+async function bannerAnimated() {
+  // Non-TTY / CI / NO_COLOR: print static
+  if (!wantsAnim) {
+    banner();
+    return;
+  }
+
+  // Cascade ignition: 3 sabers, each ignites with 80ms stagger.
+  // Saber 0 (blue) at t=0, saber 1 (green) at t=80ms, saber 2 (purple) at t=160ms.
+  // Each blade extends in 5 steps (~400ms per saber).
+  const stepChars = [0, 12, 24, 36, 44, BLADE_MAX];
+
+  function snapshot(t) {
+    const result = [];
+    for (let i = 0; i < 3; i++) {
+      const elapsed = t - i * 80;
+      if (elapsed <= 0) {
+        result.push(0);
+        continue;
+      }
+      const stepIdx = Math.min(stepChars.length - 1, Math.floor(elapsed / 80));
+      result.push(stepChars[stepIdx]);
+    }
+    return result;
+  }
+
+  const frames = [];
+  // t=0: letters only, no sabers
+  frames.push({ showHilt: false, sabersBlade: [0, 0, 0], showTagline: false, delay: 80 });
+  // t=80: hilts appear (no blade)
+  frames.push({ showHilt: true, sabersBlade: [0, 0, 0], showTagline: false, delay: 80 });
+  // Cascade ignition (~480ms)
+  for (let t = 80; t <= 560; t += 80) {
+    frames.push({ showHilt: true, sabersBlade: snapshot(t), showTagline: false, delay: 80 });
+  }
+  // Final: all blades full + tagline
+  frames.push({
+    showHilt: true,
+    sabersBlade: [BLADE_MAX, BLADE_MAX, BLADE_MAX],
+    showTagline: true,
+    delay: 0,
+  });
+
+  let isFirst = true;
+  for (const f of frames) {
+    const lines = buildFrame(f);
+    writeFrame(lines, isFirst);
+    isFirst = false;
+    if (f.delay > 0) await sleep(f.delay);
+  }
+
+  // Hold the banner for HOLD_MS so the user can see it before the command continues.
+  // Use a small spinner under the tagline to signal that the CLI is alive and not frozen.
+  const HOLD_MS = 5000;
+  const SPIN_INTERVAL = 100;
+  const SPIN_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  const purple = synthwave.purple;
+  const r = c.reset;
+  const start = Date.now();
+  let spinIdx = 0;
+  while (Date.now() - start < HOLD_MS) {
+    const frame = SPIN_FRAMES[spinIdx % SPIN_FRAMES.length];
+    process.stdout.write(`\r  ${purple}${frame}${r} ${c.dim}igniting...${r}   `);
+    spinIdx++;
+    await sleep(SPIN_INTERVAL);
+  }
+  // Clear the spinner line so command output starts cleanly
+  process.stdout.write('\r' + ' '.repeat(40) + '\r');
+}
+
 function banner() {
-  console.log(BANNER.join('\n'));
+  // Static one-shot — final state: all 3 sabers ignited + tagline
+  const lines = buildFrame({
+    showHilt: true,
+    sabersBlade: [BLADE_MAX, BLADE_MAX, BLADE_MAX],
+    showTagline: true,
+  });
+  console.log(lines.join('\n'));
 }
 
 // Box drawing
@@ -120,7 +338,7 @@ function spinner(msg) {
   if (!isTTY) {
     console.log(`${sym.arrow} ${msg}...`);
     return {
-      stop: () => {},
+      stop: () => { },
       success: (s) => ok(s || msg),
       fail: (s) => fail(s || msg),
     };
@@ -179,7 +397,9 @@ function nextSteps(steps) {
 module.exports = {
   c,
   sym,
+  synthwave,
   banner,
+  bannerAnimated,
   box,
   step,
   ok,

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>