docs: plan backend foundation phase

.planning/PROJECT.md

@@ -54,6 +54,7 @@ each short practice loop.
 - Workflow behavior should be configuration-first and inspired by
   `agent-farm-go`.
 - LLM execution should use `third-one`, defaulting to `deepseek-v4-flash`.
+- The first interview track is Backend Developer Interview.
 - Memory should be structured learner state, not a flat RAG transcript.
 - Gamification should use Flow, adaptive difficulty, growth lines, and strong
   session endings without exploitative mechanics.
@@ -79,6 +80,7 @@ each short practice loop.
 | Structured learner memory, not RAG-first | Product value is learner modeling and readiness | Pending |
 | 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 |
 
 ---
-*Last updated: 2026-04-26 after Go backend and GSD planning direction were set.*
+*Last updated: 2026-04-26 after first track and Phase 1 plan were set.*

.planning/STATE.md

@@ -19,18 +19,22 @@ interview-ready after each short practice loop.
 - Source files should stay at or below 600 lines.
 - SOLID, KISS, and YAGNI are active implementation constraints.
 - OpenSpec is the intent/requirements source of truth.
+- First interview track is Backend Developer Interview.
+- Phase 1 has context, research, and plan artifacts.
 
 ## Next Actions
 
-1. Choose first interview track and canonical concept seed list.
-2. Define typed contracts for diagnostic, grading, memory extraction, next
-   challenge, readiness update, ontology gap, and asset prompt.
-3. Plan Phase 1 with GSD before writing backend code.
+1. Execute Phase 1 Go backend foundation plan.
+2. Keep `docs/planning/WORKFLOW_CONTRACTS.md` aligned with Go structs during
+   implementation.
+3. After Phase 1, plan Phase 2 diagnostic interview loop.
 
 ## Validation Log
 
 - 2026-04-26: `openspec validate bootstrap-job-tutor-platform --strict` passed
   before GSD planning docs were created.
+- 2026-04-26: First track, workflow contracts, and Phase 1 GSD plan were
+  created.
 
 ---
 *State initialized: 2026-04-26.*

.planning/phases/001-go-backend-foundation-and-workflow-boundary/001-CONTEXT.md

@@ -0,0 +1,93 @@
+# Phase 1: Go Backend Foundation and Workflow Boundary - Context
+
+**Gathered:** 2026-04-26
+**Status:** Ready for planning
+**Source:** GSD continuation from product planning
+
+<domain>
+## Phase Boundary
+
+Phase 1 establishes the Go backend foundation and the typed workflow boundary.
+It does not need to implement the full tutoring loop. It should create the
+minimal service skeleton that future phases can build on without violating the
+600-line rule, SOLID/KISS/YAGNI, or OpenSpec.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Stack
+
+- Backend is Go.
+- The first source package structure should separate app/bootstrap, HTTP
+  transport, config, workflow contracts, and domain placeholders.
+- The implementation should not introduce a database, queue, UI, auth provider,
+  or image provider in Phase 1 unless needed for scaffold validation.
+
+### Workflow Boundary
+
+- `agent-farm-go` patterns are internalized behind typed Go interfaces.
+- API/handler code must not shell out to workflow scripts directly.
+- `third-one` / `deepseek-v4-flash` runtime selection belongs behind config and
+  workflow interfaces.
+- Workflow result contracts should align with
+  `docs/planning/WORKFLOW_CONTRACTS.md`.
+
+### Engineering Constraints
+
+- No manually authored source file over 600 lines.
+- SOLID, KISS, and YAGNI are active constraints.
+- Keep learner memory, ontology, grading, progression, and assets separated as
+  future module boundaries.
+
+</decisions>
+
+<canonical_refs>
+## Canonical References
+
+Downstream agents MUST read these before planning or implementing.
+
+### Product and Requirements
+
+- `docs/planning/PRD.md` - product direction and MVP scope.
+- `docs/planning/ARCHITECTURE.md` - Go backend and internalized workflow shape.
+- `docs/planning/ENGINEERING.md` - implementation constraints.
+- `.planning/REQUIREMENTS.md` - Phase 1 requirement IDs.
+- `.planning/ROADMAP.md` - phase goal and success criteria.
+
+### Workflow Contracts and Specs
+
+- `docs/planning/WORKFLOW_CONTRACTS.md` - typed workflow contract plan.
+- `openspec/changes/bootstrap-job-tutor-platform/specs/tutor-workflows/spec.md`
+  - workflow and Go backend requirements.
+- `openspec/changes/bootstrap-job-tutor-platform/specs/engineering-quality/spec.md`
+  - code-size and design quality requirements.
+
+</canonical_refs>
+
+<specifics>
+## Specific Ideas
+
+- Start with a small Go module and one health endpoint or CLI smoke path.
+- Add config structs for runtime/model keys without calling live providers yet.
+- Add workflow interface definitions and stub implementations that return typed
+  errors or no-op evidence-safe results.
+- Add tests for config loading and workflow interface behavior where practical.
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- Real diagnostic interview flow belongs to Phase 2.
+- Persistent learner memory belongs to Phase 3.
+- Progression/readiness map belongs to Phase 4.
+- Ontology ingestion belongs to Phase 5.
+- Image asset generation belongs to Phase 6.
+
+</deferred>
+
+---
+*Phase: 001-go-backend-foundation-and-workflow-boundary*
+*Context gathered: 2026-04-26*

