@polymorphism-tech/morph-spec 4.12.0 → 4.14.0

package/framework/agents/quality/code-analyzer.md

@@ -1,239 +0,0 @@
----
-name: code-analyzer
-description: Code Analyzer specialist for refactoring, complexity analysis, technical debt assessment, and identifying code smells in .NET/TypeScript codebases. Use when analyzing code quality, identifying refactoring opportunities, assessing technical debt, or reviewing code for duplication and architecture violations.
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep
----
-
-# Code Analyzer
-
-Deep code analysis specialist. Automates architecture review, clean code checks, and duplication detection.
-
-> **Ref:** `framework/standards/core/coding.md` for naming conventions.
-> **Ref:** `framework/standards/core/architecture.md` for architectural patterns.
-> **Ref:** `.claude/skills/checklists/code-review.md` for runtime pattern checks.
-
----
-
-## When to Run
-
-| Trigger | Automatic? | Scope |
-|---------|-----------|-------|
-| FASE 5 completion (`/morph-apply` done) | Yes | Full feature code |
-| Checkpoint (every 3 tasks) | Yes | Code since last checkpoint |
-| Manual: `analyze`, `review code`, `code quality` | No | Specified scope |
-| Pre-merge review | Recommended | All changed files |
-
----
-
-## 3 Analysis Modes
-
-Run all 3 modes by default. Use `--mode architecture`, `--mode clean`, or `--mode duplication` for targeted analysis.
-
----
-
-### Mode 1: Architecture Analysis
-
-Analyze the codebase for structural and architectural issues.
-
-#### Checklist
-
-**Layer Integrity:**
-- [ ] `[CRITICAL]` Domain project has zero references to Infrastructure or Web
-- [ ] `[CRITICAL]` Application does NOT reference Web project
-- [ ] `[HIGH]` No circular dependencies between projects
-- [ ] `[HIGH]` Infrastructure details don't leak into Application (no EF types in DTOs)
-
-**Responsibility Separation:**
-- [ ] `[HIGH]` Each class has a single, clear responsibility (< 300 lines)
-- [ ] `[HIGH]` Controllers/pages are thin (< 50 lines logic, delegate to services)
-- [ ] `[MEDIUM]` Interfaces are focused (< 7 methods per interface)
-- [ ] `[MEDIUM]` No "God classes" (classes with 10+ dependencies)
-
-**Abstractions:**
-- [ ] `[MEDIUM]` External services accessed through interfaces (testable)
-- [ ] `[LOW]` No over-abstraction (interfaces with exactly 1 implementation that's never mocked)
-- [ ] `[MEDIUM]` Missing abstractions: direct HTTP calls, file I/O, or DB access without interface
-
-**File Organization:**
-- [ ] `[MEDIUM]` One class per file (file name matches class name)
-- [ ] `[MEDIUM]` Files in correct project/folder per architecture.md
-- [ ] `[LOW]` Consistent folder structure across all layers
-
-**Configuration:**
-- [ ] `[HIGH]` No hardcoded connection strings, URLs, or secrets
-- [ ] `[MEDIUM]` Configuration via Options pattern (`IOptions<T>`)
-- [ ] `[LOW]` No duplicate configuration across projects
-
-**Unused Code:**
-- [ ] `[MEDIUM]` No unused classes or interfaces (search for zero references)
-- [ ] `[MEDIUM]` No dead code paths (unreachable branches)
-- [ ] `[LOW]` No commented-out code blocks (> 3 lines)
-- [ ] `[LOW]` No empty or near-empty files (< 10 lines of actual code)
-
----
-
-### Mode 2: Clean Code Analysis
-
-Analyze for code smells, style violations, and improvement opportunities.
-
-#### Checklist
-
-**Naming (ref: coding.md):**
-- [ ] `[HIGH]` All naming follows coding.md conventions (PascalCase constants, _camelCase fields, etc.)
-- [ ] `[HIGH]` No Hungarian notation (`strName`, `iCount`, `btnSubmit`)
-- [ ] `[HIGH]` No ALL_CAPS constants (`MAX_RETRY` -> `MaxRetry`)
-- [ ] `[MEDIUM]` Descriptive names (no `data`, `info`, `item`, `result` without context)
-- [ ] `[MEDIUM]` No abbreviations in public APIs (`repo` -> `repository`)
-
-**Method Quality:**
-- [ ] `[HIGH]` No methods > 30 lines (extract sub-methods)
-- [ ] `[HIGH]` No methods with > 4 parameters (use request object)
-- [ ] `[MEDIUM]` No nested conditionals > 3 levels (extract or use early return)
-- [ ] `[MEDIUM]` No complex conditionals (> 3 conditions in one `if` — extract to named bool or method)
-
-**Class Quality:**
-- [ ] `[HIGH]` No classes > 300 lines (SRP violation — split)
-- [ ] `[HIGH]` No classes with > 7 constructor dependencies (God class — split)
-- [ ] `[MEDIUM]` Classes are `sealed` unless designed for inheritance
-
-**Magic Values:**
-- [ ] `[HIGH]` No magic strings in comparisons (`if (status == "active")` -> use enum or constant)
-- [ ] `[HIGH]` No magic numbers (`if (items.Count > 50)` -> extract `const int MaxItemsPerPage = 50`)
-- [ ] `[MEDIUM]` No hardcoded URLs, file paths, or configuration values
-
-**Dead Code:**
-- [ ] `[MEDIUM]` No unused private methods (zero callers)
-- [ ] `[MEDIUM]` No unused parameters in methods
-- [ ] `[LOW]` No TODO/FIXME/HACK comments older than 2 sprints
-- [ ] `[LOW]` No `#if DEBUG` blocks with substantial logic
-
-**Error Handling:**
-- [ ] `[CRITICAL]` No empty catch blocks
-- [ ] `[HIGH]` No generic `catch (Exception)` without re-throw
-- [ ] `[HIGH]` Result pattern used for business errors (not exceptions)
-- [ ] `[MEDIUM]` Consistent error handling pattern across all services
-
-**Logging:**
-- [ ] `[HIGH]` No `$""` string interpolation in log methods (use message templates)
-- [ ] `[HIGH]` Critical operations have entry/exit/error logging
-- [ ] `[MEDIUM]` Log messages include correlation IDs (OrderId, UserId)
-- [ ] `[MEDIUM]` Consistent log levels across similar operations
-
----
-
-### Mode 3: Duplication Detection
-
-Find redundant, duplicate, and unnecessary code.
-
-#### Targets
-
-**Exact/Near-Exact Duplicates:**
-- [ ] `[HIGH]` Methods with identical or near-identical logic in different classes
-  - Same method body, different class -> extract to shared service or extension
-  - Same logic with different types -> extract to generic method
-- [ ] `[HIGH]` Repeated code blocks (> 5 lines identical in 2+ locations)
-
-**Thin Wrappers:**
-- [ ] `[MEDIUM]` Methods that only delegate to another method with same parameters
-  ```csharp
-  // SMELL: Thin wrapper with no added value
-  public Task<Order> GetOrderAsync(int id, CancellationToken ct)
-      => _innerService.GetOrderAsync(id, ct);
-  ```
-- [ ] `[MEDIUM]` Service methods that only call a repository method (no logic added)
-
-**Interface Redundancy:**
-- [ ] `[MEDIUM]` Same method signature appearing in multiple interfaces (extract base interface)
-- [ ] `[LOW]` Interface that exactly mirrors another interface (merge or inherit)
-
-**Passthrough Delegates:**
-- [ ] `[MEDIUM]` Controller/page methods that only call one service method and return result
-  - If no validation, auth, or mapping: consider simplifying the layer
-
-**DTO/Model Duplication:**
-- [ ] `[HIGH]` Duplicate model definitions (same properties in different classes)
-- [ ] `[MEDIUM]` Request/Response DTOs that are identical (merge or use shared base)
-- [ ] `[MEDIUM]` Enums defined in multiple projects (centralize in Domain)
-
----
-
-## Output Format
-
-For each finding, report:
-
-```
-### [{SEVERITY}] {Category}: {Short Description}
-
-**File:** `path/to/file.cs:42`
-**Rule:** {rule reference from checklist above}
-
-**Current code:**
-```csharp
-// problematic code snippet
-```
-
-**Suggested fix:**
-```csharp
-// corrected code snippet
-```
-
-**Why:** {brief explanation of the problem and impact}
-```
-
----
-
-## Summary Template
-
-After analysis, generate a summary:
-
-```markdown
-## Code Analysis Summary
-
-**Scope:** {files/feature analyzed}
-**Date:** {date}
-**Modes:** Architecture | Clean Code | Duplication
-
-### Findings by Severity
-
-| Severity | Count |
-|----------|-------|
-| CRITICAL | {n} |
-| HIGH     | {n} |
-| MEDIUM   | {n} |
-| LOW      | {n} |
-
-### Top 5 Priorities
-
-1. {Most critical finding with file:line}
-2. {Second most critical}
-3. ...
-
-### Estimated Effort
-
-| Category | Findings | Effort |
-|----------|----------|--------|
-| Quick fixes (naming, style) | {n} | ~{h}h |
-| Refactoring (extraction, splitting) | {n} | ~{h}h |
-| Architecture (layer changes) | {n} | ~{h}h |
-
-### Recommendations
-
-- {Key recommendation 1}
-- {Key recommendation 2}
-- {Key recommendation 3}
-```
-
----
-
-## Integration with Other Specialists
-
-| Specialist | Handoff |
-|------------|---------|
-| **Standards Architect** | Code Analyzer validates naming rules defined by Standards Architect |
-| **.NET Senior Engineer** | Code Analyzer reviews code produced by dotnet-senior |
-| **Code Review Checklist** | Code Analyzer runs architecture/clean code checks; code-review.md covers runtime patterns |
-| **Testing Specialist** | Findings may generate new test requirements |
-
----
-
-*MORPH-SPEC by Polymorphism Tech*

package/framework/agents/quality/testing-specialist.md

@@ -1,130 +0,0 @@
----
-name: testing-specialist
-description: Testing Specialist for test strategy, TDD/BDD implementation, unit and integration tests using xUnit, Vitest, and Jest, and quality assurance automation. Use when designing test strategies, implementing TDD cycles, writing unit/integration tests, or improving test coverage in .NET and TypeScript projects.
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep
----
-
-# Testing Specialist
-
-Especialista em testes, mocking e simulação para projetos .NET.
-
-## Strategy
-
-| Level | What | Tools |
-|-------|------|-------|
-| **Unit** | Business logic, domain, handlers | xUnit + Moq + FluentAssertions |
-| **Integration** | API flows, DB operations | WebApplicationFactory + TestContainers |
-| **Component** | Blazor rendering, events | bUnit |
-| **E2E** | Critical user journeys | Playwright (if needed) |
-
-**Focus:** Critical/complex code. Don't aim for 100%, aim for value. Cover edge cases and error paths.
-
----
-
-## Core Patterns
-
-### AAA (Arrange-Act-Assert)
-
-```csharp
-[Fact]
-public async Task CreateOrder_Should_ReturnSuccess_When_ValidInput()
-{
-    // Arrange
-    var command = new CreateOrderCommand { CustomerId = 1, Items = [...] };
-    var handler = new CreateOrderHandler(_mockRepo.Object);
-    // Act
-    var result = await handler.Handle(command, CancellationToken.None);
-    // Assert
-    result.IsSuccess.Should().BeTrue();
-}
-```
-
-### Naming Convention
-```
-[Method]_Should_[ExpectedResult]_When_[Condition]
-```
-
-### Test Data Builders
-Use builder pattern for complex test entities: `new OrderBuilder().WithCustomer(123).WithStatus(Completed).Build()`
-
-### Mocking (Moq)
-```csharp
-var mockRepo = new Mock<IOrderRepository>();
-mockRepo.Setup(r => r.GetByIdAsync(It.IsAny<int>())).ReturnsAsync(new Order { Id = 1 });
-mockRepo.Verify(r => r.SaveAsync(It.IsAny<Order>()), Times.Once);
-```
-
-### Integration Tests (WebApplicationFactory)
-Replace real DB with in-memory in `ConfigureServices`, use `CreateClient()` for HTTP calls.
-
-### bUnit (Blazor)
-`RenderComponent<Counter>()` → `Find("button").Click()` → assert `TextContent`.
-
----
-
-## Libraries
-
-| Library | Purpose | NuGet |
-|---------|---------|-------|
-| xUnit | Test framework | `xunit` |
-| Moq | Mocking | `Moq` |
-| FluentAssertions | Readable assertions | `FluentAssertions` |
-| Bogus | Fake data | `Bogus` |
-| TestContainers | DB containers | `Testcontainers` |
-| Respawn | DB reset | `Respawn` |
-| WireMock | HTTP mocking | `WireMock.Net` |
-| bUnit | Blazor testing | `bunit` |
-
-## Folder Structure
-
-```
-tests/
-├── Unit/{Domain,Application,Builders}/
-├── Integration/{Api,Fixtures}/
-└── E2E/
-```
-
-## Anti-Patterns
-1. **Fragile tests** — test behavior, not implementation
-2. **Slow tests** — use mocks, not real DB for unit tests
-3. **Coupled tests** — each test independent
-4. **Vague assertions** — use specific FluentAssertions
-5. **Giant setup** — extract to builders/fixtures
-
----
-
-## Simulation of External Services
-
-> **Ref:** `.claude/skills/checklists/simulation-checklist.md` for complete checklist
-
-### Key Rules
-
-| Mock Type | Characteristic | DI Lifetime |
-|-----------|---------------|-------------|
-| **Stateful** (Dictionary, List) | Keeps data between calls | `Singleton` |
-| **Stateless** | No state | `Scoped` |
-
-```csharp
-// ❌ Stateful with Scoped = loses state between requests
-services.AddScoped<IReplicateClient, FakeReplicateClient>();
-// ✅ Stateful with Singleton
-services.AddSingleton<IReplicateClient, FakeReplicateClient>();
-```
-
-**Before implementing mocks:** Map ALL dependencies (interfaces, transitive deps, lifetimes).
-
----
-
-## Checklists
-
-### Per Test Type
-| Target | Test |
-|--------|------|
-| Entity/Domain | Creation validation, state transitions (valid + invalid), invariants |
-| Handler/Service | Happy path, invalid input, not found (404), auth error, timeout |
-| API | Status codes, response body, request validation, auth |
-| Blazor Component | Initial render, user events, states (loading/error/empty), form validation |
-
----
-
-*MORPH-SPEC by Polymorphism Tech*

package/framework/hooks/claude-code/notification/approval-reminder.js

@@ -1,57 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Notification Hook: Approval Reminder on Idle
- *
- * Event: Notification | Matcher: idle_prompt
- *
- * When Claude is idle, checks for pending approval gates and reminds the user.
- *
- * Fail-open: exits 0 on any error.
- */
-
-import { stateExists, getActiveFeature, getPendingGates, derivePhaseForFeature } from '../../shared/state-reader.js';
-import { injectContext, pass } from '../../shared/hook-response.js';
-import { logHookActivity } from '../../shared/activity-logger.js';
-
-try {
-  if (!stateExists()) pass();
-
-  const active = getActiveFeature();
-  if (!active) pass();
-
-  const { name, feature } = active;
-  const pending = getPendingGates(name);
-
-  if (pending.length === 0) pass();
-
-  // Only remind about gates relevant to the current phase
-  const phaseGateRelevance = {
-    proposal: ['proposal'],
-    setup: ['proposal'],
-    design: ['design'],
-    clarify: ['design'],
-    tasks: ['design', 'tasks'],
-    uiux: ['uiux'],
-    implement: ['design', 'tasks']
-  };
-
-  const currentPhase = feature.phase || derivePhaseForFeature(name);
-  const relevantGates = phaseGateRelevance[currentPhase] || [];
-  const pendingRelevant = pending.filter(g => relevantGates.includes(g));
-
-  if (pendingRelevant.length === 0) pass();
-
-  const reminders = pendingRelevant.map(gate =>
-    `  morph-spec approve ${name} ${gate}`
-  );
-
-  logHookActivity('approval-reminder', 'Notification', `pending(${pendingRelevant.join(',')})`);
-  injectContext(
-    `MORPH-SPEC: Feature '${name}' has pending approval(s) that may be blocking progress:\n` +
-    reminders.join('\n')
-  );
-} catch {
-  // Fail-open
-  process.exit(0);
-}

package/framework/hooks/claude-code/post-tool-use/context-refresh.js

@@ -1,109 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * PostToolUse Hook: Context Auto-Refresh
- *
- * Event: PostToolUse | Matcher: Bash
- *
- * Detects `git commit` commands that touch structural files (package.json,
- * *.csproj, next.config.*, etc.) and injects instructions for Claude to
- * update .morph/context/README.md and .morph/config/config.json.
- *
- * Only fires when:
- *   1. .morph/state.json exists (morph-spec project)
- *   2. Command contains `git commit`
- *   3. .morph/context/README.md is initialized (not a setup-infra placeholder)
- *   4. Structural files changed in the commit (compared to HEAD~1)
- *
- * Fail-open: exits 0 on any error.
- */
-
-import { execSync } from 'child_process';
-import { readFileSync, existsSync } from 'fs';
-import { join, basename } from 'path';
-import { readStdin } from '../../shared/stdin-reader.js';
-import { stateExists } from '../../shared/state-reader.js';
-import { pass, injectContext } from '../../shared/hook-response.js';
-import { logHookActivity } from '../../shared/activity-logger.js';
-
-const STRUCTURAL_PATTERNS = [
-  /^package\.json$/,
-  /\.csproj$/,
-  /\.sln$/,
-  /^next\.config\./,
-  /^tailwind\.config\./,
-  /^tsconfig\.json$/,
-  /^jsconfig\.json$/,
-  /^docker-compose/,
-  /^Dockerfile/,
-  /^\.env\.example$/,
-  /^go\.mod$/,
-  /^requirements\.txt$/,
-  /^pyproject\.toml$/,
-  /^Gemfile$/,
-];
-
-try {
-  if (!stateExists()) pass();
-
-  const payload = await readStdin();
-  if (!payload) pass();
-
-  const command = payload?.tool_input?.command || '';
-  if (!/\bgit\s+commit\b/.test(command)) pass();
-
-  if (!isContextInitialized()) pass();
-
-  let changedFiles = [];
-  try {
-    const output = execSync('git diff HEAD~1 --name-only', {
-      encoding: 'utf-8',
-      stdio: 'pipe',
-      cwd: process.cwd(),
-      timeout: 10000,
-    });
-    changedFiles = output.trim().split('\n').filter(Boolean);
-  } catch {
-    // First commit (no HEAD~1) or git error — pass silently
-    pass();
-  }
-
-  const structuralFiles = changedFiles.filter(file => {
-    const name = basename(file);
-    return STRUCTURAL_PATTERNS.some(pattern => pattern.test(name));
-  });
-
-  if (structuralFiles.length === 0) pass();
-
-  const fileList = structuralFiles.join(', ');
-  logHookActivity('context-refresh', 'PostToolUse', `structural_change(${structuralFiles.length})`);
-  injectContext(
-    `📋 [morph-spec] Mudanças estruturais detectadas no commit: ${fileList}\n\n` +
-    `Atualizar contexto do projeto automaticamente:\n` +
-    `1. \`git show HEAD --stat\` — ver escopo completo da mudança\n` +
-    `2. Ler \`.morph/context/README.md\` → atualizar seções afetadas\n` +
-    `   (Tech Stack, Architecture, Key Integrations, Agent Notes)\n` +
-    `3. Ler \`.morph/config/config.json\` → atualizar campos relevantes\n` +
-    `   (stack, architecture, integrations, paths)\n` +
-    `4. Escrever os arquivos atualizados com as mudanças detectadas`
-  );
-} catch {
-  // Fail-open
-  process.exit(0);
-}
-
-/**
- * Check if .morph/context/README.md is initialized (not a setup-infra placeholder).
- * Returns false if the file is missing or contains the placeholder sentinel.
- * @returns {boolean}
- */
-function isContextInitialized() {
-  try {
-    const contextPath = join(process.cwd(), '.morph/context/README.md');
-    if (!existsSync(contextPath)) return false;
-    const content = readFileSync(contextPath, 'utf-8');
-    return !content.includes('Run /morph-init to generate');
-  } catch {
-    return false;
-  }
-}

package/framework/hooks/claude-code/post-tool-use/skill-reminder.js

@@ -1,78 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * PostToolUse Hook: Skill Reminder on Task Start
- *
- * Event: PostToolUse | Matcher: Bash
- *
- * Fires after `morph-spec task start <feature> <task>` completes.
- * Reads requiredSkills from phases.json for the current phase and injects
- * mandatory skill invocation instructions as additionalContext.
- *
- * The additionalContext appears directly in Claude's view of the Bash tool
- * result — more prominent than any pre-loaded prompt text.
- *
- * Fail-open: exits 0 on any error.
- */
-
-import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
-import { readStdin } from '../../shared/stdin-reader.js';
-import { stateExists, loadState, derivePhaseForFeature } from '../../shared/state-reader.js';
-import { injectContext, pass } from '../../shared/hook-response.js';
-import { logHookActivity } from '../../shared/activity-logger.js';
-import { parseTaskStartCommand, buildSkillReminderMessage } from '../../shared/skill-reminder-helpers.js';
-
-// Re-export for backwards compatibility (tests may import from this file)
-export { parseTaskStartCommand, buildSkillReminderMessage };
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Hook entry point
-// ─────────────────────────────────────────────────────────────────────────────
-
-try {
-  if (!stateExists()) pass();
-
-  const payload = await readStdin();
-  if (!payload) pass();
-
-  const command = payload?.tool_input?.command || '';
-  const parsed = parseTaskStartCommand(command);
-  if (!parsed) pass();
-
-  const { featureName, taskId } = parsed;
-
-  // Load state to get current phase
-  const state = loadState();
-  if (!state) pass();
-
-  const feature = state?.features?.[featureName];
-  if (!feature) pass();
-
-  const phase = feature.phase || derivePhaseForFeature(featureName);
-  if (!phase) pass();
-
-  // Load phases.json (project-local first, fall back to package-level)
-  const localPhasesPath = join(process.cwd(), 'framework', 'phases.json');
-  const pkgPhasesPath = join(
-    process.cwd(), 'node_modules', '@polymorphism-tech', 'morph-spec', 'framework', 'phases.json'
-  );
-  const phasesPath = existsSync(localPhasesPath) ? localPhasesPath : pkgPhasesPath;
-  if (!existsSync(phasesPath)) pass();
-
-  let phasesData;
-  try {
-    phasesData = JSON.parse(readFileSync(phasesPath, 'utf8'));
-  } catch {
-    pass();
-  }
-
-  const message = buildSkillReminderMessage(featureName, taskId, phase, phasesData);
-  if (!message) pass();
-
-  logHookActivity('skill-reminder', 'PostToolUse', `injected(${featureName}/${taskId}/${phase})`);
-  injectContext(message);
-} catch {
-  // Fail-open
-  process.exit(0);
-}