@polymorphism-tech/morph-spec 4.3.7 → 4.6.0

package/framework/rules/morph-workflow.md

@@ -0,0 +1,86 @@
+# MORPH-SPEC Workflow Rules
+
+> Always-active rules for all MORPH-SPEC managed projects.
+
+---
+
+## Spec-First Mandate
+
+**NEVER skip to code without a specification.** Every feature must progress through phases:
+
+1. **Proposal** — User story + acceptance criteria (`0-proposal/proposal.md`)
+2. **Design** — Technical spec + C# contracts + decisions (`1-design/`)
+3. **Tasks** — Atomic task list (`3-tasks/tasks.md`)
+4. **Implement** — Code + recap (`4-implement/recap.md`)
+
+UI-heavy features also include **UI/UX** phase (`2-ui/`) between Design and Tasks.
+
+---
+
+## Phase Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/morph-proposal {feature}` | Full spec pipeline (phases 1–4, pauses for approval) |
+| `/morph-apply {feature}` | Implement feature (phase 5) |
+| `/morph-status` | Feature dashboard |
+
+---
+
+## Output Paths
+
+All outputs go in `.morph/features/{feature}/`:
+
+| Phase | Path |
+|-------|------|
+| Proposal | `0-proposal/proposal.md` |
+| Spec | `1-design/spec.md` |
+| Contracts | `1-design/contracts.cs` |
+| Decisions | `1-design/decisions.md` |
+| UI Design | `2-ui/design-system.md`, `mockups.md`, `components.md`, `flows.md` |
+| Tasks | `3-tasks/tasks.md` |
+| Recap | `4-implement/recap.md` |
+
+---
+
+## Checkpoints
+
+Run a checkpoint every 3 completed tasks:
+- Validate architecture compliance
+- Check package versions
+- Scan for security issues
+- Verify design system adherence (UI features)
+
+---
+
+## Approval Gates
+
+**Design Gate:** Before moving from Design → Tasks, spec must be approved.
+**Implementation Gate:** Before starting implementation, task list must be approved.
+
+Check approval status: `morph-spec state show {feature}`
+
+---
+
+## Protected Files
+
+**NEVER directly edit:**
+- `.morph/state.json` — Managed by CLI only
+- `.morph/framework/**` — Read-only framework content
+
+---
+
+## Test File Policy
+
+When a test fails, always follow this order:
+
+1. **Analyze first** — determine if the IMPLEMENTATION is wrong or the TEST SPEC is wrong
+2. **Fix implementation first** — the test is the spec; trust it by default
+3. **Only modify a test file if the test expectation itself is incorrect** — wrong expected value, wrong behavior modeled
+4. **Before modifying any test file, explain WHY the test spec is wrong** — what the correct behavior is and why the test doesn't model it
+
+Do not modify test files to make a failing test pass when the implementation is the actual problem.
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/rules/testing-standards.md

@@ -0,0 +1,11 @@
+---
+paths:
+  - "tests/**"
+  - "**/*.test.*"
+  - "**/*.spec.*"
+  - "**/*Tests.cs"
+---
+
+# Testing Standards
+
+@.morph/framework/standards/core/testing.md

package/framework/skills/README.md

