docs: bootstrap tutor planning

docs/planning/ENGINEERING.md

@@ -0,0 +1,121 @@
+# Engineering Principles
+
+## Purpose
+
+This document defines how the tutor platform should be implemented once coding
+begins. The product is expected to grow across web UI, API backend, workflow
+orchestration, learner memory, ontology processing, and generated learning
+assets. Without explicit constraints, those areas can easily collapse into large
+files and overbuilt abstractions.
+
+## Core Rules
+
+### 0. Backend language
+
+The backend is Go.
+
+This decision aligns the service with `agent-farm-go` so workflow orchestration
+can become an internal product capability rather than a loosely attached
+automation script. Keep the Go service modular and avoid turning the backend
+into one large workflow coordinator.
+
+### 1. File size limit
+
+No source file should exceed 600 lines.
+
+When a file approaches the limit, split it by responsibility. Good split points:
+
+- route registration vs handler logic
+- handler logic vs service logic
+- service orchestration vs domain rules
+- domain rules vs persistence adapter
+- workflow contract definitions vs workflow execution
+- UI page shell vs reusable components
+
+Exemptions:
+
+- generated files
+- lockfiles
+- vendored files
+- external source snapshots
+- large fixture data
+
+### 2. SOLID
+
+Apply SOLID pragmatically:
+
+- Single responsibility: learner memory, ontology, grading, progression, and
+  asset generation should not live in one service.
+- Open/closed: add new interview tracks or asset types through data/config and
+  narrow extension points where practical.
+- Liskov substitution: adapters should honor shared contracts without hidden
+  behavior changes.
+- Interface segregation: avoid giant service interfaces.
+- Dependency inversion: domain logic should not depend directly on provider SDKs
+  or database details.
+
+### 3. KISS
+
+Prefer the simplest implementation that proves the current product loop:
+
+```text
+question -> answer -> grading -> memory update -> next challenge
+```
+
+Do not introduce queues, distributed workers, plugin systems, or complex
+multi-agent orchestration until the MVP loop needs them.
+
+### 4. YAGNI
+
+Do not build features only because they may be useful later.
+
+Examples to defer until proven necessary:
+
+- multi-school LMS administration
+- marketplace course publishing
+- company-specific interview packs
+- generalized ontology editor
+- multiple image providers
+- complex economy systems
+- social leaderboards
+
+## Product Module Boundaries
+
+Initial implementation should keep these responsibilities distinct:
+
+- `auth`: users, sessions, identity providers.
+- `interview`: questions, rubrics, answers, grading records.
+- `learner_memory`: profiles, concept mastery, misconceptions, evidence.
+- `ontology`: concepts, prerequisites, source evidence, generated candidates.
+- `progression`: readiness maps, challenge ladders, boss questions, streaks.
+- `workflows`: typed contracts and calls into `agent-farm-go` / `third-one`.
+- `assets`: generated diagrams, lesson slices, prompt lineage, review state.
+
+The names can change with the chosen stack, but the responsibilities should stay
+separate.
+
+## Workflow Contracts
+
+LLM workflow outputs should be typed and inspectable. Avoid relying on freeform
+assistant prose for product state changes.
+
+First contracts to define:
+
+- `DiagnosticResult`
+- `GradedAnswer`
+- `MemoryUpdateCandidate`
+- `NextChallenge`
+- `ReadinessUpdate`
+- `OntologyGap`
+- `TeachingAssetPrompt`
+
+## Review Checklist
+
+Before considering an implementation slice complete:
+
+- No manually authored source file exceeds 600 lines.
+- New behavior maps to an OpenSpec requirement or updates OpenSpec.
+- The implementation keeps responsibilities separated.
+- The simplest useful design was chosen.
+- No future-only abstraction was added.
+- Tests or smoke checks prove the touched behavior.