truecourse CLAUDE.md

TrueCourse — Claude Instructions

Key Files to Keep Updated

• docs/SPEC_GUARD_PLAN.md — The source of truth for the guard (spec → scenario) pipeline: design, implementation status, and the numbered decision/work items. When completing work on an item, update its STATUS:; when adding features or changing scope, update the plan.
• README.md — Must reflect the current state of the project. When adding new packages, endpoints, commands, environment variables, or changing the project structure, update the README to match.

Project Layout

• apps/dashboard/client/ — Vite + React Router frontend (React Flow graph, Tailwind CSS, dark mode)
• apps/dashboard/server/ — Express + Socket.io HTTP layer that serves the dashboard. Thin adapter over @truecourse/core; contains routes, sockets, middleware, and dashboard-only services (analytics, watcher, telemetry).
• apps/landing/ — Public marketing site (Vite + React + Tailwind v4). Standalone, deployed separately from the local dashboard. pnpm --filter @truecourse/landing dev runs it on port 3100. Sample OSS analysis reports live in apps/landing/src/data/analyses.ts.
• packages/core/ — Framework-agnostic analysis engine: pipeline, graph/flow services, LLM providers, persistence (analysis-store), config, logger, errors. Consumed by both the CLI and the dashboard server.
• packages/analyzer/ — Tree-sitter (WASM via web-tree-sitter) + TypeScript Compiler analysis engine (TS/JS/Python)
• packages/interface-mapper/ — The deterministic interface catalog: CLI (tree + probes), API (route registrations, OpenAPI contracts), RPC routers and web places/resources derived from the analyzer's per-file facts. Feeds guard setup's interfaces step and guard interfaces author; depends only on @truecourse/shared and @truecourse/guard-runner.
• packages/llm-api/ — The direct-API LlmTransport (createApiTransport) on the Vercel AI SDK: anthropic | openai | bedrock | copilot, generateObject when the request carries a schema, per-call StageUsage. The only OSS package allowed to import ai / @ai-sdk/* (enforced by tests/architecture/ee-import-boundary.test.ts); @truecourse/ee-llm re-exports it. Also home to the api-mode session driver (createApiSessionDriver) — the per-turn loop the agent sessions run on in api mode — and the per-provider cache/tool-call tuning table it applies.
• packages/llm-claude-agent/ — The Agent SDK session driver (createClaudeAgentSessionDriver): claude-code mode of the agent loop, one streaming-input query() subprocess per session, tools as in-process MCP handlers, outcome via native json-schema output. The only package allowed to reference @anthropic-ai/claude-agent-sdk (enforced by the same boundary test), which is an OPTIONAL peer behind a lazy import — never a compile-time dependency (its optionalDependencies drag a ~300MB binary).
• packages/agent-loop/ — The agent loop, defined in ONE package: the session contract (transcript events, session defs, the SessionDriver seam, sessions-store shapes) and the policy shell runAgentLoop (budgets, ceilings, resume grants, malformed-outcome policy, seq/ts stamping, depth-1 children). Driver-agnostic by construction — imports neither ai nor the Agent SDK nor node builtins; one package per backend implements the seam (llm-api, llm-claude-agent).
• packages/core/src/services/guard-setup/ — guard setup's agent sessions, injected into @truecourse/guard-generator's runGuardSetup (which stays core-free) by commands/guard-setup.ts: recipe-repair (loop only on the failure path of deterministic recipe discovery, iterating in one persistent WorkingSandbox), dependency-catalog (classify the starting state after the deterministic externals skeleton; add-only fold into scenarios/dependencies.json), interfaces-step + reconcile-interfaces (the deterministic interface catalog from @truecourse/interface-mapper, a reconcile session that settles tree-vs-probe disagreements, and the services/interface-author/ engine behind guard interfaces author; the derived catalog is guard/interfaces.json, the authored one guard/interfaces.authored.json), seed-session (prove-by-execution seed authoring against the live services; the fold re-proves the outcome in a fresh world and restores the tree on refusal) and auth-proof (one short session per user-registered supplied dependency; proof-class, never cached). session-context.ts is the holder of the run record + driver every seam draws from — lazy for the CLI, eager and keyed by repo identity for a hosted run.
• packages/core/src/services/spec-scan/ — The spec scan as agent sessions, the loop's first production consumer: orchestrate (≤1 scope session whose standing instructions ride every downstream briefing and cache key), curate-doc (pooled, one coherent keep/skip/tag judgment per doc — it may page a long doc and peek at a referenced one), settle-areas (a true barrier, concurrency 1) and overlap (pooled, one session per deterministic COLLISION CLUSTER). run.ts is the whole scan: discovery → prefilter → the four steps → the deterministic fold (pointer re-anchoring, cross-area dedup, high-confidence auto-apply) → writeCorpus. Two invariants: FAIL-OPEN per item (a dead session never drops a doc), and the ONE-ABORT rule — a kind whose every session died transport-class throws BEFORE anything is written. @truecourse/spec-consolidator keeps the deterministic half (discovery, prefilter, collision pairing, pointer verification, area grouping, the corpus/decisions stores); it holds no LLM runner and no LlmTransport reference at all.
• packages/shared/ — Shared Zod schemas and TypeScript types
• packages/db/ — @truecourse/db: the Postgres schema (drizzle) + createDb (one pool, migrations at boot, a dedicated advisory-lock pool). Used by the dashboard server and EE.
• packages/data-store/ — @truecourse/data-store: Postgres implementations of core's storage seams (analyses, specs, guard, config/ui-state, the gh_repos-derived registry, the LLM KV cache, the advisory analyze lock) over a content-addressed content table. Installed by the dashboard server at boot (apps/dashboard/server/src/stores.ts); @truecourse/ee-data-store re-exports it and keeps only EE-only stores (knowledge, traces, workspace settings). The jobs, notifications and pending-baseline stores live here too (jobs-store.ts), consumed by @truecourse/jobs.
• packages/github-app/ — The GitHub App protocol: webhook receiver, connect API, the gh_repos/installations link store (PostgresGateStore).
• packages/jobs/ — @truecourse/jobs: the generic background job runner. A Postgres-backed queue (graphile-worker) with a tracked row per job, the shared lifecycle harness (executeJob: row bookkeeping, the stepped checklist, the standardized notification, the settled hook), a local cancel registry, the LISTEN/NOTIFY event hub, and the three routers the server mounts (/api/events, /api/jobs, /api/notifications). Enqueues are single-flight per (workspace, key). Job TYPES live with their consumer — the dashboard server's are in apps/dashboard/server/src/jobs/tasks/.
• tools/cli/ — CLI commands (analyze, dashboard, list, add, rules). Thin adapter over @truecourse/core — does NOT depend on the dashboard server.
• tests/ — All tests (centralized, not colocated). Organized by package: tests/shared/, tests/analyzer/, tests/server/ (covers both dashboard-server routes and core services), tests/cli/.
• tests/fixtures/ — Fixture repos the tests drive: sample-{js,python,csharp}-project-{positive,negative,il}/ (analyzer rule fixtures), sample-scheduling-saas/, guard-fixture-cli/ (the relkit CLI) and guard-fixture-api/ (the todos + api-v2 HTTP servers) for the guard drivers, recipe-propose/ and route-manifest-monorepo/ for the deterministic recipe/route derivations