@polymorphism-tech/morph-spec 9.2.0 → 9.4.0

package/framework/evals/review-checklist.md

@@ -34,7 +34,7 @@ diferente") é nota; nota não bloqueia e não pede rodada nova. Na dúvida, sem
 | `teste` | verificador | teste vermelho; teste que não morde a regra que diz proteger | saída do verify, mutante sobrevivente, assert que passa pelo motivo errado |
 | `regressao` | revisor | comportamento que funcionava e quebrou | consumidor afetado + o caminho que quebra |
 | `escopo` | revisor | o diff faz o que nenhuma fatia pediu, ou deixa de fazer o que o contrato pede | arquivo/trecho fora das fatias, ou o item do contrato ausente |
-| `arquitetura` | revisor | padrão ou abstração nova contra o stack e os standards | o trecho e o standard que ele contraria |
+| `arquitetura` | revisor | padrão ou abstração nova contra o stack e os standards; item da lista fechada de `architecture-engineering-lens#review-blockers` que o DIFF introduziu (o que já existia é nota) | o trecho e o standard que ele contraria |
 | `performance` | revisor | custo que o volume real torna visível | a consulta/lista e o volume que a derruba |
 | `seguranca` | segurança | authz, segredo, injeção, PII, custo sem teto, migration destrutiva | o caminho de exploração |
 
@@ -129,6 +129,9 @@ Read-only, sobre o commit do dispatch: `git diff {base}..{sha}`, `git show {sha}
 5. **Performance só com evidência**: lista sem paginação no servidor sobre volume real, N+1 visível.
 6. **Chamada a LLM**: dá para reconstruir o que foi ao provedor e o que ele respondeu neste turno?
    Não → nota.
+7. **Tela no diff**: cor ou espaçamento literal fora do CSS de tokens, mais de uma ação primária,
+   erro sem próxima ação, conteúdo gerado por IA sem marca, foco invisível → nota. Bloqueia só pelo
+   contrato de tela do verificador.
 
 ## Segurança (`4-review/security.md`)
 

package/framework/hooks/README.md

@@ -25,6 +25,7 @@ typechecks or runs tests: that is `morph-spec verify`.
 | **PreToolUse** (Write\|Edit) | protect-spec-files.js | Block | Blocks edits to `plan.md` (and the uiux artifacts) after their gate is approved; an append-only `## Errata` block at the end of `plan.md` passes |
 | **PreToolUse** (Write\|Edit) | enforce-phase-writes.js | Block | Ensures writes go to current phase directory |
 | **PreToolUse** (Bash) | pre-bash-denylist.js | Block | Blocks `rm -rf .morph/` and direct state edits |
+| **PreToolUse** (Bash) | conventional-commit.js | Block | Blocks a `git commit -m` whose subject is not Conventional Commits (`<type>(<scope>): <subject>`); a `$(…)`/heredoc message, `-F` and git-generated `Merge`/`Revert` pass |
 | **PreToolUse** (Bash) | block-destructive-worktree-removal.js | Block | Blocks `git worktree remove` / `rm -rf` / `Remove-Item -Recurse` on a directory holding reparse points (the infra junctions a raw removal would FOLLOW out, emptying the root's `.claude/`); names `morph-spec worktree remove` |
 | **PreToolUse** (Bash) | block-raw-worktree-add.js | Block | Blocks raw `git worktree add` (a tree with no junctions → no hooks, no port block, no identity, outside `worktrees/`); names `morph-spec worktree setup <feature>` / `worktree provision <name> --base <ref>`. `list`/`prune`/`remove`/`lock`/`move`/`repair` pass |
 | **PreToolUse** (Bash) | warn-bash-source-write.js | Warn | Heredoc/redirect/`tee` into project source (`isProjectSource`): context naming the file, the command still runs — Write/Edit is what phase, protected-file and comment guards see |

package/framework/hooks/claude-code/core/block-raw-worktree-add.js

@@ -3,23 +3,10 @@ import { blockResult, runStandalone } from '../../shared/hook-response.js';
 import { stateExists } from '../../shared/state-reader.js';
 // From shared/, never from the sibling hook: importing a hook module fires its
 // standalone tail (stdin read + exit) inside THIS process.
-import { tokenize } from '../../shared/command-tokens.js';
-
-const GIT_GLOBAL_WITH_VALUE = new Set(['-c', '-C', '--git-dir', '--work-tree', '--namespace', '--exec-path', '--config-env']);
+import { gitInvocations } from '../../shared/command-tokens.js';
 
 export function isRawWorktreeAdd(command) {
-  const tokens = tokenize(command);
-  const lower = tokens.map((t) => t.toLowerCase());
-  for (let i = 0; i < lower.length; i++) {
-    if (lower[i] !== 'git' && !/(^|[\\/])git(\.exe)?$/.test(lower[i])) continue;
-    let j = i + 1;
-    while (j < lower.length && lower[j].startsWith('-')) {
-      if (GIT_GLOBAL_WITH_VALUE.has(tokens[j])) j += 2;
-      else j += 1;
-    }
-    if (lower[j] === 'worktree' && lower[j + 1] === 'add') return true;
-  }
-  return false;
+  return gitInvocations(command).some(({ sub, args }) => sub === 'worktree' && args[0]?.toLowerCase() === 'add');
 }
 
 export async function run(payload) {

package/framework/hooks/claude-code/core/conventional-commit.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import { blockResult, runStandalone } from '../../shared/hook-response.js';
+import { stateExists } from '../../shared/state-reader.js';
+import { gitInvocations } from '../../shared/command-tokens.js';
+
+const CONVENTIONAL = /^(feat|fix|refactor|test|chore|docs|perf|ci|build|style|revert)(\([^)]+\))?!?: \S/;
+const GIT_GENERATED = /^(Merge|Revert) /;
+const MESSAGE_FLAG = /^-[a-zA-Z]*m$/;
+
+function subjectOf(args) {
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--message' || MESSAGE_FLAG.test(arg)) return args[i + 1] ?? null;
+    if (arg.startsWith('--message=')) return arg.slice('--message='.length);
+    if (/^-m./.test(arg)) return arg.slice(2);
+  }
+  return null;
+}
+
+// `$(…)` and heredocs are only known after the shell expands them.
+function isJudgeable(subject) {
+  return subject !== null && !subject.includes('$(') && !subject.includes('<<') && !subject.includes('`');
+}
+
+export function nonConventionalSubject(command) {
+  for (const { sub, args } of gitInvocations(command)) {
+    if (sub !== 'commit') continue;
+    const subject = subjectOf(args);
+    if (!isJudgeable(subject)) continue;
+    const firstLine = subject.split('\n')[0].trim();
+    if (!CONVENTIONAL.test(firstLine) && !GIT_GENERATED.test(firstLine)) return firstLine;
+  }
+  return null;
+}
+
+export async function run(payload) {
+  try {
+    if (!stateExists()) return null;
+
+    const command = payload?.tool_input?.command || '';
+    if (!command.includes('commit')) return null;
+    const subject = nonConventionalSubject(command);
+    if (subject === null) return null;
+
+    return blockResult(
+      `Bloqueado: o assunto do commit não segue Conventional Commits: "${subject}".\n\n` +
+      'Formato: `<tipo>(<escopo>): <assunto>` — tipo em feat, fix, refactor, test, chore ' +
+      '(também docs, perf, ci, build, style, revert); `!` antes de `:` marca breaking change.\n' +
+      'Exemplos: `feat(orders): aceita cupom no checkout`, `fix: trata pedido sem itens`, ' +
+      '`chore(F2): wip handler de pagamento`.'
+    );
+  } catch {
+    return null;
+  }
+}
+
+await runStandalone(run);

