tutor-service/.planning/v1-MILESTONE-AUDIT.md

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