TRACE: Instructions file for Claude Code

TRACE — Project Instructions

Full documentation: README.md (architecture, tools, configuration, changelog) Orientation: docs/ONBOARDING.md (dev + user onboarding) · docs/WHAT-IS-TRACE.md (non-technical explainer) Formal specification: docs/specification.md Version: 0.5.2.dev0 (package, unreleased; latest release 0.5.1) · protocol/schema v0.5.1 TRACE project name: "trace-mcp" (canonical project key: trace-mcp)

Development

uv pip install -e ".[dev]"          # Install with dev dependencies
uv run pytest                       # Run full test suite (1240+ tests)
uv run pytest tests/test_invariants.py       # Invariant-registry guard (docs/INVARIANTS.md) — fast
uv run pytest -k llm                # Run real LLM integration tests
uv run ruff check src/              # Lint
uv run pyright src/                 # Type check
python scripts/generate_schema.py   # Regenerate JSON Schema from Pydantic models
uv build && uv run pytest tests/test_packaging_artifacts.py   # Verify the shipped wheel/sdist before tagging
trace-mcp identity check            # Report project-identity drift (non-zero exit on findings)
trace-mcp doctor [DIR] [--live]     # Report deployed-state drift for one project (non-zero exit on findings)
trace-mcp fleet-check [ROOTS...]    # Same check across every TRACE project under the given roots

Two console scripts ship with the package: trace-mcp (the MCP server) and trace-mcp-init (writes .mcp.json, the TRACE_PROJECT pin, and host adapter assets into a consumer project). trace-mcp identity dispatches to the migration tooling (snapshot, scan, apply, check, merge-stores, adopt, bundle) — see docs/adr/006-project-identity-and-isolation.md.

Key Patterns

• Pydantic v2 for all data models: model_dump(), model_validate(), model_rebuild()
• Forward refs across files: Import both models in schema/__init__.py, call model_rebuild() after
• All modules import Session from trace_mcp.schema (not .schema.session) to trigger rebuild
• from datetime import UTC (not timezone.utc) — ruff UP017
• MCPServer (mcp 2.x) @mcp.tool() needs parentheses
• asyncio_mode = "auto" in pytest config for async tests
• Atomic writes (temp file + os.replace) for all JSON writes — no fcntl dependency (cross-platform)
• Session writes go through storage.locked.locked_disk_session — the single fail-closed, disk-truth read-modify-write path (INV-1, docs/INVARIANTS.md). Never hand-roll a lock block; never let a write proceed on a lock timeout.
• Fail closed on integrity primitives: the per-session lock raises TimeoutError rather than writing unlocked; stale-lock theft is gated on holder-PID liveness. A missed lock must be visible, not silent.
• Read aggregates skip-and-report: project_summary/health_check catch per-session ValidationError/JSONDecodeError and surface a skipped_sessions list rather than aborting the whole aggregate.
• Schema models preserve unknown fields (extra="allow" via the TraceModel base) for forward-compat; Environment is the one closed exception (legacy trace_version drop).
• A project is identified by its canonical key, never by its free-text label — metadata.project_key is authoritative when present; a document without one resolves through the alias registry (~/.trace/projects.json). project stays an unconstrained display label. All matching and filtering goes through project_identity (INV-4, INV-9); never compare labels directly.
• Label repair is alias-table-first — a mislabelled project is fixed by adding an alias, never by rewriting a capture record. auto and shared are reserved keys.
• Cross-project reads and writes fail closed when the server is pinned via TRACE_PROJECT; TRACE_REQUIRE_PIN additionally refuses both session-creation paths on an unpinned process.
• server.py imports __version__ from trace_mcp for startup log
• Per-project OpenAI key: the key lives in the project's own .env, which overrides the machine-global ~/.trace/.env (an exported env var still wins over both). TRACE_LOCAL_ONLY is the one exception — a restrict-only ratchet ORed across sources, so no project can switch a machine-wide kill switch off. Config is read once at server start; a .env edit needs a server restart.
• A missing or refused key is loud: reported in the trace_start_session banner and in the affected trace_learn_* responses, and a provider 401/403 raises ApiKeyRejectedError regardless of TRACE_STRICT_LLM. A backend that cannot be built degrades to keyword matching with a notice rather than failing registration — an unregistered extension is indistinguishable from an uninstalled one.
• Line length: 120 (ruff configured)