pan-wizard 3.5.1 → 3.7.10

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

@@ -6,8 +6,32 @@ Create executable phase prompts (plan.md files) for a roadmap phase with integra
 Read all files referenced by the invoking prompt's execution_context before starting.
 
 @~/.claude/pan-wizard-core/references/ui-brand.md
+@~/.claude/pan-wizard-core/references/guardrails.md
+
+> **Also see:** `~/.claude/pan-wizard-core/learnings/universal/` — AI-derived patterns from prior experiments. **Don't skim the whole folder.** Run `pan-tools learn topics-for --agent planner --token-budget 5000 --raw` to load only the topics tagged relevant for planning at the configured budget. Per P-RES-002 (distractor-density research), reading every topic degrades reasoning even at modest token counts.
 </required_reading>
 
+## Phase 0 — Clarify Phase Scope (recommended)
+
+Before drafting the phase plan, confirm:
+
+1. **What does "complete" look like for this phase?**
+2. **What's deliberately out of scope?**
+3. **Any constraints or dependencies on other phases?**
+
+If the answers aren't already in `.planning/requirements.md` or the phase context file, ask the user. A 2-minute clarification prevents 30-minute rework downstream.
+
+## Re-Read Checkpoints
+
+Context compaction may have dropped earlier sections. Re-read the relevant section *before* you begin each step — not after you hit a problem.
+
+| Before this step | Re-read | Why |
+|------------------|---------|-----|
+| Writing the plan | This workflow's "Plan structure" section | Plan format drifts across long sessions |
+| Spawning the planner agent | `references/guardrails.md` | Code Preservation Principle applies to all generated code |
+| Reviewing planner output | `references/checkpoints.md` | Checkpoint conventions are easy to misremember |
+| Marking plan ready | `workflows/exec-phase.md` | The downstream consumer's expectations matter |
+
 <process>
 
 ## 1. Initialize
@@ -152,6 +176,28 @@ If `context_path` is not null, display: `Using phase context from: ${context_pat
 
 **If `context_path` is null (no context.md exists):**
 
+**P-1802 fix (v3.7.7):** in `--auto` mode (or when `workflow.auto_advance` is true) **do not call `AskUserQuestion`** and **do not attempt to spawn `discuss-phase` either** (discuss-phase has its own unguarded AskUserQuestion calls deeper in the workflow — they exit headless `claude -p` immediately). Instead, **proceed without a context.md**: the planner derives implementation decisions from project-level research, requirements, and the original idea.md frontmatter.
+
+This trades user-design-input quality for autonomous reliability — in auto mode the user has already encoded their preferences in idea.md / project.md / requirements.md, so a missing per-phase context.md is acceptable. Surfaced when wookie's Phase 3 was launched directly with `/pan:plan-phase 3 --auto` (no Phase 3 context.md yet) and `/pan:discuss-phase 3 --auto` (which itself exited): both exited in 40-75 seconds with zero commits before this fix. Same root pattern as P-1301 which removed AskUserQuestion from `new-project.md`'s auto block.
+
+**Auto-mode decision (no user prompt):**
+
+If `--auto` flag is present in `$ARGUMENTS` OR `workflow.auto_advance` is `true` in config:
+
+1. Log a `decision` trace event:
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace log \
+  --type decision --category skip-context-auto \
+  --description "Phase ${PHASE} P-1802 bypass: no context.md, proceeding with research+requirements+idea only" \
+  --agent orchestrator --impact minor 2>/dev/null || true
+```
+
+2. Display: `Auto-mode: no Phase ${PHASE} context.md — planning from project-level research + requirements + idea.md`
+
+3. Proceed to step 5 (Handle Research). The `pan-planner` agent reads project-level `.planning/research/architecture.md`, `features.md`, `stack.md` and the original `.planning/idea.md` to derive phase-scoped decisions itself.
+
+**Interactive-mode decision tree (the original behavior; runs when neither `--auto` nor `workflow.auto_advance` is set):**
+
 Use AskUserQuestion:
 - header: "No context"
 - question: "No context.md found for Phase {X}. Plans will use research and requirements only — your design preferences won't be included. Continue or capture context first?"
