@polymorphism-tech/morph-spec 8.2.1 → 8.3.0

package/src/lib/detectors/design-system-detector.js

@@ -150,49 +150,6 @@ export function detectDesignSystem(projectPath, featureName = null) {
   return result;
 }
 
-/**
- * Check if UI agents are active for a feature
- * @param {string} projectPath - Root path of the project
- * @param {string} featureName - Feature name
- * @returns {boolean} True if UI agents are active
- */
-export function hasUIAgentsActive(projectPath, featureName) {
-  try {
-    const statePath = join(projectPath, '.morph/state.json');
-
-    if (!existsSync(statePath)) {
-      return false;
-    }
-
-    const state = JSON.parse(readFileSync(statePath, 'utf8'));
-
-    // 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.activeAgents) {
-      return false;
-    }
-
-    // UI design agents that require a design system before implement phase.
-    // Implementation-only agents (nextjs-expert, css-specialist)
-    // build from existing designs and do NOT trigger this gate.
-    const uiAgents = [
-      'ui-designer',
-      'uiux-designer',
-      'ui-ux-designer',
-    ];
-
-    return feature.activeAgents.some(agentId => uiAgents.includes(agentId));
-  } catch {
-    return false;
-  }
-}
-
 /**
  * Get recommended design system locations based on project type
  * @param {string} projectPath - Root path of the project

package/src/lib/generators/index.js

@@ -6,6 +6,5 @@
 
 export * from './design-system-generator.js';
 export * from './handoff-generator.js';
-export * from './metadata-extractor.js';
 export * from './architecture-scanner.js';
 export * from './scaffold-generator.js';

package/src/lib/telemetry/telemetry-reader.js

@@ -0,0 +1,103 @@
+/**
+ * Telemetry aggregation — reads the append-only harness event stream
+ * (.morph/logs/events.jsonl, written by the telemetry-log hook) and summarizes
+ * the whole execution path: which skills ran, which personas were dispatched,
+ * which standards (knowledge base) were read, the tool mix, and the prompts.
+ *
+ * Pure aggregation (`aggregateTelemetry`) is separated from disk I/O
+ * (`loadTelemetry`) so the summary logic is unit-testable without fixtures —
+ * the same split fleet-scanner uses. CLI-side; runs in the target project cwd.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const EVENTS_FILE = join('.morph', 'logs', 'events.jsonl');
+
+/**
+ * Read the raw event stream from a project root. A corrupt/truncated line is
+ * skipped, not fatal. Returns [] when there is no log.
+ *
+ * @param {string} [projectPath]
+ * @returns {Object[]}
+ */
+export function loadTelemetry(projectPath) {
+  try {
+    const p = join(projectPath || process.cwd(), EVENTS_FILE);
+    if (!existsSync(p)) return [];
+    const events = [];
+    for (const line of readFileSync(p, 'utf-8').split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try { events.push(JSON.parse(trimmed)); } catch { /* skip corrupt line */ }
+    }
+    return events;
+  } catch {
+    return [];
+  }
+}
+
+function rank(map) {
+  return [...map.entries()]
+    .map(([name, count]) => ({ name, count }))
+    .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
+}
+
+/**
+ * Summarize an event stream.
+ *
+ * @param {Object[]} events - raw events (from loadTelemetry)
+ * @param {{ feature?: string }} [opts] - optional feature filter
+ * @returns {{
+ *   total: number,
+ *   skills: Array<{name:string,count:number}>,
+ *   personas: Array<{name:string,count:number}>,
+ *   standards: Array<{path:string,count:number}>,
+ *   tools: Array<{name:string,count:number}>,
+ *   prompts: Array<{ts:string,source:'user'|'agent',feature:?string,phase:?string,text:string}>,
+ *   features: string[]
+ * }}
+ */
+export function aggregateTelemetry(events, opts = {}) {
+  const scoped = opts.feature
+    ? (events || []).filter(e => e.feature === opts.feature)
+    : (events || []);
+
+  const skills = new Map();
+  const personas = new Map();
+  const standards = new Map();
+  const tools = new Map();
+  const features = new Set();
+  const prompts = [];
+
+  for (const e of scoped) {
+    if (e.tool) tools.set(e.tool, (tools.get(e.tool) || 0) + 1);
+    if (e.feature) features.add(e.feature);
+
+    if (e.tool === 'Skill' && e.skill) {
+      skills.set(e.skill, (skills.get(e.skill) || 0) + 1);
+    } else if ((e.tool === 'Agent' || e.tool === 'Task') && e.persona) {
+      personas.set(e.persona, (personas.get(e.persona) || 0) + 1);
+    }
+
+    if (e.kind === 'standard' && e.target) {
+      standards.set(e.target, (standards.get(e.target) || 0) + 1);
+    }
+
+    if (e.tool === 'UserPrompt' && typeof e.prompt === 'string') {
+      prompts.push({ ts: e.ts, source: 'user', feature: e.feature ?? null, phase: e.phase ?? null, text: e.prompt });
+    } else if ((e.tool === 'Agent' || e.tool === 'Task') && typeof e.prompt === 'string' && e.prompt) {
+      prompts.push({ ts: e.ts, source: 'agent', feature: e.feature ?? null, phase: e.phase ?? null, text: e.prompt });
+    }
+  }
+
+  return {
+    total: scoped.length,
+    skills: rank(skills),
+    personas: rank(personas),
+    standards: rank(standards).map(({ name, count }) => ({ path: name, count })),
+    tools: rank(tools),
+    prompts,
+    features: [...features],
+  };
+}

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

