feat: add progression readiness api

.planning/phases/004-progression/004-CONTEXT.md

@@ -0,0 +1,39 @@
+# Phase 4 Context: Progression
+
+**Status:** Ready for execution
+**Started:** 2026-04-26
+
+## Goal
+
+Expose visible, evidence-backed progression after diagnostic practice.
+
+## Inputs
+
+- OpenSpec `learning-progression` requirements.
+- `docs/planning/GAMIFICATION.md`.
+- Phase 3 learner memory snapshots.
+- Existing workflow contracts for `NextChallenge` and `ReadinessUpdate`.
+
+## Decisions
+
+- Derive MVP readiness directly from learner memory.
+- Keep progression read-only except for future workflow outputs.
+- Do not add streak persistence yet.
+- Rewards and unlocks must be deterministic and evidence-backed.
+
+## Boundaries
+
+In scope:
+
+- Role readiness map API.
+- Concept ladder level calculation.
+- Next challenge selection API.
+- Boss-style unlock when prerequisite concepts are stable.
+- Tests and verification.
+
+Out of scope:
+
+- Frontend map UI.
+- Persistent campaign/streak storage.
+- Social leaderboards.
+- Random reward economy.

.planning/phases/004-progression/004-PLAN.md

@@ -0,0 +1,46 @@
+# Phase 4 Plan: Progression
+
+**Status:** Ready for execution
+**Phase Goal:** Show evidence-backed readiness and select the next challenge.
+
+## Requirements Covered
+
+- PROG-01: User can see a role-specific readiness map.
+- PROG-02: Concepts have challenge ladders from definition to interview
+  pressure.
+- PROG-03: System selects next challenge based on learner memory and grading
+  evidence.
+- PROG-04: System unlocks boss-style integrated questions after prerequisite
+  stability.
+- PROG-05: Streaks and rewards avoid punitive or gambling-like mechanics.
+
+## Tasks
+
+### 1. Add progression package
+
+- Define readiness map, concept progress, reward, and unlock types.
+- Compute readiness from learner memory snapshots.
+
+### 2. Add next challenge selection
+
+- Select the weakest evidenced concept first.
+- Use review schedule or misconception evidence to choose recovery difficulty.
+- Produce typed `workflows.NextChallenge`.
+
+### 3. Add HTTP endpoints
+
+- `GET /api/v1/learners/{userID}/readiness-map`
+- `GET /api/v1/learners/{userID}/next-challenge`
+
+### 4. Add tests and verification
+
+- Test readiness map projection.
+- Test next challenge selection from weak memory.
+- Test HTTP readiness flow after diagnostic answer.
+- Run Go tests, OpenSpec validation, line-count check, and smoke.
+
+## Out of Scope
+
+- Frontend visualization.
+- Persistent streak history.
+- Multi-track progression graph.

.planning/phases/004-progression/004-RESEARCH.md

@@ -0,0 +1,32 @@
+# Phase 4 Research: Progression
+
+## Findings
+
+Learner memory already stores the minimum evidence needed for progression:
+
+- concept mastery state
+- evidence references
+- misconceptions
+- review schedules
+- interventions
+
+The MVP progression surface can therefore be computed as a projection rather
+than a new durable source of truth.
+
+## Recommended Shape
+
+- `internal/progression` owns readiness projection and challenge selection.
+- `learnermemory.Service` remains the source for learner state.
+- Readiness percentage should be simple and explainable.
+- Challenge ladder should map readiness state to the next useful task:
+  - unknown/fragile: define or recovery
+  - improving: tradeoffs
+  - interview-ready: design constraints
+  - strong signal: interview pressure
+- Boss unlock requires at least two stable concepts with evidence.
+
+## Risks
+
+- Too much gamification logic can become speculative. Keep it deterministic.
+- Readiness percentages can feel fake if not traceable. Include evidence.
+- Missing memory should return a normal 404, not invented progress.

.planning/phases/004-progression/004-SUMMARY.md

@@ -0,0 +1,35 @@
+# Phase 4 Summary
+
+**Status:** Complete
+**Completed:** 2026-04-26
+
+## Delivered
+
+- Added `internal/progression` for readiness projection and next challenge
+  selection.
+- Added role readiness map calculation from learner memory evidence.
+- Added deterministic challenge ladder mapping.
+- Added evidence-backed rewards and boss-question unlocks.
+- Added HTTP endpoints:
+  - `GET /api/v1/learners/{userID}/readiness-map`
+  - `GET /api/v1/learners/{userID}/next-challenge`
+- Added progression unit tests and HTTP flow coverage.
+
+## Verification
+
+```powershell
+gofmt -w cmd internal
+go test ./...
+openspec validate bootstrap-job-tutor-platform --strict
+```
+
+Additional smoke check:
+
+- Diagnostic create/answer followed by readiness-map and next-challenge reads
+  returned readiness `75`, one concept, and a typed challenge.
+
+## Deferred
+
+- Frontend readiness visualization.
+- Persistent campaign and streak state.
+- Multi-concept cluster graph beyond simple stable-count boss unlock.

.planning/phases/004-progression/004-VERIFICATION.md

@@ -0,0 +1,28 @@
+# Phase 4 Verification
+
+## Verdict
+
+PASS
+
+## Requirement Coverage
+
+- PROG-01: PASS. Readiness map API returns learner concept readiness.
+- PROG-02: PASS. Each concept maps to a challenge ladder level.
+- PROG-03: PASS. Next challenge selection targets the weakest evidenced
+  learner-memory concept.
+- PROG-04: PASS. Boss unlocks are produced only from stable evidenced concepts.
+- PROG-05: PASS. Rewards are deterministic, evidence-backed, and do not punish
+  missed days or use random reward mechanics.
+
+## Evidence
+
+- `go test ./...` passed.
+- `openspec validate bootstrap-job-tutor-platform --strict` passed.
+- Live diagnostic create/answer plus readiness and next-challenge smoke passed.
+- Go source line-count check passed.
+
+## Residual Risk
+
+Progression is currently an in-memory projection. It is enough for MVP proof but
+will need persisted campaign state before real streaks or long-running
+readiness histories.