@semacode/cli 3.10.0 → 3.11.1

package/README.md

@@ -29,9 +29,15 @@ install or update because existing tasks do not reload their skill catalog.
 
 ```bash
 sema --version
+sema sessao "describe the change" --json
 sema resumo . --curto --drift none
 ```
 
+`sema sessao` opens a governed session with one compact envelope: workspace
+identity and contract hash, artifact freshness with the exact recovery command
+when stale, the blocking and recommended docs for the declared intent, the four
+gate commands, and concrete next steps.
+
 Public Sema is local-only. The CLI runs directly without a Sema login, user
 authorization, product-license check, activation key, token, credits, billing
 service, control panel, or external service credentials. The license governs
@@ -123,6 +129,7 @@ On Windows, PowerShell resolves `sema.ps1` from `PATH`, `cmd.exe` resolves
 ## Local Workflow
 
 ```bash
+sema sessao "describe the change" --json
 sema docs-impacto --intencao "describe the change" --arquivo contratos/app.sema --json
 sema inspecionar contratos/app.sema --drift none --json
 sema drift contratos/app.sema --escopo modulo --cache fresh --json

package/dist/agentEntryPoints.js

@@ -147,7 +147,7 @@ Você está em um projeto governado por Sema. O contrato semântico vem antes de
 ## Primeira ação
 
 1. Confirme \`AGENTS.md\` na raiz e rode \`sema --version\`. Se o shell não localizar o comando, use \`$HOME/.sema/bin/sema\` no macOS/Linux; no Windows, PowerShell usa \`sema.ps1\` no PATH, cmd.exe usa \`sema.cmd\`, e o fallback absoluto é \`& "$env:SystemRoot\\System32\\WindowsPowerShell\\v1.0\\powershell.exe" -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "$HOME\\.sema\\bin\\sema-managed.ps1" --version\`. Só então declare a CLI indisponível.
-2. Use a CLI local diretamente para ler o workspace: \`sema resumo --drift none\`, \`sema docs-impacto\`, \`sema inspecionar --drift none\`, \`sema drift --cache fresh\` e \`sema impacto\`. Na 3.0.0, \`sema --version\` continua texto SemVer exato; com \`--json\`, help e falhas de controle usam \`sema.cli.control/v1\`, enquanto comandos sintaticamente válidos usam o envelope exato de oito campos \`sema.cli.result/v1\`, com o resultado aninhado em \`payload\` e \`ok\` separado do veredito de domínio desse payload.
+2. Use a CLI local diretamente para ler o workspace: \`sema sessao "<intencao>" --json\` na abertura (identidade, frescor, docs bloqueantes e gates em um envelope), depois \`sema resumo --drift none\`, \`sema docs-impacto\`, \`sema inspecionar --drift none\`, \`sema drift --cache fresh\` e \`sema impacto\`. Na 3.0.0, \`sema --version\` continua texto SemVer exato; com \`--json\`, help e falhas de controle usam \`sema.cli.control/v1\`, enquanto comandos sintaticamente válidos usam o envelope exato de oito campos \`sema.cli.result/v1\`, com o resultado aninhado em \`payload\` e \`ok\` separado do veredito de domínio desse payload.
 3. Se não estiver claro qual profile, workflow, pipeline, gerador ou adapter usar, rode \`sema descobrir recomendar --intencao "<objetivo>" --json\`; não execute automaticamente uma recomendação ambígua.
 4. Não use fonte externa de workspace para substituir a CLI local quando ela estiver operacional.
 5. Este boot é para workspace local em disco; se não houver workspace local, pare bloqueado em vez de inventar caminho.
@@ -442,16 +442,17 @@ Este workspace é governado por Sema. Antes de qualquer ação em código, contr
 
 1. Leia \`${ARQUIVO_SEMA_BOOT}\`.
 2. Rode \`sema --version\`; se o shell falhar, use \`$HOME/.sema/bin/sema\` no macOS/Linux. No Windows, PowerShell usa \`sema.ps1\` no PATH e cmd.exe usa \`sema.cmd\`; use \`& "$env:SystemRoot\\System32\\WindowsPowerShell\\v1.0\\powershell.exe" -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "$HOME\\.sema\\bin\\sema-managed.ps1" --version\` como fallback absoluto. Só então pare e peça instalação ou reparo.
-3. Use diretamente a CLI local: \`sema resumo --drift none\`, \`sema docs-impacto\`, \`sema inspecionar --drift none\`, \`sema drift --cache fresh\` e \`sema impacto\`. Na 3.0.0, \`sema --version\` continua texto SemVer exato; com \`--json\`, help e falhas de controle usam \`sema.cli.control/v1\`, enquanto comandos sintaticamente válidos usam o envelope exato de oito campos \`sema.cli.result/v1\`, com resultado em \`payload\` e \`ok\` distinto do veredito de domínio do payload.
-4. Quando a capacidade correta não estiver clara, use \`sema descobrir recomendar --intencao "<objetivo>" --json\`; não autoexecute resultado ambíguo.
-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. 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.
+3. Abra a sessão com \`sema sessao "<intencao>" --json\`: devolve identidade do workspace, hash dos contratos, frescor dos artefatos gerados, docs bloqueantes da intenção e os gates do ciclo. Se \`frescor.fresco\` for falso, rode o \`sync-codex\` sugerido antes de agir.
+4. Use diretamente a CLI local: \`sema resumo --drift none\`, \`sema docs-impacto\`, \`sema inspecionar --drift none\`, \`sema drift --cache fresh\` e \`sema impacto\`. Na 3.0.0, \`sema --version\` continua texto SemVer exato; com \`--json\`, help e falhas de controle usam \`sema.cli.control/v1\`, enquanto comandos sintaticamente válidos usam o envelope exato de oito campos \`sema.cli.result/v1\`, com resultado em \`payload\` e \`ok\` distinto do veredito de domínio do payload.
+5. Quando a capacidade correta não estiver clara, use \`sema descobrir recomendar --intencao "<objetivo>" --json\`; não autoexecute resultado ambíguo.
+6. Não use fonte externa de workspace para substituir a CLI local quando ela estiver operacional.
+7. Chame docs-impacto com a intenção declarada antes de agir.
+8. Chame inspecionar no contrato \`.sema\` aplicável.
+9. 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\`.
+10. Antes de editar código existente, rode \`sema drift --cache fresh\` e impacto.
+11. Antes de criar ou editar \`.sema\`, use exemplos oficiais.
+12. Ao concluir mudança de contrato, rode validar.
+13. 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.
 
@@ -708,6 +709,7 @@ Use this file when Codex does not know which command to run. A Sema command is a
 
 \`\`\`bash
 sema --version
+sema sessao "<intencao>" --json
 sema resumo --drift none
 sema docs-impacto --intencao "<acao>" --json
 \`\`\`
@@ -716,6 +718,10 @@ If \`sema\` is absent from \`PATH\`, use \`$HOME/.sema/bin/sema\` on macOS/Linux
 
 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.
+
 ## Public JSON output
 
 \`sema --version\` stays plain exact SemVer text. With \`--json\`, help and command-control failures use exactly one six-field \`sema.cli.control/v1\` document on stdout with empty stderr. Every syntactically valid command uses exactly one eight-field \`sema.cli.result/v1\` document containing only \`schemaVersion\`, \`ok\`, \`kind\`, \`command\`, \`code\`, \`message\`, \`exitCode\`, and \`payload\`. The command-specific result is nested under \`payload\`, never \`data\`; envelope \`ok\` does not replace domain fields inside that payload. Valid structured domain failures use \`DOMAIN_ERROR\`, while uncaught runtime exceptions remain redacted \`FATAL_ERROR\` control failures.

package/docs/cli.md

@@ -148,6 +148,7 @@ code, contracts, workflows, release scripts, or operational docs:
 
 ```bash
 sema --version
