@polymorphism-tech/morph-spec 4.2.0 → 4.3.0

package/bin/morph-spec.js

@@ -60,8 +60,44 @@ import searchPatternsProgram from '../src/commands/learning/search-patterns.js';
 // Utility commands
 import troubleshootCommand from '../src/commands/utils/troubleshoot.js';
 import { sessionSummaryCommand } from '../src/commands/utils/session-summary.js';
-import migrateStateProgram from '../src/commands/utils/migrate-state.js';
-import upgradeProgram from '../src/commands/utils/upgrade.js';
+
+// Thread, Analytics, Core Four commands
+import {
+  threadsListCommand, threadsStatusCommand, threadsKillCommand,
+  threadsAnalyticsCommand, threadsWaitAllCommand, threadsWaitAnyCommand
+} from '../src/commands/threads/threads.js';
+import {
+  analyticsFeatureCommand, analyticsContextCommand, analyticsProjectCommand
+} from '../src/commands/analytics/analytics.js';
+import { coreFourCommand } from '../src/commands/context/core-four.js';
+
+// Context Optimization commands
+import { mcpOptimizeCommand, mcpListCommand } from '../src/commands/mcp/mcp.js';
+import {
+  microAgentCreateCommand, microAgentListCommand, microAgentShowCommand
+} from '../src/commands/agents/micro-agent.js';
+import { contextPrimeCommand } from '../src/commands/context/context-prime.js';
+
+// Parallelization commands
+import {
+  squadTemplateListCommand, squadTemplateUseCommand, squadTemplateShowCommand
+} from '../src/commands/agents/squad-template.js';
+import {
+  threadTemplateListCommand, threadTemplateUseCommand
+} from '../src/commands/threads/thread-template.js';
+import { spawnTeamParallelCommand } from '../src/commands/agents/spawn-team.js';
+
+// Fusion commands
+import { agentsFuseCommand, agentsReviewAggregateCommand } from '../src/commands/agents/agents-fuse.js';
+
+// Meta-Prompts (HOP) commands
+import { hopRenderCommand, hopListCommand } from '../src/commands/templates/template-render.js';
+
+// Trust commands
+import {
+  trustStatusCommand, trustSetCommand, trustHistoryCommand,
+  trustAutoCalculateCommand, trustClearCommand
+} from '../src/commands/trust/trust.js';
 
 // Libraries
 import { LearningSystem } from '../src/lib/learning/learning-system.js';
@@ -105,6 +141,7 @@ program
 program
   .command('doctor')
   .description('Check MORPH installation health')
+  .option('--v3', 'Run v3.0 specific checks (lib files, HOPs, standards, agents, migration status)')
   .action(doctorCommand);
 
 program
@@ -423,6 +460,53 @@ templateCommand
   .option('-v, --verbose', 'Show detailed validation information')
   .action(templateValidateCommand);
 
+// HOP (Higher-Order Prompts) commands
+const hopCommand = program
+  .command('hop')
+  .description('Higher-Order Prompts — render and manage meta-prompt templates');
+
+hopCommand
+  .command('list')
+  .description('List all available HOP templates')
+  .action(hopListCommand);
+
+hopCommand
+  .command('render <hop-id> [output-path]')
+  .description('Render a HOP template with variables')
+  .option('--variables <json>', 'Variables JSON string', '{}')
+  .option('--dry-run', 'Preview without writing file')
+  .action((hopId, outputPath, options) => hopRenderCommand(hopId, outputPath, options.variables, options));
+
+// Trust commands
+const trustCommand = program
+  .command('trust')
+  .description('Trust level management for zero-touch execution');
+
+trustCommand
+  .command('status [feature]')
+  .description('Show trust level and auto-approval status')
+  .action(trustStatusCommand);
+
+trustCommand
+  .command('set <feature> <level> [reason]')
+  .description('Manually set trust level (low|medium|high|maximum)')
+  .action(trustSetCommand);
+
+trustCommand
+  .command('history')
+  .description('Show trust history for all features')
+  .action(trustHistoryCommand);
+
+trustCommand
+  .command('auto-calculate <feature>')
+  .description('Recalculate trust from checkpoint history')
+  .action(trustAutoCalculateCommand);
+
+trustCommand
+  .command('clear <feature>')
+  .description('Clear manual trust override (revert to calculated)')
+  .action(trustClearCommand);
+
 // Troubleshooting command
 program
   .command('troubleshoot <keywords...>')
@@ -467,7 +551,7 @@ program
   .option('-v, --verbose', 'Show detailed output')
   .action(rollbackPhaseCommand);
 
-// Approval workflow commands (MORPH-SPEC 3.0)
+// Approval workflow commands
 program
   .command('approve <feature> <gate>')
   .description('Approve a phase gate (design, tasks, uiux, proposal)')
@@ -486,7 +570,7 @@ program
   .option('--json', 'Output as JSON')
   .action((feature, options) => approvalStatusCommand(feature, options));
 
-// Agent team spawning (MORPH-SPEC 3.0)
+// Agent team spawning
 program
   .command('spawn-team <feature>')
   .description('Generate agent team configuration for Task tool')
@@ -494,13 +578,204 @@ program
   .option('--verbose', 'Show detailed team configuration')
   .action((feature, options) => spawnTeamCommand(feature, options));
 
-// Pattern learning system (MORPH-SPEC 3.0) - Add as subcommands
+// Pattern learning system - Add as subcommands
 program.addCommand(capturePatternProgram);
 program.addCommand(searchPatternsProgram);
 
-// Migration and upgrade commands (MORPH-SPEC 3.0) - Add as subcommands
-program.addCommand(migrateStateProgram);
-program.addCommand(upgradeProgram);
+// ─────────────────────────────────────────────────────────────────────────────
+// Thread Management
+// ─────────────────────────────────────────────────────────────────────────────
+const threadsCommand = program
+  .command('threads')
+  .description('Thread lifecycle management');
+
+threadsCommand
+  .command('list')
+  .description('List threads (optionally filtered by feature/status/type)')
+  .option('--feature <feature>', 'Filter by feature name')
+  .option('--status <status>', 'Filter by status (pending|running|completed|failed|killed)')
+  .option('--type <type>', 'Filter by type (base|parallel|fusion|long-running|zero-touch)')
+  .action((options) => threadsListCommand(options));
+
+threadsCommand
+  .command('status <id>')
+  .description('Show detailed status of a thread')
+  .action((id) => threadsStatusCommand(id));
+
+threadsCommand
+  .command('kill <id>')
+  .description('Terminate a running thread')
+  .action((id) => threadsKillCommand(id));
+
+threadsCommand
+  .command('analytics')
+  .description('Show thread analytics dashboard for a feature')
+  .option('--feature <feature>', 'Feature name (required)')
+  .action((options) => threadsAnalyticsCommand(options));
+
+threadsCommand
+  .command('wait-all <feature>')
+  .description('Block until all threads for a feature complete')
+  .option('--timeout <minutes>', 'Timeout in minutes (default: 60)', '60')
+  .action((feature, options) => threadsWaitAllCommand(feature, options));
+
+threadsCommand
+  .command('wait-any <feature>')
+  .description('Block until any thread for a feature completes')
+  .option('--timeout <minutes>', 'Timeout in minutes (default: 60)', '60')
+  .action((feature, options) => threadsWaitAnyCommand(feature, options));
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Analytics
+// ─────────────────────────────────────────────────────────────────────────────
+const analyticsCommand = program
+  .command('analytics')
+  .description('Metrics and analytics dashboards');
+
+analyticsCommand
+  .command('feature <name>')
+  .description('Show thread analytics dashboard for a feature')
+  .action((name, options) => analyticsFeatureCommand(name, options));
+
+analyticsCommand
+  .command('context <name>')
+  .description('Show context token usage and optimization opportunities')
+  .action((name, options) => analyticsContextCommand(name, options));
+
+analyticsCommand
+  .command('project')
+  .description('Show project-wide analytics dashboard (30-day summary)')
+  .option('--period <days>', 'Period in days (default: 30)', '30')
+  .action((options) => analyticsProjectCommand(options));
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Core Four
+// ─────────────────────────────────────────────────────────────────────────────
+program
+  .command('core-four <feature>')
+  .description('Show Core Four dashboard: Context/Model/Prompt/Tools')
+  .option('--json', 'Output as JSON')
+  .action((feature, options) => coreFourCommand(feature, options));
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MCP Optimizer
+// ─────────────────────────────────────────────────────────────────────────────
+const mcpCommand = program
+  .command('mcp')
+  .description('MCP server analysis and optimization');
+
+mcpCommand
+  .command('optimize')
+  .description('Analyze MCP servers and suggest optimizations')
+  .action((options) => mcpOptimizeCommand(options));
+
+mcpCommand
+  .command('list')
+  .description('List configured MCP servers with usage stats')
+  .action((options) => mcpListCommand(options));
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Micro Agents
+// ─────────────────────────────────────────────────────────────────────────────
+const microAgentCommand = program
+  .command('micro-agent')
+  .description('Create and manage ultra-specialized micro-agents');
+
+microAgentCommand
+  .command('create <name>')
+  .description('Create a new micro-agent')
+  .option('--base-agent <agent>', 'Base agent ID to specialize from')
+  .option('--mission <mission>', 'Single focused mission for this agent')
+  .option('--standards <files>', 'Comma-separated standards files to load (1-3 max)')
+  .option('--tools <tools>', 'Comma-separated tools to allow (default: Read,Write,Edit)')
+  .action((name, options) => microAgentCreateCommand(name, options));
+
+microAgentCommand
+  .command('list')
+  .description('List all micro-agents')
+  .action((options) => microAgentListCommand(options));
+
+microAgentCommand
+  .command('show <name>')
+  .description('Show micro-agent details')
+  .option('--show-prompt', 'Show the generated system prompt')
+  .action((name, options) => microAgentShowCommand(name, options));
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Context Prime
+// ─────────────────────────────────────────────────────────────────────────────
+program
+  .command('prime [type]')
+  .description('Output context priming file (feature|bug|refactor|design|infra)')
+  .option('--json', 'Output as JSON')
+  .action((type, options) => contextPrimeCommand(type, options));
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Fusion (F-Thread)
+// ─────────────────────────────────────────────────────────────────────────────
+const agentsFuseCmd = program
+  .command('agents-fuse')
+  .description('F-Thread fusion execution: run N agents, aggregate best result');
+
+agentsFuseCmd
+  .command('run')
+  .description('Run fusion: spawn N agents with same prompt, aggregate results')
+  .option('--prompt <prompt>', 'Prompt/mission for all fusion agents (required)')
+  .option('--count <n>', 'Number of agents to run (default: 3)', '3')
+  .option('--strategy <strategy>', 'Aggregation strategy: best-of-n | consensus | manual-select', 'best-of-n')
+  .option('--feature <feature>', 'Feature name for tracking')
+  .option('--agents <list>', 'Comma-separated agent IDs to use')
+  .option('--json', 'Output as JSON')
+  .action((options) => agentsFuseCommand(options));
+
+agentsFuseCmd
+  .command('aggregate-reviews <feature>')
+  .description('Aggregate review results from N agents')
+  .option('--agents <list>', 'Comma-separated agent IDs (required)')
+  .option('--strategy <strategy>', 'Aggregation strategy', 'best-of-n')
+  .action((feature, options) => agentsReviewAggregateCommand(feature, options));
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Squad Templates
+// ─────────────────────────────────────────────────────────────────────────────
+const squadTemplateCmd = program
+  .command('squad-template')
+  .description('Squad template management for parallel execution');
+
+squadTemplateCmd
+  .command('list')
+  .description('List available squad templates')
+  .action((options) => squadTemplateListCommand(options));
+
+squadTemplateCmd
+  .command('use <template-id>')
+  .description('Configure a feature to use a squad template')
+  .option('--feature <feature>', 'Feature name (required)')
+  .action((id, options) => squadTemplateUseCommand(id, options));
+
+squadTemplateCmd
+  .command('show <template-id>')
+  .description('Show squad template details')
+  .option('--json', 'Output as JSON')
+  .action((id, options) => squadTemplateShowCommand(id, options));
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Commands — Thread Templates
+// ─────────────────────────────────────────────────────────────────────────────
+const threadTemplateCmd = program
+  .command('thread-template')
+  .description('Thread type management');
+
+threadTemplateCmd
+  .command('list')
+  .description('List available thread types (B/P/F/L/Z-Thread)')
+  .action((options) => threadTemplateListCommand(options));
+
+threadTemplateCmd
+  .command('use <type>')
+  .description('Configure thread type for a feature')
+  .option('--feature <feature>', 'Feature name (required)')
+  .action((type, options) => threadTemplateUseCommand(type, options));
 
 // Wire global --stack flag to stack-resolver before any command executes
 program.hook('preAction', () => {

package/bin/validate.js

@@ -17,9 +17,9 @@
  */
 
 import chalk from 'chalk';
-import { validatePackages } from '../src/lib/validators/package-validator.js';
-import { validateArchitecture } from '../src/lib/validators/architecture-validator.js';
-import { validateContrast } from '../src/lib/validators/ui-contrast-validator.js';
+import { validatePackages } from '../src/lib/validators/packages/package-validator.js';
+import { validateArchitecture } from '../src/lib/validators/architecture/architecture-validator.js';
+import { validateContrast } from '../src/lib/validators/ui/ui-contrast-validator.js';
 import { LearningSystem } from '../src/lib/learning/learning-system.js';
 
 const VALIDATORS = {
@@ -51,7 +51,7 @@ const VALIDATORS = {
 async function validateSpecVsTasks(projectPath, options = {}) {
   const path = await import('path');
   const fs = await import('fs');
-  const { loadState } = await import('../src/lib/state-manager.js');
+  const { loadState } = await import('../src/core/state/state-manager.js');
 
   const results = [];
   let errors = 0;

package/docs/{v3.0 → next-generation}/AGENTS.md

@@ -485,7 +485,7 @@
 ```json
 {
   "squadConfigs": {
-    "full-stack-v3": {
+    "full-stack": {
       "parallel": true,
       "agents": [
         "dotnet-senior",

package/docs/next-generation/CONTEXT-OPTIMIZATION.md

@@ -0,0 +1,267 @@
+# Context Optimization — MORPH-SPEC v3.0
+
+Context optimization is the practice of maximizing what useful work fits in the AI model's context window. v3.0 introduces structured techniques to reduce token waste and increase implementation quality per session.
+
+---
+
+## The Context Budget Problem
+
+Claude's context window has a hard limit. A typical morph-next-gen feature session consumes:
+
+| Component | Tokens (approx) |
+|-----------|----------------|
+| CLAUDE.md (full) | ~23,000 |
+| spec.md (large) | ~8,000 |
+| tasks.json | ~3,000 |
+| Standards (3 files) | ~6,000 |
+| Conversation history | Grows per turn |
+| **Total overhead** | **~40,000+** |
+
+Without optimization, implementation tokens are crowded out by reference material.
+
+---
+
+## 12 Optimization Techniques
+
+### 1. Context Priming (Biggest Win: ~80% reduction)
+
+Instead of loading full CLAUDE.md, use a priming file (500 tokens vs 23,000):
+
+```bash
+# Output a focused priming file for your current task type
+morph-spec prime feature
+morph-spec prime bug
+morph-spec prime refactor
+morph-spec prime design
+morph-spec prime infra
+```
+
+Each prime file contains only the essential rules for that task type. Paste the output at the start of your session.
+
+**Priming file locations:** `framework/templates/prime/{type}.md`
+
+### 2. Context Bundles
+
+Pre-compress feature context from ~180K tokens to ~15K:
+
+```bash
+# Create a bundle (compress all outputs for a feature)
+morph-spec context bundle create user-auth
+
+# Load a bundle at session start
+morph-spec context bundle load user-auth
+
+# List available bundles
+morph-spec context bundle list
+```
+
+Bundle structure:
+
+```json
+{
+  "id": "bundle-user-auth-2026-02",
+  "feature": "user-auth",
+  "created": "2026-02-19T10:00:00Z",
+  "tokenCount": 14800,
+  "includes": ["spec-summary", "decisions-summary", "task-list", "key-standards"],
+  "compressed": true
+}
+```
+
+### 3. Selective Standards Loading
+
+Don't load all standards — load only what's relevant to the current task:
+
+```bash
+# Bad: loads everything
+# cat framework/standards/*.md
+
+# Good: load only relevant standards
+morph-spec prime feature | head -20
+# Then manually load: coding.md, and ONE domain standard
+```
+
+Standards priority for implementation tasks:
+1. `coding.md` — always load
+2. Domain standard (e.g., `supabase-rls.md` if working on auth)
+3. Skip everything else
+
+### 4. Micro-Agents for Narrow Tasks
+
+Create ultra-specialized agents with minimal context (1-3 standards, narrow mission):
+
+```bash
+morph-spec micro-agent create rls-writer \
+  --base-agent supabase-expert \
+  --mission "Write RLS policies only" \
+  --standards supabase-rls.md \
+  --tools Read,Write
+
+morph-spec micro-agent show rls-writer --show-prompt
+```
+
+Micro-agents have 90%+ fewer tokens than full agents.
+
+### 5. MCP Server Hygiene
+
+Unnecessary MCP servers consume tokens via tool definitions:
+
+```bash
+# Analyze current MCP overhead
+morph-spec mcp optimize
+
+# List configured servers with usage stats
+morph-spec mcp list
+```
+
+Disable MCP servers not used in current task via `.claude/settings.local.json`.
+
+### 6. Checkpoint Summaries Instead of Full History
+
+At each checkpoint, generate a compact summary instead of keeping full conversation:
+
+```bash
+morph-spec session-summary user-auth
+```
+
+This produces a ~500-token summary replacing thousands of tokens of history.
+
+### 7. Core Four Dashboard
+
+Before starting a session, check the Core Four to identify context wastage:
+
+```bash
+morph-spec core-four user-auth
+```
+
+Output shows: Context efficiency %, active model, prompt quality score, tool count.
+
+**Context efficiency** = (useful tokens) / (total tokens). Target: >70%.
+
+### 8. Thread-Based Context Isolation
+
+Each parallel thread (P-Thread) gets a clean context window. Instead of one massive session, split into 3 parallel sessions:
+
+```bash
+morph-spec parallel plan user-auth
+# Output: 3 squads × ~20K tokens each = 60K total but 20K per session
+```
+
+vs. single session with 60K+ tokens of context.
+
+### 9. Artifact Trail
+
+Track what was produced to avoid re-reading files:
+
+```bash
+# The artifact-trail.js lib tracks: file path, producer agent, timestamp, token cost
+# Access via:
+morph-spec analytics feature user-auth
+```
+
+This shows which files were produced and their approximate token cost.
+
+### 10. Output-First Prompting
+
+In your prompts to agents, always list expected outputs first:
+
+```markdown
+## Your Deliverables (produce these files):
+1. Services/UserService.cs
+2. DTOs/LoginRequest.cs
+
+## Then implement following these specs...
+```
+
+This front-loads the goal, keeping the model focused and reducing verbose exploration.
+
+### 11. Incremental Spec Loading
+
+Don't load the full spec at once. Load sections on demand:
+
+```markdown
+# Load only the section relevant to current task
+## API Contracts (relevant to T003)
+POST /api/auth/login
+Request: { email, password }
+Response: { token, refreshToken }
+```
+
+### 12. Session Handoffs
+
+When approaching context limit, generate a handoff document:
+
+```bash
+morph-spec generate recap user-auth
+```
+
+The recap captures: progress %, tasks completed, decisions made, next steps. Start a new session with just the recap (~1,000 tokens).
+
+---
+
+## Context Analytics
+
+Monitor context efficiency over time:
+
+```bash
+# Feature-level analytics
+morph-spec analytics context user-auth
+
+# Project-level (30-day)
+morph-spec analytics project
+```
+
+Analytics track:
+- Context efficiency score (0-100%)
+- Token usage by phase
+- Optimization opportunities detected
+
+**Optimization triggers** (auto-detected):
+- Efficiency < 60% → Recommend priming
+- Session > 50K tokens → Recommend bundle
+- Standards loaded > 5 → Recommend selective loading
+- MCP servers > 3 active → Recommend MCP hygiene
+
+---
+
+## Context Bundle Format
+
+```json
+{
+  "id": "bundle-{feature}-{date}",
+  "feature": "user-auth",
+  "created": "2026-02-19T10:00:00Z",
+  "tokenCount": 14800,
+  "sections": {
+    "specSummary": "...",
+    "keyDecisions": ["ADR-001: JWT over sessions", "ADR-002: BCrypt for hashing"],
+    "taskProgress": "8/12 completed (67%)",
+    "standards": ["coding.md summary", "supabase-auth.md summary"],
+    "nextTasks": ["T009", "T010", "T011"]
+  }
+}
+```
+
+Store bundles at: `.morph/project/bundles/{feature}/`
+
+---
+
+## Quick Reference
+
+| Technique | Token Savings | When to Use |
+|-----------|--------------|-------------|
+| Context Priming | ~80% | Always — start of every session |
+| Context Bundles | ~70% | Features with large outputs |
+| Selective Standards | ~50% | Implementation phases |
+| Micro-Agents | ~90% | Narrow, repetitive tasks |
+| MCP Hygiene | ~10-20% | When >3 MCP servers active |
+| Thread Isolation | Resets per thread | Multi-domain features |
+| Session Handoffs | Resets context | Long-running features |
+
+---
+
+## Related
+
+- [Thread Management](THREAD-MANAGEMENT.md) — Thread isolation for context efficiency
+- [Meta-Prompts](META-PROMPTS.md) — HOP templates for structured agent prompting
+- [Migration Guide](MIGRATION-GUIDE.md) — Upgrading to v3.0 context features