phronomy 0.22.0 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce5a4ac39be13ef17ca1c7cd5d812b0ccdd8ea8523fdf2e59ee8f7e78e2830fa
-  data.tar.gz: 3c943cd7b11ddd1bbe2e22fdd16f3855564361c3dba093d39f5f32d193850b5a
+  metadata.gz: 1c8712213b18692b6bf9531110ffc38fa0f9d069509bf85b3424c5b77a76eb8e
+  data.tar.gz: c63a2cc058ad50b80306bcadfd7a99304f216ab02375272e43ab6cf5c38cb451
 SHA512:
-  metadata.gz: e41fcf5aee7eaed49f3ef13c7399c787c281232909b07d1fa2a2e14b4a4d443222280ead723e885faeea0534e9173c036e16e90e6af04de4a440f0a76020e2c1
-  data.tar.gz: f0dbf8fa8947760cafbc530226a021b009acf3f0be37ddee08a5404087422b5508cd5df83ab50456b43fa8f1eb57a889f8a1974372d95b98edcad1752ddda562
+  metadata.gz: 64de5d992461ceaccc2d579bbd6b3046b8ce711ca65f68b14cfb9f9fe45d724c2db0646ef547fe7d6a4502a7ca6657b9330d33898e1f24e694418fe9e41c324d
+  data.tar.gz: 507d16006d00d4304db2d1e2e67a61e605dbabfc190dc7cdbbf198e17e4648fc5a0767904f503e2da826f7744859c78ec99f7585732b45ace6251e1296cb274a

data/.mutant.yml

@@ -15,9 +15,8 @@ matcher:
     - Phronomy::LlmContextWindow::TokenBudget
     - Phronomy::Agent::ContextAssembler
     - Phronomy::Agent::ContextPolicies::Default
-    - Phronomy::Agent::ContextParts::UnitBuilders::DependencyAwareUnitBuilder
-    - Phronomy::Agent::ContextParts::Requirements::RequiredContextResolver
-    - Phronomy::Agent::ContextParts::Selectors::RecentFirstSelector
-    - Phronomy::Agent::ContextParts::Budget::TokenBudgetPacker
+    - Phronomy::Agent::ContextPolicyInputBuilder
     - Phronomy::Agent::ContextPlanValidator
+    - Phronomy::Agent::HandoffPolicy
+    - Phronomy::Agent::HandoffProjection
     - Phronomy::VectorStore::InMemory

data/CHANGELOG.md

@@ -12,29 +12,215 @@ Release history for 0.14.0 and earlier is archived in
 
 ## [Unreleased]
 
