depyler: Instructions file for Claude Code

CLAUDE.md - Depyler Compiler Implementation Protocol

CRITICAL: Contract-First Design

NEVER write code before writing a provable contract.

All code changes MUST have a corresponding contract (YAML in ../provable-contracts/contracts// or .pmat-work//contract.json) BEFORE implementation. This is enforced by pmat comply CB-1400.

• Use pmat comply check to verify contract coverage
• Minimum verification level: L1 (recommended L3+)
• See docs/agent-instructions/provable-contract-first-agents.md for the full workflow

Prime Directive

Generate correct Rust code that compiles on first attempt. Quality is built-in, not bolted-on.

Project Context

Depyler is a Python-to-Rust transpiler focusing on energy-efficient, safe code generation with progressive verification.

Python Packaging Protocol

MANDATORY: Use uv for ALL Python operations (uv add, uv run pytest, uv run <script.py>)

Code Search (pmat query)

NEVER use grep or rg for code discovery. Use pmat query instead -- it returns quality-annotated, ranked results with TDG scores and fault annotations.

# Find functions by intent
pmat query "python ast conversion" --limit 10

# Find high-quality code
pmat query "type inference" --min-grade A --exclude-tests

# Find with fault annotations (unwrap, panic, unsafe, etc.)
pmat query "transpilation pass" --faults

# Filter by complexity
pmat query "code generation" --max-complexity 10

# Cross-project search
pmat query "rust codegen" --include-project ../trueno

# Git history search (find code by commit intent via RRF fusion)
pmat query "fix type mapping" -G
pmat query "ast visitor" --git-history

# Enrichment flags (combine freely)
pmat query "ast visitor" --churn              # git volatility (commit count, churn score)
pmat query "pattern matcher" --duplicates           # code clone detection (MinHash+LSH)
pmat query "code emitter" --entropy           # pattern diversity (repetitive vs unique)
pmat query "transpilation" --churn --duplicates --entropy --faults -G  # full audit