@@ -166,6 +212,18 @@ If "Run discuss-phase first": Display `/pan:discuss-phase {X}` and exit workflow
 
 **Skip if:** `--gaps` flag, `--skip-research` flag, or `research_enabled` is false (from init) without `--research` override.
 
+**P-1401 lightweight-phase bypass (v3.7.3+):** Also skip per-phase research when ALL three are true:
+
+1. The phase has only **1 plan** (read `plan_count` from init JSON)
+2. The plan's `change_class` is in `[chore, docs, feat-trivial]` (i.e., scaffolding, config, single-file feat with ≤3 tasks)
+3. Project-level `research/architecture.md`, `features.md`, `stack.md` already exist (so the planner has broad context to draw from)
+
+In that case, log a `decision` trace event (`type: "decision", category: "skip-research-trivial"`) and proceed directly to step 6 (planning). Saves ~3 commits and ~5 minutes per trivial phase. Surfaced by panloop run: Phase 1 (project setup, scaffolding only) over-ceremonialized.
+
+This is a workflow-level optimization — the planner still produces a plan, just without per-phase research.md. Phase 2+ phases with substantive build work still go through full research.
+
+**P-1602 phase_record_compact (v3.7.5+):** When `workflow.phase_record_compact: true` AND the lightweight-phase bypass above triggers, also skip per-phase context.md creation (step 4) and emit a single combined `${PHASE_NUM}-record.md` after planning containing: goal, locked decisions (from project-level context), plan summary, must_haves. Reduces 4-file phase output (context, research, plan, summary) to a 2-file output (record, plan) for trivial phases. Off by default — opt-in via `pan-tools config-set workflow.phase_record_compact true`. Substantive phases (>1 plan or non-trivial change_class) still produce full per-phase artifacts regardless of this flag.
+
 **If `has_research` is true (from init) AND no `--research` flag:** Use existing, skip to step 6.
 
 **If research.md missing OR `--research` flag:**

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

@@ -18,6 +18,24 @@ Mark current phase complete and advance to next. This is the natural point where
 
 </purpose>
 
+<state_write_policy>
+
+**P-1604 (v3.7.5) — batch state.md writes.** This workflow contains 5 logically separate state.md updates: position, progress bar, Project Reference, Accumulated Context, Session Continuity. Earlier versions wrote each as its own edit + commit, which produced 5 commits per transition (visible as state-file thrash in trace logs).
+
+**Required pattern from v3.7.5 onward:**
+
+1. Run the steps below to *plan* each state.md update, but **do not write or commit** between them. Hold the changes in memory.
+2. After `update_session_continuity_after_transition` (the last state.md-touching step before `offer_next_phase`), perform a **single Edit** that applies all four section updates (Project Reference, Accumulated Context, Session Continuity, plus the progress bar from `update_current_position_after_transition`).
+3. Then issue **one** commit:
+   ```bash
+   node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs(transition): phase ${current_phase} → ${next_phase} (state, progress, context)"
+   ```
+   The `phase complete` call inside `update_roadmap_and_state` makes its own commit (roadmap + state position) — that one stays separate, since it must run first to compute `next_phase`.
+
+Net result per transition: 2 commits instead of 5. Reduces git noise and keeps `/pan:learn` overhead metrics (commits_per_minute) honest. Substantive content of each step below is unchanged — only the **timing of the write** changes.
+
+</state_write_policy>
+
 <process>
 
 <step name="load_project_state" priority="first">
@@ -317,6 +335,14 @@ After (if database indexing was addressed in Phase 2):
 
 Update Session Continuity section in state.md to reflect transition completion.
 
