synthesisui 0.16.336 → 0.16.338

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 { readCredentials, readToken, resolveRegistry, sameRegistry, } from "../config.js";
 import { declaredElsewhere } from "../declared-elsewhere.js";
-import { architectureRule, componentHome, describeArchitecture, describeChoice, detectArchitectures, homeLine, proposeNewHome, } from "../doctor/architecture.js";
+import { architectureGap, architectureRule, componentHome, describeArchitecture, describeChoice, describeGap, detectArchitectures, homeLine, proposeNewHome, } from "../doctor/architecture.js";
 import { findBrokenRefs } from "../doctor/broken-refs.js";
 import { nestingRules, propRules, readDefinitionProps, readNesting, readRuntime, } from "../doctor/call-sites.js";
 import { asCatalogueTable, describeFallback, fetchCatalogue, } from "../doctor/catalogue-fetch.js";
@@ -388,6 +388,21 @@ const MAX_GLOBAL_CLASSES = 300;
  * dois com folga e continua sendo um teto de verdade, alinhado com `DISTINCT_CAP` do ledger.
  */
 const SKIPPED_CAP = 4096;
+/**
+ * UM ARQUIVO QUE MOSTRA UM COMPONENTE NÃO É UM COMPONENTE - a mesma exclusão nos três lugares.
+ *
+ * Stories and tests compose components to SHOW them; counting those as the product's own
+ * composition is the same lie the colour census told before they were set aside.
+ *
+ * E ela vale igual para a CONTAGEM que a organização declara. Medido em 30/08 em
+ * `codelevel-monorepo/packages/ui`: 75 arquivos `.tsx`, dos quais 38 são `*.stories.tsx` e 37 são
+ * componente. Dizer "we read 75 component files" a quem tem 37 é metade do número inventada por
+ * nós - e a frase existe justamente para o caso em que o cliente vai conferir o número na mão.
+ *
+ * UMA constante, e não três literais: a terceira cópia já existia antes desta, e uma delas
+ * envelhecer sozinha significa dois denominadores diferentes para a mesma palavra na mesma saída.
+ */
+const SHOWS_A_COMPONENT = /(\.(spec|test|stories)\.[a-z]+$|__tests__\/|(^|\/)\.storybook\/)/;
 export async function takeCensus(root, opts) {
     /**
      * O RELATÓRIO SÓ SAI QUANDO ALGUÉM O PEDIU - `say` cala quando o chamador é uma RE-medição.
@@ -552,6 +567,8 @@ export async function takeCensus(root, opts) {
      * naming how the project is organised costs no second pass. See `architecture.ts`.
      */
     const dirs = new Map();
+    /** Uma entrada nova da árvore, com os três contadores em zero. */
+    const freshDir = () => ({ dirs: new Set(), files: 0, direct: 0 });
     /** Parent → child → the files that put one inside the other. */
     const nesting = new Map();
     /**
@@ -621,17 +638,37 @@ export async function takeCensus(root, opts) {
             continue;
         const rel = relative(root, file);
         progress.step(rel);
-        if (/\.(tsx|jsx|vue|svelte)$/i.test(rel)) {
+        /**
+         * A ORGANIZAÇÃO SÓ CONTA COMPONENTE - `SHOWS_A_COMPONENT`, a mesma exclusão de baixo.
+         *
+         * Este bloco roda onze linhas ANTES do filtro, e por isso contava story e teste como código
+         * do produto: 75 arquivos onde o cliente tem 37 (`codelevel-monorepo/packages/ui`, 30/08). O
+         * número que a organização declara é o que ele confere na mão, então ele conta o que ele
+         * conta quando confere.
+         */
+        if (/\.(tsx|jsx|vue|svelte)$/i.test(rel) && !SHOWS_A_COMPONENT.test(rel)) {
             const parts = rel.split("/");
             // Every ancestor learns the name of the child directly under it, which is all
             // the shape detector needs and is one pass rather than a tree walk.
             for (let i = 0; i < parts.length - 1; i++) {
                 const at = parts.slice(0, i).join("/");
-                const entry = dirs.get(at) ?? { dirs: new Set(), files: 0 };
+                const entry = dirs.get(at) ?? freshDir();
                 entry.dirs.add(parts[i]);
                 entry.files += 1;
                 dirs.set(at, entry);
             }
+            /**
+             * A PASTA-MÃE, CREDITADA PELO ARQUIVO QUE ELA SEGURA - ver `DirEntry.direct`.
+             *
+             * O laço acima nunca roda para um arquivo na RAIZ do escopo (`parts.length - 1 === 0`), e
+             * era isso que fazia um projeto de quatro componentes soltos - uma forma real de biblioteca
+             * pequena - não produzir entrada nenhuma e ficar em silêncio absoluto sobre a própria
+             * organização. Aqui a raiz é uma pasta como as outras.
+             */
+            const home = parts.slice(0, -1).join("/");
+            const entry = dirs.get(home) ?? freshDir();
+            entry.direct += 1;
+            dirs.set(home, entry);
         }
         sources.push({ file: rel, source: src });
         readSignalsInto(signals, importTally, rel, src);
@@ -639,7 +676,7 @@ export async function takeCensus(root, opts) {
         // Stories and tests compose components to SHOW them; counting those as the
         // product's own composition is the same lie the colour census told before
         // they were set aside.
-        if (!/(\.(spec|test|stories)\.[a-z]+$|__tests__\/|(^|\/)\.storybook\/)/.test(rel)) {
+        if (!SHOWS_A_COMPONENT.test(rel)) {
             scanComponentsInto(tally, rel, src, internal);
             /**
              * The other half: what this file EXPORTS, with the axes its types declare. A
@@ -1282,11 +1319,24 @@ export async function takeCensus(root, opts) {
         }
     }
     progress.done();
-    const architectures = detectArchitectures([...dirs.entries()].map(([path, v]) => ({
+    /** A ÁRVORE MEDIDA, uma vez - as três leituras abaixo saem todas dela. */
+    const dirEntries = [...dirs.entries()].map(([path, v]) => ({
         path: path || ".",
         dirs: [...v.dirs],
         files: v.files,
-    })));
+        direct: v.direct,
+    }));
+    const architectures = detectArchitectures(dirEntries);
+    /**
+     * A LACUNA, quando nada foi reconhecido - ver `architectureGap` (`INV-COB-08`). Nenhuma
+     * decisão aqui: este arquivo IMPRIME e GRAVA o que aquela camada decidiu.
+     */
+    const gap = architectureGap(dirEntries, architectures);
+    /**
+     * ONDE O PRÓXIMO COMPONENTE VAI - derivado do escopo que ele apontou, e por isso a
+     * pergunta sobrevive a não reconhecermos organização nenhuma.
+     */
+    const newHome = proposeNewHome(dirEntries, scopeLabel);
     const d = diagnose(reports);
     const allComposed = tallyToInventory(tally, 400);
     /**
@@ -1419,7 +1469,7 @@ export async function takeCensus(root, opts) {
             }
             edges.set(file, edgesIn(src));
             const rel = join(u.label, relative(u.path, file));
-            if (/(\.(spec|test|stories)\.[a-z]+$|__tests__\/|(^|\/)\.storybook\/)/.test(rel)) {
+            if (SHOWS_A_COMPONENT.test(rel)) {
                 continue;
             }
             usageSeen.add(rel);
@@ -2007,6 +2057,16 @@ export async function takeCensus(root, opts) {
             say(body(paint.faint(`  ${describeArchitecture(a)}`)));
         }
     }
+    else if (gap) {
+        /**
+         * A MESMA SEÇÃO, NO MESMO LUGAR DA SAÍDA - `INV-COB-08`. Uma leitura que rodou e não
+         * reconheceu nada tinha esta seção inteira desaparecendo, e a ausência lê como "não
+         * medimos nada aqui" em vez de "medimos, e a régua é nossa".
+         */
+        say("");
+        say(section("How this project is organised"));
+        say(body(describeGap(gap, scopeLabel)));
+    }
     if (skips.length > 0) {
         say("");
         say(body(describeGate(scoped.length, skips.length)));
@@ -2492,13 +2552,24 @@ export async function takeCensus(root, opts) {
                     line: homeLine(a),
                     rule: architectureRule(a, scopeLabel),
                 })),
