docs: start frontend mvp milestone

.planning/PROJECT.md

@@ -20,20 +20,38 @@ each short practice loop.
 
 ### Validated
 
-(None yet; ship to validate.)
+- [x] Developer job seekers can complete a diagnostic technical interview.
+- [x] Answers are graded with rubrics and preserved as evidence.
+- [x] Learner memory tracks concept mastery, misconceptions, evidence, and
+  interventions.
+- [x] The system selects the next best interview challenge from learner state.
+- [x] The user sees a readiness map and meaningful progression after each loop.
+- [x] Uploaded learning materials can become source-backed ontology candidates.
+- [x] Generated learning assets preserve prompt, source, and review lineage.
+- [x] Backend implementation uses Go and keeps `agent-farm-go` workflow patterns
+  internalized behind typed interfaces.
 
 ### Active
 
-- [ ] Developer job seekers can complete a diagnostic technical interview.
+- [ ] Job seekers can use the first web app without API tooling.
-- [ ] Answers are graded with rubrics and preserved as evidence.
+- [ ] The web app guides users through diagnostic practice and shows feedback.
-- [ ] Learner memory tracks concept mastery, misconceptions, evidence, and
+- [ ] The web app shows learner memory, readiness, and next challenge after
-  interventions.
+  practice.
-- [ ] The system selects the next best interview challenge from learner state.
+- [ ] Operators can ingest learning material and inspect ontology candidates.
-- [ ] The user sees a readiness map and meaningful progression after each loop.
+- [ ] Operators can generate source-backed teaching asset prompt candidates.
-- [ ] Uploaded learning materials can become source-backed ontology candidates.
+
-- [ ] Generated learning assets preserve prompt, source, and review lineage.
+## Current Milestone: v2 Frontend MVP
-- [ ] Backend implementation uses Go and keeps `agent-farm-go` workflow patterns
+
-  internalized behind typed interfaces.
+**Goal:** Turn the completed backend learning loop into a usable web service
+experience for developer job seekers.
+
+**Target features:**
+
+- Web app shell served by the Go backend.
+- Diagnostic interview practice UI.
+- Learner memory, readiness map, and next challenge views.
+- Material ingestion and ontology snapshot UI.
+- Teaching asset prompt candidate UI.
 
 ### Out of Scope
 
@@ -81,6 +99,26 @@ each short practice loop.
 | Game-inspired progression must be evidence-backed | Creates retention without empty rewards | Pending |
 | 600-line source limit | Forces responsibility boundaries early | Pending |
 | Backend Developer Interview first track | Gives a broad but testable MVP concept set | Pending |
+| v2 frontend first | The backend loop is proven; the next risk is whether users can operate it as a web service | Active |
+
+## Evolution
+
+This document evolves at phase transitions and milestone boundaries.
+
+**After each phase transition**:
+
+1. Requirements invalidated? Move to Out of Scope with reason.
+2. Requirements validated? Move to Validated with phase reference.
+3. New requirements emerged? Add to Active.
+4. Decisions to log? Add to Key Decisions.
+5. "What This Is" still accurate? Update if drifted.
+
+**After each milestone**:
+
+1. Full review of all sections.
+2. Core Value check: still the right priority?
+3. Audit Out of Scope: reasons still valid?
+4. Update Context with current state.
 
 ---
-*Last updated: 2026-04-26 after first track and Phase 1 plan were set.*
+*Last updated: 2026-04-26 after v2 Frontend MVP milestone start.*

.planning/REQUIREMENTS.md

@@ -68,6 +68,22 @@ interview-ready after each short practice loop.
 
 ## v2 Requirements
 
+### Frontend MVP
+
+- [ ] **WEB-01**: User can open a web app served by the Go service.
+- [ ] **WEB-02**: User can create a diagnostic interview session from the web
+  app.
+- [ ] **WEB-03**: User can answer a diagnostic question and see rubric feedback.
+- [ ] **WEB-04**: User can see learner memory, readiness, and next challenge
+  after answering.
+- [ ] **WEB-05**: Operator can ingest source material from the web app.
+- [ ] **WEB-06**: Operator can inspect ontology candidate concepts, edges, and
+  gaps.
+- [ ] **WEB-07**: Operator can generate and inspect teaching asset prompt
+  candidates.
+- [ ] **WEB-08**: Web UI includes loading, empty, and error states for the MVP
+  flows.
+
 ### General Student Expansion
 
 - **GEN-01**: Support non-interview learning tracks.
@@ -100,12 +116,16 @@ interview-ready after each short practice loop.
 | PROG-01..PROG-05 | Phase 4 | Complete |
 | ONTO-01..ONTO-04 | Phase 5 | Complete |
 | ASSET-01..ASSET-03 | Phase 6 | Complete |
+| WEB-01..WEB-03 | Phase 7 | Pending |
+| WEB-04 | Phase 8 | Pending |
+| WEB-05..WEB-08 | Phase 9 | Pending |
 
 **Coverage:**
 - v1 requirements: 28 total
-- Mapped to phases: 28
+- v2 frontend requirements: 8 total
+- Mapped to phases: 36
 - Unmapped: 0
 
 ---
 *Requirements defined: 2026-04-26*
-*Last updated: 2026-04-26 after Phase 6 execution.*
+*Last updated: 2026-04-26 after v2 Frontend MVP milestone start.*

.planning/ROADMAP.md

@@ -94,5 +94,50 @@ diagnostic interview.
 - Company-specific interview packs.
 - Human ontology review console.
 
+## Milestone 2: Frontend MVP
+
+### Phase 7: Web App Shell and Diagnostic Start
+
+**Goal:** Serve the first web app from the Go service and let a job seeker
+start diagnostic practice without API tooling.
+
+**Requirements:** WEB-01, WEB-02, WEB-03
+
+**Success Criteria:**
+
+- Go service serves a web app at `/`.
+- User can enter target role, stack, and interview timeline.
+- User can create a diagnostic session from the browser.
+- User can submit an answer and see typed grading feedback.
+- UI has loading and error states for the diagnostic flow.
+
+### Phase 8: Learning Progress View
+
+**Goal:** Show evidence-backed learning progress after practice.
+
+**Requirements:** WEB-04
+
+**Success Criteria:**
+
+- User can see learner profile and concept mastery after answering.
+- User can see readiness percentage and concept ladder state.
+- User can see the next recommended challenge and its evidence.
+- Empty states explain what to do before memory/progression exists.
+
+### Phase 9: Material and Asset Workspace
+
+**Goal:** Let an operator use ontology and teaching asset prompt workflows from
+the web app.
+
+**Requirements:** WEB-05, WEB-06, WEB-07, WEB-08
+
+**Success Criteria:**
+
+- Operator can ingest text material from the browser.
+- Operator can inspect ontology candidate concepts, edges, and gaps.
+- Operator can generate teaching asset prompt candidates from a concept.
+- UI clearly shows candidate review state, source evidence, and model
+  verification guard.
+
 ---
-*Roadmap created: 2026-04-26 after initial product planning and Go backend decision.*
+*Roadmap updated: 2026-04-26 after v2 Frontend MVP milestone start.*

.planning/STATE.md

@@ -7,7 +7,7 @@ See: `.planning/PROJECT.md` (updated 2026-04-26)
 **Core value:** The user should feel and prove that they are becoming more
 interview-ready after each short practice loop.
 
-**Current focus:** v1 milestone audited; ready to choose the next milestone.
+**Current focus:** v2 Frontend MVP milestone started; ready for Phase 7.
 
 ## Current Decisions
 
@@ -35,11 +35,12 @@ interview-ready after each short practice loop.
   evidence, model config, review state, and model-id verification guard.
 - v1 milestone audit completed with all 28/28 requirements satisfied and
   tech-debt items recorded in `.planning/v1-MILESTONE-AUDIT.md`.
+- v2 Frontend MVP milestone selected to turn the backend learning loop into a
+  usable web service.
 
 ## Next Actions
 
-1. Choose the next milestone: frontend MVP, persistence, real workflow runtime,
+1. Plan and execute Phase 7: Web App Shell and Diagnostic Start.
-   or document parser integration.
 2. Verify the production OpenAI image model identifier before real image
    generation calls.
 3. Add standardized SUMMARY frontmatter or Nyquist validation files if future
