@kuyper/harness 0.1.0

package/dist/update.js

@@ -0,0 +1,434 @@
+import { spawn } from 'node:child_process';
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { checksumTree, classifyCore, coreEntriesFromLock, mapsEqual } from './coreClassification.js';
+import { KuyperRefusal } from './errors.js';
+import { checkReferences, generate, harnessVersion, loadCapabilities } from './generate.js';
+import { dirtyPaths, isGitRepo } from './gitPlumbing.js';
+import { readLock } from './lock.js';
+import { removeOrphanFile } from './outputPlan.js';
+import { packageCorePath } from './paths.js';
+import { validate } from './validate.js';
+import { writeFileAtomic } from './atomicWrite.js';
+const CORE_REL = join('.kuyper', 'core');
+const LOCK_REL = join('.kuyper', 'generated.lock');
+function corePath(projectRoot) {
+    return join(projectRoot, CORE_REL);
+}
+function lockPath(projectRoot) {
+    return join(projectRoot, LOCK_REL);
+}
+/**
+ * `spawn`, não `execFile`: as duas chamadas deste módulo (`pnpm add`, o
+ * relançamento) precisam de stdio **herdado** — o usuário vê o pnpm
+ * instalando e o binário novo relatando, do jeito que veria rodando à
+ * mão — e `execFile` é feito pra capturar saída como string, não pra
+ * repassar o terminal. Resolve com o código de saída (nunca rejeita por
+ * saída ≠0); só rejeita quando o processo **nem chega a nascer**
+ * (`ENOENT` etc.) — é essa distinção que a Fase 1 usa pra saber se a Fase
+ * 2 teve chance de explicar a própria falha.
+ */
+function runInherited(command, args, cwd) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { cwd, stdio: 'inherit' });
+        child.on('error', reject);
+        child.on('exit', (code) => resolve(code ?? 1));
+    });
+}
+function diffKeys(a, b) {
+    const diffs = new Set();
+    for (const [k, v] of a)
+        if (b.get(k) !== v)
+            diffs.add(k);
+    for (const k of b.keys())
+        if (!a.has(k))
+            diffs.add(k);
+    return [...diffs].sort();
+}
+function refuseR14(paths) {
+    throw new KuyperRefusal({
+        code: 'R14',
+        headline: 'A árvore de trabalho está suja.',
+        details: [
+            ...paths,
+            '',
+            'O update reescreve .kuyper/core/ inteiro. Com a árvore suja, o git diff da atualização viria misturado com o seu trabalho, e revisar seria impossível. Nada foi instalado.',
+        ],
+        route: ['git add -A && git commit'],
+    });
+}
+/**
+ * A PRD nomeia o arquivo específico ("core:fluxo-git.md foi editado à
+ * mão"), mas `generate()`'s própria recusa de core (`refuseCoreR7`) é
+ * genérica — "edição manual, remoção ou transição incompleta", sem listar
+ * caminho. Por isso `update()` faz o próprio diagnóstico (compara `D`
+ * contra o `L` do lock) em vez de reaproveitar a exceção do `generate`.
+ *
+ * A rota **não** é `git restore <path>` (revisão do B9, Achado 2): a R14
+ * já exige árvore limpa antes de chegar aqui, então a edição que causou a
+ * R21 **sempre** já está commitada — `git restore` sem `--source` restaura
+ * do índice/HEAD, que já contém a própria edição. É sempre um no-op,
+ * confirmado por reprodução (git init; commit original; edita; commit;
+ * git restore não muda nada). A rota certa copia de volta do pacote **já
+ * instalado** — neste ponto do `update`, ainda a versão antiga, e ela
+ * precisa coincidir com `L` pra o projeto ter chegado coerente até aqui —
+ * o mesmo mecanismo que `formatRelaunchBroken`/`formatEqualizedButIncomplete`
+ * já usam pra igualação, estendido pra este ponto mais cedo.
+ */
+function refuseR21CoreEdited(paths) {
+    throw new KuyperRefusal({
+        code: 'R21',
+        headline: 'A geração tem achados.',
+        details: [
+            ...paths.map((p) => `${p} foi editado à mão.`),
+            '',
+            'O update substituiria esse(s) arquivo(s) e a edição se perderia.',
+            'Nada foi instalado. Resolva primeiro:',
+        ],
+        route: [
+            'rm -rf .kuyper/core && cp -R node_modules/@kuyper/harness/core .kuyper/core',
+            'git add -A && git commit',
+            'pnpm exec kuyper update',
+        ],
+    });
+}
+function refuseR21PendingWrites(paths) {
+    throw new KuyperRefusal({
+        code: 'R21',
+        headline: 'A geração tem achados.',
+        details: [...paths, '', 'O generate encontrou e corrigiu isto agora, antes de instalar qualquer coisa — revise antes de tentar de novo.'],
+        route: ['git add -A && git commit', 'pnpm exec kuyper update'],
+    });
+}
+/** Sem código: o exemplo do PRD não mostra tag `(Rxx)` pra esta recusa. */
+function refusePnpmFailed(spec) {
+    throw new KuyperRefusal({
+        headline: `O pnpm falhou ao instalar ${spec}.`,
+        details: ['Nada em .kuyper/ foi alterado — a instalação vem antes da igualação.'],
+        route: [
+            'Para voltar à versão do último commit:',
+            '    git restore package.json pnpm-lock.yaml && pnpm install',
+            '',
+            'Para insistir na nova:',
+            `    pnpm add -D ${spec} && pnpm exec kuyper update`,
+        ],
+    });
+}
+/** Sem código: cenário que a PRD não antecipa por nome (o pnpm terminou bem, mas o binário instalado não roda). */
+function refuseRelaunchBroken(binPath) {
+    throw new KuyperRefusal({
+        headline: 'O binário recém-instalado não pôde ser executado.',
+        details: [`esperado em: ${binPath}`, '', 'O pnpm terminou, mas node_modules/@kuyper/harness parece incompleto.'],
+        route: ['rm -rf node_modules && pnpm install', 'pnpm exec kuyper update'],
+    });
+}
+function formatPartialCoreHybrid(newVersion) {
+    return [
+        '⚠  A versão foi instalada, mas a atualização não concluiu.',
+        '',
+        '   parou em:  igualação de .kuyper/core/   (passo 6 de 9)',
+        '',
+        `   O pacote em node_modules já é ${newVersion} e .kuyper/core/ ficou híbrido.`,
+        '   O generate vai recusar até a árvore coincidir inteira com o pacote.',
+        '',
+        '   Para concluir:',
+        '       rm -rf .kuyper/core && cp -R node_modules/@kuyper/harness/core .kuyper/core',
+        '       pnpm exec kuyper generate',
+        '       pnpm exec kuyper validate',
+    ].join('\n');
+}
+/**
+ * `.kuyper/core/` continua `= L` (nada foi tocado) e o relançamento saiu
+ * ≠0 — a Fase 2 morreu antes de qualquer escrita, tipicamente porque o
+ * binário recém-instalado não carrega. Achado real (revisão do B9,
+ * Achado 1): `spawn()` num `binPath` ausente/quebrado dispara `exit` com
+ * código ≠0, nunca o evento `error` — `refuseRelaunchBroken()` (o `catch`
+ * em `update()`) nunca roda pra este caso, só pra uma falha de spawn
+ * genuína (o próprio `node` não existir). Sem este ramo, o usuário via só
+ * o stack trace cru do Node, sem marcador, sem rota.
+ */
+function formatRelaunchBroken(newVersion, binPath) {
+    return [
+        '⚠  A versão foi instalada, mas não pôde ser executada.',
+        '',
+        '   parou em:  relançamento do binário   (passo 4 de 9)',
+        '',
+        `   O pacote em node_modules já é ${newVersion}, mas .kuyper/core/ não foi`,
+        '   tocado — nada foi perdido. O binário recém-instalado não conseguiu rodar.',
+        `   Esperado em: ${binPath}`,
+        '',
+        '   Para investigar:',
+        '       rm -rf node_modules && pnpm install',
+        '       pnpm exec kuyper update',
+    ].join('\n');
+}
+/**
+ * `.kuyper/core/` já é `= P` (a igualação terminou de verdade) mas o
+ * relançamento saiu ≠0 — a Fase 2 morreu **depois** de igualar, mas antes
+ * de terminar `generate`/`validate`/o próprio relatório. `D = P` só prova
+ * que o laço de escrita terminou, nada sobre o resto (Achado 1 da revisão
+ * do B9) — sem este ramo, o comando ficava calado justamente quando mais
+ * já tinha acontecido.
+ */
+function formatEqualizedButIncomplete(newVersion) {
+    return [
+        '⚠  A versão foi instalada e o core foi igualado, mas a atualização não concluiu.',
+        '',
+        '   parou em:  geração/validação   (passos 7-8 de 9)',
+        '',
+        `   .kuyper/core/ já é ${newVersion} — a igualação terminou. Falta confirmar`,
+        '   que as saídas e o validate convergem.',
+        '',
+        '   Para concluir:',
+        '       pnpm exec kuyper generate',
+        '       pnpm exec kuyper validate',
+    ].join('\n');
+}
+/**
+ * Sem código: R9 na tabela do §5 é escopo de `generate`/capacidades, não
+ * de `update`. Mensagem exata do §3.6 — o core novo já está em disco
+ * (passo 3 já rodou), as saídas continuam intactas.
+ */
+function refuseOrphanReplaces(rule, target) {
+    throw new KuyperRefusal({
+        headline: `core:${target} foi aposentado nesta versão, e a sua rule o substitui.`,
+        details: [`sua regra:  ${rule.sourcePath}`],
+        route: ['Remova o replaces: — a regra passa a valer por si — ou apague a sua rule.', 'Depois rode pnpm exec kuyper generate.'],
+    });
+}
+function refuseValidateInconsistent(reason) {
+    throw new KuyperRefusal({
+        headline: 'O update terminou a igualação e o generate, mas o validate não ficou coerente.',
+        details: [reason, '', 'Isto não deveria acontecer — a igualação e o generate já convergiram.'],
+        route: ['pnpm exec kuyper validate', 'Revise o que ele aponta antes de confiar na atualização.'],
+    });
+}
+function formatReplacedRuleWarning(rule, target) {
+    return [
+        `⚠  core:${target} mudou nesta versão, e você a substituiu.`,
+        '',
+        `   sua regra:      ${rule.sourcePath}`,
+        `   regra do core:  ${join(CORE_REL, 'rules', `${target}.md`)}   (veja o git diff)`,
+        '',
+        '   Compare as duas e veja se a sua ainda cobre o que você precisa.',
+        '   Manter a regra do core é preferível: ela evolui com o Harness, a sua não.',
+    ].join('\n');
+}
+/**
+ * Nome da capacidade dona de um caminho relativo do core (revisão do B9,
+ * Achado 3): `rules/<nome>.md` → `<nome>`; `skills/<nome>/**` (SKILL.md e
+ * todo `scripts/*` junto) → `<nome>` — uma skill de N arquivos conta como 1,
+ * não N.
+ */
+function capabilityKeyOf(relPath) {
+    const [kind, name] = relPath.split('/');
+    if (kind === 'rules' && name !== undefined)
+        return `rule:${name.replace(/\.md$/, '')}`;
+    if (kind === 'skills' && name !== undefined)
+        return `skill:${name}`;
+    return `outro:${relPath}`;
+}
+function groupByCapability(keys) {
+    const groups = new Map();
+    for (const key of keys) {
+        const capKey = capabilityKeyOf(key);
+        const existing = groups.get(capKey);
+        if (existing !== undefined)
+            existing.push(key);
+        else
+            groups.set(capKey, [key]);
+    }
+    return groups;
+}
+/**
+ * Diff estrutural de L vs P por CAPACIDADE, não por arquivo (Achado 3): uma
+ * skill com `SKILL.md` + scripts que mudam juntos conta 1 vez. "aposentada"
+ * é calculado direto das chaves de L, nunca de `loadCapabilities`/`set` —
+ * quando `continueUpdate()` chegou até aqui, arquivos aposentados já foram
+ * removidos do disco (passo de igualação, acima), então `set` nunca os veria.
+ */
+function diffCapabilities(L, P) {
+    const Lgroups = groupByCapability(L.keys());
+    const Pgroups = groupByCapability(P.keys());
+    const allCaps = new Set([...Lgroups.keys(), ...Pgroups.keys()]);
+    let changed = 0;
+    let added = 0;
+    let retired = 0;
+    for (const cap of allCaps) {
+        const inL = Lgroups.has(cap);
+        const inP = Pgroups.has(cap);
+        if (inL && !inP) {
+            retired += 1;
+            continue;
+        }
+        if (!inL && inP) {
+            added += 1;
+            continue;
+        }
+        const paths = new Set([...(Lgroups.get(cap) ?? []), ...(Pgroups.get(cap) ?? [])]);
+        if ([...paths].some((p) => L.get(p) !== P.get(p)))
+            changed += 1;
+    }
+    return { changed, added, retired };
+}
+function formatSuccess(previousVersion, newVersion, changed, added, retired, written, warnings) {
+    const parts = [];
+    if (changed > 0)
+        parts.push(`${changed} capacidade${changed === 1 ? '' : 's'} alterada${changed === 1 ? '' : 's'}`);
+    if (added > 0)
+        parts.push(`${added} acrescentada${added === 1 ? '' : 's'}`);
+    if (retired > 0)
+        parts.push(`${retired} aposentada${retired === 1 ? '' : 's'}`);
+    const lines = [`✓  Harness ${previousVersion} → ${newVersion}`, ''];
+    lines.push(`   core:  ${parts.length > 0 ? parts.join(', ') : 'sem mudanças'}`);
+    lines.push(written.length > 0 ? `   saídas atualizadas: ${written.join(', ')}` : '   saídas atualizadas: nenhuma');
+    if (warnings.length > 0) {
+        lines.push('');
+        for (const w of warnings)
+            lines.push(w, '');
+    }
+    lines.push('', '   Revise antes de commitar:  git diff .kuyper/core/');
+    return lines.join('\n');
+}
+/**
+ * Fase 1 — `kuyper update` de verdade (PRD §3.6, passos 1–4). Preflight,
+ * `pnpm add`, e relançamento do binário recém-instalado **de dentro da
+ * instalação do projeto**, nunca por `PATH` (mesma regra do `paths.ts`).
+ * A Fase 2 (`continueUpdate`, `__update-continue`) roda com stdio
+ * herdado — o que ela imprime é o que o usuário vê; esta função só
+ * acrescenta mensagem própria quando a Fase 2 não teve chance de
+ * explicar a própria falha.
+ */
+export async function update(options = {}) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    if (!(await isGitRepo(projectRoot))) {
+        throw new KuyperRefusal({ headline: 'Este diretório não é um repositório Git.' });
+    }
+    const dirty = await dirtyPaths(projectRoot);
+    if (dirty.length > 0)
+        refuseR14(dirty);
+    const lock = await readLock(lockPath(projectRoot));
+    if (lock !== undefined) {
+        const D = await checksumTree(corePath(projectRoot));
+        const L = coreEntriesFromLock(lock.entries);
+        if (!mapsEqual(D, L)) {
+            refuseR21CoreEdited(diffKeys(L, D).map((k) => join(CORE_REL, k)));
+        }
+    }
+    await generate({ projectRoot, ...(options.packageCoreDir !== undefined ? { packageCoreDir: options.packageCoreDir } : {}) });
+    const dirtyAfterGenerate = await dirtyPaths(projectRoot);
+    if (dirtyAfterGenerate.length > 0)
+        refuseR21PendingWrites(dirtyAfterGenerate);
+    const spec = process.env['KUYPER_UPDATE_SPEC'] ?? '@kuyper/harness@latest';
+    const pnpmCode = await runInherited('pnpm', ['add', '-D', spec], projectRoot).catch(() => 1);
+    if (pnpmCode !== 0)
+        refusePnpmFailed(spec);
+    const binPath = join(projectRoot, 'node_modules', '@kuyper', 'harness', 'dist', 'cli.js');
+    let relaunchCode;
+    try {
+        relaunchCode = await runInherited(process.execPath, [binPath, '__update-continue'], projectRoot);
+    }
+    catch {
+        refuseRelaunchBroken(binPath);
+    }
+    if (relaunchCode !== 0) {
+        await reportRelaunchFailure(projectRoot, binPath);
+    }
+    return relaunchCode;
+}
+/**
+ * Diagnóstico de três ramos pra quando a Fase 2 sai ≠0 (revisão do B9,
+ * Achado 1) — `classifyCore` já distingue os três estados possíveis, sem
+ * precisar de contador de passo em memória:
+ * - `.kuyper/core/` ainda `= L` (nada tocado) → a Fase 2 morreu antes de
+ *   escrever qualquer coisa, tipicamente porque o binário recém-instalado
+ *   não carrega;
+ * - `.kuyper/core/` já `= P` (igualação terminou) → a Fase 2 morreu
+ *   depois de igualar, mas antes de terminar generate/validate/relatório;
+ * - nem um nem outro → árvore híbrida de verdade, o caso original.
+ *
+ * Exportada só pra teste direto (sem precisar derrubar um relançamento de
+ * verdade no meio da execução pra chegar em cada estado) — a mesma
+ * categoria de seam de `packageCoreDir`, não injeção de falha: lê estado de
+ * disco, não simula uma queda.
+ */
+export async function reportRelaunchFailure(projectRoot, binPath) {
+    const lock = await readLock(lockPath(projectRoot));
+    if (lock === undefined)
+        return; // sem lock, sem classificação possível — a Fase 2 já explicou o que pôde
+    const newPackageCore = join(binPath, '..', '..', 'core');
+    const [D, L, P] = await Promise.all([
+        checksumTree(corePath(projectRoot)),
+        Promise.resolve(coreEntriesFromLock(lock.entries)),
+        checksumTree(newPackageCore),
+    ]);
+    const classification = classifyCore(L, P, D);
+    const newPkgRaw = await readFile(join(newPackageCore, '..', 'package.json'), 'utf8').catch(() => undefined);
+    const newVersion = newPkgRaw !== undefined ? (JSON.parse(newPkgRaw).version) : 'nova versão';
+    if (classification.state === 'anterior-intact') {
+        console.log(formatRelaunchBroken(newVersion, binPath));
+    }
+    else if (classification.state === 'transition-complete') {
+        console.log(formatEqualizedButIncomplete(newVersion));
+    }
+    else {
+        console.log(formatPartialCoreHybrid(newVersion));
+    }
+}
+/**
+ * Fase 2 — `__update-continue`, o binário recém-instalado (PRD §3.6,
+ * passos 5–9). Iguala `.kuyper/core/` arquivo por arquivo com escritor
+ * atômico (A13) em vez de `rm -rf`+`cp -R` cru — o equivalente manual usa
+ * o cru porque é o que dá pra digitar; o comando mantém a mesma garantia
+ * de escritor único do resto do produto. Se o processo morre no meio, o
+ * resultado é uma árvore que `classifyCore` já reconhece como híbrida —
+ * sem máquina de estado nova.
+ */
+export async function continueUpdate(options = {}) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const packageCoreDir = options.packageCoreDir ?? packageCorePath();
+    const lock = await readLock(lockPath(projectRoot));
+    const previousVersion = lock?.harness ?? 'desconhecida';
+    const newVersion = await harnessVersion();
+    const L = lock !== undefined ? coreEntriesFromLock(lock.entries) : new Map();
+    const P = await checksumTree(packageCoreDir);
+    const D = await checksumTree(corePath(projectRoot));
+    for (const [relKey, checksum] of P) {
+        if (D.get(relKey) === checksum)
+            continue;
+        const srcPath = join(packageCoreDir, relKey);
+        const [content, srcStat] = await Promise.all([readFile(srcPath), stat(srcPath)]);
+        await writeFileAtomic(join(corePath(projectRoot), relKey), content, { mode: srcStat.mode & 0o777 });
+    }
+    for (const relKey of D.keys()) {
+        if (!P.has(relKey))
+            await removeOrphanFile(projectRoot, join(CORE_REL, relKey));
+    }
+    const { set, issues } = await loadCapabilities(projectRoot);
+    if (issues.length === 0) {
+        const orphan = checkReferences(set).find((i) => i.code === 'R9');
+        if (orphan !== undefined) {
+            const rule = set.projectRules.find((r) => r.sourcePath === orphan.path);
+            const target = rule?.replaces?.slice('core:'.length) ?? '?';
+            refuseOrphanReplaces(rule, target);
+        }
+    }
+    const generateReport = await generate({ projectRoot, packageCoreDir });
+    const validateReport = await validate({ projectRoot, packageCoreDir, silent: true });
+    if (validateReport.code !== 0) {
+        refuseValidateInconsistent(validateReport.code === 1 ? validateReport.reason : validateReport.findings.join('; '));
+    }
+    const warnings = [];
+    for (const rule of set.projectRules) {
+        if (rule.replaces === undefined)
+            continue;
+        const target = rule.replaces.slice('core:'.length);
+        const key = `rules/${target}.md`; // chaves de L/P usam sempre `/` (checksumTree, coreEntriesFromLock), nunca join()
+        if (P.has(key) && L.get(key) !== P.get(key)) {
+            warnings.push(formatReplacedRuleWarning(rule, target));
+        }
+    }
+    const { changed, added, retired } = diffCapabilities(L, P);
+    console.log(formatSuccess(previousVersion, newVersion, changed, added, retired, generateReport.written, warnings));
+    return 0;
+}

