@polymorphism-tech/morph-spec 8.20.0 → 8.21.0

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.20.0"
+cliVersion: "8.21.0"
 ---
 
 # morph-review
@@ -98,7 +98,8 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
 
 7. **NÃO finalize o trace manualmente.** O hook `trace-autogen` gera e finaliza `.morph/traces/YYYY-MM-DD-{feature}-implement.json` automaticamente (incl. `phase_summary` e `completed_at`) no último write de `tasks.json` — quando a última task sai de `pending`/`in_progress`. Se o trace parecer desatualizado, a causa é um `morph-spec score` faltante ou um recap sem o bloco da task — corrija a fonte, não o trace.
 
-8. Apresente o Gate 3 segundo trust mode.
+8. Apresente o Gate 3 segundo trust mode — **única apresentação do gate**: `morph-apply` §5 aponta
+   para cá em vez de duplicar; ao devolver o controle a ela, o gate já está decidido.
 
    Rode `morph-spec gate-check {feature} review [--json]` — lê `trust` de `.morph/config/config.json`, decide via `shouldPauseGate` e persiste `gateDecisions.review` com timestamp server-side, imprimindo `pause`/`reason`/`signals`. É o default — não recompute a tabela do MORPH.md §5 em linguagem natural.
 
@@ -109,7 +110,7 @@ e o `recap.md` estar atualizado. Normalmente invocada pela skill orquestradora `
 
    Julgamento do revisor que nenhuma dessas chaves representa: use `gate-decision` direto em vez de `gate-check`.
 
-   **Nunca edite `feature.json` à mão** (colide com o hook state-sync). Os caminhos acima gravam no mesmo lugar; o hook `gate-guard.js` confere depois se a ação bateu com a decisão persistida.
+   **Nunca edite `feature.json` à mão** (colide com o hook state-sync — erro "file modified since read"). Os caminhos acima gravam no mesmo lugar; o hook `gate-guard.js` confere depois se a ação bateu com a decisão persistida.
 
    **Se `pause === true`**, use `AskUserQuestion`:
 

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.20.0"
+cliVersion: "8.21.0"
 ---
 
 # morph-stack-scan

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

@@ -1,17 +1,18 @@
 ---
 name: morph-standards
-description: Localiza e carrega um standard específico do STANDARDS.json sob demanda
+description: Localiza um standard específico via busca server-side (morph-spec standards --find) e carrega só o necessário
 version: core
 when-to-invoke: quando precisar consultar um standard específico durante a implementação
 user-invokable: true
-cliVersion: "8.20.0"
+cliVersion: "8.21.0"
 ---
 
 # morph-standards
 
 ## Objetivo
-Encontrar o standard certo para a situação atual e carregar apenas esse arquivo no contexto.
-Nunca carregue todos os standards — o custo de token não compensa.
+Encontrar o standard certo para a situação atual e carregar apenas o necessário no contexto.
+Nunca abra o `STANDARDS.json` inteiro (65 KB) — a busca server-side já devolve o suficiente
+para aplicar o standard na maioria dos casos.
 
 ## Quando invocar
 Quando durante a implementação surgir uma dúvida de padrão arquitetural, de contrato, de qualidade
@@ -19,21 +20,33 @@ ou de teste — e o mandate.md não for suficiente para resolver.
 
 ## O que fazer
 
-1. Abra `framework/standards/STANDARDS.json`.
+1. Rode a busca server-side — é O caminho, não uma opção entre várias:
+   ```
+   morph-spec standards --find "<domínio/tecnologia da task>" [--category <cat>] [--tags <a,b>] [--json]
+   ```
+   Devolve o **top 3** como `id · path · digest` — o `digest` é o texto completo do standard;
+   na maioria dos casos ele já basta para aplicar o padrão, sem abrir o `.md`.
 
-2. Filtre por `category` primeiro (valores típicos: "architecture", "contracts", "testing", "frontend", "backend").
+2. Se dois resultados parecerem relevantes e houver conflito, adote o mais específico ao stack
+   do projeto. Registre o conflito no `decisions.md` da feature.
 
-3. Dentro da categoria, filtre por `tags` que correspondam ao stack do projeto
-   (ex: "dotnet", "nextjs", "blazor", "typescript").
+3. Abra o arquivo `.md` do standard (campo `path`) só quando o `digest` não bastar para resolver
+   a dúvida — ex.: precisa de um exemplo de código completo ou de uma seção que o resumo não cobre.
 
-4. Se dois standards parecerem relevantes e houver conflito, adote o mais específico ao stack.
-   Registre o conflito no `decisions.md` da feature.
+4. Aplique o standard na tarefa atual.
 
-5. Leia o arquivo `.md` do standard selecionado — o path está no campo `path` do JSON.
+5. Registre no `recap.md`: qual standard foi consultado (via `--find`, ou navegação — item abaixo)
+   e como foi aplicado.
 
-6. Aplique o standard na tarefa atual.
+## Fallback — navegação exploratória
 
-7. Registre no `recap.md`: qual standard foi consultado e como foi aplicado.
+`--find` exige uma query. Quando a necessidade é genuinamente exploratória (ex.: "o que existe
+pra categoria X?", sem um termo de busca claro), nesta ordem:
+
+1. `morph-spec standards` sem `--find` — lista categorias + contagem, custo mínimo, o suficiente
+   pra decidir qual `--category` usar num `--find` em seguida.
+2. Só se isso não bastar, abra `framework/standards/STANDARDS.json` inteiro — último recurso,
+   nunca o primeiro passo.
 
 ## Quando não há standard adequado
 Registre no `decisions.md` que nenhum standard cobre o caso.
@@ -41,10 +54,11 @@ Descreva o critério adotado e sinalize para revisão futura.
 Não invente um standard — padrões não documentados são dívida técnica.
 
 ## Output esperado
-- Standard identificado e lido no contexto
+- Standard identificado (via `--find`/digest, ou `.md` completo quando necessário) no contexto
 - Critério de implementação claro para a tarefa atual
 - Entrada no recap.md registrando o standard consultado
 
 ## Referências
-- `framework/standards/STANDARDS.json` — índice completo com id, name, path, category, tags
+- `morph-spec standards --find "<query>" [--category] [--tags] [--json]` — busca server-side, top 3 `id · path · digest`
+- `framework/standards/STANDARDS.json` — índice completo; abrir só como fallback exploratório (ver acima)
 - `framework/MORPH.md` — seção 4 (Como consultar Standards)

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

@@ -4,7 +4,7 @@ description: Conduz a fase opcional de UI/UX — design system, mockups, compone
 version: core
 when-to-invoke: ao tomar o ramo uiux (morph-spec advance --design), depois do Gate 1 e antes do morph-plan
 user-invokable: true
-cliVersion: "8.20.0"
+cliVersion: "8.21.0"
 ---
 
 # morph-uiux
@@ -33,7 +33,7 @@ Ao tomar o ramo opcional uiux: feature/bug cuja mudança cria ou altera superfí
 
 3. **Despache `morph-ui-designer`** para o trabalho visual — dispatch é o default aqui (domínio diferente do Orchestrator, MORPH.md §6). `morph-ui-designer` tem `Read/Write/Edit/Glob/Grep` + MCPs `stitch`/`gemini-image`/`playwright`/`context7`, mas **não tem Bash** — não peça build, testes nem `morph-spec` a ele; isso é do orquestrador.
 
-   **Fallback — caminho normal fora de stack Next.js** (`ui-designer.stack = ["nextjs"]` em `agents.json`, então em qualquer outro stack o subagent não está registrado): `general-purpose` colando o campo `persona` (Read em `.morph/framework/agents.json`) no prompt, registrando o fallback no relatório. Isto não é uma exceção rara — é o caminho normal para projetos não-Next.js.
+   **Persona universal** (`ui-designer.stack = ["*"]` em `agents.json`, mesmo mecanismo de `evaluator`/`scout`): UI/UX importa sempre que há superfície de UI, então o subagent está registrado em **todo** projeto — .NET/Blazor incluído, não só Next.js. **Fallback** (caso raro: instalação anterior a essa mudança, `.claude/agents/morph-ui-designer.md` ainda não regenerado): `general-purpose` colando o campo `persona` (Read em `.morph/framework/agents.json`) no prompt, registrando o fallback no relatório — resolvido rodando `morph-spec setup-infra --reinstall`.
 
    Template do prompt (contrato do relatório em forma curta — copia o padrão de `morph-implement` §4, sem a cláusula de build/isolamento, que não se aplica a um agente sem Bash):
    ```