+### Fixed
+
+- Run recovered output filtering inside the ordinary Agent FSM so filter
+  exceptions commit a failed execution and release admission, including after
+  another restart. Preserve explicit filter blocking as the `blocked` status.
+- Propagate a coordinator's blocked outcome, and a worker's blocked outcome
+  under `on_error: :raise`, to Team failure. Preserve skipped worker errors and
+  committed failure precedence over later cancellation across restart.
+- Keep Recovery content materialization, approval restoration reads, and F1
+  resolution readback off EventLoop. Apply prepared invocation state only on
+  EventLoop, reject stale results, and retain confirmed resolution facts when
+  later content reads fail.
+- Avoid reading Orchestrator Knowledge again while constructing invocation-owned
+  Tools; those children inherit the Knowledge already saved with their slots.
+
+---
+
+## [0.23.0] - 2026-08-29
+
+### Four-category Context Policy SPI and transaction boundary (ACS-04)
+
+#### Added
+
+- Public immutable `ContextPolicyInput` typed values for `instruction`,
+  `knowledge`, `tools`, and indivisibly grouped `conversation`.
+- Agent-class `context_policy <instance>` binding for reusable Application
+  Context strategies, with built-in Default fallback.
+- Small ContextPolicy helpers for current-call generated instruction, Knowledge,
+  and conversation items.
+- Framework trace boundary around ContextPolicy invocation without standard-trace
+  inclusion of full Policy input/Plan content.
+
+#### Changed
+
+- `ContextPlan` now directly carries ordered output material in the same four
+  semantic categories.
+- Default Policy uses deterministic recent-conversation / stable-fit Knowledge
+  selection with an approximately 60/40 variable budget split and preserves the
+  effective Tool set.
+- Custom Policy may select/reorder a subset of effective Tools; arbitrary
+  schema-only runtime Tool creation remains outside ACS-04 because durable
+  runtime Tool identity/wiring is not defined.
+- ContextPolicy executes outside Phronomy Persistence transactions. The durable
+  base/revision is revalidated before the short Manifest/execution commit.
+- Context assembly policy version is `8`.
+
+#### Removed
+
+- `ContextRequest`, `ContextPolicyDescriptor`, `ContextPolicyRegistry`, and
+  `DerivedContentSpec`.
+- Intermediate selection-unit/policy-parts machinery superseded by the typed
+  four-category SPI: `Selection::Unit`, `Selection::Validator`,
+  `DependencyAwareUnitBuilder`, `RequiredContextResolver`,
+  `RecentFirstSelector`, and `TokenBudgetPacker`.
+- Descriptor persistence/reconstruction and old `ContextPlan` fields
+  `selected_unit_ids`, `derived_contents`, `ordering_hints`, and
+  `policy_descriptor`.
+
+### Workflow Runtime admission and durable terminal barrier (ACS-13)
+
+#### Added
+
+- ADR-026 defining opaque process-local Workflow admission ownership,
+  admission-before-hydration ordering, and FSMSession-integrated terminal
+  persistence.
+- Explicit Workflow terminal persistence outcomes: known success, known failure,
+  and fail-closed outcome uncertainty.
+
+#### Changed
+
+- Workflow admission ownership no longer reuses the future `fsm_session_id`.
+  EventLoop acquires a separate opaque owner token before durable load and binds
+  the concrete FSMSession routing ID only after hydration.
+- Durable Workflow halt/completion now remains nonterminal while the final
+  snapshot is saved. The save result returns to the same FSMSession, and only a
+  known-successful result permits `HALTED` / `COMPLETED`, admission release, and
+  caller Task settlement.
+- Portable known Persistence failures follow the Workflow error path. An
+  arbitrary storage/transport error whose commit outcome is not established is
+  treated as outcome-unknown: the success barrier stays closed and the
+  `workflow_instance_id` admission remains fail-closed/recovery-required.
+- Workflow persistence result handling is backend-topology neutral; the FSM does
+  not depend on local/network/database transport details.
+
+### Process-local Agent ownership and Runtime admission (ACS-12)
+
+#### Added
+
+- ADR-025 defining one mutable live Agent owner per `agent_id` per Runtime and
+  EventLoop-owned same-process top-level execution admission.
+- `Agent::Base.get(agent_id)` for process-local live-owner lookup without
+  Persistence I/O.
+- `AgentAlreadyExistsError` for create/new identity conflicts and
+  `AgentPurgedError` for stale references after successful purge.
+
+#### Changed
+
+- Repeated `Agent.load(agent_id, persistence:)` returns the exact existing live
+  Agent object; a durable-only Agent is hydrated once, and a missing durable
+  Agent remains a strict `Persistence::NotFoundError`.
+- `new` / `create` mean creation only and reject an identity that is already
+  live or already durable instead of materializing a second mutable owner.
+- EventLoop acquires the same-Agent top-level execution slot before initial
+  Offload/Persistence work. Suspension retains that slot; known durable terminal
+  completion releases it; uncertain durable outcomes remain fail-closed.
+- Persistence `executions.create_active` / atomic admission remains the durable
+  second line of integrity defense rather than the primary same-process lock.
+- Runtime-lifetime Agent ownership is released on clean Runtime shutdown.
+  Successful `purge!` is the explicit earlier destruction boundary and makes
+  the stale Agent object permanently unusable before the identity can be reused.
+
+### EventLoop single-writer Agent Runtime (ACS-11)
+
+#### Added
+
+- ADR-024 defining EventLoop as the single writer of Phronomy-managed live
+  Agent execution state and operation-specific Offload command/result apply.
+- Runtime read-only Agent execution-owner lookup for approval/live-owner
+  routing without exposing mutable execution internals.
+- Provider result authority using current FSMSession/FSM state plus semantic
+  `llm_call_id`; stale Provider results are consumed without advancing the FSM.
+
+#### Changed
+
+- Agent initial preparation, follow-up Manifest preparation, approval resume,
+  and terminal durable commits now return values from OffloadPool and apply
+  committed live-state advances only on EventLoop.
+- AgentInvocation owns FSM-local uncommitted Provider/Tool/runtime facts.
+- Tool authorization captures Agent identity and Tool description data before
+  worker execution; the authorization worker receives no live Agent, Tool, or
+  ToolInvocation reference. Application-owned approval/facts/requirement
+  callables remain explicit behavior handles.
+- `ApprovalEvaluationRequest` is value-only: Agent identity is exposed as
+  `agent_id`, `agent_definition_id`, and `agent_definition_version`; Tool
+  identity/description is exposed through `tool_name` / `tool_schema`.
+- Tool authorization/execution outcomes carry semantic `tool_invocation_id`
+  and are applied by the Tool FSMSession.
+
+#### Removed
+
+- `AgentExecutionActivation`, `Agent::ActivationRegistry`,
+  `Runtime#__agent_activations`, and the `phronomy_activation` config bridge.
+- Live-object accessors `ApprovalEvaluationRequest#agent` and
+  `ApprovalEvaluationRequest#tool`; approval policies use value identity and
+  Tool-description fields instead.
+
+
+### Semantic Multi-Agent Handoff and shared Selection
+
+#### Added
+
+- `Phronomy::MultiAgent::HandoffPolicy` with required, forbidden, and selectable
+  transfer rules for current request, history, Knowledge, and Tool exchanges.
+- `Phronomy::MultiAgent::Runner.new(main_agent:, handoffs:)` as the public
+  semantic Handoff coordinator.
+- Typed private Handoff request/context/provenance values, explicit
+  `AgentExecution` `:handed_off` terminal semantics, and Runtime/EventLoop-owned
+  active-Agent coordination.
+- Shared `Phronomy::Agent::Selection::Candidate`, `Unit`, `Constraint`, and
+  validation machinery for Context and Handoff selection.
+- ADR-016 and the 0.22 migration guide for the semantic Handoff clean break.
+
+#### Changed
+
+- Handoff is now an explicit Source-to-Target responsibility transfer rather
+  than sentinel Tool-result routing. Generated Handoff Tool names are private
+  transport details only.
+- Handoff Context is projected from the effective Source Manifest, materialized
+  immutably with provenance, and may cross Agents backed by different Persistence
+  adapters without adopting Source material into Target Journal/Knowledge.
+- Target Context Policy remains the final per-LLM-call selection authority;
+  transferred material enters Target assembly as selectable Context candidates.
+- The active Target persists across user turns and Runner-facade recreation while
+  the same main Agent instance and Runtime remain alive. Runtime/process reset
+  intentionally does not restore active-Agent continuation.
+- Context assembly policy version is now `7` for the shared Selection and
+  Handoff-Context contract.
+
+#### Removed
+
+- `Phronomy::Agent::Runner`, the `agents:` / `routes:` Runner API, sentinel-map
+  routing, and Agent-owned `_add_handoff_tool` / `_handoff_tools` mutation.
+- `Phronomy::Agent::ContextCandidate` and
+  `Phronomy::Agent::ContextSelectionUnit`; internal callers use the shared
+  `Agent::Selection` model without compatibility aliases.
+
 ### Unified Persistence and durable-state ownership
 
 #### Added
 
 - `Persistence#workflow_states` with optimistic revision checks for durable Workflow snapshots.
