Repository navigation
v1.7.0 — Honest Teaching Colony (response to external review)
What's new in v1.7.0
v1.7.0 is a correctness release for the Teaching Colony example, responding to an external review that found six concrete bugs in v1.6.x. The review described v1.6.x as "a 4,300-line artefact whose headline demonstration doesn't hold up under a single run-and-inspect". Every finding is now addressed. The review is preserved verbatim at examples/teaching_colony/docs/review-2026-04-14.md as the before-state that v1.7.0 corrects.
What was broken in v1.6.x
- The mock dispatch path was dead code — driver and adapter disagreed on argument shape, so both Teacher dispatches fell through to
{ok: True}. The README's headline claim was false. - The capability landed in the wrong place in the Mirror — deep-merge wrote a new top-level YAML key instead of appending to
capabilities.capabilities[]. - The Comprehension Contract was not enforced —
update_mirrordid none of the checkssubstrate-contract.mdpromised. - The event stream was duplicated — driver and adapter emitted the same logical actions with different names.
- Mirror writes polluted git-tracked files — every run left
colony/mirrors/teacher-agent.yamlmodified. - The classifier accepted caller-supplied
blast_radiusoverrides — a confused caller could downgrade a Colony-wide action to Local.
What v1.7.0 changes (three batches)
Batch 1 — correctness (the headline claim must become true)
- Fix 6: classifier gate — action classes in the table are authoritative; caller override only applies to unknown classes.
- Fix 2: semantic change DSL for
update_mirror—add_capability,remove_capability,patchas explicit instructions. - Fix 1: wire the mock dispatch path — adapter normalises agent id and keys on the actual input shape the driver sends. Canned answers now contain the words "worker" (beekeeping) and "Mirror" (Agent Colony pattern) — exactly what the new walkthrough test asserts against.
Batch 2 — the Comprehension Contract actually bites
- Fix 3:
update_mirrorperforms six checks before writing — co-signer presence, classifier invocation, blast-radius-ceiling, forbidden-list, co-signer policy freshness, hash/merge/write. Each check raises a specificContractViolationsubclass. - New test module:
tests/test_contract_enforcement.py— five tests that provoke each check in turn. The first time the §7 Comprehension Contract has ever done real work in running code.
Batch 3 — design cleanup
- Fix 4: single event ownership — adapters own adapter-internal events (
kb.written,mirror.updated,cosign.granted,dispatch.complete); driver stops emitting duplicates. Both substrates now emit identical event sequences in mock mode. - Fix 5: Mirror writes land in
state/mirrors/overlay.colony/mirrors/is now read-only at rest. Running the example no longer pollutes git-tracked files. - Corpus README explaining why the corpus is a snapshot (not a symlink) and how to refresh it.
- Substrate contract text fixes — the enforcement paragraph is rewritten to name the six checks; the change DSL gets its own section; the aspirational "every substrate we tried" claim about
read_eventis replaced with an honest statement.
The v1.7.0 testing innovation
tests/test_walkthrough.py runs the lifecycle driver end-to-end and asserts seven observable properties of state/events.jsonl and the Teacher Mirror:
- Teacher's beekeeping answer contains "worker" (proves the canned branch fired)
- Teacher's Agent Colony answer contains "Mirror" (proves the new capability is used)
- Teacher's Mirror contains both capabilities under
capabilities.capabilities[] - No floating
capability_addkey at the root of the Mirror - Classification event with
review_regime: Peer Review cosign.grantedevent withgranted: Truemirror.updatedevent with differing pre/post state hashes
This test is the mechanism that prevents tests-vs-demo drift in future releases. If a future change breaks the walkthrough, this test fails — even if every other adapter test passes.
Portability parity: v1.6.x skips are now v1.7.0 passes
The two tests that were marked skip in v1.6.x — test_event_log_types_match and test_teacher_mirror_final_state_matches — now pass. Both substrates produce byte-identical event sequences and Mirror final states in mock mode. The 42-vs-22 event-count gap from v1.6.1's honest note is gone.
Test results
36 passed, 2 xfailed
The 2 xfails are live-mode dispatch_agent and update_mirror for the Managed Agents adapter — these require the research-preview allowlist and real API calls. Mock-mode portability parity is fully achieved.
Known gaps after v1.7.0
- Live-mode Managed Agents
dispatch_agentandupdate_mirrorstill raiseNotImplementedError. Target: v1.8+ when research-preview access is available. - v1.7.0 ships with
write_kbandco_signas colony-policy operations that work in both mock and live mode (they don't need a Managed Agents API call — writes go to local files; co-sign is a Mirror policy lookup). This is a scope refinement: these two operations were previously xfailed but are now correctly not substrate-dependent.
Philosophically
The review's closing line: "The cure is to apply the same honesty to the example that the thesis now applies to itself." v1.7.0 is that cure — the example's code now does what its README promises, and when it doesn't, test_walkthrough.py notices.
Cite as:
Oliver, D. (2026). The Agent Colony: A Pattern Language for Self-Governing AI Agent Ecosystems (v1.7.0). https://github.com/DavidROliverBA/agent-colony-pattern