-                ...(proposeNewHome(architectures, scopeLabel)
-                    ? {
-                        newComponentHome: proposeNewHome(architectures, scopeLabel),
-                    }
-                    : {}),
             }
             : {}),
+        /**
+         * A LEITURA QUE RODOU E NÃO RECONHECEU NADA - `INV-COB-08`, ver `architectureGap`.
+         *
+         * Só os DOIS números medidos. Sem nome de forma, sem regra e sem caminho: nada foi
+         * reconhecido, então qualquer um dos três seria adivinhação nossa gravada como fato dele.
+         */
+        ...(gap ? { architectureGap: gap } : {}),
+        /**
+         * FORA DO `if` DAS FORMAS, e é isso que mantém a pergunta viva - `INV-COB-08`.
+         *
+         * "Daqui em diante vai num lugar novo" é derivada do escopo que ele apontou e não depende
+         * de reconhecermos organização nenhuma. Presa dentro do bloco acima, ela sumia junto com o
+         * resto justamente para quem mais precisa dela: o projeto sobre o qual não temos nada a
+         * dizer é o único cujo agente não recebe regra de onde criar componente.
+         */
+        ...(newHome ? { newComponentHome: newHome } : {}),
         ...(skips.length > 0
             ? {
                 /**

package/dist/doctor/architecture.js

@@ -52,12 +52,98 @@ const SHAPES = [
         describe: (a) => `Every component sits directly under \`${a.root}\`, one folder deep. It is the shape that stays legible longest while a system is small, and the one to revisit when the folder passes about forty names.`,
     },
 ];
+/**
+ * A MESMA ORGANIZAÇÃO VISTA DE MAIS PERTO NÃO É UMA SEGUNDA ESCOLHA (`INV-COB-09`).
+ *
+ * O QUE O CLIENTE GANHA: a pergunta "qual organização tem PRIORIDADE" só lhe oferece
+ * organizações que disputam de verdade. Sem isto ele escolhe entre uma escada atômica e uma
+ * pasta que mora DENTRO dela - a mesma organização, medida de duas distâncias -, e qualquer
+ * resposta que ele der é a mesma resposta. Uma pergunta cujas opções não se excluem não é uma
+ * pergunta: é um formulário que ele preenche sem que nada mude no que os agentes dele escrevem.
+ *
+ * A PROPRIEDADE: uma organização é reconhecida no lugar mais RASO que a explica. Uma forma é a
+ * mesma organização vista de mais perto quando é do MESMO tipo de uma que já a cobre, ou quando é
+ * a leitura genérica (`flat`) de um lugar que outra forma já nomeia com mais informação. Formas de
+ * tipos DIFERENTES descrevem fatos diferentes, e nenhuma apaga a outra - o peso (`MINOR_SHARE`) já
+ * decide qual delas pede decisão e qual é dita como canto.
+ *
+ * O DESEMPATE NO MESMO ROOT continua sendo só o de `flat`, e ele não muda aqui: duas formas
+ * específicas na mesma pasta (`layered` e `colocated` em `src`, por exemplo) são duas leituras
+ * legítimas do mesmo lugar, e escolher entre elas é justamente a decisão que a pergunta existe
+ * para pedir. `flat` é a forma mais permissiva das cinco - basta uma pasta `components` -, então
+ * onde uma específica também casa, ela é a mesma coisa dita com menos informação.
+ *
+ * MEDIÇÃO de 31/08 - população e régua de enumeração de escopo escritas UMA vez em
+ * `contracts/camada-4-cobertura.md` (`INV-COB-09`), e não recopiadas aqui: 65 formas reconhecidas
+ * em 43 escopos passam a 56; as 9 subordinadas dizem o mesmo fato de um ancestral, e estão em 6
+ * escopos. Foto daquelas populações naquele dia, nunca invariante.
+ */
+export function dropShapesAlreadyExplained(found) {
+    return found.filter((a) => !found.some((b) => b !== a && explains(b, a)));
+}
+/**
+ * `other` é a MESMA organização que `shape`, vista de mais longe?
+ *
+ * A pergunta não é "está por perto": é se as duas dizem o mesmo fato. Uma forma é a mesma
+ * organização vista de mais perto quando é do MESMO tipo de uma que já a cobre, ou quando é a
+ * leitura genérica (`flat`) de um lugar que outra forma já nomeia com mais informação.
+ *
+ * FORMAS DE TIPOS DIFERENTES DESCREVEM FATOS DIFERENTES, e nenhuma apaga a outra - nem quando uma
+ * mora dentro da outra. O layout React mais comum que existe é a prova: `src/{components}` com
+ * `src/components/{atoms, molecules, organisms}` embaixo. Com o ancestral vencendo sempre, a
+ * escada atômica SOME, e o que sobra é a leitura mais pobre das duas - o cliente recebe no
+ * `CLAUDE.md` dele a regra "Every component sits directly under `src`, one folder deep", que é
+ * FALSA no repositório dele, e o caminho `src/{components}`, que manda o agente parar um degrau
+ * antes de onde o componente nasce. Uma opção errada é pior que duas opções: ele nem sabe que
+ * havia o que decidir.
+ *
+ * Quem decide qual das duas pede decisão e qual é dita como canto é o PESO (`MINOR_SHARE`), e não
+ * este predicado - uma escada de 6 arquivos dentro de um `colocated` de 780 continua sendo dita,
+ * e continua não virando pergunta.
+ */
+function explains(other, shape) {
+    if (isUnderPath(other.root, shape.root))
+        return other.kind === shape.kind || shape.kind === "flat";
+    return (pathKey(other.root) === pathKey(shape.root) &&
+        shape.kind === "flat" &&
+        other.kind !== "flat");
+}
+/**
+ * O CAMINHO COMPARÁVEL - a raiz do escopo é escrita `.` pela caminhada, e comparada com `""` ela é
+ * a mesma pasta. Comparar as strings cruas faria a raiz deixar de explicar o que está embaixo
+ * dela, que é o caso mais comum de todos.
+ *
+ * AS DUAS OUTRAS NORMALIZAÇÕES SÃO DEFENSIVAS, e ficam nomeadas como tal: barra final e `./` na
+ * frente não são alcançáveis pela caminhada real - `import.ts` escreve `path || "."` e monta o
+ * resto com `parts.slice(…).join("/")` -, então nenhum teste pode reprová-las por comportamento.
+ * Elas custam duas chamadas de `replace` e protegem quem montar a árvore à mão.
+ */
+function pathKey(path) {
+    const tidy = path.replace(/\/+$/, "").replace(/^\.\//, "");
+    return tidy === "." ? "" : tidy;
+}
+/**
+ * `path` está DENTRO de `ancestor` - por SEGMENTO, nunca por prefixo de texto.
+ *
+ * `"src/ui-kit".startsWith("src/ui")` é verdadeiro e está errado: são duas pastas irmãs, e por
+ * essa comparação uma organização real desapareceria da pergunta sem que nada a explicasse.
+ */
+function isUnderPath(ancestor, path) {
+    const a = pathKey(ancestor);
+    const p = pathKey(path);
+    /**
+     * A MESMA PASTA JÁ CAI FORA POR CONSTRUÇÃO, e por isso não há guarda para ela: com `a === p`,
+     * `p.startsWith(`${a}/`)` é falso (uma pasta não é filha de si mesma) e a raiz cai no `p !== ""`.
+     * Uma guarda a mais aqui seria linha que nenhum caso alcança - e código que nenhum caso alcança
+     * é código que nenhum teste pode reprovar.
+     */
+    return a === "" ? p !== "" : p.startsWith(`${a}/`);
+}
 /**
  * Which shapes this tree actually has, ranked by how much code each holds.
  *
- * `flat` is checked last and only reported when nothing more specific matched under the
- * same root: a `components/` folder inside an atomic library is not a second
- * architecture, it is the same one seen from further away.
+ * O que sobra é o que governa código que nenhuma outra forma já governa - a subordinação inteira
+ * mora em `dropShapesAlreadyExplained` (`INV-COB-09`), numa redação só.
  */
 export function detectArchitectures(entries) {
     const found = [];
@@ -76,10 +162,6 @@ export function detectArchitectures(entries) {
             }
             if (!complete)
                 continue;
-            if (shape.kind === "flat" &&
-                found.some((f) => f.root === entry.path && f.kind !== "flat")) {
-                continue;
-            }
             found.push({
                 kind: shape.kind,
                 root: entry.path,
@@ -88,10 +170,7 @@ export function detectArchitectures(entries) {
             });
         }
     }
-    return found
-        .filter((a) => a.kind !== "flat" ||
-        !found.some((b) => b.root === a.root && b.kind !== "flat"))
-        .sort((a, b) => b.files - a.files || a.root.localeCompare(b.root));
+    return dropShapesAlreadyExplained(found).sort((a, b) => b.files - a.files || a.root.localeCompare(b.root));
 }
 /** The sentence that becomes the rule. Written for an agent about to add a file. */
 export function describeArchitecture(a) {
@@ -165,13 +244,26 @@ export function homeLine(a) {
  * ela a pergunta é sobre o passado.
  *
  * O caminho é DERIVADO, não inventado: fica dentro do escopo que a pessoa já apontou como
- * fonte de verdade, e usa `src/` só quando as formas medidas mostram que o escopo tem `src`.
+ * fonte de verdade, e usa `src/` só quando a árvore medida mostra que o escopo tem `src`.
  * Sem nome de sistema dentro dele de propósito - quem quer isso digita, e digitar um nome
  * é mais honesto do que a gente adivinhar a grafia dele.
  */
-export function proposeNewHome(found, scope) {
+export function proposeNewHome(
+/**
+ * A ÁRVORE MEDIDA, e não a lista do que foi reconhecido - a porta fechada.
+ *
+ * `hasSrc` era lido da lista de formas, e com ela VAZIA - que é exatamente o caso em que
+ * nenhuma organização conhecida apareceu - a resposta era sempre "não tem `src`": num
+ * projeto cujos 75 arquivos moram todos sob `src/`, a proposta mandava o cliente para uma
+ * pasta na raiz. Duas entradas (a árvore e as formas) podem discordar; uma não pode, e as
+ * formas saem da árvore aqui dentro.
+ */
+entries, scope) {
+    const found = detectArchitectures(entries);
     const base = scope ? scope.replace(/\/+$/, "") : "";
-    const hasSrc = found.some((a) => a.root === "src" || a.root.startsWith("src/"));
+    const hasSrc = entries.some((e) => e.path === "src" ||
+        e.path.startsWith("src/") ||
+        (isRoot(e.path) && e.dirs.includes("src")));
     const trunk = `${base ? `${base}/` : ""}${hasSrc ? "src/components" : "components"}`;
     const fresh = `${trunk}/{atoms, molecules, organisms}`;
     /** Se a proposta é o que já existe, ela não é uma pasta nova - e oferecê-la seria repetir a opção 1. */
@@ -233,3 +325,90 @@ export function describeChoice(found) {
     const list = options.map(say).join(", ");
     return `${options.length} shapes govern real code, and none of them is a mistake: ${list}.${notes.length > 0 ? ` Smaller corners, reported and not asked about: ${notes.map(say).join(", ")}.` : ""} Pick which one has PRIORITY - it becomes the rule every prompt reads, and the others stay true without deciding.`;
 }
+/** A raiz do escopo, que a caminhada escreve como `.` e o mapa guarda como "". */
+function isRoot(path) {
+    return path === "." || path === "";
+}
+/**
+ * A ORGANIZAÇÃO QUE NINGUÉM SOUBE NOMEAR - declarada, nunca calada (`INV-COB-08`).
+ *
+ * O QUE O CLIENTE GANHA: quando a leitura roda e nenhuma das organizações conhecidas
+ * aparece, ele continua recebendo uma resposta - quantos arquivos de componente foram
+ * medidos, e em quantas pastas eles estão - com a frase dizendo que o limite é a nossa
+ * régua e não o projeto dele. Sem isto a seção inteira sobre organização SOME da saída, e
+ * silêncio é indistinguível de "não medimos nada aqui": ele fica sem saber que a régua
+ * rodou, sem o número que ela mediu, e sem a chance de dizer onde o próximo componente vai.
+ *
+ * MEDIÇÃO de 30/08 - a população e a régua de enumeração de escopo estão escritas UMA vez, em
+ * `contracts/camada-4-cobertura.md` (`INV-COB-08`), e não são recopiadas aqui: 6 de 43 escopos
+ * com componentes (14%) não casam nenhuma organização conhecida, e o maior deles tem 37
+ * arquivos. No banco de produção, na mesma data, há 1 sistema com censo de import guardado, e
+ * ele é um dos mudos - 1 de 1. Foto daquelas populações naquele dia, nunca invariante.
+ *
+ * O QUE ESTE BLOCO NÃO FAZ, de propósito: reconhecer uma organização nova. Uma sexta forma é
+ * outra entrega. Aqui a ausência de reconhecimento vira DECLARAÇÃO, nunca um palpite.
+ */
+/**
+ * ABAIXO DISTO NÃO HÁ ORGANIZAÇÃO A DECLARAR - há conteúdo.
+ *
+ * MEDIÇÃO de 30/08 - população e régua de enumeração de escopo em
+ * `contracts/camada-4-cobertura.md` (`INV-COB-08`): dos 6 escopos mudos, 4 têm um ou dois
+ * arquivos de componente ao todo. Um ou dois arquivos não organizam nada, e dizer "não sei
+ * nomear a sua organização" sobre eles é ruído com cara de lacuna. Os 2 que sobram são os que a
+ * frase existe para alcançar - 37 arquivos em 37 pastas, e 7 arquivos em 1 pasta. O 3 é lido
+ * dessa foto, e não é regra do produto.
+ *
+ * O piso é ancorado por LITERAIS no spec (2 cala, 3 fala) e não por esta constante: um teste
+ * escrito como `GAP_MIN_FILES - 1` acompanha a constante para onde ela for, e com ela em zero o
+ * produto imprimiria "We read 0 component files in 0 folders" - o zero pelado da lei 14 - com a
+ * suíte inteira verde.
+ */
+export const GAP_MIN_FILES = 3;
+/**
+ * A LEITURA QUE RODOU E NÃO RECONHECEU NADA - o estado `unknown` desta leitura.
+ *
+ * Devolve `null` quando há forma reconhecida (aí quem fala é `describeChoice`) e quando o
+ * escopo é pequeno demais para ter organização (`GAP_MIN_FILES`).
+ */
+export function architectureGap(entries, found) {
+    if (found.length > 0)
+        return null;
+    /**
+     * SOMAR `direct`, e nunca `files`: a caminhada credita cada arquivo a TODOS os ancestrais,
+     * então somar `files` conta o mesmo arquivo uma vez por nível. `direct` é o arquivo na pasta
+     * onde ele está, uma vez só - a mesma conta que o `find` acima faz na máquina dele.
+     */
+    let files = 0;
+    let folders = 0;
+    for (const e of entries) {
+        if (e.direct <= 0)
+            continue;
+        files += e.direct;
+        folders += 1;
+    }
+    if (files < GAP_MIN_FILES)
+        return null;
+    return { files, folders };
+}
+/**
+ * A FRASE, no tom das outras desta camada: o número medido, o motivo, e nenhuma acusação.
+ *
+ * A ordem é a da dúvida de quem lê - o que medimos, de quem é o limite, e o que isso custa
+ * a ele hoje. A segunda parte não é gentileza: sem ela a frase lê como um defeito do
+ * repositório dele, e o defeito é da régua.
+ */
+export function describeGap(g, 
+/**
+ * ONDE MEDIMOS, quando a leitura foi apontada para uma parte do repositório.
+ *
+ * "here" não resolve para nada na cabeça de quem rodou `--scope packages/ui` da raiz de um
+ * monorepo, e num import de dois lugares a mesma seção sai duas vezes falando de pastas
+ * diferentes. Sem rótulo a redação continua a mesma: uma leitura da raiz não tem outro
+ * lugar a que se referir.
+ */
+where) {
+    const files = `${g.files} component file${g.files === 1 ? "" : "s"}`;
+    const folders = `${g.folders} folder${g.folders === 1 ? "" : "s"}`;
+    const at = where ? `under \`${where}\`` : "here";
+    return `We read ${files} in ${folders} ${at}, and none of the ways of organising code this version can name fits them. That does not mean your project has no structure; it means ours does not have a name for yours yet. Nothing about where code lives was written into your rules, so an agent reading your \`CLAUDE.md\` guesses where a new component goes until you tell it.`;
+}

package/dist/install-marks.js

@@ -375,7 +375,47 @@ export const CHECKER_SINCE = "0.16.308";
  * nunca era alcançado. Medido: 1134 componentes, 77 mudaram, e a receita que o cliente recebe muda
  * com eles. Uma medição anterior não produz o conserto, então a marca sobe.
  */
-export const READER_SINCE = "0.16.336";
+/**
+ * 0.16.336 -> 0.16.337 em 30/08 (INV-COB-08): a contagem de arquivos por organização deixou de
+ * incluir story, spec e teste. Um censo já gravado carrega o número inflado - `atomic@src/lib/SignalUI`
+ * dizia 69 arquivos onde há 38 - e esse número viaja para o CLAUDE.md do cliente como a EVIDÊNCIA da
+ * regra (`architectureRule().evidence`, "holding N component files"). Não há como corrigi-lo a partir
+ * do censo: saber quais daqueles arquivos eram story exige reler o disco, e só a remedição lê. Por
+ * isso a marca sobe.
+ *
+ * MEDIÇÃO de 30/08 - população e régua de enumeração de escopo em
+ * `contracts/camada-4-cobertura.md` (`INV-COB-08`): `frontend-hub/packages/ui` sai de 69 para 38
+ * (mesma forma, mesmo lugar); `codelevel/packages/ui` sai de 75 para 37. O ranking não mudou em
+ * nenhum dos 43 escopos medidos, então ninguém recebe uma organização DIFERENTE - só o número
+ * honesto.
+ */
+/**
+ * 0.16.337 -> 0.16.338 em 31/08 (`INV-COB-09`): uma organização passou a ser reconhecida no lugar
+ * mais RASO que a explica. Uma forma do MESMO tipo de outra que já a cobre, ou a leitura genérica
+ * de um lugar que outra já nomeia com mais informação, deixa de ser gravada como uma segunda
+ * organização. Tipos DIFERENTES continuam os dois gravados: eles dizem fatos diferentes sobre o
+ * mesmo código, e apagar o de dentro entregaria a leitura mais pobre como se fosse a única.
+ *
+ * A marca sobe porque um censo já gravado carrega as entradas duplicadas e não há como saber quais
+ * eram subordinadas sem reler a árvore do disco: a subordinação se decide comparando os CAMINHOS
+ * medidos, e um censo antigo guarda o que foi reconhecido, não a caminhada que o reconheceu. Só a
+ * remedição lê o disco.
+ *
+ * O QUE O `sync` ENTREGA, e o que ele NÃO entrega. Ele remede com `takeCensus`, então o campo
+ * `architectures` do censo é reescrito sem as entradas subordinadas e o censo reenviado já chega
+ * limpo. Ele NÃO reimprime a seção de organização no terminal - essa seção é do relatório de
+ * `import` -, e NÃO reescreve a regra no `CLAUDE.md` dele: aquela linha nasce da conversa de
+ * import, que lê `architectures[].rule` do censo, e `rulesFromCensus` não olha para este campo.
+ * Quem já tem a regra escrita a partir de uma organização subordinada continua com ela até um
+ * import novo, e dizer o contrário seria prometer que um comando conserta o que ele não conserta.
+ *
+ * MEDIÇÃO de 31/08 - população e régua de enumeração de escopo em
+ * `contracts/camada-4-cobertura.md` (`INV-COB-09`): 65 formas reconhecidas em 43 escopos passam a
+ * 56; as 9 subordinadas dizem o mesmo fato de um ancestral, e estão em 6 escopos. O hash do corpus
+ * NÃO se moveu, e isso é a informação: nenhum dos 28 apps dourados tem forma repetindo o que uma
+ * ancestral já diz, então a estabilidade ali prova ausência de regressão e não ausência de efeito.
+ */
+export const READER_SINCE = "0.16.338";
 /**
  * O QUE ESTÁ INSTALADO AQUI FICOU PARA TRÁS - e as DUAS condições que fazem isso ser verdade.
  *

package/dist/merge-census.js

@@ -119,6 +119,32 @@ export function mergeCensus(list) {
     let brokenRefs = first.brokenRefs ?? undefined;
     let conventions = first.conventions ?? undefined;
     let architectures = first.architectures ?? undefined;
+    /**
+     * A LACUNA DE ORGANIZAÇÃO, SOMADA - `INV-COB-08`, ver `architectureGap` em `import.ts`.
+     *
+     * A declaração de qualquer escopo SOBREVIVE à fusão. Ela diz "medimos aqui e não soubemos
+     * nomear"; deixá-la de fora porque o outro escopo foi reconhecido devolve o silêncio que a
+     * invariante existe para eliminar, um passo adiante - e o cliente que rodou com dois escopos
+     * é justamente quem tem mais lugar onde a resposta pode sumir.
+     *
+     * SOMADOS, e não o primeiro que aparece, porque os dois são CONTAGENS e contagem é aditiva:
+     * o total descreve exatamente as partes que ficaram sem nome, e nenhum arquivo contado aqui
+     * pertence a um escopo reconhecido. É o oposto do caso da cobertura logo abaixo, onde somar
+     * percentuais produziria um número que não descreve medição nenhuma.
+     */
+    let gapFiles = first.architectureGap
+        ?.files;
+    let gapFolders = first.architectureGap
+        ?.folders;
+    /**
+     * ONDE O PRÓXIMO COMPONENTE VAI - o PRIMEIRO escopo vence, a mesma regra de `scope`.
+     *
+     * É um caminho, não uma contagem: dois caminhos não somam, e escolher o do escopo seguinte
+     * mandaria o agente para um lugar fora do escopo que o censo declara como o dele.
+     */
+    const newComponentHome = list
+        .map((c) => c.newComponentHome)
+        .find((h) => typeof h === "string" && h.length > 0);
     let components = first.components ?? undefined;
     let defined = first.defined ?? undefined;
     const stack = [...(first.project.stack ?? [])];
@@ -177,6 +203,11 @@ export function mergeCensus(list) {
         brokenRefs = concat(brokenRefs, c.brokenRefs);
         conventions = concat(conventions, c.conventions);
         architectures = concat(architectures, c.architectures);
+        const gap = c.architectureGap;
+        if (gap) {
+            gapFiles = (gapFiles ?? 0) + (gap.files ?? 0);
+            gapFolders = (gapFolders ?? 0) + (gap.folders ?? 0);
+        }
         components = concat(components, c.components);
         defined = concat(defined, c.defined);
         for (const s of c.project.stack ?? [])
@@ -260,6 +291,10 @@ export function mergeCensus(list) {
         out.conventions = conventions;
     if (architectures && architectures.length > 0)
         out.architectures = architectures;
+    if (gapFiles !== undefined && gapFolders !== undefined)
+        out.architectureGap = { files: gapFiles, folders: gapFolders };
+    if (newComponentHome)
+        out.newComponentHome = newComponentHome;
     if (components && components.length > 0)
         out.components = components;
     if (defined && defined.length > 0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.16.336",
+  "version": "0.16.338",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {