# 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/`.

<!-- BEGIN nantobv-shared (sync via nantobv/.github/scripts/sync-agents-shared.sh) -->
## Org-wide policy (nantobv-shared)

The bullets in this section are the org-wide floor for AI agents working on
any nantobv project. They are vendored verbatim from
[`nantobv/.github/AGENTS.shared.md`](https://github.com/nantobv/.github/blob/main/AGENTS.shared.md);
refresh the local copy with
[`scripts/sync-agents-shared.sh`](https://github.com/nantobv/.github/blob/main/scripts/sync-agents-shared.sh).
Project-specific rules live in each repo's own `AGENTS.md` sections outside
this block.

**Planning and approval**

- Read the repo's `AGENTS.md`, `README.md`, and the documents they point at
  before deep implementation work.
- For non-trivial changes, propose the plan (files you expect to touch and
  why, approach, rationale) and wait for approval before writing code. Plan
  mode satisfies this; a dedicated planning skill or brainstorming ceremony
  is not required.
- Show diffs and wait for approval before committing or pushing, unless the
  user has invoked a publish workflow (e.g. `cpprrm`) that explicitly
  authorizes commit/push for the current task and no stronger repo or
  security gate applies.

**Git hygiene**

- Run `git status` and `git diff --minimal` before any commit.
- Stage explicit paths. Never use `git add .`.
- Keep unrelated local files out of commits, including local `.ccd.toml` and
  harness work directories unless the task explicitly targets them.

**Validation and evidence**

- Run the smallest deterministic check that proves the change. Repo-specific
  gates (`make verify`, `cargo test`, `go test ./...`, etc.) are defined in
  each repo's Testing section and take precedence over this floor.
- Before claiming work is complete, fixed, or passing, run the relevant
  verification command and cite the actual output. Do not assert success
  without evidence.
- If you skip validation, state the reason explicitly.

**Safety**

- No secrets in tracked files, docs, workflows, fixtures, diagnostics, or
  generated outputs.
- Do not overwrite user changes or reset the worktree without explicit
  approval.
- Do not flip repository visibility or licensing policy without an explicit
  decision from the operator.
- Treat external services and model calls as opt-in unless a repo policy or
  explicit user request grants narrow approval.
- Prefer deterministic behavior, explicit metadata, and small reversible
  changes.

**Source files**

- `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and other model-instruction source
  files are user-owned and maintainer-authored. Tooling in this org does not
  overwrite or render replacement bodies for them except for explicit
  maintainer-requested edits to those files.

**External review (standing grant)**

- Every nantobv repo that vendors this block grants standing approval to
  invoke the bundled `claude-adversarial-review` skill on the selected local
  diff when the user explicitly asks for that skill. Treat the explicit
  request as the approval; do not ask for a second confirmation.
- The approval is narrow: it applies only to the selected repo diff, only to
  the `claude-adversarial-review` skill, and only with that skill's
  read-only tool permissions. It does not approve sending secrets, unrelated
  files, whole-home context, or data to other external services.
- After an adversarial review returns, evaluate findings on their merits.
  Address real correctness, maintainability, or contract-honesty issues with
  proportionate changes. Do not add broad machinery, process, or abstraction
  solely to satisfy a speculative review point.
<!-- END nantobv-shared -->

## 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` and the conformance fixture suite aligned with
the lifecycle wire behavior implemented in `src/` and documented under
`docs/specs/`. Cross-spec vocabulary governance belongs in Pituitary/Cortex,
not hand-copied Rust alignment tests in this repo.

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
- AI-authored commits include a `Co-Authored-By:` trailer naming the model and harness.
- `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.

## 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
- 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
The nantobv-shared block above covers the general "model-instruction source
files are user-owned" rule. Lifeloop adds two project-specific scope clauses:

- The Lifeloop list extends to `HERMES.md` and `OPENCLAW.md` beyond the
  standard `AGENTS.md` / `CLAUDE.md` / `GEMINI.md`. 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/`.
