Phase 3: server-enforced pedagogy state machine + new session/hint tools

[devin-ai-integration]

Summary

Phase 3 of the redesign plan. Pedagogy moves from honor-system prompts to a server-enforced state machine: a per-problem session JSON tracks hintLevel (0–4), attempts, lastLocalRunPassed, status. list_problem_solutions and get_problem_solution are gated at the wire — they reject with HINT_LEVEL_TOO_LOW until the active session has reached the maximum level. The MCP instructions field replaces the prompt-based "remember to invoke X first" dance with rules clients receive once at handshake.

Stacked on top of #37; base auto-rebases to main once #37 reaches main.

Domain layer (src/domain/, one commit, pure logic + tests):

• hint-state-machine.ts — advanceHint / resetSession / assertSolutionUnlocked. No IO.
• pedagogy.ts — generateHint(problem, level, userCode?). Level 1 clarification → 2 approach → 3 implementation sketch → 4 solution unlock. userCode parameter is reserved for Phase 5 (workspace awareness) so the contract is stable.
• session-store.ts — FileSessionStore: one JSON per slug under ~/.leetcode-mcp/sessions/, mode 0o600, with malformed-file recovery and slug validation (rejects anything not matching ^[a-z0-9-]+$ to prevent path traversal).
• 23 unit tests under tests/domain/ cover every transition, gate, hint projection, and store edge case.

Application layer (src/domain/session-service.ts, one commit):

• SessionService is the single seam tools depend on. startOrResume is idempotent — re-running on a slug the user is already mid-way through preserves hint progress. assertSolutionUnlocked is the gate.

Wire layer (four commits):

• src/mcp/server-instructions.ts — the instructions string. Plain exported constant so it's unit-testable and easy to evolve.
• src/mcp/tools/session-tools.ts — four new tools: start_problem, request_hint, get_session_state, reset_session. Errors flow through a shared errorEnvelope that surfaces the structured code field alongside the human message.
• src/mcp/tools/solution-tools.ts — gates list_problem_solutions (already takes questionSlug) and adds a required titleSlug parameter to get_problem_solution so the gate has session context (a topicId alone doesn't tell us which session to verify).
• src/index.ts — McpServer constructor receives ServerOptions with instructions set. SessionService is constructed once per server lifetime and shared across the new and gated tools.

Tests (one commit, additive):

• tests/integration/solution-tools-integration.test.ts rewritten to inject a SessionService over a per-test temp dir; adds three gate cases (no session, below unlock, at unlock) for each tool. 8 tests, all pass.
• tests/e2e/lifecycle.test.ts — expected-tools list extended with the four new tools.
• tests/e2e/pedagogy-gate.test.ts (new) — drives a real server through start_problem → request_hint × 4 with a mocked GraphQL fixture, asserts list_problem_solutions rejects with HINT_LEVEL_TOO_LOW at every pre-unlock level and only opens at level 4. Second case: reset_session clamps back to 0 and re-engages the gate.

Tests: unit/integration 152 → 178 (+26 — 23 domain + 3 gate); e2e 7 → 9 (+2 gate cases). npm run build clean; npm run test:types clean; npm run format clean; full npm run test:all exits 0.

Why not amend behavior beyond gating + new tools:

• Existing tools (get_problem, submit_solution, etc.) keep their current signatures — Phase 3 deliberately ships only the state machine and the gate. Wiring submit_solution to the session for attempts tracking lands in Phase 6.
• get_started is kept as-is; the redesign plan called for it to be deprecated alongside the instructions field rollout, but I'd rather observe that the instructions field is honored by the clients you care about before turning get_started into a stub. Trivial follow-up if you want it.
• learning-prompts.ts survives unchanged for the same reason — clients on older MCP versions that don't honor instructions still see the prompts.

Breaking change (additive): get_problem_solution now requires titleSlug in addition to topicId. Existing clients calling without titleSlug will see a clear "required" Zod error.

Review & Testing Checklist for Human

• Spot-check src/domain/hint-state-machine.ts and assertSolutionUnlocked — this is the gate and any bug here defeats the whole pedagogy contract
• Confirm the instructions field copy in src/mcp/server-instructions.ts reads the way you want — it's the single source of truth the client will read at handshake
• Verify the slug regex in src/domain/session-store.ts (^[a-z0-9-]+$) accepts every slug shape LeetCode actually uses (I checked a sample but you have a longer history with it)
• Run npm run test:all locally to confirm e2e specs pass on your platform (Linux Node 22 in CI)

Notes

• This PR is stacked on top of Phase 2: real e2e harness — spawn build/index.js + nock + isolated HOME #37 (Phase 2). Once Phase 2: real e2e harness — spawn build/index.js + nock + isolated HOME #37 reaches main, the base will auto-rebase and this PR's diff will shrink to just the seven Phase 3 commits.
• Phase 3 part 2 (drive attempts from submit_solution and surface session info on get_problem) lands with Phase 6 (submission hardening) — kept out of this PR to keep the diff focused on pedagogy.
• Phase 4 (local Python/Go/Java runners) is independent of this and starts next.

Link to Devin session: https://app.devin.ai/sessions/d003a60939484686b2953ae32fe2794d
Requested by: @SPerekrestova

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[SPerekrestova]

LGTM

---

Generated by Claude Code

[devin-ai-integration]

Thanks for the LGTM. Continuing autonomously to Phase 4a (Python local runner) on a separate branch — will open the next PR shortly.