package/framework/hooks/claude-code/core/worktree-context.js

@@ -10,6 +10,7 @@ import {
   getPendingGates,
 } from '../../shared/state-reader.js';
 import { sliceProgress } from '../../shared/slice-progress.js';
+import { collectNextSignals, decideNext, formatNext } from '../../shared/next-step.js';
 import { contextResult, runStandalone } from '../../shared/hook-response.js';
 import { acquireClaim, foreignClaim, claimAge } from '../../shared/claim-registry.js';
 import { rotateActivityLogIfLarge } from '../../shared/activity-logger.js';
@@ -133,11 +134,31 @@ function buildHandoffLine(dir, feature) {
   }
 }
 
+// No git here, so verify staleness is unknown: an escalation the tree already moved past, or the
+// root skeleton of a feature living in a worktree, would be an order read from stale facts.
+function buildNextLine(dir, feature) {
+  try {
+    const signals = collectNextSignals(feature, dir);
+    if (!signals) return null;
+    if (signals.worktreePath && !samePath(resolve(signals.worktreePath), resolve(dir))) {
+      return `▶ ${feature} vive no worktree ${signals.worktreePath}: abra a sessão lá (aqui é o esqueleto de nascimento).`;
+    }
+    const next = decideNext(signals);
+    if (next.action === 'escalate') return `▶ verify vermelho de novo: rode \`morph-spec next ${feature}\` antes de agir.`;
+    return `▶ ${formatNext(next)} (confirme com \`morph-spec next ${feature}\` depois de mudar a árvore)`;
+  } catch {
+    return null;
+  }
+}
+
 function buildWorktreeContext(dir, feature) {
   const phase = getFeaturePhase(feature, dir);
   let text = `🌳 Worktree desta feature: ${feature} (branch morph/${feature}, fase ${phase}). ` +
     `Trabalhe apenas nesta feature nesta sessão; o estado vive no .morph/ deste worktree.`;
 
+  const nextLine = buildNextLine(dir, feature);
+  if (nextLine) text += `\n${nextLine}`;
+
   const envLine = buildEnvLine(dir);
   if (envLine) text += `\n${envLine}`;
 
@@ -173,6 +194,8 @@ function buildActiveFeatureSummary(dir) {
   if (pending.length) {
     text += ` · gates pendentes: ${pending.join(', ')}`;
   }
+  const nextLine = buildNextLine(dir, active.name);
+  if (nextLine) text += `\n${nextLine}`;
   return text;
 }
 

package/framework/hooks/claude-code/statusline.py

@@ -390,13 +390,14 @@ def derive_phase(feature_dir, gates):
 
 
 PARTIAL_MARKER = re.compile(r'^[\s#>*_]*PARCIAL\b')
+BLOCKED_MARKER = re.compile(r'^[\s#>*_]*BLOQUEADO\b')
 
 
 def count_slices(feature_dir):
     """(done, total) of the slices in 2-plan/checks.json.
 
     Same rule as framework/hooks/shared/slice-progress.js: a slice is done when
-    3-implement/reports/{id}.md exists and its first line is not PARCIAL.
+    3-implement/reports/{id}.md exists and its first line is neither PARCIAL nor BLOQUEADO.
     """
     try:
         slices = json.loads((feature_dir / '2-plan' / 'checks.json').read_text(encoding='utf-8')).get('slices')
@@ -412,7 +413,7 @@ def count_slices(feature_dir):
         except Exception:
             continue
         first = next((line for line in text.splitlines() if line.strip()), '')
-        if not PARTIAL_MARKER.match(first):
+        if not PARTIAL_MARKER.match(first) and not BLOCKED_MARKER.match(first):
             done += 1
     return done, len(ids)
 

package/framework/hooks/shared/command-tokens.js

@@ -108,6 +108,23 @@ function simpleCommands(head) {
   return commands.filter((c) => c.length > 0);
 }
 
+const GIT_EXECUTABLE = /(^|[\\/])git(\.exe)?$/i;
+const GIT_GLOBAL_WITH_VALUE = new Set(['-c', '-C', '--git-dir', '--work-tree', '--namespace', '--exec-path', '--config-env']);
+
+/** Each `git <sub> …` the command runs, global options skipped, one `{ sub, args }` per simple command. */
+export function gitInvocations(command) {
+  const invocations = [];
+  for (const tokens of simpleCommands(command)) {
+    const texts = tokens.map((t) => t.text);
+    const at = texts.findIndex((t) => GIT_EXECUTABLE.test(t));
+    if (at < 0) continue;
+    let j = at + 1;
+    while (j < texts.length && texts[j].startsWith('-')) j += GIT_GLOBAL_WITH_VALUE.has(texts[j]) ? 2 : 1;
+    if (j < texts.length) invocations.push({ sub: texts[j].toLowerCase(), args: texts.slice(j + 1) });
+  }
+  return invocations;
+}
+
 function positionals(args, takesValue) {
   const out = [];
   const values = [];

package/framework/hooks/shared/gate-event.js

@@ -0,0 +1,18 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { appendTelemetryEvent } from './telemetry-logger.js';
+
+export const GATE_EVENT = 'Gate';
+export const GATE_STEPS = ['decision', 'approve', 'unapprove'];
+
+/**
+ * The trail `cost --metrics` turns into "what did the human do with each pause":
+ * `gateDecisions` keeps only the latest decision, so the history lives here.
+ */
+export function recordGateEvent(projectPath, { feature, gate, step, pause, signal, source, approvedBy }) {
+  if (!existsSync(join(projectPath || process.cwd(), '.morph'))) return;
+  const event = { event: GATE_EVENT, feature, gate, step };
+  if (step === 'decision') Object.assign(event, { pause: pause === true, signal: signal ?? null, source: source ?? null });
+  else event.approvedBy = approvedBy ?? null;
+  appendTelemetryEvent(event, projectPath);
+}

package/framework/hooks/shared/next-step.js

@@ -0,0 +1,107 @@
+// The single rule of "what the session does next". `decideNext` is pure: collectors feed facts.
+// Hooks and the CLI share it so the SessionStart pre-fetch and `morph-spec next` never disagree.
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { derivePhaseForFeature } from './state-reader.js';
+import { sliceProgress, readySlices } from './slice-progress.js';
+
+export const FIX_ATTEMPTS = 3;
+
+const step = (action, command, reason, extra = {}) => ({ action, command, reason, ...extra });
+
+/**
+ * @param {{ feature: string, phase: string, slices: object|null, gates: object,
+ *   verification: { status?: string }|null, verificationStale?: boolean, failStreak?: number }} s
+ * `verificationStale` undefined = unknown (the hook has no git): read as fresh.
+ */
+export function decideNext(s) {
+  const f = s.feature;
+  const approved = (g) => s.gates?.[g]?.approved === true;
+  // The hotfix pipeline (scout, human approval, ship) lives in its own skill, end to end.
+  const skill = (name) => (s.workType === 'hotfix' ? `/morph-hotfix ${f}` : `/${name} ${f}`);
+
+  switch (s.phase) {
+    case 'plan':
+      return s.slices
+        ? step('gate', `morph-spec gate-check ${f} plan`, 'plano extraído: o gate do plano decide a pausa')
+        : step('plan', `/morph-plan ${f}`, 'sem checks.json: escreva o plan.md e rode plan-check até zero erro');
+
+    case 'uiux':
+      return step('design', `morph-spec gate-check ${f} uiux`, 'complete 1-design/ (morph-uiux) e passe o gate de uiux');
+
+    case 'implement': {
+      if (!s.slices) return step('plan', skill('morph-plan'), 'sem checks.json: plan.md curto (uma fatia) e plan-check até zero erro');
+      if (s.slices.done < s.slices.total) {
+        const ready = readySlices(s.slices);
+        if (!ready.length) {
+          const waiting = s.slices.slices.filter((sl) => sl.status === 'bloqueado').map((sl) => sl.id);
+          if (waiting.length) {
+            return step('decide', 'AskUserQuestion (decisão da fatia)',
+              'relatório BLOQUEADO: decida pelo plano/ADR ou pergunte, e retome o MESMO agente com a resposta — nunca re-despache',
+              { slices: waiting });
+          }
+          return step('blocked', `morph-spec report-check ${f}`, 'fatias pendentes sem dependência satisfeita');
+        }
+        const partial = ready.filter((sl) => sl.status === 'parcial').map((sl) => sl.id);
+        return step('dispatch', skill('morph-apply'),
+          partial.length ? `retome ${partial.join(', ')} (PARCIAL) e despache as prontas` : 'despache as fatias prontas',
+          { slices: ready.map((sl) => sl.id) });
+      }
+      const v = s.verification;
+      if (!v?.status || s.verificationStale === true) {
+        return step('verify', `morph-spec verify ${f}`, v?.status ? 'a árvore andou desde o último verify' : 'todas as fatias relatadas, sem verify');
+      }
+      if (v.status === 'fail') {
+        const streak = s.failStreak ?? 0;
+        if (streak > 0 && streak % FIX_ATTEMPTS === 0) {
+          return step('escalate', 'AskUserQuestion (aceitar/continuar/parar)',
+            `${streak} verifies vermelhos seguidos, nunca uma tentativa a mais por conta própria. `
+            + `aceitar → ${skill('morph-review')} (o verify vermelho pausa o gate: o humano assina lá); `
+            + 'continuar → corrija e rode o verify de novo; parar → encerre aqui. Segue `escalate` até a árvore andar');
+        }
+        return step('fix', `morph-spec verify ${f}`,
+          `corrija pelo feedback do verify e rode de novo (${FIX_ATTEMPTS - (streak % FIX_ATTEMPTS)} tentativa(s) antes de perguntar)`);
+      }
+      return step('review', skill('morph-review'), 'verify verde: Gate 3');
+    }
+
+    case 'review':
+      return approved('review')
+        ? step('finish', `morph-spec finish ${f} --pr|--merge`, 'Gate 3 aprovado: arquiva e integra num passo')
+        : step('review', skill('morph-review'), 'relatórios do Gate 3 e gate-check review');
+
+    default:
+      return step('status', `morph-spec status ${f}`, `fase desconhecida: ${s.phase ?? '—'}`);
+  }
+}
+
+export function formatNext(n) {
+  const slices = n.slices?.length ? ` [${n.slices.join(', ')}]` : '';
+  return `próximo: ${n.action}${slices} → ${n.command} — ${n.reason}`;
+}
+
+/** Facts readable from `hooks/shared`; the CLI adds `verificationStale` (git) on top. Null without feature.json. */
+export function collectNextSignals(featureName, cwd) {
+  const featureDir = join(cwd, '.morph', 'features', featureName);
+  let feature;
+  try {
+    const path = join(featureDir, 'feature.json');
+    if (!existsSync(path)) return null;
+    feature = JSON.parse(readFileSync(path, 'utf8').replace(/^/, ''));
+  } catch {
+    return null;
+  }
+  let phase = 'plan';
+  try { phase = derivePhaseForFeature(featureName, cwd) || 'plan'; } catch {}
+  return {
+    feature: featureName,
+    workType: feature.workType ?? 'feature',
+    worktreePath: feature.worktree?.path ?? null,
+    phase,
+    slices: sliceProgress(featureDir),
+    gates: feature.approvals || feature.approvalGates || {},
+    verification: feature.verification ?? null,
+    failStreak: feature.verifications?.feature?.failStreak ?? 0,
+  };
+}

package/framework/hooks/shared/slice-progress.js

@@ -4,7 +4,10 @@ import { join } from 'path';
 /** `PARCIAL` on the report's first non-blank line, tolerating heading/bold/quote typography. */
 export const PARTIAL_MARKER = /^[\s#>*_]*PARCIAL\b/;
 
-export const SLICE_STATUSES = ['pendente', 'parcial', 'feito'];
+/** `BLOQUEADO`: the slice waits on a decision only the human can make; re-dispatching it repeats the question. */
+export const BLOCKED_MARKER = /^[\s#>*_]*BLOQUEADO\b/;
+
+export const SLICE_STATUSES = ['pendente', 'parcial', 'bloqueado', 'feito'];
 
 export function checksPath(featureDir) {
   return join(featureDir, '2-plan', 'checks.json');
@@ -17,10 +20,11 @@ export function sliceReportPath(featureDir, sliceId) {
 export function sliceStatusFromReport(text) {
   if (text == null) return 'pendente';
   const first = String(text).split(/\r?\n/).find((l) => l.trim() !== '') ?? '';
+  if (BLOCKED_MARKER.test(first)) return 'bloqueado';
   return PARTIAL_MARKER.test(first) ? 'parcial' : 'feito';
 }
 
-/** @returns {{ total, done, partial, pending, slices } | null} null when the checks text is unreadable */
+/** @returns {{ total, done, partial, blocked, pending, slices } | null} null when the checks text is unreadable */
 export function sliceProgressFrom(checksText, readReport) {
   let slices;
   try {
@@ -39,7 +43,14 @@ export function sliceProgressFrom(checksText, readReport) {
       status: sliceStatusFromReport(readReport(s.id)),
     }));
   const count = (status) => out.filter((s) => s.status === status).length;
-  return { total: out.length, done: count('feito'), partial: count('parcial'), pending: count('pendente'), slices: out };
+  return {
+    total: out.length,
+    done: count('feito'),
+    partial: count('parcial'),
+    blocked: count('bloqueado'),
+    pending: count('pendente'),
+    slices: out,
+  };
 }
 
 function readOrNull(path) {
@@ -57,7 +68,7 @@ export function sliceProgress(featureDir) {
 export function readySlices(progress) {
   if (!progress) return [];
   const done = new Set(progress.slices.filter((s) => s.status === 'feito').map((s) => s.id));
-  return progress.slices.filter((s) => s.status !== 'feito' && s.depends.every((d) => done.has(d)));
+  return progress.slices.filter((s) => s.status !== 'feito' && s.status !== 'bloqueado' && s.depends.every((d) => done.has(d)));
 }
 
 // Loose on purpose: a false "complete" costs a read, a false "incomplete"
@@ -94,6 +105,8 @@ export function inspectReport(path, { covers = [] } = {}) {
   const firstLine = body.split('\n').find((l) => l.trim() !== '') ?? '';
   const partial = PARTIAL_MARKER.test(firstLine);
   if (partial) missing.push('partial');
+  const blocked = BLOCKED_MARKER.test(firstLine);
+  if (blocked) missing.push('blocked');
 
-  return { exists: true, complete: missing.length === 0, missing, partial };
+  return { exists: true, complete: missing.length === 0, missing, partial, blocked };
 }

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

@@ -4,6 +4,7 @@
 import { readFileSync, writeFileSync, renameSync, unlinkSync, existsSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';
 import { clearStateCache } from './state-reader.js';
+import { recordGateEvent } from './gate-event.js';
 
 const STATE_FILE = '.morph/state.json';
 const STATE_VERSION = '5.0.0';
@@ -81,10 +82,14 @@ export function setGateApproved(featureName, gate, meta = {}, projectPath) {
       ...(meta.selfAssessed ? { selfAssessed: true } : {}),
     };
     feature.updatedAt = now;
-    return persistFeature(featureName, feature, projectPath);
+    if (!persistFeature(featureName, feature, projectPath)) return false;
   } catch {
     return false;
   }
+  try {
+    recordGateEvent(projectPath, { feature: featureName, gate, step: 'approve', approvedBy: meta.approvedBy || 'manual' });
+  } catch {}
+  return true;
 }
 
 // Stamps identity so a feature born implicitly by a hook is never an anonymous

package/framework/mcp/registry.json

@@ -277,9 +277,39 @@
         "warnings": ["OAuth against your Neon account on first use. The server can delete branches and projects: keep destructive calls behind a human."],
         "setupGuide": "Run: claude mcp add --transport http neon https://mcp.neon.tech/mcp"
       }
+    },
+    "microsoft-learn": {
+      "phases": ["plan", "implement"],
+      "tools": ["microsoft_docs_search", "microsoft_docs_fetch", "microsoft_code_sample_search"],
+      "serverNames": ["microsoft-learn", "plugin_microsoft-docs_microsoft-learn"],
+      "detection": "mcpServers includes microsoft-learn or enabledPlugins includes microsoft-docs",
+      "fallback": "context7, then WebFetch on learn.microsoft.com",
+      "usage": "Official, current .NET 10 / ASP.NET Core / EF Core / Microsoft Agent Framework docs and code samples: search first, fetch the page when the excerpt is cut. Use it for any API the model may know from an older version",
+      "healthCheck": {
+        "toolPattern": "microsoft-learn",
+        "testCall": "Call microsoft_docs_search with query 'EF Core 10 what is new'",
+        "testParams": {
+          "query": "EF Core 10 what is new"
+        },
+        "successIndicator": "Returns Microsoft Learn excerpts with contentUrl",
+        "failureHint": "Microsoft Learn MCP not responding. Re-add it: claude mcp add --transport http microsoft-learn https://learn.microsoft.com/api/mcp"
+      },
+      "install": {
+        "autoInstall": false,
+        "transport": "http",
+        "config": {
+          "type": "http",
+          "url": "https://learn.microsoft.com/api/mcp"
+        },
+        "credentials": [],
+        "prerequisites": [],
+        "stackRelevance": ["dotnet"],
+        "warnings": [],
+        "setupGuide": "Run: claude mcp add --transport http microsoft-learn https://learn.microsoft.com/api/mcp"
+      }
     }
   },
-  "_phaseMatrixNote": "Keys must be the v5 phases from framework/phases.json. The v4 keys 'design' and 'tasks' both collapsed into 'plan'; 'review' was absent entirely, so a project in review resolved to undefined. Stack-scoped MCPs (asaas, neon) stay out of this matrix on purpose — only universal ones are listed.",
+  "_phaseMatrixNote": "Keys must be the v5 phases from framework/phases.json. The v4 keys 'design' and 'tasks' both collapsed into 'plan'; 'review' was absent entirely, so a project in review resolved to undefined. Stack-scoped MCPs (asaas, neon, microsoft-learn) stay out of this matrix on purpose — only universal ones are listed.",
   "phaseMatrix": {
     "plan": ["context7", "graphify"],
     "uiux": ["playwright", "context7", "stitch", "morph-assets"],

package/framework/rules/csharp-standards.md

@@ -8,13 +8,15 @@ stacks:
 
 # C# and .NET VSA Standards
 
-- **architecture-vertical-slice-vertical-slice** (`architecture/vertical-slice/vertical-slice.md`) — Uma slice por operação em `Features/{Entity}Feature/{Verb}{Entity}/`: Request/Response `sealed record`, Handler, Validator e Endpoint `IApiEndpoint` `internal sealed`. Decorators Scrutor: Logging → Validation → Handler. PROIBIDO: MediatR/`IRequest`, AggregateRoot, DomainEvent, CQRS formal, camada Application Service, DTO compartilhado entre features, `IRepository<T>`/`IUnitOfWork`.
-- **backend-dotnet-vsa-handler-patterns** (`backend/dotnet/vsa-handler-patterns.md`) — Handler `sealed class` com primary constructor implementando `IHandler<TRequest, TResponse>` (não MediatR): injeta `ApplicationDbContext` direto, usa `Guid.CreateVersion7()` (nunca `Guid.NewGuid()`), passa `CancellationToken` em tudo e devolve `Result<T>`. Erros em `{Feature}Errors.cs`. SQL cru ou store dedicado só com justificativa em `plan.md` (`## Decisões`).
+- **architecture-vertical-slice-vertical-slice** (`architecture/vertical-slice/vertical-slice.md`) — Uma slice por operação em `Features/{Entity}Feature/{Verb}{Entity}/`: Request/Response `record`, Handler, Validator e Endpoint `IApiEndpoint`. Decorators Scrutor: Logging → Validation → Handler. PROIBIDO: MediatR/`IRequest`, AggregateRoot, DomainEvent, CQRS formal, camada Application Service, DTO compartilhado entre features, `IRepository<T>`/`IUnitOfWork`.
+- **backend-dotnet-vsa-handler-patterns** (`backend/dotnet/vsa-handler-patterns.md`) — Handler implementando `IHandler<TRequest, TResponse>` (não MediatR): injeta `ApplicationDbContext` direto e devolve `Result<T>`. Erros em `{Feature}Errors.cs`. SQL cru ou store dedicado só com justificativa em `plan.md` (`## Decisões`).
 - **backend-dotnet-result-pattern** (`backend/dotnet/result-pattern.md`) — Falha esperada é `Result`/`Result<T>`, nunca exceção. Endpoint: `result.Match(value => Results.Ok(value), error => error.ToHttpResult())`; nunca leia `.Value` fora do `Match`. Status pelo `ErrorType` (Validation 400, NotFound 404, Conflict 409, Unauthorized 401, Forbidden 403, Unexpected 500), nunca BadRequest para tudo. PROIBIDO: try/catch no handler, retornar null, erro string sem código.
-- **backend-dotnet-fluent-validation-vsa** (`backend/dotnet/fluent-validation-vsa.md`) — Um `sealed AbstractValidator<TRequest>` (FluentValidation 12) por request, na pasta da slice; o `ValidationDecorator` roda antes do handler e devolve `Result.Failure(ValidationError)`. `AddValidatorsFromAssembly()` ANTES de `AddHandlersFromAssembly()`. Sempre `.WithMessage()`; tempo via `TimeProvider` lido DENTRO da regra. Nunca lance `ValidationException`.
+- **backend-dotnet-fluent-validation-vsa** (`backend/dotnet/fluent-validation-vsa.md`) — Um `AbstractValidator<TRequest>` (FluentValidation 12) por request, na pasta da slice; o `ValidationDecorator` roda antes do handler e devolve `Result.Failure(ValidationError)`. `AddValidatorsFromAssembly()` ANTES de `AddHandlersFromAssembly()`. Sempre `.WithMessage()`; tempo via `TimeProvider` lido DENTRO da regra. Nunca lance `ValidationException`.
 - **backend-dotnet-scrutor** (`backend/dotnet/scrutor.md`) — `AddHandlersFromAssembly` registra cada `IHandler<,>` como Scoped (filtro `!t.ContainsGenericParameters`) e depois `Decorate` Validation e então Logging (o último registrado é o mais externo). Endpoints `IApiEndpoint` via `TryAddEnumerable` Transient + `MapApiEndpoints`. Nunca registre handler um a um.
 - **backend-dotnet-scalar-ui** (`backend/dotnet/scalar-ui.md`) — Scalar no lugar do Swagger: `Microsoft.AspNetCore.OpenApi` 10.0.0 + `Scalar.AspNetCore` 2.12.40, nunca Swashbuckle. `MapOpenApi()` só em `IsDevelopment()` e antes de `MapScalarApiReference`. Todo endpoint com `.WithTags(ApiTags.X)` (constantes), `.Produces<T>` e `.ProducesProblem(status)` por falha possível.
+- **backend-dotnet-analyzers** (`backend/dotnet/analyzers.md`) — O build cobra, a prosa não repete: `Guid.NewGuid()` é erro RS0030 (use `Guid.CreateVersion7()`) e token recebido e não repassado é erro CA2016, por `Directory.Build.props` + `BannedSymbols.txt` + `morph.globalconfig` na raiz. `sealed`, primary constructor e `var` são gosto: siga o arquivo vizinho.
 - **backend-api-validation** (`backend/api/validation.md`) — O validator checa só FORMA (sem DbContext); existência, unicidade e estado ficam no handler com `{Entity}Errors` tipados. Checagem de estado valida o INVÁLIDO (enum ordenado, estados de erro em 100+). PROIBIDO: lançar exceção, validar na lambda do endpoint, misturar DataAnnotations, `if (status != Expected)`, switch exaustivo sobre estados válidos.
 - **architecture-code-comments** (`architecture/code-comments.md`) — Padrão é nenhum comentário: renomeie, extraia, tipe ou teste antes. Só o porquê que o código não mostra (invariante, ordem, quirk externo com link), até ~3 linhas. PROIBIDO: história de processo (task, UC, ADR, Gate), repetir o código, XML doc/JSDoc que repete a assinatura, banner, `#region`, código comentado, TODO solto. O hook `comment-guard` bloqueia.
+- **architecture-engineering-lens** (`architecture/engineering-lens.md`) — Escreva para quem herda amanhã: convenção do projeto, o mais simples, causa raiz. PROIBIDO no que você adiciona: `catch` que engole, flag booleana que bifurca o método (são dois métodos), efeito colateral escondido, símbolo/flag/config sem consumidor, abstração ou camada sem segundo uso, literal repetido sem constante. Nomes de domínio buscáveis, funções pequenas, ≤ 3 parâmetros, condicional positiva. Commit em Conventional Commits (hook `conventional-commit`).
 
 > Resumo injetado quando você lê ou edita um arquivo casado por `paths:`. Texto completo: `morph-spec standards --find "<id>"` e leia só a seção necessária de `.morph/framework/standards/<path>`.

package/framework/rules/dotnet-templates.md

@@ -40,8 +40,8 @@ For each new feature slice, follow the patterns in these templates:
 |----------|------|---------|
 | Endpoint | `.morph/framework/templates/code/dotnet/feature/endpoint.cs.hbs` | IApiEndpoint with MapEndpoint() |
 | Handler | `.morph/framework/templates/code/dotnet/feature/handler.cs.hbs` | IHandler<TRequest, TResponse> |
-| Request | `.morph/framework/templates/code/dotnet/feature/request.cs.hbs` | Sealed record DTO |
-| Response | `.morph/framework/templates/code/dotnet/feature/response.cs.hbs` | Sealed record DTO |
+| Request | `.morph/framework/templates/code/dotnet/feature/request.cs.hbs` | record DTO |
+| Response | `.morph/framework/templates/code/dotnet/feature/response.cs.hbs` | record DTO |
 | Validator | `.morph/framework/templates/code/dotnet/feature/validator.cs.hbs` | FluentValidation AbstractValidator |
 | Entity | `.morph/framework/templates/code/dotnet/feature/entity.cs.hbs` | Domain entity |
 | Errors | `.morph/framework/templates/code/dotnet/feature/errors.cs.hbs` | Error factory |

package/framework/rules/nextjs-standards.md

@@ -19,5 +19,6 @@ stacks:
 - **frontend-nextjs-nextjs-patterns** (`frontend/nextjs/nextjs-patterns.md`) — Route Handler é BFF: `auth.getSession()` (401 sem sessão) e delega ao .NET; banco NUNCA em route handler. Zod no client e no server (`safeParse`, 400). `strict: true` + `noUncheckedIndexedAccess`; sem `any` em resposta de API. shadcn via `npx shadcn@latest add`.
 - **frontend-nextjs-motion-patterns** (`frontend/nextjs/motion-patterns.md`) — Motion via `motion/react` (nunca `framer-motion` junto). Variants em `motion/variants.ts` com durations/easings de `@/lib/design-tokens`. `useReducedMotion()` obrigatório; o `layout.tsx` raiz segue Server Component. 3–5 momentos de motion por página; cena guiada por scroll é do GSAP, nunca no mesmo elemento.
 - **architecture-code-comments** (`architecture/code-comments.md`) — Padrão é nenhum comentário: renomeie, extraia, tipe ou teste antes. Só o porquê que o código não mostra (invariante, ordem, quirk externo com link), até ~3 linhas. PROIBIDO: história de processo (task, UC, ADR, Gate), repetir o código, XML doc/JSDoc que repete a assinatura, banner, `#region`, código comentado, TODO solto. O hook `comment-guard` bloqueia.
+- **architecture-engineering-lens** (`architecture/engineering-lens.md`) — Escreva para quem herda amanhã: convenção do projeto, o mais simples, causa raiz. PROIBIDO no que você adiciona: `catch` que engole, flag booleana que bifurca o método (são dois métodos), efeito colateral escondido, símbolo/flag/config sem consumidor, abstração ou camada sem segundo uso, literal repetido sem constante. Nomes de domínio buscáveis, funções pequenas, ≤ 3 parâmetros, condicional positiva. Commit em Conventional Commits (hook `conventional-commit`).
 
 > Resumo injetado quando você lê ou edita um arquivo casado por `paths:`. Texto completo: `morph-spec standards --find "<id>"` e leia só a seção necessária de `.morph/framework/standards/<path>`.

package/framework/schemas/feature.schema.json

@@ -95,6 +95,7 @@
               "additionalProperties": false
             },
             "attempts": { "type": "integer", "minimum": 1 },
+            "failStreak": { "type": "integer", "minimum": 0, "description": "Persisted red verifies in a row, reset to 0 by a green one. Read by `morph-spec next` (decideNext in framework/hooks/shared/next-step.js) to turn the fix loop into an escalation every FIX_ATTEMPTS reds. Absent on entries written before the field existed, which is why it is NOT in required." },
             "updatedAt": { "type": "string", "format": "date-time" }
           },
           "additionalProperties": false

package/framework/skills/core/create-umbraco-lp/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a criação de uma landing page nova ponta-a-ponta a partir do
 version: core
 when_to_use: Use quando for iniciar um novo projeto de LP com o template Umbraco genérico
 user-invocable: true
-cliVersion: "9.2.0"
+cliVersion: "9.4.0"
 stacks:
   - umbraco
 ---

package/framework/skills/core/migrate-lp-to-umbraco/SKILL.md

@@ -4,7 +4,7 @@ description: Migra uma landing page existente (React/Vite, Next.js estático ou
 version: core
 when_to_use: Use quando o usuário pedir "use /migrate-lp-to-umbraco {projeto}" ou descrever a necessidade de migrar uma LP para Umbraco
 user-invocable: true
-cliVersion: "9.2.0"
+cliVersion: "9.4.0"
 stacks:
   - umbraco
 ---

package/framework/skills/core/morph-apply/SKILL.md

@@ -4,7 +4,7 @@ description: Executa as fatias do plano de uma feature morph-spec — dispatch p
 version: core
 when_to_use: Use com o gate do plano aprovado, em "use /morph-apply {feature}" ou "implementar feature"
 user-invocable: true
-cliVersion: "9.2.0"
+cliVersion: "9.4.0"
 ---
 
 # morph-apply
@@ -108,6 +108,7 @@ relatório, não a mensagem** — a mensagem final pode não chegar ou vir resum
 | `ok` | siga |
 | `report-stale` | **não re-despache**: o agente escreveu depois de relatar; leia `observed` e atualize o relatório |
 | `report-incomplete` + `resume` | `PARCIAL` na 1ª linha = a fatia não está pronta — o `report-check` o acusa como `report-incomplete`. Retome o MESMO agente por `SendMessage`, colando `tree.dirty`, `tree.commits` e o que falta |
+| `report-blocked` + `ask-human` | `BLOQUEADO` na 1ª linha = decisão que não é do agente; a pergunta e as opções estão no relatório. **Não re-despache.** Plano ou ADR já decide → decida e registre; senão `AskUserQuestion`. Retome o MESMO agente com a resposta |
 | `report-incomplete` + `complete-degraded` | complete a partir da mensagem, carimbe DEGRADADO e registre a falha no relatório |
 | `work-landed-report-missing` | não re-despache; grave você o relatório, DEGRADADO |
 | `no-work-no-report` / `report-missing-evidence-unknown` | re-despache uma vez; segunda ausência sem trabalho = escale |
@@ -131,7 +132,8 @@ verify da feature. `--filter` é do loop do próprio sub-agente; o Gate 3 e o CI
 inteira. Nó de teste sem `expectedCount`, ou fatia que apagou teste de propósito (limpeza, `morph-spec tests-audit`): acrescente `--record-baseline` a ESTA rodada — ela mede e
 prova de uma vez; nunca um segundo verify só para gravar a baseline. Vermelho: corrija com `verify.feedback` (direto no código, ou re-despachando a fatia dona)
 e rode de novo; **3 tentativas** sem verde → `AskUserQuestion` ("Verify de {feature} vermelho após 3
-tentativas — aceitar com ressalva, continuar tentando, ou parar?").
+tentativas — aceitar com ressalva, continuar tentando, ou parar?"). Quem conta é o `feature.json`:
+`morph-spec next {feature}` devolve `fix` enquanto há tentativa e `escalate` na 3ª vermelha seguida.
 
 **Cenário que julga saída de LLM** (`prova: eval`): a evidência é rodar, não ler código. Com nó
 `runner: "evals"`: `morph-spec verify {feature} --filter {id-do-nó-evals} --skip-e2e --no-persist`

package/framework/skills/core/morph-hotfix/SKILL.md

@@ -4,7 +4,7 @@ description: ADW cirúrgico de hotfix — resolve uma queda/bug crítico de prod
 version: core
 when_to_use: Use quando chegar "/morph-hotfix {feature}", quando a morph-plan rotear o pedido como workType hotfix, ou quando o usuário disser "produção caiu / hotfix / urgente" a respeito de um incidente
 user-invocable: true
-cliVersion: "9.2.0"
+cliVersion: "9.4.0"
 ---
 
 # morph-hotfix

package/framework/skills/core/morph-machine/SKILL.md

@@ -4,7 +4,7 @@ description: Cuida da RAM e da CPU da máquina enquanto o morph-spec trabalha
 version: core
 when_to_use: Use quando a máquina estiver lenta ou sem RAM, um comando pesado esperou ou foi recusado pela fila, sobrou worktree de sub-agent, ou vários sub-agents pesados vão rodar em paralelo
 user-invocable: false
-cliVersion: "9.2.0"
+cliVersion: "9.4.0"
 ---
 
 # morph-machine

package/framework/skills/core/morph-media/SKILL.md

@@ -4,7 +4,7 @@ description: Conduz a AUTORIA de mídia gerada por IA — escolher o modelo pelo
 version: core
 when_to_use: Use quando a tarefa for PRODUZIR imagem ou vídeo por IA (catálogo, marketing, asset de LP) e alguém precisar decidir modelo, prompt e aprovação
 user-invocable: true
-cliVersion: "9.2.0"
+cliVersion: "9.4.0"
 stacks:
   - dotnet
   - nextjs