pan-wizard 3.26.0 → 3.27.0

package/README.md

@@ -659,7 +659,7 @@ PAN is not a replacement for your IDE or AI agent — it's the orchestration lay
 | `/pan:debug [desc]` | Systematic debugging with persistent state |
 | `/pan:quick [--full]` | Execute ad-hoc task with PAN guarantees (`--full` adds plan-checking and verification) |
 | `/pan:health [--repair]` | Validate `.planning/` directory integrity; `--repair` auto-fixes detected issues |
-| `/pan:hygiene [--apply] [--trace-age-days N]` | Scan for PAN version drift and stale project artifacts (legacy filenames, .tmp orphans, memory bloat, poisoned cost ledgers, trace debris, fragment planning dirs); `--apply` executes the safe fixes — ledgers are quarantined by rename, never deleted |
+| `/pan:hygiene [--apply] [--trace-age-days N] [--all-tracks]` | Scan for PAN version drift and stale project artifacts (legacy filenames, .tmp orphans, memory bloat, poisoned cost ledgers, trace and report debris, cached-context bloat, fragment planning dirs); `--apply` executes the safe fixes — ledgers are quarantined by rename, never deleted, and settled `state.md` history is archived rather than dropped |
 | `/pan:links [--strict]` | Validate the doc-code link graph: inline `[[<id>]]` refs, `// @pan:` source anchors, `require-code-mention` contracts (ADR-0027, v3.8.0+) |
 | `/pan:phase-tests [N]` | Generate tests for a completed phase based on UAT criteria |
 | `/pan:milestone-cleanup` | Archive accumulated phase directories from completed milestones |

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/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.27.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"

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');

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

@@ -5,10 +5,11 @@ const fs = require('fs');
 const path = require('path');
 const { safeReadFile, loadConfig, isGitIgnored, isGitRepo, execGit, normalizePhaseName, comparePhaseNum, getArchivedPhaseDirs, generateSlugInternal, getMilestoneInfo, resolveModelInternal, resolveEffortInternal, detectProvider, resolveTierToModel, estimateCostMultiplier, MODEL_PROFILES, output, error, findPhaseInternal, scanPendingTodos, toPosix } = require('./core.cjs');
 const { extractFrontmatter } = require('./frontmatter.cjs');
-const { PLANNING_DIR, PHASES_DIR, MILESTONES_DIR, QUICK_DIR, STATE_FILE, ROADMAP_FILE, PROJECT_FILE, PATTERNS_FILE, SESSION_HISTORY_FILE, LEARNINGS_FILE, CONTEXT_SUFFIX, UAT_SUFFIX, VERIFICATION_SUFFIX, isPlanFile, isSummaryFile, ARCHIVE_DIR_RE, PHASE_DIR_RE, CONTEXT_WINDOW, WARNING_THRESHOLD, CRITICAL_THRESHOLD, VALID_COMMIT_TYPES, DEFAULT_SENSITIVE_PATTERNS } = require('./constants.cjs');
-const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles } = require('./utils.cjs');
+const { PHASES_DIR, MILESTONES_DIR, QUICK_DIR, STATE_FILE, ROADMAP_FILE, PROJECT_FILE, PATTERNS_FILE, SESSION_HISTORY_FILE, LEARNINGS_FILE, CONTEXT_SUFFIX, UAT_SUFFIX, VERIFICATION_SUFFIX, isPlanFile, isSummaryFile, ARCHIVE_DIR_RE, PHASE_DIR_RE, CONTEXT_WINDOW, WARNING_THRESHOLD, CRITICAL_THRESHOLD, VALID_COMMIT_TYPES, DEFAULT_SENSITIVE_PATTERNS } = require('./constants.cjs');
+const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles, planningRel } = require('./utils.cjs');
 const { estimateTokens } = require('./context-budget.cjs');
 const { collectPhaseSummaries, readErrorPatterns, appendErrorPattern, appendSessionSummary, parseLearnings, formatLearningEntry, cmdLearningsExtract, cmdLearningsList, cmdLearningsPrune } = require('./commands-learnings.cjs');
