synthesisui 0.16.419 → 0.16.421

package/dist/agent-wiring.js

@@ -1,7 +1,31 @@
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { hasCodexBlock, pinnedInCodex, withCodexBlock } from "./codex-mcp.js";
-const HOOK_MATCHER = "Write|Edit|MultiEdit";
+/**
+ * QUANDO A CHECAGEM RODA - e por que `Bash` entrou em 12/09.
+ *
+ * ═══ O QUE O CLIENTE VIA ═══
+ *
+ * O filtro era `Write|Edit|MultiEdit`, e com isso a garantia inteira dependia de qual ferramenta o
+ * agente escolhesse. Medido no `codelevel` em três sessões: toda edição em lote passou por comando
+ * de shell e a checagem produziu **0 linhas**; na única edição feita pela ferramenta de edição ela
+ * falou na hora, com a regra do sistema nomeada. O produto promete atuar quando ele escreve
+ * frontend - não quando o agente segura a caneta certa.
+ *
+ * Um comando de shell não diz quais arquivos tocou, então quem responde é a árvore de trabalho -
+ * ver `changed-files.ts`, onde também está o custo medido.
+ */
+const HOOK_MATCHER = "Write|Edit|MultiEdit|Bash";
+/**
+ * O FILTRO QUE ESTE PRODUTO ESCREVIA ANTES DE 12/09 - e a única string que ele se autoriza a
+ * alargar.
+ *
+ * Quem conectou antes disso tem no arquivo dele um filtro que NÓS escrevemos, e deixá-lo como está
+ * seria entregar a correção só para quem instala do zero. Alargar um filtro que uma PESSOA
+ * escreveu é outra coisa, e continua proibido: a comparação é por igualdade exata com a nossa
+ * string antiga, nunca por parecer com ela.
+ */
+const HOOK_MATCHER_BEFORE_SHELL = "Write|Edit|MultiEdit";
 /**
  * Exportado porque a REGRA é uma só: a pasta de uma ferramenta é a evidência de que ela é usada, e
  * a mesma evidência decide o MCP daqui e a casa do bloco em `claude-md.ts`. Duas cópias deste
@@ -116,11 +140,27 @@ async function wireHook(root, command) {
      * protegia continua protegido: o matcher fica como estiver, os hooks vizinhos ficam, e uma segunda
      * entrada nunca é criada - duas entradas rodariam o verificador duas vezes por escrita.
      */
