STAGE 1.0 Readiness Review

Status: candidate owner review; 1.0.0 has not been declared

Last reviewed: 2026-07-24

Decision Boundary

STAGE 1.0.0 should mean that the owner accepts a small, stable interface for personal game engineering and is willing to maintain its compatibility through the 1.x line. It should not mean that STAGE is scientifically proven, independently adopted, optimal, universally transferable, or complete.

This review is a release decision aid, not a conformance score. Mechanical checks can establish repository consistency. They cannot decide whether the method is useful enough to freeze or whether its maintenance cost is acceptable to the owner.

Recommended Owner Disposition

Recommendation: accept the proposed contract and release 1.0.0. No known mechanical defect currently blocks the personal-use contract. In this context, 1.0.0 means “the owner is willing to keep these few interfaces compatible,” not “the method is proven, complete, or generally superior.”

Decision	Recommendation	Maintenance accepted through 1.x
Stable owner contract	Accept	Preserve the eight Safety Kernel obligations, one implicit delivery route, three explicit companion routes, truthful evidence boundary, and explicit artifact migration semantics
Project-map schemas	Keep both 0.1 and 0.3	Continue validating four historical 0.1 trial maps and current 0.3 maps; author new maps as 0.3; never extend 0.1 in place
Installed operations	Accept the narrow split	Keep validation and read-only snapshots in the plugin; keep explicit migration repository-backed; do not promote the Maintainer Laboratory into a general CLI
Support boundary	Accept	Support the owner's exercised macOS, Codex, Git, and Python 3.11 workflow; describe other hosts and platforms as best-effort unless directly evidenced
Release decision	Accept only by explicit owner statement	Rerun the full gate at the final candidate, update metadata, install the release, and record the installed probe

The compatibility cost is deliberately bounded. Exact prose, examples, templates, case-study authoring tools, trials, the Solo Unity profile, and experimental operations are not stable APIs. The retained 0.1 project-map schema is a 2.7 KB frozen validator input, not a second active authoring model; removing it would invalidate preserved artifacts while saving little ongoing design work.

Proposed 1.x Contract

Stable Owner Contract

The following surfaces are candidates for the compatibility promise:

Surface	Proposed stable meaning	Excluded from compatibility
Core specification	The eight Safety Kernel obligations, optional-contract semantics, truthful reporting rules, and stated non-goals in SPEC.md	Exact explanatory wording and examples
Codex plugin identity	Package name stage-game-engineering; implicit primary stage-deliver-change; explicit-only stage-orient, stage-verify, and stage-map-project companions	Exact prompt prose, launcher copy, and model-specific behavior
Project maps	Project-map schema versions 0.1 and 0.3, declared-version validation, and explicit migration	Formatting, comments, project extensions, and generated prose
Artifact compatibility	No silent rewrites; supported older artifacts remain valid; breaking field or vocabulary changes use a new artifact version and migration guidance	Experimental artifact families already retired before 1.0
Installed project-map operations	The explicit mapping skill packages immutable supported schemas, validate_project_map.py, and repository_snapshot.py; their documented purposes, required inputs, 0-only success semantics, target-read-only defaults, and source-state comparison behavior remain available	Exact templates and examples, incidental output wording, snapshot JSON shape, specific nonzero exit values, and internal implementation
Repository project-map migration	migrate_project_map.py retains its documented purpose, explicit replacement flags, atomic candidate publication, and 0-only success semantics from a STAGE repository checkout	Distribution with the installed plugin, incidental output wording, specific nonzero exit values, and internal implementation

The installed mapping skill packages the two read-only operations, exact schemas, and declared Python dependency ranges it needs to perform an adoption or external audit without a STAGE repository checkout. The host still supplies Python 3.11 and the declared PyYAML/jsonschema environment; plugin installation does not provision a Python runtime or virtual environment. It does not expose a general STAGE CLI or package schema migration. Explicit 0.1 to 0.3 migration remains a repository-backed owner operation because it is rare, review-bearing, and separately authorized. The operation-preflight command remains useful maintainer tooling but is not required by the installed plugin or documented as a normal practitioner entry point. The recommended 1.0.0 boundary leaves it outside the stable owner interface until a real project consumer requires that compatibility promise.

Maintained Guidance, Not A Stable API

The delivery loop, task-evidence matrix, visual-work guidance, engine profiles, reference architecture, adoption menu, failure atlas, and Solo Unity profile should remain maintained documentation. They may be corrected, reorganized, or simplified compatibly without treating every prose change as an API break.

The Solo Unity dependency catalog, recipes, and bootstrap/source-transfer tools serve the owner's current workflow. They are optional personal tooling, not a required STAGE stack and not part of the proposed 1.x interoperability promise. Their safety properties and destructive boundaries still require tests and truthful release notes.

Maintainer Laboratory And Historical Evidence

