pan-wizard 3.15.0 → 3.17.0

package/README.md

@@ -553,7 +553,7 @@ You're never locked in. The system adapts.
 
 PAN is not a replacement for your IDE or AI agent — it's the orchestration layer that handles everything *around* them: breaking work into context-safe chunks, researching before planning, verifying after execution, and maintaining state across sessions.
 
-> For the full comparison across 8 tools and 15+ dimensions, see [COMPARISON.md](docs/COMPARISON.md).
+> For the full comparison across the major AI coding tools and many dimensions, see [COMPARISON.md](docs/COMPARISON.md).
 
 ---
 
@@ -834,7 +834,7 @@ This removes all PAN commands, agents, hooks, and settings while preserving your
 ## Documentation
 
 <div align="center">
-<img src="https://cdn.jsdelivr.net/npm/pan-wizard@latest/assets/pan-docs-header.png" alt="" width="720" />
+<img src="https://cdn.jsdelivr.net/npm/pan-wizard@latest/assets/pan-developer.png" alt="A developer reading the PAN Wizard documentation" width="600" />
 </div>
 
 | Document | Audience | What it covers |

package/commands/pan/army.md

@@ -125,9 +125,13 @@ Spawn the Quality squad on the built tree (parallel, read-only). Merge findings
 ### Phase 5 — Integrate (Release, human-gated)
 Spawn `pan-release`. It prepares the squash-merge, runs the configured `verification`, and surfaces an **always-ask** approval request. A human approves the merge to the protected branch; release then tags and records the rollback target. `--push` pushes the approved result.
 
+**Phase report (opt-in build deliverable):** when `workflow.phase_reports.enabled` is `true`, generate the mission's self-contained per-phase HTML report **in the built tree, before staging the squash-merge** — `pan-tools report phase <N>` — so the report rides along in the merge as a phase deliverable. **Never run `report index` inside a squad worktree:** the timeline index is a single shared file that aggregates *all* phases, so a worktree would see only its own phase and concurrent squads would race on it. The index is a single-writer, post-merge concern (Phase 6). Never opens a browser.
+
 ### Phase 6 — Learn (Dreaming)
 Squad summaries return to Mission Control. Run `/pan:retro --write-memory` (and `/pan:learn` if traces exist) so recurring patterns persist into agent memory for the next mission. Strike the landed item; update loop-state. For a scheduled campaign, also `pan-tools campaign record-run --items <n> --points <p>` so the next-due time and the day's spend advance.
 
+**Rebuild the timeline index (single writer).** When `workflow.phase_reports.enabled` and `workflow.phase_reports.index` are `true`, Mission Control — and *only* Mission Control, on the integration branch after the merge has landed — rebuilds the project index once against the now-merged set of phases: `pan-tools report index`, then commit it (the commit honors `commit_docs`). Doing this post-merge from the single conductor is what keeps `report-index.html` consistent while builds run in parallel worktrees.
+
 ---
 
 ## Scheduled, self-resuming campaigns (ADR-0034)

package/commands/pan/focus-doc-audit.md

@@ -156,7 +156,7 @@ For each target document, extract every verifiable claim.
 | Category | Pattern | Example |
 |----------|---------|---------|
 | **Version claim** | `v1.2.3`, `version 1.2`, `Version: X` | "Currently at v3.1.0" |
-| **Count claim** | Number + noun | "42 test suites", "15 API endpoints" |
+| **Count claim** | Number + noun | "42 database tables", "15 API endpoints" |
 | **File path claim** | Path-like strings | "`src/core/handler.ts`" |
 | **Command claim** | Code block with shell prefix or instruction | "`npm run build`" |
 | **Feature claim** | "supports X", "includes Y", "provides Z" | "Supports hot reloading" |

package/commands/pan/report.md

@@ -2,7 +2,7 @@
 name: pan:report
 group: Observability
 description: Generate a self-contained HTML report for one phase, or a project-level timeline index linking every phase report
