AGENTS.md

Mandatory instructions for any coding agent (Codex, Claude Code, or otherwise) working in this repository. This file is procedural — it governs how agents work, not what the system does.

Governing sources, in authority order

1. docs/product-doctrine-and-strategic-direction.md — product strategy, target wedge, and the semantic model (evidence, provenance, identity, qualification) the whole system is built on.
2. ROADMAP.md — authoritative for release sequencing and what's shipped vs. planned.
3. The applicable release's governing specification: docs/specifications/<release>/specification.md (the parent spec for that release) and its iN-<slug>.md increment specs (the normative contract for that increment). See docs/specifications/README.md.

docs/specifications/poc.md and its siblings there (h1-h3-hardening.md, h4-opentelemetry.md, h5-open-source-readiness.md, 11h-runtime-correctness-robustness.md, 12g-public-repository-activation.md) are historical design input this project was originally built from — not the current governing specification. The current release's own docs/specifications/<release>/ directory is.

Specifications are authoritative over implementation plans, skills, and agent instructions — including this file. If anything below conflicts with a specification, the specification wins.

Mandatory agent behavior

• Before planning substantial work, read the three governing layers above for the area you're touching — not just the increment spec in isolation.
• Identify the exact governing specification revision (e.g. "Draft 0.3, amended during PR3b") before writing a plan against it.
• Fetch and merge origin/main before starting implementation, not only before pushing: governing specifications are revised on main while an increment is in progress. Re-check the revision you planned against before opening the PR. (In v0.5 I1 a formula was implemented after the spec had already changed it.)
• Write a commit or merge SHA into a record, PR body or comment only from git output captured in the same step (git rev-parse, gh pr view --json mergeCommit), never from memory or expectation. Qualification evidence depends on exact SHAs.
• Inspect the current repository — existing code, tests, prior completion records — before proposing implementation details. Reuse existing functions/utilities/patterns; don't propose new ones where suitable ones already exist.
• For substantial increment work, produce a reviewed implementation plan before changing production code. See the specification-driven-implementation skill for the full procedure and templates.
• Persist the approved plan, verbatim, in the GitHub issue or the initial PR description. Retain the original plan — do not replace it with a retrospective summary once implementation is done.
• Add an implementation reconciliation (a diff against the retained plan, not a fresh retrospective) before considering the work complete.
• If implementation exposes a semantic ambiguity the specification doesn't resolve, stop and request a specification decision. Do not guess and do not silently pick a default. Tests you write are implementation evidence, not independent qualification — a passing test suite demonstrates the plan was implemented; it never resolves what the specification should mean.
• Never silently introduce new requirements, precedence rules, identity rules, conflict-resolution behavior, or unsupported-case behavior that the specification doesn't already state.
• Preserve AIP's evidence, provenance, identity, qualification, and unsupported-case guarantees in every change — these are load-bearing product invariants, not implementation details.
• Code in the packages [tool.pyright] covers (pyproject.toml) must pass uv run pyright. Never silence it with a bare # type: ignore/# pyright: ignore, by loosening [tool.pyright], or by shrinking its include. A suppression must be rule-scoped (# pyright: ignore[<rule>]) with a comment naming the tool or stub limitation it works around. A type error that exposes a reachable None/union path is a correctness finding: fix it, don't suppress it.
• Code must keep the import boundaries in [tool.importlinter] (pyproject.toml), checked by uv run lint-imports. A broken contract means the change crossed a layer: restructure the code, don't loosen or delete the contract. Adding a contract for a boundary the code already keeps is welcome.
• Before opening a pull request or pushing a commit meant to pass CI, run the full local gate in this order: uv run ruff format ., uv run ruff check ., uv run pyright, uv run lint-imports, then uv run pytest tests/unit and uv run pytest tests/integration -m "not qualification" (the qualification tier is the slow frozen-reference/oracle/real-container set marked in tests/integration/conftest.py; CI runs it on main, tags, nightly and on PRs touching its inputs, see docs/development.md). Run both suites, not the one that seems relevant: contract changes that stay unit-green have broken integration tests here before. Also run -m qualification when the change touches its inputs or the PR will carry the run-qualification label. This applies to small changes too. There are two exceptions:
  • The documentation-only exemption in the specification-driven-implementation skill. It never covers specifications, completion records, release notes, schemas or fixtures.
  • Spec-only PRs. The diff changes only Markdown specifications under docs/specifications/ and, optionally, the process documents AGENTS.md and CLAUDE.md. No test or script reads the changed files (check with a grep of tests/ and the scripts). For these PRs, run the gate without tests/integration, and state the skip and its reason in the PR body. The exception does not apply when the diff also adds or changes vectors, fixtures, schemas, evidence packages, completion records or release docs.
• Never merge a pull request, force-push, or push directly to main; the owner merges. This rule is procedural. For Claude Code, .claude/settings.json adds best-effort deny rules for the common command forms (they override any local allow rule), but they match command text only and are not a security boundary.

Orientation and planning posture

Orientation (do this first, instead of sweeping the specs directory):

• git fetch origin, then confirm the increment spec you were asked to plan actually exists on the checked-out branch. If it only exists on origin/main, work in a worktree created from origin/main; do not hunt for it through issues or the GitHub contents API. The shared checkout is often on an unrelated branch, so never switch branches there.
• ROADMAP.md names the release in progress. The previous increment's handoff (docs/specifications/<release>/iN-iM-handoff.md) and completion record are the entry points to the next increment; read those and the target increment spec, then only the code the plan touches. Use rg/targeted sed -n ranges rather than cat-ing whole specifications.
• Do not re-read the same large file (this procedure included) within one session.

