@polymorphism-tech/morph-spec 4.8.14 → 4.8.15

package/framework/hooks/claude-code/post-tool-use/validator-feedback.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUse Hook: Validator Feedback
+ *
+ * Event: PostToolUse | Matcher: Bash
+ *
+ * Fires after `morph-spec task done` completes.
+ * Reads validationHistory for the completed task and injects
+ * remediation context when validation failed.
+ *
+ * This closes the Builder-Validator loop:
+ *   task done → runValidation → validationHistory → hook injects context
+ *   → LLM sees remediation prompt before next step → auto-fix attempt
+ *
+ * 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 } from '../../shared/state-reader.js';
+import { injectContext, pass } from '../../shared/hook-response.js';
+
+// Standard IDs referenced in remediation messages
+const STANDARD_REFS = {
+  'di': 'backend/dotnet/core.md#dependency-injection',
+  'async': 'backend/dotnet/async.md#cancellation-token-pattern',
+  'security': 'core/architecture.md#security-patterns',
+  'packages': 'backend/dotnet/program-cs-checklist.md#nuget-packages',
+  'design-system': 'frontend/design-system/naming.md#css-class-conventions',
+  'blazor': 'frontend/blazor/pitfalls.md#dbcontext-in-blazor',
+};
+
+try {
+  if (!stateExists()) pass();
+
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const command = payload?.tool_input?.command || '';
+  if (!command) pass();
+
+  // Match: morph-spec task done <feature> <taskId>
+  const taskDoneMatch = command.match(/morph-spec\s+task\s+done\s+(\S+)\s+(\S+)/);
+  if (!taskDoneMatch) pass();
+
+  const [, featureName, taskId] = taskDoneMatch;
+
+  // Load state and find validationHistory for this task
+  const statePath = join(process.cwd(), '.morph', 'state.json');
+  if (!existsSync(statePath)) pass();
+
+  let state;
+  try {
+    state = JSON.parse(readFileSync(statePath, 'utf8'));
+  } catch {
+    pass();
+  }
+
+  const feature = state?.features?.[featureName];
+  if (!feature) pass();
+
+  const taskHistory = feature.validationHistory?.[taskId];
+  if (!taskHistory) pass();
+
+  // Only act on failed validations (passed = no feedback needed)
+  if (taskHistory.status === 'passed') pass();
+
+  // Build remediation context based on validation issues
+  buildRemediationContext(featureName, taskId, taskHistory);
+} catch {
+  // Fail-open
+  process.exit(0);
+}
+
+/**
+ * Build and inject remediation context for a failed validation.
+ *
+ * @param {string} featureName
+ * @param {string} taskId
+ * @param {Object} taskHistory - validationHistory[taskId]
+ */
+function buildRemediationContext(featureName, taskId, taskHistory) {
+  const attempt = taskHistory.attempt || 1;
+  const validators = taskHistory.validators || {};
+
+  // Collect all issues across all validators
+  const allIssues = [];
+  for (const [validatorName, result] of Object.entries(validators)) {
+    if (result.passed) continue;
+    const issues = result.issues || [];
+    for (const issue of issues) {
+      allIssues.push({ validator: validatorName, ...issue });
+    }
+  }
+
+  if (allIssues.length === 0 && taskHistory.status !== 'blocked') pass();
+
+  const lines = [];
+
+  if (taskHistory.status === 'blocked') {
+    // Max attempts reached — escalation message
+    lines.push(`⛔ ESCALATION REQUIRED — Task ${taskId} in feature '${featureName}'`);
+    lines.push(`   Validation failed ${attempt} times (max attempts reached).`);
+    lines.push(`   Human review required before proceeding.`);
+    lines.push(`   Last failures:`);
+    for (const issue of allIssues.slice(0, 5)) {
+      lines.push(`     • [${issue.validator}] ${issue.message} ${issue.file ? `(${issue.file}${issue.line ? ':' + issue.line : ''})` : ''}`);
+    }
+  } else {
+    // Active remediation — attempt N of 3
+    lines.push(`🔄 REMEDIATION REQUIRED — Task ${taskId} (attempt ${attempt}/3)`);
+    lines.push(`   Validation failed. Fix the following issues and re-run:`);
+    lines.push(`   morph-spec task done ${featureName} ${taskId}`);
+    lines.push(``);
+
+    for (const issue of allIssues) {
+      const refKey = getRefKey(issue.rule || issue.validator);
+      const ref = refKey ? ` — Ref: ${STANDARD_REFS[refKey] || refKey}` : '';
+      const location = issue.file
+        ? ` (${issue.file}${issue.line ? ':' + issue.line : ''})`
+        : '';
+      lines.push(`  • [${issue.validator}] ${issue.message}${location}${ref}`);
+    }
+
+    if (attempt >= 2) {
+      lines.push(``);
+      lines.push(`  ⚠️  If this fails again, it will be escalated (attempt ${attempt + 1} = final).`);
+    }
+  }
+
+  injectContext(lines.join('\n'));
+}
+
+/**
+ * Map a rule/validator name to a STANDARD_REFS key.
+ * @param {string} ruleOrValidator
+ * @returns {string|null}
+ */
+function getRefKey(ruleOrValidator) {
+  if (!ruleOrValidator) return null;
+  const lower = ruleOrValidator.toLowerCase();
+  if (lower.includes('di') || lower.includes('dependency') || lower.includes('injection')) return 'di';
+  if (lower.includes('async') || lower.includes('await') || lower.includes('cancellation')) return 'async';
+  if (lower.includes('security') || lower.includes('sql') || lower.includes('xss')) return 'security';
+  if (lower.includes('package') || lower.includes('nuget')) return 'packages';
+  if (lower.includes('design') || lower.includes('css') || lower.includes('naming')) return 'design-system';
+  if (lower.includes('blazor') || lower.includes('dbcontext')) return 'blazor';
+  return null;
+}

