pan-wizard 3.32.0 → 3.34.0

package/pan-wizard-core/opencode/pan-wizard.js

@@ -0,0 +1,111 @@
+'use strict';
+// PAN Wizard plugin for OpenCode (memory optimisation O12)
+//
+// OpenCode was the last host without PAN's state re-injection. It runs no command
+// hooks, but its plugins can add to the prompt it compacts a session with:
+// `experimental.session.compacting` fires before the model writes the continuation
+// summary, and strings pushed onto `output.context` go into that prompt
+// (opencode.ai/docs/plugins, read 2026-10-04). This plugin pushes PAN's position —
+// the phase in flight, the plan, where it stopped — read from the planning tree on
+// disk, so the summary carries it. The other hosts get the same block from
+// hooks/pan-state-reinject.js after compaction.
+//
+// Installed by the PAN installer as <opencode config dir>/plugins/pan-wizard.js,
+// beside the `{"type":"commonjs"}` package.json PAN writes there, so this file is
+// CommonJS and exports the plugin module shape `{ id, server }`.
+//
+// Inert unless the project is a PAN project with work in flight (a state.md naming
+// a current phase and a roadmap.md with an unticked phase). Never writes anything.
+// Fail-open: an error adds nothing and never breaks a compaction.
+//
+// planningDirName(), field() and positionLines() are copies of the same logic in
+// hooks/pan-state-reinject.js; tests/opencode-plugin.test.cjs pins the two to the
+// same output.
+
+const fs = require('fs');
+const path = require('path');
+
+function planningDirName() {
+  const raw = process.env.PAN_PLANNING_DIR || '';
+  if (raw.trim()) {
+    const rel = raw.trim().replace(/\\/g, '/');
+    const bad = rel.startsWith('/') || rel.startsWith('\\') || /^[A-Za-z]:/.test(rel)
+      || rel.split('/').includes('..');
+    if (!bad) return rel;
+  }
+  const track = (process.env.PAN_TRACK || '').trim();
+  if (track && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(track)) {
+    return `.planning/tracks/${track}`;
+  }
+  return '.planning';
+}
+
+const UNTICKED_PHASE_RE = /^- \[ \] \*\*Phase (\d+(?:\.\d+)?):/m;
+const FIELD_MAX = 240;
+const BLOCK_MAX = 2000;
+
+function field(content, name) {
+  const m = content.match(new RegExp(`\\*\\*${name}:\\*\\*[ \\t]*(.+)`, 'i'));
+  if (!m) return null;
+  const v = m[1].trim();
+  if (!v || /^\[.*\]$/.test(v) || /^none$/i.test(v)) return null;
+  return v.length > FIELD_MAX ? v.slice(0, FIELD_MAX - 1) + '…' : v;
+}
+
+/** The position lines for a planning tree, or null when nothing is in flight. */
+function positionLines(stateContent, roadmapContent) {
+  if (typeof stateContent !== 'string' || typeof roadmapContent !== 'string') return null;
+  const phase = field(stateContent, 'Current Phase');
+  if (!phase) return null;
+  const unticked = roadmapContent.match(UNTICKED_PHASE_RE);
+  if (!unticked) return null;
+  const name = field(stateContent, 'Current Phase Name');
+  const plan = field(stateContent, 'Current Plan');
+  const plans = field(stateContent, 'Total Plans in Phase');
+  const status = field(stateContent, 'Status');
+  const stoppedAt = field(stateContent, 'Stopped At');
+  const lastDesc = field(stateContent, 'Last Activity Description');
+  const resume = field(stateContent, 'Resume File');
+  const lines = [];
+  let position = `- Current phase: ${phase}${name ? ` (${name})` : ''}`;
+  if (plan) position += `, plan ${plan}${plans ? ` of ${plans}` : ''}`;
+  lines.push(position);
+  if (status) lines.push(`- Status: ${status}`);
+  if (stoppedAt) lines.push(`- Stopped at: ${stoppedAt}`);
+  else if (lastDesc) lines.push(`- Last activity: ${lastDesc}`);
+  if (resume) lines.push(`- Resume file: ${resume}`);
+  lines.push(`- First unbuilt roadmap phase: Phase ${unticked[1]}`);
+  return lines;
+}
+
+function readIfExists(p) {
+  try { return fs.readFileSync(p, 'utf8'); } catch { return null; }
+}
+
+/** The block to add to the compaction prompt for a project, or null. */
+function compactionContext(directory) {
+  const rel = planningDirName();
+  const dir = path.join(directory, ...rel.split('/'));
+  const lines = positionLines(readIfExists(path.join(dir, 'state.md')), readIfExists(path.join(dir, 'roadmap.md')));
+  if (!lines) return null;
+  const block = [
+    'PAN project state at this compaction — keep it in the summary so the work resumes where it stopped:',
+    ...lines,
+    `After compaction, re-read ${rel}/state.md and the current phase's plan before the next step: continue the work in flight rather than re-planning finished work.`,
+  ].join('\n');
+  return block.length > BLOCK_MAX ? block.slice(0, BLOCK_MAX - 1) + '…' : block;
+}
+
+async function server(ctx) {
+  const directory = (ctx && (ctx.directory || ctx.worktree)) || process.cwd();
+  return {
+    'experimental.session.compacting': async (input, output) => {
+      try {
+        const block = compactionContext(directory);
+        if (block && output && Array.isArray(output.context)) output.context.push(block);
+      } catch { /* fail open: a compaction without PAN's block beats a broken one */ }
+    },
+  };
+}
+
+module.exports = { id: 'pan-wizard', server };

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">
@@ -297,7 +299,7 @@ How to verify:
   4. Mobile (375px): Sidebar hidden, hamburger menu appears
 
 ────────────────────────────────────────────────────────