-- Runtime-local Agent Activation ownership; live `AgentExecutionActivation` values are no longer Persistence repositories.
+- Runtime-local Agent execution ownership outside Persistence; ACS-11 now places the mutable live-state authority on EventLoop.
 - `Agent::Base.live_for_execution(execution_id)` for resolving the current process's live owner Agent without reloading Agent or Execution state from Persistence.
-- Owner-aware Workflow admission keyed by durable `thread_id` and owned by a per-execution internal `fsm_session_id`.
+- Owner-aware Workflow admission keyed by durable `workflow_instance_id`; ACS-13 now uses a Runtime-only opaque owner token that is separate from concrete `fsm_session_id` routing.
 - ADR-014 and the 0.19 migration guide for the unified durable-state architecture.
 
 #### Changed
 
-- Live Agent instances now remain the authoritative logical-state owners after hydration. Context Policy and follow-up Manifest preparation use the Agent-local root, Journal view, and Activation state instead of reloading mutable Agent state for freshness.
+- Live Agent instances remain authoritative for AgentRoot/Journal state after hydration, while EventLoop owns active execution-state mutation. Context Policy and follow-up Manifest preparation use those local views instead of reloading mutable Agent state for freshness.
 - `Phronomy.configuration.persistence` is the global durable backend for Workflows and for Agent `new`/`create` calls that do not explicitly inject another Persistence instance.
 - Agent durable writes use optimistic revision/Journal-position guardrails; conflicting external writes fail instead of being silently reloaded or merged.
