# CLAUDE.md

This file provides guidance to Claude Code when working with gzkit.

## Project Overview

A gzkit-governed project

## Canonical Contract

`AGENTS.md` is the authoritative governance contract.

If this file and `AGENTS.md` diverge, follow `AGENTS.md` and run `gz agent sync control-surfaces`.

## Tech Stack

Python 3.13+ with uv, ruff, ty

## Build Commands

```bash
uv sync                              # Hydrate environment
uv run -m gzkit --help            # CLI entry point
uv run gz lint                       # Lint
uv run gz format                     # Format
uv run gz typecheck                  # Type check
uv run gz test                       # Run tests
```

## Coding Conventions

Ruff defaults: 4-space indent, 100-char lines, double quotes

## Governance Rules

Loaded contextually from `.claude/rules/` (mirrored from `.github/instructions/`).

Run `gz agent sync control-surfaces` to regenerate.

## Skills

Discovered automatically from `.claude/skills/`. See `AGENTS.md` for the full catalog.

## Control Surfaces

This file is generated by `gz agent sync control-surfaces` from governance canon.

Project-specific additions come from `agents.local.md`.

---

<!-- BEGIN agents.local.md -->
# Local Agent Rules

- Order versioned identifiers semantically, never lexicographically. Example: `ADR-0.9.0` comes before `ADR-0.10.0`.
- Apply semantic-version ordering in ADR summaries, comparisons, and any operator-facing status narration.
- When adding imports in an Edit call, always include the code that uses them in the same edit. The post-edit ruff hook removes unused imports immediately — splitting import addition and usage across separate edits causes the import to be deleted before it's referenced.

<!-- END agents.local.md -->
