Roadmap to v1.0: stable Workshop tooling platform

[Teakowa]

Goal

Define Wright's path to 1.0 by stable product capabilities, semantic ownership, and verified user workflows rather than internal migration phases, feature counts, or a manually maintained progress ledger.

Product direction

Wright is the unified tooling/product layer over independently owned Workshop language engines. Product priority is:

1. check / diagnostics
2. lint / static analysis
3. inspect / semantic query
4. validated source edits / refactoring
5. agent / embedding workflows
6. CI / language services
7. Workshop stability / cost analysis
8. compilation / conversion where required by real workflows

Compiler and conversion work are product-enabling infrastructure, not the sole progress metric. A Wright surface must not claim language behavior beyond what its owning implementation actually supports.

Ownership and dependency rules

• Raw Workshop semantics, canonical Program/WIR behavior, catalog, settings, localization, validation, emission, and Workshop-domain facts belong to workshop-rs.
• OPY syntax, preprocessing/macros, project loading, semantics, HIR, diagnostics/source mapping, lowering, compiler behavior, and scoped reconstruction belong to opy-rs.
• DEL/OSTW project loading, syntax/type/runtime semantics, HIR, diagnostics/source mapping, lowering, compiler behavior, and scoped reconstruction belong to deltin-rs.
• Wright owns cross-language diagnostics, lint/analyze/inspect, validated-edit product behavior, CLI/LSP/agent surfaces, embedding, CI, and orchestration.
• language-provider-protocol owns the provider process/data contract, not source-language or Workshop semantics.
• Missing semantics must be fixed in the owning repository rather than approximated or duplicated in Wright.

Cross-repository work follows:

owning repo -> owner contract/tests -> consumable release or revision -> consumer integration -> representative workflow verification

Readiness model

Surface area is not support. A command, adapter, parser entry point, README claim, or isolated passing test does not establish a capability by itself.

Readiness depends on the workflow:

• check / inspect require correct loading, parsing, semantic resolution, diagnostics, and source locations for the declared scope; they do not require a complete compiler.
• lint / analyze require the semantic information their claims depend on, but not necessarily complete emission.
• compile requires an end-to-end owner path from source semantics through canonical Workshop validation/emission.
• conversion/reconstruction is a separate capability and must be validated independently from parsing, checking, or forward compilation.

Compatibility is capability-specific. Observable semantic correctness is always required. An owning language engine may additionally define a stricter compiler-output contract, such as canonical structural convergence with a pinned reference implementation; Wright consumes that owner contract rather than redefining it.

Source transformation

• Source mutation follows semantic understanding -> validated source edits -> original source; full-file regeneration is not the default editing model.
• Preserve comments, trivia, formatting, and unrelated source whenever practical.
• Unsafe or unsupported edits must fail explicitly rather than fall back to destructive textual rewriting.
• Workshop -> OPY/DEL reconstruction targets semantic equivalence and useful recoverable structure, with explicit information-loss boundaries rather than literal source recovery.

Verification

Tests are the primary durable verification mechanism.

Use the smallest verification surface appropriate to the claim:

• focused unit/regression tests for local behavior;
• compatibility/differential tests against pinned reference implementations where external behavior matters;
• integration/real-project tests for interactions not economically covered by focused tests;
• runtime/client validation only for claims that cannot be established statically;
• source mapping/source-location checks for diagnostics and validated editing.

Fixtures, corpora, snapshots, goldens, and reference outputs are test-support mechanisms, not parallel project-status or verification databases. Current support claims must reflect current implementation and tests.

Wright 1.0 product contract

Wright 1.0 is ready when users can rely on it as a stable Workshop tooling platform with:

• cross-platform installation and update;
• stable declared check, lint, analyze, inspect, source-edit/fix, and agent/embedding contracts;
• canonical raw Workshop parsing, validation, analysis inputs, and emission through workshop-rs;
• independently usable OPY and DEL/OSTW owner implementations for the source-language scopes Wright declares supported;
• compilation/conversion only where the owning implementation and Wright integration have actually established the declared scope;
• validated source-oriented mutation with explicit refusal for unsafe operations;
• stable CI and machine-readable diagnostic/tool contracts;
• source locations/mapping preserved where a product claim depends on authored-source attribution;
• reviewed licensing and distribution boundaries;
• user documentation that describes supported workflows without requiring knowledge of internal compiler architecture.

1.0 does not require every possible OPY/DEL feature, reconstruction path, seasonal live-client run, or speculative future tool to be complete. It requires declared public contracts and supported workflows to be intentionally stable and truthful.

Roadmap dependency order

The durable dependency order is:

real workflow need -> root owner capability -> tests -> integration when needed -> representative workflow validation -> supported Wright product capability

At the ecosystem level:

1. Engine readiness — make workshop-rs, opy-rs, and deltin-rs correct for the real workflows their declared scopes depend on.
2. Wright convergence — expose those owner capabilities consistently through check/lint/analyze/inspect/edit/CLI/LSP/provider surfaces without semantic fallbacks.
3. Advanced tooling — expand agent contracts, richer validated edits, stability/cost analysis, reconstruction/conversion, and additional language-service breadth as their dependencies become ready.

This is dependency-driven, not a rigid release-phase sequence. Higher-level work may proceed earlier when its actual prerequisites already exist.

Planning rules

