@polymorphism-tech/morph-spec 4.3.3 → 4.3.4

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

@@ -1,235 +0,0 @@
-# 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

@@ -1,253 +0,0 @@
-# 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