docs(architecture): tighten review and roadmap consistency

docs/ARCHITECTURE_REVIEW_AND_REUSE_ROADMAP.md

@@ -37,6 +37,17 @@ When making implementation decisions, prefer this ordering:
 - **DRY discipline:** Partial
 - **Readiness for multi-agent parallel work:** Moderate, but currently too dependent on scaffolds
 
+# 0.2 What This Document Does Not Claim
+
+This document does **not** claim that:
+
+- web and mobile are already fully integrated with the product backend
+- shared services are already production-verified for this repo
+- DTO contracts are already unified across all surfaces
+- the current roadmap set is a substitute for implementation verification
+
+It is a corrective architecture review and execution guide, not a claim of completion.
+
 # 1. Executive Summary
 
 This repo is on the right architectural path, but it is not yet fully aligned with the original plan or the ByteLyst workspace best practices.
@@ -557,6 +568,15 @@ The phases below should be executed in order because later cleanup depends on ea
 - Phase E can run in parallel with late Phase C / Phase D once contracts stabilize
 - Phase F should harden the final architecture rather than leading it
 
+## Cross-Workstream Dependency Rule
+
+To avoid duplicate work or rework:
+
+- backend contract decisions should precede broad web/mobile contract cleanup
+- identity/config cleanup should precede auth, telemetry, diagnostics, and storage work
+- shared-service wiring decisions should precede large UI polish efforts that depend on those services
+- any proposal to move code into `learning_ai_common_plat` should include evidence that at least one other product repo can reuse it
+
 ## Phase A — Identity and Config Consolidation
 
 ### Goal

docs/roadmaps/08_ARCHITECTURE_REUSE_MASTER_ROADMAP.md

@@ -21,6 +21,19 @@ This roadmap tracks the execution work required to bring `learning_ai_notes` int
 - [ ] platform concerns come from shared `@bytelyst/*` packages or shared services where appropriate
 - [ ] product-specific notes logic remains local to this repo
 
+# Baseline Already Confirmed
+
+- [x] Repo shape follows the expected product-repo layout (`backend/`, `web/`, `mobile/`, `docs/`, `shared/`)
+- [x] Product-specific backend modules are local to this repo rather than pushed into `platform-service`
+- [x] The repo already consumes multiple `@bytelyst/*` packages across surfaces
+
+# Dependency Notes
+
+- [ ] Complete R0 before broad auth/storage/telemetry changes
+- [ ] Complete R1 before calling web/mobile runtime alignment complete
+- [ ] Use backend contract decisions as the source of truth for R2 contract cleanup
+- [ ] Use the platform/shared-services roadmap for cross-cutting service wiring decisions
+
 # Phase R0 — Identity and Boundary Lock
 
 - [ ] Confirm `shared/product.json` is the canonical product identity source
@@ -71,6 +84,7 @@ This roadmap tracks the execution work required to bring `learning_ai_notes` int
 - [ ] route-level mock data sources
 - [ ] DTO contract definitions
 - [ ] platform integration wiring
+- [ ] roadmap truth-alignment versus implementation reality
 
 # Done When
 

docs/roadmaps/09_BACKEND_REUSE_ALIGNMENT_ROADMAP.md

@@ -10,23 +10,29 @@ Keep the backend strongly product-specific for notes domain logic while maximizi
 
 # Preserve As Product-Local
 
-- [ ] `notes` module remains local
-- [ ] `workspaces` module remains local
-- [ ] `note-relationships` module remains local
-- [ ] `note-tasks` module remains local
-- [ ] `note-artifacts` module remains local
-- [ ] `note-agent-actions` module remains local
+- [x] `notes` module remains local
+- [x] `workspaces` module remains local
+- [x] `note-relationships` module remains local
+- [x] `note-tasks` module remains local
+- [x] `note-artifacts` module remains local
+- [x] `note-agent-actions` module remains local
 
 # Shared Package Alignment
 
