Milestone 4: Hand-off & Roadmap¶

Status: Tracking. Phases 11–12 cover the testing & CI gate and the documentation hand-off; this milestone also lists the creator/marketplace feature proposals that have not been committed to a numbered phase.

Reading guide: Detailed phase prose lives in reference/implementation.md. Detailed feature proposals live in roadmap.md. When this milestone disagrees with either, treat them as authoritative.

See also:

• Part 1: Foundational — Project scaffold, design system, persistence, Auth.js, email.
• Part 2: Core Application — Schemas/CMS client, public site, enrollment, entry pagination.
• Part 3: Operationalization — Quiz, dashboards, errors/security, well-known files.
• Roadmap — full creator/marketplace feature catalogue (F1–F15) and documentation backlog.

Overview¶

This milestone closes the V1 build (testing & CI, documentation drift correction) and surfaces the creator/marketplace feature backlog that should drive the next round of product work.

Dependency order

Testing & CI → Documentation & Hand-off → (Roadmap features prioritised individually)

Phase Checklist¶

Phase 11 — Testing & CI¶

Goal: enforce regressions cannot land.

• Vitest with happy-dom; coverage thresholds for src/db/queries, src/lib/cms, src/auth, schemas, and 100% file coverage on src/components/** (every component has a co-located test, enforced by a CI check that fails when a .tsxlacks a sibling.test.tsx).
• Playwright with DATA_DIR=./data/test, project-level seeds, unique resource names per test.
• Suites:
  • Component (per-component Vitest specs — already required in every phase; this is the aggregate run).
  • Auth (sign-in, redirect, role gates).
  • Enrollment (enrol, idempotency, tenant isolation).
  • Entry pagination + gating.
  • Quiz (pass, fail, retry exhaustion).
  • Admin (promotion, audit visibility).
  • i18n smoke — each locale renders home + sign-in; assert at least one Spanish-only key renders on es to prove the locale switcher is wired.
  • i18n regression — visit each top-level route on es and assert no English-locale-only string from en.json appears in the rendered HTML.
  • Theme smoke — each top-level route renders in light, dark, and system with prefers-color-scheme toggled at the Playwright level.
  • WCAG sweep with @axe-core/playwright in both light and dark.
• CI workflow runs npm run verify && npm run test:unit && npm run test:components && npm run test:e2e.
• scripts/check-i18n.mjs (run from root npm run check) greps for unwrapped JSX/aria/placeholder strings and diffs key sets across messages/*.json. See Root Scripts Reference.

Reference detail: reference/implementation.md — Phase 11, reference/tech-stack.md, .cursor/rules/030-testing.mdc.

Phase 12 — Documentation & Hand-off¶

Goal: reference docs, generated documentation, and hand-off notes stay aligned with the implemented product.

• Update reference docs in apps/lms/docs/reference/ with realised behaviour where implementation diverged from the design specs. The current authoritative docs are not stubs; this phase is for drift correction, examples, and any implementation-specific decisions discovered during the build.
• Run npm run docs:check (Zensical invalid_links must pass).
• Append OpenAPI / Swagger pointers to root .cursor/rules/050-apis.mdc and verify the Phase 10.5 well-known surface matches the rule's caching policy table exactly.
• Final npm run verify (check + build + docs:check).

Reference detail: reference/implementation.md — Phase 12, root .cursor/rules/100-documentation.mdc.

Creator / Marketplace Feature Backlog (F1–F15)¶

These features are proposals, not binding specs. Full descriptions, rationale, and implementation pointers live in roadmap.md. Prioritisation should be revisited when the V1 build (Phases 0–12) is complete.

Adoption of any item promotes it from this backlog into a numbered phase appended to reference/implementation.md. Until then, do not fold roadmap items into the V1 plan unless separately approved.

Hand-off Verification¶

1. npm run verify — clean.
2. npm run docs:publish — Zensical site rebuilds; apps/lms/public/docs/ updates.
3. Manual readout: index → milestone 1–4 → reference → guides → admin pages all link without 404s.
4. Open the published Zensical site (/docs/) and walk top-level nav: every entry resolves.