<!-- governance-sync: source=abi-governance contract=contracts/ai_contract_v1.md sha=ea96706335d864c768b1053c1632f5fb45c33518f5c1c2f4f644a2658462b1bd synced=2026-03-07T23:40:09.514728+00:00 -->

# AI Operating Contract v1

Universal rules for AI agents (builders, verifiers, critics) working in AbilityBI repositories.

## 1. Branch & Workflow Policy

- **Default-branch only.** Commit and push directly to the default branch (usually `main`).
- Do NOT create feature branches or pull requests unless the human explicitly instructs you to.
- **Always push** after every commit. Never leave commits local-only.

## 2. Versioning & Changelog

- Follow **Semantic Versioning** (SemVer 2.0): `MAJOR.MINOR.PATCH`.
- Every behavioural change must include a CHANGELOG entry (or update an existing one).
- Tag releases only when the human requests a release.

## 3. Privacy & Publishing

- All repositories are **private by default**. Never change repository visibility.
- Do NOT publish packages, create GitHub releases, or push to any registry unless explicitly instructed.
- Never include secrets, tokens, or credentials in code, commits, logs, or prompts.

## 4. Required Reporting

After completing work, report:
1. Commit SHA(s) created.
2. Commands run and their exit codes.
3. Artifact paths (files created or modified, with absolute paths).

## 5. Role Responsibilities

### Builder
- Implement what is asked -- nothing more, nothing less.
- Do not invent requirements. Flag ambiguity and propose options.
- Tests are mandatory for behaviour changes.

### Verifier / Critic
- Review with evidence, not opinion.
- **Evidence-for-severity rule:** Critical findings MUST include `file:line` plus test, log, or repro evidence. Otherwise downgrade to Important.
- Demand diffs, tests, or reproducible steps before approving.

## 6. Repository Metadata Standards (GitHub Topics)

- Topics are **mandatory and governed**. Every AbilityBI repo must carry baseline topics.
- **Baseline topics (all repos):** `abilitybi`, `ai-native`, `private-by-default`, `deterministic`, `governance`
- **Additional topics (abi-infra repos):** `abi`, `abi-infra`
- Repo-specific extra topics are allowed (e.g., `orchestrator`, `policy-engine`, `specpack`, `prompt-engineering`, `runtime`, `promotion`, `evals`, `plugins`, `repository-template`).
- Topic edits should be done via `abi-governance-sync topics apply` (not manually in the GitHub UI).

## 7. LLM Telemetry Mandate

**Status:** Mandatory | **Version:** 1.0.0 | **Scope:** All roles, all providers, all repos

Every LLM invocation across the ABI fleet MUST emit a standardized telemetry record, regardless of the agent's role. No LLM call may execute without producing an auditable trace.

**Covered roles:** builder, verifier, auditor, planner, evaluator, reviewer, classifier, router, extractor, summarizer

**Covered providers:** anthropic, openai, google, ollama, replay, mock

**Required fields per record:** invocation_id, run_id, timestamp, provider, model, role, task_id, task_category, repo, tokens_in, tokens_out, total_tokens, cost_usd, duration_ms, status, error_class

**Output:** `llm_telemetry.ndjson` in the run output directory (one JSON line per invocation)

**Enforcement:**
- All repos calling LLMs must use `TelemetryEmitter` from `abi-core`
- Fleet audit checks that all LLM-calling repos have telemetry wired
- Evidence packs must include a telemetry summary before promotion
- Violations detected by the absence of `llm_telemetry.ndjson` in run artifacts

**Reference implementation:** `abi-core/src/abi_control_core/sdk/telemetry_emitter.py`

## 8. General Rules

- Respect the governance profile of the target repository.
- Never exceed the configured human-involvement floor.
- Use semantic design tokens for UI code; never hardcode colours or spacing.
- Run the project test suite (`script/test` or equivalent) before declaring work complete.

---

*Contract version: 1.2.0 | Effective: 2026-03-07*
