synthesisui 0.16.338 → 0.16.342

package/dist/commands/align.js

@@ -313,8 +313,14 @@ const REPAIR_SAID = {
     spacing: "spacing values in your system were connected to the steps your own scale declares",
     orphans: "recipes your measured scope no longer declares were removed",
     roles: "colour roles were pointed at the ramps your repository declares",
-    reground: "the foundation was rebuilt from your census",
-    interpretation: "your census was re-read with a newer interpretation",
+    /**
+     * `census` SAIU DESTAS DUAS - `INV-VOC-05`. As três irmãs acima já dizem a coisa pelo efeito no
+     * projeto dele ("the steps your own scale declares"), e estas duas diziam pelo nome da nossa
+     * peça. O texto do `align` entra no contexto do modelo no `SessionStart`, e o que o agente lê é
+     * o que ele repete para a pessoa.
+     */
+    reground: "the foundation was rebuilt from what we measured in your repository",
+    interpretation: "what we measured in your repository was read again, with a newer interpretation",
 };
 export function repairSaid(body, lock) {
     if (!lock.slug)

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 { architectureGap, architectureRule, componentHome, describeArchitecture, describeChoice, describeGap, detectArchitectures, homeLine, proposeNewHome, } from "../doctor/architecture.js";
+import { architectureGap, architectureRule, componentHome, describeArchitecture, describeChoice, describeGap, detectArchitectures, homeLine, packagingOf, proposeNewHome, resolvesAs, } 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";
@@ -44,7 +44,7 @@ import { frontierKind, packageRoot } from "../frontier-kind.js";
 import { keyframesInSheets } from "../global-keyframes.js";
 import { globalClassesWorn } from "../global-wear.js";
 import { withLibraryStructure } from "../library-structure.js";
-import { mergeCensus } from "../merge-census.js";
+import { architectureGaps, mergeCensus } from "../merge-census.js";
 import { claimName } from "../name-claim.js";
 import { mergeNamespacePairs } from "../namespace-pairs.js";
 import { namingQueue } from "../naming-queue.js";
@@ -567,8 +567,14 @@ 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 });
+    /** Uma entrada nova da árvore, com os contadores em zero e nada observado. */
+    const freshDir = () => ({
+        dirs: new Set(),
+        files: 0,
+        direct: 0,
+        index: false,
+        names: [],
+    });
     /** Parent → child → the files that put one inside the other. */
     const nesting = new Map();
     /**
@@ -668,6 +674,21 @@ export async function takeCensus(root, opts) {
             const home = parts.slice(0, -1).join("/");
             const entry = dirs.get(home) ?? freshDir();
             entry.direct += 1;
+            entry.names.push((parts[parts.length - 1] ?? "").replace(/\.[a-z]+$/i, ""));
+            dirs.set(home, entry);
+        }
+        /**
+         * O BARRIL, REGISTRADO FORA DO FILTRO DE COMPONENTE - e é por isso que ele precisa de
+         * bloco próprio.
+         *
+         * `index.ts` não é um arquivo de componente pela régua acima, então o bloco anterior nunca
+         * o vê. Sem este registro, a pasta que o cliente importa como uma unidade
+         * (`from "./ActivityRing"`) é indistinguível de uma pasta qualquer com um arquivo dentro.
+         */
+        if (/(^|\/)index\.(tsx|ts|jsx|js|vue|svelte)$/i.test(rel)) {
+            const home = rel.split("/").slice(0, -1).join("/");
+            const entry = dirs.get(home) ?? freshDir();
+            entry.index = true;
             dirs.set(home, entry);
         }
         sources.push({ file: rel, source: src });
