@polymorphism-tech/morph-spec 3.2.0 → 4.3.0

package/docs/llm-interaction-config.md

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