@polymorphism-tech/morph-spec 4.5.0 → 4.7.0

package/framework/skills/{level-1-workflows/morph-replicate.md → level-0-meta/morph-replicate/SKILL.md}

@@ -1,7 +1,6 @@
 ---
 name: morph-replicate
-description: >
-  Replicates a completed MORPH-SPEC feature into a new feature, copying and adapting phase outputs. Called when a user wants to clone an existing feature as a starting point.
+description: Simplified workflow for converting HTML prototypes into functional Blazor components, extracting design patterns and mapping HTML elements to Fluent UI/MudBlazor equivalents. Use when an approved HTML prototype exists and needs conversion to Blazor without a full MORPH-SPEC spec pipeline.
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 ---
@@ -209,12 +208,12 @@ Mapeamento HTML → Blazor:
 
 ---
 
-## Referencias
+## Referências
 
-- [HTML to Blazor Guide](../../../../framework/standards/html-to-blazor.md)
-- [CSS Naming Convention](../../../../framework/standards/css-naming.md)
-- [CSS Animations](../../../../framework/standards/css-animations.md)
-- [Fluent UI Blazor](../../../../framework/standards/fluent-ui-blazor.md)
+- **Ref:** `framework/standards/frontend/blazor/html-conversion.md`
+- **Ref:** `framework/standards/frontend/design-system/naming.md`
+- **Ref:** `framework/standards/frontend/design-system/animations.md`
+- **Ref:** `framework/standards/frontend/blazor/fluent-ui.md`
 
 ---
 

package/framework/skills/level-0-meta/{simulation-checklist.md → simulation-checklist/SKILL.md}

@@ -1,16 +1,13 @@
 ---
 name: simulation-checklist
-description: >
-  Checklist for simulating a full MORPH-SPEC workflow run to validate phase outputs and state consistency. Use to verify the framework is working correctly.
+description: Checklist for implementing mock/simulation clients for external .NET services (AI APIs, payments, email). Use when setting up simulation mode without real API access, when creating fake service implementations for development/testing, or when debugging external service integrations.
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 
-# Skill: /morph-checklist simulation
+# Simulation Checklist
 
-> **Layer:** 2 | **Load:** on-keyword | **Keywords:** simulation, mock, fake, external service, sandbox
-
-Checklist for simulating external services (AI, payment, email APIs).
+Checklist for simulating external services (AI, payment, email APIs) in .NET projects.
 
 ## Pre-Implementation
 

package/framework/skills/level-0-meta/{tool-usage-guide.md → tool-usage-guide/SKILL.md}

@@ -1,7 +1,6 @@
 ---
 name: tool-usage-guide
-description: >
-  Decision guide for selecting the right Claude Code tool (Read, Grep, Glob, Bash, Task) for each situation in MORPH-SPEC workflows. Reference when unsure which tool to use.
+description: Decision flowchart and per-phase reference for selecting the right Claude Code tool (Read, Grep, Glob, Bash, Task) or MCP tool in MORPH-SPEC workflows. Use when unsure which tool to use for a given action, when choosing between native tools and MCPs, or when deciding whether to use a subagent vs direct tools.
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 ---
@@ -128,7 +127,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 
 ### Phase 2 — Design (Technical Spec)
 
-**Goal:** Analyze schema, create spec.md, contracts.cs, decisions.md
+**Goal:** Analyze schema, create spec.md, contracts-level{N}.cs, decisions.md
 
 | Action | Tool | Why |
 |--------|------|-----|
@@ -142,7 +141,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 | Look up library for ADR | **Context7 MCP** `query_docs()` | Compare library capabilities |
 | Check existing code patterns | **GitHub MCP** `search_code()` | Find patterns in large repos |
 | **Fallback:** Search codebase | **Grep** patterns across project | When no GitHub MCP |
-| Render contracts template | **Bash** `npx morph-spec template render code/dotnet/contracts/contracts.cs ...` | CLI command |
+| Render contracts template (detected level) | **Bash** `npx morph-spec template render code/dotnet/contracts/contracts-level{N}.cs ...` where N = level detected | CLI command |
 | Render spec template | **Bash** `npx morph-spec template render docs/spec ...` | CLI command |
 | Render decisions template | **Bash** `npx morph-spec template render docs/decisions ...` | CLI command |
 | Create schema-analysis.md | **Write** to output directory | Document findings |
