@polymorphism-tech/morph-spec 4.8.12 → 4.8.15

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 {
@@ -71,6 +81,30 @@ try {
       lines.push(`- Last checkpoint: #${lastCp.checkpointNum} (${lastCp.passed ? 'passed' : 'failed'})`);
     }
 
+    // Task tracking guidance for work phases
+    if (['design', 'tasks', 'implement'].includes(phase)) {
+      lines.push('');
+      lines.push('💡 TaskCreate/TaskUpdate: Para sessões com 3+ ações planejadas, crie tasks Claude Code');
+      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/statusline.py

@@ -161,6 +161,12 @@ def get_all_active_features(cwd, entries):
 
         # Filter to features belonging to this session (mentioned in transcript)
         session_names = get_session_feature_names(features, entries)
+
+        # Auto-detect: if only one feature is in_progress, show it regardless of transcript
+        in_progress = [n for n, f in features.items() if f.get('status') == 'in_progress']
+        if len(in_progress) == 1:
+            session_names.add(in_progress[0])
+
         if not session_names:
             return []
 

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;
@@ -120,11 +135,30 @@ try {
     }
   }
 
-  if (warnings.length === 0) pass();
+  // ── MEMORY.md reminder ────────────────────────────────────────────────────
+  const WORK_PHASES = new Set(['design', 'clarify', 'tasks', 'implement']);
+  const memoryLines = [];
+  if (WORK_PHASES.has(currentPhase)) {
+    memoryLines.push('📝 Sessão encerrando. Considere salvar no MEMORY.md:');
+    memoryLines.push('  • Padrões de domínio descobertos (regras, invariants, edge cases)');
+    memoryLines.push('  • Decisões arquiteturais tomadas nesta sessão (e o motivo)');
+    memoryLines.push('  • Erros frequentes desta stack/projeto e como resolvê-los');
+    memoryLines.push('  • Nuances do projeto que diferem do padrão (convenções, libs específicas)');
+    memoryLines.push('  • Bugs encontrados e a causa raiz');
+    memoryLines.push('  Se nada relevante foi descoberto nesta sessão, ignore este lembrete.');
+  }
+
+  if (warnings.length === 0 && memoryLines.length === 0) pass();
+
+  const allLines = [...warnings];
+  if (memoryLines.length > 0) {
+    if (allLines.length > 0) allLines.push('');
+    allLines.push(...memoryLines);
+  }
 
   const message = [
     'MORPH-SPEC:',
-    ...warnings.map(w => `  ${w}`),
+    ...allLines.map(w => `  ${w}`),
     '',
     `Status: morph-spec status ${name}`,
   ].join('\n');

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',
@@ -29,6 +29,7 @@ export const OUTPUT_PHASE_MAP = {
   spec: 'design',
   clarifications: 'clarify',
   contracts: 'design',
+  contractsVsa: 'design',
   tasks: 'tasks',
   uiDesignSystem: 'uiux',
   uiMockups: 'uiux',
@@ -45,6 +46,7 @@ export const FILENAME_TO_OUTPUT = {
   'spec.md': 'spec',
   'clarifications.md': 'clarifications',
   'contracts.cs': 'contracts',
+  'contracts-vsa.cs': 'contractsVsa',
   'tasks.md': 'tasks',
   'design-system.md': 'uiDesignSystem',
   'mockups.md': 'uiMockups',
@@ -59,6 +61,7 @@ export const PROTECTED_SPEC_FILES = {
   'schema-analysis.md': 'design',
   'spec.md': 'design',
   'contracts.cs': 'design',
+  'contracts-vsa.cs': 'design',
   'tasks.md': 'tasks',
   'design-system.md': 'uiux',
   'mockups.md': 'uiux',

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