pan-wizard 3.29.0 → 3.31.0

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

@@ -320,6 +320,78 @@ function cmdRoadmapAnalyze(cwd, raw) {
  * @param {boolean} raw - If true, output raw value instead of JSON
  * @returns {void}
  */
+// ─── Progress table and Plans line, located by name ─────────────────────────
+//
+// `roadmap update-plan-progress` used to rewrite the phase's table row by column
+// POSITION — cells 2 to 4, whatever the header said. On PAN's own milestone
+// variant (`| Phase | Milestone | Plans Complete | Status | Completed |`) that put
+// the plan count in the Milestone column; on a roadmap with other columns it
+// destroyed the phase's goal and requirement ids. And the `**Plans:**` update was a
+// lazy match from the phase heading onward, so a phase without its own Plans line
+// had the NEXT phase's rewritten. Both are now located by name, and a table without
+// Plans and Status columns is left alone and reported.
+
+const splitRow = (line) => {
+  const inner = line.trim().replace(/^\|/, '').replace(/\|$/, '');
+  return inner.split(/(?<!\\)\|/).map((c) => c.trim());
+};
+const isTableLine = (line) => /^\s*\|.*\|\s*$/.test(line);
+const isSeparator = (line) => /^\s*\|(?:\s*:?-{3,}:?\s*\|)+\s*$/.test(line);
+
+/**
+ * Set the Plans / Status / Completed cells of the phase's row in any table whose
+ * header names Plans and Status columns. Pure.
+ * @returns {{content: string, updated: boolean, reason: string|null}}
+ */
+function updateProgressTableRow(content, phaseNum, values) {
+  const eol = content.includes('\r\n') ? '\r\n' : '\n';
+  const lines = content.split(/\r?\n/);
+  const phaseRe = new RegExp(`^(?:phase\\s+)?${escapeRegex(String(phaseNum))}\\.?(?=\\s|:|$)`, 'i');
+  let reason = null;
+  for (let i = 0; i + 1 < lines.length; i++) {
+    if (!isTableLine(lines[i]) || !isSeparator(lines[i + 1])) continue;
+    const header = splitRow(lines[i]);
+    const col = (re) => header.findIndex((h) => re.test(h));
+    const plansIdx = col(/\bplans?\b/i);
+    const statusIdx = col(/^status$/i);
+    const doneIdx = col(/^completed?(?:\s+on|\s+date)?$/i);
+    for (let r = i + 2; r < lines.length && isTableLine(lines[r]); r++) {
+      const cells = splitRow(lines[r]);
+      if (!phaseRe.test(cells[0] || '')) continue;
+      if (plansIdx < 0 || statusIdx < 0) {
+        reason = `the table holding phase ${phaseNum} has no Plans and Status columns (${header.join(' | ')}) — left unchanged`;
+        continue;
+      }
+      while (cells.length < header.length) cells.push('');
+      cells[plansIdx] = values.plans;
+      cells[statusIdx] = values.status;
+      if (doneIdx >= 0) cells[doneIdx] = values.completed || '';
+      const indent = lines[r].match(/^\s*/)[0];
+      lines[r] = `${indent}| ${cells.join(' | ')} |`;
+      return { content: lines.join(eol), updated: true, reason: null };
+    }
+  }
+  return { content, updated: false, reason: reason || `no progress-table row for phase ${phaseNum}` };
+}
+
+/** Rewrite `**Plans:**` inside the phase's own section only. Pure. */
+function updatePhasePlansLine(content, phaseNum, text) {
+  const lines = content.split(/(?<=\n)/);
+  const headRe = new RegExp(`^(#{2,4})\\s*Phase\\s+${escapeRegex(String(phaseNum))}(?=[\\s:.]|$)`, 'i');
+  const start = lines.findIndex((l) => headRe.test(l));
+  if (start < 0) return { content, updated: false };
+  const level = lines[start].match(headRe)[1].length;
+  const nextHead = new RegExp(`^#{1,${level}}\\s`);
+  for (let i = start + 1; i < lines.length && !nextHead.test(lines[i]); i++) {
+    const m = lines[i].match(/^(.*?(?:\*\*Plans:\*\*|\*\*Plans\*\*:)\s*)[^\r\n]*(\r?\n?)$/);
+    if (m) {
+      lines[i] = `${m[1]}${text}${m[2]}`;
+      return { content: lines.join(''), updated: true };
+    }
+  }
+  return { content, updated: false };
+}
+
 function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
   if (!phaseNum) {
     error('phase number required for roadmap update-plan-progress');
@@ -356,26 +428,19 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
   }
   const phaseEscaped = escapeRegex(phaseNum);
 
-  // Progress table row: update Plans column (summaries/plans) and Status column
-  const tablePattern = new RegExp(
-    `(\\|\\s*${phaseEscaped}\\.?\\s[^|]*\\|)[^|]*(\\|)\\s*[^|]*(\\|)\\s*[^|]*(\\|)`,
-    'i'
-  );
-  const dateField = isComplete ? ` ${today} ` : '  ';
-  roadmapContent = roadmapContent.replace(
-    tablePattern,
-    `$1 ${summaryCount}/${planCount} $2 ${status.padEnd(11)}$3${dateField}$4`
-  );
-
-  // Update plan count in phase detail section
-  const planCountPattern = new RegExp(
-    `(#{2,4}\\s*Phase\\s+${phaseEscaped}[\\s\\S]*?(?:\\*\\*Plans:\\*\\*|\\*\\*Plans\\*\\*:)\\s*)[^\\n]+`,
-    'i'
-  );
+  // Progress table row: the Plans, Status and Completed cells, found by header.
+  const table = updateProgressTableRow(roadmapContent, phaseNum, {
+    plans: `${summaryCount}/${planCount}`,
+    status,
+    completed: isComplete ? today : '',
+  });
+  roadmapContent = table.content;
+
+  // Update plan count in the phase's own detail section
   const planCountText = isComplete
     ? `${summaryCount}/${planCount} plans complete`
     : `${summaryCount}/${planCount} plans executed`;
-  roadmapContent = roadmapContent.replace(planCountPattern, `$1${planCountText}`);
+  roadmapContent = updatePhasePlansLine(roadmapContent, phaseNum, planCountText).content;
 
   // If complete: check checkbox
   if (isComplete) {
@@ -402,6 +467,8 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
 
   try {
     fs.writeFileSync(roadmapPath, roadmapContent, 'utf-8');
+    // Read back: report success only for the file this command produced.
+    if (fs.readFileSync(roadmapPath, 'utf-8') !== roadmapContent) throw new Error('roadmap.md did not read back as written');
   } catch (err) {
     // error key => exit 1: the write failed, so progress was computed and then lost.
     output({ updated: false, reason: 'Failed to write roadmap.md: ' + err.message, error: err.message || 'roadmap_write_failed' }, raw, 'write error');
@@ -415,7 +482,9 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
     summary_count: summaryCount,
     status,
     complete: isComplete,
-  }, raw, `${summaryCount}/${planCount} ${status}`);
+    table_updated: table.updated,
+    ...(table.updated ? {} : { table_reason: table.reason }),
+  }, raw, `${summaryCount}/${planCount} ${status}${table.updated ? '' : ' (progress table not updated)'}`);
 }
 
 /**

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

@@ -799,20 +799,32 @@ function calculateProgressBar(completed, total) {
  * Orchestrates extractFieldsFromState, scanPhaseProgress,
  * normalizePhaseStatus, and calculateProgressBar.
  */
