@polymorphism-tech/morph-spec 8.16.0 → 8.18.0

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

@@ -4,7 +4,7 @@ description: Guia a produção dos artefatos de planejamento de uma feature (use
 version: core
 when-to-invoke: ao iniciar a fase plan de uma feature, após o Gate 1 (proposal aprovado)
 user-invokable: true
-cliVersion: "8.16.0"
+cliVersion: "8.18.0"
 ---
 
 # morph-plan
@@ -88,13 +88,7 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
 4. Produza `mandate.md` em `.morph/features/{feature}/2-plan/`:
    - Stack exata do projeto (leia de `.morph/config/config.json` → `project.stack` ou do CLAUDE.md).
    - Standards obrigatórios: liste os IDs relevantes de `.morph/framework/standards/STANDARDS.json`.
-   - Patterns proibidos — inclua sempre os defaults abaixo mais qualquer específico da feature:
-     - `Guid.NewGuid()` → usar `Guid.CreateVersion7()`
-     - Classes não-sealed sem justificativa documentada
-     - Exceptions como fluxo de controle → usar result pattern com `result.Match()`
-     - Camada de Service/Manager entre handler e dados → handler usa `ApplicationDbContext` direto no slice
-     - Repository genérico (`IRepository<T>`/`IUnitOfWork`) → redundante sobre EF Core: `DbSet<T>` já é repository, `DbContext` já é unit of work
-     - SQL cru (`FromSqlRaw`, `ExecuteQuery(string)`) sem justificativa em `decisions.md` → usar LINQ
+   - Patterns proibidos — **copie por extenso no mandate.md** a lista canônica de `MORPH.md` § "Stack baked-in" (`Guid.NewGuid()`→`Guid.CreateVersion7()`, 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`, SQL cru sem justificativa) mais qualquer proibição específica da feature. Copie o texto completo — o mandate.md é lido por implementadores em contexto fresco, sem `MORPH.md` carregado, então um ponteiro sozinho não basta aqui.
    - Política de acesso a dados (registre no mandate): `ApplicationDbContext` injetado direto no slice — para CRUD e para queries específicas (joins, projeção, paginação). Para concorrência ou SQL específico, store dedicado hand-written com justificativa em `decisions.md`.
    - **Features com agentes de IA (MAF):** se a feature envolve um agente (Microsoft Agent Framework), **use a tool Read** nos standards relevantes de `framework/standards/ai-agents/*.md` (ex.: `setup`, `agent-session`, `middleware-patterns`, `mcp-server`, `mcp-tools`, `multi-agent-patterns`, `production`) — filtre pelo que a feature exige via STANDARDS.json. Esses standards carregam as **convenções de projeto** (single-agent por padrão — Workflows só para fan-in/out real; provider, caching, observability, A2A) que uma fonte externa de docs (ex.: context7) não conhece. Padrão de divisão: **superfície da API** pode vir de docs ao vivo/context7 (mais frescas para um SDK em evolução), mas **as convenções vêm dos standards** — registre ambas no mandate. Não pule os `ai-agents/*.md` só porque o STANDARDS.json index lista que eles existem.
    - Checklist de done com critérios verificáveis por tarefa.
@@ -118,7 +112,9 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
          "status": "pending",
          "outputs": [],
          "group": "backend",
-         "usecase": "UC-07"
+         "usecase": "UC-07",
+         "agent": "dotnet-senior",
+         "standards": ["standards/backend/dotnet/vsa-handler-patterns.md"]
        }
      ]
    }
@@ -132,6 +128,14 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
    - `group` (opcional): backend, frontend, tests, infra, docs. Default backend.
    - `outputs` (opcional): array de paths que serão criados/modificados.
    - `usecase` (opcional): o **ID** do use case que a task realiza — `UC-07`, nunca o nome do arquivo. Task puramente técnica (build, config, migração) não tem.
+   - `agent` (opcional): o `id` da persona de `agents.json` responsável pelo domínio da task — **sem** o prefixo `morph-` (ex.: `"dotnet-senior"`, não `"morph-dotnet-senior"`). Carimbado no passo 5a abaixo; ausente numa task sem domínio de agente claro (config/docs) ou num plano legado.
+   - `standards` (opcional): array de paths relativos de `framework/standards/` (ex.: `["standards/backend/dotnet/vsa-handler-patterns.md"]`) — os standards da persona resolvida em `agent`, mais qualquer standard específico que a task exija.
+
+   **5a. Carimbe `agent` e `standards` — uma leitura de `agents.json`, N tasks.** Antes de fechar o array `tasks`, **use a tool Read UMA VEZ** em `.morph/framework/agents.json` (não releia por task — é essa releitura repetida por task, hoje feita em `morph-implement`/`morph-apply` a cada dispatch, que este passo existe para eliminar). Para cada task do plano, resolva:
+   - `agent`: o `id` da persona (chave do objeto `agents`, sem prefixo `morph-`) cujo `domains` cobre o `group`/domínio da task — o mesmo casamento que `morph-implement` §3 e `morph-apply` §3b fariam manualmente a cada dispatch; aqui você faz uma vez, no plano.
+   - `standards`: o array `standards` dessa persona, mais qualquer standard adicional que a task especificamente exija (some, não substitua).
+
+   Uma task cujo domínio não bate com nenhuma persona registrada (ex.: task pura de config/docs) fica sem `agent` — `morph-implement` cai no fallback de Read de `agents.json` nesse caso.
 
    **O `doneCriteria` carrega a pós-condição LITERAL.** Este é o elo que amarra a cadeia inteira: a pós-condição escrita em linguagem de negócio chega **sem tradução** ao critério que o `morph-spec verify` e o `morph-eval` cobram. Copie o texto da pós-condição, prefixado pelo seu rótulo (`"P2 — Cada veterinário traz..."`). Reescrever com outras palavras aqui é exatamente o ponto em que o requisito se perde hoje.
 
@@ -193,7 +197,7 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
 - `.morph/features/{feature}/2-plan/usecases/UC-{nn}-{slug}.md` — um arquivo por use case, com pós-condições testáveis
 - `.morph/features/{feature}/2-plan/spec.md` — especificação técnica completa
 - `.morph/features/{feature}/2-plan/mandate.md` — contrato de implementação
-- `.morph/features/{feature}/2-plan/tasks.json` — task list estruturada válida contra schema, com o `doneCriteria` carregando a pós-condição literal
+- `.morph/features/{feature}/2-plan/tasks.json` — task list estruturada válida contra schema, com o `doneCriteria` carregando a pós-condição literal e, por task, `agent`/`standards` carimbados a partir de `agents.json` (passo 5a)
 - Gate 2 registrado aprovado em `.morph/features/{feature}/feature.json` (autoritativo)
 
 Ao registrar a aprovação do Gate 2, atualize o frontmatter de cada use case de `status: draft` para `status: approved`. O ciclo fecha na integração: `morph-spec finish` promove os use cases para o acervo permanente `.morph/specs/usecases/` já com `status: implemented`. O status é **descritivo** — quem trava fase é o gate, não este campo.
@@ -202,6 +206,7 @@ Ao registrar a aprovação do Gate 2, atualize o frontmatter de cada use case de
 
 - `.morph/framework/MORPH.md` — seções 2 (Fases), 3 (Contratos de Output), 5 (Gates), Trust Mode
 - `.morph/framework/standards/STANDARDS.json` — para identificar standards relevantes ao mandate
+- `.morph/framework/agents.json` — personas por domínio; lido UMA VEZ no passo 5a para carimbar `agent`/`standards` por task
 - `.morph/framework/schemas/tasks.schema.json` — schema obrigatório de tasks.json
 - `.morph/specs/usecases/` — acervo permanente de use cases do projeto (leia antes de numerar; em `bug`, é onde mora o UC a corrigir)
 - `.morph/features/{feature}/0-proposal/proposal.md` — escopo da feature

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

@@ -4,7 +4,7 @@ description: Orquestra a fase de proposta+plano de uma feature morph-spec. Encad
 version: core
 when-to-invoke: ao receber instrução "use /morph-proposal" do usuário, ou ao iniciar uma nova feature
 user-invokable: true
-cliVersion: "8.16.0"
+cliVersion: "8.18.0"
 ---
 
 # morph-proposal

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

@@ -4,7 +4,7 @@ description: Conduz a fase de revisão e produz o review-report.md para o Gate 3
 version: core
 when-to-invoke: ao iniciar a fase review, após todas as tasks de tasks.json estarem com status `done`
 user-invokable: true
-cliVersion: "8.16.0"
+cliVersion: "8.18.0"
 ---
 
 # morph-review

package/framework/skills/core/morph-stack-scan/SKILL.md

@@ -4,7 +4,7 @@ description: Varre o codebase existente, detecta stack atual, compara com o stac
 version: core
 when-to-invoke: ao iniciar uma feature em projeto brownfield (codebase já existente)
 user-invokable: true
-cliVersion: "8.16.0"
+cliVersion: "8.18.0"
 ---
 
 # morph-stack-scan
@@ -17,19 +17,7 @@ Quando o projeto já tem código existente e você precisa entender o estado atu
 
 ## Stack padrão de referência
 
-| Camada | Esperado |
-|--------|----------|
-| Runtime | .NET 10 |
-| Arquitetura | VSA — feature-folder: `{Feature}/` com Handler, Validator, Endpoint, Errors, Tests |
-| ORM | EF Core + Neon (Postgres) |
-| IDs | `Guid.CreateVersion7()` |
-| Classes | `sealed` por padrão |
-| Erros | Result pattern (`result.Match()`), não exceptions não tratadas |
-| IA | Microsoft Agent Framework (MAF) |
-| Frontend | Next.js App Router + Tailwind + Framer Motion + Shadcn |
-| Jobs | Hangfire (apenas quando necessário) |
-
-**Padrões proibidos:** `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`), SQL cru sem justificativa. Acesso a dados em VSA: `ApplicationDbContext` direto no slice (`DbSet<T>` já é repository, `DbContext` já é unit of work); para concorrência ou SQL específico, store dedicado hand-written com justificativa em `decisions.md`.
+O "Esperado" da comparação do passo 2 é o stack baked-in (runtime .NET 10 + VSA, EF Core/Neon, `Guid.CreateVersion7()`, `sealed`, result pattern, MAF, Next.js/Tailwind/Shadcn, Hangfire) e a lista de padrões proibidos (`Guid.NewGuid()`, classes não-sealed, Service/Manager layer, repository genérico, SQL cru sem justificativa) — regra canônica em `MORPH.md` § "Stack baked-in". Os templates de `stack-scan.md` abaixo (greenfield e brownfield) escrevem essa lista por extenso no artefato da feature, para que quem ler o `stack-scan.md` depois não precise reabrir o `MORPH.md`.
 
 ## Greenfield short-circuit
 

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

@@ -4,7 +4,7 @@ description: Localiza e carrega um standard específico do STANDARDS.json sob de
 version: core
 when-to-invoke: quando precisar consultar um standard específico durante a implementação
 user-invokable: true
-cliVersion: "8.16.0"
+cliVersion: "8.18.0"
 ---
 
 # morph-standards

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "8.16.0",
+  "version": "8.18.0",
   "description": "MORPH-SPEC: NLH (Natural Language Harness) for spec-driven development with Claude Code",
   "keywords": [
     "claude-code",
@@ -45,7 +45,7 @@
     "generate:check": "node scripts/generate-refs.js --check",
     "generate-standards": "node scripts/generate-standards-registry.js",
     "generate-standards:check": "node scripts/generate-standards-registry.js --check",
-    "validate": "node scripts/validate-framework.js",
+    "validate": "node scripts/validate-framework.js && node scripts/check-rubric-parity.js",
     "freshness": "node scripts/check-freshness.js",
     "verify": "npm run generate:check && npm run generate-standards:check && npm run validate && npm run freshness && npm test",
     "test": "node scripts/run-tests.mjs",

package/src/commands/project/doctor.js

@@ -826,13 +826,20 @@ export async function doctorCommand(options = {}) {
     hasErrors = true;
   }
 
-  // Check templates
+  // Check templates — as of the R3 perf plan (Task 2), setup-infra/update no
+  // longer pre-populate .morph/framework/templates/: template resolution is
+  // layered (template-registry.js / architecture-scanner.js resolveTemplatePath)
+  // and falls back to the npm package's own framework/templates/ when the
+  // project-local copy is absent, which is now the expected default rather
+  // than an error. The project-local copy remains a supported override — if
+  // present, report it as such. The "key templates" check further below
+  // verifies the package copy itself is intact, which is the check that
+  // actually matters now.
   const templatesPath = join(morphPath, 'framework', 'templates');
   if (await pathExists(templatesPath)) {
-    checks.push({ name: 'templates/', status: 'ok' });
+    checks.push({ name: 'templates/', status: 'ok', msg: 'local override present' });
   } else {
-    checks.push({ name: 'templates/', status: 'missing' });
-    hasErrors = true;
+    checks.push({ name: 'templates/', status: 'ok', msg: 'resolved from package (no local override)' });
   }
 
   // Check .claude folder

package/src/commands/project/init.js

@@ -486,7 +486,7 @@ export async function initCommand(options) {
     logger.info('Files installed:');
     logger.dim(`  ✓ CLAUDE.md`);
     logger.dim(`  ✓ .morph/config/ (config.json)`);
-    logger.dim(`  ✓ .morph/framework/ (agents.json, standards/, templates/, hooks/)`);
+    logger.dim(`  ✓ .morph/framework/ (agents.json, standards/, hooks/)`);
     logger.dim(`  ✓ .morph/context/ (project context)`);
     logger.dim(`  ✓ .morph/features/ (feature outputs)`);
     if (commandsCopied) {

package/src/commands/project/standards.js

@@ -0,0 +1,220 @@
+/**
+ * `morph-spec standards --find "<query>" [--category <c>] [--tags <a,b>] [--json]`
+ *
+ * Server-side replacement for "read the whole STANDARDS.json to pick 1-3
+ * standards" (R2 of the performance plan — token cut per task). Today
+ * morph-implement loads the full 65 KB / 60-entry registry (with a `digest`
+ * per entry) just to choose a couple of relevant standards: ~16k tokens per
+ * task. This command searches server-side and returns only the TOP 3 hits —
+ * `id · path · digest` — where the digest is the FULL text: it is what
+ * substitutes for actually reading the standard's .md file.
+ *
+ * Without `--find` (a bare call): lists categories + counts — a cheap
+ * orientation view, no scoring.
+ *
+ * A query with no hit exits 0 (this is advisory tooling, not a gate) with a
+ * human-readable warning + category suggestions on stderr, and — under
+ * `--json` — a stable `{ query, results: [], suggestion }` shape on stdout so
+ * a JSON consumer never has to special-case "no results" as a parse error.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+
+/**
+ * Resolve STANDARDS.json the same way doctor.js resolves the standards root:
+ * an installed project first (`.morph/framework/standards/`), falling back
+ * to this package's own bundled copy (`framework/standards/`) — the framework
+ * repo in dev, or the npm package's own copy before `setup-infra` has run.
+ *
+ * @param {string} targetPath - project root to look for `.morph/` under
+ * @returns {string|null} absolute path to STANDARDS.json, or null if neither exists
+ */
+export function resolveStandardsJsonPath(targetPath) {
+  const installed = join(targetPath, '.morph', 'framework', 'standards', 'STANDARDS.json');
+  if (existsSync(installed)) return installed;
+
+  const packageFallback = join(import.meta.dirname, '..', '..', '..', 'framework', 'standards', 'STANDARDS.json');
+  if (existsSync(packageFallback)) return packageFallback;
+
+  return null;
+}
+
+/** Load + parse STANDARDS.json. Throws on missing/invalid file — caller decides how to report it. */
+function loadRegistry(standardsJsonPath) {
+  const raw = readFileSync(standardsJsonPath, 'utf8');
+  return JSON.parse(raw);
+}
+
+/**
+ * category → count, sorted by count desc then name asc.
+ * @param {object[]} standards
+ * @returns {{ category: string, count: number }[]}
+ */
+export function categoryCounts(standards) {
+  const counts = {};
+  for (const std of standards) {
+    const cat = std.category || 'uncategorized';
+    counts[cat] = (counts[cat] || 0) + 1;
+  }
+  return Object.entries(counts)
+    .map(([category, count]) => ({ category, count }))
+    .sort((a, b) => b.count - a.count || a.category.localeCompare(b.category));
+}
+
+/**
+ * Simple weighted relevance score for one standard against a query.
+ * Tiers, as specified: name/id > tags(+aliases) > digest. category/subcategory
+ * ride alongside the tags tier (lighter). A token-level fallback keeps
+ * multi-word queries findable even without a verbatim phrase match anywhere.
+ *
+ * @param {object} std - one STANDARDS.json entry
+ * @param {string} query - raw user query (already trimmed, non-empty)
+ * @returns {number} score, 0 = no match
+ */
+export function scoreStandard(std, query) {
+  const q = query.toLowerCase();
+  const tokens = q.split(/\s+/).filter((t) => t.length >= 3);
+
+  const name = String(std.name || '').toLowerCase();
+  const id = String(std.id || '').toLowerCase();
+  const category = String(std.category || '').toLowerCase();
+  const subcategory = String(std.subcategory || '').toLowerCase();
+  const tags = (std.tags || []).map((t) => String(t).toLowerCase());
+  const aliases = (std.aliases || []).map((a) => String(a).toLowerCase());
+  const digest = String(std.digest || '').toLowerCase();
+
+  let score = 0;
+
+  // Tier 1: name / id — the strongest signal.
+  if (id === q || name === q) score += 20;
+  else if (id.includes(q) || name.includes(q)) score += 12;
+
+  // Tier 2: tags / aliases (curated search terms) + category/subcategory.
+  if (tags.includes(q) || aliases.includes(q)) score += 8;
+  else if (tags.some((t) => t.includes(q)) || aliases.some((a) => a.includes(q))) score += 5;
+  if (category === q || subcategory === q) score += 4;
+
+  // Tier 3: digest — weakest signal, full-phrase substring only.
+  if (digest.includes(q)) score += 2;
+
+  // Token-level fallback for multi-word queries with no verbatim match above.
+  for (const tok of tokens) {
+    if (name.includes(tok) || id.includes(tok)) score += 2;
+    if (tags.some((t) => t.includes(tok)) || aliases.some((a) => a.includes(tok))) score += 1;
+    if (digest.includes(tok)) score += 0.5;
+  }
+
+  return score;
+}
+
+/**
+ * Rank standards against a query, applying optional category/tags filters
+ * first. Returns the TOP 3 with score > 0, sorted desc (ties broken by id).
+ *
+ * @param {object[]} standards
+ * @param {string} query
+ * @param {{ category?: string, tags?: string[] }} [filters]
+ * @returns {Array<object & { score: number }>}
+ */
+export function findStandards(standards, query, filters = {}) {
+  const category = filters.category?.toLowerCase();
+  const tags = (filters.tags || []).map((t) => t.toLowerCase());
+
+  let candidates = standards;
+  if (category) {
+    candidates = candidates.filter((s) => String(s.category || '').toLowerCase() === category);
+  }
+  if (tags.length) {
+    candidates = candidates.filter((s) =>
+      (s.tags || []).some((t) => tags.includes(String(t).toLowerCase())));
+  }
+
+  return candidates
+    .map((s) => ({ ...s, score: scoreStandard(s, query) }))
+    .filter((s) => s.score > 0)
+    .sort((a, b) => b.score - a.score || String(a.id).localeCompare(String(b.id)))
+    .slice(0, 3);
+}
+
+/** Parse `--tags a,b,c` into a trimmed, non-empty array. */
+function parseTagsOption(raw) {
+  if (!raw) return [];
+  return String(raw).split(',').map((t) => t.trim()).filter(Boolean);
+}
+
+/**
+ * @param {{ find?: string, category?: string, tags?: string, json?: boolean, cwd?: string }} [options]
+ */
+export function standardsCommand(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const standardsJsonPath = resolveStandardsJsonPath(cwd);
+
+  if (!standardsJsonPath) {
+    console.error(chalk.red('\n❌ STANDARDS.json não encontrado — nem em .morph/framework/standards/ nem no pacote.'));
+    console.error(chalk.gray('   Rode `morph-spec setup-infra` (projeto instalado) ou verifique framework/standards/ (repo do framework).\n'));
+    process.exit(1);
+  }
+
+  let registry;
+  try {
+    registry = loadRegistry(standardsJsonPath);
+  } catch (err) {
+    console.error(chalk.red(`\n❌ STANDARDS.json inválido em ${standardsJsonPath}: ${err.message}\n`));
+    process.exit(1);
+  }
+
+  const standards = Array.isArray(registry.standards) ? registry.standards : [];
+  const query = (options.find || '').trim();
+
+  // ── Bare call (no --find): categories + counts, cheap orientation ────────
+  if (!query) {
+    const counts = categoryCounts(standards);
+    if (options.json) {
+      console.log(JSON.stringify({ total: standards.length, categories: counts }));
+      process.exit(0);
+    }
+    console.log(chalk.bold(`\nSTANDARDS.json — ${standards.length} standards, ${counts.length} categorias\n`));
+    const col = (s, w) => String(s).padEnd(w);
+    for (const { category, count } of counts) {
+      console.log(`  ${col(category, 20)}${count}`);
+    }
+    console.log(chalk.gray('\nUse --find "<query>" para buscar (top 3, com digest completo).\n'));
+    process.exit(0);
+  }
+
+  // ── --find: score + filter ────────────────────────────────────────────
+  const filters = { category: options.category, tags: parseTagsOption(options.tags) };
+  const results = findStandards(standards, query, filters);
+
+  if (!results.length) {
+    const counts = categoryCounts(standards);
+    if (options.json) {
+      console.log(JSON.stringify({ query, results: [], suggestion: { categories: counts } }));
+      process.exit(0);
+    }
+    console.error(chalk.yellow(`\n⚠️  Nenhum standard encontrado para "${query}".`));
+    console.error(chalk.gray('   Categorias disponíveis: ' +
+      counts.map((c) => `${c.category} (${c.count})`).join(', ') + '\n'));
+    process.exit(0);
+  }
+
+  const shaped = results.map((r) => ({
+    id: r.id, name: r.name, path: r.path, category: r.category, digest: r.digest, score: r.score,
+  }));
+
+  if (options.json) {
+    console.log(JSON.stringify({ query, results: shaped }));
+    process.exit(0);
+  }
+
+  console.log(chalk.bold(`\nTOP ${shaped.length} para "${query}"\n`));
+  shaped.forEach((r, i) => {
+    console.log(chalk.cyan(`${i + 1}. ${r.id}`) + chalk.gray(`  (${r.category})`));
+    console.log(`   ${r.path}`);
+    console.log(chalk.gray(`   ${r.digest}`));
+    console.log('');
+  });
+  process.exit(0);
+}

package/src/commands/project/update.js

@@ -24,7 +24,8 @@ import {
   checkProjectOutdated,
   saveProjectMorphVersion,
   getUpdateInstructions,
-  detectInstallMethod
+  detectInstallMethod,
+  compareVersions
 } from '../../utils/version-checker.js';
 import { installClaudeHooks, installGlobalStatusline } from '../../utils/claude-settings-manager.js';
 import { installSkills } from '../../utils/skills-installer.js';
@@ -59,7 +60,12 @@ async function backupUserConfig(morphPath) {
 async function cleanFrameworkDirs(morphPath, targetPath) {
   const claudeDir = join(targetPath, '.claude');
   const dirsToClean = [
-    join(morphPath, 'framework', 'templates'),
+    // NOTE: framework/templates is intentionally NOT in this list (R3 perf
+    // plan, Task 2). It's no longer copied/refreshed here — see
+    // reconcileLegacyTemplatesCopy() below, which decides per-run whether a
+    // pre-existing local copy is safe to remove or must be preserved as a
+    // user override. Blindly deleting it here (the old behavior) destroyed
+    // any customization on every single `update` run, override or not.
     join(morphPath, 'framework', 'standards'),
     join(morphPath, 'framework', 'hooks'),
     join(morphPath, 'framework', 'schemas'),
@@ -83,6 +89,67 @@ async function cleanFrameworkDirs(morphPath, targetPath) {
   }
 }
 
+/**
+ * Last CLI version whose `update`/`setup-infra` still wrote
+ * `.morph/framework/templates/` unconditionally, before Task 2 of the R3
+ * perf plan removed that copy. Used as the decision boundary in
+ * `reconcileLegacyTemplatesCopy` below — see its doc comment for why a
+ * version check is used instead of diffing file content.
+ */
+const LAST_VERSION_THAT_COPIED_TEMPLATES = '8.17.0';
+
+/**
+ * Reconcile a pre-existing `.morph/framework/templates/` copy now that
+ * `update` no longer writes it (Task 2, R3 perf plan — resolution falls
+ * back to the npm package's own framework/templates/, see
+ * template-registry.js / architecture-scanner.js's layered resolver).
+ *
+ * Decided from the project's PRIOR recorded CLI version (before THIS
+ * update writes a new one), not by diffing content against the package.
+ * A content diff can't tell "stale copy from an older CLI version" apart
+ * from "deliberate user override" — and staleness is the dominant case for
+ * anyone who actually runs `update`, since template content does change
+ * between releases. The version boundary is unambiguous instead:
+ *
+ *   - No local copy → nothing to do.
+ *   - Prior version is unrecorded, OR <= LAST_VERSION_THAT_COPIED_TEMPLATES
+ *     → the copy could ONLY have been put there by the OLD installer:
+ *     `.morph/framework/**` is Edit-denied to the agent (MORPH_DENY in
+ *     hooks-installer.js — "installer-managed, immutable at runtime"),
+ *     the directory is gitignored, and every `update` before this fix
+ *     unconditionally wiped + recopied it. There is no path by which a
+ *     project on an old version could have a genuine override sitting
+ *     here. Safe to delete unconditionally — it is dead weight, not data.
+ *   - Prior version > LAST_VERSION_THAT_COPIED_TEMPLATES → `update` and
+ *     `setup-infra` have never written this directory for this project.
+ *     Anything found here was placed deliberately (by the user or other
+ *     tooling) — this is the forward-looking override use case the
+ *     layered resolver exists for. Preserve untouched, unconditionally,
+ *     with no diffing.
+ *
+ * @param {string} templatesDest - .morph/framework/templates (may not exist)
+ * @param {string|null} priorProjectVersion - project's recorded morph-spec
+ *   version BEFORE this update run (checkProjectOutdated().current)
+ * @returns {'absent'|'removed-legacy'|'preserved-override'}
+ */
+export function reconcileLegacyTemplatesCopy(templatesDest, priorProjectVersion) {
+  if (!existsSync(templatesDest)) return 'absent';
+
+  const isLegacy = !priorProjectVersion
+    || compareVersions(priorProjectVersion, LAST_VERSION_THAT_COPIED_TEMPLATES) <= 0;
+
+  if (!isLegacy) return 'preserved-override';
+
+  try {
+    fs.removeSync(templatesDest);
+    return 'removed-legacy';
+  } catch {
+    // Couldn't remove — don't risk a half-broken state; leave it and let
+    // the layered resolver's override-first check pick it up as before.
+    return 'preserved-override';
+  }
+}
+
 /**
  * Restore user's config.json after reinstallation
  * @param {string} morphPath - Path to .morph directory
@@ -240,12 +307,14 @@ export async function updateCommand(options) {
     const updateTemplates = !options.standards || options.templates;
     const updateStandards = !options.templates || options.standards;
 
-    // Update templates
+    // Templates are no longer copied to .morph/framework/templates/ (Task 2,
+    // R3 perf plan) — see reconcileLegacyTemplatesCopy()'s doc comment for
+    // why. Only reconcile a leftover copy from a pre-R3 install.
+    let templatesReconcile = 'absent';
     if (updateTemplates) {
-      updateSpinner.text = 'Updating templates...';
-      const templatesSrc = join(contentDir, 'framework', 'templates');
+      updateSpinner.text = 'Checking for a legacy templates copy...';
       const templatesDest = join(morphPath, 'framework', 'templates');
-      await copyDirectory(templatesSrc, templatesDest);
+      templatesReconcile = reconcileLegacyTemplatesCopy(templatesDest, projectCheck.current);
     }
 
     // Update standards
@@ -289,6 +358,13 @@ export async function updateCommand(options) {
         await copyDirectory(src, join(morphPath, 'framework', dir));
       }
     }
+    // CLI.md vive em framework/docs/ na fonte mas instala achatado em
+    // .morph/framework/CLI.md (o CLAUDE.md residente aponta para lá) —
+    // por isso não entra no loop de nomes acima.
+    const cliMdSrc = join(canonicalFrameworkDir, 'docs', 'CLI.md');
+    if (await pathExists(cliMdSrc)) {
+      await copyFile(cliMdSrc, join(morphPath, 'framework', 'CLI.md'));
+    }
 
     // Regenerate derived files (phase-utils.js, skill output tables) from output-schema.js
     // Only runs when the generator script is present (framework dev installs via npm link)
@@ -415,7 +491,15 @@ export async function updateCommand(options) {
 
     logger.blank();
     logger.info('Updated files:');
-    if (updateTemplates) logger.dim('  ✓ .morph/framework/templates/');
+    if (updateTemplates) {
+      if (templatesReconcile === 'removed-legacy') {
+        logger.dim('  ✓ .morph/framework/templates/ (legacy installer copy removed — resolved from package)');
+      } else if (templatesReconcile === 'preserved-override') {
+        logger.dim('  ⚠ .morph/framework/templates/ (local override present — preserved untouched, not updated)');
+      } else {
+        logger.dim('  · .morph/framework/templates/ (not present — resolved from package, no local override)');
+      }
+    }
     if (updateStandards) logger.dim('  ✓ .morph/framework/standards/');
     logger.dim('  ✓ .morph/framework/hooks/');
     logger.dim('  ✓ .morph/framework/agents.json');

package/src/lib/stack-filter.js

@@ -16,10 +16,15 @@ export function parseStacks(content) {
 
   const fm = fmMatch[1];
 
-  // Try inline format: stacks: [dotnet, blazor]
+  // Try inline format: stacks: [dotnet, blazor] — quotes stripped like the
+  // list branch below; `["umbraco"]` sem isso parseava como a string literal
+  // `"umbraco"` (com aspas) e nunca casava tag nenhuma.
   const inlineMatch = fm.match(/^stacks:\s*\[([^\]]*)\]/m);
   if (inlineMatch) {
-    const items = inlineMatch[1].split(',').map(s => s.trim()).filter(Boolean);
+    const items = inlineMatch[1]
+      .split(',')
+      .map(s => s.replace(/["']/g, '').trim())
+      .filter(Boolean);
     return items.length > 0 ? items : ['*'];
   }
 

package/src/lib/tasks/tasks-json-parser.js

@@ -87,6 +87,32 @@ export function validateTasksJson(data) {
     if (task.usecase !== undefined && (typeof task.usecase !== 'string' || !USECASE_RE.test(task.usecase))) {
       errors.push(`${ctx}.usecase must match /^UC-\\d+$/ (the ID alone, e.g. "UC-07")`);
     }
+
+    // Optional: morph-plan may stamp a persona + standards per task (R2 token
+    // cut — `morph-spec standards --find` replaces reading the whole
+    // STANDARDS.json). Both are part of the plan contract and frozen after
+    // Gate 2 by protect-spec-files (any key outside MUTABLE_SPEC_FIELDS is
+    // blocked by construction — see that hook's top comment). Type-check
+    // only here: no cross-check against agents.json, since stack-filtered
+    // installs carry fewer personas than the full set and would false-fail.
+    if (task.agent !== undefined) {
+      if (typeof task.agent !== 'string' || !task.agent.trim()) {
+        errors.push(`${ctx}.agent must be a non-empty string (persona id, e.g. "dotnet-senior")`);
+      } else if (task.agent.startsWith('morph-')) {
+        errors.push(`${ctx}.agent must be the bare persona id — no "morph-" prefix (got "${task.agent}")`);
+      }
+    }
+    if (task.standards !== undefined) {
+      if (!Array.isArray(task.standards)) {
+        errors.push(`${ctx}.standards must be an array of paths`);
+      } else {
+        task.standards.forEach((s, i) => {
+          if (typeof s !== 'string' || !s.trim()) {
+            errors.push(`${ctx}.standards[${i}] must be a non-empty string path`);
+          }
+        });
+      }
+    }
   }
 
   return { valid: errors.length === 0, errors };

package/src/scripts/setup-infra.js

@@ -264,14 +264,23 @@ export async function setupInfra(targetPath, { _exec = execSync, reinstall = fal
     await writeFile(contextReadmePath, readmeContent);
   }
 
-  // --- 5. Copy framework/templates → .morph/framework/templates ---
-  log('Step 5: Copying framework templates...');
-  const frameworkTemplatesSrc = join(FRAMEWORK_DIR, 'templates');
-  const templatesDest = join(frameworkDestDir, 'templates');
-  if (await pathExists(frameworkTemplatesSrc)) {
-    await copyDirectory(frameworkTemplatesSrc, templatesDest);
-  } else {
-    await ensureDir(templatesDest);
+  // --- 5. framework/templates is intentionally NOT copied to
+  // .morph/framework/templates anymore (R3 perf plan, Task 2). Template
+  // resolution is layered (template-registry.js, architecture-scanner.js
+  // resolveTemplatePath): a project-local .morph/framework/templates/{path}
+  // is still checked FIRST as an explicit override, then falls back to the
+  // npm package's own framework/templates/ — which is what every template
+  // actually rendered from until now anyway, since the installed copy was
+  // never read as anything but that override. Pre-populating it was a
+  // byte-for-byte redundant 348KB copy on every install/update.
+  log('Step 5: Skipping framework templates copy (resolved from package; local override still supported)...');
+  // Cópia legada de instalação pré-R3: se existir, ela SOMBREIA os templates
+  // do pacote (override-first). O `morph-spec update` reconcilia (remove cópia
+  // stale por fronteira de versão); aqui só avisamos — init não conhece a
+  // versão anterior do projeto para decidir com segurança.
+  const legacyTemplatesDir = join(frameworkDestDir, 'templates');
+  if (await pathExists(legacyTemplatesDir)) {
+    log('  ⚠ .morph/framework/templates/ existe (instalação antiga) e tem precedência sobre os templates do pacote — rode `morph-spec update` para reconciliar, ou apague se não for customização sua.');
   }
 
   // --- 6. Copy framework/standards → .morph/framework/standards ---
@@ -324,6 +333,16 @@ export async function setupInfra(targetPath, { _exec = execSync, reinstall = fal
     await copyFile(morphMdSrc, morphMdDest);
   }
 
+  // --- 8b2. Copy framework/docs/CLI.md → .morph/framework/CLI.md ---
+  // Referência completa dos comandos (flags, semântica, exemplos) — o
+  // CLAUDE.md residente carrega só a tabela compacta e aponta para cá.
+  log('Step 8b2: Copying CLI.md (command reference)...');
+  const cliMdSrc = join(FRAMEWORK_DIR, 'docs', 'CLI.md');
+  const cliMdDest = join(frameworkDestDir, 'CLI.md');
+  if (await pathExists(cliMdSrc)) {
+    await copyFile(cliMdSrc, cliMdDest);
+  }
+
   // --- 8c. Copy framework/phases.json → .morph/framework/phases.json ---
   log('Step 8c: Copying phases.json...');
   const phasesSrc = join(FRAMEWORK_DIR, 'phases.json');