# agent-team — R720 Plane-2 FOUNDATION

Pre-deployment scaffolding for the R720 agent-team SDLC pipeline (design:
`../docs/r720-agent-team-design.md`). This commit ships the **Plane-2
FOUNDATION** layer only — the durable, transport-agnostic **contracts** the leaf
builders import verbatim. Nothing here is provisioned, scheduled, or wired to
live infrastructure.

> Status: FOUNDATION modules only. No coordinator, no transports' concrete
> adapters, no CI workflow, no provisioning. Those are later phases (§7).

## Layout

```
agent-team/
  agent_team/                 # importable package (snake_case)
    state_store.py            # §6.7 atomic write + integrity-checked read
    billing.py                # §3.1 claude_invoke billing-mode seam
    task_model.py             # §3.3 TaskRecord / Phase / PipelineState
    db/
      schema.py               # §3.3.1/§6.7 SQLite DDL + connect/init/migrate
      schema.sql              # raw DDL, mirrors schema.py verbatim
    transport/
      base.py                 # §3.3.1 Transport ABC + QuestionSet/NormalizedAnswer
  tests/                      # pytest unit tests, one module per source module
```

The top directory is kebab-case (`agent-team/`); the importable package is
snake_case (`agent_team/`), per the engineering handbook.

## Modules (contracts)

| Module | Design ref | What it provides |
|---|---|---|
| `state_store` | §6.7 | `atomic_write(path, data)` (write-temp → fsync → rename), `read_checked(path, *, schema_version)` (schema-version + content-hash integrity check, raises `IntegrityError`), `compute_content_hash(data)`. Pure stdlib; no other `agent_team` deps. |
| `db.schema` | §3.3.1, §6.7 | `SCHEMA_VERSION`, `PENDING_QUESTIONS_DDL`, `BUDGET_LEDGER_DDL`, `connect()` (WAL + foreign_keys + busy_timeout), `init_db()`, `migrate()`, and the `BEGIN IMMEDIATE` compare-and-set helpers (`answer_question`/`expire_question`/`supersede_question`). SQL DDL lives **only** here. |
| `billing` | §3.1 | `BillingMode{SUBSCRIPTION,API,BEDROCK}`, `claude_invoke(prompt, *, mode=None, **kw) -> ClaudeResult`, `resolve_mode(config)`. Single seam; subscription mode pops any stray `ANTHROPIC_API_KEY` so OAuth can't be overridden. |
| `transport.base` | §3.3.1 | `Transport` ABC (`post_question` → `channel_ref`; `parse_answer` → `(question_id, answer, via)`), `QuestionSet`, `NormalizedAnswer`. Transport-independent; Slack/GitHub/Claude-Code adapters subclass in the leaves. |
| `task_model` | §3.3 | `TaskRecord`, `TaskStatus`, `Phase{INTAKE…DONE}`, `new_thread_id()`, `PipelineState` TypedDict (LangGraph state schema), JSON serialization helpers. Pure model, no I/O. |

### Durable human-in-the-loop (§3.3.1)

The `pending_questions` ledger is the single durable source of truth for the
question lifecycle. Every race (duplicate answers, transport redelivery,
answer-vs-timeout) resolves via one atomic compare-and-set against the `status`
column, run inside a `BEGIN IMMEDIATE` transaction so concurrent responders are
serialized — first-answer-wins (`rowcount == 1`), late/duplicate ignored
(`rowcount == 0`). The LangGraph `SqliteSaver` checkpointer creates its own
tables against the **same** DB file.

## Running the tests

```
cd agent-team
python3 -m pytest tests/ -q
```

`tests/conftest.py` puts the package on `sys.path`, so no install is required.

## Not in this commit (later phases)

Coordinator/brain, concrete Slack/GitHub/Claude-Code transport adapters, the
CI apply/verify workflow (§3.3.2), step-ca / Roles Anywhere, scheduling, and
the operator CLI (`run-team.py`). See `../docs/r720-agent-team-design.md` §7
for the phased rollout. Secrets are never committed.