Merge pull request #169 from BitPolito/docs/roadmap-pipeline-order

docs: record the development pipeline order and the branch model

Author: longobucco

AGENTS.md

@@ -35,6 +35,25 @@ scripts/, tests/      Evaluation tooling and cross-service test assets
 
 ## 3. Workflow
 
+### 3.0 Branch model
+
+Two long-lived branches, and nothing else:
+
+| Branch | Role |
+|---|---|
+| `master` | Default branch. Protected. Only ever updated through a merged pull request. |
+| `mvp-testing` | The active development line, where the MVP is built and tested. |
+
+`master` receives reviewed, gated work. `mvp-testing` periodically receives `master` — that
+direction only — so it is tested with the current gate and fixes in place. Work travels back toward
+`master` in reviewable slices, not as one large merge.
+
+CI runs on both. Feature branches are short-lived: created from the branch they target, merged, and
+deleted immediately. A branch that outlives its pull request is drift waiting to happen.
+
+> The former `mvp` branch was deleted: it contained no commits that `mvp-testing` did not already
+> have, so keeping it only invited work to land on a stale line.
+
 ### 3.1 Pick up work
 
 Work starts from a GitHub issue. Assign it to yourself and move it to **In Progress** on the

docs/overview.md

@@ -160,7 +160,37 @@ architectural work and is the highest-priority refactor in the roadmap.
 
 ---
 
-## 5. Documentation map
+## 5. Development pipeline
+
+Work proceeds in a deliberate order, tracked as milestones on GitHub. The order matters and is not
+the obvious one:
+
+```
+1. Testing        →  2. Persistence  →  3. Agent harness  →  4. Implementation completion
+   (M2)               (M3)               (M4)                 (M5)
+```
+
+**Testing comes first.** The quality gate is established before any substantial code lands, so every
+later phase merges through it. The alternative — integrating a large body of work and then building
+the gate — means the largest, riskiest change is the one thing the gate never protected. This
+project has already seen what an unenforced gate costs: CI was configured for branches that were not
+the default branch, so nothing ran on `master` for weeks and nobody noticed.
+
+**Persistence comes before the agent harness.** An agent that plans, generates, critiques and
+repairs is expensive to run. Without durable memory, every repetition pays that cost again. Building
+the harness first would mean building it against a memory model that is about to change.
+
+**Implementation completion comes last.** The `mvp-testing` branch carries a large body of working,
+tested code — quiz unification, the course builder, structured generation, the inference ladder.
+Integrating it is sequenced last so it lands on top of the gate, the persistence layer and the agent
+foundations, rather than underneath them.
+
+Milestones M6–M9 (topic base, retrieval consolidation, assessment and exam prep, platform health)
+follow, and are not strictly ordered relative to each other.
+
+---
+
+## 6. Documentation map
 
 | Document | Contents |
 |---|---|

docs/specifications.md

@@ -262,7 +262,20 @@ The system must authenticate users and protect its endpoints.
 
 **Implementation.** JWT-based authentication with refresh, a token blacklist for revocation,
 account lockout after repeated failures, `admin`/`student` roles, rate limiting, security headers
-and audit middleware. Development accounts are seeded automatically.
+and audit middleware. Development accounts are seeded automatically, and seeding refuses to run
+when `ENVIRONMENT=production`.
+
+Endpoint protection is asserted structurally rather than by convention:
+`tests/integration/test_authorization_matrix.py` derives the endpoint list from the live OpenAPI
+schema, so an endpoint added without authentication fails the build. Endpoints that are deliberately
+public are listed explicitly in `PUBLIC_ENDPOINTS`, which makes publishing one a visible decision.
+
+Two defects in this area were found and fixed by that suite: sixteen endpoints across the courses
+and documents APIs declared no authentication at all, and logout blacklisted a refresh token whose
+`jti` the refresh endpoint never checked — so a revoked token kept minting access tokens until it
+expired on its own.
+
+**Not yet implemented.** Refresh token rotation with reuse detection.
 
 ---