pan-wizard 3.26.0 → 3.28.0

package/bin/install.js

@@ -46,7 +46,7 @@ const pkg = require('../package.json');
 // phrased by capability, not by name; these are the "switch to this" examples
 // that keep the advice actionable. Nothing in PAN gates on these values.
 const RECOMMENDED_MODELS = {
-  flagship: 'claude-fable-5',
+  flagship: 'claude-fable-5-1',
   reasoningTier: 'claude-opus-5 / claude-opus-4-8',
 };
 
@@ -565,21 +565,15 @@ function copyCommandsAsUnifiedSkills(srcDir, skillsDir, prefix, pathPrefix, core
       fs.mkdirSync(skillDir, { recursive: true });
 
       let content = fs.readFileSync(srcPath, 'utf8');
-      // Core + agent-definition references → shared .agents/ copies (specific,
-      // before the generic rewrites); everything else .claude-scoped → the
-      // installing runtime. Agent refs point at the canonical reference copies
-      // shipped with the shared core — the runtime's own agents dir may carry
-      // a different format (Codex TOML, Copilot .agent.md).
-      content = content.replace(/~\/\.claude\/pan-wizard-core\//g, `${corePrefix}pan-wizard-core/`);
-      content = content.replace(/\.\/\.claude\/pan-wizard-core\//g, `${corePrefix}pan-wizard-core/`);
-      content = content.replace(/~\/\.claude\/agents\//g, `${corePrefix}pan-wizard-core/agents/`);
-      content = content.replace(/\.\/\.claude\/agents\//g, `${corePrefix}pan-wizard-core/agents/`);
-      content = content.replace(/~\/\.claude\//g, pathPrefix);
-      content = content.replace(/\.\/\.claude\//g, `./${getDirName(runtime)}/`);
-      // Not every runtime puts a `pan-tools` bin on PATH — invoke via node.
-      const panToolsPath = `${corePrefix}pan-wizard-core/bin/pan-tools.cjs`;
-      content = content.replace(/\bpan-tools\b(?=\s+[a-z])/g, `node ${panToolsPath}`);
-      content = processAttribution(content, getCommitAttribution(runtime));
+      // The path rewrite lives in install-lib (rewriteUnifiedSkillCommandContent)
+      // because the Agent Plugins bundle builder runs the SAME function — one
+      // converter, several call sites, never a second copy (ADR-0028, ADR-0045).
+      content = lib.rewriteUnifiedSkillCommandContent(content, {
+        corePrefix,
+        pathPrefix,
+        projectDirPrefix: `./${getDirName(runtime)}/`,
+        attribution: getCommitAttribution(runtime),
+      });
       content = convertClaudeCommandToUnifiedSkill(content, skillName);
 
       fs.writeFileSync(path.join(skillDir, 'SKILL.md'), content);
@@ -670,17 +664,14 @@ function copySharedCore(srcDir, destDir, corePrefix, runtimePathPrefix, runtime)
         recurse(srcPath, destPath);
       } else if (entry.name.endsWith('.md')) {
         try {
-          let content = fs.readFileSync(srcPath, 'utf8');
-          content = content.replace(/~\/\.claude\/pan-wizard-core\//g, `${corePrefix}pan-wizard-core/`);
-          content = content.replace(/\.\/\.claude\/pan-wizard-core\//g, `${corePrefix}pan-wizard-core/`);
-          // Agent-definition refs → the canonical reference copies in the
-          // shared core (runtime agents dirs carry runtime-specific formats).
-          content = content.replace(/~\/\.claude\/agents\//g, `${corePrefix}pan-wizard-core/agents/`);
-          content = content.replace(/\.\/\.claude\/agents\//g, `${corePrefix}pan-wizard-core/agents/`);
-          content = content.replace(/~\/\.claude\//g, runtimePathPrefix);
-          content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
-          content = processAttribution(content, getCommitAttribution(runtime));
-          content = convertSlashCommandsToCopilotSkillMentions(content);
+          // Shared with the Agent Plugins bundle builder (install-lib) — see
+          // rewriteSharedCoreMarkdown for the rewrite order and rationale.
+          const content = lib.rewriteSharedCoreMarkdown(fs.readFileSync(srcPath, 'utf8'), {
+            corePrefix,
+            pathPrefix: runtimePathPrefix,
+            projectDirPrefix: `./${dirName}/`,
+            attribution: getCommitAttribution(runtime),
+          });
           fs.writeFileSync(destPath, content);
         } catch (err) {
           pushInstallWarning('copySharedCore(md)', destPath, err);
@@ -728,21 +719,13 @@ function stripInternalFromLearningsIndex(indexPath) {
     if (err.code !== 'ENOENT') pushInstallWarning('stripInternalLearnings', 'learnings/index.json', err);
     return;
   }
-  if (!parsed || !Array.isArray(parsed.topics)) return;
-
-  const kept = parsed.topics.filter(t => t && t.scope !== 'internal');
-  if (kept.length === parsed.topics.length) return; // nothing internal to drop
-
-  parsed.topics = kept;
-  if (parsed.totals && typeof parsed.totals === 'object') {
-    parsed.totals.topics = kept.length;
-    parsed.totals.patterns = kept.reduce((n, t) => n + (Array.isArray(t.patterns) ? t.patterns.length : 0), 0);
-    parsed.totals.size_bytes = kept.reduce((n, t) => n + (t.size_bytes || 0), 0);
-    parsed.totals.size_tokens_est = kept.reduce((n, t) => n + (t.size_tokens_est || 0), 0);
-  }
+  // The transform is pure and shared with the bundle builders (install-lib):
+  // null means "not an index" or "nothing internal to drop" — both no-ops here.
+  const stripped = lib.stripInternalLearningsTopics(parsed);
+  if (!stripped) return;
 
   try {
-    fs.writeFileSync(indexPath, JSON.stringify(parsed, null, 2) + '\n');
+    fs.writeFileSync(indexPath, JSON.stringify(stripped, null, 2) + '\n');
   } catch (err) {
     pushInstallWarning('stripInternalLearnings', 'learnings/index.json', err);
   }
@@ -2230,10 +2213,8 @@ function install(isGlobal, runtime = 'claude') {
         fs.mkdirSync(agentsRefDir, { recursive: true });
         const agentsSrc = path.join(src, 'agents');
         for (const f of fs.readdirSync(agentsSrc).filter(n => n.endsWith('.md'))) {
-          let content = fs.readFileSync(path.join(agentsSrc, f), 'utf8');
-          content = content.replace(/~\/\.claude\/pan-wizard-core\//g, `${corePrefix}pan-wizard-core/`);
-          content = content.replace(/\.\/\.claude\/pan-wizard-core\//g, `${corePrefix}pan-wizard-core/`);
-          content = convertSlashCommandsToCopilotSkillMentions(content);
+          // Shared with the Agent Plugins bundle builder (install-lib).
+          const content = lib.rewriteAgentReferenceCopy(fs.readFileSync(path.join(agentsSrc, f), 'utf8'), corePrefix);
           fs.writeFileSync(path.join(agentsRefDir, f), content);
         }
       } catch (e) {

package/commands/pan/army.md

@@ -92,7 +92,7 @@ Every cap the conductor enforces applies to the campaign, scaled up:
 | `--push` | off | Push approved merges to origin (still human-gated). |
 | `--clean-seal` | off | One clean build + full verification after the last item (commands from config). |
 | `--schedule` | off | Arm a self-resuming campaign at this cadence (`hourly`/`daily`/`weekly`/`Nh`/`Nd`) instead of running once — writes the schedule descriptor (ADR-0034). Pair with `--daily-budget`. |
-| `--daily-budget` | 300 | Per-day point budget for a scheduled campaign. Advisory by default (an indicator of the day's spend); it only pauses the day's run when `budget.enforce`/`enforce_budget` is set. |
+| `--daily-budget` | 300 | Per-day point budget for a scheduled campaign. Advisory by default (an indicator of the day's spend); it only pauses the day's run when `enforce_budget: true` is set by hand in the schedule descriptor (`schedule.json`); no flag or config key sets it. |
 | `--dry-run` | off | Plan + squad delegation preview only; STOP. |
 | `--continue` / `--stop` / `--status` | — | Resume / halt / report from `.planning/orchestration/` + focus-auto state. |
 

package/commands/pan/hygiene.md

@@ -2,7 +2,7 @@
 name: pan:hygiene
 group: System
 description: Scan the project for PAN version drift and stale artifacts (legacy filenames, memory bloat, poisoned ledgers, trace debris) and apply safe cleanups
-argument-hint: "[--apply] [--trace-age-days N]"
+argument-hint: "[--apply] [--trace-age-days N] [--all-tracks] [--track <name>]"
 allowed-tools:
   - Read
   - Bash
@@ -17,12 +17,18 @@ Keep a PAN-managed project aligned with the latest PAN version and free of accum
 ## 1. Scan
 
 ```bash
-SCAN=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs hygiene scan)
+SCAN=$(node ~/.claude/pan-wizard-core/bin/pan-tools.cjs hygiene scan --all-tracks)
 ```
 
-Parse JSON: `findings[]` (`check`, `severity`, `path`, `detail`, `fixable`), `installs[]`, `latest_version`, `summary`.
+Pass `--all-tracks` by default: a project may hold several planning trees (`.planning/` plus `.planning/tracks/<name>/`), and scanning only the root tree reports "clean" for debris sitting in a sibling track. Use `--track <name>` to scan one specific tree instead.
 
-Display the findings grouped by severity (critical → warn → info). If `summary.total` is 0: report "Project is clean and aligned" and stop.
+Parse JSON: `findings[]` (`check`, `severity`, `path`, `detail`, `fixable`, `track`), `installs[]`, `latest_version`, `roots_scanned[]`, `summary` (including `summary.by_track`).
+
+Display the findings grouped by severity (critical → warn → info), labelling each with its `track` when more than one tree was scanned.
+
+**Always state which trees were scanned** — read `roots_scanned[]` and name them. If `summary.total` is 0, report "Project is clean and aligned" *together with* the list of trees that were read. A clean verdict without its scope is what let stale debris hide in an unscanned track; never report one without the other.
+
+If any root has `planning_root_exists: false`, say so plainly — that is a mistyped `--track`, not a clean tree.
 
 ## 2. Version drift (manual remediation)
 
@@ -41,7 +47,7 @@ Hygiene never runs the installer itself.
 **Without `--apply` in $ARGUMENTS:** run the dry-run and present what WOULD change:
 
 ```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs hygiene clean
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs hygiene clean --all-tracks
 ```
 
 Then ask the user (AskUserQuestion, header "Apply fixes", options: "Apply safe fixes" / "Skip") unless running headless — in auto/headless contexts, report the dry-run only and stop.
@@ -49,14 +55,14 @@ Then ask the user (AskUserQuestion, header "Apply fixes", options: "Apply safe f
 **With `--apply` (or after user confirmation):**
 
 ```bash
-node ~/.claude/pan-wizard-core/bin/pan-tools.cjs hygiene clean --apply
+node ~/.claude/pan-wizard-core/bin/pan-tools.cjs hygiene clean --all-tracks --apply
 ```
 
-Safe fixes are: lowercase renames of legacy planning filenames, deletion of aged .tmp orphans, memory-log compaction, poisoned-ledger quarantine (rename in place — never deleted), and pruning of trace sessions past retention (newest 5 always kept). Pass through `--trace-age-days N` if provided.
+Safe fixes are: lowercase renames of legacy planning filenames, deletion of aged .tmp orphans, memory-log compaction, poisoned-ledger quarantine (rename in place — never deleted), pruning of trace sessions **and optimization reports** past retention (newest 5 of each always kept), and **state.md compaction** (`compact-state`) — settled history is archived to `state-history.md` so it stops being re-read into every agent call. Nothing is deleted by any of these: the ledger is renamed, and state history is written to the archive before state.md is rewritten. Each fix is applied inside its own tree's scope, so a track's debris is cleaned in that track. Pass through `--trace-age-days N` and any `--track <name>` if provided.
 
 ## 4. Report
 
-Summarize: fixes executed / failed / left manual, plus the installer command if version drift remains. Recommend re-running `/pan:hygiene` after the installer to confirm alignment.
+Summarize: the trees scanned, fixes executed / failed / left manual (attributed per track), plus the installer command if version drift remains. If a `cache-context` finding appeared, state the per-call token cost it represents — that block is re-read on **every** agent call, so it is the project's largest recurring expense. Recommend re-running `/pan:hygiene` after the installer to confirm alignment.
 
 </process>
 

package/commands/pan/milestone-audit.md

@@ -2,7 +2,7 @@
 name: pan:milestone-audit
 group: Milestone
 description: Audit milestone completion against original intent before archiving
-argument-hint: "[version]"
+argument-hint: "[version] [--track <name>] [--all-tracks]"
 allowed-tools:
   - Read
   - Glob
@@ -26,9 +26,11 @@ Version: $ARGUMENTS (optional — defaults to current milestone)
 
 Core planning files are resolved in-workflow (`init milestone-op`) and loaded only as needed.
 
-**Completed Work:**
-Glob: .planning/phases/*/*-summary.md
-Glob: .planning/phases/*/*-verification.md
+**Planning tree:** the project may hold several. `init milestone-op` reports the `planning_root` it resolved; use that root for every glob below rather than assuming `.planning/`. Pass `--track <name>` to audit a specific tree, or run `init milestone-op --all-tracks` first to see every tree's milestone state.
+
+**Completed Work:** (relative to the resolved `planning_root`)
+Glob: {planning_root}/phases/*/*-summary.md
+Glob: {planning_root}/phases/*/*-verification.md
 </context>
 
 <citation_requirement>
@@ -57,4 +59,8 @@ Do not trust summary files at face value. If a verification.md says "all tests p
 <process>
 Execute the audit-milestone workflow from @~/.claude/pan-wizard-core/workflows/milestone-audit.md end-to-end.
 Preserve all workflow gates (scope determination, verification reading, integration check, requirements coverage, routing).
+
+Two gates are non-negotiable because they guard against auditing the wrong thing:
+- **State the resolved `planning_root` in the report.** An audit that does not name the tree it read cannot be checked.
+- **Stop if `milestone_ambiguous` is true.** More than one milestone marked current is a roadmap defect for the owner to fix; auditing one of them silently is how a report ends up describing a milestone that does not exist.
 </process>

package/commands/pan/preview.md

@@ -34,9 +34,9 @@ Consolidates Spec B v1's architect + simulate + predict-milestone into one entry
 **What it does:**
 1. `pan-tools preview phase <N>` returns `{files_mentioned, test_files_mentioned, risk_signals, risk_score, plans[], status}`.
 2. Spawn `pan-previewer` with the payload as `<preview_input>`.
-3. Agent writes `.planning/phases/<N>/preview.md` with files touched / tests at risk / migration steps / risk assessment / bottom line.
+3. Agent writes `.planning/phases/<NN-slug>/preview.md` with files touched / tests at risk / migration steps / risk assessment / bottom line.
 
-**Output:** `.planning/phases/<N>/preview.md`
+**Output:** `.planning/phases/<NN-slug>/preview.md`
 
 ### `phases` — Cross-phase dependency graph
 

package/hooks/dist/pan-cost-logger.js

@@ -20,6 +20,38 @@ const crypto = require('crypto');
 // Runtime config dirs a local PAN install lands in (mirrors installer getDirName).
 const PAN_RUNTIME_DIRS = ['.claude', '.codex', '.gemini', '.opencode', '.github'];
 
+/**
+ * Which planning tree this hook writes to.
+ *
+ * Mirrors pan-wizard-core/bin/lib/planning-root.cjs, which the hook cannot
+ * require (hooks are standalone and run inside the host runtime). Without this
+ * the CLI could be pointed at `--track verify` while the cost hook kept writing
+ * to `.planning/`, so a track's telemetry landed in the wrong tree.
+ *
+ * Env only — a hook gets no argv. Values that escape the project root are
+ * ignored rather than honoured; a bad value must degrade to the default, never
+ * write outside the project.
+ */
+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';
+}
+
+/** Absolute path inside the active planning tree. */
+function planningPath(cwd, ...segments) {
+  return path.join(cwd, ...planningDirName().split('/'), ...segments);
+}
+
 // M62: only instrument actual PAN projects. A global-install hook fires in EVERY
 // repo the user opens; without this gate it silently creates .planning/ metrics
 // artifacts in non-PAN repos. A project counts as PAN if it already has a
@@ -30,7 +62,7 @@ const PAN_RUNTIME_DIRS = ['.claude', '.codex', '.gemini', '.opencode', '.github'
 function isPanProject(cwd) {
   try {
     if (!cwd) return false;
-    if (fs.existsSync(path.join(cwd, '.planning'))) return true;
+    if (fs.existsSync(planningPath(cwd))) return true;
     for (const d of PAN_RUNTIME_DIRS) {
       if (fs.existsSync(path.join(cwd, d, 'pan-file-manifest.json'))) return true;
       if (fs.existsSync(path.join(cwd, d, 'pan-wizard-core'))) return true;
@@ -71,7 +103,7 @@ function tierForModel(model) {
 // Never throws — returns {} on any miss.
 function readActiveSessionMeta(cwd) {
   try {
-    const optDir = path.join(cwd, '.planning', 'optimization');
+    const optDir = planningPath(cwd, 'optimization');
     const sid = fs.readFileSync(path.join(optDir, 'current-session'), 'utf-8').trim();
     if (!sid) return {};
     const meta = JSON.parse(fs.readFileSync(path.join(optDir, 'traces', sid, 'session.json'), 'utf-8'));
@@ -81,6 +113,35 @@ function readActiveSessionMeta(cwd) {
   }
 }
 
+/**
+ * Current phase from state.md — the fallback when no optimizer trace is running.
+ *
+ * Phase attribution used to come ONLY from the active trace session, and
+ * tracing is off by default, so in normal use every ledger row carried
+ * `phase: null`. A field ledger had 121 rows and 100% of them were unattributed,
+ * which makes "which phase got expensive" unanswerable from PAN's own telemetry
+ * — exactly the question a slowdown raises.
+ *
+ * state.md is authoritative for the current phase and is present whenever the
+ * phase model is in use. Frontmatter first (cheap, canonical), then the
+ * `**Current Phase:**` body field that `extractFieldsFromState` reads.
+ */
+function readCurrentPhase(cwd) {
+  try {
+    const content = fs.readFileSync(planningPath(cwd, 'state.md'), 'utf-8');
+    const fm = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (fm) {
+      const m = fm[1].match(/^\s*current_phase\s*:\s*["']?([^"'\r\n]+)["']?\s*$/mi);
+      if (m && m[1].trim() && m[1].trim() !== 'null') return m[1].trim();
+    }
+    const body = content.match(/\*\*Current Phase:\*\*\s*(.+)/i);
+    if (body && body[1].trim()) return body[1].trim();
+    return null;
+  } catch {
+    return null;
+  }
+}
+
 // Duration of a transcript slice from its first→last record timestamp. Returns
 // null when either bound is absent/unparseable — never a fabricated 0.
 function durationFromSpan(firstTs, lastTs) {
@@ -97,7 +158,7 @@ function durationFromSpan(firstTs, lastTs) {
 // cache-read into the billions/trillions and stamps it onto every subagent record
 // (field report 2026-06). Stored next to tokens.jsonl; best-effort, never blocks.
 function cursorFilePath(cwd) {
-  return path.join(cwd, '.planning', METRICS_DIR, CURSOR_FILE);
+  return planningPath(cwd, METRICS_DIR, CURSOR_FILE);
 }
 function readCursor(cwd) {
   try {
@@ -373,7 +434,10 @@ function buildCostRecord(data, cwd) {
   // them (real SubagentStop payloads carry neither); tier is derived from the model.
   const sessionMeta = readActiveSessionMeta(cwd);
   const command = data.command || sessionMeta.command || null;
-  const phase = data.phase || sessionMeta.phase || null;
+  // The trace session is only present while the optimizer is running (off by
+  // default), so state.md is the fallback that makes phase attribution work in
+  // ordinary use instead of only under tracing.
+  const phase = data.phase || sessionMeta.phase || readCurrentPhase(cwd) || null;
 
   const record = {
     v: SCHEMA_V,
@@ -513,7 +577,7 @@ function appendRecord(cwd, record) {
   // differs from the real row it follows, so the dedup never fired (M61).
   if (record.__emptySlice) return false;
   try {
-    const dir = path.join(cwd, '.planning', METRICS_DIR);
+    const dir = planningPath(cwd, METRICS_DIR);
     fs.mkdirSync(dir, { recursive: true });
     const file = path.join(dir, TOKENS_FILE);
     // Idempotency guard: a re-fired SubagentStop must not double-log. Skip the

package/hooks/dist/pan-stop-guard.js

@@ -52,6 +52,37 @@
 
 const fs = require('fs');
 const path = require('path');
+/**
+ * Which planning tree this hook acts on.
+ *
+ * Mirrors pan-wizard-core/bin/lib/planning-root.cjs, which hooks cannot require
+ * (they are standalone and run inside the host runtime). All PAN hooks carry an
+ * identical copy — if the CLI is pointed at a track while a hook still writes to
+ * `.planning/`, that tree's telemetry lands in the wrong place.
+ *
+ * Env only — a hook gets no argv. A value that escapes the project root is
+ * ignored rather than honoured: a bad value degrades to the default, never
+ * writes outside the project.
+ */
+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';
+}
+
+/** Absolute path inside the active planning tree. */
+function planningPath(cwd, ...segments) {
+  return path.join(cwd, ...planningDirName().split('/'), ...segments);
+}
 
 // Unticked phase line, exactly as templates/roadmap.md and pan-roadmapper.md
 // emit it. Fixture doctrine: this shape is pinned against the shipped template
@@ -135,7 +166,7 @@ function main() {
       if (!payload || typeof payload !== 'object') payload = {};
 
       const projectDir = typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd();
-      const planningDir = path.join(projectDir, '.planning');
+      const planningDir = planningPath(projectDir);
 
       let config = null;
       try { config = JSON.parse(fs.readFileSync(path.join(planningDir, 'config.json'), 'utf8')); } catch { /* no project / bad config -> allow */ }

package/hooks/dist/pan-trace-logger.js

@@ -18,6 +18,37 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
+/**
+ * Which planning tree this hook acts on.
+ *
+ * Mirrors pan-wizard-core/bin/lib/planning-root.cjs, which hooks cannot require
+ * (they are standalone and run inside the host runtime). All PAN hooks carry an
+ * identical copy — if the CLI is pointed at a track while a hook still writes to
+ * `.planning/`, that tree's telemetry lands in the wrong place.
+ *
+ * Env only — a hook gets no argv. A value that escapes the project root is
+ * ignored rather than honoured: a bad value degrades to the default, never
+ * writes outside the project.
+ */
+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';
+}
+
+/** Absolute path inside the active planning tree. */
+function planningPath(cwd, ...segments) {
+  return path.join(cwd, ...planningDirName().split('/'), ...segments);
+}
 
 // Runtime config dirs a local PAN install lands in (mirrors installer getDirName).
 const PAN_RUNTIME_DIRS = ['.claude', '.codex', '.gemini', '.opencode', '.github'];
@@ -32,7 +63,7 @@ const PAN_RUNTIME_DIRS = ['.claude', '.codex', '.gemini', '.opencode', '.github'
 function isPanProject(cwd) {
   try {
     if (!cwd) return false;
-    if (fs.existsSync(path.join(cwd, '.planning'))) return true;
+    if (fs.existsSync(planningPath(cwd))) return true;
     for (const d of PAN_RUNTIME_DIRS) {
       if (fs.existsSync(path.join(cwd, d, 'pan-file-manifest.json'))) return true;
       if (fs.existsSync(path.join(cwd, d, 'pan-wizard-core'))) return true;
@@ -43,7 +74,9 @@ function isPanProject(cwd) {
   }
 }
 
-const PLANNING_DIR = '.planning';
+// Resolved per call via planningDirName() so a track-scoped run traces into
+// its own tree; kept as a name for the code paths that only need the label.
+const PLANNING_DIR = planningDirName();
 const OPTIMIZE_DIR = 'optimization';
 const TRACES_DIR = 'traces';
 const CURRENT_SESSION_FILE = 'current-session';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pan-wizard",
-  "version": "3.26.0",
+  "version": "3.28.0",
   "description": "Command a bot army for your codebase: a reasoning-tier Mission Control delegates whole-project goals to specialist squads and ships behind a human merge gate. Five AI CLIs, zero context rot.",
   "bin": {
     "pan-wizard": "bin/install.js"
@@ -70,6 +70,9 @@
     "test:e2e": "node scripts/run-tests.cjs tests/scenarios",
     "test:vscode": "npx playwright test --config tests/e2e/playwright.config.mjs",
     "test:watch": "node scripts/run-tests.cjs --watch tests tests/scenarios",
-    "build:plugin": "node scripts/build-plugin.js"
+    "build:plugin": "node scripts/build-plugin.js",
+    "build:agent-plugin": "node scripts/build-agent-plugin.js",
+    "harness": "node harness/src/run.cjs --tier 0",
+    "harness:model": "node harness/src/run.cjs --tier 2"
   }
 }

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

@@ -30,7 +30,6 @@
 const fs = require('fs');
 const path = require('path');
 const { output, error, safeReadFile, toPosix, findPhaseInternal } = require('./core.cjs');
-const { PLANNING_DIR } = require('./constants.cjs');
 const { planningPath } = require('./utils.cjs');
 
 const BRIDGE_DIR = 'bridge';

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

@@ -26,7 +26,6 @@
 const fs = require('fs');
 const path = require('path');
 const { output, error } = require('./core.cjs');
-const { PLANNING_DIR } = require('./constants.cjs');
 const { planningPath } = require('./utils.cjs');
 
 const BUS_DIR = 'bus';

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

@@ -13,7 +13,8 @@
 const fs = require('fs');
 const path = require('path');
 const { output, error } = require('./core.cjs');
-const { PLANNING_DIR, VERIFY_RESERVE_FRACTION } = require('./constants.cjs');
+const { VERIFY_RESERVE_FRACTION } = require('./constants.cjs');
+const { planningPath } = require('./utils.cjs');
 
 const ORCH_DIR = 'orchestration';
 const SCHEDULE_FILE = 'schedule.json';
@@ -21,7 +22,7 @@ const HISTORY_CAP = 50;
 const DAY_MS = 86400000;
 
 function schedulePath(cwd) {
-  return path.join(cwd, PLANNING_DIR, ORCH_DIR, SCHEDULE_FILE);
+  return planningPath(cwd, ORCH_DIR, SCHEDULE_FILE);
 }
 
 /**

package/pan-wizard-core/bin/lib/commands-learnings.cjs

@@ -9,8 +9,8 @@ const fs = require('fs');
 const path = require('path');
 const { getArchivedPhaseDirs, output, error } = require('./core.cjs');
 const { extractFrontmatter } = require('./frontmatter.cjs');
-const { PLANNING_DIR, PATTERNS_FILE, SESSION_HISTORY_FILE, LEARNINGS_FILE, isSummaryFile } = require('./constants.cjs');
-const { phasesPath } = require('./utils.cjs');
+const { PATTERNS_FILE, SESSION_HISTORY_FILE, LEARNINGS_FILE, isSummaryFile } = require('./constants.cjs');
+const { phasesPath, planningPath } = require('./utils.cjs');
 
 /**
  * Scan all phase directories (archived + current) and read summary frontmatter.
@@ -78,7 +78,7 @@ function collectPhaseSummaries(cwd) {
  * @returns {Array<{id: string, title: string, wrong: string, right: string, context: string|null, date: string|null}>}
  */
 function readErrorPatterns(cwd) {
-  const filePath = path.join(cwd, PLANNING_DIR, PATTERNS_FILE);
+  const filePath = planningPath(cwd, PATTERNS_FILE);
   let content;
   try {
     content = fs.readFileSync(filePath, 'utf-8');
@@ -141,7 +141,7 @@ function appendErrorPattern(cwd, pattern) {
     return { error: "Pattern requires 'wrong' and 'right' fields" };
   }
 
-  const filePath = path.join(cwd, PLANNING_DIR, PATTERNS_FILE);
+  const filePath = planningPath(cwd, PATTERNS_FILE);
   const existing = readErrorPatterns(cwd);
 
   // Determine next ID
@@ -198,7 +198,7 @@ function appendSessionSummary(cwd, summary) {
     return { error: "Summary requires 'phase' field" };
   }
 
-  const filePath = path.join(cwd, PLANNING_DIR, SESSION_HISTORY_FILE);
+  const filePath = planningPath(cwd, SESSION_HISTORY_FILE);
   const date = summary.date || new Date().toISOString().split('T')[0];
 
   const entry = [
@@ -308,7 +308,7 @@ function formatLearningEntry(learning) {
  * @returns {void}
  */
 function cmdLearningsExtract(cwd, raw) {
-  const learningsPath = path.join(cwd, PLANNING_DIR, LEARNINGS_FILE);
+  const learningsPath = planningPath(cwd, LEARNINGS_FILE);
   const newLearnings = [];
   const today = new Date().toISOString().split('T')[0];
 
@@ -445,7 +445,7 @@ function cmdLearningsExtract(cwd, raw) {
  * @returns {void}
  */
 function cmdLearningsList(cwd, raw) {
-  const learningsPath = path.join(cwd, PLANNING_DIR, LEARNINGS_FILE);
+  const learningsPath = planningPath(cwd, LEARNINGS_FILE);
 
   let content;
   try {
@@ -484,7 +484,7 @@ function cmdLearningsList(cwd, raw) {
  * @returns {void}
  */
 function cmdLearningsPrune(cwd, opts, raw) {
-  const learningsPath = path.join(cwd, PLANNING_DIR, LEARNINGS_FILE);
+  const learningsPath = planningPath(cwd, LEARNINGS_FILE);
 
   if (!opts || (opts.days == null && opts.id == null)) {
     error('Prune requires --days N or --id LEARN-NNN');