selvedge: Instructions file for Claude Code

CLAUDE.md — Selvedge agent instructions

This file is auto-loaded by Claude Code and Cowork on every session. It's the rules and conventions agents follow when working on Selvedge.

For everything else:

• README.md — user-facing docs (install, quickstart, comparison, "what's new", CLI reference)
• docs/architecture.md — internal architecture, data model, MCP tool reference, CLI reference, full phase plan, non-goals
• CHANGELOG.md — source of truth for what's actually shipped

Sources of truth

• What's shipped → CHANGELOG.md. The phase-plan checkboxes in docs/architecture.md can drift; trust the changelog when they disagree.
• Current MCP tool count and shape → selvedge/server.py. Don't infer from manifest.json — the bundle can lag the live server.
• Version string → pyproject.toml AND selvedge/__init__.py AND manifest.json must all match.

Code conventions

• No external dependencies beyond the declared ones. Keep the install footprint small.
• No LLM calls inside Selvedge core. Templated, deterministic output only. When a feature design is tempted toward an LLM hop, the PR description must explain how the templated output covers the user need; reviewers reject "we'll add an LLM later if needed." See docs/architecture.md cross-cutting risk register for the full rationale.
• SQLite first, always. Don't reach for Postgres until Phase 3. SQLite with WAL handles concurrent reads fine.
• ChangeEvent is a dataclass, not Pydantic. Keep the core dependency-free. MCP serialization uses to_dict().
• New TypedDict result types must justify themselves. Before introducing a new MCP tool result shape, check whether an existing one (LogChangeResult, BlameResult, the auto-generated list-shapes) extends to fit. Prefer extending an existing type to introducing a new one. Every field always populated, never null — same convention as LogChangeResult / BlameResult (empty string / empty list / empty dict for "absent").
• Every public function has a docstring. The MCP tool docstrings in server.py are user-facing — they appear in agent tool listings and propagate into manifest.json.
• Tests use tmp_path fixtures and SELVEDGE_DB env var. Never write to the real DB in tests.
• Rich for all terminal output. No bare print() in cli.py.
• --json flag on every read command. Machine-readable output is a first-class concern.
• Type hints everywhere. Python 3.10+ syntax (X | Y, list[dict], etc.).
• Destructive actions require both interactive consent AND environment-level opt-in. Any command that can delete events from the store (e.g. selvedge prune --include-events, landing in v0.3.10 alongside .selvedge/config.toml) must require BOTH a confirmation prompt AND SELVEDGE_DESTRUCTIVE=1 in the environment. Defends against the cron / non-interactive --yes footgun.