-→ YOUR ACTION: Type "approved" or describe issues
+→ Type "approved" or describe issues
 ────────────────────────────────────────────────────────
 ```
 
@@ -328,7 +330,7 @@ Options:
      Cons: More setup work, DIY security updates
 
 ────────────────────────────────────────────────────────
-→ YOUR ACTION: Select supabase, clerk, or nextauth
+→ Select: supabase / clerk / nextauth
 ────────────────────────────────────────────────────────
 ```
 
@@ -352,7 +354,7 @@ What you need to do:
 I'll verify: vercel whoami returns your account
 
 ────────────────────────────────────────────────────────
-→ YOUR ACTION: Type "done" when authenticated
+→ Type "done" when authenticated
 ────────────────────────────────────────────────────────
 ```
 </execution_protocol>

package/pan-wizard-core/references/continuation-format.md

@@ -191,7 +191,7 @@ Extract: `**Phase 2: Authentication** — JWT login flow with refresh tokens`
 
 ```markdown
 Plans:
-- [ ] 02-03: Add refresh token rotation
+- [ ] 02-03-plan.md — Add refresh token rotation
 ```
 
 Or from plan.md `<objective>`:
@@ -240,10 +240,10 @@ Sounds like an afterthought. Use "Also available:" instead.
 
 ### Don't: Fenced code blocks for commands
 
-```
+~~~
 ```
 /pan:plan-phase 3
 ```
-```
+~~~
 
 Fenced blocks inside templates create nesting ambiguity. Use inline backticks instead.

package/pan-wizard-core/references/decimal-phase-calculation.md

@@ -32,9 +32,8 @@ With existing decimals:
 ## Extract Values
 
 ```bash
-DECIMAL_INFO=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phase next-decimal "${AFTER_PHASE}")
-DECIMAL_PHASE=$(echo "$DECIMAL_INFO" | jq -r '.next')
-BASE_PHASE=$(echo "$DECIMAL_INFO" | jq -r '.base_phase')
+DECIMAL_PHASE=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs phase next-decimal "${AFTER_PHASE}" --raw)
+BASE_PHASE="${DECIMAL_PHASE%.*}"
 ```
 
 Or with --raw flag:

package/pan-wizard-core/references/design-methodology.md

@@ -2,7 +2,7 @@
 
 Single source of truth for how PAN designs a change **before** it is planned or
 executed. Cited by `pan-designer` (main flow, via `/pan:design-phase`) and by
-`focus-design` (the `/featureAI` feature pipeline). Both flows use the *same*
+`/pan:focus-design` (the feature investigation and design pipeline). Both flows use the *same*
 method at different **depth tiers** so design quality can't drift between them.
 
 This reference defines: the depth tiers, what each tier must produce, and the

package/pan-wizard-core/references/git-integration.md

@@ -13,9 +13,9 @@ The git log should read like a changelog of what shipped, not a diary of plannin
 
 | Event                   | Commit? | Why                                              |
 | ----------------------- | ------- | ------------------------------------------------ |
-| BRIEF + ROADMAP created | YES     | Project initialization                           |
-| plan.md created         | NO      | Intermediate - commit with plan completion       |
-| research.md created     | NO      | Intermediate                                     |
+| project.md + roadmap.md created | YES     | Project initialization                           |
+| plan.md created         | YES     | pan-planner: `docs({phase}): create phase plan`  |
+| research.md created     | OPTIONAL | phase researcher: `docs({phase}): research phase domain` |
 | discovery.md created    | NO      | Intermediate                                     |
 | **Task completed**      | YES     | Atomic unit of work (1 commit per task)         |
 | **Plan completed**      | YES     | Metadata commit (SUMMARY + STATE + ROADMAP)     |
@@ -40,7 +40,7 @@ If NO_GIT: Run `git init` silently. PAN projects always get their own repo.
 ```
 docs: initialize [project-name] ([N] phases)
 
