pan-wizard 3.30.0 → 3.32.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

@@ -20,6 +20,7 @@ const {
   PROGRESS_BAR_WIDTH,
   FILLED_BLOCK,
   EMPTY_BLOCK,
+  STATE_CONTRACT,
 } = require('./constants.cjs');
 const {
   planningPath,
@@ -51,6 +52,7 @@ function cmdStateLoad(cwd, raw) {
   const stateExists = stateRaw.length > 0;
 
   const result = {
+    contract: STATE_CONTRACT,
     config,
     state_raw: stateRaw,
     state_exists: stateExists,
@@ -799,20 +801,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 +851,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 +880,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 +932,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,13 +977,16 @@ function cmdStateJson(cwd, raw) {
   const frontmatter = extractFrontmatter(content);
 
   if (!frontmatter || Object.keys(frontmatter).length === 0) {
-    const body = stripFrontmatter(content);
-    const built = buildStateFrontmatter(body, cwd);
+    const body = stripFrontmatter(content).replace(/\r\n/g, '\n');
+    const built = { ...buildStateFrontmatter(body, cwd), contract: STATE_CONTRACT };
     output(built, raw, JSON.stringify(built, null, 2));
     return;
   }
 
-  output(frontmatter, raw, JSON.stringify(frontmatter, null, 2));
+  // `contract` is the output's shape version (STATE_CONTRACT), never a state.md
+  // field: PAN's state frontmatter has no such key, so nothing is shadowed.
+  const withContract = { ...frontmatter, contract: STATE_CONTRACT };
+  output(withContract, raw, JSON.stringify(withContract, null, 2));
 }
 
 /**

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) || [];