-- [ ] Continue using `@bytelyst/auth`
-- [ ] Continue using `@bytelyst/config`
-- [ ] Continue using `@bytelyst/cosmos`
-- [ ] Continue using `@bytelyst/datastore`
-- [ ] Continue using `@bytelyst/errors`
-- [ ] Continue using `@bytelyst/fastify-core`
-- [ ] Continue using `@bytelyst/logger`
-- [ ] Continue using `@bytelyst/testing`
+- [x] Continue using `@bytelyst/auth`
+- [x] Continue using `@bytelyst/config`
+- [x] Continue using `@bytelyst/cosmos`
+- [x] Continue using `@bytelyst/datastore`
+- [x] Continue using `@bytelyst/errors`
+- [x] Continue using `@bytelyst/fastify-core`
+- [x] Continue using `@bytelyst/logger`
+- [x] Continue using `@bytelyst/testing`
+
+# Dependency Notes
+
+- [ ] Finalize backend contract decisions before broad web/mobile DTO cleanup
+- [ ] Use this roadmap to define what must stay local before proposing any common-plat extraction
+- [ ] Coordinate blob/extraction/MCP decisions with the platform/shared-services roadmap
 
 # Phase B0 — Identity and Config Alignment
 
@@ -58,11 +64,11 @@ Keep the backend strongly product-specific for notes domain logic while maximizi
 - [ ] Review request tracing and error behavior against workspace standards
 - [ ] Replace raw stdout/stderr startup output with shared logger patterns if practical
 
-# Non-Goals
+# Guardrails
 
-- [ ] Do not move notes-specific modules into `platform-service`
-- [ ] Do not create shared abstractions that only benefit this one product
-- [ ] Do not over-generalize the notes domain into common platform prematurely
+- Do not move notes-specific modules into `platform-service`
+- Do not create shared abstractions that only benefit this one product
+- Do not over-generalize the notes domain into common platform prematurely
 
 # Done When
 

docs/roadmaps/10_WEB_REUSE_ALIGNMENT_ROADMAP.md

@@ -8,6 +8,12 @@ Scope: `web/`
 
 Make the web app the strongest notes authoring/operator surface while ensuring that shared platform concerns come from common ByteLyst packages and services rather than repo-local duplication or long-term scaffold behavior.
 
+# Baseline Already Confirmed
+
+- [x] `web/` follows the intended web-app direction for this product repo
+- [x] `web/package.json` already consumes several shared `@bytelyst/*` packages
+- [x] shared design-token usage is already part of the current web architecture
+
 # Phase W0 — Identity and Config Alignment
 
 - [ ] Align `web/src/lib/product-config.ts` with `shared/product.json`
@@ -18,12 +24,18 @@ Make the web app the strongest notes authoring/operator surface while ensuring t
 
 # Phase W1 — Auth and Platform Reuse
 
-- [ ] Keep `@bytelyst/react-auth` as the auth provider foundation
-- [ ] Keep `@bytelyst/platform-client` as the platform-service client foundation
-- [ ] Keep `@bytelyst/telemetry-client` as telemetry foundation
-- [ ] Keep `@bytelyst/diagnostics-client` as diagnostics foundation
+- [x] Keep `@bytelyst/react-auth` as the auth provider foundation
+- [x] Keep `@bytelyst/platform-client` as the platform-service client foundation
+- [x] Keep `@bytelyst/telemetry-client` as telemetry foundation
+- [x] Keep `@bytelyst/diagnostics-client` as diagnostics foundation
 - [ ] Remove demo-first auth behavior once real auth integration is stable
 
+# Dependency Notes
+
+- [ ] Complete W0 before removing demo-first auth behavior
+- [ ] Use backend route contracts as the source of truth for W2 and W4
+- [ ] Coordinate shared component reuse decisions with the platform/shared-services roadmap
+
 # Phase W2 — Replace Runtime Mock Paths
 
 - [ ] Replace dashboard runtime mock data with backend-backed data

docs/roadmaps/11_MOBILE_REUSE_ALIGNMENT_ROADMAP.md

