@semacode/cli 2.3.0 → 3.0.0

package/docs/cli.md

@@ -1,79 +1,197 @@
-# Sema CLI
-
-Sema is a Codex-native local CLI distribution. The public package reads the
-workspace on the user's machine, validates `.sema` contracts, checks drift,
-maps impact, and generates code without login, user authorization, license
-activation, tokens, credits, billing services, a control panel, or external
-service credentials.
-
-Support: suporte@otimitare.online
-
-## Install
-
-```bash
-npm install -g @semacode/cli
-sema --version
-```
-
-For development inside this repository:
-
-```bash
-npm install
-npm run build
-node pacotes/cli/dist/index.js --help
-```
-
-## Codex Setup
-
-`AGENTS.md` is the official Sema entrypoint for Codex. Create or refresh it from
-the local CLI:
-
-```bash
-sema sync-codex --json
-```
-
-Codex automatically loads `AGENTS.md` as repository guidance. Sema is an
-independent product and is not affiliated with or endorsed by OpenAI.
-
-## Required Local Flow
-
-Codex and humans should use the same local sequence before changing governed
-code, contracts, workflows, release scripts, or operational docs:
-
-```bash
-sema --version
-sema resumo
-sema docs-impacto --intencao "describe the change" --json
-sema inspecionar contratos/example.sema --json
-sema drift contratos/example.sema --escopo modulo --json
-sema impacto contratos/example.sema --alvo sema.example.target --mudanca "describe the change" --json
-```
-
-Commands run directly against the local workspace. If `sema --version` fails,
-install or repair the npm package; there is no separate authorization gate.
-
-## Core Commands
-
-- `sema iniciar`: create a governed starting point.
-- `sema validar`: validate `.sema` contracts.
-- `sema inspecionar`: inspect the applicable contract surface.
-- `sema drift`: compare contracts and implementation.
-- `sema impacto`: map the blast radius of a planned change.
-- `sema docs-impacto`: identify docs that must be read or updated.
-- `sema finalizar-mudanca`: close the governed change with evidence.
-- `sema compilar`: generate code from contracts.
-- `sema testar`: generate, compile, and execute local contract tests, including `dotnet` and `cpp`.
-- `sema verificar`: run the final local verification bundle.
-- `sema contexto-ia`: build local AI context from a contract.
-- `sema sync-codex`: create or refresh the official `AGENTS.md` entrypoint.
-
-Generation targets are `typescript`, `python`, `php`, `dart`, `lua`,
-`javascript`, `html`, `css`, `dotnet`, and `cpp`. The aliases `cs` and
-`csharp` select `dotnet`; `c++`, `cxx`, and `cc` select `cpp`.
-Native targets are opt-in in `sema.config.json.alvos` for project-wide
-verification because they require local compiler toolchains.
-
-## Public Boundary
-
-Do not publish private or sensitive operational material in public Sema
-artifacts.
+# Sema CLI
+
+Sema is a Codex-native local CLI distribution. The public package reads the
+workspace on the user's machine, validates `.sema` contracts, checks drift,
+maps impact, and generates code without login, user authorization, license
+activation, tokens, credits, billing services, a control panel, or external
+service credentials.
+
+Support: suporte@otimitare.online
+
+## Install
+
+```bash
+npm install -g @semacode/cli
+sema --version
+sema skill status --json
+```
+
+The global install bundles the portable Sema skill and creates a launcher under
+`~/.sema/bin` with absolute Node.js and CLI paths. If the npm shim is absent
+from `PATH`, run `~/.sema/bin/sema` on macOS/Linux. On Windows, PowerShell
+resolves `sema.ps1` from `PATH`, while `cmd.exe` resolves `sema.cmd`; invoke the
+managed fallback through the absolute system executable:
+
+```powershell
+& "$env:SystemRoot\System32\WindowsPowerShell\v1.0\powershell.exe" -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "$HOME\.sema\bin\sema-managed.ps1" --version
+```
+
+Use `sema skill sync --json` to repair an installation performed with lifecycle
+scripts disabled.
+
+For development inside this repository:
+
+```bash
+npm install
+npm run build
+node pacotes/cli/dist/bin.js --help
+```
+
+## Side-Effect-Free Help
+
+`--help` and `-h` take precedence wherever they appear in argv, including after
+an unknown command or option. The CLI exits with status `0` before command
+runtime import, command dispatch, or handler resolution. Help does not inspect or mutate the workspace,
+home, user cache, or plugin cache, start a subprocess, or make a network call.
+
+`dist/bin.js` is the executable bootstrap and imports the operational runtime
+only after these control paths finish. `dist/index.js` remains the package API
+entrypoint and is not an executable alias.
+
+```bash
+sema iniciar --help
+sema formatar --help
+sema sync-codex --help
+sema skill sync --help
+sema unknown --option value --help
+```
+
+## Public JSON Output
+
+`sema --version` (and its version aliases) prints one plain exact SemVer string.
+It is intentionally not wrapped in JSON.
+
+### Help and command control
+
+Adding `--json` to help or a command-control failure emits exactly one JSON
+document on stdout and keeps stderr empty:
+
+```json
+{
+  "schemaVersion": "sema.cli.control/v1",
+  "ok": true,
+  "kind": "HELP",
+  "code": "CLI_HELP",
+  "message": "Sema CLI help",
+  "exitCode": 0
+}
+```
+
+The envelope contains exactly `schemaVersion`, `ok`, `kind`, `code`, `message`,
+and `exitCode`. Supported control kinds are `HELP`, `UNKNOWN_COMMAND`,
+`ARGUMENT_ERROR`, and `FATAL_ERROR`. Help uses exit code `0`; failures preserve
+a non-zero process status equal to `exitCode`. Failure messages are public and
+redacted: they do not include stacks, absolute paths, raw argv, or internal
+causes.
+
+Command-control failures are unknown top-level commands or subcommands, missing
+or invalid required CLI arguments/options rejected before valid dispatch, and
+uncaught runtime exceptions. An uncaught exception uses the redacted
+`FATAL_ERROR` control envelope. `sema.cli.control/v1` is never nested inside a
+command result.
+
+### Valid command results
+
+In 3.0.0, every syntactically valid command invoked with `--json` emits exactly
+one `sema.cli.result/v1` document on stdout with empty stderr:
+
+```json
+{
+  "schemaVersion": "sema.cli.result/v1",
+  "ok": true,
+  "kind": "SUCCESS",
+  "command": "resumo",
+  "code": "CLI_SUCCESS",
+  "message": null,
+  "exitCode": 0,
+  "payload": {
+    "comando": "resumo",
+    "sucesso": true
+  }
+}
+```
+
+The result envelope contains exactly `schemaVersion`, `ok`, `kind`, `command`,
+`code`, `message`, `exitCode`, and `payload`; extra or missing fields are
+invalid, and `data` is not an alias for `payload`. `command` is the canonical
+top-level command name. `payload` is always present and may be any JSON value,
+including an object, array, scalar, or `null`.
+
+- `SUCCESS` requires `ok: true`, `code: "CLI_SUCCESS"`, `message: null`, and
+  `exitCode: 0`.
+- `DOMAIN_ERROR` requires `ok: false`, `code: "CLI_DOMAIN_ERROR"`, a non-empty
+  safe public `message`, and a positive `exitCode` equal to the process status.
+
+The envelope describes the CLI result transport and classification. It does
+not replace the command's domain model: consumers must unwrap `payload` and
+evaluate fields such as `payload.sucesso`, `payload.aprovado`,
+`payload.bloqueado`, or another command-specific verdict separately. A
+syntactically valid operation that returns a structured domain failure uses
+`DOMAIN_ERROR`; it does not fall back to `sema.cli.control/v1`.
+
+## Codex Setup
+
+`AGENTS.md` is the official Sema entrypoint for Codex. Create or refresh it from
+the local CLI:
+
+```bash
+sema sync-codex --json
+```
+
+Codex automatically loads `AGENTS.md` as repository guidance. Sema is an
+independent product and is not affiliated with or endorsed by OpenAI.
+
+## Required Local Flow
+
+Codex and humans should use the same local sequence before changing governed
+code, contracts, workflows, release scripts, or operational docs:
+
+```bash
+sema --version
+sema resumo --drift none
+sema docs-impacto --intencao "describe the change" --json
+sema inspecionar contratos/example.sema --drift none --json
+sema drift contratos/example.sema --escopo modulo --cache fresh --json
+sema impacto contratos/example.sema --alvo sema.example.target --mudanca "describe the change" --json
+```
+
+Commands run directly against the local workspace. If `sema --version` fails,
+try the managed absolute launcher before declaring the CLI unavailable. If both
+fail, install or repair the npm package; there is no separate authorization
+gate.
+
+## Core Commands
+
+- `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.
+- `sema drift`: compare contracts and implementation with `--cache none|cache|fresh` (default `fresh`).
+- `sema impacto`: map the blast radius of a planned change.
+- `sema docs-impacto`: identify docs that must be read or updated.
+- `sema finalizar-mudanca`: close the governed change with evidence.
+- `sema compilar`: generate code from contracts.
+- `sema testar`: generate, compile, and execute local contract tests, including `dotnet` and `cpp`.
+- `sema verificar`: run the final local verification bundle.
+- `sema contexto-ia`: build local AI context from a contract.
+- `sema sync-codex`: create or refresh the official `AGENTS.md` entrypoint.
+- `sema skill status|sync`: inspect or repair the managed launcher and bundled
+  global skill without touching plugin caches or workspace files.
+
+`resumo` and `inspecionar` default to `--drift none`, so they do not fabricate
+scores or implementation evidence. In this mode those fields inside `payload`
+are `null` or explicitly not evaluated. `sema drift --cache none` still runs
+the analysis but does not touch persistent cache. `cache` reuses only a validated extraction hit;
+`fresh` ignores hits and republishes recalculated extraction data. Cache objects
+live in the operating system's user-cache directory outside the workspace, and
+the final links, diagnostics, score, and success decision are always recomputed.
+
+Generation targets are `typescript`, `python`, `php`, `dart`, `lua`,
+`javascript`, `html`, `css`, `dotnet`, and `cpp`. The aliases `cs` and
+`csharp` select `dotnet`; `c++`, `cxx`, and `cc` select `cpp`.
+Native targets are opt-in in `sema.config.json.alvos` for project-wide
+verification because they require local compiler toolchains.
+
+## Public Boundary
+
+Do not publish private or sensitive operational material in public Sema
+artifacts.

package/docs/commands.md

@@ -7,19 +7,30 @@ Use this file when Codex does not know which command to run. A Sema command is a
 
 ```bash
 sema --version
