@semacode/cli 2.1.0 → 2.3.0

package/docs/descoberta-capacidades.md

@@ -0,0 +1,106 @@
+# Capability Discovery
+
+Sema exposes one explainable catalog so an AI can distinguish a validation
+profile, an orchestration pipeline, a specialized workflow, a generator, a
+governance gate, an adapter descriptor, and an opaque capability token.
+
+Discovery is local, deterministic, and read-only. It recommends or explains a
+capability but never executes the recommended command:
+
+```bash
+sema descobrir catalogo --json
+sema descobrir recomendar --intencao "validar simulador 3D autonomo calibrado" --json
+sema descobrir recomendar --intencao "port a 16-bit game to another engine and declare losses" --json
+sema descobrir explicar interactive.portability --json
+sema pipeline listar --json
+sema pipeline descrever interactive.playtest --json
+sema capabilities --json
+```
+
+The response schema is `sema.discovery/v1` and always reports:
+
+- `executed: false`;
+- `workspaceMutated: false`;
+- `externalCalls: false`;
+- actionable command templates with placeholders;
+- required inputs and execution boundaries;
+- matched signals, reasons, missing inputs, and stable scores.
+
+Advanced interactive intent is routed to the narrowest local validator or
+analyzer (`validar-temporal`, `validar-playtest-fuzz`, `analisar-portabilidade`,
+and peers). A broad profile or engine descriptor does not outrank that specific
+pipeline, and the suggested template retains every required file and flag.
+
+Raw paths and credential-like values supplied in intents or filters are used
+only for the in-memory lookup and are redacted from JSON and human output.
+
+## Catalog coverage
+
+The interactive catalog exposes **35 unique pipelines** and **28 unique
+external adapter descriptors**. The pipeline set covers the original game and
+simulation lifecycle plus P0/P1/P2 operational capabilities:
+
+- P0 representation and observation: Experience IR, engine snapshots, asset
+  provenance, editor state, multimodal evidence, resumable jobs, and acceptance
+  locks;
+- P1 behavior over time: timeline validation, shot/camera checks, physics
+  relations, temporal QA, clean-install/launch/smoke checks, and hardware
+  budgets;
+- P2 autonomy and scale: safe repair cycles, bot playtests, state fuzzing,
+  multiplayer authority, engine migration, portability with declared losses,
+  and distributed job DAGs.
+
+These entries apply across 3D, 2.5D, 2D, 8-bit, 16-bit, text, XR, and headless
+games and simulations. Discovery ranks the requested goal independently from
+the spatial model and visual profile.
+
+The 28 adapters are **descriptors for external capabilities**. Catalog lookup
+does not detect an installed engine, inspect an editor, enumerate plug-ins,
+probe processes, contact a worker, or prove that any integration is available.
+An external runner must establish runtime availability and return bound
+evidence.
+
+## Capability kinds
+
+- `GOVERNANCE_FLOW`: contract, drift, impact, verification, and closure gates.
+- `PROFILE_GATE`: semantic validation such as game, simulation, software, or ops.
+- `SPECIALIZED_WORKFLOW`: dedicated surfaces such as `sema author`.
+- `ORCHESTRATION_PIPELINE`: a staged workflow such as content, interactive
+  playtest, temporal validation, portability, or distributed jobs.
+- `CAPABILITY_TOKEN`: an opaque producer, evaluator, runtime, or evidence token.
+- `GENERATOR`: code generation targets.
+- `ADAPTER`: compatibility descriptors for external engines, editors, runtimes,
+  observers, verifiers, asset tools, build systems, and workers.
+
+`author` is intentionally a specialized workflow, not a fake
+`sema profile validar author` command. Likewise, `profile.game` validates game
+semantics; it is not the same thing as the `interactive.playtest` pipeline.
+
+## Deterministic recommendation
+
+The base router normalizes accents and aliases, applies positive and negative
+signals, scores the entry kind and domain, and sorts by score then stable ID.
+The minimum recommendation score is 60. When the top two candidates are within
+seven points, the response reports ambiguity and does not choose a command.
+
+This rule is deliberate: an AI should request more concrete intent instead of
+silently running the wrong pipeline.
+
+Interactive pipeline entries point to declarative planning with
+`sema interativo planejar <definition.json> --json`. The definition must list
+the recommended pipeline ID; the secondary `descrever` template remains
+available when the AI first needs the pipeline contract. Advanced entries point
+to their dedicated `sema interativo` validator or analyzer. Those commands
+still return local, non-authoritative results and do not execute engines,
+editors, plug-ins, or workers.
+
+Legacy views remain available:
+
+```bash
+sema profile capabilities --json
+sema conteudo capabilities --json
+sema interativo capabilities --json
+```
+
+They are projections of the same authoritative catalog sources, not separate
+manually maintained product maps.

