CORE: Instructions file for Claude Code

CLAUDE.md — CORE

v3 done; CORE 3.1 in progress (since 2026-10-29)

The freeze ended 2026-10-29: every v3 gate issue is closed (milestone CORE 3.0: 48 closed, 0 open). Work is filed in milestone CORE 3.1. No new features before the v3 release. New infrastructure (timers, crons, credentials, services) needs the governor's yes first. The PR check freeze-scope still refuses a PR whose description names no v3 or CORE 3.1 issue.

CORE is a Python runtime that audits a codebase against rules in .intent/, records violations in PostgreSQL, proposes fixes, and logs the chain from finding to commit.

Layout

src/api/     FastAPI routes; DB access only via api/dependencies.py
src/body/    atomic actions, services, workers (execution)
src/mind/    rule engines; read .intent/, no I/O or execution
src/will/    agents and autonomous orchestration
src/shared/  common substrate; must not import mind/body/will
src/cli/     Typer commands; Rich rendering only here
.intent/     rules and config the runtime reads (YAML/JSON)
.specs/      design history (ADRs, papers); reference, not instructions

Facts (update when they change)

• PyPI: core-runtime 3.1.0 (2026-11-03; consumer: proof run 10).
• Latest proof run: 9 (#1053, 2026-10-30, on 3.0.0 from PyPI); gate met, no issues filed. Next run: 10.
• Production-ready (docs/release.md): stays Beta until an independent person, not an AI agent, installs CORE from the README and uses it.
• Credentials: a closed list (governor 2026-10-23). No new token, no permission change, never asked of the governor. A job uses one of these and checks it at start, failing loudly if it does not work.
  • core-claude-bot gh login (core-claude; scopes repo, workflow, read:org): pushes branches, opens PRs into main and turns on their auto-merge, creates promote/<sha> branches, opens or updates the promotion PR, and closes a superseded one and deletes its branch. After review finding F2: also opens the PR for CORE's generated tests. The 06:00 job hands this login's token to promote propose as CORE_GITHUB_TOKEN. Every 15 minutes infra/scripts/core_alert_check.py opens and closes the [alert] issues that mention the governor (review F4); no new credential.
  • CORE's own token (CORE daemon): read as CORE_GITHUB_TOKEN from the environment, else the unit credential github-token (delivery_branch.py). Pushes CORE's branches; cannot open PRs (#1252). Same variable name as above, a different credential.
  • /etc/core/pipeline-github-token (core-runner): an issues-only token on the governor's own account (#1198); it opens the issue for a failed promotion, and every other pipeline read is unauthenticated. GitHub sends no email for one's own issue, so an alert meant to reach the governor is opened as core-claude-bot (#1201 was opened as the governor).
  • /etc/core/pipeline-deploy-key (core-runner): the write deploy key; moves live. Ruleset live-writers lets any write deploy key do so; this is the only one (governor counted, 2026-10-23), and it stays the only one.
  • Deliberately not on the list: the governor's own GitHub login, the built-in GITHUB_TOKEN of Actions jobs, and PyPI (Trusted Publishing, no stored token).