-sema resumo
+sema resumo --drift none
 sema docs-impacto --intencao "<acao>" --json
 ```
 
+If `sema` is absent from `PATH`, use `$HOME/.sema/bin/sema` on macOS/Linux. On Windows, PowerShell resolves `sema.ps1` from PATH, cmd.exe resolves `sema.cmd`, and the absolute fallback is `& "$env:SystemRoot\System32\WindowsPowerShell\v1.0\powershell.exe" -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "$HOME\.sema\bin\sema-managed.ps1" --version`. `sema skill sync --json` repairs launcher and skill without touching the workspace or plugin caches.
+
 Then read every required doc returned by `docs-impacto`.
 
+## 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.
+
+## Global Distribution
+
+- `sema skill status --json`: diagnoses the managed launcher and bundled skill without writing.
+- `sema skill sync --json`: repairs only Sema-managed launcher and skill destinations; it never writes into the workspace or plugin caches.
+
 ## Contract and Discovery
 
 - `sema iniciar --template <template> [--force]`: creates a new Sema project and preserves existing files by default; `--force` is the only explicit overwrite path.
 - `sema validar <arquivo-ou-pasta> --json`: validates `.sema` contracts.
 - `sema diagnosticos <arquivo.sema> --json`: details errors and warnings.
 - `sema formatar <arquivo-ou-pasta>`: formats contracts.
-- `sema inspecionar <arquivo-ou-pasta> --json`: shows modules, tasks, routes, entities, links, and expected files.
+- `sema inspecionar <arquivo-ou-pasta> [--drift <none|cache|fresh>] --json`: shows the contract surface; drift is skipped by default.
 - `sema ast <arquivo.sema> --json`: shows AST for syntax debugging.
 - `sema ir <arquivo.sema> --json`: shows the IR used by gates and generators.
 - `sema descobrir catalogo --json`: lists governance flows, profiles, specialized workflows, pipelines, generators, capability tokens, and adapters from their canonical registries.
@@ -30,12 +41,24 @@ Then read every required doc returned by `docs-impacto`.
 ## Change and Closure
 
 - `sema docs-impacto --intencao "<acao>" --json`: discovers required docs and documentary blockers.
-- `sema drift <arquivo-ou-pasta> --escopo modulo --json`: compares contract and implementation.
+- `sema drift <arquivo-ou-pasta> --escopo modulo [--cache <none|cache|fresh>] --json`: plans a safe physical scope, then compares contract and implementation without a global fallback.
 - `sema impacto <arquivo-ou-pasta> --alvo <token> --mudanca "<descricao>" --json`: maps impact before changing behavior.
 - `sema verificar <arquivo-ou-pasta> --json`: runs aggregated final verification.
 - `sema finalizar-mudanca --intencao "<acao>" --doc-lida <arquivo> --json`: proves documentation reading before closure.
 
-Honest closure: treat drift JSON as the source of truth. `sucesso:false`, `vinculos_quebrados`, `rotas_divergentes`, or broken impls mean the change is not complete yet. Do not report "clean drift" without green JSON.
+Honest closure: unwrap drift JSON and treat its command payload as the source of truth. `payload.sucesso:false`, non-empty `payload.vinculos_quebrados`, non-empty `payload.rotas_divergentes`, or non-empty `payload.impls_quebrados` mean the change is not complete yet. Do not report "clean drift" without a green payload.
+
+Focused drift exposes its planned, declared, inferred, and missing files plus catalog visit/read metrics in `escopo_aplicado`. File and module scopes fail closed without a safe anchor, with homonymous implementation candidates, or with missing local dependencies; only `--escopo projeto` may walk every configured code root. Logical roots such as `src` are probed deterministically without a discovery walk. Configured contract origins and code roots are confined before enumeration, and `inspecionar`, `impacto`, and `renomear-semantico` reuse the same directed boundary without reopening arbitrary external paths.
+
+Drift analysis and cache modes are explicit:
+
+- `sema drift` defaults to `--cache fresh`. `none` still executes drift but performs zero persistent-cache I/O; `cache` reuses a fully validated extraction hit and publishes misses; `fresh` ignores hits, recalculates, and publishes the new extraction.
+- `sema resumo` and `sema inspecionar` default to `--drift none`. In that mode their payload does not execute drift and returns `null` for score, confidence, implementation, routes, or other code evidence that was not observed. Use `--drift cache` or `--drift fresh` when that evidence is required. `--com-drift` remains a temporary alias for `--drift fresh`.
+- When a query explicitly runs drift, `payload.analiseDrift.sucesso` exposes the result and a failed requested analysis returns a nonzero exit code.
+- The value aliases `off`, `auto`, and `refresh` normalize to `none`, `cache`, and `fresh` for one compatibility release and emit a structured deprecation warning. Wrong flags, repeated flags, conflicts, and invalid values fail instead of falling back silently.
+- Persistent cache objects live outside the workspace under the operating system's user-cache directory. Workspace identity is hashed; public JSON and events expose only an opaque key and `$SEMA_CACHE/...` paths. Corruption or cache unavailability becomes a miss and never changes the drift result. Only validated extraction data is reused; links, diagnostics, scores, and the final success decision are recalculated.
+
+A cache hit is acceleration, not final evidence; closure still requires fresh drift.
 
 ## Sema Code
 
@@ -63,6 +86,7 @@ Ready UI rule: if the task generates an app, site, dashboard, form, or static HT
 - `sema ajuda-ia`: short guidance for Codex.
 - `sema starter-ia`: operational starter.
 - `sema contexto-ia <arquivo.sema> --saida <dir> --json`: AI context package.
+- `sema resumo <arquivo-ou-pasta> [--drift <none|cache|fresh>] --json`: compact context; drift is not executed unless requested.
 - `sema prompt-curto <arquivo-ou-pasta> --json`: compact prompt.
 - `sema sync-codex --json`: synchronizes the official Codex entrypoint and local support docs.
 - `sema instalar-exemplos --json`: installs official examples in the workspace.
@@ -119,12 +143,12 @@ Spatial model and render mode are orthogonal: `THREE_D + HEADLESS` is valid, whi
 
 ## Forbidden
 
-- Do not use an external workspace source to inspect a local workspace when `sema --version` works.
+- Do not use an external workspace source to inspect a local workspace when `sema --version` or the managed launcher works.
 - Do not search the entire disk for `.sema` syntax; use `exemplos/`, `docs/syntax.md`, and this catalog.
 - Do not stop after `sema compilar` if the contract target files still do not exist.
 - Do not replace `sema compilar` with `sema testar` when the contract requires generated code.
 - Do not create a Markdown report to pretend a gate ran.
-- Do not say drift passed when `sema drift --json` returned `sucesso:false`, broken link, divergent route, or broken impl.
+- Do not say drift passed when the unwrapped `sema drift --cache fresh --json` payload returned `sucesso:false`, a non-empty `vinculos_quebrados`, `rotas_divergentes`, or `impls_quebrados` list.
 - Do not declare a UI responsive without mobile/desktop proof; horizontal scroll at 390px blocks closure.
 
 Governed code policy: keep the `SEMA-GOVERNED` marker, split large code by real responsibility, preserve contract links, and never treat a generated output directory as the final delivery.

package/docs/database.md

@@ -1,15 +1,15 @@
-# Database Boundary
-
-The public Sema CLI does not require a database.
-
-Sema reads contracts and source files from the local workspace. Any database used
-by an application governed by Sema belongs to that application, not to the public
-Sema CLI distribution.
-
-## Public Rule
-
-Do not ship private database material, real credentials, operational schemas, or
-project-specific data in the public Sema package.
-
-Application-specific database docs should live in the application repository
-that owns the database.
+# Database Boundary
+
+The public Sema CLI does not require a database.
+
+Sema reads contracts and source files from the local workspace. Any database used
+by an application governed by Sema belongs to that application, not to the public
+Sema CLI distribution.
+
+## Public Rule
+
+Do not ship private database material, real credentials, operational schemas, or
+project-specific data in the public Sema package.
+
+Application-specific database docs should live in the application repository
+that owns the database.

package/docs/deploy.md

@@ -1,41 +1,54 @@
-# Deployment Boundary
-
-The public Sema repository documents two coordinated release surfaces: the
-local npm CLI and the Codex bootstrap skill. The skill remains a separate,
-explicit Codex installation and is never injected by npm lifecycle scripts.
-
-Run the complete public gate:
-
-```bash
-npm run build
-npm run codex:sync-entrypoint
-npm run status:check
-npm run repo:verificar-publico
-npm run plugin:testar-codex
-npm test
-npm run release:verificar-drift
-npm run release:preparar-publica
-npm run release:publicar-npm-dry-run
-```
-
-`release:preparar-publica` performs the Codex entrypoint sync before checking
-the public boundary, so a clean clone does not depend on ignored generated
-handshake files left by a previous local run.
-
-The plugin smoke installs the repo marketplace into an isolated `CODEX_HOME`,
-installs `sema@sema`, compares the cached skill with the versioned source, and
-proves no Sema MCP server was registered. Plugin and CLI versions must match
-before the commit is pushed. The release command itself runs the full test suite
-and project-wide Sema drift gate; these are not optional manual preliminaries.
-
-Push the commit containing `.agents/plugins/marketplace.json` and
-`plugins/sema/` before telling users to install from `gerlanss/Sema`. Publish
-the npm package only after the tarball smoke passes. After npm publication, run
-`npm run release:verificar-distribuicao` to verify the registry and live GitHub
-state. That final verifier also requires the remote GitHub HEAD to match the
-local commit, installs `sema@sema` from `gerlanss/Sema` in an isolated
-`CODEX_HOME`, compares the remote skill with the versioned source, and proves
-that the remote plugin registers no Sema MCP. The current contract does not
-permit creating a GitHub Release or release asset.
-
-Do not publish private or sensitive operational material in this repository.
+# Deployment Boundary
+
+The public Sema repository documents one coordinated npm artifact containing
+the local CLI, its absolute managed launcher, and the portable bootstrap skill.
+The repository Codex plugin remains an optional namespaced distribution channel
+for the same versioned skill.
+
+Run the complete public gate:
+
+```bash
+npm run build
+npm run codex:sync-entrypoint
+npm run status:check
+npm run repo:verificar-publico
+npm run plugin:testar-codex
+npm test
+npm run release:verificar-drift
+npm run release:preparar-publica
+npm run release:publicar-npm-dry-run
+```
+
+`release:preparar-publica` performs the Codex entrypoint sync before checking
+the public boundary, so a clean clone does not depend on ignored generated
+handshake files left by a previous local run.
+
+All release and local-install routes delegate to `npm run
+cli:empacotar-publica`. The factory uses a unique private stage, disables npm
+lifecycle scripts while packing that stage, and publishes only a fully
+validated tarball. Do not use `npm pack --workspace @semacode/cli`; the source
+package guard rejects that unsupported path without staging files in the
+workspace.
+
+The public-package smoke performs a global install with isolated home, npm
+prefix, npm cache, and user cache. It proves the launcher works through its
+absolute path with Node.js and npm removed from `PATH`. On Windows it exercises
+`sema.ps1` as the PowerShell `PATH` entrypoint, `sema-managed.ps1` through the
+absolute `%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe`, and
+`sema.cmd` through `cmd.exe`. The smoke also proves the synchronized
+skill matches the packaged source, the real user home is unchanged, and local
+installs leave global state untouched. The plugin smoke independently compares
+its cached skill with the versioned source and proves no Sema MCP server was
+registered. Plugin and CLI versions must match before the commit is pushed.
+
+Push the commit containing `.agents/plugins/marketplace.json` and
+`plugins/sema/` before telling users to install from `gerlanss/Sema`. Publish
+the npm package only after the tarball smoke passes. After npm publication, run
+`npm run release:verificar-distribuicao` to verify the registry and live GitHub
+state. That final verifier also requires the remote GitHub HEAD to match the
+local commit, installs `sema@sema` from `gerlanss/Sema` in an isolated
+`CODEX_HOME`, compares the remote skill with the versioned source, and proves
+that the remote plugin registers no Sema MCP. The current contract does not
+permit creating a GitHub Release or release asset.
+
+Do not publish private or sensitive operational material in this repository.

package/docs/documentation.md

@@ -35,14 +35,15 @@ sema finalizar-mudanca \
 - Keep commands, file paths, package names, environment variable names, and DSL
   keywords literal.
 - Do not include private or sensitive operational material.
-- Prefer local CLI examples.
-- Point support requests to suporte@otimitare.online.
-
-## Contract Split Plan
+- Prefer local CLI examples.
+- Point support requests to suporte@otimitare.online.
+
+## Contract Structure
 
-`contratos/sema/governanca_ia_documentacao.sema` is close to the 500-line
-blocking limit. Before adding another documentation capability, split it by
-responsibility into contracts for required-document resolution, localization,
-and change-finalization evidence. Preserve the existing task names, guarantees,
-implementations, and links; the contracts may continue to govern the same CLI
-files through multiple `vinculos`. Do not create numbered part files.
+Documentation governance is split by capability: required-document resolution
+stays in `governanca_ia_documentacao.sema`, while localization and
+change-finalization evidence live in explicitly named child contracts. The
+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.

package/docs/drift-cache.md

@@ -0,0 +1,108 @@
+# Drift Cache And Query Evidence
+
+Sema exposes three drift modes, but the `none` mode intentionally means
+different things for direct drift execution and for query commands. The
+defaults preserve honest, low-cost queries while keeping an explicit drift run
+fresh by default.
+
+| Mode | `sema drift --cache <mode>` | `sema resumo --drift <mode>` / `sema inspecionar --drift <mode>` |
+| --- | --- | --- |
+| `none` | Runs drift without reading or writing persistent cache. | Skips drift analysis. This is the query default. |
+| `cache` | Reuses a valid cache entry; otherwise recalculates and publishes a new entry. | Runs drift with the same reuse-or-recalculate behavior. |
+| `fresh` | Does not reuse a prior hit, recalculates, and publishes a fresh entry. This is the direct drift default. | Runs drift from fresh inputs without reusing prior extraction data, then publishes the resulting entry. |
+
+Use `--cache none` when a direct analysis must leave no persistent cache access.
+Use `--drift none` when a summary or inspection should not perform drift at all.
+The two forms are not interchangeable.
+
+## Honest Query Evidence
+
+`sema resumo` and `sema inspecionar` default to `--drift none`. Their JSON
+payload includes an `analiseDrift` envelope that makes the omitted evaluation
+explicit:
+
+```json
+{
+  "analiseDrift": {
+    "modo": "none",
+    "executada": false,
+    "sucesso": null,
+    "cache": null
+  },
+  "scoreDrift": null,
+  "confiancaGeral": null
+}
+```
+
+The surrounding payload varies by command. A human-readable `aviso` or
+`avisos` entry explains why drift was not evaluated. Drift-derived framework,
+route, surface, bridge, and module implementation evidence is also `null` when
+applicable. In this context, `null` means **not evaluated**; it must never be
+interpreted as zero, empty, passing, or absent drift.
+
+Request `--drift cache` or `--drift fresh` when a query needs evaluated drift
+evidence. In that case, `payload.analiseDrift.sucesso` is `true` or `false`, and a
+failed requested analysis makes the command exit nonzero instead of hiding the
+failure behind a successful query response.
+
+## External Cache Location
+
+Persistent drift cache is stored outside the governed workspace:
+
+| Platform | Cache root |
+| --- | --- |
+| Windows | `%LOCALAPPDATA%\Sema\Cache`, falling back to `%USERPROFILE%\AppData\Local\Sema\Cache` |
+| macOS | `~/Library/Caches/Sema` |
+| Linux and other Unix systems | `$XDG_CACHE_HOME/sema`, falling back to `~/.cache/sema` |
+
+Drift entries live below `drift/v3/workspaces/<opaque-id>/objects/` inside that
+root. Public output represents such paths as `$SEMA_CACHE/drift/v3/...`.
+`$SEMA_CACHE` is a safe display placeholder, not a promise that an environment
+variable with that name exists, and Sema does not expose the real user cache
+path.
+
+Sema never writes persistent drift cache inside the repository, `.sema`,
+`.tmp`, generated project folders, or any other workspace location.
+
+## Authority And Recovery
+
+The cache is an acceleration layer, not governance evidence and not a source of
+truth. Contracts, source files, the active analysis plan, and the validated
+result remain authoritative.
+
+- A corrupt or incompatible entry is treated as a recoverable miss: Sema
+  recalculates instead of trusting it.
+- If external cache storage is unavailable, analysis continues by
+  recalculating; cache persistence does not become a governance blocker.
+- `cache` may reuse only a valid entry for the current workspace and inputs.
+- `fresh` never reuses cached extraction data before analysis. Publication may
+  read and validate an existing content-addressed winner to preserve CAS
+  integrity without changing the freshly calculated result.
+- Direct `none` performs no persistent cache reads or writes.
+
+These rules keep cache failures from hiding drift and keep the governed
+workspace free of machine-local state.
+
+## Semantic Integrity And Trust Limit
+
+The reusable payload stores canonical per-extractor indices. It does not store
+`todosSimbolos`, route aggregates, resource aggregates, or known-file
+aggregates as independent sources. Sema derives those values again after a
+cache entry is restored, so a redundant aggregate cannot silently override its
+source indices.
+
+Before accepting a hit, Sema checks exact field allowlists, relative catalog
+paths, extractor-specific file extensions and symbol origins, consumer-surface
+to route relationships, and derived integrity digests across symbols, routes,
+resources, surfaces, and persistence details. Detectable structural or
+semantic inconsistency becomes a corrupt miss, followed by a fresh in-memory
+calculation and repair. A valid hit is therefore limited to a compatible
+payload produced for the same CLI, schema, extractor, workspace identity, Git
+HEAD, plan, configuration, contracts, and content-digested members.
+
+These SHA-256 digests detect corruption and incoherent rewriting; they do not
+authenticate a hostile process running as the same operating-system user. Such
+a process can read the implementation and rewrite both data and checksums. The
+external cache is not a security boundary, a signature, or final evidence.
+Use `--cache fresh` for closure and retain stronger evidence outside the local
+user cache when the threat model includes local-user compromise.