pan-wizard 3.26.0 → 3.27.0

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

@@ -5,11 +5,12 @@
 const fs = require('fs');
 const path = require('path');
 const { loadConfig, resolveModelInternal, findPhaseInternal, getRoadmapPhaseInternal, pathExistsInternal, generateSlugInternal, getMilestoneInfo, normalizePhaseName, toPosix, output, error, scanPendingTodos, isGitRepo, execGit } = require('./core.cjs');
-const { PLANNING_DIR, PHASES_DIR, CODEBASE_DIR, QUICK_DIR, MILESTONES_DIR, STATE_FILE, ROADMAP_FILE, CONFIG_FILE, PROJECT_FILE, REQUIREMENTS_FILE, isPlanFile, isSummaryFile, isResearchFile, isContextFile, isVerificationFile, PLAN_SUFFIX, SUMMARY_SUFFIX, CONTEXT_SUFFIX, RESEARCH_SUFFIX, VERIFICATION_SUFFIX, UAT_SUFFIX, MAX_SLUG_LENGTH } = require('./constants.cjs');
-const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles, classifyPhaseStatus, hasBraveSearchKey, parsePhaseDir } = require('./utils.cjs');
+const { PHASES_DIR, CODEBASE_DIR, QUICK_DIR, MILESTONES_DIR, STATE_FILE, ROADMAP_FILE, CONFIG_FILE, PROJECT_FILE, REQUIREMENTS_FILE, isPlanFile, isSummaryFile, isResearchFile, isContextFile, isVerificationFile, PLAN_SUFFIX, SUMMARY_SUFFIX, CONTEXT_SUFFIX, RESEARCH_SUFFIX, VERIFICATION_SUFFIX, UAT_SUFFIX, MAX_SLUG_LENGTH } = require('./constants.cjs');
+const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles, classifyPhaseStatus, hasBraveSearchKey, parsePhaseDir, planningRel } = require('./utils.cjs');
 const { classifyPlanTier } = require('./phase.cjs');
 const { extractFrontmatter } = require('./frontmatter.cjs');
 const { detectLanguages } = require('./codebase.cjs');
+const { planningRootRel, describePlanningRoot, planningRoots, withPlanningRoot } = require('./planning-root.cjs');
 
 // ---- Git helpers ----
 