package/docs/documentation.md

@@ -35,5 +35,14 @@ 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.
+- Prefer local CLI examples.
+- Point support requests to suporte@otimitare.online.
+
+## Contract Split Plan
+
+`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.

package/docs/pipeline-conteudo.md

@@ -0,0 +1,246 @@
+# AI-native Content Pipeline
+
+Sema Content Pipeline is a contract-first control plane for creating content
+with AI agents across arbitrary destinations and formats. It plans work,
+verifies signed evidence, evaluates policy, derives canonical state, and tells
+an external runner what can happen next. It does not execute agents, call
+creative tools, publish content, or provide a native human-review path.
+
+Brands, channels, accounts, and formats are configuration. They are never
+closed enums in the pipeline core. A video channel, a site, a newsletter, an
+RSS feed, or a future destination all use the same target and adapter model.
+
+## Architecture
+
+```text
+.sema contracts, target set, and signed policy
+  -> Sema creates a declarative plan
+  -> external runner invokes producer agents and tools
+  -> producers submit signed claims and immutable artifacts
+  -> independent adapters/verifiers attest observable facts
+  -> specialized AI evaluators submit signed semantic assessments
+  -> Sema verifies identity, scope, independence, quorum, and deterministic rules
+  -> state is replayed from the canonical ledger
+  -> the external runner receives nextActions
+  -> manifests and dashboards are regenerated projections
+```
+
+Existing Author, research, writing, copy, image, video, creative-QA, and
+publication profiles are optional capabilities used by a pipeline definition.
+They are not the pipeline state machine and they do not become universal
+requirements for every kind of content.
+
+## Trust boundary
+
+A hash proves the identity and integrity of bytes. It does not prove that a
+claim is true. A JSON receipt produced by the runner therefore remains a claim.
+It becomes accepted evidence only when an authorized, independent principal
+attests it with an Ed25519 signature and the attestation matches the exact run,
+artifact digest, target, evidence type, policy, and validity window.
+
+The trust configuration accepts only Ed25519 SPKI public material
+(`-----BEGIN PUBLIC KEY-----`). PKCS#8 private PEM is rejected even though the
+crypto runtime could derive a public key from it. Private keys must stay in the
+producer, evaluator, adapter, or independent verification service that owns
+them. If the executor controls every private key and the canonical store, the
+signatures provide no meaningful separation.
+
+For high assurance, keep trust anchors outside the runner workspace and store
+the ledger in an independently controlled append-only service, WORM store, or
+transparency log. Every trusted operation requires a canonical trust-root digest
+retained by that external boundary; reading `trust.json` and trusting a digest
+from the same file would merely let the executor nominate its own authority.
+
+The signed policy is bound to the exact execution, pipeline definition, trust
+root, ledger, and complete target set through `runId`, `definitionDigest`,
+`trustRootDigest`, `ledgerId`, and `targetSetDigest`. Its `issuedAt` and
+`expiresAt` define the complete authorization window: the trusted `recordedAt`
+of `RUN_STARTED` must satisfy the configured maximum envelope age, and every
+event must be recorded inclusively between those policy bounds. Once
+`expiresAt` passes, the policy cannot authorize another append. It cannot be
+replayed as authorization for another run, and a controller cannot silently
+remove a channel to make a run appear complete.
+
+The trust-root digest and revocation digest are separate external pins. The
+trust root identifies the immutable authority set and its verification rules;
+`revocationDigest` identifies the current revocation overlay. Rotating that
+overlay must not redefine historical signatures, while revoked credentials no
+longer count as active evidence, authorization, or quorum.
+An authority key in the current revocation overlay cannot authorize a policy;
+historical ledger verification remains a separate operation.
+
+Public-key fingerprints, principal IDs, and key IDs must be unique, so one key
+cannot masquerade as several independent voters.
+
+The local file backend is useful for development and portable replay, but it is
+not advertised as a strong append-only root. A trusted external checkpoint
+(`expectedHead`) is required on ledger reads and writes to detect a truncated
+or concurrently replaced local ledger. A trust file
+inside the current workspace is rejected unless
+`--development-local-trust` is explicit; that flag relaxes file placement only
+and never removes digest pinning.
+
+## Evidence and semantic evaluation
+
+The pipeline separates three things:
+
+- a producer or runner claim (`EVIDENCE_CLAIMED`);
+- an independently signed observation (`EVIDENCE_ATTESTED`);
+- a specialized AI assessment (`AI_ASSESSMENT`).
+
+Sema evaluates deterministic constraints directly. Artifact metadata and
+producer claims never prove those constraints by themselves: observable facts
+must come from independently signed adapter/verifier observations bound to the
+artifact digest, run, target, policy, and trust context. This includes
+`observedMediaType`, obtained through independent sniffing; an artifact's
+producer-declared `mediaType` cannot satisfy adapter acceptance on its own.
+Semantic questions such as
+factual quality, narrative quality, channel fit, brand voice, accessibility,
+or audiovisual coherence require assessments from principals with the declared
+capability. Sema verifies those assessments against policy; it does not invent
+their semantic judgment.
+
+Critical gates can require multiple approvals, distinct principals, distinct
+control domains, and producer/evaluator separation. Deterministic attestations
+use `minAttestationsPerEvidence` and
+`minDistinctAttesterControlDomains` for every required evidence type; semantic
+AI opinions use `minApprovals` and `minDistinctControlDomains`. Multiple agent
+names under one credential or control domain do not create an independent
+quorum.
+Every gate that contributes to canonical completion must set
+`producerDisjoint: true`; self-approval cannot be configured as a completion
+shortcut.
+
+A generic `content.evidence.attest` capability never authorizes evidence. Base
+evidence requires `content.evidence.attest:<evidenceType>`. Adapter evidence is
+stricter: the externally pinned trust root must grant
+`content.adapter.attest:<adapterId>@<version>:<evidenceType>`, and the signed
+data must name the exact adapter and version. Delivery confirmation also carries
+an `observationDigest`; it is not a bare success receipt from the runner.
+
+## Canonical state
+
+Ledger events are hash-chained and carry signed envelopes. The state engine
+replays the ledger deterministically. It never reads `concluido`, `approved`, or
+similar fields from a hand-edited manifest.
+
+Event and envelope wrappers are exact schemas: unsigned extra fields are
+rejected. Every append requires the signed policy envelope and a complete
+expected context derived from it. The genesis event is anchored to the
+externally pinned trust domain, trust root, ledger ID, policy, definition, and
+complete target set; none of those values are accepted merely because
+`RUN_STARTED` declared them. During append, envelope freshness is measured
+against the platform clock; caller-controlled `recordedAt` cannot backdate an
+expired signature.
+
+Gate verdicts are independent from operational conditions:
+
+- verdict: `NAO_AVALIADO`, `APROVADO`, `REPROVADO`, `INCONCLUSIVO`;
+- condition: `PENDENTE`, `PRONTA`, `EXECUTANDO`,
+  `AGUARDANDO_EVIDENCIA`, `AGUARDANDO_EVENTO_EXTERNO`,
+  `FERRAMENTA_INDISPONIVEL`, `CAPACIDADE_AUSENTE`,
+  `AUTORIZACAO_AUSENTE`, `FALHA_TRANSITORIA`, `FALHA_TERMINAL`, or
+  `EXECUCAO_ENCERRADA`.
+
+For example, a content-quality gate may be `APROVADO` while a publication gate
+is `NAO_AVALIADO` and its operational condition is
+`AGUARDANDO_EVENTO_EXTERNO`. Tool unavailability never approves or rejects a
+gate. Missing semantic capacity becomes `CAPACIDADE_AUSENTE`; the runner can
+route the task to another authorized AI evaluator.
+
+Changing an artifact creates a new digest. Evidence and assessments bound to
+the previous digest become superseded for gate calculation. Targets also evolve
+independently: failure for one destination does not invalidate another.
+
+Every generated manifest declares:
+
+```json
+{
+  "authoritative": false,
+  "ledgerHead": "sha256:..."
+}
+```
+
+It is a read model, not an input to canonical state.
+
+The isolated gate calculator is internal. The public authoritative surface is
+canonical state derivation after the ledger replay has independently derived
+the producer, authorization scope, target, and complete producer lineage.
+The npm package exposes only its root entrypoint; `dist/pipelineConteudo/*`
+deep imports are blocked by the package `exports` map, including in the
+generated public tarball.
+
+## Open adapters and targets
+
+An adapter declares an opaque `adapterId`, immutable version, accepted media
+types, format profiles, deterministic constraints, required public metadata,
+optional public metadata, and externally verifiable confirmation predicates.
+`requiredMetadata + optionalMetadata` is the exact top-level allowlist signed
+through the definition digest. Target metadata accepts only declared keys and
+scalar public values. `accountScope` is a strict `account:<alias>` reference;
+credentials and tokens remain outside the ledger and are resolved by the
+external runner from that alias. Artifact metadata is prohibited in v1 until a
+separate signed schema exists. Recursive DLP checks additionally reject common
+secret key names, private-key material, JWTs, provider-token prefixes, and
+authorization headers without echoing the detected value.
+Deterministic-constraint configuration has an exact one-field numeric schema;
+extra, ambiguous, or sensitive fields block the adapter before its constraints
+can be copied into a public plan. Free-form operational `reason` text passes
+the same credential detector before it can enter the signed ledger.
+
+Public CLI failures expose static error codes and a sanitized command label;
+filesystem exceptions, unknown subcommands, rejected schema field names, and
+invalid trust identifiers are not echoed. Domain identifiers that belong to a
+valid definition or signed ledger (such as stage, target, evidence, and
+assessment IDs) remain public because they are required for planning,
+traceability, and remediation; they are never credential storage.
+
+Each stage declares an `adapterPolicy`:
+
+- `NONE`: no adapter gate is introduced by the stage;
+- `CONSTRAINTS`: require independently signed observations for the adapter's
+  deterministic format constraints;
+- `CONFIRMATION`: require the target adapter's externally verifiable
+  confirmation predicates.
+
+Pipeline definition v1 requires exactly one declared output per stage. A stage
+that needs several artifacts must split them into semantically distinct stages,
+preserving explicit lineage and dependency edges.
+
+No platform literal is required by the core. A project-specific experience is
+just a pipeline definition plus target configuration and can coexist with any
+number of other channels and formats.
+
+## CLI
+
+The public surface is `sema conteudo`:
+
+```bash
+sema conteudo capabilities --json
+sema conteudo validar <definition.json> --json
+sema conteudo planejar <definition.json> --alvos-arquivo <targets.json> --json
+sema conteudo validar-envelope --envelope-arquivo <envelope.json> --confianca-arquivo <trust.json> --trust-root-digest <sha256:...> --revocation-digest <sha256:...> --payload-type <type> --json
+sema conteudo registrar <ledger.ndjson> --envelope-arquivo <envelope.json> --politica-arquivo <policy-envelope.json> --confianca-arquivo <trust.json> --trust-root-digest <sha256:...> --revocation-digest <sha256:...> --ledger-id <id> --expected-head <sha256:...> --json
+sema conteudo status <definition.json> --politica-arquivo <policy-envelope.json> --confianca-arquivo <trust.json> --trust-root-digest <sha256:...> --revocation-digest <sha256:...> --ledger-arquivo <ledger.ndjson> --expected-head <sha256:...> --json
+sema conteudo projetar <definition.json> --politica-arquivo <policy-envelope.json> --confianca-arquivo <trust.json> --trust-root-digest <sha256:...> --revocation-digest <sha256:...> --ledger-arquivo <ledger.ndjson> --expected-head <sha256:...> --saida <manifest.json> --json
+```
+
+`--trust-root-digest` and `--revocation-digest` may also come from the
+externally controlled `SEMA_CONTENT_TRUST_ROOT_DIGEST` and
+`SEMA_CONTENT_REVOCATION_DIGEST` environment variables. If a value is present
+in both sources, the values must match. `registrar`, `status`, and `projetar` also require the
+externally retained `expectedHead`, including the genesis head for a new
+ledger. This protects against stale concurrent append and detects truncation;
+it does not turn a runner-controlled file into protected storage.
+
+## External runner protocol
+
+The runner may schedule, execute, retry, resume, and request more AI capacity.
+It may submit signed envelopes and report operational conditions. It may not
+write calculated verdicts, mark an execution complete, edit canonical history,
+or promote its own claim to accepted evidence.
+
+The runner advances only from `nextActions` derived by Sema. There is no native
+human-approval transition. Organizations may build an external policy adapter
+for human input if they need one, but that is outside this AI-native pipeline
+and never a hidden fallback.

package/docs/profiles.md

@@ -21,6 +21,7 @@ When a profile returns `bloqueado: true`, the artifact is not approved.
 ```bash
 sema profile capabilities --json
 sema profile validar software contratos/example.sema --maturidade production --preset default --json
+sema profile validar simulation contratos/example.sema --maturidade production --preset calibration --json
 sema rule-packs --profile software --json
 ```
 
@@ -32,8 +33,8 @@ sema rule-packs --profile software --json
 - `legal`: terms, privacy, compliance, risk, and regulated language.
 - `research`: comparisons, uncertainty, evidence, citations, and decisions.
 - `game`: rules, loops, player states, scoring, and playability checks.
-- `author`: creative writing, narrative continuity, cliche review, and style
-  guardrails.
+- `simulation`: models, assumptions, units, scenarios, calibration, uncertainty,
+  deterministic replay, and tolerance evidence.
 - `redacao`: editorial and creative writing, narrative structure, voice,
   clarity, and publication-ready evidence.
 - `propostas`: commercial proposals, scope clarity, deliverables, constraints,
@@ -43,3 +44,11 @@ sema rule-packs --profile software --json
 
 Profiles are local CLI checks. They do not create or require external service
 accounts.
+
+`author` remains a dedicated workflow under `sema author`; it is not exposed as
+a fake `sema profile validar author` gate. Use `sema descobrir explicar workflow.author`
+to inspect that boundary.
+
+The legacy `sema profile capabilities` view lists only profiles accepted by
+`profile validar`; its separate `workflowsEspecializados` field points Author
+to `sema author` without advertising an invalid validation command.