rootsign: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

NEVER commit or push project/sprint artifacts

Sprint plans, agent guides, internal audits, memory snapshots, and similar working documents must stay local. They are gitignored as a backstop, but the rule is the rule regardless of whether .gitignore catches a given filename:

• AGENTS*.md, AGENTS_Phase*.md, RootSign_Phase*.{md,docx}, ProvidexAI_Phase*.{md,docx}
• MEMORY.md and anything under a memory/ directory
• rootsign_review.md and other founder-run audit artifacts

If a new artifact like this gets created during a session, treat it as local-only by default. Do not git add, do not stage, do not include in commits. If a git add -A / git add . would sweep one in, switch to per-file staging. If a similar file pattern appears that isn't already gitignored, add the pattern to .gitignore in the same change.

Why: these documents contain unreleased product strategy, audit findings, and pre-decision context. A Sprint 4 history-rewrite was needed once to scrub an accidentally-tracked sprint plan — the gitignore patterns added in commit 128cec5 exist as a mechanical backstop. The rule is to never need that backstop.

Where the code actually lives

The Python project is phase0/ (this directory). The parent turbo/ is just a workspace wrapper. All paths below are relative to phase0/.

Dev environment

CONTRIBUTING.md has the full setup. The non-obvious bits:

• Always run python -m pytest, never bare pytest. A brew-installed pytest shadows the venv binary and silently runs under the system interpreter — produces ModuleNotFoundError: sqlalchemy and similar.
• Even unit tests need a running database. tests/conftest.py has a session-scoped _bootstrap_test_db fixture that runs alembic before any test collection. Start the DB first: rootsign-admin start-db (or docker-compose up -d db in-repo).
• Schema bootstrap: rootsign-admin init applies migrations. Idempotent. --reset drops and recreates the public schema (no confirmation prompt — be careful).
• Single test: python -m pytest tests/integration/test_show_hn_quickstart.py::TestShowHNQuickstart::test_readme_quickstart_end_to_end -v
• Test markers: integration and benchmark are declared in pyproject.toml. Performance suite at tests/performance/ is opt-in via -m benchmark.
• Coverage gate: fail_under = 85 in pyproject.toml. CI enforces it. New code expected at ≥90% per CONTRIBUTING.
• Lint: ruff check . and ruff format . before pushing.