feat: scaffold go backend foundation

internal/workflows/contracts.go

@@ -0,0 +1,192 @@
+package workflows
+
+type EvidenceKind string
+
+const (
+	EvidenceAnswer  EvidenceKind = "answer"
+	EvidenceGrading EvidenceKind = "grading"
+	EvidenceSource  EvidenceKind = "source"
+	EvidenceSession EvidenceKind = "session"
+	EvidenceAsset   EvidenceKind = "asset"
+)
+
+type EvidenceRef struct {
+	Kind       EvidenceKind `json:"kind"`
+	ID         string       `json:"id"`
+	Quote      string       `json:"quote,omitempty"`
+	Confidence float64      `json:"confidence"`
+}
+
+type ConceptRef struct {
+	ID    string `json:"id"`
+	Label string `json:"label"`
+	Track string `json:"track"`
+}
+
+type ReadinessState string
+
+const (
+	ReadinessUnknown        ReadinessState = "unknown"
+	ReadinessFragile        ReadinessState = "fragile"
+	ReadinessImproving      ReadinessState = "improving"
+	ReadinessInterviewReady ReadinessState = "interview_ready"
+	ReadinessStrongSignal   ReadinessState = "strong_signal"
+)
+
+type DiagnosticResult struct {
+	UserID                  string           `json:"user_id"`
+	Track                   string           `json:"track"`
+	TargetRole              string           `json:"target_role"`
+	Stack                   []string         `json:"stack"`
+	InitialReadiness        ReadinessState   `json:"initial_readiness"`
+	ConceptFindings         []ConceptFinding `json:"concept_findings"`
+	RecommendedNextConcepts []ConceptRef     `json:"recommended_next_concepts"`
+}
+
+type ConceptFinding struct {
+	Concept   ConceptRef     `json:"concept"`
+	Readiness ReadinessState `json:"readiness"`
+	Reason    string         `json:"reason"`
+	Evidence  []EvidenceRef  `json:"evidence"`
+}
+
+type GradedAnswer struct {
+	AnswerID                string                   `json:"answer_id"`
+	QuestionID              string                   `json:"question_id"`
+	Concepts                []ConceptRef             `json:"concepts"`
+	Scores                  AnswerScores             `json:"scores"`
+	Overall                 AnswerOverall            `json:"overall"`
+	Strengths               []string                 `json:"strengths"`
+	Gaps                    []string                 `json:"gaps"`
+	MisconceptionCandidates []MisconceptionCandidate `json:"misconception_candidates"`
+	FollowUp                FollowUpRecommendation   `json:"follow_up"`
+}
+
+type AnswerScores struct {
+	Correctness        int `json:"correctness"`
+	Depth              int `json:"depth"`
+	Communication      int `json:"communication"`
+	ProductionJudgment int `json:"production_judgment"`
+}
+
+type AnswerOverall string
+
+const (
+	AnswerMiss    AnswerOverall = "miss"
+	AnswerPartial AnswerOverall = "partial"
+	AnswerSolid   AnswerOverall = "solid"
+	AnswerStrong  AnswerOverall = "strong"
+)
+
+type MisconceptionCandidate struct {
+	Label       string        `json:"label"`
+	Description string        `json:"description"`
+	Evidence    []EvidenceRef `json:"evidence"`
+	Confidence  float64       `json:"confidence"`
+}
+
+type FollowUpRecommendation struct {
+	Needed   bool            `json:"needed"`
+	Question string          `json:"question,omitempty"`
+	Purpose  FollowUpPurpose `json:"purpose,omitempty"`
+}
+
+type FollowUpPurpose string
+
+const (
+	FollowUpClarify      FollowUpPurpose = "clarify"
+	FollowUpRepair       FollowUpPurpose = "repair"
+	FollowUpStretch      FollowUpPurpose = "stretch"
+	FollowUpPressureTest FollowUpPurpose = "pressure_test"
+)
+
+type MemoryUpdateCandidate struct {
+	UserID         string         `json:"user_id"`
+	SourceAnswerID string         `json:"source_answer_id"`
+	Updates        []MemoryUpdate `json:"updates"`
+}
+
+type MemoryUpdate struct {
+	Kind          MemoryUpdateKind `json:"kind"`
+	Concept       ConceptRef       `json:"concept"`
+	ProposedState ReadinessState   `json:"proposed_state"`
+	Summary       string           `json:"summary"`
+	Evidence      []EvidenceRef    `json:"evidence"`
+	Confidence    float64          `json:"confidence"`
+	Durability    Durability       `json:"durability"`
+}
+
+type MemoryUpdateKind string
+
+const (
+	MemoryConceptMastery MemoryUpdateKind = "concept_mastery"
+	MemoryMisconception  MemoryUpdateKind = "misconception"
+	MemoryIntervention   MemoryUpdateKind = "intervention"
+	MemoryReviewSchedule MemoryUpdateKind = "review_schedule"
+)
+
+type Durability string
+
+const (
+	DurabilityTentative Durability = "tentative"
+	DurabilityConfirmed Durability = "confirmed"
+)
+
+type NextChallenge struct {
+	UserID           string           `json:"user_id"`
+	Track            string           `json:"track"`
+	Concept          ConceptRef       `json:"concept"`
+	LadderLevel      LadderLevel      `json:"ladder_level"`
+	Question         string           `json:"question"`
+	Rationale        string           `json:"rationale"`
+	DifficultyAction DifficultyAction `json:"difficulty_action"`
+	Evidence         []EvidenceRef    `json:"evidence"`
+}
+
+type LadderLevel string
+
+const (
+	LadderDefine            LadderLevel = "define"
+	LadderTradeoffs         LadderLevel = "tradeoffs"
+	LadderDebug             LadderLevel = "debug"
+	LadderDesignConstraints LadderLevel = "design_constraints"
+	LadderInterviewPressure LadderLevel = "interview_pressure"
+)
+
+type DifficultyAction string
+
+const (
+	DifficultyLower   DifficultyAction = "lower"
+	DifficultyHold    DifficultyAction = "hold"
+	DifficultyRaise   DifficultyAction = "raise"
+	DifficultyRecover DifficultyAction = "recover"
+)
+
+type ReadinessUpdate struct {
+	UserID         string                  `json:"user_id"`
+	Track          string                  `json:"track"`
+	ConceptUpdates []ConceptReadinessDelta `json:"concept_updates"`
+	Unlocks        []Unlock                `json:"unlocks"`
+}
+
+type ConceptReadinessDelta struct {
+	Concept  ConceptRef     `json:"concept"`
+	Previous ReadinessState `json:"previous"`
+	Next     ReadinessState `json:"next"`
+	Reason   string         `json:"reason"`
+	Evidence []EvidenceRef  `json:"evidence"`
+}
+
+type Unlock struct {
+	Kind   UnlockKind `json:"kind"`
+	Label  string     `json:"label"`
+	Reason string     `json:"reason"`
+}
+
+type UnlockKind string
+
+const (
+	UnlockBossQuestion   UnlockKind = "boss_question"
+	UnlockReviewCard     UnlockKind = "review_card"
+	UnlockPortfolioEntry UnlockKind = "portfolio_entry"
+)

internal/workflows/runner.go

@@ -0,0 +1,66 @@
+package workflows
+
+import (
+	"context"
+	"errors"
+)
+
+var ErrNotImplemented = errors.New("workflow runner not implemented")
+
+type DiagnosticInput struct {
+	UserID     string
+	Track      string
+	TargetRole string
+	Stack      []string
+}
+
+type Runner interface {
+	DiagnoseJobSeeker(context.Context, DiagnosticInput) (DiagnosticResult, error)
+	GradeInterviewAnswer(context.Context, GradeAnswerInput) (GradedAnswer, error)
+	ExtractLearningMemory(context.Context, GradedAnswer) (MemoryUpdateCandidate, error)
+	SelectNextChallenge(context.Context, NextChallengeInput) (NextChallenge, error)
+	UpdateReadinessMap(context.Context, ReadinessUpdateInput) (ReadinessUpdate, error)
+}
+
+type GradeAnswerInput struct {
+	UserID     string
+	QuestionID string
+	AnswerID   string
+	AnswerText string
+}
+
+type NextChallengeInput struct {
+	UserID string
+	Track  string
+}
+
+type ReadinessUpdateInput struct {
+	UserID string
+	Track  string
+}
+
+type StubRunner struct{}
+
+func NewStubRunner() StubRunner {
+	return StubRunner{}
+}
+
+func (StubRunner) DiagnoseJobSeeker(context.Context, DiagnosticInput) (DiagnosticResult, error) {
+	return DiagnosticResult{}, ErrNotImplemented
+}
+
+func (StubRunner) GradeInterviewAnswer(context.Context, GradeAnswerInput) (GradedAnswer, error) {
+	return GradedAnswer{}, ErrNotImplemented
+}
+
+func (StubRunner) ExtractLearningMemory(context.Context, GradedAnswer) (MemoryUpdateCandidate, error) {
+	return MemoryUpdateCandidate{}, ErrNotImplemented
+}
+
+func (StubRunner) SelectNextChallenge(context.Context, NextChallengeInput) (NextChallenge, error) {
+	return NextChallenge{}, ErrNotImplemented
+}
+
+func (StubRunner) UpdateReadinessMap(context.Context, ReadinessUpdateInput) (ReadinessUpdate, error) {
+	return ReadinessUpdate{}, ErrNotImplemented
+}

internal/workflows/runner_test.go

@@ -0,0 +1,21 @@
+package workflows
+
+import (
+	"context"
+	"errors"
+	"testing"
+)
+
+func TestStubRunnerReturnsTypedNotImplemented(t *testing.T) {
+	runner := NewStubRunner()
+
+	_, err := runner.DiagnoseJobSeeker(context.Background(), DiagnosticInput{
+		UserID:     "user-1",
+		Track:      "backend-developer",
+		TargetRole: "junior-backend-developer",
+	})
+
+	if !errors.Is(err, ErrNotImplemented) {
+		t.Fatalf("err = %v, want %v", err, ErrNotImplemented)
+	}
+}