# AGENTS.md
> Canonical AI policy for this repo.
## Project
Lifeloop is the provider-neutral lifecycle abstraction and normalizer for AI
harnesses: lifecycle events, capability manifests, callback envelopes, payload
delivery metadata, and receipts without importing CCD.
## Boundary
Lifeloop owns:
- harness identity, aliases, adapter manifests, lifecycle event vocabulary,
hook timing normalization, and integration modes;
- capability negotiation, lifecycle receipts, payload placement/delivery
metadata, lifecycle telemetry, failure classes, retry posture, and extension
dispatch as a lifecycle mechanism.
Lifeloop does not own:
- CCD continuity semantics; memory, recall, promotion, compaction, or
governance; recursive inference policy; prompt semantics above placement
metadata; model selection; tool or skill abstraction; or a universal IDE.
For the full boundary decision on harness concepts, see
[`docs/harness-concept-boundary.md`](docs/harness-concept-boundary.md). The
single rule is: *Lifeloop normalizes lifecycle reach. It does not normalize
meaning.*
For deep work, read `README.md`, `docs/product-thesis.md`,
`docs/harness-concept-boundary.md`, `docs/release-gates.md`, and relevant
`docs/decisions/`.
## Engineering Rules
- Keep the library contract first; the CLI is an adapter/inspection surface.
- Prefer deterministic, machine-readable, fail-closed behavior.
- Keep client semantics out of core types. CCD, RLM, Reforge, Fixity, and
other clients attach through public contracts.
- Do not add CCD, RLM, Reforge, or Fixity dependencies to core Lifeloop.
- Add dependencies conservatively; protocol/adapter boundaries stay auditable.
- Compatibility shims are acceptable only as explicit tombstones with removal
criteria, not as hidden old implementations.
## Contract Changes
Public contract changes require tests and docs in the same change: events,
capabilities, manifests, callback/dispatch/payload envelopes, placement
metadata, receipts, failure classes, and retry posture.
Keep `tests/wire_contract.rs` (current JSON shape) aligned with
`tests/spec_alignment.rs` (target vocabulary in
`docs/specs/lifecycle-contract/body.md`).
For wire-affecting changes, update both tests in the same commit. If code and
spec disagree, the spec is the goal; file a tombstone and move toward it.
Use `docs/playbooks/wire-contract-review.md` for contract review and
`docs/playbooks/schema-bump.md` when a schema bump is required.
## Workflow
- Inspect repo state before committing.
- Stage explicit paths only. Never use `git add .`.
- AI-authored commits include a `Co-Authored-By:` trailer naming the model and harness.
- Workflow-specific approvals apply: `cpprrm` authorizes commit, push, PR,
review follow-up, and merge according to that skill. Do not add an extra
diff-approval gate unless repo-local policy explicitly requires it.
- Invoking `claude-adversarial-review` authorizes disclosing the selected
review scope to Claude through that skill's runner; do not ask again.
## Automation
Dev automations live in harness-neutral surfaces so every harness and bare CI
run the same checks.
- `scripts/` — reusable shell logic.
- `Makefile` — named workflows: `make verify`, `make wire-check`,
`make lockfile-check`, `make commit`, `make bump-schema`.
- `lefthook.yml`, `docs/playbooks/`, and `.cargo/config.toml` — hooks,
checklists, and cargo aliases.
Add no logic to harness configs (`.claude/`, `.codex/`, etc.); logic must be
reachable from `make`, `git`, and CI without a harness.
## Testing
- Run the smallest check that proves the change.
- Prefer `make verify` for repo-wide validation.
- For public contracts, add serialization tests that pin wire names.
- Foreign plugin manifest fixtures live under
`tests/fixtures/foreign_manifests/`; they must be synthetic, host-neutral,
client-neutral, and marked with `provenance.kind = "synthetic"`.
## Release
Release cut: move changelog entries from `Unreleased`; confirm `Cargo.toml`
and `Cargo.lock`; run `scripts/check-wire-contract.sh`, `make verify`, and
`cargo publish --dry-run`; commit with explicit paths and AI co-author trailer;
push `main`; create/push `vX.Y.Z`; create the GitHub release; run
`cargo publish` only after dry-run passes.
## Pituitary
Pituitary is an advisory lexical governance gate during rollout. Its config is
`.pituitary/pituitary.toml`; local equivalent: `pituitary index --rebuild &&
pituitary check-terminology`.
Treat findings as terminology-drift signals to review, not as a hard release
blocker unless the project deliberately flips the CI jobs to fail-closed.
## Source Files
Lifeloop does not write to model instruction source files (`AGENTS.md`,
`CLAUDE.md`, `GEMINI.md`, `HERMES.md`, `OPENCLAW.md`) or render replacement
bodies for managed sections inside them. See
[`docs/decisions/source-files-are-user-owned.md`](docs/decisions/source-files-are-user-owned.md).
Target host integration asset paths that Lifeloop may render or manage
(`.claude/settings.json`, `.codex/config.toml`, `.codex/hooks.json`) remain in
scope and live in `src/host_assets.rs` plus `src/host_assets/`.
## Safety
- No secrets in tracked files, docs, fixtures, receipts, or diagnostics.
- Do not overwrite user changes or reset the worktree without explicit
approval.