@@ -154,7 +153,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 - ❌ Guessing field names without checking schema (use MCP or Grep first!)
 - ❌ Task agent to read a single spec file (just use Read)
 - ❌ WebSearch for database schema (use Supabase MCP or code analysis)
-- ❌ Manually writing contracts.cs from scratch (use template render)
+- ❌ Manually writing contracts-level{N}.cs from scratch (use template render)
 
 ---
 

package/framework/skills/level-0-meta/{verification-before-completion.md → verification-before-completion/SKILL.md}

@@ -1,11 +1,13 @@
 ---
 name: verification-before-completion
-description: Morph-spec-aware verification checklist before claiming any work is complete. Runs validation, checks outputs, and confirms with evidence.
+description: Phase-specific verification checklists and morph-spec validation commands for confirming MORPH-SPEC outputs are complete and correct. Use before marking any task done, before advancing to the next phase, before committing, or before creating PRs.
 ---
 
 # Verification Before Completion — MORPH-SPEC Integrated
 
 > Never claim work is complete without running verification. Evidence before assertions.
+>
+> **Script:** Run `node scripts/check-phase-outputs.mjs <feature> [phase]` to check required output files exist.
 
 ## When to Use
 

package/framework/skills/level-0-meta/verification-before-completion/scripts/check-phase-outputs.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * check-phase-outputs.mjs
+ *
+ * Verifies that required MORPH-SPEC output files exist for a feature/phase.
+ * Executed locally by Claude via Bash — output is returned to Claude.
+ *
+ * Usage:
+ *   node check-phase-outputs.mjs <feature> [phase]
+ *
+ * Examples:
+ *   node check-phase-outputs.mjs photo-processing design
+ *   node check-phase-outputs.mjs photo-processing        # checks all phases
+ *
+ * Output: JSON array of { phase, file, exists, required }
+ */
+
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+const PHASE_OUTPUTS = {
+  proposal: [
+    { file: '0-proposal/proposal.md', required: true },
+  ],
+  design: [
+    { file: '1-design/spec.md', required: true },
+    { file: '1-design/contracts.cs', required: true },
+    { file: '1-design/decisions.md', required: true },
+    { file: '1-design/schema-analysis.md', required: false },
+  ],
+  uiux: [
+    { file: '2-ui/design-system.md', required: true },
+    { file: '2-ui/mockups.md', required: true },
+    { file: '2-ui/components.md', required: true },
+    { file: '2-ui/flows.md', required: false },
+  ],
+  tasks: [
+    { file: '3-tasks/tasks.md', required: true },
+  ],
+  implement: [
+    { file: '4-implement/recap.md', required: true },
+  ],
+};
+
+const feature = process.argv[2];
+const targetPhase = process.argv[3];
+
+if (!feature) {
+  console.error(JSON.stringify({ error: 'Usage: check-phase-outputs.mjs <feature> [phase]' }));
+  process.exit(1);
+}
+
+// Walk up to find .morph/ directory
+let cwd = process.cwd();
+let morphDir = null;
+for (let i = 0; i < 5; i++) {
+  const candidate = join(cwd, '.morph');
+  if (existsSync(candidate)) {
+    morphDir = candidate;
+    break;
+  }
+  const parent = join(cwd, '..');
+  if (parent === cwd) break;
+  cwd = parent;
+}
+
+if (!morphDir) {
+  console.error(JSON.stringify({ error: '.morph/ directory not found. Run from inside a MORPH-SPEC project.' }));
+  process.exit(1);
+}
+
+const featureDir = join(morphDir, 'features', feature);
+if (!existsSync(featureDir)) {
+  console.error(JSON.stringify({ error: `Feature directory not found: .morph/features/${feature}` }));
+  process.exit(1);
+}
+
+const phases = targetPhase
+  ? { [targetPhase]: PHASE_OUTPUTS[targetPhase] }
+  : PHASE_OUTPUTS;
+
+if (targetPhase && !PHASE_OUTPUTS[targetPhase]) {
+  console.error(JSON.stringify({ error: `Unknown phase: ${targetPhase}. Valid: ${Object.keys(PHASE_OUTPUTS).join(', ')}` }));
+  process.exit(1);
+}
+
+const results = [];
+let missingRequired = 0;
+
+for (const [phase, outputs] of Object.entries(phases)) {
+  for (const { file, required } of outputs) {
+    const fullPath = join(featureDir, file);
+    const exists = existsSync(fullPath);
+    if (required && !exists) missingRequired++;
+    results.push({ phase, file, exists, required });
+  }
+}
+
+const summary = {
+  feature,
+  featureDir: featureDir.replace(/\\/g, '/'),
+  checks: results.length,
+  passed: results.filter(r => r.exists).length,
+  missingRequired,
+  ready: missingRequired === 0,
+  results,
+};
+
+console.log(JSON.stringify(summary, null, 2));
+process.exit(missingRequired > 0 ? 1 : 0);