Repository gates, test runners, release helpers, snapshots, semantic hashes, external-trial refreshers, behavior probes, trials, fixtures, case-study schemas and validators, and study runners are Maintainer Laboratory surfaces. They may evolve with the repository as long as they continue to validate the owner contract they claim to check. Exact case-study schemas remain frozen for the historical records that declare them, but that archival obligation does not turn research authoring into a practitioner-facing 1.x API.

Historical ADRs, release notes, retired schemas, rejected visual-rehearsal artifacts, and failed or inconclusive studies remain evidence. Their existence does not make their old interfaces supported in 1.x.

Proposed 1.x Compatibility Policy

If accepted, the 1.x line should use these rules:

1. A breaking change to the stable owner contract requires 2.0.0.
2. Compatible new capability uses a minor release; compatible corrections use a patch release.
3. Project-map schemas 0.1 and 0.3 remain valid throughout 1.x. New project-map capability uses a new declared schema version rather than changing an existing exact schema in place. Historical case-study records remain readable in the STAGE repository, but their authoring schema is not a stable practitioner interface.
4. A stable owner interface may be deprecated in a minor release but is not removed before the next major release. A safety or security defect may force earlier removal, with explicit migration guidance and release notes.
5. Validators never silently rewrite project artifacts. Migration remains an explicit, separately reviewable operation that preserves human decisions; replacing the source or an existing candidate requires a distinct flag.
6. Exact skill prose is not an API. Skill behavior may be clarified while the named route, authority boundary, preservation rules, and truthful evidence contract remain compatible.
7. Maintainer Laboratory and personal-profile internals may change without a major release, but releases must not represent those changes as stable practitioner compatibility.

Proposed Support Boundary

The first stable release should support the environment actually exercised by the owner rather than claiming an untested platform matrix:

• the installed Codex plugin on the owner's current Codex desktop/CLI workflow;
• packaged and repository Python operations on Python 3.11 with the declared dependency ranges; plugin installation itself does not create that runtime;
• Git repositories on the owner's current macOS workflow; and
• Unity guidance and optional personal tooling as source-visible reference material, with exact Unity, package, platform, and visual acceptance owned by each game project.

Other operating systems, agent hosts, models, engines, and team workflows are best-effort unless a release record names direct evidence for them. External maps and operational studies may support bounded transferability claims, but do not silently expand this support boundary.

Release Gates

Gate	Current status	What closes it
Public-contract inventory	Candidate defined above	Owner accepts or corrects the proposed stable surfaces
Compatibility and migration policy	Candidate defined above	Owner accepts the 1.x rules and they are promoted into canonical compatibility guidance
Support boundary	Candidate defined above	Owner accepts the personal-use platform and toolchain boundary
Critical defect review	Mechanical review, installed 0.6.11 routing evidence, and the complete 443-test release gate passed in a disposable committed candidate clone on 2026-07-29; a 1.0 candidate rerun remains required	Full release gate and direct package validation pass at the eventual 1.0 candidate revision; open failures are fixed or explicitly deferred
Release metadata	Available	Version, specification, README, changelog, release note, tag, and installed-plugin refresh are updated together
Owner acceptance	Pending and non-delegable	Owner explicitly chooses to freeze the contract as 1.0.0

Explicit Non-Gates

The following evidence would improve understanding but does not block a stable personal-use release:

• another maintainer;
• independent adoption;
• a productivity improvement claim;
• a cross-team workflow;
• support for every game engine or operating system;
• a maturity score;
• a visual-review package, gallery, contact sheet, or capture protocol; and
• repeatable or durable owner-readiness status.

Those remain separate evidence dimensions. They must not be implied by the release number.

Owner Decisions

Before 1.0.0, the owner should answer only these compatibility-bearing questions. The recommendation above is not acceptance on the owner's behalf.

1. Accept the proposed stable contract, or name a surface to add or remove.
2. Accept support for project-map schemas 0.1 and 0.3 throughout 1.x.
3. Accept the packaged validation and snapshot operations, the separate repository-backed migration command, and keeping case-study validation, operation preflight, and Solo Unity tooling outside a bundled general CLI.
4. Accept the owner-macOS, Codex, and Python 3.11 support boundary.
5. After the critical defect review, explicitly accept or defer 1.0.0.

Until those decisions are recorded, STAGE remains a 0.6 initial-development release even when all mechanical checks pass.

An unambiguous owner response can be one line:

Accept the proposed STAGE 1.x contract and release 1.0.0.

To change or defer it instead:

Accept except: <specific contract correction>.
Defer 1.0 because: <specific owner concern>.

Current Mechanical Evidence

