@polymorphism-tech/morph-spec 4.2.0 → 4.3.0

package/docs/next-generation/EXECUTION-FLOW.md

@@ -0,0 +1,274 @@
+# Execution Flow — MORPH-SPEC v3.0
+
+This document describes the complete execution flow of a v3.0 feature from first request to sync, including all new v3.0 decision points and automation paths.
+
+---
+
+## High-Level Flow
+
+```
+User Request
+    │
+    ▼
+┌─────────────┐
+│  WORKFLOW   │  Auto-detect: fast-track / standard / full-morph
+│  DETECTION  │  Command: morph-spec detect-workflow "<request>"
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│   CONTEXT   │  Load priming file (500 tokens vs 23K CLAUDE.md)
+│   PRIMING   │  Command: morph-spec prime feature
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│   PROPOSAL  │  Agents detected, workflow confirmed
+│    PHASE    │  Gate: proposal approval (auto if trust >= high)
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│   DESIGN    │  spec.md + contracts + decisions.md
+│    PHASE    │  Gate: design approval (auto if trust >= medium)
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│   CLARIFY   │  Resolve ambiguities, update spec
+│    PHASE    │  (no gate, auto-continues)
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│    TASKS    │  tasks.json: IDs, deps, phases
+│    PHASE    │  Gate: tasks approval (auto if trust >= high)
+└──────┬──────┘
+       │
+       ▼
+┌─────────────────────────────────────────────────────────┐
+│                   IMPLEMENT PHASE                       │
+│                                                         │
+│   ┌─────────────┐    ┌─────────────┐                   │
+│   │  Single     │    │  Parallel   │                   │
+│   │  B-Thread   │    │  P-Threads  │                   │
+│   │  (simple)   │    │  (complex)  │                   │
+│   └──────┬──────┘    └──────┬──────┘                   │
+│          │                  │                           │
+│          │         ┌────────┴────────┐                  │
+│          │         │  Squad Planning │                  │
+│          │         │ morph-spec      │                  │
+│          │         │ parallel plan   │                  │
+│          │         └────────┬────────┘                  │
+│          │                  │                           │
+│          │    ┌─────────────┼─────────────┐             │
+│          │    ▼             ▼             ▼             │
+│          │  Backend     Frontend       Infra            │
+│          │  P-Thread    P-Thread     P-Thread           │
+│          │    │             │             │             │
+│          │    └─────────────┴─────────────┘             │
+│          │                  │                           │
+│          │              Coordinator                     │
+│          │              Merges results                  │
+│          │                  │                           │
+│          └──────────────────┘                           │
+│                             │                           │
+│                    Every 3 tasks:                       │
+│                   CHECKPOINT ──> Validators             │
+│                             │    - architecture         │
+│                             │    - security             │
+│                             │    - packages             │
+│                             │                           │
+│                   Trust updates automatically           │
+└─────────────────────────────┬───────────────────────────┘
+                              │
+                              ▼
+                      ┌─────────────┐
+                      │    SYNC     │  Recap + decisions archive
+                      │    PHASE    │
+                      └──────┬──────┘
+                             │
+                             ▼
+                      ┌─────────────┐
+                      │  ARCHIVED   │  Feature complete
+                      └─────────────┘
+```
+
+---
+
+## v3.0 Decision Points
+
+### 1. Workflow Detection
+
+```
+morph-spec detect-workflow "<request>"
+   │
+   ├─ fast-track  → 2 phases (skip most)
+   ├─ standard    → 4 phases (skip UIUX, CLARIFY, SYNC)
+   ├─ full-morph  → ALL phases
+   ├─ design-impl → prototype-focused
+   └─ ui-refresh  → visual-only
+```
+
+### 2. Trust-Based Auto-Approval
+
+```
+Phase gate reached?
+   │
+   ├─ Trust: low (<80%)     → Manual approval required
+   ├─ Trust: medium (>=80%) → Auto-approve: design gate
+   ├─ Trust: high (>=90%)   → Auto-approve: design + tasks gates
+   └─ Trust: maximum (>=95%)→ Auto-approve: all gates + zero-touch eligible
+```
+
+Check current trust: `morph-spec trust status`
+
+### 3. Parallel vs Sequential Implementation
+
+```
+Task count > 10 AND multi-domain?
+   YES → morph-spec parallel plan {feature}
+         → Spawn P-Threads per domain
+         → Wait: morph-spec threads wait-all {feature}
+         → Merge results
+   NO  → Single B-Thread sequential implementation
+```
+
+### 4. Fusion Decision
+
+```
+Need highest-quality output for critical component?
+   YES → morph-spec agents-fuse run --count 3 --strategy best-of-n
+         → 3 F-Threads run independently
+         → Aggregator picks best result
+   NO  → Standard single-agent approach
+```
+
+### 5. Checkpoint Gate
+
+```
+Task 3, 6, 9, ... completed?
+   │
+   ├─ Run validators (architecture, security, packages)
+   ├─ ALL PASS → Continue, update trust metrics
+   └─ FAIL     → Block progress
+                  → Attempt 2: fix violations
+                  → Attempt 3: fix violations
+                  → Attempt 4: AskUserQuestion
+```
+
+---
+
+## Zero-Touch Path (Maximum Trust)
+
+When trust level is `maximum` (>95% checkpoint pass rate across 10+ checkpoints):
+
+```
+Feature request
+    │
+    ▼ morph-spec feature create --auto
+┌──────────────────────────────────────┐
+│         ZERO-TOUCH EXECUTION         │
+│                                      │
+│  Proposal auto-approved              │
+│  Design auto-approved                │
+│  Tasks auto-approved                 │
+│  Commits auto-signed                 │
+│  Rollback auto-triggered on fail     │
+│                                      │
+│  Escalation triggers:                │
+│  - Checkpoint fails 3x → pause       │
+│  - Architecture error → pause        │
+│  - Security error → BLOCK            │
+│  - Out-of-scope change → pause       │
+└──────────────────────────────────────┘
+    │
+    ▼
+Feature complete (no human intervention)
+```
+
+Configure zero-touch: `framework/workflows/configs/zero-touch.json`
+
+---
+
+## Analytics & Observability
+
+At every step, analytics events are logged to `.morph/analytics/`:
+
+| Event | Log File | When |
+|-------|----------|------|
+| Phase advanced | `threads-log.jsonl` | Each phase transition |
+| Task completed | `threads-log.jsonl` | Each `task done` |
+| Checkpoint passed/failed | `threads-log.jsonl` | Every 3 tasks |
+| Trust level changed | `trust-log.jsonl` | After each checkpoint |
+| Auto-approval used | `trust-log.jsonl` | When gate auto-approved |
+| Thread created/killed | `threads-log.jsonl` | Thread lifecycle events |
+
+View analytics: `morph-spec analytics feature {feature-name}`
+
+---
+
+## Context Efficiency at Each Phase
+
+Recommended context loading per phase:
+
+| Phase | Context Budget | Load |
+|-------|---------------|------|
+| Proposal | 5K tokens | `morph-spec prime feature` output only |
+| Design | 15K tokens | Prime + relevant 2-3 standards |
+| Clarify | 10K tokens | Spec summary + decisions |
+| Tasks | 8K tokens | Spec summary + existing tasks |
+| Implement | 20K/thread | Bundle + task-specific standards |
+| Sync | 5K tokens | Recap + new decisions |
+
+---
+
+## CLI Quick Reference (v3.0 New Commands)
+
+```bash
+# Workflow detection
+morph-spec detect-workflow "implement X"
+
+# Context
+morph-spec prime feature
+morph-spec context bundle create {feature}
+
+# Threads
+morph-spec threads list
+morph-spec threads wait-all {feature}
+
+# Trust
+morph-spec trust status
+morph-spec trust auto-calculate {feature}
+
+# Parallel
+morph-spec parallel plan {feature}
+morph-spec squad-template list
+
+# Fusion
+morph-spec agents-fuse run --count 3 --prompt "..."
+
+# HOPs
+morph-spec hop list
+morph-spec hop render hop-backend-squad output.md --variables '{...}'
+
+# Migration
+morph-spec migrate status
+morph-spec migrate v2-to-v3
+
+# Analytics
+morph-spec analytics feature {feature}
+morph-spec core-four {feature}
+
+# Doctor
+morph-spec doctor --v3
+```
+
+---
+
+## Related
+
+- [Thread Management](THREAD-MANAGEMENT.md) — Thread types and lifecycle
+- [Context Optimization](CONTEXT-OPTIMIZATION.md) — Token efficiency techniques
+- [Meta-Prompts](META-PROMPTS.md) — HOP template system
+- [Migration Guide](MIGRATION-GUIDE.md) — Upgrading from v2.x

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