@semacode/cli 2.3.1 → 3.5.0

package/docs/documentation.md

@@ -1,39 +1,49 @@
-# Documentation Governance
-
-Documentation is part of every governed change. Codex must use
-`sema docs-impacto` before editing contracts, code, operational docs, workflows,
-profiles, generated artifacts, or release material.
-
-Public Sema documentation is English and local-only.
-
-## Required Flow
-
-```bash
-sema docs-impacto --intencao "describe the change" --json
-```
-
-The result lists:
-
-- `leituraObrigatoria`: files that must be read before the change;
-- `docsAusentes`: missing docs that block the change;
-- `docsCriadas`: generated draft docs that must be completed by Codex;
-- `bloqueios`: blocking diagnostics.
-
-Before closing the change, prove the required docs were read:
-
-```bash
-sema finalizar-mudanca \
-  --intencao "describe the change" \
-  --doc-lida README.md \
-  --doc-lida docs/documentation.md \
-  --json
-```
-
-## Public Docs Rules
-
-- Write public docs in English.
-- 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.
+# Documentation Governance
+
+Documentation is part of every governed change. Codex must use
+`sema docs-impacto` before editing contracts, code, operational docs, workflows,
+profiles, generated artifacts, or release material.
+
+Public Sema documentation is English and local-only.
+
+## Required Flow
+
+```bash
+sema docs-impacto --intencao "describe the change" --json
+```
+
+The result lists:
+
+- `leituraObrigatoria`: files that must be read before the change;
+- `docsAusentes`: missing docs that block the change;
+- `docsCriadas`: generated draft docs that must be completed by Codex;
+- `bloqueios`: blocking diagnostics.
+
+Before closing the change, prove the required docs were read:
+
+```bash
+sema finalizar-mudanca \
+  --intencao "describe the change" \
+  --doc-lida README.md \
+  --doc-lida docs/documentation.md \
+  --json
+```
+
+## Public Docs Rules
+
+- Write public docs in English.
+- 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 Structure
+
+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.

package/docs/getting-started.md

@@ -4,53 +4,78 @@ Sema is installed and used as a local CLI.
 
 ```bash
 npm install -g @semacode/cli
-codex plugin marketplace add gerlanss/Sema
-codex plugin add sema@sema
+sema skill status --json
 ```
 
-Open a new Codex task in the target repository so the newly installed `$sema`
-skill is loaded, then ask it to initialize Sema. Existing tasks do not refresh
-their skill catalog. After bootstrap, `AGENTS.md` becomes the automatic protocol
-for subsequent tasks.
+The global package creates an absolute launcher under `~/.sema/bin`, installs
+the bundled skill in `~/.agents/skills/sema`, and mirrors it to
+`~/.claude/skills/sema` only when Claude is already present. Open a new task so
+the updated skill catalog is loaded. Installing or updating the global CLI does
+not authorize Sema adoption in the current workspace: informational requests
+stay read-only, and implementation requires explicit adoption authorization.
+After an authorized bootstrap, `AGENTS.md` becomes the automatic protocol for
+subsequent tasks.
 
 Then verify the local engine:
 
 ```bash
 sema --version
-sema resumo
+sema resumo --drift none
 ```
 
 The CLI is ready when `sema --version` succeeds. No Sema login, user
 authorization, activation key, product-license check, token, credits, billing
 service, or control panel is involved.
 
-The Codex skill is required for first contact with a project that does not yet
-have Sema. It only bootstraps the local CLI and generates the repository's
-`AGENTS.md`; that file becomes the automatic workspace protocol afterward.
-Plugin installation is explicit and does not happen from npm lifecycle scripts.
+The skill handles first contact with a project that does not yet have Sema. It
+only bootstraps the local CLI and generates the repository's `AGENTS.md`; that
+file becomes the automatic workspace protocol afterward. The npm lifecycle does
+not install plugins or touch plugin caches.
+
+If the install used `--ignore-scripts`, run `sema skill sync --json`. If the
+shell cannot resolve the npm shim, use `~/.sema/bin/sema` on macOS or Linux. On
+Windows, PowerShell resolves `sema.ps1` from `PATH`, `cmd.exe` resolves
+`sema.cmd`, and the robust PowerShell fallback is:
+
+```powershell
+& "$env:SystemRoot\System32\WindowsPowerShell\v1.0\powershell.exe" -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "$HOME\.sema\bin\sema-managed.ps1" --version
+```
+
+The managed fallback contains absolute Node.js and CLI paths and does not
+depend on `PATH`.
 
 ## First Project
 
 ```bash
+sema descobrir explicar flow.project-adoption --json
 sema iniciar --template base
+sema sync-codex --json
 sema validar contratos/*.sema --json
-sema resumo
+sema resumo --drift none
 ```
 
-`sema iniciar` preserves existing project files and refuses symlink or junction
-escapes. The bootstrap skill never uses `--force`; explicit overwrite remains a
-human decision.
+Run this sequence only after explicit project-adoption authorization. The
+`sema iniciar` command preserves existing project files and refuses symlink or
+junction escapes. The bootstrap skill never uses `--force`; explicit overwrite
+remains a human decision.
 
 ## Existing Project
 
 ```bash
-sema resumo
+sema resumo --drift none
 sema docs-impacto --intencao "describe the change" --json
-sema inspecionar contratos/example.sema --json
-sema drift contratos/example.sema --escopo modulo --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
 ```
 
+`sema resumo` and `sema inspecionar` default to `--drift none`: they skip drift
+analysis and report drift-derived evidence as `null`, meaning not evaluated.
+Direct `sema drift` defaults to `--cache fresh`; its `--cache none` mode still
+runs the analysis, but without reading or writing persistent cache. See
+[Drift Cache And Query Evidence](./drift-cache.md) for the complete mode table,
+external cache locations, and recovery behavior.
+
 The public CLI does not require private service credentials or an external
 request before local commands run.