logic: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

Atomic logic for decision-making — turning abstract ideas into executable functions. A modular, privacy-first toolkit built with FastAPI and SQLAlchemy. Five live modules: TCO, PERT, Monte Carlo, EVM, and Bayesian estimation calibration.

The logic repo is the open source foundation of pmo.run — a PMO service combining AI and human expertise. Strategy, audiences, and monetisation: docs/STRATEGY.md. Architecture and technical decisions: docs/DESIGN.md. Sprint actuals: docs/SPRINT_HISTORY.md. Content pipeline: skills/operational/content-cadence/SKILL.md.

Commands

# Install dependencies
uv pip install -e ".[dev]"

# Run API server (hot reload)
uv run uvicorn app.main:app --reload

# Run all tests
pytest

# Run a single test file
pytest tests/test_foo.py

# Run standalone module tests (each module ships its own pytest suite)
pytest examples/standalone/{module}/

# Run standalone example
python examples/standalone/tco/tco.py

# Run the site's parity tests (site/src/lib vs the Python core)
cd site && npm test

# Run the remote-MCP example's parity tests (examples/remote-mcp/src vs the core)
cd examples/remote-mcp && npm test

# Build the site. NOT optional when you have touched site/ — `npm test` covers the
# parity net and the crawlability gate's parsing, but the gate itself only runs
# after `astro build`, because what it checks does not exist until then. CI runs
# `npm test` BEFORE `npm run build`, so a green test run says nothing about it.
cd site && npm run build

# Regenerate BOTH parity fixture sets after changing app/pert or app/tco core.
# The pytest CI job re-runs these and fails on a non-empty diff, so a core change
# that leaves the fixtures behind now goes red instead of quietly netting the two
# TypeScript ports against a core that no longer exists.
uv run python site/scripts/generate_parity_fixtures.py
uv run python examples/remote-mcp/scripts/generate_fixtures.py

# Lint and format
ruff check .
ruff format --check .    # check only
ruff format .            # auto-fix

# Type check (app/ directory only)
pyright

# Security audit (SAST)
opengrep scan --config auto --config .opengrep/ --scan-unknown-extensions .

# Dependency vulnerability scan (SCA)
# Use --config even though the suppression list is currently EMPTY. This is the
# invocation the pre-commit hook and the CI job both use, so it is what
# reproduces them; drop it and you are testing something else.
# It matters the moment a suppression exists again: without the flag the
# auto-discovered root config does not apply to the nested lockfiles, so osv
# reports the project's own waivers as "unused ignores" and then prints them as
# live findings — indistinguishable from expired suppressions, and the tempting
# "fix" is to edit osv-scanner.toml and weaken a control that was working.
# That symptom is dormant, not gone: the Astro 6->7 upgrade discharged all three
# waivers on 2026-07-31, so there is nothing left for it to misreport today.
osv-scanner scan source --config=osv-scanner.toml --recursive .

# Run all pre-commit hooks
pre-commit run --all-files