docs: audit v1 milestone

2026-04-26 18:00:59 +09:00
parent 156daa9087
commit 4bb1d07f94
2 changed files with 171 additions and 4 deletions
--- a/.planning/v1-MILESTONE-AUDIT.md
+++ b/.planning/v1-MILESTONE-AUDIT.md
@@ -0,0 +1,160 @@
+---
+milestone: v1
+audited: 2026-04-26
+status: tech_debt
+scores:
+  requirements: 28/28
+  phases: 6/6
+  integration: 6/6
+  flows: 2/2
+gaps:
+  requirements: []
+  integration: []
+  flows: []
+tech_debt:
+  - phase: "001-go-backend-foundation-and-workflow-boundary"
+    items:
+      - "Workflow runner is still a deterministic stub; real third-one/agent-farm runtime is deferred."
+      - "Persistence, auth, frontend, ontology, and asset generation were deferred from the foundation phase."
+  - phase: "002-diagnostic-interview-loop"
+    items:
+      - "Diagnostic sessions are in-memory and lost on process restart."
+      - "Real third-one grading calls are deferred."
+  - phase: "003-learner-memory"
+    items:
+      - "Learner memory is in-memory."
+      - "Memory decay, ranking, and repeated-mistake clustering are deferred."
+  - phase: "004-progression"
+    items:
+      - "Readiness history, campaign state, and streak persistence are deferred."
+      - "Boss unlocks use simple stable-count logic rather than a richer concept cluster graph."
+  - phase: "005-ontology-materials"
+    items:
+      - "Material ingestion accepts JSON text only; multipart/PDF/PPT parsing is deferred."
+      - "Ontology analyzer is deterministic and shallow."
+      - "Human review and graph database persistence are deferred."
+  - phase: "006-teaching-assets"
+    items:
+      - "Prompt candidates are generated, but real image generation is deferred."
+      - "gpt-image-v2 is a product config key; actual provider model id must be verified before production calls."
+      - "Binary asset storage and slide/PPT export are deferred."
+nyquist:
+  compliant_phases: []
+  partial_phases: []
+  missing_phases:
+    - "001-go-backend-foundation-and-workflow-boundary"
+    - "002-diagnostic-interview-loop"
+    - "003-learner-memory"
+    - "004-progression"
+    - "005-ontology-materials"
+    - "006-teaching-assets"
+  overall: missing
+---
+
+# v1 Milestone Audit
+
+## Verdict
+
+TECH_DEBT
+
+All v1 functional requirements are satisfied and all phase verification reports
+are PASS. No critical requirement, integration, or end-to-end flow blocker was
+found.
+
+The milestone should still be treated as a tech-debt review before archival
+because the v1 backend is intentionally MVP-scoped: in-memory stores, stubbed
+workflow execution, shallow deterministic ontology extraction, and prompt-only
+teaching assets.
+
+## Scope
+
+| Phase | Name | Verification |
+|-------|------|--------------|
+| 1 | Go backend foundation and workflow boundary | PASS |
+| 2 | Diagnostic interview loop | PASS |
+| 3 | Learner memory | PASS |
+| 4 | Progression | PASS |
+| 5 | Ontology and learning materials | PASS |
+| 6 | Teaching assets | PASS |
+
+## Requirements Coverage
+
+| Requirement Group | Count | Status | Evidence |
+|-------------------|-------|--------|----------|
+| BACK-01..BACK-05 | 5/5 | Satisfied | Phase 1 verification |
+| INT-01..INT-06 | 6/6 | Satisfied | Phase 2 verification |
+| MEM-01..MEM-05 | 5/5 | Satisfied | Phase 3 verification |
+| PROG-01..PROG-05 | 5/5 | Satisfied | Phase 4 verification |
+| ONTO-01..ONTO-04 | 4/4 | Satisfied | Phase 5 verification |
+| ASSET-01..ASSET-03 | 3/3 | Satisfied | Phase 6 verification |
+
+Total: 28/28 v1 requirements satisfied.
+
+## Cross-Phase Integration
+
+| Flow | Result | Evidence |
+|------|--------|----------|
+| Diagnostic to learner memory to progression | PASS | Live smoke created a diagnostic session, submitted an answer, read learner memory, readiness map, and next challenge. |
+| Material ingestion to ontology to teaching asset prompt | PASS | Live smoke ingested material, read ontology candidates, and generated a source-backed teaching asset prompt. |
+| App wiring | PASS | `internal/app/server.go` wires workflow runner, interview service, learner memory, progression, ontology, and teaching assets into one HTTP handler. |
+| Typed workflow boundary | PASS | State-changing workflow outputs use Go structs and evidence references; handlers do not parse shell output. |
+| Source lineage | PASS | Ontology candidates and teaching asset prompts preserve source evidence and candidate review state. |
+| Image model guard | PASS | Teaching asset prompts store `model_key` and keep `requires_model_id_verification=true`. |
+
+## End-to-End Smoke Evidence
+
+Latest audit smoke result:
+
+```json
+{
+  "SessionID": "diag-1",
+  "AnswerGrade": "solid",
+  "MemoryMastery": 1,
+  "Readiness": 75,
+  "ChallengeConcept": "http-idempotency",
+  "MaterialID": "material-1",
+  "OntologyConcepts": 4,
+  "OntologyEdges": 3,
+  "AssetPromptID": "asset-prompt-1",
+  "AssetModelKey": "gpt-image-v2",
+  "AssetRequiresVerification": true
+}
+```
+
+## Validation Evidence
+
+- `go test ./...` passed.
+- `openspec validate bootstrap-job-tutor-platform --strict` passed.
+- Go source line-count check passed; no manually authored Go file exceeds 600
+  lines.
+- Git worktree was clean before the audit began.
+
+## Requirement Cross-Reference Notes
+
+The requirement checklist and phase verification reports agree: every v1
+requirement is marked complete and has a matching PASS entry in the relevant
+phase verification file.
+
+Phase summary files do not include YAML frontmatter with
+`requirements-completed`. This is not a product blocker because each summary has
+a matching verification report, but adding standardized summary frontmatter
+would make future automated audits cleaner.
+
+## Nyquist Discovery
+
+No `*-VALIDATION.md` files were found for phases 1 through 6. This audit treats
+that as validation-process debt rather than a v1 product blocker because each
+phase already has a PASS verification report plus current tests and smoke
+coverage.
+
+## Recommended Next Milestone
+
+Choose one of these as the next milestone:
+
+- Frontend MVP: build the web experience on top of the completed backend flow.
+- Persistence: replace in-memory stores with durable storage and migration
+  boundaries.
+- Real workflow runtime: connect the typed runner boundary to third-one and
+  internalized agent-farm workflow execution.
+- Document parser integration: add PDF/PPT/slide/document ingestion before
+  richer ontology work.