@polymorphism-tech/morph-spec 4.5.0 → 4.6.0

package/framework/skills/level-0-meta/code-review/scripts/scan-csharp.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+/**
+ * scan-csharp.mjs
+ *
+ * Scans .cs files for MORPH-SPEC coding standard violations.
+ * Executed locally by Claude via Bash — output returned to Claude.
+ *
+ * Usage:
+ *   node scan-csharp.mjs [path]           # scan directory or file
+ *   node scan-csharp.mjs src/             # scan src/ recursively
+ *   node scan-csharp.mjs --summary        # counts only, no details
+ *
+ * Checks (ref: framework/standards/core/coding.md):
+ *   - UPPER_SNAKE_CASE constants       → should be PascalCase
+ *   - Hungarian notation               → strName, iCount, btnSubmit
+ *   - Missing CancellationToken        → async methods without CT param
+ *   - String interpolation in logging  → $"" in ILogger calls
+ *   - Empty catch blocks               → catch { } or catch (E) { }
+ */
+
+import { readdirSync, readFileSync, statSync, existsSync } from 'fs';
+import { join, extname, relative } from 'path';
+
+const targetPath = process.argv[2] ?? '.';
+const summaryOnly = process.argv.includes('--summary');
+
+const CHECKS = [
+  {
+    id: 'UPPER_SNAKE_CASE',
+    severity: 'CRITICAL',
+    pattern: /\bconst\s+\w+\s+([A-Z][A-Z_]{2,})\s*=/g,
+    message: (m) => `Constant '${m[1]}' uses UPPER_SNAKE_CASE (anti-pattern in C#) → use PascalCase`,
+  },
+  {
+    id: 'HUNGARIAN_NOTATION',
+    severity: 'CRITICAL',
+    pattern: /\b(str|int|bool|btn|lbl|txt|dbl|flt|obj|arr|lst)([A-Z]\w*)\b/g,
+    message: (m) => `'${m[0]}' looks like Hungarian notation → rename to '${m[2].charAt(0).toLowerCase() + m[2].slice(1)}'`,
+  },
+  {
+    id: 'MISSING_CANCELLATION_TOKEN',
+    severity: 'HIGH',
+    pattern: /public\s+async\s+Task(?:<[^>]+>)?\s+(\w+Async)\s*\(([^)]*)\)/g,
+    message: (m) => {
+      const params = m[2];
+      if (params.includes('CancellationToken') || params.includes('ct ') || params.includes('ct,') || params.includes('ct)')) return null;
+      return `Async method '${m[1]}' missing CancellationToken parameter`;
+    },
+  },
+  {
+    id: 'LOG_STRING_INTERPOLATION',
+    severity: 'HIGH',
+    pattern: /\.(LogInformation|LogWarning|LogError|LogDebug|LogCritical)\s*\(\s*\$"/g,
+    message: () => 'String interpolation ($"") in log call → use message template with structured parameters',
+  },
+  {
+    id: 'EMPTY_CATCH',
+    severity: 'CRITICAL',
+    pattern: /catch\s*(\([^)]*\))?\s*\{\s*\}/g,
+    message: () => 'Empty catch block — exceptions are silently swallowed',
+  },
+];
+
+function collectCsFiles(dir) {
+  if (!existsSync(dir)) return [];
+  const stat = statSync(dir);
+  if (stat.isFile()) return dir.endsWith('.cs') ? [dir] : [];
+  const results = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory() && entry.name !== 'bin' && entry.name !== 'obj' && entry.name !== '.git') {
+      results.push(...collectCsFiles(join(dir, entry.name)));
+    } else if (entry.isFile() && extname(entry.name) === '.cs') {
+      results.push(join(dir, entry.name));
+    }
+  }
+  return results;
+}
+
+const files = collectCsFiles(targetPath);
+const findings = [];
+
+for (const file of files) {
+  const content = readFileSync(file, 'utf-8');
+  const lines = content.split('\n');
+
+  for (const check of CHECKS) {
+    const regex = new RegExp(check.pattern.source, check.pattern.flags);
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+      const msg = check.message(match);
+      if (!msg) continue;
+      const lineNum = content.slice(0, match.index).split('\n').length;
+      findings.push({
+        severity: check.severity,
+        id: check.id,
+        file: relative(process.cwd(), file).replace(/\\/g, '/'),
+        line: lineNum,
+        message: msg,
+        snippet: lines[lineNum - 1]?.trim().slice(0, 100),
+      });
+    }
+  }
+}
+
+const bySeverity = { CRITICAL: 0, HIGH: 0, MEDIUM: 0, LOW: 0 };
+for (const f of findings) bySeverity[f.severity] = (bySeverity[f.severity] ?? 0) + 1;
+
+const summary = {
+  scanned: files.length,
+  findings: findings.length,
+  bySeverity,
+  clean: findings.length === 0,
+};
+
+if (summaryOnly) {
+  console.log(JSON.stringify(summary, null, 2));
+} else {
+  console.log(JSON.stringify({ summary, findings }, null, 2));
+}
+
+process.exit(findings.some(f => f.severity === 'CRITICAL') ? 1 : 0);

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

@@ -1,14 +1,11 @@
 ---
 name: morph-checklist
-description: >
-  Pre-implementation checklist verifying that all MORPH-SPEC phases are complete and outputs exist before starting code. Use before any implementation work begins.
+description: Pre-deploy, security, SEO, performance, accessibility, and LGPD compliance checklists for MORPH-SPEC projects. Use before deploying to production, during security audits, when optimizing for SEO or performance, or when validating Brazilian LGPD data protection compliance.
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 
-# Skill: /morph-checklist
-
-> **Layer:** 2 | **Load:** on-keyword | **Keywords:** checklist, deploy, security, seo, performance, accessibility, lgpd, legal
+# MORPH Checklists
 
 Types: `deploy`, `security`, `seo`, `performance`, `accessibility`, `legal-brazil`, `simulation` (see [simulation-checklist.md](simulation-checklist.md))
 

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
 ---

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 |