Roadmap/Documentation To-Do

Scope: Remaining tasks to finalize and maintain the roadmap and supporting documentation (non-code features unless noted).

Tasks

• Set up CI link validation for roadmap docs

  • Priority: High
  • Owner: TBD
  • Description: Add a GitHub Actions workflow to run scripts/validate_links.py on pull requests that change roadmap/**/*.md. Fail the check on broken links or anchors.
  • Acceptance Criteria:
    • Workflow triggers on PRs touching roadmap/**
    • Job fails when script exits non-zero
    • Passing status required to merge

• Capture performance baselines and record in docs

  • Priority: High
  • Owner: TBD
  • Description: Run scripts/perf_baseline.sh against staging/production URLs; commit reports under reports/performance/. Summarize PSI/LCP/INP/CLS results in current-state.md and Phase A KPIs.
  • Acceptance Criteria:
    • Baseline reports exist for home, article, category pages
    • current-state.md updated with dated metrics
    • Phase A KPIs section references baseline and targets

• Export Phase Highlights and Roadmap to PDF and add guidance

  • Priority: Medium
  • Owner: TBD
  • Description: Add a short “How to export to PDF” section in PHASE_HIGHLIGHTS.md (pandoc/VSCode) and commit exported PDFs for exec sharing (docs/exports/).
  • Acceptance Criteria:
    • Export instructions present
    • PDFs committed for PHASE_HIGHLIGHTS.md and roadmap.md

• Expand OpenAPI spec and add server contract tests

  • Priority: Medium
  • Owner: TBD
  • Description: Enrich roadmap/api/openapi.yaml with error models, auth refresh flows, pagination meta and headers. Add CI contract tests to validate server responses against the spec.
  • Acceptance Criteria:
    • Spec includes errors, pagination meta, and token refresh endpoints
    • CI contract test job passes against a mock or dev server

• Document Redis object caching activation plan (Phase A)

  • Priority: Medium
  • Owner: TBD
  • Description: Add a section describing enabling Redis object cache, verification steps, rollback, and measurement plan in PHASE_A_THEME.md, security.md, and infrastructure.md.
  • Acceptance Criteria:
    • Clear step-by-step enable/disable/verify instructions
    • Risk and rollback documented
    • Pre/post performance measurement steps defined

• Diagram pass using DIAGRAMS_GUIDE

  • Priority: Medium
  • Owner: TBD
  • Description: Add missing container and sequence diagrams where helpful (Phase B API data flow, Phase C migration sequence), using diagrams-guide.md notation.
  • Acceptance Criteria:
    • At least one container diagram added for Phase B API data flow
    • One sequence diagram for Phase C migration cutover
    • Diagrams referenced from relevant phase docs

Nice-to-haves (Optional)

• External link checker in CI (for http/https links)
• Markdown linting (markdownlint) with a simple ruleset
• Auto-generate ToCs in CI and verify consistency

Notes

• All documentation changes should keep anchors stable to avoid breaking links.
• Prefer adding cross-links between related docs for discoverability.