.planning/phases/001-go-backend-foundation-and-workflow-boundary/001-PLAN.md

@@ -0,0 +1,108 @@
+# Phase 1 Plan: Go Backend Foundation and Workflow Boundary
+
+**Status:** Ready for execution
+**Phase Goal:** Establish the Go service skeleton and typed workflow boundary
+for internalized `agent-farm-go` patterns.
+
+## Scope
+
+This phase creates the backend foundation only. It should not implement the full
+diagnostic interview loop, persistence, frontend, ontology ingestion, or image
+generation.
+
+## Requirements Covered
+
+- BACK-01: Backend service is implemented in Go.
+- BACK-02: Backend exposes typed interfaces for tutor workflows.
+- BACK-03: Backend integrates internalized `agent-farm-go` workflow patterns
+  without ad hoc handler shellouts.
+- BACK-04: Workflow LLM execution uses `third-one` with configurable runtime and
+  default `deepseek-v4-flash`.
+- BACK-05: Manually authored source files stay at or below 600 lines.
+
+## Tasks
+
+### 1. Initialize Go backend scaffold
+
+- Create `go.mod`.
+- Create `cmd/tutor-api/main.go`.
+- Create minimal app assembly package under `internal/app`.
+- Keep entrypoint thin and below 600 lines.
+
+### 2. Add configuration boundary
+
+- Add `internal/config`.
+- Support app address, environment name, workflow runtime path, model key, and
+  third-one binary path as config fields.
+- Default model key to `deepseek-v4-flash`.
+- Avoid storing secrets in tracked files.
+
+### 3. Add typed workflow boundary
+
+- Add `internal/workflows`.
+- Define minimal Go structs/interfaces for:
+  - `DiagnosticResult`
+  - `GradedAnswer`
+  - `MemoryUpdateCandidate`
+  - `NextChallenge`
+  - `ReadinessUpdate`
+- Add a narrow runner interface that future internalized `agent-farm-go`
+  execution can satisfy.
+- Do not call shell commands from HTTP handlers.
+
+### 4. Add HTTP smoke surface
+
+- Add `internal/httpapi`.
+- Add health endpoint such as `GET /healthz`.
+- Optionally expose config-safe runtime metadata, excluding secrets.
+
+### 5. Add validation tests
+
+- Test config defaults.
+- Test health handler.
+- Test workflow stub returns typed results or typed not-implemented errors.
+- Verify no source file exceeds 600 lines.
+
+### 6. Update repo instructions
+
+- Add concrete Go build/test commands to `AGENTS.md`.
+- Update OpenSpec/GSD state if implementation changes scope.
+
+## Verification
+
+Run:
+
+```powershell
+go test ./...
+openspec validate bootstrap-job-tutor-platform --strict
+```
+
+Also check manually authored source file length:
+
+```powershell
+Get-ChildItem -Recurse -File *.go | ForEach-Object {
+  $lines = (Get-Content -LiteralPath $_.FullName | Measure-Object -Line).Lines
+  if ($lines -gt 600) { throw "$($_.FullName) has $lines lines" }
+}
+```
+
+## Out of Scope
+
+- Database schema.
+- Authentication.
+- Real LLM calls.
+- Live `third-one` execution.
+- Frontend.
+- Material ingestion.
+- Image generation.
+
+## Plan Quality Check
+
+- Goal-backward fit: each task supports Go scaffold or typed workflow boundary.
+- KISS/YAGNI: no database, queue, provider SDK, or full workflow engine in this
+  phase.
+- SOLID: app, config, HTTP, and workflow responsibilities are separated.
+- Evidence: build/tests/OpenSpec/file-length checks prove the phase.
+
+---
+*Plan created: 2026-04-26*