-- Approval suspension/resume preserves the same live Agent/Activation/AgentInvocation. Approval remains an Agent-instance operation; callers with only an `execution_id` resolve the live owner with `Agent::Base.live_for_execution` (or the expected concrete Agent class) before calling `agent.approve` / `agent.approve_async`.
-- Workflow durable I/O runs outside EventLoop through OffloadPool, while `thread_id` admission remains owned until terminal/halted snapshot persistence completes inside the current Runtime. Workflow admission is process-local; optimistic revisions detect stale commits across processes but do not prevent duplicate execution or undo already-performed external side effects.
-- Workflow `thread_id`, Runtime `fsm_session_id`, and application `session_id` now have distinct responsibilities.
+- Approval suspension/resume preserves the same process-local Agent/AgentInvocation owner. Approval remains an Agent-instance operation; callers with only an `execution_id` resolve the EventLoop-backed live owner with `Agent::Base.live_for_execution` (or the expected concrete Agent class) before calling `agent.approve` / `agent.approve_async`.
+- Workflow durable I/O runs outside EventLoop through OffloadPool. Terminal/halted snapshot persistence now completes inside the owning FSMSession lifecycle; only a known-successful save permits normal terminalization and admission release. Workflow admission remains process-local; optimistic revisions detect stale commits across processes but do not prevent duplicate execution or undo already-performed external side effects.
+- Workflow `workflow_instance_id` is distinct from one concrete Runtime FSMSession identity; generic application `session_id` is not a Phronomy core domain identity.
 
 #### Removed
 
 - `Phronomy::StateStore`, `StateStore::InMemory`, `Workflow.define(..., state_store:)`, `Configuration#state_store`, and per-invocation `config[:state_store]`.
-- `Persistence#activations`; ActivationRegistry is transient Runtime state.
+- `Persistence#activations`; live Agent execution state is Runtime-only. The transitional ActivationRegistry is subsequently removed by ACS-11.
 - Class-level `Agent::Base.approve` / `Agent::Base.approve_async` routing APIs and their caller-supplied `persistence:` argument; approval execution now goes through the resolved live Agent instance.
 
 ### Public API façade and typed contracts
