Skip to content

docs(roadmap): reconcile root v2 status with native roadmap and Core migration ledger #559

Description

@qnbs

Context

WorldScript Studio intentionally has multiple planning/evidence documents with different scopes:

  • root ROADMAP.md — high-level product/v2 direction;
  • TODO.md — current operational/sprint/human tasks;
  • docs/native/ROADMAP-QT-GPUI-DESKTOP.md — binding native renderer strategy/admission gates;
  • docs/native/CORE-MIGRATION-LEDGER.md — living capability-by-capability Core authority state;
  • focused ADRs/issues — detailed implementation authority.

The current root roadmap contains status wording that can drift behind the living native/Core documents. In particular, broad statements equivalent to Rust Core prerequisite work being “not yet started” are no longer precise once the Core Migration Ledger records multiple CI-proven or in-progress Rust proofs/adapters.

This issue owns documentation truth reconciliation only so roadmap readers do not infer a contradictory execution state.

Goal

Make planning documents form a hierarchy of truth rather than competing roadmaps:

ROOT ROADMAP
  = strategic product direction / milestone summary

NATIVE ROADMAP
  = binding Qt/GPUI admission sequence

CORE MIGRATION LEDGER
  = live capability authority/evidence state

GITHUB ISSUES
  = executable durable work owners

TODO
  = current operational/human checklist

Each higher-level document should link to the lower-level live authority instead of duplicating volatile details unnecessarily.

Required audit

Review at minimum:

Issue/PR-number hygiene

Do not rely on historical shorthand like #NNN = topic without checking the live GitHub object.

Issue and PR numbers share the repository namespace and older planning notes can become misleading if a remembered number actually refers to a merged/closed PR or a different subject.

Where roadmap docs cite a numbered object, verify:

current title
issue vs pull request
open/closed/merged state
actual scope

Prefer descriptive link text plus the number when ambiguity matters.

Status vocabulary

Use a small consistent status vocabulary, for example:

PLANNED
PROOF / SHADOW
IN PROGRESS
ADMISSION GATED
PRODUCTION AUTHORITY
DEFERRED
DONE

Do not call a capability “implemented” merely because a shadow Rust proof exists, and do not call it “not started” when CI-proven migration work already exists.

For Qt/GPUI preserve the binding native-roadmap distinction:

  • Qt = primary native target after Core admission gates;
  • GPUI = deferred/exploratory, not a current numbered implementation commitment;
  • Tauri = transitional until acceptance/retirement gates are met;
  • PWA = independent first-class product surface.

TODO relationship

TODO.md may intentionally contain operational or human-only actions that do not deserve durable engineering issues, such as manual release checks or external badge/account registration.

Do not mechanically convert every TODO checkbox into a GitHub issue. Instead, ensure durable architecture/product work points to an issue/roadmap owner and transient operational work remains clearly classified.

Acceptance criteria

Non-goals

  • implementing any roadmap capability in this docs issue;
  • starting Qt or GPUI;
  • rewriting all historical handoff/archive documents;
  • converting every TODO item into an issue;
  • using documentation edits to declare unresolved issues complete;
  • creating a second master roadmap that would itself drift.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions