@polymorphism-tech/morph-spec 4.12.0 → 4.13.0

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

@@ -1,285 +1,72 @@
-/**
- * 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';
-import { shouldInstall, getProjectTags } from '../../lib/stack-filter.js';
-
-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');
-
-/** Token budget threshold — warn if briefing exceeds this */
-const TOKEN_BUDGET_THRESHOLD = 8000;
-
-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;
-  }
-}
-
-/**
- * Load project config.json from .morph/config.json.
- *
- * @param {string} [projectPath] - Override project path (defaults to cwd)
- * @returns {Object|null}
- */
-function loadProjectConfig(projectPath) {
-  const configPath = join(projectPath || process.cwd(), '.morph', 'config.json');
-  try {
-    if (!existsSync(configPath)) return null;
-    return JSON.parse(readFileSync(configPath, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Estimate token count for a text string.
- * Uses ~4 chars/token heuristic (conservative for English + code).
- *
- * @param {string} text
- * @returns {number}
- */
-export function estimateTokens(text) {
-  if (!text) return 0;
-  return Math.ceil(text.length / 4);
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// 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 or stack.
- *
- * @param {string} agentId - Agent ID from agents.json
- * @param {string} phase - Current phase (design|tasks|implement)
- * @param {Object} [opts] - Options
- * @param {string} [opts.projectPath] - Override project path (defaults to cwd)
- * @returns {string} Formatted briefing or ''
- */
-export function buildAgentBriefing(agentId, phase, opts = {}) {
-  const agents = loadAgents();
-  const agentData = agents.agents?.[agentId];
-  if (!agentData) return '';
-
-  const standardsRefs = agentData.standards || [];
-  if (standardsRefs.length === 0) return '';
-
-  const standards = loadStandards();
-
-  // Load project tags for stack filtering
-  const config = loadProjectConfig(opts.projectPath);
-  const projectTags = config ? getProjectTags(config) : [];
-
-  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;
-    }
-
-    // Stack filtering: skip standards not relevant to this project's stack
-    if (projectTags.length > 0 && !shouldInstall(entry.stacks || ['*'], projectTags)) continue;
-
-    const line = formatBriefingLine(entry, ref.priority, ref.anchor);
-    if (line) lines.push(line);
-  }
-
-  const briefing = lines.length > 0 ? lines.join('\n') : '';
-
-  // Token budget warning
-  if (briefing) {
-    const tokens = estimateTokens(briefing);
-    if (tokens > TOKEN_BUDGET_THRESHOLD) {
-      process.stderr.write(
-        `[digest-builder] Warning: briefing for agent '${agentId}' is ~${tokens} tokens (threshold: ${TOKEN_BUDGET_THRESHOLD})\n`
-      );
-    }
-  }
-
-  return briefing;
-}
-
-/**
- * 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;
-}
+/**
+ * Validator Prompt Builder
+ *
+ * Generates read-only validation task prompts for Tier-4 validator agents
+ * from agents.json hook_behavior configuration.
+ *
+ * Used by dispatch-agents.js in --mode validate.
+ */
+
+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');
+
+let _agentsCache = null;
+
+/** 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: {} };
+  }
+}
+
+/**
+ * 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.
+ */
+export function clearCache() {
+  _agentsCache = null;
+}

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

@@ -82,7 +82,7 @@ export function parseTaskList(content) {
 // ============================================================================
 
 /**
- * Parse tasks.md and return a map of { parallelGroup -> taskId[] }.
+ * Parse tasks.md and return a map of { group -> taskId[] }.
  * Gracefully returns {} if the file doesn't exist or is unparseable.
  *
  * @param {string} tasksPath - Absolute path to tasks.md
@@ -187,6 +187,10 @@ export async function ensureTaskList(feature, featureName, cwd = process.cwd())
  * After modifying taskList, sync the counter fields back to feature.tasks.
  * tasks.total is derived from the actual taskList length (not trusted from state).
  *
+ * @deprecated Prefer reading directly from feature.taskList. Counter fields
+ * (feature.tasks) duplicate native Claude Code task tracking. This function
+ * is kept for backward compatibility but will be removed in a future version.
+ *
  * @param {Object} feature - Feature state object (mutated in place)
  */
 export function syncCounters(feature) {
@@ -196,8 +200,10 @@ export function syncCounters(feature) {
     feature.tasks = { total: 0, completed: 0, inProgress: 0, pending: 0 };
   }
   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;
+  // Exclude expanded tasks — they are replaced by their sub-tasks
+  const active = list.filter(t => t.status !== 'expanded');
+  feature.tasks.total = active.length;
+  feature.tasks.completed = active.filter(t => t.status === 'completed').length;
+  feature.tasks.inProgress = active.filter(t => t.status === 'in_progress').length;
+  feature.tasks.pending = active.filter(t => t.status === 'pending').length;
 }