@@ -59,6 +245,25 @@ Release history for 0.14.0 and earlier is archived in
   return `Task`.
 - `InvocationContext` construction is classified consistently with its documented
   Beta application API.
+- Generic Agent invocation identity is removed: `InvocationContext` no longer
+  exposes `thread_id` / `session_id`, Agent invocation APIs no longer accept
+  `thread_id:`, and no replacement generic correlation identity is introduced.
+- The canonical `JournalRecord` representation no longer contains
+  `correlation_id`; legacy durable Hashes containing the removed key remain
+  readable without an eager data rewrite.
+- Tool approval notification/policy parent identity now uses canonical Agent
+  `execution_id` instead of `agent_invocation_id`; new suspended-execution
+  approval data uses the same parent identity.
+- Legacy embedded suspended approval hashes remain readable by deriving the
+  logical parent from their enclosing Agent execution; historical
+  content-addressed audit bodies are not rewritten.
+- Agent, Tool, and Multi-Agent concrete `FSMSession` instances no longer reuse
+  domain/context IDs as EventLoop routing targets. Async callbacks use
+  session-local event sinks, and Provider completion is routed to the owning
+  FSMSession before EventLoop validates/applies `llm_call_id`-bound result
+  state. Workflow retains its pre-load admission ordering through a private
+  single-use FSMSession identity reservation; opaque Workflow admission
+  ownership remains ACS-13 work.
 - OutputParser `parse` is classified as the public subclass extension point that
   concrete parsers implement.
 
@@ -133,8 +338,8 @@ Release history for 0.14.0 and earlier is archived in
   returns a completion handle immediately.
 - `Tool#call_async` for ordinary cooperative Tools no longer consumes a
   OffloadPool worker. `:offloaded` remains the worker-pool route.
-- Framework-owned short in-memory Tools (handoff sentinels, TeamCoordinator
-  queue controls, and SharedState store access) explicitly declare
+- Framework-owned short in-memory Tools (TeamCoordinator queue controls and
+  SharedState store access) explicitly declare
   `execution_mode :cooperative` instead of using the blocking-I/O default.
 - MultiAgent fan-out uses a FanOut FSMSession rather than per-child OS Threads.
 - `TimerQueue` is driven by EventLoop and owns no Thread.
@@ -172,7 +377,7 @@ Release history for 0.14.0 and earlier is archived in
   transcript/Knowledge lifecycle semantics.
 - Active Context tests, integration fixtures, benchmarks, mutation subjects,
   design documents, and API snapshots now describe the canonical
-  Journal -> ContextCandidate -> Context Policy -> Manifest architecture.
+  Journal -> Selection::Candidate -> Context Policy -> Manifest architecture.
 
 #### Removed
 

data/CONTRIBUTING.md

@@ -114,17 +114,85 @@ OffloadPool work is supplied through `CancellationToken`.
 
 ---
 
