aristo: Instructions file for Claude Code

CLAUDE.md — Aristo working agreement

This file is law. Every Claude Code session in this repo MUST read this file before touching code, and MUST obey every rule below. These rules are not aspirational — they are how we work. Violating any of them is grounds for the user to revert your change.

If you find yourself rationalizing an exception ("just this once," "the rule doesn't really apply here"), STOP. The rule applies. If the rule is genuinely wrong, surface that to the user and propose a CLAUDE.md edit — do not silently bypass it.

---

§1. Commit size — small or medium ONLY

• Large commits are FORBIDDEN. No exceptions.
• Heuristic: if the diff exceeds ~200 changed lines OR touches more than ~5 files for unrelated reasons, SPLIT IT.
• One logical change per commit. If the message needs the word "and," it is two commits.
• The only allowed "wide" commit is a mechanical, atomic refactor (e.g. a project-wide rename) that is trivially reviewable as a single operation. Surface these to the user before making them.

§2. Commit messages — semantic / conventional

Required prefix from this exact set:

Prefix	Use for
feat:	new user-visible functionality
fix:	bug fix
refactor:	code change that neither fixes a bug nor adds a feature
perf:	performance improvement, no behavior change
docs:	documentation only (including this file, README, CHANGELOG-only edits — but see §3)
test:	tests only
build:	build system, dependencies, Cargo.toml, workspace config
chore:	housekeeping that doesn't fit above
ci:	CI / GitHub Actions config

Optional scope in parens: feat(macros): ..., fix(cli): ..., build(workspace): ....

Banned messages: wip, stuff, updates, misc, fixes, progress, more changes. Say what changed.

§3. CHANGELOG.md — one line per commit, in the same commit

• Every commit MUST add at least one bullet to the ## [Unreleased] section of CHANGELOG.md, describing what changed in customer-facing language.
• The CHANGELOG bullet ships in the same commit as the code change. Never a separate "update changelog" commit.
• Format: - <area>: <what changed and why a user cares>. Examples:
  • - macros: \#[aristo::intent]` now accepts multi-line text without escaping.`
  • - cli: \aristo verify --audit` exits non-zero on stale/refuted proofs for CI gating.`
• At release: promote ## [Unreleased] to ## [vX.Y.Z] — YYYY-MM-DD. The [Unreleased] block must read coherently as a release-note draft when scanned end-to-end.