@polymorphism-tech/morph-spec 4.8.12 → 4.8.15

package/src/lib/standards/digest-builder.js

@@ -0,0 +1,231 @@
+/**
+ * Standard Digest Builder
+ *
+ * Composes agent briefings from STANDARDS.json digests.
+ * Reduces context per agent from ~2000-8000 tokens (file reads)
+ * to ~400-600 tokens (digest inline).
+ *
+ * Usage:
+ *   buildAgentBriefing(agentId, phase) → string
+ *   Injected into dispatch taskPrompt as "\n\nConstraints:\n" + briefing
+ *
+ * Standards refs in agents.json support two formats:
+ *   Legacy: "core/coding.md"   (treated as scope:'all', priority:'required')
+ *   Scoped: { id, scope, priority, anchor }
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const AGENTS_JSON_PATH = join(__dirname, '../../../framework/agents.json');
+const STANDARDS_JSON_PATH = join(__dirname, '../../../framework/standards/STANDARDS.json');
+
+let _agentsCache = null;
+let _standardsCache = null;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Loaders
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Load and cache agents.json */
+function loadAgents() {
+  if (_agentsCache) return _agentsCache;
+  if (!existsSync(AGENTS_JSON_PATH)) return { agents: {} };
+  try {
+    _agentsCache = JSON.parse(readFileSync(AGENTS_JSON_PATH, 'utf8'));
+    return _agentsCache;
+  } catch {
+    return { agents: {} };
+  }
+}
+
+/** Load STANDARDS.json and build path/id lookup maps (module-level cache) */
+function loadStandards() {
+  if (_standardsCache) return _standardsCache;
+  if (!existsSync(STANDARDS_JSON_PATH)) {
+    _standardsCache = { byPath: new Map(), byId: new Map() };
+    return _standardsCache;
+  }
+  try {
+    const raw = JSON.parse(readFileSync(STANDARDS_JSON_PATH, 'utf8'));
+    const byPath = new Map();
+    const byId = new Map();
+    for (const entry of raw.standards || []) {
+      byPath.set(entry.path, entry);
+      byId.set(entry.id, entry);
+    }
+    _standardsCache = { byPath, byId };
+    return _standardsCache;
+  } catch {
+    _standardsCache = { byPath: new Map(), byId: new Map() };
+    return _standardsCache;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Normalize a standards reference to canonical shape.
+ * Supports legacy string format and new scoped object format.
+ *
+ * @param {string|Object} ref
+ * @returns {{ id?: string, path?: string, scope: string, priority: string, anchor?: string }}
+ */
+function normalizeRef(ref) {
+  if (typeof ref === 'string') {
+    return { path: ref, scope: 'all', priority: 'required' };
+  }
+  return {
+    id: ref.id,
+    path: ref.path,
+    scope: ref.scope || 'all',
+    priority: ref.priority || 'required',
+    anchor: ref.anchor,
+  };
+}
+
+/**
+ * Resolve a normalized ref to a STANDARDS.json entry.
+ * Tries id lookup first, then exact path, then suffix match for short paths.
+ *
+ * @param {{ id?: string, path?: string }} ref
+ * @param {{ byPath: Map, byId: Map }} standards
+ * @returns {Object|null}
+ */
+function resolveEntry(ref, standards) {
+  if (ref.id) {
+    const entry = standards.byId.get(ref.id);
+    if (entry) return entry;
+  }
+  if (ref.path) {
+    const entry = standards.byPath.get(ref.path);
+    if (entry) return entry;
+
+    // Some agents use short paths like "azure.md" — try suffix match
+    for (const [, e] of standards.byPath) {
+      if (e.path.endsWith('/' + ref.path)) return e;
+    }
+  }
+  return null;
+}
+
+/**
+ * Format a single standards entry as a briefing line.
+ *
+ * priority='required' with digest → inline digest text
+ * priority='reference' → path + optional anchor only
+ * no digest → path reference fallback
+ *
+ * @param {Object} entry - STANDARDS.json entry
+ * @param {string} priority - 'required' | 'reference'
+ * @param {string} [anchor] - specific anchor key from entry.anchors
+ * @returns {string}
+ */
+function formatBriefingLine(entry, priority, anchor) {
+  const anchorFrag = anchor && entry.anchors?.[anchor] ? entry.anchors[anchor] : '';
+
+  if (priority === 'required' && entry.digest) {
+    const ref = anchorFrag ? ` (ref: ${entry.path}${anchorFrag})` : '';
+    return `[${entry.name.toUpperCase()}] ${entry.digest}${ref}`;
+  }
+
+  if (priority === 'reference') {
+    return `[REF: ${entry.path}${anchorFrag}]`;
+  }
+
+  // No digest — inject path reference as fallback
+  return `[REF: ${entry.path}${anchorFrag}]`;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Public API
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Build an agent briefing string for injection into taskPrompt.
+ * Returns empty string when agent not found, has no standards, or all refs
+ * are filtered by scope.
+ *
+ * @param {string} agentId - Agent ID from agents.json
+ * @param {string} phase - Current phase (design|tasks|implement)
+ * @returns {string} Formatted briefing or ''
+ */
+export function buildAgentBriefing(agentId, phase) {
+  const agents = loadAgents();
+  const agentData = agents.agents?.[agentId];
+  if (!agentData) return '';
+
+  const standardsRefs = agentData.standards || [];
+  if (standardsRefs.length === 0) return '';
+
+  const standards = loadStandards();
+  const lines = [];
+
+  for (const rawRef of standardsRefs) {
+    const ref = normalizeRef(rawRef);
+
+    // Scope filtering: skip refs scoped to a different phase
+    if (ref.scope !== 'all' && ref.scope !== phase) continue;
+
+    const entry = resolveEntry(ref, standards);
+    if (!entry) {
+      // No entry found in registry — emit a path reference as fallback
+      const path = ref.path || ref.id;
+      if (path) lines.push(`[REF: ${path}]`);
+      continue;
+    }
+
+    const line = formatBriefingLine(entry, ref.priority, ref.anchor);
+    if (line) lines.push(line);
+  }
+
+  return lines.length > 0 ? lines.join('\n') : '';
+}
+
+/**
+ * Build a read-only validation task prompt for Tier-4 validator agents.
+ * Uses hook_behavior.validates[] from agents.json.
+ *
+ * @param {string} agentId - Agent ID (must be tier 4 with hook_behavior)
+ * @param {string} [taskId] - Optional task ID being validated
+ * @returns {string} Validator task prompt or ''
+ */
+export function buildValidatorPrompt(agentId, taskId) {
+  const agents = loadAgents();
+  const agentData = agents.agents?.[agentId];
+  if (!agentData?.hook_behavior) return '';
+
+  const validates = agentData.hook_behavior.validates || [];
+  const severity = agentData.hook_behavior.severity || 'error';
+  const blocksOnFail = agentData.hook_behavior.blocks_on_fail ?? true;
+  const taskSuffix = taskId ? ` for task ${taskId}` : '';
+
+  const lines = [
+    `You are ${agentData.title || agentId} (Tier 4 Validator). Mode: READ-ONLY validation${taskSuffix}.`,
+    `DO NOT edit any files. Review the current implementation for the following violations:`,
+    ``,
+    `Checks (severity: ${severity}):`,
+    ...validates.map(v => `  - ${v}`),
+    ``,
+    `Output a single JSON line: { "passed": boolean, "issues": [{ "file": "path/to/file", "line": 0, "message": "description", "rule": "rule-name" }] }`,
+    blocksOnFail
+      ? `BLOCKING: if any issues found, implementation must be fixed before task can complete.`
+      : `NON-BLOCKING: issues are warnings only — task completion is not blocked.`,
+  ];
+
+  return lines.join('\n');
+}
+
+/**
+ * Invalidate module-level caches.
+ * Used in tests to ensure a fresh load of agents.json / STANDARDS.json.
+ */
+export function clearCache() {
+  _agentsCache = null;
+  _standardsCache = null;
+}

package/src/lib/tasks/task-parser.js

@@ -0,0 +1,94 @@
+/**
+ * Task Parser — Shared utilities for reading and syncing task state.
+ *
+ * Extracted from bin/task-manager.cjs so both the task-manager and any
+ * future consumers can share the same parsing logic without duplication.
+ */
+
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+
+// ============================================================================
+// parseTasksMd
+// ============================================================================
+
+/**
+ * Parse tasks.md to extract task stubs for the v3 state format.
+ * Accepts headings in either format:
+ *   ### T001 — Task title   (em-dash / en-dash / hyphen)
+ *   ### T001: Task title    (colon)
+ *
+ * @param {string} featureName
+ * @param {string} [cwd] - Project root (defaults to process.cwd())
+ * @returns {Promise<Array<{id, title, status, dependencies, files, checkpoint}>>}
+ */
+export async function parseTasksMd(featureName, cwd = process.cwd()) {
+  const tasksPath = join(cwd, `.morph/features/${featureName}/3-tasks/tasks.md`);
+  let content = '';
+  try {
+    content = await readFile(tasksPath, 'utf-8');
+  } catch {
+    return [];
+  }
+
+  const tasks = [];
+  const headingRe = /^###\s+(T\d+)\s*[—–:\-]\s*(.+)$/gm;
+  let match;
+  while ((match = headingRe.exec(content)) !== null) {
+    tasks.push({
+      id: match[1],
+      title: match[2].trim(),
+      status: 'pending',
+      dependencies: [],
+      files: [],
+      checkpoint: null,
+    });
+  }
+  return tasks;
+}
+
+// ============================================================================
+// ensureTaskList
+// ============================================================================
+
+/**
+ * Ensure feature.taskList exists (array of individual task objects).
+ *
+ * In v3 state, feature.tasks is a counter object {total, completed, …}.
+ * Individual task objects live in feature.taskList.
+ *
+ * @param {Object} feature - Feature state object (mutated in place)
+ * @param {string} featureName
+ * @param {string} [cwd]
+ * @returns {Promise<Array>} The task list
+ */
+export async function ensureTaskList(feature, featureName, cwd = process.cwd()) {
+  if (Array.isArray(feature.tasks)) {
+    // v2 format: tasks IS the array
+    return feature.tasks;
+  }
+  // v3 format: use taskList or build from tasks.md
+  if (!feature.taskList || feature.taskList.length === 0) {
+    feature.taskList = await parseTasksMd(featureName, cwd);
+  }
+  return feature.taskList;
+}
+
+// ============================================================================
+// syncCounters
+// ============================================================================
+
+/**
+ * After modifying taskList, sync the counter fields back to feature.tasks.
+ * tasks.total is derived from the actual taskList length (not trusted from state).
+ *
+ * @param {Object} feature - Feature state object (mutated in place)
+ */
+export function syncCounters(feature) {
+  if (Array.isArray(feature.tasks)) return; // v2 format — nothing to sync
+  const list = feature.taskList || [];
+  feature.tasks.total = list.length;
+  feature.tasks.completed = list.filter(t => t.status === 'completed').length;
+  feature.tasks.inProgress = list.filter(t => t.status === 'in_progress').length;
+  feature.tasks.pending = list.filter(t => t.status === 'pending').length;
+}

package/src/lib/validators/blazor/blazor-concurrency-analyzer.js

@@ -7,6 +7,8 @@
  * @module blazor-concurrency-analyzer
  */
 
+import { readFileSync } from 'fs';
+import { glob } from 'glob';
 import { countIssues } from '../shared/index.js';
 
 /**
@@ -174,6 +176,9 @@ export function checkScopedInSingleton(content, filePath) {
   const issues = [];
   const lines = content.split('\n');
 
+  // Type guard: filePath must be a string (validation-runner may pass options object)
+  if (typeof filePath !== 'string') return [];
+
   // Check if class might be a singleton (common naming patterns)
   const isSingletonCandidate =
     filePath.includes('BackgroundService') ||
@@ -267,8 +272,42 @@ export function analyzeConcurrency(content, filePath) {
 }
 
 
+/**
+ * Project-level concurrency validator. Scans all .cs files in projectPath.
+ * Follows the same interface as other project-level validators (validateNextComponentFiles, etc.)
+ *
+ * @param {string} projectPath - Project root path
+ * @param {Object} [_options]
+ * @returns {Promise<{errors: number, warnings: number, issues: Array}>}
+ */
+export async function validateConcurrencyFiles(projectPath, _options = {}) {
+  const result = { errors: 0, warnings: 0, issues: [] };
+  const pattern = projectPath.replace(/\\/g, '/') + '/**/*.cs';
+  const files = await glob(pattern, { ignore: ['**/node_modules/**', '**/obj/**', '**/bin/**'] });
+
+  for (const filePath of files) {
+    const content = readFileSync(filePath, 'utf8');
+    const relPath = filePath.replace(projectPath.replace(/\\/g, '/') + '/', '');
+    const fileIssues = analyzeConcurrency(content, relPath);
+    for (const issue of fileIssues) {
+      result.issues.push({
+        level: issue.type,
+        message: issue.message,
+        file: issue.file,
+        line: issue.line,
+        solution: issue.suggestion,
+      });
+      if (issue.type === 'error') result.errors++;
+      else result.warnings++;
+    }
+  }
+
+  return result;
+}
+
 export default {
   analyzeConcurrency,
+  validateConcurrencyFiles,
   checkScopedDbContextInBackground,
   checkHangfireWithScopedServices,
   checkScopedInSingleton,

package/src/lib/validators/content/content-validator.js

@@ -23,16 +23,19 @@ export function validateSpecContent(specPath) {
 
   const content = readFileSync(specPath, 'utf8');
 
-  // Required sections for a complete spec
+  // Required sections for a complete spec (prefix-match to handle variants like
+  // "## Functional Requirements" and "## Technical Architecture")
   const requiredSections = [
     '## Overview',
-    '## Requirements',
-    '## Technical Design',
+    '## Functional Requirements',
+    '## Technical',
     '## Data Model',
-    '## API Contracts'
   ];
 
-  const missing = requiredSections.filter(section => !content.includes(section));
+  const lines = content.split('\n');
+  const missing = requiredSections.filter(section =>
+    !lines.some(line => line.startsWith(section))
+  );
 
   // Additional quality checks
   const errors = [];
@@ -79,8 +82,8 @@ export function validateSpecContent(specPath) {
 }
 
 /**
- * Validate tasks.json structure
- * @param {string} tasksPath - Path to tasks.json file
+ * Validate tasks.md structure
+ * @param {string} tasksPath - Path to tasks.md file
  * @returns {Object} Validation result
  */
 export function validateTasksContent(tasksPath) {
@@ -91,111 +94,36 @@ export function validateTasksContent(tasksPath) {
     };
   }
 
-  let tasks;
-  try {
-    const content = readFileSync(tasksPath, 'utf8');
-    tasks = JSON.parse(content);
-  } catch (error) {
-    return {
-      valid: false,
-      errors: ['Invalid JSON in tasks file: ' + error.message]
-    };
-  }
-
+  const content = readFileSync(tasksPath, 'utf8');
   const errors = [];
   const warnings = [];
 
-  // Check required top-level fields
-  if (!tasks.feature) {
-    errors.push('Missing "feature" field in tasks.json');
-  }
+  // Extract task IDs from headings: ### T001 — title OR ### T001: title
+  const taskRe = /^###\s+(T\d{3})\s*[—–:\-]\s*(.+)$/gm;
+  const checkpointRe = /^###\s+(CHECKPOINT[_-]\d+)\s*[—–:\-]\s*(.+)$/gm;
 
-  if (!tasks.tasks || !Array.isArray(tasks.tasks)) {
-    errors.push('Missing or invalid "tasks" array in tasks.json');
-    return { valid: false, errors, warnings };
-  }
+  const tasks = [...content.matchAll(taskRe)];
+  const checkpoints = [...content.matchAll(checkpointRe)];
 
-  if (tasks.tasks.length === 0) {
-    errors.push('Tasks array is empty - no tasks defined');
+  if (tasks.length === 0) {
+    errors.push('No tasks found in tasks.md — expected headings like "### T001 — Title" or "### T001: Title"');
     return { valid: false, errors, warnings };
   }
 
-  // Validate individual tasks
-  tasks.tasks.forEach((task, index) => {
-    const taskId = task.id || `Task ${index}`;
+  // Validate no duplicate IDs
+  const ids = tasks.map(m => m[1]);
+  const dupes = ids.filter((id, i) => ids.indexOf(id) !== i);
+  dupes.forEach(id => errors.push(`Duplicate task ID: ${id}`));
 
-    // Check required fields
-    if (!task.id) {
-      errors.push(`${taskId}: Missing "id" field`);
-    } else if (!/^(T\d{3}|CHECKPOINT_\d{3})$/.test(task.id)) {
-      warnings.push(`${taskId}: ID should follow format T### or CHECKPOINT_###`);
-    }
-
-    if (!task.title) {
-      errors.push(`${taskId}: Missing "title" field`);
-    }
-
-    if (!task.description) {
-      errors.push(`${taskId}: Missing "description" field`);
-    }
+  // Check for dependency references (look for "Dependencies: T###")
+  const depRe = /\*\*Dependenc(?:y|ies):\*\*\s*([T\d, ]+)/gi;
+  const allDepRefs = [...content.matchAll(depRe)]
+    .flatMap(m => m[1].split(/[,\s]+/).filter(s => /^T\d{3}$/.test(s)));
 
-    if (!task.dependencies) {
-      errors.push(`${taskId}: Missing "dependencies" field (use empty array if no deps)`);
-    }
-
-    // For regular tasks (not checkpoints)
-    if (task.id && task.id.startsWith('T')) {
-      if (!task.category) {
-        warnings.push(`${taskId}: Missing "category" field`);
-      }
-
-      if (!task.estimatedMinutes) {
-        warnings.push(`${taskId}: Missing "estimatedMinutes" field`);
-      }
-
-      if (!task.files || task.files.length === 0) {
-        warnings.push(`${taskId}: No files specified - consider adding affected files`);
-      }
-    }
-
-    // For checkpoints
-    if (task.id && task.id.startsWith('CHECKPOINT')) {
-      if (!task.afterTasks || task.afterTasks.length === 0) {
-        warnings.push(`${taskId}: Checkpoint should specify "afterTasks"`);
-      }
-
-      if (!task.validations || task.validations.length === 0) {
-        warnings.push(`${taskId}: Checkpoint should specify "validations"`);
-      }
-    }
-  });
-
-  // Check for orphaned tasks (missing dependencies)
-  const taskIds = new Set(tasks.tasks.map(t => t.id));
-  tasks.tasks.forEach(task => {
-    if (task.dependencies && Array.isArray(task.dependencies)) {
-      task.dependencies.forEach(depId => {
-        if (depId && !taskIds.has(depId)) {
-          errors.push(`${task.id}: References non-existent dependency "${depId}"`);
-        }
-      });
-    }
-  });
-
-  // Check for circular dependencies (simple check)
-  const hasCycle = (taskId, visited = new Set()) => {
-    if (visited.has(taskId)) return true;
-    visited.add(taskId);
-
-    const task = tasks.tasks.find(t => t.id === taskId);
-    if (!task || !task.dependencies) return false;
-
-    return task.dependencies.some(depId => hasCycle(depId, new Set(visited)));
-  };
-
-  tasks.tasks.forEach(task => {
-    if (task.id && hasCycle(task.id)) {
-      errors.push(`Circular dependency detected involving task ${task.id}`);
+  const idSet = new Set(ids);
+  allDepRefs.forEach(depId => {
+    if (!idSet.has(depId)) {
+      warnings.push(`Dependency reference "${depId}" not found in task list`);
     }
   });
 
@@ -204,10 +132,10 @@ export function validateTasksContent(tasksPath) {
     errors,
     warnings,
     stats: {
-      totalTasks: tasks.tasks.length,
-      regularTasks: tasks.tasks.filter(t => t.id?.startsWith('T')).length,
-      checkpoints: tasks.tasks.filter(t => t.id?.startsWith('CHECKPOINT')).length
-    }
+      totalTasks: tasks.length + checkpoints.length,
+      regularTasks: tasks.length,
+      checkpoints: checkpoints.length,
+    },
   };
 }
 

package/src/lib/validators/nextjs/next-component-validator.js

@@ -86,7 +86,9 @@ export function validateNextComponent(content, filePath) {
   }
 
   // Check 2: hooks used without use client
+  // .ts files (custom hooks, utilities) never render JSX — skip this check
   if (!hasUseClient) {
+    if (!filePath.endsWith('.tsx')) return issues;
     const usedHooks = CLIENT_HOOKS.filter(hook => new RegExp(`\\b${hook}\\b`).test(content));
     if (usedHooks.length > 0) {
       issues.push({

package/src/lib/validators/validation-runner.js

@@ -202,8 +202,8 @@ async function runSingleValidator(validatorId, projectPath, featureName, options
     }
 
     case 'blazor-concurrency': {
-      const { analyzeConcurrency } = await import('./blazor/blazor-concurrency-analyzer.js');
-      return await analyzeConcurrency(projectPath, options);
+      const { validateConcurrencyFiles } = await import('./blazor/blazor-concurrency-analyzer.js');
+      return await validateConcurrencyFiles(projectPath, options);
     }
 
     case 'blazor-state': {

package/src/utils/file-copier.js

@@ -136,6 +136,7 @@ export async function updateGitignore(projectPath) {
     '# MORPH-SPEC',
     '.morph/framework/',
     '.morph/memory/',
+    '.morph/plans/',
     '.morph/analytics/',
     '.claude/commands/',
     '.claude/rules/',

package/src/utils/hooks-installer.js

@@ -15,7 +15,7 @@ import { homedir } from 'os';
 import { execSync } from 'child_process';
 
 /** Current hooks schema version — bump when hook definitions change */
-const HOOKS_VERSION = '2.5.1';
+const HOOKS_VERSION = '2.6.0';
 
 /** Marker for old dispatch.js (v1) */
 const OLD_DISPATCH_COMMAND = 'node framework/hooks/agent-teams/dispatch.js';
@@ -67,10 +67,16 @@ const MORPH_HOOKS = [
   {
     event: 'UserPromptSubmit',
     matcher: null,
-    hooks: [{
-      type: 'command',
-      command: 'node framework/hooks/claude-code/user-prompt/enrich-prompt.js'
-    }]
+    hooks: [
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/user-prompt/enrich-prompt.js'
+      },
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/user-prompt/set-terminal-title.js'
+      }
+    ]
   },
 
   // === PreToolUse: Write|Edit ===
@@ -155,6 +161,20 @@ Otherwise respond: {"ok": true}`
       type: 'command',
       command: 'node framework/hooks/claude-code/notification/approval-reminder.js'
     }]
+  },
+
+  // === TeammateIdle ===
+  // Fires when an Agent Team teammate finishes and is about to go idle.
+  // Exit 2 = send feedback to teammate to continue working (validation failed).
+  // Exit 0 = teammate may become idle (validation passed).
+  // Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 (set in env above).
+  {
+    event: 'TeammateIdle',
+    matcher: null,
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/teammate-idle/teammate-idle.js'
+    }]
   }
 ];
 
@@ -241,8 +261,12 @@ export async function installClaudeHooks(targetPath) {
   // JSON Schema for IDE auto-complete and validation
   settings['$schema'] = 'https://json.schemastore.org/claude-code-settings.json';
 
-  // Environment variables — always set MORPH_SPEC_ACTIVE, preserve user additions
-  settings.env = { ...settings.env, MORPH_SPEC_ACTIVE: 'true' };
+  // Environment variables — always set MORPH_SPEC_ACTIVE + Agent Teams flag, preserve user additions
+  settings.env = {
+    ...settings.env,
+    MORPH_SPEC_ACTIVE: 'true',
+    CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: '1',
+  };
 
   // Attribution — only set if not already customized by user
   if (!settings.attribution) {