@@ -1,8 +1,8 @@
 /**
  * MORPH-SPEC Validation Runner
  *
- * Unified orchestrator that runs the right validators based on the feature's
- * active agents and decisions. Called by task-done before marking tasks complete.
+ * Unified orchestrator that runs the right validators based on the project's
+ * stack profile. Called by task-done before marking tasks complete.
  *
  * MORPH-SPEC 3.0 - Phase A: Active Validation Pipeline
  */
@@ -10,16 +10,10 @@
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import chalk from 'chalk';
-import { loadState } from '../../core/state/state-manager.js';
 import { getAbsoluteOutputPath, resolveContractsOutputType } from '../../core/paths/output-schema.js';
 import { getStackProfile } from '../stack/stack-profile.js';
 import { aggregateScores, loadRubric } from './score-aggregator.js';
 
-/** Validators that only make sense for .NET projects. */
-const DOTNET_ONLY_VALIDATORS = new Set([
-  'architecture', 'packages', 'contract-compliance'
-]);
-
 /**
  * Heavy validators skipped in 'light' mode (checkpoint-only).
  * Light mode runs only spec, content, and stack-specific lightweight validators.
@@ -29,31 +23,6 @@ const HEAVY_VALIDATORS = new Set([
   'css', 'design-system'
 ]);
 
-/**
- * Load agent → validators map from agents.json (data-driven)
- * @param {string} projectPath - Root path of the project
- * @returns {Object} Map of agent IDs to validator arrays
- */
-function loadAgentValidatorMap(projectPath) {
-  try {
-    const agentsPath = join(projectPath, '.morph/framework/agents.json');
-    const agentsConfig = JSON.parse(readFileSync(agentsPath, 'utf8'));
-
-    const map = {};
-    Object.entries(agentsConfig.agents || {}).forEach(([agentId, agent]) => {
-      if (!agentId.startsWith('_comment') && agent.validators && agent.validators.length > 0) {
-        map[agentId] = agent.validators;
-      }
-    });
-
-    return map;
-  } catch (err) {
-    console.warn(chalk.yellow('⚠️  Failed to load agents.json - no validators will run'));
-    console.warn(chalk.gray(`   Run 'morph-spec init' to set up MORPH-SPEC configuration`));
-    return {}; // Empty map = honest failure
-  }
-}
-
 /**
  * Run all relevant validators for a feature
  *
@@ -61,7 +30,7 @@ function loadAgentValidatorMap(projectPath) {
  * @param {string} featureName - Feature name from state.json
  * @param {Object} options - Options
  * @param {boolean} options.verbose - Show detailed output
- * @param {string[]} options.validators - Specific validators to run (overrides agent-based detection)
+ * @param {string[]} options.validators - Specific validators to run (overrides stack-based detection)
  * @returns {Object} { passed, errors, warnings, issues, summary }
  */
 export async function runValidation(projectPath, featureName, options = {}) {
@@ -81,7 +50,7 @@ export async function runValidation(projectPath, featureName, options = {}) {
   };
 
   // Determine which validators to run
-  const validatorIds = options.validators || detectValidators(featureName, projectPath);
+  const validatorIds = options.validators || detectValidators(projectPath);
 
   // Filter by mode: 'light' skips heavy validators, 'full' (default) runs all
   const mode = options.mode || 'full';
@@ -98,17 +67,8 @@ export async function runValidation(projectPath, featureName, options = {}) {
   validatorIds.push(...constraints.enabledValidators);
 
   if (validatorIds.length === 0) {
-    // Distinguish: no agents vs. no validators mapped
-    const state = loadState(false);
-    const activeAgents = state?.features?.[featureName]?.activeAgents || [];
-    if (activeAgents.length === 0) {
-      result.summary = 'No validators ran — feature has no active agents';
-      console.log(chalk.gray('\n  ℹ️  No validators configured (no active agents in state.json)'));
-      console.log(chalk.gray('     Add agents: morph-spec state add-agent ' + featureName + ' <agent-id>'));
-    } else {
-      result.summary = `No validators mapped for active agents: ${activeAgents.join(', ')}`;
-      console.log(chalk.gray(`\n  ℹ️  Agents [${activeAgents.join(', ')}] have no validators in agents.json`));
-    }
+    result.summary = 'No validators ran — no validators configured for this stack';
+    console.log(chalk.gray('\n  ℹ️  No validators configured for this stack'));
     result._skipReason = result.summary;
     return result;
   }
@@ -191,37 +151,13 @@ export async function runValidation(projectPath, featureName, options = {}) {
 }
 
 /**
- * Detect which validators to run based on feature's active agents
- * @param {string} featureName - Feature name
+ * Detect which validators to run, driven by the project's stack profile.
  * @param {string} projectPath - Project root path (default: current directory)
  * @returns {string[]} Array of validator IDs to run
  */
-function detectValidators(featureName, projectPath = '.') {
+function detectValidators(projectPath = '.') {
   const profile = getStackProfile(projectPath);
-  const state = loadState(false);
-
-  if (!state || !state.features[featureName]) {
-    return [...profile.defaultValidators]; // stack-aware defaults
-  }
-
-  const feature = state.features[featureName];
-  const agents = feature.activeAgents || [];
-  const validatorSet = new Set(profile.defaultValidators); // stack defaults first
-
-  const agentValidatorMap = loadAgentValidatorMap(projectPath);
-  for (const agentId of agents) {
-    const validators = agentValidatorMap[agentId] || [];
-    validators.forEach(v => validatorSet.add(v));
-  }
-
-  // Filter out .NET-only validators for non-.NET projects
-  if (!profile.isDotnet) {
-    for (const v of DOTNET_ONLY_VALIDATORS) {
-      validatorSet.delete(v);
-    }
-  }
-
-  return Array.from(validatorSet);
+  return [...profile.defaultValidators];
 }
 
 /**

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 = '3.3.0';
+const HOOKS_VERSION = '3.4.0';
 
 /** Marker for old dispatch.js (v1) */
 const OLD_DISPATCH_COMMAND = 'node framework/hooks/agent-teams/dispatch.js';
@@ -165,13 +165,37 @@ const MORPH_HOOKS = [
     ]
   },
 
-  // === PostToolUse: All — loop detection ===
+  // === PostToolUse: All — telemetry capture (silent) + loop detection ===
+  // telemetry-log is the single generic vantage point of an NLH: it appends
+  // every tool call (skill, sub-agent dispatch, knowledge-base read, …) to
+  // .morph/logs/events.jsonl. Silent and fail-open — never blocks, never
+  // injects. `morph-spec telemetry` reads the stream back.
   {
     event: 'PostToolUse',
     matcher: null,
+    hooks: [
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/core/telemetry-log.js',
+        timeout: 5000
+      },
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/core/loop-detect.js',
+        timeout: 5000
+      }
+    ]
+  },
+
+  // === UserPromptSubmit — telemetry capture of the user's prompt (silent) ===
+  // The only vantage point on the user's own prompt; completes the execution
+  // path alongside sub-agent prompts captured on PostToolUse.
+  {
+    event: 'UserPromptSubmit',
+    matcher: null,
     hooks: [{
       type: 'command',
-      command: 'node framework/hooks/claude-code/core/loop-detect.js',
+      command: 'node framework/hooks/claude-code/core/telemetry-log.js',
       timeout: 5000
     }]
   },