@@ -0,0 +1,66 @@
+# MORPH-SPEC Skills
+
+Skills installed to `.claude/skills/` during `morph-spec init` (or `morph-spec update`).
+
+Each skill is a directory: `{name}/SKILL.md` + optional `scripts/`, `references/`, `assets/`.
+
+---
+
+## level-0-meta — Utilities & Meta-Skills
+
+| Skill | Description |
+|-------|-------------|
+| `tool-usage-guide` | Tool selection flowchart — which tool for which action |
+| `morph-checklist` | Pre-session checklist for MORPH-SPEC projects |
+| `simulation-checklist` | Checklist for AI simulation / prompt testing |
+| `brainstorming` | Collaborative ideation → spec via dialogue |
+| `verification-before-completion` | Gate check before marking any work done |
+| `code-review` | .NET/C# review checklist (naming, arch, async, DI, DTOs) |
+| `morph-replicate` | Convert HTML prototypes to Blazor components |
+
+### level-0-meta extras
+
+| Skill | File | Purpose |
+|-------|------|---------|
+| `brainstorming` | `references/proposal-example.md` | Filled-in proposal.md example |
+| `verification-before-completion` | `scripts/check-phase-outputs.mjs` | Validate required phase outputs exist |
+| `code-review` | `references/review-example.md` | Filled-in review with finding format |
+| `code-review` | `scripts/scan-csharp.mjs` | Scan .cs files for CRITICAL/HIGH violations |
+
+---
+
+## level-1-workflows — Phase Workflow Skills
+
+Invoked internally by `/morph-proposal` and `/morph-apply`. Not user-invocable.
+
+| Skill | Phase | Description |
+|-------|-------|-------------|
+| `phase-codebase-analysis` | 0 | Analyse existing codebase before design |
+| `phase-setup` | 1 | Project scaffolding and initial setup |
+| `phase-design` | 2 | Technical spec + contracts + decisions |
+| `phase-uiux` | 3 | UI/UX design system + mockups + components |
+| `phase-clarify` | 4 | Clarification questions → edge cases → spec update |
+| `phase-tasks` | 5 | Break spec into ordered task list (tasks.md) |
+| `phase-implement` | 6 | Implement tasks with TDD + checkpoints + recap |
+
+### level-1-workflows extras
+
+| Skill | File | Purpose |
+|-------|------|---------|
+| `phase-design` | `references/spec-example.md` | Filled-in spec.md example |
+| `phase-clarify` | `references/clarifications-example.md` | Filled-in clarifications Q&A |
+| `phase-tasks` | `references/tasks-example.md` | Filled-in tasks.md with T### format |
+| `phase-tasks` | `scripts/validate-tasks.mjs` | Validate tasks.md structure and IDs |
+| `phase-implement` | `references/recap-example.md` | Filled-in recap.md example |
+
+---
+
+## Domain Agents
+
+Domain specialist agents (`framework/agents/`) are installed separately as `.claude/agents/morph-domain-{name}.md` — they are subagents, not skills.
+
+See `framework/agents/README.md` for the full list.
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/skills/level-0-meta/brainstorming/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: brainstorming
+description: Morph-spec-aware brainstorming that loads project context, explores multiple design approaches, asks clarifying questions, and produces proposal.md or decisions.md. Use before designing a feature, when facing architectural decisions with multiple valid approaches, or when a feature needs requirements exploration before committing to a direction.
+---
+
+# Brainstorming — MORPH-SPEC Integrated
+
+> Explore context, ask questions, generate multiple approaches, and produce a design document before committing to implementation.
+>
+> **Example:** `references/proposal-example.md` — filled-in proposal.md showing expected quality.
+
+## When to Use
+
+- **Phase 0 (Proposal):** Explore the feature request before writing `proposal.md`
+- **Phase 2 (Design):** Explore architectural alternatives before writing `spec.md`
+- **Any phase:** When facing a decision with multiple valid approaches
+
+## Prerequisites
+
+Before brainstorming, load project context:
+
+```bash
+# Load current state
+npx morph-spec state get {feature-name}
+
+# Read project config
+Read: .morph/config/config.json
+
+# Read existing proposal (if Phase 2)
+Read: .morph/features/{feature}/0-proposal/proposal.md
+```
+
+---
+
+## Workflow
+
+### Step 1: Explore Context
+
+**Gather information before generating ideas:**
+
+1. **Read state.json** — current phase, active agents, existing outputs
+2. **Read config.json** — stack, architecture, project name
+3. **Read existing outputs** — proposal.md, spec.md (if they exist)
+4. **Scan codebase** — use Glob/Grep to understand existing patterns
+5. **Check integrations.json** — available MCPs and plugins
+
+**Use MCP tools when available:**
+- **Context7** → look up library capabilities relevant to the feature
+- **Supabase** → check existing schema for data-related features
+- **GitHub** → check existing issues/PRs for related work
+
+### Step 2: Ask Clarifying Questions
+
+Generate **3-5 focused questions** for the user:
+
+```markdown
+### Q1: Scope
+What is the minimum viable version of this feature?
+
+### Q2: Constraints
+Are there performance/budget/timeline constraints?
+
+### Q3: Integration
+Does this need to integrate with existing features?
+
+### Q4: Users
+Who are the primary users of this feature?
+
+### Q5: Success Criteria
+How will we know this feature is working correctly?
+```
+
+**Wait for user responses before proceeding.**
+
+### Step 3: Generate 2-3 Approaches
+
+For each approach, document:
+
+```markdown
+## Approach A: {Name}
+
+**Description:** {1-2 sentences}
+
+**Pros:**
+- Pro 1
+- Pro 2
+
+**Cons:**
+- Con 1
+- Con 2
+
+**Complexity:** Low / Medium / High
+**Estimated Tasks:** ~N
+**Key Dependencies:** {list}
+```
+
+### Step 4: Recommend and Document
+
+1. **Recommend** the best approach with reasoning
+2. **Write output** to the appropriate location:
+   - Phase 0 → render `docs/proposal` template → `.morph/features/{feature}/0-proposal/proposal.md`
+   - Phase 2 → document in `decisions.md` as an ADR
+
+3. **Update state:**
+```bash
+npx morph-spec state mark-output {feature-name} proposal    # Phase 0
+npx morph-spec state mark-output {feature-name} decisions    # Phase 2
+```
+
+---
+
+## Integration with Superpowers
+
+> Available when the `superpowers` plugin is installed.
+
+This skill replaces `superpowers:brainstorming` within morph-spec workflows. It adds:
+- Automatic context loading from `.morph/` state and config
+- Template rendering for outputs (proposal.md, decisions.md)
+- State tracking via `morph-spec state mark-output`
+- MCP integration for research (Context7, Supabase)
+
+For brainstorming **outside** morph-spec workflows, the original `superpowers:brainstorming` skill remains available.
+
+---
+
+## Anti-patterns
+
+- Never skip brainstorming for features with multiple valid approaches
+- Never commit to an approach without documenting alternatives
+- Never brainstorm without loading project context first
+- Never write code before completing the brainstorming output
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/skills/level-0-meta/brainstorming/references/proposal-example.md

