@polymorphism-tech/morph-spec 4.5.0 → 4.7.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/rules/frontend-standards.md

@@ -1,8 +1,6 @@
 ---
 paths:
   - "**/*.razor"
-  - "**/*.tsx"
-  - "**/*.ts"
   - "**/*.css"
   - "**/*.scss"
 ---
@@ -10,5 +8,4 @@ paths:
 # Frontend Standards
 
 @.morph/framework/standards/frontend/blazor/design-checklist.md
-@.morph/framework/standards/frontend/nextjs/nextjs-patterns.md
 @.morph/framework/standards/frontend/design-system/naming.md

package/framework/rules/nextjs-standards.md

@@ -0,0 +1,17 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/*.ts"
+---
+
+# Next.js Standards
+
+@.morph/framework/standards/frontend/nextjs/naming-conventions.md
+@.morph/framework/standards/frontend/nextjs/project-structure.md
+@.morph/framework/standards/frontend/nextjs/app-router.md
+@.morph/framework/standards/frontend/nextjs/components.md
+@.morph/framework/standards/frontend/nextjs/data-fetching.md
+@.morph/framework/standards/frontend/nextjs/forms.md
+@.morph/framework/standards/frontend/nextjs/state-management.md
+@.morph/framework/standards/frontend/nextjs/testing.md
+@.morph/framework/standards/frontend/nextjs/nextjs-patterns.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.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.
 
 ---