.planning/phases/001-go-backend-foundation-and-workflow-boundary/001-RESEARCH.md

@@ -0,0 +1,69 @@
+# Phase 1 Research
+
+## Question
+
+How should the first Go backend scaffold be shaped so it can internalize
+`agent-farm-go` workflow patterns without overbuilding?
+
+## Findings
+
+### Keep the first backend narrow
+
+Phase 1 should prove structure, contracts, and validation, not product behavior.
+The safest first slice is:
+
+- `cmd/tutor-api` entrypoint
+- internal config package
+- internal HTTP/app package
+- internal workflow contract package
+- small health or version endpoint
+- tests for config and workflow boundary behavior
+
+### Prefer typed interfaces over runtime coupling
+
+The backend should expose a `WorkflowRunner` style interface that future phases
+can implement using internalized `agent-farm-go` execution. Phase 1 can use
+stub/no-op implementations as long as the interface boundaries and contracts are
+clear.
+
+### Avoid premature infrastructure
+
+Do not add Postgres, migrations, queues, auth, frontend, or image generation in
+Phase 1. Those are real needs later, but adding them before the backend boundary
+exists would violate KISS/YAGNI.
+
+### Module boundary recommendation
+
+Initial Go package boundaries:
+
+- `internal/app`: service assembly and dependency wiring
+- `internal/config`: environment/runtime config
+- `internal/httpapi`: HTTP routing and handlers
+- `internal/workflows`: workflow interfaces and typed contracts
+- `internal/version`: version/build metadata if needed
+
+Future packages can be added when their phase arrives:
+
+- `internal/interview`
+- `internal/learner_memory`
+- `internal/progression`
+- `internal/ontology`
+- `internal/assets`
+
+## Risks
+
+- Making workflow interfaces too generic creates a framework before use.
+- Putting typed contracts in HTTP handlers will make future phases hard to
+  isolate.
+- Shelling out from handlers would contradict the internalized workflow decision.
+
+## Recommendation
+
+Plan Phase 1 as a scaffold and boundary proof:
+
+1. Create Go module and package skeleton.
+2. Add config for app address and workflow runtime keys.
+3. Add typed workflow contracts from the planning document in minimal Go form.
+4. Add a stub workflow runner.
+5. Add health endpoint and tests.
+6. Document build/test commands in `AGENTS.md`.

docs/planning/ARCHITECTURE.md

@@ -58,6 +58,9 @@ Implementation should follow the engineering rules in
 SOLID responsibility boundaries, KISS implementation choices, and YAGNI for
 future-only abstractions.
 
+Initial typed workflow contracts are defined in
+`docs/planning/WORKFLOW_CONTRACTS.md`.
+
 Initial workflow set:
 
 - `diagnose_job_seeker`
@@ -91,6 +94,9 @@ Core progression surfaces:
 - strong-answer portfolio
 - interview-date campaign plan
 
