pan-wizard 3.32.0 → 3.33.0

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

@@ -16,13 +16,14 @@ const {
 } = require('./constants.cjs');
 const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles, fileAccessible, detectPlanningModel } = require('./utils.cjs');
 const { detectForeignPlanningTree } = require('./foreign-planning.cjs');
+const { unknownConfigKeys, nearestConfigKey } = require('./config.cjs');
 // Drift detection lives in verify-drift.cjs; re-exported below so consumers of
 // verify.cjs are unaffected by the decomposition.
 const { runDriftCheck, parseConventionRules, checkFileConventions, calculateDriftScore, getChangedFiles, cmdDriftCheck } = require('./verify-drift.cjs');
 const { collectVerificationStats, countRoadmapPhases, groupGapPatterns, cmdRetro } = require('./verify-retro.cjs');
 const { detectInstalledRuntimes, validateRuntimeInstall, cmdValidateDeployment } = require('./verify-deploy.cjs');
 const { cmdPreflight, cmdDepsValidate } = require('./verify-preflight.cjs');
-const { scopePhase, cmdVerifyScope } = require('./verify-scope.cjs');
+const { scopePhase, cmdVerifyScope, verificationFreshness, cmdVerifyStale } = require('./verify-scope.cjs');
 const { planningRootRel } = require('./planning-root.cjs');
 
 /**
@@ -116,6 +117,56 @@ function cmdVerifySummary(cwd, summaryPath, checkFileCount, raw) {
   }, raw, passed ? 'passed' : 'failed');
 }
 
+// Longer than a signature, a type or a short config snippet: an implementation body.
+const MAX_ACTION_CODE_LINES = 20;
+
+/** The line count of the longest fenced code block in a piece of markdown (0 if none). */
+function longestFencedBlock(text) {
+  let longest = 0;
+  for (const m of String(text).matchAll(/(^|\n)[ \t]*(`{3,}|~{3,})[^\n]*\n([\s\S]*?)\n[ \t]*\2[ \t]*(?=\n|$)/g)) {
+    longest = Math.max(longest, m[3].split('\n').length);
+  }
+  return longest;
+}
+
+// The elements each checkpoint type needs (references/checkpoints.md).
+const CHECKPOINT_REQUIRED = {
+  'checkpoint:human-verify': ['what-built', 'how-to-verify'],
+  'checkpoint:decision': ['decision', 'options'],
+  'checkpoint:human-action': ['action'],
+};
+
+/**
+ * Check one checkpoint task against its type's shape. A decision checkpoint may
+ * carry `auto_select="<option id>"`: the option auto mode takes. Without one, auto
+ * mode stops for a human instead of taking whichever option is listed first
+ * (market-ideas M22), and an `auto_select` naming no option is an error.
+ * @returns {{name: string, type: string, auto_select?: string|null}} the task entry
+ */
+function checkCheckpointTask(type, attrs, body, errors, warnings) {
+  const keyText = (body.match(/<(?:decision|what-built|action)>([\s\S]*?)<\/(?:decision|what-built|action)>/) || [])[1];
+  const label = keyText ? keyText.trim().replace(/\s+/g, ' ').slice(0, 80) : `unnamed ${type}`;
+  const required = CHECKPOINT_REQUIRED[type];
+  if (!required) {
+    errors.push(`Task '${label}' has unknown checkpoint type '${type}'`);
+    return { name: label, type };
+  }
+  for (const el of required) {
+    if (!body.includes(`<${el}>`)) errors.push(`Checkpoint '${label}' missing <${el}>`);
+  }
+  if (type !== 'checkpoint:decision') return { name: label, type };
+
+  const optionIds = [...body.matchAll(/<option\b[^>]*\bid=["']([^"']+)["']/g)].map(m => m[1]);
+  if (optionIds.length === 0) errors.push(`Decision checkpoint '${label}' has no <option id="...">`);
+  const autoMatch = attrs.match(/\bauto_select=["']([^"']*)["']/);
+  if (!autoMatch) {
+    warnings.push(`Decision checkpoint '${label}' has no auto_select: auto mode stops here for a human`);
+  } else if (!optionIds.includes(autoMatch[1])) {
+    errors.push(`Decision checkpoint '${label}' auto_select="${autoMatch[1]}" names no option (options: ${optionIds.join(', ') || 'none'})`);
+  }
+  return { name: label, type, auto_select: autoMatch ? autoMatch[1] : null };
+}
+
 /**
  * Validate a plan.md structure: required frontmatter, task elements, and consistency.
  * @param {string} cwd - Working directory path
@@ -139,14 +190,24 @@ function cmdVerifyPlanStructure(cwd, filePath, raw) {
     if (fm[field] === undefined) errors.push(`Missing required frontmatter field: ${field}`);
   }
 
-  // Parse XML <task> elements and validate each has required sub-elements:
-  // <name> (required), <action> (required), <verify> (recommended),
-  // <done> (recommended), <files> (recommended)
-  const taskPattern = /<task[^>]*>([\s\S]*?)<\/task>/g;
+  // Parse XML <task> elements. An auto task needs <name> and <action> and should
+  // have <verify>, <done> and <files>. A checkpoint task has its own shape
+  // (references/checkpoints.md) and is checked against that instead: until
+  // 2026-10-03 every checkpoint failed the auto-task checks, and the `<task[^>]*>`
+  // pattern also matched the `<tasks>` wrapper, so a decision's first option name
+  // was read as the task's name. `\b` keeps the wrapper out.
+  const taskPattern = /<task\b([^>]*)>([\s\S]*?)<\/task>/g;
   const tasks = [];
   let taskMatch;
   while ((taskMatch = taskPattern.exec(content)) !== null) {
-    const taskContent = taskMatch[1];
+    const attrs = taskMatch[1];
+    const taskContent = taskMatch[2];
+    const typeMatch = attrs.match(/\btype=["']?([\w:-]+)/);
+    const taskType = typeMatch ? typeMatch[1] : 'auto';
+    if (taskType.startsWith('checkpoint:')) {
+      tasks.push(checkCheckpointTask(taskType, attrs, taskContent, errors, warnings));
+      continue;
+    }
     const nameMatch = taskContent.match(/<name>([\s\S]*?)<\/name>/);
     const taskName = nameMatch ? nameMatch[1].trim() : 'unnamed';
     const hasFiles = /<files>/.test(taskContent);
@@ -156,11 +217,19 @@ function cmdVerifyPlanStructure(cwd, filePath, raw) {
 
     if (!nameMatch) errors.push('Task missing <name> element');
     if (!hasAction) errors.push(`Task '${taskName}' missing <action>`);
+    // Decisions, not code (market-ideas M32): an <action> names signatures, values,
+    // assertions and the verify command. A long fenced block there is an
+    // implementation body the planner wrote for the executor.
+    const actionText = (taskContent.match(/<action>([\s\S]*?)<\/action>/) || [])[1] || '';
+    const longest = longestFencedBlock(actionText);
+    if (longest > MAX_ACTION_CODE_LINES) {
+      warnings.push(`Task '${taskName}' embeds a ${longest}-line code block in <action>: a plan records decisions (signatures, values, assertions, the verify command), not implementation`);
+    }
     if (!hasVerify) warnings.push(`Task '${taskName}' missing <verify>`);
     if (!hasDone) warnings.push(`Task '${taskName}' missing <done>`);
     if (!hasFiles) warnings.push(`Task '${taskName}' missing <files>`);
 
-    tasks.push({ name: taskName, hasFiles, hasAction, hasVerify, hasDone });
+    tasks.push({ name: taskName, type: taskType, hasFiles, hasAction, hasVerify, hasDone });
   }
 
   if (tasks.length === 0) warnings.push('No <task> elements found');
@@ -856,6 +925,15 @@ function checkConfigFile(cwd, addIssue, repairs) {
     if (parsed.model_profile && !validProfiles.includes(parsed.model_profile)) {
       addIssue('warning', 'W004', `${CONFIG_FILE}: invalid model_profile "${parsed.model_profile}"`, `Valid values: ${validProfiles.join(', ')}`);
     }
+    // I006 (market-ideas M26): keys PAN does not read. Info, not a warning: the key
+    // may be the user's own note or meant for a newer PAN, but a typo must not pass
+    // as a setting that took effect.
+    const unknown = unknownConfigKeys(parsed);
+    if (unknown.length) {
+      const hints = unknown.map((k) => { const n = nearestConfigKey(k); return n ? `${k} → ${n}?` : k; });
+      addIssue('info', 'I006', `${CONFIG_FILE}: PAN does not read ${unknown.length === 1 ? 'this key' : 'these keys'}: ${unknown.join(', ')}`,
+        `Check the spelling (${hints.join('; ')}), or remove the key. pan-tools config-set names an unknown key when you set it.`);
+    }
   } catch (err) {
     // JSON parse failed -- config is corrupt and should be reset
     addIssue('error', 'E005', `${CONFIG_FILE}: JSON parse error - ${err.message}`, 'Run /pan:health --repair to reset to defaults', true);
@@ -1558,6 +1636,8 @@ module.exports = {
   cmdVerifyStubs,
   scopePhase,
   cmdVerifyScope,
+  verificationFreshness,
+  cmdVerifyStale,
   cmdValidateConsistency,
   cmdValidateHealth,
   cmdPreflight,

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

@@ -611,12 +611,19 @@ async function main() {
         verify.cmdVerifyStubs(cwd, { gate: args.includes('--gate') }, raw);
       } else if (subcommand === 'scope') {
         verify.cmdVerifyScope(cwd, args[2], raw);
+      } else if (subcommand === 'stale') {
+        verify.cmdVerifyStale(cwd, args[2], raw);
       } else {
-        error('Unknown verify subcommand. Available: plan-structure, phase-completeness, references, commits, artifacts, key-links, reconcile, stubs, scope');
+        error('Unknown verify subcommand. Available: plan-structure, phase-completeness, references, commits, artifacts, key-links, reconcile, stubs, scope, stale');
       }
       break;
     }
 
+    case 'version': {
+      commands.cmdVersion(cwd, { check: args.includes('--check') }, raw);
+      break;
+    }
+
     case 'generate-slug': {
       commands.cmdGenerateSlug(args[1], raw);
       break;
@@ -844,7 +851,8 @@ async function main() {
     }
 
     case 'phase-plan-index': {
-      phase.cmdPhasePlanIndex(cwd, args[1], raw);
+      const failedIdx = args.indexOf('--failed');
+      phase.cmdPhasePlanIndex(cwd, args[1], raw, { failed: failedIdx !== -1 ? args[failedIdx + 1] : null });
       break;
     }
 

package/pan-wizard-core/mcp/server.cjs

@@ -50,6 +50,15 @@ const META_SERVER_INFO_KEY = 'io.modelcontextprotocol/serverInfo';
 // claim to speak a version we don't. Newest first (the `server/discover` order).
 const SUPPORTED_VERSIONS_LIST = [MODERN_PROTOCOL_VERSION, '2025-06-18', '2025-03-26', '2024-11-05'];
 const SUPPORTED_PROTOCOL_VERSIONS = new Set(SUPPORTED_VERSIONS_LIST);
+// The `CacheableResult` fields a modern result MUST carry where its type extends
+// that interface: DiscoverResult, ListToolsResult, ListResourcesResult and
+// ReadResourceResult (schema/2026-07-28/schema.ts). Claude Code 2.1.288 drops a
+// list without them, so the server showed as connected with no tools and no
+// resources (live check H2, 2026-10-03). The registry is fixed for the life of the
+// process, so its lists are public and long-lived; a resource is the project's
+// state at the moment it is read, so a read is private and stale at once.
+const REGISTRY_CACHE = Object.freeze({ ttlMs: 3600000, cacheScope: 'public' });
+const READ_CACHE = Object.freeze({ ttlMs: 0, cacheScope: 'private' });
 /**
  * The version the server reports in `initialize` / `server/discover`. Read from the
  * package.json two levels up: the repository root in the source tree, the runtime
@@ -320,12 +329,13 @@ function createServer(opts = {}) {
         { supported: SUPPORTED_VERSIONS_LIST, requested: requestedVersion });
     }
 
-    // Modern results MUST carry a `resultType`; legacy results MUST NOT change
-    // shape (clients treat an absent resultType as "complete"). Stamp it only on
+    // Modern results MUST carry a `resultType`, a cacheable one its caching fields,
+    // and each SHOULD name the server in `_meta`; legacy results MUST NOT change
+    // shape (clients treat an absent resultType as "complete"). Stamp them only on
     // the modern path.
-    const reply = (result) => rpcResult(id,
+    const reply = (result, cache) => rpcResult(id,
       isModern && result && typeof result === 'object' && result.resultType === undefined
-        ? { resultType: 'complete', ...result }
+        ? { resultType: 'complete', ...cache, ...result, _meta: { ...result._meta, [META_SERVER_INFO_KEY]: SERVER_INFO } }
         : result);
 
     switch (method) {
@@ -339,8 +349,7 @@ function createServer(opts = {}) {
           supportedVersions: SUPPORTED_VERSIONS_LIST,
           capabilities: { tools: {}, resources: {} },
           instructions: 'PAN Wizard engine bridge: planning, verification, and orchestration tools backed by the pan-tools CLI. All tools are read-only except the gated pan_confirm_merge.',
-          ttlMs: 3600000,
-          cacheScope: 'public',
+          ...REGISTRY_CACHE,
           _meta: { [META_SERVER_INFO_KEY]: SERVER_INFO },
         });
       case 'initialize': {
@@ -354,9 +363,9 @@ function createServer(opts = {}) {
       case 'ping':
         return reply({});
       case 'tools/list':
-        return reply({ tools: reg.TOOLS.map(toMcpTool) });
+        return reply({ tools: reg.TOOLS.map(toMcpTool) }, REGISTRY_CACHE);
       case 'resources/list':
-        return reply({ resources: reg.RESOURCES.map(toMcpResource) });
+        return reply({ resources: reg.RESOURCES.map(toMcpResource) }, REGISTRY_CACHE);
       case 'tools/call': {
         const out = callTool(params && params.name, params && params.arguments);
         return out.error ? rpcError(id, out.error.code, out.error.message) : reply(out.result);
@@ -364,7 +373,7 @@ function createServer(opts = {}) {
       case 'resources/read': {
         const out = readResource(params && params.uri);
         if (out.unknown) return rpcError(id, -32602, `Unknown resource: ${params && params.uri}`);
-        return out.error ? rpcError(id, out.error.code, out.error.message) : reply(out.result);
+        return out.error ? rpcError(id, out.error.code, out.error.message) : reply(out.result, READ_CACHE);
       }
       default:
         return rpcError(id, -32601, `Method not found: ${method}`);

package/pan-wizard-core/references/checkpoints.md

@@ -8,7 +8,7 @@ Plans execute autonomously. Checkpoints formalize interaction points where human
 2. **Claude sets up the verification environment** - Start dev servers, seed databases, configure env vars
 3. **User only does what requires human judgment** - Visual checks, UX evaluation, "does this feel right?"
 4. **Secrets come from user, automation comes from Claude** - Ask for API keys, then Claude uses them via CLI
-5. **Auto-mode bypasses verification/decision checkpoints** — When `workflow.auto_advance` is true in config: human-verify auto-approves, decision auto-selects first option, human-action still stops (auth gates cannot be automated)
+5. **Auto-mode bypasses verification checkpoints, and decisions only where the planner named a default** — When `workflow.auto_advance` is true in config: human-verify auto-approves; a decision with `auto_select="<option id>"` takes that option, and a decision without it stops for a human (auto mode never takes an option because it is listed first); human-action still stops (auth gates cannot be automated)
 </overview>
 
 <checkpoint_types>
@@ -105,7 +105,7 @@ Plans execute autonomously. Checkpoints formalize interaction points where human
 
 **Structure:**
 ```xml
-<task type="checkpoint:decision" gate="blocking">
+<task type="checkpoint:decision" gate="blocking" auto_select="option-a">
   <decision>[What's being decided]</decision>
   <context>[Why this decision matters]</context>
   <options>
@@ -124,6 +124,8 @@ Plans execute autonomously. Checkpoints formalize interaction points where human
 </task>
 ```
 
+**`auto_select` (optional)** names the option auto mode takes. Set it only when the choice is safe to make without the user: reversible, no new paid service, no credential, no data-model lock-in. It must name an `id` from this checkpoint's options; `verify plan-structure` fails one that names no option. Leave it out when a human must choose, and auto mode stops at this checkpoint. The examples below omit it: picking a vendor or a database is the user's call.
+
 **Example: Auth Provider Selection**
 ```xml
 <task type="checkpoint:decision" gate="blocking">

package/pan-wizard-core/references/verdict-contract.md

@@ -26,6 +26,7 @@ A judging agent ends its report with one fenced `pan-verdict` block. The block i
 | `verdict` | yes | your own verdict word (table below) |
 | `outcome` | yes | `pass`, `fail` or `needs_human` |
 | `findings` | yes (may be empty) | a list of `{class, severity, where, summary}` |
+| `not_checked` | when a check could not run | a list of `{check, reason}`: a check you were asked to make and could not run, and why (no test script, no browser, a file you could not read). Never fold it into `pass`: a verdict with entries here says what it did not see |
 
 | Agent | `verdict` → `outcome` |
 |---|---|
@@ -33,7 +34,7 @@ A judging agent ends its report with one fenced `pan-verdict` block. The block i
 | pan-reviewer | `PASS` → `pass` · `PASS_WITH_WARNINGS` → `pass` · `NEEDS_FIXES` → `fail` |
 | pan-design-checker | `PASS` → `pass` · `GAPS` → `fail` |
 
-The verifier does not emit this block. Its verification.md frontmatter (`status`, `gaps`, `human_verification`, `unrequested`) is its machine contract, and the recorder reads that directly.
+The verifier does not emit this block. Its verification.md frontmatter (`status`, `gaps`, `human_verification`, `unrequested`, `test_gate`, `not_checked`) is its machine contract, and the recorder reads that directly. `test_gate` is `passed`, `failed` or `skipped`. A skipped gate is recorded as a `tests` entry in `not_checked` even when the list leaves it out, and a verification that does not record `test_gate` at all is recorded with a `test_gate_unrecorded` warning.
 
 ## `class`: what kind of finding
 

package/pan-wizard-core/templates/discovery.md

@@ -30,7 +30,7 @@ Discover [topic] to inform [phase name] implementation.
 
 Purpose: [What decision/implementation this enables]
 Scope: [Boundaries]
-Output: DISCOVERY.md with recommendation
+Output: discovery.md with recommendation
 </discovery_objective>
 
 <discovery_scope>

package/pan-wizard-core/templates/phase-prompt.md

@@ -79,7 +79,8 @@ Output: [What artifacts will be created]
 <!-- For checkpoint task examples and patterns, see @~/.claude/pan-wizard-core/references/checkpoints.md -->
 <!-- Key rule: Claude starts dev server BEFORE human-verify checkpoints. User only visits URLs. -->
 
-<task type="checkpoint:decision" gate="blocking">
+<task type="checkpoint:decision" gate="blocking" auto_select="option-a">
+  <!-- auto_select: the option auto mode takes. Omit it when a human must choose. -->
   <decision>[What needs deciding]</decision>
   <context>[Why this decision matters]</context>
   <options>

package/pan-wizard-core/templates/verification-report.md

@@ -10,8 +10,13 @@ Template for `.planning/phases/XX-name/{phase_num}-verification.md` — phase go
 ---
 phase: XX-name
 verified: YYYY-MM-DDTHH:MM:SSZ
+verified_commit: <sha> # git rev-parse HEAD before writing this file; `pan-tools verify stale` compares against it
 status: passed | gaps_found | human_needed
 score: N/M must-haves verified
+test_gate: passed | failed | skipped
+not_checked: # Only for checks that could not run, with why — a skipped test gate is one
+  - check: "tests"
+    reason: "no test script in package.json"
 unrequested: # Only when the scope check (`pan-tools verify scope <phase>`) found work no plan asked for
   - path: "src/admin/panel.tsx"
     what: "An admin panel no plan or requirement asked for"

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

@@ -256,7 +256,11 @@ Execute each wave in sequence. Within a wave: parallel if `PARALLELIZATION=true`
 
    **Known Claude Code bug (classifyHandoffIfNeeded):** If an agent reports "failed" with error containing `classifyHandoffIfNeeded is not defined`, this is a Claude Code runtime bug — not a PAN or agent issue. The error fires in the completion handler AFTER all tool calls finish. In this case: run the same spot-checks as step 4 (summary.md exists, git commits present, no Self-Check: FAILED). If spot-checks PASS → treat as **successful**. If spot-checks FAIL → treat as real failure below.
 
-   For real failures: report which plan failed → ask "Continue?" or "Stop?" → if continue, dependent plans may also fail. If stop, partial completion report.
+   For real failures: report which plan failed → ask "Continue?" or "Stop?". If stop, partial completion report. If continue, never run a plan that depends on a failed one; ask the engine which plans are blocked:
+   ```bash
+   BLOCKED=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phase-plan-index "${PHASE_NUMBER}" --failed "${FAILED_PLAN_IDS}")
+   ```
+   `${FAILED_PLAN_IDS}` is the comma-separated ids of every plan that failed so far. `blocked` lists each unfinished plan whose `depends_on` reaches a failed plan, directly or through another blocked plan, with the failed plans behind it. Do not spawn those plans in this or any later wave. Name them in the wave report and the final summary ("Skipped 03-03 and 03-04: they depend on 03-01, which failed"), and run every other plan as planned. The same applies after "Continue with remaining waves?" in step 4.
 
 6. **Execute checkpoint plans between waves** — see `<checkpoint_handling>`.
 
@@ -275,7 +279,7 @@ AUTO_CFG=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs config-get workflow.
 
 When executor returns a checkpoint AND `AUTO_CFG` is `"true"`:
 - **human-verify** → Auto-spawn continuation agent with `{user_response}` = `"approved"`. Log `⚡ Auto-approved checkpoint`.
-- **decision** → Auto-spawn continuation agent with `{user_response}` = first option from checkpoint details. Log `⚡ Auto-selected: [option]`.
+- **decision** → The executor already took the plan's `auto_select` option when the task had one, so a decision that comes back has none: present it to the user (standard flow below). If a returned decision's task does carry `auto_select` in the plan file, auto-spawn the continuation agent with `{user_response}` = that option id and log `⚡ Auto-selected: [option] (auto_select)`. Never answer with an option because it is listed first.
 - **human-action** → Present to user (existing behavior below). Auth gates cannot be automated.
 
 **Standard flow (not auto-mode, or human-action type):**
@@ -567,6 +571,7 @@ Phase goal: {goal from roadmap.md}
 Phase requirement IDs: {phase_req_ids}
 Check must_haves against actual codebase.
 Cross-reference requirement IDs from PLAN frontmatter against requirements.md — every ID MUST be accounted for.
+Run the project's test suite as the test gate (the run_test_suite step of @~/.claude/pan-wizard-core/workflows/verify-phase.md) and record test_gate in the frontmatter.
 Create verification.md.",
   subagent_type="pan-verifier",
   model="{verifier_model}"
@@ -585,7 +590,7 @@ VERIF_STATUS=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings record
 
 | Status | Action |
 |--------|--------|
-| `passed` | → update_roadmap |
+| `passed` | → update_roadmap. If the verification frontmatter has `test_gate: skipped` or a `not_checked` list, say so when you report the phase: "passed — not checked: tests (no test script)". A pass never hides what it did not check |
 | `human_needed` | Present items for human testing, get approval or feedback |
 | `gaps_found` | Present gap summary, offer `/pan:plan-phase {phase} --gaps` |
 

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

@@ -165,6 +165,7 @@ Report final status.
 | I003 | info | Focus-model or campaign tree — the phase-model checks do not apply | No |
 | I004 | info | planning-with-files shares the tree — PAN leaves its files alone | No |
 | I005 | info | The planning tree is gitignored while commit_docs is true — planning commits commit nothing | No |
+| I006 | info | config.json holds keys PAN does not read (usually a typo); the fix names the nearest known key | No |
 | STATE_REQ_DRIFT | warning | state.md complete but REQUIREMENTS.md has unchecked boxes | Yes |
 | STATE_ROADMAP_DRIFT | warning | state.md complete but roadmap.md has unchecked plan boxes | Yes |
 | VERIFICATION_GATE_MISSING | warning | Phase has completed plans but no verification record | No |

package/pan-wizard-core/workflows/new-project.md

@@ -985,7 +985,7 @@ Use AskUserQuestion:
   - .planning/roadmap.md (Current roadmap to revise)
   </files_to_read>
 
-  Update the roadmap based on feedback. Edit files in place.
+  Update the roadmap based on feedback: rewrite each changed file with one Write.
   Return ROADMAP REVISED with changes made.
   </revision>
   ", subagent_type="pan-roadmapper", model="{roadmapper_model}", description="Revise roadmap")

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

@@ -46,7 +46,7 @@ If `$FULL_MODE`:
 INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init quick "$DESCRIPTION")
 ```
 
-Parse JSON for: `planner_model`, `executor_model`, `checker_model`, `verifier_model`, `commit_docs`, `next_num`, `slug`, `date`, `timestamp`, `quick_dir`, `task_dir`, `roadmap_exists`, `planning_exists`.
+Parse JSON for: `planner_model`, `executor_model`, `checker_model`, `verifier_model`, `commit_docs`, `next_num`, `slug`, `description_cell`, `date`, `timestamp`, `quick_dir`, `task_dir`, `roadmap_exists`, `planning_exists`.
 
 **If `roadmap_exists` is false:** Error — Quick mode requires an active project with roadmap.md. Run `/pan:new-project` first.
 
@@ -365,23 +365,23 @@ Insert after `### Blockers/Concerns` section:
 
 **7c. Append new row to table:**
 
-Use `date` from init:
+Use `date` and `description_cell` from init. Write `description_cell` exactly as init returned it, never `$DESCRIPTION`: init escapes `|` and folds line breaks, and a raw `|` in a description would split the row into an extra column and break the table for every later read.
 
 **If `$FULL_MODE` (or table has Status column):**
 ```markdown
-| ${next_num} | ${DESCRIPTION} | ${date} | ${commit_hash} | ${VERIFICATION_STATUS} | [${next_num}-${slug}](./quick/${next_num}-${slug}/) |
+| ${next_num} | ${description_cell} | ${date} | ${commit_hash} | ${VERIFICATION_STATUS} | [${next_num}-${slug}](./quick/${next_num}-${slug}/) |
 ```
 
 **If NOT `$FULL_MODE` (and table has no Status column):**
 ```markdown
-| ${next_num} | ${DESCRIPTION} | ${date} | ${commit_hash} | [${next_num}-${slug}](./quick/${next_num}-${slug}/) |
+| ${next_num} | ${description_cell} | ${date} | ${commit_hash} | [${next_num}-${slug}](./quick/${next_num}-${slug}/) |
 ```
 
 **7d. Update "Last activity" line:**
 
-Use `date` from init:
+Use `date` and `description_cell` from init (one line, whatever the description held):
 ```
-Last activity: ${date} - Completed quick task ${next_num}: ${DESCRIPTION}
+Last activity: ${date} - Completed quick task ${next_num}: ${description_cell}
 ```
 
 Use Edit tool to make these changes atomically

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

@@ -136,6 +136,10 @@ TEST_TOTAL: ${TEST_COUNT}
 TEST_PASSED: ${TEST_PASS}
 TEST_FAILED: ${TEST_FAIL}
 ```
+   Write `test_gate: ${TEST_GATE_STATUS}` into the verification.md frontmatter. When it is
+   `skipped`, also add a `not_checked` entry (`check: "tests"`, `reason: "no test script in
+   package.json"`). The recorder reads both: a pass whose tests never ran is recorded as a
+   pass with tests not checked, never as a plain pass.
 
 **If test gate FAILED:** Continue verification (gather full picture) but set overall status to `gaps_found` regardless of goal-backward results. Include test failures as gaps in the report.
 </step>
@@ -284,7 +288,7 @@ Format each as: Test Name → What to do → Expected result → Why can't verif
 </step>
 
 <step name="determine_status">
-**passed:** All truths VERIFIED, all artifacts pass levels 1-3, all key links WIRED, no blocker anti-patterns, AND test gate passed or skipped.
+**passed:** All truths VERIFIED, all artifacts pass levels 1-3, all key links WIRED, no blocker anti-patterns, AND test gate passed or skipped. A skipped gate is listed in `not_checked` with its reason, and the report to the user says the tests did not run.
 
 **gaps_found:** Any truth FAILED, artifact MISSING/STUB, key link NOT_WIRED, blocker found, OR test gate FAILED (test regressions detected).
 
@@ -306,9 +310,10 @@ If gaps_found:
 <step name="create_report">
 ```bash
 REPORT_PATH="$PHASE_DIR/${PHASE_NUM}-verification.md"
+VERIFIED_COMMIT=$(git rev-parse HEAD 2>/dev/null)
 ```
 
-Fill template sections: frontmatter (phase/timestamp/status/score), **test gate results** (status/total/passed/failed), goal achievement, artifact table, wiring table, requirements coverage, anti-patterns, human verification, gaps summary, fix plans (if gaps_found), metadata.
+Fill template sections: frontmatter (phase/timestamp/`verified_commit: ${VERIFIED_COMMIT}`/status/score/`test_gate`), **test gate results** (status/total/passed/failed), goal achievement, artifact table, wiring table, requirements coverage, anti-patterns, human verification, gaps summary, fix plans (if gaps_found), metadata.
 
 See ~/.claude/pan-wizard-core/templates/verification-report.md for complete template.
 </step>

package/scripts/build-agent-plugin.js

@@ -5,7 +5,9 @@
  *
  *   plugin.json                   closed-schema manifest ($schema + name + metadata)
  *   skills/pan-<name>/SKILL.md    every PAN command as an Agent Skill, from the
- *                                 ONE unified-skills compiler (ADR-0028)
+ *                                 ONE unified-skills compiler (ADR-0028); a skill
+ *                                 over Codex's 8,000-byte plugin cut is a pointer
+ *                                 page plus references/instructions.md (S8)
  *   mcp.json                      the bundled bridge, launched as
  *                                 `node ${PLUGIN_ROOT}/pan-wizard-core/mcp/server.cjs`
  *   pan-wizard-core/              dispatcher + modules + workflows + templates +
@@ -74,9 +76,14 @@ function assertSafeToReplace(dir) {
   throw new Error(`build-agent-plugin: refusing to replace ${dir} — it is non-empty and does not look like a previous bundle build (no Agent Plugins plugin.json)`);
 }
 
-/** commands/pan/**.md → skills/pan-<name>/SKILL.md, mirroring the installer's recursion. */
+/**
+ * commands/pan/**.md → skills/pan-<name>/SKILL.md, mirroring the installer's recursion.
+ * A skill longer than Codex loads from a plugin (8,000 bytes) is split: a pointer
+ * SKILL.md plus references/instructions.md (lib.splitOversizedSkill, market-ideas S8).
+ */
 function emitSkills(srcDir, skillsDir, prefix) {
   let count = 0;
+  let split = 0;
   (function recurse(currentSrc, currentPrefix) {
     for (const entry of fs.readdirSync(currentSrc, { withFileTypes: true })) {
       const srcPath = path.join(currentSrc, entry.name);
@@ -88,11 +95,18 @@ function emitSkills(srcDir, skillsDir, prefix) {
       let content = fs.readFileSync(srcPath, 'utf8');
       content = lib.rewriteUnifiedSkillCommandContent(content, REWRITE);
       content = lib.convertClaudeCommandToUnifiedSkill(content, skillName, { adapterNote: lib.agentPluginSkillAdapterNote() });
-      fs.writeFileSync(path.join(skillDir, 'SKILL.md'), content);
+      const { skill, reference } = lib.splitOversizedSkill(content, skillName);
+      fs.writeFileSync(path.join(skillDir, 'SKILL.md'), skill);
+      if (reference) {
+        const refPath = path.join(skillDir, ...lib.AGENT_PLUGIN_SKILL_REFERENCE.split('/'));
+        fs.mkdirSync(path.dirname(refPath), { recursive: true });
+        fs.writeFileSync(refPath, reference);
+        split++;
+      }
       count++;
     }
   })(srcDir, prefix);
-  return count;
+  return { count, split };
 }
 
 /** pan-wizard-core → bundle, markdown rewritten, everything else verbatim. */
@@ -214,7 +228,7 @@ function main() {
   const copilotAgents = emitCopilotNamespace(path.join(ROOT, 'agents'), path.join(OUT, lib.COPILOT_PLUGIN_NAMESPACE));
 
   console.log('PAN Agent Plugins bundle built at', path.relative(ROOT, OUT) || OUT);
-  console.log('  skills:', skills);
+  console.log('  skills:', skills.count, `(${skills.split} as a short SKILL.md + ${lib.AGENT_PLUGIN_SKILL_REFERENCE})`);
   console.log('  agent reference copies:', agents);
   console.log('  hook scripts:', hookScripts.length);
   console.log(`  ${lib.COPILOT_PLUGIN_NAMESPACE}/agents:`, copilotAgents);

package/scripts/test-surface.cjs

@@ -69,6 +69,10 @@ const EVENT_HOOKS = Object.freeze({
   subagentStop: ['pan-cost-logger.js', 'pan-trace-logger.js'],
   stop: ['pan-stop-guard.js'],
   compact: ['pan-state-reinject.js'],
+  // Gemini and Copilot (market-ideas M33): the marker before a compaction, and the
+  // block on the next tool result — the same script in two modes.
+  compactMark: ['pan-state-reinject.js'],
+  compactInject: ['pan-state-reinject.js'],
 });
 
 // ─── Parsers (pure) ─────────────────────────────────────────────────────────