package/framework/skills/level-1-workflows/{phase-clarify.md → phase-clarify/SKILL.md}

@@ -1,7 +1,6 @@
 ---
 name: phase-clarify
-description: >
-  MORPH-SPEC Phase 3 (Clarify). Resolves ambiguities from the design phase, producing clarifications.md and updating the spec. Called after design approval.
+description: MORPH-SPEC Phase 3 (Clarify). Reviews spec.md for ambiguities, generates 3-7 targeted clarification questions, waits for user answers, then updates spec with edge cases and clarification sections. Use after design approval to eliminate spec ambiguities before task breakdown begins.
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
@@ -21,8 +20,9 @@ Identifique ambiguidades na especificação e faça perguntas de clarificação
 
 ## Ferramentas Recomendadas
 
-> **Ref:** `framework/skills/level-0-meta/tool-usage-guide.md` para guia completo.
+> **Ref:** `framework/skills/level-0-meta/tool-usage-guide/SKILL.md` para guia completo.
 > **Ref:** `framework/standards/integration/mcp/mcp-tools.md` para referência MCP.
+> **Example:** `references/clarifications-example.md` — filled-in clarifications.md showing expected Q&A format.
 
 | Ação | Ferramenta | Alternativa |
 |------|------------|-------------|

package/framework/skills/level-1-workflows/phase-clarify/references/clarifications-example.md

