@polymorphism-tech/morph-spec 4.2.0 → 4.3.1

package/docs/next-generation/META-PROMPTS.md

@@ -0,0 +1,235 @@
+# Meta-Prompts (HOPs) — MORPH-SPEC v3.0
+
+Higher-Order Prompts (HOPs) are Handlebars-powered prompt templates that generate consistent, context-rich system prompts for agent spawning. Instead of writing prompts from scratch each time, HOPs inject standards, mission context, and role definitions automatically.
+
+---
+
+## HOP Categories
+
+### 1. Squad Leaders (`squad-leaders/`)
+
+Prompts for orchestrating domain squads. Use when spawning the head of a multi-agent squad.
+
+| HOP ID | File | Use Case |
+|--------|------|----------|
+| `hop-backend-squad` | `backend-squad.md` | .NET backend squad with dotnet-senior as lead |
+| `hop-frontend-squad` | `frontend-squad.md` | Blazor or Next.js frontend squad |
+
+### 2. Parallel Workers (`parallel-workers/`)
+
+Prompts for P-Thread agents working in isolation.
+
+| HOP ID | File | Use Case |
+|--------|------|----------|
+| `hop-parallel-worker` | `parallel-worker.md` | Individual domain worker in a parallel squad |
+| `hop-parallel-coordinator` | `parallel-coordinator.md` | Coordinator managing multiple parallel workers |
+
+### 3. Generic HOPs (`hops/`)
+
+General-purpose prompt wrappers.
+
+| HOP ID | File | Use Case |
+|--------|------|----------|
+| `hop-wrapper` | `hop-wrapper.md` | Wrap any agent prompt with standard context injection |
+| `hop-retry` | `hop-retry.md` | Retry a failed task with per-attempt strategy hints |
+| `hop-validation` | `hop-validation.md` | Spawn a validation agent for specific validator types |
+
+### 4. Validators (`validators/`)
+
+Prompts for checkpoint and pre-commit validation agents.
+
+| HOP ID | File | Use Case |
+|--------|------|----------|
+| `hop-checkpoint-validator` | `checkpoint-validator.md` | Run full checkpoint validation (architecture, security, etc.) |
+| `hop-pre-commit-validator` | `pre-commit-validator.md` | Pre-commit hook validation agent |
+
+### 5. Fusion (`fusion/`)
+
+Prompts for F-Thread fusion workflows.
+
+| HOP ID | File | Use Case |
+|--------|------|----------|
+| `hop-fusion-agent` | `fusion-agent.md` | One of N agents in a fusion run |
+| `hop-fusion-aggregator` | `fusion-aggregator.md` | Aggregates N fusion results into the best output |
+
+---
+
+## Rendering HOPs
+
+### CLI
+
+```bash
+# List all available HOPs
+morph-spec hop list
+
+# Render a HOP to stdout
+morph-spec hop render hop-backend-squad \
+  --variables '{"AGENT_ID":"dotnet-senior","MISSION":"Implement auth API","FEATURE_NAME":"user-auth"}'
+
+# Render and save to file
+morph-spec hop render hop-backend-squad output.md \
+  --variables '{"AGENT_ID":"dotnet-senior","MISSION":"Implement auth API"}'
+```
+
+### Programmatic (Node.js)
+
+```javascript
+import { renderHOP, listAvailableHOPs } from './src/lib/hop-composer.js';
+import { join } from 'path';
+
+const frameworkRoot = join(process.cwd(), 'framework');
+
+// List HOPs
+const hops = listAvailableHOPs(frameworkRoot);
+console.log(hops); // [{ id, type, file, description }, ...]
+
+// Render a HOP
+const prompt = renderHOP('hop-backend-squad', {
+  AGENT_ID: 'dotnet-senior',
+  MISSION: 'Implement user authentication',
+  FEATURE_NAME: 'user-auth',
+  SPEC_SUMMARY: 'JWT auth with BCrypt, Supabase JWT validation',
+  TASKS: '- T001: User entity\n- T002: AuthService\n- T003: AuthController',
+  DELIVERABLES: 'Entities/User.cs, Services/AuthService.cs, Controllers/AuthController.cs',
+  CONSTRAINTS: 'IDbContextFactory, no direct DbContext injection'
+}, { frameworkRoot });
+```
+
+---
+
+## Variable Reference
+
+### Standard Variables (auto-injected)
+
+| Variable | Source | Example |
+|----------|--------|---------|
+| `{{FEATURE_NAME}}` | CLI arg | `user-auth` |
+| `{{DATE}}` | System | `2026-02-19` |
+| `{{TIMESTAMP}}` | System | `2026-02-19T10:00:00Z` |
+| `{{STACK}}` | config.json | `Blazor` |
+
+### Squad Leader Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `{{AGENT_ID}}` | Yes | Agent identifier (e.g., `dotnet-senior`) |
+| `{{MISSION}}` | Yes | One-sentence mission statement |
+| `{{SPEC_SUMMARY}}` | Yes | 2-5 sentence spec summary |
+| `{{ADDITIONAL_LEADERS}}` | No | Domain leader list (markdown bullets) |
+| `{{TASKS}}` | Yes | Task list (markdown bullets with IDs) |
+| `{{DELIVERABLES}}` | Yes | Expected output files |
+| `{{CONSTRAINTS}}` | No | Architecture constraints |
+
+### Parallel Worker Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `{{THREAD_ID}}` | Yes | Unique thread identifier |
+| `{{DOMAIN}}` | Yes | Domain name (backend, frontend, infra) |
+| `{{ASSIGNED_FILES}}` | Yes | Files this worker owns |
+| `{{SHARED_FILES}}` | No | Read-only shared context files |
+| `{{TASKS}}` | Yes | Tasks assigned to this worker |
+
+### Fusion Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `{{FUSION_INDEX}}` | Yes | Agent number (1, 2, 3...) |
+| `{{TOTAL_AGENTS}}` | Yes | Total agents in fusion run |
+| `{{STRATEGY}}` | Yes | Aggregation strategy |
+| `{{MISSION}}` | Yes | Shared mission for all agents |
+
+### Retry Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `{{ATTEMPT}}` | Yes | Current attempt number (1-3) |
+| `{{MAX_ATTEMPTS}}` | Yes | Maximum retry count |
+| `{{FAILURE_REASON}}` | Yes | Why the previous attempt failed |
+| `{{ORIGINAL_TASK}}` | Yes | The task being retried |
+
+---
+
+## Handlebars Helpers
+
+HOPs use Handlebars v2.0 helpers:
+
+```handlebars
+{{pascalCase FEATURE_NAME}}  → UserAuth
+{{camelCase FEATURE_NAME}}   → userAuth
+{{snakeCase FEATURE_NAME}}   → user_auth
+{{pluralize "entity"}}       → entities
+{{#if IS_BLAZOR}}...{{/if}} → Conditional blocks
+```
+
+Conditionals available in squad leader HOPs:
+- `{{#if IS_BLAZOR}}` — Blazor-specific content
+- `{{#if IS_NEXTJS}}` — Next.js-specific content
+- `{{#if HAS_BACKEND}}` — Backend domain present
+- `{{#if HAS_INFRA}}` — Infrastructure domain present
+
+---
+
+## HOP Composition Example
+
+Combining HOPs for a full parallel execution:
+
+```javascript
+// 1. Render coordinator prompt
+const coordinatorPrompt = renderHOP('hop-parallel-coordinator', {
+  FEATURE_NAME: 'user-auth',
+  SQUADS: 'backend, frontend',
+  TOTAL_THREADS: '2'
+}, { frameworkRoot });
+
+// 2. Render worker prompts per domain
+const backendPrompt = renderHOP('hop-parallel-worker', {
+  THREAD_ID: 'thr_backend_001',
+  DOMAIN: 'backend',
+  ASSIGNED_FILES: 'Services/UserService.cs\nControllers/AuthController.cs',
+  TASKS: '- T001: UserService\n- T002: AuthController'
+}, { frameworkRoot });
+
+const frontendPrompt = renderHOP('hop-parallel-worker', {
+  THREAD_ID: 'thr_frontend_001',
+  DOMAIN: 'frontend',
+  ASSIGNED_FILES: 'components/LoginForm.tsx\npages/login.tsx',
+  TASKS: '- T003: LoginForm\n- T004: Login page'
+}, { frameworkRoot });
+
+// 3. Spawn via Task tool
+// Use backendPrompt and frontendPrompt as subagent prompts
+```
+
+---
+
+## REGISTRY.json
+
+All HOPs are registered in `framework/templates/meta-prompts/REGISTRY.json`:
+
+```json
+{
+  "hops": [
+    {
+      "id": "hop-backend-squad",
+      "type": "squad-leader",
+      "file": "squad-leaders/backend-squad.md",
+      "description": "Backend squad leader for .NET implementation",
+      "variables": ["AGENT_ID", "MISSION", "SPEC_SUMMARY", "TASKS", "DELIVERABLES"]
+    }
+  ]
+}
+```
+
+To add a custom HOP:
+1. Create your `.md` file in the appropriate category folder
+2. Add an entry to `REGISTRY.json`
+3. Use `morph-spec hop list` to verify it appears
+
+---
+
+## Related
+
+- [Thread Management](THREAD-MANAGEMENT.md) — How HOPs are used in thread spawning
+- [Context Optimization](CONTEXT-OPTIMIZATION.md) — Token-efficient prompt design
+- `src/lib/hop-composer.js` — Rendering engine source

