synthesisui 0.16.256 → 0.16.259

package/dist/claude-md.js

@@ -1,6 +1,7 @@
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { hasHook } from "./agent-wiring.js";
+import { declaredReference } from "./group-role.js";
 const START = "<!-- synthesisui:start -->";
 const END = "<!-- synthesisui:end -->";
 /** Reads the installed DSs from the .lock files in _synthesisui/ds/<slug>/. */
@@ -326,7 +327,7 @@ async function renderRegion(projectRoot, installed) {
      * repo de um sistema só para negar uma relação que ninguém cogitou é ruído no
      * arquivo mais lido do projeto.
      */
-    const ref = installed.find((d) => d.reference)?.reference;
+    const ref = declaredReference(installed);
     if (installed.length > 1 && ref) {
         sections.push(`\n**${ref.name}** (\`${ref.slug}\`) is the reference system of this group. When two of the systems above name the same thing differently, its answer is the one to follow - the others are moving towards it.`);
     }

package/dist/commands/absorb.js

@@ -49,7 +49,8 @@ export async function absorb(opts) {
      * dela - o mesmo caminho que `absorb: "code"` já servia a quem escolheu. Ver `sendProposal`.
      */
     const hasSystem = Boolean(installed.table.slug);
-    const measured = await measuredScope(root);
+    /** O escopo DESTE sistema - ver `actingSlug`: sem o slug o vizinho responde. */
+    const measured = await measuredScope(root, installed.table.slug ?? undefined);
     const rel = scopePaths(measured);
     const roots = rel.length > 0 ? rel.map((s) => resolve(root, s)) : [root];
     /**

package/dist/commands/add.js

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { syncClaudeMd } from "../claude-md.js";
 import { readProjectConfig, resolveRegistry } from "../config.js";
 import { customFontFamilies, googleFontsHref, nextFontSnippet, } from "../fonts.js";
+import { lockReference } from "../group-role.js";
 import { buildGuide } from "../guide.js";
 import { censusScope } from "../measured-scope.js";
 import { body as line, section, snippet } from "../output.js";
@@ -195,15 +196,19 @@ export async function add(slug, opts) {
         /**
          * A RELAÇÃO ENTRE OS SISTEMAS DESTE REPO, vinda da plataforma.
          *
-         * Preservada quando o registry não a manda: um servidor mais antigo não sabe
-         * do campo, e apagar a relação por causa disso faria a resposta oscilar entre
-         * dois `add` seguidos.
+         * `payload.group` é a resposta COMPLETA - ver `RegistryPayload.group`: quando
+         * ela vem, ela manda, inclusive para APAGAR a referência. Foi a metade que
+         * faltava: clicar "eles são independentes" na tela do grupo não chegava aqui,
+         * porque o campo ausente era indistinguível de servidor antigo.
+         *
+         * Sem `group`, o comportamento antigo continua - preservar o que está no lock,
+         * senão a resposta oscilaria entre dois `add` contra um registry que não
+         * conhece o campo.
          */
-        ...(payload.groupReference
-            ? { reference: payload.groupReference }
-            : prev?.reference
-                ? { reference: prev.reference }
-                : {}),
+        ...(() => {
+            const reference = lockReference(payload, prev);
+            return reference ? { reference } : {};
+        })(),
     };
     const landed = (() => {
         if (!prev?.fetchedAt)

package/dist/commands/align.js

@@ -6,6 +6,7 @@ import { isOlderCli } from "../cli-version.js";
 import { readToken, resolveRegistry } from "../config.js";
 import { unsentEvents } from "../doctor/ledger.js";
 import { readRequests } from "../doctor/requests.js";
+import { declaredReference } from "../group-role.js";
 import { CHECKER_SINCE, installedBehind, MATERIALISER_SINCE, READER_SINCE, } from "../install-marks.js";
 import { measuredScope } from "../measured-scope.js";
 import { body } from "../output.js";
@@ -110,7 +111,7 @@ opts = {}) {
      * comandos seguem agindo sobre o primeiro, e agora dá para dizer QUAL deveria
      * ser. Sem referência, o aviso é o de sempre.
      */
-    const declared = locks.find((l) => l.reference)?.reference;
+    const declared = declaredReference(locks);
     if (locks.length > 1) {
         const names = locks.map((l) => l.slug).join(", ");
         if (declared && locks.some((l) => l.slug === declared.slug)) {
@@ -161,7 +162,7 @@ opts = {}) {
      * e manda os componentes de todos os apps para um sistema que é uma biblioteca (06/08, 338 num
      * sistema de 36).
      */
-    const scope = await measuredScope(root);
+    const scope = await measuredScope(root, lock.slug);
     if (!scope.system && scope.usage.length === 0)
         out.push({
             says: `"${lock.slug}" does not record where it was measured, so a re-measure would read this whole repo instead of the folder the system came from. Sync asks once and remembers the answer.`,

package/dist/commands/doctor.js

@@ -16,7 +16,8 @@ import { diagnose, nameToWrite, scanSource, siblingTokens, } from "../doctor/sca
 import { findSelfConflicts, forbiddenProps, isReset, propMatchesLabel, } from "../doctor/self-conflict.js";
 import { withTheirNames } from "../doctor/their-names.js";
 import { buildTable, EMPTY_TABLE, nearestToken, } from "../doctor/tokens.js";
-import { describeScope, measuredScope, scopePaths } from "../measured-scope.js";
+import { groupRole } from "../group-role.js";
+import { actingSlug, describeScope, measuredScope, scopePaths, } from "../measured-scope.js";
 import { body, paint, section, snippet } from "../output.js";
 import { resolveDeps } from "../stack.js";
 /**
@@ -192,6 +193,7 @@ measured) {
             documents: [],
             requires: [],
             doctrines: [],
+            groupLocks: [],
         };
     }
     // Several systems can live side by side; every token is prefixed --ds-, so
@@ -203,6 +205,7 @@ measured) {
     const documents = [];
     const requires = [];
     const doctrines = [];
+    const groupLocks = [];
     for (const slug of slugs) {
         const dir = join(dsDir, slug);
         const raw = await readFile(join(dir, ".lock"), "utf8").catch(() => "");
@@ -214,6 +217,11 @@ measured) {
             mine = null;
         }
         lock ??= mine;
+        if (mine?.slug)
+            groupLocks.push({
+                slug: mine.slug,
+                ...(mine.reference ? { reference: mine.reference } : {}),
+            });
         // The file at the root is a POINTER - `@import "./v1/tokens.css"` - so the
         // pinned folder is where the declarations actually live. Read that first,
         // and fall back to following whatever the root imports, for a project that
@@ -331,6 +339,7 @@ measured) {
         documents,
         requires,
         doctrines,
+        groupLocks,
     };
 }
 /**
@@ -566,7 +575,15 @@ export async function doctor(opts) {
      */
     const measured = (opts.scopes ?? []).length > 0
         ? { system: null, systems: [], usage: [], from: "none" }
-        : await measuredScope(root);
+        : /**
+           * O ESCOPO DO SISTEMA SOBRE O QUAL ESTE COMANDO AGE - ver `actingSlug`.
+           *
+           * Sem o slug, um repo de dois sistemas podia responder com o escopo do
+           * outro: `scopeInLock` devolvia o primeiro lock QUE TEM escopo, e o
+           * comando age no primeiro lock que EXISTE. Num monorepo isso é a
+           * diferença entre ler a biblioteca e ler um app de 780 arquivos.
+           */
+            await measuredScope(root, (await actingSlug(root)) ?? undefined);
     const relScopes = (opts.scopes ?? []).length > 0
         ? opts.scopes
         : scopePaths(measured);
@@ -582,7 +599,6 @@ export async function doctor(opts) {
      */
     const fullRun = (opts.scopes ?? []).length === 0;
     /** A intenção ordena o relatório, e a precedência é flag > config > default. */
-    const intent = intentOf(await readProjectConfig(root), opts.intent);
     /**
      * A RAIZ, MEDIDA ANTES DE COMPARAR VALOR NENHUM - ver `rootSizeOf`.
      *
@@ -595,6 +611,16 @@ export async function doctor(opts) {
         px: rootSize.ambiguous ? DEFAULT_ROOT_PX : rootSize.px,
         from: rootSize.from,
     });
+    /**
+     * A INTENÇÃO SABE DA REFERÊNCIA - é o que faz as duas superfícies falarem a
+     * mesma língua.
+     *
+     * A tela do grupo declara qual sistema é a fonte; este comando ordena a lista
+     * por isso, sem perguntar de novo. Um sistema que não é a referência do seu
+     * grupo está migrando para ela - e antes disto a referência existia na
+     * plataforma e o comando que ordena a lista nunca ficava sabendo.
+     */
+    const intent = intentOf(await readProjectConfig(root), opts.intent, groupRole(installed.groupLocks, installed.table.slug));
     const { recipes, documents } = installed;
     /**
      * A TABELA JÁ VEM COM O VOCABULÁRIO DELE DENTRO - ver `loadSystem` e `their-names.ts`.

package/dist/commands/import.js

@@ -2155,6 +2155,31 @@ function sayScopes(c) {
     console.log("");
     console.log(section("Two folders, one system"));
     console.log(body(`Measured ${scopes.length} scopes and fused them: ${scopes.map((x, i) => (i === 0 ? paint.strong(x) : x)).join(" · ")}. The first one is the authority - it wins a tie, and nothing from the others is dropped without a line.`));
+    /**
+     * A CONVERGÊNCIA VEM ANTES DOS CONFLITOS, porque ela decide se a lista de
+     * conflitos é o assunto.
+     *
+     * Com 60% compartilhado, três divergências são o trabalho. Com 0%, elas são um
+     * detalhe de dois vocabulários que não se encontram - e a conversa que precisa
+     * acontecer é outra: isto é um sistema ou são dois? Medido no monorepo do dono,
+     * `packages/ui` e `apps/web-dashboard` dão exatamente 0%.
+     */
+    const conv = c.scopeConvergence;
+    if (conv && conv.percent !== null) {
+        console.log("");
+        console.log(body(conv.covered === 0
+            ? `${paint.strong(`None of the ${conv.declares} names`)} the other scope${scopes.length > 2 ? "s" : ""} declare${scopes.length > 2 ? "" : "s"} exists in ${paint.strong(scopes[0])} yet - not by name and not by value. These are different vocabularies, not one drifting from the other.`
+            : `${paint.strong(`${conv.covered} of ${conv.declares} names`)} the other scope${scopes.length > 2 ? "s" : ""} declare${scopes.length > 2 ? "" : "s"} already exist in ${paint.strong(scopes[0])} (${conv.percent}%)${conv.aliased > 0 ? `, and ${conv.aliased} of those under a DIFFERENT name - one decision written twice` : ""}.`));
+        /**
+         * E A PERGUNTA, dita em voz alta em vez de assumida.
+         *
+         * A fusão presume que os escopos são um sistema só. Abaixo de um terço de
+         * convergência essa premissa deixa de se sustentar sozinha, e quem decide não
+         * é a esteira - é quem conhece os dois produtos.
+         */
+        if (conv.percent < 34)
+            console.log(body(paint.faint("Worth answering before this becomes one system: are these two ONE vocabulary, or two that live in the same repo? Two is a legitimate answer - import each scope on its own, and name which of them is the reference on the group's screen.")));
+    }
     if (conflicts.length === 0)
         return;
     console.log("");

package/dist/commands/summary.js

@@ -34,7 +34,7 @@ export async function summary(slug, opts) {
     const lock = await readFile(join(root, "_synthesisui", "ds", slug, ".lock"), "utf8")
         .then((raw) => JSON.parse(raw))
         .catch(() => null);
-    const measured = await measuredScope(root);
+    const measured = await measuredScope(root, slug);
     const name = lock?.name ?? slug;
     /**
      * `looks`, NUNCA `components`.

package/dist/commands/sync.js

@@ -73,7 +73,26 @@ export async function sync(opts) {
         console.log(body("    synthesisui login"));
         return;
     }
-    const slug = await installedSlug(root);
+    /**
+     * QUAL SISTEMA - e num repo com dois isto deixou de ser óbvio.
+     *
+     * `installedSlug` devolve o primeiro em ordem alfabética, então o segundo
+     * sistema de um repo NUNCA era sincronizado: o comando não tinha como
+     * alcançá-lo. O `align` avisava ("commands act on the first") e não havia o que
+     * fazer com o aviso.
+     *
+     * `synthesisui sync <slug>` resolve, e sem argumento nada muda para quem tem um
+     * sistema só - que é praticamente todo mundo.
+     */
+    const installed = await installedSlugs(root);
+    const slug = opts.slug
+        ? installed.find((x) => x === opts.slug)
+        : installed[0];
+    if (opts.slug && !slug) {
+        console.log("");
+        console.log(body(`No system called ${paint.strong(opts.slug)} is installed here.${installed.length > 0 ? ` This repo has: ${installed.map((x) => paint.strong(x)).join(", ")}.` : ""}`));
+        return;
+    }
     if (!slug) {
         console.log(section("Sync"));
         console.log(body("No installed system here, so there is nowhere to sync to."));
@@ -247,7 +266,14 @@ export async function remeasure(args) {
      *
      * O servidor continua valendo como segunda fonte: um clone fresco tem o `.lock` e não tem censo.
      */
-    const local = await measuredScope(root);
+    /**
+     * O ESCOPO DESTE SISTEMA, e não o do vizinho - ver `measuredScope`.
+     *
+     * Num repo com dois sistemas instalados, o escopo vinha do primeiro lock que
+     * tivesse um, enquanto `installedSlug` escolhia o primeiro que tivesse slug.
+     * Quando não eram o mesmo, este comando media um sistema e mandava para o outro.
+     */
+    const local = await measuredScope(root, slug);
     /**
      * TODOS os escopos do sistema, não só o primeiro.
      *
@@ -506,35 +532,36 @@ async function askToOverwrite() {
     }
 }
 /**
- * O SLUG QUE ESTE PROJETO TEM INSTALADO, ou `null`.
+ * TODOS os sistemas instalados, na ordem em que o disco os devolve.
+ *
+ * Era `installedSlug`, singular, e devolvia o primeiro - o que fazia o segundo
+ * sistema de um repo ser inalcançável por este comando. O `align` avisava
+ * ("commands act on the first") e não havia o que fazer com o aviso.
  *
- * Uma função e não duas cópias: o `sync` e a ferramenta `refresh_system` do MCP precisam da mesma
- * busca, e a regra que ela carrega - um DS ADOTADO é descrito aqui e pertencido em outro lugar, então
- * não tem linha no dashboard para onde sincronizar - discordaria entre duas cópias na primeira vez que
- * alguém a mudasse.
+ * `adopted` fica fora: um sistema adotado é o vocabulário do próprio projeto, sem
+ * versão publicada, e não há para onde sincronizá-lo.
  */
-export async function installedSlug(root) {
+export async function installedSlugs(root) {
     const dsDir = join(root, "_synthesisui", "ds");
-    try {
-        const slugs = (await readdir(dsDir, { withFileTypes: true }))
-            .filter((e) => e.isDirectory())
-            .map((e) => e.name);
-        for (const name of slugs) {
-            const raw = await readFile(join(dsDir, name, ".lock"), "utf8").catch(() => "");
-            try {
-                const lock = JSON.parse(raw);
-                if (lock.slug && !lock.adopted)
-                    return lock.slug;
-            }
-            catch {
-                // unreadable lock - try the next
-            }
+    const out = [];
+    const slugs = (await readdir(dsDir, { withFileTypes: true }).catch(() => []))
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name)
+        .sort();
+    for (const name of slugs) {
+        const raw = await readFile(join(dsDir, name, ".lock"), "utf8").catch(() => null);
+        if (!raw)
+            continue;
+        try {
+            const lock = JSON.parse(raw);
+            if (lock.slug && !lock.adopted)
+                out.push(lock.slug);
+        }
+        catch {
+            // lock ilegível: aquele sistema não entra, e o resto segue
         }
     }
-    catch {
-        // no _synthesisui at all
-    }
-    return null;
+    return out;
 }
 /**
  * DE ONDE ESTE SISTEMA FOI MEDIDO - perguntado uma vez, com os candidatos do próprio repo.
@@ -577,3 +604,13 @@ async function askForScope(root) {
         rl.close();
     }
 }
+/**
+ * O PRIMEIRO sistema instalado - o que o MCP usa quando a pergunta é "deste repo".
+ *
+ * Mantido porque as ferramentas do MCP falam de UM sistema por natureza: quem
+ * pergunta "qual é a doutrina daqui" quer a do sistema que governa este repo, e a
+ * escolha entre dois é uma decisão de quem opera, não do servidor.
+ */
+export async function installedSlug(root) {
+    return (await installedSlugs(root))[0] ?? null;
+}

package/dist/config.js

@@ -156,7 +156,19 @@ export async function readProjectConfig(root) {
  * porque é o único dos dois cuja lista tem conserto automático (`--fix`). Migrar é uma fase, e uma
  * fase se declara.
  */
-export function intentOf(config, flag) {
+export function intentOf(config, flag, 
+/**
+ * O PAPEL DESTE SISTEMA NO GRUPO, lido dos locks por `groupRole`.
+ *
+ * Recebe o papel inteiro e não um slug solto, porque as duas metades decidem
+ * coisas opostas e um argumento que se pode esquecer é um argumento que alguém
+ * vai esquecer: `follows` sozinho derivaria `adopt` para a própria referência.
+ *
+ * Derivar em vez de perguntar de novo é o que faz as duas superfícies falarem a
+ * mesma língua - a tela do grupo declara uma vez, e o doctor de todo repo do
+ * grupo passa a ordenar por aquilo.
+ */
+group) {
     if (flag === "migrate" || flag === "adopt")
         return { intent: flag, from: "flag" };
     if (config.intent)
@@ -164,7 +176,14 @@ export function intentOf(config, flag) {
             intent: config.intent,
             from: "config",
             ...(config.intentAt ? { at: config.intentAt } : {}),
+            ...(group?.follows ? { towards: group.follows } : {}),
         };
+    /** Sou a fonte: o design dos outros vem para cá, e absorver é o que eu faço. */
+    if (group?.isReference)
+        return { intent: "migrate", from: "reference" };
+    /** Sigo a fonte: o meu vocabulário converge, então eu adoto os nomes dela. */
+    if (group?.follows)
+        return { intent: "adopt", from: "reference", towards: group.follows };
     return { intent: "adopt", from: "default" };
 }
 /**
@@ -183,7 +202,18 @@ export function describeIntent(source) {
         ? "this run only"
         : source.from === "config"
             ? `set in _synthesisui/config.json${source.at ? ` on ${source.at.slice(0, 10)}` : ""}`
-            : "nobody chose, so this is the default";
+            : source.from === "reference"
+                ? /**
+                   * A frase diz que ninguém digitou isto, e de onde saiu: uma intenção
+                   * derivada que se apresenta como escolhida é a etiqueta que envelhece
+                   * sem ninguém notar. E ela nomeia o outro sistema nos dois sentidos,
+                   * porque "sou a referência" e "sigo a referência" ordenam a lista de
+                   * jeitos opostos.
+                   */
+                    source.towards
+                        ? `derived: this group's reference is \`${source.towards}\`, and your vocabulary is converging on it`
+                        : "derived: this is the group's reference system, so the design moves in"
+                : "nobody chose, so this is the default";
     const flip = source.intent === "migrate"
         ? "`doctor --adopt` sorts the other way"
         : "`doctor --migrate` sorts the other way";

package/dist/group-role.js

@@ -0,0 +1,54 @@
+/**
+ * Lê o papel dos locks instalados. Sem referência declarada no grupo, os dois
+ * campos ficam vazios: independentes é uma resposta, não a ausência de uma.
+ */
+export function groupRole(locks, 
+/**
+ * `null` quando não há sistema instalado - e aí não há papel, nem derivação. É
+ * o estado de um projeto que só rodou `import`: sem lock, sem grupo.
+ */
+self) {
+    if (!self)
+        return { isReference: false };
+    const mine = locks.find((l) => l.slug === self);
+    const follows = mine?.reference?.slug;
+    /**
+     * `follows` e `isReference` não coexistem: quem segue não é seguido. Se um repo
+     * chegar nesse estado, o lock que aponta para mim está velho - e é o `align` que
+     * fala de lock velho, não esta função, que responde pelo MEU lock.
+     */
+    const isReference = !follows &&
+        locks.some((l) => l.reference?.slug === self && l.slug !== self);
+    return {
+        ...(follows ? { follows } : {}),
+        isReference,
+    };
+}
+/**
+ * QUE REFERÊNCIA O `.lock` PASSA A GUARDAR depois de uma busca no registry.
+ *
+ * Uma função em vez de um ternário dentro do `add` porque a decisão tem três
+ * entradas e um caso que ninguém adivinha (apagar), e um ternário de três níveis
+ * no meio de um objeto de 12 campos é onde o caso apagar se perdeu por semanas.
+ */
+export function lockReference(payload, prev) {
+    /** A resposta completa manda, e ela também apaga. */
+    if (payload.group)
+        return payload.group.reference;
+    /** Um servidor que só conhece a metade antiga: ele afirma, nunca nega. */
+    if (payload.groupReference)
+        return payload.groupReference;
+    return prev?.reference;
+}
+/**
+ * A REFERÊNCIA DO GRUPO, lida dos locks - a mesma leitura para todo mundo.
+ *
+ * Três lugares faziam esta linha à mão (`align`, o `CLAUDE.md` e o doctor), e
+ * "todos falam a mesma língua" começa por ler o fato no mesmo lugar. O lock que
+ * aponta para si mesmo é ignorado: é lock velho, e ele nomearia como referência do
+ * grupo alguém que já não é.
+ */
+export function declaredReference(locks) {
+    return locks.find((l) => l.reference && l.reference.slug !== l.slug)
+        ?.reference;
+}

package/dist/index.js

@@ -65,7 +65,7 @@ Usage - governance (deterministic, FREE):
                                            something no reader would change
   synthesisui request [component|token]    the queue of what your agent needed and the system
                                            refused to invent (--done <id> closes one)
-  synthesisui sync                         re-measure this repo with the current reader and send it,
+  synthesisui sync [<slug>]                         re-measure this repo with the current reader and send it,
                                            reusing the reading you already authored, plus the local
                                            record - checks, fixes, open requests (--record-only skips
                                            the measurement, --yes skips the overwrite question)
@@ -528,6 +528,14 @@ async function main() {
                 dir,
                 registry,
                 cli: CLI_VERSION,
+                /**
+                 * `sync <slug>`: qual sistema, num repo que tem mais de um.
+                 *
+                 * Sem ele o comando agia sempre no primeiro em ordem alfabética, e o
+                 * segundo sistema de um repositório era inalcançável - o `align` avisava
+                 * e não havia o que fazer com o aviso.
+                 */
+                ...(args[0] ? { slug: args[0] } : {}),
                 recordOnly: boolFlag(flags, "record-only"),
                 yes: boolFlag(flags, "yes"),
                 /** `--full`: o relatório inteiro do leitor. Por padrão a re-medição conta o que MUDOU. */

package/dist/install-marks.js

@@ -100,7 +100,7 @@
  *
  * Quem instalou antes desta versão tem o stub que estanca: o `upgrade`/`connect` é o que alcança.
  */
-export const MATERIALISER_SINCE = "0.16.256";
+export const MATERIALISER_SINCE = "0.16.259";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *

package/dist/measured-scope.js

@@ -16,12 +16,26 @@ const EMPTY = {
  *
  * Um lock sem `scope` é o caso de todo sistema instalado antes disto: cai no censo, como antes.
  */
-async function scopeInLock(root) {
+async function scopeInLock(root, 
+/**
+ * DE QUAL SISTEMA - e sem isto o escopo era o do PRIMEIRO diretório que tinha um.
+ *
+ * Com dois sistemas instalados (um fork da galeria, sem escopo, e um importado,
+ * com escopo) o laço pulava o primeiro e devolvia o escopo do segundo, enquanto
+ * `installedSlug` devolvia o PRIMEIRO. O `sync` então media o escopo de um
+ * sistema e mandava para o outro - provado num repo de teste em 19/08.
+ *
+ * Ausente mantém o comportamento antigo, que é o certo para um sistema só.
+ */
+slug) {
     const dsDir = join(root, "_synthesisui", "ds");
     const names = await readdir(dsDir, { withFileTypes: true }).catch(() => []);
     for (const entry of names) {
         if (!entry.isDirectory())
             continue;
+        /** Pedido um sistema, é o dele que responde - nunca o do vizinho. */
+        if (slug && entry.name !== slug)
+            continue;
         const raw = await readFile(join(dsDir, entry.name, ".lock"), "utf8").catch(() => null);
         if (!raw)
             continue;
@@ -75,6 +89,37 @@ async function scopeInLock(root) {
 async function present(root, rel) {
     return stat(resolve(root, rel)).then((s) => s.isDirectory(), () => false);
 }
+/**
+ * O SISTEMA SOBRE O QUAL OS COMANDOS AGEM - o primeiro em ordem alfabética.
+ *
+ * Não é uma escolha nova: é a que `loadSystem` já faz (`slugs.sort()`, e o
+ * primeiro lock legível ganha), e o `align` já avisa sobre ela. Ela existe aqui
+ * para que quem precisa do ESCOPO possa dizer DE QUEM - sem isto, `measuredScope`
+ * responde com o primeiro lock que tem escopo, que num repo de dois sistemas pode
+ * ser o do outro. Provado em 19/08: um fork sem escopo mais um importado com
+ * escopo, e a medição de um ia para o outro.
+ */
+export async function actingSlug(root) {
+    const dsDir = join(root, "_synthesisui", "ds");
+    const dirs = (await readdir(dsDir, { withFileTypes: true }).catch(() => []))
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name)
+        .sort();
+    for (const name of dirs) {
+        const raw = await readFile(join(dsDir, name, ".lock"), "utf8").catch(() => null);
+        if (!raw)
+            continue;
+        try {
+            const lock = JSON.parse(raw);
+            if (lock.slug)
+                return lock.slug;
+        }
+        catch {
+            // lock ilegível: o próximo responde
+        }
+    }
+    return null;
+}
 /**
  * Lê `_synthesisui/census.json` e devolve o que ele diz sobre ONDE.
  *
@@ -82,8 +127,17 @@ async function present(root, rel) {
  * desde então não pode fazer o doctor estourar - ela simplesmente sai da lista, e a lista vazia cai no
  * comportamento antigo (a raiz).
  */
-export async function measuredScope(root) {
-    const fromLock = await scopeInLock(root);
+export async function measuredScope(root, 
+/**
+ * O SISTEMA CUJO ESCOPO SE QUER - e passar isto deixou de ser opcional na
+ * prática quando um repo pode ter dois.
+ *
+ * Quem sincroniza um sistema tem que medir O ESCOPO DELE. Sem o slug, o
+ * primeiro lock com escopo respondia por todos, e num repo com um fork sem
+ * escopo mais um importado com escopo o `sync` media um e mandava para o outro.
+ */
+slug) {
+    const fromLock = await scopeInLock(root, slug);
     if (fromLock)
         return fromLock;
     return censusScope(root);

package/dist/merge-census.js

@@ -227,5 +227,57 @@ export function mergeCensus(list) {
         out.collisions = collisions;
     if (conflicts.length > 0)
         out.scopeConflicts = conflicts;
+    /**
+     * A CONVERGÊNCIA ENTRE OS ESCOPOS, calculada aqui porque é aqui que os
+     * vocabulários separados ainda existem - depois da fusão eles são um só.
+     *
+     * `shared` conta os nomes que mais de um escopo declara; `agree` são os que
+     * resolvem igual. Zero compartilhado não é "quase lá": é a informação de que
+     * não há design em comum, e que fundir produziria a média de dois sistemas que
+     * não se parecem.
+     */
+    {
+        /**
+         * O NÚMERO É DIRECIONAL: quanto do vocabulário dos escopos SEGUINTES o
+         * PRIMEIRO já nomeia. A primeira versão media `agree/union`, simétrico, e o
+         * dono estranhou na hora - com razão: um percentual simétrico lê como NOTA, e
+         * se os escopos são vocabulários diferentes de propósito não existe nota a
+         * dar. A pergunta útil é a da migração, e ela tem um sentido.
+         *
+         * E conta POR VALOR além do nome: `--dashboard-blue-500` e `--color-blue-500`
+         * são a mesma decisão com dois nomes - invisível numa comparação por nome, e
+         * é o item mais acionável que sai daqui (dois casos no repo do dono).
+         */
+        const norm = (v) => v.trim().toLowerCase().replace(/\s+/g, " ");
+        const first = asRecord(list[0].declared);
+        const byValue = new Map();
+        for (const [name, value] of Object.entries(first))
+            if (!byValue.has(norm(value)))
+                byValue.set(norm(value), name);
+        let declares = 0;
+        let covered = 0;
+        let aliased = 0;
+        for (const c of list.slice(1)) {
+            for (const [name, value] of Object.entries(asRecord(c.declared))) {
+                declares += 1;
+                const sameName = first[name];
+                if (sameName !== undefined) {
+                    if (sameName === value)
+                        covered += 1;
+                    continue;
+                }
+                if (byValue.has(norm(value))) {
+                    covered += 1;
+                    aliased += 1;
+                }
+            }
+        }
+        out.scopeConvergence = {
+            declares,
+            covered,
+            aliased,
+            percent: declares === 0 ? null : Math.round((covered / declares) * 100),
+        };
+    }
     return out;
 }

package/package.json

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