+The first progression track is the backend developer interview seed list in
+`docs/planning/INTERVIEW_TRACKS.md`.
+
 Progression decisions should read from learner memory and grading evidence.
 They should be exposed as workflow outputs so the service can explain why a
 question, reward, or unlock appeared.

docs/planning/INTERVIEW_TRACKS.md

@@ -0,0 +1,112 @@
+# Interview Tracks
+
+## MVP Track: Backend Developer Interview
+
+The first interview track is backend developer preparation. This track is broad
+enough to be valuable to job seekers and narrow enough to produce testable
+diagnostic, grading, memory, and progression behavior.
+
+## Target User
+
+- Junior backend developer candidates.
+- Bootcamp graduates preparing for backend interviews.
+- Full-stack developers who need backend interview readiness.
+- Developers changing stack into backend service work.
+
+## Canonical Concept Seed List
+
+### 1. HTTP and Web Fundamentals
+
+- request and response lifecycle
+- headers, status codes, methods
+- idempotency and safe methods
+- cookies, sessions, tokens
+- latency, timeout, retry basics
+
+### 2. REST and API Design
+
+- resource modeling
+- endpoint shape
+- validation and error responses
+- pagination and filtering
+- versioning
+- backward compatibility
+
+### 3. Databases and Indexes
+
+- relational modeling
+- primary keys and foreign keys
+- index purpose and tradeoffs
+- query plans at a conceptual level
+- N+1 query problem
+- migrations
+
+### 4. Transactions and Consistency
+
+- ACID
+- isolation anomalies
+- transaction boundaries
+- optimistic vs pessimistic locking
+- idempotent writes
+- eventual consistency basics
+
+### 5. Caching
+
+- cache-aside
+- TTL and invalidation
+- stale data risks
+- cache stampede
+- CDN vs application cache
+- when not to cache
+
+### 6. Concurrency and Async Work
+
+- race conditions
+- locks and coordination
+- worker queues
+- retry and dead-letter basics
+- backpressure
+- Go goroutine/channel concepts for Go-oriented tracks
+
+### 7. Testing and Reliability
+
+- unit vs integration tests
+- test doubles
+- contract tests
+- observability basics
+- logging and metrics
+- failure-mode thinking
+
+### 8. System Design Basics
+
+- load balancing
+- horizontal scaling
+- stateless service design
+- database bottlenecks
+- rate limiting
+- file/object storage
+- basic architecture tradeoffs
+
+## Challenge Ladder
+
+Each concept should support five levels:
+
+1. Define the concept.
+2. Explain tradeoffs.
+3. Debug a realistic scenario.
+4. Design under constraints.
+5. Answer under interview pressure.
+
+## First Boss Question
+
+"Design a rate-limited backend API for submitting job applications. Cover HTTP
+API design, database transaction boundaries, duplicate submission prevention,
+cache behavior, failure handling, and test strategy."
+
+## MVP Exclusions
+
+- Advanced distributed systems theory.
+- Deep database internals.
+- Language-specific trivia-heavy questions.
+- Company-specific interview packs.
+- Frontend, mobile, AI, and DevOps tracks.

docs/planning/PRD.md

@@ -85,12 +85,13 @@ The first MVP should prove one loop:
 7. User sees visible readiness progress, next unlocks, and a recommended next
    challenge.
 
-Recommended first track:
+First track:
 
 - Backend developer interview preparation.
-- Topics: HTTP, REST, databases, transactions, caching, concurrency, testing,
-  system design basics, Go or JavaScript/TypeScript depending on first content
-  corpus.
+- Topics: HTTP and web fundamentals, REST/API design, databases and indexes,
+  transactions and consistency, caching, concurrency/async work, testing and
+  reliability, and system design basics.
+- Canonical seed list: `docs/planning/INTERVIEW_TRACKS.md`.
 
 ## Core User Flows
 
@@ -183,6 +184,8 @@ the configured image generation provider.
   configuration.
 - Workflow outputs SHALL prefer typed JSON contracts for grading, memory
   extraction, ontology updates, and review-plan generation.
