# Inference Guardian Pilot Findings

This pilot applied the Agent Spine contract to `inference-guardian`, an existing Rust and Python repository for LLM inference SRE workflows.

The pilot used manual adoption rather than `scripts/bootstrap-template.sh` because the target repository already had product documentation, CI, tests, and a detailed `AGENTS.md`.

## Adopted Surface

The target repository received:

- `.codex/config.toml`
- `.codex/hooks.json`
- `.codex/hooks/`
- `.codex/agents/`
- `.agents/skills/`
- `docs/COGNITIVE_OPERATING_SYSTEM.md`
- `docs/QUALITY_MODEL.md`
- `docs/ADOPTION_CHECKLIST.md`
- `docs/AGENT_SPINE_PILOT.md`
- `scripts/verify-agent-contract.sh`
- a GitHub Actions `agent-contract` job

The target `AGENTS.md` was extended instead of replaced.

## Findings That Affect The Template

### 1. Existing repositories need merge-first adoption

The greenfield bootstrap flow is still useful, but real repositories may already have a stronger project-specific `AGENTS.md` than any generic profile.

Template implication:

- keep documenting bootstrap as greenfield-first
- keep the migration playbook focused on porting durable surfaces manually
- avoid recommending README or AGENTS overwrite for mature repositories

### 2. Downstream repositories need project-local contract verification

The target repository should not depend on `scripts/verify-template.sh`, because that script validates template-maintenance concerns.

Template implication:

- downstream adoption should create a small project-local verifier for `.codex/`, `.agents/skills/`, and required docs
- project-native Rust, Python, Node, or other checks remain the real runtime quality gates

### 3. Prompt-context hooks must be project-specific

The copied `user_prompt_submit_context.py` needed edits because the template version described adapter boundaries that were not relevant to the target.

Template implication:

- migration docs should explicitly call out prompt-context hook customization
- copied hooks should be reviewed as policy code, not treated as inert scaffolding

### 4. Existing machine-local artifacts need a separate cleanup decision

The target repository already had tracked supervisor state, coverage reports, and local data files. The pilot added ignore rules for future artifacts but did not remove tracked files.

Template implication:

- adoption checklist should separate "prevent future local artifacts" from "remove already tracked artifacts"
- cleanup of tracked generated files should be its own reviewable change

### 5. Dirty or detached target state changes the commit strategy

The target repository started in detached HEAD with an existing uncommitted `src/main.rs` change. The pilot created a local branch and committed only adoption files.

Template implication:

- migration playbooks should require a git-state check before adoption
- adoption agents must avoid staging unrelated user changes

## Verification Run

In the target repository:

```bash
./scripts/verify-agent-contract.sh
cargo fmt --check
git diff --check
```

All passed.

The target repository had no configured remote, so the pilot commit remained local:

```text
54aa972 docs: add agent spine pilot contract
branch: agent-spine-pilot
```