@@ -23,7 +24,7 @@ function ensureGitRepo(cwd) {
 
 /** Build a forward-slash relative path under .planning for JSON output */
 function planningRelPath(...segments) {
-  return [PLANNING_DIR, ...segments].join('/');
+  return planningRel(...segments);
 }
 
 /**
@@ -178,6 +179,9 @@ function cmdInitExecutePhase(cwd, phase, raw, opts) {
         : null,
 
     // Milestone info
+    // Which tree this milestone came from — a spliced or wrong-track milestone
+    // must never look like a confident answer.
+    ...describePlanningRoot(cwd),
     milestone_version: milestone.version,
     milestone_name: milestone.name,
     milestone_slug: generateSlugInternal(milestone.name),
@@ -251,7 +255,10 @@ function cmdInitPlanPhase(cwd, phase, raw) {
     plan_count: phaseInfo?.plans?.length || 0,
 
     // Environment
-    planning_exists: pathExistsInternal(cwd, PLANNING_DIR),
+    planning_exists: pathExistsInternal(cwd, planningRootRel()),
+    // Which tree this ran against — so a wrong --track/--planning-dir is visible
+    // in the output rather than silently producing plausible results.
+    ...describePlanningRoot(cwd),
     roadmap_exists: pathExistsInternal(cwd, planningRelPath(ROADMAP_FILE)),
 
     // File paths
@@ -322,7 +329,10 @@ function cmdInitNewProject(cwd, raw) {
     // Existing state
     project_exists: pathExistsInternal(cwd, planningRelPath(PROJECT_FILE)),
     has_codebase_map: pathExistsInternal(cwd, planningRelPath(CODEBASE_DIR)),
-    planning_exists: pathExistsInternal(cwd, PLANNING_DIR),
+    planning_exists: pathExistsInternal(cwd, planningRootRel()),
+    // Which tree this ran against — so a wrong --track/--planning-dir is visible
+    // in the output rather than silently producing plausible results.
+    ...describePlanningRoot(cwd),
 
     // Brownfield detection
     has_existing_code: hasCode,
@@ -435,7 +445,10 @@ function cmdInitQuick(cwd, description, raw) {
 
     // File existence
     roadmap_exists: pathExistsInternal(cwd, planningRelPath(ROADMAP_FILE)),
-    planning_exists: pathExistsInternal(cwd, PLANNING_DIR),
+    planning_exists: pathExistsInternal(cwd, planningRootRel()),
+    // Which tree this ran against — so a wrong --track/--planning-dir is visible
+    // in the output rather than silently producing plausible results.
+    ...describePlanningRoot(cwd),
 
   };
 
@@ -464,7 +477,10 @@ function cmdInitResume(cwd, raw) {
     state_exists: pathExistsInternal(cwd, planningRelPath(STATE_FILE)),
     roadmap_exists: pathExistsInternal(cwd, planningRelPath(ROADMAP_FILE)),
     project_exists: pathExistsInternal(cwd, planningRelPath(PROJECT_FILE)),
-    planning_exists: pathExistsInternal(cwd, PLANNING_DIR),
+    planning_exists: pathExistsInternal(cwd, planningRootRel()),
+    // Which tree this ran against — so a wrong --track/--planning-dir is visible
+    // in the output rather than silently producing plausible results.
+    ...describePlanningRoot(cwd),
 
     // File paths
     state_path: planningRelPath(STATE_FILE),
@@ -572,7 +588,10 @@ function cmdInitPhaseOp(cwd, phase, raw) {
 
     // File existence
     roadmap_exists: pathExistsInternal(cwd, planningRelPath(ROADMAP_FILE)),
-    planning_exists: pathExistsInternal(cwd, PLANNING_DIR),
+    planning_exists: pathExistsInternal(cwd, planningRootRel()),
+    // Which tree this ran against — so a wrong --track/--planning-dir is visible
+    // in the output rather than silently producing plausible results.
+    ...describePlanningRoot(cwd),
 
     // File paths
     state_path: planningRelPath(STATE_FILE),
@@ -610,7 +629,10 @@ function cmdInitTodos(cwd, area, raw) {
     area_filter: area || null,
     pending_dir: planningRelPath('todos/pending'),
     completed_dir: planningRelPath('todos/completed'),
-    planning_exists: pathExistsInternal(cwd, PLANNING_DIR),
+    planning_exists: pathExistsInternal(cwd, planningRootRel()),
+    // Which tree this ran against — so a wrong --track/--planning-dir is visible
+    // in the output rather than silently producing plausible results.
+    ...describePlanningRoot(cwd),
     todos_dir_exists: pathExistsInternal(cwd, planningRelPath('todos')),
     pending_dir_exists: pathExistsInternal(cwd, planningRelPath('todos/pending')),
   };
@@ -624,7 +646,7 @@ function cmdInitTodos(cwd, area, raw) {
  * @param {boolean} raw - If true, output raw value instead of JSON
  * @returns {void}
  */
-function cmdInitMilestoneOp(cwd, raw) {
+function buildMilestoneOpPayload(cwd) {
   const config = loadConfig(cwd);
   const milestone = getMilestoneInfo(cwd);
 
@@ -667,10 +689,21 @@ function cmdInitMilestoneOp(cwd, raw) {
     commit_docs: config.commit_docs,
 
     // Current milestone
+    // Which tree this milestone came from — a spliced or wrong-track milestone
+    // must never look like a confident answer.
+    ...describePlanningRoot(cwd),
     milestone_version: milestone.version,
     milestone_name: milestone.name,
     milestone_slug: generateSlugInternal(milestone.name),
 
+    // How the milestone was decided. `milestone_ambiguous` means the roadmap
+    // marks more than one milestone current — a planning-state error the audit
+    // must surface rather than silently resolve to whichever came first.
+    milestone_status: milestone.status,
+    milestone_basis: milestone.basis,
+    milestone_ambiguous: milestone.ambiguous,
+    milestone_candidates: milestone.candidates,
+
     // Phase counts
     phase_count: phaseCount,
     completed_phases: completedPhases,
@@ -688,7 +721,44 @@ function cmdInitMilestoneOp(cwd, raw) {
     phases_dir_exists: pathExistsInternal(cwd, planningRelPath(PHASES_DIR)),
   };
 
-  output(result, raw);
+  return result;
+}
+
+/**
+ * Milestone bootstrap context for one planning tree, or for every tree at once.
+ *
+ * `--all-tracks` exists because a milestone audit run against the wrong tree
+ * produces a confident, plausible, wrong report. Sweeping every tree and
+ * labelling each result makes the scope of the audit explicit instead of
+ * implicit in whichever directory the command happened to resolve.
+ *
+ * @param {string} cwd - Project root directory
+ * @param {boolean} raw - If true, output raw value instead of JSON
+ * @param {Object} [opts] - {allTracks}
+ * @returns {void}
+ */
+function cmdInitMilestoneOp(cwd, raw, opts = {}) {
+  if (!opts.allTracks) {
+    output(buildMilestoneOpPayload(cwd), raw);
+    return;
+  }
+
+  const roots = planningRoots(cwd, { allTracks: true });
+  const tracks = roots.map(root => withPlanningRoot(root.rel, () => ({
+    ...buildMilestoneOpPayload(cwd),
+    // Authoritative: `track` comes from the root we are sweeping, and must win
+    // over anything the spread payload carries.
+    track: root.name,
+  }), root.name));
+
+  output({
+    all_tracks: true,
+    track_count: tracks.length,
+    // A milestone the tooling could not resolve unambiguously in ANY tree is
+    // worth surfacing at the top level — the audit should stop, not guess.
+    ambiguous_tracks: tracks.filter(t => t.milestone_ambiguous).map(t => t.track),
+    tracks,
+  }, raw);
 }
 
 /**
@@ -726,7 +796,10 @@ function cmdInitMapCodebase(cwd, raw) {
     has_maps: existingMaps.length > 0,
 
     // File existence
-    planning_exists: pathExistsInternal(cwd, PLANNING_DIR),
+    planning_exists: pathExistsInternal(cwd, planningRootRel()),
+    // Which tree this ran against — so a wrong --track/--planning-dir is visible
+    // in the output rather than silently producing plausible results.
+    ...describePlanningRoot(cwd),
     codebase_dir_exists: pathExistsInternal(cwd, planningRelPath(CODEBASE_DIR)),
 
     // Language detection
@@ -785,7 +858,7 @@ function scanAllPhases(cwd) {
       const phaseInfo = {
         number: phaseNumber,
         name: phaseName,
-        directory: toPosix(path.join(PLANNING_DIR, PHASES_DIR, dirName)),
+        directory: planningRel(PHASES_DIR, dirName),
         status,
         plan_count: plans.length,
         summary_count: summaries.length,
@@ -833,6 +906,9 @@ function cmdInitProgress(cwd, raw) {
     commit_docs: config.commit_docs,
 
     // Milestone
+    // Which tree this milestone came from — a spliced or wrong-track milestone
+    // must never look like a confident answer.
+    ...describePlanningRoot(cwd),
     milestone_version: milestone.version,
     milestone_name: milestone.name,
 
@@ -873,6 +949,7 @@ module.exports = {
   cmdInitPhaseOp,
   cmdInitTodos,
   cmdInitMilestoneOp,
+  buildMilestoneOpPayload,
   cmdInitMapCodebase,
   cmdInitProgress,
 };

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

@@ -15,7 +15,6 @@
 const fs = require('fs');
 const path = require('path');
 const { output, error, safeReadFile, toPosix, escapeRegex } = require('./core.cjs');
-const { PLANNING_DIR } = require('./constants.cjs');
 const { planningPath } = require('./utils.cjs');
 const { listMemoryAgents, readMemory } = require('./memory.cjs');
 

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

@@ -22,7 +22,7 @@
 const fs = require('fs');
 const path = require('path');
 const { output, error } = require('./core.cjs');
-const { PLANNING_DIR, CHARS_PER_TOKEN, MEMORY_SELECT_BUDGET_TOKENS, MEMORY_RECENCY_FLOOR, MEMORY_SOFT_CAP_MULT, MEMORY_LOAD_WARN_TOKENS, MEMORY_LOAD_CRIT_TOKENS, MEMORY_LOAD_MAX_FRACTION } = require('./constants.cjs');
+const { CHARS_PER_TOKEN, MEMORY_SELECT_BUDGET_TOKENS, MEMORY_RECENCY_FLOOR, MEMORY_SOFT_CAP_MULT, MEMORY_LOAD_WARN_TOKENS, MEMORY_LOAD_CRIT_TOKENS, MEMORY_LOAD_MAX_FRACTION } = require('./constants.cjs');
 const { planningPath } = require('./utils.cjs');
 
 const MEMORY_DIR = 'memory';

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

@@ -4,8 +4,8 @@
 
 const fs = require('fs');
 const path = require('path');
-const { PLANNING_DIR, PHASES_DIR, MILESTONES_DIR, ROADMAP_FILE, REQUIREMENTS_FILE, STATE_FILE, isPlanFile } = require('./constants.cjs');
-const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles, fileAccessible } = require('./utils.cjs');
+const { PHASES_DIR, MILESTONES_DIR, ROADMAP_FILE, REQUIREMENTS_FILE, STATE_FILE, isPlanFile } = require('./constants.cjs');
+const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles, fileAccessible, planningRel } = require('./utils.cjs');
 const { output, error, isGitRepo, execGit, escapeRegex } = require('./core.cjs');
 const { extractFrontmatter } = require('./frontmatter.cjs');
 const { writeStateMd } = require('./state.cjs');
@@ -260,7 +260,7 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
 
   // Auto-commit + tag unless --no-commit or not a git repo
   if (!options.noCommit && isGitRepo(cwd)) {
-    execGit(cwd, ['add', PLANNING_DIR + '/']);
+    execGit(cwd, ['add', planningRel() + '/']);
     const commitMsg = `docs: milestone ${version} complete`;
     const commitResult = execGit(cwd, ['commit', '-m', commitMsg]);
     if (commitResult.exitCode === 0) {

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

@@ -9,7 +9,7 @@
 const fs = require('fs');
 const path = require('path');
 const { output, escapeRegex, execGit } = require('./core.cjs');
-const { PLANNING_DIR } = require('./constants.cjs');
+const { planningPath, planningRel } = require('./utils.cjs');
 
 // ─── Storage layout ──────────────────────────────────────────────────────────
 
@@ -29,7 +29,7 @@ const IMPACT_LEVELS = ['critical', 'major', 'minor', 'trivial'];
 // ─── Path helpers ─────────────────────────────────────────────────────────────
 
 function getOptimizeDir(cwd) {
-  return path.join(cwd, PLANNING_DIR, OPTIMIZE_DIR);
+  return planningPath(cwd, OPTIMIZE_DIR);
 }
 
 function getTracesDir(cwd) {
@@ -817,7 +817,7 @@ function cmdOptimizeLearn(cwd, opts, raw) {
 
   output({
     session_id: sessionId,
-    analysis_path: path.join(PLANNING_DIR, OPTIMIZE_DIR, OPT_REPORTS_DIR, reportName).replace(/\\/g, '/'),
+    analysis_path: planningRel(OPTIMIZE_DIR, OPT_REPORTS_DIR, reportName),
     summary: report.summary,
     top_error_patterns: report.error_patterns.slice(0, 5),
     top_gap_patterns: report.gap_patterns.slice(0, 5),

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

@@ -8,8 +8,8 @@ const { escapeRegex, normalizePhaseName, comparePhaseNum, findPhaseInternal, get
 const { extractFrontmatter } = require('./frontmatter.cjs');
 const { writeStateMd, readStateSafe } = require('./state.cjs');
 const { enumerateRoadmapPhases } = require('./roadmap.cjs');
-const { PLANNING_DIR, PHASES_DIR, ROADMAP_FILE, REQUIREMENTS_FILE, STATE_FILE, isPlanFile, isSummaryFile, getPlanId, PHASE_DIR_RE, ARCHIVE_DIR_RE } = require('./constants.cjs');
-const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles, parsePhaseDir, fileAccessible } = require('./utils.cjs');
+const { PHASES_DIR, ROADMAP_FILE, REQUIREMENTS_FILE, STATE_FILE, isPlanFile, isSummaryFile, getPlanId, PHASE_DIR_RE, ARCHIVE_DIR_RE } = require('./constants.cjs');
+const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles, parsePhaseDir, fileAccessible, planningRel } = require('./utils.cjs');
 // Phase removal lives in phase-remove.cjs; re-exported below so consumers of
 // phase.cjs are unaffected by the decomposition.
 const { removePhaseFromDisk, renumberDecimalPhases, renumberIntegerPhases, updateRoadmapAfterRemoval, cmdPhaseRemove } = require('./phase-remove.cjs');
@@ -218,7 +218,7 @@ function cmdFindPhase(cwd, phase, raw) {
 
     const result = {
       found: true,
-      directory: toPosix(path.join(PLANNING_DIR, PHASES_DIR, match)),
+      directory: planningRel(PHASES_DIR, match),
       phase_number: phaseNumber,
       phase_name: phaseName,
       plans,
@@ -855,7 +855,7 @@ function cmdPhaseComplete(cwd, phaseNum, raw, opts) {
   const noCommit = opts && opts.noCommit;
   if (!noCommit && isGitRepo(cwd)) {
     const commitMsg = `docs(${normalized}): complete phase — ${phaseInfo.phase_name}`;
-    execGit(cwd, ['add', PLANNING_DIR + '/']);
+    execGit(cwd, ['add', planningRel() + '/']);
     const commitResult = execGit(cwd, ['commit', '-m', commitMsg]);
     if (commitResult.exitCode === 0) {
       const hashResult = execGit(cwd, ['rev-parse', '--short', 'HEAD']);

package/pan-wizard-core/bin/lib/planning-root.cjs

@@ -0,0 +1,327 @@
+/**
+ * Planning root — resolves WHICH planning tree a pan-tools invocation acts on.
+ *
+ * Before this module every path was `path.join(cwd, '.planning', …)`, so a repo
+ * holding more than one planning tree (several products merged into one repo, a
+ * monorepo, a spike kept beside the mainline) could address exactly one of
+ * them. The other trees were not merely awkward to reach — they were
+ * unreachable, and commands did not say so. `hygiene scan` reported "clean"
+ * while a sibling track sat three times over its trace retention, because it
+ * had looked at the wrong directory and had no vocabulary for saying which one.
+ *
+ * The rule this module encodes: a command may operate on a tree other than
+ * `.planning/`, but it must always be able to name the tree it chose. Every
+ * resolution carries its `source`, and callers surface it, so a wrong target is
+ * visible in the output instead of being indistinguishable from a right one.
+ *
+ * Resolution precedence, highest first:
+ *   1. explicit override      — `--planning-dir <path>` / `--track <name>`
+ *   2. PAN_PLANNING_DIR env   — a project-relative path
+ *   3. PAN_TRACK env          — a track name under `.planning/tracks/`
+ *   4. default                — `.planning`
+ *
+ * Roots are always stored project-relative and POSIX-separated: they are used
+ * both to build absolute paths and, verbatim, as the display paths in command
+ * output and `git add` arguments.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** The planning tree every project has unless told otherwise. */
+const DEFAULT_PLANNING_DIR = '.planning';
+
+/** Directory under the default root that holds sibling planning trees. */
+const TRACKS_DIR = 'tracks';
+
+/**
+ * Files/dirs that mark a directory as a real planning tree rather than an
+ * incidental folder. Mirrors the hygiene "spine" test: the phase model, the
+ * focus model, or an orchestration campaign.
+ */
+const PLANNING_SPINE = [
+  'state.md', 'roadmap.md', 'project.md', 'requirements.md',
+  'phases', 'milestones', 'focus', 'quick', 'orchestration', 'config.json',
+];
+
+/** Explicit override set by the CLI, or null. @type {{rel: string, source: string, track: string|null}|null} */
+let override = null;
+
+/**
+ * Normalize a project-relative planning path to POSIX form, rejecting anything
+ * that escapes the project root.
+ *
+ * @param {string} input - candidate path, relative to the project root
+ * @param {string} label - flag/env name, for error text
+ * @returns {string} normalized POSIX-relative path
+ * @throws {Error} if absolute, empty, or containing a `..` segment
+ */
+function normalizeRoot(input, label) {
+  const value = String(input == null ? '' : input).trim();
+  if (!value) throw new Error(`${label}: missing value`);
+
+  // Reject absolute paths on both platforms, plus Windows drive-relative
+  // ("C:foo") and UNC forms. Checked inline rather than via a helper: static
+  // analysis does not follow guards across function boundaries, and this is
+  // the barrier that keeps a planning root inside the project.
+  if (value.startsWith('/') || value.startsWith('\\')) {
+    throw new Error(`${label}: must be relative to the project root, got absolute path "${value}"`);
+  }
+  if (/^[A-Za-z]:/.test(value)) {
+    throw new Error(`${label}: must be relative to the project root, got drive path "${value}"`);
+  }
+
+  const segments = value.split(/[\\/]+/).filter(s => s && s !== '.');
+  if (segments.length === 0) throw new Error(`${label}: missing value`);
+  if (segments.includes('..')) {
+    throw new Error(`${label}: must stay inside the project root, got "${value}"`);
+  }
+  return segments.join('/');
+}
+
+/**
+ * Validate a track name. Track names become a single path segment, so they are
+ * restricted to a slug alphabet — this is the barrier against traversal via
+ * `--track ../../etc`, and it is deliberately stricter than normalizeRoot.
+ *
+ * @param {string} name
+ * @returns {string} the validated name
+ * @throws {Error} if the name is empty or not a plain slug
+ */
+function normalizeTrackName(name) {
+  const value = String(name == null ? '' : name).trim();
+  if (!value) throw new Error('--track: missing value');
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value)) {
+    throw new Error(`--track: "${value}" is not a valid track name (letters, digits, dot, dash, underscore)`);
+  }
+  return value;
+}
+
+/**
+ * Project-relative path of a named track's planning tree.
+ * @param {string} name - track name
+ * @returns {string} e.g. `.planning/tracks/verify`
+ */
+function trackRel(name) {
+  return [DEFAULT_PLANNING_DIR, TRACKS_DIR, normalizeTrackName(name)].join('/');
+}
+
+/**
+ * Set the planning root explicitly. Called by the CLI once, before dispatch.
+ *
+ * @param {Object} opts
+ * @param {string} [opts.planningDir] - project-relative path (`--planning-dir`)
+ * @param {string} [opts.track] - track name (`--track`)
+ * @returns {{rel: string, source: string, track: string|null}|null} the resolution
+ */
+function setPlanningRoot({ planningDir, track } = {}) {
+  if (planningDir && track) {
+    throw new Error('--planning-dir and --track are mutually exclusive');
+  }
+  if (track) {
+    const name = normalizeTrackName(track);
+    override = { rel: trackRel(name), source: 'flag:--track', track: name };
+  } else if (planningDir) {
+    override = { rel: normalizeRoot(planningDir, '--planning-dir'), source: 'flag:--planning-dir', track: null };
+  } else {
+    override = null;
+  }
+  return override;
+}
+
+/** Drop any explicit override, returning to env/default resolution. */
+function clearPlanningRoot() {
+  override = null;
+}
+
+/**
+ * Run `fn` with the planning root pinned to `rel`, then restore the previous
+ * resolution — always, including on throw.
+ *
+ * This exists for the one job that genuinely needs it: sweeping several trees
+ * in a single invocation (`hygiene --all-tracks`). The alternative, threading a
+ * root argument through every check, would stop at the module boundary — the
+ * checks call into memory.cjs and cost.cjs, which resolve the root themselves.
+ * Scoping the ambient root is what makes those downstream readers follow the
+ * sweep instead of all reporting on `.planning/`.
+ *
+ * Synchronous only. Do not await inside `fn`: overlapping scopes would
+ * interleave and the restore would land on the wrong value.
+ *
+ * @param {string} rel - project-relative planning root to pin
+ * @param {Function} fn - synchronous callback
+ * @param {string|null} [track] - track name this root belongs to, so anything
+ *   reporting from inside the scope (describePlanningRoot, and every payload
+ *   that spreads it) names the right tree rather than defaulting to null
+ * @returns {*} whatever `fn` returns
+ */
+function withPlanningRoot(rel, fn, track = null) {
+  const previous = override;
+  override = { rel: normalizeRoot(rel, 'planning root'), source: 'scoped', track: track || null };
+  try {
+    return fn();
+  } finally {
+    override = previous;
+  }
+}
+
+/**
+ * Resolve the active planning root.
+ *
+ * Env vars are read on every call rather than cached at load, so a host that
+ * sets them late (and every test that does) sees the change.
+ *
+ * @returns {{rel: string, source: string, track: string|null}}
+ */
+function resolvePlanningRoot() {
+  if (override) return { ...override };
+
+  const envDir = process.env.PAN_PLANNING_DIR;
+  if (envDir && envDir.trim()) {
+    return { rel: normalizeRoot(envDir, 'PAN_PLANNING_DIR'), source: 'env:PAN_PLANNING_DIR', track: null };
+  }
+
+  const envTrack = process.env.PAN_TRACK;
+  if (envTrack && envTrack.trim()) {
+    const name = normalizeTrackName(envTrack);
+    return { rel: trackRel(name), source: 'env:PAN_TRACK', track: name };
+  }
+
+  return { rel: DEFAULT_PLANNING_DIR, source: 'default', track: null };
+}
+
+/**
+ * Active planning root, project-relative and POSIX-separated.
+ * This is the value that replaces the old `PLANNING_DIR` constant at call sites.
+ * @returns {string}
+ */
+function planningRootRel() {
+  return resolvePlanningRoot().rel;
+}
+
+/**
+ * Absolute path of the active planning root.
+ * @param {string} cwd - project root
+ * @returns {string}
+ */
+function planningRootAbs(cwd) {
+  return path.join(cwd, ...planningRootRel().split('/'));
+}
+
+/**
+ * Does this directory look like a planning tree (as opposed to any old folder)?
+ * @param {string} abs - absolute directory path
+ * @returns {boolean}
+ */
+function isPlanningTree(abs) {
+  let entries;
+  try { entries = fs.readdirSync(abs); } catch { return false; }
+  const lower = entries.map(e => e.toLowerCase());
+  return PLANNING_SPINE.some(s => lower.includes(s));
+}
+
+/**
+ * Discover sibling planning trees under `.planning/tracks/`.
+ *
+ * Only directories that pass isPlanningTree() are returned — an empty or
+ * incidental folder under tracks/ is not a track, and silently treating one as
+ * a track would reintroduce the very "operated on the wrong thing" failure this
+ * module exists to prevent.
+ *
+ * @param {string} cwd - project root
+ * @returns {Array<{name: string, rel: string, abs: string}>} sorted by name
+ */
+function discoverTracks(cwd) {
+  const tracksAbs = path.join(cwd, DEFAULT_PLANNING_DIR, TRACKS_DIR);
+  let entries = [];
+  try { entries = fs.readdirSync(tracksAbs, { withFileTypes: true }); } catch { return []; }
+
+  const tracks = [];
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    let name;
+    try { name = normalizeTrackName(e.name); } catch { continue; }
+    const abs = path.join(tracksAbs, name);
+    if (!isPlanningTree(abs)) continue;
+    tracks.push({ name, rel: [DEFAULT_PLANNING_DIR, TRACKS_DIR, name].join('/'), abs });
+  }
+  tracks.sort((a, b) => a.name.localeCompare(b.name));
+  return tracks;
+}
+
+/**
+ * Every planning root a command should act on.
+ *
+ * Without `allTracks` this is exactly the resolved root — one tree, the one the
+ * user asked for. With it, the default root (when it is a real tree) plus every
+ * discovered track, each labelled, so aggregate output can attribute findings.
+ *
+ * @param {string} cwd - project root
+ * @param {Object} [opts]
+ * @param {boolean} [opts.allTracks] - include every discovered track
+ * @returns {Array<{name: string|null, rel: string, abs: string, source: string}>}
+ */
+function planningRoots(cwd, opts = {}) {
+  const resolved = resolvePlanningRoot();
+
+  if (!opts.allTracks) {
+    return [{
+      name: resolved.track,
+      rel: resolved.rel,
+      abs: path.join(cwd, ...resolved.rel.split('/')),
+      source: resolved.source,
+    }];
+  }
+
+  const roots = [];
+  const rootAbs = path.join(cwd, DEFAULT_PLANNING_DIR);
+  if (isPlanningTree(rootAbs)) {
+    roots.push({ name: null, rel: DEFAULT_PLANNING_DIR, abs: rootAbs, source: 'all-tracks' });
+  }
+  for (const t of discoverTracks(cwd)) {
+    roots.push({ name: t.name, rel: t.rel, abs: t.abs, source: 'all-tracks' });
+  }
+  // A project with no tracks and no root spine still gets one root to act on,
+  // so --all-tracks never silently does nothing.
+  if (roots.length === 0) {
+    roots.push({ name: null, rel: DEFAULT_PLANNING_DIR, abs: rootAbs, source: 'all-tracks' });
+  }
+  return roots;
+}
+
+/**
+ * Human/machine-readable description of the active root, for command output.
+ * @param {string} cwd - project root
+ * @returns {{planning_root: string, track: string|null, planning_root_source: string, planning_root_exists: boolean}}
+ */
+function describePlanningRoot(cwd) {
+  const resolved = resolvePlanningRoot();
+  const abs = path.join(cwd, ...resolved.rel.split('/'));
+  let exists = false;
+  try { exists = fs.statSync(abs).isDirectory(); } catch { /* absent */ }
+  return {
+    planning_root: resolved.rel,
+    track: resolved.track,
+    planning_root_source: resolved.source,
+    planning_root_exists: exists,
+  };
+}
+
+module.exports = {
+  DEFAULT_PLANNING_DIR,
+  TRACKS_DIR,
+  PLANNING_SPINE,
+  normalizeRoot,
+  normalizeTrackName,
+  trackRel,
+  setPlanningRoot,
+  clearPlanningRoot,
+  withPlanningRoot,
+  resolvePlanningRoot,
+  planningRootRel,
+  planningRootAbs,
+  isPlanningTree,
+  discoverTracks,
+  planningRoots,
+  describePlanningRoot,
+};

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

@@ -22,7 +22,6 @@ const {
   toPosix,
 } = require('./core.cjs');
 const {
-  PLANNING_DIR,
   ROADMAP_FILE,
   STATE_FILE,
   PHASES_DIR,

package/pan-wizard-core/bin/lib/review-deep.cjs

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

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

@@ -4,7 +4,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { PLANNING_DIR, PHASES_DIR, ROADMAP_FILE, REQUIREMENTS_FILE, isPlanFile, isSummaryFile, isContextFile, isResearchFile, PHASE_HEADER_RE, getPlanId, getSummaryId } = require('./constants.cjs');
+const { PHASES_DIR, ROADMAP_FILE, REQUIREMENTS_FILE, isPlanFile, isSummaryFile, isContextFile, isResearchFile, PHASE_HEADER_RE, getPlanId, getSummaryId } = require('./constants.cjs');
 const { planningPath, phasesPath, filterPlanFiles, filterSummaryFiles, classifyPhaseStatus } = require('./utils.cjs');
 const { escapeRegex, normalizePhaseName, output, error, findPhaseInternal } = require('./core.cjs');