-[One-liner from PROJECT.md]
+[One-liner from project.md]
 
 Phases:
 1. [phase-name]: [goal]
@@ -205,8 +205,6 @@ Each plan produces 2-4 commits (tasks + metadata). Clear, granular, bisectable.
 <anti_patterns>
 
 **Still don't commit (intermediate artifacts):**
-- plan.md creation (commit with plan completion)
-- research.md (intermediate)
 - discovery.md (intermediate)
 - Minor planning tweaks
 - "Fixed typo in roadmap"

package/pan-wizard-core/references/git-planning-commit.md

@@ -28,8 +28,8 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "" --files .planning/cod
 | execute-phase | phase | `docs(phase-03): complete authentication phase` |
 | new-milestone | milestone | `docs: start milestone v1.1` |
 | remove-phase | chore | `chore: remove phase 17 (dashboard)` |
-| insert-phase | phase | `docs: insert phase 16.1 (critical fix)` |
-| add-phase | phase | `docs: add phase 07 (settings page)` |
+| insert-phase | — | no commit (the user decides when to commit) |
+| add-phase | — | no commit |
 
 ## When to Skip
 

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

@@ -9,8 +9,8 @@ phase — context compaction may have dropped earlier sections.
 
 | Shortcut | Why it fails | Correct action |
 |----------|--------------|----------------|
-| "User's request is clear, no need to clarify" | You're guessing at intent. Phase 0 catches misunderstandings before scaffolding. | Run the Phase 0 4-question check (see `new-project.md` / `plan-phase.md`). |
-| "Phase tests passed locally, /pan:verify-phase isn't needed" | One run isn't validation. verify-phase checks state consistency, doc sync, blockers, and the full suite — not just the phase's own tests. | Always run `/pan:verify-phase` before marking a phase complete. |
+| "User's request is clear, no need to clarify" | You're guessing at intent. Phase 0 catches misunderstandings before scaffolding. | Run the Phase 0 clarification check (see `new-project.md` / `plan-phase.md`). |
+| "Phase tests passed locally, /pan:verify-phase isn't needed" | One run isn't validation. verify-phase checks the phase goal against the code (must-haves, artifacts, wiring, requirements, anti-patterns) and runs the full test suite — not just the phase's own tests. | Always run `/pan:verify-phase` before marking a phase complete. |
 | "I'll skip /pan:focus-scan and pick the next item myself" | Manual selection ignores priority/budget logic in `focus.cjs`. You'll bias toward easy items and miss higher-priority work. | Use `/pan:focus-scan` → `/pan:focus-plan` → `/pan:focus-exec`. |
 | "I'll bump the model / add a flag / refactor while I'm here" | Scope creep. The user asked for one change; surrounding cleanup belongs in a separate item. | Do only the requested change. Note unrelated cleanup as a TODO for a future focus-scan. |
 | "I'll mark this phase complete; the docs can lag behind" | Doc/state drift compounds. By the next session, the agent reads stale docs and proceeds on false assumptions. | Run the doc-sync step (update CHANGELOG/state and commit via `pan-tools commit`) before phase completion. CHANGELOG and version bumps are part of the phase, not after it. |

package/pan-wizard-core/references/handoff-decisions.md

