pan-wizard 3.22.0 → 3.24.0

package/pan-wizard-core/bin/lib/hud.cjs

@@ -625,24 +625,39 @@ function renderCommandStack(d) {
       ? s.agents.map(ag => `<div class="ag"><span class="amono">↳ ${esc(ag.name)}</span>`
         + `<span class="amono ${ag.active ? 'okc' : 'dim'}">${ag.active ? `${ag.calls} calls · ${fmtTokens(ag.tokens)} tok` : 'idle'}</span></div>`).join('')
       : '<div class="ag"><span class="amono dim">git-tool driven · no agents</span></div>';
+    // `tier` and `access` are reproduced verbatim from squads.cjs, and both are
+    // advisory there: `tier` is a squad grouping attribute (the active
+    // `model_profile` is what resolves a model), and `access` is the intended
+    // contract the conductor's prompt is told to honour, not a sandbox. The
+    // tooltip says so, because a bare `read-only` badge in a dashboard reads as
+    // enforcement to anyone who has not read the module.
     return `
     <div class="squad" style="border-left:3px solid ${color}">
       <div class="squad-head">
         <span class="squad-name"><span class="dot" style="background:${color}"></span>${esc(s.label)}
-          <span class="amono dim">· ${esc(s.tier)} · ${esc(s.access)}</span></span>
+          <span class="amono dim" title="Advisory labels from squads.cjs: tier is a squad grouping (the active model_profile resolves the model), and access is the contract the conductor is instructed to honour — the binding tool grant is each agent's own frontmatter.">· ${esc(s.tier)} · ${esc(s.access)}</span></span>
         ${pillEl}
       </div>
       <div class="squad-sum">${esc(s.summary)}</div>
       ${drill}
     </div>`;
   }).join('');