+sema sessao "describe the change" --json
 sema resumo --drift none
 sema docs-impacto --intencao "describe the change" --json
 sema inspecionar contratos/example.sema --drift none --json
@@ -162,6 +163,7 @@ gate.
 
 ## Core Commands
 
+- `sema sessao`: open a governed session; one envelope with workspace identity, artifact freshness, intent-specific blocking docs, gates, and next steps.
 - `sema iniciar`: create a governed starting point.
 - `sema validar`: validate `.sema` contracts.
 - `sema inspecionar`: inspect the applicable contract surface; add `--drift cache|fresh` to request code evidence.

package/docs/commands.md

@@ -7,6 +7,7 @@ Use this file when Codex does not know which command to run. A Sema command is a
 
 ```bash
 sema --version
+sema sessao "<intencao>" --json
 sema resumo --drift none
 sema docs-impacto --intencao "<acao>" --json
 ```
@@ -15,6 +16,10 @@ If `sema` is absent from `PATH`, use `$HOME/.sema/bin/sema` on macOS/Linux. On W
 
 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.
+
 ## Public JSON output
 
 `sema --version` stays plain exact SemVer text. With `--json`, help and command-control failures use exactly one six-field `sema.cli.control/v1` document on stdout with empty stderr. Every syntactically valid command uses exactly one eight-field `sema.cli.result/v1` document containing only `schemaVersion`, `ok`, `kind`, `command`, `code`, `message`, `exitCode`, and `payload`. The command-specific result is nested under `payload`, never `data`; envelope `ok` does not replace domain fields inside that payload. Valid structured domain failures use `DOMAIN_ERROR`, while uncaught runtime exceptions remain redacted `FATAL_ERROR` control failures.

package/package.json

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