[BW-DOC-01] Establish canonical documentation index and roadmap #14

Closed
opened 2026-09-18 08:45:33 +02:00 by alexander · 0 comments
Owner

Migrated from GitHub issue #103. Forgejo issue: #14. GitHub source content synchronized on 2026-09-19. Migrated issue references below use Forgejo numbers where an equivalent issue exists; historical references without a Forgejo counterpart remain explicit GitHub links.

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

  • Create docs/README.md as the documentation entry point and status taxonomy.
  • Create docs/roadmap.md as the only canonical answer to "what work comes next?".
  • Create docs/architecture/playback.md to consolidate lasting playback contracts after the recent playback architecture work, while preserving detailed bug/ADR evidence elsewhere.
  • Update repository-level README.md so it no longer presents docs/closeout.md as the live work list or describes project state in misleadingly final terms.
  • Add status/authority guidance to PRODUCT_SPEC.md explaining that accepted ADRs may deliberately supersede baseline requirements and the roadmap owns post-baseline work.
  • Reclassify 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.
  • Correct current architecture docs against main, including dependency verification/locking state, current module boundaries, and completed repository-boundary debt.
  • Update relevant ADR headers/status metadata without rewriting their historical reasoning: especially ADR-0013, ADR-0016, ADR-0027, and cross-reference ADR-0029 when GitHub #78 lands.
  • Register missing risk R-103 in docs/risks.md; retain closed-risk reasoning and PR/ADR closure links.
  • Mark docs/android-auto-player-opportunities.md and docs/comparison-absorb.md as experiment/research rather than roadmap commitments.
  • Mark docs/dependency-upgrade-plan.md as an active child plan whose sequence is subordinate to the canonical roadmap.
  • Make docs/testing.md the current testing authority and clearly mark historical/version-specific device instructions.

Explicitly out of scope

  • No application feature implementation.
  • No behavior changes.
  • No merging of GitHub #78, GitHub #93, GitHub #86, or GitHub #98.
  • No deletion of useful historical reasoning simply to reduce file count.
  • No module restructuring.
  • No rewriting accepted ADR reasoning to make history look cleaner.

Dependencies

None. This can run alongside the committed PR chain. Documents describing GitHub #78/GitHub #93 must clearly distinguish pending PR state from main until 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.

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

  1. GitHub #78 — Android Auto/routing finalization
  2. GitHub #93 — unified resume freshness
  3. GitHub #86 — Appearance inline controls
  4. GitHub #98 — Playback settings UI refresh

Acceptance criteria

  • A fresh contributor can locate the current product contract, architecture, ADRs, risk register, testing authority, active roadmap, active child plans, experiments, and history from docs/README.md.
  • docs/roadmap.md is the sole canonical "what next" list.
  • README.md no longer points at historical closeout material as current planning authority.
  • Current architecture docs agree with main.
  • R-103 exists in the risk register.
  • Completed/superseded plans remain available as historical evidence but cannot be mistaken for active work.
  • Resolved bugs/reviews are clearly marked as snapshots/evidence.
  • No application code or behavior changes are included in the PR.
> Migrated from [GitHub issue #103](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/103). Forgejo issue: #14. GitHub source content synchronized on 2026-09-19. Migrated issue references below use Forgejo numbers where an equivalent issue exists; historical references without a Forgejo counterpart remain explicit GitHub links. ## 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 - Create `docs/README.md` as the documentation entry point and status taxonomy. - Create `docs/roadmap.md` as the only canonical answer to "what work comes next?". - Create `docs/architecture/playback.md` to consolidate lasting playback contracts after the recent playback architecture work, while preserving detailed bug/ADR evidence elsewhere. - Update repository-level `README.md` so it no longer presents `docs/closeout.md` as the live work list or describes project state in misleadingly final terms. - Add status/authority guidance to `PRODUCT_SPEC.md` explaining that accepted ADRs may deliberately supersede baseline requirements and the roadmap owns post-baseline work. - Reclassify `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. - Correct current architecture docs against `main`, including dependency verification/locking state, current module boundaries, and completed repository-boundary debt. - Update relevant ADR headers/status metadata without rewriting their historical reasoning: especially ADR-0013, ADR-0016, ADR-0027, and cross-reference ADR-0029 when [GitHub #78](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/78) lands. - Register missing risk R-103 in `docs/risks.md`; retain closed-risk reasoning and PR/ADR closure links. - Mark `docs/android-auto-player-opportunities.md` and `docs/comparison-absorb.md` as experiment/research rather than roadmap commitments. - Mark `docs/dependency-upgrade-plan.md` as an active child plan whose sequence is subordinate to the canonical roadmap. - Make `docs/testing.md` the current testing authority and clearly mark historical/version-specific device instructions. ## Explicitly out of scope - No application feature implementation. - No behavior changes. - No merging of [GitHub #78](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/78), [GitHub #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/93), [GitHub #86](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/86), or [GitHub #98](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/98). - No deletion of useful historical reasoning simply to reduce file count. - No module restructuring. - No rewriting accepted ADR reasoning to make history look cleaner. ## Dependencies None. This can run alongside the committed PR chain. Documents describing [GitHub #78](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/78)/[GitHub #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/93) must clearly distinguish pending PR state from `main` until 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 1. [GitHub #78](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/78) — Android Auto/routing finalization 2. [GitHub #93](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/93) — unified resume freshness 3. [GitHub #86](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/86) — Appearance inline controls 4. [GitHub #98](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/98) — Playback settings UI refresh ## Acceptance criteria - A fresh contributor can locate the current product contract, architecture, ADRs, risk register, testing authority, active roadmap, active child plans, experiments, and history from `docs/README.md`. - `docs/roadmap.md` is the sole canonical "what next" list. - `README.md` no longer points at historical closeout material as current planning authority. - Current architecture docs agree with `main`. - R-103 exists in the risk register. - Completed/superseded plans remain available as historical evidence but cannot be mistaken for active work. - Resolved bugs/reviews are clearly marked as snapshots/evidence. - No application code or behavior changes are included in the PR.
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
alexander/Audiobookshelf-Manager-Claude#14
No description provided.