@ktpartners/dgs-platform 2.6.2

package/deliver-great-systems/bin/lib/context.cjs

@@ -0,0 +1,929 @@
+/**
+ * Context -- Context tier engine for DGS workflow context loading
+ *
+ * Parses tier definitions from references/context-tiers.md (YAML code blocks)
+ * and resolves file lists against the current project's planning root.
+ * Handles scope flags (--phase, --idea, --spec) for context enrichment.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { safeReadFile, loadConfig, output, error, findPhaseInternal, getMilestoneInfo, getMilestonePhaseFilter, toPosixPath } = require('./core.cjs');
+const { getPlanningRoot } = require('./paths.cjs');
+
+// ─── Tier Definition Cache ──────────────────────────────────────────────────
+
+/** @type {Map<string, Object>|null} */
+let _tierCache = null;
+
+// ─── YAML Parsing ───────────────────────────────────────────────────────────
+
+/**
+ * Lightweight YAML parser for our controlled schema.
+ * Handles key: value, arrays (- item), nested objects, and multi-line
+ * object items in arrays. Does NOT support full YAML spec -- only the
+ * subset used in context-tiers.md.
+ *
+ * Strategy: Build a flat list of {indent, type, key, value} tokens,
+ * then assemble into a tree structure.
+ *
+ * @param {string} yamlText - Raw YAML text from a code block
+ * @returns {Object} Parsed object
+ */
+function parseSimpleYaml(yamlText) {
+  const lines = yamlText.split('\n');
+  return parseYamlBlock(lines, 0, lines.length, 0);
+}
+
+/**
+ * Parse a block of YAML lines at a given indent level.
+ *
+ * @param {string[]} lines - All lines
+ * @param {number} start - Start line index
+ * @param {number} end - End line index (exclusive)
+ * @param {number} baseIndent - Expected indent level for this block
+ * @returns {Object} Parsed object
+ */
+function parseYamlBlock(lines, start, end, baseIndent) {
+  const result = {};
+  let i = start;
+
+  while (i < end) {
+    const line = lines[i];
+    const trimmed = line.trimEnd();
+    if (trimmed === '' || trimmed.trimStart().startsWith('#')) {
+      i++;
+      continue;
+    }
+
+    const indent = line.length - line.trimStart().length;
+    if (indent < baseIndent) break; // Dedent -- end of this block
+    if (indent > baseIndent) {
+      i++; // Skip unexpected extra-indented lines
+      continue;
+    }
+
+    const stripped = trimmed.trim();
+
+    // Array item at this indent level (shouldn't happen at top level in our schema)
+    if (stripped.startsWith('- ')) {
+      i++;
+      continue;
+    }
+
+    // Key: value pair
+    const kvMatch = stripped.match(/^([\w_]+):\s*(.*)/);
+    if (!kvMatch) {
+      i++;
+      continue;
+    }
+
+    const key = kvMatch[1];
+    const rawValue = kvMatch[2].trim();
+    i++;
+
+    // Check what follows at deeper indent
+    const childIndent = baseIndent + 2;
+    const childStart = i;
+
+    // Peek ahead to see if there are child lines
+    let hasChildren = false;
+    if (i < end) {
+      const nextLine = lines[i];
+      const nextTrimmed = nextLine.trimEnd();
+      if (nextTrimmed !== '' && !nextTrimmed.trimStart().startsWith('#')) {
+        const nextIndent = nextLine.length - nextLine.trimStart().length;
+        if (nextIndent >= childIndent) {
+          hasChildren = true;
+        }
+      }
+    }
+
+    if (!hasChildren) {
+      // Simple scalar, inline array, or empty
+      result[key] = parseYamlValue(rawValue);
+      continue;
+    }
+
+    // Has children -- determine if it's an array or object
+    const firstChildLine = lines[i].trimStart();
+    if (firstChildLine.startsWith('- ')) {
+      // Array
+      result[key] = parseYamlArray(lines, i, end, childIndent);
+      // Skip past all child lines
+      while (i < end) {
+        const ln = lines[i];
+        const tr = ln.trimEnd();
+        if (tr === '' || tr.trimStart().startsWith('#')) { i++; continue; }
+        const ind = ln.length - ln.trimStart().length;
+        if (ind < childIndent) break;
+        i++;
+      }
+    } else {
+      // Nested object
+      const childEnd = findBlockEnd(lines, i, end, childIndent);
+      result[key] = parseYamlBlock(lines, i, childEnd, childIndent);
+      i = childEnd;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Parse an array starting at the given position.
+ *
+ * @param {string[]} lines - All lines
+ * @param {number} start - Start line index (first array item)
+ * @param {number} end - End line index (exclusive)
+ * @param {number} itemIndent - Indent level of array items (the "- " prefix)
+ * @returns {Array} Parsed array
+ */
+function parseYamlArray(lines, start, end, itemIndent) {
+  const result = [];
+  let i = start;
+
+  while (i < end) {
+    const line = lines[i];
+    const trimmed = line.trimEnd();
+    if (trimmed === '' || trimmed.trimStart().startsWith('#')) {
+      i++;
+      continue;
+    }
+
+    const indent = line.length - line.trimStart().length;
+    if (indent < itemIndent) break; // Dedent
+
+    const stripped = trimmed.trim();
+
+    if (indent === itemIndent && stripped.startsWith('- ')) {
+      // New array item
+      const itemContent = stripped.slice(2).trim();
+      const itemKv = itemContent.match(/^([\w_]+):\s*(.*)/);
+
+      if (itemKv) {
+        // Object item (e.g., "- path: ...")
+        const obj = {};
+        obj[itemKv[1]] = parseYamlScalar(itemKv[2].trim());
+
+        // Look ahead for continuation lines (same object, deeper indent)
+        i++;
+        const contIndent = itemIndent + 2;
+        while (i < end) {
+          const contLine = lines[i];
+          const contTrimmed = contLine.trimEnd();
+          if (contTrimmed === '' || contTrimmed.trimStart().startsWith('#')) { i++; continue; }
+          const contInd = contLine.length - contLine.trimStart().length;
+          if (contInd < contIndent) break;
+          if (contInd === contIndent) {
+            const contKv = contTrimmed.trim().match(/^([\w_]+):\s*(.*)/);
+            if (contKv) {
+              obj[contKv[1]] = parseYamlScalar(contKv[2].trim());
+              i++;
+              continue;
+            }
+          }
+          break;
+        }
+
+        result.push(obj);
+      } else {
+        // Simple scalar item
+        result.push(parseYamlScalar(itemContent));
+        i++;
+      }
+    } else {
+      i++; // Skip unexpected lines
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Find the end of a block at the given indent level.
+ *
+ * @param {string[]} lines - All lines
+ * @param {number} start - Start position
+ * @param {number} end - Maximum end
+ * @param {number} minIndent - Minimum indent that belongs to this block
+ * @returns {number} Line index where block ends
+ */
+function findBlockEnd(lines, start, end, minIndent) {
+  let i = start;
+  while (i < end) {
+    const line = lines[i];
+    const trimmed = line.trimEnd();
+    if (trimmed === '' || trimmed.trimStart().startsWith('#')) {
+      i++;
+      continue;
+    }
+    const indent = line.length - line.trimStart().length;
+    if (indent < minIndent) break;
+    i++;
+  }
+  return i;
+}
+
+/**
+ * Parse a YAML value string (inline).
+ *
+ * @param {string} raw - Raw value text
+ * @returns {*} Parsed value (scalar, array, or empty object)
+ */
+function parseYamlValue(raw) {
+  if (raw === '' || raw === undefined) return null;
+  if (raw === '{}') return {};
+  if (raw === '[]') return [];
+  // Inline array: [item1, item2]
+  if (raw.startsWith('[') && raw.endsWith(']')) {
+    const inner = raw.slice(1, -1).trim();
+    if (inner === '') return [];
+    return inner.split(',').map(s => s.trim().replace(/^["']|["']$/g, ''));
+  }
+  return parseYamlScalar(raw);
+}
+
+/**
+ * Parse a YAML scalar value.
+ *
+ * @param {string} raw - Raw scalar text
+ * @returns {string|number|boolean|null}
+ */
+function parseYamlScalar(raw) {
+  if (raw === 'null' || raw === '~') return null;
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+  // Strip quotes
+  if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) {
+    return raw.slice(1, -1);
+  }
+  // Numbers
+  if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw);
+  return raw;
+}
+
+// ─── Tier Definition Parsing ────────────────────────────────────────────────
+
+/**
+ * Parse tier definitions from references/context-tiers.md.
+ * Extracts YAML code blocks between ``` markers within each ## Tier section.
+ * Results are cached after first parse within the process.
+ *
+ * @returns {Map<string, Object>} Map of tier name to parsed tier definition
+ */
+function parseTierDefinitions() {
+  if (_tierCache) return _tierCache;
+
+  const tiersPath = path.resolve(__dirname, '..', '..', 'references', 'context-tiers.md');
+  const content = safeReadFile(tiersPath);
+  if (!content) {
+    _tierCache = new Map();
+    return _tierCache;
+  }
+
+  const tiers = new Map();
+  // Find all yaml code blocks
+  const yamlBlockPattern = /```yaml\n([\s\S]*?)```/g;
+  let match;
+  while ((match = yamlBlockPattern.exec(content)) !== null) {
+    const parsed = parseSimpleYaml(match[1]);
+    if (parsed.tier) {
+      tiers.set(parsed.tier, parsed);
+    }
+  }
+
+  _tierCache = tiers;
+  return _tierCache;
+}
+
+/**
+ * Reset the tier definition cache. Used for testing.
+ */
+function resetTierCache() {
+  _tierCache = null;
+}
+
+// ─── File Resolution ────────────────────────────────────────────────────────
+
+/**
+ * Resolve the flat list of static files for a tier, including inherited files.
+ *
+ * @param {string} tierName - Tier name (none, lite, planning, execution, verification)
+ * @param {Map<string, Object>} tiers - Parsed tier definitions
+ * @returns {Array<{path: string, category: string}>} Static file entries
+ */
+function resolveTierFiles(tierName, tiers) {
+  const tier = tiers.get(tierName);
+  if (!tier) return [];
+
+  let files = [];
+
+  // Recursively include inherited tier files
+  if (tier.includes_tier && tier.includes_tier !== 'null' && tiers.has(tier.includes_tier)) {
+    files = resolveTierFiles(tier.includes_tier, tiers);
+  }
+
+  // Add this tier's own static files
+  if (Array.isArray(tier.files)) {
+    for (const entry of tier.files) {
+      if (entry && typeof entry === 'object' && entry.path) {
+        files.push({ path: entry.path, category: entry.category || 'general' });
+      }
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Resolve dynamic file rules (glob patterns) against the planning root.
+ * Uses recursive readdirSync for glob matching -- no external library.
+ *
+ * @param {Array<Object>} dynamicRules - Dynamic rules from tier definition
+ * @param {string} planningRoot - Absolute path to planning root
+ * @returns {Array<{path: string, category: string}>} Resolved file entries
+ */
+function resolveDynamicFiles(dynamicRules, planningRoot) {
+  if (!Array.isArray(dynamicRules) || dynamicRules.length === 0) return [];
+
+  const results = [];
+  for (const rule of dynamicRules) {
+    if (!rule || rule.type !== 'glob' || !rule.pattern) continue;
+
+    const category = rule.category || 'dynamic';
+    const matched = globMatch(planningRoot, rule.pattern);
+    for (const filePath of matched) {
+      results.push({ path: filePath, category });
+    }
+  }
+  return results;
+}
+
+/**
+ * Simple glob matching using recursive readdirSync.
+ * Supports patterns like "codebase/ ** /*.md" and "UAT*.md".
+ *
+ * @param {string} baseDir - Base directory to search from
+ * @param {string} pattern - Glob pattern (relative to baseDir)
+ * @returns {string[]} Matched file paths relative to baseDir
+ */
+function globMatch(baseDir, pattern) {
+  const results = [];
+
+  // Handle ** patterns (recursive)
+  if (pattern.includes('**')) {
+    const parts = pattern.split('**');
+    const prefix = parts[0].replace(/\/$/, '');
+    const suffix = (parts[1] || '').replace(/^\//, '');
+    const searchDir = prefix ? path.join(baseDir, prefix) : baseDir;
+
+    if (!fs.existsSync(searchDir)) return results;
+
+    const allFiles = readdirRecursive(searchDir);
+    const suffixPattern = globToRegex(suffix);
+
+    for (const file of allFiles) {
+      if (suffixPattern.test(file)) {
+        const relPath = prefix ? toPosixPath(path.join(prefix, file)) : toPosixPath(file);
+        results.push(relPath);
+      }
+    }
+    return results;
+  }
+
+  // Handle simple wildcard patterns (e.g., "UAT*.md")
+  if (pattern.includes('*')) {
+    const dir = path.dirname(pattern);
+    const filePattern = path.basename(pattern);
+    const searchDir = dir === '.' ? baseDir : path.join(baseDir, dir);
+
+    if (!fs.existsSync(searchDir)) return results;
+
+    try {
+      const entries = fs.readdirSync(searchDir);
+      const regex = globToRegex(filePattern);
+      for (const entry of entries) {
+        if (regex.test(entry)) {
+          const fullPath = path.join(searchDir, entry);
+          try {
+            if (fs.statSync(fullPath).isFile()) {
+              const relPath = dir === '.' ? entry : toPosixPath(path.join(dir, entry));
+              results.push(relPath);
+            }
+          } catch {}
+        }
+      }
+    } catch {}
+    return results;
+  }
+
+  // No wildcards -- just check if file exists
+  if (fs.existsSync(path.join(baseDir, pattern))) {
+    results.push(toPosixPath(pattern));
+  }
+  return results;
+}
+
+/**
+ * Convert a simple glob pattern to a RegExp.
+ * Supports * (any chars except /) and *.ext patterns.
+ *
+ * @param {string} pattern - Glob pattern
+ * @returns {RegExp}
+ */
+function globToRegex(pattern) {
+  if (!pattern) return /^.*$/;
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  const regexStr = escaped.replace(/\*/g, '[^/]*');
+  return new RegExp('^' + regexStr + '$');
+}
+
+/**
+ * Recursively list all files in a directory.
+ *
+ * @param {string} dir - Directory to scan
+ * @param {string} [prefix=''] - Path prefix for relative results
+ * @returns {string[]} Relative file paths
+ */
+function readdirRecursive(dir, prefix) {
+  const results = [];
+  prefix = prefix || '';
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const relPath = prefix ? prefix + '/' + entry.name : entry.name;
+      if (entry.isDirectory()) {
+        results.push(...readdirRecursive(path.join(dir, entry.name), relPath));
+      } else if (entry.isFile()) {
+        results.push(relPath);
+      }
+    }
+  } catch {}
+  return results;
+}
+
+// ─── Scope Resolution ───────────────────────────────────────────────────────
+
+/**
+ * Resolve phase-scoped files for the --phase flag.
+ * Includes CONTEXT.md, RESEARCH.md, all PLANs and SUMMARYs from the phase,
+ * plus all SUMMARYs from completed phases in the current milestone.
+ *
+ * @param {string|number} phaseNum - Phase number
+ * @param {string} planningRoot - Absolute path to planning root
+ * @param {string} cwd - Working directory
+ * @returns {Array<{path: string, category: string}>} Phase-scoped file entries
+ */
+function resolvePhaseScope(phaseNum, planningRoot, cwd) {
+  const results = [];
+  const phaseInfo = findPhaseInternal(cwd, phaseNum);
+  if (!phaseInfo || !phaseInfo.found) return results;
+
+  const phaseDir = phaseInfo.directory;
+
+  // Add phase-specific files
+  const contextPath = path.join(phaseDir, phaseInfo.phase_number + '-CONTEXT.md');
+  results.push({ path: toPosixPath(contextPath), category: 'phase' });
+
+  const researchPath = path.join(phaseDir, phaseInfo.phase_number + '-RESEARCH.md');
+  results.push({ path: toPosixPath(researchPath), category: 'phase' });
+
+  // Add all PLANs
+  if (Array.isArray(phaseInfo.plans)) {
+    for (const plan of phaseInfo.plans) {
+      results.push({ path: toPosixPath(path.join(phaseDir, plan)), category: 'phase-plan' });
+    }
+  }
+
+  // Add all SUMMARYs from this phase
+  if (Array.isArray(phaseInfo.summaries)) {
+    for (const summary of phaseInfo.summaries) {
+      results.push({ path: toPosixPath(path.join(phaseDir, summary)), category: 'phase-summary' });
+    }
+  }
+
+  // Add all SUMMARYs from completed phases in the current milestone (not capped)
+  const milestoneSummaries = getMilestoneSummaries(cwd, planningRoot, phaseNum);
+  for (const entry of milestoneSummaries) {
+    results.push(entry);
+  }
+
+  return results;
+}
+
+/**
+ * Get all SUMMARY.md files from completed phases in the current milestone.
+ * Per user decision: ALL summaries included, not capped at 3.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} planningRoot - Absolute path to planning root
+ * @param {string|number} currentPhaseNum - Current phase number (to exclude)
+ * @returns {Array<{path: string, category: string}>}
+ */
+function getMilestoneSummaries(cwd, planningRoot, currentPhaseNum) {
+  const results = [];
+  const isDirInMilestone = getMilestonePhaseFilter(cwd);
+
+  // Scan phases directory for milestone phases with summaries
+  let projectRoot;
+  try {
+    const { getProjectRoot } = require('./core.cjs');
+    projectRoot = getProjectRoot(cwd);
+  } catch {
+    projectRoot = path.relative(cwd, planningRoot) || '.planning';
+  }
+
+  const phasesDir = path.join(cwd, projectRoot, 'phases');
+  if (!fs.existsSync(phasesDir)) return results;
+
+  try {
+    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+    const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort();
+
+    const currentNum = String(currentPhaseNum).replace(/^0+/, '') || '0';
+
+    for (const dir of dirs) {
+      // Check if this phase is in the current milestone
+      if (!isDirInMilestone(dir)) continue;
+
+      // Extract phase number from directory name
+      const dirMatch = dir.match(/^0*(\d+[A-Za-z]?(?:\.\d+)*)/);
+      if (!dirMatch) continue;
+      const dirPhaseNum = dirMatch[1];
+
+      // Skip the current phase
+      if (dirPhaseNum === currentNum) continue;
+
+      // Look for SUMMARY files in this phase
+      const phasePath = path.join(phasesDir, dir);
+      try {
+        const phaseFiles = fs.readdirSync(phasePath);
+        const summaries = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
+        for (const summary of summaries) {
+          const relPath = toPosixPath(path.join(projectRoot, 'phases', dir, summary));
+          results.push({ path: relPath, category: 'milestone-summary' });
+        }
+      } catch {}
+    }
+  } catch {}
+
+  return results;
+}
+
+/**
+ * Resolve idea-scoped files for the --idea flag.
+ * Searches pending, done, rejected, consolidated directories.
+ *
+ * @param {string|number} ideaId - Idea ID or filename
+ * @param {string} planningRoot - Absolute path to planning root
+ * @param {string} [cwd] - Working directory for relative path resolution (defaults to process.cwd())
+ * @returns {Array<{path: string, category: string}>}
+ */
+function resolveIdeaScope(ideaId, planningRoot, cwd) {
+  const results = [];
+  if (!ideaId) return results;
+
+  const idStr = String(ideaId).replace(/^0+/, '') || '0';
+  const paddedId = String(parseInt(idStr, 10)).padStart(3, '0');
+  const planRootRel = path.relative(cwd || process.cwd(), planningRoot) || '.';
+
+  const ideaStates = ['pending', 'done', 'rejected', 'consolidated'];
+
+  for (const state of ideaStates) {
+    const dir = path.join(planningRoot, 'ideas', state);
+    let files;
+    try {
+      files = fs.readdirSync(dir).filter(f => f.endsWith('.md'));
+    } catch {
+      continue;
+    }
+
+    for (const file of files) {
+      // Match by ID prefix (e.g., "005-some-idea.md")
+      if (file.startsWith(paddedId + '-') || file === ideaId || file === ideaId + '.md') {
+        const relPath = toPosixPath(path.join(planRootRel, 'ideas', state, file));
+        results.push({ path: relPath, category: 'idea' });
+
+        // Check for docs/ directory alongside the idea
+        // Idea docs/ is at ideas/<state>/<idea-slug>/docs/ where idea-slug matches the filename stem
+        const stem = file.replace(/\.md$/, '');
+        const docsDir = path.join(dir, stem, 'docs');
+        if (fs.existsSync(docsDir)) {
+          const docFiles = readdirRecursive(docsDir);
+          for (const docFile of docFiles) {
+            const docRelPath = toPosixPath(path.join(planRootRel, 'ideas', state, stem, 'docs', docFile));
+            results.push({ path: docRelPath, category: 'idea-docs' });
+          }
+        }
+
+        // Also check docs/ directly under the ideas state dir named by idea slug
+        const altDocsDir = path.join(planningRoot, 'ideas', state, 'docs');
+        // This is less common, skip unless the first pattern doesn't exist
+
+        return results; // Found the idea, stop searching
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Resolve spec-scoped files for the --spec flag.
+ * For approved specs, truncates content to frontmatter + sections 1-3 only.
+ *
+ * @param {string|number} specId - Spec ID or filename
+ * @param {string} planningRoot - Absolute path to planning root
+ * @param {string} [cwd] - Working directory for relative path resolution (defaults to process.cwd())
+ * @returns {{files: Array<{path: string, category: string}>, approved_truncated: boolean}}
+ */
+function resolveSpecScope(specId, planningRoot, cwd) {
+  const results = [];
+  let approvedTruncated = false;
+
+  if (!specId) return { files: results, approved_truncated: approvedTruncated };
+
+  const specsDir = path.join(planningRoot, 'specs');
+  const planRootRel = path.relative(cwd || process.cwd(), planningRoot) || '.';
+
+  let files;
+  try {
+    files = fs.readdirSync(specsDir).filter(f => f.endsWith('.md'));
+  } catch {
+    return { files: results, approved_truncated: approvedTruncated };
+  }
+
+  const searchLower = String(specId).toLowerCase();
+
+  for (const file of files) {
+    const fileLower = file.toLowerCase();
+    const matchById = fileLower.startsWith(searchLower + '-') ||
+                      fileLower === searchLower + '.md' ||
+                      fileLower === searchLower;
+
+    // Also check frontmatter id field
+    let matchByFrontmatterId = false;
+    let isApproved = false;
+    const fullPath = path.join(specsDir, file);
+    const content = safeReadFile(fullPath);
+
+    if (content) {
+      const fmMatch = content.match(/^---\n([\s\S]+?)\n---/);
+      if (fmMatch) {
+        const idMatch = fmMatch[1].match(/^id:\s*(.+)$/m);
+        if (idMatch && idMatch[1].trim().toLowerCase() === searchLower) {
+          matchByFrontmatterId = true;
+        }
+        const statusMatch = fmMatch[1].match(/^status:\s*(.+)$/m);
+        if (statusMatch) {
+          const status = statusMatch[1].trim().toLowerCase();
+          isApproved = status === 'approved' || status === 'final';
+        }
+      }
+    }
+
+    if (matchById || matchByFrontmatterId) {
+      const relPath = toPosixPath(path.join(planRootRel, 'specs', file));
+
+      if (isApproved) {
+        approvedTruncated = true;
+        // For approved specs: store metadata indicating truncation
+        results.push({ path: relPath, category: 'spec', truncated: true });
+      } else {
+        results.push({ path: relPath, category: 'spec' });
+      }
+
+      // Check for docs/ directory
+      const stem = file.replace(/\.md$/, '');
+      const docsDir = path.join(specsDir, stem, 'docs');
+      if (fs.existsSync(docsDir)) {
+        const docFiles = readdirRecursive(docsDir);
+        for (const docFile of docFiles) {
+          const docRelPath = toPosixPath(path.join(planRootRel, 'specs', stem, 'docs', docFile));
+          results.push({ path: docRelPath, category: 'spec-docs' });
+        }
+      }
+
+      return { files: results, approved_truncated: approvedTruncated };
+    }
+  }
+
+  return { files: results, approved_truncated: approvedTruncated };
+}
+
+/**
+ * Truncate an approved spec to frontmatter + sections 1-3 only.
+ * Sections are identified by ## headings in the body.
+ *
+ * @param {string} content - Full spec content
+ * @returns {string} Truncated content
+ */
+function truncateApprovedSpec(content) {
+  if (!content) return '';
+
+  // Extract frontmatter
+  const fmMatch = content.match(/^(---\n[\s\S]+?\n---)\n?([\s\S]*)/);
+  if (!fmMatch) return content;
+
+  const frontmatter = fmMatch[1];
+  const body = fmMatch[2] || '';
+
+  // Find section headings (## level)
+  const sectionPattern = /^##\s+/gm;
+  let sectionCount = 0;
+  let lastIndex = 0;
+  let sectionMatch;
+  let cutoffIndex = body.length;
+
+  while ((sectionMatch = sectionPattern.exec(body)) !== null) {
+    sectionCount++;
+    if (sectionCount > 3) {
+      cutoffIndex = sectionMatch.index;
+      break;
+    }
+    lastIndex = sectionMatch.index;
+  }
+
+  const truncatedBody = body.slice(0, cutoffIndex).trimEnd();
+  return frontmatter + '\n' + truncatedBody + '\n\n*[Truncated: approved spec -- showing frontmatter + sections 1-3 only]*\n';
+}
+
+// ─── Main Engine ────────────────────────────────────────────────────────────
+
+/**
+ * Load context files for a given tier with optional scope flags.
+ * This is the main engine function used by CLI and other modules.
+ *
+ * @param {string} tierName - Tier name (none, lite, planning, execution, verification)
+ * @param {string} planningRoot - Absolute path to planning root
+ * @param {Object} [options={}] - Scope options
+ * @param {string|number} [options.phase] - Phase number for --phase scope
+ * @param {string|number} [options.idea] - Idea ID for --idea scope
+ * @param {string|number} [options.spec] - Spec ID for --spec scope
+ * @param {string} [options.cwd] - Working directory (defaults to process.cwd())
+ * @returns {{files: Array<{path: string, exists: boolean, category: string}>, tier: string, scope: Object}}
+ */
+function loadTierInternal(tierName, planningRoot, options) {
+  options = options || {};
+  const cwd = options.cwd || process.cwd();
+  const tiers = parseTierDefinitions();
+
+  if (!tiers.has(tierName)) {
+    return { files: [], tier: tierName, scope: {}, error: 'Unknown tier: ' + tierName };
+  }
+
+  // 1. Resolve static files for this tier (including inherited)
+  const staticFiles = resolveTierFiles(tierName, tiers);
+
+  // 2. Resolve dynamic files for this tier (including inherited)
+  const dynamicFiles = resolveDynamicFilesForTier(tierName, tiers, planningRoot);
+
+  // 3. Resolve scope flags
+  const scopeFiles = [];
+  const scope = {};
+
+  if (options.phase) {
+    scope.phase = options.phase;
+    const phaseFiles = resolvePhaseScope(options.phase, planningRoot, cwd);
+    scopeFiles.push(...phaseFiles);
+  }
+
+  if (options.idea) {
+    scope.idea = options.idea;
+    const ideaFiles = resolveIdeaScope(options.idea, planningRoot, cwd);
+    scopeFiles.push(...ideaFiles);
+  }
+
+  if (options.spec) {
+    scope.spec = options.spec;
+    const specResult = resolveSpecScope(options.spec, planningRoot, cwd);
+    scopeFiles.push(...specResult.files);
+    if (specResult.approved_truncated) {
+      scope.spec_truncated = true;
+    }
+  }
+
+  // 4. Combine all files
+  const allEntries = [...staticFiles, ...dynamicFiles, ...scopeFiles];
+
+  // 5. Resolve paths relative to cwd and filter to existing files
+  const planRootRel = path.relative(cwd, planningRoot) || '.';
+  const seen = new Set();
+  const files = [];
+
+  for (const entry of allEntries) {
+    // Static/dynamic files are relative to planning root
+    // Scope files are already relative to cwd
+    let relPath;
+    if (entry._fromScope) {
+      relPath = entry.path;
+    } else if (entry.path.startsWith(planRootRel) || entry.path.startsWith('.planning')) {
+      // Already relative to cwd
+      relPath = entry.path;
+    } else {
+      relPath = toPosixPath(path.join(planRootRel, entry.path));
+    }
+
+    // Deduplicate
+    if (seen.has(relPath)) continue;
+    seen.add(relPath);
+
+    // Check existence
+    const absPath = path.resolve(cwd, relPath);
+    if (fs.existsSync(absPath)) {
+      const fileEntry = { path: relPath, exists: true, category: entry.category };
+      if (entry.truncated) fileEntry.truncated = true;
+      files.push(fileEntry);
+    }
+    // Missing files are silently omitted (TOOL-09)
+  }
+
+  return { files, tier: tierName, scope };
+}
+
+/**
+ * Resolve dynamic files for a tier including inherited tiers.
+ *
+ * @param {string} tierName - Tier name
+ * @param {Map<string, Object>} tiers - Parsed tier definitions
+ * @param {string} planningRoot - Absolute path to planning root
+ * @returns {Array<{path: string, category: string}>}
+ */
+function resolveDynamicFilesForTier(tierName, tiers, planningRoot) {
+  const tier = tiers.get(tierName);
+  if (!tier) return [];
+
+  let files = [];
+
+  // Recursively include inherited tier dynamic files
+  if (tier.includes_tier && tier.includes_tier !== 'null' && tiers.has(tier.includes_tier)) {
+    files = resolveDynamicFilesForTier(tier.includes_tier, tiers, planningRoot);
+  }
+
+  // Add this tier's own dynamic files
+  if (Array.isArray(tier.dynamic)) {
+    const resolved = resolveDynamicFiles(tier.dynamic, planningRoot);
+    files.push(...resolved);
+  }
+
+  return files;
+}
+
+// ─── CLI Command ────────────────────────────────────────────────────────────
+
+/**
+ * CLI command handler for `context load-tier <tierName>`.
+ * Parses CLI args for --phase, --idea, --spec flags.
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} tierName - Tier name
+ * @param {string[]} args - Remaining CLI arguments
+ * @param {boolean} raw - Raw output mode
+ */
+function cmdContextLoadTier(cwd, tierName, args, raw) {
+  if (!tierName) {
+    error('tier name required. Valid tiers: none, lite, planning, execution, verification');
+  }
+
+  const validTiers = ['none', 'lite', 'planning', 'execution', 'verification'];
+  if (!validTiers.includes(tierName)) {
+    error('invalid tier: ' + tierName + '. Valid tiers: ' + validTiers.join(', '));
+  }
+
+  // Parse scope flags from args
+  const options = { cwd };
+  if (Array.isArray(args)) {
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] === '--phase' && i + 1 < args.length) {
+        options.phase = args[++i];
+      } else if (args[i] === '--idea' && i + 1 < args.length) {
+        options.idea = args[++i];
+      } else if (args[i] === '--spec' && i + 1 < args.length) {
+        options.spec = args[++i];
+      }
+    }
+  }
+
+  const planningRoot = getPlanningRoot(cwd);
+  const result = loadTierInternal(tierName, planningRoot, options);
+
+  output(result, raw, result.files.map(f => f.path).join('\n'));
+}
+
+// ─── Exports ────────────────────────────────────────────────────────────────
+
+module.exports = {
+  loadTierInternal,
+  cmdContextLoadTier,
+  truncateApprovedSpec,
+  resetTierCache,
+  // Internal exports for testing
+  parseTierDefinitions,
+  parseSimpleYaml,
+  resolvePhaseScope,
+  resolveIdeaScope,
+  resolveSpecScope,
+  resolveTierFiles,
+  resolveDynamicFiles,
+};