@semacode/cli 4.1.3 → 4.2.0

package/dist/cliHelpTexto.js

@@ -25,7 +25,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]",
+            "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>",
@@ -145,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/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");

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/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