+  // The coordinator strap is deliberately narrow, because both halves of what it
+  // used to say were wrong. It does NOT name a model family: the agent file
+  // (`agents/pan-conductor.md`) carries no `model:` field, so it resolves to
+  // `inherit` and runs on whatever model launched the session — PAN selects
+  // nothing. And it says delegation-*first*, not delegation-only: that agent's
+  // `tools:` grant includes `Write` and `Bash`, and nothing strips them (squads.cjs
+  // is a registry + resolver). Routing rather than coding is how the conductor is
+  // instructed to behave, not something the runtime prevents. Do not re-add a
+  // family name or an enforcement word here without changing the agent file first.
   return `
   <section class="panel">
     <div class="ph">command stack — live</div>
     <div class="coord">
       <span class="dot" style="background:var(--coral)"></span>
       <span class="cname">Mission Control</span>
-      <span class="amono dim">· ${esc(a.coordinator)} · opus · reasoning · delegation-only</span>
+      <span class="amono dim">· ${esc(a.coordinator)} · session model · delegation-first</span>
       <span class="mc-state">${anyActive ? 'delegating' : 'idle'}</span>
     </div>
     <div class="squads">${squadCards}</div>

package/pan-wizard-core/bin/lib/init.cjs

@@ -3,11 +3,10 @@
  */
 
 const fs = require('fs');
-const os = require('os');
 const path = require('path');
 const { loadConfig, resolveModelInternal, findPhaseInternal, getRoadmapPhaseInternal, pathExistsInternal, generateSlugInternal, getMilestoneInfo, normalizePhaseName, toPosix, output, error, scanPendingTodos, isGitRepo, execGit } = require('./core.cjs');
 const { PLANNING_DIR, PHASES_DIR, CODEBASE_DIR, QUICK_DIR, MILESTONES_DIR, STATE_FILE, ROADMAP_FILE, CONFIG_FILE, PROJECT_FILE, REQUIREMENTS_FILE, isPlanFile, isSummaryFile, isResearchFile, isContextFile, isVerificationFile, PLAN_SUFFIX, SUMMARY_SUFFIX, CONTEXT_SUFFIX, RESEARCH_SUFFIX, VERIFICATION_SUFFIX, UAT_SUFFIX, MAX_SLUG_LENGTH } = require('./constants.cjs');
-const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles, classifyPhaseStatus, hasBraveSearchKey } = require('./utils.cjs');
+const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles, classifyPhaseStatus, hasBraveSearchKey, parsePhaseDir } = require('./utils.cjs');
 const { classifyPlanTier } = require('./phase.cjs');
 const { extractFrontmatter } = require('./frontmatter.cjs');
 const { detectLanguages } = require('./codebase.cjs');
@@ -768,9 +767,7 @@ function scanAllPhases(cwd) {
     const dirNames = entries.filter(entry => entry.isDirectory()).map(entry => entry.name).sort();
 
     for (const dirName of dirNames) {
-      const dirMatch = dirName.match(/^(\d+(?:\.\d+)*)-?(.*)/);
-      const phaseNumber = dirMatch ? dirMatch[1] : dirName;
-      const phaseName = dirMatch && dirMatch[2] ? dirMatch[2] : null;
+      const { number: phaseNumber, name: phaseName } = parsePhaseDir(dirName);
 
       const phaseFullPath = path.join(phasesDirPath, dirName);
       let phaseFiles;

package/pan-wizard-core/bin/lib/knowledge.cjs

@@ -151,6 +151,22 @@ function conversationsDir(cwd) {
   return path.join(planningPath(cwd), CONVERSATIONS_DIR);
 }
 
+// Phase ids are shaped like "1", "2.1", "06A" — never a path fragment. Validate
+// before using phaseNum as a directory segment so a malformed/traversal value
+// (e.g. "../../../outside") cannot write session.json outside .planning/conversations.
+// Mirrors memory.cjs's validateAgentName hardening convention (2026-07).
+const PHASE_NUM_RE = /^[0-9]+(\.[0-9]+)*[A-Z]?$/i;
+
+function validatePhaseNum(phaseNum) {
+  if (phaseNum === undefined || phaseNum === null || String(phaseNum).trim() === '') {
+    return 'phaseNum required';
+  }
+  if (!PHASE_NUM_RE.test(String(phaseNum))) {
+    return `Invalid phase: ${phaseNum}. Must match ${PHASE_NUM_RE}`;
+  }
+  return null;
+}
+
 function sessionFile(cwd, phaseNum) {
   return path.join(conversationsDir(cwd), String(phaseNum), 'session.json');
 }
@@ -159,6 +175,8 @@ function sessionFile(cwd, phaseNum) {
  * Read or initialize a discussion session for a phase.
  */
 function loadSession(cwd, phaseNum) {
+  const err = validatePhaseNum(phaseNum);
+  if (err) return { error: err };
   const file = sessionFile(cwd, phaseNum);
   try {
     return JSON.parse(fs.readFileSync(file, 'utf-8'));
@@ -176,7 +194,8 @@ function loadSession(cwd, phaseNum) {
  * @returns {{appended: true, turn_count: number, file: string}|{error: string}}
  */
 function appendTurn(cwd, phaseNum, turn) {
-  if (!phaseNum) return { error: 'phaseNum required' };
+  const phaseErr = validatePhaseNum(phaseNum);
+  if (phaseErr) return { error: phaseErr };
   if (!turn || !turn.role || !turn.content) return { error: 'turn requires role + content' };
   if (turn.role !== 'user' && turn.role !== 'agent') {
     return { error: 'turn.role must be "user" or "agent"' };

package/pan-wizard-core/bin/lib/learn-lint.cjs

@@ -10,6 +10,7 @@
  *  - L-004: Universal-scope rule prose mentions PAN-internal terms
  *           (candidate for internal/ scope rather than universal/)
  *  - L-005: Revision marker (rN) appended in body but no supersession field
+ *  - L-006: Universal-scope pattern cites an internal pattern id (dangles after install)
  *
  * These are not patterns themselves — they're integrity checks for the
  * pattern store. Wired to `pan-tools learn lint`.
@@ -20,6 +21,25 @@ const path = require('path');
 
 const VALID_SCOPES = ['universal', 'internal'];
 
+/**
+ * Default root for the learnings store: three levels up from lib/ — the install
+ * root (`<runtime-dir>/`) or the source repo root. Both layouts keep
+ * pan-wizard-core/ at that level, so this resolves correctly in either.
+ *
+ * Why this exists rather than defaulting to cwd: the dispatcher used
+ * `--source-root || cwd`, which is only right when cwd IS the PAN source repo. In
+ * a real install cwd is the user's project, where pan-wizard-core/learnings/ does
+ * not exist — so `learn topics-for` returned zero topics from a store holding
+ * dozens, `learn lint` reported PASS on a store it never opened, and
+ * `build-index` crashed. Twenty-five shipped instruction sites across the
+ * exec/plan/verify workflows tell agents to run these commands from the project
+ * root, and none passes --source-root, so every one of them silently got nothing.
+ * Mirrors skill-align.cjs resolveSkillRoot() and experiment.cjs PAN_SOURCE_ROOT.
+ */
+function resolveLearningsRoot() {
+  return path.resolve(__dirname, '..', '..', '..');
+}
+
 function getLearningsDir(sourceRoot, scope) {
   return path.join(sourceRoot, 'pan-wizard-core', 'learnings', scope);
 }
@@ -248,6 +268,35 @@ function lintPatterns(patterns) {
     }
   }
 
+  // L-006: a universal-scope pattern citing an INTERNAL pattern id.
+  //
+  // This is the only rule that must run in the source repo to catch a defect that
+  // only manifests after install. `internal/` is stripped when PAN is installed, so
+  // a universal topic citing an internal id resolves fine here — where both scopes
+  // are present — and becomes a dangling L-002 reference on every user's machine.
+  // That is exactly what shipped: universal/concurrency.md cited P-1402 from
+  // internal/pan-dev-bugs.md, so `learn lint` FAILED in every install while passing
+  // in the repo, making the integrity gate un-greenable for users and invisible to us.
+  // Checking scope-crossing directly, rather than waiting for the reference to
+  // dangle, is what makes it catchable before release.
+  const internalIds = new Set(patterns.filter(p => p.scope === 'internal').map(p => p.id));
+  if (internalIds.size > 0) {
+    for (const p of patterns) {
+      if (p.scope !== 'universal') continue;
+      const refs = [...new Set(p.body.match(PATTERN_REF_RE) || [])].filter(r => r !== p.id);
+      for (const ref of refs.filter(r => internalIds.has(r))) {
+        violations.push({
+          code: 'L-006',
+          severity: 'error',
+          pattern_id: p.id,
+          file: p.file,
+          message: `Universal pattern "${p.id}" cites internal pattern "${ref}" — internal/ is stripped at install time, so this becomes a dangling reference in every install`,
+          internal_ref: ref,
+        });
+      }
+    }
+  }
+
   return {
     violations,
     pattern_count: patterns.length,
@@ -284,6 +333,7 @@ function cmdLearnLint(sourceRoot, opts = {}) {
 
 module.exports = {
   cmdLearnLint,
+  resolveLearningsRoot,
   collectAllPatterns,
   lintPatterns,
   extractPatternBody,

package/pan-wizard-core/bin/lib/links.cjs

@@ -509,8 +509,13 @@ function validateAll(cwd, opts = {}) {
 
 function cmdLinksValidate(cwd, opts = {}) {
   const result = validateAll(cwd, opts);
-  // Bypass core.output() because it unconditionally exits 0; we need exit 1
-  // when status is "fail" so CI / hooks can detect violations.
+  // This used to hand-roll process.stdout.write + process.exit to get exit 1 on a
+  // failing status, because output() exited 0 unconditionally. It no longer does
+  // (see its contract comment in core.cjs), so the gate goes through output() like
+  // every other command — which also picks up the >50KB @file: overflow protocol
+  // this bypass was silently missing. The payload has no `error` key, so the code
+  // is passed explicitly: "fail" is a verdict, not a malfunction.
+  let human;
   if (opts.raw) {
     const lines = [
       `Links: ${result.summary.status.toUpperCase()}`,
@@ -529,11 +534,9 @@ function cmdLinksValidate(cwd, opts = {}) {
       const where = f.source_line ? `${f.source}:${f.source_line}` : f.source;
       lines.push(`[${f.severity.toUpperCase()}] ${f.code} ${where}: ${f.detail}`);
     }
-    process.stdout.write(lines.join('\n'));
-  } else {
-    process.stdout.write(JSON.stringify(result, null, 2));
+    human = lines.join('\n');
   }
-  process.exit(result.summary.status === 'fail' ? 1 : 0);
+  output(result, opts.raw, human, result.summary.status === 'fail' ? 1 : 0);
 }
 
 module.exports = {

package/pan-wizard-core/bin/lib/lock.cjs

@@ -48,8 +48,18 @@ function acquireLock(filePath, opts = {}) {
       try {
         const age = Date.now() - fs.statSync(lockPath).mtimeMs;
         if (age > staleMs) {
-          // Holder likely crashed — steal and retry immediately.
-          try { fs.unlinkSync(lockPath); } catch { /* racing steal — loop retries */ }
+          // Holder likely crashed — steal via an atomic rename to a unique name.
+          // rename() moves the specific inode: exactly ONE concurrent stealer can
+          // rename a given lock file; every other contender's rename fails with
+          // ENOENT (the source is gone) instead of blindly unlinking a lock that a
+          // winner may already have re-created. This closes the double-holder race
+          // where two processes both stat the same stale lock and both unlink it.
+          const stealPath = `${lockPath}.steal.${process.pid}.${Date.now()}`;
+          try {
+            fs.renameSync(lockPath, stealPath);
+            // We won the steal — discard the stolen lock and retry wx-create.
+            try { fs.unlinkSync(stealPath); } catch { /* best-effort */ }
+          } catch { /* another contender stole/cleared it first — loop retries */ }
           continue;
         }
       } catch { /* lock vanished between EEXIST and stat — loop retries */ }
@@ -59,9 +69,18 @@ function acquireLock(filePath, opts = {}) {
   return { acquired: false, lockPath };
 }
 
-/** Release a lock acquired by acquireLock. Best-effort. */
+/**
+ * Release a lock acquired by acquireLock. Best-effort, but ownership-verified:
+ * only unlink when the lock file still contains THIS process's pid, so a lock
+ * that was stolen (stale) and re-created by a successor is never deleted out
+ * from under that successor.
+ */
 function releaseLock(lockPath) {
-  try { fs.unlinkSync(lockPath); } catch { /* already gone */ }
+  try {
+    const owner = fs.readFileSync(lockPath, 'utf-8').trim();
+    if (owner !== String(process.pid)) return; // not ours anymore — leave it
+    fs.unlinkSync(lockPath);
+  } catch { /* already gone / unreadable — nothing to release */ }
 }
 
 /**

package/pan-wizard-core/bin/lib/memory-optimize.cjs

@@ -263,14 +263,19 @@ function cmdMemoryOptimize(cwd, opts = {}, raw) {
   // Consolidate any per-agent log over the entry cap (reuses compactMemory, which
   // no-ops under the cap). Dry-run counts entries without writing.
   try {
-    for (const a of listMemoryAgents(cwd)) {
-      const rawMem = readMemory(cwd, a);
-      if (rawMem == null) continue;
-      const count = parseEntries(rawMem).length;
+    // M21: listMemoryAgents(cwd) returns { agents: [{ agent, entries }] }, and
+    // readMemory(cwd, name) returns { agent, entries, raw }. The old loop iterated
+    // the return OBJECT directly (a TypeError, silently swallowed by this catch)
+    // and passed the whole object to readMemory/parseEntries — so the agent-log
+    // consolidation never ran. Iterate .agents, read each by name, count entries.
+    for (const a of listMemoryAgents(cwd).agents) {
+      const mem = readMemory(cwd, a.agent);
+      if (mem == null) continue;
+      const count = parseEntries(mem.raw).length;
       if (count > DEFAULT_MAX_ENTRIES) {
         let removed = 0;
-        if (apply) { const r = compactMemory(cwd, a, DEFAULT_MAX_ENTRIES); removed = (r && r.removed) || 0; }
-        result.agents.push({ agent: a, entries: count, over_cap: true, compacted: apply, removed });
+        if (apply) { const r = compactMemory(cwd, a.agent, DEFAULT_MAX_ENTRIES); removed = (r && r.removed) || 0; }
+        result.agents.push({ agent: a.agent, entries: count, over_cap: true, compacted: apply, removed });
       }
     }
   } catch { /* agent sweep is best-effort */ }

package/pan-wizard-core/bin/lib/milestone.cjs

@@ -6,7 +6,7 @@ const fs = require('fs');
 const path = require('path');
 const { PLANNING_DIR, PHASES_DIR, MILESTONES_DIR, ROADMAP_FILE, REQUIREMENTS_FILE, STATE_FILE, isPlanFile } = require('./constants.cjs');
 const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles, fileAccessible } = require('./utils.cjs');
-const { output, error, isGitRepo, execGit } = require('./core.cjs');
+const { output, error, isGitRepo, execGit, escapeRegex } = require('./core.cjs');
 const { extractFrontmatter } = require('./frontmatter.cjs');
 const { writeStateMd } = require('./state.cjs');
 
@@ -39,7 +39,9 @@ function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
   try {
     reqContent = fs.readFileSync(reqPath, 'utf-8');
   } catch {
-    output({ updated: false, reason: 'requirements.md not found', ids: reqIds }, raw, 'no requirements file');
+    // error key => exit 1: the caller asked to mark requirements complete and no
+    // requirement was marked - the milestone record does not reflect the work.
+    output({ updated: false, reason: 'requirements.md not found', error: 'requirements_not_found', ids: reqIds }, raw, 'no requirements file');
     return;
   }
   const updated = [];
@@ -47,20 +49,24 @@ function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
 
   for (const reqId of reqIds) {
     let found = false;
+    // Escape the requirement ID before interpolating into RegExp — an ID with
+    // regex metacharacters otherwise crashes or mis-matches (M22, ADR audit
+    // 2026-08). Matches the escapeRegex convention in phase-remove.cjs/knowledge.cjs.
+    const reqEsc = escapeRegex(reqId);
 
     // Update checkbox: - [ ] **REQ-ID** -> - [x] **REQ-ID**
-    const checkboxPattern = new RegExp(`(-\\s*\\[)[ ](\\]\\s*\\*\\*${reqId}\\*\\*)`, 'gi');
+    const checkboxPattern = new RegExp(`(-\\s*\\[)[ ](\\]\\s*\\*\\*${reqEsc}\\*\\*)`, 'gi');
     if (checkboxPattern.test(reqContent)) {
       reqContent = reqContent.replace(checkboxPattern, '$1x$2');
       found = true;
     }
 
     // Update traceability table: | REQ-ID | Phase N | Pending | -> | REQ-ID | Phase N | Complete |
-    const tablePattern = new RegExp(`(\\|\\s*${reqId}\\s*\\|[^|]+\\|)\\s*Pending\\s*(\\|)`, 'gi');
+    const tablePattern = new RegExp(`(\\|\\s*${reqEsc}\\s*\\|[^|]+\\|)\\s*Pending\\s*(\\|)`, 'gi');
     if (tablePattern.test(reqContent)) {
       // Re-create regex since test() advances lastIndex for global regex
       reqContent = reqContent.replace(
-        new RegExp(`(\\|\\s*${reqId}\\s*\\|[^|]+\\|)\\s*Pending\\s*(\\|)`, 'gi'),
+        new RegExp(`(\\|\\s*${reqEsc}\\s*\\|[^|]+\\|)\\s*Pending\\s*(\\|)`, 'gi'),
         '$1 Complete $2'
       );
       found = true;

package/pan-wizard-core/bin/lib/optimize.cjs

@@ -121,7 +121,7 @@ function initTraceSession(cwd, opts = {}) {
 
     return { session_id: sessionId, started_at: meta.started_at, directory: sessionDir, reused: false };
   } catch (e) {
-    return { error: e.message };
+    return { error: e.message || 'trace_init_failed' };
   }
 }
 
@@ -278,7 +278,7 @@ function endTraceSession(cwd, sessionId) {
       ended_at: meta.ended_at,
     };
   } catch (e) {
-    return { error: e.message };
+    return { error: e.message || 'trace_read_failed' };
   }
 }
 
@@ -303,7 +303,7 @@ function reconcileTraceSession(cwd, sessionId) {
     fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2) + '\n');
     return { session_id: sid, reconciled: true, event_count: counts.event_count, malformed_count: counts.malformed_count };
   } catch (e) {
-    return { error: e.message };
+    return { error: e.message || 'trace_write_failed' };
   }
 }
 
@@ -349,7 +349,7 @@ function readTraceSession(cwd, sessionId) {
 
     return { session_id: sessionId, metadata, events, event_count: events.length, malformed_count: malformed };
   } catch (e) {
-    return { error: e.message };
+    return { error: e.message || 'trace_end_failed' };
   }
 }
 
@@ -380,7 +380,7 @@ function listTraceSessions(cwd) {
 
     return { sessions, count: sessions.length };
   } catch (e) {
-    return { error: e.message };
+    return { error: e.message || 'trace_reconcile_failed' };
   }
 }
 
@@ -585,7 +585,7 @@ function listOptimizationReports(cwd) {
 
     return { reports, count: reports.length };
   } catch (e) {
-    return { error: e.message };
+    return { error: e.message || 'report_write_failed' };
   }
 }
 
@@ -626,8 +626,19 @@ function applyReportRecommendations(cwd, reportPath) {
   const applied = [];
   const skipped = [];
 
+  const resolvedCwd = path.resolve(cwd);
   for (const action of actions) {
     try {
+      // Containment: action.path on memory writes is report/agent-authored and
+      // must stay inside the project. A `../` (or absolute) path otherwise
+      // escapes and writes anywhere the process can (M23, ADR audit 2026-08).
+      if (action.type === 'memory' || action.type === 'memory_append') {
+        const abs = path.resolve(cwd, action.path || '');
+        if (abs !== resolvedCwd && !abs.startsWith(resolvedCwd + path.sep)) {
+          skipped.push({ action, reason: 'path escapes project root — skipped' });
+          continue;
+        }
+      }
       if (action.type === 'memory') {
         // Write new memory entry (skip if file exists to avoid overwriting manual edits)
         const memPath = path.join(cwd, action.path);
@@ -751,7 +762,7 @@ function getOptimizeStats(cwd) {
       current_session: getCurrentSessionId(cwd),
     };
   } catch (e) {
-    return { error: e.message };
+    return { error: e.message || 'apply_failed' };
   }
 }
 

package/pan-wizard-core/bin/lib/phase-remove.cjs

@@ -20,7 +20,7 @@ function removePhaseFromDisk(phaseDir) {
   try {
     fs.rmSync(phaseDir, { recursive: true, force: true });
   } catch (e) {
-    return { removed: false, error: e.message };
+    return { removed: false, error: e.message || 'remove_failed' };
   }
   return { removed: true };
 }
@@ -214,7 +214,12 @@ function updateRoadmapAfterRemoval(cwd, phaseNum, isDecimal, normalized) {
 
     // Reasonable upper bound for phase numbers
     const maxPhase = 99;
-    for (let oldNum = maxPhase; oldNum > removedInt; oldNum--) {
+    // Floor the loop independently of removedInt. cmdPhaseRemove rejects a phase
+    // below 1 before we get here, but this function is also reachable directly,
+    // and an unbounded lower end is how `phase remove -1234567890` turned into
+    // ~1.2 billion regex passes. The loop can now never exceed maxPhase steps.
+    const stopAt = Math.max(removedInt, 0);
+    for (let oldNum = maxPhase; oldNum > stopAt; oldNum--) {
       const newNum = oldNum - 1;
       const oldStr = String(oldNum);
       const newStr = String(newNum);
@@ -269,6 +274,23 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
     error('phase number required for phase remove');
   }
 
+  // Validate the identifier BEFORE touching the roadmap or any directory.
+  // normalizePhaseName does not validate — it returns its input unchanged when
+  // PHASE_NUM_RE does not match — so a bad argument used to reach the renumber
+  // logic and do real damage, in both cases reporting success and exiting 0:
+  //   `phase remove 0`      renumbered EVERY roadmap heading down to "Phase 0"
+  //                         (the descending renumber loop runs 99..1 and re-hits
+  //                         its own output, collapsing 3->2->1->0) and renamed
+  //                         every phase directory one lower.
+  //   `phase remove -1e9`   spun that same loop ~1.2 billion times, each pass
+  //                         running several regex replaces over the roadmap —
+  //                         hours of CPU, no output, no way to tell it was stuck.
+  // Phases are numbered from 1, so anything below that is a typo, never a target.
+  const phaseIdent = String(targetPhase).trim();
+  if (!/^\d+[A-Za-z]?(?:\.\d+)*$/.test(phaseIdent) || parseInt(phaseIdent, 10) < 1) {
+    error(`invalid phase number: ${targetPhase} (expected a phase numbered from 1, e.g. 3, 3A or 3.1)`);
+  }
+
   const roadmapPath = path.join(planningPath(cwd), ROADMAP_FILE);
   const phasesDir = phasesPath(cwd);
   const force = options.force || false;
@@ -291,6 +313,23 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
     // Phases directory does not exist; targetDir remains null
   }
 
+  // Refuse a phase that exists nowhere. A phase CAN legitimately have a roadmap
+  // entry and no directory yet (planned, not scaffolded), so only refuse when it
+  // is in neither place. Previously this reported {removed: <n>} with exit 0 for
+  // a phase that was never there, and claimed roadmap.md and state.md had been
+  // rewritten — an orchestrator reads that as "it is gone" and moves on.
+  if (!targetDir) {
+    let roadmapText = '';
+    try {
+      roadmapText = fs.readFileSync(roadmapPath, 'utf8');
+    } catch { /* unreadable roadmap is reported below as not-found */ }
+    const displayNum = escapeRegex(String(parseInt(phaseIdent, 10)) + (phaseIdent.includes('.') ? '.' + phaseIdent.split('.').slice(1).join('.') : ''));
+    const inRoadmap = new RegExp(`^#{2,4}\\s*Phase\\s+0*${displayNum}(\\D|$)`, 'im').test(roadmapText);
+    if (!inRoadmap) {
+      error(`Phase ${targetPhase} not found — no phase directory and no roadmap entry`);
+    }
+  }
+
   // Check for executed work (summary.md files)
   if (targetDir && !force) {
     const targetPath = path.join(phasesDir, targetDir);