-argument-hint: "phase <N> | index | all [--out <file>] [--open] [--stdout]"
+argument-hint: "phase <N> | index [--bundle] | all [--out <file>] [--open] [--stdout]"
 allowed-tools:
   - Read
   - Bash
@@ -24,7 +24,7 @@ Reports are honest by construction: the `verify reconcile` verdict is shown besi
 
 ```
 pan-tools report phase <N> [--out <file>] [--open] [--stdout]
-pan-tools report index      [--out <file>] [--open] [--stdout]
+pan-tools report index      [--out <file>] [--open] [--stdout] [--bundle]
 pan-tools report all        [--open]
 ```
 
@@ -37,6 +37,7 @@ pan-tools report all        [--open]
 - `--out <file>` — write to a custom path instead of the default (relative paths resolve against the project root).
 - `--open` — best-effort: launch the written file in the default browser (cross-platform; silently no-ops if no opener is available, and never opens when nothing was written).
 - `--stdout` — print the HTML to stdout instead of writing a file (for `phase`/`index`).
+- `--bundle` (on `index`) — emit one self-contained `.planning/report-bundle.html`: the timeline plus every phase report inlined under in-page anchors, with no links to sibling files. This is the form to email or attach — a single file that stays whole when moved off-disk.
 
 **Behaviour worth knowing:**
 - **Deterministic writes.** Re-running with unchanged phase data rewrites nothing (the only volatile value, the generated-at timestamp, is ignored when comparing) — so reports produce no git churn.
@@ -61,7 +62,7 @@ pan-tools report all        [--open]
 
 **Review a phase:** run `pan-tools report phase <N> --open` to see one phase's objective, what changed, and its verification verdict at a glance.
 
-**Share the project:** `pan-tools report index` builds the timeline entry point — send `.planning/report-index.html` and the linked phase files, or open the index and click through.
+**Share the project:** `pan-tools report index` builds the timeline entry point — send `.planning/report-index.html` and the linked phase files, or open the index and click through. To hand someone a single file instead, `pan-tools report index --bundle` inlines every phase into one `.planning/report-bundle.html` that survives being emailed or moved.
 
 **Refresh everything:** `pan-tools report all` after a milestone regenerates every report; unchanged ones are skipped, so only what actually moved is rewritten.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pan-wizard",
-  "version": "3.15.0",
+  "version": "3.17.0",
   "description": "Command a bot army for your codebase: an Opus Mission Control delegates whole-project goals to specialist squads and ships behind a human merge gate. Five AI CLIs, zero context rot.",
   "bin": {
     "pan-wizard": "bin/install.js"

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

@@ -53,6 +53,8 @@ function buildConfigDefaults(hasBraveSearch, userDefaults) {
       verifier: true,
       nyquist_validation: false,
       phase_record_compact: false,
+      // M2: opt-in per-phase HTML reports at the verify→complete gate.
+      phase_reports: { enabled: false, open: false, theme: 'auto', index: true },
     },
     parallelization: true,
     brave_search: hasBraveSearch,

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

@@ -809,11 +809,48 @@ function focusAutoUpdate(cwd, raw, getVal) {
   }, raw);
 }
 