-function buildStateFrontmatter(bodyContent, cwd) {
+function buildStateFrontmatter(bodyContent, cwd, existing = {}) {
   const fields = extractFieldsFromState(bodyContent);
+  const prior = existing && typeof existing === 'object' ? existing : {};
 
+  // The milestone comes from the roadmap resolver — unless the resolver only
+  // guessed (no milestone heading at all) and state.md already records one. A
+  // guess overwriting a recorded value is how a letter-series milestone ("R-2")
+  // was rewritten to the resolver's `v1.0` / `milestone` on every state write.
   let milestone = null;
   let milestoneName = null;
   if (cwd) {
     try {
       const info = getMilestoneInfo(cwd);
-      milestone = info.version;
-      milestoneName = info.name;
+      const guessed = info.basis === 'default' || info.basis === 'no-milestone-heading';
+      if (!(guessed && prior.milestone)) {
+        milestone = info.version;
+        milestoneName = info.name;
+      }
     } catch {
       // No milestone configured or milestone file unreadable -- skip milestone fields
     }
   }
+  if (milestone == null && prior.milestone) {
+    milestone = prior.milestone;
+    milestoneName = prior.milestone_name != null ? prior.milestone_name : null;
+  }
 
   let totalPhases = fields.totalPhasesRaw ? parseInt(fields.totalPhasesRaw, 10) : null;
   let completedPhases = null;
@@ -837,20 +849,27 @@ function buildStateFrontmatter(bodyContent, cwd) {
     if (pctMatch) progressPercent = parseInt(pctMatch[1], 10);
   }
 
-  const normalizedStatus = normalizePhaseStatus(fields.status, fields.pausedAt);
-
   const frontmatter = { pan_state_version: '1.0' };
 
   if (milestone) frontmatter.milestone = milestone;
   if (milestoneName) frontmatter.milestone_name = milestoneName;
-  if (fields.currentPhase) frontmatter.current_phase = fields.currentPhase;
-  if (fields.currentPhaseName) frontmatter.current_phase_name = fields.currentPhaseName;
-  if (fields.currentPlan) frontmatter.current_plan = fields.currentPlan;
-  frontmatter.status = normalizedStatus;
-  if (fields.stoppedAt) frontmatter.stopped_at = fields.stoppedAt;
-  if (fields.pausedAt) frontmatter.paused_at = fields.pausedAt;
+  // A field the body restates wins; one it does not keeps its recorded value.
+  // Rebuilding from the body alone dropped current_phase_name, current_plan and
+  // the rest whenever a project's state.md did not repeat them in prose.
+  const keep = (key, fromBody) => {
+    if (fromBody != null && fromBody !== '') frontmatter[key] = fromBody;
+    else if (prior[key] != null) frontmatter[key] = prior[key];
+  };
+  keep('current_phase', fields.currentPhase);
+  keep('current_phase_name', fields.currentPhaseName);
+  keep('current_plan', fields.currentPlan);
+  frontmatter.status = (fields.status || fields.pausedAt)
+    ? normalizePhaseStatus(fields.status, fields.pausedAt)
+    : (prior.status != null ? prior.status : normalizePhaseStatus(null, null));
+  keep('stopped_at', fields.stoppedAt);
+  keep('paused_at', fields.pausedAt);
   frontmatter.last_updated = new Date().toISOString();
-  if (fields.lastActivity) frontmatter.last_activity = fields.lastActivity;
+  keep('last_activity', fields.lastActivity);
 
   const progress = {};
   if (totalPhases !== null) progress.total_phases = totalPhases;
@@ -859,19 +878,48 @@ function buildStateFrontmatter(bodyContent, cwd) {
   if (completedPlans !== null) progress.completed_plans = completedPlans;
   if (progressPercent !== null) progress.percent = progressPercent;
   if (Object.keys(progress).length > 0) frontmatter.progress = progress;
-
-  return frontmatter;
+  else if (prior.progress != null) frontmatter.progress = prior.progress;
+
+  // Keys PAN does not manage (a project's own notes) survive every write, in the
+  // order the file already had them; PAN's keys fill in around them.
+  const merged = {};
+  for (const key of Object.keys(prior)) merged[key] = key in frontmatter ? frontmatter[key] : prior[key];
+  for (const key of Object.keys(frontmatter)) if (!(key in merged)) merged[key] = frontmatter[key];
+  return merged;
 }
 
+// One front-matter block at the top of state.md: BOM-tolerant, LF or CRLF. The
+// previous `^---\n…\n---\n` matched LF only, so on a CRLF checkout (git
+// core.autocrlf=true) the old block was never stripped and every state write
+// stacked a new, re-derived block on top of it.
+const STATE_FRONTMATTER_RE = /^\uFEFF?---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/;
+
 function stripFrontmatter(content) {
-  return content.replace(/^---\n[\s\S]*?\n---\n*/, '');
+  return String(content).replace(STATE_FRONTMATTER_RE, '').replace(/^\uFEFF/, '').replace(/^(?:\r?\n)+/, '');
 }
 
-function syncStateFrontmatter(content, cwd) {
-  const body = stripFrontmatter(content);
-  const frontmatter = buildStateFrontmatter(body, cwd);
+/**
+ * Re-derive state.md's front matter from its body, merged with the front matter
+ * already there. Output uses `eol` (default: whatever the content already uses).
+ * Throws (code STATE_STACKED_FRONTMATTER) when the content starts with more than
+ * one front-matter block — earlier releases stacked them on CRLF files, and
+ * choosing between them silently is exactly the guess this function must not make.
+ */
+function syncStateFrontmatter(content, cwd, eol) {
+  const text = String(content);
+  const lineEnd = eol || (/\r\n/.test(text) ? '\r\n' : '\n');
+  const m = text.match(STATE_FRONTMATTER_RE);
+  const existing = m ? extractFrontmatter(m[0]) : {};
+  const body = stripFrontmatter(text).replace(/\r\n/g, '\n');
+  if (STATE_FRONTMATTER_RE.test(body)) {
+    const err = new Error('state.md starts with more than one front-matter block (an earlier PAN release stacked them on CRLF files). Keep the block with the right values, delete the other, and run the command again — PAN will not pick one for you.');
+    err.code = 'STATE_STACKED_FRONTMATTER';
+    throw err;
+  }
+  const frontmatter = buildStateFrontmatter(body, cwd, existing);
   const yamlStr = reconstructFrontmatter(frontmatter);
-  return `---\n${yamlStr}\n---\n\n${body}`;
+  const out = `---\n${yamlStr}\n---\n\n${body}`;
+  return lineEnd === '\r\n' ? out.replace(/\n/g, '\r\n') : out;
 }
 
 /**
@@ -882,17 +930,33 @@ function syncStateFrontmatter(content, cwd) {
  * state.md.lock and lands atomically (temp + rename), so concurrent agents
  * cannot tear the file or interleave read-modify-write cycles. Lock
  * acquisition is best-effort — on timeout the write proceeds unlocked,
- * preserving single-agent behavior exactly.
+ * matching the file-lock contract.
+ *
+ * The file keeps its own line ending, and the write is verified: exactly one
+ * front-matter block goes in, and what is read back under the lock must be what
+ * was written. A write that cannot meet either stops with an error and leaves
+ * the file as it was — it never reports success over a file it did not produce.
  */
 function writeStateMd(statePath, content, cwd) {
-  const synced = syncStateFrontmatter(content, cwd);
+  let diskEol = null;
+  try { diskEol = /\r\n/.test(fs.readFileSync(statePath, 'utf-8')) ? '\r\n' : '\n'; } catch { /* new file */ }
+  let synced;
+  try {
+    synced = syncStateFrontmatter(content, cwd, diskEol);
+  } catch (err) {
+    if (err && err.code === 'STATE_STACKED_FRONTMATTER') error(err.message);
+    throw err;
+  }
+  let mismatch = false;
   try {
     withFileLock(statePath, () => {
       writeFileAtomic(statePath, synced);
+      mismatch = fs.readFileSync(statePath, 'utf-8') !== synced;
     });
   } catch (err) {
     throw new Error('Failed to write state.md: ' + err.message);
   }
+  if (mismatch) error('state.md did not read back as written — another writer changed it during the write. Re-run the command.');
 }
 
 /**
@@ -911,7 +975,7 @@ function cmdStateJson(cwd, raw) {
   const frontmatter = extractFrontmatter(content);
 
   if (!frontmatter || Object.keys(frontmatter).length === 0) {
-    const body = stripFrontmatter(content);
+    const body = stripFrontmatter(content).replace(/\r\n/g, '\n');
     const built = buildStateFrontmatter(body, cwd);
     output(built, raw, JSON.stringify(built, null, 2));
     return;

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

@@ -48,15 +48,27 @@
 function buildSubcommandIndex(sourceText) {
   const index = {};
   if (typeof sourceText !== 'string') return index;
-  const re = /Unknown ([a-z][a-z-]*) subcommand\. Available: ([^'"`\n]+)/g;
-  let m;
-  while ((m = re.exec(sourceText)) !== null) {
-    const group = m[1];
-    const subs = m[2]
-      .split(',')
-      .map((s) => s.trim().split(/\s+/)[0])   // drop " [--apply]"-style hints
-      .filter((s) => /^[a-z][a-z0-9-]*$/.test(s));
-    if (subs.length) index[group] = subs;
+  // The dispatcher words these messages three ways, and until 2026-09-26 only the
+  // first was read, so git, distill, experiment, init, state and links got no
+  // suggestion on a typo:
+  //   Unknown optimize subcommand. Available: …
+  //   Unknown state subcommand: ${subcommand}. Available: …   (also `unknown …`, and
+  //   Unknown init workflow: ${workflow}\nAvailable: …)
+  //   git subcommand required. Available: …
+  const patterns = [
+    /[Uu]nknown ([a-z][a-z-]*) (?:subcommand|workflow)[^'"`\n.]*(?:\.\s*|\\n)Available: ([^'"`\n\\]+)/g,
+    /([a-z][a-z-]*) subcommand required\. Available: ([^'"`\n\\]+)/g,
+  ];
+  for (const re of patterns) {
+    let m;
+    while ((m = re.exec(sourceText)) !== null) {
+      const group = m[1];
+      const subs = m[2]
+        .split(',')
+        .map((s) => s.trim().split(/\s+/)[0])   // drop " [--apply]"-style hints
+        .filter((s) => /^[a-z][a-z0-9-]*$/.test(s));
+      if (subs.length) index[group] = [...new Set([...(index[group] || []), ...subs])];
+    }
   }
   return index;
 }

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

@@ -28,9 +28,12 @@ function cmdTemplateSelect(cwd, planPath, raw) {
     const fullPath = path.join(cwd, planPath);
     const content = fs.readFileSync(fullPath, 'utf-8');
 
-    // Count task headings (### Task N)
-    const taskMatch = content.match(/###\s*Task\s*\d+/g) || [];
-    const taskCount = taskMatch.length;
+    // Count tasks: PAN plans write `<task type="...">` blocks (templates/phase-prompt.md,
+    // pan-planner); older plans used `### Task N` headings. Counting only the headings
+    // gave every current plan a task count of 0.
+    const xmlTasks = content.match(/<task[\s>]/g) || [];
+    const headingTasks = content.match(/###\s*Task\s*\d+/g) || [];
+    const taskCount = xmlTasks.length || headingTasks.length;
 
     // Check for decision-related keywords
     const decisionMatch = content.match(/decision/gi) || [];

package/pan-wizard-core/bin/lib/verify-deploy.cjs

@@ -32,6 +32,24 @@ function detectInstalledRuntimes(cwd) {
   return found;
 }
 
+/**
+ * Whether `buf` is the file a manifest hash was taken from, allowing for line
+ * endings: raw bytes, the all-LF form or the all-CRLF form may match, so a file
+ * git re-checked out with `core.autocrlf=true` is not reported as modified.
+ * Binary (NUL-bearing) buffers compare raw only. Same rule as
+ * `bytesMatchHashIgnoringEol` in bin/install-lib.cjs, which the installed core
+ * cannot require; tests/install-eol-hash.test.cjs pins both.
+ */
+function bytesMatchHashIgnoringEol(crypto, buf, expectedHash) {
+  if (!expectedHash) return false;
+  const sha = b => crypto.createHash('sha256').update(b).digest('hex');
+  if (sha(buf) === expectedHash) return true;
+  if (buf.includes(0)) return false;
+  const lf = buf.toString('latin1').replace(/\r\n/g, '\n');
+  if (sha(Buffer.from(lf, 'latin1')) === expectedHash) return true;
+  return sha(Buffer.from(lf.replace(/\n/g, '\r\n'), 'latin1')) === expectedHash;
+}
+
 /**
  * Validate a single PAN runtime installation.
  * Checks: manifest files exist, hashes match, settings integrity.
@@ -61,8 +79,7 @@ function validateRuntimeInstall(cwd, configDir, runtime) {
     const absPath = path.join(baseDir, relPath);
     try {
       const content = fs.readFileSync(absPath);
-      const actualHash = crypto.createHash('sha256').update(content).digest('hex');
-      if (actualHash !== expectedHash) {
+      if (!bytesMatchHashIgnoringEol(crypto, content, expectedHash)) {
         modified.push(relPath);
       }
     } catch (_) {
@@ -107,7 +124,7 @@ function validateRuntimeInstall(cwd, configDir, runtime) {
         }
       }
     }
-    // Copilot/Gemini statusLine
+    // statusLine (Claude, Copilot; PAN writes none for Gemini since 2026-09-23)
     if (settings.statusLine && settings.statusLine.command) {
       hookCommands.push(settings.statusLine.command);
     }

package/pan-wizard-core/bin/pan-tools.cjs

@@ -420,7 +420,13 @@ async function main() {
     case 'resolve-model': {
       const metadataIdx = args.indexOf('--metadata');
       const metadataJson = metadataIdx !== -1 ? args[metadataIdx + 1] : undefined;
-      commands.cmdResolveModel(cwd, args[1], raw, metadataJson);
+      const attemptRaw = getArgValue(args, '--attempt');
+      let attempt;
+      if (attemptRaw !== null && attemptRaw !== undefined) {
+        if (!/^[1-9]\d*$/.test(String(attemptRaw))) error('--attempt must be a positive integer (1 for a first try)');
+        attempt = parseInt(attemptRaw, 10);
+      }
+      commands.cmdResolveModel(cwd, args[1], raw, metadataJson, attempt);
       break;
     }
 
@@ -1272,6 +1278,9 @@ async function main() {
           daily_budget: budget != null ? Number(budget) : undefined,
           enabled: args.includes('--disable') ? false : undefined,
           paused: args.includes('--pause') ? true : (args.includes('--resume') ? false : undefined),
+          // campaign.cjs has always honoured enforce_budget; no flag reached it, so
+          // making the daily budget a hard stop meant editing schedule.json by hand.
+          enforce_budget: args.includes('--enforce-budget') ? true : (args.includes('--advisory-budget') ? false : undefined),
         }, raw);
       } else if (subcommand === 'status' || !subcommand) {
         campaign.cmdCampaignStatus(cwd, raw);

package/pan-wizard-core/mcp/tool-registry.cjs

@@ -75,13 +75,23 @@ const RESOURCES = [
 const SPAWN_TOOLS = [
   {
     name: 'pan_resolve_model', title: 'Resolve model for an agent', verb: 'resolve-model',
-    description: 'Resolve the model tier/id PAN would use for an agent under the active profile.',
+    description: 'Resolve the model tier/id PAN would use for an agent under the active profile. Pass attempt > 1 for a retry after a failure: the tier climbs toward the agent\'s quality tier (routing.max_escalations caps it).',
     readOnly: true, destructive: false,
     inputSchema: {
       type: 'object', additionalProperties: false, required: ['agent'],
-      properties: { agent: { type: 'string', description: 'Agent type, e.g. pan-planner' } },
+      properties: {
+        agent: { type: 'string', description: 'Agent type, e.g. pan-planner' },
+        attempt: { type: 'integer', minimum: 1, maximum: 99, description: '1 for a first try; 2 for the first retry after a failure' },
+      },
+    },
+    args: (i) => {
+      const out = [str('agent', i && i.agent, AGENT_RE, 64)];
+      if (i && i.attempt !== undefined) {
+        if (!Number.isInteger(i.attempt) || i.attempt < 1 || i.attempt > 99) throw new Error('Invalid "attempt": must be an integer from 1 to 99');
+        out.push('--attempt', String(i.attempt));
+      }
+      return out;
     },
-    args: (i) => [str('agent', i && i.agent, AGENT_RE, 64)],
   },
   {
     name: 'pan_find_phase', title: 'Find a phase', verb: 'find-phase',
@@ -155,7 +165,7 @@ const { NATIVE_TOOLS } = require('./native-tools.cjs');
 // safety argument of ADR-0041 is that no client input reaches it.
 const PROJECT_CWD_PROPERTY = Object.freeze({
   type: 'string',
-  description: 'Absolute path of the PAN project to operate on. Optional: defaults to the directory the server was started in. Pass it when the server was launched from a plugin directory (Agent Plugins clients do this by default), or to address another project.',
+  description: 'Absolute path of the PAN project to operate on. Optional: defaults to the directory the server was started in. Pass it when the server was launched from a plugin directory (Agent Plugins clients do this by default), or to address another project. The server acts on any existing directory named here with the permissions of the user who runs it — it trusts its caller as it trusts the session that started it.',
 });
 
 const PROJECT_CWD_MAX = 1024;

package/pan-wizard-core/references/model-profiles.md

@@ -11,8 +11,8 @@ PAN uses three abstract tiers instead of hardcoded model names:
 | Tier | Purpose | Anthropic | OpenAI | Google |
 |------|---------|-----------|--------|--------|
 | `reasoning` | Architecture, planning, complex decisions | inherit (your session's top-tier model) | inherit | inherit |
-| `mid` | Execution, research, verification | Sonnet | mid | gemini-2.5-flash |
-| `fast` | Read-only extraction, budget tasks | Haiku | fast | gemini-2.5-flash-lite |
+| `mid` | Execution, research, verification | Sonnet | gpt-6-sol | gemini-3.8-flash |
+| `fast` | Read-only extraction, budget tasks | Haiku | gpt-6-luna | gemini-3.5-flash-lite |
 
 **Why `inherit` for reasoning?** Host runtimes map "opus" to a specific model version. PAN returns `inherit` for reasoning-tier agents, so they use whatever top-tier model the user has configured. This avoids version conflicts and silent fallbacks.
 
@@ -39,7 +39,7 @@ At install time PAN also runs a **best-effort, advisory** capability check on th
 | Class | Example model IDs | Role in PAN | Context | Relative cost | Notes |
 |-------|-------------------|-------------|---------|---------------|-------|
 | Fable / Mythos | `claude-fable-5` | **Recommended flagship** — deepest long-horizon reasoning; best for the bot army's Mission Control + planning | 1M | ~2× Opus | Runs input safety classifiers (see caveat below); requires 30-day data retention |
-| Opus | `claude-opus-5`, `claude-opus-4-8` | **Cost-conscious pick** — same 1M context + thinking, about half the cost, no cyber classifier | 1M | 1× | The safe pick when you want Opus behavior without Fable's refusal surface |
+| Opus | `claude-opus-5-5`, `claude-opus-5`, `claude-opus-4-8` | **Cost-conscious pick** — same 1M context + thinking, about half the cost, no cyber classifier | 1M | 1× | The safe pick when you want Opus behavior without Fable's refusal surface |
 
 **Why the Fable class is the recommended flagship.** It is Anthropic's deepest class for demanding, long-horizon agentic work — exactly what PAN's hierarchical bot army (Mission Control → squads → workers) asks of its reasoning tier. Select the current release in that class in your host runtime and `inherit` routes the reasoning-tier agents to it automatically.
 
@@ -117,7 +117,7 @@ PAN auto-detects the LLM provider to map tiers to the right model names:
 
 1. **Explicit config** — `routing.provider` in config.json (if not `"auto"`)
 2. **Environment variable** — `PAN_PROVIDER` env var
-3. **Runtime directory** — `.claude/` → Anthropic, `.codex/` → OpenAI, `.gemini/` → Google
+3. **Runtime directory** — `.claude/` → Anthropic, `.codex/` → OpenAI, `.gemini/` → Google, `.opencode/` → OpenAI, `.github/` → default (first match wins)
 4. **Fallback** — Default provider map (Anthropic-style names)
 
 ---

package/pan-wizard-core/references/planning-config.md

@@ -4,24 +4,22 @@ Configuration options for `.planning/` directory behavior.
 
 <config_schema>
 ```json
-"planning": {
-  "commit_docs": true,
-  "search_gitignored": false
-},
-"git": {
-  "branching_strategy": "none",
-  "phase_branch_template": "pan/phase-{phase}-{slug}",
-  "milestone_branch_template": "pan/{milestone}-{slug}"
-}
+"commit_docs": true,
+"search_gitignored": false,
+"branching_strategy": "none",
+"phase_branch_template": "pan/phase-{phase}-{slug}",
+"milestone_branch_template": "pan/{milestone}-{slug}"
 ```
 
 | Option | Default | Description |
 |--------|---------|-------------|
 | `commit_docs` | `true` | Whether to commit planning artifacts to git |
 | `search_gitignored` | `false` | Add `--no-ignore` to broad rg searches |
-| `git.branching_strategy` | `"none"` | Git branching approach: `"none"`, `"phase"`, or `"milestone"` |
-| `git.phase_branch_template` | `"pan/phase-{phase}-{slug}"` | Branch template for phase strategy |
-| `git.milestone_branch_template` | `"pan/{milestone}-{slug}"` | Branch template for milestone strategy |
+| `branching_strategy` | `"none"` | Git branching approach: `"none"`, `"phase"`, or `"milestone"` |
+| `phase_branch_template` | `"pan/phase-{phase}-{slug}"` | Branch template for phase strategy |
+| `milestone_branch_template` | `"pan/{milestone}-{slug}"` | Branch template for milestone strategy |
+
+These keys are top-level. The nested `planning.*` / `git.*` forms older versions wrote are read only when the top-level key is absent. A config `config-ensure-section` creates carries every top-level key, and one `/pan:new-project` writes carries a top-level `commit_docs` — so write the top-level key; a nested one is ignored whenever the top-level key exists.
 </config_schema>
 
 <commit_docs_behavior>
@@ -84,10 +82,8 @@ To use uncommitted mode:
 
 1. **Set config:**
    ```json
-   "planning": {
-     "commit_docs": false,
-     "search_gitignored": true
-   }
+   "commit_docs": false,
+   "search_gitignored": true
    ```
 
 2. **Add to .gitignore:**
@@ -101,7 +97,7 @@ To use uncommitted mode:
    git commit -m "chore: stop tracking planning docs"
    ```
 
-4. **Branch merges:** When using `branching_strategy: phase` or `milestone`, the `milestone-done` workflow automatically strips `.planning/` files from staging before merge commits when `commit_docs: false`.
+4. **Branch merges:** PAN never merges branches; when you merge a phase or milestone branch yourself with `commit_docs: false`, keep `.planning/` out of the merge commit.
 
 </setup_uncommitted_mode>
 
@@ -113,24 +109,24 @@ To use uncommitted mode:
 |----------|---------------------|--------------|-------------|
 | `none` | Never | N/A | N/A |
 | `phase` | At `execute-phase` start | Single phase | User merges after phase |
-| `milestone` | At first `execute-phase` of milestone | Entire milestone | At `milestone-done` |
+| `milestone` | At first `execute-phase` of milestone | Entire milestone | User merges after milestone |
 
-**When `git.branching_strategy: "none"` (default):**
+**When `branching_strategy: "none"` (default):**
 - All work commits to current branch
 - Standard PAN behavior
 
-**When `git.branching_strategy: "phase"`:**
+**When `branching_strategy: "phase"`:**
 - `execute-phase` creates/switches to a branch before execution
 - Branch name from `phase_branch_template` (e.g., `pan/phase-03-authentication`)
 - All plan commits go to that branch
 - User merges branches manually after phase completion
-- `milestone-done` offers to merge all phase branches
+- `milestone-done` does not merge — merge the phase branches yourself
 
-**When `git.branching_strategy: "milestone"`:**
+**When `branching_strategy: "milestone"`:**
 - First `execute-phase` of milestone creates the milestone branch
 - Branch name from `milestone_branch_template` (e.g., `pan/v1.0-mvp`)
 - All phases in milestone commit to same branch
-- `milestone-done` offers to merge milestone branch to main
+- `milestone-done` archives and tags but does not merge — merge the milestone branch yourself
 
 **Template variables:**
 

package/pan-wizard-core/workflows/exec-phase.md

@@ -117,6 +117,14 @@ Parse JSON for: `phase`, `plans[]` (each with `id`, `wave`, `autonomous`, `objec
 
 **Filtering:** Skip plans where `has_summary: true`. If `--gaps-only`: also skip non-gap_closure plans. If all filtered: "No matching incomplete plans" → exit.
 
+**If `--gaps-only`:** this run is the fix round after a verification found gaps — a second attempt at work that failed once. Resolve the executor for that attempt and use it in place of `executor_model` for every spawn in this run:
+
+```bash
+EXECUTOR_MODEL=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs resolve-model pan-executor --attempt 2 --raw)
+```
+
+It equals `executor_model` unless the `budget` profile runs the executor below its quality tier; then it is one tier higher (capped by `routing.max_escalations`), so the gaps are not retried on the tier that left them.
+
 Report:
 ```
 ## Execution Plan

package/pan-wizard-core/workflows/help.md

@@ -224,7 +224,7 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 | `/pan:plan-phase <N>` | Research + plan a phase with verification |
 | `/pan:exec-phase <N>` | Execute plans with wave-based parallelization |
 | `/pan:research-phase <N>` | Deep ecosystem research for specialized domains |
-| `/pan:verify-phase <N>` | Validate built features through UAT |
+| `/pan:verify-phase <N>` | Re-run goal-backward verification with a test-suite gate |
 
 ### Phase Management
 | Command | Description |
@@ -348,7 +348,7 @@ The Focus workflow is a **scan → plan → exec → sync** pipeline. Each step
 
 **`/pan:exec-phase <N>`** — Execute all plans in a phase. Groups by wave, runs waves sequentially, plans within each wave in parallel.
 
-**`/pan:verify-phase <N>`** — Conversational UAT. Presents tests one at a time, diagnoses failures, creates fix plans.
+**`/pan:verify-phase <N>`** — Re-run goal-backward verification behind a test-suite gate. Writes the phase's verification report (passed, gaps_found or human_needed); fix gaps with `/pan:plan-phase <N> --gaps`.
 
 **`/pan:quick <desc>`** — Small tasks with PAN guarantees but shorter path. Skips researcher, checker, verifier. Lives in `.planning/quick/`.
 

package/pan-wizard-core/workflows/phase-tests.md

@@ -364,7 +364,7 @@ Present next steps:
 
 **Also available:**
 - `/pan:phase-tests {next_phase}` — test another phase
-- `/pan:verify-phase {phase_number}` — run UAT verification
+- `/pan:verify-phase {phase_number}` — re-run goal-backward verification
 
 ---
 ```

package/pan-wizard-core/workflows/progress.md

@@ -252,7 +252,7 @@ uat.md exists with gaps (diagnosed issues). User needs to plan fixes.
 
 **Also available:**
 - `/pan:exec-phase {phase}` — execute phase plans
-- `/pan:verify-phase {phase}` — run more UAT testing
+- `/pan:verify-phase {phase}` — re-run goal-backward verification
 
 ---
 ```