@polymorphism-tech/morph-spec 4.8.19 → 4.9.0

package/framework/hooks/shared/stale-task-reset.js

@@ -0,0 +1,57 @@
+/**
+ * Stale Task Reset — shared hook utility
+ *
+ * Detects tasks stuck in `in_progress` for longer than STALE_MS and resets
+ * them to `pending`. Works for both v2 (tasks is array) and v3 (taskList)
+ * state formats. Pure function: mutates state in-place, returns reset log.
+ *
+ * Stale threshold: 1 hour (hardcoded — not user-configurable)
+ */
+
+export const STALE_MS = 60 * 60 * 1000; // 1 hour
+
+/**
+ * Determine if a task is stale (in_progress for longer than STALE_MS).
+ * @param {Object} task
+ * @param {number} [now] - timestamp for testability (defaults to Date.now())
+ * @returns {boolean}
+ */
+export function isStaleTask(task, now = Date.now()) {
+  if (task.status !== 'in_progress') return false;
+  if (!task.startedAt) return true; // missing timestamp → treat as stale
+  return now - new Date(task.startedAt).getTime() > STALE_MS;
+}
+
+/**
+ * Reset all stale in_progress tasks across all features in state.
+ * Mutates state in-place. Returns log of reset task identifiers.
+ *
+ * @param {Object} state - Full state object (state.features)
+ * @param {number} [now] - Timestamp for testability
+ * @returns {string[]} resetLog — entries like "feature-name/T008"
+ */
+export function resetStaleTasks(state, now = Date.now()) {
+  const resetLog = [];
+
+  for (const [featureName, feature] of Object.entries(state.features || {})) {
+    // Resolve task list for both v2 (array) and v3 (taskList) formats
+    const isV2 = Array.isArray(feature.tasks);
+    const list = isV2 ? feature.tasks : (feature.taskList || []);
+
+    for (const task of list) {
+      if (isStaleTask(task, now)) {
+        task.status = 'pending';
+        delete task.startedAt;
+        resetLog.push(`${featureName}/${task.id ?? '(unknown)'}`);
+      }
+    }
+
+    // Re-sync counters (v3 only — v2 tasks IS the list, no separate counters)
+    if (!isV2 && feature.tasks) {
+      feature.tasks.inProgress = list.filter(t => t.status === 'in_progress').length;
+      feature.tasks.pending = list.filter(t => t.status === 'pending').length;
+    }
+  }
+
+  return resetLog;
+}

package/framework/hooks/shared/state-reader.js