+**P-1804 fix (v3.7.8):** the "Stopped at" line is mirrored into the frontmatter `stopped_at:` field by `syncStateFrontmatter()`. Direct `Edit` on the body alone leaves frontmatter and body out of sync — that's why the wookie run's frontmatter still showed `"Phase 1 plan 01-01 executed, awaiting verification"` after Phase 5 completed. **Use `pan-tools state update` for "Stopped at"** so the frontmatter resyncs automatically; the other two lines (Last session, Resume file) have no frontmatter mirror and can be edited directly.
+
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state update "Stopped at" "Phase ${current_phase} complete, ready to plan Phase ${next_phase}"
+```
+
+Then Edit state.md (still under the P-1604 batched-write policy — fold this Edit into the final batched Edit at the end of the workflow):
+
 **Format:**
 
 ```markdown
@@ -328,7 +354,7 @@ Resume file: None
 **Step complete when:**
 
 - [ ] Last session timestamp updated to current date and time
-- [ ] Stopped at describes phase completion and next phase
+- [ ] Stopped at field updated **via `pan-tools state update`** (not raw Edit) so the frontmatter `stopped_at` field stays in sync
 - [ ] Resume file confirmed as None (transitions don't use resume files)
 
 </step>
@@ -368,29 +394,98 @@ ls .planning/phases/*[X+1]*/*-context.md 2>/dev/null
 
 <if mode="yolo">
 
-**If context.md exists:**
+**P-1801 fix (v3.7.6):** In auto mode, **spawn the next phase as a Task subagent** — same pattern as `plan-phase.md`'s auto-advance to exec-phase. Prose-based "DO NOT exit. Read X" instructions (the v3.7.4 P-1701 attempt) were not behaviorally binding: the orchestrator returned from sub-agent calls and exited cleanly at the phase boundary. A `Task(...)` invocation is a tool call the orchestrator cannot ignore — control flow is forced into the next phase's workflow.
+
+Cost trade-off: each Task spawn restarts context (loses the cumulative cache reads from the previous phase). Acceptable because: (1) cross-phase cache value is low — phase N's plan/research is mostly irrelevant to phase N+1's executor — and (2) reliability beats marginal cost optimization for autonomous runs.
+
+**If context.md exists for the next phase:**
 
+Display:
 ```
 Phase [X] marked complete.
 
 Next: Phase [X+1] — [Name]
 
-⚡ Auto-continuing: Plan Phase [X+1] in detail
+⚡ Auto-spawning Phase [X+1] planning...
 ```
 
-Exit skill and invoke SlashCommand("/pan:plan-phase [X+1] --auto")
+Then spawn the next phase as a Task subagent — do NOT call SlashCommand or attempt in-context continuation:
 
-**If context.md does NOT exist:**
+```
+Task(
+  prompt="
+    <objective>
+    You are the plan-phase orchestrator. Plan all work for Phase ${NEXT_PHASE}: ${NEXT_PHASE_NAME}.
+    </objective>
+
+    <execution_context>
+    @~/.claude/pan-wizard-core/workflows/plan-phase.md
+    @~/.claude/pan-wizard-core/references/guardrails.md
+    @~/.claude/pan-wizard-core/references/model-profile-resolution.md
+    </execution_context>
+
+    <arguments>
+    PHASE=${NEXT_PHASE}
+    ARGUMENTS='${NEXT_PHASE} --auto'
+    </arguments>
+
+    <instructions>
+    1. Read plan-phase.md from execution_context for your complete workflow.
+    2. Follow ALL steps: initialize, validate_phase, load context.md, handle research (P-1401 bypass if applicable), spawn pan-planner, optionally spawn pan-plan-checker, then auto-advance to exec-phase via Task (per plan-phase.md step 14).
+    3. After exec-phase completes and verification passes, exec-phase will return to its own auto-advance handler which spawns transition.md — that transition will spawn Phase ${NEXT_PHASE}+1 via this same pattern, recursing until milestone-done.
+    4. Do NOT use the Skill tool or /pan: commands. Do NOT exit early — let the recursion run.
+    </instructions>
+  ",
+  subagent_type="general-purpose",
+  description="Plan Phase ${NEXT_PHASE}"
+)
+```
+
+**If context.md does NOT exist for the next phase:**
 
+Display:
 ```
 Phase [X] marked complete.
 
 Next: Phase [X+1] — [Name]
 
-⚡ Auto-continuing: Discuss Phase [X+1] first
+⚡ Auto-spawning Phase [X+1] discussion (no context.md)...
+```
+
+Then spawn discuss-phase as a Task subagent:
+
+```
+Task(
+  prompt="
+    <objective>
+    You are the discuss-phase orchestrator. Capture decisions for Phase ${NEXT_PHASE}: ${NEXT_PHASE_NAME}, then auto-advance to plan-phase.
+    </objective>
+
+    <execution_context>
+    @~/.claude/pan-wizard-core/workflows/discuss-phase.md
+    @~/.claude/pan-wizard-core/references/questioning.md
+    </execution_context>
+
+    <arguments>
+    PHASE=${NEXT_PHASE}
+    ARGUMENTS='${NEXT_PHASE} --auto'
+    </arguments>
+
+    <instructions>
+    1. Read discuss-phase.md from execution_context for your complete workflow.
+    2. In --auto mode, use sensible defaults rather than blocking on AskUserQuestion (P-1301 pattern).
+    3. After context.md is captured, auto-advance to plan-phase via Task spawn (the discuss-phase auto-advance step handles this).
+    4. Do NOT use the Skill tool or /pan: commands. Do NOT exit early.
+    </instructions>
+  ",
+  subagent_type="general-purpose",
+  description="Discuss Phase ${NEXT_PHASE}"
+)
 ```
 
-Exit skill and invoke SlashCommand("/pan:discuss-phase [X+1] --auto")
+**Handle next-phase Task return:**
+- **PHASE COMPLETE** (the spawned chain reached verification + roadmap update for ${NEXT_PHASE} and beyond, and either hit milestone-done or recursed further) → Done. Workflow chain finished.
+- **GAPS FOUND / FAILED / TIMEOUT** → Display the failure, stop the recursion, return status to user. Do NOT attempt to skip ahead.
 
 </if>
 

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

@@ -19,9 +19,23 @@ Then verify each level against the actual codebase.
 
 <required_reading>
 @~/.claude/pan-wizard-core/references/verification-patterns.md
+@~/.claude/pan-wizard-core/references/guardrails.md
 @~/.claude/pan-wizard-core/templates/verification-report.md
+
+> **Also see:** `~/.claude/pan-wizard-core/learnings/universal/` — AI-derived patterns from prior experiments. **Don't skim the whole folder.** Run `pan-tools learn topics-for --agent verifier --token-budget 5000 --raw` to load only the topics tagged relevant for verification at the configured budget. Per P-RES-002 (distractor-density research), reading every topic degrades reasoning even at modest token counts.
 </required_reading>
 
+## Re-Read Checkpoints
+
+Context compaction may have dropped earlier sections. Re-read the relevant section *before* you begin each step — not after you hit a problem.
+
+| Before this step | Re-read | Why |
+|------------------|---------|-----|
+| Running test suite | `references/guardrails.md` Stop-the-Line rule | Test regressions block phase completion — do not paper over |
+| Verifying truths/artifacts | This workflow's `<core_principle>` | Goal-backward analysis is easy to skip under time pressure |
+| Determining final status | This workflow's `<step name="determine_status">` | Status criteria (passed / gaps_found / human_needed) are precise |
+| Writing verification report | `templates/verification-report.md` | Report shape is checked downstream |
+
 <process>
 
 <step name="load_context" priority="first">

package/scripts/build-hooks.js

@@ -1,6 +1,12 @@
 #!/usr/bin/env node
 /**
- * Copy PAN hooks to dist for installation.
+ * Copy PAN hooks from hooks/ to hooks/dist/ for installation.
+ *
+ * This is COPY-ONLY. PAN's hooks are pure Node.js with zero runtime
+ * dependencies, so no bundling step is needed. The script is named
+ * "build-hooks" for npm-script convention, but the work is `cp`.
+ *
+ * (See docs/IMPROVEMENT-TODO.md P2 for the rationale.)
  */
 
 const fs = require('fs');

package/scripts/generate-skills-docs.py

@@ -232,13 +232,14 @@ def generate_full_text(shipped: list[Skill], dev: list[Skill], version: str) ->
     w("Every skill (slash command) available in PAN Wizard, reproduced in full.")
     w("This is the actual prompt text that Claude receives when a skill is invoked.")
     w("")
-    w(f"**Version:** {version} | **Shipped:** {len(shipped)} skills | **Dev:** {len(dev)} skills | **Total:** {len(shipped) + len(dev)}")
+    w(f"**Version:** {version}")
     w("")
     w("> Auto-generated by `scripts/generate-skills-docs.py` — do not edit manually.")
+    w("> For canonical counts (commands / agents / modules / etc.), see `CLAUDE.md`.")
     w("")
     w("---")
     w("")
-    w(f"## Part 1: Shipped Skills ({len(shipped)})")
+    w("## Part 1: Shipped Skills")
     w("")
     w("These are installed into host projects via the PAN installer.")
 
@@ -256,7 +257,7 @@ def generate_full_text(shipped: list[Skill], dev: list[Skill], version: str) ->
     w("")
     w("---")
     w("")
-    w(f"## Part 2: Dev Skills ({len(dev)})")
+    w("## Part 2: Dev Skills")
     w("")
     w("These exist only in the PAN source repository and are NOT shipped to end users.")
 
@@ -329,9 +330,10 @@ def generate_reference(shipped: list[Skill], dev: list[Skill], version: str) ->
     w("Complete catalog of every skill (slash command) available in PAN Wizard, organized by purpose.")
     w("Each entry shows the command, what it does, what tools it uses, and when to reach for it.")
     w("")
-    w(f"**Version:** {version} | **Total:** {len(shipped)} shipped skills + {len(dev)} dev skills = {len(shipped) + len(dev)}")
+    w(f"**Version:** {version}")
     w("")
     w("> Auto-generated by `scripts/generate-skills-docs.py` — do not edit manually.")
+    w("> For canonical counts (commands / agents / modules / etc.), see `CLAUDE.md`.")
     w("")
     w("---")
     w("")
@@ -346,11 +348,11 @@ def generate_reference(shipped: list[Skill], dev: list[Skill], version: str) ->
 
     w("## Table of Contents")
     w("")
-    w(f"- [Shipped Skills ({len(shipped)})](#shipped-skills-{len(shipped)}) — installed into host projects")
+    w("- [Shipped Skills](#shipped-skills) — installed into host projects")
     for g in ordered_groups:
         anchor = g.lower().replace(" & ", "--").replace(" ", "-")
         w(f"  - [{g}](#{anchor})")
-    w(f"- [Dev Skills ({len(dev)})](#dev-skills-{len(dev)}) — PAN source repo only")
+    w("- [Dev Skills](#dev-skills) — PAN source repo only")
     for cat in DEV_CATEGORIES:
         anchor = cat.lower().replace(" & ", "--").replace(" ", "-")
         w(f"  - [{cat}](#{anchor})")
@@ -359,7 +361,7 @@ def generate_reference(shipped: list[Skill], dev: list[Skill], version: str) ->
     w("")
 
     # ── Shipped Skills ──
-    w(f"## Shipped Skills ({len(shipped)})")
+    w("## Shipped Skills")
     w("")
     w("These are installed into host projects via the PAN installer and available to end users.")
     w("")
@@ -401,7 +403,7 @@ def generate_reference(shipped: list[Skill], dev: list[Skill], version: str) ->
         w("")
 
     # ── Dev Skills ──
-    w(f"## Dev Skills ({len(dev)})")
+    w("## Dev Skills")
     w("")
     w("These exist only in the PAN source repository (`.claude/commands/`) and are NOT shipped to end users.")
     w("")

package/scripts/release-check.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+/**
+ * release-check.js — Pre-publish validation gate.
+ *
+ * Wired into `prepublishOnly` so `npm publish` fails BEFORE upload if any
+ * gate is red. Runs five checks in order; first failure aborts.
+ *
+ *   1. build:hooks      — hook scripts copy/build cleanly
+ *   2. test:all         — full test suite (unit + scenario) passes
+ *   3. npm audit        — no known vulnerabilities in production deps
+ *                         (we have zero runtime deps, but esbuild dev-dep is checked)
+ *   4. doc-lint counts  — no drift-prone count violations in user-facing docs
+ *   5. npm pack dry-run — package builds; size is sane
+ *   6. smoke install    — npm pack + install into temp dir + run pan-tools list
+ *                         catches "ships but doesn't actually work" failures
+ *
+ * Usage:
+ *   node scripts/release-check.js              # all gates
+ *   node scripts/release-check.js --skip-audit # skip audit (use carefully)
+ *   node scripts/release-check.js --skip-smoke # skip pack+install (faster)
+ *
+ * Exit code 0 = all clear; non-zero = a gate failed (see stderr).
+ */
+
+'use strict';
+
+const { execFileSync, spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const ARGS = process.argv.slice(2);
+const SKIP_AUDIT = ARGS.includes('--skip-audit');
+const SKIP_SMOKE = ARGS.includes('--skip-smoke');
+
+const checks = [];
+let failed = false;
+
+function logGate(name, ok, detail = '') {
+  const mark = ok ? 'OK' : 'FAIL';
+  const line = `[release-check] ${mark}  ${name}${detail ? ' — ' + detail : ''}`;
+  process.stderr.write(line + '\n');
+  checks.push({ name, ok, detail });
+  if (!ok) failed = true;
+}
+
+function run(cmd, args, opts = {}) {
+  return spawnSync(cmd, args, {
+    cwd: REPO_ROOT,
+    stdio: opts.capture ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+    encoding: 'utf-8',
+    shell: process.platform === 'win32',
+    ...opts,
+  });
+}
+
+// Gate 1: build:hooks
+process.stderr.write('\n[release-check] Gate 1/6: build:hooks\n');
+{
+  const r = run('npm', ['run', 'build:hooks']);
+  logGate('build:hooks', r.status === 0, r.status !== 0 ? `exit ${r.status}` : '');
+  if (failed) process.exit(1);
+}
+
+// Gate 2: test:all
+process.stderr.write('\n[release-check] Gate 2/6: test:all\n');
+{
+  const r = run('npm', ['run', 'test:all']);
+  logGate('test:all', r.status === 0, r.status !== 0 ? `exit ${r.status}` : '');
+  if (failed) process.exit(1);
+}
+
+// Gate 3: npm audit (production deps only)
+if (SKIP_AUDIT) {
+  process.stderr.write('\n[release-check] Gate 3/6: npm audit (SKIPPED)\n');
+} else {
+  process.stderr.write('\n[release-check] Gate 3/6: npm audit --omit=dev\n');
+  const r = run('npm', ['audit', '--omit=dev', '--audit-level=high'], { capture: true });
+  // npm audit exits non-zero on findings. We tolerate moderate; fail on high+.
+  const ok = r.status === 0;
+  logGate('npm audit', ok, ok ? 'no high-severity findings' : `exit ${r.status} — high or critical CVEs in production deps`);
+  if (!ok) {
+    process.stderr.write((r.stdout || '') + '\n' + (r.stderr || '') + '\n');
+    process.exit(1);
+  }
+}
+
+// Gate 4: doc-lint counts on user-facing docs (count-SSoT enforcement)
+process.stderr.write('\n[release-check] Gate 4/6: doc-lint counts docs/\n');
+{
+  const tools = path.join(REPO_ROOT, 'pan-wizard-core', 'bin', 'pan-tools.cjs');
+  const docsDir = path.join(REPO_ROOT, 'docs');
+  const r = run('node', [tools, 'doc-lint', 'counts', docsDir, '--raw'], { capture: true });
+  const ok = r.status === 0;
+  logGate('doc-lint counts', ok, ok ? 'no count violations in docs/' : 'drift-prone counts found outside CLAUDE.md');
+  if (!ok) {
+    process.stderr.write((r.stdout || '') + '\n');
+    process.exit(1);
+  }
+}
+
+// Gate 5: npm pack dry-run
+process.stderr.write('\n[release-check] Gate 5/6: npm pack --dry-run\n');
+{
+  const r = run('npm', ['pack', '--dry-run', '--json'], { capture: true });
+  if (r.status !== 0) {
+    logGate('npm pack dry-run', false, `exit ${r.status}`);
+    process.stderr.write((r.stderr || '') + '\n');
+    process.exit(1);
+  }
+  // Parse the JSON output to check size
+  try {
+    const parsed = JSON.parse(r.stdout);
+    const entry = Array.isArray(parsed) ? parsed[0] : parsed;
+    const size = entry.size || 0;
+    const fileCount = entry.files ? entry.files.length : 0;
+    const sizeMB = (size / 1024 / 1024).toFixed(2);
+    // Flag if pack size exceeds 50MB — large for a zero-runtime-dep tool
+    const ok = size < 50 * 1024 * 1024;
+    logGate('npm pack dry-run', ok, `${sizeMB}MB, ${fileCount} files`);
+    if (!ok) process.exit(1);
+  } catch (err) {
+    logGate('npm pack dry-run', false, 'JSON parse failed: ' + err.message);
+    process.exit(1);
+  }
+}
+
+// Gate 6: smoke install — pack and install into temp dir, run pan-tools
+if (SKIP_SMOKE) {
+  process.stderr.write('\n[release-check] Gate 6/6: smoke install (SKIPPED)\n');
+} else {
+  process.stderr.write('\n[release-check] Gate 6/6: smoke install (npm pack + install + sanity)\n');
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pan-release-smoke-'));
+  try {
+    // Pack
+    const pack = run('npm', ['pack', '--pack-destination', tmpDir, '--json'], { capture: true });
+    if (pack.status !== 0) {
+      logGate('smoke install (pack)', false, `exit ${pack.status}`);
+      process.exit(1);
+    }
+    const packJson = JSON.parse(pack.stdout);
+    const tarball = path.join(tmpDir, packJson[0].filename);
+    if (!fs.existsSync(tarball)) {
+      logGate('smoke install (pack)', false, `tarball not found at ${tarball}`);
+      process.exit(1);
+    }
+    // Install into a separate fake project dir
+    const installDir = path.join(tmpDir, 'install-target');
+    fs.mkdirSync(installDir, { recursive: true });
+    fs.writeFileSync(path.join(installDir, 'package.json'), JSON.stringify({ name: 'smoke-test', version: '0.0.0' }));
+    const inst = run('npm', ['install', tarball, '--no-save', '--prefix', installDir], { capture: true });
+    if (inst.status !== 0) {
+      logGate('smoke install (install)', false, `exit ${inst.status}`);
+      process.stderr.write((inst.stderr || '') + '\n');
+      process.exit(1);
+    }
+    // Sanity: invoke pan-tools experiment list against an empty root
+    const panToolsPath = path.join(installDir, 'node_modules', 'pan-wizard', 'pan-wizard-core', 'bin', 'pan-tools.cjs');
+    if (!fs.existsSync(panToolsPath)) {
+      logGate('smoke install (sanity)', false, `pan-tools.cjs missing in installed package at ${panToolsPath}`);
+      process.exit(1);
+    }
+    // Pick a non-existent root so we exercise the read path without scaffolding anything
+    const fakeRoot = path.join(tmpDir, 'no-experiments-here');
+    const sanity = run('node', [panToolsPath, 'experiment', 'list', '--root', fakeRoot], { capture: true });
+    const ok = sanity.status === 0;
+    logGate('smoke install', ok, ok ? 'pan-tools experiment list works in installed package' : `exit ${sanity.status}`);
+    if (!ok) {
+      process.stderr.write((sanity.stderr || '') + '\n');
+      process.exit(1);
+    }
+  } finally {
+    try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { /* best-effort */ }
+  }
+}
+
+// Summary
+process.stderr.write('\n[release-check] Summary:\n');
+for (const c of checks) {
+  process.stderr.write(`  [${c.ok ? 'OK' : 'FAIL'}] ${c.name}${c.detail ? ' — ' + c.detail : ''}\n`);
+}
+process.stderr.write(`\n[release-check] ${failed ? 'FAILED' : 'PASSED'}\n`);
+process.exit(failed ? 1 : 0);