• Real user workflows outrank roadmap neatness, support-matrix completion, documentation volume, feature counts, or architecture cleanup.
• Fix root capabilities in the owning implementation before integration-layer workarounds.
• Inspect existing tests before adding new ones; protect observable behavior and meaningful failure modes rather than incidental implementation details.
• Do not weaken diagnostics, validation, compatibility expectations, or tests to make CI pass.
• Keep near-term executable work in owner Issues. Keep this roadmap focused on durable product, ownership, readiness, and prioritization contracts.
• Do not split catalog-scale work into per-symbol Issues.
• Infrastructure, protocol, release, or cleanup work is justified when it unlocks or protects a concrete workflow.

Non-goals

• Maintaining a current-progress dashboard in this Issue body.
• Encoding transient release versions, active blockers, current child-Issue state, or near-term execution ordering here.
• Treating roadmap completion, Issue closure, README claims, or historical CI results as proof that a capability is currently supported.
• Replacing owner-specific language or compatibility contracts with Wright-side policy.

Current execution state must be rebuilt from live Issues/PRs, current code/tests, CI/releases, and representative workflow validation.

[Teakowa]

Current execution roadmap — 2026-09-10

The structural reorganization and first OPY provider product milestone are complete enough that neither is on the feature critical path. Near-term development remains concentrated on wright and opy-rs; deltin-rs feature development remains paused.

Current reality after direct live-state recheck:

• Make Wright CLI CI-ready for real Workshop and OverPy projects #242 is completed. The real-project Wright milestone now has completed provider-backed OPY check, compile, lint, and analyze evidence on Bastion and Overwatch-AI-PVE.
• Converge source-language workflows on an explicit provider boundary #243/Run real OPY check and compile workflows through the first-party provider #245/Preserve Wright lint and analyze semantics across the OPY provider boundary #246 are completed. Provider-backed inspect remains explicitly unsupported by the feat(driver): run OPY lint and analyze through provider #304 implementation and is the next demonstrated cross-boundary tooling gap.
• Analyze persistent Workshop object lifecycle and fan-out #262 is completed through PR feat: analyze persistent Workshop object lifecycle #308. Wright now exposes persistent HUD text, in-world text, and effect lifecycle/fan-out facts through the persistentObjects semantic/tool query without promoting weak cleanup heuristics to built-in lint.
• Define an extensible analysis and lint rule contract #309 is now open as the concrete next lint/static-analysis extension contract, motivated by Analyze persistent Workshop object lifecycle and fan-out #262/feat: analyze persistent Workshop object lifecycle #308: keep canonical facts in Wright, keep built-in lint thin, and allow bounded project/community policy through a declarative Workshop-shaped YAML rule format.
• Converge residual OPY compiler and canonical-WIR gaps opy-rs#157 remains open. PR fix(conformance): honor semantic oracle references opy-rs#238 corrected semantic-oracle handling and the resulting full offline conformance baseline is 46 match / 15 divergence / 2 inconclusive. No OPY feature PR is currently open; opy-rs 0.1.29 is released.
• Wright 0.2.22 is staged in release PR chore(main): release 0.2.22 #305 and includes feat(driver): run OPY lint and analyze through provider #304, fix(provider): make OPY bootstrap concurrency-safe #307, and feat: analyze persistent Workshop object lifecycle #308; the release PR is still open/pending.

Active execution order:

1. Advance Define an extensible analysis and lint rule contract #309 as the current lint / static-analysis product lane, but keep the implementation bounded by the concrete Analyze persistent Workshop object lifecycle and fan-out #262 consumer evidence. Do not turn YAML into a general-purpose query language or introduce plugin/package infrastructure.
2. Create the next executable provider-backed inspect / semantic-query work from the demonstrated feat(driver): run OPY lint and analyze through provider #304 limitation. Preserve source-language ownership: OPY-specific semantic queries belong in opy-rs; Wright owns cross-language product/query orchestration and must not consume provider-private IR.
3. Advance Converge residual OPY compiler and canonical-WIR gaps opy-rs#157 in parallel from the corrected conformance baseline. Classify each remaining divergence by demonstrated root ownership before implementation; Workshop-owned gaps continue to route to workshop-rs.
4. Move into provider-driven validated source edits through Wire provider-driven mutation through Wright product surfaces #156 after the semantic-query boundary is reliable and the owning source-language implementation exposes the required mutation/validation capability. Preserve semantic understanding -> validated source edits -> original source; no textual fallback or default whole-file regeneration.
5. Build agent/embedding workflows on top of the semantic-query and validated-edit surfaces. Dynamic Workshop/OPY context and best-practice loading should consume those stable facts rather than create a parallel semantic system.
6. Keep Remove residual static OPY implementation after provider cutover #155 available as now-unblocked post-cutover cleanup, but do not move it ahead of user-visible feature work unless residual static OPY implementation materially interferes with the active product path.
7. Keep release/CI optimization (Publish the GitHub Release only after verified R2 staging #293 and related work), reconstruction/conversion, broad API hardening, and additional structural cleanup as parallel operational/backlog lanes unless they directly block active workflows.
8. Keep deltin-rs implementation and DEL provider work paused until explicitly resumed.

Active focus: extensible lint/static analysis -> inspect/semantic query -> validated source edits -> agent tooling, with opy-rs#157 running in parallel as owner-side compatibility convergence. Real-project/tooling evidence remains the priority signal.