@@ -55,7 +55,7 @@ No decisions worth documenting — plan is mechanical implementation of must_hav
 - **Open** — Choices left to the executor's judgment, but bounded.
   The planner names the decision space and the constraints; the
   executor picks within them. The executor should log which option
-  they took in the summary's `Decisions Taken`.
+  they took in the summary's `Implementation Decisions` → `Taken` bucket (DT-N).
   Example: "Hashing algorithm: bcrypt | argon2 | scrypt. Constraint:
   zero-deps Node builtin. Reason left open: equivalent for this use case."
 
@@ -74,7 +74,7 @@ No decisions worth documenting — plan is mechanical implementation of must_hav
 
 ## Schema — `## Implementation Decisions` (executor → verifier handoff)
 
-Lives in `summary.md`, after `## Files Changed`:
+Lives in `summary.md`, after `## Files Created/Modified`:
 
 ```markdown
 ## Implementation Decisions
@@ -152,5 +152,5 @@ that field default to v1.
 
 - Cognition, "Don't Build Multi-Agents" (Jun 2025): https://cognition.ai/blog/dont-build-multi-agents
 - Anthropic, "How we built our multi-agent research system": https://www.anthropic.com/engineering/multi-agent-research-system
-- Internal: `pan-wizard-core/learnings/internal/external-research.md` P-RES-003
+- Internal: P-RES-003 (PAN's source-only internal learnings)
 - Spec: this reference doc IS the spec; no separate doc.

package/pan-wizard-core/references/model-profile-resolution.md

@@ -5,7 +5,7 @@ Resolve model profile once at the start of orchestration, then use it for all Ta
 ## Resolution Pattern
 
 ```bash
-MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"'); MODEL_PROFILE=${MODEL_PROFILE:-balanced}
 ```
 
 Default: `balanced` if not set or config missing.
@@ -14,13 +14,13 @@ Default: `balanced` if not set or config missing.
 
 @~/.claude/pan-wizard-core/references/model-profiles.md
 
-Look up the agent in the table for the resolved profile. Pass the model parameter to Task calls:
+Prefer the `*_model` fields your workflow's `init` call returns, or `pan-tools resolve-model <agent> --raw`: both apply `model_overrides` and the provider mapping, which a table lookup skips. A phase's `<!-- model_tier: … -->` pin applies only when the phase is passed: `resolve-model <agent> --metadata '{"phaseNum":"N"}' --raw`. `routing.strategy: complexity` applies to any `--metadata`, and scores only its `fileCount`, `waveCount`, `requirementCount` and `isArchitectural`: metadata without them, a bare `phaseNum` included, scores as a simple task and drops the agent one tier (an agent already on the fast tier stays there). Otherwise look up the agent in the table for the resolved profile. Pass the model parameter to Task calls:
 
 ```
 Task(
   prompt="...",
   subagent_type="pan-planner",
-  model="{resolved_model}"  # "inherit", "sonnet", or "haiku"
+  model="{resolved_model}"  # "inherit" for the reasoning tier, otherwise the provider's model name ("sonnet"/"haiku" on Anthropic)
 )
 ```
 
@@ -30,5 +30,5 @@ Task(
 
 1. Resolve once at orchestration start
 2. Store the profile value
-3. Look up each agent's model from the table when spawning
-4. Pass model parameter to each Task call (values: `"inherit"`, `"sonnet"`, `"haiku"`)
+3. Take each agent's model from the init `*_model` field or `resolve-model` (the table only when neither is available)
+4. Pass that value to each Task call as is

package/pan-wizard-core/references/model-profiles.md

@@ -105,10 +105,13 @@ Use `/pan:profile <profile>` to see estimated cost differences before switching.
 Model resolution follows this priority chain:
 
 ```
-1. Per-agent override (model_overrides in config.json)     ← highest priority
-2. Per-phase override (<!-- model_tier: X --> in roadmap)
-3. Complexity routing (if strategy = "complexity")
-4. Profile lookup (MODEL_PROFILES[agent][profile])          ← lowest priority
+1. Per-agent override (model_overrides in config.json)     ← highest priority; used as-is
+2. Per-phase override (<!-- model_tier: X --> in roadmap)   ← used as-is
+3. Profile lookup (MODEL_PROFILES[agent][profile])          ← the base tier
+4. Complexity routing (if strategy = "complexity")          ← moves that tier ±1
+5. Capability hints (context_estimate / needs_thinking / cache_warm)
+6. Failure escalation (attempt > 1, capped by routing.max_escalations)
+7. Provider resolution (tier → model id)
 ```
 
 ### Provider Detection
@@ -117,8 +120,9 @@ PAN auto-detects the LLM provider to map tiers to the right model names:
 
 1. **Explicit config** — `routing.provider` in config.json (if not `"auto"`)
 2. **Environment variable** — `PAN_PROVIDER` env var
-3. **Runtime directory** — `.claude/` → Anthropic, `.codex/` → OpenAI, `.gemini/` → Google, `.opencode/` → OpenAI, `.github/` → default (first match wins)
-4. **Fallback** — Default provider map (Anthropic-style names)
+3. **OpenCode's configured model** — on an OpenCode install, the provider prefix (anthropic, openai or google) of `model` in `opencode.json` or `.opencode/opencode.json`
+4. **Runtime directory** — `.claude/` → Anthropic, `.codex/` → OpenAI, `.gemini/` → Google, `.opencode/` → OpenAI, `.github/` → default (first match wins)
+5. **Fallback** — Default provider map (Anthropic-style names)
 
 ---
 
@@ -136,7 +140,7 @@ Set in `.planning/config.json` under the `routing` section:
 }
 ```
 
-Every agent always gets the tier assigned by its profile. Predictable and simple.
+Every agent gets the tier its profile assigns, with no complexity scoring; only capability hints and failure escalation (steps 5–6 above) can still move it, when the caller passes them. Predictable and simple.
 
 ### Complexity
 
@@ -232,6 +236,7 @@ Full routing config in `.planning/config.json`:
 | `routing.cascade_quality_gate` | `true`, `false` | `true` | Reserved for future cascade routing |
 | `routing.complexity_thresholds.downgrade_max` | number | `2` | Max complexity score to downgrade tier |
 | `routing.complexity_thresholds.upgrade_min` | number | `6` | Min complexity score to upgrade tier |
+| `routing.max_escalations` | integer | `1` | How many tiers a retry may climb (failure escalation) |
 
 ---
 
@@ -243,12 +248,12 @@ Runtime: `/pan:profile <profile>`
 
 | Direction | Example | Behavior |
 |-----------|---------|----------|
-| Downgrade | quality → balanced | Confirmation required |
+| Same tier | quality → balanced | Proceeds silently (both resolve every agent to the reasoning tier) |
 | Downgrade | balanced → budget | Confirmation required |
 | Upgrade | budget → balanced | Proceeds silently |
 | Same | balanced → balanced | Proceeds silently |
 
-**Tier Order:** `quality` (3) > `balanced` (2) > `budget` (1)
+**Tier Order:** `quality` = `balanced` (2) > `budget` (1)
 
 ---
 

package/pan-wizard-core/references/phase-argument-parsing.md

@@ -19,11 +19,11 @@ PHASE_INFO=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs find-phase "${PHAS
 
 Returns JSON with:
 - `found`: true/false
-- `directory`: Full path to phase directory
+- `directory`: Phase directory, relative to the project root (e.g., ".planning/phases/06-foundation")
 - `phase_number`: Normalized number (e.g., "06", "06.1")
 - `phase_name`: Name portion (e.g., "foundation")
-- `plans`: Array of PLAN.md files
-- `summaries`: Array of SUMMARY.md files
+- `plans`: Array of plan file names (e.g., "06-01-plan.md")
+- `summaries`: Array of summary file names (e.g., "06-01-summary.md")
 
 ## Manual Normalization (Legacy)
 
@@ -33,10 +33,10 @@ Zero-pad integer phases to 2 digits. Preserve decimal suffixes.
 # Normalize phase number
 if [[ "$PHASE" =~ ^[0-9]+$ ]]; then
   # Integer: 8 → 08
-  PHASE=$(printf "%02d" "$PHASE")
+  PHASE=$(printf "%02d" "$((10#$PHASE))")
 elif [[ "$PHASE" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
   # Decimal: 2.1 → 02.1
-  PHASE=$(printf "%02d.%s" "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}")
+  PHASE=$(printf "%02d.%s" "$((10#${BASH_REMATCH[1]}))" "${BASH_REMATCH[2]}")
 fi
 ```
 
@@ -45,8 +45,8 @@ fi
 Use `roadmap get-phase` to validate phase exists:
 
 ```bash
-PHASE_CHECK=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "${PHASE}")
-if [ "$(echo "$PHASE_CHECK" | jq -r '.found')" = "false" ]; then
+PHASE_SECTION=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs roadmap get-phase "${PHASE}" --raw)   # empty when the phase is not in the roadmap
+if [ -z "$PHASE_SECTION" ]; then
   echo "ERROR: Phase ${PHASE} not found in roadmap"
   exit 1
 fi

