Roadmaps
Roadmaps remain useful working documents. The docs app should index them, summarize stable decisions, and extract durable reference material only when it has stopped moving quickly.
Planning Ownership And Location
Section titled “Planning Ownership And Location”New ephemeral roadmaps and task graphs belong in repository-root planning/<workstream>/, grouped by the bounded feature or workstream. Use roadmap.md, an optional existing mentor roadmap, and one canonical graph as complementary views; individual issues extend those surfaces instead of generating their own note documents. planning/README.md indexes their paths and lifecycle. Event Details has moved to planning/event-details/; other existing roadmaps are grandfathered in apps/wavemap-docs/working-notes until a scoped migration is useful. Scratch experiments may remain in working-notes. Neither location is published automatically.
The product repository owns its graph and stable graph/node identities. Tracker issue IDs, team prefixes, assignments and publication payloads are mappings to external coordination tools, not graph identity. Keep decisions, dependency meaning, proof gaps and links to reviewed evidence readable without requiring a tracker account. Update current source paths when moving files; preserve historical publication payloads and fingerprints, with a path mapping for readers.
Retention And Lifecycle
Section titled “Retention And Lifecycle”- Keep one canonical graph per workstream and retain it by default after completion. Record an explicit lifecycle (
active,completed,supersededorabandoned), review date, owner, and completion/disposition explanation. Closed tracker issues do not automatically close or delete the graph. - Keep active indexes concise. On closure, update the index and roadmap to show the outcome, remaining proof or carried-forward work, and successor links where applicable. Moving a completed directory is optional; completion alone requires no archive copy or storage service.
- Use Git commits as near-term versioned snapshots at reviewed planning and implementation milestones. Record the source revision when evidence depends on a particular state. Preserve stable node IDs, dependency rationale, accepted decisions and historical publication evidence; do not generate a duplicate graph per ticket or commit.
- When scope is superseded, link predecessor and successor identities and explain what was carried forward, completed or intentionally dropped. Archive history remains context, not standing permission for new actions.
- Graduate reusable explanations into curated documentation and trim duplicated prose from the active roadmap. Retain the reviewed decomposition and decision trail in the graph and Git history so trimming does not erase why the work was organized that way.
- Local work-pass receipts have a separate runtime retention policy; their expiry must never delete canonical planning history.
Compressed bundles and cold storage are deferred until volume or retrieval cost warrants them. A future design should preserve graph/schema versions, decisions, source revisions, evidence references and tracker mappings in a checksummed bundle, keep a searchable manifest in the repository, and prove restoration before deleting any accessible source. This policy introduces no compression job, bucket or automated deletion.
Current Sources
Section titled “Current Sources”planning/event-details/roadmap.mdplanning/event-details/mentor-roadmap.mdplanning/event-details/issue-graph.yaml
The following paths are relative to apps/wavemap-docs and remain grandfathered:
working-notes/FUTURE_FEATURES_ROADMAP.mdworking-notes/DEV_DEPLOYMENT_AND_CD_ROADMAP.mdworking-notes/CI_CD_MODERNIZATION_ROADMAP.md(closed acceptance record)working-notes/AUTH_PUSH_ROADMAP.mdworking-notes/EVENT_TIME_ARCHITECTURE_ROADMAP.md(foundation exit record)working-notes/EVENTS_UX_ROADMAP.mdworking-notes/VENUES_UX_ROADMAP.mdworking-notes/VENUE_ADDRESS_MODELLING_ROADMAP.mdworking-notes/MAP_ARCHITECTURE_ROADMAP.mdworking-notes/COMPONENT_ARCHITECTURE_SWEEP_ROADMAP.mdworking-notes/COMPONENT_LIBRARY_EXTRACTION.mdworking-notes/WAVEMAP_COMPONENT_POLISH_AUDIT.md- App-local feature roadmaps under the front-end app.
Extraction Policy
Section titled “Extraction Policy”- Keep implementation checklists in roadmaps while they are active.
- Move stable decisions into admin, developer architecture, testing, release, or operations/platform pages.
- When roadmap content becomes redundant with settled docs-site content, strip the roadmap back to actionable future work.
- After promotion, roadmaps should keep only remaining tasks, open questions, blockers, proof still needed, and links to the durable reference page.
- Use ADRs to track durable decisions that may eventually need full decision records.
- Keep roadmap links close to the extracted pages so the live planning trail remains discoverable.
- Avoid turning the docs app into a second roadmap tracker.
Current Graduation Map
Section titled “Current Graduation Map”Use this map before copying from a roadmap into another roadmap or into a new docs page. When a durable home already exists, update that page for stable reference and trim the roadmap back to the next action.
| Roadmap Area | Durable Home | Roadmaps Should Still Own |
|---|---|---|
| Monorepo shape and cross-app feature flow | Monorepo Map and Feature Slice Workflow | New package/app boundaries that are still being tested in active work. |
| Auth, route access, and permission patterns | Authentication And Authorization and Admin Content Model | Browser-runtime hardening, future profile/MFA work, and admin/permissions UX follow-through. |
| Testing layers, commands, runtime contracts, and smoke posture | Testing and Local Development Runtime | Built-app Playwright migration, browser-safe backend paths, and future smoke-promotion decisions. |
| i18n resources, runtime, assets, and guardrails | i18n, Contributor Workflows, and Guardrails | Branch-specific localization sweeps, unsettled verifier ideas, and future app/runtime consumers. |
| Media architecture and validation lanes | Media Storage And Delivery and Media Workflow And Validation | Real-cloud media proof, discrepancy-report scheduling decisions, Azure continuity, and future ingest derivatives. |
| Public entity identity, canonical URLs, and DTO IDs | Public Entity Identifiers | Event/venue/series detail-route canonicalization, user handles, and global resolver decisions. |
| Lifecycle, provenance, ownership seams, and audit vocabulary | Content Entity Governance | Event time modeling, soft-delete rollout, ownership implementation, and full audit-trail implementation. |
| Relationship modeling, query controls, URL state, and saved views | Domain Relationships, Query Controls And Browsing State, and Front End State | The reusable EntityRelationshipSheet contract and relationship-row lifecycle/provenance decisions. |
| Event time, schedule ownership, and integrity repair | Event Scheduling Architecture, Admin Event Scheduling, and Event Schedule Integrity | Full-fidelity authoring and public presentation UX, venue/address migration, recurrence, hierarchy, and corpus capture. |
| Deployed-dev, CD, infrastructure, runbooks, and recovery | Operations / Platform and its focused orientation, deployment, lifecycle, runbook, and recovery pages | Workflow-update triggers, environment profiles, backup/restore proof, and later-environment gates. |
| Public CLI, typed operations, and shell-script conventions | Wavemap CLI, Wavemap CLI Command Reference, and Shell Scripting Conventions | Generated command-reference source decisions and future cross-environment command-profile work. |
| Component-library source distribution and reusable UI boundaries | Front End Components today, plus a future focused component-library/source-distribution page if the Amino workflow becomes contributor-facing reference. | CLI lifecycle behavior, public registry/package policy, compatibility-bridge retirement, and second-consumer proof. |
| Wavemap component module architecture and cleanup sequencing | Front End Components for module, calibration, controller, workflow, subsystem, and extraction boundaries. | The live component inventory, representative-slice decisions, family status, exceptions, and verification evidence. |
| Docs site, release identity, ADRs, and generated docs | Docs Content Model, Release And Versioning, ADRs, and Generated Documentation | Release-note policy, docs previews/versioning, generated API docs, and full ADR promotion triggers. |
Next Promotion Candidates
Section titled “Next Promotion Candidates”These are not automatic new pages. Promote them when the implementation pattern or operating rule has stopped moving fast enough that future contributors need reference more than branch history.
Use the readiness tier to decide whether the next action is writing reference, gathering proof, or leaving the topic in working notes.
Ready To Distill
Section titled “Ready To Distill”There are no component-architecture candidates in this tier. The reusable ownership and module/calibration boundaries have been distilled into Front End Components; the active sweep remains a working note until its family-specific implementation patterns have repeated evidence.
Recently Distilled
Section titled “Recently Distilled”| Candidate | Durable Home | Still Owned By Working Notes |
|---|---|---|
| Component module and calibration boundaries | Front End Components for thin TSX orchestration, pure and hook-backed calibration, controllers, workflows, subsystem ownership, and extraction review. | The live Wavemap component inventory, representative-slice checkpoints, family propagation status, exceptions, and branch-specific proof. |
| Component-library extraction proof workflow | Amino UI docs-site pages for source graph receipt, adapter boundaries, consumer proofs, registry contracts, ingest packets, local snapshots, consumer lifecycle, and fixture evidence. | Branch-specific command logs, per-component proof chronology, compatibility bridge experiments, raw lockfile hash evidence, and CLI lifecycle implementation checklists. |
Waiting On Proof
Section titled “Waiting On Proof”These topics already have likely durable homes, but the docs should wait for evidence from implementation, repeated runs, or a settled operating shape.
| Candidate | Needed Before Promotion | Likely Home |
|---|---|---|
| Environment profiles | More than one command or environment depends on a stable profile shape for account, region, stack, lifecycle, and destructive-operation posture. | Configuration And Secrets, Deployment Workflows, or a future focused operations page. |
| Expanded auth browser smoke | Browser-safe auth routing, stable non-text selectors, deterministic account/session fixtures, cleanup, and useful failure artifacts. | Testing and Authentication And Authorization. |
| Backup/restore learning drill | Real commands, artifact location, disposable restore target, validation evidence, and restore friction have been recorded. | Data Durability And Recovery and Runbooks. |
| Amino CLI lifecycle commands | update --advisory, update --dry-run, safe remove / delete, focused diff, and eject have fixture evidence and settled mutation policy. | A future component-library CLI reference page or a focused developer workflow page. |
Keep In Notes
Section titled “Keep In Notes”These topics still need product shape, cross-surface proof, or a stronger source-of-truth decision before they should become reference material.
| Candidate | Keep In Notes Until | Likely Home |
|---|---|---|
| Full-fidelity event page UX | Events Index, Event Details, Add Event, and Edit Event are implemented from reviewed designs and the stats dashboard has a separately oriented page roadmap. | Event Scheduling Architecture, related front-end guidance, and focused admin pages. |
| Admin authoring and permissions UX | Content authoring, role display, permission editing, audit, or moderation surfaces exist as product workflows. | Admin Content Model or focused admin pages. |
| Entity relationship management shell | The EntityRelationshipSheet contract is proven beyond one surface and its assignment, pagination, metadata, and permissions boundaries are stable. | Domain Relationships and Front End Components. |
| Generated CLI reference source | Route contracts, root scripts, wrapper metadata, or a dedicated manifest becomes the clear source of truth. | Wavemap CLI Command Reference and Wavemap CLI. |
| Public Amino registry/package policy | Registry hosting, package publication, compatibility bridge retirement, generated token writers, and Waveguide consumption are deliberately opened. | Future component-library operations or release docs. |
| Full ADRs | A focused reference page no longer preserves enough tradeoff history for a durable cross-cutting decision. | ADRs. |
Keep In Working Notes
Section titled “Keep In Working Notes”Keep these outside the curated docs site until a reviewer intentionally promotes a sanitized summary:
- Branch-specific implementation checklists and sequencing notes.
- Proof history, failed attempts, and raw command evidence.
- Raw cloud inventory, Pulumi exports, workflow logs, provider identifiers, and other private operational artifacts.
- Unsettled questions where the project still needs options, not reference.
- App-local feature notes until the pattern matters outside the owning route or package.
- Detailed route, handler, or component inventories when a curated page already summarizes the stable boundary.