Artifact Compatibility

Supported Versions

STAGE 0.6 tooling validates project manifests declared as 0.1 or 0.3 and case-study records declared as 0.1, 0.3, or 0.4. The method release and artifact schema versions are separate: applying the 0.6 Safety Kernel does not require creating or migrating a manifest.

• schemas/*-v0.1.schema.json are frozen compatibility schemas.
• schemas/stage-project-v0.3.schema.json and schemas/stage-case-study-v0.4.schema.json are the current exact schemas for their artifact families.
• case-study 0.4 adds an explicit player-experience hypothesis, human playtest, categorical dimensions, and expansion gate while retaining 0.3 validation for existing studies.
• unversioned schema files point to the current schema for new tooling.
• command-line validators select the exact schema from the artifact's declared version.

The installed stage-map-project skill packages the supported project-map schemas, the read-only project-map validator, and the read-only repository snapshot helper used by adoption and external-audit work. Explicit project-map migration remains available only from a STAGE repository checkout. Case-study schemas, validators, refreshers, and operation-preflight tooling remain Maintainer Laboratory surfaces rather than a bundled general CLI.

For these installed read-only operations, observing Git state does not refresh the inspected repository index. The commands disable optional Git locks and automatic diff index refreshes rather than relying on the target's local Git configuration. Their preservation claim remains limited to the source-state scope declared by the snapshot receipt; it is not a whole-filesystem claim.

External project-map review metadata has a narrower comparison boundary than the snapshot helper: repository identity, branch, HEAD, dirty state, and Git status-record count. Its validator reports those as review coordinates and does not imply that dirty-path content was fingerprinted.

The packaged project-map validator also carries its exact Python dependency ranges. The supported operation boundary is therefore "without a STAGE repository checkout on the declared Python environment," not "without host runtime dependencies." Codex plugin installation does not install Python, PyYAML, or jsonschema. Missing dependencies produce a nonzero result and an install command that points to the packaged declaration; they must not be reported as a successful formal validation.

The declared human-readable project map is confined to the map artifact root. Parent traversal and symlinks that resolve outside that root are invalid even when the external file exists; a map cannot satisfy its contract by borrowing an unrelated host file.

Declared target paths, whether exact or wildcard, resolve only through tracked or non-ignored untracked project files in the inspected repository. Ignored cache state and symlinks escaping the target cannot satisfy a project-map declaration merely because they exist on the current machine.

Project-map wildcards are case-sensitive and segment-aware. *, ?, and bracket expressions do not cross /; a segment that is exactly ** matches zero or more complete path segments. This keeps a direct-child declaration such as schemas/*.json from being accidentally satisfied by a nested file, while recursive declarations such as src/**/*.cs include both direct and nested source files.

Generated ownership may declare an output family that is absent from the checkout, but its source must be a safe repository-relative expression that resolves in the inspected target and its regeneration operation must name a declared operation. A nullable schema field does not waive this semantic reproducibility check.

The former detached visual evidence pipeline is not a supported public contract. Its request, capture-plan, manifest, review, baseline, comparison, receipt, contact-sheet, migration, and validation interfaces were retired in 0.3 after dogfood showed no real consumer for their compatibility cost. Git history preserves the implementation and rejected trial. Projects remain free to produce screenshots, videos, visual baselines, or CI comparisons through their own engine-native tooling; STAGE does not prescribe their package shape.

The former Visual Almanac capability-manifest family is also retired. Versions 0.1 through 0.4, the unversioned alias, templates, and validator are preserved in Git history but are not accepted by current STAGE tooling. No runtime or independent tool consumed the format, and ordinary project maps already record native routes, operations, ownership, evidence, and limitations. Projects may retain an old local file as historical documentation, but current guidance is to move useful facts into the normal project map and operating docs and then delete the duplicate artifact.

The pre-1.0 stage-visual-almanac and stage-visual-review skills are retired. Visual work now enters through ordinary change delivery. The later optional gallery recipes were retired under ADR 0038 because a justified codex, gallery, world previewer, or inspect mode is an ordinary project feature, not a STAGE artifact family. No dedicated skill, manifest, dual-mode UI, or common runtime architecture is implied.

