@polymorphism-tech/morph-spec 8.47.0 → 9.0.0

package/bin/morph-spec.js

@@ -45,6 +45,8 @@ const claimCommand = lazy('../src/commands/project/claim.js', 'claimCommand');
 const standardsCommand = lazy('../src/commands/project/standards.js', 'standardsCommand');
 const reportCheckCommand = lazy('../src/commands/state/report-check.js', 'reportCheckCommand');
 const scoutCheckCommand = lazy('../src/commands/validation/scout-check.js', 'scoutCheckCommand');
+const planCheckCommand = lazy('../src/commands/validation/plan-check.js', 'planCheckCommand');
+const stackScanCommand = lazy('../src/commands/project/stack-scan.js', 'stackScanCommand');
 
 // === Approval gates (human-only) ===
 const approveCommand = lazy('../src/commands/state/approve.js', 'approveCommand');
@@ -60,11 +62,8 @@ const retypeCommand = lazy('../src/commands/state/retype.js', 'retypeCommand');
 const handoffCommand = lazy('../src/commands/state/handoff.js', 'handoffCommand');
 const listCommand = lazy('../src/commands/state/list.js', 'listCommand');
 const deleteCommand = lazy('../src/commands/state/delete.js', 'deleteCommand');
-const usecaseReserveCommand = lazy('../src/commands/state/usecase.js', 'usecaseReserveCommand');
-const usecaseCheckCommand = lazy('../src/commands/state/usecase.js', 'usecaseCheckCommand');
 
 // === Tasks ===
-const dagCommand = lazy('../src/commands/tasks/dag.js', 'dagCommand');
 
 // === Codebase graph ===
 const graphStatusCommand = lazy('../src/commands/graph/status.js', 'graphStatusCommand');
@@ -174,7 +173,7 @@ program
 
 program
   .command('list')
-  .description('List every feature × status × gates (G1/G2/G3) × workType — the audit board')
+  .description('List every feature × status × gates (G1 plan / Gd uiux / G3 review) × workType — the audit board')
   .option('--all', 'Include archived features (.morph/archive)')
   .option('--archived', 'Include archived features (alias of --all)')
   .option('--no-branch', 'Skip reading morph/{feature} for truth — report only what is on disk in this tree')
@@ -184,12 +183,12 @@ program
 // ─── Approval gates (dev-only) ────────────────────────────────────────────
 program
   .command('approve <feature> <gate>')
-  .description('Approve a phase gate (proposal, plan, review). Enforces gate order (N requires N-1)')
+  .description('Approve a phase gate (plan, uiux, review). Enforces gate order (uiux and review require plan)')
   .option('--approver <name>', 'Name of approver (default: current user when interactive, "auto" otherwise)')
   .option('--mode <mode>', 'Approval mode: "user" or "auto" (default: detected from TTY)')
   .option('--notes <notes>', 'Approval notes')
   .option('--force', 'Approve out of order (bypass the gate-monotonicity check)')
-  .option('--self-assessed', 'Gate 3 only: approve without 4-review/evaluator-report.md, recording the degradation in feature.json')
+  .option('--self-assessed', 'Gate 3 only: approve without the review reports (verifier.md, reviewer.md, security.md), recording the degradation in feature.json')
   .action((feature, gate, options) => approveCommand(feature, gate, options));
 
 program
@@ -197,7 +196,7 @@ program
   .description('Approve the current phase gate and scaffold the next phase folder (one step)')
   .option('--approver <name>', 'Name of approver (default: current user when interactive, "auto" otherwise)')
   .option('--mode <mode>', 'Approval mode: "user" or "auto" (default: detected from TTY)')
-  .option('--design', 'From proposal, advance into the optional design (uiux) phase instead of plan')
+  .option('--design', 'From plan, advance into the optional design (uiux) phase instead of implement')
   .option('--notes <notes>', 'Approval notes')
   .option('--force', 'Advance even if a prerequisite gate is unapproved (out-of-order recovery)')
   .action((feature, options) => advanceCommand(feature, options));
@@ -251,7 +250,7 @@ program
 program
   .command('gate-check <feature> <gate>')
   .description('Decide + record a gate\'s trust decision from disk-derived signals (shouldPauseGate) — the deterministic default; see gate-decision for the manual escape hatch')
-  .option('--signals <json>', 'Override ONLY standardsViolations/designSystemDivergence (not derivable from disk) — everything else is read from feature.json/tasks.json/git and cannot be overridden here')
+  .option('--signals <json>', 'Override ONLY standardsViolations/designSystemDivergence (not derivable from disk) — everything else is read from feature.json/checks.json/git and cannot be overridden here')
   .option('--trust <mode>', 'Trust mode to decide with (default: config.json → trust, or "auto")')
   .option('--json', 'Output as JSON')
   .action((feature, gateArg, options) => gateCheckCommand(feature, gateArg, options));
@@ -294,33 +293,6 @@ program
   .option('--here', 'Force building/writing in the current directory, even if another tree owns this feature')
   .action((feature, options) => handoffCommand(feature, options));
 
-// ─── Use cases ────────────────────────────────────────────────────────────
-const usecaseCommand = program
-  .command('usecase')
-  .description('Project-wide use cases: UC-{nn} numbering (acervo + every worktree of this repo) and the acervo lifecycle check');
-
-usecaseCommand
-  .command('reserve')
-  .description('Atomically reserve the next N UC-{nn} numbers, shared across every worktree of this repo — replaces the old max+1 disk scan, which collides across worktrees')
-  .option('--count <n>', 'How many numbers to reserve', '1')
-  .option('--feature <name>', 'Feature to record as the reservation owner (defaults to the sole active feature, if unambiguous) — also what the promotion collision guard compares against')
-  .option('--json', 'Output as JSON')
-  .action((options) => usecaseReserveCommand(options));
-
-usecaseCommand
-  .command('check <feature>')
-  .description('Check a feature against the acervo lifecycle: tasks citing a superseded UC, malformed supersession frontmatter, spec.md revocation rows the finish could not apply (plus the task/use-case plumbing dag checks, when tasks.json exists)')
-  .option('--json', 'Output as JSON')
-  .action((feature, options) => usecaseCheckCommand(feature, options));
-
-// ─── Tasks ────────────────────────────────────────────────────────────────
-program
-  .command('dag <feature>')
-  .description('Analyze the tasks.json DAG and print the sequential vs parallel dispatch decision (effort-weighted)')
-  .option('--json', 'Output as JSON')
-  .option('--mermaid', 'Emit the tasks.json DAG as a Mermaid flowchart (flowchart TD)')
-  .action((feature, options) => dagCommand(feature, options));
-
 // ─── Codebase graph ───────────────────────────────────────────────────────
 const graphCommand = program
   .command('graph')
@@ -388,24 +360,23 @@ program
   .action(validateFeatureCommand);
 
 program
-  .command('verify <feature> [task]')
+  .command('verify <feature>')
   .description('Run the deterministic verification chain (build + tests + validators + e2e) — code before the LLM judge')
   .option('--json', 'Output as JSON')
   .option('--timeout <ms>', 'Timeout in ms for the build AND tests nodes (build default 120000; tests default 120000 per test project, or project.testTimeoutMs)', (v) => parseInt(v, 10))
   .option('--filter <ids>', 'Run only the test nodes whose id matches (comma-separated; exact or substring). Unmatched nodes are reported as skip; matching nothing is a usage error (exit 2)')
   .option('--linux', 'Run the test nodes inside a Linux container, on a COPY of the tree (the host tree is mounted read-only and copied in — a bind mount is case-insensitive and cannot reproduce case defects). No Docker = usage error, never a skip')
   .option('--linux-image <img>', 'Image used by --linux (default: mcr.microsoft.com/dotnet/sdk:10.0)')
-  .option('--full', 'No escopo de task, desliga o recorte automático e roda todos os nós inteiros (o group da task não escolhe nós e os outputs não estreitam comandos). No escopo de feature não muda nada: ali nada é recortado')
-  .option('--record-baseline', 'Measure every test node and write expectedCount back into .morph/config/config.json (only from an all-green run at FEATURE scope; with a task id it is a usage error; never creates config.json)')
+  .option('--record-baseline', 'Measure every test node and write expectedCount back into .morph/config/config.json (only from an all-green run; never creates config.json)')
   .option('--refresh-cache', 'Rewrite the response cache of every `runner: "evals"` node against the real provider. NEVER implicit: a cache rewrite is a paid call nobody asked for. Requires the declared envFile; no eval node declared, --skip-tests, or a --filter that excludes them all are usage errors (exit 2), refused BEFORE the cache is touched')