package/pan-wizard-core/references/planning-config.md

@@ -14,7 +14,7 @@ Configuration options for `.planning/` directory behavior.
 | Option | Default | Description |
 |--------|---------|-------------|
 | `commit_docs` | `true` | Whether to commit planning artifacts to git |
-| `search_gitignored` | `false` | Add `--no-ignore` to broad rg searches |
+| `search_gitignored` | `false` | Reserved — no workflow or agent acts on it; to include `.planning/` in a broad rg search, add `--no-ignore` yourself |
 | `branching_strategy` | `"none"` | Git branching approach: `"none"`, `"phase"`, or `"milestone"` |
 | `phase_branch_template` | `"pan/phase-{phase}-{slug}"` | Branch template for phase strategy |
 | `milestone_branch_template` | `"pan/{milestone}-{slug}"` | Branch template for milestone strategy |
@@ -49,7 +49,7 @@ INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init execute-phase "1")
 # commit_docs is included in all init command outputs
 ```
 
-**Auto-detection:** If `.planning/` is gitignored, `commit_docs` is automatically `false` regardless of config.json. This prevents git errors when users have `.planning/` in `.gitignore`.
+**Gitignored planning tree:** if `.planning/` is gitignored, `pan-tools commit` and `phase complete` skip their commit (`commit` reports `reason: skipped_gitignored`, exit 0) whatever `commit_docs` says; `commit_docs` itself still reads as configured, and `/pan:health` reports the mismatch as I005.
 
 **Commit via CLI (handles checks automatically):**
 
@@ -68,8 +68,8 @@ The CLI checks `commit_docs` config and gitignore status internally — no manua
 - Direct path searches work: `rg "pattern" .planning/` finds files
 - Broad searches skip gitignored: `rg "pattern"` skips `.planning/`
 
-**When `search_gitignored: true`:**
-- Add `--no-ignore` to broad rg searches that should include `.planning/`
+**When `search_gitignored: true`:** nothing changes — no workflow or agent reads the setting.
+- To include `.planning/` in a broad rg search, add `--no-ignore` to that `rg` call yourself
 - Only needed when searching entire repo and expecting `.planning/` matches
 
 **Note:** Most PAN operations use direct file reads or explicit paths, which work regardless of gitignore status.

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

@@ -41,6 +41,15 @@ Each TDD plan implements **one feature** through the full RED-GREEN-REFACTOR cyc
 phase: XX-name
 plan: NN
 type: tdd
+wave: N
+depends_on: []
+files_modified: []
+autonomous: true
+requirements: []
+must_haves:
+  truths: []
+  artifacts: []
+  key_links: []
 ---
 
 <objective>
@@ -51,7 +60,7 @@ Output: [Working, tested feature]
 
 <context>
 @.planning/project.md
-@.planning/roadmap.md
+@.planning/phases/XX-name/{phase}-roadmap-slice.md
 @relevant/source/files.ts
 </context>
 

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/references/verification-patterns.md

@@ -316,7 +316,7 @@ grep -E "^$VAR_NAME=" .env .env.local 2>/dev/null
 **Substantive check:**
 ```bash
 # Variable has actual value (not placeholder)
-grep -E "^$VAR_NAME=.+" .env .env.local 2>/dev/null | grep -v "your-.*-here|xxx|placeholder|TODO" -i
+grep -E "^$VAR_NAME=.+" .env .env.local 2>/dev/null | grep -viE "your-.*-here|xxx|placeholder|TODO"
 
 # Value looks valid for type:
 # - URLs should start with http