package/dist/validate.js

@@ -0,0 +1,142 @@
+import { join } from 'node:path';
+import { readConfig, readPackageScripts } from './config.js';
+import { checksumTree, classifyCore, coreEntriesFromLock, mapsEqual, } from './coreClassification.js';
+import { readLock, computeChecksum } from './lock.js';
+import { decideOutput, decideOrphan, computeOrphanPaths } from './outputPlan.js';
+import { packageCorePath } from './paths.js';
+import { getCoreHooksPath, classifyHooksPath } from './hooks.js';
+import { loadCapabilities, checkReferences, buildDesiredOutputs, diskChecksumOf, diskIsExecutable } from './generate.js';
+/**
+ * A string exata que o `init` grava (B5) e que o `validate` exige de volta,
+ * byte a byte (PRD §3.3, A8c).
+ */
+export const PREPARE_SCRIPT = 'pnpm exec kuyper generate';
+function formatReport(report) {
+    if (report.code === 0) {
+        return '✓  Coerente: disco bate com o que a fonte canônica produziria.';
+    }
+    if (report.code === 1) {
+        return `⚠  Inconclusivo: ${report.reason}`;
+    }
+    const lines = [
+        report.findings.length === 1
+            ? '✗  Divergente: 1 achado.'
+            : `✗  Divergente: ${report.findings.length} achados.`,
+        '',
+    ];
+    for (const f of report.findings)
+        lines.push(`   ${f}`);
+    return lines.join('\n');
+}
+/**
+ * O `generate` sem escrita (PRD §3.3). Reaproveita a mesma comparação de três
+ * pontas do B2 — não decide nada novo, só não grava o resultado.
+ */
+export async function validate(options = {}) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const lockPath = join(projectRoot, '.kuyper', 'generated.lock');
+    const log = (report) => {
+        if (!options.silent)
+            console.log(formatReport(report));
+    };
+    const P = await checksumTree(options.packageCoreDir ?? packageCorePath());
+    const lock = await readLock(lockPath);
+    let config;
+    try {
+        config = await readConfig(join(projectRoot, '.kuyper', 'config.yaml'));
+    }
+    catch {
+        const report = {
+            code: 1,
+            findings: [],
+            reason: '.kuyper/config.yaml ausente ou inválido — não é possível calcular as saídas desejadas.',
+        };
+        log(report);
+        return report;
+    }
+    const { set, issues } = await loadCapabilities(projectRoot);
+    if (issues.length > 0) {
+        const report = {
+            code: 1,
+            findings: [],
+            reason: `A fonte canônica é inválida (${issues.length} achados) — não é possível calcular as saídas desejadas.`,
+        };
+        log(report);
+        return report;
+    }
+    const refIssues = checkReferences(set);
+    if (refIssues.length > 0) {
+        const report = {
+            code: 1,
+            findings: [],
+            reason: `Referências de capacidade inválidas (${refIssues.length} achados) — não é possível calcular as saídas desejadas.`,
+        };
+        log(report);
+        return report;
+    }
+    const findings = [];
+    const D = await checksumTree(join(projectRoot, '.kuyper', 'core'));
+    if (lock === undefined) {
+        if (D.size === 0 || !mapsEqual(D, P)) {
+            findings.push('.kuyper/core/ ausente, ou não coincide inteiramente com o core/ do pacote instalado.');
+        }
+    }
+    else {
+        const L = coreEntriesFromLock(lock.entries);
+        const classification = classifyCore(L, P, D);
+        if (classification.state === 'unknown-path') {
+            findings.push(`.kuyper/core/ contém conteúdo desconhecido: ${classification.paths.join(', ')}.`);
+        }
+        else if (classification.state === 'mismatch') {
+            findings.push('.kuyper/core/ não coincide integralmente com o lock anterior nem com o pacote em execução.');
+        }
+    }
+    const desired = buildDesiredOutputs(set, config);
+    const desiredPaths = new Set(desired.map((o) => o.path));
+    for (const output of desired) {
+        const disk = await diskChecksumOf(projectRoot, output.path);
+        const newChecksum = computeChecksum(output.content);
+        const lockChecksum = lock?.entries[output.path];
+        const decision = decideOutput(disk, lockChecksum, newChecksum);
+        if (decision.action === 'write') {
+            findings.push(`${output.path}: desatualizado em relação à fonte canônica — generate reescreveria.`);
+        }
+        else if (decision.action === 'refuse-edited') {
+            findings.push(`${output.path}: editado à mão — generate recusaria (R7). Descarte com "git restore ${output.path}" ou aceite com "pnpm exec kuyper generate --force".`);
+        }
+        else if (decision.action === 'refuse-foreign') {
+            findings.push(`${output.path}: ocupado por conteúdo alheio, não rastreado pelo Harness — generate recusaria (R8).`);
+        }
+        else if (output.mode !== undefined && !(await diskIsExecutable(projectRoot, output.path))) {
+            findings.push(`${output.path}: sem bit de execução — generate corrigiria.`);
+        }
+    }
+    if (lock !== undefined) {
+        const orphanPaths = computeOrphanPaths(lock.entries, desiredPaths);
+        for (const path of orphanPaths) {
+            const disk = await diskChecksumOf(projectRoot, path);
+            const decision = decideOrphan(disk, lock.entries[path]);
+            if (decision.action === 'remove') {
+                findings.push(`${path}: órfão de uma capacidade removida, ainda presente — generate o removeria.`);
+            }
+            else if (decision.action === 'refuse-edited') {
+                findings.push(`${path}: órfão editado à mão — generate recusaria (R7).`);
+            }
+        }
+    }
+    const hooksPathCurrent = await getCoreHooksPath(projectRoot);
+    const hooksPathState = classifyHooksPath(hooksPathCurrent);
+    if (hooksPathState === 'absent') {
+        findings.push('core.hooksPath não está configurado. "pnpm exec kuyper generate" resolve.');
+    }
+    else if (hooksPathState === 'other') {
+        findings.push(`core.hooksPath aponta para "${hooksPathCurrent}", fora de .kuyper/hooks — "pnpm exec kuyper generate" vai recusar (R24), não corrige sozinho.`);
+    }
+    const scripts = await readPackageScripts(join(projectRoot, 'package.json')).catch(() => ({}));
+    if (scripts['prepare'] !== PREPARE_SCRIPT) {
+        findings.push(`package.json "prepare" ausente ou diferente de "${PREPARE_SCRIPT}".`);
+    }
+    const report = findings.length > 0 ? { code: 2, findings } : { code: 0, findings: [] };
+    log(report);
+    return report;
+}