pan-wizard 3.33.0 → 3.35.0

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

@@ -0,0 +1,139 @@
+'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,
+// below the `{"type":"commonjs"}` package.json PAN writes in the config dir, so this file is
+// CommonJS and exports one object both loaders accept: `{ id, server, setup }`
+// (OpenCode 1 calls server(), OpenCode 2 calls setup()).
+//
+// 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;
+}
+
+function directoryOf(ctx) {
+  return (ctx && (ctx.directory || ctx.worktree)) || process.cwd();
+}
+
+/** Push PAN's block onto the first array target; fail-open, inert outside work in flight. */
+function pushBlock(directory, target) {
+  try {
+    if (!Array.isArray(target)) return;
+    const block = compactionContext(directory);
+    if (block) target.push(block);
+  } catch { /* fail open: a compaction without PAN's block beats a broken one */ }
+}
+
+// OpenCode 1: the loader calls server() and reads its hook map.
+async function server(ctx) {
+  const directory = directoryOf(ctx);
+  return {
+    'experimental.session.compacting': async (input, output) => {
+      pushBlock(directory, output && output.context);
+    },
+  };
+}
+
+// OpenCode 2: the loader requires `setup` (or `effect`) and hooks register through
+// `ctx.session.hook(name, fn)` (opencode.ai/v2/docs/build/plugins, migrate-v1). The
+// compaction event's prompt parts are `system` (read from the 2.0 binary); `context`
+// is the documented v1 name and the fallback.
+function setup(ctx) {
+  try {
+    const directory = directoryOf(ctx);
+    const session = ctx && ctx.session;
+    if (!session || typeof session.hook !== 'function') return;
+    session.hook('compaction', async (event) => {
+      if (!event) return;
+      pushBlock(directory, Array.isArray(event.system) ? event.system : event.context);
+    });
+  } catch { /* fail open: a plugin that cannot register leaves the session as it was */ }
+}
+
+module.exports = { id: 'pan-wizard', server, setup };

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

@@ -299,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
 ────────────────────────────────────────────────────────
 ```
 
@@ -330,7 +330,7 @@ Options:
      Cons: More setup work, DIY security updates
 
 ────────────────────────────────────────────────────────
-→ YOUR ACTION: Select supabase, clerk, or nextauth
+→ Select: supabase / clerk / nextauth
 ────────────────────────────────────────────────────────
 ```
 
@@ -354,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

@@ -34,7 +34,7 @@ PAN never selects your host model — it recommends a *class*. Because the `reas
 
 The IDs below are *examples* of what you can configure in each class — not an exhaustive or only-valid list. A newer release in the same class behaves the same way here.
 
-At install time PAN also runs a **best-effort, advisory** capability check on the model ID you have configured (`detectModelCapabilities` in `bin/install-lib.cjs`). It recognizes the current Claude generations by name, and its forward threshold per family is the last reduced-capability release it records rather than the newest release it lists: any Claude ID newer than that boundary — a new major, or a later point release inside a major it already lists — inherits that family's modern profile instead of reporting no capabilities at all. "That family's profile" is the point: a newer Haiku inherits Haiku's, which is not a 1M-context/thinking profile. An ID resolves either by matching an explicit branch in the table or — for Claude names — by carrying a family plus a readable release number strictly newer than that family's last reduced-capability release; anything that resolves neither way reads as `tier: 'unknown'` with every capability flag false. It is a name-matching heuristic, not a live probe of the model, so it can still be imprecise about something released after this table — read it as a hint, not a contract. Either way it decides one thing only: whether the installer prints a capability *warning*. No routing, mode-selection, or feature gate in PAN reads it, so a wrong guess costs you a misleading install-time line and nothing else.
+At install time PAN also runs a **best-effort, advisory** capability check on the model ID you have configured (`detectModelCapabilities` in `bin/install-lib.cjs`). It recognizes the current Claude generations by name, and its forward threshold per family is the last reduced-capability release it records rather than the newest release it lists: any Claude ID newer than that boundary — a new major, or a later point release inside a major it already lists — inherits that family's modern profile instead of reporting no capabilities at all. "That family's profile" is the point: a newer Haiku inherits the newest Haiku profile the table records (1M context and thinking, at the fast tier), not Opus's. An ID resolves either by matching an explicit branch in the table or — for Claude names — by carrying a family plus a readable release number strictly newer than that family's last reduced-capability release; anything that resolves neither way reads as `tier: 'unknown'` with every capability flag false. It is a name-matching heuristic, not a live probe of the model, so it can still be imprecise about something released after this table — read it as a hint, not a contract. Either way it decides one thing only: whether the installer prints a capability *warning*. No routing, mode-selection, or feature gate in PAN reads it, so a wrong guess costs you a misleading install-time line and nothing else.
 
 | Class | Example model IDs | Role in PAN | Context | Relative cost | Notes |
 |-------|-------------------|-------------|---------|---------------|-------|
@@ -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 |
@@ -42,14 +42,14 @@ node ~/.claude/pan-wizard-core/bin/pan-tools.cjs commit "docs: update state" --f
 
 # Load config via state load (returns JSON):
 INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state load)
-# commit_docs is available in the JSON output
+# commit_docs is at .config.commit_docs in the JSON output
 
 # Or use init commands which include commit_docs:
 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.
@@ -147,7 +147,7 @@ INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs init execute-phase "1")
 Or use `state load` for the config values:
 ```bash
 INIT=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs state load)