-    const mine = post
-        .flatMap((e) => e.hooks ?? [])
-        .find((h) => (h.command ?? "").includes("synthesisui"));
-    if (mine) {
+    const owner = post.find((e) => (e.hooks ?? []).some((h) => (h.command ?? "").includes("synthesisui")));
+    const mine = (owner?.hooks ?? []).find((h) => (h.command ?? "").includes("synthesisui"));
+    if (owner && mine) {
         const was = mine.command ?? "";
+        /**
+         * O FILTRO NOSSO ANTIGO SOBE JUNTO - ver `HOOK_MATCHER_BEFORE_SHELL`.
+         *
+         * Sem isto, a checagem passar a valer para edição por shell alcançaria só quem instalasse do
+         * zero: quem já tinha conectado ficaria com o filtro estreito para sempre, e nada no produto
+         * diria isso a ele.
+         *
+         * **E SÓ QUANDO A ENTRADA É NOSSA INTEIRA** - achado da revisão de contrato no fecho, e a
+         * fronteira estava larga demais. `matcher` vale para TODOS os comandos da entrada: se ele
+         * acrescentou um hook dele ali ao lado - um formatador, um linter -, alargar o filtro passaria
+         * a disparar o comando DELE depois de todo comando de shell, sem ele ter pedido. É a mesma lei
+         * que impede escrever arquivo de um agente que ele não escolheu.
+         */
+        const onlyOurs = (owner.hooks ?? []).every((h) => (h.command ?? "").includes("synthesisui"));
+        const widen = owner.matcher === HOOK_MATCHER_BEFORE_SHELL && onlyOurs;
+        if (widen)
+            owner.matcher = HOOK_MATCHER;
         /**
          * SÓ UM PIN NOSSO É SUBSTITUÍDO, e a fronteira é estreita de propósito.
          *
@@ -132,12 +172,16 @@ async function wireHook(root, command) {
          */
         const pinnedAt = /synthesisui@(\d+\.\d+\.\d+)/.exec(was)?.[1];
         const proposedAt = /synthesisui@(\d+\.\d+\.\d+)/.exec(command)?.[1];
-        if (!pinnedAt || !proposedAt || pinnedAt === proposedAt)
+        const samePin = !pinnedAt || !proposedAt || pinnedAt === proposedAt;
+        if (samePin && !widen)
             return { status: "already there", command: was || command };
-        mine.command = command;
+        if (!samePin)
+            mine.command = command;
         await mkdir(dir, { recursive: true });
         await writeFile(path, `${JSON.stringify({ ...settings, hooks: { ...hooks, PostToolUse: post } }, null, 2)}\n`, "utf8");
-        return { status: "updated", command, was };
+        return samePin
+            ? { status: "updated", command: was || command }
+            : { status: "updated", command, was };
     }
     post.push({
         matcher: HOOK_MATCHER,

package/dist/changed-files.js

@@ -0,0 +1,56 @@
+import { execFile } from "node:child_process";
+import { stat } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+/**
+ * O QUE A ÁRVORE DE TRABALHO TEM DE DIFERENTE DO ÚLTIMO COMMIT, mais o que não está rastreado.
+ *
+ * `--relative` e o `cwd` na raiz do projeto: num monorepo cujo `_synthesisui` mora em
+ * `apps/landing/`, os caminhos do git saem a partir do topo da ÁRVORE, e compará-los com os do
+ * projeto é comparar dois endereços diferentes para o mesmo arquivo. É o mesmo defeito que o
+ * `HEAD:./` já conserta do outro lado.
+ */
+async function listed(root) {
+    const out = [];
+    for (const args of [
+        ["diff", "--name-only", "--relative", "HEAD", "--", "."],
+        ["ls-files", "--others", "--exclude-standard"],
+    ]) {
+        const { stdout } = await run("git", args, {
+            cwd: root,
+            maxBuffer: 4 * 1024 * 1024,
+        }).catch(() => ({ stdout: "" }));
+        for (const line of stdout.split("\n"))
+            if (line.trim())
+                out.push(line.trim());
+    }
+    return [...new Set(out)];
+}
+/**
+ * OS ARQUIVOS INTERESSANTES QUE MUDARAM DESDE `since`, do mais recente para o mais antigo.
+ *
+ * `since` é o instante da última checagem. Sem ele, a árvore inteira de trabalho responderia - e
+ * num repositório com trinta arquivos em aberto o primeiro comando de shell do dia produziria um
+ * relatório sobre trabalho de ontem. O corte por instante é o que faz a resposta ser *"o que este
+ * comando acabou de fazer"*.
+ */
+export async function changedSince(root, since, keep) {
+    const out = [];
+    for (const rel of await listed(root)) {
+        if (!keep(rel))
+            continue;
+        const info = await stat(join(root, rel)).catch(() => null);
+        if (!info?.isFile())
+            continue;
+        /**
+         * `<` E NÃO `<=`, e o lado do erro é declarado: um arquivo escrito no MESMO milissegundo em
+         * que o relógio andou é RELATADO, não perdido. O preço é um relatório repetido numa corrida
+         * rara; o preço do outro lado é uma escrita que ninguém checa nunca mais.
+         */
+        if (info.mtimeMs < since)
+            continue;
+        out.push({ rel, at: info.mtimeMs });
+    }
+    return out.sort((a, b) => b.at - a.at);
+}

package/dist/commands/connect.js

@@ -4,6 +4,7 @@ import { codexPinBefore, exists, wireAgent } from "../agent-wiring.js";
 import { AGENTS, chooseAgents, filesOf, rememberChoice, } from "../agents-chosen.js";
 import { blockHomes, syncClaudeMd } from "../claude-md.js";
 import { resolveRegistry } from "../config.js";
+import { guaranteeIfNew } from "../guarantee.js";
 import { notAProject, projectRootFrom } from "../is-a-project.js";
 import { fmt, say } from "../lang.js";
 import { body, bodyWrapped, paint, section, snippet } from "../output.js";
@@ -14,6 +15,7 @@ import { SKILLS } from "../skills.js";
 import { add, ensureGovernanceHome } from "./add.js";
 import { reportWhatIsLeft } from "./align.js";
 import { ci } from "./ci.js";
+import { loadSystem } from "./doctor.js";
 import { MCP_TOOL_COUNT } from "./mcp.js";
 import { installedSlugs } from "./sync.js";
 /**
@@ -672,6 +674,37 @@ export async function connect(opts) {
         console.log("");
         await ci({ dir: root, write: true });
     }
+    /**
+     * ATÉ ONDE A GARANTIA VAI - uma vez, e de novo só quando a resposta muda.
+     *
+     * ═══ POR QUE AQUI ═══
+     *
+     * Este é o comando que LIGA a checagem, então é o único lugar onde a fronteira dela é notícia. O
+     * que o produto passa a fazer sozinho no repositório de alguém precisa vir com o que ele NÃO
+     * faz, na mesma tela - senão o silêncio da checagem lê como aprovação, que é a lacuna calada da
+     * lei 8.
+     *
+     * A frase sai depois da fiação de propósito: ela fala do estado que este comando acabou de
+     * deixar no disco, e não do que havia antes dele.
+     */
+    {
+        const { table } = await loadSystem(root).catch(() => ({
+            table: { name: null, slug: null, utilities: new Map() },
+        }));
+        const said = await guaranteeIfNew(root, {
+            name: table.name ?? table.slug,
+            utilities: table.utilities,
+        }).catch(() => null);
+        if (said) {
+            console.log("");
+            console.log(section(say("How far this check goes here")));
+            for (const line of said) {
+                console.log("");
+                for (const wrapped of bodyWrapped(fmt(line.text, line.values)))
+                    console.log(wrapped);
+            }
+        }
+    }
     /** A mesma versão que a fiação do editor recebe - os dois pinam no mesmo número. */
     await offerShellHook(opts.shell === true, opts.version);
     /**

package/dist/commands/doctor.js

@@ -269,6 +269,23 @@ measured) {
             }
         }
         css += `\n${real || root}`;
+        /**
+         * O ADAPTADOR DE TEMA ENTRA JUNTO - é ele que diz QUAIS utilities este sistema gera.
+         *
+         * `theme.css` carrega o bloco `@theme`, e é essa declaração que autoriza a régua a ler
+         * `bg-primary` como referência a `--color-primary` (ver `idiom-names.ts`). Sem ele, um projeto
+         * de idioma utility volta a ser medido com a régua do idioma vizinho - era o caso do
+         * `codelevel`, cujo `tokens.css` traz os mesmos nomes, mas dentro do escopo do sistema.
+         *
+         * As declarações são as MESMAS que já vieram acima, e a primeira vence: nenhum valor muda, só
+         * o marcador passa a ser visível. Ausente é o caso normal de um sistema adotado.
+         */
+        const themePointer = await readFile(join(dir, "theme.css"), "utf8").catch(() => "");
+        const theme = mine?.version
+            ? await readFile(join(dir, `v${mine.version}`, "theme.css"), "utf8").catch(() => "")
+            : "";
+        if (theme || themePointer)
+            css += `\n${theme || themePointer}`;
         // An ADOPTED system has no tokens.css of ours - `adopt` deliberately
         // writes no CSS, because the project's own stylesheet already works. Its
         // vocabulary lives in system.json, and without this the doctor falls
@@ -894,9 +911,11 @@ export async function doctor(opts) {
                 : "") +
             " (--verbose for why)"));
     }