+/**
+ * Whether opt-in HTML phase reports are enabled for this project.
+ * Reads the raw config.json (loadConfig doesn't surface the workflow block);
+ * absent / malformed config → disabled.
+ */
+function phaseReportsEnabled(cwd) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(path.join(planningPath(cwd), 'config.json'), 'utf-8'));
+    return !!(raw.workflow && raw.workflow.phase_reports && raw.workflow.phase_reports.enabled);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Regenerate every phase report + index as part of a focus-auto checkpoint,
+ * when the feature is enabled. Best-effort and side-effect-light: never opens a
+ * browser, and silently no-ops for phase-less / focus-auto-only projects. The
+ * fresh HTML lands in .planning/ so the checkpoint's `git add` sweeps it in.
+ */
+function maybeRenderPhaseReports(cwd) {
+  if (!phaseReportsEnabled(cwd)) return;
+  try {
+    const { renderAllToDisk } = require('./phase-report.cjs');
+    renderAllToDisk(cwd, {});
+  } catch {
+    // Report generation must never block the checkpoint commit.
+  }
+}
+
 function focusAutoCheckpointCommit(cwd, cycle, run) {
   if (!isGitRepo(cwd)) return null;
   const config = loadConfig(cwd);
   const autoCommit = config.focus && config.focus.auto_commit !== undefined ? config.focus.auto_commit : true;
   if (!autoCommit) return null;
+  // commit_docs is the global switch for committing planning artifacts; focus-auto
+  // is a planning-doc committer, so honor it. commit_docs=false → hands the .planning
+  // commit (and any report regeneration) back to the user.
+  if (config.commit_docs === false) return null;
+  // Enabled projects: refresh the HTML reports before staging so the committed
+  // .planning/ snapshot reflects this cycle.
+  maybeRenderPhaseReports(cwd);
   const status = execGit(cwd, ['status', '--porcelain', PLANNING_DIR + '/']);
   if (status.exitCode !== 0 || !status.stdout) return null;
   execGit(cwd, ['add', PLANNING_DIR + '/']);

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

@@ -44,6 +44,7 @@ const cost = require('./cost.cjs');
 
 const REPORT_SUFFIX = '-report.html';
 const INDEX_FILE = 'report-index.html';
+const BUNDLE_FILE = 'report-bundle.html';
 
 // ─── small helpers ─────────────────────────────────────────────────────────────
 
@@ -548,7 +549,8 @@ function indexHero(d) {
   </section>`;
 }
 
-function indexTimeline(d) {
+function indexTimeline(d, hrefFn) {
+  const href = hrefFn || ((p) => p.href);
   const rows = d.phases.map((p, i) => {
     const color = STATUS_DOT[p.status] || '#C9C0AE';
     const isLast = i === d.phases.length - 1;
@@ -560,7 +562,7 @@ function indexTimeline(d) {
     return `
     <div class="trow">
       <div class="rail"><span class="rd" style="background:${color}"></span>${isLast ? '' : `<span class="rl" style="background:${railColor}"></span>`}</div>
-      <a class="tcard" href="${esc(p.href)}">
+      <a class="tcard" href="${esc(href(p))}">
         <div>
           <div class="tt">${esc(p.number)}${p.name ? ' · ' + esc(p.name) : ''}</div>
           <div class="tsub"><span class="mini">${mini}</span><span>${p.plansTotal ? p.plansDone + ' / ' + p.plansTotal + ' plans' : 'no plans'}</span>${p.has_report ? '' : '<span>· report pending</span>'}</div>
@@ -577,6 +579,33 @@ function renderIndexHtml(d) {
   return docShell(`PanWizard · ${d.project} — timeline`, body, d.generated_at);
 }
 
+/**
+ * Bundle: the timeline index plus EVERY phase report inlined into one
+ * self-contained document, cross-linked by in-page #phase-NN anchors. Because
+ * navigation is anchors (not sibling files), the links never dangle when the
+ * single file is emailed or copied on its own. (indexData, phaseDatas) are pure.
+ */
+function renderBundleHtml(indexData, phaseDatas) {
+  const anchorHref = (p) => '#phase-' + encodeURIComponent(String(p.number));
+  const sections = (phaseDatas || []).filter(Boolean).map(d => `
+  <section id="phase-${esc(d.phase.number)}" style="margin-top:26px;border-top:1px solid var(--border);padding-top:8px">
+    <div class="crumbs"><a href="#top">↑ back to timeline</a></div>
+    ${reportHero(d)}
+    ${reportMetrics(d)}
+    <div class="grid"><div class="gcol">${reportObjective(d)}</div><div class="gcol">${reportVerification(d)}</div></div>
+    ${reportChanges(d)}
+    ${reportGaps(d)}
+  </section>`).join('\n');
+  const body = [
+    '<span id="top"></span>',
+    indexTopBar(indexData),
+    indexHero(indexData),
+    indexTimeline(indexData, anchorHref),
+    sections,
+  ].filter(Boolean).join('\n');
+  return docShell(`PanWizard · ${indexData.project} — full report`, body, indexData.generated_at);
+}
+
 // ─── side effects (the only impure layer) ────────────────────────────────────────
 
 /**
@@ -667,6 +696,19 @@ function cmdReport(cwd, opts = {}, raw) {
   if (action === 'index') {
     const data = collectIndexData(cwd, { now });
     if (!data) return error('No phases found — nothing to index (phase-less / focus-auto project). Use `pan-tools hud` instead.');
+    if (opts.bundle) {
+      const phaseDatas = data.phases.map(p => collectPhaseData(cwd, p.number, { now })).filter(Boolean);
+      const html = renderBundleHtml(data, phaseDatas);
+      if (opts.stdout) { process.stdout.write(html); return; }
+      const outPath = opts.out ? path.resolve(cwd, opts.out) : path.join(planningPath(cwd), BUNDLE_FILE);
+      const res = writeIfChanged(outPath, html);
+      const opened = opts.open && res.written ? openInBrowser(outPath) : false;
+      return output(
+        { action: 'bundle', phases: phaseDatas.length, path: toPosix(outPath), bytes: Buffer.byteLength(html), written: res.written, opened },
+        raw,
+        `bundle ${res.written ? 'written' : 'unchanged'}: ${toPosix(outPath)}`,
+      );
+    }
     const html = renderIndexHtml(data);
     if (opts.stdout) { process.stdout.write(html); return; }
     const outPath = opts.out ? path.resolve(cwd, opts.out) : path.join(planningPath(cwd), INDEX_FILE);
@@ -680,42 +722,62 @@ function cmdReport(cwd, opts = {}, raw) {
   }
 
   if (action === 'all') {
-    const dirs = listPhaseDirs(cwd);
-    if (!dirs.length) return error('No phases found — nothing to report.');
-    const reports = [];
-    for (const dirName of dirs) {
-      const { number } = parsePhaseDir(dirName);
-      const data = collectPhaseData(cwd, number, { now });
-      if (!data) continue;
-      const outPath = path.join(data.phase.dir, `${data.phase.number}${REPORT_SUFFIX}`);
-      const res = writeIfChanged(outPath, renderPhaseHtml(data));
-      reports.push({ phase: data.phase.number, path: toPosix(outPath), written: res.written });
-    }
-    const idx = collectIndexData(cwd, { now });
-    let index = { path: null, written: false };
-    if (idx) {
-      const outPath = path.join(planningPath(cwd), INDEX_FILE);
-      const res = writeIfChanged(outPath, renderIndexHtml(idx));
-      index = { path: toPosix(outPath), written: res.written };
-    }
+    const res = renderAllToDisk(cwd, { now });
+    if (!res) return error('No phases found — nothing to report.');
     return output(
-      { action, reports, index },
+      { action, reports: res.reports, index: res.index },
       raw,
-      `generated ${reports.length} phase report(s)${index.path ? ' + index' : ''}`,
+      `generated ${res.reports.length} phase report(s)${res.index.path ? ' + index' : ''}`,
     );
   }
 
   return error('Unknown report action. Available: phase <N>, index, all');
 }
 
+/**
+ * Regenerate every phase report + the timeline index straight to disk.
+ * Programmatic sibling of `cmdReport('all')` with NO stdout side effects and
+ * no browser opening — used by focus-auto / army in-tree checkpoints, which
+ * emit their own JSON and must not have report output interleaved into it.
+ * @param {string} cwd
+ * @param {{now?:Date}} opts
+ * @returns {{reports:Array<{phase:string,path:string,written:boolean}>, index:{path:string|null,written:boolean}}|null}
+ *   null when the project has no phases (phase-less / focus-auto-only).
+ */
+function renderAllToDisk(cwd, opts = {}) {
+  const now = opts.now;
+  const dirs = listPhaseDirs(cwd);
+  if (!dirs.length) return null;
+  const reports = [];
+  for (const dirName of dirs) {
+    const { number } = parsePhaseDir(dirName);
+    const data = collectPhaseData(cwd, number, { now });
+    if (!data) continue;
+    const outPath = path.join(data.phase.dir, `${data.phase.number}${REPORT_SUFFIX}`);
+    const res = writeIfChanged(outPath, renderPhaseHtml(data));
+    reports.push({ phase: data.phase.number, path: toPosix(outPath), written: res.written });
+  }
+  const idx = collectIndexData(cwd, { now });
+  let index = { path: null, written: false };
+  if (idx) {
+    const outPath = path.join(planningPath(cwd), INDEX_FILE);
+    const res = writeIfChanged(outPath, renderIndexHtml(idx));
+    index = { path: toPosix(outPath), written: res.written };
+  }
+  return { reports, index };
+}
+
 module.exports = {
   REPORT_SUFFIX,
   INDEX_FILE,
+  BUNDLE_FILE,
   collectPhaseData,
   collectIndexData,
   renderPhaseHtml,
   renderIndexHtml,
+  renderBundleHtml,
   cmdReport,
+  renderAllToDisk,
   // exported for focused unit tests
   resolvePhase,
   extractPhaseGoal,

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

@@ -890,6 +890,7 @@ async function main() {
           out: getArgValue(args, '--out'),
           open: args.includes('--open'),
           stdout: args.includes('--stdout'),
+          bundle: args.includes('--bundle'),
         }, raw);
       } else if (subcommand === 'all') {
         phaseReport.cmdReport(cwd, { action: 'all', open: args.includes('--open') }, raw);

package/pan-wizard-core/templates/config.json

@@ -7,7 +7,8 @@
     "verifier": true,
     "auto_advance": false,
     "nyquist_validation": false,
-    "phase_record_compact": false
+    "phase_record_compact": false,
+    "phase_reports": { "enabled": false, "open": false, "theme": "auto", "index": true }
   },
   "planning": {
     "commit_docs": true,

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

@@ -602,8 +602,24 @@ The CLI handles:
 
 Extract from result: `next_phase`, `next_phase_name`, `is_last_phase`.
 
+**Phase reports (opt-in build deliverable):** when `workflow.phase_reports.enabled` is `true`, generate the self-contained per-phase HTML report — and, when `workflow.phase_reports.index` is `true`, the project timeline index — at this verify→complete gate so they ship with the phase and ride the commit below. Disabled by default; phase-less projects are skipped automatically by `report`. Never opens a browser here (that's reserved for a manual `pan-tools report --open`).
+
+```bash
+REPORT_FILES=""
+if [ "$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-get workflow.phase_reports.enabled 2>/dev/null || echo false)" = "true" ]; then
+  if node ~/.claude/pan-wizard-core/bin/pan-tools.cjs report phase "${PHASE_NUMBER}" >/dev/null 2>&1; then
+    REPORT_FILES="{phase_dir}/*-report.html"
+    if [ "$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-get workflow.phase_reports.index 2>/dev/null || echo true)" = "true" ]; then
+      node ~/.claude/pan-wizard-core/bin/pan-tools.cjs report index >/dev/null 2>&1 && REPORT_FILES="$REPORT_FILES .planning/report-index.html"
+    fi
+  fi
+fi
+```
+
+The report files are appended to the completion commit's `--files` list (`$REPORT_FILES`, empty when disabled), so `cmdCommit` still honors `commit_docs` + gitignore + safety checks with no new commit logic:
+
 ```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs(phase-{X}): complete phase execution" --files .planning/roadmap.md .planning/state.md .planning/requirements.md {phase_dir}/*-verification.md
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs(phase-{X}): complete phase execution" --files .planning/roadmap.md .planning/state.md .planning/requirements.md {phase_dir}/*-verification.md $REPORT_FILES
 ```
 
 **Circular optimization — finalize trace session:**