-  .option('--skip-tests', 'Skip the test node. At feature scope the run is partial, so the verification stamp is NOT written (reason "skip-tests")')
-  .option('--skip-build', 'Skip the build node. At feature scope the run is partial, so the verification stamp is NOT written (reason "skip-build")')
+  .option('--skip-tests', 'Skip the test node. The run is partial, so the verification stamp is NOT written (reason "skip-tests")')
+  .option('--skip-build', 'Skip the build node. The run is partial, so the verification stamp is NOT written (reason "skip-build")')
   .option('--skip-e2e', 'Skip the e2e node (Docker bring-up + Playwright)')
   .option('--fresh-e2e', 'Recreate the e2e stack from scratch: down -v (named volumes included), drop the freshness stamp, rebuild, re-seed auth')
   .option('--no-persist', 'Do not persist the result to feature.json')
-  .option('--ci', 'Feature scope only: push morph/<feature> and take the proof from the project CI (creates .github/workflows/morph-verify.yml when no workflow runs verify). Same stamp, source "ci". No GitHub/gh/workflow = local verify with the reason; uncommitted code = exit 2; CI still running after 50 min = exit 3, no stamp')
-  .action((feature, task, options) =>
-    verifyCommand(feature, task, { ...options, noPersist: options.persist === false })
+  .option('--ci', 'Push morph/<feature> and take the proof from the project CI (creates .github/workflows/morph-verify.yml when no workflow runs verify). Same stamp, source "ci". No GitHub/gh/workflow = local verify with the reason; uncommitted code = exit 2; CI still running after 50 min = exit 3, no stamp')
+  .action((feature, options) =>
+    verifyCommand(feature, { ...options, noPersist: options.persist === false })
   );
 
 program
@@ -616,8 +587,9 @@ program
 // ─── Standards search (server-side, R2 token cut) ─────────────────────────
 program
   .command('standards')
-  .description('Search STANDARDS.json server-side (top 3, full digest) instead of reading the whole registry. No --find: list categories + counts')
+  .description('Search STANDARDS.json server-side (top 3, digest + anchors) or print one section, instead of reading the whole registry. Bare: categories + counts')
   .option('--find <query>', 'Search query — matches name/id, tags/aliases, category, digest')
+  .option('--show <target>', '<id>: digest + anchors; <id>#<anchor>: only that section of the standard .md')
   .option('--category <category>', 'Restrict --find to a single category')
   .option('--tags <tags>', 'Restrict --find to standards carrying any of these comma-separated tags')
   .option('--json', 'Output as JSON')
@@ -625,11 +597,11 @@ program
 
 // ─── Sub-agent report protocol ────────────────────────────────────────────
 program
-  .command('report-check <feature> [tasks...]')
-  .description('Audit sub-agent report files against the work that actually landed. Answers "did the WORK land even though the REPORT did not" — exits 0 only when everything is intact. Several task ids audit a parallel batch in one call')
-  .option('--before-eval', 'Save a snapshot of the tree before dispatching the evaluator; later runs report what changed since')
+  .command('report-check <feature> [slices...]')
+  .description('Audit slice report files (3-implement/reports/{slice}.md) against the work the dispatch actually wrote (telemetry, keyed by the agent that wrote the report). Exits 0 only when every audited slice is intact; naming slices audits only those')
+  .option('--before-eval', 'Save a snapshot of the tree before dispatching the review agents and print their models; later runs report what changed since')
   .option('--json', 'Output as JSON')
-  .action((feature, tasks, options) => reportCheckCommand(feature, tasks.length > 1 ? tasks : tasks[0], options));
+  .action((feature, slices, options) => reportCheckCommand(feature, slices, options));
 
 program
   .command('scout-check <map>')
@@ -638,6 +610,20 @@ program
   .option('--json', 'Output as JSON')
   .action((map, options) => scoutCheckCommand(map, options));
 
+program
+  .command('plan-check <feature>')
+  .description('Parse 2-plan/plan.md (scenarios, slices, decisions, reuse) and, with no error, write 2-plan/checks.json — the only writer of checks.json. Refuses to rewrite it once the plan gate is approved and the plan changed outside ## Errata. Exits 1 on errors, 2 when plan.md is missing')
+  .option('--json', 'Output as JSON')
+  .addHelpText('after', () => '\nGramática (framework/templates/docs/plan.md):\n\n' +
+    readFileSync(join(__dirname, '..', 'framework', 'templates', 'docs', 'plan.md'), 'utf8').replace(/\{\{FEATURE_NAME\}\}/g, '<feature>'))
+  .action((feature, options) => planCheckCommand(feature, options));
+
+program
+  .command('stack-scan [feature]')
+  .description('Audit the code against config.project.stack, judging only the configured stacks (runtime, ORM, database, Guid.NewGuid, generic repository, service layer, raw SQL, sealed, router, UI library) by severity. With a feature, write .morph/features/<f>/2-plan/stack-scan.md; without, print the report')
+  .option('--json', 'Output as JSON')
+  .action((feature, options) => stackScanCommand(feature, options));
+
 // ─── Dashboard ────────────────────────────────────────────────────────────
 program
   .command('dashboard')
@@ -657,10 +643,10 @@ program
 
 program
   .command('cost [feature]')
-  .description('Cost-facing view over .morph/logs/events.jsonl: task duration, bytes re-ingested by kind (proxy, not tokens), dispatch counts')
-  .option('--by <mode>', 'Group by: task|phase (default: feature-wide summary; with --all-trees, applies to the combined aggregate)')
+  .description('Cost-facing view over .morph/logs/events.jsonl: bytes re-ingested by kind (proxy, not tokens), dispatch counts, real tokens when observed')
+  .option('--by <mode>', 'Group by: phase (default: feature-wide summary; with --all-trees, applies to the combined aggregate)')
   .option('--all-trees', 'Aggregate across every git worktree with a log plus the logs finish saved in .git/morph-spec/finish-backup — per-tree breakdown + combined total')
-  .option('--metrics', 'Loop measurements: turns, tool calls (orchestrator x sub-agent), time per command class, identical reruns, rereads, feature verify count, git per task, reuse validator per tree')
+  .option('--metrics', 'Loop measurements: turns, tool calls (orchestrator x sub-agent), time per command class, identical reruns, rereads, verify count per feature, git calls, reuse validator per tree')
   .option('--top <n>', 'With --metrics: how many reread files to list (default 10)', (v) => Number.parseInt(v, 10))
   .option('--json', 'Output the aggregate as JSON')
   .action((feature, options) => costCommand(feature, options));

package/bin/validate.js

@@ -5,9 +5,8 @@
  *
  * Runs validators for the current project stack (detected from .morph/config/config.json).
  *
- * .NET stacks:       packages, spec-tasks
- * Next.js stack:      next-components, spec-tasks
- * Other stacks:       spec-tasks
+ * .NET stacks:       packages
+ * Next.js stack:      next-components
  *
  * Usage:
  *   morph-spec validate [options]
@@ -21,12 +20,7 @@
 import chalk from 'chalk';
 import { getStackProfile } from '../src/lib/stack/stack-profile.js';
 
-/**
- * Build the VALIDATORS registry for the current stack.
- * .NET stacks  → packages, spec-tasks
- * nextjs stack → next-components, spec-tasks
- * other stacks → spec-tasks only
- */
+/** The validators of the current stack: .NET → packages, Next.js → next-components. */
 async function buildValidators(stack) {
   const validators = {};
 
@@ -52,111 +46,9 @@ async function buildValidators(stack) {
     };
   }
 
-  validators['spec-tasks'] = {
-    name: 'Spec vs Tasks Coverage',
-    description: 'Validates that tasks.json covers all requirements from spec.md',
-    run: validateSpecVsTasks
-  };
-
   return validators;
 }
 
