Artifact Compatibility

Supported Versions

STAGE 1.0 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 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

The owner accepted this contract and authorized the 1.0.0 release on September 27, 2026. The readiness review records that decision.

Stable 1.x Surface

Surface	Compatibility commitment throughout 1.x
Safety Kernel	Preserve S1–S8's obligations, human authority, truthful evidence, and optional-contract semantics
Plugin identity and routes	Preserve stage-game-engineering, implicit stage-deliver-change, and explicit-only stage-orient, stage-verify, and stage-map-project
Project maps	Preserve exact schemas 0.1 and 0.3, declared-version selection, permitted extensions, and explicit migration
Installed map validation and snapshots	Preserve validate_project_map.py and repository_snapshot.py, their existing commands, flags, successful report fields, and declared read-only source-state boundary
Orientation and verification inventory	Preserve orient_project.py and verify_change.py, existing flags and successful fields, truthful observation failure, valid unborn/detached states, and documented first-parent/root comparison
Repository-backed migration	Preserve migrate_project_map.py's separate candidate by default, explicit replacement flags, source/candidate validation, and human-value preservation

Exit 0 remains the only success disposition for these commands. Documented orientation conflict and verification inconclusive results remain available; other diagnostic wording and particular nonzero exit values are not a general machine-readable error API. New optional fields may be added without removing or changing existing successful fields. Callers should tolerate additions.

Compatible corrections use patch releases; compatible capabilities use minor releases. Breaking a stable interface requires a major release, an explicit decision, migration guidance, and a changelog entry. Never silently rewrite an adopted artifact. A safety correction may reject input that was accepted only because a validator failed to enforce its existing contract; document that correction and cover it with a regression. Do not use that exception to silently change a valid declared schema or weaken preservation.

Keep older supported schemas throughout 1.x. Historical case-study schemas 0.1, 0.3, and 0.4 also remain available unchanged for recorded evidence; that does not freeze the entire research-tool CLI as a practitioner API. Artifact versions remain separate from the plugin and method versions.

Maintained Guidance And Support

Exact wording, recommended step names, examples, templates, reference layout, optional board labels, engine profiles, and model selection are maintained guidance. They may improve without a major release while preserving the stable obligations and interfaces. There is no required game architecture or model.

The exercised support baseline is the owner's macOS, Codex, Git, and Python 3.11 workflow; release records identify actual versions and checks. Packaged map validators retain their declared dependency ranges. Installation does not supply Python or an engine. Other environments need their own evidence. This is a personal maintainer commitment throughout the 1.x line, without a fixed calendar support term or response-time service promise.

Mapping, Unity bootstrap, and research tooling receive correctness, compatibility, and maintenance support. New capabilities need a named present consumer. Internal helper modules and laboratory orchestration are not a new installed STAGE CLI. Human documentation links remain stable through retained pages or redirects.

Historical 0.x Policy

Before 1.0, the following policy applied:

• 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.

Independent adoption is reported separately as transferability evidence, not inferred from the accepted compatibility commitment above.

0.7 Delivery And Helper Corrections

Installing plugin 0.7.0 does not create or rewrite game-project artifacts. Project migration is optional. The plugin identity, four skill names, command names and arguments, successful report fields, and exact supported schema validation remain unchanged. Templates, prose, packaged reference layout, and optional attention-board labels are maintained guidance, not machine interfaces.

Orientation now returns nonzero with conflict and a diagnostic when Git state cannot be observed. Verification inventory returns nonzero with inconclusive and a diagnostic when observation fails. Neither represents failure as clean state or an empty successful inventory. Missing upstream, unborn branches, and detached HEAD remain valid states. Committed-revision inventory compares with the first parent, includes all introduced paths for an initial commit, and reports the comparison mode explicitly, including merges.

External refresh rejects linked output ancestors and destinations overlapping the protected target; it preserves earlier external outputs after publication failure and reports unexpected target changes without restoring concurrent work. Unity bootstrap rejects linked manifests and linked project-relative ancestors before mutation. These are correctness fixes to preservation promises, not new artifact versions. See the candidate release record.