+- Initial workflow contract plan SHALL follow
+  `docs/planning/WORKFLOW_CONTRACTS.md`.
 
 ### Visual teaching assets
 

docs/planning/WORKFLOW_CONTRACTS.md

@@ -0,0 +1,200 @@
+# Workflow Contracts
+
+## Purpose
+
+LLM workflow outputs that affect product state must be typed and inspectable.
+The Go backend should call internalized workflow interfaces and then persist
+validated results. Product state must not depend on parsing arbitrary prose.
+
+These contracts are initial planning contracts. Field names may evolve during
+implementation, but the responsibilities should remain stable.
+
+## Shared Types
+
+```json
+{
+  "evidence_ref": {
+    "kind": "answer|grading|source|session|asset",
+    "id": "string",
+    "quote": "string",
+    "confidence": 0.0
+  }
+}
+```
+
+```json
+{
+  "concept_ref": {
+    "id": "string",
+    "label": "string",
+    "track": "backend-developer"
+  }
+}
+```
+
+## DiagnosticResult
+
+Produced by `diagnose_job_seeker`.
+
+```json
+{
+  "user_id": "string",
+  "track": "backend-developer",
+  "target_role": "junior-backend-developer",
+  "stack": ["go", "postgres"],
+  "initial_readiness": "unknown|fragile|improving|interview_ready|strong_signal",
+  "concept_findings": [
+    {
+      "concept": "concept_ref",
+      "readiness": "unknown|fragile|improving|interview_ready|strong_signal",
+      "reason": "string",
+      "evidence": ["evidence_ref"]
+    }
+  ],
+  "recommended_next_concepts": ["concept_ref"]
+}
+```
+
+## GradedAnswer
+
+Produced by `grade_interview_answer`.
+
+```json
+{
+  "answer_id": "string",
+  "question_id": "string",
+  "concepts": ["concept_ref"],
+  "scores": {
+    "correctness": 0,
+    "depth": 0,
+    "communication": 0,
+    "production_judgment": 0
+  },
+  "overall": "miss|partial|solid|strong",
+  "strengths": ["string"],
+  "gaps": ["string"],
+  "misconception_candidates": [
+    {
+      "label": "string",
+      "description": "string",
+      "evidence": ["evidence_ref"],
+      "confidence": 0.0
+    }
+  ],
+  "follow_up": {
+    "needed": true,
+    "question": "string",
+    "purpose": "clarify|repair|stretch|pressure_test"
+  }
+}
+```
+
+## MemoryUpdateCandidate
+
+Produced by `extract_learning_memory`.
+
+```json
+{
+  "user_id": "string",
+  "source_answer_id": "string",
+  "updates": [
+    {
+      "kind": "concept_mastery|misconception|intervention|review_schedule",
+      "concept": "concept_ref",
+      "proposed_state": "unknown|fragile|improving|interview_ready|strong_signal",
+      "summary": "string",
+      "evidence": ["evidence_ref"],
+      "confidence": 0.0,
+      "durability": "tentative|confirmed"
+    }
+  ]
+}
+```
+
+## NextChallenge
+
+Produced by `select_next_challenge`.
+
+```json
+{
+  "user_id": "string",
+  "track": "backend-developer",
+  "concept": "concept_ref",
+  "ladder_level": "define|tradeoffs|debug|design_constraints|interview_pressure",
+  "question": "string",
+  "rationale": "string",
+  "difficulty_action": "lower|hold|raise|recover",
+  "evidence": ["evidence_ref"]
+}
+```
+
+## ReadinessUpdate
+
+Produced by `update_readiness_map`.
+
+```json
+{
+  "user_id": "string",
+  "track": "backend-developer",
+  "concept_updates": [
+    {
+      "concept": "concept_ref",
+      "previous": "unknown|fragile|improving|interview_ready|strong_signal",
+      "next": "unknown|fragile|improving|interview_ready|strong_signal",
+      "reason": "string",
+      "evidence": ["evidence_ref"]
+    }
+  ],
+  "unlocks": [
+    {
+      "kind": "boss_question|review_card|portfolio_entry",
+      "label": "string",
+      "reason": "string"
+    }
+  ]
+}
+```
+
+## OntologyGap
+
+Produced by `detect_ontology_gaps`.
+
+```json
+{
+  "track": "backend-developer",
+  "missing_or_weak": [
+    {
+      "concept": "concept_ref",
+      "gap_type": "missing_prerequisite|weak_evidence|outdated|needs_rubric",
+      "reason": "string",
+      "supporting_sources": ["evidence_ref"],
+      "proposed_action": "generate_candidate|request_source|human_review"
+    }
+  ]
+}
+```
+
+## TeachingAssetPrompt
+
+Produced by `generate_teaching_asset_prompt`.
+
+```json
+{
+  "concept": "concept_ref",
+  "asset_type": "diagram|lesson_slice|worksheet|interview_card",
+  "prompt": "string",
+  "source_evidence": ["evidence_ref"],
+  "model_key": "gpt-image-v2",
+  "requires_model_id_verification": true,
+  "review_state": "candidate"
+}
+```
+
+## Validation Rules
+
+- Required IDs must be non-empty.
+- Any state-changing output must include evidence.
+- Confidence values must be between 0 and 1.
+- Generated or inferred content starts as `candidate` or `tentative`.
+- `model_key` is a product config key; production code must verify the actual
+  provider model identifier before image calls.

