@polymorphism-tech/morph-spec 4.5.0 → 4.7.0

package/docs/plans/2026-02-23-nextjs-code-review-impl.md

@@ -0,0 +1,1254 @@
+# Next.js Code Review & Scan Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add full Next.js code review coverage to morph-spec — wire the existing validator into the auto-validation pipeline, build a CLI scan script, and create the `code-review-nextjs` skill with a reference example.
+
+**Architecture:** Three-layer system. Layer 1 (auto): `nextjs-component` validator wired into `validation-runner.js` via `agents.json`, runs automatically on `morph-spec validate`. Layer 2 (CLI): `scripts/scan-nextjs.mjs` wraps `validateNextComponent` + adds extra checks, usable in CI. Layer 3 (LLM): `code-review-nextjs` skill references the scan script first, then manual checklist covering all 8 Next.js standards.
+
+**Tech Stack:** Node.js/ESM, `glob` package, `node:test` + `node:assert/strict`, `node:fs/promises`, `node:os`, chalk
+
+---
+
+## Key Context
+
+- `validateNextComponent(content, filePath)` is in `src/lib/validators/nextjs/next-component-validator.js`
+  - Returns `{ type: 'error'|'warning', message, suggestion, file, line? }[]`
+  - Currently exports only `validateNextComponent` — no project-level scanner
+- `validation-runner.js:runSingleValidator()` uses a `switch` on validatorId and expects `{ errors, warnings, issues: [{level, message, file, line?, solution?}] }`
+- `agents.json` `nextjs-expert.validators` currently = `["packages"]` — bug, missing `nextjs-component`
+- `glob` package is available in package.json
+- Skills installer copies entire directory trees from `framework/skills/level-0-meta/{name}/` → `.claude/skills/{name}/`
+
+---
+
+### Task 1: Wire nextjs-component validator (bug fix + TDD)
+
+**Files:**
+- Modify: `src/lib/validators/nextjs/next-component-validator.js` (add project-level scanner)
+- Modify: `src/lib/validators/nextjs/index.js` (export new function)
+- Modify: `src/lib/validators/validation-runner.js` (add case)
+- Modify: `framework/agents.json` (fix validators array)
+- Create: `test/validators/nextjs/next-component-files-validator.test.js`
+
+**Step 1: Write failing tests first**
+
+Create `test/validators/nextjs/next-component-files-validator.test.js`:
+
+```js
+import { test, describe, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { validateNextComponentFiles } from '../../../src/lib/validators/nextjs/next-component-validator.js';
+
+describe('validateNextComponentFiles', () => {
+  let tempDir;
+
+  beforeEach(() => {
+    tempDir = join(tmpdir(), `morph-nextjs-files-test-${Date.now()}`);
+    mkdirSync(join(tempDir, 'src', 'components'), { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  test('returns { errors: 0, warnings: 0, issues: [] } for a clean project', async () => {
+    writeFileSync(
+      join(tempDir, 'src', 'components', 'user-card.tsx'),
+      `'use client';\nimport { useState } from 'react';\nexport function UserCard() { const [x] = useState(0); return <div>{x}</div>; }`
+    );
+    const result = await validateNextComponentFiles(tempDir, {});
+    assert.equal(result.errors, 0);
+    assert.equal(result.warnings, 0);
+    assert.equal(result.issues.length, 0);
+  });
+
+  test('returns error when useState used without use client', async () => {
+    writeFileSync(
+      join(tempDir, 'src', 'components', 'broken.tsx'),
+      `import { useState } from 'react';\nexport function Broken() { const [x] = useState(0); return <div>{x}</div>; }`
+    );
+    const result = await validateNextComponentFiles(tempDir, {});
+    assert.ok(result.errors > 0, 'should have errors');
+    assert.ok(result.issues.length > 0, 'should have issues');
+    assert.equal(result.issues[0].level, 'error');
+  });
+
+  test('returns warning when use client has no interactivity', async () => {
+    writeFileSync(
+      join(tempDir, 'src', 'components', 'static.tsx'),
+      `'use client';\nexport function Static() { return <div>Hello</div>; }`
+    );
+    const result = await validateNextComponentFiles(tempDir, {});
+    assert.ok(result.warnings > 0, 'should have warnings');
+    assert.equal(result.issues[0].level, 'warning');
+  });
+
+  test('maps ValidationIssue.suggestion to issue.solution', async () => {
+    writeFileSync(
+      join(tempDir, 'src', 'components', 'static.tsx'),
+      `'use client';\nexport function Static() { return <div>Hello</div>; }`
+    );
+    const result = await validateNextComponentFiles(tempDir, {});
+    assert.ok(result.issues[0].solution, 'solution should be populated from suggestion');
+  });
+
+  test('returns { errors: 0, warnings: 0 } for empty src/ directory', async () => {
+    const result = await validateNextComponentFiles(tempDir, {});
+    assert.equal(result.errors, 0);
+    assert.equal(result.warnings, 0);
+  });
+
+  test('scans multiple files and accumulates issues', async () => {
+    // file 1: useState without use client (error)
+    writeFileSync(
+      join(tempDir, 'src', 'components', 'bad-a.tsx'),
+      `import { useState } from 'react';\nexport function BadA() { const [x] = useState(0); return <div>{x}</div>; }`
+    );
+    // file 2: unnecessary use client (warning)
+    writeFileSync(
+      join(tempDir, 'src', 'components', 'bad-b.tsx'),
+      `'use client';\nexport function BadB() { return <div>Static</div>; }`
+    );
+    const result = await validateNextComponentFiles(tempDir, {});
+    assert.ok(result.errors >= 1, 'should have at least 1 error from bad-a');
+    assert.ok(result.warnings >= 1, 'should have at least 1 warning from bad-b');
+    assert.ok(result.issues.length >= 2, 'should have issues from both files');
+  });
+});
+```
+
+**Step 2: Run tests to confirm they FAIL (module not found)**
+
+```bash
+cd "R:/Polymorphism Tech/repos/morph-spec-framework" && node --test test/validators/nextjs/next-component-files-validator.test.js 2>&1 | head -10
+```
+
+Expected: Error — `validateNextComponentFiles is not exported`
+
+**Step 3: Add `validateNextComponentFiles` to `next-component-validator.js`**
+
+Add after the existing `validateNextComponent` function (after the `toKebabCase` helper):
+
+```js
+// ============================================
+// PROJECT-LEVEL SCANNER
+// ============================================
+
+/**
+ * Validates all Next.js component files in a project directory.
+ * Wraps validateNextComponent for use in validation-runner.js.
+ *
+ * @param {string} projectPath - Root path of the project
+ * @param {Object} options - Validator options
+ * @returns {{ errors: number, warnings: number, issues: Array }}
+ */
+export async function validateNextComponentFiles(projectPath, options = {}) {
+  const { glob } = await import('glob');
+  const { readFileSync } = await import('node:fs');
+  const { join } = await import('node:path');
+
+  const result = { errors: 0, warnings: 0, issues: [] };
+
+  // Find all .tsx and .ts files under src/
+  const srcDir = join(projectPath, 'src');
+  const pattern = `${srcDir.replace(/\\/g, '/')}/**/*.{tsx,ts}`;
+  const files = await glob(pattern, { ignore: ['**/node_modules/**', '**/.next/**'] });
+
+  for (const filePath of files) {
+    let content;
+    try {
+      content = readFileSync(filePath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    // Make path relative for cleaner output
+    const relPath = filePath.replace(projectPath.replace(/\\/g, '/') + '/', '').replace(/\\/g, '/');
+    const fileIssues = validateNextComponent(content, relPath);
+
+    for (const issue of fileIssues) {
+      result.issues.push({
+        level: issue.type,       // 'error' | 'warning' → validation-runner format
+        message: issue.message,
+        file: issue.file,
+        line: issue.line,
+        solution: issue.suggestion,
+      });
+      if (issue.type === 'error') result.errors++;
+      else result.warnings++;
+    }
+  }
+
+  return result;
+}
+```
+
+**Step 4: Export from index.js**
+
+Edit `src/lib/validators/nextjs/index.js` — add:
+```js
+export { validateNextComponent, validateNextComponentFiles } from './next-component-validator.js';
+```
+
+**Step 5: Add case to validation-runner.js**
+
+In `src/lib/validators/validation-runner.js`, inside `runSingleValidator()` switch, add before the `default:` case:
+
+```js
+    case 'nextjs-component': {
+      const { validateNextComponentFiles } = await import('./nextjs/next-component-validator.js');
+      return await validateNextComponentFiles(projectPath, options);
+    }
+```
+
+**Step 6: Fix agents.json**
+
+Find `"nextjs-expert"` entry, change:
+```json
+"validators": ["packages"]
+```
+to:
+```json
+"validators": ["packages", "nextjs-component"]
+```
+
+**Step 7: Validate JSON**
+
+```bash
+cd "R:/Polymorphism Tech/repos/morph-spec-framework" && node -e "JSON.parse(require('fs').readFileSync('framework/agents.json','utf8')); console.log('OK')"
+```
+
+**Step 8: Run the new tests — must all pass**
+
+```bash
+cd "R:/Polymorphism Tech/repos/morph-spec-framework" && node --test test/validators/nextjs/next-component-files-validator.test.js 2>&1
+```
+
+Expected: 6/6 pass
+
+**Step 9: Run full test suite**
+
+```bash
+cd "R:/Polymorphism Tech/repos/morph-spec-framework" && npm test 2>&1 | tail -8
+```
+
+Expected: 0 failures (652+ pass)
+
+**Step 10: Commit**
+
+```bash
+cd "R:/Polymorphism Tech/repos/morph-spec-framework" && git add src/lib/validators/nextjs/ test/validators/nextjs/next-component-files-validator.test.js framework/agents.json src/lib/validators/validation-runner.js && git commit -m "fix(validators): wire nextjs-component validator — add validateNextComponentFiles, register in validation-runner, fix agents.json"
+```
+
+---
+
+### Task 2: Create scan-nextjs.mjs (E2E TDD with real temp dirs)
+
+**Files:**
+- Create: `scripts/scan-nextjs.mjs`
+- Create: `test/scripts/scan-nextjs.test.mjs`
+
+**Step 1: Write failing tests FIRST — real temp dirs, real user cases**
+
+Create `test/scripts/scan-nextjs.test.mjs`:
+
+```js
+import { test, describe, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { execSync } from 'node:child_process';
+
+const SCAN_SCRIPT = join(process.cwd(), 'scripts', 'scan-nextjs.mjs');
+
+/**
+ * Run scan-nextjs.mjs against a temp dir.
+ * Returns { stdout, stderr, exitCode }
+ */
+function runScan(targetDir, extraArgs = '') {
+  try {
+    const stdout = execSync(
+      `node "${SCAN_SCRIPT}" "${targetDir}" ${extraArgs}`,
+      { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+    );
+    return { stdout, stderr: '', exitCode: 0 };
+  } catch (err) {
+    return {
+      stdout: err.stdout || '',
+      stderr: err.stderr || '',
+      exitCode: err.status ?? 1,
+    };
+  }
+}
+
+describe('scan-nextjs.mjs — E2E with real temp directories', () => {
+  let tempDir;
+
+  beforeEach(() => {
+    tempDir = join(tmpdir(), `morph-scan-nextjs-${Date.now()}`);
+    mkdirSync(join(tempDir, 'src', 'components'), { recursive: true });
+    mkdirSync(join(tempDir, 'src', 'features', 'users', 'components'), { recursive: true });
+    mkdirSync(join(tempDir, 'src', 'app'), { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  // =============================================
+  // User case 1: Clean project — developer did everything right
+  // =============================================
+  test('user case: clean project with correctly written components → 0 issues, exit 0', () => {
+    writeFileSync(
+      join(tempDir, 'src', 'features', 'users', 'components', 'user-card.tsx'),
+      `'use client';\nimport { useState } from 'react';\nexport function UserCard({ user }) {\n  const [open, setOpen] = useState(false);\n  return <div onClick={() => setOpen(!open)}>{user.name}</div>;\n}`
+    );
+    writeFileSync(
+      join(tempDir, 'src', 'app', 'page.tsx'),
+      `export default async function Page() {\n  return <div>Home</div>;\n}`
+    );
+    const { stdout, exitCode } = runScan(tempDir);
+    assert.equal(exitCode, 0, `Expected exit 0, got ${exitCode}. stdout: ${stdout}`);
+    assert.ok(stdout.includes('0 issues') || stdout.includes('No issues'), `Expected 0 issues in output: ${stdout}`);
+  });
+
+  // =============================================
+  // User case 2: Developer forgot 'use client' on interactive component
+  // =============================================
+  test('user case: useState without use client → CRITICAL finding, exit 1', () => {
+    writeFileSync(
+      join(tempDir, 'src', 'components', 'counter.tsx'),
+      `import { useState } from 'react';\nexport function Counter() {\n  const [count, setCount] = useState(0);\n  return <button onClick={() => setCount(c => c+1)}>{count}</button>;\n}`
+    );
+    const { stdout, exitCode } = runScan(tempDir);
+    assert.equal(exitCode, 1, 'Should exit 1 when errors found');
+    assert.ok(stdout.toLowerCase().includes('critical') || stdout.toLowerCase().includes('error'), `Expected CRITICAL in output: ${stdout}`);
+    assert.ok(stdout.includes('use client'), `Expected 'use client' mention: ${stdout}`);
+  });
+
+  // =============================================
+  // User case 3: Developer added 'use client' defensively to all components
+  // =============================================
+  test('user case: unnecessary use client on static component → HIGH warning, exit 0', () => {
+    writeFileSync(
+      join(tempDir, 'src', 'components', 'static-badge.tsx'),
+      `'use client';\nexport function StaticBadge({ label }) {\n  return <span className="badge">{label}</span>;\n}`
+    );
+    const { stdout, exitCode } = runScan(tempDir);
+    // Warnings alone should NOT fail (exit 0)
+    assert.equal(exitCode, 0, 'Warnings should not cause exit 1');
+    assert.ok(stdout.toLowerCase().includes('warning') || stdout.toLowerCase().includes('high'), `Expected warning in output: ${stdout}`);
+  });
+
+  // =============================================
+  // User case 4: Developer created component file with PascalCase name
+  // =============================================
+  test('user case: PascalCase filename → HIGH warning in output', () => {
+    writeFileSync(
+      join(tempDir, 'src', 'components', 'UserList.tsx'),
+      `export function UserList() { return <ul/>; }`
+    );
+    const { stdout } = runScan(tempDir);
+    assert.ok(stdout.includes('UserList') || stdout.toLowerCase().includes('kebab'), `Expected file name mention: ${stdout}`);
+  });
+
+  // =============================================
+  // User case 5: Developer used useEffect to fetch data (anti-pattern)
+  // =============================================
+  test('user case: useEffect for data fetching → CRITICAL finding', () => {
+    writeFileSync(
+      join(tempDir, 'src', 'components', 'user-list.tsx'),
+      `'use client';\nimport { useEffect, useState } from 'react';\nexport function UserList() {\n  const [users, setUsers] = useState([]);\n  useEffect(() => {\n    fetch('/api/users').then(r => r.json()).then(setUsers);\n  }, []);\n  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;\n}`
+    );
+    const { stdout } = runScan(tempDir);
+    assert.ok(
+      stdout.toLowerCase().includes('useeffect') || stdout.toLowerCase().includes('fetch') || stdout.toLowerCase().includes('tanstack'),
+      `Expected useEffect/fetch warning in output: ${stdout}`
+    );
+  });
+
+  // =============================================
+  // User case 6: Mixed project — some clean, some violations
+  // =============================================
+  test('user case: mixed project — correct count in summary', () => {
+    // Clean file
+    writeFileSync(
+      join(tempDir, 'src', 'app', 'layout.tsx'),
+      `export default function RootLayout({ children }) { return <html><body>{children}</body></html>; }`
+    );
+    // Error: useState without use client
+    writeFileSync(
+      join(tempDir, 'src', 'components', 'bad-component.tsx'),
+      `import { useState } from 'react';\nexport function Bad() { const [x] = useState(0); return <div>{x}</div>; }`
+    );
+    const { stdout, exitCode } = runScan(tempDir);
+    assert.equal(exitCode, 1);
+    // Should mention file count
+    assert.ok(/\d+ file/.test(stdout), `Expected file count in output: ${stdout}`);
+  });
+
+  // =============================================
+  // User case 7: --json flag for CI integration
+  // =============================================
+  test('--json flag produces valid JSON output', () => {
+    writeFileSync(
+      join(tempDir, 'src', 'components', 'good.tsx'),
+      `'use client';\nimport { useState } from 'react';\nexport function Good() { const [x] = useState(0); return <div onClick={() => {}}>{x}</div>; }`
+    );
+    const { stdout, exitCode } = runScan(tempDir, '--json');
+    assert.equal(exitCode, 0);
+    let parsed;
+    assert.doesNotThrow(() => { parsed = JSON.parse(stdout); }, 'Output must be valid JSON');
+    assert.ok(typeof parsed.files === 'number', 'JSON must have files count');
+    assert.ok(Array.isArray(parsed.issues), 'JSON must have issues array');
+    assert.ok(typeof parsed.errors === 'number', 'JSON must have errors count');
+    assert.ok(typeof parsed.warnings === 'number', 'JSON must have warnings count');
+    assert.ok(typeof parsed.exitCode === 'number', 'JSON must have exitCode');
+  });
+
+  // =============================================
+  // User case 8: Empty src/ directory
+  // =============================================
+  test('empty src/ directory → 0 files scanned, exit 0', () => {
+    const { stdout, exitCode } = runScan(tempDir);
+    assert.equal(exitCode, 0);
+    assert.ok(stdout.includes('0 file') || stdout.includes('No files') || stdout.includes('0 issues'), `Expected 0 files or 0 issues: ${stdout}`);
+  });
+
+  // =============================================
+  // User case 9: Non-existent path → graceful error
+  // =============================================
+  test('non-existent path → exit 2, error message', () => {
+    const { stdout, stderr, exitCode } = runScan(join(tempDir, 'does-not-exist'));
+    assert.equal(exitCode, 2, `Expected exit 2, got ${exitCode}`);
+    const combined = stdout + stderr;
+    assert.ok(combined.toLowerCase().includes('error') || combined.toLowerCase().includes('not found') || combined.toLowerCase().includes('does not exist'), `Expected error message: ${combined}`);
+  });
+});
+```
+
+**Step 2: Run tests to confirm they all FAIL**
+
+```bash
+cd "R:/Polymorphism Tech/repos/morph-spec-framework" && node --test test/scripts/scan-nextjs.test.mjs 2>&1 | head -15
+```
+
+Expected: `Cannot find module` or all fail with script not found.
+
+**Step 3: Implement `scripts/scan-nextjs.mjs`**
+
+Create `scripts/scan-nextjs.mjs`:
+
+```js
+#!/usr/bin/env node
+/**
+ * scan-nextjs.mjs
+ *
+ * CLI scan for Next.js CRITICAL/HIGH violations.
+ * Runs automatically before code-review-nextjs skill for mechanical checks.
+ *
+ * Usage:
+ *   node scripts/scan-nextjs.mjs [path]      # defaults to src/
+ *   node scripts/scan-nextjs.mjs --json      # JSON output for CI
+ *
+ * Exit codes: 0 = clean, 1 = errors found, 2 = scan failed
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { validateNextComponent } from '../src/lib/validators/nextjs/next-component-validator.js';
+
+// ============================================
+// CLI ARGUMENT PARSING
+// ============================================
+
+const args = process.argv.slice(2);
+const jsonMode = args.includes('--json');
+const pathArg = args.find(a => !a.startsWith('--'));
+const targetPath = pathArg ? resolve(pathArg) : resolve('src');
+
+// ============================================
+// ADDITIONAL CHECKS (beyond validateNextComponent)
+// ============================================
+
+/**
+ * Check for useEffect used for data fetching anti-pattern.
+ * @param {string} content
+ * @param {string} filePath
+ * @returns {import('../src/lib/validators/nextjs/next-component-validator.js').ValidationIssue[]}
+ */
+function checkUseEffectFetch(content, filePath) {
+  const issues = [];
+  // Pattern: useEffect containing fetch() or axios() call
+  if (/useEffect\s*\(\s*\(\s*\)\s*=>/.test(content) && /\bfetch\s*\(/.test(content)) {
+    issues.push({
+      type: 'error',
+      message: "useEffect used for data fetching — use Server Components or TanStack Query (useQuery) instead",
+      suggestion: "Replace with a Server Component fetch or TanStack Query useQuery hook",
+      file: filePath,
+    });
+  }
+  return issues;
+}
+
+/**
+ * Check for default exports on non-special files (should use named exports).
+ * @param {string} content
+ * @param {string} filePath
+ * @returns {import('../src/lib/validators/nextjs/next-component-validator.js').ValidationIssue[]}
+ */
+function checkDefaultExport(content, filePath) {
+  const issues = [];
+  const fileName = filePath.split('/').pop() ?? '';
+  const SPECIAL = ['page.tsx', 'layout.tsx', 'loading.tsx', 'error.tsx', 'not-found.tsx'];
+  if (!SPECIAL.includes(fileName) && /^export\s+default\s+/m.test(content) && fileName.endsWith('.tsx')) {
+    issues.push({
+      type: 'warning',
+      message: `Default export in '${fileName}' — prefer named exports for easier refactoring`,
+      suggestion: "Change to: export function ComponentName() {}",
+      file: filePath,
+    });
+  }
+  return issues;
+}
+
+// ============================================
+// FILE WALKER
+// ============================================
+
+/**
+ * Recursively find all .tsx and .ts files in a directory.
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function findTsxFiles(dir) {
+  const { readdirSync, statSync } = await import('node:fs');
+  // Use sync version since we imported at top
+  const results = [];
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.name === 'node_modules' || entry.name === '.next' || entry.name === 'dist') continue;
+    if (entry.isDirectory()) {
+      results.push(...findTsxFiles(fullPath));
+    } else if (entry.name.endsWith('.tsx') || entry.name.endsWith('.ts')) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+// ============================================
+// MAIN
+// ============================================
+
+function main() {
+  // Validate path exists
+  if (!existsSync(targetPath)) {
+    const msg = `Error: Path does not exist: ${targetPath}`;
+    if (jsonMode) {
+      process.stdout.write(JSON.stringify({ error: msg, exitCode: 2 }) + '\n');
+    } else {
+      process.stderr.write(msg + '\n');
+    }
+    process.exit(2);
+  }
+
+  // Find all files
+  let files;
+  try {
+    files = findTsxFiles(targetPath);
+  } catch (err) {
+    const msg = `Error scanning directory: ${err.message}`;
+    if (jsonMode) {
+      process.stdout.write(JSON.stringify({ error: msg, exitCode: 2 }) + '\n');
+    } else {
+      process.stderr.write(msg + '\n');
+    }
+    process.exit(2);
+  }
+
+  // Run validators
+  const allIssues = [];
+  for (const filePath of files) {
+    let content;
+    try {
+      content = readFileSync(filePath, 'utf8');
+    } catch {
+      continue;
+    }
+    const relPath = filePath.replace(targetPath, '').replace(/\\/g, '/').replace(/^\//, '');
+    const issues = [
+      ...validateNextComponent(content, relPath),
+      ...checkUseEffectFetch(content, relPath),
+      ...checkDefaultExport(content, relPath),
+    ];
+    allIssues.push(...issues);
+  }
+
+  const errors = allIssues.filter(i => i.type === 'error');
+  const warnings = allIssues.filter(i => i.type === 'warning');
+
+  // ---- JSON output mode ----
+  if (jsonMode) {
+    process.stdout.write(JSON.stringify({
+      files: files.length,
+      issues: allIssues.map(i => ({ severity: i.type, message: i.message, file: i.file, line: i.line ?? null, suggestion: i.suggestion ?? null })),
+      errors: errors.length,
+      warnings: warnings.length,
+      exitCode: errors.length > 0 ? 1 : 0,
+    }, null, 2) + '\n');
+    process.exit(errors.length > 0 ? 1 : 0);
+  }
+
+  // ---- Human-readable output ----
+  console.log(`\n🔍 Scanning ${targetPath.replace(process.cwd(), '.')} (${files.length} file${files.length !== 1 ? 's' : ''})...\n`);
+
+  if (allIssues.length === 0) {
+    console.log(`✅ No issues found — ${files.length} file${files.length !== 1 ? 's' : ''} scanned\n`);
+    console.log(`Summary: ${files.length} files scanned | 0 issues (0 critical, 0 high, 0 medium)\n`);
+    process.exit(0);
+  }
+
+  if (errors.length > 0) {
+    console.log(`CRITICAL (${errors.length})`);
+    for (const issue of errors) {
+      const loc = issue.line ? `:${issue.line}` : '';
+      console.log(`  ${issue.file}${loc}  — ${issue.message}`);
+      if (issue.suggestion) console.log(`    → ${issue.suggestion}`);
+    }
+    console.log('');
+  }
+
+  if (warnings.length > 0) {
+    console.log(`HIGH/MEDIUM (${warnings.length})`);
+    for (const issue of warnings) {
+      console.log(`  ${issue.file}  — ${issue.message}`);
+    }
+    console.log('');
+  }
+
+  const clean = files.length - new Set(allIssues.map(i => i.file)).size;
+  if (clean > 0) console.log(`✅ No issues found in ${clean} file${clean !== 1 ? 's' : ''}\n`);
+
+  console.log(`Summary: ${files.length} files scanned | ${allIssues.length} issue${allIssues.length !== 1 ? 's' : ''} (${errors.length} critical, ${warnings.length} high/medium)\n`);
+  process.exit(errors.length > 0 ? 1 : 0);
+}
+
+main();
+```
+
+**NOTE FOR IMPLEMENTER:** The `findTsxFiles` function above uses `import` inside a regular function which won't work. Fix it to use the top-level `readdirSync` and `statSync` that are already imported at the top of the file. Replace the body of `findTsxFiles` with a synchronous version using `readdirSync`/`statSync` directly (they were imported at the top with `readFileSync`):
+
+```js
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+```
+
+And `findTsxFiles`:
+```js
+function findTsxFiles(dir) {
+  const results = [];
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (['node_modules', '.next', 'dist'].includes(entry.name)) continue;
+    if (entry.isDirectory()) {
+      results.push(...findTsxFiles(fullPath));
+    } else if (entry.name.endsWith('.tsx') || entry.name.endsWith('.ts')) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+```
+
+**Step 4: Run tests — all 9 should pass**
+
+```bash
+cd "R:/Polymorphism Tech/repos/morph-spec-framework" && node --test test/scripts/scan-nextjs.test.mjs 2>&1
+```
+
+Expected: 9/9 pass
+
+**Step 5: Smoke-test the scan script manually**
+
+```bash
+cd "R:/Polymorphism Tech/repos/morph-spec-framework" && node scripts/scan-nextjs.mjs scripts/ 2>&1
+```
+
+Expected: clean output (scripts/ has no .tsx files so 0 files scanned)
+
+```bash
+node scripts/scan-nextjs.mjs scripts/ --json 2>&1
+```
+
+Expected: valid JSON with `{ "files": 0, "issues": [], "errors": 0, ... }`
+
+**Step 6: Run full test suite**
+
+```bash
+cd "R:/Polymorphism Tech/repos/morph-spec-framework" && npm test 2>&1 | tail -8
+```
+
+Expected: 0 failures
+
+**Step 7: Commit**
+
+```bash
+cd "R:/Polymorphism Tech/repos/morph-spec-framework" && git add scripts/scan-nextjs.mjs test/scripts/scan-nextjs.test.mjs && git commit -m "feat(scripts): add scan-nextjs.mjs — CLI scan for use-client, hooks, kebab-case, useEffect-fetch violations"
+```
+
+---
+
+### Task 3: Create code-review-nextjs skill + reference example
+
+**Files:**
+- Create: `framework/skills/level-0-meta/code-review-nextjs/SKILL.md`
+- Create: `framework/skills/level-0-meta/code-review-nextjs/references/review-example-nextjs.md`
+
+**Note:** No unit tests needed for content files. The skills-installer test suite already validates skill directory structure. We verify installation in Task 4.
+
+**Step 1: Create the directory structure**
+
+```bash
+mkdir -p "R:/Polymorphism Tech/repos/morph-spec-framework/framework/skills/level-0-meta/code-review-nextjs/references"
+```
+
+**Step 2: Create `SKILL.md`**
+
+Create `framework/skills/level-0-meta/code-review-nextjs/SKILL.md`:
+
+```markdown
+---
+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.
+
+---
+
+## 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*
+```
+
+**Step 3: Create `references/review-example-nextjs.md`**
+
+Create `framework/skills/level-0-meta/code-review-nextjs/references/review-example-nextjs.md`:
+
+```markdown
+# Code Review Report — User Management Feature
+
+> Example of a well-structured Next.js code review output. Filled-in reference — not a template.
+
+**Scope:** `src/features/users/` + `src/app/(dashboard)/users/page.tsx`
+**Date:** 2026-02-23
+**Reviewer:** code-review-nextjs skill
+
+---
+
+## Automated Scan Results
+
+```bash
+$ node scripts/scan-nextjs.mjs src/features/users/
+
+CRITICAL (1)
+  features/users/components/UserList.tsx:1  — React hooks used (useState) without 'use client'
+
+HIGH/MEDIUM (2)
+  features/users/components/UserList.tsx  — PascalCase filename (should be user-list.tsx)
+  features/users/components/user-form.tsx — 'use client' directive present but no interactivity detected
+
+Summary: 8 files scanned | 3 issues (1 critical, 2 high/medium)
+```
+
+---
+
+## Findings by Severity
+
+| Severity | Count |
+|----------|-------|
+| CRITICAL | 2 |
+| HIGH | 3 |
+| MEDIUM | 2 |
+| LOW | 1 |
+
+---
+
+### [CRITICAL] Missing 'use client' on interactive component
+
+**File:** `src/features/users/components/UserList.tsx:1`
+
+**Current code:**
+```tsx
+import { useState } from 'react';
+
+export function UserList() {
+  const [selected, setSelected] = useState<string | null>(null);
+  return <div onClick={() => setSelected('test')}>...</div>;
+}
+```
+
+**Suggested fix:**
+```tsx
+'use client';
+
+import { useState } from 'react';
+// ... rest unchanged
+```
+
+**Why:** React hooks (`useState`) require `'use client'`. Without it, Next.js treats this as a Server Component and the `useState` call fails at runtime.
+
+---
+
+### [CRITICAL] useEffect for data fetching
+
+**File:** `src/features/users/components/user-list.tsx:8`
+
+**Current code:**
+```tsx
+'use client';
+import { useEffect, useState } from 'react';
+
+export function UserList() {
+  const [users, setUsers] = useState([]);
+  useEffect(() => {
+    fetch('/api/users').then(r => r.json()).then(setUsers);
+  }, []);
+  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
+}
+```
+
+**Suggested fix:**
+```tsx
+// Option A — Server Component (no 'use client' needed)
+// app/(dashboard)/users/page.tsx
+async function getUsers() {
+  const res = await fetch(`${process.env.API_URL}/api/users`, { next: { revalidate: 30 } });
+  return res.json();
+}
+export default async function UsersPage() {
+  const users = await getUsers();
+  return <UserList initialData={users} />;
+}
+
+// Option B — TanStack Query (when client interactivity needed)
+'use client';
+import { useUsers } from '@/features/users/hooks/use-users';
+export function UserList() {
+  const { data: users = [], isLoading } = useUsers();
+  if (isLoading) return <div>Loading...</div>;
+  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
+}
+```
+
+**Why:** `useEffect` + `useState` for fetching: (1) doubles renders, (2) no caching, (3) no SSR, (4) no error/loading states, (5) can't be cancelled. TanStack Query or Server Components solve all five.
+
+---
+
+### [HIGH] PascalCase file name
+
+**File:** `src/features/users/components/UserList.tsx`
+
+**Suggested fix:** Rename to `user-list.tsx`
+
+**Why:** Linux servers are case-sensitive. `UserList.tsx` and `user-list.tsx` are different files on the server but the same on macOS/Windows, causing import failures in production.
+
+---
+
+### [HIGH] Default export on non-page component
+
+**File:** `src/features/users/components/user-card.tsx:3`
+
+**Current code:**
+```tsx
+export default function UserCard({ user }: { user: User }) {
+```
+
+**Suggested fix:**
+```tsx
+export function UserCard({ user }: { user: User }) {
+```
+
+**Why:** Named exports are refactor-safe — IDEs track renames automatically. Default exports are anonymous in imports (`import X from './user-card'` allows `X` to be anything).
+
+---
+
+### [HIGH] Type defined manually instead of deriving from Zod schema
+
+**File:** `src/features/users/types/user.types.ts:1`
+
+**Current code:**
+```ts
+export type User = {
+  id: string;
+  name: string;
+  email: string;
+  role: 'admin' | 'user';
+};
+```
+
+**Suggested fix:**
+```ts
+// user.schemas.ts — single source of truth
+export const userSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+  role: z.enum(['admin', 'user']),
+});
+
+// user.types.ts — derived, never written manually
+export type User = z.infer<typeof userSchema>;
+```
+
+**Why:** Manually written types drift from API responses. `z.infer<>` ensures the TypeScript type is always in sync with the runtime validation.
+
+---
+
+### [MEDIUM] Deep path import instead of feature index
+
+**File:** `src/app/(dashboard)/users/page.tsx:2`
+
+**Current code:**
+```tsx
+import { UserList } from '@/features/users/components/user-list';
+```
+
+**Suggested fix:**
+```tsx
+import { UserList } from '@/features/users';
+```
+
+**Why:** Deep path imports expose internal structure. When `user-list.tsx` moves or is renamed, every consumer breaks. The feature index is the stable public API.
+
+---
+
+### [MEDIUM] Query key not using factory pattern
+
+**File:** `src/features/users/hooks/use-users.ts:8`
+
+**Current code:**
+```ts
+return useQuery({
+  queryKey: ['users'],
+```
+
+**Suggested fix:**
+```ts
+// query-keys.ts
+export const userKeys = {
+  all: ['users'] as const,
+  lists: () => [...userKeys.all, 'list'] as const,
+};
+
+// use-users.ts
+return useQuery({
+  queryKey: userKeys.lists(),
+```
+
+**Why:** Hardcoded `['users']` cannot be selectively invalidated. `queryClient.invalidateQueries({ queryKey: userKeys.lists() })` correctly invalidates only list queries, not detail queries with the same prefix.
+
+---
+
+### [LOW] Test uses fireEvent instead of userEvent
+
+**File:** `src/features/users/components/user-card.test.tsx:14`
+
+**Current code:**
+```tsx
+fireEvent.click(screen.getByRole('button', { name: /edit/i }));
+```
+
+**Suggested fix:**
+```tsx
+await userEvent.click(screen.getByRole('button', { name: /edit/i }));
+```
+
+**Why:** `fireEvent.click` dispatches a synthetic event. `userEvent.click` simulates the full browser interaction sequence (pointerdown, mousedown, focus, click, etc.) — closer to real user behaviour.
+
+---
+
+## Top Priorities
+
+1. `UserList.tsx:1` — CRITICAL missing `'use client'` (2 min fix)
+2. `user-list.tsx:8` — CRITICAL useEffect fetch → useQuery (15 min)
+3. `UserList.tsx` — HIGH rename to `user-list.tsx` (2 min)
+4. `user-card.tsx:3` — HIGH named export (2 min)
+5. `user.types.ts:1` — HIGH derive from Zod (10 min)
+
+---
+
+## Passed Checks ✅
+
+- `components/ui/` files untouched
+- `zodResolver` correctly wired in `user-form.tsx`
+- `isPending` used (v5 correct — not `isLoading`)
+- `loading.tsx` and `error.tsx` present in `app/(dashboard)/users/`
+- Feature has `index.ts` re-exporting public API
+- Test file co-located with component
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*
+```
+
+**Step 4: Verify files exist**
+
+```bash
+ls "R:/Polymorphism Tech/repos/morph-spec-framework/framework/skills/level-0-meta/code-review-nextjs/"
+```
+
+Expected: `SKILL.md` + `references/` directory
+
+**Step 5: Commit**
+
+```bash
+cd "R:/Polymorphism Tech/repos/morph-spec-framework" && git add framework/skills/level-0-meta/code-review-nextjs/ && git commit -m "feat(skills): add code-review-nextjs skill — 9-category checklist + filled review example"
+```
+
+---
+
+### Task 4: Install skill + final end-to-end verification
+
+**Files:**
+- Modified: `.claude/skills/code-review-nextjs/` (installed by running installSkills)
+- No test changes needed — existing skills-installer tests will cover the new skill
+
+**Step 1: Check if skills-installer test count needs updating**
+
+The existing `test/utils/skills-installer.test.js` likely has a count assertion for level-0-meta skills. Check:
+
+```bash
+grep -n "level-0-meta\|skill.*count\|\.length" "R:/Polymorphism Tech/repos/morph-spec-framework/test/utils/skills-installer.test.js" | head -20
+```
+
+If there's an assertion like `skills.length === N` for level-0-meta, update it to `N+1` since we added `code-review-nextjs`.
+
+**Step 2: Manually install the skill to .claude/skills/**
+
+```bash
+cd "R:/Polymorphism Tech/repos/morph-spec-framework" && node -e "
+import('./src/utils/skills-installer.js').then(m => m.installSkills('.', 'framework')).then(r => console.log('Installed:', r.installed, 'skills'))
+" --input-type=module
+```
+
+**Step 3: Verify skill is installed**
+
+```bash
+ls ".claude/skills/code-review-nextjs/" 2>/dev/null && echo "INSTALLED" || echo "NOT FOUND"
+```
+
+Expected: `INSTALLED`, with `SKILL.md` and `references/` present.
+
+**Step 4: Run full test suite — 0 failures**
+
+```bash
+cd "R:/Polymorphism Tech/repos/morph-spec-framework" && npm test 2>&1 | tail -10
+```
+
+Expected: 0 failures (659+ tests pass)
+
+**Step 5: E2E smoke test — run the full pipeline manually**
+
+```bash
+# Create a realistic temp project with real violations
+node -e "
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const dir = '/tmp/morph-review-e2e-demo';
+mkdirSync(join(dir, 'src/features/users/components'), { recursive: true });
+mkdirSync(join(dir, 'src/app/(dashboard)/users'), { recursive: true });
+
+// Bad: useState without use client
+writeFileSync(join(dir, 'src/features/users/components/UserList.tsx'),
+  \`import { useState } from 'react';
+export function UserList() {
+  const [users, setUsers] = useState([]);
+  return <ul/>;
+}\`);
+
+// Bad: useEffect fetch
+writeFileSync(join(dir, 'src/features/users/components/user-form.tsx'),
+  \`'use client';
+import { useEffect, useState } from 'react';
+export function UserForm() {
+  const [data, setData] = useState(null);
+  useEffect(() => { fetch('/api/users').then(r => r.json()).then(setData); }, []);
+  return <form/>;
+}\`);
+
+// Good: clean server component
+writeFileSync(join(dir, 'src/app/(dashboard)/users/page.tsx'),
+  \`export default async function UsersPage() { return <div>Users</div>; }\`);
+
+console.log('Demo project created at', dir);
+" --input-type=module
+
+node scripts/scan-nextjs.mjs /tmp/morph-review-e2e-demo/src/
+```
+
+Expected output: Shows CRITICAL findings for `UserList.tsx` (useState without use client) and `user-form.tsx` (useEffect fetch), clean pass for `page.tsx`.
+
+**Step 6: Test --json flag**
+
+```bash
+node scripts/scan-nextjs.mjs /tmp/morph-review-e2e-demo/src/ --json | node -e "const d=require('fs').readFileSync('/dev/stdin','utf8'); const j=JSON.parse(d); console.log('files:', j.files, '| errors:', j.errors, '| warnings:', j.warnings, '| exitCode:', j.exitCode)"
+```
+
+Expected: valid JSON with correct counts.
+
+**Step 7: Commit final state**
+
+```bash
+cd "R:/Polymorphism Tech/repos/morph-spec-framework" && git add .claude/skills/code-review-nextjs/ && git commit -m "feat(skills): install code-review-nextjs to .claude/skills/ — available as /code-review-nextjs"
+```
+
+**Step 8: Final git log**
+
+```bash
+cd "R:/Polymorphism Tech/repos/morph-spec-framework" && git log --oneline -6
+```
+
+Expected: 4 clean commits covering all 4 tasks.