-    // 0 of 0 is not a perfect score, it is an empty measurement - printing a
-    // full bar there would be the report's first lie.
-    const measurable = d.tokenUses + d.findings.length > 0;
+    /**
+     * 0 de 0 não é nota máxima, é medição vazia - e desde 12/09 a própria régua carrega essa
+     * distinção em vez de cada tela refazê-la. Ver `Reach` em `scan.ts`.
+     */
+    const measurable = d.reach.measured;
     // Before the number, because the number is the thing that misleads. An
     // installed-but-unwired system reads 0%, and 0% reads as "broken product"
     // rather than "one import missing".
@@ -1230,7 +1249,7 @@ export async function doctor(opts) {
             await appendEvent(root, {
                 kind: "doctor",
                 at: new Date().toISOString(),
-                coverage: d.coverage,
+                ...(d.reach.measured ? { coverage: d.reach.percent } : {}),
                 rule: COVERAGE_RULE,
                 named: d.named,
                 ...(d.findings.some((f) => f.crossFamily)
@@ -1321,9 +1340,10 @@ export async function doctor(opts) {
             console.log(body("  and every shadcn component switches over."));
         }
     }
-    if (hasSystem && measurable) {
+    if (hasSystem && d.reach.measured) {
+        const { percent, uses, of } = d.reach;
         console.log("");
-        console.log(body(`Token coverage  ${meter(d.coverage)}  ${paint.strong(`${String(d.coverage).padStart(3)}%`)}`));
+        console.log(body(`Token coverage  ${meter(percent)}  ${paint.strong(`${String(percent).padStart(3)}%`)}  ${paint.dim(`${uses} of ${of} design values come from the system`)}`));
         console.log(body(paint.dim(
         /**
          * DE QUEM É O VOCABULÁRIO, dito na própria linha.
@@ -1435,7 +1455,7 @@ export async function doctor(opts) {
          * O `1` não muda nada do que a frase afirma: os valores escritos à mão continuam sendo a FONTE
          * de onde os tokens saíram, e não um desvio deles.
          */
-        if (d.coverage === 0 && measured.system) {
+        if (d.reach.measured && d.reach.percent === 0 && measured.system) {
             console.log(body(paint.dim(`                zero is the expected start here - this system was measured FROM`)));
             console.log(body(paint.dim(`                \`${measured.system}\`, so these values are where the tokens`)));
             console.log(body(paint.dim(`                came from. They count once the code points at the names they became.`)));
@@ -1478,7 +1498,7 @@ export async function doctor(opts) {
         await appendEvent(root, {
             kind: "doctor",
             at: new Date().toISOString(),
-            coverage: d.coverage,
+            ...(d.reach.measured ? { coverage: d.reach.percent } : {}),
             /** Qual régua mediu - ver `COVERAGE_RULE`. Sem isto a tendência compara duas réguas. */
             rule: COVERAGE_RULE,
             named: d.named,

package/dist/commands/hook.js

@@ -1,8 +1,10 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile, stat, writeFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
-import { appendEvent } from "../doctor/ledger.js";
+import { changedSince } from "../changed-files.js";
+import { appendEvent, ledgerPath } from "../doctor/ledger.js";
 import { diagnose, nameToWrite, scanSource } from "../doctor/scan.js";
-import { namesRemoved, previousText, rulesTouchedBy } from "../rule-touched.js";
+import { governs, ungovernedIn } from "../governed.js";
+import { namesRemoved, previousText, rulesTouchedBy, } from "../rule-touched.js";
 import { loadSystem } from "./doctor.js";
 const pass = () => ({ continue: true });
 const speak = (context) => ({
@@ -12,15 +14,59 @@ const speak = (context) => ({
         additionalContext: context,
     },
 });
-/** Files where a design value can even appear. A hook that parses a README on
- *  every edit is paying for nothing. */
-const UI_FILE = /\.(tsx|jsx|ts|js|css|scss|vue|svelte)$/i;
 /** Written after the hook's first report of any kind, and never read for anything
  *  else. Lives in our own directory, so removing the system removes the memory
  *  too. It is committed with `_synthesisui/`, which means the greeting is
  *  per-project and not per-teammate - a wart worth the simplicity, since the
  *  second person to clone a wired repo is not the one wondering if it installed. */
 const GREETED = "_synthesisui/.hook-greeted";
+/**
+ * QUANDO ESTA CHECAGEM OLHOU PELA ÚLTIMA VEZ - e o relógio é o registro que ela já escreve.
+ *
+ * ═══ POR QUE NÃO UM ARQUIVO NOVO ═══
+ *
+ * A primeira versão criava `_synthesisui/.hook-seen` só para carregar uma data de modificação, e a
+ * revisão de QA no fecho achou o custo: um arquivo NOVO no repositório dele, não rastreado, que a
+ * lista de ignorados gerenciada só alcança em projeto novo - porque ela é escrita uma vez e nunca
+ * reescrita, e isso é decisão declarada em `commands/add.ts`.
+ *
+ * O livro-razão já responde a mesma pergunta e já é ignorado: ele ganha uma linha a cada arquivo
+ * checado, então a data de modificação dele É o instante da última checagem. Um `doctor` também o
+ * move, e isso está certo - ele olhou o projeto inteiro.
+ *
+ * ═══ E SEM ELE A RESPOSTA É "NUNCA OLHEI", que não é "olhei em 1970" ═══
+ *
+ * Zero faria a árvore inteira de trabalho responder, e o primeiro comando do dia produziria um
+ * relatório sobre o trabalho de ontem - ver `baseline`.
+ */
+const clockOf = async (root) => stat(ledgerPath(root)).then((s) => s.mtimeMs, () => 0);
+/**
+ * A PRIMEIRA VEZ NÃO FALA DE TRABALHO QUE ELE NÃO ACABOU DE FAZER - achado da revisão de QA.
+ *
+ * Num repositório com cinco arquivos em aberto desde ontem, o primeiro comando de shell - um `ls`,
+ * um `git status` - encontraria os cinco e falaria de três. Isso é ruído sobre trabalho que
+ * ninguém acabou de tocar, e ruído é o que faz alguém desinstalar a checagem.
+ *
+ * Então a primeira rodada ACERTA O RELÓGIO e cala. O que se perde é um relatório, na única vez em
+ * que o produto acabou de ser instalado - e a tela do `connect` já disse que ele está vivo.
+ */
+const startClock = (root) => writeFile(ledgerPath(root), "", { flag: "a" }).catch(() => { });
+/**
+ * QUANTOS ARQUIVOS UM COMANDO DE SHELL PODE FAZER O PRODUTO RELATAR DE UMA VEZ.
+ *
+ * Um script que reescreve trinta arquivos produziria trinta relatórios numa resposta só, e o
+ * cabeçalho deste arquivo já diz o que acontece com uma checagem barulhenta. Três é o que cabe numa
+ * leitura.
+ *
+ * **E O QUE FICA DE FORA É NOMEADO** - achado da revisão de QA no fecho, e o defeito era pior que o
+ * corte: o relógio andava por cima de TODOS os arquivos, então do quarto em diante eles não eram
+ * relatados por ninguém, nunca mais. Um script de dez telas rendia três relatórios e sete arquivos
+ * apagados em silêncio. Agora os outros saem pelo NOME, com o comando que os olha.
+ *
+ * E a ordem é do mais recente para o mais antigo: numa lista cortada, o que o comando acabou de
+ * escrever é o que a pessoa tem em mente.
+ */
+const AT_MOST = 3;
 const markGreeted = (root) => writeFile(join(root, GREETED), "", "utf8").catch(() => { });
 /** One sentence, once per project. Addressed to the agent because the hook has
  *  no way to reach the person, and the person is who needs to know. */
@@ -72,13 +118,13 @@ async function greet(root, rel) {
  * O retorno continua sendo contexto: `continue: true` em todo caminho. E nenhum nome é proposto -
  * a frase diz qual regra, qual nome declarado amarra a regra ao que saiu, e devolve a decisão.
  */
-async function amendment(root, rel, after, rules, declared) {
+async function amendment(root, rel, after, rules, names) {
     if (rules.length === 0)
         return [];
     const before = await previousText(root, rel);
     if (before == null)
         return [];
-    const touched = rulesTouchedBy(namesRemoved(before, after, declared), rules);
+    const touched = rulesTouchedBy(namesRemoved(before, after, names), rules);
     if (touched.length === 0)
         return [];
     return [
@@ -121,7 +167,7 @@ async function report(root, filePath) {
     if (src == null)
         return null;
     const rel = relative(root, filePath);
-    const broke = await amendment(root, rel, src, doctrines.flatMap((doc) => doc.rules), table.declared).catch(() => []);
+    const broke = await amendment(root, rel, src, doctrines.flatMap((doc) => doc.rules), table).catch(() => []);
     const d = diagnose([scanSource(rel, src, table)]);
     const named = d.findings.filter((f) => nameToWrite(f));
     /**
@@ -228,6 +274,18 @@ async function report(root, filePath) {
     }
     return lines.join("\n");
 }
+/**
+ * O QUE O AGENTE ACABOU DE ESCREVER, pelo caminho que o cliente do agente nomeia.
+ *
+ * `Write`, `Edit` e `MultiEdit` trazem o arquivo no payload, e é a resposta mais barata que
+ * existe: nenhuma pergunta ao git, nenhum `stat`.
+ */
+const namedInPayload = (input) => {
+    const writes = input.tool_name === "Write" ||
+        input.tool_name === "Edit" ||
+        input.tool_name === "MultiEdit";
+    return writes ? (input.tool_input?.file_path ?? null) : null;
+};
 export async function hook(opts) {
     const root = resolve(opts.dir ?? process.cwd());
     let raw = "";
@@ -243,32 +301,66 @@ export async function hook(opts) {
         process.stdout.write(`${JSON.stringify(pass())}\n`);
         return;
     }
-    const writes = input.tool_name === "Write" ||
-        input.tool_name === "Edit" ||
-        input.tool_name === "MultiEdit";
-    const file = input.tool_input?.file_path;
-    if (input.hook_event_name !== "PostToolUse" || !writes || !file) {
+    if (input.hook_event_name !== "PostToolUse") {
         process.stdout.write(`${JSON.stringify(pass())}\n`);
         return;
     }
-    const abs = resolve(root, file);
-    // Our own installed artifacts are the answer, not the problem - and a file
-    // outside the project is none of our business.
+    const ungoverned = await ungovernedIn(root);
+    const named = namedInPayload(input);
     /**
-     * O CAMINHO TESTADO É O RELATIVO - achado da revisão de QA no fecho.
+     * A FERRAMENTA DE EDIÇÃO DIZ O ARQUIVO; QUALQUER OUTRA COISA PERGUNTA À ÁRVORE.
      *
-     * `abs.includes("_synthesisui")` olhava o caminho ABSOLUTO, então quem clonasse o projeto para
-     * qualquer diretório com esse nome no meio (`~/_synthesisui-demo/app`) tinha TODOS os arquivos
-     * pulados e um hook permanentemente mudo. O relativo já estava calculado uma linha acima.
+     * Um comando de shell não tem como dizer o que escreveu, e era exatamente por ali que passavam
+     * as edições em lote das duas sessões medidas em 12/09 - ver o cabeçalho deste arquivo e
+     * `changed-files.ts`. As duas chamadas ao git custaram 12ms medidos, e elas vêm ANTES de
+     * qualquer leitura de folha de estilo: quando nada mudou, isto termina aqui.
      */
-    const rel = relative(root, abs);
-    const inside = !rel.startsWith("..");
-    if (!UI_FILE.test(abs) ||
-        !inside ||
-        rel.split("/").includes("_synthesisui")) {
+    if (named) {
+        const rel = relative(root, resolve(root, named));
+        const body = governs(rel, ungoverned)
+            ? await report(root, join(root, rel)).catch(() => null)
+            : null;
+        process.stdout.write(`${JSON.stringify(body ? speak(body) : pass())}\n`);
+        return;
+    }
+    const clock = await clockOf(root);
+    /** Ver `startClock`: a primeira rodada acerta o relógio e cala. */
+    if (clock === 0) {
+        await startClock(root);
         process.stdout.write(`${JSON.stringify(pass())}\n`);
         return;
     }
-    const body = await report(root, abs).catch(() => null);
-    process.stdout.write(`${JSON.stringify(body ? speak(body) : pass())}\n`);
+    const changed = await changedSince(root, clock, (rel) => governs(rel, ungoverned)).catch(() => []);
+    if (changed.length === 0) {
+        process.stdout.write(`${JSON.stringify(pass())}\n`);
+        return;
+    }
+    const said = [];
+    for (const { rel } of changed.slice(0, AT_MOST)) {
+        const body = await report(root, join(root, rel)).catch(() => null);
+        if (body)
+            said.push(body);
+    }
+    /**
+     * O QUE FICOU DE FORA É NOMEADO, e com o comando que o olha - ver `AT_MOST`.
+     *
+     * O corte calado era pior do que parecia: o relógio anda por cima de TODOS os arquivos que esta
+     * rodada encontrou, então do quarto em diante eles não voltariam a ser vistos por ninguém. Sair
+     * pelo nome é o que transforma uma perda silenciosa numa lacuna declarada (lei 8).
+     */
+    const rest = changed.slice(AT_MOST);
+    if (rest.length > 0)
+        said.push([
+            `${rest.length} more file${rest.length === 1 ? "" : "s"} changed in this command and ${rest.length === 1 ? "was" : "were"} not checked here: ${rest
+                .slice(0, 10)
+                .map((c) => c.rel)
+                .join(", ")}${rest.length > 10 ? `, +${rest.length - 10} more` : ""}.`,
+            "Run `npx synthesisui doctor` to see them, or write one of them again and this will check it.",
+        ].join("\n"));
+    /**
+     * E O RELÓGIO ANDA AQUI, depois de olhar - `appendEvent` já o moveu para cada arquivo relatado,
+     * e esta linha cobre o caso em que todos os relatórios falharam na leitura.
+     */
+    await startClock(root);
+    process.stdout.write(`${JSON.stringify(said.length > 0 ? speak(said.join("\n\n")) : pass())}\n`);
 }

package/dist/commands/import.js

@@ -5,7 +5,7 @@ import { applyAnatomyPatch, hasEdits, } from "../anatomy-patch.js";
 import { resolveAnatomy, resolveFlatParts, safePartName, } from "../anatomy-read.js";
 import { craftLines } from "../baseline-craft.js";
 import { PAGES_MAX, pageCompositionOf } from "../census-pages.js";
-import { readCredentials, readToken, resolveRegistry, sameRegistry, } from "../config.js";
+import { readCredentials, readProjectConfig, readToken, resolveRegistry, sameRegistry, } from "../config.js";
 import { declaredElsewhere } from "../declared-elsewhere.js";
 import { architectureGap, architectureRule, componentHome, describeArchitecture, describeChoice, describeGap, detectArchitectures, homeLine, packagingOf, proposeNewHome, resolvesAs, } from "../doctor/architecture.js";
 import { findBrokenRefs } from "../doctor/broken-refs.js";
@@ -52,7 +52,7 @@ import { mergeNamespacePairs } from "../namespace-pairs.js";
 import { namingQueue } from "../naming-queue.js";
 import { notExpressed } from "../not-expressed.js";
 import { body, paint, section } from "../output.js";
-import { outsideScope } from "../outside-scope.js";
+import { consumersOf, outsideScope, } from "../outside-scope.js";
 import { phase, startProgress } from "../progress.js";
 import { repoStateOf } from "../repo-state.js";
 import { runtimeDeclaredVars, runtimeDeclaredVarsIn } from "../runtime-vars.js";
@@ -477,10 +477,11 @@ export async function takeCensus(root, opts) {
     const repoRoot = scopeLabel && root.endsWith(join(sep, ...scopeLabel.split("/")))
         ? root.slice(0, root.length - scopeLabel.length - 1)
         : root;
-    const outside = await outsideScope(repoRoot, [
-        ...(scopeLabel ? [scopeLabel] : []),
-        ...(opts?.usage ?? []).map((u) => u.label),
-    ]).catch(() => null);
+    /**
+     * A MEDIÇÃO EM SI ACONTECE MAIS ABAIXO, quando o nome do pacote do escopo já foi lido - ver
+     * `scopePkg`. É ele que diz quem CONSOME a biblioteca, e sem essa resposta a linha do fora
+     * nomeia os lugares sem design e cala sobre os dois apps onde ele escreve tela.
+     */
     /**
      * THE LIVE CATALOGUE, once, before anything is matched.
      *
@@ -2494,6 +2495,23 @@ export async function takeCensus(root, opts) {
      * terceiro, e os dois casos são nós já nomeados. Sem eles a fila cobraria trabalho que não
      * existe, que é exatamente o defeito que ela vem medir.
      */
+    /**
+     * O QUE O ESCOPO DEIXOU DE FORA, e quem continua governado apesar de estar fora dele.
+     *
+     * Aqui e não lá em cima porque a resposta depende de `scopePkg`: os consumidores são quem
+     * DECLARA depender desta biblioteca, e a saída deles é a lista que ele escreveu no config.
+     */
+    const outside = await outsideScope(repoRoot, [
+        ...(scopeLabel ? [scopeLabel] : []),
+        ...(opts?.usage ?? []).map((u) => u.label),
+    ], {
+        consumers: [
+            ...(opts?.usage ?? []).map((u) => u.label),
+            ...(await consumersOf(repoRoot, scopePkg).catch(() => [])),
+        ],
+        ungoverned: (await readProjectConfig(repoRoot).catch(() => null))
+            ?.ungoverned,
+    }).catch(() => null);
     const naming = namingQueue(looks, (name) => {
         const c = components.find((x) => x.name === name && !x.from);
         const target = c?.canonical ?? (c?.bucket === "exclusive" ? c.name : null);
@@ -2824,7 +2842,12 @@ export async function takeCensus(root, opts) {
             values: d.findings.length,
             named: d.named,
             tokenUses: d.tokenUses,
-            coverage: d.coverage,
+            /**
+             * O PERCENTUAL SÓ EXISTE QUANDO HOUVE O QUE MEDIR - ver `Reach` em `scan.ts`. Um repositório
+             * sem um único valor de design não tira 100: o campo simplesmente não sai, e quem lê o censo
+             * distingue "não veio do sistema" de "não havia o que contar".
+             */
+            ...(d.reach.measured ? { coverage: d.reach.percent } : {}),
             ownUses: d.ownUses,
             phantomUses: d.phantomUses,
         },

package/dist/commands/mcp.js

@@ -386,10 +386,24 @@ async function checkFile(root, path) {
     if (reports.length === 0)
         return fromContract(`Nothing readable at ${path}.`);
     const d = diagnose(reports);
-    const out = [
-        `${table.name ?? table.slug}: ${d.coverage}% of design values come from the system.`,
-        `${d.tokenUses} from the system, ${d.findings.length} written by hand${d.phantomUses > 0 ? `, ${d.phantomUses} naming nothing` : ""}.`,
-    ];
+    /**
+     * `0%` DEIXOU DE RESPONDER POR TRÊS COISAS - ver `Reach` em `scan.ts`.
+     *
+     * Esta linha dizia `0% of design values come from the system` tanto para um arquivo que escreve
+     * tudo à mão quanto para um onde a régua não tinha o que ler. Medido em 12/09 no `codelevel`:
+     * `CapabilityCard.tsx` tem 0 usos e 0 achados, e a mesma conta interna que aqui devolvia `0%`
+     * devolvia `100%` no relatório do projeto inteiro. Agora a frase é outra, e ela é a verdade
+     * daquele arquivo em vez de uma nota que ninguém consegue conferir.
+     */
+    const out = d.reach.measured
+        ? [
+            `${table.name ?? table.slug}: ${d.reach.percent}% of design values come from the system - ${d.reach.uses} of ${d.reach.of}.`,
+            `${d.tokenUses} from the system, ${d.findings.length} written by hand${d.phantomUses > 0 ? `, ${d.phantomUses} naming nothing` : ""}.`,
+        ]
+        : [
+            `${table.name ?? table.slug}: ${d.reach.why} here, so there is no coverage to report - not 0%, and not 100%.`,
+            "Nothing in this file writes a colour, a length, a font or a shadow.",
+        ];
     if (d.findings.length > 0) {
         out.push("", "Written by hand:");
         for (const f of d.findings.slice(0, 40)) {

package/dist/commands/upgrade.js

@@ -335,6 +335,23 @@ export async function upgrade(asked, opts) {
         }
         if (!opts.force) {
             console.log(`✓ ${slug} is already at the latest version (v${installed}).`);
+            /**
+             * A FIAÇÃO É REFEITA AQUI TAMBÉM - e a falta disto era um comando que mandava rodar ELE
+             * MESMO (dono, 12/09).
+             *
+             * `rewireIfBehind` só era chamado dentro do ramo de rematerialização, ou seja: só quando a
+             * PASTA estava atrasada. A pasta e o hook são dois lugares diferentes e ficam defasados por
+             * motivos diferentes - `align` já os trata como dois fatos, e o comentário dele diz por quê:
+             * *"um alarme desligado por um conserto parcial é pior que alarme nenhum"*. Faltava o outro
+             * lado da mesma moeda: um CONSERTO parcial que desliga nada.
+             *
+             * O que ele viu: pasta em dia, hook pinado em 0.16.416, CLI rodando 0.16.419. O `upgrade`
+             * imprimia *"already at the latest version"* e saía, e o alinhamento seguinte recomendava
+             * `npx synthesisui upgrade` - o comando que ele tinha acabado de rodar.
+             *
+             * `wireAgent` é um merge idempotente: quando já está na versão certa, não escreve nada.
+             */
+            await rewireIfBehind(root, opts.cli);
             /**
              * E AQUI TAMBEM, que e' o caminho mais percorrido de todos: sem gap de versao, este comando
              * dizia uma linha e sumia. Quem editou tres componentes ficava sem saber se eles seguem sendo

package/dist/config.js

@@ -163,6 +163,20 @@ export async function readProjectConfig(root) {
             ...(parsed.absorb === "code" || parsed.absorb === "system"
                 ? { absorb: parsed.absorb }
                 : {}),
+            /**
+             * O QUE ELE TIROU DA GOVERNANÇA - ver `ProjectConfig.ungoverned`.
+             *
+             * Sem o campo, a lista é vazia e tudo que consome a biblioteca segue governado. Entradas que
+             * não são caminho são descartadas em silêncio: um config meio escrito não pode governar mais
+             * do que o dono dele pediu, e também não pode derrubar o comando.
+             */
+            ...(Array.isArray(parsed.ungoverned)
+                ? {
+                    ungoverned: parsed.ungoverned
+                        .filter((x) => typeof x === "string" && !!x.trim())
+                        .map((x) => x.trim().replace(/^\.\//, "").replace(/\/$/, "")),
+                }
+                : {}),
         };
     }
     catch {