@polymorphism-tech/morph-spec 4.3.7 → 4.6.0

package/.morph/framework/templates/docs/clarifications.md

@@ -0,0 +1,253 @@
+# Clarifications - {{FEATURE_NAME_TITLE}}
+
+**Feature**: {{FEATURE_NAME}}
+**Date**: {{DATE}}
+**Phase**: CLARIFY (Phase 3)
+**Status**: {{#if status}}{{status}}{{else}}In Progress{{/if}}
+
+---
+
+## Purpose
+
+This document addresses ambiguities, edge cases, and questions identified during the design review. All clarifications should be incorporated back into `spec.md` after approval.
+
+---
+
+## Questions & Answers
+
+{{#each questions}}
+### Q{{this.id}}: {{this.category}} - {{this.title}}
+
+**Question:**
+{{this.question}}
+
+**Context:**
+{{this.context}}
+
+**Answer:**
+{{this.answer}}
+
+**Impact:**
+{{this.impact}}
+
+**Spec Updates Required:**
+{{#each this.specUpdates}}
+- {{this}}
+{{/each}}
+
+**Priority:** {{this.priority}}
+**Resolved:** {{#if this.resolved}}✅ Yes{{else}}❌ No{{/if}}
+**Resolved By:** {{#if this.resolvedBy}}{{this.resolvedBy}}{{else}}_Pending_{{/if}}
+
+---
+{{/each}}
+
+## Edge Cases Identified
+
+{{#each edgeCases}}
+### EC{{@index}}: {{this.title}}
+
+**Scenario:**
+{{this.scenario}}
+
+**Current Behavior:**
+{{this.currentBehavior}}
+
+**Expected Behavior:**
+{{this.expectedBehavior}}
+
+**Proposed Solution:**
+{{this.proposedSolution}}
+
+**Acceptance Criteria:**
+{{#each this.acceptanceCriteria}}
+- [ ] {{this}}
+{{/each}}
+
+**Affected Components:**
+{{#each this.affectedComponents}}
+- {{this}}
+{{/each}}
+
+---
+{{/each}}
+
+## Assumptions Validated
+
+{{#each assumptions}}
+### A{{@index}}: {{this.title}}
+
+**Assumption:**
+{{this.description}}
+
+**Validation:**
+{{#if this.validated}}✅ Confirmed{{else}}❌ Invalid{{/if}}
+
+**Notes:**
+{{this.notes}}
+
+**Action Required:**
+{{#if this.action}}{{this.action}}{{else}}_None_{{/if}}
+
+---
+{{/each}}
+
+## Business Rules Clarified
+
+{{#each businessRules}}
+### BR{{@index}}: {{this.title}}
+
+**Rule:**
+{{this.rule}}
+
+**Rationale:**
+{{this.rationale}}
+
+**Examples:**
+{{#each this.examples}}
+- {{this}}
+{{/each}}
+
+**Exceptions:**
+{{#if this.exceptions}}
+{{#each this.exceptions}}
+- {{this}}
+{{/each}}
+{{else}}
+_None_
+{{/if}}
+
+---
+{{/each}}
+
+## Data Validation Rules
+
+{{#each dataValidations}}
+### DV{{@index}}: {{this.field}} Validation
+
+**Field:** {{this.field}}
+**Entity:** {{this.entity}}
+
+**Validation Rules:**
+{{#each this.rules}}
+- {{this}}
+{{/each}}
+
+**Error Messages:**
+{{#each this.errorMessages}}
+- {{this.condition}}: "{{this.message}}"
+{{/each}}
+
+**Impact on UX:**
+{{this.uxImpact}}
+
+---
+{{/each}}
+
+## Performance & Scalability Clarifications
+
+{{#each performanceClarifications}}
+### PC{{@index}}: {{this.title}}
+
+**Concern:**
+{{this.concern}}
+
+**Clarification:**
+{{this.clarification}}
+
+**Solution:**
+{{this.solution}}
+
+**Performance Target:**
+{{this.target}}
+
+---
+{{/each}}
+
+## Security & Authorization Clarifications
+
+{{#each securityClarifications}}
+### SC{{@index}}: {{this.title}}
+
+**Security Concern:**
+{{this.concern}}
+
+**Clarification:**
+{{this.clarification}}
+
+**Implementation:**
+{{this.implementation}}
+
+**Affected Roles:**
+{{#each this.affectedRoles}}
+- {{this}}
+{{/each}}
+
+---
+{{/each}}
+
+## Integration & External Dependencies
+
+{{#each integrationClarifications}}
+### IC{{@index}}: {{this.title}}
+
+**External System:**
+{{this.externalSystem}}
+
+**Question:**
+{{this.question}}
+
+**Clarification:**
+{{this.clarification}}
+
+**API Endpoint/Method:**
+{{this.apiDetails}}
+
+**Error Handling:**
+{{this.errorHandling}}
+
+---
+{{/each}}
+
+## Summary
+
+**Total Questions:** {{#if totalQuestions}}{{totalQuestions}}{{else}}0{{/if}}
+**Resolved:** {{#if resolvedCount}}{{resolvedCount}}{{else}}0{{/if}}
+**Pending:** {{#if pendingCount}}{{pendingCount}}{{else}}0{{/if}}
+
+**Edge Cases Identified:** {{#if edgeCaseCount}}{{edgeCaseCount}}{{else}}0{{/if}}
+**Business Rules Documented:** {{#if businessRuleCount}}{{businessRuleCount}}{{else}}0{{/if}}
+**Assumptions Validated:** {{#if assumptionCount}}{{assumptionCount}}{{else}}0{{/if}}
+
+---
+
+## Next Steps
+
+1. [ ] Resolve all pending questions
+2. [ ] Update `spec.md` with all clarifications
+3. [ ] Update `contracts.cs` if data model changes are needed
+4. [ ] Document breaking changes in `decisions.md`
+5. [ ] Get stakeholder approval on all clarifications
+6. [ ] Advance to Phase 4 (Tasks)
+
+---
+
+## Spec Updates Log
+
+**Changes to be made to `spec.md`:**
+
+{{#each specUpdates}}
+### Update {{@index}}
+
+**Section:** {{this.section}}
+**Type:** {{this.type}}
+**Description:** {{this.description}}
+**From Clarification:** {{this.clarificationId}}
+
+---
+{{/each}}
+
+---
+
+*Generated by MORPH-SPEC v{{FRAMEWORK_VERSION}}*
+*All clarifications must be incorporated into spec.md before advancing to Phase 4*

package/.morph/framework/templates/docs/onboarding.md

@@ -0,0 +1,123 @@
+# Onboarding Guide — {{PROJECT_NAME}}
+
+> Generated by MORPH-SPEC on {{DATE}}
+
+---
+
+## Project Overview
+
+- **Project:** {{PROJECT_NAME}}
+- **Stack:** {{STACK}}
+- **Architecture:** {{ARCHITECTURE}}
+
+---
+
+## Active Agents
+
+The following agents are configured for this project:
+
+{{AGENTS_LIST}}
+
+---
+
+## Available MCPs & Plugins
+
+{{AVAILABLE_MCPS}}
+
+---
+
+## Standards
+
+The following standards are enforced in this project:
+
+{{STANDARDS_SUMMARY}}
+
+Standards are located in:
+- `.morph/framework/standards/` — Framework standards (universal)
+- `.morph/context/` — Project-specific overrides
+
+---
+
+## Configured Workflow
+
+{{WORKFLOW_SUMMARY}}
+
+### Available Workflows
+
+| Workflow | Description | Phases |
+|----------|-------------|--------|
+| fast-track | Simple, well-defined features | 0→1→2→4→5 |
+| standard | Most features | 0→1→(1.5)→2→3→4→5 |
+| full-morph | Complex features with sync | 0→1→1.5→2→3→4→5→6 |
+| design-impl | Pre-planned work | 2→4→5 |
+| ui-refresh | Visual redesigns | 1.5→2→5 |
+
+---
+
+## Key Commands
+
+```bash
+# Start a feature
+# Just ask Claude Code to implement something
+
+# Check feature progress
+morph-spec status <feature>
+
+# Validate feature outputs
+morph-spec validate-feature <feature>
+
+# Manage tasks
+morph-spec task next <feature>
+morph-spec task start <feature> <task-id>
+morph-spec task done <feature> <task-id>
+
+# Save/restore checkpoints
+morph-spec checkpoint-save <feature>
+morph-spec checkpoint-list <feature>
+
+# View changes since last snapshot
+morph-spec diff <feature>
+
+# Health check
+morph-spec doctor
+```
+
+---
+
+## Project Structure
+
+```
+{{PROJECT_NAME}}/
+├── CLAUDE.md                      # Claude Code instructions
+├── .morph/
+│   ├── config/
+│   │   └── config.json            # Project configuration
+│   ├── framework/
+│   │   ├── agents.json            # Agent definitions
+│   │   ├── standards/             # Framework standards
+│   │   └── templates/             # Output templates
+│   ├── context/                   # Project context & overrides
+│   └── features/{feature}/        # Feature outputs
+│       ├── 0-proposal/
+│       ├── 1-design/
+│       ├── 2-ui/
+│       ├── 3-tasks/
+│       └── 4-implement/
+└── .claude/
+    ├── commands/                  # Slash commands
+    ├── skills/                    # Workflow skills
+    └── settings.local.json        # Hooks & permissions
+```
+
+---
+
+## Getting Started
+
+1. **Ask Claude Code** to implement a feature
+2. **Follow the phases** — the framework guides you automatically
+3. **Approve at pauses** — design and task breakdowns need your approval
+4. **Check progress** with `morph-spec status <feature>`
+
+---
+
+*Generated by MORPH-SPEC v{{VERSION}} — Polymorphism Tech*

package/.morph/framework/templates/docs/schema-analysis.md

@@ -0,0 +1,119 @@
+# Schema Analysis - {{FEATURE_NAME_TITLE}}
+
+**Feature**: {{FEATURE_NAME}}
+**Date**: {{DATE}}
+**Method**: {{#if method}}{{method}}{{else}}Manual Code Analysis{{/if}}
+**Analyzed By**: {{AUTHOR}}
+
+---
+
+## Summary
+
+**Tables Analyzed**: {{#if tableCount}}{{tableCount}}{{else}}0{{/if}}
+**Code Files Scanned**: {{#if fileCount}}{{fileCount}}{{else}}0{{/if}}
+**MCP Tools Used**: {{#if mcpUsed}}{{mcpUsed}}{{else}}No (manual analysis){{/if}}
+
+---
+
+## Tables Analyzed
+
+{{#each tables}}
+### Table: {{this.name}}
+
+**Source:**
+{{#if this.mcpSource}}- MCP: {{this.mcpSource}}{{/if}}
+{{#if this.codeSource}}- Code: {{this.codeSource}}{{/if}}
+
+**Columns:**
+| Column Name | Type | Nullable | Default | Notes |
+|------------|------|----------|---------|-------|
+{{#each this.columns}}
+| {{this.name}} | {{this.type}} | {{#if this.nullable}}YES{{else}}NO{{/if}} | {{#if this.default}}{{this.default}}{{else}}-{{/if}} | {{#if this.notes}}{{this.notes}}{{else}}-{{/if}} |
+{{/each}}
+
+**Relationships:**
+{{#each this.relationships}}
+- {{this.description}}
+{{/each}}
+
+**Indexes:**
+{{#each this.indexes}}
+- {{this.description}}
+{{/each}}
+
+---
+{{/each}}
+
+## ⚠️ CRITICAL FINDINGS
+
+### Field Name Mismatches (MUST FIX)
+
+{{#if fieldMismatches}}
+{{#each fieldMismatches}}
+- ❌ {{this.description}}
+{{/each}}
+{{else}}
+✅ No field name mismatches found
+{{/if}}
+
+### Type Mismatches
+
+{{#if typeMismatches}}
+{{#each typeMismatches}}
+- ⚠️ {{this.description}}
+{{/each}}
+{{else}}
+✅ No type mismatches found
+{{/if}}
+
+### Relationship Corrections
+
+{{#if relationshipIssues}}
+{{#each relationshipIssues}}
+- ⚠️ {{this.description}}
+{{/each}}
+{{else}}
+✅ All relationships correctly identified
+{{/if}}
+
+---
+
+## Recommendations for contracts.cs
+
+Based on real schema analysis:
+
+\`\`\`csharp
+{{#each dtoRecommendations}}
+// {{this.tableName}} → {{this.dtoName}}
+public record {{this.dtoName}}(
+{{#each this.fields}}
+    {{this.type}} {{this.name}}{{#if this.nullable}}?{{/if}}{{#unless @last}},{{/unless}}  // {{#if this.comment}}{{this.comment}}{{/if}}
+{{/each}}
+);
+
+{{/each}}
+\`\`\`
+
+---
+
+## Analysis Notes
+
+{{#if notes}}
+{{notes}}
+{{else}}
+_No additional notes._
+{{/if}}
+
+---
+
+## Next Steps
+
+- [ ] Verify schema analysis with stakeholders
+- [ ] Generate `contracts.cs` using real field names
+- [ ] Update `spec.md` data model section with findings
+- [ ] Document any schema migrations needed in `decisions.md`
+
+---
+
+*Generated by MORPH-SPEC v{{FRAMEWORK_VERSION}}*
+*Schema analysis helps prevent DTO field name mismatches and ensures contracts match real database schema*