pan-wizard 3.26.0 → 3.28.0

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.
@@ -667,6 +687,27 @@ const REFLECTION_THRESHOLD = {
   enable_on_tiers: ['reasoning'],
 };
 
+/**
+ * Markers of a `.planning/` tree written by ANOTHER tool. gsd-core (open-gsd/gsd-core,
+ * the continuation of Get Shit Done) uses the same directory name and the same uppercase
+ * core files PAN's pre-v2.2 layout used, so hygiene's legacy-filename rename would rename
+ * another tool's state. These are POSITIVE markers PAN never writes — files, directories,
+ * and gsd-core's flat dotted config keys (PAN nests `workflow: {}`). Source: gsd-core
+ * docs/USER-GUIDE.md, read 2026-09-10. Consumed by foreign-planning.cjs (reality check R15).
+ */
+const FOREIGN_PLANNING_MARKERS = Object.freeze({
+  gsd: Object.freeze({
+    tool: 'gsd-core',
+    files: Object.freeze(['HANDOFF.json', '.gsd-allow-shrink']),
+    dirs: Object.freeze(['forensics', 'threads', 'seeds', 'ui-reviews', 'sketches', 'spikes', 'onboarding']),
+    configKeys: Object.freeze([
+      'workflow.discuss_mode', 'workflow.context_coverage_gate', 'workflow.ui_phase', 'workflow.ui_safety_gate',
+      'workflow.skip_discuss', 'workflow.drift_action', 'workflow.drift_threshold', 'plan_review.source_grounding',
+      'graphify.enabled', 'intel.enabled', 'hooks.workflow_guard', 'dynamic_routing', 'resolve_model_ids',
+    ]),
+  }),
+});
+
 module.exports = {
   // Directories
   PLANNING_DIR,
@@ -745,6 +786,7 @@ module.exports = {
   COMPLEX_FILE_THRESHOLD,
   CHARS_PER_TOKEN,
   HEALTH_STATUS,
+  FOREIGN_PLANNING_MARKERS,
   MAX_JSON_SIZE,
   PROGRESS_BAR_WIDTH,
   MAX_SLUG_LENGTH,
@@ -772,8 +814,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,

package/pan-wizard-core/bin/lib/context-budget.cjs

@@ -71,6 +71,66 @@ function estimateRelevanceRatio(text) {
  * @param {string} cwd - Project root directory
  * @param {boolean} raw - If true, output human-readable string
  */
+// ─── Prompt-cache lifetime signal (2026-09, ADR-0044 follow-up) ─────────────
+//
+// Claude Code decides the prompt-cache lifetime per request bucket: the main
+// conversation can get one hour on a subscription, but EVERYTHING ELSE —
+// subagents, workflows, forks — gets five minutes unless `subagentPromptCacheTtl`
+// (≥2.1.242) says otherwise. Every PAN agent is a subagent. So a phase whose
+// agents are spaced more than five minutes apart re-writes the same cached
+// context block each time, and ADR-0044 measured that block as the bulk of PAN's
+// token traffic. This assessor reads the cost ledger for exactly that signature:
+// a cache WRITE that follows an idle gap of five to sixty minutes — a miss the
+// one-hour lifetime would have turned into a hit. It recommends the setting only
+// when the pattern recurs, because one-hour writes bill at 2× base input against
+// 1.25× for five-minute writes: the longer lifetime pays off once a block is read
+// twice inside the hour, and costs more on bursts that never idle.
+
+const TTL_SHORT_MIN = 5;     // the default subagent lifetime, in minutes
+const TTL_LONG_MIN = 60;     // the lifetime the setting buys
+const TTL_MIN_WRITE_TOKENS = 1000;  // ignore trivial writes (a few tokens of tool results)
+const TTL_RECOMMEND_AT = 2;  // recurrence, not a single event, earns the recommendation
+
+/**
+ * Pure. Scan ledger records (oldest first by `ts`) for cache writes that follow
+ * an idle gap in (TTL_SHORT_MIN, TTL_LONG_MIN] — writes the one-hour lifetime
+ * would have avoided. Records without a parseable `ts`, and records flagged
+ * suspect by the caller (pass them pre-filtered), are ignored.
+ *
+ * @param {Array<object>} records - cost ledger rows ({ts, cache_write_tokens, …})
+ * @param {{minWriteTokens?:number, recommendAt?:number}} [opts]
+ * @returns {{records_considered:number, writes_after_short_idle:number, tokens_after_short_idle:number, writes_after_long_idle:number, recommend:boolean, setting:string, advice:string|null}}
+ */
+function assessCacheTtl(records, opts = {}) {
+  const minWrite = opts.minWriteTokens ?? TTL_MIN_WRITE_TOKENS;
+  const recommendAt = opts.recommendAt ?? TTL_RECOMMEND_AT;
+  const rows = (Array.isArray(records) ? records : [])
+    .map(r => ({ t: r && r.ts ? new Date(r.ts).getTime() : NaN, w: Number(r && r.cache_write_tokens) || 0 }))
+    .filter(r => Number.isFinite(r.t))
+    .sort((a, b) => a.t - b.t);
+  let shortIdle = 0; let shortIdleTokens = 0; let longIdle = 0;
+  for (let i = 1; i < rows.length; i++) {
+    if (rows[i].w < minWrite) continue;
+    const gapMin = (rows[i].t - rows[i - 1].t) / 60000;
+    if (gapMin > TTL_SHORT_MIN && gapMin <= TTL_LONG_MIN) { shortIdle++; shortIdleTokens += rows[i].w; }
+    else if (gapMin > TTL_LONG_MIN) longIdle++;
+  }
+  const recommend = shortIdle >= recommendAt;
+  const setting = 'subagentPromptCacheTtl';
+  const advice = recommend
+    ? `${shortIdle} cache writes followed an idle gap of ${TTL_SHORT_MIN}–${TTL_LONG_MIN} min (~${shortIdleTokens.toLocaleString()} tokens re-written): subagents get the five-minute cache lifetime by default — set \`${setting}: "1h"\` in a Claude Code settings file. One-hour writes bill at 2× base input against 1.25×, so this pays off once a block is read twice within the hour.`
+    : null;
+  return {
+    records_considered: rows.length,
+    writes_after_short_idle: shortIdle,
+    tokens_after_short_idle: shortIdleTokens,
+    writes_after_long_idle: longIdle,
+    recommend,
+    setting,
+    advice,
+  };
+}
+
 function cmdContextBudget(cwd, raw) {
   const planDir = planningPath(cwd);
   if (!fileAccessible(planDir)) {
@@ -182,12 +242,49 @@ function cmdContextBudget(cwd, raw) {
     const eligiblePct = totalTokens > 0
       ? Math.round((cacheTokens / totalTokens) * 1000) / 10
       : 0;
+    // The cached block is re-read into EVERY agent call, so its size is the
+    // project's largest recurring cost. This used to be measured and reported
+    // with no threshold attached, which meant a block that had grown to ~28k
+    // tokens of mostly closed history looked exactly like a healthy one.
+    // Classifying it is what turns the measurement into a signal.
+    const { CACHE_BLOCK_WARN_TOKENS, CACHE_BLOCK_CRIT_TOKENS, CACHE_FILE_WARN_TOKENS } = require('./constants.cjs');
+    const largest = cached.blocks
+      .map(b => ({ path: b.path, tokens: Math.ceil((b.content || '').length / 4) }))
+      .sort((a, b) => b.tokens - a.tokens);
+
+    let cacheStatus = 'ok';
+    if (cached.blocks.length === 0) cacheStatus = 'absent';
+    else if (cacheTokens >= CACHE_BLOCK_CRIT_TOKENS) cacheStatus = 'critical';
+    else if (cacheTokens >= CACHE_BLOCK_WARN_TOKENS) cacheStatus = 'warn';
+
+    const advice = cacheStatus === 'absent'
+      ? 'no cacheable context files — every agent call re-sends its context uncached'
+      : cacheStatus === 'ok'
+        ? null
+        : `cached context is re-read on every agent call; largest file ${largest[0].path} (~${largest[0].tokens} tokens)`
+          + (largest[0].path.endsWith('state.md') ? ' — run `pan-tools state compact`' : '');
+
+    // Lifetime signal from the ledger (suspect rows excluded — they carry
+    // poisoned counters, not real writes). Absent ledger → zero rows, no advice.
+    let ttl = null;
+    try {
+      const { readRecords, isSuspectRecord } = require('./cost.cjs');
+      ttl = assessCacheTtl(readRecords(cwd).filter(r => !isSuspectRecord(r)));
+    } catch { ttl = null; }
+
     cache = {
       block_count: cached.blocks.length,
       block_paths: cached.blocks.map(b => b.path),
+      block_tokens: largest,
       total_bytes: cached.total_bytes,
       total_tokens: cacheTokens,
       eligible_pct: eligiblePct,
+      status: cacheStatus,
+      warn_tokens: CACHE_BLOCK_WARN_TOKENS,
+      crit_tokens: CACHE_BLOCK_CRIT_TOKENS,
+      file_warn_tokens: CACHE_FILE_WARN_TOKENS,
+      advice,
+      ttl,
       sha: cached.sha,
     };
   } catch {
@@ -247,4 +344,5 @@ module.exports = {
   cmdContextBudget,
   estimateTokens,
   estimateRelevanceRatio,
+  assessCacheTtl,
 };