Planning posture:

• A plan is proportional to the increment's risk. Fill the plan template; do not add pre-checks, guard tests, decision records or ADRs that the specification does not require. Qualification is multi-stage by design: a mistake caught at a later gate with a clean audit trail is the model working, so do not front-load extra checking to avoid ever surfacing one.
• Solve the current problem. Do not propose decisions, triggers, tripwire tests, registries or documents for hypothetical future cases; at most one line, and only if relevant. A deferred option is an option, not a decision. ADRs are for real architecture decisions, never small refactors.
• "Propose" means a quick menu of distinct approaches with rough cost and gain, based on cheap data (a code read, CI logs). Do not run long local trials before answering; run experiments after the owner picks an option.
• When a spec or workflow document prescribes a process (for example task -> PR -> merge -> next task), follow it as written. Implement one task, stop, and open its PR; plan approval does not license batching tasks.
• Report plans to the owner at the length of the decisions they contain. If the owner says the plan is too heavy, remove scope; do not just reword it.

Implementation habits

• Before opening a PR, perform an independent self-review of the complete proposed diff against .claude/agents/aip-reviewer.md sections A-H (evidence membership, schema parity, sanitized diagnostics, determinism, environment parity, tests as proof, pinned qualification identity). Claude Code must invoke the aip-reviewer agent sequentially; other agents must apply the same checklist independently from the implementation pass. Resolve every BLOCKER/MAJOR before opening the PR. If review exposes a semantic ambiguity, stop and return it to the owner. After material fixes, run the applicable validation again and repeat the self-review once; do not churn on MINOR/NIT findings. A change that qualifies for the strict documentation-only pre-PR validation exemption in the specification-driven implementation skill also skips this independent reviewer pass; specifications, completion records, release notes, schemas, fixtures and other release-candidate content do not qualify for that exemption.
• Assert the branch inside the commit command (test "$(git branch --show-current)" = <branch> && git commit ...). Do not commit unless the owner asks; end a change by reporting what changed and that it is not committed.
• After pushing review fixes, update the PR body and post a summary comment (fixes, regressions, local test results) immediately; do not wait for CI.
• A bare "merged" from the owner reports a merge, nothing more. Verify it, propose the next step, and stop until told to proceed.
• Specifications are sometimes authored by the owner and appear as untracked files mid-session. Check for an existing spec at the expected path before drafting one. If one appears while you are drafting, stop and treat theirs as authoritative.
• Verify cited evidence paths with git ls-files --cached, not the working tree: .gitignore has *.log, so git add skips logs silently. Hand-authored AIP inputs (declarations, bindings, manifests) must be proven through the real discoverer (CANDIDATE_FILENAMES and directory depth), not only parsed.
• Known flake: demo-e2e's test_missing_env_exits_nonzero can spuriously hit its 15s timeout in CI. Compare other runs on the same SHA and re-run the failed jobs before touching the test.

Continuous refactoring

Treat refactoring as part of normal Python implementation, not as a separate project phase. Leave touched code simpler where there is a concrete maintainability benefit: remove unnecessary complexity or duplication, clarify responsibilities, and prefer improving existing abstractions over speculative new ones. Keep improvements within the current task's scope; report larger structural concerns separately rather than expanding the change.

Preserve observable behavior, public contracts, deterministic results, and AIP's evidence, provenance, identity, qualification, and snapshot/observation-context semantics. Verify relevant behavior after any refactoring with the repository's existing checks.

Before opening a PR that changes Python code, briefly review the diff for material refactoring opportunities. Fix local, low-risk problems within scope; do not turn cosmetic preferences into blocking work. Skip this check for documentation-only changes. For substantial specification-driven work, follow the canonical skill's pre-PR refactoring check as part of the established workflow.

Minimum implementation-plan content

• Governing specification path and exact revision.
• Bounded scope and explicit non-goals.
• Affected components and expected change surface.
• Specification-requirement → implementation-task mapping.
• Acceptance-criterion → test/evidence mapping.
• Validation commands.
• Unresolved questions, assumptions, and stop conditions.

Minimum reconciliation content

• Work completed as planned.
• Material deviations and their justification.
• Specification questions discovered during implementation.
• Deferred work.
• Test and qualification evidence.
• Remaining limitations.

Small-change exemption

Maintenance changes that don't alter public contracts, identity rules, evidence/provenance semantics, qualification behavior, reconciliation logic, or release semantics don't need the full plan-then-implement-then-reconcile workflow. When in doubt about whether a change is "small," default to treating it as substantial.

Where to go next

For the full procedure, phase-by-phase guidance, and copy-paste plan/reconciliation templates, see the specification-driven-implementation skill. Don't duplicate that procedure here — this file states what's mandatory, the skill states how to execute it.

For recurring PR maintenance, use the canonical address-review and post-merge-sync skills rather than reconstructing those procedures from memory.

For build/lint/test commands and local dev setup, see docs/development.md. For general contribution mechanics (branching, PRs, commit style), see CONTRIBUTING.md — that file is unaffected by this workflow and covers a different concern.