@semacode/cli 4.1.2 → 4.2.0

package/dist/cliHelpTexto.js

@@ -25,11 +25,12 @@ 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]",
+            "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> [--janela-contexto <tokens>] [--orcamento-contexto <tokens>] [--reserva-saida <tokens>] [--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. 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",
+            "sema verificar <arquivo-ou-pasta> [--saida <dir>] [--alvo <alvo>] [--sem-cache] [--preservar-implementacao] --json",
+            "  --preservar-implementacao: somente Python base; preserva implementação local, regenera testes e ignora cache. Não comprova produção.",
             "",
             "[2] Editar projeto que já usa Sema",
             "sema inspecionar . [--drift <none|cache|fresh>] --json",
@@ -121,7 +122,7 @@ export function criarAjudaRaiz(versao) {
             "geração: sema compilar <arquivo-ou-pasta> --alvo <typescript|python|php|dart|lua|javascript|html|css|dotnet|cpp> --saida <diretorio> [--estrutura <flat|modulos|backend>] [--framework <base|nestjs|fastapi>]",
             "teste local: sema testar <arquivo.sema> --alvo <typescript|python|php|dart|lua|javascript|html|css|dotnet|cpp> --saida <diretorio-temporario> [--estrutura <flat|modulos|backend>] [--framework <base|nestjs|fastapi>]",
             "aliases nativos: cs|csharp -> dotnet; c++|cxx|cc -> cpp (CLI e sema.config.json)",
-            "verificação final: sema verificar <arquivo-ou-pasta> [--saida <diretorio-base>] [--alvo <alvo>] [--sem-cache] [--json]",
+            "verificação final: sema verificar <arquivo-ou-pasta> [--saida <diretorio-base>] [--alvo <alvo>] [--sem-cache] [--preservar-implementacao] [--json]",
             "formatação: sema formatar <arquivo-ou-pasta> [--check] [--json]",
             "author: sema author <iniciar|validar|briefing|revisar-cliches|validar-narrativa|validar-proibicoes> [arquivo] [--tema-sensivel] [--preset conto|romance|roteiro|lore|campanha] [--saida <arquivo>] [--texto <texto>] [--json]",
             "profile: sema profile validar <software|workflow|ops|game|simulation|legal|research|redacao|propostas|conversas> <arquivo-ou-pasta> [--maturidade draft|prototype|production|critical] [--preset <preset>] [--artefato <texto>|--artefato-arquivo <arquivo>] [--json]",
@@ -144,7 +145,7 @@ export function criarAjudaRaiz(versao) {
             "sema contexto-ia <arquivo.sema> [--saida <diretorio>] [--capacidade <fraca|media|forte>] [--pacote] [--json]",
             "sema sync-codex [--json]",
             "sema instalar-exemplos [--json]",
-            "sema sessao [intencao] [entrada] [--json]",
+            "sema sessao [intencao] [entrada] [--arquivo <contrato-ou-codigo>] [--janela-contexto <tokens>] [--orcamento-contexto <tokens>] [--reserva-saida <tokens>] [--salvar-perfil] [--json]",
             "sema docs-impacto --intencao <acao> [--arquivo <caminho>] [--criar-ausentes] [--completo] [--json]",
             "sema finalizar-mudanca --intencao <acao> [--arquivo <caminho>] [--doc-lida <caminho>] [--json]",
             "sema author briefing <arquivo.sema> [--json]",

package/dist/comandoSessao.d.ts

@@ -1,34 +1 @@
-export interface SessaoEnvelope {
-    comando: "sessao";
-    sucesso: boolean;
-    workspace: {
-        baseProjeto: string;
-        nomePasta: string;
-        hashContratos: string;
-        cliVersao: string;
-    };
-    frescor: {
-        fresco: boolean;
-        hashArtefato: string | null;
-        hashAtual: string;
-        sugestao: string;
-    };
-    contratos: {
-        total: number;
-        modulos: string[];
-    };
-    intencoes: {
-        intencao: string;
-        categorias: string[];
-        docsBloqueantes: string[];
-        docsRecomendadas: string[];
-    };
-    gates: {
-        drift: string;
-        validar: string;
-        verificar: string;
-        finalizar: string;
-    };
-    proximosPassos: string[];
-}
 export declare function comandoSessao(posicionais: string[], args: string[], emJson: boolean, cwd?: string): Promise<number>;

package/dist/comandoSessao.js

@@ -1,86 +1,87 @@
 // SEMA-GOVERNED: sema.produto.cli_sessao
-// Descricao: comando sessao devolve envelope compacto de abertura governada.
+// Descrição: abertura progressiva com perfil explícito, frescor e navegação limitada por orçamento.
 import path from "node:path";
 import { verificarFrescorArtefatos } from "./index.part04.js";
 import { carregarProjeto } from "./projetoCarregar.js";
+import { carregarConfiguracaoProjeto } from "./projetoConfig.js";
 import { resolverDocumentacaoObrigatoria } from "./docs.js";
+import { resolverPerfilContexto, salvarPerfilContexto, estimarRespostaTokens, PERGUNTA_CONTEXTO } from "./contextBudget.js";
+import { navegarContextoSessao } from "./sessionContext.js";
+function opcao(args, nome) {
+    const i = args.findIndex((arg) => arg === nome || arg.startsWith(`${nome}=`));
+    return i < 0 ? undefined : args[i].startsWith(`${nome}=`) ? args[i].slice(nome.length + 1) : args[i + 1];
+}
 export async function comandoSessao(posicionais, args, emJson, cwd = process.cwd()) {
-    const intencao = posicionais[0] ?? args.find((arg) => arg.startsWith("--intencao="))?.split("=")[1] ?? "";
+    const emitir = (payload, codigo = 0) => {
+        if (emJson)
+            console.log(JSON.stringify(payload));
+        else {
+            const p = payload;
+            console.log(`Sessão Sema — ${p.status ?? "consulta"}`);
+            for (const candidato of p.contexto?.candidatos ?? [])
+                console.log(`  ${candidato.contrato} — ${candidato.motivo}`);
+            for (const passo of p.proximosPassos ?? [])
+                console.log(`  → ${passo}`);
+        }
+        return codigo;
+    };
+    const intencao = posicionais[0] ?? "";
+    if (intencao.length > 2048)
+        return emitir({ comando: "sessao", sucesso: false, status: "intencao_longa", proximosPassos: ["Descreva a intenção em até 2048 caracteres e informe --arquivo para fixar o escopo."] }, 1);
     const entrada = posicionais[1];
-    const baseProjeto = entrada ? path.resolve(cwd, entrada) : cwd;
-    const contextoProjeto = await carregarProjeto(entrada, cwd, {
-        escopo: "projeto",
-        adiarDescobertaCodigo: true,
-    });
-    const pacoteCli = (await import("../package.json", { with: { type: "json" } })).default;
-    const frescor = await verificarFrescorArtefatos(contextoProjeto.baseProjeto);
-    const modulosNomes = contextoProjeto.modulosSelecionados.map((item) => item.resultado.modulo?.nome ?? path.basename(item.caminho, ".sema"));
-    let categorias = [];
-    let docsBloqueantes = [];
-    let docsRecomendadas = [];
-    if (intencao.trim()) {
-        const impacto = await resolverDocumentacaoObrigatoria({
-            baseProjeto: contextoProjeto.baseProjeto,
-            intencao,
-            arquivosAlvo: [],
-            criarAusentes: false,
+    const configuracao = await carregarConfiguracaoProjeto(entrada ? path.resolve(cwd, entrada) : cwd);
+    const base = configuracao?.baseDiretorio ?? cwd;
+    const perfil = await resolverPerfilContexto(base, args);
+    if (!perfil)
+        return emitir({
+            comando: "sessao", sucesso: true, status: "configuracao_necessaria", execucaoAutorizada: false,
+            proximosPassos: [PERGUNTA_CONTEXTO, 'Repita sema sessao "<intenção>" --janela-contexto <tokens> --salvar-perfil --json. Não infira a janela pelo modelo.'],
         });
-        categorias = impacto.categorias;
-        docsBloqueantes = impacto.leituraObrigatoria
-            .filter((doc) => doc.obrigatoriedade !== "recomendada" && doc.existe)
-            .map((doc) => doc.relativo);
-        docsRecomendadas = impacto.leituraRecomendada.map((doc) => doc.relativo);
-    }
-    const envelope = {
-        comando: "sessao",
-        sucesso: true,
-        workspace: {
-            baseProjeto: contextoProjeto.baseProjeto,
-            nomePasta: path.basename(contextoProjeto.baseProjeto),
-            hashContratos: frescor.hashAtual,
-            cliVersao: pacoteCli.version,
-        },
+    if (args.includes("--salvar-perfil"))
+        await salvarPerfilContexto(base, perfil);
+    const projeto = await carregarProjeto(entrada, cwd, { escopo: "projeto", adiarDescobertaCodigo: true });
+    const frescor = await verificarFrescorArtefatos(projeto.baseProjeto);
+    const pacoteCli = (await import("../package.json", { with: { type: "json" } })).default;
+    const arquivo = opcao(args, "--arquivo");
+    const contexto = frescor.fresco && intencao.trim() ? await navegarContextoSessao(projeto.baseProjeto, intencao, arquivo) : undefined;
+    const contrato = contexto?.candidatos.length === 1 ? contexto.candidatos[0].contrato : undefined;
+    const docs = contrato ? await resolverDocumentacaoObrigatoria({ baseProjeto: projeto.baseProjeto, intencao, arquivosAlvo: [contrato], criarAusentes: false }) : undefined;
+    const alvo = contrato ? JSON.stringify(contrato) : "<contrato>";
+    const payload = {
+        comando: "sessao", sucesso: true,
+        status: !frescor.fresco ? "indice_desatualizado" : contexto?.status ?? "intencao_necessaria",
+        execucaoAutorizada: false,
+        workspace: { baseProjeto: projeto.baseProjeto, nomePasta: path.basename(projeto.baseProjeto), hashContratos: frescor.hashAtual, cliVersao: pacoteCli.version },
         frescor,
-        contratos: {
-            total: contextoProjeto.modulosSelecionados.length,
-            modulos: modulosNomes.slice(0, 10),
-        },
-        intencoes: {
-            intencao,
-            categorias,
-            docsBloqueantes,
-            docsRecomendadas,
-        },
+        perfil,
+        contexto: contexto ? { ...contexto, candidatosOmitidos: 0 } : undefined,
+        intencoes: { intencao, docsBloqueantes: docs?.leituraObrigatoria.map((doc) => doc.relativo) ?? [], leituraPendente: true },
         gates: {
-            drift: "sema drift . --escopo projeto --cache fresh --json",
-            validar: "sema validar contratos --json",
-            verificar: "sema verificar contratos --alvo typescript --json",
-            finalizar: 'sema finalizar-mudanca --intencao "<intencao>" --doc-lida <doc> --json',
+            drift: `sema drift ${alvo} --cache fresh --json`,
+            validar: `sema validar ${alvo} --json`,
+            verificar: `sema verificar ${alvo} --alvo <alvo> --json`,
+            finalizar: `sema finalizar-mudanca --intencao "<intenção>" --arquivo ${alvo} --doc-lida <doc> --json`,
         },
-        proximosPassos: [
-            ...(!frescor.fresco ? ["Artefatos stale detectados — rode sema sync-codex --json antes de agir"] : []),
-            ...(docsBloqueantes.length > 0 ? [`Leia antes de agir: ${docsBloqueantes.slice(0, 5).join(", ")}`] : []),
-            ...(intencao.trim() ? ["Siga o protocolo AGENTS.md passo a passo"] : ["Declare --intencao para receber gates especificos"]),
-        ],
+        proximosPassos: !frescor.fresco ? ["Rode sema sync-codex --json e repita a sessão."]
+            : contrato ? [`Leia ${contrato}; consulte docs-impacto com esse --arquivo para motivos e dependências. Depois inspecione apenas o código vinculado.`, "Referências do índice são navegação. Confirme regras completas e gates antes de agir."]
+                : ["Informe uma intenção específica ou --arquivo <contrato-ou-código> para resolver o escopo. Não edite enquanto houver ambiguidade."],
+        orcamento: { metodo: "chars_div_4", tokensEstimadosResposta: 0, limiteTokens: perfil.orcamentoTokens, contagemExata: false, contextoDaConversaMedido: false },
     };
-    if (emJson) {
-        console.log(JSON.stringify(envelope, null, 2));
-        return 0;
-    }
-    console.log(`Sessao Sema — ${envelope.workspace.nomePasta}`);
-    console.log(`  Hash contratos: ${envelope.workspace.hashContratos}`);
-    console.log(`  CLI: ${envelope.workspace.cliVersao}`);
-    console.log(`  Frescor: ${frescor.fresco ? "fresco" : "STALE"} ${!frescor.fresco ? `(${frescor.sugestao})` : ""}`);
-    console.log(`  Contratos: ${envelope.contratos.total}`);
-    if (intencao) {
-        console.log(`  Intencao: ${intencao}`);
-        console.log(`  Categorias: ${categorias.join(", ")}`);
-        console.log(`  Docs bloqueantes: ${docsBloqueantes.length}`);
-        console.log(`  Docs recomendadas: ${docsRecomendadas.length}`);
+    while (estimarRespostaTokens(payload) > perfil.orcamentoTokens && payload.contexto?.candidatos.length) {
+        payload.contexto.candidatos.pop();
+        payload.contexto.candidatosOmitidos++;
     }
-    for (const passo of envelope.proximosPassos) {
-        console.log(`  → ${passo}`);
+    if (payload.contexto?.candidatosOmitidos) {
+        payload.status = "refinar_escopo";
+        payload.proximosPassos = ["Há candidatos omitidos pelo orçamento. Refine a intenção ou informe --arquivo; não interprete omissão como ausência de dependência."];
     }
-    return 0;
+    for (let i = 0; i < 3; i++)
+        payload.orcamento.tokensEstimadosResposta = estimarRespostaTokens(payload);
+    if (payload.orcamento.tokensEstimadosResposta > perfil.orcamentoTokens)
+        return emitir({
+            comando: "sessao", sucesso: false, status: "orcamento_insuficiente", execucaoAutorizada: false,
+            proximosPassos: ["Metadados e leituras bloqueantes excedem o orçamento. Refine --arquivo ou ajuste --orcamento-contexto; nenhuma leitura foi dispensada."],
+        }, 1);
+    return emitir(payload);
 }
 //# sourceMappingURL=comandoSessao.js.map

package/dist/contextBudget.d.ts

@@ -0,0 +1,15 @@
+export declare const ARQUIVO_PERFIL_CONTEXTO = ".sema/contexto-ia.json";
+export declare const OPCOES_CONTEXTO: readonly ["--janela-contexto", "--orcamento-contexto", "--reserva-saida"];
+export declare const PERGUNTA_CONTEXTO = "Qual \u00E9 a janela de contexto efetivamente configurada para esta IA, em tokens?";
+export interface PerfilContexto {
+    schema: "sema.agent-context-profile/v1";
+    janelaTokens: number;
+    orcamentoTokens: number;
+    reservaSaidaTokens: number;
+}
+export declare function criarPerfilContexto(janela: number, orcamento?: number, reserva?: number): PerfilContexto;
+export declare function numeroOpcaoContexto(args: readonly string[], nome: string): number | undefined;
+export declare function lerPerfilContexto(base: string): Promise<PerfilContexto | undefined>;
+export declare function resolverPerfilContexto(base: string, args: readonly string[]): Promise<PerfilContexto | undefined>;
+export declare function salvarPerfilContexto(base: string, perfil: PerfilContexto): Promise<void>;
+export declare function estimarRespostaTokens(payload: unknown): number;

package/dist/contextBudget.js

@@ -0,0 +1,64 @@
+// SEMA-GOVERNED: sema.produto.cli_sessao
+// Descrição: perfil local explícito e orçamento estimado de contexto, sem inferir capacidade pelo modelo.
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { escreverArquivoWorkspaceSeguro, validarDestinosEscritaWorkspace } from "./workspaceWrite.js";
+export const ARQUIVO_PERFIL_CONTEXTO = ".sema/contexto-ia.json";
+export const OPCOES_CONTEXTO = ["--janela-contexto", "--orcamento-contexto", "--reserva-saida"];
+export const PERGUNTA_CONTEXTO = "Qual é a janela de contexto efetivamente configurada para esta IA, em tokens?";
+export function criarPerfilContexto(janela, orcamento, reserva) {
+    const perfil = {
+        schema: "sema.agent-context-profile/v1",
+        janelaTokens: janela,
+        orcamentoTokens: orcamento ?? Math.min(4096, Math.floor(janela / 8)),
+        reservaSaidaTokens: reserva ?? Math.min(4096, Math.floor(janela / 4)),
+    };
+    if (![perfil.janelaTokens, perfil.orcamentoTokens, perfil.reservaSaidaTokens].every(Number.isSafeInteger)
+        || janela < 4096 || perfil.orcamentoTokens < 512 || perfil.reservaSaidaTokens < 256
+        || perfil.orcamentoTokens + perfil.reservaSaidaTokens > janela - 1024) {
+        throw new Error("Perfil inválido: janela >= 4096, orçamento >= 512, reserva >= 256 e pelo menos 1024 tokens livres para instruções e conversa.");
+    }
+    return perfil;
+}
+export function numeroOpcaoContexto(args, nome) {
+    const indice = args.findIndex((arg) => arg === nome || arg.startsWith(`${nome}=`));
+    if (indice < 0)
+        return undefined;
+    const raw = args[indice].startsWith(`${nome}=`) ? args[indice].slice(nome.length + 1) : args[indice + 1];
+    if (!raw || !/^[1-9]\d*$/u.test(raw) || !Number.isSafeInteger(Number(raw))) {
+        throw new Error(`${nome} exige um inteiro positivo em tokens.`);
+    }
+    return Number(raw);
+}
+export async function lerPerfilContexto(base) {
+    const [destino] = await validarDestinosEscritaWorkspace(base, [ARQUIVO_PERFIL_CONTEXTO]);
+    if (!destino?.existe)
+        return undefined;
+    const perfil = JSON.parse(await readFile(path.join(base, ARQUIVO_PERFIL_CONTEXTO), "utf8"));
+    if (perfil.schema !== "sema.agent-context-profile/v1")
+        throw new Error("Schema do perfil de contexto inválido.");
+    return criarPerfilContexto(perfil.janelaTokens, perfil.orcamentoTokens, perfil.reservaSaidaTokens);
+}
+export async function resolverPerfilContexto(base, args) {
+    const janela = numeroOpcaoContexto(args, "--janela-contexto");
+    const orcamento = numeroOpcaoContexto(args, "--orcamento-contexto");
+    const reserva = numeroOpcaoContexto(args, "--reserva-saida");
+    const salvo = await lerPerfilContexto(base);
+    if (janela !== undefined)
+        return criarPerfilContexto(janela, orcamento, reserva);
+    if (!salvo) {
+        if (orcamento !== undefined || reserva !== undefined)
+            throw new Error("Informe --janela-contexto antes de ajustar o orçamento.");
+        return undefined;
+    }
+    return criarPerfilContexto(salvo.janelaTokens, orcamento ?? salvo.orcamentoTokens, reserva ?? salvo.reservaSaidaTokens);
+}
+export async function salvarPerfilContexto(base, perfil) {
+    await escreverArquivoWorkspaceSeguro(base, ARQUIVO_PERFIL_CONTEXTO, `${JSON.stringify(perfil, null, 2)}\n`, { sobrescrever: true });
+}
+// Reserva conservadora para o envelope público e a indentação que o adaptador acrescenta.
+export function estimarRespostaTokens(payload) {
+    const envelope = { schemaVersion: "sema.cli.result/v1", ok: true, kind: "SUCCESS", command: "sessao", code: "CLI_SUCCESS", message: null, exitCode: 0, payload };
+    return Math.ceil((JSON.stringify(envelope, null, 2).length + 256) / 4);
+}
+//# sourceMappingURL=contextBudget.js.map

package/dist/docs.part01.js

@@ -309,7 +309,6 @@ export function resumoConteudo(conteudo) {
 export async function adicionarDocsRaizExistentes(baseProjeto, registrar) {
     const docsRaiz = [
         { relativo: "AGENTS.md", tipo: "raiz", motivo: "regras obrigatorias do agente no projeto" },
-        { relativo: "SEMA_INDEX.json", tipo: "raiz", motivo: "indice IA-first do projeto" },
         { relativo: "README.md", tipo: "raiz", motivo: "visao geral publica do projeto" },
         { relativo: "docs/README.md", tipo: "documentacao", motivo: "indice de documentacao" },
     ];

package/dist/docs.part02.js

@@ -2,29 +2,12 @@
 // Descricao: resolve e cria documentacao obrigatoria sem escapar do workspace nem gravar lotes parcialmente.
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { resolverRelacoesDocumentais } from "./docsRelations.js";
 import { emitirDiagnosticosArquivosOrcamento } from "./driftOrcamento.js";
 import { escreverArquivoWorkspaceSeguro, validarDestinosEscritaWorkspace, } from "./workspaceWrite.js";
-import { REGRAS_DOCUMENTACAO, adicionarDocsRaizExistentes, adicionarReadmesDeArquivos, caminhoEstaDentro, caminhoExiste, criarTemplateDoc, documentoPareceTemplateCriadoPelaSema, documentoTemSubstancia, inferirCategorias, listarArquivosRecursivo, normalizarRelativo, normalizarTexto, resumoConteudo, termosRelacionamentoContratos } from "./docs.part01.js";
+import { REGRAS_DOCUMENTACAO, adicionarDocsRaizExistentes, adicionarReadmesDeArquivos, caminhoEstaDentro, caminhoExiste, criarTemplateDoc, documentoPareceTemplateCriadoPelaSema, documentoTemSubstancia, inferirCategorias, normalizarRelativo, resumoConteudo } from "./docs.part01.js";
 export async function adicionarContratosRelacionados(baseProjeto, intencao, arquivosAlvo, registrar) {
-    const pastaContratos = path.join(baseProjeto, "contratos");
-    if (!(await caminhoExiste(pastaContratos))) {
-        return;
-    }
-    const termos = termosRelacionamentoContratos(intencao, arquivosAlvo);
-    const arquivos = (await listarArquivosRecursivo(pastaContratos)).filter((arquivo) => arquivo.endsWith(".sema"));
-    for (const arquivo of arquivos) {
-        const relativo = normalizarRelativo(path.relative(baseProjeto, arquivo));
-        const nome = normalizarTexto(relativo);
-        const relacionado = termos.some((parte) => nome.includes(parte));
-        if (relacionado) {
-            registrar({
-                relativo,
-                tipo: "contrato",
-                motivo: "contrato Sema relacionado a intencao declarada",
-                permitirCriacao: false,
-            });
-        }
-    }
+    await resolverRelacoesDocumentais(baseProjeto, intencao, arquivosAlvo, registrar);
 }
 export function criarRegistrador(baseProjeto) {
     const docs = [];
@@ -34,6 +17,11 @@ export function criarRegistrador(baseProjeto) {
         registrar(doc) {
             const relativo = normalizarRelativo(doc.relativo);
             const absoluto = path.resolve(baseProjeto, relativo);
+            if (vistos.has(relativo) && doc.obrigatoriedade !== "recomendada") {
+                const anterior = docs.find((item) => item.relativo === relativo);
+                if (anterior)
+                    Object.assign(anterior, doc, { relativo, obrigatoriedade: "bloqueante" });
+            }
             if (!caminhoEstaDentro(baseProjeto, absoluto) || vistos.has(relativo)) {
                 return;
             }
@@ -86,7 +74,7 @@ export async function resolverDocumentacaoObrigatoria(opcoes) {
             existe,
             criado,
             criacaoAutomatica: doc.permitirCriacao,
-            obrigatorio: true,
+            obrigatorio: doc.obrigatoriedade !== "recomendada",
             obrigatoriedade: doc.obrigatoriedade ?? "bloqueante",
             template: existe ? undefined : template,
         };
@@ -100,7 +88,7 @@ export async function resolverDocumentacaoObrigatoria(opcoes) {
         }
         leituraObrigatoria.push(item);
     }
-    const docsAusentes = leituraObrigatoria.filter((doc) => !doc.existe);
+    const docsAusentes = leituraObrigatoria.filter((doc) => !doc.existe && doc.obrigatoriedade !== "recomendada");
     const docsCriadas = leituraObrigatoria.filter((doc) => doc.criado);
     const bloqueios = docsAusentes.filter((doc) => doc.obrigatoriedade !== "recomendada").map((doc) => ({
         tipo: "documentacao_ausente",
@@ -116,7 +104,7 @@ export async function resolverDocumentacaoObrigatoria(opcoes) {
         intencao,
         categorias,
         arquivosAlvo,
-        leituraObrigatoria,
+        leituraObrigatoria: leituraObrigatoria.filter((doc) => doc.obrigatoriedade !== "recomendada"),
         docsAusentes,
         docsCriadas,
         leituraRecomendada: leituraObrigatoria

package/dist/docsRelations.d.ts

@@ -0,0 +1,2 @@
+import { type DocumentoPlanejado } from "./docs.part01.js";
+export declare function resolverRelacoesDocumentais(base: string, intencao: string, alvos: string[], registrar: (doc: DocumentoPlanejado) => void): Promise<void>;

package/dist/docsRelations.js

@@ -0,0 +1,83 @@
+// SEMA-GOVERNED: sema.produto.governanca_ia.documentacao
+// Descrição: resolve contrato exato, vínculos e dependências declaradas; palavras são apenas recomendações.
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { tokenizar, parsear, listarCandidatosUseRelativo } from "@sema/nucleo";
+import { validarDestinosEscritaWorkspace } from "./workspaceWrite.js";
+import { caminhoExiste, caminhoEstaDentro, listarArquivosRecursivo, normalizarRelativo, normalizarTexto, termosRelacionamentoContratos } from "./docs.part01.js";
+export async function resolverRelacoesDocumentais(base, intencao, alvos, registrar) {
+    const relativo = (p) => {
+        const absoluto = path.resolve(base, p);
+        if (!caminhoEstaDentro(base, absoluto))
+            throw new Error("Referência documental fora do workspace.");
+        return normalizarRelativo(path.relative(base, absoluto));
+    };
+    const explicitos = alvos.map(relativo);
+    const pasta = path.join(base, "contratos");
+    const caminhos = await caminhoExiste(pasta) ? (await listarArquivosRecursivo(pasta, Number.POSITIVE_INFINITY)).filter((p) => p.endsWith(".sema")).map(relativo) : [];
+    const todos = [...new Set([...caminhos, ...explicitos.filter((p) => p.endsWith(".sema"))])];
+    await validarDestinosEscritaWorkspace(base, todos);
+    const catalogo = new Map();
+    for (const p of todos) {
+        if (!await caminhoExiste(path.join(base, p)))
+            continue;
+        const lexer = tokenizar(await readFile(path.join(base, p), "utf8"), p);
+        const parser = parsear(lexer.tokens);
+        if (parser.modulo && lexer.diagnosticos.length === 0 && parser.diagnosticos.length === 0)
+            catalogo.set(p, parser.modulo);
+    }
+    const fila = explicitos.filter((p) => p.endsWith(".sema"))
+        .map((arquivo) => ({ arquivo, motivo: "Contrato informado explicitamente em --arquivo" }));
+    for (const [arquivo, modulo] of catalogo) {
+        const donos = [modulo, ...modulo.tasks, ...modulo.routes, ...modulo.flows];
+        for (const dono of donos) {
+            for (const campo of dono.vinculos?.campos ?? []) {
+                if (campo.nome !== "arquivo")
+                    continue;
+                const vinculo = relativo(campo.valor.replace(/^["']|["']$/g, ""));
+                if (explicitos.includes(vinculo))
+                    fila.push({ arquivo, motivo: `Vínculo declarado em ${modulo.nome}: ${vinculo}` });
+            }
+        }
+    }
+    const vistos = new Set();
+    for (let i = 0; i < fila.length; i++) {
+        const item = fila[i];
+        if (vistos.has(item.arquivo))
+            continue;
+        vistos.add(item.arquivo);
+        registrar({ relativo: item.arquivo, tipo: "contrato", motivo: item.motivo, permitirCriacao: false });
+        const modulo = catalogo.get(item.arquivo);
+        if (!modulo) {
+            if (await caminhoExiste(path.join(base, item.arquivo)))
+                throw new Error(`Contrato inválido: ${item.arquivo}. Rode sema validar.`);
+            continue; // O resolvedor público transforma o contrato ausente em bloqueio.
+        }
+        for (const use of modulo.uses.filter((u) => u.origem === "sema")) {
+            let encontrados = [];
+            for (const nome of [use.caminho, ...listarCandidatosUseRelativo(modulo.nome, use.caminho)]) {
+                encontrados = [...catalogo].filter(([, m]) => m.nome === nome);
+                if (encontrados.length)
+                    break;
+            }
+            if (encontrados.length !== 1)
+                throw new Error(`Dependência use ${use.caminho} de ${item.arquivo} ausente ou ambígua. Rode sema validar.`);
+            fila.push({ arquivo: encontrados[0][0], motivo: `Dependência use ${use.caminho} declarada em ${item.arquivo}` });
+        }
+        for (const campo of modulo.docs?.campos ?? []) {
+            if (campo.nome !== "arquivo")
+                continue;
+            const doc = relativo(campo.valor.replace(/^["']|["']$/g, ""));
+            const motivo = `Referência docs.arquivo declarada em ${item.arquivo}`;
+            registrar({ relativo: doc, tipo: doc.endsWith(".sema") ? "contrato" : "documentacao", motivo, permitirCriacao: false, obrigatoriedade: "recomendada" });
+        }
+    }
+    // Arquivo explícito fixa o escopo; não acrescentar contratos por palavras genéricas.
+    if (explicitos.length > 0)
+        return;
+    const termos = termosRelacionamentoContratos(intencao, []);
+    const sugestoes = [...catalogo].filter(([arquivo]) => termos.some((t) => normalizarTexto(path.basename(arquivo, ".sema")).includes(t))).slice(0, 8);
+    for (const [arquivo] of sugestoes)
+        registrar({ relativo: arquivo, tipo: "contrato", motivo: "Sugestão por intenção; confirme o contrato usando --arquivo", permitirCriacao: false, obrigatoriedade: "recomendada" });
+}
+//# sourceMappingURL=docsRelations.js.map

package/dist/geracaoCore.d.ts

@@ -18,7 +18,7 @@ export interface ResumoAlvoVerificacao {
     estrutura: EstruturaSaida;
     testesExecutados: boolean;
     origem?: "executado" | "cache";
-    tipoEvidencia?: "andaime_demonstrativo";
+    tipoEvidencia?: "andaime_demonstrativo" | "implementacao_local_preservada";
     implementacaoExternaExecutada?: boolean;
 }
 export interface ResumoModuloVerificacao {

package/dist/index.part07.d.ts

@@ -3,6 +3,7 @@ import type { EstruturaSaida } from "./tipos.js";
 export interface OpcoesVerificar {
     alvo?: string;
     semCache?: boolean;
+    preservarImplementacao?: boolean;
 }
 export declare function alvosSuportadosPelaStack(fontesLegado: string[] | undefined): AlvoGeracao[] | undefined;
 export declare function avisoEscopoStackVerificacao(fontesLegado: string[] | undefined, alvosEfetivos: AlvoGeracao[]): string | undefined;