@@ -73,6 +74,8 @@ interview-ready after each short practice loop.
   integration, E2E diagnostic/progression and material/asset flows. Audit
   status is `tech_debt` because MVP storage, real workflow runtime, parsers,
   real image generation, and Nyquist validation artifacts remain deferred.
+- 2026-04-26: v2 Frontend MVP milestone started with WEB-01..WEB-08 mapped to
+  phases 7 through 9.
 
 ---
 *State initialized: 2026-04-26.*

openspec/changes/frontend-mvp/design.md

@@ -0,0 +1,30 @@
+# Design: Frontend MVP
+
+## Approach
+
+Use a dependency-light web app served by the Go backend. The first UI can be
+plain HTML/CSS/JavaScript so the repo avoids frontend build tooling until the
+interaction model is proven.
+
+## UX Principles
+
+- First screen is the working tutor experience, not a marketing landing page.
+- Keep the UI quiet, operational, and focused on repeated practice.
+- Show evidence-backed feedback and next actions after each loop.
+- Use clear loading, empty, and error states.
+
+## Boundaries
+
+In scope:
+
+- Diagnostic practice.
+- Learner memory and readiness display.
+- Material ingestion and ontology inspection.
+- Teaching asset prompt candidates.
+
+Out of scope:
+
+- Authentication.
+- Multi-user persistence.
+- Payment/subscription.
+- Real provider image generation.

openspec/changes/frontend-mvp/proposal.md

@@ -0,0 +1,19 @@
+# Change: frontend-mvp
+
+## Why
+
+The backend MVP now exposes the core tutoring loop, but job seekers still need
+a web service experience instead of API tooling.
+
+## What Changes
+
+- Serve a web app from the Go backend.
+- Add diagnostic practice UI.
+- Add learner progress UI.
+- Add material ingestion, ontology inspection, and teaching asset prompt UI.
+
+## Impact
+
+- Adds frontend capability requirements.
+- Keeps Go backend as the serving boundary for the MVP.
+- Does not introduce authentication, persistence, or real image generation.

openspec/changes/frontend-mvp/specs/frontend-mvp/spec.md

@@ -0,0 +1,44 @@
+# frontend-mvp Specification
+
+## ADDED Requirements
+
+### Requirement: Web app exposes the job-seeker tutoring loop
+
+The system SHALL provide a browser UI for the diagnostic interview loop.
+
+#### Scenario: user starts diagnostic practice
+
+- **GIVEN** a job seeker opens the web app
+- **WHEN** they enter target role, stack, and interview timeline
+- **THEN** the app creates a diagnostic session
+- **AND** shows role-relevant questions.
+
+#### Scenario: user submits an answer
+
+- **GIVEN** a diagnostic session is active
+- **WHEN** the user submits an answer
+- **THEN** the app shows typed grading feedback
+- **AND** the feedback links to evidence-backed learning state.
+
+### Requirement: Web app exposes learning progress
+
+The system SHALL show learner memory, readiness, and next challenge from the
+backend APIs.
+
+#### Scenario: progress appears after answer
+
+- **GIVEN** the user has submitted at least one answer
+- **WHEN** the app refreshes progress
+- **THEN** it shows concept mastery, readiness percentage, and next challenge.
+
+### Requirement: Web app exposes content operations
+
+The system SHALL provide MVP operator controls for material ingestion,
+ontology inspection, and teaching asset prompt candidates.
+
+#### Scenario: operator creates teaching asset prompt
+
+- **GIVEN** source material has produced ontology candidates
+- **WHEN** the operator generates an asset prompt for a concept
+- **THEN** the prompt shows source evidence, review state, model key, and model
+  verification guard.

openspec/changes/frontend-mvp/tasks.md

@@ -0,0 +1,8 @@
+# Tasks
+
+- [ ] 1. Implement web app shell served by the Go backend.
+- [ ] 2. Implement diagnostic session start and answer submission UI.
+- [ ] 3. Implement learner memory, readiness, and next challenge UI.
+- [ ] 4. Implement material ingestion and ontology inspection UI.
+- [ ] 5. Implement teaching asset prompt candidate UI.
+- [ ] 6. Validate frontend MVP with tests, smoke checks, and OpenSpec.