Projection outcomes and diagnostics

✓exact

The target represents the canonical intent faithfully, with no information left behind.

⇄adapted

The same intent, delivered through a different native mechanism — a procedure exported as a skill, for example.

!lossy

Some canonical meaning cannot be represented. A lossy mapping must carry at least one diagnostic explaining what was lost.

✕blocked

The projection would be unsafe or invalid, so nothing is written for that entity.

–skipped

Deliberately excluded: documentation-only, a human audience, disabled, excluded by a profile, or removed as a duplicate.

stemma explain shows a single entity's projection for one target: its activation, where it was imported from, whether a profile touched it, the outcome, the destination and the reason.

Get an entity ID from stemma plan --target codex --explain, then replace the example ID below with one from your own project.

stemma explain context.api-layer-conventions --target codex

context.api-layer-conventions  (context)  title:        API layer conventions  target:       codex  activation:   paths src/api/**, src/handlers/**  imported from: .github/instructions/api.instructions.md (github-copilot, parsed)                lines 1-11  profile:      no override  outcome:      lossy  destination:  AGENTS.md  reason:       No single directory could be derived from src/api/**, src/handlers/**,                so the content stays in the root AGENTS.md and is no longer scoped.  est. tokens:  ~24 (approximate)Capability decisions for codex  always-on instructions:      yes  path-scoped instructions:    yes  include glob patterns:       no  exclude glob patterns:       no  multiple include patterns:   no  directory-scoped delivery:   yes  native skills:               yes  native specialist agents:    no  native procedures/prompts:   no

The same entity compiled for Claude Code is exact, because paths: front matter can carry both patterns. That difference between targets, made visible per entity, is the point of the command.

A code, a severity of info, warning or error, a one-line summary, and optionally a detailed explanation, a source path, a line and column, a canonical entity id, a target and a suggested resolution. It also carries blocking and a stable fingerprint.

The fingerprint is derived from code, severity, path, entity id and target — deliberately not from prose — so improving a message never invalidates an acceptance recorded in a profile. Diagnostics are sorted deterministically and de-duplicated in both human and JSON output.

Once you have reviewed a mapping and decided the loss is acceptable, list its fingerprint in the target profile. Accepted diagnostics are downgraded to info and stop blocking apply — but they stay visible. Acceptance is not suppression.

{  "schemaVersion": 1,  "target": "codex",  "overrides": {},  "acceptedDiagnostics": ["dg_184cf4cbcf883cfa"]}

Fingerprints come from stemma plan --target <target> --json. Replace the example fingerprint with the one you reviewed, and merge it into the existing profile without discarding overrides or earlier acceptances. Re-run the plan and check --warnings-as-errors for that target after generating its reviewed output.

STEMMA4302 is reported at import, when the canonical project cannot be compiled back into a source file byte-for-byte. It is a warning: the import is still saved, but that file is left unowned, so a later attempt to overwrite it is a STEMMA4301 conflict.

STEMMA4303 is a warning during import when replacing the canonical project revokes a destination's ownership and the new import does not re-establish it. It names the path and target; the provider file stays untouched. An identical re-import preserves ownership, and normal edits to .stemma/ followed by apply also preserve it.

STEMMA4301 reports a later write conflict. A destination Stemma has neither written nor verified is foreign, as is one whose ownership was revoked by a project replacement; --adopt-untracked authorizes replacing those files after review. The flag does not bypass an external edit to a tracked file or a source that failed STEMMA4302. Preserve those edits or reconcile the unverified source first. Adopting a file Stemma does not own covers exactly which states the flag changes.

Accepting a fingerprint does not change any of this. Acceptance downgrades a projection diagnostic you have reviewed; it is not a way to authorize a write over a file whose ownership was never established.

Diagnostic codes are part of Stemma's public contract: human wording may improve, codes do not change after release, and numbers are never reused.

How exit codes map onto these families is covered in workflow and CI.