docs: record the development pipeline order and the branch model

The milestone order is deliberate and not the obvious one, so the reasoning
belongs in the documentation rather than only in the milestone titles:

    Testing -> Persistence -> Agent harness -> Implementation completion

Testing comes first so every later phase merges through the gate, rather
than the largest and riskiest change being the one thing the gate never
protected. Persistence precedes the agent harness because an agent that
plans, critiques and repairs is expensive to re-run without durable
memory. Integration of the mvp-testing line comes last so it lands on top
of those foundations.

Also records the branch model now that only master and mvp-testing remain,
and updates requirement 21 to describe authentication as it actually is:
the authorization matrix asserts endpoint protection structurally, and the
two defects it found (sixteen unauthenticated endpoints, and logout not
revoking refresh tokens) are noted along with the rotation work still
outstanding.

Author: lucaosti

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.
 
 ---