@@ -74,7 +74,7 @@ export function getFeature(featureName, projectPath) {
 }
 
 /**
- * Derive phase from filesystem (v5.0.0+: phase deleted from state).
+ * Derive phase from filesystem (phase deleted from state).
  * Checks for phase folders in descending order, returns highest present.
  * @param {string} featureName
  * @param {string} [projectPath]
@@ -98,7 +98,7 @@ export function derivePhaseForFeature(featureName, projectPath) {
 
 /**
  * Get the current phase of a feature.
- * Falls back to filesystem derivation when phase is not in state (v5.0.0+).
+ * Falls back to filesystem derivation when phase is not in state.
  * @param {string} featureName
  * @param {string} [projectPath]
  * @returns {string|null}

package/framework/hooks/shared/worktree-helpers.js

@@ -0,0 +1,53 @@
+/**
+ * Shared helpers for worktree-related hook logic.
+ * Pure functions — no side effects, easy to test.
+ */
+
+/**
+ * Parse JSON output from `morph-spec worktree setup`.
+ * Finds the last line starting with '{' to skip chalk-colored output.
+ * @param {string} stdout - Raw stdout from the command
+ * @returns {Object|null}
+ */
+export function parseWorktreeResult(stdout) {
+  if (!stdout || typeof stdout !== 'string') return null;
+  try {
+    const trimmed = stdout.trim();
+    if (!trimmed) return null;
+    const lines = trimmed.split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const line = lines[i].trim();
+      if (line.startsWith('{')) {
+        return JSON.parse(line);
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build context line(s) to inject based on worktree setup result.
+ * @param {Object|null} result - Parsed result from parseWorktreeResult
+ * @returns {string} Context lines to inject, or '' to skip injection
+ */
+export function buildWorktreeContextLine(result) {
+  if (!result) return '';
+  if (result.error) return '';
+
+  if (result.created) {
+    return `🪴 Worktree created: Working in .worktrees/${result.feature || ''} on branch ${result.branch}`;
+  }
+
+  if (result.alreadyExists) {
+    return [
+      `⚠️  Existing worktree found for feature '${result.feature}': ${result.path} (branch: ${result.branch})`,
+      `   Use AskUserQuestion to ask: "resume existing worktree or start fresh (--fresh)?"`,
+      `   • Resume: continue in existing worktree (no change)`,
+      `   • Fresh: run \`morph-spec worktree setup ${result.feature} --fresh\``
+    ].join('\n');
+  }
+
+  return '';
+}

package/framework/phases.json

@@ -17,7 +17,10 @@
       "pausePoints": [
         { "id": "proposal", "label": "Approve Proposal" }
       ],
-      "agentTiers": [1]
+      "agentTiers": [1],
+      "requiredSkills": [
+        { "trigger": "beforePhaseStart", "skill": "morph:brainstorming" }
+      ]
     },
     "setup": {
       "id": "setup",
@@ -33,7 +36,8 @@
       "optionalOutputs": [],
       "recommendedMCPs": ["github"],
       "pausePoints": [],
-      "agentTiers": [1, 2]
+      "agentTiers": [1, 2],
+      "requiredSkills": []
     },
     "uiux": {
       "id": "uiux",
@@ -52,7 +56,12 @@
       "pausePoints": [
         { "id": "uiux", "label": "Approve UI/UX Design" }
       ],
-      "agentTiers": [1, 2, 3]
+      "agentTiers": [1, 2, 3],
+      "requiredSkills": [
+        { "trigger": "beforeArchitecturalDecision", "skill": "morph:brainstorming" },
+        { "trigger": "onHTMLPrototypeAvailable",    "skill": "morph:replicate" },
+        { "trigger": "beforePhaseComplete",         "skill": "morph:frontend-review" }
+      ]
     },
     "design": {
       "id": "design",
@@ -71,7 +80,13 @@
       "pausePoints": [
         { "id": "design", "label": "Approve Design Spec" }
       ],
-      "agentTiers": [1, 2, 3, 4]
+      "agentTiers": [1, 2, 3, 4],
+      "requiredSkills": [
+        { "trigger": "beforePhaseStart",             "skill": "morph:phase-codebase-analysis" },
+        { "trigger": "beforeArchitecturalDecision",  "skill": "morph:brainstorming" },
+        { "trigger": "onExternalServiceIntegration", "skill": "morph:simulation-checklist" },
+        { "trigger": "beforePhaseComplete",          "skill": "morph:verification-before-completion" }
+      ]
     },
     "clarify": {
       "id": "clarify",
@@ -87,7 +102,10 @@
       "optionalOutputs": [],
       "recommendedMCPs": ["context7", "github"],
       "pausePoints": [],
-      "agentTiers": [1, 2]
+      "agentTiers": [1, 2],
+      "requiredSkills": [
+        { "trigger": "beforePhaseComplete", "skill": "morph:verification-before-completion" }
+      ]
     },
     "tasks": {
       "id": "tasks",
@@ -105,7 +123,12 @@
       "pausePoints": [
         { "id": "tasks", "label": "Approve Task List" }
       ],
-      "agentTiers": [1, 2, 3]
+      "agentTiers": [1, 2, 3],
+      "requiredSkills": [
+        { "trigger": "beforePhaseStart",          "skill": "superpowers:writing-plans" },
+        { "trigger": "onParallelTasksIdentified", "skill": "superpowers:dispatching-parallel-agents" },
+        { "trigger": "beforePhaseComplete",       "skill": "morph:verification-before-completion" }
+      ]
     },
     "implement": {
       "id": "implement",
@@ -122,7 +145,15 @@
       "optionalOutputs": [],
       "recommendedMCPs": ["supabase", "context7", "playwright", "github", "docker", "azure"],
       "pausePoints": [],
-      "agentTiers": [1, 2, 3, 4]
+      "agentTiers": [1, 2, 3, 4],
+      "requiredSkills": [
+        { "trigger": "beforeEachTask",    "skill": "superpowers:test-driven-development" },
+        { "trigger": "beforeTaskDone",    "skill": "morph:verification-before-completion" },
+        { "trigger": "onBugOrUnexpected", "skill": "superpowers:systematic-debugging" },
+        { "trigger": "afterAllTasks",     "skill": "morph:post-implementation" },
+        { "trigger": "afterAllTasks",     "skill": "superpowers:requesting-code-review" },
+        { "trigger": "beforePR",          "skill": "morph:checklist" }
+      ]
     },
     "sync": {
       "id": "sync",
@@ -139,7 +170,8 @@
       "optionalOutputs": [],
       "recommendedMCPs": [],
       "pausePoints": [],
-      "agentTiers": [1]
+      "agentTiers": [1],
+      "requiredSkills": []
     }
   }
 }

