[BW-DOC-01] Establish canonical documentation index and roadmap #14
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Classification
Active plan / documentation-only.
Problem / opportunity
BookWave's implementation has moved faster than several of its planning and architecture documents. Detailed historical files are still valuable, but some are now presented as current authority even after their plans completed or architecture changed. Fresh implementation workers can therefore follow stale closeout plans, obsolete test instructions, contradictory architecture notes, or historical reviews as if they were the current backlog.
User / project value
Create one reliable documentation entry point and one canonical roadmap so a fresh implementation chat can determine what is current, what is planned, what is experimental, and what is historical without reconstructing months of Git history.
Scope
docs/README.mdas the documentation entry point and status taxonomy.docs/roadmap.mdas the only canonical answer to "what work comes next?".docs/architecture/playback.mdto consolidate lasting playback contracts after the recent playback architecture work, while preserving detailed bug/ADR evidence elsewhere.README.mdso it no longer presentsdocs/closeout.mdas the live work list or describes project state in misleadingly final terms.PRODUCT_SPEC.mdexplaining that accepted ADRs may deliberately supersede baseline requirements and the roadmap owns post-baseline work.docs/handover.md,docs/closeout.md,docs/gaps.md, old version-specific device tests, dated reviews, and resolved bug investigations without deleting useful engineering history.main, including dependency verification/locking state, current module boundaries, and completed repository-boundary debt.docs/risks.md; retain closed-risk reasoning and PR/ADR closure links.docs/android-auto-player-opportunities.mdanddocs/comparison-absorb.mdas experiment/research rather than roadmap commitments.docs/dependency-upgrade-plan.mdas an active child plan whose sequence is subordinate to the canonical roadmap.docs/testing.mdthe current testing authority and clearly mark historical/version-specific device instructions.Explicitly out of scope
Dependencies
None. This can run alongside the committed PR chain. Documents describing GitHub #78/GitHub #93 must clearly distinguish pending PR state from
mainuntil those PRs merge.Architecture seams affected
Documentation only, but it must accurately describe
:app,:playback,:domain,:core:*, and:data:*boundaries, repository ownership, playback/session ownership, and current build/dependency verification architecture.Server / API assumptions
None changed. Any API or platform statement retained as current must be cross-checked against code/ADRs and, for platform behavior, current official documentation where appropriate.
Storage / migration implications
None.
Privacy / security
No runtime change. Documentation must preserve existing privacy/security reasoning, especially profile boundaries, diagnostic redaction, Recents privacy, and risk closure history.
Automated-test level
Docs-only review. Verify internal links/status references and cross-check every statement presented as current against
main. No application tests should be required unless an existing docs check is part of the repository gate.Device / platform acceptance
None. Historical device evidence must remain labeled as device evidence and not be upgraded to platform contract.
Estimated effort
Medium.
Implementation risk
Low runtime risk; medium documentation risk because incorrectly reclassifying evidence could lose important engineering context.
Recommended sequence
Start now. Complete before creating many more roadmap documents/issues so new work links to a stable authority.
Current committed work that must remain intact
Acceptance criteria
docs/README.md.docs/roadmap.mdis the sole canonical "what next" list.README.mdno longer points at historical closeout material as current planning authority.main.