@semacode/cli 3.8.3 → 3.8.5

package/dist/agentEntryPoints.js

@@ -153,8 +153,9 @@ Você está em um projeto governado por Sema. O contrato semântico vem antes de
 5. Este boot é para workspace local em disco; se não houver workspace local, pare bloqueado em vez de inventar caminho.
 6. Antes de criar módulo, rota, task ou contrato, inspecione o contrato \`.sema\` aplicável.
 7. Antes de editar código existente, rode \`sema drift --cache fresh\` e impacto pela CLI local.
-8. Antes de criar ou corrigir \`.sema\`, use os exemplos oficiais na CLI local.
-9. Se qualquer etapa falhar, pare e diga que está bloqueado.
+8. Para módulo novo com contrato validado, gere o andaime com \`sema compilar\` no alvo padrão, preencha a implementação real mantendo \`impl\`/\`vinculos\` e feche com \`sema verificar\`.
+9. Antes de criar ou corrigir \`.sema\`, use os exemplos oficiais na CLI local.
+10. Se qualquer etapa falhar, pare e diga que está bloqueado.
 
 Não substitua esse fluxo por leitura manual de \`AGENTS.md\`, \`README.md\`, busca local, inferência pelo nome do projeto, bom senso ou ferramenta não citada aqui.
 
@@ -446,10 +447,11 @@ Este workspace é governado por Sema. Antes de qualquer ação em código, contr
 5. Não use fonte externa de workspace para substituir a CLI local quando ela estiver operacional.
 6. Chame docs-impacto com a intenção declarada antes de agir.
 7. Chame inspecionar no contrato \`.sema\` aplicável.
-8. Antes de editar código existente, rode \`sema drift --cache fresh\` e impacto.
-9. Antes de criar ou editar \`.sema\`, use exemplos oficiais.
-10. Ao concluir mudança de contrato, rode validar.
-11. Antes de finalizar, use finalizar-mudanca com as docs lidas.
+8. Para módulo novo com contrato validado, gere o andaime com \`sema compilar <contrato> --alvo <alvoPadrao>\`, preencha a implementação real mantendo \`impl\`/\`vinculos\` e feche com \`sema verificar\`.
+9. Antes de editar código existente, rode \`sema drift --cache fresh\` e impacto.
+10. Antes de criar ou editar \`.sema\`, use exemplos oficiais.
+11. Ao concluir mudança de contrato, rode validar.
+12. Antes de finalizar, use finalizar-mudanca com as docs lidas.
 
 É proibido substituir esse fluxo por leitura manual de \`AGENTS.md\`, \`README.md\`, busca local por arquivos, inferência pelo nome do projeto, bom senso ou ferramenta não citada nesta lista.
 
@@ -657,8 +659,9 @@ This is the minimum workflow for Codex in a local workspace.
 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.
-10. Run \`sema formatar\` and \`sema validar\` after changing a \`.sema\` contract.
-11. Run \`sema finalizar-mudanca\` with the documents read before closure.
+10. For a new module with a validated contract, scaffold with \`sema compilar <contract> --alvo <default target>\`, fill the real implementation keeping \`impl\`/\`vinculos\`, and close with \`sema verificar\`.
+11. Run \`sema formatar\` and \`sema validar\` after changing a \`.sema\` contract.
+12. Run \`sema finalizar-mudanca\` with the documents read before closure.
 
 Contract edit rule: \`.sema\` has its own size budget. Above ${LIMITE_AVISO_LINHAS_CONTRATO_SEMA} lines, plan a split by domain/capability; above ${LIMITE_BLOQUEIO_LINHAS_CONTRATO_SEMA}, do not create or edit before splitting. Do not use parte_1/parte_2 and do not force a 1:1 contract-to-file relationship; several contracts can govern the same file through \`vinculos\`.
 

package/dist/docs.part01.d.ts

@@ -5,6 +5,7 @@ export interface DocumentoPlanejado {
     tipo: TipoDocumentoMudanca;
     motivo: string;
     permitirCriacao: boolean;
+    obrigatoriedade?: "bloqueante" | "recomendada";
 }
 export interface DocumentoObrigatorioMudanca {
     caminho: string;
@@ -20,6 +21,7 @@ export interface DocumentoObrigatorioMudanca {
     template?: string;
     templatePendente?: boolean;
     substancia?: boolean;
+    obrigatoriedade: "bloqueante" | "recomendada";
 }
 export interface BloqueioDocumentacaoMudanca {
     tipo: "documentacao_ausente" | "leitura_obrigatoria_nao_comprovada" | "documentacao_template_cru" | "documentacao_sem_substancia" | "arquivo_monolitico" | "codigo_governado_sem_cabecalho";
@@ -38,6 +40,7 @@ export interface ResultadoDocumentacaoObrigatoria {
     leituraObrigatoria: DocumentoObrigatorioMudanca[];
     docsAusentes: DocumentoObrigatorioMudanca[];
     docsCriadas: DocumentoObrigatorioMudanca[];
+    leituraRecomendada: DocumentoObrigatorioMudanca[];
     bloqueios: BloqueioDocumentacaoMudanca[];
     instrucoes: string[];
 }
@@ -45,6 +48,7 @@ export interface ResultadoVerificacaoDocumentacaoMudanca {
     sucesso: boolean;
     baseProjeto: string;
     intencao: string;
+    leituraRecomendada: DocumentoObrigatorioMudanca[];
     categorias: string[];
     docsLidas: string[];
     leituraObrigatoria: DocumentoObrigatorioMudanca[];

package/dist/docs.part02.js

@@ -51,7 +51,7 @@ export async function resolverDocumentacaoObrigatoria(opcoes) {
     await adicionarDocsRaizExistentes(baseProjeto, registrar);
     for (const regra of REGRAS_DOCUMENTACAO.filter((item) => categorias.includes(item.categoria))) {
         for (const doc of regra.docs) {
-            registrar(doc);
+            registrar({ ...doc, obrigatoriedade: "recomendada" });
         }
     }
     await adicionarReadmesDeArquivos(baseProjeto, arquivosAlvo, registrar);
@@ -87,6 +87,7 @@ export async function resolverDocumentacaoObrigatoria(opcoes) {
             criado,
             criacaoAutomatica: doc.permitirCriacao,
             obrigatorio: true,
+            obrigatoriedade: doc.obrigatoriedade ?? "bloqueante",
             template: existe ? undefined : template,
         };
         if (existe) {
@@ -101,7 +102,7 @@ export async function resolverDocumentacaoObrigatoria(opcoes) {
     }
     const docsAusentes = leituraObrigatoria.filter((doc) => !doc.existe);
     const docsCriadas = leituraObrigatoria.filter((doc) => doc.criado);
-    const bloqueios = docsAusentes.map((doc) => ({
+    const bloqueios = docsAusentes.filter((doc) => doc.obrigatoriedade !== "recomendada").map((doc) => ({
         tipo: "documentacao_ausente",
         severidade: 4,
         caminho: doc.relativo,
@@ -118,6 +119,9 @@ export async function resolverDocumentacaoObrigatoria(opcoes) {
         leituraObrigatoria,
         docsAusentes,
         docsCriadas,
+        leituraRecomendada: leituraObrigatoria
+            .filter((doc) => doc.obrigatoriedade === "recomendada")
+            .map(compactarDocumentoObrigatorio),
         bloqueios,
         instrucoes: [
             "A IA deve ler todos os itens de leituraObrigatoria antes de executar a mudanca.",
@@ -149,9 +153,9 @@ export async function verificarDocumentacaoMudanca(opcoes) {
     });
     const docsLidas = [...new Set((opcoes.docsLidas ?? []).map((doc) => normalizarDocLida(baseProjeto, doc)).filter(Boolean))];
     const setDocsLidas = new Set(docsLidas);
-    const docsNaoLidas = impacto.leituraObrigatoria.filter((doc) => doc.existe && !setDocsLidas.has(doc.relativo));
-    const docsTemplatePendentes = impacto.leituraObrigatoria.filter((doc) => (doc.existe && doc.templatePendente && setDocsLidas.has(doc.relativo)));
-    const docsSemSubstancia = impacto.leituraObrigatoria.filter((doc) => (doc.existe && !doc.templatePendente && doc.substancia === false));
+    const docsNaoLidas = impacto.leituraObrigatoria.filter((doc) => (doc.existe && doc.obrigatoriedade !== "recomendada" && !setDocsLidas.has(doc.relativo)));
+    const docsTemplatePendentes = impacto.leituraObrigatoria.filter((doc) => (doc.existe && doc.obrigatoriedade !== "recomendada" && doc.templatePendente && setDocsLidas.has(doc.relativo)));
+    const docsSemSubstancia = impacto.leituraObrigatoria.filter((doc) => (doc.existe && doc.obrigatoriedade !== "recomendada" && !doc.templatePendente && doc.substancia === false));
     const diagnosticosOrcamento = await emitirDiagnosticosArquivosOrcamento({
         baseProjeto,
         arquivos: opcoes.arquivosAlvo ?? [],
@@ -201,6 +205,7 @@ export async function verificarDocumentacaoMudanca(opcoes) {
         intencao: opcoes.intencao,
         categorias: impacto.categorias,
         docsLidas,
+        leituraRecomendada: impacto.leituraRecomendada,
         leituraObrigatoria: impacto.leituraObrigatoria.map(compactarDocumentoObrigatorio),
         docsNaoLidas: docsNaoLidas.map(compactarDocumentoObrigatorio),
         docsAusentes: impacto.docsAusentes.map(compactarDocumentoObrigatorio),

package/docs/ai-workflow.md

@@ -12,8 +12,9 @@ This is the minimum workflow for Codex in a local workspace.
 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.
-10. Run `sema formatar` and `sema validar` after changing a `.sema` contract.
-11. Run `sema finalizar-mudanca` with the documents read before closure.
+10. For a new module with a validated contract, scaffold with `sema compilar <contract> --alvo <default target>`, fill the real implementation keeping `impl`/`vinculos`, and close with `sema verificar`.
+11. Run `sema formatar` and `sema validar` after changing a `.sema` contract.
+12. Run `sema finalizar-mudanca` with the documents read before closure.
 
 Contract edit rule: `.sema` has its own size budget. Above 300 lines, plan a split by domain/capability; above 500, do not create or edit before splitting. Do not use parte_1/parte_2 and do not force a 1:1 contract-to-file relationship; several contracts can govern the same file through `vinculos`.
 

package/package.json

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