@polymorphism-tech/morph-spec 4.5.0 → 4.6.0

package/framework/hooks/shared/phase-utils.js

@@ -1,129 +1,129 @@
-// GENERATED by scripts/generate-refs.js — DO NOT EDIT manually
-// Source of truth: src/core/paths/output-schema.js
-// Regenerate with: node scripts/generate-refs.js
-/**
- * Shared phase utilities for Claude Code hooks.
- *
- * Maps phases to directories and output types.
- */
-
-/** Phase order */
-export const PHASE_ORDER = ["proposal","setup","uiux","design","clarify","tasks","implement","sync"];
-
-/** Map phase → allowed output subdirectory */
-export const PHASE_DIRS = {
-  proposal: '0-proposal',
-  setup: '0-proposal',
-  uiux: '2-ui',
-  design: '1-design',
-  clarify: '1-design',
-  tasks: '3-tasks',
-  implement: '4-implement',
-  sync: '4-implement',
-};
-
-/** Map output type (camelCase) → phase that produces it */
-export const OUTPUT_PHASE_MAP = {
-  proposal: 'proposal',
-  schemaAnalysis: 'design',
-  spec: 'design',
-  clarifications: 'clarify',
-  contracts: 'design',
-  tasks: 'tasks',
-  uiDesignSystem: 'uiux',
-  uiMockups: 'uiux',
-  uiComponents: 'uiux',
-  uiFlows: 'uiux',
-  decisions: 'design',
-  recap: 'implement',
-};
-
-/** Map filename → output type (camelCase) */
-export const FILENAME_TO_OUTPUT = {
-  'proposal.md': 'proposal',
-  'schema-analysis.md': 'schemaAnalysis',
-  'spec.md': 'spec',
-  'clarifications.md': 'clarifications',
-  'contracts.cs': 'contracts',
-  'tasks.md': 'tasks',
-  'design-system.md': 'uiDesignSystem',
-  'mockups.md': 'uiMockups',
-  'components.md': 'uiComponents',
-  'flows.md': 'uiFlows',
-  'decisions.md': 'decisions',
-  'recap.md': 'recap',
-};
-
-/** Protected spec files and the approval gate that locks them */
-export const PROTECTED_SPEC_FILES = {
-  'schema-analysis.md': 'design',
-  'spec.md': 'design',
-  'contracts.cs': 'design',
-  'tasks.md': 'tasks',
-  'design-system.md': 'uiux',
-  'mockups.md': 'uiux',
-  'components.md': 'uiux',
-  'flows.md': 'uiux',
-};
-
-/**
- * Extract feature name from a .morph/features/{feature}/... path
- * @param {string} filePath - File path to analyze
- * @returns {string|null} Feature name or null
- */
-export function extractFeatureName(filePath) {
-  const normalized = filePath.replace(/\\/g, '/');
-  const match = normalized.match(/\.morph\/features\/([^/]+)\//);
-  return match ? match[1] : null;
-}
-
-/**
- * Extract phase subdirectory from a .morph/features/{feature}/{phaseDir}/... path
- * @param {string} filePath - File path to analyze
- * @returns {string|null} Phase directory (e.g., '0-proposal', '1-design') or null
- */
-export function extractPhaseDir(filePath) {
-  const normalized = filePath.replace(/\\/g, '/');
-  const match = normalized.match(/\.morph\/features\/[^/]+\/(\d+-[^/]+)\//);
-  return match ? match[1] : null;
-}
-
-/**
- * Check if a file path is inside .morph/features/
- * @param {string} filePath
- * @returns {boolean}
- */
-export function isFeaturePath(filePath) {
-  const normalized = filePath.replace(/\\/g, '/');
-  return normalized.includes('.morph/features/');
-}
-
-/**
- * Check if a file path is inside .morph/framework/ (readonly)
- * @param {string} filePath
- * @returns {boolean}
- */
-export function isFrameworkPath(filePath) {
-  const normalized = filePath.replace(/\\/g, '/');
-  return normalized.includes('.morph/framework/');
-}
-
-/**
- * Check if a file path is state.json
- * @param {string} filePath
- * @returns {boolean}
- */
-export function isStatePath(filePath) {
-  const normalized = filePath.replace(/\\/g, '/');
-  return normalized.endsWith('.morph/state.json');
-}
-
-/**
- * Get the basename of a file path
- * @param {string} filePath
- * @returns {string}
- */
-export function getBasename(filePath) {
-  const normalized = filePath.replace(/\\/g, '/');
-  return normalized.split('/').pop();
-}
+// GENERATED by scripts/generate-refs.js — DO NOT EDIT manually
+// Source of truth: src/core/paths/output-schema.js
+// Regenerate with: node scripts/generate-refs.js
+/**
+ * Shared phase utilities for Claude Code hooks.
+ *
+ * Maps phases to directories and output types.
+ */
+
+/** Phase order */
+export const PHASE_ORDER = ["proposal","setup","uiux","design","clarify","tasks","implement","sync"];
+
+/** Map phase → allowed output subdirectory */
+export const PHASE_DIRS = {
+  proposal: '0-proposal',
+  setup: '0-proposal',
+  uiux: '2-ui',
+  design: '1-design',
+  clarify: '1-design',
+  tasks: '3-tasks',
+  implement: '4-implement',
+  sync: '4-implement',
+};
+
+/** Map output type (camelCase) → phase that produces it */
+export const OUTPUT_PHASE_MAP = {
+  proposal: 'proposal',
+  schemaAnalysis: 'design',
+  spec: 'design',
+  clarifications: 'clarify',
+  contracts: 'design',
+  tasks: 'tasks',
+  uiDesignSystem: 'uiux',
+  uiMockups: 'uiux',
+  uiComponents: 'uiux',
+  uiFlows: 'uiux',
+  decisions: 'design',
+  recap: 'implement',
+};
+
+/** Map filename → output type (camelCase) */
+export const FILENAME_TO_OUTPUT = {
+  'proposal.md': 'proposal',
+  'schema-analysis.md': 'schemaAnalysis',
+  'spec.md': 'spec',
+  'clarifications.md': 'clarifications',
+  'contracts.cs': 'contracts',
+  'tasks.md': 'tasks',
+  'design-system.md': 'uiDesignSystem',
+  'mockups.md': 'uiMockups',
+  'components.md': 'uiComponents',
+  'flows.md': 'uiFlows',
+  'decisions.md': 'decisions',
+  'recap.md': 'recap',
+};
+
+/** Protected spec files and the approval gate that locks them */
+export const PROTECTED_SPEC_FILES = {
+  'schema-analysis.md': 'design',
+  'spec.md': 'design',
+  'contracts.cs': 'design',
+  'tasks.md': 'tasks',
+  'design-system.md': 'uiux',
+  'mockups.md': 'uiux',
+  'components.md': 'uiux',
+  'flows.md': 'uiux',
+};
+
+/**
+ * Extract feature name from a .morph/features/{feature}/... path
+ * @param {string} filePath - File path to analyze
+ * @returns {string|null} Feature name or null
+ */
+export function extractFeatureName(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  const match = normalized.match(/\.morph\/features\/([^/]+)\//);
+  return match ? match[1] : null;
+}
+
+/**
+ * Extract phase subdirectory from a .morph/features/{feature}/{phaseDir}/... path
+ * @param {string} filePath - File path to analyze
+ * @returns {string|null} Phase directory (e.g., '0-proposal', '1-design') or null
+ */
+export function extractPhaseDir(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  const match = normalized.match(/\.morph\/features\/[^/]+\/(\d+-[^/]+)\//);
+  return match ? match[1] : null;
+}
+
+/**
+ * Check if a file path is inside .morph/features/
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function isFeaturePath(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  return normalized.includes('.morph/features/');
+}
+
+/**
+ * Check if a file path is inside .morph/framework/ (readonly)
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function isFrameworkPath(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  return normalized.includes('.morph/framework/');
+}
+
+/**
+ * Check if a file path is state.json
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function isStatePath(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  return normalized.endsWith('.morph/state.json');
+}
+
+/**
+ * Get the basename of a file path
+ * @param {string} filePath
+ * @returns {string}
+ */
+export function getBasename(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  return normalized.split('/').pop();
+}

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.md → brainstorming/SKILL.md}

@@ -1,11 +1,13 @@
 ---
 name: brainstorming
-description: Morph-spec-aware brainstorming for exploring feature approaches, generating proposals, and designing architecture. Use before any creative or implementation work.
+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
 

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,7 +1,6 @@
 ---
 name: code-review
-description: >
-  Structured code review checklist for MORPH-SPEC projects covering architecture, standards compliance, contracts, and quality gates. Use after implementation to validate work.
+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
 ---
@@ -12,6 +11,8 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 > **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.
 
 ---
 

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*