package/framework/skills/level-0-meta/brainstorming/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: brainstorming
+name: morph:brainstorming
 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.
 user-invocable: true
 argument-hint: "[feature-name or topic]"

package/framework/skills/level-0-meta/code-review/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: code-review
+name: morph:code-review
 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

package/framework/skills/level-0-meta/code-review-nextjs/SKILL.md

@@ -1,163 +1,163 @@
----
-name: code-review-nextjs
-description: Next.js code review checklist covering naming conventions, component architecture (Server vs Client), data fetching patterns, form implementation, state management, TypeScript/Zod discipline, feature boundaries, and testing. Use after implementing Next.js code, before creating PRs, or when reviewing TSX/TS code for compliance with MORPH-SPEC Next.js standards.
-user-invocable: true
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep
----
-
-# Next.js Code Review Checklist
-
-> Comprehensive checklist for Next.js code review: naming, component architecture, data fetching, forms, state, TypeScript, structure, and testing.
-> **Ref:** `framework/standards/frontend/nextjs/naming-conventions.md`
-> **Ref:** `framework/standards/frontend/nextjs/app-router.md`
-> **Ref:** `framework/standards/frontend/nextjs/components.md`
-> **Ref:** `framework/standards/frontend/nextjs/data-fetching.md`
-> **Ref:** `framework/standards/frontend/nextjs/forms.md`
-> **Ref:** `framework/standards/frontend/nextjs/state-management.md`
-> **Ref:** `framework/standards/frontend/nextjs/testing.md`
-> **Example:** `references/review-example-nextjs.md` — filled-in review showing expected finding format.
-> **Script:** `scripts/scan-nextjs.mjs` — automated scan for CRITICAL/HIGH violations before manual review.
-> **Ref:** `.claude/skills/code-review/references/review-guidelines.md` — false-positive rubric, confidence scoring, evidence format.
-
----
-
-## Step 0 — Eligibility Check
-
-```bash
-git diff --name-only main...HEAD -- "*.tsx" "*.ts" | wc -l
-```
-
-**Pular revisão se:**
-- 0 arquivos `.tsx`/`.ts` alterados → sem código frontend para revisar
-- Apenas mudanças em `*.json`, `*.md`, arquivos de config → escopo de infra
-- Já existe `.morph/features/$ARGUMENTS/4-implement/code-review-nextjs.md` criado hoje → já revisado
-
-Se skip: output `"Skipping code-review-nextjs: [motivo]"` e parar.
-
----
-
-## Step 1 — Run automated scan first
-
-```bash
-node scripts/scan-nextjs.mjs src/
-```
-
-Review and address CRITICAL findings before proceeding with the manual checklist below. Warnings can be addressed during review.
-
----
-
-## Naming & Style (ref: naming-conventions.md)
-
-- [ ] `[CRITICAL]` File names use kebab-case (`user-card.tsx`, NOT `UserCard.tsx`)
-- [ ] `[HIGH]` Components exported as named exports (`export function UserCard`, NOT `export default function UserCard`)
-- [ ] `[HIGH]` Hook files named `use-{action}.ts` and export `use{Action}()`
-- [ ] `[HIGH]` Schema files named `{feature}.schemas.ts` with Zod exports
-- [ ] `[HIGH]` Type files named `{feature}.types.ts` with `z.infer<>` derived types
-- [ ] `[MEDIUM]` No abbreviations in public API names (`repository` not `repo`)
-- [ ] `[MEDIUM]` Feature folder uses kebab-case (`features/user-management/`, NOT `features/userManagement/`)
-
----
-
-## Component Architecture (ref: app-router.md, components.md)
-
-### Server vs Client Discipline
-- [ ] `[CRITICAL]` `'use client'` only on components that use hooks or event handlers
-- [ ] `[CRITICAL]` No `useEffect(() => { fetch(...) }, [])` for data fetching — use Server Components or TanStack Query
-- [ ] `[HIGH]` Server Components used for initial page data (no `'use client'` on page files)
-- [ ] `[HIGH]` `loading.tsx`, `error.tsx` co-located with every `page.tsx`
-- [ ] `[HIGH]` No business logic in `app/` route files — import from `features/`
-
-### Three-Tier Hierarchy
-- [ ] `[CRITICAL]` No edits to `components/ui/` files — shadcn primitives are never modified
-- [ ] `[HIGH]` `components/` (Tier 2) has no imports from `features/` — no domain knowledge
-- [ ] `[HIGH]` Feature components (`features/*/components/`) do not import from other features
-- [ ] `[MEDIUM]` Feature cross-dependencies extracted to `components/` or `lib/`
-
----
-
-## Data Fetching (ref: data-fetching.md)
-
-- [ ] `[CRITICAL]` No `useEffect` + `useState` pattern for API data — use `useQuery`
-- [ ] `[HIGH]` TanStack Query v5 syntax: `useQuery({ queryKey: [...], queryFn: async () => {} })`
-- [ ] `[HIGH]` Query key factory pattern used (`userKeys.lists()`, NOT hardcoded `['users']`)
-- [ ] `[HIGH]` `useMutation` used for POST/PUT/DELETE — not inline `fetch` in handlers
-- [ ] `[HIGH]` API responses validated with Zod before use
-- [ ] `[MEDIUM]` `onSuccess` in `useMutation` invalidates relevant query keys
-- [ ] `[MEDIUM]` `QueryClientProvider` wraps app in `app/layout.tsx`, not per-component
-
----
-
-## Forms (ref: forms.md)
-
-- [ ] `[CRITICAL]` Zod schema defined BEFORE TypeScript type — type derived with `z.infer<>`
-- [ ] `[HIGH]` `useForm` uses `zodResolver(schema)` — NOT manual validation
-- [ ] `[HIGH]` shadcn `<Form>`, `<FormField>`, `<FormItem>`, `<FormLabel>`, `<FormControl>`, `<FormMessage>` used
-- [ ] `[HIGH]` Form submission uses `useMutation` — NOT direct `fetch` in `onSubmit`
-- [ ] `[MEDIUM]` `isPending` used for loading state — NOT `isLoading` (v5 renamed)
-- [ ] `[MEDIUM]` Root-level errors displayed: `form.formState.errors.root`
-- [ ] `[MEDIUM]` No `useState` for individual form fields — react-hook-form handles this
-
----
-
-## State Management (ref: state-management.md)
-
-- [ ] `[HIGH]` No Zustand/Redux installed without documented justification
-- [ ] `[HIGH]` No React Context used for server state (API data) — use TanStack Query
-- [ ] `[MEDIUM]` Local UI state (open/closed, selected) in `useState` — not global store
-- [ ] `[MEDIUM]` Context only for truly global UI: theme, auth user, locale
-- [ ] `[LOW]` No prop drilling beyond 3 levels — consider Context or co-location
-
----
-
-## TypeScript Discipline
-
-- [ ] `[CRITICAL]` No `any` type — use `unknown` and narrow, or fix the actual type
-- [ ] `[HIGH]` Types derived from Zod schemas (`type User = z.infer<typeof userSchema>`)
-- [ ] `[HIGH]` No duplicate type definitions — if the server returns it, define it once with Zod
-- [ ] `[MEDIUM]` API response types come from the shared schema, not manually written
-- [ ] `[MEDIUM]` `noUncheckedIndexedAccess` respected — array accesses use optional chaining
-- [ ] `[LOW]` No type assertions (`as User`) without validation
-
----
-
-## Feature Structure (ref: project-structure.md)
-
-- [ ] `[HIGH]` Feature exposes public API via `features/{name}/index.ts` — no deep path imports
-- [ ] `[HIGH]` Consumers import from index: `from '@/features/users'` NOT `from '@/features/users/components/user-list'`
-- [ ] `[MEDIUM]` New features create: `components/`, `hooks/`, `types/` subdirectories
-- [ ] `[MEDIUM]` TanStack Query hooks in `features/{name}/hooks/` — NOT co-located with components
-- [ ] `[MEDIUM]` Zod schemas in `features/{name}/types/{name}.schemas.ts`
-- [ ] `[LOW]` Feature index only exports what external consumers actually need (no over-exposure)
-
----
-
-## Testing (ref: testing.md)
-
-- [ ] `[HIGH]` Test files co-located with source (`user-card.test.tsx` next to `user-card.tsx`)
-- [ ] `[HIGH]` `@testing-library/user-event` used — NOT `fireEvent`
-- [ ] `[HIGH]` API calls mocked with MSW — NOT `jest.mock('fetch')` or `global.fetch = jest.fn()`
-- [ ] `[MEDIUM]` Hook tests use `QueryClientWrapper` helper with `retry: false`
-- [ ] `[MEDIUM]` Tests cover happy path + one error path per component
-- [ ] `[LOW]` No snapshot tests — use `expect(screen.getByText(...))`
-
----
-
-## Quick Pre-Merge Checklist
-
-```
-[ ] node scripts/scan-nextjs.mjs src/ — 0 CRITICAL findings
-[ ] File names are kebab-case (UserCard.tsx → user-card.tsx)
-[ ] 'use client' only on interactive components (hooks or event handlers)
-[ ] No useEffect for data fetching — Server Component or useQuery
-[ ] Zod schema defined first, type derived with z.infer<>
-[ ] zodResolver connected to useForm, useMutation for submit
-[ ] Query key factory used (userKeys.lists() not ['users'])
-[ ] Feature public API via features/{name}/index.ts
-[ ] components/ui/ files untouched (shadcn CLI only)
-[ ] Tests: userEvent not fireEvent, MSW not mock fetch
-```
-
----
-
-*Covers: naming-conventions.md + app-router.md + components.md + data-fetching.md + forms.md + state-management.md + testing.md + project-structure.md*
-*MORPH-SPEC by Polymorphism Tech*
+---
+name: morph:code-review-nextjs
+description: Next.js code review checklist covering naming conventions, component architecture (Server vs Client), data fetching patterns, form implementation, state management, TypeScript/Zod discipline, feature boundaries, and testing. Use after implementing Next.js code, before creating PRs, or when reviewing TSX/TS code for compliance with MORPH-SPEC Next.js standards.
+user-invocable: true
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Next.js Code Review Checklist
+
+> Comprehensive checklist for Next.js code review: naming, component architecture, data fetching, forms, state, TypeScript, structure, and testing.
+> **Ref:** `framework/standards/frontend/nextjs/naming-conventions.md`
+> **Ref:** `framework/standards/frontend/nextjs/app-router.md`
+> **Ref:** `framework/standards/frontend/nextjs/components.md`
+> **Ref:** `framework/standards/frontend/nextjs/data-fetching.md`
+> **Ref:** `framework/standards/frontend/nextjs/forms.md`
+> **Ref:** `framework/standards/frontend/nextjs/state-management.md`
+> **Ref:** `framework/standards/frontend/nextjs/testing.md`
+> **Example:** `references/review-example-nextjs.md` — filled-in review showing expected finding format.
+> **Script:** `scripts/scan-nextjs.mjs` — automated scan for CRITICAL/HIGH violations before manual review.
+> **Ref:** `.claude/skills/code-review/references/review-guidelines.md` — false-positive rubric, confidence scoring, evidence format.
+
+---
+
+## Step 0 — Eligibility Check
+
+```bash
+git diff --name-only main...HEAD -- "*.tsx" "*.ts" | wc -l
+```
+
+**Pular revisão se:**
+- 0 arquivos `.tsx`/`.ts` alterados → sem código frontend para revisar
+- Apenas mudanças em `*.json`, `*.md`, arquivos de config → escopo de infra
+- Já existe `.morph/features/$ARGUMENTS/4-implement/code-review-nextjs.md` criado hoje → já revisado
+
+Se skip: output `"Skipping code-review-nextjs: [motivo]"` e parar.
+
+---
+
+## Step 1 — Run automated scan first
+
+```bash
+node scripts/scan-nextjs.mjs src/
+```
+
+Review and address CRITICAL findings before proceeding with the manual checklist below. Warnings can be addressed during review.
+
+---
+
+## Naming & Style (ref: naming-conventions.md)
+
+- [ ] `[CRITICAL]` File names use kebab-case (`user-card.tsx`, NOT `UserCard.tsx`)
+- [ ] `[HIGH]` Components exported as named exports (`export function UserCard`, NOT `export default function UserCard`)
+- [ ] `[HIGH]` Hook files named `use-{action}.ts` and export `use{Action}()`
+- [ ] `[HIGH]` Schema files named `{feature}.schemas.ts` with Zod exports
+- [ ] `[HIGH]` Type files named `{feature}.types.ts` with `z.infer<>` derived types
+- [ ] `[MEDIUM]` No abbreviations in public API names (`repository` not `repo`)
+- [ ] `[MEDIUM]` Feature folder uses kebab-case (`features/user-management/`, NOT `features/userManagement/`)
+
+---
+
+## Component Architecture (ref: app-router.md, components.md)
+
+### Server vs Client Discipline
+- [ ] `[CRITICAL]` `'use client'` only on components that use hooks or event handlers
+- [ ] `[CRITICAL]` No `useEffect(() => { fetch(...) }, [])` for data fetching — use Server Components or TanStack Query
+- [ ] `[HIGH]` Server Components used for initial page data (no `'use client'` on page files)
+- [ ] `[HIGH]` `loading.tsx`, `error.tsx` co-located with every `page.tsx`
+- [ ] `[HIGH]` No business logic in `app/` route files — import from `features/`
+
+### Three-Tier Hierarchy
+- [ ] `[CRITICAL]` No edits to `components/ui/` files — shadcn primitives are never modified
+- [ ] `[HIGH]` `components/` (Tier 2) has no imports from `features/` — no domain knowledge
+- [ ] `[HIGH]` Feature components (`features/*/components/`) do not import from other features
+- [ ] `[MEDIUM]` Feature cross-dependencies extracted to `components/` or `lib/`
+
+---
+
+## Data Fetching (ref: data-fetching.md)
+
+- [ ] `[CRITICAL]` No `useEffect` + `useState` pattern for API data — use `useQuery`
+- [ ] `[HIGH]` TanStack Query v5 syntax: `useQuery({ queryKey: [...], queryFn: async () => {} })`
+- [ ] `[HIGH]` Query key factory pattern used (`userKeys.lists()`, NOT hardcoded `['users']`)
+- [ ] `[HIGH]` `useMutation` used for POST/PUT/DELETE — not inline `fetch` in handlers
+- [ ] `[HIGH]` API responses validated with Zod before use
+- [ ] `[MEDIUM]` `onSuccess` in `useMutation` invalidates relevant query keys
+- [ ] `[MEDIUM]` `QueryClientProvider` wraps app in `app/layout.tsx`, not per-component
+
+---
+
+## Forms (ref: forms.md)
+
+- [ ] `[CRITICAL]` Zod schema defined BEFORE TypeScript type — type derived with `z.infer<>`
+- [ ] `[HIGH]` `useForm` uses `zodResolver(schema)` — NOT manual validation
+- [ ] `[HIGH]` shadcn `<Form>`, `<FormField>`, `<FormItem>`, `<FormLabel>`, `<FormControl>`, `<FormMessage>` used
+- [ ] `[HIGH]` Form submission uses `useMutation` — NOT direct `fetch` in `onSubmit`
+- [ ] `[MEDIUM]` `isPending` used for loading state — NOT `isLoading` (v5 renamed)
+- [ ] `[MEDIUM]` Root-level errors displayed: `form.formState.errors.root`
+- [ ] `[MEDIUM]` No `useState` for individual form fields — react-hook-form handles this
+
+---
+
+## State Management (ref: state-management.md)
+
+- [ ] `[HIGH]` No Zustand/Redux installed without documented justification
+- [ ] `[HIGH]` No React Context used for server state (API data) — use TanStack Query
+- [ ] `[MEDIUM]` Local UI state (open/closed, selected) in `useState` — not global store
+- [ ] `[MEDIUM]` Context only for truly global UI: theme, auth user, locale
+- [ ] `[LOW]` No prop drilling beyond 3 levels — consider Context or co-location
+
+---
+
+## TypeScript Discipline
+
+- [ ] `[CRITICAL]` No `any` type — use `unknown` and narrow, or fix the actual type
+- [ ] `[HIGH]` Types derived from Zod schemas (`type User = z.infer<typeof userSchema>`)
+- [ ] `[HIGH]` No duplicate type definitions — if the server returns it, define it once with Zod
+- [ ] `[MEDIUM]` API response types come from the shared schema, not manually written
+- [ ] `[MEDIUM]` `noUncheckedIndexedAccess` respected — array accesses use optional chaining
+- [ ] `[LOW]` No type assertions (`as User`) without validation
+
+---
+
+## Feature Structure (ref: project-structure.md)
+
+- [ ] `[HIGH]` Feature exposes public API via `features/{name}/index.ts` — no deep path imports
+- [ ] `[HIGH]` Consumers import from index: `from '@/features/users'` NOT `from '@/features/users/components/user-list'`
+- [ ] `[MEDIUM]` New features create: `components/`, `hooks/`, `types/` subdirectories
+- [ ] `[MEDIUM]` TanStack Query hooks in `features/{name}/hooks/` — NOT co-located with components
+- [ ] `[MEDIUM]` Zod schemas in `features/{name}/types/{name}.schemas.ts`
+- [ ] `[LOW]` Feature index only exports what external consumers actually need (no over-exposure)
+
+---
+
+## Testing (ref: testing.md)
+
+- [ ] `[HIGH]` Test files co-located with source (`user-card.test.tsx` next to `user-card.tsx`)
+- [ ] `[HIGH]` `@testing-library/user-event` used — NOT `fireEvent`
+- [ ] `[HIGH]` API calls mocked with MSW — NOT `jest.mock('fetch')` or `global.fetch = jest.fn()`
+- [ ] `[MEDIUM]` Hook tests use `QueryClientWrapper` helper with `retry: false`
+- [ ] `[MEDIUM]` Tests cover happy path + one error path per component
+- [ ] `[LOW]` No snapshot tests — use `expect(screen.getByText(...))`
+
+---
+
+## Quick Pre-Merge Checklist
+
+```
+[ ] node scripts/scan-nextjs.mjs src/ — 0 CRITICAL findings
+[ ] File names are kebab-case (UserCard.tsx → user-card.tsx)
+[ ] 'use client' only on interactive components (hooks or event handlers)
+[ ] No useEffect for data fetching — Server Component or useQuery
+[ ] Zod schema defined first, type derived with z.infer<>
+[ ] zodResolver connected to useForm, useMutation for submit
+[ ] Query key factory used (userKeys.lists() not ['users'])
+[ ] Feature public API via features/{name}/index.ts
+[ ] components/ui/ files untouched (shadcn CLI only)
+[ ] Tests: userEvent not fireEvent, MSW not mock fetch
+```
+
+---
+
+*Covers: naming-conventions.md + app-router.md + components.md + data-fetching.md + forms.md + state-management.md + testing.md + project-structure.md*
+*MORPH-SPEC by Polymorphism Tech*

package/framework/skills/level-0-meta/frontend-review/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: frontend-review
+name: morph:frontend-review
 description: Auditoria completa do frontend — valida design outputs (design-system, contraste WCAG,
   mockups), scan estático de acessibilidade (TSX + Razor), screenshots responsivos em 3
   breakpoints via Playwright, axe-core a11y em runtime, e SEO (Next.js metadata). Cobre Next.js
@@ -10,7 +10,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep,
   mcp__playwright__browser_navigate, mcp__playwright__browser_resize,
   mcp__playwright__browser_take_screenshot, mcp__playwright__browser_snapshot,
   mcp__playwright__browser_evaluate, mcp__playwright__browser_console_messages
-cliVersion: "4.8.14"
+cliVersion: "4.8.19"
 ---
 
 # Frontend Review
@@ -79,7 +79,7 @@ contraste ≥ 4.5:1. Ferramentas de referência: WebAIM Contrast Checker (crité
 ## Step 2 — Scan Estático de Acessibilidade
 
 ```bash
-node .claude/skills/frontend-review/scripts/scan-accessibility.mjs $frontendPath
+node .claude/skills/morph:frontend-review/scripts/scan-accessibility.mjs $frontendPath
 ```
 
 O script detecta automaticamente a extensão dos arquivos para determinar Next.js (`.tsx`) vs
@@ -190,7 +190,7 @@ Solicite confirmação explícita ao usuário antes de pular os screenshots:
 Dev server não detectado. Screenshots responsivos via Playwright não podem ser capturados.
 
 Opções:
-1. Inicie manualmente o servidor e re-execute /frontend-review
+1. Inicie manualmente o servidor e re-execute /morph:frontend-review
 2. Confirme explicitamente que deseja pular os screenshots e por quê
 
 Não é possível prosseguir para axe-core sem dev server.
@@ -297,7 +297,7 @@ Criar arquivo de resumo consolidado:
 mkdir -p ".morph/features/$ARGUMENTS/visual-screenshots"
 ```
 
-Salvar em `.morph/features/$ARGUMENTS/visual-screenshots/frontend-review-summary.md`:
+Salvar em `.morph/features/$ARGUMENTS/visual-screenshots/morph:frontend-review-summary.md`:
 
 ```markdown
 # Frontend Review — {feature}

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

@@ -1,5 +1,5 @@
 ---
-name: morph-checklist
+name: morph:checklist
 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
@@ -7,7 +7,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 
 # MORPH Checklists
 
-Types: `deploy`, `security`, `seo`, `performance`, `accessibility`, `legal-brazil`, `simulation` (ver skill: `simulation-checklist`)
+Types: `deploy`, `security`, `seo`, `performance`, `accessibility`, `legal-brazil`, `simulation` (ver skill: `morph:simulation-checklist`)
 
 ---