@@ -336,7 +336,7 @@ NEXT_PUBLIC_API_URL=http://localhost:3000  # Still pointing to localhost in prod
 **Wiring check:**
 ```bash
 # Variable is actually used in code
-grep -r "process\.env\.$VAR_NAME|env\.$VAR_NAME" src/ --include="*.ts" --include="*.tsx"
+grep -rE "process\.env\.$VAR_NAME|env\.$VAR_NAME" src/ --include="*.ts" --include="*.tsx"
 
 # Variable is in validation schema (if using zod/etc for env)
 grep -E "$VAR_NAME" src/env.ts src/env.mjs 2>/dev/null
@@ -530,7 +530,7 @@ check_exists() {
 # 2. Check for stub patterns
 check_stubs() {
   local file="$1"
-  local stubs=$(grep -c -E "TODO|FIXME|placeholder|not implemented" "$file" 2>/dev/null || echo 0)
+  local stubs=$(grep -c -E "TODO|FIXME|placeholder|not implemented" "$file" 2>/dev/null); stubs=${stubs:-0}
   [ "$stubs" -gt 0 ] && echo "STUB_PATTERNS: $stubs in $file"
 }
 
@@ -547,7 +547,7 @@ check_substantive() {
   local min_lines="$2"
   local pattern="$3"
   local lines=$(wc -l < "$file" 2>/dev/null || echo 0)
-  local has_pattern=$(grep -c -E "$pattern" "$file" 2>/dev/null || echo 0)
+  local has_pattern=$(grep -c -E "$pattern" "$file" 2>/dev/null); has_pattern=${has_pattern:-0}
   [ "$lines" -ge "$min_lines" ] && [ "$has_pattern" -gt 0 ] && echo "SUBSTANTIVE: $file" || echo "THIN: $file ($lines lines, $has_pattern matches)"
 }
 ```
@@ -652,7 +652,7 @@ Fixture the wrong-shape case explicitly: feed the loader `[]`, `null`, `{}`, and
 
 **Implication for the agents:** `pan-plan-checker`, `pan-verifier`, `pan-reviewer`, `pan-meta-reviewer`, `pan-hardener` should each periodically audit their own prose-vs-mechanical check ratio. If a dimension is 100% prose, ask whether the role earns its compute or whether the structural reset (fresh context, forced re-reading of plan/code) is doing the real work.
 
-**Source:** `pan-wizard-core/learnings/internal/external-research.md` P-RES-006 (S2R / RLVR, ACL 2025).
+**Source:** P-RES-006 (S2R / RLVR, ACL 2025), recorded in PAN's source-only internal learnings.
 
 ---
 

package/pan-wizard-core/templates/codebase/architecture.md

@@ -8,7 +8,7 @@ Template for `.planning/codebase/architecture.md` - captures conceptual code org
 
 ## File Template
 
-```markdown
+~~~markdown
 # Architecture
 
 **Analysis Date:** [YYYY-MM-DD]
@@ -129,7 +129,7 @@ sequenceDiagram
 
 *Architecture analysis: [date]*
 *Update when major patterns change*
-```
+~~~
 
 <good_examples>
 ```markdown

package/pan-wizard-core/templates/codebase/best-practices.md

@@ -8,7 +8,7 @@ Template for `.planning/codebase/best-practices.md` - assesses coding practices
 
 ## File Template
 
-```markdown
+~~~markdown
 # Best Practices Assessment
 
 **Analysis Date:** [YYYY-MM-DD]
@@ -98,7 +98,7 @@ Top 3 improvements ranked by impact:
 
 *Best practices assessment: [date]*
 *Update after significant codebase changes*
-```
+~~~
 
 <guidelines>
 **What belongs in best-practices.md:**

package/pan-wizard-core/templates/codebase/concerns.md

@@ -8,7 +8,7 @@ Template for `.planning/codebase/concerns.md` - captures known issues and areas
 
 ## File Template
 
-```markdown
+~~~markdown
 # Codebase Concerns
 
 **Analysis Date:** [YYYY-MM-DD]
@@ -132,7 +132,7 @@ quadrantChart
 
 *Concerns audit: [date]*
 *Update as issues are fixed or new ones discovered*
-```
+~~~
 
 <good_examples>
 ```markdown
@@ -321,5 +321,5 @@ quadrantChart
 - Planning refactoring work
 
 **How this gets populated:**
-Explore agents detect these during codebase mapping. Manual additions welcome for human-discovered issues. This is living documentation, not a complaint list.
+The `pan-document_code` mapper agents detect these during codebase mapping. Manual additions welcome for human-discovered issues. This is living documentation, not a complaint list.
 </guidelines>