docs: plan backend foundation phase

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