@@ -0,0 +1,138 @@
+# Feature Proposal: Photo Processing Pipeline
+
+> Example of a well-structured proposal.md. This is a filled-in reference — not a template.
+
+## Metadata
+
+| Field | Value |
+|-------|-------|
+| **Proposed** | 2025-01-15 |
+| **Author** | Product Team |
+| **Status** | Approved |
+| **Priority** | High |
+| **Stack** | blazor-azure |
+
+---
+
+## Overview
+
+Users currently cannot upload photos for AI-based transformations because no upload infrastructure exists. This feature adds an end-to-end photo upload, processing, and delivery pipeline using Azure Blob Storage and Hangfire background jobs.
+
+---
+
+## Problem Statement
+
+### What is the problem?
+
+Users cannot submit photos for AI transformation, blocking the core product value proposition. The system has no file upload capability, no background processing queue, and no way to notify users when processing completes.
+
+### Who is affected?
+
+All end users who want to use the photo transformation feature — the primary user journey is completely unavailable.
+
+### What is the impact?
+
+- User productivity loss: 100% of core use case unavailable
+- Revenue impact: Feature is the primary paid tier differentiator
+- User satisfaction: Can't demo product to prospects
+
+---
+
+## Proposed Solution
+
+### Overview
+
+A multi-step pipeline: user uploads a photo via a Blazor form → the file is stored in Azure Blob Storage → a Hangfire background job is queued for AI processing → the user polls for completion → the processed photo is returned via a download link.
+
+### Key Features
+
+1. **Upload endpoint** — Validates file type/size, stores in Azure Blob
+2. **Background processing** — Hangfire job calls AI API, stores result in Blob
+3. **Status polling** — User sees real-time progress (Pending → Processing → Completed)
+
+### User Journey
+
+```
+1. User selects a photo file on the upload page
+2. System validates (max 10MB, .jpg/.png only) and shows preview
+3. User clicks "Upload" → system enqueues job, redirects to /processing/{jobId}
+4. User sees progress bar polling every 5 seconds
+5. On completion: "Download" button appears, user gets processed photo
+```
+
+---
+
+## Success Metrics
+
+| Metric | Current | Target |
+|--------|---------|--------|
+| Upload success rate | N/A | >99% |
+| Processing time (p95) | N/A | <120s |
+| Error recovery rate | N/A | >95% (auto-retry) |
+
+---
+
+## Scope
+
+### In Scope
+
+- Photo upload (Blazor form, Azure Blob Storage)
+- Background processing via Hangfire
+- Status polling page with progress indicator
+- Download link for processed photo
+- Basic error handling and retry logic
+
+### Out of Scope
+
+- Batch uploads (multiple photos at once)
+- Email notifications when processing completes
+- Photo editing before upload (crop, resize)
+
+### Future Considerations
+
+- Webhooks for external integrations
+- Processing history and gallery view
+
+---
+
+## Risks & Concerns
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| AI API unavailable | Medium | High | Retry with exponential backoff, fallback error state |
+| Large file upload timeout | Low | Medium | Chunked upload or presigned URL direct to Blob |
+| Blob storage costs unexpectedly high | Low | Low | Set blob lifecycle policy (auto-delete after 30 days) |
+
+---
+
+## Estimated Effort
+
+| Phase | Estimate |
+|-------|----------|
+| Design & Spec | 2h |
+| Implementation | 6h |
+| Testing | 2h |
+| **Total** | **10h** |
+
+---
+
+## Questions & Clarifications
+
+1. Maximum file size: 10MB or higher for pro users?
+2. Should processed photos be kept indefinitely or expire after 30 days?
+3. Does the AI API support async webhooks or only polling?
+
+---
+
+## Next Steps
+
+Once approved:
+1. Create detailed `spec.md` with technical design
+2. Define contracts in `contracts.cs`
+3. Record decisions in `decisions.md`
+4. Break down into `tasks.md`
+5. Begin implementation
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/skills/level-0-meta/{code-review.md → code-review/SKILL.md}

@@ -1,9 +1,18 @@
+---
+name: code-review
+description: .NET/C# code review checklist covering naming conventions, architecture layer integrity, async patterns, logging, error handling, DI lifetimes, and DTO contracts. Use after implementing .NET code, before creating PRs, or when reviewing C# code for compliance with MORPH-SPEC standards.
+user-invocable: true
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
 # Code Review Checklist
 
 > Comprehensive checklist for .NET code review: naming, architecture, clean code, duplication, and runtime patterns.
-> **Ref:** `framework/standards/coding.md` for naming conventions and style.
-> **Ref:** `framework/standards/architecture.md` for layer rules and SOLID.
-> **Ref:** `framework/standards/blazor-efcore.md` for DbContext patterns and background ops.
+> **Ref:** `framework/standards/core/coding.md` for naming conventions and style.
+> **Ref:** `framework/standards/core/architecture.md` for layer rules and SOLID.
+> **Ref:** `framework/standards/backend/database/ef-core.md` for DbContext patterns and background ops.
+> **Example:** `references/review-example.md` — filled-in review showing expected finding format and severity levels.
+> **Script:** `scripts/scan-csharp.mjs` — automated scan for CRITICAL/HIGH violations before manual review.
 
 ---
 
@@ -223,4 +232,4 @@ public enum OrderStatus
 ---
 
 *Consolidated from: code-review-services.md + code-review-background.md + code-review-contracts.md + architecture/clean-code/duplication analysis.*
-*MORPH-SPEC by Polymorphism Tech*
+*MORPH-SPEC by Polymorphism Tech*

package/framework/skills/level-0-meta/code-review/references/review-example.md