@@ -1325,18 +1346,20 @@ export async function takeCensus(root, opts) {
         dirs: [...v.dirs],
         files: v.files,
         direct: v.direct,
+        /** COMO ESTA PASTA RESOLVE - a decisão é de `doctor/architecture.ts`; aqui só se mede. */
+        resolves: resolvesAs(path || ".", v.index, v.names),
     }));
     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 gap = architectureGap(dirEntries, architectures, scopeLabel ?? ".", newHome);
     const d = diagnose(reports);
     const allComposed = tallyToInventory(tally, 400);
     /**
@@ -2054,7 +2077,12 @@ export async function takeCensus(root, opts) {
         if (choice)
             say(body(choice));
         for (const a of architectures.slice(0, 4)) {
-            say(body(paint.faint(`  ${describeArchitecture(a)}`)));
+            /**
+             * O ESCOPO VAI JUNTO, ou o terminal imprime um caminho que não existe na raiz dele.
+             * `a.root` é relativo ao escopo medido - num monorepo lido com `--scope packages/ui`,
+             * `src/lib/SignalUI` sozinho manda a pessoa procurar na pasta errada.
+             */
+            say(body(paint.faint(`  ${describeArchitecture(a, scopeLabel)}`)));
         }
     }
     else if (gap) {
@@ -2065,7 +2093,7 @@ export async function takeCensus(root, opts) {
          */
         say("");
         say(section("How this project is organised"));
-        say(body(describeGap(gap, scopeLabel)));
+        say(body(describeGap(gap)));
     }
     if (skips.length > 0) {
         say("");
@@ -2545,22 +2573,35 @@ export async function takeCensus(root, opts) {
             : {}),
         ...(architectures.length > 0
             ? {
-                architectures: architectures.slice(0, 6).map((a) => ({
-                    ...a,
-                    /** O caminho e a frase que a PERGUNTA usa verbatim - ver `componentHome`. */
-                    home: componentHome(a, scopeLabel),
-                    line: homeLine(a),
-                    rule: architectureRule(a, scopeLabel),
-                })),
+                architectures: architectures.slice(0, 6).map((a) => {
+                    /**
+                     * O EMPACOTAMENTO DAQUELE LUGAR, medido uma vez e usado nas duas pontas: ele entra
+                     * na regra que vai para o `CLAUDE.md` dele e viaja no censo como fato conferível.
+                     */
+                    const packaging = packagingOf(dirEntries, a.root);
+                    return {
+                        ...a,
+                        /** O caminho e a frase que a PERGUNTA usa verbatim - ver `componentHome`. */
+                        home: componentHome(a, scopeLabel),
+                        line: homeLine(a),
+                        rule: architectureRule(a, packaging, scopeLabel),
+                        ...(packaging ? { packaging } : {}),
+                    };
+                }),
             }
             : {}),
         /**
          * 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.
+         * UMA LISTA DE UM, porque esta função mede UM lugar. O merge concatena as de cada escopo,
+         * e é a lista que mantém cada número junto do lugar onde ele foi medido.
+         *
+         * Os dois números, o lugar, e a frase que os declara. Sem nome de forma, sem regra e sem
+         * caminho de destino: nada foi reconhecido, então qualquer um dos três seria adivinhação
+         * nossa gravada como fato dele. A frase é a exceção, e ela é declarada no tipo: fala da
+         * NOSSA régua, e a única oração com data de validade fica no terminal.
          */
-        ...(gap ? { architectureGap: gap } : {}),
+        ...(gap ? { architectureGaps: [gap] } : {}),
         /**
          * FORA DO `if` DAS FORMAS, e é isso que mantém a pergunta viva - `INV-COB-08`.
          *
@@ -4063,6 +4104,20 @@ export async function runImport(opts) {
         }
         try {
             census = JSON.parse(raw);
+            /**
+             * A LACUNA DE UM CENSO ANTIGO, LIDA AQUI - `INV-COB-08`.
+             *
+             * Este é o único caminho por onde um censo medido por outra versão entra: a fusão só vê o
+             * que `takeCensus` acabou de produzir. Um arquivo de 0.16.337 ou 0.16.338 traz o par somado
+             * `architectureGap`, que nenhuma superfície de hoje lê - sem esta linha, o agente que
+             * anotou aquele censo e o reenvia perde a declaração de que a leitura rodou e não
+             * reconheceu nada, que é exatamente o silêncio que a invariante existe para eliminar.
+             *
+             * O lugar não é inventado: a forma antiga não o guardou, e a entrada convertida diz isso.
+             */
+            const carried = architectureGaps(census);
+            if (carried.length > 0)
+                census.architectureGaps = carried;
         }
         catch {
             console.log(section("Import"));

package/dist/commands/sync.js

@@ -115,7 +115,7 @@ export async function sync(opts) {
          */
         const measured = existsSync(join(root, "_synthesisui", "census.json"));
         console.log(body(measured
-            ? "This repo has a census but no installed system, so there is nowhere to send it. `import` created the system on the platform; bringing it back is what tells sync which one this repo feeds:"
+            ? "This repo has been measured but has no installed system, so there is nowhere to send it. `import` created the system on the platform; bringing it back is what tells sync which one this repo feeds:"
             : "No installed system here, so there is nowhere to sync to. Install one first:"));
         console.log(body(paint.blue("    npx synthesisui@latest add <slug>")));
         console.log(body(paint.faint("    npx synthesisui@latest list --mine    # the slugs you own")));

package/dist/doctor/architecture.js

@@ -26,12 +26,12 @@ const SHAPES = [
             ["molecules", "molecule"],
             ["organisms", "organism"],
         ],
-        describe: (a) => `Components live in an atomic ladder under \`${a.root}\` - ${a.evidence.join("/")}. A new component goes on the rung that matches what it is made of: an atom composes nothing of yours, a molecule composes atoms, an organism is a whole region of a screen. Put it on the wrong rung and the ladder stops being true.`,
+        describe: (a, where) => `Components live in an atomic ladder under \`${where}\` - ${a.evidence.join("/")}. A new component goes on the rung that matches what it is made of: an atom composes nothing of yours, a molecule composes atoms, an organism is a whole region of a screen. Put it on the wrong rung and the ladder stops being true.`,
     },
     {
         kind: "feature",
         needs: [["features", "modules", "domains"]],
-        describe: (a) => `Code is organised BY FEATURE under \`${a.root}\`. A new component belongs to the feature that uses it, beside its own logic, and only moves up to the shared layer when a second feature needs it. Reaching across features is the thing this shape exists to prevent.`,
+        describe: (_a, where) => `Code is organised BY FEATURE under \`${where}\`. A new component belongs to the feature that uses it, beside its own logic, and only moves up to the shared layer when a second feature needs it. Reaching across features is the thing this shape exists to prevent.`,
     },
     {
         kind: "layered",
@@ -39,19 +39,116 @@ const SHAPES = [
             ["ui", "components"],
             ["hooks", "lib", "utils"],
         ],
-        describe: (a) => `Code is split by LAYER under \`${a.root}\` - ${a.evidence.join(", ")}. A component goes in the ui layer and nothing else does; state and helpers stay in theirs. A component reaching into another layer is fine, a helper reaching back into ui is not.`,
+        describe: (a, where) => `Code is split by LAYER under \`${where}\` - ${a.evidence.join(", ")}. A component goes in the ui layer and nothing else does; state and helpers stay in theirs. A component reaching into another layer is fine, a helper reaching back into ui is not.`,
     },
     {
         kind: "colocated",
         needs: [["app", "routes", "pages"]],
-        describe: (a) => `Components sit BESIDE THE ROUTE that uses them, under \`${a.root}\`. A new one starts local to its page and only moves to the shared folder when a second page needs it - which keeps the shared folder meaning "shared" rather than "everything".`,
+        describe: (_a, where) => `Components sit BESIDE THE ROUTE that uses them, under \`${where}\`. A new one starts local to its page and only moves to the shared folder when a second page needs it - which keeps the shared folder meaning "shared" rather than "everything".`,
     },
     {
         kind: "flat",
         needs: [["components"]],
-        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.`,
+        describe: (_a, where) => `Every component sits directly under \`${where}\`, 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.`,
     },
 ];
+/**
+ * O MESMO NOME, MÓDULO CAIXA E SEPARADOR - a única normalização deste arquivo.
+ *
+ * Ela não inventa convenção: `Tooltip` e `tooltip`, `ContentWrapper` e `content-wrapper` são o
+ * mesmo nome escrito com a preferência de quem digitou. Comparar as strings cruas faria a
+ * régua responder por convenção de nome de arquivo, e duas pessoas com a MESMA organização
+ * receberiam respostas opostas.
+ */
+export function sameName(a, b) {
+    const tidy = (x) => x.toLowerCase().replace(/[-_.\s]/g, "");
+    return tidy(a) === tidy(b);
+}
+/**
+ * COMO UMA PASTA RESOLVE - lido dos fatos que a caminhada mediu, num lugar só.
+ *
+ * O barril vence a eponímia quando os dois existem, porque é ele que decide o que o import
+ * escreve: numa pasta com `index.ts` e `Button.tsx`, quem importa escreve o nome da PASTA.
+ */
+export function resolvesAs(folder, hasIndex, componentNames) {
+    const leaf = folder.split("/").pop() ?? folder;
+    const eponymous = componentNames.some((n) => sameName(n, leaf));
+    /**
+     * UM BARRIL NÃO BASTA - e este era o falso positivo que uma revisão de QA pegou.
+     *
+     * `src/components/{Card,Pill,Tag}.tsx` com um `index.ts` ao lado tinha barril e virava
+     * "módulo de um componente". Num repositório onde NENHUM componente mora em pasta própria, a
+     * regra passava a mandar o agente criar `src/Toast/Toast.tsx` - o defeito do `frontend-hub`
+     * ao contrário, e uma pessoa move o arquivo do mesmo jeito.
+     *
+     * O que separa os dois não é o barril: é a pasta ser DE UM componente. Ela é, quando carrega
+     * o arquivo de mesmo nome - `Select/` com `SelectItem` e `SelectOption` dentro continua sendo
+     * a pasta do `Select` -, ou quando carrega UM componente só, que é o `Button/index.tsx` puro.
+     */
+    if (eponymous)
+        return hasIndex ? "index" : "eponymous";
+    return hasIndex && componentNames.length <= 1 ? "index" : null;
+}
+/**
+ * O EMPACOTAMENTO DE UM LUGAR, medido das pastas que estão DIRETAMENTE sob ele.
+ *
+ * `null` quando não há o que medir - menos de duas pastas com componente, ou nenhuma que
+ * resolva. Um lugar sem empacotamento observável não recebe campo, em vez de receber zero: um
+ * zero pelado aqui leria como "o projeto dele não embala nada", e o que é verdade é que a
+ * nossa leitura não viu.
+ */
+export function packagingOf(entries, 
+/** O lugar, como a caminhada o escreve - `"."` para a raiz do escopo. */
+root) {
+    /**
+     * TODAS AS PASTAS SOB O LUGAR, e não só as filhas diretas - o primeiro rascunho errava aqui.
+     *
+     * Medido: com as filhas diretas, o `SignalUI` não era encontrado. A forma reconhecida ali é
+     * `atomic@src/lib/SignalUI`, e as filhas diretas dela são `atoms`, `molecules`, `organisms` -
+     * que não seguram componente NENHUM diretamente: os componentes moram um degrau abaixo, em
+     * `atoms/Button/Button.tsx`. A pergunta é sobre as pastas onde o componente MORA, e elas
+     * podem estar a qualquer profundidade sob o lugar.
+     */
+    const kids = entries.filter((e) => e.direct > 0 && e.path !== root && isUnderPath(root, e.path));
+    if (kids.length < 2)
+        return null;
+    const resolving = kids.filter((c) => c.resolves !== null);
+    if (resolving.length === 0)
+        return null;
+    const byIndex = resolving.filter((c) => c.resolves === "index").length;
+    return {
+        folders: kids.length,
+        resolving: resolving.length,
+        file: byIndex === resolving.length
+            ? "index"
+            : byIndex === 0
+                ? "eponymous"
+                : "mixed",
+    };
+}
+/**
+ * A SEGUNDA FRASE DA REGRA - o que o agente precisa saber para criar o próximo arquivo.
+ *
+ * `null` quando o empacotamento NÃO é a convenção do lugar. O limiar é a maioria simples, e
+ * ele está aqui em vez de dentro da medição de propósito: a maioria é o que torna a frase
+ * verdadeira como REGRA ("é assim que se faz aqui"), e abaixo dela os dois números continuam
+ * gravados como fato sem virar instrução.
+ *
+ * O QUE ELA NÃO AFIRMA, e cada omissão é uma medição que não temos: nada sobre onde a story ou
+ * o teste moram - a caminhada os exclui desde 0.16.337, então nunca os contamos; e nada sobre
+ * haver um arquivo só por pasta - o caso de uma pasta com o componente MAIS as partes dele é
+ * real, e a régua o aceita de propósito.
+ */
+export function packagingRule(p) {
+    if (p.resolving * 2 <= p.folders)
+        return null;
+    const how = p.file === "index"
+        ? "each one holding an `index` that re-exports it"
+        : p.file === "eponymous"
+            ? "each one holding a file of the same name"
+            : "some holding an `index` that re-exports it, some a file of the same name";
+    return `A new component starts a folder of its own, named after it, ${how} - ${p.resolving} of the ${p.folders} folders here are written that way. Whatever belongs only to that component goes in the same folder; a \`SelectItem\` beside \`Select\` is still one folder, not two. This says nothing about where a story or a test lives - the reading never counted those.`;
+}
 /**
  * A MESMA ORGANIZAÇÃO VISTA DE MAIS PERTO NÃO É UMA SEGUNDA ESCOLHA (`INV-COB-09`).
  *
@@ -173,9 +270,12 @@ export function detectArchitectures(entries) {
     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) {
+export function describeArchitecture(a, scope) {
+    const where = pathUnderScope(a.root, scope);
     const shape = SHAPES.find((s) => s.kind === a.kind);
-    return shape ? shape.describe(a) : `Components live under \`${a.root}\`.`;
+    return shape
+        ? shape.describe(a, where)
+        : `Components live under \`${where}\`.`;
 }
 /**
  * The rule itself, in the shape `reading.rules` holds.
@@ -186,6 +286,15 @@ export function describeArchitecture(a) {
  * true once, not a habit that needs a third sighting.
  */
 export function architectureRule(a, 
+/**
+ * COMO O COMPONENTE É EMBALADO ALI - a segunda frase, quando ela é a convenção do lugar.
+ *
+ * OBRIGATÓRIO, e `null` é uma resposta: sem isso a regra volta a dizer só onde o componente
+ * nasce, num repositório onde todo componente é uma pasta - e o agente cria `atoms/Toast.tsx`
+ * onde o projeto inteiro escreve `atoms/Toast/Toast.tsx`. Um argumento opcional aqui seria a
+ * família do `fixReach`: o chamador esquece, `tsc` aceita, e a regra sai pela metade.
+ */
+packaging, 
 /**
  * O ESCOPO, para a regra dizer um caminho que existe. `a.root` é relativo ao escopo, e uma
  * regra no CLAUDE.md de um monorepo que diz `src/lib/SignalUI` manda o agente para um caminho
@@ -193,12 +302,14 @@ export function architectureRule(a,
  */
 scope) {
     const home = componentHome(a, scope);
+    const where = pathUnderScope(a.root, scope);
+    const packs = packaging ? packagingRule(packaging) : null;
     return {
-        text: `${describeArchitecture(a)} A new component goes under \`${home}\`.`,
+        text: `${describeArchitecture(a, scope)} A new component goes under \`${home}\`.${packs ? ` ${packs}` : ""}`,
         applies: [],
         kind: "implementation",
         fact: true,
-        evidence: `${a.evidence.join("/")} under ${scope ? `${scope}/${a.root}` : a.root}, holding ${a.files} component file${a.files === 1 ? "" : "s"}`,
+        evidence: `${a.evidence.join("/")} under ${where}, holding ${a.files} component file${a.files === 1 ? "" : "s"}`,
     };
 }
 /**
@@ -215,10 +326,30 @@ scope) {
  * na frente é ambíguo num monorepo, e é para o CLAUDE.md que essa linha vai.
  */
 export function componentHome(a, scope) {
-    const base = scope ? `${scope.replace(/\/+$/, "")}/${a.root}` : a.root;
-    const tidy = base.replace(/\/\.$/, "").replace(/^\.\//, "");
+    const tidy = pathUnderScope(a.root, scope);
     return a.evidence.length > 0 ? `${tidy}/{${a.evidence.join(", ")}}` : tidy;
 }
+/**
+ * O LUGAR, COMPOSTO UMA VEZ - a régua de caminho que todas as superfícies usam.
+ *
+ * O QUE O CLIENTE GANHA: o caminho que ele lê na regra, na evidência e na pergunta é sempre o
+ * mesmo, e sempre resolve a partir da raiz do repositório dele.
+ *
+ * ELA ERA DUAS, E AS DUAS DISCORDAVAM. `componentHome` normalizava barra final, `./` na frente e
+ * `/.` no fim; a `evidence` concatenava cru. Medido em 31/08, com o escopo real de um monorepo:
+ *
+ *     scope="packages/ui/"  root="src/components"   evidência dizia  packages/ui//src/components
+ *     scope="packages/ui"   root="."                evidência dizia  packages/ui/.
+ *
+ * A raiz do escopo é `"."` pela caminhada (`import.ts` escreve `path || "."`), então o segundo
+ * caso não é defensivo: é a organização reconhecida na raiz de um pacote, que é comum. Duas
+ * redações da mesma régua são duas réguas no dia em que uma for editada, e neste caso elas já
+ * tinham sido.
+ */
+export function pathUnderScope(root, scope) {
+    const base = scope ? `${scope.replace(/\/+$/, "")}/${root}` : root;
+    return base.replace(/\/\.$/, "").replace(/^\.\//, "");
+}
 /**
  * A MESMA FORMA EM UMA FRASE - o que decide, e o número que a torna credível.
  *
@@ -370,7 +501,20 @@ export const GAP_MIN_FILES = 3;
  * 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) {
+export function architectureGap(entries, found, 
+/**
+ * ONDE ESTA LEITURA MEDIU - `"."` para a raiz, ou o caminho apontado. OBRIGATÓRIO.
+ *
+ * Não tem default de propósito: um default aqui devolve o parâmetro opcional que a frase
+ * tinha, e com ele um chamador podia esquecer o lugar sem que nada reprovasse.
+ */
+scope, 
+/**
+ * A PASTA NOVA DESTE ESCOPO - `proposeNewHome` sobre a MESMA árvore, ou `null`.
+ *
+ * Obrigatório pelo mesmo motivo de `scope`: uma proposta de outro lugar é pior que nenhuma.
+ */
+newHome) {
     if (found.length > 0)
         return null;
     /**
@@ -388,27 +532,61 @@ export function architectureGap(entries, found) {
     }
     if (files < GAP_MIN_FILES)
         return null;
-    return { files, folders };
+    /**
+     * O EMPACOTAMENTO NÃO ENTRA AQUI, e a ausência é decisão declarada.
+     *
+     * A leitura sabe medi-lo mesmo num escopo mudo, e o cliente que menos tem regra é justamente
+     * esse. Mas o caminho pelo qual o empacotamento alcança alguém é `architectures[].rule`, que
+     * uma lacuna não tem: gravá-lo aqui criaria um campo sem leitor - o defeito exato que esta
+     * mesma entrega existe para consertar um campo ao lado. Ele entra no dia em que a lacuna
+     * ganhar a frase que o carrega, e entra com o leitor junto.
+     */
+    return {
+        scope,
+        files,
+        folders,
+        reason: gapReason({ scope, files, folders }),
+        newHome,
+    };
 }
 /**
- * A FRASE, no tom das outras desta camada: o número medido, o motivo, e nenhuma acusação.
+ * O LUGAR, EM PALAVRAS - a única tradução de `scope` para prosa neste produto.
  *
- * 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.
+ * `"."` não resolve para nada na cabeça de quem lê um relatório, e "here" não resolve para nada
+ * na cabeça de quem rodou a leitura sobre uma parte de um monorepo. Uma leitura da raiz não tem
+ * outro lugar a que se referir, então ela é a única que pode dizer "here".
  */
-export function describeGap(g, 
+function whereWeRead(scope) {
+    return scope === null || isRoot(scope) ? "here" : `under \`${scope}\``;
+}
 /**
- * ONDE MEDIMOS, quando a leitura foi apontada para uma parte do repositório.
+ * O QUE MEDIMOS, E DE QUEM É O LIMITE - a metade da frase que sobrevive a ser GRAVADA.
  *
- * "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.
+ * As duas orações que são verdade para sempre sobre aquela leitura: os números medidos, e que
+ * a régua é nossa. Nada aqui tem data de validade, e é por isso que esta é a parte que vai
+ * para o censo e para a pergunta que o agente faz.
+ *
+ * A segunda oração não é gentileza: sem ela a frase lê como um defeito do repositório dele, e
+ * o defeito é da régua.
  */
-where) {
+export function gapReason(g) {
     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.`;
+    return `We read ${files} in ${folders} ${whereWeRead(g.scope)}, 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.`;
+}
+/**
+ * A FRASE INTEIRA, para o TERMINAL - a declaração gravável mais a consequência de hoje.
+ *
+ * A ordem é a da dúvida de quem lê: o que medimos, de quem é o limite, e o que isso custa a ele
+ * agora. As duas primeiras vêm de `gapReason` e são as mesmas que o censo carrega - uma redação
+ * só, e não duas que divergem no dia em que alguém editar uma.
+ *
+ * A TERCEIRA MORA SÓ AQUI, e é a razão de esta função existir separada. Ela afirma o estado do
+ * `CLAUDE.md` DELE, o que é verdade no instante do relatório e falso depois - inclusive falso
+ * por causa da pergunta que este mesmo relatório abre. Gravada no censo, ela viraria medição
+ * corrente promovida a fato permanente, e seria reescrita como nova a cada `sync` sobre um
+ * repositório que já tem a regra.
+ */
+export function describeGap(g) {
+    return `${g.reason} 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

@@ -415,7 +415,76 @@ export const CHECKER_SINCE = "0.16.308";
  * 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";
+/**
+ * 0.16.338 -> 0.16.339 em 31/08 (`INV-COB-08`): a lacuna de organização passou a viajar no censo
+ * como LISTA, com o lugar de cada leitura e a frase pronta que a declara - `architectureGaps[]`,
+ * no lugar do par somado `architectureGap`.
+ *
+ * A marca sobe porque o AGENTE dele é o leitor. A skill `sui-import-ds` copia
+ * `architectureGaps[].reason` verbatim para abrir a pergunta de onde nasce um componente novo, e
+ * um censo medido antes não carrega esse campo: o agente volta ao estado em que a leitura rodou,
+ * não reconheceu nada, e nenhuma pergunta chegou à tela dele. O par antigo também não guarda o
+ * LUGAR da medição, e nada pode recuperá-lo sem reler o disco - a caminhada é o que sabe onde
+ * cada arquivo estava.
+ *
+ * O QUE O `sync` ENTREGA: ele remede com `takeCensus`, então o censo em disco e o reenviado já
+ * nascem com a lista e a frase. O que ele NÃO entrega continua sendo a linha do `CLAUDE.md` dele,
+ * pelo mesmo motivo da marca anterior - `rulesFromCensus` não olha para este campo, e a regra de
+ * organização nasce da conversa de import.
+ *
+ * MEDIÇÃO de 31/08, no banco de produção: **1 sistema com censo de import guardado, e `0` com a
+ * forma antiga** - aquele censo é anterior a 0.16.337 e não carrega campo de organização nenhum.
+ * Foto daquela população naquele dia, nunca invariante.
+ *
+ * A COMPATIBILIDADE NÃO É O QUE ALCANÇA ELE, e a distinção foi medida por uma revisão de QA. A
+ * leitura da forma antiga (`architectureGaps`, em `merge-census.ts`) roda em UM caminho:
+ * `import --census <arquivo>`, onde um agente reenvia um censo que ele mesmo anotou. A FUSÃO
+ * nunca a alcança - ela só vê censos que `takeCensus` acabou de medir, e esses já nascem na forma
+ * nova. Quem tem `census.json` em disco e não usa aquele comando é alcançado pelo `sync`, que
+ * remede e reescreve o arquivo: é isso, e não a compatibilidade, que esta marca anuncia.
+ */
+/**
+ * 0.16.339 -> 0.16.340 em 31/08 (`INV-COB-10`): a leitura passou a medir COMO o componente é
+ * embalado - se as pastas sob um lugar resolvem como o módulo dele, por barril `index.*` ou por
+ * arquivo de mesmo nome módulo caixa e separador - e a regra que vai para o `CLAUDE.md` dele
+ * ganhou uma segunda frase dizendo isso.
+ *
+ * A marca sobe porque o fato nasce da CAMINHADA. Um censo medido antes não carrega `resolves`
+ * por pasta nem `packaging` por lugar, e nada aqui pode recuperá-los sem reler o disco: o
+ * `index.ts` que faz `ActivityRing/` resolver como módulo não é arquivo de componente e nunca
+ * foi contado. Só a remedição vê.
+ *
+ * O QUE O CLIENTE GANHA: hoje a regra dele diz onde o próximo componente nasce e cala sobre o
+ * empacotamento. O agente cria `atoms/Toast.tsx` num repositório onde tudo é
+ * `atoms/Toast/Toast.tsx` com `index.ts` ao lado, e uma pessoa move o arquivo toda vez. A regra
+ * estava certa e incompleta.
+ *
+ * O `sync` remede com `takeCensus`, então o censo em disco e o reenviado já nascem com os dois
+ * campos. O que ele NÃO faz continua sendo reescrever a regra já escrita no `CLAUDE.md` dele.
+ *
+ * MEDIÇÃO de 31/08, duas populações: 35 formas reconhecidas ganham a segunda frase, 3 têm o
+ * fato e ficam abaixo da maioria, 37 não têm empacotamento observável.
+ */
+/**
+ * 0.16.340 -> 0.16.341 em 31/08 (`INV-COB-11`): o caminho que a regra de organização cita passou
+ * a resolver a partir da raiz do repositório, nas QUATRO superfícies que o dizem.
+ *
+ * O QUE O CLIENTE DE MONOREPO VIVIA: a regra que governa todo prompt dele se contradizia na mesma
+ * frase - *"Components live in an atomic ladder under `src/components`. (...) A new component goes
+ * under `packages/ui/src/components/{…}`"*. A primeira metade é a que descreve o projeto, e ela
+ * mandava o agente procurar uma pasta que não existe na raiz.
+ *
+ * A marca sobe porque o campo é COMPOSTO na medição: `architectures[].rule.text` já está gravado
+ * com o caminho pelado, e nada do lado de cá o reescreve. O `sync` remede com `takeCensus`, então
+ * quem rodar recebe a regra certa no censo em disco e no reenviado; sem a marca, o `align` não
+ * chamaria ninguém para rodar.
+ *
+ * QUEM NÃO É AFETADO, e é a maioria: quem mede a raiz do repositório. Sem escopo o caminho já era
+ * o mesmo nas quatro superfícies - o defeito só existe quando a leitura foi apontada para uma
+ * parte do repositório. O corpus dourado NÃO se moveu por isso: nenhum dos 29 apps é medido com
+ * escopo, e o hash parado aqui é ausência de cobertura, nunca ausência de efeito.
+ */
+export const READER_SINCE = "0.16.341";
 /**
  * O QUE ESTÁ INSTALADO AQUI FICOU PARA TRÁS - e as DUAS condições que fazem isso ser verdade.
  *

package/dist/merge-census.js

@@ -1,3 +1,4 @@
+import { gapReason } from "./doctor/architecture.js";
 const asRecord = (v) => (v ?? {});
 /** Nome do escopo para as mensagens - `.` quando a medição não escopou nada. */
 const nameOf = (c, i) => c.scope ?? (i === 0 ? "." : `#${i + 1}`);
@@ -120,22 +121,30 @@ export function mergeCensus(list) {
     let conventions = first.conventions ?? undefined;
     let architectures = first.architectures ?? undefined;
     /**
-     * A LACUNA DE ORGANIZAÇÃO, SOMADA - `INV-COB-08`, ver `architectureGap` em `import.ts`.
+     * AS LACUNAS DE ORGANIZAÇÃO, CONCATENADAS - `INV-COB-08`, ver `architectureGaps` 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.
+     * CONCATENADAS, E NUNCA SOMADAS, e este era o defeito: contagem é aditiva, mas contagem COM
+     * UM LUGAR não é. Somando, dois escopos mudos de 37 e 7 arquivos produziam `{files: 44}` com
+     * a mesma forma de uma leitura só - e a frase construída sobre aquilo diria "44 arquivos sob
+     * `packages/ui`", que é falso, ou "44 arquivos aqui", que não é conferível. O próprio tipo
+     * promete que o cliente confere os dois números com um `find` de uma linha sobre UMA pasta, e
+     * nenhum `find` devolve 44.
+     *
+     * É o mesmo defeito que `scope-of.ts` já consertou um campo adiante (`census.scope` era o
+     * PRIMEIRO escopo, e todo componente do segundo era atribuído a ele), e a mesma forma que
+     * `architectures` já usa: cada entrada carrega o seu lugar embutido.
+     *
+     * O PISO É POR ESCOPO, e a lista é o que o mantém assim. Dois escopos de 2 arquivos calam
+     * cada um por `GAP_MIN_FILES`; somados antes do piso, os 4 falariam sobre uma organização que
+     * nenhum dos dois tem.
      */
-    let gapFiles = first.architectureGap
-        ?.files;
-    let gapFolders = first.architectureGap
-        ?.folders;
+    let gaps = architectureGaps(first);
     /**
      * ONDE O PRÓXIMO COMPONENTE VAI - o PRIMEIRO escopo vence, a mesma regra de `scope`.
      *
@@ -203,11 +212,7 @@ 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);
-        }
+        gaps = [...gaps, ...architectureGaps(c)];
         components = concat(components, c.components);
         defined = concat(defined, c.defined);
         for (const s of c.project.stack ?? [])
@@ -291,8 +296,8 @@ 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 (gaps.length > 0)
+        out.architectureGaps = gaps;
     if (newComponentHome)
         out.newComponentHome = newComponentHome;
     if (components && components.length > 0)
@@ -357,3 +362,52 @@ export function mergeCensus(list) {
     }
     return out;
 }
+/**
+ * AS LACUNAS DE UM CENSO, NAS DUAS FORMAS QUE EXISTEM - `INV-COB-08`.
+ *
+ * O QUE O CLIENTE GANHA: quem entrega um censo JÁ MEDIDO continua recebendo a declaração de que
+ * a leitura rodou e não reconheceu nada. Descartar a forma antiga devolveria a esse cliente o
+ * silêncio exato que a invariante existe para eliminar, e ele nem saberia que houve leitura.
+ *
+ * ONDE ISTO É ALCANÇADO, e não é aqui dentro: a fusão só vê censos que `takeCensus` acabou de
+ * medir no mesmo processo, e esses já nascem na forma nova. O caminho por onde um censo ANTIGO
+ * entra de verdade é `import --census <arquivo>`, que lê o JSON do disco e o usa como está - o
+ * comando que a nossa própria skill ensina a um agente que anotou o censo. Uma revisão de QA
+ * mediu que este ramo só tinha o spec como chamador; ele agora roda naquele caminho, e por isso
+ * é exportado.
+ *
+ * A FORMA ANTIGA NÃO GUARDA O LUGAR, e nada aqui pode inventá-lo. Um censo de 0.16.337 ou
+ * 0.16.338 traz `architectureGap: {files, folders}` e nada mais - possivelmente já somado de
+ * dois escopos pela versão anterior desta função. Assumir a raiz produziria uma frase apontando
+ * para um lugar onde a contagem não fecha, que é pior que dizer que não sabemos. `null` é o
+ * terceiro estado do campo, e ele NÃO é a raiz: a frase resultante diz "here", que é a redação
+ * honesta para uma leitura sem lugar registrado, e o dado continua dizendo que não sabemos.
+ *
+ * `reason` é RECOMPOSTO e nunca herdado, porque a frase antiga foi escrita com um argumento de
+ * escopo que este censo não guardou.
+ */
+export function architectureGaps(c) {
+    const anyish = c;
+    const fresh = anyish.architectureGaps;
+    if (Array.isArray(fresh))
+        return fresh;
+    const legacy = anyish.architectureGap;
+    if (!legacy)
+        return [];
+    const files = legacy.files ?? 0;
+    const folders = legacy.folders ?? 0;
+    const scope = null;
+    return [
+        {
+            scope,
+            files,
+            folders,
+            reason: gapReason({ scope, files, folders }),
+            /**
+             * A FORMA ANTIGA NÃO GUARDOU A PROPOSTA, e o `newComponentHome` do topo é o do PRIMEIRO
+             * escopo - oferecê-lo aqui apontaria a pergunta para um lugar que pode não ser este.
+             */
+            newHome: null,
+        },
+    ];
+}

package/package.json

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