-/**
- * Validate spec.md requirements are covered by tasks
- */
-async function validateSpecVsTasks(projectPath, options = {}) {
-  const path = await import('path');
-  const fs = await import('fs');
-  const { loadState } = await import('../src/core/state/state-manager.js');
-
-  const results = [];
-  let errors = 0;
-  let warnings = 0;
-
-  try {
-    const state = loadState(false);
-    if (!state || !state.features) {
-      return { status: 'ok', errors: 0, warnings: 0, message: 'No features to validate' };
-    }
-
-    for (const [featureName, feature] of Object.entries(state.features)) {
-      const outputsPath = path.join(projectPath, '.morph/features', featureName);
-      const specPath = path.join(outputsPath, 'spec.md');
-
-      if (!fs.existsSync(specPath)) {
-        continue; // No spec to validate
-      }
-
-      // Read spec.md and extract requirements
-      const specContent = fs.readFileSync(specPath, 'utf-8');
-
-      // Extract requirement patterns (## Requisitos, - [ ], numbered lists, etc.)
-      const requirementPatterns = [
-        /^#+\s*Requisitos?\s*$/gim,
-        /^-\s*\[.\]\s*(.+)$/gm,
-        /^\d+\.\s+(.+)$/gm
-      ];
-
-      const requirements = [];
-      for (const pattern of requirementPatterns) {
-        const matches = specContent.matchAll(pattern);
-        for (const match of matches) {
-          if (match[1]) {
-            requirements.push(match[1].trim());
-          }
-        }
-      }
-
-      // Check if feature has tasks
-      if (!feature.tasks || (Array.isArray(feature.tasks) && feature.tasks.length === 0)) {
-        if (requirements.length > 0) {
-          warnings++;
-          results.push({
-            feature: featureName,
-            level: 'warning',
-            message: `Spec has ${requirements.length} requirements but no tasks defined`
-          });
-        }
-        continue;
-      }
-
-      // Get task titles
-      const taskTitles = Array.isArray(feature.tasks)
-        ? feature.tasks.map(t => t.title?.toLowerCase() || '')
-        : [];
-
-      // Check each requirement has a matching task (fuzzy match)
-      for (const req of requirements.slice(0, 20)) { // Limit to first 20
-        const reqLower = req.toLowerCase();
-        const hasMatch = taskTitles.some(title =>
-          title.includes(reqLower.slice(0, 20)) ||
-          reqLower.includes(title.slice(0, 20))
-        );
-
-        if (!hasMatch && options.verbose) {
-          console.log(chalk.gray(`  ? Requirement may not be covered: "${req.slice(0, 50)}..."`));
-        }
-      }
-
-      if (options.verbose) {
-        console.log(chalk.green(`  ✓ ${featureName}: ${requirements.length} requirements, ${taskTitles.length} tasks`));
-      }
-    }
-
-  } catch (error) {
-    if (options.verbose) {
-      console.log(chalk.yellow(`  ⚠ Could not validate: ${error.message}`));
-    }
-  }
-
-  return {
-    status: errors > 0 ? 'error' : warnings > 0 ? 'warning' : 'ok',
-    errors,
-    warnings,
-    results
-  };
-}
-
 /**
  * Main validation command
  */

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "8.47.0",
+  "version": "9.0.0",
   "displayName": "MORPH-SPEC Framework",
   "description": "Spec-driven development with 38 agents and 8-phase workflow for .NET/Blazor/Next.js/Azure",
   "publisher": "polymorphism-tech",

package/docs/CHEATSHEET.md

@@ -185,4 +185,4 @@ Never edited directly — go through CLI commands or `morph-spec update` instead
 
 ---
 
-*morph-spec v8.47.0 by Polymorphism Tech*
+*morph-spec v9.0.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -249,4 +249,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v8.47.0 by Polymorphism Tech*
+*morph-spec v9.0.0 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -1,114 +1,54 @@
 # MORPH-SPEC Runtime Instructions
 
-> by Polymorphism Tech — Spec-driven development harness for Claude Code
-
-## Como começar cada sessão
-
-1. Leia `.morph/framework/MORPH.md` — o charter NLH com papéis, fases, gates e skills.
-2. Leia `.morph/state.json` — índice fino e gitignored (status + updatedAt por feature), reconstruído a cada load. **Não o edite à mão.** Estado autoritativo e commitado de cada feature: `.morph/features/{feature}/feature.json`.
-3. Se existir `.morph/features/{feature}/handoff.md` para a feature ativa, **leia-o antes de re-derivar contexto à mão** — documento de retomada comprimido (regenere com `morph-spec handoff <f>` se parecer velho).
-4. Assuma o papel correspondente (Orchestrator/Specialist/Evaluator) e continue o trabalho. Não aguarde instrução do usuário se há trabalho pendente entre gates.
-
-Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
-
-## Regras críticas
-
-**NUNCA:**
-- Pular para código sem proposal aprovado (Gate 1) e plano aprovado (Gate 2).
-- Modificar o contrato do plano depois do Gate 2 — `spec.md` e os campos `title`/`description`/`dependencies`/`effort`/`doneCriteria`/`group`/`agent`/`standards` de `tasks.json` ficam congelados (`protect-spec-files` bloqueia `Write`/`Edit`); mutáveis: `status`/`outputs`/`notes` (ver SEMPRE). **Fato errado sobre o código não exige revogar gate**: bloco `## Errata` append-only no fim, corpo intacto (MORPH.md §3). **Use cases (`2-plan/usecases/UC-*.md`) NÃO congelam** — editáveis por design.
-- Escrever critérios de aceite no `proposal.md` — pertencem aos use cases (pós-condição **observável em teste**, chega **literal** ao `doneCriteria`).
-- Editar `.morph/specs/usecases/` à mão — só o `finish` escreve lá. Mudar um UC existente (`bug`): copie para `2-plan/usecases/` da feature e corrija lá.
-- Listar perguntas em texto simples — sempre `AskUserQuestion` (1-4 perguntas por chamada).
-- Usar `Guid.NewGuid()`, classes não-sealed sem justificativa, exceptions como fluxo de controle, camada de Service/Manager entre handler e dados, repository genérico (`IRepository<T>`/`IUnitOfWork`), ou SQL cru sem justificativa.
-- Comentar o que nome, tipo ou teste já dizem: o padrão é nenhum comentário, mesmo ao lado de código comentado; o elo com a pós-condição vai no nome do teste (`architecture-code-comments`, hook `comment-guard`).
-- Editar `gateDecisions` ou gates de `feature.json` à mão — sempre via `morph-spec gate-check`/`approve` (timestamps server-side; Edit manual colide com o hook `state-sync`).
-
-**SEMPRE:**
-- Auto-advance entre tarefas durante a fase implement — não pause sem ambiguidade bloqueante.
-- Abrir toda feature `feature`/`bug` com a escolha de **modo de descoberta** (entrevista ou automático), depois de varrer o ambiente. **No modo entrevista, uma pergunta por chamada de `AskUserQuestion`** — o "1-4 por chamada" não é licença para agrupar a entrevista. O Gate 1 pausa sempre nesse modo.
-- Atualizar `tasks.json` ao concluir cada task gravando só os campos mutáveis `status`/`outputs`/`notes` — via `Write` OU `Edit`.
-- Apresentar gates com o template fixo (MORPH.md/morph-plan). **A pergunta PRECISA nomear a feature** ("Gate 2 — Plano de {feature} aprovado?") — é por esse nome que `state-sync` atribui a aprovação ao `feature.json` certo. Sem nome, com mais de uma feature na árvore, ele **recusa gravar** — aprove com `morph-spec approve <feature> <gate>`.
-- Registrar decisões não triviais em `decisions.md`.
-- Fechar cada task só com `verify {f} {T}` verde e cada `doneCriteria` com a evidência que o prova; vermelho ou critério sem prova dispara o loop de correção autônomo, sem escalar ao humano entre tarefas. No Gate 3, o veredito (`SHIP`/`FIX`) vem do **avaliador independente** despachado pela `morph-review` — nunca de quem implementou.
-- Em `hotfix`, o Gate 3 pausa **sempre** para um humano, mesmo em `trust: auto` — `approve ... review --mode auto` é recusado; aprove com `--approver`.
-- Confirmar antes de `finish`/`archive`/`delete` se o SessionStart avisar que outra sessão tem claim vivo na mesma feature.
-- **Ao retomar o controle depois de um dispatch, o orquestrador lê o arquivo de relatório, não a mensagem final** — a mensagem pode não chegar ou vir resumida. As cláusulas do prompt vivem só nos templates (`morph-implement` §4, `morph-apply` §3b).
+> by Polymorphism Tech — harness spec-driven para Claude Code
+
+## Início de cada sessão
+
+1. Leia `.morph/framework/MORPH.md` uma vez (de novo após `/compact`): papéis, fases, gates, dispatch.
+2. `.morph/state.json` é índice gitignored, só para achar a feature ativa; o estado autoritativo é `.morph/features/{feature}/feature.json`.
+3. Existe `.morph/features/{feature}/handoff.md`? Leia antes de re-derivar contexto à mão.
+4. Feature em andamento → assuma o papel da fase e continue entre gates sem esperar instrução. Nenhuma ativa → pergunte qual trabalhar.
+
+## Regras
+
+- Perguntas ao usuário só por `AskUserQuestion` (1-4 por chamada), nunca em texto solto. Na entrevista da `morph-plan`, **uma pergunta por chamada**: lote impede que uma resposta pode os ramos seguintes. Única exceção: ferramenta indisponível ou negada (headless) — texto numerado com a resposta recomendada e gate pausado (`morph-plan` §3).
+- A pergunta de gate nomeia a feature ("Gate do plano — Plano de {feature} aprovado?"): é por esse nome que o hook `state-sync` grava a aprovação no `feature.json` certo; sem nome, com mais de uma feature, ele recusa e você aprova por `morph-spec approve <feature> <gate>`.
+- Estado só pela CLI, nunca à mão: `feature.json`, `gateDecisions`, `checks.json` (escrito só por `plan-check`) e o corpo do `plan.md` depois do gate (fato errado → `## Errata` no fim; escopo mudou → `unapprove`).
+- SessionStart avisou claim vivo de outra sessão na mesma feature → confirme com o usuário antes de `finish`/`archive`/`delete`.
+- Depois de um dispatch, leia o arquivo de relatório da fatia, não a mensagem final, que pode não chegar.
+
+## CLI do loop
+
+Prefixo `morph-spec`; flags e porquês em `.morph/framework/CLI.md` (um `###` por comando).
+
+| Comando | Para quê |
+|---|---|
+| `create <f> --description "…" --type <t> [--worktree]` | nasce a feature; exit 2 = você escolhe o tipo |
+| `stack-scan [f]` | desvios do código contra `project.stack` |
+| `plan-check <f>` | valida `plan.md`, grava `checks.json`, imprime as ondas |
+| `gate-check <f> <gate>` | decide a pausa pelos sinais do disco |
+| `approve <f> <gate> --mode auto` / `advance <f>` | aprova (advance também abre a próxima fase) |
+| `verify <f> [--ci]` | build + testes + validadores + e2e, sem filtro |
+| `report-check <f> [F1 …]` | audita o relatório de cada fatia e diz a ação |
+| `mutate <f>` | mutação dirigida do Gate 3 (até 3 mutantes) |
+| `finish <f> --pr\|--merge` | encerra; só o `--merge` integra |
+| `standards --find "<tema>"` / `--show <id>#<âncora>` | digest do standard / uma seção |
+| `heavy status\|run -- <cmd>` | fila de build/teste; exit 3 = fila cheia |
+| `worktree setup\|provision\|link\|remove\|list\|reap` | ciclo da worktree; `remove` é a única remoção segura |
+| `graph affected\|explain <sym>` | blast radius; sem grafo, caia para grep |
 
 ## Slash commands
 