package/framework/templates/context/CONTEXT-FEATURE.md

@@ -1,269 +0,0 @@
-# {{FEATURE_NAME}} - Feature Context
-
-> Auto-generated by MORPH-SPEC Framework
-> Last updated: {{TIMESTAMP}}
-
-## Feature Overview
-
-**Name:** {{FEATURE_NAME}}
-**Phase:** {{PHASE}}
-**Status:** {{STATUS}}
-**Complexity:** {{COMPLEXITY}}
-
-{{#if DESCRIPTION}}
-{{DESCRIPTION}}
-{{/if}}
-
----
-
-## Progress Tracking
-
-### Current Phase: {{PHASE}}
-
-{{PHASE_DESCRIPTION}}
-
-**Completed Phases:**
-{{#each COMPLETED_PHASES}}
-- ✅ {{name}} - {{completedAt}}
-{{/each}}
-
-**Next Phases:**
-{{#each UPCOMING_PHASES}}
-- ⏭️ {{name}}
-{{/each}}
-
-### Task Progress
-
-**Total Tasks:** {{TASKS_TOTAL}}
-**Completed:** {{TASKS_COMPLETED}} ({{TASKS_PROGRESS}}%)
-**In Progress:** {{TASKS_IN_PROGRESS}}
-**Blocked:** {{TASKS_BLOCKED}}
-
-{{#if CURRENT_TASK}}
-**Current Task:** {{CURRENT_TASK.id}} - {{CURRENT_TASK.title}}
-{{/if}}
-
----
-
-## Active Agents ({{ACTIVE_AGENTS_COUNT}})
-
-### Team Structure
-
-{{#if TEAM_LEAD}}
-**Team Lead:** {{TEAM_LEAD.title}} (`{{TEAM_LEAD.id}}`)
-{{/if}}
-
-{{#each SQUADS}}
-### {{leader.title}} Squad
-**Leader:** `{{leader.id}}`
-**Members ({{members.length}}):**
-{{#each members}}
-- {{title}} (`{{id}}`) {{#if status}}[{{status}}]{{/if}}
-{{/each}}
-{{/each}}
-
-### Validators (Run in Hooks)
-{{#each VALIDATORS}}
-- {{title}} (`{{id}}`)
-{{/each}}
-
----
-
-## Agent Teams
-
-{{#if AGENT_TEAMS_DECISION}}
-{{#if AGENT_TEAMS_DECISION.useAgentTeams}}
-✅ **Agent Teams Recommended**
-
-**Reason:** {{AGENT_TEAMS_DECISION.reason}}
-**Display Mode:** {{AGENT_TEAMS_DECISION.displayMode}}
-**Total Teammates:** {{AGENT_TEAMS_DECISION.totalTeammates}}
-
-**Team Composition:**
-- Team Lead: {{AGENT_TEAMS_DECISION.teamLead}}
-- Domain Leaders: {{AGENT_TEAMS_DECISION.squads}}
-- Validators (hooks): {{AGENT_TEAMS_DECISION.validators}}
-
-{{else}}
-❌ **Single Session Recommended**
-
-**Reason:** {{AGENT_TEAMS_DECISION.reason}}
-**Recommendation:** {{AGENT_TEAMS_DECISION.recommendation}}
-{{/if}}
-{{/if}}
-
----
-
-## Outputs Generated
-
-{{#each OUTPUTS}}
-### {{type}}
-**Status:** {{#if generated}}✅ Generated{{else}}⏳ Pending{{/if}}
-{{#if path}}**Path:** `{{path}}`{{/if}}
-{{#if generatedAt}}**Generated:** {{generatedAt}}{{/if}}
-{{/each}}
-
----
-
-## Decisions Log
-
-{{#each DECISIONS}}
-### ADR-{{id}}: {{title}}
-
-**Status:** {{status}}
-**Date:** {{date}}
-**Decided By:** {{decidedBy}}
-
-**Context:** {{context}}
-
-**Decision:** {{decision}}
-
-{{#if constraints}}
-**Constraints for Validators:**
-```json
-{{constraints}}
-```
-{{/if}}
-
-{{#if alternatives}}
-**Alternatives Considered:**
-{{#each alternatives}}
-- {{name}}: {{rationale}}
-{{/each}}
-{{/if}}
-
----
-{{/each}}
-
-{{#unless DECISIONS}}
-No decisions documented yet. Decisions will be logged in `decisions.md` during Design phase.
-{{/unless}}
-
----
-
-## Validation Status
-
-{{#if VALIDATION_RESULTS}}
-### Latest Validation ({{VALIDATION_TIMESTAMP}})
-
-**Overall:** {{#if VALIDATION_PASSED}}✅ PASSED{{else}}❌ FAILED{{/if}}
-
-{{#each VALIDATION_RESULTS}}
-#### {{validator}}
-**Status:** {{#if passed}}✅ PASSED{{else}}❌ FAILED{{/if}}
-{{#if issues}}
-**Issues ({{issues.length}}):**
-{{#each issues}}
-- [{{severity}}] {{message}} ({{file}}:{{line}})
-{{/each}}
-{{/if}}
-{{/each}}
-
-{{else}}
-No validation runs yet. Validators run automatically via checkpoints.
-{{/if}}
-
----
-
-## Tasks Breakdown
-
-{{#each TASKS}}
-### {{id}}: {{title}}
-
-**Status:** {{status}}
-{{#if priority}}**Priority:** {{priority}}{{/if}}
-{{#if estimatedFiles}}**Estimated Files:** {{estimatedFiles}}{{/if}}
-{{#if dependencies}}**Dependencies:** {{dependencies}}{{/if}}
-
-{{#if description}}
-{{description}}
-{{/if}}
-
-{{#if agent}}**Assigned Agent:** `{{agent}}`{{/if}}
-
-{{#if checkpointAfter}}🔖 **Checkpoint after this task**{{/if}}
-
-{{#if completedAt}}✅ Completed: {{completedAt}}{{/if}}
-{{#if blockedReason}}❌ Blocked: {{blockedReason}}{{/if}}
-
----
-{{/each}}
-
----
-
-## Checkpoints
-
-{{#each CHECKPOINTS}}
-### {{timestamp}}
-**Phase:** {{phase}}
-**Tasks Completed:** {{tasksCompleted}}/{{tasksTotal}}
-
-{{#if note}}
-**Note:** {{note}}
-{{/if}}
-
-{{#if validation}}
-**Validation:** {{validation.passed}}/{{validation.total}} checks passed
-{{#if validation.issues}}
-- Issues: {{validation.issues}}
-{{/if}}
-{{/if}}
-
----
-{{/each}}
-
----
-
-## Related Standards
-
-{{#each RELATED_STANDARDS}}
-### {{name}}
-**Path:** `{{path}}`
-{{#if relevantSections}}
-**Relevant Sections:** {{relevantSections}}
-{{/if}}
-{{/each}}
-
----
-
-## Quick Actions
-
-### Continue Implementation
-During the implement phase, track your work with the native `TaskCreate`/`TaskUpdate`
-tools. Persist progress by writing `tasks.json` (`2-plan/tasks.json`), touching ONLY
-the mutable fields `status`, `outputs`, and `notes` — via the `Write` tool or an `Edit`
-that touches only those fields. The plan contract (`title`, `description`,
-`dependencies`, `effort`, `doneCriteria`, `group`) is frozen after Gate 2. The recap is
-written by the implement skill; state syncs automatically via the `state-sync` hook.
-
-### Advance Phase
-```bash
-# Approve the current gate and scaffold the next phase folder in one step
-morph-spec advance {{FEATURE_NAME}}
-
-# Validate feature outputs
-morph-spec validate-feature {{FEATURE_NAME}}
-```
-
-### Validation
-```bash
-# Validate this feature's outputs against active standards
-morph-spec validate-feature {{FEATURE_NAME}}
-```
-
----
-
-## File Paths
-
-- **Outputs Directory:** `.morph/features/{{FEATURE_NAME}}/`
-- **Proposal:** `{{PROPOSAL_PATH}}`
-- **Spec:** `{{SPEC_PATH}}`
-- **Contracts:** `{{CONTRACTS_PATH}}`
-- **Tasks:** `{{TASKS_PATH}}`
-- **Decisions:** `{{DECISIONS_PATH}}`
-- **Recap:** `{{RECAP_PATH}}`
-
----
-
-*Generated by MORPH-SPEC Framework v{{MORPH_VERSION}}*
-*Feature ID: {{FEATURE_ID}}*