The initial readiness review passed 255 tests across 26 test modules. The installed 0.6.5 candidate passed 264 tests across the same 26 modules. The 0.6.6 source candidate passed 274 tests across 27 modules. The 0.6.7 release candidate passed 292 tests across 27 modules, every supported study and map, frozen compatibility fingerprints, the Solo Unity profile, repository links, structured files, and diff hygiene. The 0.6.8 candidate passed 303 tests across the same 27 modules plus those repository-level checks. The 0.6.9 candidate passed 306 tests after adding direct target-index preservation regressions for validation, snapshots, and external refreshes. The post-0.6.9 source candidate passed 347 tests across the same 27 modules after project-map operation, evidence, ownership, provenance, and preflight hardening. The post-0.6.10 source candidate passed 398 tests across 29 modules after shared structured-data model enforcement, atomic-publication portability and metadata preservation, and release-gate cleanliness hardening. The current 0.6.11 source candidate passes 443 tests across 37 modules after adding the explicit orientation and verification workflows, deterministic helper coverage, and the derived human-documentation consumer. The current Codex plugin validator and all four skill validators also passed. A disposable local clone containing a commit of the complete candidate passed the repository release gate, including physical package completeness, schemas, studies, maps, the Solo Unity profile, links, and documentation discovery. The source package contains only the four declared workflows. Installed-version evidence belongs to the release record because an open Codex task retains the skill snapshot with which it started.

Proposed stable surface	Current mechanical guard	Remaining judgment
Safety Kernel and optional contracts	test_core_workflow_routing.py checks the eight named obligations, finite optional contracts, bounded requirement language, and explicit mapping route	Whether the obligations are useful and small enough to freeze
Plugin identity and routing	test_plugin_packaging.py, test_core_workflow_routing.py, and the current Codex package validators check the four-workflow package, explicit-only companions, and launcher metadata	Whether this is the owner’s desired long-term invocation surface
Project-map schemas 0.1 and 0.3	Frozen SHA-256 fingerprints plus template, adopted-map, external-audit, path, provenance, ownership, and operation-reference validation	Whether both versions should remain supported for all of 1.x
Historical case-study records	Frozen SHA-256 fingerprints plus template, historical-study, immutable-revision, and maintainer-review validation protect current repository evidence	How the Maintainer Laboratory may evolve without rewriting historical conclusions
Installed project-map operations	Package parity and real subprocess tests cover exact schemas, truthful success/failure, read-only validation, unchanged-target snapshots, and preservation of the target Git index	Whether their narrow purpose and invocation flags should be frozen for 1.x
Repository project-map migration	Real subprocess tests cover exact source and candidate schema validation, all four preserved 0.1 trial maps, explicit replacement, atomic publication, and failed-output absence	Whether this rare owner operation should remain supported throughout 1.x
Repository release gate	check_repository.py --scope release composes all 443 tests and repository-level artifact, link, profile, and diff checks	Product usefulness, human acceptance, and release timing

No open GitHub issue or source TODO, FIXME, HACK, XXX, or BUG marker identified a known critical release defect. This is a bounded mechanical review, not a warranty. The same gates must run again against the actual release candidate, and the owner still decides whether any known product or workflow limitation is critical enough to defer 1.0.

A fresh installed-0.6.6 ordinary-delivery probe also passed the proposed artifact-free route: implicit skill selection produced only the requested source, test, and documentation diff, ran the focused suite, created no STAGE artifact, and did not commit. This supports route availability, not treatment effect or general model behavior. The corresponding installed mapping dogfood is recorded in the 0.6.6 release evidence. The installed 0.6.7 mapping commands also passed a clean-environment packaging probe: validation succeeded, before-and-after snapshots matched, and a nested repository target failed closed. That supports the packaged command boundary, not map completeness or workflow efficacy. The installed 0.6.8 commands repeated that probe after the snapshot hardening: the adopted map validated, receipts declared the git_source_state scope and matched at the release revision, and a nested target again failed closed. This narrows packaging and boundary uncertainty; it does not add independent-adoption or productivity evidence. The installed 0.6.9 commands then repeated the package probe against a disposable release clone with deliberately stale tracked-file metadata. Validation and scoped snapshot comparison passed, the nested target failed closed, and the exact target index bytes remained unchanged. This directly exercises the corrected read-only boundary without broadening its stated source-state scope. The installed 0.6.10 cache repeated that fixed-revision probe after the operation, ownership, and provenance hardening. Its validator accepted the adopted map, scoped snapshots matched, a nested target failed closed, and the clean clone's Git index hash remained byte-identical despite deliberately stale tracked-file metadata. This confirms packaging of the current candidate; it does not add independent-adoption, usefulness, or productivity evidence. The installed 0.6.11 cache added a bounded explicit-orientation probe. A fresh ephemeral Codex process injected the qualified stage-orient skill, loaded its bundled helper from the versioned cache, inspected the dirty STAGE tree read-only, and stopped with continuity-gap. That confirms this route's installed availability and stopping behavior in one consumer invocation; it does not establish universal routing reliability or replace owner acceptance.