@@ -0,0 +1,164 @@
+# Code Review Report — Photo Processing Pipeline
+
+> Example of a well-structured code review output. Filled-in reference — not a template.
+
+**Scope:** `src/Application/PhotoProcessing/` + `src/Web/Endpoints/PhotoProcessingEndpoints.cs`
+**Date:** 2025-01-22
+**Reviewer:** code-review skill
+
+---
+
+## Findings by Severity
+
+| Severity | Count |
+|----------|-------|
+| CRITICAL | 1 |
+| HIGH | 2 |
+| MEDIUM | 2 |
+| LOW | 1 |
+
+---
+
+### [CRITICAL] Naming: UPPER_SNAKE_CASE constant
+
+**File:** `src/Application/PhotoProcessing/PhotoProcessingService.cs:14`
+
+**Current code:**
+```csharp
+private const int MAX_RETRY_COUNT = 3;
+private const int DEFAULT_TIMEOUT_SECONDS = 30;
+```
+
+**Suggested fix:**
+```csharp
+private const int MaxRetryCount = 3;
+private const int DefaultTimeoutSeconds = 30;
+```
+
+**Why:** `ALL_CAPS` constants violate C# conventions (§ coding.md). Pascal case is the .NET standard.
+
+---
+
+### [HIGH] Async: Missing CancellationToken propagation
+
+**File:** `src/Infrastructure/Storage/AzureBlobStorageService.cs:28`
+
+**Current code:**
+```csharp
+public async Task<string> UploadAsync(Stream content, string blobName)
+{
+    var blobClient = _containerClient.GetBlobClient(blobName);
+    await blobClient.UploadAsync(content);  // no CT
+    return blobClient.Uri.ToString();
+}
+```
+
+**Suggested fix:**
+```csharp
+public async Task<string> UploadAsync(Stream content, string blobName, CancellationToken ct = default)
+{
+    var blobClient = _containerClient.GetBlobClient(blobName);
+    await blobClient.UploadAsync(content, cancellationToken: ct);
+    return blobClient.Uri.ToString();
+}
+```
+
+**Why:** Cancellation cannot propagate into the Blob SDK call, meaning a cancelled HTTP request still holds the upload open.
+
+---
+
+### [HIGH] Logging: String interpolation in ILogger call
+
+**File:** `src/Application/PhotoProcessing/PhotoProcessingJob.cs:52`
+
+**Current code:**
+```csharp
+_logger.LogError($"Job {jobId} failed after {retryCount} retries: {ex.Message}");
+```
+
+**Suggested fix:**
+```csharp
+_logger.LogError("Job {JobId} failed after {RetryCount} retries: {ErrorMessage}",
+    jobId, retryCount, ex.Message);
+```
+
+**Why:** String interpolation allocates eagerly even if the log level is filtered. Message templates are structured and queryable in Application Insights / Seq.
+
+---
+
+### [MEDIUM] Architecture: Controller logic exceeds 50 lines
+
+**File:** `src/Web/Endpoints/PhotoProcessingEndpoints.cs`
+
+**Issue:** The upload endpoint inline lambda is 60+ lines — includes validation, service call, response mapping, and error handling all inline.
+
+**Suggested fix:** Extract a `UploadPhotoRequestHandler` or move validation to a FluentValidation `IValidator<UploadPhotoCommand>`. The endpoint lambda should be < 10 lines.
+
+**Why:** Fat endpoints are hard to test and violate the "thin API layer" rule (§ architecture.md).
+
+---
+
+### [MEDIUM] Error Handling: Generic catch without context
+
+**File:** `src/Application/PhotoProcessing/PhotoProcessingService.cs:89`
+
+**Current code:**
+```csharp
+catch (Exception ex)
+{
+    _logger.LogError(ex, "Upload failed");
+    throw;
+}
+```
+
+**Suggested fix:**
+```csharp
+catch (Exception ex)
+{
+    _logger.LogError(ex, "Upload failed for user {UserId}", userId);
+    throw;
+}
+```
+
+**Why:** Log entries without correlation IDs (UserId, JobId) are unqueryable in production. Always include the relevant entity ID.
+
+---
+
+### [LOW] Dead Code: Unused private method
+
+**File:** `src/Application/PhotoProcessing/PhotoProcessingService.cs:110`
+
+**Current code:**
+```csharp
+private string BuildBlobPath(Guid jobId, string suffix)
+    => $"uploads/{jobId}/{suffix}";
+// Called 0 times — path built inline everywhere
+```
+
+**Suggested fix:** Either use `BuildBlobPath` consistently or delete it.
+
+**Why:** Dead code misleads future readers and increases maintenance surface.
+
+---
+
+## Top Priorities
+
+1. `PhotoProcessingService.cs:14` — CRITICAL naming violation (5 min fix)
+2. `AzureBlobStorageService.cs:28` — HIGH missing CancellationToken (10 min fix)
+3. `PhotoProcessingJob.cs:52` — HIGH structured logging (5 min fix)
+4. `PhotoProcessingEndpoints.cs` — MEDIUM endpoint refactor (30 min)
+
+---
+
+## Passed Checks ✅
+
+- Layer integrity: Domain has no Infrastructure references
+- All async methods have `Async` suffix
+- Private fields use `_camelCase`
+- No hardcoded connection strings or secrets
+- External services accessed through interfaces (`IBlobStorageService`, `IPhotoProcessingJob`)
+- `ProcessingJob` entity uses private setters + domain methods
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*