@semacode/cli 4.1.2 → 4.2.0

package/dist/index.part07.js

@@ -6,6 +6,7 @@ import pacoteCli from "../package.json" with { type: "json" };
 import { compilarCodigo, formatarDiagnosticos, lerArquivoTexto, temErros, } from "@sema/nucleo";
 import { carregarProjeto, resolverAlvosVerificacao, } from "./projeto.js";
 import { SCHEMA_CACHE_VERIFICACAO, calcularChaveVerificacao, carregarCacheVerificacao, gravarCacheVerificacao, } from "./verificacaoCache.js";
+import { erroModoPreservacao, prepararImplementacaoPythonLocal, evidenciaPython } from "./verificacaoPythonLocal.js";
 const FONTES_POR_ALVO_SUPORTADO = {
     typescript: ["typescript", "javascript"],
     javascript: ["typescript", "javascript"],
@@ -210,7 +211,7 @@ export function imprimirResumoVerificacao(resumos) {
             totalArquivos += alvo.arquivosGerados;
             totalTestes += alvo.quantidadeTestes;
             totalAlvos += 1;
-            console.log(`  alvo=${alvo.alvo} framework=${alvo.framework} estrutura=${alvo.estrutura} status=${alvo.sucesso ? "ok" : "falhou"} arquivos=${alvo.arquivosGerados} testes=${alvo.quantidadeTestes}${alvo.testesExecutados ? "" : " (skip)"} saida=${alvo.pastaSaida}`);
+            console.log(`  alvo=${alvo.alvo} framework=${alvo.framework} estrutura=${alvo.estrutura} status=${alvo.sucesso ? "ok" : "falhou"} arquivos=${alvo.arquivosGerados} testes=${alvo.quantidadeTestes}${alvo.testesExecutados ? "" : " (skip)"}${alvo.tipoEvidencia ? ` evidencia=${alvo.tipoEvidencia} (não comprova produção)` : ""} saida=${alvo.pastaSaida}`);
         }
     }
     console.log(`Totais: modulos=${resumos.length} alvos=${totalAlvos} arquivos=${totalArquivos} testes=${totalTestes}`);
@@ -240,6 +241,11 @@ export async function comandoVerificar(entrada, baseSaida, cwd = process.cwd(),
         ...resolverConfiguracaoVerificacaoPorAlvo(alvo, contextoProjeto.configCarregada),
     }));
     const incompatibilidade = configuracoesAlvo.find((item) => item.incompatibilidade);
+    const erroPreservacao = erroModoPreservacao(opcoes.preservarImplementacao, configuracoesAlvo);
+    if (erroPreservacao) {
+        console.error(erroPreservacao);
+        return 1;
+    }
     if (incompatibilidade?.incompatibilidade) {
         console.error(incompatibilidade.incompatibilidade);
         return 1;
@@ -272,7 +278,7 @@ export async function comandoVerificar(entrada, baseSaida, cwd = process.cwd(),
                 estrutura,
                 conteudoContrato,
             });
-            const emCache = opcoes.semCache ? undefined : await carregarCacheVerificacao(chave, pastaAlvo);
+            const emCache = opcoes.semCache || opcoes.preservarImplementacao ? undefined : await carregarCacheVerificacao(chave, pastaAlvo);
             if (emCache) {
                 resumoModulo.alvos.push({
                     alvo,
@@ -294,21 +300,27 @@ export async function comandoVerificar(entrada, baseSaida, cwd = process.cwd(),
                 continue;
             }
             const arquivos = aplicarEstruturaSaida(gerarArquivosPorAlvo(ir, alvo, framework), ir, estrutura);
-            const escrita = await escreverArquivos(pastaAlvo, arquivos, { artefatoGerado: true });
+            const preparacao = opcoes.preservarImplementacao ? await prepararImplementacaoPythonLocal(pastaAlvo, arquivos) : { arquivosParaEscrita: arquivos };
+            if (preparacao.erro) {
+                console.error(preparacao.erro);
+                return 1;
+            }
+            const escrita = await escreverArquivos(pastaAlvo, preparacao.arquivosParaEscrita, { artefatoGerado: true });
             artefatosGeradosAcimaDoLimite.push(...escrita.artefatosGeradosAcimaDoLimite);
             const { execucao, testesExecutados } = executarTestesParaVerificacao(alvo, pastaAlvo, arquivos, framework);
-            await gravarCacheVerificacao({
-                schemaVersion: SCHEMA_CACHE_VERIFICACAO,
-                chave,
-                versaoCli: pacoteCli.version,
-                alvo,
-                modulo: ir.nome,
-                sucesso: execucao.codigoSaida === 0,
-                quantidadeTestes: execucao.quantidadeTestes,
-                testesExecutados,
-                arquivosGerados: arquivos.map((arquivo) => arquivo.caminhoRelativo),
-                geradoEm: new Date().toISOString(),
-            });
+            if (!opcoes.preservarImplementacao)
+                await gravarCacheVerificacao({
+                    schemaVersion: SCHEMA_CACHE_VERIFICACAO,
+                    chave,
+                    versaoCli: pacoteCli.version,
+                    alvo,
+                    modulo: ir.nome,
+                    sucesso: execucao.codigoSaida === 0,
+                    quantidadeTestes: execucao.quantidadeTestes,
+                    testesExecutados,
+                    arquivosGerados: arquivos.map((arquivo) => arquivo.caminhoRelativo),
+                    geradoEm: new Date().toISOString(),
+                });
             resumoModulo.alvos.push({
                 alvo,
                 arquivosGerados: arquivos.length,
@@ -319,7 +331,7 @@ export async function comandoVerificar(entrada, baseSaida, cwd = process.cwd(),
                 estrutura,
                 testesExecutados,
                 origem: "executado",
-                ...(alvo === "python" ? { tipoEvidencia: "andaime_demonstrativo", implementacaoExternaExecutada: false } : {}),
+                ...(alvo === "python" ? evidenciaPython(opcoes.preservarImplementacao) : {}),
             });
             if (execucao.codigoSaida !== 0) {
                 imprimirResumoVerificacao([...resumos, resumoModulo]);
@@ -372,6 +384,11 @@ export async function comandoVerificarJson(entrada, baseSaida, cwd = process.cwd
         ...resolverConfiguracaoVerificacaoPorAlvo(alvo, contextoProjeto.configCarregada),
     }));
     const incompatibilidade = configuracoesAlvo.find((item) => item.incompatibilidade);
+    const erroPreservacao = erroModoPreservacao(opcoes.preservarImplementacao, configuracoesAlvo);
+    if (erroPreservacao) {
+        console.log(JSON.stringify({ comando: "verificar", sucesso: false, erro: erroPreservacao, modulos: [], totais: { modulos: 0, alvos: 0, arquivos: 0, testes: 0 } }));
+        return 1;
+    }
     if (incompatibilidade?.incompatibilidade) {
         console.log(JSON.stringify({
             comando: "verificar",
@@ -418,7 +435,7 @@ export async function comandoVerificarJson(entrada, baseSaida, cwd = process.cwd
                 estrutura,
                 conteudoContrato,
             });
-            const emCache = opcoes.semCache ? undefined : await carregarCacheVerificacao(chave, pastaAlvo);
+            const emCache = opcoes.semCache || opcoes.preservarImplementacao ? undefined : await carregarCacheVerificacao(chave, pastaAlvo);
             if (emCache) {
                 resumoModulo.alvos.push({
                     alvo,
@@ -439,21 +456,27 @@ export async function comandoVerificarJson(entrada, baseSaida, cwd = process.cwd
                 continue;
             }
             const arquivos = aplicarEstruturaSaida(gerarArquivosPorAlvo(ir, alvo, framework), ir, estrutura);
-            const escrita = await escreverArquivos(pastaAlvo, arquivos, { artefatoGerado: true });
+            const preparacao = opcoes.preservarImplementacao ? await prepararImplementacaoPythonLocal(pastaAlvo, arquivos) : { arquivosParaEscrita: arquivos };
+            if (preparacao.erro) {
+                console.log(JSON.stringify({ comando: "verificar", sucesso: false, erro: preparacao.erro, modulos: resumos, totais: { modulos: resumos.length, alvos: 0, arquivos: 0, testes: 0 } }));
+                return 1;
+            }
+            const escrita = await escreverArquivos(pastaAlvo, preparacao.arquivosParaEscrita, { artefatoGerado: true });
             artefatosGeradosAcimaDoLimite.push(...escrita.artefatosGeradosAcimaDoLimite);
             const { execucao, testesExecutados } = executarTestesParaVerificacao(alvo, pastaAlvo, arquivos, framework, true);
-            await gravarCacheVerificacao({
-                schemaVersion: SCHEMA_CACHE_VERIFICACAO,
-                chave,
-                versaoCli: pacoteCli.version,
-                alvo,
-                modulo: ir.nome,
-                sucesso: execucao.codigoSaida === 0,
-                quantidadeTestes: execucao.quantidadeTestes,
-                testesExecutados,
-                arquivosGerados: arquivos.map((arquivo) => arquivo.caminhoRelativo),
-                geradoEm: new Date().toISOString(),
-            });
+            if (!opcoes.preservarImplementacao)
+                await gravarCacheVerificacao({
+                    schemaVersion: SCHEMA_CACHE_VERIFICACAO,
+                    chave,
+                    versaoCli: pacoteCli.version,
+                    alvo,
+                    modulo: ir.nome,
+                    sucesso: execucao.codigoSaida === 0,
+                    quantidadeTestes: execucao.quantidadeTestes,
+                    testesExecutados,
+                    arquivosGerados: arquivos.map((arquivo) => arquivo.caminhoRelativo),
+                    geradoEm: new Date().toISOString(),
+                });
             resumoModulo.alvos.push({
                 alvo,
                 arquivosGerados: arquivos.length,
@@ -464,7 +487,7 @@ export async function comandoVerificarJson(entrada, baseSaida, cwd = process.cwd
                 estrutura,
                 testesExecutados,
                 origem: "executado",
-                ...(alvo === "python" ? { tipoEvidencia: "andaime_demonstrativo", implementacaoExternaExecutada: false } : {}),
+                ...(alvo === "python" ? evidenciaPython(opcoes.preservarImplementacao) : {}),
             });
             resumoModulo.saidaTestes.push({ alvo, stdout: execucao.saidaPadrao, stderr: execucao.saidaErro });
             if (execucao.codigoSaida !== 0) {

package/dist/index.part08.js

@@ -34,7 +34,7 @@ export async function principal() {
     let codigoSaida = 0;
     switch (comando) {
         case "iniciar":
-            codigoSaida = await comandoIniciar(cwd, normalizarTemplateIniciar(obterOpcao(resto, "--template")), { force: possuiFlag(resto, "--force"), exemplosCompletos: possuiFlag(resto, "--com-exemplos") });
+            codigoSaida = await comandoIniciar(cwd, normalizarTemplateIniciar(obterOpcao(resto, "--template")), { force: possuiFlag(resto, "--force"), exemplosCompletos: possuiFlag(resto, "--com-exemplos"), contextoArgs: resto });
             break;
         case "sessao": {
             const { comandoSessao } = await import("./comandoSessao.js");
@@ -105,8 +105,8 @@ export async function principal() {
             break;
         case "verificar":
             codigoSaida = possuiFlag(resto, "--json")
-                ? await comandoVerificarJson(posicionais[0], resolverSaidaPadrao(obterOpcao(resto, "--saida", "./.tmp/sema-verificar"), "typescript", await carregarConfiguracaoProjeto(posicionais[0] ? path.resolve(cwd, posicionais[0]) : cwd)), cwd, { alvo: obterOpcao(resto, "--alvo"), semCache: possuiFlag(resto, "--sem-cache") })
-                : await comandoVerificar(posicionais[0], resolverSaidaPadrao(obterOpcao(resto, "--saida", "./.tmp/sema-verificar"), "typescript", await carregarConfiguracaoProjeto(posicionais[0] ? path.resolve(cwd, posicionais[0]) : cwd)), cwd, { alvo: obterOpcao(resto, "--alvo"), semCache: possuiFlag(resto, "--sem-cache") });
+                ? await comandoVerificarJson(posicionais[0], resolverSaidaPadrao(obterOpcao(resto, "--saida", "./.tmp/sema-verificar"), "typescript", await carregarConfiguracaoProjeto(posicionais[0] ? path.resolve(cwd, posicionais[0]) : cwd)), cwd, { alvo: obterOpcao(resto, "--alvo"), semCache: possuiFlag(resto, "--sem-cache"), preservarImplementacao: possuiFlag(resto, "--preservar-implementacao") })
+                : await comandoVerificar(posicionais[0], resolverSaidaPadrao(obterOpcao(resto, "--saida", "./.tmp/sema-verificar"), "typescript", await carregarConfiguracaoProjeto(posicionais[0] ? path.resolve(cwd, posicionais[0]) : cwd)), cwd, { alvo: obterOpcao(resto, "--alvo"), semCache: possuiFlag(resto, "--sem-cache"), preservarImplementacao: possuiFlag(resto, "--preservar-implementacao") });
             break;
         case "inspecionar":
             codigoSaida = await comandoInspecionar(posicionais[0], possuiFlag(resto, "--json"), cwd, resto);

package/dist/indexPack.d.ts

@@ -50,5 +50,6 @@ export declare function selecionarIndiceContexto(input: {
     mode?: string;
     drift?: string;
     sourceIndexChars?: number;
+    maximoModulos?: number;
 }): IndexPack;
 export {};

package/dist/indexPack.js

@@ -84,7 +84,7 @@ export function selecionarIndiceContexto(input) {
         .map((modulo) => compactarModulo(modulo, requestTokens, projetarResumoInteiro))
         .filter((item) => item !== null)
         .sort((a, b) => b.relevanceScore - a.relevanceScore || a.module.localeCompare(b.module, "pt-BR"))
-        .slice(0, projetarResumoInteiro ? input.modulos.length : 8);
+        .slice(0, input.maximoModulos ?? (projetarResumoInteiro ? input.modulos.length : 8));
     const base = {
         schema: "sema.ai.index-pack/v1",
         selection,

package/dist/initCommand.d.ts

@@ -2,5 +2,6 @@ import { type TemplateIniciar } from "./initTemplatesBase.js";
 export declare function comandoIniciar(cwd: string, template: TemplateIniciar, opcoes?: {
     force?: boolean;
     exemplosCompletos?: boolean;
+    contextoArgs?: string[];
 }): Promise<number>;
 export declare function comandoInstalarExemplos(emJson: boolean): Promise<number>;

package/dist/initCommand.js

@@ -1,5 +1,6 @@
 // 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 { resolverPerfilContexto, salvarPerfilContexto, ARQUIVO_PERFIL_CONTEXTO, PERGUNTA_CONTEXTO } from "./contextBudget.js";
 import * as fs from "node:fs";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
@@ -57,8 +58,14 @@ const EXEMPLOS_STARTER_INICIAR = new Set([
     "exemplos/autenticacao.sema",
 ]);
 export async function comandoIniciar(cwd, template, opcoes = {}) {
-    const arquivosCompletos = arquivosTemplateIniciar(template);
     const configAncestral = await carregarConfiguracaoProjeto(cwd);
+    const basePerfil = configAncestral?.baseDiretorio ?? cwd;
+    const perfilContexto = await resolverPerfilContexto(basePerfil, opcoes.contextoArgs ?? []);
+    if (!perfilContexto) {
+        console.log(JSON.stringify({ comando: "iniciar", sucesso: false, status: "configuracao_necessaria", pergunta: PERGUNTA_CONTEXTO, proximoPasso: "Repita iniciar com --janela-contexto <tokens>; nenhum arquivo foi criado." }));
+        return 1;
+    }
+    const arquivosCompletos = arquivosTemplateIniciar(template);
     const subpastaGovernada = Boolean(configAncestral
         && path.resolve(configAncestral.baseDiretorio) !== path.resolve(cwd));
     // Em subpasta de workspace ja governado o config do template e omitido: a
@@ -84,6 +91,7 @@ export async function comandoIniciar(cwd, template, opcoes = {}) {
     ]);
     const caminhosTemplate = new Set(arquivos.map((arquivo) => arquivo.caminhoRelativo));
     const destinos = await validarDestinosEscritaWorkspace(cwd, [
+        ...(basePerfil === cwd ? [ARQUIVO_PERFIL_CONTEXTO] : []),
         ...caminhosTemplate,
         ...exemplosIniciar.map((arquivo) => arquivo.caminhoRelativo),
         ...ARQUIVOS_RESUMO_PROJETO_IA,
@@ -95,6 +103,7 @@ export async function comandoIniciar(cwd, template, opcoes = {}) {
     const arquivosParaEscrever = opcoes.force
         ? arquivos
         : arquivos.filter((arquivo) => !existentes.has(arquivo.caminhoRelativo));
+    await salvarPerfilContexto(basePerfil, perfilContexto);
     await escreverArquivos(cwd, arquivosParaEscrever, { inserirCabecalhoGovernado: true });
     const exemplos = await materializarExemplosOficiais(cwd, true, opcoes.exemplosCompletos ? undefined : EXEMPLOS_STARTER_INICIAR);
     if (!exemplos.sucesso) {

package/dist/sessionContext.d.ts

@@ -0,0 +1,13 @@
+export declare function navegarContextoSessao(base: string, pedido: string, arquivo?: string): Promise<{
+    totalModulos: number;
+    indiceCaracteres: number;
+    candidatos: {
+        modulo: any;
+        contrato: string;
+        motivo: string;
+        resumo: any;
+        arquivos: any;
+    }[];
+    status: string;
+    execucaoAutorizada: boolean;
+}>;

package/dist/sessionContext.js

@@ -0,0 +1,41 @@
+// SEMA-GOVERNED: sema.produto.cli_sessao
+// Descrição: consulta o índice local internamente e retorna candidatos rastreáveis, sem autorização de edição.
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { selecionarIndiceContexto } from "./indexPack.js";
+import { validarDestinosEscritaWorkspace } from "./workspaceWrite.js";
+export async function navegarContextoSessao(base, pedido, arquivo) {
+    await validarDestinosEscritaWorkspace(base, ["SEMA_INDEX.json"]);
+    const texto = await readFile(path.join(base, "SEMA_INDEX.json"), "utf8");
+    const indice = JSON.parse(texto);
+    if (!Array.isArray(indice.modulos))
+        throw new Error("Índice sem módulos; rode sema sync-codex --json.");
+    const relativo = (valor) => {
+        const absoluto = path.resolve(base, valor);
+        const rel = path.relative(base, absoluto);
+        if (rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel))
+            throw new Error("Referência de contexto fora do workspace.");
+        return rel.replace(/\\/g, "/");
+    };
+    const alvo = arquivo ? relativo(arquivo) : undefined;
+    const exatos = alvo ? indice.modulos.filter((m) => relativo(m.arquivo) === alvo
+        || m.arquivosProvaveis?.some((p) => relativo(p) === alvo)) : [];
+    const pack = selecionarIndiceContexto({ modulos: indice.modulos, request: pedido, baseProject: base, sourceIndexChars: texto.length, maximoModulos: indice.modulos.length });
+    const encontrados = alvo ? exatos.map((m) => ({
+        module: m.modulo, contract: m.arquivo, purpose: m.faz, likelyFiles: m.arquivosProvaveis,
+    })) : pack.matches;
+    return {
+        totalModulos: indice.modulos.length,
+        indiceCaracteres: texto.length,
+        candidatos: encontrados.map((m) => ({
+            modulo: m.module,
+            contrato: relativo(m.contract),
+            motivo: alvo ? `Referência exata: ${alvo}` : "Correspondência de intenção; confirme no contrato antes de editar.",
+            resumo: m.purpose,
+            arquivos: (m.likelyFiles ?? []).map(relativo),
+        })),
+        status: encontrados.length === 0 ? "sem_correspondencia" : encontrados.length === 1 ? "contrato_localizado" : "selecionar_contrato",
+        execucaoAutorizada: false,
+    };
+}
+//# sourceMappingURL=sessionContext.js.map

package/dist/verificacaoPythonLocal.d.ts

@@ -0,0 +1,17 @@
+type Arquivo = {
+    caminhoRelativo: string;
+    conteudo: string;
+};
+export declare function erroModoPreservacao(preservar: boolean | undefined, configuracoes: Array<{
+    alvo: string;
+    framework: string;
+}>): string | undefined;
+export declare function prepararImplementacaoPythonLocal(base: string, arquivos: Arquivo[]): Promise<{
+    arquivosParaEscrita: Arquivo[];
+    erro?: string;
+}>;
+export declare function evidenciaPython(preservar: boolean | undefined): {
+    tipoEvidencia: "andaime_demonstrativo" | "implementacao_local_preservada";
+    implementacaoExternaExecutada: boolean;
+};
+export {};

package/dist/verificacaoPythonLocal.js

@@ -0,0 +1,46 @@
+// SEMA-GOVERNED: sema.produto.cli_verificacao
+// Contrato: contratos/sema/cli_verificacao.sema
+// Descrição: preserva Python local explicitamente; testes continuam derivados do contrato, sem cache.
+import { lstat } from "node:fs/promises";
+import path from "node:path";
+export function erroModoPreservacao(preservar, configuracoes) {
+    if (preservar && (configuracoes.length !== 1 || configuracoes[0].alvo !== "python" || configuracoes[0].framework !== "base")) {
+        return "--preservar-implementacao exige --alvo python e framework base.";
+    }
+    return undefined;
+}
+export async function prepararImplementacaoPythonLocal(base, arquivos) {
+    const implementacoes = arquivos.filter(arquivo => arquivo.caminhoRelativo.endsWith(".py") && !path.basename(arquivo.caminhoRelativo).startsWith("test_"));
+    if (implementacoes.length === 0)
+        return { arquivosParaEscrita: [], erro: "Nenhuma implementação Python local prevista pelo contrato." };
+    try {
+        for (const arquivo of implementacoes) {
+            const destino = path.resolve(base, arquivo.caminhoRelativo);
+            const relativo = path.relative(path.resolve(base), destino);
+            if (path.isAbsolute(relativo) || relativo.split(path.sep).includes(".."))
+                throw new Error("escape");
+            let atual = destino;
+            while (true) {
+                const info = await lstat(atual);
+                if (info.isSymbolicLink() || (atual === destino ? !info.isFile() || info.nlink > 1 : !info.isDirectory()))
+                    throw new Error("link ou tipo inválido");
+                const pai = path.dirname(atual);
+                if (pai === atual)
+                    break;
+                atual = pai;
+            }
+        }
+        const preservados = new Set(implementacoes.map(arquivo => arquivo.caminhoRelativo));
+        return { arquivosParaEscrita: arquivos.filter(arquivo => !preservados.has(arquivo.caminhoRelativo)) };
+    }
+    catch {
+        return { arquivosParaEscrita: [], erro: "Implementação Python local ausente ou caminho não seguro. Gere e preencha a implementação antes de usar --preservar-implementacao." };
+    }
+}
+export function evidenciaPython(preservar) {
+    return {
+        tipoEvidencia: preservar ? "implementacao_local_preservada" : "andaime_demonstrativo",
+        implementacaoExternaExecutada: false,
+    };
+}
+//# sourceMappingURL=verificacaoPythonLocal.js.map

package/docs/ai-integration.md

@@ -60,19 +60,11 @@ while contract-only queries keep unobserved implementation fields null inside th
 
 ## Codex Context Tiers
 
-Codex with a small context budget should start with `SEMA_BOOT.md`,
-`SEMA_SMALL_MODEL.md`, `SEMA_BRIEF.micro.txt`,
-`AGENT_CONTEXT_PACK.json`, and `SEMA_INDEX.json`. They should stop early
-when a gate is unclear.
-
-Codex with a medium context budget should start with `SEMA_BOOT.md`,
-`AGENT_CONTEXT_PACK.json`, `SEMA_BRIEF.curto.txt`,
-`SEMA_INDEX.json`, and `AGENTS.md`. They must run docs-impact, drift, and
-impact before edits.
-
-Codex with a large context budget may consume `AGENT_CONTEXT_PACK.json`, `SEMA_BRIEF.md`,
-`SEMA_INDEX.json`, AST, IR, drift, and impact outputs, but larger context does
-not remove the contract-first rule.
+All context capacities start with AGENTS.md, SEMA_BOOT.md and sema sessao.
+The first session asks for the effective window in tokens. Declare --janela-contexto
+and use --salvar-perfil to remember it; --orcamento-contexto and --reserva-saida are adjustable.
+SEMA_INDEX.json and AGENT_CONTEXT_PACK.json are internal CLI data, never mandatory full reads.
+Read the selected contract and its declared dependencies, then the linked code. Ambiguity requires refinement.
 
 ## Governed Code
 

package/docs/ai-workflow.md

@@ -5,10 +5,10 @@ This is the minimum workflow for Codex in a local workspace.
 
 1. Read `SEMA_BOOT.md`.
 2. Run `sema --version`. If the shell cannot find it, use `$HOME/.sema/bin/sema` on macOS/Linux. On Windows, PowerShell resolves `sema.ps1` from PATH and cmd.exe resolves `sema.cmd`; use `& "$env:SystemRoot\System32\WindowsPowerShell\v1.0\powershell.exe" -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "$HOME\.sema\bin\sema-managed.ps1" --version` as the absolute fallback. Only then declare the CLI unavailable.
-3. Run `sema resumo --drift none` for contract-only orientation; request `--drift cache` or `--drift fresh` only when code evidence is needed.
-4. Run `sema docs-impacto --intencao "<change>" --json`.
+3. Run `sema sessao "<intenção>" --json`; then `sema resumo <contrato> --micro --drift none --json` only for the selected contract.
+4. Run `sema docs-impacto --intencao "<change>" --arquivo <contract> --json`.
 5. Read every required document returned by the command.
-6. Read `docs/commands.md` before selecting a command or interpreting `--saida`.
+6. Consult command help or the relevant section of `docs/commands.md` when syntax, a gate or `--saida` is unclear.
 7. If the right capability is unclear, run `sema descobrir recomendar --intencao "<goal>" --json`; do not auto-run ambiguous recommendations.
 8. Use `exemplos/` and `docs/syntax.md` before creating or editing a contract.
 9. Run `sema drift --cache fresh` and `sema impacto` before editing existing code.
@@ -30,9 +30,11 @@ UI rule: if the task involves an interface, minimum evidence includes desktop an
 
 ## Codex Context Capacity
 
-- Small context: `SEMA_SMALL_MODEL.md`, `SEMA_BRIEF.micro.txt`, `AGENT_CONTEXT_PACK.json`, `SEMA_INDEX.json`.
-- Medium context: `SEMA_BOOT.md`, `AGENT_CONTEXT_PACK.json`, `SEMA_BRIEF.curto.txt`, `SEMA_INDEX.json`, `AGENTS.md`.
-- Large context: `SEMA_BOOT.md`, `AGENT_CONTEXT_PACK.json`, `SEMA_BRIEF.md`, `SEMA_INDEX.json`, AST, IR, drift, and impact.
+All capacities use AGENTS.md -> SEMA_BOOT.md -> the contract returned by `sema sessao`.
+The first session asks for the configured token window; declare `--janela-contexto <tokens> --salvar-perfil`.
+Use `--orcamento-contexto` and `--reserva-saida` to allocate space. Counts use characters / 4, not the model tokenizer.
+The CLI reads SEMA_INDEX.json internally. Do not load the full index, global pack, or unrelated modules.
+An explicit `--arquivo` selects its contract and declared dependencies. Word matches are optional references.
 
 ## When to Generate Code
 

package/docs/commands.md

@@ -18,7 +18,7 @@ Then read every required doc returned by `docs-impacto`.
 
 ## Session Opening
 
-- `sema sessao "<intencao>" --json`: opens a governed session with one compact envelope. It returns workspace identity (`baseProjeto`, `hashContratos`, CLI version), artifact freshness (`frescor.fresco` plus the exact recovery command when stale), the project's contract count and modules, the declared intent's categories with blocking and recommended docs, the four gate commands for the full loop, and concrete next steps. Treat `frescor.fresco:false` as a pre-action blocker: run the suggested `sema sync-codex --json` before editing, because gates protect the consistency that stale artifacts break.
+- `sema sessao "<intencao>" [--arquivo <contrato-ou-codigo>] [--janela-contexto <tokens>] [--orcamento-contexto <tokens>] [--reserva-saida <tokens>] [--salvar-perfil] --json`: asks for the effective window when absent and stores the profile only on explicit request. The compact response contains workspace identity, artifact freshness, matching contracts and linked files, mandatory document paths, scoped gates and next steps. The index stays inside the CLI. The budget estimates the public JSON size using characters/4; it does not measure the conversation or the model's exact tokenizer. Omitted candidates are counted and require scope refinement; mandatory readings are never silently waived. Treat `frescor.fresco:false` as a pre-action blocker and run the suggested `sema sync-codex --json`. Navigation never authorizes execution.
 
 ## Public JSON output
 

package/docs/documentation.md

@@ -47,3 +47,36 @@ same rule applies to drift and semantic-budget governance: keep a cohesive
 primary capability in the root contract and move secondary responsibilities to
 named children. Preserve task names, guarantees, implementations, and
 `vinculos`; never create numbered part files.
+
+
+## Progressive AI Context
+
+The mandatory entry is AGENTS.md and SEMA_BOOT.md. SEMA_INDEX.json and
+AGENT_CONTEXT_PACK.json are internal CLI sources, not required full readings.
+The session asks for the effective context window when it is unknown. The local
+`.sema/contexto-ia.json` profile is saved only by `--salvar-perfil` or by `iniciar`
+with a declared window. Reconfigure it after switching models.
+
+`sema sessao "<intent>" --janela-contexto 32768 --salvar-perfil --json`
+configures a 32K window. Defaults allocate 4096 estimated tokens to the session
+response and reserve 4096 for output. Other instructions, tools, conversation
+and code need the remaining space. `--orcamento-contexto` and `--reserva-saida`
+adjust this split. The characters/4 estimate includes the public envelope and
+a margin; it is not an exact tokenizer or a measurement of the client's used
+context. The limit applies to the session response, not every legacy command
+or the cumulative conversation. The output reserve does not configure the model.
+
+In docs-impacto and finalizar-mudanca, `--arquivo` fixes the target. Explicit
+contracts are included even beyond the 80th catalog entry. Source files resolve
+through `vinculos.arquivo`. Required expansion follows declared `use` dependencies,
+with reasons and originating contracts. Missing or ambiguous dependencies block.
+`docs.arquivo` references are recommendations and do not expand the dependency
+graph. Intent suggestions stay in `leituraRecomendada`, distinct from
+`leituraObrigatoria`, and do not block closure. Pass the same target at closure
+and confirm the selected contracts before editing code.
+
+The context-budget and docs-relevancia tests measure actual CLI output, prove
+that the raw index is absent, verify hash invalidation and configuration before
+writes, and cover WhatsApp alongside 85 unrelated contracts. Drift, contract
+and behavioral gates remain required. To roll back, restore the prior generators
+and resolvers and run sync-codex; preserve manual blocks and the local profile.

package/docs/testing.md

@@ -169,3 +169,21 @@ this scaffold: its tests and guarantees cannot establish production behavior.
 Use the application's real tests and drift evidence for that claim. Generated
 failure cases currently retain the explicit synthetic error context and are
 not evidence that the real implementation produces those errors.
+
+To execute an explicitly filled local Python implementation without overwriting
+it, use the same verification output base that contains the generated module:
+
+```bash
+sema verificar contratos/app.sema --alvo python --saida .tmp/check --preservar-implementacao --json
+```
+
+This opt-in mode supports only Python with the base framework. All expected
+implementation files must already exist as regular files, without symlinks,
+junctions or hardlinks. It preserves those files byte for byte, regenerates the
+contract tests and support artifacts, and always runs the tests without reading
+or writing the verification cache. Missing implementations fail before writes;
+new expectations and incorrect implementation results still fail. The output
+reports `tipoEvidencia: implementacao_local_preservada` and
+`implementacaoExternaExecutada: false`: it proves execution of those local files,
+not automatic execution of a linked `impl`, a remote deployment or production.
+Normal verification retains the demonstration scaffold behavior.

package/exemplos/python_verificacao.sema

@@ -1,68 +1,68 @@
-module exemplos.python_verificacao {
-  docs {
-    resumo: "Regressao executavel Python para garantias numericas, formulario tipado, status e metadados aninhados."
-  }
-  entity FormularioEntrega {
-    fields {
-      tipo: Texto
-    }
-  }
-  entity MetaTemplate {
-    fields {
-      original_campaign_id: Texto
-    }
-  }
-  entity Template {
-    fields {
-      _template_meta: MetaTemplate
-    }
-  }
-  entity Status {
-    fields {
-      desired_action: Texto
-    }
-  }
-  task preparar {
-    input {
-      formulario: FormularioEntrega required
-    }
-    output {
-      poolSize: Inteiro
-      workersAplicados: Inteiro
-      template: Template
-      status: Status
-    }
-    rules {
-      formulario.tipo existe
-    }
-    guarantees {
-      poolSize > 0
-      workersAplicados >= 2
-      template._template_meta existe
-      template._template_meta.original_campaign_id em ["campanha_1"]
-      status.desired_action em ["iniciar", "parar"]
-    }
-    tests {
-      caso "verifica cada saida" {
-        given {
-          formulario {
-            tipo: "entrega"
-          }
-        }
-        expect {
-          sucesso: verdadeiro
-          poolSize: 1
-          workersAplicados: 2
-          template {
-            _template_meta {
-              original_campaign_id: "campanha_1"
-            }
-          }
-          status {
-            desired_action: "iniciar"
-          }
-        }
-      }
-    }
-  }
-}
+module exemplos.python_verificacao {
+  docs {
+    resumo: "Regressao executavel Python para garantias numericas, formulario tipado, status e metadados aninhados."
+  }
+  entity FormularioEntrega {
+    fields {
+      tipo: Texto
+    }
+  }
+  entity MetaTemplate {
+    fields {
+      original_campaign_id: Texto
+    }
+  }
+  entity Template {
+    fields {
+      _template_meta: MetaTemplate
+    }
+  }
+  entity Status {
+    fields {
+      desired_action: Texto
+    }
+  }
+  task preparar {
+    input {
+      formulario: FormularioEntrega required
+    }
+    output {
+      poolSize: Inteiro
+      workersAplicados: Inteiro
+      template: Template
+      status: Status
+    }
+    rules {
+      formulario.tipo existe
+    }
+    guarantees {
+      poolSize > 0
+      workersAplicados >= 2
+      template._template_meta existe
+      template._template_meta.original_campaign_id em ["campanha_1"]
+      status.desired_action em ["iniciar", "parar"]
+    }
+    tests {
+      caso "verifica cada saida" {
+        given {
+          formulario {
+            tipo: "entrega"
+          }
+        }
+        expect {
+          sucesso: verdadeiro
+          poolSize: 1
+          workersAplicados: 2
+          template {
+            _template_meta {
+              original_campaign_id: "campanha_1"
+            }
+          }
+          status {
+            desired_action: "iniciar"
+          }
+        }
+      }
+    }
+  }
+}