package/docs/next-generation/MIGRATION-GUIDE.md

@@ -0,0 +1,253 @@
+# Migration Guide — MORPH-SPEC v2.x → v3.0
+
+This guide covers migrating an existing MORPH-SPEC v2.x installation to v3.0.0.
+
+---
+
+## What Changes in v3.0
+
+### state.json Schema (breaking)
+
+v3.0 adds required fields to `state.json`:
+
+| Field | Where | Description |
+|-------|-------|-------------|
+| `version` | root | Updated from `2.x.x` → `3.0.0` |
+| `threads` | root | New `{}` object for thread tracking |
+| `features.*.threadMetrics` | per-feature | Thread statistics object |
+| `features.*.trustConfig` | per-feature | Trust level and override |
+| `features.*.contextBundles` | per-feature | Array of context bundle references |
+| `features.*.checkpoints` | per-feature | Array (if not already present) |
+| `metadata.migratedAt` | metadata | Migration timestamp |
+
+### agents.json (additive, non-breaking)
+
+v3.0 adds 4 new agents. Existing agents are preserved unchanged:
+- `vector-search-expert` — Azure AI Search + RAG
+- `thread-orchestrator` — Parallel execution coordination
+- `context-optimizer` — Token efficiency
+- `observability-expert` — App Insights, Serilog, OpenTelemetry
+
+### New CLI Commands
+
+All new — no existing commands changed:
+- `morph-spec threads [list|status|kill|analytics|wait-all|wait-any]`
+- `morph-spec trust [status|set|history|auto-calculate|clear]`
+- `morph-spec migrate [status|v2-to-v3|rollback-to-v2]`
+- `morph-spec hop [list|render]`
+- `morph-spec analytics [feature|context|project]`
+- `morph-spec core-four`
+- `morph-spec parallel [plan|run|status]`
+- `morph-spec fusion [run|aggregate]`
+- `morph-spec mcp [optimize|list]`
+- `morph-spec micro-agent [create|list|show]`
+- `morph-spec prime`
+
+### New Framework Files
+
+83 new files added across:
+- `src/lib/` — 15 new library files
+- `src/commands/` — 11 new command files
+- `src/migrations/` — 2 migration scripts
+- `framework/templates/meta-prompts/` — 12 HOP templates
+- `framework/standards/` — 23 new standards files
+- `framework/workflows/configs/zero-touch.json`
+- `test/integration/` — 4 integration test suites
+- `docs/next-generation/` — 6 documentation files
+
+---
+
+## Prerequisites
+
+Before migrating:
+
+- [ ] MORPH-SPEC CLI version ≥ 4.2.0 (`morph-spec --version`)
+- [ ] Node.js ≥ 18 (`node --version`)
+- [ ] Git working tree clean (`git status`)
+- [ ] Current `.morph/state.json` is valid JSON
+
+```bash
+# Verify CLI version
+morph-spec --version
+# Should show: 4.2.0 or higher
+
+# Check migration status before starting
+morph-spec migrate status
+```
+
+---
+
+## Step-by-Step Migration
+
+### Step 1: Check current state
+
+```bash
+morph-spec migrate status
+```
+
+Expected output:
+```
+📊 Migration Status
+
+state.json
+  Version:      ⚠ Needs migration (current: v2.1.1)
+  Needs update: Yes
+  Has backup:   No
+
+agents.json files
+  ⚠ .morph/config/agents.json
+    Missing: vector-search-expert, thread-orchestrator, context-optimizer, observability-expert
+```
+
+### Step 2: Run the migration
+
+```bash
+morph-spec migrate v2-to-v3
+```
+
+This will:
+1. Backup `state.json` → `state.v2.backup.json`
+2. Update `state.json` version to `3.0.0`
+3. Add `threads: {}` to root
+4. Add `threadMetrics`, `trustConfig`, `contextBundles` to each feature
+5. Add 4 new agents to each `agents.json` file found
+
+Expected output:
+```
+🚀 Migrating MORPH-SPEC v2 → v3.0
+
+Step 1: Migrating state.json (2.1.1 → 3.0.0)
+  ✓ Migration complete: v2.1.1 → 3.0.0
+  Backup: .morph/state.v2.backup.json
+  Changes:
+    • Version: 2.1.1 → 3.0.0
+    • Added: threads: {}
+    • Feature "user-auth": added threadMetrics, trustConfig, contextBundles, checkpoints
+    • Updated metadata.lastUpdated and migratedAt
+
+Step 2: Updating agents.json files
+  ✓ .morph/config/agents.json: added vector-search-expert, thread-orchestrator, context-optimizer, observability-expert
+  – stacks/blazor-azure/.morph/config/agents.json: already up to date
+
+✅ Migration complete! MORPH-SPEC is now on v3.0.0
+```
+
+### Step 3: Verify migration
+
+```bash
+morph-spec doctor --v3
+```
+
+All checks should pass:
+```
+✅ 8/8 — All v3.0 checks passed!
+```
+
+### Step 4: Commit the migration
+
+```bash
+git add .morph/state.json .morph/config/agents.json
+git commit -m "chore(migration): upgrade MORPH-SPEC state to v3.0.0"
+```
+
+---
+
+## Rollback
+
+If the migration causes issues, restore the v2 backup:
+
+```bash
+morph-spec migrate rollback-to-v2 --force
+```
+
+This restores `state.v2.backup.json` → `state.json`.
+
+**Note:** `agents.json` changes are NOT rolled back (additive only, safe to keep).
+
+---
+
+## Manual Migration (Fallback)
+
+If the automated migration fails, update `state.json` manually:
+
+```json
+{
+  "version": "3.0.0",
+  "threads": {},
+  "features": {
+    "your-feature": {
+      "threadMetrics": {
+        "totalThreads": 0,
+        "completedThreads": 0,
+        "failedThreads": 0,
+        "parallelBatches": 0
+      },
+      "trustConfig": {
+        "level": "low",
+        "passRate": 0,
+        "lastCalculated": "2026-02-19T10:00:00.000Z"
+      },
+      "contextBundles": [],
+      "checkpoints": []
+    }
+  },
+  "metadata": {
+    "migratedAt": "2026-02-19T10:00:00.000Z",
+    "migratedFrom": "2.1.1"
+  }
+}
+```
+
+---
+
+## Post-Migration: Enable v3.0 Features
+
+After migration, v3.0 features are available immediately:
+
+```bash
+# Check trust level (starts at "low")
+morph-spec trust status
+
+# View thread management
+morph-spec threads list
+
+# Try context priming
+morph-spec prime feature
+
+# Explore HOPs
+morph-spec hop list
+```
+
+**Trust level** starts at `low` until checkpoints accumulate. To reach `maximum` trust (required for zero-touch), complete 10+ checkpoints with >95% pass rate.
+
+---
+
+## Troubleshooting
+
+### "state.json not found"
+
+Run `morph-spec state init` first to create the initial state.
+
+### "agents.json: Failed to parse"
+
+Check for JSON syntax errors: `cat .morph/config/agents.json | node -e "JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'))"`
+
+### "migration fails with unknown version"
+
+The migration handles any version string that isn't `3.0.0`. If your version field is missing or corrupted, set it manually to `2.1.1` before running migration.
+
+### Rollback backup missing
+
+If `state.v2.backup.json` is gone but you need v2:
+- Restore from git: `git show HEAD:.morph/state.json > .morph/state.json`
+- Or re-run migration (it's idempotent for already-migrated files)
+
+---
+
+## Related
+
+- [Thread Management](THREAD-MANAGEMENT.md) — New thread features in v3.0
+- [Context Optimization](CONTEXT-OPTIMIZATION.md) — Using new context tools
+- [Meta-Prompts](META-PROMPTS.md) — HOP system overview
+- `src/migrations/v2-to-v3.js` — Migration script source
+- `src/migrations/agents-update.js` — Agents update script source