+const { planningRootRel } = require('./planning-root.cjs');
 
 /**
  * Generate a URL-safe slug from text by lowercasing and replacing non-alphanumeric chars.
@@ -381,7 +382,7 @@ function cmdCommit(cwd, message, files, raw, amend, opts) {
     output({ committed: false, hash: null, reason: 'skipped_commit_docs_false' }, raw, 'skipped');
     return;
   }
-  if (isGitIgnored(cwd, PLANNING_DIR)) {
+  if (isGitIgnored(cwd, planningRootRel())) {
     // No error key, exit 0: .planning/ is gitignored - also the user's choice.
     output({ committed: false, hash: null, reason: 'skipped_gitignored' }, raw, 'skipped');
     return;
@@ -395,7 +396,7 @@ function cmdCommit(cwd, message, files, raw, amend, opts) {
   const preStaged = new Set(stagedFiles(cwd));
 
   // Stage files
-  const filesToStage = files && files.length > 0 ? files : [PLANNING_DIR + '/'];
+  const filesToStage = files && files.length > 0 ? files : [planningRel() + '/'];
   for (const file of filesToStage) execGit(cwd, ['add', file]);
 
   // Safety checks
@@ -614,7 +615,7 @@ function renderProgressBar(percent, width) {
  */
 function cmdProgressRender(cwd, format, raw) {
   const phasesDir = phasesPath(cwd);
-  const roadmapPath = path.join(cwd, PLANNING_DIR, ROADMAP_FILE);
+  const roadmapPath = planningPath(cwd, ROADMAP_FILE);
   const milestone = getMilestoneInfo(cwd);
 
   const phases = [];
@@ -693,9 +694,9 @@ function cmdProgressRender(cwd, format, raw) {
  * Compute and output a composite health score from progress, context budget, and staleness.
  */
 function renderHealthReport(cwd, { phasesDir, phases, totalPlans, totalSummaries, percent }, raw) {
-  const stateContent = safeReadFile(path.join(cwd, PLANNING_DIR, STATE_FILE));
-  const roadmapContent = safeReadFile(path.join(cwd, PLANNING_DIR, ROADMAP_FILE));
-  const projectContent = safeReadFile(path.join(cwd, PLANNING_DIR, PROJECT_FILE));
+  const stateContent = safeReadFile(planningPath(cwd, STATE_FILE));
+  const roadmapContent = safeReadFile(planningPath(cwd, ROADMAP_FILE));
+  const projectContent = safeReadFile(planningPath(cwd, PROJECT_FILE));
 
   const stateTokens = estimateTokens(stateContent);
   const roadmapTokens = estimateTokens(roadmapContent);
@@ -742,7 +743,7 @@ function renderHealthReport(cwd, { phasesDir, phases, totalPlans, totalSummaries
   // Read session history count
   let sessionCount = 0;
   try {
-    const sessionContent = fs.readFileSync(path.join(cwd, PLANNING_DIR, SESSION_HISTORY_FILE), 'utf-8');
+    const sessionContent = fs.readFileSync(planningPath(cwd, SESSION_HISTORY_FILE), 'utf-8');
     sessionCount = (sessionContent.match(/^### Session — /gm) || []).length;
   } catch { /* file doesn't exist */ }
 
@@ -782,8 +783,8 @@ function cmdTodoComplete(cwd, filename, raw) {
     error('filename required for todo complete');
   }
 
-  const pendingDir = path.join(cwd, PLANNING_DIR, 'todos', 'pending');
-  const completedDir = path.join(cwd, PLANNING_DIR, 'todos', 'completed');
+  const pendingDir = planningPath(cwd, 'todos', 'pending');
+  const completedDir = planningPath(cwd, 'todos', 'completed');
   const sourcePath = path.join(pendingDir, filename);
 
   let content;
@@ -870,14 +871,14 @@ function cmdScaffold(cwd, type, options, raw) {
       }
       const slug = generateSlugInternal(name);
       const dirName = `${padded}-${slug}`;
-      const phasesParent = path.join(cwd, PLANNING_DIR, PHASES_DIR);
+      const phasesParent = planningPath(cwd, PHASES_DIR);
       try {
         fs.mkdirSync(phasesParent, { recursive: true });
         fs.mkdirSync(path.join(phasesParent, dirName), { recursive: true });
       } catch (e) {
         error(`Failed to create phase directory: ${e.message}`);
       }
-      output({ created: true, directory: `${PLANNING_DIR}/${PHASES_DIR}/${dirName}` }, raw, `${PLANNING_DIR}/${PHASES_DIR}/${dirName}`);
+      output({ created: true, directory: planningRel(PHASES_DIR, dirName) }, raw, planningRel(PHASES_DIR, dirName));
       return;
     }
     default:
@@ -972,7 +973,7 @@ function cmdBatchCommit(cwd, items, raw) {
   }
 
   // Stage .planning/ only
-  execGit(cwd, ['add', PLANNING_DIR + '/']);
+  execGit(cwd, ['add', planningRel() + '/']);
 
   // Check if there's anything to commit
   const statusResult = execGit(cwd, ['diff', '--cached', '--name-only']);

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

@@ -7,11 +7,11 @@ const os = require('os');
 const path = require('path');
 const { output, error, safeReadFile, toPosix, findPhaseInternal } = require('./core.cjs');
 const {
-  PLANNING_DIR, CONFIG_FILE, PROJECT_FILE, STANDARDS_FILE,
+  CONFIG_FILE, PROJECT_FILE, STANDARDS_FILE,
   STANDARDS_CATALOG, STANDARDS_CATEGORIES, STANDARDS_RECOMMENDATIONS,
   PHASE_KEYWORDS_TO_STANDARDS, STANDARDS_EXTERNAL_TOOLS,
 } = require('./constants.cjs');
-const { readJsonFile, planningPath, fileAccessible, hasBraveSearchKey } = require('./utils.cjs');
+const { readJsonFile, planningPath, fileAccessible, hasBraveSearchKey, planningRel } = require('./utils.cjs');
 
 /**
  * Count checked checklist items in a standards section.
@@ -119,7 +119,7 @@ function cmdConfigEnsureSection(cwd, raw) {
 
   try {
     fs.writeFileSync(configPath, JSON.stringify(defaults, null, 2), 'utf-8');
-    output({ created: true, path: PLANNING_DIR + '/' + CONFIG_FILE }, raw, 'created');
+    output({ created: true, path: planningRel(CONFIG_FILE) }, raw, 'created');
   } catch (err) {
     error('Failed to create config.json: ' + err.message);
   }
@@ -354,7 +354,7 @@ function cmdStandardsSelect(cwd, standardId, raw) {
   output({
     added: standardId,
     project_standards: currentIds,
-    standards_file: toPosix(PLANNING_DIR + '/' + STANDARDS_FILE),
+    standards_file: toPosix(planningRel(STANDARDS_FILE)),
   }, raw, 'Added ' + STANDARDS_CATALOG[standardId].name);
 }
 
@@ -398,7 +398,7 @@ function cmdStandardsRemove(cwd, standardId, raw) {
   output({
     removed: standardId,
     project_standards: newIds,
-    standards_file: toPosix(PLANNING_DIR + '/' + STANDARDS_FILE),
+    standards_file: toPosix(planningRel(STANDARDS_FILE)),
   }, raw, 'Removed ' + standardId);
 }
 

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

@@ -572,11 +572,31 @@ const MEMORY_LOAD_WARN_TOKENS = 4000;     // memory-budget telemetry: warn thres
 const MEMORY_LOAD_CRIT_TOKENS = 8000;     // memory-budget telemetry: critical threshold (absolute tokens)
 const MEMORY_LOAD_MAX_FRACTION = 0.15;    // memory-budget telemetry: max fraction of median agent input
 
+// Cached prompt context (ADR-0044). The files in CACHEABLE_CONTEXT_FILES are
+// re-read into EVERY agent call, so their combined size is the single largest
+// recurring cost in a PAN project — cache reads dominate token traffic by roughly
+// two orders of magnitude over generation. These thresholds mirror the
+// MEMORY_LOAD_* pattern above: measured, classified, and surfaced.
+const CACHE_BLOCK_WARN_TOKENS = 15000;    // cached context block: warn threshold (absolute tokens)
+const CACHE_BLOCK_CRIT_TOKENS = 25000;    // cached context block: critical threshold
+const CACHE_FILE_WARN_TOKENS = 6000;      // any SINGLE cacheable file past this is the one to fix
+
+// state.md compaction (ADR-0044). state.md is the largest cacheable file in
+// practice because its section writers only ever append; closed history keeps
+// being re-read months after it stopped being actionable.
+const STATE_HISTORY_FILE = 'state-history.md';
+const STATE_COMPACT_KEEP_DAYS = 30;       // dated sections newer than this stay in state.md
+
 // Hygiene — project cleanup + version alignment (docs/FIELD-HARVEST-2026-07.md follow-ups).
 const HYGIENE_TRACE_RETENTION_DAYS = 30;  // trace sessions older than this are prunable…
 const HYGIENE_TRACE_KEEP_MIN = 5;         // …but always keep this many newest sessions
+const HYGIENE_REPORT_KEEP_MIN = 5;        // …same shape for optimization/reports/
 const HYGIENE_LEDGER_SUSPECT_RATIO = 0.5; // ledger "poisoned" when suspect fraction ≥ this…
 const HYGIENE_LEDGER_MIN_RECORDS = 20;    // …and it has at least this many records
+// …OR when the suspect rows, however few, carry this share of the token MASS.
+// A count-only gate passes a ledger whose 24% bad rows hold 90% of the tokens —
+// statistically fine, arithmetically useless. Mass is what aggregates read.
+const HYGIENE_LEDGER_SUSPECT_MASS_RATIO = 0.5;
 const HYGIENE_TMP_AGE_MS = 60 * 60 * 1000; // .tmp orphans older than 1h are deletable
 
 // Skill-Aligned Decomposition pass (ADR-0038): planner draft ↔ skill-surface alignment.
@@ -772,8 +792,15 @@ module.exports = {
   MEMORY_LOAD_CRIT_TOKENS,
   MEMORY_LOAD_MAX_FRACTION,
   // Hygiene
+  CACHE_BLOCK_WARN_TOKENS,
+  CACHE_BLOCK_CRIT_TOKENS,
+  CACHE_FILE_WARN_TOKENS,
+  STATE_HISTORY_FILE,
+  STATE_COMPACT_KEEP_DAYS,
   HYGIENE_TRACE_RETENTION_DAYS,
   HYGIENE_TRACE_KEEP_MIN,
+  HYGIENE_REPORT_KEEP_MIN,
+  HYGIENE_LEDGER_SUSPECT_MASS_RATIO,
   HYGIENE_LEDGER_SUSPECT_RATIO,
   HYGIENE_LEDGER_MIN_RECORDS,
   HYGIENE_TMP_AGE_MS,