@@ -0,0 +1,117 @@
+# Clarifications - Photo Processing Pipeline
+
+> Example of a well-structured clarifications.md. Filled-in reference — not a template.
+> Each Q&A is concise: question raised during design review → answer → spec update.
+
+**Feature**: photo-processing
+**Phase**: CLARIFY (Phase 3)
+**Status**: Resolved — all items incorporated into spec.md
+
+---
+
+## Questions & Answers
+
+### Q1: File size limit — 10MB for all users or tiered?
+
+**Question:** The spec says max 10MB but the proposal mentioned "higher for pro users." Should we implement tiered limits now?
+
+**Answer:** Free tier: 10MB. Pro tier: 50MB. Enforce via `[Authorize]` + claims check in the upload endpoint. YAGNI — don't build a generic tier system, just check the plan claim directly.
+
+**Spec Updates:**
+- Updated `spec.md` FR1 to specify tiered limits
+- Added `CanUploadLargeFile` policy to Security section
+- Updated `UploadPhotoCommand` to accept `userPlan` claim
+
+**Priority:** High — affects contracts
+**Resolved:** ✅ Yes
+
+---
+
+### Q2: Processed photo retention — indefinite or expiring?
+
+**Question:** Should processed photos in Blob Storage be kept forever, or do they expire?
+
+**Answer:** Auto-delete after 30 days via Blob lifecycle policy (no code needed, configured in Azure). Free tier: 7 days. Pro tier: 30 days. This is infrastructure-only — `ProcessingJob.ProcessedPhotoUrl` stays in DB but becomes a dead link after expiry.
+
+**Spec Updates:**
+- Added ADR-003 (Blob lifecycle policy over code-based cleanup)
+- Added note to `AzureBlobStorageService` about lifecycle dependency
+
+**Priority:** Low — no code change
+**Resolved:** ✅ Yes
+
+---
+
+### Q3: AI API — async webhook or polling?
+
+**Question:** spec.md assumed Hangfire polls job completion, but the AI vendor docs mention a webhook callback option.
+
+**Answer:** Use fire-and-forget HTTP call + Hangfire continuation (not webhook). The AI API's webhook requires a public URL we don't have in dev. Fire-and-forget is simpler and testable. If the vendor SLA changes, we can swap to webhook via `IPhotoProcessingJob` interface — no consumer changes needed.
+
+**Spec Updates:**
+- Clarified Processing Flow in spec.md to show fire-and-forget + await pattern
+- Added to Risks: "AI API webhook migration path if needed"
+
+**Priority:** High — affects job implementation
+**Resolved:** ✅ Yes
+
+---
+
+## Edge Cases
+
+### EC1: Upload during Hangfire downtime
+
+**Scenario:** User uploads successfully but Hangfire server is stopped — job never executes.
+
+**Expected Behavior:** Job stays in `Pending` indefinitely. On next Hangfire server start, job auto-resumes (Hangfire persistent storage).
+
+**Solution:** No code change. Add monitoring alert if job stays Pending > 10 minutes.
+
+**Acceptance Criteria:**
+- [ ] `ProcessingJob` with status `Pending` survives Hangfire restart
+- [ ] Hangfire picks up orphaned jobs on startup (built-in behavior, covered by docs)
+
+---
+
+### EC2: Concurrent uploads of same file
+
+**Scenario:** User double-clicks Upload button, sending two identical requests simultaneously.
+
+**Expected Behavior:** Two separate `ProcessingJob` records created. Both process independently. No deduplication (not required at MVP scale).
+
+**Solution:** No code change. Each request gets a fresh GUID. If deduplication becomes needed, add idempotency key header in v2.
+
+---
+
+## Business Rules Clarified
+
+### BR1: Only the uploading user can download their processed photo
+
+**Rule:** `GET /api/download/{jobId}` must check `job.UserId == currentUserId`. Return 403 if mismatch.
+
+**Rationale:** Users might guess sequential GUIDs (they can't since we use random GUIDs, but defense in depth).
+
+**Implementation:** Add `[Authorize]` + ownership check to download endpoint. Already in Security section of spec.md.
+
+---
+
+## Summary
+
+| | Count |
+|---|---|
+| Questions Answered | 3 / 3 |
+| Edge Cases Documented | 2 |
+| Business Rules Clarified | 1 |
+| Spec Updates Made | 6 |
+
+## Next Steps
+
+1. [x] All questions resolved
+2. [x] `spec.md` updated with all clarifications
+3. [x] `contracts.cs` updated (`UploadPhotoCommand` + plan claim)
+4. [x] Stakeholder approval received
+5. [ ] Advance to Phase 4 (Tasks)
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/skills/level-1-workflows/{phase-codebase-analysis.md → phase-codebase-analysis/SKILL.md}

@@ -1,7 +1,6 @@
 ---
 name: phase-codebase-analysis
-description: >
-  MORPH-SPEC sub-phase of Design. Analyzes existing codebase patterns, architecture, and conventions before writing the spec. Called automatically at the start of Design phase.
+description: MORPH-SPEC Design sub-phase that analyzes existing codebase and database schema, producing schema-analysis.md with real column names, types, relationships, and field mismatches. Use at the start of Design phase before generating contracts.cs to prevent incorrect field names or types.
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 ---
@@ -21,7 +20,7 @@ Automatiza a análise de código existente para gerar `schema-analysis.md` com d
 
 ## Ferramentas Recomendadas
 
-> **Ref:** `framework/skills/level-0-meta/tool-usage-guide.md` para guia completo.
+> **Ref:** `framework/skills/level-0-meta/tool-usage-guide/SKILL.md` para guia completo.
 > **Ref:** `framework/standards/integration/mcp/mcp-tools.md` para referência MCP.
 
 | Ação | Ferramenta | Alternativa |