Adam Moussa
3c29ce3fdb
Resolves three execution-proven verifier findings from the scaffold review. Full suite: 548 passed, 1 skipped (stable across repeated runs); ruff clean. builders denylist (§3.3.2 #2): scan was +++-only and missed header-only sections. Now section-driven off `diff --git a/<src> b/<dest>`, catching the 4 proven bypasses — delete of a denied path, mode-change-only, `copy to` a denied path, out-of-scope delete (regression tests for each). §3.3.1 compare-and-set concurrency: BEGIN IMMEDIATE moved inside guarded retry; each CAS now runs on its own connection (shared sqlite3.Connection cannot hold two transactions, and is unsafe for concurrent use even for reads). connect() stashes the db path on a Connection subclass so the path is derived by a thread-safe attribute read, not a PRAGMA on the shared conn; busy_timeout set before the WAL pragma. Added shared-connection concurrent regression tests (distinct + same question) — previously raised "transaction within a transaction". operator CLI (run-team.py): added the design-named re-deliver and force-resume verbs (were missing); audit now records the attempt BEFORE the mutation and the outcome after, so a ledger mutation can never land without a trail; main() catches OSError instead of leaving an uncaught traceback on audit-write failure. |
||
|---|---|---|
| .. | ||
| agent_team | ||
| ci | ||
| tests | ||
| .gitignore | ||
| README.md | ||
| run-team.py | ||
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.