-# Parse branching_strategy, phase_branch_template, milestone_branch_template from JSON
+# Parse .config.branching_strategy, .config.phase_branch_template, .config.milestone_branch_template from JSON
 ```
 
 **Branch creation:**
@@ -168,7 +168,7 @@ if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
 fi
 ```
 
-**Merge options at milestone-done:**
+**Merge options after milestone-done (it does not merge — run one yourself):**
 
 | Option | Git command | Result |
 |--------|-------------|--------|

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}` |
+| `resolutions` | on a re-check | a list of `{id, status, evidence}` answering each earlier open finding you were given in `<open_findings>`: `status` is `resolved` (with `evidence`: what you checked and saw), `still_present` or `cannot_tell`. A finding you leave out stays open, and `resolved` without evidence is recorded as `cannot_tell` |
 | `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` |
@@ -36,6 +37,10 @@ A judging agent ends its report with one fenced `pan-verdict` block. The block i
 
 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.
 
+**Findings close on evidence, never on silence.** An earlier finding closes only when the judge answers it `resolved` with evidence (a `resolutions` entry, or a truth in the verifier's `re_verification.gaps_closed`), or, for a `code-fact:` finding, when that fact passes. A finding the new report neither repeats nor answers stays open and is listed as `unaddressed`. A reworded report of an earlier finding (same class family, where `missing` and `partial` count as one; same file; same truth or a similar summary) keeps the earlier id.
+
+**Code facts only lower a verdict (two-key verdict).** A fact the engine measures can turn a judge's `pass` or `needs_human` into a fail, never the reverse. `test_gate: failed` under `status: passed` records as `gaps_found`: the record keeps the judge's own word as `agent_verdict`, names the fact in `lowered_by`, and adds a high finding at `code-fact:test_gate` for the gap round to close. `findings record --raw` prints the lowered word, so the workflow routes to gap closure.
+
 ## `class`: what kind of finding
 
 | Class | Use when |
@@ -67,7 +72,7 @@ The verifier does not emit this block. Its verification.md frontmatter (`status`
 - `where`: `NN-MM-plan.md` or `NN-MM-plan.md#task-N`.
 
 **pan-reviewer.**
-- Classes by category: Convention → `quality`, Security → `risk`, Code Quality → `defect`, work no plan asked for → `unrequested`.
+- Classes by category: Convention → `quality`, Security → `risk`, Code Quality → `defect`, Design smell → `quality`, work no plan asked for → `unrequested`.
 - Severity: ERROR → `high`, WARNING → `medium`, INFO → `info`.
 - `where`: `path:line`.
 

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:**