v1 roadmap format

[OthmaneZ05]

Summary of Changes

Introduces the open roadmap file format (versioned JSON Schema) — the foundation for guided, auto-corrected learning roadmaps in Torollo.

A roadmap is a purely declarative, versioned JSON file: Roadmap → steps[] → { instruction, hints[], solution?, validators[] }, where a validator is inert data { type, params } — nothing in a roadmap file is ever executed. This format is the public contract that the upcoming validation engine and roadmap player will consume, and that community-written content will target.

What this PR adds:

• JSON Schema (draft 2020-12) at backend/src/modules/learning/format/roadmap.schema.json — schemaVersion: 1 required (const), strict additionalProperties: false everywhere so hand-written files fail on typos, $id set to the raw GitHub URL for editor autocompletion. Emitted to backend/dist via resolveJsonModule, so the future roadmap loader gets it at runtime for free.
• TypeScript types: source of truth in backend/src/modules/learning/format/roadmapTypes.ts, documented KEEP-IN-SYNC copy in frontend/src/shared/types/roadmap.ts (same deliberate-duplication policy as the existing Project type).
• Validation function validateRoadmap(data) (pure, no I/O) — every error points at the faulty field: missing required fields are named, unknown fields get a "check for typos" hint, unsupported schemaVersion gets an explicit rejection, duplicate step ids report both positions.
• CLI for roadmap authors: cd backend && npm run roadmap:validate -- <file> (exit 0/1).
• Reference example roadmaps/example-first-architecture.json: 4 steps, one step with 2 hints + solution, one step with 2 validators of different types, stable slug ids decoupled from position.
• Format documentation docs/roadmap-format.md: philosophy, copy-pasteable quick start, field-by-field reference, the 8 v1 validator types with their params, the name-based targeting convention (nodes are referenced by canvas name, never by runtime ids), the i18n decision (one language per file; a translation is a separate file with the same id), and the versioning policy (v1 frozen at merge — any field change ⇒ schemaVersion: 2; new validator types are NOT schema changes).

New runtime dependency: ajv ^8 (backend). No CI changes, no root package changes, no frontend build changes.

Types of Changes

• New feature / node type addition
• Bug fix (non-breaking change resolving an issue)
• Refactoring / structural cleanup
• Documentation update

Verification & Testing

Automated Checks

• Run npm run lint successfully with no errors
• Run npm run build successfully with no compilation errors
• Run npm test successfully (all tests pass)

Backend: 53 tests green (18 new — including one embedding all 8 validator types with their documented params, and one asserting the example file structurally keeps covering the format's reference requirements so it can't silently regress). Frontend: 107 tests green, no regression.

Manual Verification

• npm run roadmap:validate -- ../roadmaps/example-first-architecture.json → OK ... (roadmap "example-first-architecture", 4 steps).
• Deliberately broken files rejected with actionable messages:
  • schemaVersion: 2 → /schemaVersion: unsupported schemaVersion 2 — this version of Torollo reads schemaVersion 1
  • typo field titel → (root): unknown field "titel" — check for typos + missing title named.
• Authored a minimal new roadmap from the Quick start section of docs/roadmap-format.md alone, in under 15 minutes.

Checklist

• My code follows the repository's code style and lint standards
• I have updated the documentation or instructions if necessary
• All unit and integration tests are passing