@polymorphism-tech/morph-spec 3.1.0 → 4.2.0

package/docs/llm-interaction-config.md

@@ -0,0 +1,735 @@
+# LLM Interaction Configuration Guide
+
+**MORPH-SPEC v3.0** introduces a comprehensive configuration system for controlling LLM interaction features via `.morph/config/llm-interaction.json`.
+
+---
+
+## Quick Start
+
+### 1. Default Configuration
+
+On `morph-spec init`, a default `llm-interaction.json` is created with recommended settings:
+
+```json
+{
+  "$schema": "./llm-interaction-schema.json",
+  "version": "1.0.0",
+  "enabled": true,
+
+  "approvalGates": {
+    "enabled": true,
+    "required": ["design", "tasks"],
+    "optional": ["proposal", "uiux"],
+    "allowSkip": false
+  },
+
+  "checkpoints": {
+    "frequency": 3,
+    "autoValidate": true,
+    "validators": {
+      "enabled": ["architecture", "packages", "design-system", "security"]
+    },
+    "hooks": {
+      "runTests": false,
+      "runLinters": true,
+      "buildCheck": false
+    },
+    "onFailure": {
+      "blockProgress": true,
+      "maxRetries": 3
+    }
+  },
+
+  "phaseValidation": {
+    "strictTransitions": true,
+    "requireContentValidation": true,
+    "allowPhaseSkip": false,
+    "forceSequential": true
+  },
+
+  "agentSpawning": {
+    "enabled": true,
+    "autoDetect": true,
+    "spawnThreshold": {
+      "complexity": "high",
+      "fileCount": 15,
+      "multiDomain": true,
+      "agentCount": 5
+    },
+    "teamMode": "auto"
+  },
+
+  "metadata": {
+    "autoGenerate": true,
+    "updateFrequency": "on_task_done"
+  },
+
+  "patterns": {
+    "captureOnComplete": true,
+    "searchBeforeStart": true,
+    "location": ".morph/memory/patterns-learned.md"
+  },
+
+  "templates": {
+    "mcpDataInjection": true,
+    "dataSources": ["projectStructure", "complianceStatus", "recentActivity"]
+  },
+
+  "interactiveDecisions": {
+    "enabled": true,
+    "usePromptTemplates": true,
+    "requireUserInput": ["architecture-choice", "scope-change", "validator-override"]
+  }
+}
+```
+
+---
+
+## Configuration Sections
+
+### 1. Approval Gates
+
+**Controls:** Explicit approval tracking for phase transitions.
+
+```json
+{
+  "approvalGates": {
+    "enabled": true,              // Enable approval gate system
+    "required": ["design", "tasks"],  // Required gates that block advancement
+    "optional": ["proposal", "uiux"], // Optional gates (tracked but don't block)
+    "allowSkip": false            // Allow --skip-approval flag
+  }
+}
+```
+
+**Behavior:**
+- When `enabled: true`, phase transitions check approval status
+- `required` gates **block** `npx morph-spec phase advance` until approved
+- `optional` gates are tracked but don't block
+- `allowSkip: false` prevents `--skip-approval` override (strict mode)
+
+**Commands:**
+```bash
+# Approve a gate
+npx morph-spec approve {feature} design
+
+# Reject with reason
+npx morph-spec reject {feature} design "Missing security considerations"
+
+# Check status
+npx morph-spec approval-status {feature}
+```
+
+**Use Cases:**
+- **Strict governance:** `required: ["proposal", "design", "tasks"]`, `allowSkip: false`
+- **Lightweight:** `required: ["design"]`, `allowSkip: true`
+- **No gates:** `enabled: false`
+
+---
+
+### 2. Checkpoints
+
+**Controls:** Automated validation at regular task intervals.
+
+```json
+{
+  "checkpoints": {
+    "frequency": 3,               // Run checkpoint every N tasks
+    "autoValidate": true,         // Auto-run validators
+    "validators": {
+      "enabled": ["architecture", "packages", "security"]
+    },
+    "hooks": {
+      "runTests": false,          // Run test suite at checkpoints
+      "runLinters": true,         // Run linters (eslint, dotnet format)
+      "buildCheck": false         // Run build verification
+    },
+    "onFailure": {
+      "blockProgress": true,      // Block task completion if checkpoint fails
+      "maxRetries": 3             // Max retries before escalation
+    }
+  }
+}
+```
+
+**Behavior:**
+- Every `frequency` tasks (e.g., T003, T006, T009), runs checkpoint hooks
+- If `autoValidate: true`, runs all `enabled` validators
+- If `onFailure.blockProgress: true`, task NOT marked done until violations fixed
+- After `maxRetries` failures, prompts LLM to escalate or simplify
+
+**Validators:**
+- `architecture`: DI patterns, Blazor lifecycle, async/await anti-patterns
+- `packages`: NuGet/npm conflicts, outdated dependencies
+- `design-system`: CSS compliance, color palette, spacing
+- `security`: Secrets exposed, SQL injection, XSS
+
+**Use Cases:**
+- **Strict:** `autoValidate: true`, `blockProgress: true`, `frequency: 3`
+- **Lightweight:** `autoValidate: false`, `blockProgress: false`, `frequency: 5`
+- **Manual only:** `autoValidate: false`, `hooks: {runTests: false}`
+
+---
+
+### 3. Phase Validation
+
+**Controls:** State machine enforcement for phase transitions.
+
+```json
+{
+  "phaseValidation": {
+    "strictTransitions": true,       // Enforce valid state machine transitions
+    "requireContentValidation": true, // Validate spec.md and tasks.json structure
+    "allowPhaseSkip": false,         // Allow jumping phases (e.g., setup → tasks)
+    "forceSequential": true          // Must go through all phases in order
+  }
+}
+```
+
+**Behavior:**
+- `strictTransitions: true`: Only valid transitions allowed (e.g., `proposal → setup`, NOT `proposal → implement`)
+- `requireContentValidation: true`: Checks spec.md has required sections, tasks.json has valid structure
+- `allowPhaseSkip: false`: Cannot skip optional phases (uiux, sync) without explicit decision
+- `forceSequential: true`: Must complete phases in order (proposal → setup → uiux/design → clarify → tasks → implement)
+
+**Valid Transitions (State Machine):**
+```
+proposal → setup
+setup → uiux | design
+uiux → design
+design → clarify
+clarify → tasks
+tasks → implement
+implement → sync | archived
+sync → archived
+```
+
+**Use Cases:**
+- **Strict:** All true (recommended for teams)
+- **Flexible:** `allowPhaseSkip: true`, `forceSequential: false`
+- **No validation:** `strictTransitions: false`
+
+---
+
+### 4. Agent Spawning
+
+**Controls:** When to suggest Task tool agent spawning.
+
+```json
+{
+  "agentSpawning": {
+    "enabled": true,                // Enable agent spawning suggestions
+    "autoDetect": true,             // Auto-detect based on thresholds
+    "spawnThreshold": {
+      "complexity": "high",         // Suggest if complexity >= high
+      "fileCount": 15,              // Suggest if 15+ files to modify
+      "multiDomain": true,          // Suggest if backend + frontend + infra
+      "agentCount": 5               // Suggest if 5+ agents activated
+    },
+    "teamMode": "auto"              // auto | manual | always
+  }
+}
+```
+
+**Behavior:**
+- When ALL thresholds met, LLM suggests spawning agents via Task tool
+- `teamMode`:
+  - `auto`: Suggest based on thresholds
+  - `manual`: Never suggest, only if user requests
+  - `always`: Always spawn for multi-agent features
+
+**Command:**
+```bash
+# Get team configuration
+npx morph-spec spawn-team {feature}
+
+# Returns Task tool configs for:
+# - Backend Squad (dotnet-senior, ef-modeler, api-designer)
+# - Frontend Squad (blazor-senior, fluent-designer)
+# - Infrastructure Squad (bicep-architect, azure-specialist)
+```
+
+**Use Cases:**
+- **Auto-spawn:** `autoDetect: true`, `teamMode: "auto"`
+- **Manual only:** `autoDetect: false`, `teamMode: "manual"`
+- **Always parallel:** `teamMode: "always"` (even for simple features)
+
+---
+
+### 5. Metadata
+
+**Controls:** Auto-generation of metadata.json summaries.
+
+```json
+{
+  "metadata": {
+    "autoGenerate": true,             // Auto-generate metadata.json
+    "updateFrequency": "on_task_done" // When to update (on_task_done | on_checkpoint | on_phase_advance)
+  }
+}
+```
+
+**Behavior:**
+- `autoGenerate: true`: After each task completion, regenerates `metadata.json`
+- `updateFrequency`:
+  - `on_task_done`: Update after every task (most frequent, recommended)
+  - `on_checkpoint`: Update only at checkpoints (e.g., T003, T006)
+  - `on_phase_advance`: Update only when phase changes
+
+**metadata.json Structure:**
+```json
+{
+  "version": "1.0.0",
+  "feature": "user-authentication",
+  "status": "active",
+  "phase": "implement",
+  "spec": {
+    "id": "user-auth",
+    "summary": { "problem": "...", "solution": "...", "tags": [...] },
+    "requirements": [...],
+    "dataModel": [...]
+  },
+  "decisions": {
+    "decisions": [ { "id": "ADR-001", "title": "...", "fullPath": "..." } ]
+  },
+  "tasks": { "total": 12, "completed": 8, "progress": "67%" },
+  "agents": ["dotnet-senior", "ef-modeler"],
+  "checkpoints": [ { "num": 1, "passed": true } ]
+}
+```
+
+**Use Cases:**
+- **Always up-to-date:** `autoGenerate: true`, `updateFrequency: "on_task_done"`
+- **Checkpoint-based:** `updateFrequency: "on_checkpoint"`
+- **Manual only:** `autoGenerate: false`
+
+---
+
+### 6. Patterns
+
+**Controls:** Learning system and pattern library.
+
+```json
+{
+  "patterns": {
+    "captureOnComplete": true,              // Prompt to capture patterns on feature complete
+    "searchBeforeStart": true,              // Search patterns before starting new feature
+    "location": ".morph/memory/patterns-learned.md"
+  }
+}
+```
+
+**Behavior:**
+- `searchBeforeStart: true`: LLM runs `npx morph-spec search-patterns "{keywords}"` before PROPOSAL phase
+- `captureOnComplete: true`: After feature archived, LLM prompts to capture lessons
+
+**Commands:**
+```bash
+# Search patterns
+npx morph-spec search-patterns "blazor state"
+npx morph-spec search-patterns "background job"
+
+# Capture pattern
+npx morph-spec capture-pattern {feature} success "Pattern description"
+npx morph-spec capture-pattern {feature} avoid "Anti-pattern description"
+npx morph-spec capture-pattern {feature} optimization "Performance improvement"
+
+# Categories: success, avoid, optimization, security, convention, best-practice
+```
+
+**Use Cases:**
+- **Continuous learning:** Both true (recommended)
+- **Search only:** `searchBeforeStart: true`, `captureOnComplete: false`
+- **No learning:** Both false
+
+---
+
+### 7. Templates
+
+**Controls:** MCP data injection in templates.
+
+```json
+{
+  "templates": {
+    "mcpDataInjection": true,                     // Enable MCP data injection
+    "dataSources": [
+      "projectStructure",                         // File counts, language stats
+      "complianceStatus",                         // Validators, violations
+      "recentActivity"                            // Last feature, commits, branches
+    ]
+  }
+}
+```
+
+**Behavior:**
+- When rendering templates with `--with-mcp-data`, injects live project metrics
+- Available placeholders:
+  - `{{MCP_PROJECT_FILES}}`, `{{MCP_CS_FILES}}`, `{{MCP_TS_FILES}}`
+  - `{{MCP_TEST_COVERAGE}}`, `{{MCP_COMPLIANCE_SCORE}}`
+  - `{{MCP_ARCHITECTURE_VIOLATIONS}}`, `{{MCP_SECURITY_ISSUES}}`
+  - `{{MCP_LAST_FEATURE}}`, `{{MCP_LAST_COMMIT}}`
+  - [Full list in `.morph/templates/MCP-TEMPLATES-README.md`]
+
+**Usage:**
+```bash
+# Render with MCP data
+node bin/render-template.js \
+  .morph/templates/proposal-with-mcp.md \
+  .morph/features/{feature}/proposal.md \
+  '{"FEATURE_NAME":"{feature}"}' \
+  --with-mcp-data --verbose
+```
+
+**Use Cases:**
+- **Context-aware docs:** `mcpDataInjection: true`, all data sources
+- **No dynamic data:** `mcpDataInjection: false`
+
+---
+
+### 8. Interactive Decisions
+
+**Controls:** When to use AskUserQuestion patterns.
+
+```json
+{
+  "interactiveDecisions": {
+    "enabled": true,                              // Enable structured decision prompts
+    "usePromptTemplates": true,                   // Use templates from decision-prompts.md
+    "requireUserInput": [
+      "architecture-choice",                      // Multiple valid approaches
+      "scope-change",                             // Significant scope modifications
+      "validator-override"                        // Skipping failed validation
+    ]
+  }
+}
+```
+
+**Behavior:**
+- When `enabled: true`, LLM uses AskUserQuestion for key decisions
+- `usePromptTemplates: true`: Uses templates from `.morph/templates/decision-prompts.md`
+- `requireUserInput`: Decisions that MUST use AskUserQuestion (not free-form text)
+
+**Templates Available:**
+- Scope clarification (proposal phase)
+- Architecture choice (design phase)
+- Task ordering conflict (tasks phase)
+- Validation failure recovery (implement phase)
+- Breaking change approval (implement phase)
+
+**Use Cases:**
+- **Interactive:** All enabled (recommended for team projects)
+- **Autonomous:** `enabled: false` (LLM makes all decisions)
+
+---
+
+## Configuration Presets
+
+### Preset 1: Strict (Recommended for Teams)
+
+```json
+{
+  "approvalGates": { "enabled": true, "required": ["design", "tasks"], "allowSkip": false },
+  "checkpoints": { "autoValidate": true, "onFailure": { "blockProgress": true } },
+  "phaseValidation": { "strictTransitions": true, "requireContentValidation": true },
+  "agentSpawning": { "enabled": true, "teamMode": "auto" },
+  "metadata": { "autoGenerate": true },
+  "patterns": { "searchBeforeStart": true, "captureOnComplete": true },
+  "interactiveDecisions": { "enabled": true }
+}
+```
+
+**Best for:**
+- Team projects with governance
+- Production features
+- Learning from mistakes
+
+---
+
+### Preset 2: Lightweight (Solo Developers)
+
+```json
+{
+  "approvalGates": { "enabled": true, "required": ["design"], "allowSkip": true },
+  "checkpoints": { "autoValidate": true, "onFailure": { "blockProgress": false } },
+  "phaseValidation": { "strictTransitions": true, "allowPhaseSkip": true },
+  "agentSpawning": { "enabled": false },
+  "metadata": { "autoGenerate": false },
+  "patterns": { "searchBeforeStart": true, "captureOnComplete": false },
+  "interactiveDecisions": { "enabled": true }
+}
+```
+
+**Best for:**
+- Solo developers
+- Rapid prototyping
+- Experimental features
+
+---
+
+### Preset 3: No Guardrails (Fast Iteration)
+
+```json
+{
+  "approvalGates": { "enabled": false },
+  "checkpoints": { "autoValidate": false },
+  "phaseValidation": { "strictTransitions": false, "allowPhaseSkip": true },
+  "agentSpawning": { "enabled": false },
+  "metadata": { "autoGenerate": false },
+  "patterns": { "searchBeforeStart": false, "captureOnComplete": false },
+  "interactiveDecisions": { "enabled": false }
+}
+```
+
+**Best for:**
+- Spikes and experiments
+- Throwaway code
+- Learning the framework
+
+**⚠️ Warning:** Not recommended for production features.
+
+---
+
+## Runtime Overrides
+
+Most features can be overridden at runtime:
+
+```bash
+# Skip approval gate (if allowSkip: true)
+npx morph-spec phase advance {feature} --skip-approval
+
+# Force invalid transition
+npx morph-spec phase advance {feature} --force
+
+# Skip validation
+npx morph-spec task done {feature} T001 --skip-validation
+
+# Disable checkpoints for one task
+# (Not available - checkpoints run based on config only)
+```
+
+---
+
+## Migration & Upgrade
+
+### Migrating Existing Projects
+
+```bash
+# Auto-migrate state.json to include approval gates
+npx morph-spec migrate-state
+
+# Creates llm-interaction.json if missing
+npx morph-spec init --force
+```
+
+**Migration Behavior:**
+- Adds `approvalGates` to all features in `state.json`
+- Past phases auto-approved (e.g., if currently in implement, design/tasks gates approved)
+- Creates empty `.morph/memory/patterns-learned.md`
+- Creates default `llm-interaction.json` with conservative settings
+
+### Upgrading Configuration
+
+```bash
+# Upgrade to latest schema version
+npx morph-spec upgrade --to-version=3.0.0
+
+# Options:
+# [1] Full upgrade (all breaking changes)
+# [2] Conservative (keep old behavior, opt-in to new)
+# [3] Custom (choose per-feature)
+```
+
+---
+
+## Troubleshooting
+
+### Checkpoint Always Failing
+
+**Problem:** Checkpoint fails every 3 tasks despite fixing issues.
+
+**Solutions:**
+1. Check which validator is failing:
+   ```bash
+   npx morph-spec validate architecture --verbose
+   npx morph-spec validate packages --verbose
+   npx morph-spec validate security --verbose
+   ```
+
+2. Disable problematic validator temporarily:
+   ```json
+   {
+     "checkpoints": {
+       "validators": {
+         "enabled": ["packages", "security"]  // Removed "architecture"
+       }
+     }
+   }
+   ```
+
+3. Set `blockProgress: false` to continue despite failures:
+   ```json
+   {
+     "checkpoints": {
+       "onFailure": { "blockProgress": false }
+     }
+   }
+   ```
+
+---
+
+### Approval Gates Not Blocking
+
+**Problem:** Can advance phase without approval.
+
+**Solutions:**
+1. Check `allowSkip` setting:
+   ```json
+   { "approvalGates": { "allowSkip": false } }
+   ```
+
+2. Ensure gate is in `required` list:
+   ```json
+   { "approvalGates": { "required": ["design", "tasks"] } }
+   ```
+
+3. Verify no `--force` flag used:
+   ```bash
+   # DON'T use --force unless intentional
+   npx morph-spec phase advance {feature}  # ✅ Correct
+   npx morph-spec phase advance {feature} --force  # ❌ Bypasses gates
+   ```
+
+---
+
+### MCP Data Not Injecting
+
+**Problem:** `{{MCP_PROJECT_FILES}}` appears in rendered template.
+
+**Solutions:**
+1. Ensure `--with-mcp-data` flag used:
+   ```bash
+   node bin/render-template.js template.md output.md '{}' --with-mcp-data
+   ```
+
+2. Check config:
+   ```json
+   { "templates": { "mcpDataInjection": true } }
+   ```
+
+3. Verify data sources available:
+   - Git repo initialized (`git log` works)
+   - Coverage file exists (`coverage/coverage-summary.json`)
+   - `.morph/state.json` exists
+
+---
+
+## Best Practices
+
+### 1. Start Strict, Relax Later
+
+Begin with **Preset 1: Strict** for first 2-3 features. Once comfortable, adjust:
+- Reduce checkpoint frequency (3 → 5)
+- Make some gates optional
+- Disable MCP data if not useful
+
+### 2. Use Approval Gates for Critical Decisions
+
+**ALWAYS require approval for:**
+- Design phase (spec + contracts)
+- Tasks phase (breakdown + estimates)
+
+**Optional approval for:**
+- Proposal (if quick iteration needed)
+- UI/UX (if design-heavy feature)
+
+### 3. Checkpoint Frequency
+
+- **High-risk features:** `frequency: 3` (every 3 tasks)
+- **Standard features:** `frequency: 5`
+- **Low-risk features:** `frequency: 10` or `autoValidate: false`
+
+### 4. Pattern Library
+
+**Day 1-30:** Focus on `searchBeforeStart: true` (leverage pre-seeded patterns)
+**Day 30+:** Enable `captureOnComplete: true` (build your own library)
+
+### 5. Metadata
+
+**Always enable** `autoGenerate: true` for features with:
+- 10+ tasks
+- Multiple agents
+- Complex decision history
+
+**Skip for:**
+- Spike/POC features
+- 1-2 task features
+
+---
+
+## Schema Reference
+
+Full JSON schema: `.morph/config/llm-interaction-schema.json`
+
+Validate config:
+```bash
+# Auto-validates on phase advance, checkpoint, etc.
+# Manual validation:
+node -e "require('ajv')().validate(require('.morph/config/llm-interaction-schema.json'), require('.morph/config/llm-interaction.json'))"
+```
+
+---
+
+## Examples
+
+### Example 1: Enable Strict Mode Mid-Project
+
+```bash
+# Edit .morph/config/llm-interaction.json
+{
+  "checkpoints": {
+    "onFailure": { "blockProgress": true }  // Changed from false
+  }
+}
+
+# Next task will block on checkpoint failure
+npx morph-spec task done my-feature T007
+```
+
+---
+
+### Example 2: Disable Agent Spawning Suggestions
+
+```bash
+# Edit .morph/config/llm-interaction.json
+{
+  "agentSpawning": { "enabled": false }
+}
+
+# LLM will never suggest spawning agents, even if thresholds met
+```
+
+---
+
+### Example 3: Custom Checkpoint Frequency
+
+```bash
+# Edit .morph/config/llm-interaction.json
+{
+  "checkpoints": { "frequency": 5 }
+}
+
+# Checkpoints now at T005, T010, T015 instead of T003, T006, T009
+```
+
+---
+
+## See Also
+
+- [CLAUDE.md](../CLAUDE.md) - LLM instructions for using these features
+- [.morph/templates/MCP-TEMPLATES-README.md](.morph/templates/MCP-TEMPLATES-README.md) - MCP data placeholders
+- [.morph/templates/decision-prompts.md](.morph/templates/decision-prompts.md) - Decision templates
+- [.morph/memory/patterns-learned.md](.morph/memory/patterns-learned.md) - Pattern library
+
+---
+
+*MORPH-SPEC v3.0 - LLM Interaction Configuration Guide*