@@ -8,6 +8,12 @@ Scope: `mobile/`
 
 Make the React Native / Expo MVP follow the ByteLyst reuse-first path more strictly by removing temporary local wrapper code and relying on shared clients and shared platform capabilities wherever available.
 
+# Baseline Already Confirmed
+
+- [x] mobile follows the intended Expo / React Native MVP path
+- [x] `mobile/package.json` already consumes multiple shared `@bytelyst/*` packages
+- [x] `@bytelyst/offline-queue` is already part of the current mobile direction
+
 # Phase M0 — Identity and Config Alignment
 
 - [ ] Align mobile config with `shared/product.json`
@@ -17,12 +23,19 @@ Make the React Native / Expo MVP follow the ByteLyst reuse-first path more stric
 
 # Phase M1 — Shared Client and SDK Alignment
 
-- [ ] Keep `@bytelyst/auth-client` as auth foundation
-- [ ] Keep `@bytelyst/api-client` as product-backend client foundation
-- [ ] Keep `@bytelyst/platform-client` as platform-service client foundation
-- [ ] Keep `@bytelyst/offline-queue` as queue foundation
+- [x] Keep `@bytelyst/auth-client` as auth foundation
+- [x] Keep `@bytelyst/api-client` as product-backend client foundation
+- [x] Keep `@bytelyst/platform-client` as platform-service client foundation
+- [x] Keep `@bytelyst/offline-queue` as queue foundation
 - [ ] Evaluate actual runtime adoption path for `@bytelyst/react-native-platform-sdk`
 
+# Dependency Notes
+
+- [ ] Complete M0 before broad auth/storage cleanup
+- [ ] Complete M2 before declaring mobile reuse alignment healthy
+- [ ] Use backend contract decisions to drive M3 data-shape cleanup
+- [ ] Coordinate telemetry/diagnostics/blob/extraction choices with the platform/shared-services roadmap
+
 # Phase M2 — Remove Placeholder Local Wrappers
 
 - [ ] Delete or replace `mobile/src/lib/platform.ts`

docs/roadmaps/12_PLATFORM_SHARED_SERVICES_ALIGNMENT_ROADMAP.md

@@ -10,19 +10,30 @@ Ensure `learning_ai_notes` uses shared ByteLyst platform packages and shared ser
 
 # Core Shared Inputs
 
-- [ ] `platform-service`
-- [ ] `extraction-service`
-- [ ] `mcp-server`
-- [ ] `@bytelyst/auth`
-- [ ] `@bytelyst/api-client`
-- [ ] `@bytelyst/platform-client`
-- [ ] `@bytelyst/react-auth`
-- [ ] `@bytelyst/telemetry-client`
-- [ ] `@bytelyst/diagnostics-client`
-- [ ] `@bytelyst/offline-queue`
-- [ ] `@bytelyst/design-tokens`
+- [x] `platform-service`
+- [x] `extraction-service`
+- [x] `mcp-server`
+- [x] `@bytelyst/auth`
+- [x] `@bytelyst/api-client`
+- [x] `@bytelyst/platform-client`
+- [x] `@bytelyst/react-auth`
+- [x] `@bytelyst/telemetry-client`
+- [x] `@bytelyst/diagnostics-client`
+- [x] `@bytelyst/offline-queue`
+- [x] `@bytelyst/design-tokens`
 - [ ] `@bytelyst/dashboard-components`
 
+# Baseline Interpretation
+
+- [x] Checked items above mean the dependency/service is already part of the intended architecture or current dependency graph
+- [ ] Unchecked items above mean the dependency is expected but not yet confirmed as adopted in this repo
+
+# Dependency Notes
+
+- [ ] Identity alignment must precede telemetry/diagnostics/header verification
+- [ ] Platform-service and extraction-service decisions should precede broad UI claims of readiness
+- [ ] Shared package adoption should not be described as complete until runtime wiring is verified
+
 # Phase P0 — Identity and Package Alignment
 
 - [ ] Verify product identity is consistent across all shared-client usage