@polymorphism-tech/morph-spec 6.0.0 → 7.1.0

package/src/lib/generators/context-generator.js

@@ -1,518 +1,516 @@
-/**
- * @fileoverview Context Generator - Auto-generates CONTEXT.md files
- *
- * Populates CONTEXT.md templates with real project data from:
- * - state.json (features, phases, tasks, checkpoints)
- * - config.json (project settings, Azure resources, agent config)
- * - agents.json (hierarchical agent structure)
- * - project.md (project description)
- * - standards/*.md (project-specific standards)
- *
- * @module context-generator
- */
-
-import fs from 'fs/promises';
-import path from 'path';
-import { existsSync } from 'fs';
-import { getOutputPath } from '../../core/paths/output-schema.js';
-
-/**
- * Resolve a template path: check .morph/framework/templates/ first, then framework/templates/.
- * @param {string} projectPath
- * @param {string} templatePath - relative path e.g. 'context/CONTEXT.md'
- * @returns {string|null}
- */
-function resolveTemplatePath(projectPath, templatePath) {
-  const projectLocal = path.join(projectPath, '.morph/framework/templates', templatePath);
-  if (existsSync(projectLocal)) return projectLocal;
-  const framework = path.join(projectPath, 'framework/templates', templatePath);
-  if (existsSync(framework)) return framework;
-  return null;
-}
-
-/**
- * Load project state from state.json
- * @param {string} projectPath - Root path of the project
- * @returns {Promise<Object>} Parsed state
- */
-async function loadState(projectPath) {
-  const statePath = path.join(projectPath, '.morph/state.json');
-  try {
-    const content = await fs.readFile(statePath, 'utf8');
-    return JSON.parse(content);
-  } catch (err) {
-    return { features: [], checkpoints: [] };
-  }
-}
-
-/**
- * Load project config from config.json
- * @param {string} projectPath - Root path of the project
- * @returns {Promise<Object>} Parsed config
- */
-async function loadConfig(projectPath) {
-  const configPath = path.join(projectPath, '.morph/config/config.json');
-  try {
-    const content = await fs.readFile(configPath, 'utf8');
-    return JSON.parse(content);
-  } catch (err) {
-    return null;
-  }
-}
-
-/**
- * Load agents hierarchy from agents.json
- * @param {string} projectPath - Root path of the project
- * @returns {Promise<Object>} Parsed agents config
- */
-async function loadAgents(projectPath) {
-  const agentsPath = path.join(projectPath, '.morph/framework/agents.json');
-  try {
-    const content = await fs.readFile(agentsPath, 'utf8');
-    return JSON.parse(content);
-  } catch (err) {
-    return null;
-  }
-}
-
-/**
- * Load project description from project.md
- * @param {string} projectPath - Root path of the project
- * @returns {Promise<string>} Project description
- */
-async function loadProjectDescription(projectPath) {
-  const projectMdPath = path.join(projectPath, '.morph/project.md');
-  try {
-    return await fs.readFile(projectMdPath, 'utf8');
-  } catch (err) {
-    return '';
-  }
-}
-
-/**
- * Load project-specific standards
- * @param {string} projectPath - Root path of the project
- * @returns {Promise<Array>} Array of {name, path, description}
- */
-async function loadProjectStandards(projectPath) {
-  const standardsDir = path.join(projectPath, '.morph/context');
-  try {
-    const files = await fs.readdir(standardsDir);
-    return files
-      .filter(f => f.endsWith('.md'))
-      .map(f => ({
-        name: f.replace('.md', ''),
-        path: `standards/${f}`,
-        description: null
-      }));
-  } catch (err) {
-    return [];
-  }
-}
-
-/**
- * Get nested property value from object using dot notation
- * @param {Object} obj - Object to get value from
- * @param {string} path - Dot-notation path (e.g., 'tasks.completed')
- * @returns {*} Value at path or empty string
- */
-function getNestedValue(obj, path) {
-  const keys = path.split('.');
-  let value = obj;
-
-  for (const key of keys) {
-    if (value && typeof value === 'object' && key in value) {
-      value = value[key];
-    } else {
-      return '';
-    }
-  }
-
-  return value !== null && value !== undefined ? value : '';
-}
-
-/**
- * Simple template renderer (Handlebars-like syntax)
- * @param {string} template - Template string with {{VAR}} placeholders
- * @param {Object} data - Data object with values
- * @returns {string} Rendered template
- */
-function renderTemplate(template, data) {
-  let result = template;
-
-  // Handle {{#each VAR}}...{{/each}} blocks first (before variable replacement)
-  result = result.replace(/{{#each\s+(\w+)}}([\s\S]*?){{\/each}}/g, (_, varName, itemTemplate) => {
-    const array = data[varName];
-    if (!Array.isArray(array) || array.length === 0) return '';
-
-    return array.map(item => {
-      let itemResult = itemTemplate;
-
-      // Replace all {{prop}} and {{nested.prop}} in the item template
-      itemResult = itemResult.replace(/{{([\w.]+)}}/g, (__, propPath) => {
-        return String(getNestedValue(item, propPath));
-      });
-
-      return itemResult;
-    }).join('');
-  });
-
-  // Handle {{#if VAR}}...{{/if}} blocks
-  result = result.replace(/{{#if\s+(\w+)}}([\s\S]*?){{\/if}}/g, (_, varName, content) => {
-    return data[varName] ? content : '';
-  });
-
-  // Handle {{#unless VAR}}...{{/unless}} blocks
-  result = result.replace(/{{#unless\s+(\w+)}}([\s\S]*?){{\/unless}}/g, (_, varName, content) => {
-    const value = data[varName];
-    // Check if value is falsy, empty array, or empty object
-    const isFalsy = !value ||
-                    (Array.isArray(value) && value.length === 0) ||
-                    (typeof value === 'object' && Object.keys(value).length === 0);
-    return isFalsy ? content : '';
-  });
-
-  // Replace simple {{VAR}} and {{nested.prop}} placeholders
-  result = result.replace(/{{([\w.]+)}}/g, (_, path) => {
-    return String(getNestedValue(data, path));
-  });
-
-  return result;
-}
-
-/**
- * Generate project-level CONTEXT.md
- * @param {string} projectPath - Root path of the project
- * @returns {Promise<string>} Generated CONTEXT.md content
- */
-export async function generateProjectContext(projectPath) {
-  const [state, config, agents, projectDesc, standards] = await Promise.all([
-    loadState(projectPath),
-    loadConfig(projectPath),
-    loadAgents(projectPath),
-    loadProjectDescription(projectPath),
-    loadProjectStandards(projectPath)
-  ]);
-
-  // Load template with fallback (.morph/framework/templates/ → framework/templates/)
-  const templatePath = resolveTemplatePath(projectPath, 'context/CONTEXT.md');
-
-  if (!templatePath) {
-    throw new Error('CONTEXT.md template not found in stack templates or framework/templates/');
-  }
-
-  const template = await fs.readFile(templatePath, 'utf8');
-
-  // Build data object
-  const data = {
-    PROJECT_NAME: config?.project?.name || 'Unknown Project',
-    PROJECT_TYPE: config?.project?.type || 'dotnet-nextjs',
-    PROJECT_DESCRIPTION: projectDesc || config?.project?.description || '',
-    REPOSITORY_URL: config?.project?.repository || '',
-    TIMESTAMP: new Date().toISOString(),
-
-    // Stack detection
-    DOTNET_ENABLED: config?.project?.type?.includes('dotnet') ? true : false,
-    NEXTJS_ENABLED: config?.project?.type?.includes('nextjs') ? true : false,
-    DOTNET_VERSION: '10.0',
-    EF_VERSION: '10.0',
-
-    // Azure config
-    AZURE_LOCATION: config?.azure?.location || 'eastus2',
-    CONTAINER_APPS_ENABLED: config?.azure?.resources?.containerApps?.enabled || false,
-    CONTAINER_ENV: config?.azure?.resources?.containerApps?.environment || '',
-    SQL_ENABLED: config?.azure?.resources?.sql?.enabled || false,
-    SQL_SERVER: config?.azure?.resources?.sql?.server || '',
-    SQL_DATABASE: config?.azure?.resources?.sql?.database || '',
-    OPENAI_ENABLED: config?.azure?.resources?.openai?.enabled || false,
-    OPENAI_MODEL: config?.azure?.resources?.openai?.model || '',
-    MONITORING_ENABLED: config?.azure?.resources?.monitoring?.enabled || false,
-    APP_INSIGHTS: config?.azure?.resources?.monitoring?.appInsights || '',
-
-    // Active features (convert object to array if needed)
-    ACTIVE_FEATURES: (Array.isArray(state?.features)
-      ? state.features
-      : Object.entries(state?.features || {}).map(([name, data]) => ({ name, ...data }))
-    ).map(f => ({
-      name: f.name,
-      phase: f.phase,
-      status: f.status,
-      complexity: f.complexity || 'medium',
-      activeAgents: (f.activeAgents || []).join(', '),
-      description: f.description || '',
-      tasks: {
-        completed: f.tasks?.completed || 0,
-        total: f.tasks?.total || 0
-      },
-      outputs: Array.isArray(f.outputs)
-        ? f.outputs.join(', ')
-        : (f.outputs ? Object.keys(f.outputs).join(', ') : '')
-    })),
-
-    // Project standards
-    PROJECT_STANDARDS: standards,
-
-    // Agents (v5: flat personas, no tiers)
-    AGENT_COUNT: agents?.total_agents || Object.keys(agents?.agents || {}).length,
-    PERSONAS: Object.entries(agents?.agents || {})
-      .filter(([id]) => !id.startsWith('_'))
-      .map(([id, agent]) => ({
-        id,
-        title: agent.title,
-        domains: (agent.domains || []).join(', '),
-        stack: (agent.stack || ['*']).join(', ')
-      })),
-    // v4 compat (kept empty so legacy templates still render)
-    TIER_1_AGENTS: [],
-    TIER_2_AGENTS: [],
-    TIER_3_AGENTS: [],
-
-    // Agent Teams config
-    AGENT_TEAMS_ENABLED: config?.agentTeams?.enabled || false,
-    AGENT_TEAMS_DISPLAY_MODE: config?.agentTeams?.displayMode || 'auto',
-    AGENT_TEAMS_THRESHOLDS: config?.agentTeams?.spawnThresholds || {},
-
-    // Recent checkpoints
-    RECENT_CHECKPOINTS: (state?.checkpoints || []).slice(-5).map(cp => ({
-      timestamp: cp.timestamp,
-      feature: cp.feature,
-      phase: cp.phase,
-      note: cp.note,
-      validation: cp.validation
-    })),
-
-    // DevOps config
-    DEVOPS_ENABLED: config?.devops ? true : false,
-    DEVOPS_ORG: config?.devops?.organization || '',
-    DEVOPS_PROJECT: config?.devops?.project || '',
-    DEVOPS_BOARDS_ENABLED: config?.devops?.boards?.enabled || false,
-    DEVOPS_AREA_PATH: config?.devops?.boards?.areaPath || '',
-    DEVOPS_WIKI_ENABLED: config?.devops?.wiki?.enabled || false,
-    DEVOPS_WIKI_NAME: config?.devops?.wiki?.wikiName || '',
-    DEVOPS_BUILD_PIPELINE: config?.devops?.pipelines?.buildPipeline || '',
-    DEVOPS_RELEASE_PIPELINE: config?.devops?.pipelines?.releasePipeline || '',
-
-    // Version
-    MORPH_VERSION: '3.0.0-hierarchical'
-  };
-
-  return renderTemplate(template, data);
-}
-
-/**
- * Generate feature-specific CONTEXT-{feature}.md
- * @param {string} projectPath - Root path of the project
- * @param {string} featureName - Feature name
- * @returns {Promise<string>} Generated CONTEXT-{feature}.md content
- */
-export async function generateFeatureContext(projectPath, featureName) {
-  const [state, agents] = await Promise.all([
-    loadState(projectPath),
-    loadAgents(projectPath)
-  ]);
-
-  // Find feature in state (handle both array and object format)
-  let feature;
-  if (Array.isArray(state?.features)) {
-    feature = state.features.find(f => f.name === featureName);
-  } else if (state?.features && typeof state.features === 'object') {
-    feature = state.features[featureName];
-    if (feature) {
-      feature = { name: featureName, ...feature };
-    }
-  }
-
-  if (!feature) {
-    throw new Error(`Feature "${featureName}" not found in state.json`);
-  }
-
-  // Load feature outputs
-  const outputsDir = path.join(projectPath, `.morph/features/${featureName}`);
-  let decisions = [];
-  let tasks = [];
-
-  try {
-    const decisionsPath = path.join(outputsDir, '2-plan', 'decisions.md');
-    const decisionsContent = await fs.readFile(decisionsPath, 'utf8');
-    // Parse decisions.md (simplified - just extract ADR headers)
-    const adrMatches = decisionsContent.matchAll(/##\s+ADR-(\d+):\s+(.+)/g);
-    decisions = Array.from(adrMatches).map(match => ({
-      id: match[1],
-      title: match[2],
-      status: 'Accepted',
-      date: new Date().toISOString().split('T')[0],
-      context: '',
-      decision: ''
-    }));
-  } catch (err) {
-    // No decisions.md yet
-  }
-
-  try {
-    const tasksPath = path.join(outputsDir, '2-plan', 'tasks.md');
-    const tasksContent = await fs.readFile(tasksPath, 'utf8');
-    tasks = JSON.parse(tasksContent).tasks || [];
-  } catch (err) {
-    // No tasks.json yet
-  }
-
-  // Load template with fallback (.morph/framework/templates/ → framework/templates/)
-  const featureTemplatePath = resolveTemplatePath(projectPath, 'context/CONTEXT-FEATURE.md');
-
-  if (!featureTemplatePath) {
-    throw new Error('CONTEXT-FEATURE.md template not found in stack templates or framework/templates/');
-  }
-
-  const template = await fs.readFile(featureTemplatePath, 'utf8');
-
-  // Build active agents list with hierarchy
-  const activeAgentIds = feature.activeAgents || [];
-  const activeAgents = activeAgentIds
-    .filter(id => agents?.agents[id])
-    .map(id => ({ id, ...agents.agents[id] }));
-
-  // v5: flat persona model — no tiers, no squads. Just list active personas.
-  const teamLead = null;
-  const domainLeaders = [];
-  const specialists = activeAgents;
-  const validators = activeAgents.filter(a => a.id === 'evaluator');
-  const squads = [];
-
-  // Build data object
-  const data = {
-    FEATURE_NAME: feature.name,
-    PHASE: feature.phase,
-    WORKFLOW_TYPE: feature.workflow || 'standard',
-    STATUS: feature.status,
-    COMPLEXITY: feature.complexity || 'medium',
-    DESCRIPTION: feature.description || '',
-    TIMESTAMP: new Date().toISOString(),
-
-    // Phase tracking
-    PHASE_DESCRIPTION: `Current phase: ${feature.phase}`,
-    COMPLETED_PHASES: [], // TODO: track phase history
-    UPCOMING_PHASES: [], // TODO: calculate remaining phases
-
-    // Tasks
-    TASKS_TOTAL: feature.tasks?.total || tasks.length,
-    TASKS_COMPLETED: feature.tasks?.completed || tasks.filter(t => t.status === 'completed').length,
-    TASKS_IN_PROGRESS: tasks.filter(t => t.status === 'in_progress').length,
-    TASKS_BLOCKED: tasks.filter(t => t.status === 'blocked').length,
-    TASKS_PROGRESS: feature.tasks?.total > 0
-      ? Math.round((feature.tasks.completed / feature.tasks.total) * 100)
-      : 0,
-    CURRENT_TASK: tasks.find(t => t.status === 'in_progress') || null,
-
-    // Active agents
-    ACTIVE_AGENTS_COUNT: activeAgents.length,
-    TEAM_LEAD: teamLead ? {
-      id: teamLead.id,
-      title: teamLead.title
-    } : null,
-    SQUADS: squads,
-    VALIDATORS: validators.map(v => ({
-      id: v.id,
-      title: v.title
-    })),
-
-    // Outputs (handle both object and array format)
-    OUTPUTS: (Array.isArray(feature.outputs)
-      ? feature.outputs.map(output => ({
-          type: output,
-          generated: true,
-          path: `.morph/features/${featureName}/${output}`,
-          generatedAt: null
-        }))
-      : Object.entries(feature.outputs || {}).map(([type, data]) => ({
-          type,
-          generated: data.created || false,
-          path: data.path || `.morph/features/${featureName}/${type}`,
-          generatedAt: data.createdAt || null
-        }))
-    ),
-
-    // Decisions
-    DECISIONS: decisions,
-
-    // Validation
-    VALIDATION_RESULTS: feature.lastValidation?.results || null,
-    VALIDATION_PASSED: feature.lastValidation?.passed || false,
-    VALIDATION_TIMESTAMP: feature.lastValidation?.timestamp || null,
-
-    // Tasks list
-    TASKS: tasks,
-
-    // Checkpoints
-    CHECKPOINTS: (state?.checkpoints || [])
-      .filter(cp => cp.feature === featureName)
-      .map(cp => ({
-        timestamp: cp.timestamp,
-        phase: cp.phase,
-        tasksCompleted: cp.tasksCompleted,
-        tasksTotal: cp.tasksTotal,
-        note: cp.note,
-        validation: cp.validation
-      })),
-
-    // Related standards
-    RELATED_STANDARDS: [], // TODO: link standards based on activeAgents
-
-    // File paths
-    CURRENT_TASK_ID: tasks.find(t => t.status === 'in_progress')?.id || '',
-    PROPOSAL_PATH: getOutputPath(featureName, 'proposal'),
-    SPEC_PATH: getOutputPath(featureName, 'spec'),
-    CONTRACTS_PATH: getOutputPath(featureName, 'contracts'),
-    TASKS_PATH: `.morph/features/${featureName}/2-plan/tasks.md`,
-    DECISIONS_PATH: getOutputPath(featureName, 'decisions'),
-    RECAP_PATH: getOutputPath(featureName, 'recap'),
-
-    // Version
-    MORPH_VERSION: '5.0.0',
-    FEATURE_ID: feature.id || featureName
-  };
-
-  return renderTemplate(template, data);
-}
-
-/**
- * Write generated context to file
- * @param {string} projectPath - Root path of the project
- * @param {string} content - Generated content
- * @param {string} filename - Output filename
- * @returns {Promise<string>} Path to written file
- */
-export async function writeContext(projectPath, content, filename = 'CONTEXT.md') {
-  const contextDir = path.join(projectPath, '.morph/context');
-  await fs.mkdir(contextDir, { recursive: true });
-
-  const outputPath = path.join(contextDir, filename);
-  await fs.writeFile(outputPath, content, 'utf8');
-
-  return outputPath;
-}
-
-/**
- * Generate and write both project and feature context files
- * @param {string} projectPath - Root path of the project
- * @param {string} featureName - Optional feature name (if null, only generates project context)
- * @returns {Promise<Object>} Paths to generated files
- */
-export async function generateContext(projectPath, featureName = null) {
-  const results = {};
-
-  // Always generate project context
-  const projectContext = await generateProjectContext(projectPath);
-  results.projectContext = await writeContext(projectPath, projectContext, 'CONTEXT.md');
-
-  // Generate feature context if requested
-  if (featureName) {
-    const featureContext = await generateFeatureContext(projectPath, featureName);
-    results.featureContext = await writeContext(
-      projectPath,
-      featureContext,
-      `CONTEXT-${featureName}.md`
-    );
-  }
-
-  return results;
-}
+/**
+ * @fileoverview Context Generator - Auto-generates CONTEXT.md files
+ *
+ * Populates CONTEXT.md templates with real project data from:
+ * - state.json (features, phases, tasks, checkpoints)
+ * - config.json (project settings, Azure resources, agent config)
+ * - agents.json (hierarchical agent structure)
+ * - project.md (project description)
+ * - standards/*.md (project-specific standards)
+ *
+ * @module context-generator
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { getOutputPath } from '../../core/paths/output-schema.js';
+import { resolveTemplatePathById } from '../../core/templates/template-registry.js';
+
+/**
+ * Resolve a context template by its REGISTRY.json id, honoring a project-local
+ * override. REGISTRY owns the relative path; resolveTemplatePathById checks
+ * `.morph/framework/templates/` first, then `framework/templates/`.
+ * @param {string} projectPath
+ * @param {string} templateId - REGISTRY id, e.g. 'context' or 'context-feature'
+ * @returns {string|null} Absolute path, or null if neither location has the file
+ */
+function resolveTemplatePath(projectPath, templateId) {
+  return resolveTemplatePathById(templateId, projectPath);
+}
+
+/**
+ * Load project state from state.json
+ * @param {string} projectPath - Root path of the project
+ * @returns {Promise<Object>} Parsed state
+ */
+async function loadState(projectPath) {
+  const statePath = path.join(projectPath, '.morph/state.json');
+  try {
+    const content = await fs.readFile(statePath, 'utf8');
+    return JSON.parse(content);
+  } catch (err) {
+    return { features: [], checkpoints: [] };
+  }
+}
+
+/**
+ * Load project config from config.json
+ * @param {string} projectPath - Root path of the project
+ * @returns {Promise<Object>} Parsed config
+ */
+async function loadConfig(projectPath) {
+  const configPath = path.join(projectPath, '.morph/config/config.json');
+  try {
+    const content = await fs.readFile(configPath, 'utf8');
+    return JSON.parse(content);
+  } catch (err) {
+    return null;
+  }
+}
+
+/**
+ * Load agents hierarchy from agents.json
+ * @param {string} projectPath - Root path of the project
+ * @returns {Promise<Object>} Parsed agents config
+ */
+async function loadAgents(projectPath) {
+  const agentsPath = path.join(projectPath, '.morph/framework/agents.json');
+  try {
+    const content = await fs.readFile(agentsPath, 'utf8');
+    return JSON.parse(content);
+  } catch (err) {
+    return null;
+  }
+}
+
+/**
+ * Load project description from project.md
+ * @param {string} projectPath - Root path of the project
+ * @returns {Promise<string>} Project description
+ */
+async function loadProjectDescription(projectPath) {
+  const projectMdPath = path.join(projectPath, '.morph/project.md');
+  try {
+    return await fs.readFile(projectMdPath, 'utf8');
+  } catch (err) {
+    return '';
+  }
+}
+
+/**
+ * Load project-specific standards
+ * @param {string} projectPath - Root path of the project
+ * @returns {Promise<Array>} Array of {name, path, description}
+ */
+async function loadProjectStandards(projectPath) {
+  const standardsDir = path.join(projectPath, '.morph/context');
+  try {
+    const files = await fs.readdir(standardsDir);
+    return files
+      .filter(f => f.endsWith('.md'))
+      .map(f => ({
+        name: f.replace('.md', ''),
+        path: `standards/${f}`,
+        description: null
+      }));
+  } catch (err) {
+    return [];
+  }
+}
+
+/**
+ * Get nested property value from object using dot notation
+ * @param {Object} obj - Object to get value from
+ * @param {string} path - Dot-notation path (e.g., 'tasks.completed')
+ * @returns {*} Value at path or empty string
+ */
+function getNestedValue(obj, path) {
+  const keys = path.split('.');
+  let value = obj;
+
+  for (const key of keys) {
+    if (value && typeof value === 'object' && key in value) {
+      value = value[key];
+    } else {
+      return '';
+    }
+  }
+
+  return value !== null && value !== undefined ? value : '';
+}
+
+/**
+ * Simple template renderer (Handlebars-like syntax)
+ * @param {string} template - Template string with {{VAR}} placeholders
+ * @param {Object} data - Data object with values
+ * @returns {string} Rendered template
+ */
+function renderTemplate(template, data) {
+  let result = template;
+
+  // Handle {{#each VAR}}...{{/each}} blocks first (before variable replacement)
+  result = result.replace(/{{#each\s+(\w+)}}([\s\S]*?){{\/each}}/g, (_, varName, itemTemplate) => {
+    const array = data[varName];
+    if (!Array.isArray(array) || array.length === 0) return '';
+
+    return array.map(item => {
+      let itemResult = itemTemplate;
+
+      // Replace all {{prop}} and {{nested.prop}} in the item template
+      itemResult = itemResult.replace(/{{([\w.]+)}}/g, (__, propPath) => {
+        return String(getNestedValue(item, propPath));
+      });
+
+      return itemResult;
+    }).join('');
+  });
+
+  // Handle {{#if VAR}}...{{/if}} blocks
+  result = result.replace(/{{#if\s+(\w+)}}([\s\S]*?){{\/if}}/g, (_, varName, content) => {
+    return data[varName] ? content : '';
+  });
+
+  // Handle {{#unless VAR}}...{{/unless}} blocks
+  result = result.replace(/{{#unless\s+(\w+)}}([\s\S]*?){{\/unless}}/g, (_, varName, content) => {
+    const value = data[varName];
+    // Check if value is falsy, empty array, or empty object
+    const isFalsy = !value ||
+                    (Array.isArray(value) && value.length === 0) ||
+                    (typeof value === 'object' && Object.keys(value).length === 0);
+    return isFalsy ? content : '';
+  });
+
+  // Replace simple {{VAR}} and {{nested.prop}} placeholders
+  result = result.replace(/{{([\w.]+)}}/g, (_, path) => {
+    return String(getNestedValue(data, path));
+  });
+
+  return result;
+}
+
+/**
+ * Generate project-level CONTEXT.md
+ * @param {string} projectPath - Root path of the project
+ * @returns {Promise<string>} Generated CONTEXT.md content
+ */
+export async function generateProjectContext(projectPath) {
+  const [state, config, agents, projectDesc, standards] = await Promise.all([
+    loadState(projectPath),
+    loadConfig(projectPath),
+    loadAgents(projectPath),
+    loadProjectDescription(projectPath),
+    loadProjectStandards(projectPath)
+  ]);
+
+  // Resolve via REGISTRY id, with project-local override fallback.
+  const templatePath = resolveTemplatePath(projectPath, 'context');
+
+  if (!templatePath) {
+    throw new Error('CONTEXT.md template not found in stack templates or framework/templates/');
+  }
+
+  const template = await fs.readFile(templatePath, 'utf8');
+
+  // Build data object
+  const data = {
+    PROJECT_NAME: config?.project?.name || 'Unknown Project',
+    PROJECT_TYPE: config?.project?.type || 'dotnet-nextjs',
+    PROJECT_DESCRIPTION: projectDesc || config?.project?.description || '',
+    REPOSITORY_URL: config?.project?.repository || '',
+    TIMESTAMP: new Date().toISOString(),
+
+    // Stack detection
+    DOTNET_ENABLED: config?.project?.type?.includes('dotnet') ? true : false,
+    NEXTJS_ENABLED: config?.project?.type?.includes('nextjs') ? true : false,
+    DOTNET_VERSION: '10.0',
+    EF_VERSION: '10.0',
+
+    // Azure config
+    AZURE_LOCATION: config?.azure?.location || 'eastus2',
+    CONTAINER_APPS_ENABLED: config?.azure?.resources?.containerApps?.enabled || false,
+    CONTAINER_ENV: config?.azure?.resources?.containerApps?.environment || '',
+    SQL_ENABLED: config?.azure?.resources?.sql?.enabled || false,
+    SQL_SERVER: config?.azure?.resources?.sql?.server || '',
+    SQL_DATABASE: config?.azure?.resources?.sql?.database || '',
+    OPENAI_ENABLED: config?.azure?.resources?.openai?.enabled || false,
+    OPENAI_MODEL: config?.azure?.resources?.openai?.model || '',
+    MONITORING_ENABLED: config?.azure?.resources?.monitoring?.enabled || false,
+    APP_INSIGHTS: config?.azure?.resources?.monitoring?.appInsights || '',
+
+    // Active features (convert object to array if needed)
+    ACTIVE_FEATURES: (Array.isArray(state?.features)
+      ? state.features
+      : Object.entries(state?.features || {}).map(([name, data]) => ({ name, ...data }))
+    ).map(f => ({
+      name: f.name,
+      phase: f.phase,
+      status: f.status,
+      complexity: f.complexity || 'medium',
+      activeAgents: (f.activeAgents || []).join(', '),
+      description: f.description || '',
+      tasks: {
+        completed: f.tasks?.completed || 0,
+        total: f.tasks?.total || 0
+      },
+      outputs: Array.isArray(f.outputs)
+        ? f.outputs.join(', ')
+        : (f.outputs ? Object.keys(f.outputs).join(', ') : '')
+    })),
+
+    // Project standards
+    PROJECT_STANDARDS: standards,
+
+    // Agents (v5: flat personas, no tiers)
+    AGENT_COUNT: agents?.total_agents || Object.keys(agents?.agents || {}).length,
+    PERSONAS: Object.entries(agents?.agents || {})
+      .filter(([id]) => !id.startsWith('_'))
+      .map(([id, agent]) => ({
+        id,
+        title: agent.title,
+        domains: (agent.domains || []).join(', '),
+        stack: (agent.stack || ['*']).join(', ')
+      })),
+    // v4 compat (kept empty so legacy templates still render)
+    TIER_1_AGENTS: [],
+    TIER_2_AGENTS: [],
+    TIER_3_AGENTS: [],
+
+    // Agent Teams config
+    AGENT_TEAMS_ENABLED: config?.agentTeams?.enabled || false,
+    AGENT_TEAMS_DISPLAY_MODE: config?.agentTeams?.displayMode || 'auto',
+    AGENT_TEAMS_THRESHOLDS: config?.agentTeams?.spawnThresholds || {},
+
+    // Recent checkpoints
+    RECENT_CHECKPOINTS: (state?.checkpoints || []).slice(-5).map(cp => ({
+      timestamp: cp.timestamp,
+      feature: cp.feature,
+      phase: cp.phase,
+      note: cp.note,
+      validation: cp.validation
+    })),
+
+    // DevOps config
+    DEVOPS_ENABLED: config?.devops ? true : false,
+    DEVOPS_ORG: config?.devops?.organization || '',
+    DEVOPS_PROJECT: config?.devops?.project || '',
+    DEVOPS_BOARDS_ENABLED: config?.devops?.boards?.enabled || false,
+    DEVOPS_AREA_PATH: config?.devops?.boards?.areaPath || '',
+    DEVOPS_WIKI_ENABLED: config?.devops?.wiki?.enabled || false,
+    DEVOPS_WIKI_NAME: config?.devops?.wiki?.wikiName || '',
+    DEVOPS_BUILD_PIPELINE: config?.devops?.pipelines?.buildPipeline || '',
+    DEVOPS_RELEASE_PIPELINE: config?.devops?.pipelines?.releasePipeline || '',
+
+    // Version
+    MORPH_VERSION: '3.0.0-hierarchical'
+  };
+
+  return renderTemplate(template, data);
+}
+
+/**
+ * Generate feature-specific CONTEXT-{feature}.md
+ * @param {string} projectPath - Root path of the project
+ * @param {string} featureName - Feature name
+ * @returns {Promise<string>} Generated CONTEXT-{feature}.md content
+ */
+export async function generateFeatureContext(projectPath, featureName) {
+  const [state, agents] = await Promise.all([
+    loadState(projectPath),
+    loadAgents(projectPath)
+  ]);
+
+  // Find feature in state (handle both array and object format)
+  let feature;
+  if (Array.isArray(state?.features)) {
+    feature = state.features.find(f => f.name === featureName);
+  } else if (state?.features && typeof state.features === 'object') {
+    feature = state.features[featureName];
+    if (feature) {
+      feature = { name: featureName, ...feature };
+    }
+  }
+
+  if (!feature) {
+    throw new Error(`Feature "${featureName}" not found in state.json`);
+  }
+
+  // Load feature outputs
+  const outputsDir = path.join(projectPath, `.morph/features/${featureName}`);
+  let decisions = [];
+  let tasks = [];
+
+  try {
+    const decisionsPath = path.join(outputsDir, '2-plan', 'decisions.md');
+    const decisionsContent = await fs.readFile(decisionsPath, 'utf8');
+    // Parse decisions.md (simplified - just extract ADR headers)
+    const adrMatches = decisionsContent.matchAll(/##\s+ADR-(\d+):\s+(.+)/g);
+    decisions = Array.from(adrMatches).map(match => ({
+      id: match[1],
+      title: match[2],
+      status: 'Accepted',
+      date: new Date().toISOString().split('T')[0],
+      context: '',
+      decision: ''
+    }));
+  } catch (err) {
+    // No decisions.md yet
+  }
+
+  try {
+    const tasksPath = path.join(outputsDir, '2-plan', 'tasks.md');
+    const tasksContent = await fs.readFile(tasksPath, 'utf8');
+    tasks = JSON.parse(tasksContent).tasks || [];
+  } catch (err) {
+    // No tasks.json yet
+  }
+
+  // Resolve via REGISTRY id, with project-local override fallback.
+  const featureTemplatePath = resolveTemplatePath(projectPath, 'context-feature');
+
+  if (!featureTemplatePath) {
+    throw new Error('CONTEXT-FEATURE.md template not found in stack templates or framework/templates/');
+  }
+
+  const template = await fs.readFile(featureTemplatePath, 'utf8');
+
+  // Build active agents list with hierarchy
+  const activeAgentIds = feature.activeAgents || [];
+  const activeAgents = activeAgentIds
+    .filter(id => agents?.agents[id])
+    .map(id => ({ id, ...agents.agents[id] }));
+
+  // v5: flat persona model — no tiers, no squads. Just list active personas.
+  const teamLead = null;
+  const domainLeaders = [];
+  const specialists = activeAgents;
+  const validators = activeAgents.filter(a => a.id === 'evaluator');
+  const squads = [];
+
+  // Build data object
+  const data = {
+    FEATURE_NAME: feature.name,
+    PHASE: feature.phase,
+    WORKFLOW_TYPE: feature.workflow || 'standard',
+    STATUS: feature.status,
+    COMPLEXITY: feature.complexity || 'medium',
+    DESCRIPTION: feature.description || '',
+    TIMESTAMP: new Date().toISOString(),
+
+    // Phase tracking
+    PHASE_DESCRIPTION: `Current phase: ${feature.phase}`,
+    COMPLETED_PHASES: [], // TODO: track phase history
+    UPCOMING_PHASES: [], // TODO: calculate remaining phases
+
+    // Tasks
+    TASKS_TOTAL: feature.tasks?.total || tasks.length,
+    TASKS_COMPLETED: feature.tasks?.completed || tasks.filter(t => t.status === 'completed').length,
+    TASKS_IN_PROGRESS: tasks.filter(t => t.status === 'in_progress').length,
+    TASKS_BLOCKED: tasks.filter(t => t.status === 'blocked').length,
+    TASKS_PROGRESS: feature.tasks?.total > 0
+      ? Math.round((feature.tasks.completed / feature.tasks.total) * 100)
+      : 0,
+    CURRENT_TASK: tasks.find(t => t.status === 'in_progress') || null,
+
+    // Active agents
+    ACTIVE_AGENTS_COUNT: activeAgents.length,
+    TEAM_LEAD: teamLead ? {
+      id: teamLead.id,
+      title: teamLead.title
+    } : null,
+    SQUADS: squads,
+    VALIDATORS: validators.map(v => ({
+      id: v.id,
+      title: v.title
+    })),
+
+    // Outputs (handle both object and array format)
+    OUTPUTS: (Array.isArray(feature.outputs)
+      ? feature.outputs.map(output => ({
+          type: output,
+          generated: true,
+          path: `.morph/features/${featureName}/${output}`,
+          generatedAt: null
+        }))
+      : Object.entries(feature.outputs || {}).map(([type, data]) => ({
+          type,
+          generated: data.created || false,
+          path: data.path || `.morph/features/${featureName}/${type}`,
+          generatedAt: data.createdAt || null
+        }))
+    ),
+
+    // Decisions
+    DECISIONS: decisions,
+
+    // Validation
+    VALIDATION_RESULTS: feature.lastValidation?.results || null,
+    VALIDATION_PASSED: feature.lastValidation?.passed || false,
+    VALIDATION_TIMESTAMP: feature.lastValidation?.timestamp || null,
+
+    // Tasks list
+    TASKS: tasks,
+
+    // Checkpoints
+    CHECKPOINTS: (state?.checkpoints || [])
+      .filter(cp => cp.feature === featureName)
+      .map(cp => ({
+        timestamp: cp.timestamp,
+        phase: cp.phase,
+        tasksCompleted: cp.tasksCompleted,
+        tasksTotal: cp.tasksTotal,
+        note: cp.note,
+        validation: cp.validation
+      })),
+
+    // Related standards
+    RELATED_STANDARDS: [], // TODO: link standards based on activeAgents
+
+    // File paths
+    CURRENT_TASK_ID: tasks.find(t => t.status === 'in_progress')?.id || '',
+    PROPOSAL_PATH: getOutputPath(featureName, 'proposal'),
+    SPEC_PATH: getOutputPath(featureName, 'spec'),
+    CONTRACTS_PATH: getOutputPath(featureName, 'contracts'),
+    TASKS_PATH: `.morph/features/${featureName}/2-plan/tasks.md`,
+    DECISIONS_PATH: getOutputPath(featureName, 'decisions'),
+    RECAP_PATH: getOutputPath(featureName, 'recap'),
+
+    // Version
+    MORPH_VERSION: '5.0.0',
+    FEATURE_ID: feature.id || featureName
+  };
+
+  return renderTemplate(template, data);
+}
+
+/**
+ * Write generated context to file
+ * @param {string} projectPath - Root path of the project
+ * @param {string} content - Generated content
+ * @param {string} filename - Output filename
+ * @returns {Promise<string>} Path to written file
+ */
+export async function writeContext(projectPath, content, filename = 'CONTEXT.md') {
+  const contextDir = path.join(projectPath, '.morph/context');
+  await fs.mkdir(contextDir, { recursive: true });
+
+  const outputPath = path.join(contextDir, filename);
+  await fs.writeFile(outputPath, content, 'utf8');
+
+  return outputPath;
+}
+
+/**
+ * Generate and write both project and feature context files
+ * @param {string} projectPath - Root path of the project
+ * @param {string} featureName - Optional feature name (if null, only generates project context)
+ * @returns {Promise<Object>} Paths to generated files
+ */
+export async function generateContext(projectPath, featureName = null) {
+  const results = {};
+
+  // Always generate project context
+  const projectContext = await generateProjectContext(projectPath);
+  results.projectContext = await writeContext(projectPath, projectContext, 'CONTEXT.md');
+
+  // Generate feature context if requested
+  if (featureName) {
+    const featureContext = await generateFeatureContext(projectPath, featureName);
+    results.featureContext = await writeContext(
+      projectPath,
+      featureContext,
+      `CONTEXT-${featureName}.md`
+    );
+  }
+
+  return results;
+}