-| Comando | Propósito |
-|---------|-----------|
-| `/morph-proposal {feature}` | Entendimento de negócio + plano (Gates 1 e 2). Passo 0 roteia por tipo de trabalho (`feature`/`bug`/`chore`/`hotfix`) |
-| `/morph-hotfix {feature}` | ADW cirúrgico de hotfix (scout → fix → gate humano → ship) |
-| `/morph-apply {feature}` | Execução autônoma + review (Gate 3) |
-| `/morph-status [feature]` | Status da feature ativa (ou a especificada) |
-| `/morph-archive {feature}` | Arquiva-**sem-integrar** (legadas/faxina) — wrapper de `archive`. Fechamento normal = `finish --pr\|--merge` |
-| `/morph-preflight` | Validação pré-deploy (specs, contratos, testes, infra) |
-| `/morph-troubleshoot [erro]` | Diagnóstico de erros .NET/Next.js com root-cause analysis |
-
-**Comandos CLI de gate e de estado** (a LLM os usa em vez de editar o estado à mão):
-
-| Comando | Propósito |
-|---------|-----------|
-| `approve <f> <gate> --mode auto` | Aprova gate em `trust:auto`. Gate 3 exige `evaluator-report.md` (ou `--self-assessed`); `hotfix` nunca aceita `--mode auto` — use `--approver` |
-| `advance <f>` | Aprova o gate corrente + já cria a pasta da próxima fase |
-| `gate-check <f> <gate> [--json]` | Default: decide via sinais do disco (`shouldPauseGate`) |
-| `gate-decision <f> <gate> --pause <bool>` | Escape manual: risco que o disco não vê |
-| `create <f> --description "..." --type <t>` | Nasce a feature + `feature.json`; `--worktree` já isola |
-| `list [--all] [--json]` | Quadro de auditoria: feature × workType × status × gates |
-| `delete <f> [--archive] [--force]` | Remove feature; recusa se gate aprovado sem `--force` |
-| `retype <f> <tipo>` | Muda o workType mid-flight; bloqueado após o Gate 3 |
-| `finish <f> --pr\|--merge` | Encerramento único: arquiva, promove use cases, desmonta worktree. Integra só no `--merge`; `--pr` abre PR e fica `aguardando-merge` até alguém mergear |
-| `archive <f>` | Arquiva sem integrar (legadas/faxina) |
-| `worktree setup\|provision\|link\|remove\|list\|reap` | Ciclo do worktree; `provision` = isolamento de task; `remove` é a única remoção segura |
-| `branch prune [--dry-run]` | Apaga branch já integrada, inclusive squash-merge; nunca a com PR aberto |
-| `handoff <f>` | Regenera o documento de retomada da feature |
-| `fleet` | Visão agregada de toda feature ativa (raiz + worktrees) |
-| `claim [f] [--release] [--list]` | Posse advisory — confirme antes de `finish`/`archive`/`delete` se outra sessão tiver claim vivo |
-| `dag <f>` | DAG de `tasks.json`: sequencial/paralelo, recomenda isolamento |
-| `graph status\|build\|refresh` | Grafo de codebase. `status` reporta frescor e se há refresh em background |
-| `graph affected\|explain <sym>` | Blast radius e vizinhança saneados. Sem grafo, caia para grep — nunca é erro |
-| `verify <f> [task] [--ci]` | Build+testes+validadores+e2e — prova da task; a do Gate 3 com `--ci` (no CI) |
-| `e2e up\|status\|down <f>` | Stack de verificação (docker compose) |
-| `doctor --worktrees [--prune]` | Reconcilia git × disco × features; só `--prune` remove algo |
-| `report-check <f> [task...] [--json]` | Audita relatório de sub-agent vs. trabalho entregue |
-| `telemetry [--feature] [--limit]` | Caminho de execução da sessão a partir de `events.jsonl` |
-| `cost [f] [--by task\|phase] [--metrics]` | Custo (bytes/duração) e medições do loop (turnos, rerun, releitura) do mesmo log |
-
-Prefixo de todo comando: `morph-spec`. Flags/exemplos: `.morph/framework/CLI.md`.
-
-## Skills core (em `.claude/skills/`)
-
-| Skill | Quando usar |
-|-------|-------------|
-| `morph-brainstorming` | Entender negócio, escanear stack, produzir proposal.md |
-| `morph-stack-scan` | Desvios de stack em projeto brownfield |
-| `morph-uiux` | Ramo opcional de UI/UX — design system e mockups |
-| `morph-plan` | Destilar use cases e produzir spec.md + tasks.json |
-| `morph-implement` | Executar uma tarefa com auto-advance entre tasks |
-| `morph-review` | Produzir review-report.md (Gate 3) |
-| `morph-hotfix` | Hotfix cirúrgico (`/morph-hotfix`) |
-| `morph-standards` | Localizar standard sob demanda |
-| `morph-machine` | RAM/CPU: fila pesada, órfãos, worktrees sobrando |
-
-## Roteamento por tipo de trabalho
-
-`workType` (`create --type <tipo>` ou classificado de `--request`) dimensiona o pipeline: `feature` completo (+ ramo uiux quando há superfície de UI), `bug` enxuto, `chore` fast-track (Gates 1/2 por política), `hotfix` scout→fix→gate humano→ship. Canônico: `MORPH.md` §2.1/§5.
-
-Features independentes rodam em paralelo, uma por git worktree (`create --worktree`/`worktree setup`), bloco de portas próprio + handoff.md. Fechamento: `finish <f> --pr|--merge`; agregado: `fleet`. Canônico: `MORPH.md` §2.2.
+`/morph-proposal {f}` (plano), `/morph-apply {f}` (execução + Gate 3), `/morph-hotfix {f}`, `/morph-status [f]`.
 
 ## Personas (em `.claude/agents/`)
 