-## Architecture Decision Records
-
-Key design decisions are documented as ADRs in
-[docs/decisions/](docs/decisions/). Read these before making significant changes
-to the threading model, persistence/context authority, or public API shape.
+## Architecture Authority and Decision Records
+
+Phronomy has **no universal artifact priority**. Different artifacts answer
+different questions. The normative repository rule is
+[`017-design-authority-and-adr-governance`](docs/decisions/017-design-authority-and-adr-governance.md);
+the complete ADR status/supersession index is
+[`docs/decisions/README.md`](docs/decisions/README.md).
+
+Use these authority boundaries:
+
+- Accepted, non-superseded ADRs define architecture intent.
+- Source/runtime behavior defines current implementation reality; it does not
+  silently amend an ADR.
+- Public API and extension-SPI contracts are composite: runtime behavior,
+  `@api` classification, formal API documentation, and explicit
+  compatibility/contract tests all participate.
+- RBS does not create a contract. It types a contract already established by
+  those sources.
+- Ordinary implementation tests are regression evidence. Only tests explicitly
+  maintained as architecture guards or compatibility/contract tests have that
+  stronger role.
+- Historical, Archived, and Superseded material is non-normative for current
+  architecture.
+
+When architecture intent, public contract, and implementation reality disagree,
+treat the discrepancy as an **architecture inconsistency**. Do not choose a
+winner merely because one artifact is newer. Record the conflict and resolve it
+explicitly according to the process in the ADR index.
+
+ADR references should use a file link or the canonical filename key. This is
+required for the two legacy `011` decisions because bare `ADR-011` is
+ambiguous. Do not renumber historical ADRs to repair that legacy collision.
 
 For Agent Context work, ADR-012 and ADR-013 define the current Journal,
 Manifest, Context Policy and persistent Knowledge model. ADR-010 defines the
 EventLoop/FSMSession, Task, and OffloadPool execution boundary. ADR-015 defines
 the Tool public façade, extension-SPI boundary, and RBS ownership rules.
 
+Current explanatory architecture starts at [`docs/architecture.md`](docs/architecture.md).
+Non-current design snapshots live under `docs/archive/design/` and are
+non-normative. Do not treat archived/historical material as a current contract
+merely because it remains searchable in the repository.
+
+### Durability, recovery, and failure vocabulary
+
+Architecture-sensitive durability, concurrency, recovery, cancellation, and
+external-effect changes must use
+[`018-durability-guarantees-and-failure-model`](docs/decisions/018-durability-guarantees-and-failure-model.md).
+
+Do not write a bare claim such as "durable", "recoverable", "safe", or
+"exactly once". State:
+
+1. the guarantee subject;
+2. the exact guarantee property (for example durable-state restart
+   readability, execution resumption, stale durable-transition conflict
+   detection, or duplicate external-side-effect prevention);
+3. the component/contract that provides it;
+4. the applicable F0-F4 failure class(es);
+5. whether X0 External Effect Boundary is crossed; and
+6. whether the architecture result is YES, CONDITIONAL, or NO, including the
+   condition for every CONDITIONAL guarantee.
+
+In particular:
+
+- F0 operation failure and F1 outcome uncertainty are distinct dimensions and
+  may co-occur; an F0 result does not prove durable/external outcome certainty.
+- durable-transition atomicity is not commit-outcome certainty.
+- optimistic conflict detection is not cross-process execution exclusion.
+- process/runtime loss (F4) does not imply confirmed durable state was lost.
+- X0 external side effects are not automatically atomic with Persistence.
+- semantic IDs do not by themselves provide duplicate prevention.
+- arbitrary external exactly-once execution is not an unconditional Phronomy
+  guarantee.
+
+Fault-injection and recovery tests should state which failure class/boundary
+they exercise and must not imply stronger guarantees than the test proves.
+F0-F4/X0 are architecture/test vocabulary, not a required public exception
+hierarchy.
+
 ---
 
 ## Mutation Testing
@@ -155,13 +223,17 @@ The authoritative subject list is `.mutant.yml`. It currently includes:
 - `Phronomy::LlmContextWindow::TokenBudget`
 - `Phronomy::Agent::ContextAssembler`
 - `Phronomy::Agent::ContextPolicies::Default`
-- `Phronomy::Agent::ContextParts::UnitBuilders::DependencyAwareUnitBuilder`
-- `Phronomy::Agent::ContextParts::Requirements::RequiredContextResolver`
-- `Phronomy::Agent::ContextParts::Selectors::RecentFirstSelector`
-- `Phronomy::Agent::ContextParts::Budget::TokenBudgetPacker`
+- `Phronomy::Agent::ContextPolicyInputBuilder`
 - `Phronomy::Agent::ContextPlanValidator`
+- `Phronomy::Agent::HandoffPolicy`
+- `Phronomy::Agent::HandoffProjection`
 - `Phronomy::VectorStore::InMemory`
 