@@ -93,7 +93,7 @@ Ao tomar o ramo opcional uiux: feature/bug cuja mudança cria ou altera superfí
 
    Aguardar resposta. Se "preciso ajustar", aplicar e reapresentar.
 
-   **Divergência do hook state-sync — só neste gate:** ao contrário de Gate 1/2/3, o hook `state-sync.js` (`gateFromQuestion`) não reconhece o texto "Gate uiux" — uma resposta "aprovado" aqui **não** grava o gate sozinha. Depois do "aprovado", grave explicitamente:
+   **Hook state-sync reconhece este gate, como os demais.** Igual a Gate 1/2/3, o hook `state-sync.js` (`gateFromQuestion`) reconhece o texto "Gate uiux" — uma resposta "aprovado" ao template acima grava sozinha `approvalGates.uiux = { approved: true, timestamp, approvedBy: "manual" }` no `feature.json` autoritativo, atribuído pelo nome da feature que a pergunta cita (MORPH.md §5). Sem nome na pergunta, ou fora de `AskUserQuestion` (headless/CI): aprove explicitamente:
    ```
    morph-spec approve {feature} uiux --approver <quem respondeu>
    # ou, para já aprovar e criar 2-plan/ num passo só:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "8.20.0",
+  "version": "8.21.0",
   "description": "MORPH-SPEC: NLH (Natural Language Harness) for spec-driven development with Claude Code",
   "keywords": [
     "claude-code",

package/src/commands/observability/cost.js

@@ -1,16 +1,26 @@
 /**
- * `morph-spec cost [feature] [--by task|phase] [--json]`
+ * `morph-spec cost [feature] [--by task|phase] [--all-trees] [--json]`
  *
  * A cost-facing view over the same harness event stream `telemetry` reads
  * (.morph/logs/events.jsonl): how much wall-clock time was spent inside
  * measured tasks (TaskStart→TaskEnd), how many context bytes were
  * re-ingested (grouped by kind: rubric/standard/skill/agents/plan-artifact/
  * code), and how many sub-agent dispatches happened (with total prompt
- * chars).
+ * chars). When the stream has `SessionUsage` events (real, hook-observed
+ * token counts), those are summed and shown too — see the sessionUsage
+ * caveat below.
  *
  * IMPORTANT: bytes re-ingested is a DETERMINISTIC PROXY for cost, not a
  * token count. Hooks only see what tools read off disk — never the model's
  * actual token usage — so this measures re-ingestion pressure, not spend.
+ * `sessionUsage` (when present) is the exception: real tokens, observed
+ * directly, not a proxy — see aggregateCost's docstring for the contract.
+ *
+ * `--all-trees` (Furo 3) widens the source from "just the current tree" to
+ * every git worktree that has its own events.jsonl — a fleet running N
+ * features in N worktrees otherwise only ever sees whichever tree `cost` was
+ * run from. Reuses the same worktree enumeration `doctor --worktrees`/`fleet`
+ * use (see loadTelemetryAllTrees in telemetry-reader.js).
  *
  * Read-only, always exits 0 on a normal (even empty) run — fail-open, an
  * empty stream is an answer, not an error. Only `--by` with an unknown value
@@ -18,7 +28,7 @@
  */
 
 import chalk from 'chalk';
-import { loadTelemetry, aggregateCost } from '../../lib/telemetry/telemetry-reader.js';
+import { loadTelemetry, loadTelemetryAllTrees, aggregateCost } from '../../lib/telemetry/telemetry-reader.js';
 
 const BYTES_CAVEAT =
   'Bytes re-ingeridos são um PROXY determinístico de custo (o que as ferramentas leram do disco) — NÃO são tokens reais. Hooks não enxergam o uso real de tokens do modelo.';
@@ -77,6 +87,19 @@ function printPhases(phases) {
   }
 }
 
+/**
+ * Real (hook-observed) token counts, when the stream has `SessionUsage`
+ * events — the non-proxy sibling of the bytes-re-ingested numbers above.
+ * No-op when absent (aggregateCost returns `null`, never a zeroed object).
+ */
+function printSessionUsage(sessionUsage) {
+  if (!sessionUsage) return;
+  console.log('\n' + chalk.white.bold('Tokens reais (sessões observadas)')
+    + chalk.gray(` · ${sessionUsage.sessions} SessionUsage`));
+  console.log(`  input=${sessionUsage.inputTokens}  output=${sessionUsage.outputTokens}  `
+    + `cacheRead=${sessionUsage.cacheReadTokens}  cacheCreation=${sessionUsage.cacheCreationTokens}`);
+}
+
 function printSummary(summary) {
   console.log(`\n  duração dentro de tasks medidas: ${fmtDuration(summary.taskDurationSeconds)}`);
   console.log(`  dispatches: ${summary.dispatches.count} (${summary.dispatches.promptChars} chars de prompt)`);
@@ -88,11 +111,67 @@ function printSummary(summary) {
     console.log('\n' + chalk.white.bold('Mix de tools'));
     for (const t of summary.tools) console.log(`  ${t.name.padEnd(16)} ${t.count}`);
   }
+
+  printSessionUsage(summary.sessionUsage);
+}
+
+/**
+ * `--all-trees` rendering: a short line per tree (so a fleet operator can
+ * spot which tree is expensive) followed by the COMBINED aggregate — full
+ * detail (task/phase breakdown honors `--by` here too, same as the
+ * single-tree path; a typeable flag combination is never a silent no-op).
+ *
+ * @param {string} [feature]
+ * @param {{ json?: boolean, by?: 'task'|'phase' }} options
+ * @param {string} cwd
+ */
+function printAllTrees(feature, options, cwd) {
+  const treesData = loadTelemetryAllTrees(cwd);
+  const perTree = treesData.map(({ tree, path, events }) => ({
+    tree,
+    path,
+    ...aggregateCost(events, { feature }),
+  }));
+  const combined = aggregateCost(treesData.flatMap((t) => t.events), { feature });
+
+  if (options.json) {
+    console.log(JSON.stringify({ allTrees: true, trees: perTree, combined }));
+    return;
+  }
+
+  if (combined.total === 0) {
+    const scope = feature ? ` para a feature "${feature}"` : '';
+    console.log(chalk.gray(`Telemetria vazia${scope} em todas as árvores — nenhuma tem eventos capturados ainda.`));
+    return;
+  }
+
+  console.log(chalk.white.bold(
+    `Custo do harness (proxy determinística) — todas as árvores (${perTree.length} com eventos, ${combined.total} eventos no total)`
+  ));
+  console.log(chalk.gray(`⚠ ${BYTES_CAVEAT}`));
+
+  for (const t of perTree) {
+    console.log('\n' + chalk.cyan.bold(`── Árvore: ${t.tree}`) + chalk.gray(` — ${t.path}`));
+    console.log(`   ${t.total} eventos · duração em tasks: ${fmtDuration(t.taskDurationSeconds)} · `
+      + `bytes: ${fmtBytes(t.bytesTotal)} · dispatches: ${t.dispatches.count}`);
+  }
+
+  console.log('\n' + chalk.white.bold('── Total agregado (todas as árvores)'));
+  if (combined.features.length) {
+    console.log(chalk.gray(`Features: ${combined.features.join(', ')}`));
+  }
+  if (options.by === 'task') {
+    printTasks(combined.tasks);
+  } else if (options.by === 'phase') {
+    printPhases(combined.phases);
+  } else {
+    printSummary(combined);
+  }
 }
 
 /**
  * @param {string} [feature] - narrow to a single feature
- * @param {{ json?: boolean, by?: 'task'|'phase', cwd?: string }} [options]
+ * @param {{ json?: boolean, by?: 'task'|'phase', allTrees?: boolean, cwd?: string }} [options]
  */
 export function costCommand(feature, options = {}) {
   if (options.by && !BY_MODES.includes(options.by)) {
@@ -102,7 +181,16 @@ export function costCommand(feature, options = {}) {
     return;
   }
 
-  const events = loadTelemetry(options.cwd || process.cwd());
+  const cwd = options.cwd || process.cwd();
+
+  if (options.allTrees) {
+    // Same fail-open + Windows-flush discipline as the single-tree path
+    // below — no forced process.exit(), --json included.
+    printAllTrees(feature, options, cwd);
+    return;
+  }
+
+  const events = loadTelemetry(cwd);
   const summary = aggregateCost(events, { feature });
 
   if (options.json) {

package/src/commands/project/update.js

@@ -24,8 +24,7 @@ import {
   checkProjectOutdated,
   saveProjectMorphVersion,
   getUpdateInstructions,
-  detectInstallMethod,
-  compareVersions
+  detectInstallMethod
 } from '../../utils/version-checker.js';
 import { installClaudeHooks, installGlobalStatusline } from '../../utils/claude-settings-manager.js';
 import { installSkills } from '../../utils/skills-installer.js';
@@ -33,6 +32,7 @@ import { installAgents, installDomainAgents } from '../../utils/agents-installer
 import { injectMorphImport } from '../../utils/claude-md-injector.js';
 import { getProjectTags } from '../../lib/stack-filter.js';
 import { updateClaudeMdAgentsBlock, installRulesForStack } from '../../scripts/setup-infra.js';
+import { reconcileLegacyTemplatesCopy } from '../../lib/installers/templates-reconcile.js';
 
 /**
  * Backup user's config.json before cleaning
@@ -89,67 +89,6 @@ 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

package/src/commands/state/gate-check.js

@@ -87,9 +87,12 @@ function evaluatorCompositeScore(cwd, featureName) {
  * never had (it shipped fully tested with zero callers; see the R4 report).
  *
  * `verificationStatus` feeds a real pause rule (verify vermelho pausa —
- * política adicionada em risk-detector.js no fecho do R4); `verification`
- * completo, verificationStale, diffstat e sha seguem como contexto de
- * auditoria persistido, sem regra própria.
+ * política adicionada em risk-detector.js no fecho do R4, qualquer gate).
+ * `verificationStale` também alimenta uma regra própria, mas só no ship
+ * (`gate === 'review'`) — sha do stamp divergindo do HEAD atual. `gate` em si
+ * é o que permite risk-detector.js diferenciar as duas. `verification`
+ * completo, diffstat e sha seguem como contexto de auditoria persistido, sem
+ * regra própria.
  *
  * @param {string} featureName
  * @param {object} feature
@@ -104,6 +107,10 @@ function collectSignals(featureName, feature, cwd, gateName) {
   const verification = feature.verification || null;
 
   const signals = {
+    // Furo 2: disk-derived, never in OVERRIDABLE_SIGNAL_KEYS — a caller
+    // cannot spoof which gate risk-detector.js thinks it is deciding, same
+    // anti-spoof rationale as workType (hotfix's forced pause).
+    gate: gateName,
     workType: feature.workType || 'feature',
     taskCount: tasks.length,
     standardsViolations: [],

package/src/core/templates/template-registry.js

@@ -171,34 +171,6 @@ export function searchTemplates(keyword, projectPath = null) {
   });
 }
 
-/**
- * Get template absolute path with fallback logic.
- *
- * Resolution order:
- *   1. Project-local override (.morph/framework/templates/{path})
- *   2. Framework universal template (framework/templates/{path})
- *
- * @param {string} templateId - Template identifier
- * @param {string} projectPath - Project root path
- * @returns {string|null} Absolute template path or null if not found
- */
-export function resolveTemplatePathById(templateId, projectPath) {
-  const template = getTemplateById(templateId, projectPath);
-  if (!template) {
-    return null;
-  }
-
-  // 1. Project-local override
-  const projectLocalPath = join(projectPath, '.morph/framework/templates', template.path);
-  if (existsSync(projectLocalPath)) {
-    return projectLocalPath;
-  }
-
-  // 2. Framework universal template
-  const frameworkPath = join(projectPath, 'framework/templates', template.path);
-  return existsSync(frameworkPath) ? frameworkPath : null;
-}
-
 /** Absolute path of this repo's own framework/templates/ directory. */
 const FRAMEWORK_TEMPLATES_DIR = join(__dirname, '../../../framework/templates');
 
@@ -206,8 +178,8 @@ const FRAMEWORK_TEMPLATES_DIR = join(__dirname, '../../../framework/templates');
  * Resolve a template id to its absolute path inside THIS framework repo's
  * `framework/templates/` directory — for generators running against the
  * framework itself (scaffold-generator, context-generator), not against an
- * installed `.morph/`. Use resolveTemplatePathById() when a project root and
- * its project-local overrides are in play.
+ * installed `.morph/`. Use architecture-scanner.js's `resolveTemplatePath()`
+ * when a project root and its project-local overrides are in play.
  *
  * @param {string} templateId - Template identifier (REGISTRY.json `id`)
  * @returns {string} Absolute path to the template file

package/src/lib/git/default-branch.js

@@ -112,26 +112,62 @@ function parseShortstat(text) {
   };
 }
 
+/**
+ * Count brand-new UNTRACKED files (never `git add`-ed) — the gap plain
+ * `git diff --shortstat` never sees, tracked-edits-only by design. Fail-open:
+ * any error (not a repo, git missing) reads as 0 untracked, never throws —
+ * this must not take down the whole `getDiffStat` result over a probe that
+ * is secondary to the diff itself.
+ *
+ * `--exclude-standard` matches gitignore the same way `git status` does, so
+ * scratch/build output never inflates the count.
+ *
+ * @param {string} cwd
+ * @returns {number}
+ */
+function countUntrackedFiles(cwd) {
+  try {
+    const out = execFileSync('git', ['ls-files', '--others', '--exclude-standard'], { cwd, stdio: 'pipe' })
+      .toString();
+    return out.split('\n').filter((l) => l.trim()).length;
+  } catch {
+    return 0;
+  }
+}
+
 /**
  * `git diff --shortstat <baseRef>` against the CURRENT WORKING TREE (tracked
  * edits — staged, unstaged, and everything committed since baseRef —
  * deliberately not `baseRef...HEAD`, so a gate-check mid-implement still sees
- * uncommitted work). Same as plain `git diff`, this does NOT count brand-new
- * UNTRACKED files (never `git add`-ed) — a real, known gap if a gate check
- * runs before `git add`; not fixed here since covering it needs `--no-index`
- * or `git add -N` bookkeeping this shared helper doesn't own. Fail-open: null
- * when `baseRef` is falsy, cwd isn't a git repo, or the diff itself fails
- * (e.g. baseRef doesn't resolve).
+ * uncommitted work), PLUS a count of brand-new UNTRACKED files (never
+ * `git add`-ed) that plain `git diff` never shows regardless of commit vs
+ * working tree. `filesChanged` is the combined total (tracked-changed +
+ * untracked) so a caller reading just that one number gets the true scope of
+ * what changed; `untrackedFiles` is broken out separately so a caller that
+ * cares CAN tell diff-vs-new apart instead of the two being silently fused.
+ *
+ * Both git calls run with the same `cwd` — every current caller passes a
+ * feature/worktree root there, so `git diff`'s repo-wide default and
+ * `git ls-files`'s cwd-relative listing agree; a caller passing a
+ * sub-directory as `cwd` would see `untrackedFiles` scoped to that
+ * sub-directory while `insertions`/`deletions` stay repo-wide — not a
+ * concern today, but worth knowing if that assumption ever changes.
+ *
+ * Fail-open: null when `baseRef` is falsy, cwd isn't a git repo, or the diff
+ * itself fails (e.g. baseRef doesn't resolve). The untracked probe fails open
+ * on its own (see countUntrackedFiles) and never turns a good diff into null.
  *
  * @param {string|null} baseRef - typically `detectDefaultBranch(cwd)`
  * @param {string} [cwd]
- * @returns {{ filesChanged: number, insertions: number, deletions: number }|null}
+ * @returns {{ filesChanged: number, insertions: number, deletions: number, untrackedFiles: number }|null}
  */
 export function getDiffStat(baseRef, cwd = process.cwd()) {
   if (!baseRef) return null;
   try {
     const out = execFileSync('git', ['diff', '--shortstat', baseRef], { cwd, stdio: 'pipe' }).toString().trim();
-    return parseShortstat(out);
+    const stat = parseShortstat(out);
+    const untrackedFiles = countUntrackedFiles(cwd);
+    return { ...stat, filesChanged: stat.filesChanged + untrackedFiles, untrackedFiles };
   } catch {
     return null;
   }

package/src/lib/installers/templates-reconcile.js

@@ -0,0 +1,81 @@
+/**
+ * templates-reconcile.js — reconcile a pre-existing `.morph/framework/templates/`
+ * copy against the project's prior recorded morph-spec version.
+ *
+ * Shared by BOTH install paths that can encounter this directory:
+ *   - `morph-spec update` (src/commands/project/update.js) — always knows the
+ *     project's prior version (`checkProjectOutdated().current`, read from
+ *     `.morph/.morphversion` BEFORE this run overwrites it).
+ *   - `morph-spec init`/`setup-infra` (src/scripts/setup-infra.js) — the SAME
+ *     source (`getProjectMorphVersion()`, the function `checkProjectOutdated`
+ *     itself calls), read at the same point in the run (before its own write
+ *     of `.morph/.morphversion`), when it's available — e.g. a repair run
+ *     over an already-initialized project. Falls back to a plain warning when
+ *     it isn't (a project with no recorded version has nothing here for this
+ *     function to reconcile against safely).
+ */
+
+import { existsSync } from 'fs';
+import fs from 'fs-extra';
+import { compareVersions } from '../../utils/version-checker.js';
+
+/**
+ * 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.
+ */
+export const LAST_VERSION_THAT_COPIED_TEMPLATES = '8.17.0';
+
+/**
+ * Reconcile a pre-existing `.morph/framework/templates/` copy now that
+ * neither install path unconditionally writes it anymore (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 run
+ * 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`/`setup-infra` again, 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 install/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 → this install path
+ *     has 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 run (e.g. `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';
+  }
+}