The Solo Unity profile-assessment and attestation experiment is likewise not a supported public contract. Its assessment versions, status renderer, human and operational forms, gate-resolution records, and milestone manifests duplicated direct Unity and source evidence without performing the checks they described. They were retired under ADR 0028. Dependency catalogs, bootstrap plans, guarded source transfer, and direct test/build evidence remain supported because each has a concrete project operation or artifact consumer.

The Solo Unity slice-charter experiment is also retired. Its schema, preparer, validator, and trial charters duplicated the normal STAGE delivery plan while binding product decisions to a dependency-plan hash. Existing projects should move any useful state, lifecycle, ownership, and acceptance notes into their ordinary plan or optional feature brief, then delete the charter. Bootstrap plans remain supported as read-only dependency-selection artifacts. ADR 0029 records the decision.

The generic normalized Unity test receipt is retired under ADR 0030. Its schema and capture tool copied Unity Test Framework results without a named downstream consumer. Use the complete native Unity result directly and record durable pass counts and limits in the ordinary change or study. A future CI, release, analytics, or publishing consumer should own the smallest adapter it actually needs rather than depending on the retired universal format.

The clean post-commit Unity dependency-provenance receipt is retired under ADR 0031. Exact owner-source transfer now closes at the receipt-bound staged checkpoint, which can still detect unrelated staged paths and Git/LFS byte transformations before commit. Historical exact-source conclusions remain in the trials and Git history; the retired verifier is not a current audit API.

Migration

Migration is optional. A valid supported 0.1 project map or case study does not become invalid because a newer contract exists. Former detached visual evidence artifacts and visual capability manifests are historical records, not inputs accepted by current STAGE tooling.

There is no replacement visual manifest migration. Preserve native subjects, recurring questions, human and agent routes, actual native state and playback semantics, settings, lifecycle, evidence, and limitations in the existing project map and operating docs. Then validate the project map and verify the engine behavior separately.

scripts/migrate_project_map.py writes a separate 0.3 candidate by default. It preserves legacy owner values, maps only unambiguous manual/runtime/legacy authority, and marks other authority unresolved. Migrated operation safety and effects are conservative and require review. Before publication, the command requires the source to satisfy the immutable 0.1 schema and the transformed candidate to satisfy the exact 0.3 schema. It refuses to replace an existing candidate unless --force is explicit and publishes the completed YAML atomically.

The command refuses to overwrite the source manifest unless --in-place is explicitly supplied. In-place migration may change YAML comments and formatting and should be used only from a clean checkpoint.

For the stable artifact commands, exit 0 is the only success disposition. A nonzero exit means the requested validation or migration result was not produced; diagnostics are written to standard error. Callers must not interpret a particular nonzero value as a stable machine-readable failure taxonomy.

External refreshes replace each draft file atomically and restore the prior map and manifest when publication fails. This is failure consistency for one refresh process, not a concurrent-reader transaction. Refreshes require the target to be its Git work-tree root, reject a trial root inside that target, and require a clean target by default. They reject a source branch, revision, status, adopted map, or adopted manifest that changes before publication. Git worktrees are supported. Dirty-state counts follow Git porcelain records, with a rename or copy counted once. If a target has no origin, pass the same stable identifier to refresh_external_trial.py --source-repository and validate_project_map.py --source-repository; local absolute paths should not be committed as public provenance.

Compatibility Promise

Within the 0.x line:

• validators will not silently rewrite artifacts;
• exact project-map and case-study schemas remain available for adopted maps and recorded studies;
• experimental artifact families may be retired before 1.0 when dogfood shows that they have no real consumer; retirement requires an ADR, migration or deletion guidance, and a changelog entry;
• breaking field or vocabulary changes require a new declared artifact version, migration guidance, and changelog entry;
• project-specific extension fields remain allowed where the schema says so.

This is a pre-1.0 compatibility policy because STAGE's public contract is still in initial development. A 1.0.0 release requires an explicit public-contract inventory, stable compatibility and migration decisions, and owner acceptance. Independent adoption is reported separately as transferability evidence.