@daniellins/power-claude 0.16.3

package/installer/doctor.js

@@ -0,0 +1,266 @@
+'use strict';
+/**
+ * doctor.js — diagnóstico da instalação POWER CLAUDE no cwd.
+ *
+ * Checa:
+ *   1. Manifest existe e está íntegro (hashes conferem); `frameworkRoot` registrado
+ *      ainda hospeda um `bin/cli.js` (AVISO, nunca FALHA — SF11.1).
+ *   2. Hook registrado no .claude/settings.json (e arquivo do hook presente).
+ *   3. .gitignore cobre .env.
+ *   4. scripts/validate-budgets.js do projeto passa (se pods/ presente).
+ *   5. Estimativa de tokens do .claude/CLAUDE.md (bytes/4) — alerta se > 2.000.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { readManifest, sha256OfFile, frameworkCliPath } = require('./manifest');
+const { motorEntries, ownerInstalled } = require('./motor-scripts');
+
+const CLAUDE_MD_TOKEN_ALERT = 2000;
+
+function check(label, ok, detail) {
+  const mark = ok === true ? 'OK   ' : ok === 'warn' ? 'AVISO' : 'FALHA';
+  console.log(`[${mark}] ${label}${detail ? ` — ${detail}` : ''}`);
+  return ok === true || ok === 'warn';
+}
+
+async function doctor() {
+  const destDir = process.cwd();
+  let allOk = true;
+  console.log(`POWER CLAUDE doctor — ${destDir}\n`);
+
+  // SF10.20 — comandos de correção CONCRETOS. O `doctor` roda a partir do framework,
+  // então `pkgRoot` é fato, não palpite. Nunca prescrever `npx power-claude` nem
+  // `power-claude <cmd>` nu: numa instalação sem package.json/node_modules/PATH, o
+  // primeiro resolve pelo registry público (onde o nome é de um pacote de TERCEIRO)
+  // e o segundo simplesmente não existe. Comando prescrito tem que ser executável.
+  const pkgRoot = path.resolve(__dirname, '..');
+  const frameworkVersion = require(path.join(pkgRoot, 'package.json')).version;
+  const cliPath = frameworkCliPath(pkgRoot);
+  const cmd = (sub) => (cliPath ? `node ${cliPath} ${sub}` : `"${sub}" a partir do repositório do POWER CLAUDE`);
+  const fixCmd = `${cmd('adopt')} && ${cmd('update --scope motor')}`;
+
+  // 1. Manifest
+  let manifest = null;
+  try {
+    manifest = readManifest(destDir);
+  } catch (error) {
+    allOk = check('Manifest legível', false, error.message) && allOk;
+  }
+  if (manifest === null) {
+    allOk = check('Manifest presente (.power-claude/manifest.json)', false, `não encontrado — rode ${cmd('install')}`) && allOk;
+  } else {
+    check('Manifest presente (.power-claude/manifest.json)', true, `versão ${manifest.version}, ${manifest.files.length} arquivos`);
+    let intact = 0;
+    let modified = 0;
+    let missing = 0;
+    for (const entry of manifest.files) {
+      const p = path.join(destDir, ...entry.path.split('/'));
+      if (!fs.existsSync(p)) missing++;
+      else if (sha256OfFile(p) === entry.sha256) intact++;
+      else modified++;
+    }
+    const detail = `${intact} íntegros, ${modified} modificados, ${missing} ausentes`;
+    allOk = check('Integridade dos arquivos do manifest', missing === 0 ? (modified === 0 ? true : 'warn') : false, detail) && allOk;
+
+    // 1b. SF11.1 — guard PROATIVO do `frameworkRoot`.
+    //
+    // O campo é o único elo entre a árvore instalada e o framework (manifest.js): é ele
+    // que faz o comando de correção da SF10.20 sair concreto em vez de placeholder. Como
+    // é registro e não oráculo, envelhece calado — um checkout efêmero (worktree, pasta
+    // temporária) que sumiu depois só se manifesta no pior momento, dentro de uma rodada
+    // já quebrada. Aqui a mesma verificação que `correctionCommand()` faz sob pressão
+    // roda ANTES, fora de banda.
+    //
+    // Nível AVISO, nunca FALHA, deliberadamente: um `frameworkRoot` que não resolve não
+    // degrada nada do que o projeto FAZ (nenhum caminho de execução o consome), e o
+    // próprio `doctor` que reporta o problema já é a prova de que existe um framework
+    // vivo para reancorar. Tratar registro como oráculo transformaria uma instalação
+    // perfeitamente funcional em "doente".
+    const recordedRoot = typeof manifest.frameworkRoot === 'string' ? manifest.frameworkRoot : null;
+    if (!recordedRoot) {
+      check('frameworkRoot do manifest', 'warn', `não registrado (manifest anterior à SF10.20) — rode ${cmd('update --scope motor')} a partir do framework para carimbá-lo`);
+    } else if (frameworkCliPath(recordedRoot)) {
+      check('frameworkRoot do manifest', true, `${recordedRoot} (bin/cli.js presente)`);
+    } else {
+      check(
+        'frameworkRoot do manifest',
+        'warn',
+        `aponta "${recordedRoot}", que não hospeda bin/cli.js — o framework foi movido/apagado. ` +
+        `O comando de correção do motor sai como placeholder até reancorar: rode ${cmd('update --scope motor')} a partir do framework atual`
+      );
+    }
+  }
+
+  // 2. Hook no settings.json
+  const settingsPath = path.join(destDir, '.claude', 'settings.json');
+  const hookPath = path.join(destDir, '.claude', 'hooks', 'enforce-git-push-authority.cjs');
+  if (!fs.existsSync(settingsPath)) {
+    allOk = check('settings.json presente (.claude/settings.json)', false) && allOk;
+  } else {
+    try {
+      const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+      const hasHooks = settings.hooks && typeof settings.hooks === 'object' && Object.keys(settings.hooks).length > 0;
+      const registersEnforce = JSON.stringify(settings.hooks || {}).includes('enforce-git-push-authority');
+      allOk = check('Hooks registrados no settings.json', Boolean(hasHooks), hasHooks ? undefined : 'chave "hooks" ausente ou vazia') && allOk;
+      allOk = check('Hook enforce-git-push-authority registrado', registersEnforce) && allOk;
+
+      // 2b. SF13.2 (`ADR-032` `DF-SF13.2-4`) — acoplamento de distribuição da
+      //     trava de `Ready`. O hook e o validador viajam por canais
+      //     DIFERENTES: `enforce-ready-oracles.cjs` só sabe avaliar os 5
+      //     predicados porque `require`a as funções puras de
+      //     `scripts/validate-story-acs.cjs`. Numa instalação em skew
+      //     (`ADR-019`) o hook chega e o script não — e aí a trava degrada
+      //     para `ask` em TODA transição `Draft`→`Ready`, para sempre. Guard
+      //     que sempre pergunta é guard desligado com uma tecla a mais: a
+      //     checagem existe para que esse `ask` seja transitório e tenha
+      //     conserto nomeado, não crônico.
+      //
+      //     Condicional ao hook estar registrado, de propósito (mesmo
+      //     precedente literal de `Workflows de pod`, :172-177): numa
+      //     instalação sem a trava, exigir o validador seria FALHA inventada.
+      const registersReadyOracles = JSON.stringify(settings.hooks || {}).includes('enforce-ready-oracles');
+      const acValidatorPath = path.join(destDir, 'scripts', 'validate-story-acs.cjs');
+      const READY_ORACLES_LABEL = 'Validador de ACs presente (exigido pela trava de Ready)';
+      if (!registersReadyOracles) {
+        check(READY_ORACLES_LABEL, 'warn', 'hook enforce-ready-oracles.cjs não registrado no settings.json — checagem pulada');
+      } else if (!fs.existsSync(acValidatorPath)) {
+        allOk = check(
+          READY_ORACLES_LABEL,
+          false,
+          `scripts/validate-story-acs.cjs ausente no projeto, mas o hook da trava de Ready está registrado — toda transição Draft→Ready vai pedir aprovação até isto ser resolvido: ${fixCmd}`
+        ) && allOk;
+      } else {
+        allOk = check(READY_ORACLES_LABEL, true, 'scripts/validate-story-acs.cjs presente') && allOk;
+      }
+    } catch (error) {
+      allOk = check('settings.json parseável', false, error.message) && allOk;
+    }
+  }
+  allOk = check('Arquivo do hook presente (.claude/hooks/enforce-git-push-authority.cjs)', fs.existsSync(hookPath)) && allOk;
+
+  // 3. .gitignore cobre .env
+  const gitignorePath = path.join(destDir, '.gitignore');
+  if (!fs.existsSync(gitignorePath)) {
+    allOk = check('.gitignore cobre .env', false, '.gitignore não existe') && allOk;
+  } else {
+    const lines = fs.readFileSync(gitignorePath, 'utf8').split(/\r?\n/).map((l) => l.trim());
+    allOk = check('.gitignore cobre .env', lines.includes('.env')) && allOk;
+  }
+
+  // 4. validate-budgets.js do projeto
+  const budgetScript = path.join(destDir, 'scripts', 'validate-budgets.js');
+  const podsDir = path.join(destDir, 'pods');
+  if (!fs.existsSync(podsDir)) {
+    check('Gate de budgets (pods/)', 'warn', 'pods/ não presente — checagem pulada');
+  } else if (!fs.existsSync(budgetScript)) {
+    allOk = check('Gate de budgets (scripts/validate-budgets.js)', false, 'script não encontrado no projeto') && allOk;
+  } else {
+    const result = spawnSync(process.execPath, [budgetScript], { cwd: destDir, encoding: 'utf8' });
+    const passed = result.status === 0;
+    allOk = check('Gate de budgets passa', passed, passed ? undefined : 'rode "node scripts/validate-budgets.js" para detalhes') && allOk;
+  }
+
+  // 4b. Scripts do motor presentes (ADR-007): um check por entrada do manifest,
+  //     condicional por owner — owner ausente → check pulado (warn); owner
+  //     presente e script ausente → FALHA diagnosticável.
+  for (const { path: rel, owner } of motorEntries()) {
+    if (!ownerInstalled(destDir, owner)) {
+      check(`Motor: ${rel}`, 'warn', `owner ${owner} não instalado — checagem pulada`);
+      continue;
+    }
+    const present = fs.existsSync(path.join(destDir, ...rel.split('/')));
+    allOk = check(`Motor: ${rel}`, present, present ? `owner ${owner}` : `ausente com owner ${owner} presente — rode ${cmd('update --scope motor')}`) && allOk;
+  }
+
+  // 4c. SF10.20 / ADR-019 `DF-SF10.20-4` — detector de skew FORA DE BANDA.
+  //
+  // Fecha o furo de bootstrap do item (1) daquela decisão: uma instalação velha demais
+  // para carregar a mensagem de atribuição nova ainda é diagnosticável por um `doctor`
+  // de framework atual, sem que o dono precise tentar rodar o pod e perder a rodada.
+  //
+  // (i) AVISO de versão — é a ÚNICA comparação de versão de todo o desenho, e vive do
+  //     lado que conhece as DUAS pontas (o framework sabe o que existe lá fora; a
+  //     instalação, não). Nunca é o gate bloqueante (`DF-SF10.20-3`).
+  if (manifest) {
+    const behind = compareVersions(manifest.version, frameworkVersion) < 0;
+    check(
+      'Versão da instalação vs. framework',
+      behind ? 'warn' : true,
+      behind
+        ? `instalação em ${manifest.version}, framework em ${frameworkVersion} — ${fixCmd}`
+        : `instalação em ${manifest.version}, framework em ${frameworkVersion}`
+    );
+  }
+
+  // (ii) FALHA quando um `wf` instalado não é carregável pelo motor INSTALADO. A
+  //      assimetria é deliberada: o `doctor` roda do framework, mas EXECUTA o binário
+  //      do projeto (spawnSync) — é a única forma de a checagem falar sobre a
+  //      instalação e não sobre o framework validando a si mesmo (`DF-SF10.20-1`).
+  const installedValidator = path.join(destDir, 'scripts', 'validate-pod-workflow.cjs');
+  const podWorkflows = listInstalledPodWorkflows(destDir);
+  if (podWorkflows.length === 0) {
+    check('Workflows de pod executáveis pelo motor instalado', 'warn', 'nenhum wf-*.yaml de pod encontrado — checagem pulada');
+  } else if (!fs.existsSync(installedValidator)) {
+    allOk = check('Workflows de pod executáveis pelo motor instalado', false, `scripts/validate-pod-workflow.cjs ausente no projeto — ${fixCmd}`) && allOk;
+  } else {
+    for (const rel of podWorkflows) {
+      const result = spawnSync(process.execPath, [installedValidator, rel], { cwd: destDir, encoding: 'utf8' });
+      const passed = result.status === 0;
+      const firstLine = String(result.stderr || result.stdout || '').split('\n').find((l) => l.trim()) || '';
+      allOk = check(
+        `wf executável pelo motor instalado: ${rel}`,
+        passed,
+        passed ? undefined : `o motor deste projeto NÃO carrega este wf — ${firstLine.trim()} · corrija com: ${fixCmd}`
+      ) && allOk;
+    }
+  }
+
+  // 5. Estimativa de tokens do CLAUDE.md
+  const claudeMdPath = path.join(destDir, '.claude', 'CLAUDE.md');
+  if (!fs.existsSync(claudeMdPath)) {
+    allOk = check('.claude/CLAUDE.md presente', false) && allOk;
+  } else {
+    const bytes = fs.statSync(claudeMdPath).size;
+    const estTokens = Math.ceil(bytes / 4);
+    const within = estTokens <= CLAUDE_MD_TOKEN_ALERT;
+    allOk =
+      check(
+        'Budget do CLAUDE.md',
+        within ? true : 'warn',
+        `~${estTokens} tokens estimados (alerta se > ${CLAUDE_MD_TOKEN_ALERT})`
+      ) && allOk;
+  }
+
+  console.log(allOk ? '\nDiagnóstico: saudável.' : '\nDiagnóstico: problemas encontrados (veja FALHA acima).');
+  return allOk ? 0 : 1;
+}
+
+/** Compara versões `a.b.c` numericamente. <0 se `a` é anterior a `b`. */
+function compareVersions(a, b) {
+  const pa = String(a || '0').split('.').map((n) => parseInt(n, 10) || 0);
+  const pb = String(b || '0').split('.').map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+/** `pods/<pod>/workflows/*.yaml` instalados no projeto (paths relativos ao destDir). */
+function listInstalledPodWorkflows(destDir) {
+  const out = [];
+  const podsDir = path.join(destDir, 'pods');
+  if (!fs.existsSync(podsDir)) return out;
+  for (const pod of fs.readdirSync(podsDir)) {
+    const wfDir = path.join(podsDir, pod, 'workflows');
+    if (!fs.existsSync(wfDir) || !fs.statSync(wfDir).isDirectory()) continue;
+    for (const f of fs.readdirSync(wfDir)) {
+      if (/\.ya?ml$/.test(f)) out.push(`pods/${pod}/workflows/${f}`);
+    }
+  }
+  return out.sort();
+}
+
+module.exports = { doctor, compareVersions, listInstalledPodWorkflows };

package/installer/install.js

@@ -0,0 +1,155 @@
+'use strict';
+/**
+ * install.js — orquestra a instalação do POWER CLAUDE no cwd.
+ *
+ * Fluxo: wizard → cópia do template → cópia do validate-budgets.js →
+ * garantia de .gitignore cobrindo .env → manifest → git init (opcional).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const { runWizard } = require('./wizard');
+const { copyTemplate, listPods } = require('./copy');
+const { readManifest, writeManifest, sha256OfFile } = require('./manifest');
+const { createPrompter, ensureParentDir } = require('./util');
+const { motorEntries } = require('./motor-scripts');
+
+async function install({ yes = false } = {}) {
+  const destDir = process.cwd();
+  const pkgRoot = path.resolve(__dirname, '..');
+  const templateDir = path.join(pkgRoot, 'template');
+  const pkg = require(path.join(pkgRoot, 'package.json'));
+
+  if (path.resolve(destDir) === path.resolve(pkgRoot)) {
+    throw new Error('Não instale o POWER CLAUDE dentro do próprio repositório do framework. Rode em outro diretório.');
+  }
+  if (!fs.existsSync(templateDir)) {
+    throw new Error(`Template não encontrado em ${templateDir}. Pacote corrompido?`);
+  }
+
+  const existing = readManifest(destDir);
+  if (existing) {
+    console.log(`POWER CLAUDE ${existing.version} já instalado neste projeto (em ${existing.installedAt}).`);
+    console.log('Use "power-claude update" para atualizar ou "power-claude uninstall" para remover.');
+    return 0;
+  }
+
+  console.log(`POWER CLAUDE ${pkg.version} — instalação em ${destDir}\n`);
+
+  const pods = listPods(templateDir);
+  const prompter = yes ? null : createPrompter();
+  let report;
+  let entries;
+  let wizardResult;
+  try {
+    wizardResult = await runWizard({ yes, pods, destDir, prompter });
+    ({ entries, report } = await copyTemplate({
+      templateDir,
+      destDir,
+      yes,
+      selectedPods: wizardResult.selectedPods,
+      prompter,
+    }));
+  } finally {
+    if (prompter) prompter.close();
+  }
+
+  // Copia os scripts do motor (`.cjs`/`.js` fora de template/) que as skills e o
+  // pod squad-forge instalados referenciam — manifest versionado (ADR-007).
+  copyMotorScripts(pkgRoot, destDir, entries, report);
+
+  // Garante que .gitignore cobre .env.
+  ensureGitignoreCoversEnv(destDir, entries, report);
+
+  writeManifest(destDir, { version: pkg.version, files: entries });
+
+  if (wizardResult.initGit) {
+    initGitRepo(destDir);
+  }
+
+  printReport(report, entries.length);
+  console.log('\nInstalação concluída. Manifesto em .power-claude/manifest.json');
+  return 0;
+}
+
+function copyMotorScripts(pkgRoot, destDir, entries, report) {
+  // Cópia incondicional (não filtra por owner — arquivos inertes; o `owner` do
+  // manifest filtra só o diagnóstico do doctor). MESMO contrato de conflito do
+  // template: ausente → copia+registra; idêntico → registra; diferente → kept.
+  for (const { path: rel } of motorEntries()) {
+    const src = path.join(pkgRoot, ...rel.split('/'));
+    if (!fs.existsSync(src)) continue;
+    const dest = path.join(destDir, ...rel.split('/'));
+    if (fs.existsSync(dest)) {
+      if (sha256OfFile(dest) === sha256OfFile(src)) {
+        entries.push({ path: rel, sha256: sha256OfFile(dest) });
+      } else {
+        report.kept.push(rel);
+      }
+      continue;
+    }
+    ensureParentDir(dest);
+    fs.copyFileSync(src, dest);
+    entries.push({ path: rel, sha256: sha256OfFile(dest) });
+    report.installed.push(rel);
+  }
+}
+
+function ensureGitignoreCoversEnv(destDir, entries, report) {
+  const gitignorePath = path.join(destDir, '.gitignore');
+  if (!fs.existsSync(gitignorePath)) {
+    const content = '# POWER CLAUDE\n.env\n.env.*\n!.env.example\n';
+    fs.writeFileSync(gitignorePath, content, 'utf8');
+    entries.push({ path: '.gitignore', sha256: sha256OfFile(gitignorePath) });
+    report.installed.push('.gitignore');
+    return;
+  }
+  const content = fs.readFileSync(gitignorePath, 'utf8');
+  const lines = content.split(/\r?\n/).map((l) => l.trim());
+  if (!lines.includes('.env')) {
+    const appended = content.replace(/\n*$/, '\n') + '\n# POWER CLAUDE\n.env\n.env.*\n!.env.example\n';
+    fs.writeFileSync(gitignorePath, appended, 'utf8');
+    report.merged.push('.gitignore (linha .env adicionada)');
+  }
+}
+
+function initGitRepo(destDir) {
+  try {
+    execFileSync('git', ['init'], { cwd: destDir, stdio: 'pipe' });
+    execFileSync('git', ['add', '-A'], { cwd: destDir, stdio: 'pipe' });
+    try {
+      execFileSync('git', ['commit', '-m', 'chore: bootstrap POWER CLAUDE framework'], {
+        cwd: destDir,
+        stdio: 'pipe',
+      });
+      console.log('\nRepositório git inicializado com commit inicial.');
+    } catch {
+      console.warn('\nAviso: git init ok, mas o commit inicial falhou (configure user.name/user.email do git e commite manualmente).');
+    }
+  } catch (error) {
+    console.warn(`\nAviso: falha ao inicializar git: ${error.message}`);
+  }
+}
+
+function printReport(report, totalManaged) {
+  console.log('\n--- Relatório de instalação ---');
+  console.log(`Arquivos instalados: ${report.installed.length}`);
+  if (report.merged.length > 0) {
+    console.log(`Mesclados (aditivo em hooks/permissions): ${report.merged.join(', ')}`);
+  }
+  if (report.kept.length > 0) {
+    console.log('Preservados (já existiam com conteúdo próprio — NÃO sobrescritos):');
+    for (const f of report.kept) console.log(`  - ${f}`);
+  }
+  if (report.overwritten.length > 0) {
+    console.log(`Sobrescritos (com sua confirmação): ${report.overwritten.join(', ')}`);
+  }
+  if (report.skippedPods.length > 0) {
+    console.log(`Pods não instalados (sua escolha): ${report.skippedPods.join(', ')}`);
+  }
+  console.log(`Total de arquivos gerenciados no manifest: ${totalManaged}`);
+}
+
+module.exports = { install };

package/installer/manifest.js

@@ -0,0 +1,102 @@
+'use strict';
+/**
+ * manifest.js — leitura/escrita do manifest de instalação do POWER CLAUDE.
+ *
+ * O manifest vive em `.power-claude/manifest.json` no projeto destino:
+ *   { version, frameworkRoot, installedAt, files: [{ path, sha256, origin? }] }
+ *
+ * - `path`: relativo à raiz do projeto, separadores POSIX.
+ * - `sha256`: hash do conteúdo NO MOMENTO da instalação/atualização.
+ * - `origin`: opcional; "merged" marca arquivos mesclados com conteúdo do
+ *   usuário (ex.: .claude/settings.json) — nunca removidos automaticamente.
+ * - `frameworkRoot` (SF10.20): caminho ABSOLUTO do framework que escreveu este
+ *   manifest. É a única forma de a árvore instalada saber onde o framework está —
+ *   uma instalação não tem `package.json` nem `node_modules` do POWER CLAUDE, e
+ *   `npx power-claude` resolveria pelo REGISTRY PÚBLICO, onde esse nome pertence a
+ *   um pacote de terceiro. Um comando de correção que baixasse código de estranho
+ *   no repo do usuário seria pior do que não imprimir comando nenhum.
+ *
+ *   É registro, NÃO oráculo: pode envelhecer (o framework pode ser movido/apagado).
+ *   Todo consumidor VERIFICA a existência do executável antes de imprimir o caminho,
+ *   e degrada para instrução genérica quando não confere. Nunca é condição de falha.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const MANIFEST_DIR = '.power-claude';
+const MANIFEST_FILE = 'manifest.json';
+
+function sha256OfBuffer(buf) {
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+function sha256OfFile(filePath) {
+  return sha256OfBuffer(fs.readFileSync(filePath));
+}
+
+function manifestPath(destRoot) {
+  return path.join(destRoot, MANIFEST_DIR, MANIFEST_FILE);
+}
+
+/** Lê o manifest do projeto. Retorna null se não existir. Lança se corrompido. */
+function readManifest(destRoot) {
+  const p = manifestPath(destRoot);
+  if (!fs.existsSync(p)) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (error) {
+    throw new Error(`Manifest corrompido em ${p}: ${error.message}`);
+  }
+  if (!parsed || !Array.isArray(parsed.files)) {
+    throw new Error(`Manifest inválido em ${p}: campo "files" ausente.`);
+  }
+  return parsed;
+}
+
+/**
+ * Raiz do framework que está escrevendo o manifest. Correto por construção: todo o
+ * `installer/` só executa a partir do próprio pacote do framework (não é distribuído
+ * para instalações — ver ADR-019 `DF-SF10.20-6`).
+ */
+function frameworkRoot() {
+  return path.resolve(__dirname, '..');
+}
+
+/** Caminho do CLI do framework, ou null se `root` não hospeda um CLI utilizável. */
+function frameworkCliPath(root) {
+  if (!root || typeof root !== 'string') return null;
+  const cli = path.join(root, 'bin', 'cli.js');
+  return fs.existsSync(cli) ? cli : null;
+}
+
+/** Escreve o manifest. `files` = [{ path, sha256, origin? }]. */
+function writeManifest(destRoot, { version, files, installedAt, updatedAt }) {
+  const manifest = {
+    version,
+    // SF10.20: carimbado aqui, e não em cada caller, para que install/adopt/update
+    // não possam divergir sobre de onde a instalação veio.
+    frameworkRoot: frameworkRoot(),
+    installedAt: installedAt || new Date().toISOString(),
+    ...(updatedAt ? { updatedAt } : {}),
+    files: [...files].sort((a, b) => a.path.localeCompare(b.path)),
+  };
+  const p = manifestPath(destRoot);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+  return manifest;
+}
+
+module.exports = {
+  MANIFEST_DIR,
+  MANIFEST_FILE,
+  manifestPath,
+  readManifest,
+  writeManifest,
+  sha256OfFile,
+  sha256OfBuffer,
+  frameworkRoot,
+  frameworkCliPath,
+};

package/installer/motor-scripts.js

@@ -0,0 +1,50 @@
+'use strict';
+/**
+ * motor-scripts.js — fonte única do contrato de distribuição dos scripts do
+ * motor (ADR-007). Lê `installer/motor-scripts.json` (23 entradas + exclude) e
+ * expõe helpers consumidos por install/update/adopt/doctor e pelo teste-guarda.
+ *
+ * `owner`/`reason` por entrada NÃO filtram a cópia (que é incondicional, como o
+ * precedente `validate-budgets.js`); `owner` filtra apenas o DIAGNÓSTICO do
+ * doctor (Decisão 3 do ADR-007).
+ */
+
+const MANIFEST = require('./motor-scripts.json');
+
+/** Objeto do manifest (scripts[] + exclude[]). */
+function loadManifest() {
+  return MANIFEST;
+}
+
+/** Entradas do motor: [{ path, owner, reason, requiredBy? }]. */
+function motorEntries() {
+  return MANIFEST.scripts;
+}
+
+/** Só os paths relativos (repo-root, prefixo `scripts/`). */
+function motorRels() {
+  return MANIFEST.scripts.map((e) => e.path);
+}
+
+/** Padrões de exclusão do teste-guarda. */
+function excludePatterns() {
+  return MANIFEST.exclude;
+}
+
+/**
+ * True se o owner de um script do motor está instalado no projeto — o diagnóstico só
+ * cobra o script se o dono (pod ou skill) que o referencia estiver presente (ADR-007
+ * Decisão 3). Fonte única: consumido pelo `doctor` e pelo `update --scope motor`
+ * (SF10.20) — duas cópias desta regra divergiriam e o escopo do sync deixaria de bater
+ * com o escopo do diagnóstico.
+ */
+function ownerInstalled(destDir, owner) {
+  const fs = require('node:fs');
+  const path = require('node:path');
+  if (owner.startsWith('skill:')) return fs.existsSync(path.join(destDir, '.claude', 'skills', owner.slice('skill:'.length)));
+  if (owner.startsWith('pod:')) return fs.existsSync(path.join(destDir, 'pods', owner.slice('pod:'.length)));
+  if (owner === 'pods:*') return fs.existsSync(path.join(destDir, 'pods'));
+  return true;
+}
+
+module.exports = { loadManifest, motorEntries, motorRels, excludePatterns, ownerInstalled };

package/installer/motor-scripts.json

@@ -0,0 +1,39 @@
+{
+  "scripts": [
+    { "path": "scripts/pc-run-pod.cjs",           "owner": "skill:pc-run-pod", "reason": "referenced" },
+    { "path": "scripts/pod-memory.cjs",           "owner": "skill:pc-run-pod", "reason": "referenced" },
+    { "path": "scripts/pod-memory-note.cjs",      "owner": "skill:pc-run-pod", "reason": "referenced", "requiredBy": "skill:pc-run-pod" },
+    { "path": "scripts/validate-pod-workflow.cjs", "owner": "pod:squad-forge", "reason": "referenced" },
+    { "path": "scripts/smoke-pod-workflow.cjs",   "owner": "pod:squad-forge", "reason": "referenced" },
+    { "path": "scripts/harness-g5-lite.cjs",      "owner": "pod:squad-forge", "reason": "referenced" },
+    { "path": "scripts/migration-manifest.cjs",   "owner": "pod:squad-forge", "reason": "referenced" },
+    { "path": "scripts/watcher-audit.cjs",        "owner": "pod:squad-forge", "reason": "referenced" },
+    { "path": "scripts/validate-no-clone.cjs",    "owner": "pod:squad-forge", "reason": "referenced" },
+    { "path": "scripts/forge-assess-tier.cjs",    "owner": "pod:squad-forge", "reason": "referenced" },
+    { "path": "scripts/validate-fidelity-output.cjs", "owner": "squad-forge/mind-extractor", "reason": "referenced" },
+    { "path": "scripts/validate-source-audit.cjs",    "owner": "squad-forge/mind-extractor", "reason": "referenced" },
+    { "path": "scripts/arena.cjs",                    "owner": "skill:pc-arena", "reason": "referenced" },
+    { "path": "scripts/forge-generate.cjs",       "owner": "pod:squad-forge", "reason": "referenced" },
+    { "path": "scripts/forge-ingest-memory.cjs",  "owner": "pod:squad-forge", "reason": "referenced" },
+    { "path": "scripts/forge-upgrade-pod.cjs",    "owner": "pod:squad-forge", "reason": "referenced" },
+    { "path": "scripts/forge-harden-learning.cjs", "owner": "pod:squad-forge", "reason": "referenced" },
+    { "path": "scripts/validate-branding.js",     "owner": "pod:squad-forge", "reason": "require-dependency", "requiredBy": "scripts/validate-no-clone.cjs" },
+    { "path": "scripts/validate-budgets.js",      "owner": "pods:*",          "reason": "referenced" },
+    { "path": "scripts/veto-checks/lexical-check.cjs", "owner": "veto:command_check", "reason": "referenced", "requiredBy": "scripts/pc-run-pod.cjs" },
+    { "path": "scripts/veto-checks/html-valid.cjs",    "owner": "veto:command_check", "reason": "referenced", "requiredBy": "scripts/pc-run-pod.cjs" },
+    { "path": "scripts/veto-checks/render-gate.cjs",   "owner": "veto:command_check", "reason": "referenced", "requiredBy": "scripts/pc-run-pod.cjs" },
+    { "path": "scripts/veto-checks/phash-gate.cjs",    "owner": "veto:command_check", "reason": "referenced", "requiredBy": "scripts/pc-run-pod.cjs" },
+    { "path": "scripts/veto-checks/render-png.cjs",    "owner": "veto:command_check", "reason": "referenced", "requiredBy": "scripts/pc-run-pod.cjs" },
+    { "path": "scripts/pc-run-pipeline.cjs",      "owner": "skill:pc-pipeline", "reason": "referenced", "requiredBy": "skill:pc-pipeline" },
+    { "path": "scripts/validate-pipeline.cjs",    "owner": "skill:pc-pipeline", "reason": "require-dependency", "requiredBy": "scripts/pc-run-pipeline.cjs" },
+    { "path": "scripts/pod-export-compile.cjs",   "owner": "skill:pc-export", "reason": "referenced", "requiredBy": "skill:pc-export" },
+    { "path": "scripts/pod-export-executor.cjs",  "owner": "skill:pc-export", "reason": "referenced", "requiredBy": "skill:pc-export" },
+    { "path": "scripts/pod-export-release.cjs",   "owner": "skill:pc-export", "reason": "referenced", "requiredBy": "skill:pc-export" },
+    { "path": "scripts/pod-export-tools.cjs",     "owner": "skill:pc-export", "reason": "require-dependency", "requiredBy": "scripts/pod-export-executor.cjs" },
+    { "path": "scripts/pod-export-postprocess.cjs", "owner": "skill:pc-export", "reason": "require-dependency", "requiredBy": "scripts/pod-export-executor.cjs" },
+    { "path": "scripts/pod-export-service.cjs",   "owner": "skill:pc-export", "reason": "referenced", "requiredBy": "skill:pc-export" },
+    { "path": "scripts/pod-export-ui.cjs",        "owner": "skill:pc-export", "reason": "referenced", "requiredBy": "skill:pc-export" },
+    { "path": "scripts/validate-story-acs.cjs",   "owner": "skill:pc-validate-story", "reason": "referenced" }
+  ],
+  "exclude": ["*.test.cjs", "__tests__/", "__fixtures__/", "validate-install.js", "validate-adopt.js", "validate-update-scope-motor.js", "owner-layer.cjs", "derive-ready-transitions.cjs"]
+}