Skip to content

v5.0.0 — Seams: pluggable storage, vault-write safety, dev-loop split

Choose a tag to compare

View all tags
@alexherrero alexherrero released this 13 Jun 20:09
· 115 commits to main since this release
v5.0.0
cc31d85

[v5.0.0] — 2026-06-13 — Seams: pluggable storage, vault-write safety, and the dev-loop split completes

MAJOR. V5 is the seam release: the load-bearing parts of the harness — how memory data is stored, how concurrent vault writes stay safe, how the memory layer talks to the process layer, and how plans are addressed — are now formal, tested boundaries instead of inlined assumptions. The headline is the memory↔storage seam (V5-1, five parts): a backend-agnostic storage contract with a named-protocol registry, a built-in device-local backend, a backend-agnostic conformance suite, the existing vault write-path wrapped behind the seam (moving zero data — the never-orphan invariant), and fail-loud backend selection that refuses a memory operation with an "install the plugin" error rather than silently demoting to device-local. It also lands the V5-0 vault-write protocol (a real cross-process lock + content-hash CAS + atomic writes + a broadened conflict-janitor), the V5-4 process seam (a one-way memory↔process read-only edge with an import-direction gate), V5-10 named plans (multiple concurrently-addressable plans + a read-only queue dashboard), and the seven-section documentation convergence. The MAJOR bump is earned by the breaking half: the dev-loop primitives and the migrate-to-diataxis / documenter / diataxis-author surfaces that used to be vendored in the harness are retired — they are now provided by crickets plugins, which the harness dispatches via graceful-skip. Single-repo release; many of these commits were already on main untagged — this is the bundled tag.

Breaking

  • The dev-loop primitives are no longer vendored in the harness — they come from crickets plugins (3d2b328). The harness used to carry its own copy of the /setup·/plan·/work·/review·/release·/bugfix loop primitives; those are retired here and provided by crickets's developer-workflows plugin instead. The harness dispatches them via the wiki-maintenance / capability-probe graceful-skip path — present → dispatch, absent → silently skip — so a standalone harness with no crickets installed still runs, just without the loop primitives.
  • migrate-to-diataxis and the vendored documenter / diataxis-author copies are retired → crickets (5e85b6b, 8a3b238, 0b831ab, 53ec0b9, 0344ad8). The harness no longer ships the documentation sub-agents; it dispatches the crickets-provided documenter through the same graceful-skip probe. A retire-invariant gate (0344ad8) keeps the duplicate copy from creeping back. See ADR 0011 — V5 unbundling (8f4adb6) for the split rationale.

Added

  • Memory↔storage seam — a pluggable, backend-agnostic storage contract (V5-1). A verb-by-verb StorageBackend protocol with a Locator abstraction (no raw Path leaks across the seam, enforced by a gate), a named-protocol BackendRegistry (protocol → backend, resolve-as-absent), and a three-tier source/derived contract (Tier / TierLayout + named V6 ops) (5598e95, 21312ba, a287478). Ships a built-in device-local backend over the seam with a named conflict-strategy slot and a scope guard (214979e, eb48524, 745b86d). The existing vault write path is wrapped behind the seam moving zero data — the never-orphan invariant, proven by test (05a7ce1, f870aab, 4b9c397, 298861d).
  • Fail-loud backend selection + a doctor storage preview (V5-1 part 5). A storage.backend config key (set via agentm_config.py --storage-backend) and a selection resolver (explicit storage.backend → existing vault_path → fresh device-local); if the named backend's plugin is not installed, the engine refuses with an "install the plugin" error and never silently demotes to device-local (208bca5, c9ec6e3, bd3a9e6, 53a7982). A read-only doctor storage check (python3 scripts/backend_selection.py --doctor) previews the selected backend and its plugin-installed state before any memory operation could refuse — [OK]/[WARN]/[FAIL] with the [FAIL] line byte-identical to the engine's live refusal, and without constructing a backend (construction would mkdir the root) (8264bb4). See ADR 0013 — storage-seam fail-loud selection and the Choose a storage backend how-to.
  • Vault-write protocol — safe concurrent vault writes (V5-0). A real cross-process vault_lock (the Phase-0 protocol), content-hash CAS for replace-style writes routed through atomic_write, the harness_memory state writers + /memory save+evolve routed through a vault_mutex, and a conflict-janitor broadened to four marker families plus the Windows DriveFS lost_and_found (0d6d2fd, 64d24b4, a39019e, 04ae3f3, 6362bab). See ADR 0012 — vault-write protocol (0e04117).
  • Named plans — multiple concurrently-addressable plans (V5-10). A named-plan resolver contract + resolve_active_plan binding with a loud-error guard, a read-only queue_status_lite multi-plan dashboard, a named-plan naming gate, named-plan-aware session-start hooks + doctor, and a resolve-active-plan CLI verb bridging the crickets writers (dfdcf8f, 7f6baa5, 0f27f8f, 454108c, d76a2d1, 543bb3c). Includes a worktree slug-resolution safety probe (da25ca5).
  • Process seam — a one-way memory↔process edge (V5-4). A read-only process_seam memory↔process client seam, with a check-process-seam-import-direction gate enforcing the one-way dependency (3358c6b, 6a4d5b5, 04ae267).

Changed

  • Documentation converged on the seven-section taxonomy. The wiki was rebuilt to a seven-section frame (Architecture manifest + six pillar overview pages, How-to / Reference / Explanation / Decisions), check-wiki.py swapped to the seven-section linter, documentation.md and templates/wiki/ reshaped to match, and ADR 0004 amended to the new taxonomy (265420e, 3488346, a0f3328, 1cefcb3, 9e5322c, 16842b6, 51f77a9, deb6ef4, b0f3747).
  • Documenter dispatch rewired to crickets graceful-skip across the harness and the Claude Code adapter surfaces (0b831ab, 53ec0b9) — present → dispatch the crickets documenter, absent → skip silently, no hard dependency.
  • /work runs the full task list autonomously, gated by a per-task safety pre-check, rather than one task per session (51574f4).

Internal

  • Backend-agnostic conformance suite (V5-1). A storage-backend conformance suite + a derived_maintenance accessor, run against device-local on the cross-OS gate, with negative + positive fixtures proving the suite actually bites (da01599, ef16985, 36d0102, d0712c3).
  • Storage-seam hardening (audit follow-ups). Reject backslash + NUL keys in normalize_key (a Windows traversal hole), a mutex + bounded retry on the registry CAS, a Windows DriveFS lost_and_found probe, and a documented "mtime is a hint, not a total order on synced backends" clarification (380d171, cc2887f, 394ee84, fbf4459, b2442c0).
  • Gate + CI breadth. check-workflow-parity mirroring the dogfood workflows, a wiki-sync dupe-guard fix applied to the template twin + reserved-special-files exclusion, an agentm pre-push PII guardrail template, and a Windows CI regression fix from the V5-0 + V5-10 push (68039c4, 91f813c, 6ba8ba9, ce041b3, 6230b34).
  • Design-doc + memory plumbing. Adopted the Agent-M architecture design docs from crickets, codified the design-doc authoring conventions, added an external/<slug> vault directory, and taught the documenter-context to read the relocated _global wiki-style store (936e391, 9bec04e, d650d9e, 90262d0, 8776f03).

Cross-references

Assets 2
Loading