+The nightly mutation matrix mirrors this authoritative list so each subject can
+run in an isolated job with its own timeout. The regular test suite includes a
+configuration-consistency guard that fails if the nightly subject set diverges
+from `.mutant.yml`.
+
 The Tool mutation subject intentionally uses
 `Phronomy::Agent::Context::Capability::Base`, which is the implementation
 canonical name returned by the single Class object's runtime `Class#name`.

data/README.md

@@ -19,6 +19,7 @@ tracking `main` directly.
 - **Persistence** — unified durable backend for Agent state and Workflow `workflow_states`.
 - **Workflow** — state-machine-driven application workflow with explicit events and wait states.
 - **Tool / Capability** — callable application capability exposed to an Agent; application-defined Tools subclass `Phronomy::Tool::Base`.
+- **Multi-Agent Handoff** — semantic Source-to-Target responsibility transfer with policy-bounded Context projection and persisted active responsibility and exact Target recovery within one Persistence domain.
 - **EventLoop + FSMSession** — the framework control plane for logical lifecycle coordination.
 - **OffloadPool** — bounded operating-system-thread execution boundary for synchronous work that must not run on EventLoop.
 - **Task** — the common thread-free completion handle returned by Phronomy asynchronous APIs, including OffloadPool-backed work.
@@ -91,17 +92,23 @@ task = ResearchAgent.new.invoke_async("Research Ruby AI frameworks")
 result = task.wait_result   # top-level/external caller only
 ```
 
-A block listener receives Agent lifecycle events and is equivalent to `on_event:`:
+Agent lifecycle events are bound to one live Agent Runtime incarnation.
+Register `on_event:` (or the equivalent construction block) when the Agent
+is created or loaded, then invoke it without a per-call listener:
 
 ```ruby
-task = ResearchAgent.new.invoke_async("Research Ruby AI frameworks") do |event|
-  puts event.type   # :done, :error, :tool_call, :tool_result, etc.
-end
+agent = ResearchAgent.new(
+  on_event: ->(event) {
+    puts event.type   # :done, :error, :tool_call, :tool_result, etc.
+  }
+)
 
-# on_event: keyword form is also accepted and behaves identically
-task = ResearchAgent.new.invoke_async("Research Ruby AI frameworks", on_event: listener)
+task = agent.invoke_async("Research Ruby AI frameworks")
 ```
 
+The same listener registration is available on `create` and `load`.
+Public per-invocation `on_event:` / listener blocks are removed.
+
 ## Runtime model
 
 Phronomy uses one completion model with two execution mechanisms:
@@ -134,11 +141,13 @@ contracts, timeout/cancellation semantics, metrics, and callback rules.
 
 - [Getting started](docs/getting-started.md) — installation, RubyLLM setup, Agent/Workflow basics, persistence, streaming.
 - [Features and API stability](docs/features.md) — public feature matrix and stability labels.
+- [Architecture](docs/architecture.md) — canonical current explanatory architecture entry and authority navigation.
 - [Runtime and concurrency](docs/runtime-and-concurrency.md) — EventLoop, FSMSession, Task, OffloadPool, cancellation, observability.
 - [MCP client](docs/mcp-client.md) — Model Context Protocol (MCP) integration and supported schema subset.
 - [Migration from 0.15-era APIs](docs/migrations/0.15.md).
 - [0.16 cleanup migration](docs/migrations/0.16.md).
 - [0.19 unified Persistence migration](docs/migrations/0.19.md).
+- [0.22 semantic Multi-Agent Handoff migration](docs/migrations/0.22.md).
 - [Architecture Decision Records](docs/decisions/) — design rationale and superseding decisions.
 - [CHANGELOG](CHANGELOG.md) — current development and recent release history.
 - [Changelog archive: 0.14.0 and earlier](docs/changelog/0.14-and-earlier.md).