openspec/changes/bootstrap-job-tutor-platform/specs/job-seeker-tutor/spec.md

@@ -15,6 +15,14 @@ while preserving an architecture that can later support general students.
 - **AND** grades the user's answers against explicit rubrics
 - **AND** creates an initial concept weakness map.
 
+#### Scenario: backend developer track is the first canonical track
+
+- **GIVEN** the MVP track catalog is initialized
+- **WHEN** the system loads the first interview track
+- **THEN** it provides the Backend Developer Interview track
+- **AND** includes HTTP, REST/API design, databases, transactions, caching,
+  concurrency, testing, and system design basics as seed concept clusters.
+
 #### Scenario: practice session adapts to weak answers
 
 - **GIVEN** a user answers an interview question weakly or incorrectly

openspec/changes/bootstrap-job-tutor-platform/specs/tutor-workflows/spec.md

@@ -23,6 +23,15 @@ The system SHALL express core tutor behavior as configurable workflows using
 - **THEN** it emits memory update candidates
 - **AND** each candidate identifies its evidence and confidence.
 
+#### Scenario: initial contract set is available for backend planning
+
+- **GIVEN** the backend workflow boundary is planned
+- **WHEN** implementation begins
+- **THEN** the initial contract set includes DiagnosticResult, GradedAnswer,
+  MemoryUpdateCandidate, NextChallenge, ReadinessUpdate, OntologyGap, and
+  TeachingAssetPrompt
+- **AND** each state-changing contract carries evidence references.
+
 ### Requirement: Default LLM runtime is configurable
 
 The system SHALL keep the LLM model target configurable while defaulting the

openspec/changes/bootstrap-job-tutor-platform/tasks.md

@@ -7,8 +7,9 @@
 - [x] 4. Incorporate game-design learning loop and progression planning.
 - [x] 5. Add repository engineering principles and code-size constraints.
 - [x] 6. Lock Go backend and internalized agent-farm workflow direction.
-- [ ] 7. Choose the first interview track and canonical concept seed list.
-- [ ] 8. Define typed JSON contracts for diagnostic, grading, memory extraction,
+- [x] 7. Choose the first interview track and canonical concept seed list.
+- [x] 8. Define typed JSON contracts for diagnostic, grading, memory extraction,
   ontology gap detection, and asset prompt generation.
-- [ ] 9. Draft the first `agent-farm-go` YAML workflow package.
-- [x] 10. Validate the OpenSpec change.
+- [x] 9. Create Phase 1 GSD context, research, and plan artifacts.
+- [ ] 10. Draft the first `agent-farm-go` YAML workflow package.
+- [x] 11. Validate the OpenSpec change.