@semacode/cli 3.12.1 → 3.13.1

package/dist/agentEntryPoints.js

@@ -201,7 +201,7 @@ Score composto, \`achados[]\` e \`decisaoAgente\` são sinais para guiar a próx
 - Consultas honestas: \`resumo\` e \`inspecionar\` usam \`--drift none\` por padrão; score, confiança, implementação, rotas e superfícies não observadas ficam nulos/não avaliados.
 - Se uma consulta executar drift explicitamente, \`payload.analiseDrift.sucesso\` expõe o resultado e uma falha solicitada retorna exit code diferente de zero.
 - Cache: \`sema drift\` usa \`fresh\` por padrão. \`--cache none\` ainda executa sem persistência; \`cache\` acelera extrações validadas, mas não é prova final.
-- Fechamento governado: se o \`payload\` de \`sema drift --cache fresh --json\` retornar \`sucesso:false\`, \`vinculos_quebrados\`, \`rotas_divergentes\` ou \`impls_quebrados\`, não diga que passou limpo. Corrija e rode drift de novo.
+- Fechamento governado: se o \`payload\` de \`sema drift --cache fresh --json\` retornar \`sucesso:false\`, \`vinculos_quebrados\`, \`rotas_divergentes\` ou \`impls_quebrados\`, não diga que passou limpo. Corrija e rode drift de novo. \`vinculos_fora_do_escopo\` é informativo: o arquivo existe no workspace fora dos \`diretoriosCodigo\`; siga o \`diretorioSugerido\` do registro para incluir o diretório no \`sema.config.json\` — não bloqueia fechamento.
 - Experiência governada: se a tarefa cria ou altera site, sistema, app, UI, painel, jogo, CLI/TUI ou terminal, prove acabamento moderno, contextual e não genérico. Em UI estreita (ex. 390px), \`document.documentElement.scrollWidth <= document.documentElement.clientWidth\` precisa ser verdadeiro.
 - Caminho fora do workspace local aberto pelo usuário não substitui a pasta local.
 
@@ -265,7 +265,7 @@ Leia isto primeiro se você tem pouco contexto, pouca memória, pouco tool use o
 15. Payload inline acima de ${LIMITE_CARACTERES_PAYLOAD_INLINE} caracteres não é lentidão: divida por responsabilidade; não aumente timeout para tentar passar limite de transporte.
 16. Se aparecer caminho que não pertence ao workspace local aberto pelo usuário, pare e confirme a fonte antes de agir.
 17. Se Sema estourar por timeout local: aumente o timeout e tente de novo. Não trate isso como falha do Sema.
-18. Para fechamento, rode \`sema drift --cache fresh --json\`; cache persistente só acelera navegação e não é prova final. Se o \`payload\` retornar \`sucesso:false\`, \`vinculos_quebrados\`, \`rotas_divergentes\` ou \`impls_quebrados\`, não conclua. Na 3.0.0, não procure campos de domínio no topo do envelope \`sema.cli.result/v1\` nem use \`ok\` como substituto do veredito do payload.
+18. Para fechamento, rode \`sema drift --cache fresh --json\`; cache persistente só acelera navegação e não é prova final. Se o \`payload\` retornar \`sucesso:false\`, \`vinculos_quebrados\`, \`rotas_divergentes\` ou \`impls_quebrados\`, não conclua. \`vinculos_fora_do_escopo\` é informativo com \`diretorioSugerido\` para o \`sema.config.json\`; não bloqueia fechamento. Na 3.0.0, não procure campos de domínio no topo do envelope \`sema.cli.result/v1\` nem use \`ok\` como substituto do veredito do payload.
 19. Se a tarefa tiver site, sistema, app, UI, painel, jogo, CLI/TUI ou terminal: aplique acabamento moderno, contextual, responsivo/ergonômico, com hierarquia clara, estados e evidência. Em UI, valide mobile/desktop e prove \`scrollWidth <= clientWidth\` em viewport estreito como 390px.
 20. Não substitua o contexto Sema por AGENTS.md, README.md, busca local, inferência por nome ou bom senso.
 
@@ -486,7 +486,7 @@ Sinal e evidência:
 - Score composto, \`achados[]\` e \`decisaoAgente\` orientam a ação; abaixo de 80 bloqueia, alvo evolui 0.5 ponto até 100, e nada substitui evidência concreta.
 - Palavra-chave ou regex passando não prova governança se contrato, código e comportamento não batem.
 - \`resumo\` e \`inspecionar\` usam \`--drift none\` por padrão; campos derivados nulos significam não avaliados, nunca zero.
-- \`sema drift --cache fresh --json\` com \`payload.sucesso:false\`, \`payload.vinculos_quebrados\`, \`payload.rotas_divergentes\` ou \`payload.impls_quebrados\` bloqueia fechamento. Cache persistente é aceleração, não prova final.
+- \`sema drift --cache fresh --json\` com \`payload.sucesso:false\`, \`payload.vinculos_quebrados\`, \`payload.rotas_divergentes\` ou \`payload.impls_quebrados\` bloqueia fechamento. \`payload.vinculos_fora_do_escopo\` é informativo com \`diretorioSugerido\` para os \`diretoriosCodigo\`; não bloqueia. Cache persistente é aceleração, não prova final.
 - Caminho fora do workspace local aberto pelo usuário não substitui a pasta local.
 
 Acabamento visual e terminal:
@@ -685,9 +685,9 @@ This is the minimum workflow for Codex in a local workspace.
 
 Contract edit rule: \`.sema\` has its own size budget. Above ${LIMITE_AVISO_LINHAS_CONTRATO_SEMA} lines, plan a split by domain/capability; above ${LIMITE_BLOQUEIO_LINHAS_CONTRATO_SEMA}, do not create or edit before splitting. Do not use parte_1/parte_2 and do not force a 1:1 contract-to-file relationship; several contracts can govern the same file through \`vinculos\`.
 
-Closing rule: the \`payload\` of \`sema drift --cache fresh --json\` must return \`sucesso:true\`. If it reports \`sucesso:false\`, \`vinculos_quebrados\`, \`rotas_divergentes\`, or \`impls_quebrados\`, the task is still blocked. Passing unit tests or a cache hit do not replace fresh green drift. In 3.0.0, \`ok\` describes the CLI result path and never replaces a command-specific domain verdict.
+Closing rule: the \`payload\` of \`sema drift --cache fresh --json\` must return \`sucesso:true\`. If it reports \`sucesso:false\`, \`vinculos_quebrados\`, \`rotas_divergentes\`, or \`impls_quebrados\`, the task is still blocked. Passing unit tests or a cache hit do not replace fresh green drift. \`vinculos_fora_do_escopo\` is informational: the file exists in the workspace outside the configured \`diretoriosCodigo\`, and each entry carries a \`diretorioSugerido\` to add to \`sema.config.json\`; it does not block closure. In 3.0.0, \`ok\` describes the CLI result path and never replaces a command-specific domain verdict.
 
-Focused drift rule: file and module scopes plan their physical file set before cataloging. They never fall back to a whole-project walk when no safe anchor exists. All indexers and semantic-budget checks reuse the same in-memory source read; a global walk is reserved for explicit \`--escopo projeto\`. Code discovery is deferred until that plan exists, homonymous candidates fail as ambiguous, and configured contract origins or code roots resolving outside the workspace are rejected before enumeration. \`inspecionar\`, \`impacto\`, and \`renomear-semantico\` preserve the same directed boundary. Missing local dependencies make coverage partial and block success.
+Focused drift rule: file and module scopes plan their physical file set before cataloging. They never fall back to a whole-project walk when no safe anchor exists. All indexers and semantic-budget checks reuse the same in-memory source read; a global walk is reserved for explicit \`--escopo projeto\`. Code discovery is deferred until that plan exists, homonymous candidates fail as ambiguous, and configured contract origins or code roots resolving outside the workspace are rejected before enumeration. \`inspecionar\`, \`impacto\`, and \`renomear-semantico\` preserve the same directed boundary. Missing unambiguous local dependencies make coverage partial and block success. In Python, an unresolved \`name\` from \`from module import name\` is not itself a missing file after \`module\` resolves: it may be an exported symbol, while a real child module is still included whenever its file exists.
 
 Cache rule: a closure gate should use \`sema drift <contrato> --escopo modulo --cache fresh --json\`. \`--cache none\` executes the same analysis without persistent-cache I/O, while \`--cache cache\` may reuse only extraction data whose schema, workspace identity, Git HEAD, plan, configuration, contracts, member paths, and strong content digests all match. Cache objects are stored in the operating system's user-cache directory, never below the workspace. A hit is acceleration, not evidence: final links, diagnostics, score, and success are always recalculated. Corruption or an unavailable cache degrades to an in-memory calculation.
 
@@ -752,7 +752,7 @@ Then read every required doc returned by \`docs-impacto\`.
 
 ## Contract and Discovery
 
-- \`sema iniciar --template <base|nestjs|fastapi|nextjs-api|nextjs-consumer|react-vite-consumer|angular-consumer|flutter-consumer|node-firebase-worker|aspnet-api|springboot-api|go-http-api|rust-axum-api|cpp-service-bridge> [--force]\`: creates a new Sema project and preserves existing files by default; \`--force\` is the only explicit overwrite path.
+- \`sema iniciar --template <base|nestjs|fastapi|nextjs-api|nextjs-consumer|react-vite-consumer|angular-consumer|flutter-consumer|node-firebase-worker|aspnet-api|springboot-api|go-http-api|rust-axum-api|cpp-service-bridge> [--force]\`: creates a new Sema project and preserves existing files by default; \`--force\` is the only explicit overwrite path. Inside a subfolder of an already governed workspace, the subfolder is registered under \`diretoriosCodigo\` of the ancestral \`sema.config.json\` (safe write, deduplicated) instead of creating a local config; if the parent config cannot be written, the scaffold proceeds and prints the exact line to add.
 - \`sema validar <arquivo-ou-pasta> --json\`: validates \`.sema\` contracts.
 - \`sema diagnosticos <arquivo.sema> --json\`: details errors and warnings.
 - \`sema formatar <arquivo-ou-pasta>\`: formats contracts.
@@ -772,9 +772,9 @@ Then read every required doc returned by \`docs-impacto\`.
 - \`sema verificar <arquivo-ou-pasta> --json\`: runs aggregated final verification.
 - \`sema finalizar-mudanca --intencao "<acao>" --doc-lida <arquivo> --json\`: proves documentation reading before closure.
 
-Honest closure: unwrap drift JSON and treat its command payload as the source of truth. \`payload.sucesso:false\`, non-empty \`payload.vinculos_quebrados\`, non-empty \`payload.rotas_divergentes\`, or non-empty \`payload.impls_quebrados\` mean the change is not complete yet. Do not report "clean drift" without a green payload.
+Honest closure: unwrap drift JSON and treat its command payload as the source of truth. \`payload.sucesso:false\`, non-empty \`payload.vinculos_quebrados\`, non-empty \`payload.rotas_divergentes\`, or non-empty \`payload.impls_quebrados\` mean the change is not complete yet. Do not report "clean drift" without a green payload. \`payload.vinculos_fora_do_escopo\` is informational: the file exists in the workspace outside \`diretoriosCodigo\`, and each entry carries a \`diretorioSugerido\` for \`sema.config.json\`.
 
-Focused drift exposes its planned, declared, inferred, and missing files plus catalog visit/read metrics in \`escopo_aplicado\`. A missing declared file or a missing code-referenced dependency is a blocker reported as \`vinculo_quebrado\`; a missing inferred candidate derived from an \`impl\` symbol is informational under \`arquivosAusentesInferidos\` and never blocks an implementation that resolved. File and module scopes fail closed without a safe anchor, with homonymous implementation candidates, or with missing local dependencies; only \`--escopo projeto\` may walk every configured code root. Logical roots such as \`src\` are probed deterministically without a discovery walk. Configured contract origins and code roots are confined before enumeration, and \`inspecionar\`, \`impacto\`, and \`renomear-semantico\` reuse the same directed boundary without reopening arbitrary external paths.
+Focused drift exposes its planned, declared, inferred, and missing files plus catalog visit/read metrics in \`escopo_aplicado\`. A missing declared file or a missing unambiguous code-referenced dependency is a blocker reported as \`vinculo_quebrado\`; a missing inferred candidate derived from an \`impl\` symbol is informational under \`arquivosAusentesInferidos\` and never blocks an implementation that resolved. For Python \`from module import name\`, Sema still includes \`name\` when it resolves as a real submodule, but never reports the absent submodule candidate as a broken link after the parent module resolved because \`name\` may be a function, class, or variable. File and module scopes fail closed without a safe anchor, with homonymous implementation candidates, or with missing local dependencies; only \`--escopo projeto\` may walk every configured code root. Logical roots such as \`src\` are probed deterministically without a discovery walk. Configured contract origins and code roots are confined before enumeration, and \`inspecionar\`, \`impacto\`, and \`renomear-semantico\` reuse the same directed boundary without reopening arbitrary external paths.
 
 Drift analysis and cache modes are explicit:
 
@@ -877,7 +877,7 @@ Spatial model and render mode are orthogonal: \`THREE_D + HEADLESS\` is valid, w
 - Do not stop after \`sema compilar\` if the contract target files still do not exist.
 - Do not replace \`sema compilar\` with \`sema testar\` when the contract requires generated code.
 - Do not create a Markdown report to pretend a gate ran.
-- Do not say drift passed when the unwrapped \`sema drift --cache fresh --json\` payload returned \`sucesso:false\`, a non-empty \`vinculos_quebrados\`, \`rotas_divergentes\`, or \`impls_quebrados\` list.
+- Do not say drift passed when the unwrapped \`sema drift --cache fresh --json\` payload returned \`sucesso:false\`, a non-empty \`vinculos_quebrados\`, \`rotas_divergentes\`, or \`impls_quebrados\` list. \`vinculos_fora_do_escopo\` entries are informational scope hints, not broken links.
 - Do not declare a UI responsive without mobile/desktop proof; horizontal scroll at 390px blocks closure.
 
 Governed code policy: keep the \`SEMA-GOVERNED\` marker, split large code by real responsibility, preserve contract links, and never treat a generated output directory as the final delivery.

package/dist/cliHelpTexto.js

@@ -26,7 +26,7 @@ export function criarAjudaRaiz(versao) {
         renderizarSecaoAscii("Fluxos rápidos", [
             "[1] Projeto novo / produção inicial",
             "sema iniciar --template <base|nestjs|fastapi|nextjs-api|nextjs-consumer|react-vite-consumer|angular-consumer|flutter-consumer|node-firebase-worker|aspnet-api|springboot-api|go-http-api|rust-axum-api|cpp-service-bridge> [--force] [--com-exemplos]",
-            "Arquivos existentes são preservados; use --force somente para sobrescrita explícita. O starter de exemplos vem por padrão; --com-exemplos instala o pacote completo.",
+            "Arquivos existentes são preservados; use --force somente para sobrescrita explícita. O starter de exemplos vem por padrão; --com-exemplos instala o pacote completo. Em subpasta de workspace já governado, a subpasta é registrada nos diretoriosCodigo do sema.config.json ancestral em vez de criar config local.",
             "sema validar contratos/<modulo>.sema --json",
             "sema compilar <arquivo-ou-pasta> --alvo <typescript|python|php|dart|lua|javascript|html|css|dotnet|cpp> --saida <diretorio>",
             "sema verificar <arquivo-ou-pasta> [--saida <dir>] [--alvo <alvo>] [--sem-cache] --json",

package/dist/drift.contrato.d.ts

@@ -19,6 +19,7 @@ export declare function executarDriftCheck(contratos: string[], codigoVivo: stri
     impls_quebrados: number;
     vinculos_validos: number;
     vinculos_quebrados: number;
+    vinculos_fora_do_escopo: number;
     score: number;
     piso_operacional: number;
     alvo_atual: number;

package/dist/drift.contrato.js

@@ -30,6 +30,7 @@ export function executarDriftCheck(contratos, codigoVivo) {
         impls_quebrados: implsQuebrados,
         vinculos_validos: vinculosValidos,
         vinculos_quebrados: vinculosQuebrados,
+        vinculos_fora_do_escopo: 0,
         score,
         piso_operacional: avaliacao.pontuacaoMinimaOperacional,
         alvo_atual: avaliacao.pontuacaoAlvoAtual,

package/dist/drift.part01.d.ts

@@ -39,7 +39,7 @@ export interface OpcoesDriftLegado {
     observador?: ObservadorOperacaoDrift | undefined;
 }
 export interface DiagnosticoDrift {
-    tipo: "impl_quebrado" | "task_sem_impl" | "rota_divergente" | "recurso_divergente" | "vinculo_quebrado" | "seguranca_frouxa" | "pontuacao_semantica_insuficiente" | "contrato_monolitico" | "codigo_monolitico" | "codigo_governado_sem_cabecalho" | "escopo_estreito_sem_vinculos" | "escopo_estreito_ambiguo" | "design_nao_declarado";
+    tipo: "impl_quebrado" | "task_sem_impl" | "rota_divergente" | "recurso_divergente" | "vinculo_quebrado" | "vinculo_fora_do_escopo" | "seguranca_frouxa" | "pontuacao_semantica_insuficiente" | "contrato_monolitico" | "codigo_monolitico" | "codigo_governado_sem_cabecalho" | "escopo_estreito_sem_vinculos" | "escopo_estreito_ambiguo" | "design_nao_declarado";
     modulo: string;
     task?: string;
     route?: string;
@@ -149,8 +149,9 @@ export interface RegistroVinculoDrift {
     valor: string;
     arquivo?: string;
     simbolo?: string;
-    status: "resolvido" | "parcial" | "nao_encontrado";
+    status: "resolvido" | "parcial" | "nao_encontrado" | "fora_do_escopo";
     confianca: NivelConfiancaSemantica;
+    diretorioSugerido?: string;
 }
 export interface RegistroPersistenciaRealDrift {
     modulo: string;
@@ -256,6 +257,7 @@ export interface ResultadoDrift {
     impls_quebrados: RegistroImplDrift[];
     vinculos_validos: RegistroVinculoDrift[];
     vinculos_quebrados: RegistroVinculoDrift[];
+    vinculos_fora_do_escopo: RegistroVinculoDrift[];
     rotas_divergentes: RegistroRotaDivergente[];
     recursos_validos: RegistroRecursoDrift[];
     recursos_divergentes: RegistroRecursoDrift[];

package/dist/drift.part11.js

@@ -10,7 +10,8 @@ import { calcularConfiancaTask, calcularRiscoOperacional, calcularScoreTask, car
 import { analisarPersistenciaReal, ordenarCandidatos } from "./drift.part09.js";
 import { simboloEhBridgeConsumer } from "./drift.part05.js";
 import { prepararIndicesDrift } from "./drift.part13.js";
-import { analisarModulosSelecionadosDrift } from "./drift.part14.js";
+import { sondarCaminhosDeclaradosExistentes } from "./driftEscopo.js";
+import { analisarModulosSelecionadosDrift, coletarCaminhosDeclaradosVinculosDrift } from "./drift.part14.js";
 import { resolverPoliticaPontuacaoSemantica } from "./driftScore.js";
 function arquivosVinculadosFisicamenteDrift(contexto, modulo, task) {
     const arquivos = new Set();
@@ -158,6 +159,7 @@ export async function analisarDriftLegado(contexto, opcoes) {
         const implsQuebrados = [];
         const vinculosValidos = [];
         const vinculosQuebrados = [];
+        const vinculosForaDoEscopo = [];
         const rotasDivergentes = [];
         const recursosValidos = [];
         const recursosDivergentes = [];
@@ -209,6 +211,12 @@ export async function analisarDriftLegado(contexto, opcoes) {
         for (const substituicao of substituicoesCaminho) {
             substituicao.implementacao.caminho = substituicao.temporario;
         }
+        // Sonda previa: distingue vinculo apontando para arquivo inexistente de
+        // arquivo existente fora dos diretoriosCodigo (informativo, nao bloqueante).
+        const caminhosDeclaradosVinculos = coletarCaminhosDeclaradosVinculosDrift(contexto);
+        const arquivosDeclaradosExistentes = caminhosDeclaradosVinculos.length > 0
+            ? await sondarCaminhosDeclaradosExistentes(caminhosDeclaradosVinculos, contexto.baseProjeto)
+            : new Map();
         try {
             analisarModulosSelecionadosDrift({
                 contexto,
@@ -222,6 +230,8 @@ export async function analisarDriftLegado(contexto, opcoes) {
                 implsQuebrados,
                 vinculosValidos,
                 vinculosQuebrados,
+                vinculosForaDoEscopo,
+                arquivosDeclaradosExistentes,
                 rotasDivergentes,
                 recursosValidos,
                 recursosDivergentes,
@@ -563,6 +573,7 @@ export async function analisarDriftLegado(contexto, opcoes) {
             impls_quebrados: implsQuebrados,
             vinculos_validos: vinculosValidos,
             vinculos_quebrados: vinculosQuebrados,
+            vinculos_fora_do_escopo: vinculosForaDoEscopo,
             rotas_divergentes: rotasDivergentes,
             recursos_validos: recursosValidos,
             recursos_divergentes: recursosDivergentes,

package/dist/drift.part14.d.ts

@@ -14,6 +14,7 @@ export interface GuardrailsTaskDrift {
     efeitoPrivilegiado: boolean;
     exigeSegredos: boolean;
 }
+export declare function coletarCaminhosDeclaradosVinculosDrift(contexto: ContextoProjetoCarregado): string[];
 export interface ResumoVinculosTaskDrift {
     validos: number;
     quebrados: number;
@@ -31,6 +32,8 @@ export interface EstadoAnaliseModulosDrift {
     implsQuebrados: RegistroImplDrift[];
     vinculosValidos: RegistroVinculoDrift[];
     vinculosQuebrados: RegistroVinculoDrift[];
+    vinculosForaDoEscopo: RegistroVinculoDrift[];
+    arquivosDeclaradosExistentes: ReadonlyMap<string, boolean>;
     rotasDivergentes: RegistroRotaDivergente[];
     recursosValidos: RegistroRecursoDrift[];
     recursosDivergentes: RegistroRecursoDrift[];

package/dist/drift.part14.js

@@ -2,7 +2,7 @@
 // Descricao: analisa modulos selecionados no drift; consulte contratos/sema/governanca_ia_contexto.sema antes de editar.
 import path from "node:path";
 import { escolherArquivoPorVinculo, escolherSimboloPorVinculo } from "./drift.part03.js";
-import { calcularRiscoOperacional, encontrarAncoraSuperficie } from "./drift.part04.js";
+import { calcularRiscoOperacional, chaveCaminhoCanonicoDrift, encontrarAncoraSuperficie } from "./drift.part04.js";
 import { resolverPersistenciaLocalPorTask } from "./drift.part08.js";
 import { escolherRotasEsperadas, normalizarCaminhoRota, ordenarCandidatos, sugerirCandidatosParaImpl, sugerirCandidatosParaTaskSemImpl } from "./drift.part09.js";
 import { coletarVinculosIr, extrairRecursosEsperados, resolverRecursoEsperado } from "./drift.part10.js";
@@ -30,8 +30,61 @@ function redigirCaminhoDeclaradoExterno(baseProjeto, valor) {
     const nome = path.basename(path.normalize(valor)) || "arquivo";
     return `[fora_do_workspace]/${nome}`;
 }
+function caminhoDeclaradoTentadoVinculo(vinculo) {
+    const arquivoDeclarado = vinculo.arquivo ?? (vinculo.tipo === "arquivo" ? vinculo.valor : undefined);
+    if (arquivoDeclarado) {
+        return arquivoDeclarado;
+    }
+    const recursoDeclarado = vinculo.recurso ?? (["recurso", "tabela", "fila", "cache", "storage"].includes(vinculo.tipo) ? vinculo.valor : undefined);
+    if (recursoDeclarado) {
+        return undefined;
+    }
+    const superficieDeclarada = vinculo.superficie ?? (["superficie", "rota", "worker", "cron", "webhook", "evento", "policy", "fila", "cache", "storage"].includes(vinculo.tipo) ? vinculo.valor : undefined);
+    return superficieDeclarada ?? vinculo.valor;
+}
+function sugerirDiretorioCodigoDrift(baseProjeto, caminhoAbsoluto) {
+    const diretorioRelativo = path.relative(path.resolve(baseProjeto), path.dirname(path.resolve(caminhoAbsoluto))).replace(/\\/g, "/");
+    return `./${diretorioRelativo || "."}`;
+}
+function arquivoDentroDoEscopoCodigo(contexto, caminhoAbsoluto) {
+    return contexto.diretoriosCodigo.some((diretorio) => {
+        const relativo = path.relative(path.resolve(diretorio), path.resolve(caminhoAbsoluto));
+        return relativo === "" || (!relativo.startsWith("..") && !path.isAbsolute(relativo));
+    });
+}
+// Simbolo declarado cujo dono ancora codigo em arquivo existente fora dos
+// diretoriosCodigo: casa o caminho do simbolo com o diretorio do arquivo.
+function escolherAncoraForaDoEscopoPorSimbolo(caminhos, baseProjeto, simbolo) {
+    const simboloComoCaminho = simbolo.toLowerCase().replaceAll(".", "/");
+    const porPrefixo = caminhos.find((caminho) => {
+        const diretorioRelativo = path.relative(path.resolve(baseProjeto), path.dirname(path.resolve(caminho))).replace(/\\/g, "/").toLowerCase();
+        return diretorioRelativo !== "" && simboloComoCaminho.startsWith(`${diretorioRelativo}/`);
+    });
+    if (porPrefixo) {
+        return porPrefixo;
+    }
+    return caminhos.length === 1 ? caminhos[0] : undefined;
+}
+// O analisador de modulos e sincrono: a existencia em disco dos caminhos
+// declarados em vinculos e sondada antes, pelo chamador, e injetada no estado.
+export function coletarCaminhosDeclaradosVinculosDrift(contexto) {
+    const caminhos = [];
+    for (const item of contexto.modulosSelecionados) {
+        const ir = item.resultado.ir;
+        if (!ir) {
+            continue;
+        }
+        for (const itemVinculo of coletarVinculosIr(ir)) {
+            const declarado = caminhoDeclaradoTentadoVinculo(itemVinculo.vinculo);
+            if (declarado) {
+                caminhos.push(path.resolve(contexto.baseProjeto, declarado));
+            }
+        }
+    }
+    return caminhos;
+}
 export function analisarModulosSelecionadosDrift(estado) {
-    const { contexto, mapaImpl, todosSimbolos, mapaRecursos, todosRecursos, todasRotasIndexadas, todosArquivosConhecidos, implsValidos, implsQuebrados, vinculosValidos, vinculosQuebrados, rotasDivergentes, recursosValidos, recursosDivergentes, diagnosticos, tasksResumo, taskPorChave, guardrailsPorTask, resumoVinculosPorTask, arquivosAncoraHerdadosPorTask, } = estado;
+    const { contexto, mapaImpl, todosSimbolos, mapaRecursos, todosRecursos, todasRotasIndexadas, todosArquivosConhecidos, implsValidos, implsQuebrados, vinculosValidos, vinculosQuebrados, vinculosForaDoEscopo, arquivosDeclaradosExistentes, rotasDivergentes, recursosValidos, recursosDivergentes, diagnosticos, tasksResumo, taskPorChave, guardrailsPorTask, resumoVinculosPorTask, arquivosAncoraHerdadosPorTask, } = estado;
     for (const item of contexto.modulosSelecionados) {
         const ir = item.resultado.ir;
         if (!ir) {
@@ -309,6 +362,23 @@ export function analisarModulosSelecionadosDrift(estado) {
                 });
             }
         }
+        const arquivosForaDoEscopoPorDono = new Map();
+        for (const itemVinculoDono of coletarVinculosIr(ir)) {
+            const declarado = itemVinculoDono.vinculo.arquivo
+                ?? (itemVinculoDono.vinculo.tipo === "arquivo" ? itemVinculoDono.vinculo.valor : undefined);
+            if (!declarado) {
+                continue;
+            }
+            const absoluto = path.resolve(contexto.baseProjeto, declarado);
+            if (arquivosDeclaradosExistentes.get(chaveCaminhoCanonicoDrift(absoluto)) !== true
+                || arquivoDentroDoEscopoCodigo(contexto, absoluto)) {
+                continue;
+            }
+            const chaveDono = `${itemVinculoDono.donoTipo}:${itemVinculoDono.dono}`;
+            const lista = arquivosForaDoEscopoPorDono.get(chaveDono) ?? [];
+            lista.push(absoluto);
+            arquivosForaDoEscopoPorDono.set(chaveDono, lista);
+        }
         for (const itemVinculo of coletarVinculosIr(ir)) {
             const registro = {
                 modulo: ir.nome,
@@ -385,13 +455,41 @@ export function analisarModulosSelecionadosDrift(estado) {
                 }
             }
             if (registro.status === "nao_encontrado") {
-                vinculosQuebrados.push(registro);
-                diagnosticos.push({
-                    tipo: "vinculo_quebrado",
-                    modulo: ir.nome,
-                    mensagem: `Vinculo ${registro.tipo}="${registro.valor}" de ${registro.donoTipo} "${registro.dono}" nao foi resolvido no codigo vivo.`,
-                    ...(itemVinculo.donoTipo === "task" ? { task: itemVinculo.dono } : itemVinculo.donoTipo === "route" ? { route: itemVinculo.dono } : {}),
-                });
+                const caminhoTentado = caminhoDeclaradoTentadoVinculo(itemVinculo.vinculo);
+                const caminhoAbsoluto = caminhoTentado ? path.resolve(contexto.baseProjeto, caminhoTentado) : undefined;
+                const existeNoDisco = caminhoAbsoluto !== undefined
+                    && arquivosDeclaradosExistentes.get(chaveCaminhoCanonicoDrift(caminhoAbsoluto)) === true;
+                // Arquivo proprio declarado fora do escopo, ou simbolo que herda a ancora
+                // de arquivo declarado do mesmo dono existente fora dos diretoriosCodigo.
+                const alvoForaDoEscopo = existeNoDisco && caminhoAbsoluto !== undefined && !arquivoDentroDoEscopoCodigo(contexto, caminhoAbsoluto)
+                    ? caminhoAbsoluto
+                    : simboloDeclarado
+                        ? escolherAncoraForaDoEscopoPorSimbolo(arquivosForaDoEscopoPorDono.get(`${itemVinculo.donoTipo}:${itemVinculo.dono}`) ?? [], contexto.baseProjeto, simboloDeclarado)
+                        : undefined;
+                if (alvoForaDoEscopo) {
+                    const diretorioSugerido = sugerirDiretorioCodigoDrift(contexto.baseProjeto, alvoForaDoEscopo);
+                    registro.status = "fora_do_escopo";
+                    registro.confianca = "baixa";
+                    registro.arquivo = alvoForaDoEscopo;
+                    registro.diretorioSugerido = diretorioSugerido;
+                    vinculosForaDoEscopo.push(registro);
+                    diagnosticos.push({
+                        tipo: "vinculo_fora_do_escopo",
+                        modulo: ir.nome,
+                        severidade: "aviso",
+                        mensagem: `Vinculo ${registro.tipo}="${registro.valor}" de ${itemVinculo.donoTipo} "${itemVinculo.dono}": o codigo existe no workspace mas esta fora dos diretoriosCodigo do sema.config.json; adicione "${diretorioSugerido}" a diretoriosCodigo para o drift verificar este vinculo.`,
+                        ...(itemVinculo.donoTipo === "task" ? { task: itemVinculo.dono } : itemVinculo.donoTipo === "route" ? { route: itemVinculo.dono } : {}),
+                    });
+                }
+                else {
+                    vinculosQuebrados.push(registro);
+                    diagnosticos.push({
+                        tipo: "vinculo_quebrado",
+                        modulo: ir.nome,
+                        mensagem: `Vinculo ${registro.tipo}="${registro.valor}" de ${itemVinculo.donoTipo} "${itemVinculo.dono}" nao foi resolvido no codigo vivo.`,
+                        ...(itemVinculo.donoTipo === "task" ? { task: itemVinculo.dono } : itemVinculo.donoTipo === "route" ? { route: itemVinculo.dono } : {}),
+                    });
+                }
             }
             else {
                 vinculosValidos.push(registro);
@@ -429,7 +527,7 @@ export function analisarModulosSelecionadosDrift(estado) {
                 if (registro.status === "nao_encontrado") {
                     resumo.quebrados += 1;
                 }
-                else {
+                else if (registro.status !== "fora_do_escopo") {
                     resumo.validos += 1;
                 }
                 if (registro.arquivo) {

package/dist/driftEscopo.d.ts

@@ -18,5 +18,6 @@ export interface PlanoEscopoDrift {
     bloqueios: string[];
     dependencias: Record<string, string[]>;
 }
+export declare function sondarCaminhosDeclaradosExistentes(caminhos: readonly string[], baseProjeto: string): Promise<Map<string, boolean>>;
 export declare function planejarEscopoDrift(contexto: ContextoProjetoCarregado, configuracao: ConfiguracaoEscopoDriftAplicada): Promise<PlanoEscopoDrift>;
 export declare function expandirDependenciasPlanoDrift(contexto: ContextoProjetoCarregado, plano: PlanoEscopoDrift, catalogo: CatalogoDrift): Promise<PlanoEscopoDrift>;

package/dist/driftEscopo.js

@@ -84,6 +84,12 @@ async function sondarArquivosRegularesContidos(caminhos, raizReal) {
     const resultados = await mapearComLimite(unicos, CONCORRENCIA_SONDAGENS_DRIFT, async ([chave, caminho]) => [chave, await arquivoRegularContido(caminho, raizReal)]);
     return new Map(resultados);
 }
+// Sonda arquivos declarados em vinculos contra o workspace real: alimenta a
+// distincao entre "arquivo nao existe" e "existe fora dos diretoriosCodigo".
+export async function sondarCaminhosDeclaradosExistentes(caminhos, baseProjeto) {
+    const raizReal = await realpath(baseProjeto);
+    return sondarArquivosRegularesContidos(caminhos, raizReal);
+}
 function vinculosModulo(ir) {
     return [
         ...ir.vinculos,
@@ -570,7 +576,12 @@ async function resolverReferenciasLocais(contexto, arquivoOrigem, referencias, c
         }
         const modulo = item.referencia.slice("python:".length);
         const prefixoLocalResolvido = modulosPythonResolvidos.some((prefixo) => prefixo !== modulo && modulo.startsWith(`${prefixo}.`));
-        if (!referenciaPythonEhLocalObrigatoria(item.referencia) && !prefixoLocalResolvido) {
+        if (prefixoLocalResolvido) {
+            // Em `from modulo import nome`, `nome` pode ser simbolo exportado ou submodulo.
+            // Inclua o submodulo quando existir, mas sua ausencia nao prova dependencia quebrada.
+            return { referencia: item.referencia };
+        }
+        if (!referenciaPythonEhLocalObrigatoria(item.referencia)) {
             return item;
         }
         const candidatos = candidatosReferenciaLocalDrift(contexto, arquivoOrigem, item.referencia);

package/dist/index.part03.d.ts

@@ -13,6 +13,7 @@ export declare function resumirDriftPorModulo(modulo: string | null, caminho: st
     implsQuebrados: number;
     vinculosValidos: number;
     vinculosQuebrados: number;
+    vinculosForaDoEscopo: number;
     recursosValidos: number;
     recursosDivergentesCount: number;
     tasksSemImplementacao: number;
@@ -31,6 +32,7 @@ export declare function resumirDriftPorModulo(modulo: string | null, caminho: st
     rotasDivergentes: import("./drift.part01.js").RegistroRotaDivergente[];
     recursosDivergentes: import("./drift.part01.js").RegistroRecursoDrift[];
     vinculosQuebradosDetalhes: import("./drift.part01.js").RegistroVinculoDrift[];
+    vinculosForaDoEscopoDetalhes: import("./drift.part01.js").RegistroVinculoDrift[];
 };
 export declare function criarBriefingAgente(arquivo: string, modulo: string, ir: IrModulo | null, resumoDrift: ReturnType<typeof resumirDriftPorModulo>, resultadoDrift: Awaited<ReturnType<typeof analisarDriftLegado>>): {
     arquivo: string;

package/dist/index.part03.js

@@ -112,6 +112,9 @@ export function resumirDriftPorModulo(modulo, caminho, resultadoDrift) {
     const vinculosQuebrados = modulo
         ? resultadoDrift.vinculos_quebrados.filter((vinculo) => vinculo.modulo === modulo)
         : [];
+    const vinculosForaDoEscopo = modulo
+        ? resultadoDrift.vinculos_fora_do_escopo.filter((vinculo) => vinculo.modulo === modulo)
+        : [];
     const rotasDivergentes = modulo
         ? resultadoDrift.rotas_divergentes.filter((rota) => rota.modulo === modulo)
         : [];
@@ -136,6 +139,7 @@ export function resumirDriftPorModulo(modulo, caminho, resultadoDrift) {
             ...implsValidos.map((impl) => impl.arquivo).filter((item) => Boolean(item)),
             ...implsQuebrados.flatMap((impl) => impl.candidatos?.map((candidato) => candidato.arquivo) ?? []),
             ...vinculosValidos.map((vinculo) => vinculo.arquivo).filter((item) => Boolean(item)),
+            ...vinculosForaDoEscopo.map((vinculo) => vinculo.arquivo).filter((item) => Boolean(item)),
             ...recursosValidos.map((recurso) => recurso.arquivo).filter(Boolean),
             ...recursosDivergentes.map((recurso) => recurso.arquivo).filter(Boolean),
         ])].sort((a, b) => a.localeCompare(b, "pt-BR"));
@@ -176,6 +180,7 @@ export function resumirDriftPorModulo(modulo, caminho, resultadoDrift) {
         implsQuebrados: implsQuebrados.length,
         vinculosValidos: vinculosValidos.length,
         vinculosQuebrados: vinculosQuebrados.length,
+        vinculosForaDoEscopo: vinculosForaDoEscopo.length,
         recursosValidos: recursosValidos.length,
         recursosDivergentesCount: recursosDivergentes.length,
         tasksSemImplementacao: tasks.filter((task) => task.semImplementacao).length,
@@ -198,6 +203,7 @@ export function resumirDriftPorModulo(modulo, caminho, resultadoDrift) {
         rotasDivergentes,
         recursosDivergentes,
         vinculosQuebradosDetalhes: vinculosQuebrados,
+        vinculosForaDoEscopoDetalhes: vinculosForaDoEscopo,
     };
 }
 export function criarBriefingAgente(arquivo, modulo, ir, resumoDrift, resultadoDrift) {

package/dist/index.part05.js

@@ -173,6 +173,7 @@ export async function comandoDrift(entrada, args, emJson, cwd = process.cwd()) {
     console.log(`- Impl quebrados: ${resultado.impls_quebrados.length}`);
     console.log(`- Vinculos validos: ${resultado.vinculos_validos.length}`);
     console.log(`- Vinculos quebrados: ${resultado.vinculos_quebrados.length}`);
+    console.log(`- Vinculos fora do escopo (informativo): ${resultado.vinculos_fora_do_escopo.length}`);
     console.log(`- Rotas divergentes: ${resultado.rotas_divergentes.length}`);
     console.log(`- Recursos vivos validos: ${resultado.recursos_validos.length}`);
     console.log(`- Recursos vivos divergentes: ${resultado.recursos_divergentes.length}`);
@@ -229,6 +230,12 @@ export async function comandoDrift(entrada, args, emJson, cwd = process.cwd()) {
             console.log(`  - ${vinculo.modulo}.${vinculo.dono} :: ${vinculo.tipo}=${vinculo.valor}`);
         }
     }
+    if (resultado.vinculos_fora_do_escopo.length > 0) {
+        console.log("- Vinculos fora do escopo (arquivo existe fora dos diretoriosCodigo; informativo):");
+        for (const vinculo of resultado.vinculos_fora_do_escopo) {
+            console.log(`  - ${vinculo.modulo}.${vinculo.dono} :: ${vinculo.tipo}=${vinculo.valor} :: adicione "${vinculo.diretorioSugerido ?? "./"}" a diretoriosCodigo`);
+        }
+    }
     if (resultado.resumo_operacional.oQueTocar.length > 0) {
         console.log("- O que tocar primeiro:");
         for (const alvo of resultado.resumo_operacional.oQueTocar.slice(0, 8)) {

package/dist/initCommand.js

@@ -1,11 +1,35 @@
 // SEMA-GOVERNED: sema.produto.cli_init_templates, sema.produto.escrita_segura_workspace
 // Descrição: inicializa projetos preservando arquivos existentes e bloqueando escapes do workspace.
 import * as fs from "node:fs";
+import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { escreverArquivos } from "./fsGovernado.js";
 import { arquivosTemplateIniciar } from "./initTemplatesBase.js";
 import { materializarExemplosOficiais, normalizarCaminhoExemplo, planejarExemplosOficiais } from "./exemplosOficiais.js";
-import { validarDestinosEscritaWorkspace } from "./workspaceWrite.js";
+import { carregarConfiguracaoProjeto } from "./projetoConfig.js";
+import { escreverArquivoWorkspaceSeguro, validarDestinosEscritaWorkspace } from "./workspaceWrite.js";
+async function registrarSubpastaNoConfigAncestral(caminhoConfig, subpastaAbsoluta) {
+    const basePai = path.dirname(caminhoConfig);
+    const relativoSubpasta = `./${path.relative(basePai, subpastaAbsoluta).replace(/\\/g, "/")}`;
+    try {
+        const configPai = JSON.parse(await readFile(caminhoConfig, "utf8"));
+        const diretoriosAtuais = Array.isArray(configPai.diretoriosCodigo)
+            ? configPai.diretoriosCodigo.filter((valor) => typeof valor === "string")
+            : [];
+        const jaRegistrado = diretoriosAtuais.some((diretorio) => diretorio.replace(/\\/g, "/").toLowerCase() === relativoSubpasta.toLowerCase());
+        if (jaRegistrado) {
+            console.log(`Subpasta ${relativoSubpasta} ja consta em diretoriosCodigo de ${caminhoConfig}.`);
+            return;
+        }
+        configPai.diretoriosCodigo = [...diretoriosAtuais, relativoSubpasta];
+        await escreverArquivoWorkspaceSeguro(basePai, "sema.config.json", `${JSON.stringify(configPai, null, 2)}\n`, { sobrescrever: true });
+        console.log(`Subpasta ${relativoSubpasta} registrada em diretoriosCodigo de ${caminhoConfig}.`);
+    }
+    catch (erro) {
+        console.error(`Nao foi possivel registrar a subpasta no config do workspace pai: ${erro instanceof Error ? erro.message : String(erro)}`);
+        console.error(`Adicione "${relativoSubpasta}" a diretoriosCodigo em ${caminhoConfig} para o drift cobrir esta subpasta.`);
+    }
+}
 async function sincronizarKitIaInicial(cwd) {
     const [{ gerarResumoProjetoIa }, { sincronizarEntrypointCodex }] = await Promise.all([
         import("./index.part04.js"),
@@ -33,7 +57,19 @@ const EXEMPLOS_STARTER_INICIAR = new Set([
     "exemplos/autenticacao.sema",
 ]);
 export async function comandoIniciar(cwd, template, opcoes = {}) {
-    const arquivos = arquivosTemplateIniciar(template);
+    const arquivosCompletos = arquivosTemplateIniciar(template);
+    const configAncestral = await carregarConfiguracaoProjeto(cwd);
+    const subpastaGovernada = Boolean(configAncestral
+        && path.resolve(configAncestral.baseDiretorio) !== path.resolve(cwd));
+    // Em subpasta de workspace ja governado o config do template e omitido: a
+    // subpasta e registrada nos diretoriosCodigo do sema.config.json ancestral
+    // e o lookup de workspace continua subindo para o pai.
+    const arquivos = subpastaGovernada && configAncestral
+        ? arquivosCompletos.filter((arquivo) => arquivo.caminhoRelativo !== "sema.config.json")
+        : arquivosCompletos;
+    if (subpastaGovernada && configAncestral) {
+        await registrarSubpastaNoConfigAncestral(configAncestral.caminho, path.resolve(cwd));
+    }
     const planoExemplos = await planejarExemplosOficiais();
     if (!planoExemplos.origem) {
         console.error("Diretorio de exemplos oficiais nao foi encontrado no pacote da CLI.");

package/docs/ai-workflow.md

@@ -18,9 +18,9 @@ This is the minimum workflow for Codex in a local workspace.
 
 Contract edit rule: `.sema` has its own size budget. Above 300 lines, plan a split by domain/capability; above 500, do not create or edit before splitting. Do not use parte_1/parte_2 and do not force a 1:1 contract-to-file relationship; several contracts can govern the same file through `vinculos`.
 
-Closing rule: the `payload` of `sema drift --cache fresh --json` must return `sucesso:true`. If it reports `sucesso:false`, `vinculos_quebrados`, `rotas_divergentes`, or `impls_quebrados`, the task is still blocked. Passing unit tests or a cache hit do not replace fresh green drift. In 3.0.0, `ok` describes the CLI result path and never replaces a command-specific domain verdict.
+Closing rule: the `payload` of `sema drift --cache fresh --json` must return `sucesso:true`. If it reports `sucesso:false`, `vinculos_quebrados`, `rotas_divergentes`, or `impls_quebrados`, the task is still blocked. Passing unit tests or a cache hit do not replace fresh green drift. `vinculos_fora_do_escopo` is informational: the file exists in the workspace outside the configured `diretoriosCodigo`, and each entry carries a `diretorioSugerido` to add to `sema.config.json`; it does not block closure. In 3.0.0, `ok` describes the CLI result path and never replaces a command-specific domain verdict.
 
-Focused drift rule: file and module scopes plan their physical file set before cataloging. They never fall back to a whole-project walk when no safe anchor exists. All indexers and semantic-budget checks reuse the same in-memory source read; a global walk is reserved for explicit `--escopo projeto`. Code discovery is deferred until that plan exists, homonymous candidates fail as ambiguous, and configured contract origins or code roots resolving outside the workspace are rejected before enumeration. `inspecionar`, `impacto`, and `renomear-semantico` preserve the same directed boundary. Missing local dependencies make coverage partial and block success.
+Focused drift rule: file and module scopes plan their physical file set before cataloging. They never fall back to a whole-project walk when no safe anchor exists. All indexers and semantic-budget checks reuse the same in-memory source read; a global walk is reserved for explicit `--escopo projeto`. Code discovery is deferred until that plan exists, homonymous candidates fail as ambiguous, and configured contract origins or code roots resolving outside the workspace are rejected before enumeration. `inspecionar`, `impacto`, and `renomear-semantico` preserve the same directed boundary. Missing unambiguous local dependencies make coverage partial and block success. In Python, an unresolved `name` from `from module import name` is not itself a missing file after `module` resolves: it may be an exported symbol, while a real child module is still included whenever its file exists.
 
 Cache rule: a closure gate should use `sema drift <contrato> --escopo modulo --cache fresh --json`. `--cache none` executes the same analysis without persistent-cache I/O, while `--cache cache` may reuse only extraction data whose schema, workspace identity, Git HEAD, plan, configuration, contracts, member paths, and strong content digests all match. Cache objects are stored in the operating system's user-cache directory, never below the workspace. A hit is acceleration, not evidence: final links, diagnostics, score, and success are always recalculated. Corruption or an unavailable cache degrades to an in-memory calculation.
 

package/docs/commands.md

@@ -31,7 +31,7 @@ Then read every required doc returned by `docs-impacto`.
 
 ## Contract and Discovery
 
-- `sema iniciar --template <base|nestjs|fastapi|nextjs-api|nextjs-consumer|react-vite-consumer|angular-consumer|flutter-consumer|node-firebase-worker|aspnet-api|springboot-api|go-http-api|rust-axum-api|cpp-service-bridge> [--force]`: creates a new Sema project and preserves existing files by default; `--force` is the only explicit overwrite path.
+- `sema iniciar --template <base|nestjs|fastapi|nextjs-api|nextjs-consumer|react-vite-consumer|angular-consumer|flutter-consumer|node-firebase-worker|aspnet-api|springboot-api|go-http-api|rust-axum-api|cpp-service-bridge> [--force]`: creates a new Sema project and preserves existing files by default; `--force` is the only explicit overwrite path. Inside a subfolder of an already governed workspace, the subfolder is registered under `diretoriosCodigo` of the ancestral `sema.config.json` (safe write, deduplicated) instead of creating a local config; if the parent config cannot be written, the scaffold proceeds and prints the exact line to add.
 - `sema validar <arquivo-ou-pasta> --json`: validates `.sema` contracts.
 - `sema diagnosticos <arquivo.sema> --json`: details errors and warnings.
 - `sema formatar <arquivo-ou-pasta>`: formats contracts.
@@ -51,9 +51,9 @@ Then read every required doc returned by `docs-impacto`.
 - `sema verificar <arquivo-ou-pasta> --json`: runs aggregated final verification.
 - `sema finalizar-mudanca --intencao "<acao>" --doc-lida <arquivo> --json`: proves documentation reading before closure.
 
-Honest closure: unwrap drift JSON and treat its command payload as the source of truth. `payload.sucesso:false`, non-empty `payload.vinculos_quebrados`, non-empty `payload.rotas_divergentes`, or non-empty `payload.impls_quebrados` mean the change is not complete yet. Do not report "clean drift" without a green payload.
+Honest closure: unwrap drift JSON and treat its command payload as the source of truth. `payload.sucesso:false`, non-empty `payload.vinculos_quebrados`, non-empty `payload.rotas_divergentes`, or non-empty `payload.impls_quebrados` mean the change is not complete yet. Do not report "clean drift" without a green payload. `payload.vinculos_fora_do_escopo` is informational: the file exists in the workspace outside `diretoriosCodigo`, and each entry carries a `diretorioSugerido` for `sema.config.json`.
 
-Focused drift exposes its planned, declared, inferred, and missing files plus catalog visit/read metrics in `escopo_aplicado`. A missing declared file or a missing code-referenced dependency is a blocker reported as `vinculo_quebrado`; a missing inferred candidate derived from an `impl` symbol is informational under `arquivosAusentesInferidos` and never blocks an implementation that resolved. File and module scopes fail closed without a safe anchor, with homonymous implementation candidates, or with missing local dependencies; only `--escopo projeto` may walk every configured code root. Logical roots such as `src` are probed deterministically without a discovery walk. Configured contract origins and code roots are confined before enumeration, and `inspecionar`, `impacto`, and `renomear-semantico` reuse the same directed boundary without reopening arbitrary external paths.
+Focused drift exposes its planned, declared, inferred, and missing files plus catalog visit/read metrics in `escopo_aplicado`. A missing declared file or a missing unambiguous code-referenced dependency is a blocker reported as `vinculo_quebrado`; a missing inferred candidate derived from an `impl` symbol is informational under `arquivosAusentesInferidos` and never blocks an implementation that resolved. For Python `from module import name`, Sema still includes `name` when it resolves as a real submodule, but never reports the absent submodule candidate as a broken link after the parent module resolved because `name` may be a function, class, or variable. File and module scopes fail closed without a safe anchor, with homonymous implementation candidates, or with missing local dependencies; only `--escopo projeto` may walk every configured code root. Logical roots such as `src` are probed deterministically without a discovery walk. Configured contract origins and code roots are confined before enumeration, and `inspecionar`, `impacto`, and `renomear-semantico` reuse the same directed boundary without reopening arbitrary external paths.
 
 Drift analysis and cache modes are explicit:
 
@@ -156,7 +156,7 @@ Spatial model and render mode are orthogonal: `THREE_D + HEADLESS` is valid, whi
 - Do not stop after `sema compilar` if the contract target files still do not exist.
 - Do not replace `sema compilar` with `sema testar` when the contract requires generated code.
 - Do not create a Markdown report to pretend a gate ran.
-- Do not say drift passed when the unwrapped `sema drift --cache fresh --json` payload returned `sucesso:false`, a non-empty `vinculos_quebrados`, `rotas_divergentes`, or `impls_quebrados` list.
+- Do not say drift passed when the unwrapped `sema drift --cache fresh --json` payload returned `sucesso:false`, a non-empty `vinculos_quebrados`, `rotas_divergentes`, or `impls_quebrados` list. `vinculos_fora_do_escopo` entries are informational scope hints, not broken links.
 - Do not declare a UI responsive without mobile/desktop proof; horizontal scroll at 390px blocks closure.
 
 Governed code policy: keep the `SEMA-GOVERNED` marker, split large code by real responsibility, preserve contract links, and never treat a generated output directory as the final delivery.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semacode/cli",
-  "version": "3.12.1",
+  "version": "3.13.1",
   "description": "Local-first semantic governance CLI for AI agents, proven with Claude, Codex, zCode (GLM) and Kimi: contracts, drift, impact, docs gates, and code generation.",
   "type": "module",
   "icon": "logo.png",