package/framework/hooks/claude-code/pre-tool-use/enforce-phase-writes.js

@@ -30,6 +30,12 @@ import {
 import { block, pass } from '../../shared/hook-response.js';
 
 try {
+  // Amend mode: bypass phase write enforcement for legitimate corrections
+  if (process.env.MORPH_AMEND_PHASE) {
+    console.error(`[morph-spec] AMEND MODE: bypassing phase protection for phase '${process.env.MORPH_AMEND_PHASE}'`);
+    pass();
+  }
+
   if (!stateExists()) pass();
 
   const payload = await readStdin();

package/framework/hooks/claude-code/pre-tool-use/protect-spec-files.js

@@ -24,6 +24,12 @@ import {
 import { block, pass } from '../../shared/hook-response.js';
 
 try {
+  // Amend mode: bypass spec protection for legitimate in-implementation corrections
+  if (process.env.MORPH_AMEND_PHASE) {
+    console.error(`[morph-spec] AMEND MODE: bypassing spec protection for phase '${process.env.MORPH_AMEND_PHASE}'`);
+    pass();
+  }
+
   if (!stateExists()) pass();
 
   const payload = await readStdin();

package/framework/hooks/claude-code/session-start/inject-morph-context.js

@@ -30,6 +30,16 @@ function getSpecMaxChars() {
   }
 }
 
+function getProjectConfig() {
+  try {
+    const configPath = join(process.cwd(), '.morph/config/config.json');
+    if (!existsSync(configPath)) return null;
+    return JSON.parse(readFileSync(configPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
 const SPEC_MAX_CHARS = getSpecMaxChars();
 
 try {
@@ -78,6 +88,23 @@ try {
       lines.push('   para visibilidade do progresso. Ex: TaskCreate("Gerar spec.md"), TaskUpdate(id, "completed")');
     }
 
+    // Trust level visibility — warn when low trust may block approval gates
+    const APPROVAL_GATE_PHASES = new Set(['proposal', 'setup', 'design', 'tasks']);
+    if (APPROVAL_GATE_PHASES.has(phase)) {
+      const config = getProjectConfig();
+      const trustLevel = config?.trust?.level || config?.trustLevel || 'low';
+      const workflow = feature.workflow || config?.workflow;
+      if (trustLevel !== 'high' && trustLevel !== 'maximum') {
+        lines.push('');
+        lines.push(`⚠ Trust level: ${trustLevel} — approval gates require manual approval`);
+        lines.push(`  To auto-approve: npx morph-spec trust set ${name} high`);
+      }
+      if (!workflow && config?.workflowDetection?.confidence === 0) {
+        lines.push('');
+        lines.push('ℹ Workflow not detected (confidence: 0). Set manually in .morph/config/config.json → workflow');
+      }
+    }
+
     // Active feature spec (truncated for context budget)
     const specPath = join(process.cwd(), `.morph/features/${name}/1-design/spec.md`);
     if (existsSync(specPath)) {

package/framework/hooks/claude-code/stop/validate-completion.js

@@ -21,7 +21,7 @@
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import {
-  stateExists, getActiveFeature, getMissingOutputs, derivePhaseForFeature,
+  stateExists, loadState, getActiveFeature, getMissingOutputs, derivePhaseForFeature,
 } from '../../shared/state-reader.js';
 import { injectContext, pass } from '../../shared/hook-response.js';
 
@@ -37,7 +37,22 @@ try {
 
   if (!stateExists()) pass();
 
-  const active = getActiveFeature();
+  // getActiveFeature() only returns in_progress/draft features.
+  // Fall back to the most recently updated feature when all features are 'done'.
+  let active = getActiveFeature();
+  if (!active) {
+    const state = loadState();
+    if (state?.features) {
+      let latestUpdate = '';
+      for (const [name, feature] of Object.entries(state.features)) {
+        const updated = feature.updatedAt || feature.createdAt || '';
+        if (updated >= latestUpdate) {
+          latestUpdate = updated;
+          active = { name, feature };
+        }
+      }
+    }
+  }
   if (!active) pass();
 
   const { name, feature } = active;

package/framework/hooks/claude-code/teammate-idle/teammate-idle.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+/**
+ * TeammateIdle Hook: Validate feature before teammate becomes idle
+ *
+ * Event: TeammateIdle
+ *
+ * When an Agent Team teammate finishes its turn and is about to go idle,
+ * this hook runs `morph-spec validate-feature` to check implementation quality.
+ *
+ * Exit codes:
+ *   0 = validation passed — teammate may become idle
+ *   2 = validation failed — send feedback to teammate to continue working
+ *
+ * Fail-open: exits 0 on any error (never blocks teammate incorrectly).
+ */
+
+import { execSync } from 'child_process';
+import { readStdin } from '../../../shared/stdin-reader.js';
+import { loadState, stateExists, getActiveFeature } from '../../../shared/state-reader.js';
+
+try {
+  // Read hook payload (TeammateIdle provides teammate info)
+  const payload = await readStdin();
+
+  if (!stateExists()) process.exit(0);
+
+  // Try to extract feature name from payload or fall back to active feature
+  let featureName = payload?.feature_name || payload?.featureName;
+
+  if (!featureName) {
+    const active = getActiveFeature();
+    featureName = active?.name;
+  }
+
+  if (!featureName) process.exit(0);
+
+  // Only validate during implement phase
+  const state = loadState();
+  const feature = state?.features?.[featureName];
+  if (!feature) process.exit(0);
+
+  // derive phase — only run validation during implement phase
+  const phase = feature.phase;
+  if (phase && phase !== 'implement') process.exit(0);
+
+  // Run validate-feature with --quiet flag (suppress non-error output)
+  let output = '';
+  let exitCode = 0;
+
+  try {
+    output = execSync(
+      `npx morph-spec validate-feature "${featureName}" --phase implement --quiet`,
+      {
+        cwd: process.cwd(),
+        encoding: 'utf-8',
+        timeout: 30000,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      }
+    );
+  } catch (err) {
+    // Non-zero exit from validate-feature means validation errors
+    exitCode = err.status || 1;
+    output = err.stdout || err.stderr || '';
+  }
+
+  if (exitCode !== 0) {
+    // Exit 2: send feedback to teammate to continue working
+    const feedback = [
+      'MORPH-SPEC validation found issues — please fix before going idle:',
+      '',
+      output.trim() || 'Run `npx morph-spec validate-feature to see details.',
+      '',
+      `Run: npx morph-spec validate-feature ${featureName} --phase implement`,
+    ].join('\n');
+
+    // Claude Code reads additionalContext from stdout for exit code 2
+    process.stdout.write(JSON.stringify({ additionalContext: feedback }) + '\n');
+    process.exit(2);
+  }
+
+  // Exit 0: validation passed, teammate may become idle
+  process.exit(0);
+} catch {
+  // Fail-open: never block a teammate due to hook errors
+  process.exit(0);
+}

package/framework/hooks/claude-code/user-prompt/set-terminal-title.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+/**
+ * UserPromptSubmit Hook: Set Terminal Title
+ *
+ * Event: UserPromptSubmit
+ *
+ * Extracts a concise title from the user's prompt and sets it as the
+ * terminal window title using ANSI escape sequences written to /dev/tty.
+ * Also saves to ~/.claude/terminal_title for shell hook integration.
+ *
+ * Title format: "[first ~40 chars of prompt, truncated at word boundary]"
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readStdin } from '../../shared/stdin-reader.js';
+import { openSync, writeSync, closeSync } from 'fs';
+import { writeFile, mkdir } from 'fs/promises';
+import { homedir } from 'os';
+import { join } from 'path';
+
+try {
+  const payload = await readStdin();
+  if (!payload) process.exit(0);
+
+  const prompt = payload?.prompt || payload?.user_prompt || payload?.content || '';
+  if (!prompt || prompt.length < 3) process.exit(0);
+
+  // Generate title: clean prompt, truncate at word boundary within 40 chars
+  const cleaned = prompt.replace(/[\r\n\t]+/g, ' ').replace(/\s+/g, ' ').trim();
+  const maxLen = 40;
+  let title = cleaned.slice(0, maxLen);
+  if (cleaned.length > maxLen) {
+    const lastSpace = title.lastIndexOf(' ');
+    if (lastSpace > 20) title = title.slice(0, lastSpace);
+  }
+
+  const prefix = process.env.CLAUDE_TITLE_PREFIX ? `${process.env.CLAUDE_TITLE_PREFIX} ` : '';
+  const finalTitle = `${prefix}${title}`;
+
+  // Save to ~/.claude/terminal_title (for shell hook integration)
+  try {
+    const claudeDir = join(homedir(), '.claude');
+    await mkdir(claudeDir, { recursive: true });
+    await writeFile(join(claudeDir, 'terminal_title'), finalTitle, 'utf-8');
+  } catch { /* non-critical */ }
+
+  // Write ANSI escape to /dev/tty (bypasses stdout capture by Claude Code)
+  try {
+    const tty = openSync('/dev/tty', 'w');
+    writeSync(tty, `\x1b]0;${finalTitle}\x07`);
+    closeSync(tty);
+  } catch { /* terminal may not support /dev/tty */ }
+
+} catch { /* fail-open */ }
+
+process.exit(0);

package/framework/hooks/shared/phase-utils.js

@@ -16,7 +16,7 @@ export const PHASE_DIRS = {
   setup: '0-proposal',
   uiux: '2-ui',
   design: '1-design',
-  clarify: '1-design',
+  clarify: '2-clarify',
   tasks: '3-tasks',
   implement: '4-implement',
   sync: '4-implement',

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

@@ -85,6 +85,7 @@ export function derivePhaseForFeature(featureName, projectPath) {
   const phaseMap = [
     ['4-implement', 'implement'],
     ['3-tasks', 'tasks'],
+    ['2-clarify', 'clarify'],
     ['2-ui', 'uiux'],
     ['1-design', 'design'],
     ['0-proposal', 'proposal'],

package/framework/skills/README.md

@@ -17,6 +17,7 @@ Each skill is a directory: `{name}/SKILL.md` + optional `scripts/`, `references/
 | `verification-before-completion` | Gate check before marking any work done |
 | `code-review` | .NET/C# review checklist (naming, arch, async, DI, DTOs) |
 | `morph-replicate` | Convert HTML prototypes to Blazor components |
+| `terminal-title` | Manually override the terminal window title for the current task |
 
 ### level-0-meta extras
 

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

@@ -1,6 +1,8 @@
 ---
 name: 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]"
 ---
 
 # Brainstorming — MORPH-SPEC Integrated

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

@@ -13,6 +13,22 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 > **Ref:** `framework/standards/backend/database/ef-core.md` for DbContext patterns and background ops.
 > **Example:** `references/review-example.md` — filled-in review showing expected finding format and severity levels.
 > **Script:** `scripts/scan-csharp.mjs` — automated scan for CRITICAL/HIGH violations before manual review.
+> **Ref:** `references/review-guidelines.md` — false-positive rubric, confidence scoring, evidence format.
+
+---
+
+## Step 0 — Eligibility Check
+
+```bash
+git diff --name-only main...HEAD -- "*.cs" | wc -l
+```
+
+**Pular revisão se:**
+- 0 arquivos `.cs` alterados → sem código backend para revisar
+- Apenas mudanças em `*.json`, `*.csproj`, `*.md`, arquivos de migration → escopo de infra
+- Já existe `.morph/features/$ARGUMENTS/4-implement/code-review.md` criado hoje → já revisado
+
+Se skip: output `"Skipping code-review: [motivo]"` e parar.
 
 ---
 

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

@@ -0,0 +1,100 @@
+# Review Guidelines — False-Positive Rubric
+
+> Documento de referência compartilhado por todos os review skills.
+> Claude deve ler este documento antes de executar qualquer revisão de código.
+
+---
+
+## Confidence Scoring
+
+Antes de reportar um finding, atribua um confidence score de 0–100:
+
+| Score | Interpretação | Ação |
+|-------|--------------|------|
+| 90–100 | Definitivamente real — reproduzível mecanicamente | Reportar |
+| 75–89 | Provavelmente real — padrão forte de problema | Reportar com justificativa |
+| 50–74 | Incerto — depende de contexto não visível | Só reportar se CRITICAL/HIGH |
+| 25–49 | Provavelmente false positive | Ignorar |
+| 0–24 | Definitivamente false positive | Nunca reportar |
+
+**Threshold: reportar apenas findings com confidence ≥ 75.**
+
+O confidence score não aparece no output — aplique o filtro internamente. Output limpo = só findings que passaram ≥ 75.
+
+---
+
+## Categorias de False Positives (sempre ignorar)
+
+1. **Violações pré-existentes** — código não alterado neste PR/branch. Se está no `git diff`, é relevante. Se não está, é dívida técnica para uma task de refactor separada.
+
+2. **Linter/formatter-catchable** — naming trivial, whitespace, import order. Ferramentas automáticas cobrem isso; não gaste tempo de review manual neles.
+
+3. **Preocupações arquiteturais especulativas** — "pode ser problema se escalar para 1M users", "esta abordagem pode causar N+1 se o dataset crescer". Só reporte se o problema for atual e concreto.
+
+4. **Nitpicks abaixo de LOW** — preferências cosméticas sem impacto em corretude, performance ou manutenibilidade. Se não tem severidade, não reportar.
+
+5. **Build errors** — se o código compila, não é build error. Não reporte problemas que o compilador já rejeitaria.
+
+---
+
+## Formato de Evidência Obrigatório
+
+Todo finding DEVE incluir:
+
+```
+src/Application/Orders/OrderService.cs:42
+```csharp
+catch { }  // ← snippet do código ofensivo (≤ 5 linhas)
+```
+Motivo: viola [EMPTY_CATCH] — exceções silenciadas impossibilitam diagnóstico.
+Fix: adicionar logging mínimo + re-throw, ou tratar o caso explicitamente.
+```
+
+Campos obrigatórios por finding:
+- **File:line** — caminho relativo ao projeto + número da linha
+- **Snippet** — trecho do código ofensivo, ≤ 5 linhas
+- **Motivo** — por que viola o padrão (referência de regra ou checklist item)
+- **Fix** — sugestão concreta e acionável
+
+Findings sem file:line são invalidos e não devem ser reportados.
+
+---
+
+## Escopo: Apenas Código Alterado
+
+Focar exclusivamente em arquivos de:
+
+```bash
+git diff --name-only main...HEAD
+```
+
+Issues pré-existentes = dívida técnica para tasks de refactor dedicadas, **não** para revisões de feature PR.
+
+Se usando `scan-csharp.mjs` ou `scan-nextjs.mjs`, prefira `--diff` para limitar o escopo automaticamente.
+
+---
+
+## Saída Esperada
+
+Após filtrar por confidence ≥ 75 e ignorar false positives, a saída deve ser uma das duas formas:
+
+**Se há findings:**
+```
+## Code Review — [stack]
+
+### CRITICAL
+- `src/Foo/Bar.cs:15` — [EMPTY_CATCH] Empty catch block swallows exceptions.
+  ```csharp
+  catch { }
+  ```
+  Fix: log + re-throw, ou tratar o caso.
+
+### HIGH
+- `src/Foo/OrderService.cs:88` — [MISSING_CANCELLATION_TOKEN] Async method `ProcessOrderAsync` sem CancellationToken.
+  Fix: adicionar `CancellationToken ct = default` como último parâmetro.
+```
+
+**Se sem findings CRITICAL/HIGH:**
+```
+✅ Sem CRITICAL/HIGH em [stack] alterado. [N arquivos revisados]
+```

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

@@ -6,9 +6,11 @@
  * Executed locally by Claude via Bash — output returned to Claude.
  *
  * Usage:
- *   node scan-csharp.mjs [path]           # scan directory or file
- *   node scan-csharp.mjs src/             # scan src/ recursively
- *   node scan-csharp.mjs --summary        # counts only, no details
+ *   node scan-csharp.mjs [path]                  # scan directory or file
+ *   node scan-csharp.mjs src/                    # scan src/ recursively
+ *   node scan-csharp.mjs --summary               # counts only, no details
+ *   node scan-csharp.mjs --diff                  # scan only changed files (git diff main...HEAD)
+ *   node scan-csharp.mjs --diff --base=develop   # use different base branch
  *
  * Checks (ref: framework/standards/core/coding.md):
  *   - UPPER_SNAKE_CASE constants       → should be PascalCase
@@ -20,9 +22,13 @@
 
 import { readdirSync, readFileSync, statSync, existsSync } from 'fs';
 import { join, extname, relative } from 'path';
+import { execSync } from 'child_process';
 
-const targetPath = process.argv[2] ?? '.';
-const summaryOnly = process.argv.includes('--summary');
+const args = process.argv.slice(2);
+const diffMode = args.includes('--diff');
+const summaryOnly = args.includes('--summary');
+const baseBranch = args.find(a => a.startsWith('--base='))?.split('=')[1] ?? 'main';
+const targetPath = args.find(a => !a.startsWith('--')) ?? '.';
 
 const CHECKS = [
   {
@@ -76,7 +82,29 @@ function collectCsFiles(dir) {
   return results;
 }
 
-const files = collectCsFiles(targetPath);
+function getChangedFiles(base) {
+  try {
+    const raw = execSync(`git diff --name-only ${base}...HEAD`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+    return raw.split('\n').map(f => f.trim()).filter(f => f.endsWith('.cs') && existsSync(f));
+  } catch {
+    return null;
+  }
+}
+
+let mode = 'full';
+let files;
+if (diffMode) {
+  const changed = getChangedFiles(baseBranch);
+  if (changed !== null) {
+    files = changed;
+    mode = 'diff';
+  } else {
+    files = collectCsFiles(targetPath);
+  }
+} else {
+  files = collectCsFiles(targetPath);
+}
+
 const findings = [];
 
 for (const file of files) {
@@ -110,6 +138,8 @@ const summary = {
   findings: findings.length,
   bySeverity,
   clean: findings.length === 0,
+  mode,
+  ...(mode === 'diff' && { baseBranch, changedFilesCount: files.length }),
 };
 
 if (summaryOnly) {

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

@@ -17,6 +17,22 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 > **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.
 
 ---