Skip to content

v1.7.0 — Honest Teaching Colony (response to external review)

Choose a tag to compare

@DavidROliverBA DavidROliverBA released this 14 Apr 14:49
· 6 commits to main since this release

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

  1. 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.
  2. 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[].
  3. The Comprehension Contract was not enforced — update_mirror did none of the checks substrate-contract.md promised.
  4. The event stream was duplicated — driver and adapter emitted the same logical actions with different names.
  5. Mirror writes polluted git-tracked files — every run left colony/mirrors/teacher-agent.yaml modified.
  6. The classifier accepted caller-supplied blast_radius overrides — 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, patch as 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_mirror performs 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 specific ContractViolation subclass.
  • 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_event is 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:

  1. Teacher's beekeeping answer contains "worker" (proves the canned branch fired)
  2. Teacher's Agent Colony answer contains "Mirror" (proves the new capability is used)
  3. Teacher's Mirror contains both capabilities under capabilities.capabilities[]
  4. No floating capability_add key at the root of the Mirror
  5. Classification event with review_regime: Peer Review
  6. cosign.granted event with granted: True
  7. mirror.updated event 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_agent and update_mirror still raise NotImplementedError. Target: v1.8+ when research-preview access is available.
  • v1.7.0 ships with write_kb and co_sign as 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