pan-wizard 3.31.0 → 3.33.0

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

@@ -222,7 +222,7 @@ In that case, log a `decision` trace event (`type: "decision", category: "skip-r
 
 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.
+**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 the planning output (context, research, plan) to a record and a plan for trivial phases; execution still writes the plan's summary. 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.
 
@@ -448,20 +448,20 @@ Task(
 
 ## 11. Handle Checker Return
 
-- **`## VERIFICATION PASSED`:** Display confirmation, proceed to step 13.
-  ```bash
-  node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace log \
-    --type decision --category plan_verified \
-    --description "Plan-checker passed for phase ${PHASE_NUMBER}" \
-    --agent pan-plan-checker --impact trivial 2>/dev/null || true
-  ```
-- **`## ISSUES FOUND`:** Display issues, check iteration count, proceed to step 12.
-  ```bash
-  node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace log \
-    --type error --category plan_checker_issues \
-    --description "Plan-checker found issues in phase ${PHASE_NUMBER} plans" \
-    --agent pan-plan-checker --impact minor 2>/dev/null || true
-  ```
+Save the checker's returned text, verbatim and in full (including its closing `pan-verdict` block), to `{phase_dir}/{padded_phase}-plan-check.md` with the Write tool. Then record it, and branch on the record. The record also adds the issues to the findings ledger and logs the check to the trace; there is no separate trace call:
+
+```bash
+CHECK_FILE="{phase_dir}/{padded_phase}-plan-check.md"
+CHECK_VERDICT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings record --phase "${PHASE_NUMBER}" --agent pan-plan-checker --file "$CHECK_FILE" --raw 2>/dev/null) \
+  || CHECK_VERDICT=$(grep -q '^## VERIFICATION PASSED' "$CHECK_FILE" && echo passed || echo issues_found)
+```
+
+The fallback reads the heading when the report carries no valid `pan-verdict` block.
+
+- **`passed`:** Display confirmation, proceed to step 13.
+- **`issues_found`:** Display issues, check iteration count, proceed to step 12.
+
+Each re-check in the revision loop overwrites the same file and is recorded again as the next attempt. The issues a revision resolved are closed by that record.
 
 ## 12. Revision Loop (Max 3 Iterations)
 
@@ -510,6 +510,11 @@ Display: `Max iterations reached. {N} issues remain:` + issue list
 
 Offer: 1) Force proceed, 2) Provide guidance and retry, 3) Abandon
 
+**On "Force proceed":** record that planning continues past the remaining issues. Execution and the milestone audit will see them as deferred, with this reason:
+```bash
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings dispose --phase "${PHASE_NUMBER}" --agent pan-plan-checker --open --as deferred --reason "force proceed after 3 plan revision iterations"
+```
+
 ## 13. Present Final Status
 
 **Sync state.md first** — without this, state.md says "Ready to plan" until the

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>
@@ -321,21 +326,11 @@ If human_needed: list items requiring human testing.
 
 Orchestrator routes: `passed` → update_roadmap | `gaps_found` → create/execute fixes, re-verify | `human_needed` → present to user.
 
-**Circular optimization — log verification outcome:**
+**Record the verification.** The record adds its findings to the ledger and logs the outcome to the trace (`verdict_passed`, `verdict_failed` or `verdict_needs_human`). A re-verification is the next attempt, and it closes the gaps it no longer reports:
 ```bash
-# Map status to impact and event type
-if [ "${STATUS}" = "passed" ]; then
-  node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace log \
-    --type decision --category verification_passed \
-    --description "Phase ${PHASE_NUMBER} verification passed (score: ${SCORE})" \
-    --agent pan-verifier --impact minor 2>/dev/null || true
-elif [ "${STATUS}" = "gaps_found" ]; then
-  node ~/.claude/pan-wizard-core/bin/pan-tools.cjs optimize trace log \
-    --type error --category verification_gaps \
-    --description "Phase ${PHASE_NUMBER} verification found gaps (score: ${SCORE})" \
-    --agent pan-verifier --impact major 2>/dev/null || true
-fi
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs findings record --phase "${PHASE_NUMBER}" --file "$REPORT_PATH" 2>/dev/null || true
 ```
+Recording the same report twice is a no-op, so exec-phase recording it again after this workflow returns is safe.
 </step>
 
 </process>

package/pan-zcode/README.md

@@ -50,7 +50,7 @@ before ADR-0028.
   preserves the body; plus a command → skill wrapper.
 - **M4 — bundle + install.** `bin/install-zcode.js` — assembles `agents/` + `pan-mcp.json` +
   manifest + `INSTALL-ZCODE.md` into a `--target` dir; refuses to write inside the source repo;
-  drives ZCode's own Import to finish.
+  leaves the finish to the human in ZCode's own Settings and Import, following `INSTALL-ZCODE.md`.
 - **M5 — hardening + docs.** Full test matrix + [`KNOWN-BETA-RISKS.md`](KNOWN-BETA-RISKS.md)
   (the beta-churn ledger + the M0 go/no-go questions).
 
@@ -59,11 +59,11 @@ Tests: `tests/pan-zcode-mcp.test.cjs`, `tests/pan-zcode-orchestration.test.cjs`,
 
 ## Still pending — M0 (needs a real ZCode install)
 
-Two go/no-go facts can only be settled empirically: **can a subagent call MCP tools?** and **are
+Among the go/no-go facts only a real install can settle (the M0 table in `KNOWN-BETA-RISKS.md`) are **can a subagent call MCP tools?** and **are
 local stdio MCP calls metered?** Both have folded-in fallbacks (see `KNOWN-BETA-RISKS.md`), so the
 design holds either way — but confirm them before relying on the richer paths.
 
-A third M0 checkpoint (added 2026-08): **which protocol era does the real ZCode client speak?**
+Another M0 checkpoint (added 2026-08, not yet in `KNOWN-BETA-RISKS.md`): **which protocol era does the real ZCode client speak?**
 The bridge is now dual-era (ADR-0041), so it answers both a legacy `initialize` handshake and a
 modern `server/discover` probe. Confirm on a real install which path ZCode takes and that the
 version it declares is in our supported list; if ZCode ever declares a revision newer than

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/git-hooks/pre-commit

@@ -10,7 +10,8 @@
 # Or with a symlink (Unix / Git Bash):
 #   ln -sf ../../scripts/git-hooks/pre-commit .git/hooks/pre-commit
 #
-# Bypass for an emergency (creates a paper trail in the commit log):
+# Bypass for an emergency (the hook only prints that the scan was skipped;
+# nothing is recorded in the commit):
 #   SKIP_GITLEAKS=1 git commit -m "..."
 #
 # Exit codes:

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) ─────────────────────────────────────────────────────────