-Despache tasks de domínio com `subagent_type: "morph-{id}"` — a persona é o **system prompt** do subagent registrado (gerado de `agents.json`, a fonte única). Tipo não registrado (stack não instalado): fallback `general-purpose` + campo `persona` colado no prompt, **registrando nas `notes` da task** (detalhe: `morph-apply` §3b).
+Despache fatias com `subagent_type: "morph-{id}"` — a persona, gerada de `agents.json`, é o system prompt. Tipo não registrado: `general-purpose` com o `persona` colado, registrado no relatório da fatia. Nunca edite `.claude/agents/morph-*.md` à mão (`morph-spec doctor` acusa o drift).
 
 <!-- morph-agents:start -->
-_Lista derivada na instalação (`morph-spec setup-infra`). Se este bloco está vazio, rode `morph-spec setup-infra --reinstall`._
+_Lista derivada na instalação. Bloco vazio → `morph-spec setup-infra --reinstall`._
 <!-- morph-agents:end -->
 
-Drift entre `agents.json` e os `.md` gerados é detectado por `morph-spec doctor` — nunca edite `.claude/agents/morph-*.md` à mão.
-
-## Regra de precedência de skills
-
-Com o plugin superpowers ativo, `morph-*` vence o equivalente genérico (aplica Gates e paths de `.morph/`), e `using-git-worktrees`→`morph-spec worktree setup|provision`.
+## Precedência de skills
 
-*MORPH-SPEC v5 by Polymorphism Tech*
+Com o plugin superpowers ativo, `morph-*` vence o equivalente genérico (aplica os gates e os paths de `.morph/`), e `using-git-worktrees`→`morph-spec worktree setup|provision`.