@polymorphism-tech/morph-spec 8.33.0 → 8.35.0

package/src/lib/evaluator-report.js

@@ -15,6 +15,41 @@
  * checagem por `existsSync` puro do `approve` aceitava um relatório SEM o token
  * que o `gate-check` então descartava — o Gate 3 passava carimbado `auto` sobre
  * uma média de auto-avaliação, exatamente o que MORPH.md §5 proíbe.
+ *
+ * ── O TOKEN VIGENTE É O ÚLTIMO ──────────────────────────────────────────────
+ *
+ * O `evaluator-report.md` é APPEND-ONLY por contrato: uma reavaliação acrescenta
+ * ao fim, preservando a análise anterior. Este módulo lia o COMEÇO (`String.match`
+ * com regex sem flag `g`), então num relatório reavaliado o gate era decidido
+ * pelo score SUPERADO. Medido em campo três vezes na mesma epic — #90 (8.7 →
+ * 9.4), #92 (8.2 → 9.0) e #93 (8.9 → 8.3 → 9.1) — e nas três o avaliador teve de
+ * desarmar o token antigo à mão para o gate ler a nota vigente.
+ *
+ * O caso perigoso é o INVERSO e é silencioso: numa reavaliação que BAIXA a nota
+ * (o #93 caiu de 8.9 para 8.3 quando uma correção abriu um bloqueante), o gate
+ * leria a nota antiga, mais alta, e AUTO-PASSARIA o Gate 3 sobre um produto com
+ * bloqueante aberto — a mesma classe de defeito que a v8.26.0 existiu para
+ * fechar, voltando por outra porta: lendo um veredito real, porém vencido.
+ *
+ * DECISÃO EXPLÍCITA — "o último vence", e não "múltiplos tokens viram
+ * `report-ambiguous` e recusam":
+ *
+ *   1. É a semântica do próprio artefato. Append-only significa que o arquivo é
+ *      um LOG, e o valor corrente de um log é a sua última entrada. Ler o
+ *      primeiro não é uma política conservadora — é ler a entrada errada.
+ *   2. Recusar transformaria um veredito REAL e CORRENTE numa pausa que só sai
+ *      editando à mão um arquivo declarado append-only. Isto é exatamente o
+ *      contorno manual que este conserto existe para eliminar, promovido a
+ *      requisito.
+ *   3. Recusar não é mais seguro em nenhum dos dois casos observados: com a nota
+ *      SUBINDO, o humano é obrigado a mexer no relatório para liberar um gate
+ *      que já foi aprovado; com a nota CAINDO, "o último vence" já pausa sozinho
+ *      pela regra de score, que é a razão certa a reportar.
+ *
+ * Ambiguidade não fica silenciosa, ainda assim: `evaluatorReportState` devolve
+ * `scoreTokens` (quantos tokens vivos o arquivo tem) e `superseded` (os valores
+ * anteriores, na ordem do arquivo). Quem consome pode dizer "9.1, terceira
+ * rodada, superando 8.9 e 8.3" em vez de fingir que só havia um veredito.
  */
 
 import { existsSync, readFileSync } from 'fs';
@@ -27,29 +62,133 @@ import { getAbsoluteOutputPath } from '../core/paths/output-schema.js';
  */
 export const COMPOSITE_SCORE_TOKEN = '**Composite-Score:**';
 
-const COMPOSITE_SCORE_RE = /\*\*Composite-Score:\*\*\s*([0-9]+(?:\.[0-9]+)?)/;
+/**
+ * O token das rubricas de PROVA (`.morph/framework/evals/proof-rubrics/`):
+ * `**Proof-Scores:** mutation=9 verde=8 fiacao=9 guard=7 eval=8`. Mesma convenção
+ * literal do Composite-Score de propósito — mesmo arquivo, mesmo módulo leitor,
+ * mesmo estilo de token. Ele pontua a EVIDÊNCIA que o avaliador produziu, nunca
+ * o produto: não entra no composto, impõe teto em `test-coverage`.
+ */
+export const PROOF_SCORES_TOKEN = '**Proof-Scores:**';
+
+/** `g` é obrigatório: o arquivo é append-only e o token vigente é o ÚLTIMO. */
+const COMPOSITE_SCORE_RE = /\*\*Composite-Score:\*\*\s*([0-9]+(?:\.[0-9]+)?)/g;
+
+/** Idem — uma reavaliação reescreve os Proof-Scores acrescentando ao fim. */
+const PROOF_SCORES_RE = /\*\*Proof-Scores:\*\*[ \t]*([^\r\n]*)/g;
+
+/**
+ * A seção de prova de mutação. Exige `##`: um `# Mutações` é outra estrutura
+ * (H1 é título de documento, não seção), e o template que a `morph-review`
+ * entrega ao avaliador gera exatamente `## Mutações`. Aceita a grafia sem
+ * acento porque um relatório escrito em terminal ASCII continua sendo o mesmo
+ * fato — o que não se aceita é o nível errado de cabeçalho.
+ */
+const MUTATION_SECTION_RE = /^##\s+Muta[çc][õo]es\s*$/m;
+
+/**
+ * A seção de prova de MÍDIA. Mesma disciplina do `## Mutações`: exige `##`, e
+ * aceita a grafia sem acento porque um relatório escrito em terminal ASCII
+ * continua sendo o mesmo fato. `Mídia gerada` / `Midia gerada`.
+ */
+const MEDIA_SECTION_RE = /^##\s+M[íi]dia\s+gerada\s*$/m;
+
+/**
+ * As chaves reconhecidas de `**Proof-Scores:**`, uma por rubrica de prova.
+ * Chave fora desta lista é IGNORADA (não vira score, não vira erro): o relatório
+ * é texto de LLM e uma chave inventada não deve nem contaminar nenhum mínimo nem
+ * derrubar a leitura das outras.
+ *
+ * `media` PRECISA estar aqui. Sem isso a rubrica `media-claims.md` seria
+ * decorativa: o avaliador escreveria `media=7` e o número seria descartado em
+ * silêncio, que é o caso "campo publicado sem nenhum leitor".
+ */
+export const PROOF_SCORE_KEYS = ['mutation', 'verde', 'fiacao', 'guard', 'eval', 'media', 'obs'];
+
+/**
+ * As chaves que NÃO entram no `min` de `test-coverage` porque impõem teto em
+ * OUTRA dimensão: `media` (teto em `architecture`) e `obs` (teto em
+ * `code-quality`).
+ *
+ * **`obs` chegou exatamente pelo caminho que o parágrafo abaixo antecipou**, e
+ * vale registrar porque o aviso não bastou. A feature irmã (#94) criou a rubrica
+ * `observabilidade-genai.md`, escreveu `obs=` onze vezes no seu próprio
+ * `evaluator-report.md` — e a chave não estava em `PROOF_SCORE_KEYS`, nem lá nem
+ * na base dela. O parser a descartava em silêncio (ver o `continue` de
+ * `parseProofScores`), então a rubrica nasceu DECORATIVA e atravessou **onze
+ * rodadas de Gate 3** sem que ninguém percebesse: o número era escrito, lido por
+ * um humano no relatório, e nunca chegava ao gate. Só o rebase, que põe as duas
+ * features na mesma árvore, tornou o buraco visível.
+ *
+ * **Isto é uma exclusão, e a forma importa mais que a lista.** A primeira versão
+ * era o inverso — uma lista fechada das quatro chaves que entram. Ela responde
+ * certo hoje e erra sozinha amanhã: a feature irmã acrescenta uma quinta chave
+ * (`eval`) com rubrica própria, e depois do rebase esse `eval=N` cairia do teto
+ * **em silêncio** — o "campo publicado sem nenhum leitor" que este mesmo arquivo
+ * existe para impedir, produzido pela correção.
+ *
+ * Por exclusão, uma chave nova nasce DENTRO do mínimo por padrão, e tirá-la de lá
+ * passa a ser um ato deliberado e visível: uma linha aqui, com a dimensão que ela
+ * limita escrita ao lado. Errar para o lado de "conta no mínimo" custa um teto a
+ * mais; errar para o outro lado devolve o gate cego.
+ *
+ * O motivo de `media` estar fora continua o mesmo: as quatro do mínimo perguntam
+ * "a evidência é real?"; `media` pergunta "a chamada mora no lugar certo? que
+ * estados existem? o que é publicado?". Um `media=4` derrubando o teto de TESTE
+ * seriam dois fatos diferentes lidos como um só.
+ */
+export const NON_MUTATION_PROOF_KEYS = ['media', 'obs'];
+
+/**
+ * As chaves que entram no `min` que impõe teto em `test-coverage`: DERIVADA de
+ * {@link PROOF_SCORE_KEYS} menos {@link NON_MUTATION_PROOF_KEYS} — nunca digitada.
+ * Ver o racional da exclusão acima.
+ */
+export const MUTATION_PROOF_KEYS =
+  PROOF_SCORE_KEYS.filter((k) => !NON_MUTATION_PROOF_KEYS.includes(k));
 
 /** Path canônico do evaluator-report da feature. Fonte única para os dois comandos. */
 export function evaluatorReportPath(cwd, featureName) {
   return getAbsoluteOutputPath(cwd, featureName, 'evaluatorReport');
 }
 
+/** Conteúdo do relatório, ou null quando ausente/ilegível. Nunca lança. */
+function readReport(cwd, featureName) {
+  try {
+    const p = evaluatorReportPath(cwd, featureName);
+    if (!existsSync(p)) return null;
+    return readFileSync(p, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Todos os valores de `**Composite-Score:**` do arquivo, NA ORDEM DO ARQUIVO.
+ * O último é o vigente; os anteriores são rodadas superadas.
+ *
+ * @param {string} text
+ * @returns {number[]}
+ */
+function compositeScoresIn(text) {
+  return [...text.matchAll(COMPOSITE_SCORE_RE)].map((m) => Number(m[1]));
+}
+
 /**
  * Score composto REAL da feature, do token gravado pelo avaliador independente.
  *
+ * Num relatório reavaliado (append-only), é o token do FIM — o veredito
+ * vigente. Ver o bloco "O TOKEN VIGENTE É O ÚLTIMO" no topo do arquivo.
+ *
  * @returns {number|undefined} undefined quando o relatório não existe, não é
  *   legível, ou existe sem o token (relatório legado ou oco). `undefined` é
  *   deliberado e não 0: quem chama distingue "sem veredito" de "veredito ruim".
  */
 export function evaluatorCompositeScore(cwd, featureName) {
-  try {
-    const p = evaluatorReportPath(cwd, featureName);
-    if (!existsSync(p)) return undefined;
-    const m = readFileSync(p, 'utf8').match(COMPOSITE_SCORE_RE);
-    return m ? Number(m[1]) : undefined;
-  } catch {
-    return undefined;
-  }
+  const text = readReport(cwd, featureName);
+  if (text === null) return undefined;
+  const scores = compositeScoresIn(text);
+  return scores.length === 0 ? undefined : scores[scores.length - 1];
 }
 
 /**
@@ -60,13 +199,128 @@ export function evaluatorCompositeScore(cwd, featureName) {
  * "o avaliador rodou mas o relatório está oco — ele não seguiu o contrato";
  * e só o terceiro caso é aprovável.
  *
- * @returns {{ status: 'ok'|'missing'|'untokenized', score?: number, path: string }}
+ * `scoreTokens`/`superseded` só aparecem no caso `ok` e existem para que uma
+ * reavaliação nunca passe silenciosa: o score é o último, mas quem consome sabe
+ * quantas rodadas o arquivo carrega e quais notas foram superadas.
+ *
+ * @returns {{ status: 'ok'|'missing'|'untokenized', score?: number,
+ *   scoreTokens?: number, superseded?: number[], path: string }}
  */
 export function evaluatorReportState(cwd, featureName) {
   const path = evaluatorReportPath(cwd, featureName);
-  if (!existsSync(path)) return { status: 'missing', path };
-  const score = evaluatorCompositeScore(cwd, featureName);
-  return score === undefined
-    ? { status: 'untokenized', path }
-    : { status: 'ok', score, path };
+  const text = readReport(cwd, featureName);
+  if (text === null) return { status: 'missing', path };
+  const scores = compositeScoresIn(text);
+  if (scores.length === 0) return { status: 'untokenized', path };
+  return {
+    status: 'ok',
+    score: scores[scores.length - 1],
+    scoreTokens: scores.length,
+    superseded: scores.slice(0, -1),
+    path,
+  };
+}
+
+/**
+ * Parseia o corpo de UMA linha `**Proof-Scores:**` — pares `chave=N` separados
+ * por espaço.
+ *
+ * @param {string} body
+ * @returns {Record<string, number>|undefined} undefined quando nenhum par
+ *   VÁLIDO foi lido (linha vazia, só chaves desconhecidas, ou só valores
+ *   não-numéricos). `undefined` e não `{}` pela mesma disciplina do
+ *   `evaluatorCompositeScore`: "sem veredito" tem de ser distinguível de
+ *   "veredito vazio".
+ */
+function parseProofScores(body) {
+  const out = {};
+  for (const m of body.matchAll(/([A-Za-zÀ-ÿ][\w-]*)\s*=\s*([^\s]+)/g)) {
+    const key = m[1].toLowerCase();
+    if (!PROOF_SCORE_KEYS.includes(key)) continue;
+    if (!/^[0-9]+(?:\.[0-9]+)?$/.test(m[2])) continue;
+    out[key] = Number(m[2]);
+  }
+  return Object.keys(out).length === 0 ? undefined : out;
+}
+
+/**
+ * Estado de PROVA do relatório: a seção `## Mutações` está lá, e quais
+ * Proof-Scores o avaliador registrou.
+ *
+ * Deriva do disco e não julga: quem decide se a ausência pausa o Gate 3 é
+ * `risk-detector.js` (a divisão "gate-check coleta, risk-detector decide"), e
+ * quem decide o teto é a rubrica `test-coverage.md`. O `min` NÃO é gravado
+ * aqui — é derivado por quem consome, para que exista um só lugar onde
+ * "mínimo de quantas chaves" é definido.
+ *
+ * Arquivo ausente ou ilegível: `{ mutationSection: false, mediaSection: false,
+ * proofScores: undefined }`. Nunca lança, e nunca devolve `0` no lugar de
+ * `undefined`.
+ *
+ * `mediaSection` é lido do MESMO arquivo pelo MESMO módulo, de propósito: uma
+ * segunda leitura do relatório noutro lugar é como duas superfícies passam a
+ * discordar sobre o que ele diz.
+ *
+ * @param {string} cwd
+ * @param {string} featureName
+ * @returns {{ mutationSection: boolean, mediaSection: boolean, proofScores: Record<string, number>|undefined, path: string }}
+ */
+export function evaluatorProofState(cwd, featureName) {
+  const path = evaluatorReportPath(cwd, featureName);
+  const text = readReport(cwd, featureName);
+  if (text === null) {
+    return { mutationSection: false, mediaSection: false, proofScores: undefined, path };
+  }
+
+  // Append-only outra vez: numa reavaliação a linha nova vai para o fim, e é
+  // ela que vale. A primeira linha descreveria a prova de uma rodada superada.
+  const lines = [...text.matchAll(PROOF_SCORES_RE)];
+  const proofScores = lines.length === 0
+    ? undefined
+    : parseProofScores(lines[lines.length - 1][1]);
+
+  return {
+    mutationSection: MUTATION_SECTION_RE.test(text),
+    mediaSection: MEDIA_SECTION_RE.test(text),
+    proofScores,
+    path,
+  };
+}
+
+/**
+ * O menor Proof-Score das provas de EVIDÊNCIA — o que impõe o teto em
+ * `test-coverage`.
+ *
+ * Calculado sobre {@link MUTATION_PROOF_KEYS} — que é
+ * {@link PROOF_SCORE_KEYS} MENOS {@link NON_MUTATION_PROOF_KEYS}, e não uma lista
+ * digitada. `media` responde a outra pergunta e limita outra dimensão
+ * (`architecture`); ler as duas famílias como um mínimo só faria um `media=4`
+ * derrubar o teto de teste sem que nada de teste tivesse acontecido. Uma chave
+ * NOVA de prova entra aqui sozinha: excluí-la exige uma linha deliberada em
+ * `NON_MUTATION_PROOF_KEYS`, e nunca acontece por esquecimento.
+ *
+ * @param {Record<string, number>|undefined} proofScores
+ * @returns {number|null} null quando não há nenhum score do mínimo: SEM TETO A
+ *   APLICAR, jamais "teto 0". A mesma razão pela qual `count: null` do verify
+ *   não é 0.
+ */
+export function minProofScore(proofScores) {
+  if (!proofScores) return null;
+  const values = MUTATION_PROOF_KEYS
+    .map((key) => proofScores[key])
+    .filter((n) => typeof n === 'number' && Number.isFinite(n));
+  return values.length === 0 ? null : Math.min(...values);
+}
+
+/**
+ * O Proof-Score de MÍDIA, lido à parte. Impõe teto em `architecture` (tabela em
+ * `framework/evals/rubrics/architecture.md`, "Tetos de prova de mídia").
+ *
+ * @param {Record<string, number>|undefined} proofScores
+ * @returns {number|null} null quando a chave não foi registrada — o caso normal
+ *   de uma feature que não gera mídia, e nunca "teto 0".
+ */
+export function mediaProofScore(proofScores) {
+  const value = proofScores?.media;
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
 }

package/src/lib/generators/architecture-scanner.js

@@ -20,8 +20,9 @@ import { fileURLToPath } from 'url';
 import { existsSync, readFileSync } from 'fs';
 import { scanGraph } from '../graph/god-nodes.js';
 import { renderTemplate } from '../../core/templates/template-renderer.js';
+import { WORKTREE_DIR_NAMES } from '../worktree/dirs.js';
 
-const SKIP_DIRS = new Set(['node_modules', 'bin', 'obj', '.git', '.morph', '.next', 'dist', 'out', 'worktrees', '.worktrees']);
+export const SKIP_DIRS = new Set(['node_modules', 'bin', 'obj', '.git', '.morph', '.next', 'dist', 'out', ...WORKTREE_DIR_NAMES]);
 const MAX_FILES_PER_SCANNER = 200;
 
 /**

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

@@ -126,12 +126,52 @@ function parseShortstat(text) {
  * @returns {number}
  */
 function countUntrackedFiles(cwd) {
+  return listUntrackedFiles(cwd).length;
+}
+
+/**
+ * Split git's stdout into clean, forward-slashed, non-empty path lines.
+ *
+ * One helper for both probes because the two disagreeing about what a "line" is
+ * — a stray `\r` on Windows, a trailing empty line — would make the count and
+ * the listing describe different sets from the same output.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+function splitLines(text) {
+  return String(text)
+    .split('\n')
+    .map((line) => line.trim().replace(/\\/g, '/'))
+    .filter(Boolean);
+}
+
+/**
+ * The brand-new UNTRACKED files, by NAME — the listing behind
+ * {@link countUntrackedFiles}, and the second half of {@link changedPathsAgainst}.
+ *
+ * The two callers need the same fact at different resolutions, and this is the
+ * ONLY place the probe is spelled: `git diff` never shows a file that was never
+ * `git add`-ed, regardless of ref or working-tree mode, so anything that answers
+ * "what changed" has to ask twice. A second copy of this command is exactly how
+ * the invisible-new-file bug would come back on one caller and not the other.
+ *
+ * `--exclude-standard` honours gitignore the way `git status` does, so build
+ * output never inflates either answer.
+ *
+ * Fail-open to `[]`: this probe is secondary to the diff and must never take the
+ * whole result down.
+ *
+ * @param {string} cwd
+ * @returns {string[]}
+ */
+function listUntrackedFiles(cwd) {
   try {
-    const out = execFileSync('git', ['ls-files', '--others', '--exclude-standard'], { cwd, stdio: 'pipe' })
-      .toString();
-    return out.split('\n').filter((l) => l.trim()).length;
+    return splitLines(
+      execFileSync('git', ['ls-files', '--others', '--exclude-standard'], { cwd, stdio: 'pipe' }).toString()
+    );
   } catch {
-    return 0;
+    return [];
   }
 }
 
@@ -172,3 +212,51 @@ export function getDiffStat(baseRef, cwd = process.cwd()) {
     return null;
   }
 }
+
+/**
+ * Every path this working tree CHANGED against `baseRef` — tracked edits plus
+ * brand-new untracked files.
+ *
+ * WHY IT LIVES BESIDE getDiffStat, AND REUSES ITS UNTRACKED PROBE
+ *
+ * The two answer the same question at different resolutions ("how much changed"
+ * versus "what changed"), and both depend on the SAME fragile fact: `git diff`
+ * is tracked-edits-only, so a brand-new file is invisible to it no matter which
+ * ref is named. `getDiffStat`'s docblock has documented that for a while; a
+ * second copy of the probe here is precisely how the "new file is invisible"
+ * bug comes back on one of the two call sites and not the other. So
+ * `countUntrackedFiles`'s command is not retyped — the listing is.
+ *
+ * `git diff --name-only <baseRef>` against the WORKING TREE, deliberately not
+ * `baseRef...HEAD`: a gate-check in the middle of implement must see work that
+ * is not committed yet. Someone who has only staged the prompt change has still
+ * changed the prompt.
+ *
+ * FAIL-OPEN, and the caller must know what that means. `[]` comes back both for
+ * "nothing changed" and for "the ref did not resolve", exactly like
+ * `getDiffStat` returning null. The distinction that MATTERS to the caller is a
+ * different one — "the project declares no watched path" versus "it declares
+ * some and none were touched" — and that one is answered by the caller's own
+ * `declared` flag, never by the emptiness of this array.
+ *
+ * @param {string|null} baseRef - typically `detectDefaultBranch(cwd)`
+ * @param {string} [cwd]
+ * @returns {string[]} Repo-relative paths with forward slashes, deduplicated,
+ *   sorted. Empty when `baseRef` is falsy, cwd is not a repo, or the diff fails.
+ */
+export function changedPathsAgainst(baseRef, cwd = process.cwd()) {
+  if (!baseRef) return [];
+
+  let tracked;
+  try {
+    tracked = splitLines(
+      execFileSync('git', ['diff', '--name-only', baseRef], { cwd, stdio: 'pipe' }).toString()
+    );
+  } catch {
+    // A baseRef that does not resolve is not a reason to claim "nothing
+    // changed" loudly — the caller's policy is written to be inert on `[]`.
+    return [];
+  }
+
+  return [...new Set([...tracked, ...listUntrackedFiles(cwd)])].sort();
+}

package/src/lib/graph/graphifyignore.js

@@ -17,9 +17,10 @@
  */
 import { writeFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { WORKTREE_DIR_NAMES } from '../worktree/dirs.js';
 
 export const ALWAYS_IGNORED = [
-  '.git/', '.morph/', 'artifacts/', 'worktrees/', '.worktrees/',
+  '.git/', '.morph/', 'artifacts/', ...WORKTREE_DIR_NAMES.map((d) => `${d}/`),
   'coverage/', 'graphify-out/', 'dist/', 'out/',
 ];
 

package/src/lib/installers/effects.js

@@ -0,0 +1,193 @@
+/**
+ * effects.js — o coletor de efeitos ÚNICO do caminho de instalação/atualização.
+ *
+ * A propriedade que faz o `--dry-run` ser honesto está numa frase:
+ *
+ *   > **o caminho real também emite.**
+ *
+ * Em modo normal cada verbo EXECUTA e registra; em `dryRun`, só registra. O
+ * resumo impresso ao fim de uma execução real sai de `list()`, não de
+ * contadores paralelos. A consequência é o ponto: um ponto de emissão
+ * esquecido some das DUAS saídas ao mesmo tempo, e o resumo de uma execução
+ * real fica visivelmente incompleto — o defeito aparece sem sequer usar o
+ * `--dry-run`.
+ *
+ * **Não há segunda travessia.** Nenhum filtro, walker ou lista de payload é
+ * reimplementado aqui. Os filtros que decidem o que instalar
+ * (`shouldInstallSkill`, `agentEligible`, `shouldInstall`) já são puros e
+ * continuam sendo os únicos. O anti-exemplar tem nome e mora neste
+ * repositório: `checkAgentsDrift` funciona como preditor porque re-deriva o
+ * conjunto elegível por conta própria e porque os dois lados chamam o mesmo
+ * renderer puro. Estender essa forma para 9 payloads + hooks + merge de
+ * settings + gitignore + índice do git é reimplementar o instalador inteiro e
+ * depender de disciplina humana para mantê-los sincronizados.
+ *
+ * **Os verbos são SÍNCRONOS de propósito.** Metade dos instaladores que eles
+ * atravessam (`installSkills`, `installAgents`, `installRulesForStack`) é
+ * síncrona; um coletor assíncrono obrigaria a tornar `installRulesForStack`
+ * async e a mudar a assinatura que `setup-infra`, `init` e os testes já usam.
+ *
+ * **O registro é a IDENTIDADE do efeito, nunca o conteúdo.** `writeFile` grava
+ * `{ verb, target }`, não os bytes: `installClaudeHooks` carimba um
+ * `generated_at` a cada execução, e comparar conteúdo faria o canário de
+ * igualdade dry × real reprovar por causa do relógio.
+ */
+
+import fs from 'fs-extra';
+import { spawnSync } from 'node:child_process';
+import { dirname } from 'node:path';
+
+/**
+ * @typedef {Object} Effect
+ * @property {string} verb   - ensureDir | remove | copyDir | copyFile | writeFile | writeJson | mergeJson | spawn | gitIndex
+ * @property {string} target - o caminho (ou comando) sobre o qual o efeito age
+ * @property {string} [from] - origem, para os verbos de cópia
+ * @property {string} [detail] - qualificador estável (argumentos do spawn, operação do git)
+ */
+
+/**
+ * Cria um coletor de efeitos.
+ *
+ * @param {{ dryRun?: boolean }} [options]
+ * @returns {{
+ *   dryRun: boolean,
+ *   ensureDir: (path: string) => void,
+ *   remove: (path: string) => void,
+ *   copyDir: (from: string, to: string) => void,
+ *   copyFile: (from: string, to: string) => void,
+ *   writeFile: (path: string, content: string) => void,
+ *   writeJson: (path: string, data: object) => void,
+ *   mergeJson: (path: string, patch: object) => void,
+ *   spawn: (cmd: string, args: string[], options?: object) => object|null,
+ *   gitIndex: (op: string, path: string, options?: object) => boolean,
+ *   list: () => Effect[],
+ * }}
+ */
+export function createEffects({ dryRun = false } = {}) {
+  /** @type {Effect[]} */
+  const effects = [];
+
+  const record = (verb, target, extra = {}) => {
+    const effect = { verb, target };
+    if (extra.from !== undefined) effect.from = extra.from;
+    if (extra.detail !== undefined) effect.detail = extra.detail;
+    if (extra.args !== undefined) effect.args = extra.args;
+    effects.push(effect);
+    return effect;
+  };
+
+  return {
+    dryRun,
+
+    ensureDir(path) {
+      record('ensureDir', path);
+      if (!dryRun) fs.ensureDirSync(path);
+    },
+
+    remove(path) {
+      record('remove', path);
+      if (!dryRun) fs.removeSync(path);
+    },
+
+    copyDir(from, to, options = {}) {
+      record('copyDir', to, { from });
+      if (!dryRun) fs.copySync(from, to, { overwrite: true, errorOnExist: false, ...options });
+    },
+
+    copyFile(from, to) {
+      record('copyFile', to, { from });
+      if (!dryRun) {
+        fs.ensureDirSync(dirname(to));
+        fs.copySync(from, to, { overwrite: true });
+      }
+    },
+
+    writeFile(path, content) {
+      record('writeFile', path);
+      if (!dryRun) {
+        fs.ensureDirSync(dirname(path));
+        fs.writeFileSync(path, content, 'utf8');
+      }
+    },
+
+    writeJson(path, data) {
+      record('writeJson', path);
+      if (!dryRun) {
+        fs.ensureDirSync(dirname(path));
+        fs.writeJsonSync(path, data, { spaces: 2 });
+      }
+    },
+
+    /**
+     * Leitura + fusão rasa + escrita, como UM efeito.
+     *
+     * A leitura acontece nos dois modos (ler não muda nada); só a escrita é
+     * suprimida em dry. É assim que `~/.claude/settings.json` — um arquivo do
+     * usuário, FORA do projeto — é atualizado sem que o dry o toque.
+     */
+    mergeJson(path, patch) {
+      record('mergeJson', path);
+      if (dryRun) return;
+      let current = {};
+      try {
+        if (fs.existsSync(path)) current = fs.readJsonSync(path);
+      } catch {
+        current = {};
+      }
+      fs.ensureDirSync(dirname(path));
+      fs.writeJsonSync(path, { ...current, ...patch }, { spaces: 2 });
+    },
+
+    /**
+     * @param {string} cmd
+     * @param {string[]} args
+     * @param {{ cwd?: string, dryRunArgs?: string[] }} [options]
+     *   `dryRunArgs` é a variante SÓ-LEITURA do mesmo comando (por exemplo
+     *   `--check`). Em dry ela é executada no lugar; sem ela, nada roda.
+     *   O REGISTRO é o mesmo nos dois modos: o efeito previsto é o comando
+     *   real, não a sua sonda.
+     */
+    spawn(cmd, args = [], options = {}) {
+      // `args` viaja no registro ALÉM do `detail` legível. O `detail` é para
+      // humano; quebrá-lo por espaço para descobrir onde o spawn escreve é o
+      // bug que um caminho como `R:\Polymorphism Tech\...` produz em silêncio,
+      // e que o relatório mostrou pondo um efeito do PACOTE da CLI no grupo
+      // "no projeto".
+      record('spawn', cmd, { detail: args.join(' '), args: [...args] });
+      const { cwd, dryRunArgs } = options;
+      if (dryRun) {
+        if (!dryRunArgs) return null;
+        return spawnSync(cmd, dryRunArgs, { cwd, encoding: 'utf8' });
+      }
+      return spawnSync(cmd, args, { cwd, encoding: 'utf8' });
+    },
+
+    /**
+     * Mutação do índice do git (`git rm --cached`, etc.). A SONDA que decide
+     * se há o que fazer fica fora daqui de propósito: sondar é ler, e ler
+     * acontece nos dois modos.
+     */
+    gitIndex(op, path, options = {}) {
+      record('gitIndex', path, { detail: op });
+      if (dryRun) return true;
+      const result = spawnSync('git', [...op.split(' '), path], {
+        cwd: options.cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'],
+      });
+      return result.status === 0;
+    },
+
+    list() {
+      return effects.map((e) => ({ ...e }));
+    },
+  };
+}
+
+/**
+ * Coletor no-op-de-registro para chamadores que não passam um: executa
+ * normalmente e registra numa lista descartada. Existe para que assinaturas
+ * novas de `installSkills`/`installAgents`/`installRulesForStack` continuem
+ * funcionando para `setup-infra` e `init` sem mudança de comportamento.
+ */
+export function realEffects() {
+  return createEffects({ dryRun: false });
+}

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

@@ -16,8 +16,8 @@
  */
 
 import { existsSync } from 'fs';
-import fs from 'fs-extra';
 import { compareVersions } from '../../utils/version-checker.js';
+import { realEffects } from './effects.js';
 
 /**
  * Last CLI version whose `update`/`setup-infra` still wrote
@@ -62,7 +62,7 @@ export const LAST_VERSION_THAT_COPIED_TEMPLATES = '8.17.0';
  *   version BEFORE this run (e.g. `checkProjectOutdated().current`)
  * @returns {'absent'|'removed-legacy'|'preserved-override'}
  */
-export function reconcileLegacyTemplatesCopy(templatesDest, priorProjectVersion) {
+export function reconcileLegacyTemplatesCopy(templatesDest, priorProjectVersion, fx = realEffects()) {
   if (!existsSync(templatesDest)) return 'absent';
 
   const isLegacy = !priorProjectVersion
@@ -71,7 +71,7 @@ export function reconcileLegacyTemplatesCopy(templatesDest, priorProjectVersion)
   if (!isLegacy) return 'preserved-override';
 
   try {
-    fs.removeSync(templatesDest);
+    fx.remove(templatesDest);
     return 'removed-legacy';
   } catch {
     // Couldn't remove — don't risk a half-broken state; leave it and let