phronomy 0.25.0 → 0.27.0

data/docs/decisions/030-agent-handoff-domain-and-durable-responsibility.md

@@ -4,6 +4,11 @@
 
 Accepted. V2 revision 2, 2026-09-06.
 
+The HandoffRunner namespace and ownership are amended by
+[034-handoff-runner-coordination-ownership](034-handoff-runner-coordination-ownership.md).
+The public Runner is now `Phronomy::MultiAgent::HandoffRunner`. Other Handoff
+types and the durable semantics below remain unchanged in this first step.
+
 User approval covers the V2 boundary and the five recovery-contract clarifications.
 Acceptance is design authority; it is not a claim of repository integration or test success.
 

data/docs/decisions/031-durable-multi-agent-coordination.md

@@ -4,6 +4,11 @@
 
 Accepted. V2 revision 2, 2026-09-06.
 
+The HandoffRunner namespace and ownership are amended by
+[034-handoff-runner-coordination-ownership](034-handoff-runner-coordination-ownership.md).
+The public Runner is now `Phronomy::MultiAgent::HandoffRunner`. Other Handoff
+types and the durable semantics below remain unchanged in this first step.
+
 User approval covers the V2 boundary and the five recovery-contract clarifications.
 Acceptance is design authority; it is not a claim of repository integration or test success.
 

data/docs/decisions/032-storage-backend-composition.md

@@ -0,0 +1,80 @@
+# 032: Compose domain persistence over a storage backend
+
+- Status: Accepted
+- Domain ownership refined by: [033-domain-persistence-ownership](033-domain-persistence-ownership.md)
+- Date: 2026-09-17
+- Refines: [014-unified-persistence-durable-state](014-unified-persistence-durable-state.md)
+
+The raw fixed-repository/error portions are amended by
+[ADR-058](058-neutral-storage-primitives.md). Domain ownership and applicable
+transaction/uncertainty decisions below remain in force.
+
+## Context
+
+The previous `Persistence` class combined raw storage contracts with domain
+repository construction, codecs, and result queries. Physical backends inherited
+that class, and SQL implementations called `build_transaction_view` to construct
+upper domain facades. This made the common storage boundary depend on the
+entities whose records it stored.
+
+## Decision
+
+1. `Storage::Backend` and `Storage::Repositories` define synchronous raw storage
+   and transaction-view protocols. `Storage::DurableRecord` and portable storage
+   errors belong to this common contract. These files do not depend on Agent,
+   MultiAgent, Runtime, or the domain-facing Persistence implementation.
+2. Concrete backends depend on that contract and their physical storage tools.
+   The in-memory implementation lives in `storage/backends/in_memory.rb` and
+   retains its single Monitor and single all-repository transaction snapshot.
+3. `Persistence.new(backend:)` composes the domain service over a selected backend.
+   The existing domain codecs and facades remain in `persistence/`. They validate
+   and convert records using the actual domain record definitions.
+4. The same facade builder wraps the root backend and the raw view yielded by
+   `backend.transaction`. Transaction conversion stays inside the backend block;
+   conversion failures therefore participate in its normal rollback semantics.
+5. `Persistence.in_memory` is the explicit convenience assembly. Backend selection
+   belongs to construction, not to the common storage contract.
+6. Replace the old Persistence subclass SPI, raw-repository constructor,
+   `build_transaction_view`, `Persistence::InMemory`, and old record/error owners.
+   No compatibility aliases or second implementation of that SPI are retained.
+   See the [migration guide](../migrations/storage-backend-composition.md).
+
+Both concrete backends and domain persistence depend on the common storage
+contract. These are sibling responsibility groups, not a requirement for one
+strict vertical ordering of the entire system. Runtime calls to a selected
+backend do not establish a source dependency on that backend's concrete class.
+
+## Preserved contracts
+
+All eight repositories remain one atomic transaction domain. Their IDs,
+revision/position checks, active execution constraints, record types, format
+versions, and payload schemas are unchanged. ContentStore retains its separate
+canonicalization API. The shared `AgentBusyError` remains the existing admission
+failure contract; its standalone definition does not load Agent implementation.
+
+Atomic durable-state transitions remain CONDITIONAL on a conforming backend for
+F0 operations; commit-outcome certainty under F1 remains NO as a general promise.
+F4 restart readability remains CONDITIONAL on retained confirmed durable data;
+InMemory does not provide disk retention. X0 external effects remain outside the
+storage transaction. This change adds no asynchronous SPI or execution ownership.
+
+## Consequences and validation
+
+Custom SQL backends migrate their superclass, record/error references, and raw
+transaction view construction. They keep all transaction repositories and the
+watermark bound to the same connection. Applications wrap a raw backend once.
+
+An isolated-load architecture test checks that storage can use opaque records and
+admission without loading domain or execution code. Public contract tests cover
+root/transaction view separation and removal of the replaced SPI. Existing
+repository conformance, commit/rollback/CAS, codec, recovery, and integration tests
+remain required. Codec rejection after a physical write must roll back the whole
+transaction, not leave a committed partial operation.
+
+Shared Immutable ownership has already moved to `Values::Immutable`; this change
+preserves that boundary. Domain model placement and unrelated module cycles
+remain separate subsequent changes. In particular, DurableCodec retains its
+TeamRoot / TeamExecution references to validate and reconstruct Team records.
+Those belong to domain persistence, not to the common storage contract.
+Moving a type or hiding a constant reference alone is not evidence that this
+storage boundary has been separated.

data/docs/decisions/033-domain-persistence-ownership.md

@@ -0,0 +1,79 @@
+# 033: Own persistence rules within each domain
+
+- Status: Amended
+- Date: 2026-09-18
+- Error boundary refined by: [043-storage-execution-constraint-notifications](043-storage-execution-constraint-notifications.md)
+- Refines: [032-storage-backend-composition](032-storage-backend-composition.md)
+
+The raw fixed-repository/error portions are amended by
+[ADR-058](058-neutral-storage-primitives.md). Domain ownership and applicable
+transaction/uncertainty decisions below remain in force.
+
+## Context
+
+ADR-032 separated raw storage from domain persistence, but the common-looking
+`persistence/` directory still collected Agent, Team, and Workflow schemas and
+repository facades. Moving that directory to an upper band in a dependency
+diagram described its contents; it did not establish suitable domain ownership.
+The public Persistence entry point also contained domain-specific result queries.
+
+## Decision
+
+1. `agent/persistence/` owns AgentRoot, Journal, AgentExecution, and Handoff
+   codecs/repositories and Agent/Handoff result queries.
+2. `multi_agent/persistence/` owns TeamRoot and TeamExecution codecs/repositories
+   and Team result queries. Team persistence can be used over a raw backend
+   without loading Agent implementation or the combined Persistence service.
+3. `workflow/persistence/` owns the Workflow record schema, normalization rules,
+   and state repository. Workflow symbol normalization remains specific to that
+   domain; other codecs do not adopt it implicitly.
+4. `Storage::RecordCodec` contains shared record-envelope and scalar validation.
+   Domain codecs extend it; it neither selects nor imports a domain codec.
+   These helpers and domain components are private implementation, not new SPI.
+5. `PersistenceComposition::Repositories` explicitly assembles the seven domain
+   repository wrappers and the existing ContentStore from one raw storage view.
+   The public `Phronomy::Persistence` service remains the compatible entry point.
+   It delegates queries and retains the Runtime observation-thread guard.
+   Each view creates and caches domain wrappers on first use, under one lock,
+   so Agent-only use does not load Team or Workflow implementations.
+6. Conversion remains inside `backend.transaction`. Root and transaction paths
+   use the same builder. Reusing the root view when the backend yields itself
+   retains the existing repository identity and fault-injection behavior.
+7. Delete the private combined `Persistence::DurableCodec` and
+   `Persistence::RepositoryFacades`; do not preserve a second owner through
+   compatibility aliases. Explicit historical migration keeps its public API
+   and calls the new domain codecs.
+
+InMemory, SQLite, and PostgreSQL are all concrete implementations of the common
+Backend contract. Domain repository wrappers are consumers of that contract;
+they do not introduce a second physical transaction boundary.
+
+## Preserved contracts and limits
+
+Public Persistence methods, Backend SPI, eight repository accessors, IDs,
+revisions/positions, active constraints, physical SQL schemas, record types,
+format versions, and payload schemas are unchanged. Existing SQL backends need
+no source migration for this ownership change. The public result-reader dispatch
+and observation guard remain in the public entry point.
+
+Atomic durable-state transitions and rollback remain CONDITIONAL on a conforming
+backend for F0. Commit-outcome certainty under F1 is not added. F4 restart
+readability depends on retained confirmed data; InMemory is not disk retention.
+X0 effects remain outside storage transactions.
+
+The raw `Storage::Repositories` still names eight Phronomy record repositories and
+an Agent watermark operation. This is an explicit intermediate state, not a claim
+that the framework contract is domain-neutral. Contract generalization and naming
+of the final common persistence framework are deferred to the staged plan below.
+
+## Validation
+
+Existing record-schema, backend conformance, optimistic conflict, recovery,
+Handoff, Team, Workflow, and public compatibility tests remain required. A
+separate-process boundary test uses Team persistence without Agent, Workflow,
+Runtime, or combined-Persistence loading. Another process uses the public Agent
+repositories without loading Team or Workflow implementations. A failure-injection test rejects the
+Team response after writes and verifies rollback across Agent, Team, and content.
+Dependency analysis must not introduce a new nontrivial file cycle.
+
+See [the staged implementation plan](../architecture/persistence-refactoring-plan.md).

data/docs/decisions/034-handoff-runner-coordination-ownership.md

@@ -0,0 +1,76 @@
+# ADR-034: Handoff Runner Coordination Ownership
+
+## Status
+
+Accepted for the H1 step on `refactor/architecture`, 2026-09-18.
+The subsequent Handoff contract and persistence separation is deferred.
+
+## Scope of supersession
+
+This amends the Runner placement/public namespace in
+[030-agent-handoff-domain-and-durable-responsibility](030-agent-handoff-domain-and-durable-responsibility.md)
+and the domain map in
+[031-durable-multi-agent-coordination](031-durable-multi-agent-coordination.md).
+All other durable Handoff semantics remain in force.
+
+## Context
+
+HandoffRunner validates a graph of concrete Agents, selects the active Agent,
+invokes or resumes exact executions, follows multiple transfers, and scopes
+cancellation/result lookup to a specified chain. Those responsibilities span
+Agents. They differ from an individual Agent's execution, Journal and Context.
+
+Calling Handoff from an Agent does not make that whole coordination lifetime an
+Agent implementation detail. Updating the Source and routing state in one
+transaction also does not require them to occupy one module.
+
+The Runner and TeamCoordinator share the Runtime-local AdmissionRegistry. Keeping
+the Runner inside Agent creates an Agent-to-MultiAgent concrete dependency.
+Moving only the Runner aligns ownership without generalizing the registry or
+changing the existing shutdown participant contract.
+
+## Decision
+
+1. Move the public Runner implementation from `agent/handoff_runner.rb` to
+   `multi_agent/handoff_runner.rb` and expose
+   `Phronomy::MultiAgent::HandoffRunner`.
+2. Remove `Phronomy::Agent::HandoffRunner` without a compatibility alias on the
+   refactoring branch. Migrate API documentation, RBS, snapshot and consumers
+   together. See the [migration guide](../migrations/handoff-runner-multi-agent.md).
+3. Retain `Agent::Handoff`, `HandoffPolicy`, Context/Request/State and Agent
+   terminal/persistence integration during H1. Qualify the Runner's dependencies
+   explicitly. This mixed placement is an intermediate state.
+4. Keep AdmissionRegistry in MultiAgent. The admission key, exception classes,
+   successful-call release and Runtime shutdown participation are unchanged.
+5. Preserve method parameters/results, record formats, main-Agent anchor,
+   deterministic Target IDs, transaction boundaries, exact recovery and scoped
+   cancellation. H1 introduces no new execution or shutdown manager.
+
+## Consequences and limits
+
+Agent no longer directly names a MultiAgent implementation in production source.
+The Runner's existing Tracing dependency now belongs to the MultiAgent directory.
+Module-edge totals and large strongly connected components need not decrease:
+this step changes responsibility placement, not the underlying algorithm.
+
+Agent still interprets Handoff/Team coordination metadata. This logical coupling
+is not removed merely because a directory edge disappears.
+
+Later work must separate Request construction, Coordinator selection, Context
+conversion, transaction participation and purge/recovery constraints before
+moving the remaining Handoff-specific types and persistence rules. That work must
+preserve one transaction for Source termination plus responsibility transfer and
+for Target termination plus routing stabilization. It must not promote transferred
+Context into permanent Target Journal/Knowledge or depend on post-commit callbacks
+for coordination correctness.
+
+## Verification obligations
+
+The new public constant must load with Zeitwerk and match its RBS/API snapshot;
+the old constant must not remain as an alias. Existing Handoff, multi-hop,
+cancellation/recovery, shutdown and SQLite reconstruction scenarios must pass.
+API guards must distinguish `MultiAgent::HandoffRunner` from the removed exact
+constant `MultiAgent::Handoff`.
+
+The implementation delivery records test results separately; this ADR does not
+assert that unexecuted live-LLM or database-server tests passed.

data/docs/decisions/035-tool-executor-capability-ownership.md

@@ -0,0 +1,68 @@
+# ADR-035: Default Tool Executor Ownership
+
+## Status
+
+Accepted on the architecture refactoring branch as T1.
+
+This decision assigns the default Tool execution helper to the existing
+Capability implementation. The public Tool facade defined by ADR-015 remains
+the same Class object with the same canonical implementation name.
+
+## Context
+
+`Agent::Context::Capability::Base#call_async` delegates default asynchronous
+dispatch to `Agent::ToolExecutor`. The helper selects inline cooperative work
+or OffloadPool submission and returns a TaskResult. It has no responsibility
+for Agent state, approval, persistence, recovery, or multi-Agent coordination.
+
+Placing this helper directly under Agent makes the Capability directory depend
+on Agent execution while Agent execution also depends on Capability. The
+underlying helper is part of the Tool calling contract and its standard
+implementation, so its ownership should reflect that role.
+
+Moving only the helper to `tool/` would introduce another directory cycle:
+`tool/base.rb` currently aliases `Agent::Context::Capability::Base`. Moving the
+canonical Tool class and changing its runtime name would require a separate
+public compatibility decision.
+
+## Decision
+
+1. Move the helper to
+   `Phronomy::Agent::Context::Capability::ToolExecutor`, in
+   `agent/context/capability/tool_executor.rb`. Classify this helper as private
+   API and remove the old internal constant without a compatibility alias.
+2. Use the new helper from Capability Base and Agent ToolInvocation. Preserve
+   the existing dispatch implementation and error messages.
+3. Keep `Tool::Base` and `Agent::Context::Capability::Base` as the same Class
+   object. Preserve their canonical name, DSL state, method-owner checks, and
+   the public `call_async(args, cancellation_token:, config:)` protocol.
+4. Keep Runtime selection, authorization and logical result ownership in Agent
+   ToolInvocation. Its standard path passes Runtime and `on_full: :raise` to
+   the private helper; custom Tool implementations receive the public protocol.
+   Agent-as-Tool continues through its own asynchronous Agent lifecycle.
+5. Keep the existing TaskResult and OffloadPool mechanisms in Engine. This
+   step adds no execution manager or application registration requirement.
+
+## Consequences and limits
+
+The Capability directory now directly names its existing Engine dependencies
+instead of an Agent-owned wrapper. The code-level algorithm and file-level
+dependency graph are preserved when the moved file is matched to its source.
+Directory placement changes do not imply that all larger dependency cycles
+have been resolved.
+
+Applications should use the public Tool authoring and invocation contracts.
+Code or tests that directly reference the removed private Agent::ToolExecutor
+constant need to follow its new internal name. The public Tool API and durable
+formats require no migration, and the Context contract regrouping remains a
+separate change.
+
+## Verification obligations
+
+Verify cooperative execution, OffloadPool dispatch, cancellation propagation,
+Runtime injection, custom `call_async`, and Agent-as-Tool. Keep the existing
+offload-boundary observations aligned with the moved source path. The public
+API snapshot, RBS and Tool class identity must remain unchanged; Zeitwerk must
+load the new helper and leave the old internal constant absent.
+
+The implementation delivery records its actual test results separately.

data/docs/decisions/036-context-contract-ownership.md

@@ -0,0 +1,86 @@
+# ADR-036: Context Contract Ownership
+
+## Status
+
+Accepted on the architecture refactoring branch as C1.
+
+This decision clarifies the ownership of existing Context contracts. The
+Journal/Manifest authority model in ADR-012 and the Knowledge model in ADR-013
+remain in force. It does not change either model or introduce a new public API.
+
+## Context
+
+`ContextPolicies::Default` depends on `ContextPolicy` and `ContextPolicyInput`.
+Agent execution also consumes these contracts and selects a concrete policy.
+Keeping the contracts beside execution classes directly under `agent/` makes
+the policy directory appear to depend back on Agent execution.
+
+The shared vocabulary is broader than a policy base class. Policy inputs refer
+to the previous `LLMInputManifest`; plans and generated items have common
+validation rules; `before_llm_input` hooks exchange typed input and result
+values. Moving only a base class would leave those shared contracts split
+across responsibility groups.
+
+The Manifest constructs, validates, and converts record values. It does not
+open transactions or write records to a backend. Its representation therefore
+belongs with the Context contracts used by both producers and consumers.
+
+## Decision
+
+1. Move these seven unchanged files into `lib/phronomy/agent/context_contract/`:
+   - `context_policy.rb`
+   - `context_policy_input.rb`
+   - `context_plan.rb`
+   - `context_plan_validator.rb`
+   - `llm_input_manifest.rb`
+   - `llm_input_build_context.rb`
+   - `llm_input_patch.rb`
+2. Collapse the directory with Zeitwerk, following the existing Engine layout
+   mechanism. Keep the existing `Phronomy::Agent::*` definitions and canonical
+   names, including nested input and Manifest value types. Add no aliases or
+   `Phronomy::Agent::ContextContract` namespace.
+3. Keep `ContextPolicies::Default` with the concrete policy implementations.
+   Keep Context assembly, input building, candidate resolution, Runtime
+   integration, hook invocation, and persistence transactions with their
+   existing execution-side owners.
+4. Preserve policy instance binding, the `call(input)` protocol, hook input and
+   result types, and the Manifest version and encoded representation. Add no
+   descriptor, registry, application registration step, or data migration.
+5. Treat the contracts and concrete policies as separate responsibility groups.
+   They may share a horizontal band in a dependency view. Directory nesting and
+   Ruby namespace nesting do not determine architectural dependency direction.
+
+## Consequences and limits
+
+Policies and hooks reference the contract definitions in their shared group,
+while Agent execution composes and consumes them. The contract files have no
+static dependency on Agent execution or MultiAgent implementation classes.
+Their dependencies on immutable values, token estimation, canonical JSON,
+shared errors, and Storage serialization errors remain unchanged.
+
+The source bodies and mapped file-level dependency graph are preserved. A new
+directory group exposes edges previously internal to `agent/`, so aggregate
+directory edge counts and strongly connected component sizes can increase.
+This is not evidence that the existing file-level cycles were resolved.
+
+The contracts still contain Handoff-related categories and metadata vocabulary.
+That semantic coupling belongs to the subsequent Handoff responsibility review.
+The mixed root directory and execution cycles also require separate work.
+
+Applications continue to `require "phronomy"` and use the same documented
+constants. Individual implementation paths that previously lived directly
+under `agent/` have moved; no forwarding files are retained at those paths.
+
+## Verification obligations
+
+Verify ordinary lazy loading and eager loading, canonical constant names,
+independently accessing each contract, custom Policy binding, Plan validation,
+hook input/result handling, Manifest serialization and restoration, Context
+assembly, and existing migration/persistence integration.
+
+Keep the public API snapshot and RBS unchanged. Match each moved file to its
+source when comparing dependencies. Record the removal of direct policy/hook
+references to the execution directory without presenting aggregate graph
+changes as the elimination of all cycles.
+
+The implementation delivery records its test results separately.

data/docs/decisions/037-common-definition-ownership.md

@@ -0,0 +1,62 @@
+# ADR-037: Common Definition Ownership
+
+## Status
+
+Accepted on the architecture refactoring branch.
+
+The initial extraction scope is amended by
+[038-responsibility-based-source-layout](038-responsibility-based-source-layout.md),
+which adds reviewed general definitions and relocates feature-owned definitions.
+The common-ownership rule and public Error contract below remain in force.
+
+## Context
+
+`lib/phronomy.rb` combines the application loading entry point with shared
+exception definitions and global configuration. Internal consumers of the
+base `Phronomy::Error` therefore refer back to the entry point even though
+they do not explicitly require it.
+
+The shared base exception has no dependency on feature implementations. It
+belongs to a common definition group. An `errors/` group would not convey the
+distinction between general definitions and feature-owned exception contracts.
+The same distinction applies to definitions other than exceptions.
+
+## Decision
+
+1. Use `lib/phronomy/common/` for general definitions shared across the
+   framework that do not belong to a particular feature. These definitions
+   must not depend on concrete Agent, Workflow, Runtime, or other feature
+   implementations. Multiple consumers alone do not establish common ownership.
+2. Move only the base `Phronomy::Error < StandardError` definition from the
+   entry point to `common/error.rb`. Name files after their responsibility;
+   do not introduce an unbounded `common/common.rb` collection.
+3. Collapse `common/` with Zeitwerk to retain `Phronomy::Error` as its canonical
+   name. Do not introduce a second class, alias, or `Phronomy::Common` namespace.
+   Ordinary application loading remains `require "phronomy"`.
+4. Keep existing subclass definitions, inheritance, constructors, and rescue
+   behavior unchanged. Inheriting from `Phronomy::Error` does not require a
+   feature-owned exception to live in `common/`.
+5. Keep the common base independent of entry-point loading. Reading its
+   implementation file in isolation must not initialize the full framework.
+   This is an internal architecture check, not a new public partial-loading API.
+
+## Consequences and limits
+
+Internal references to the shared base resolve to its common definition rather
+than to the loading entry point. The application-facing constant and signatures
+remain unchanged. No new explicit require of the application entry point is
+introduced.
+
+Other exceptions still defined in the entry point, global configuration, and
+the mixed root implementation group need separate ownership reviews. This
+single extraction does not establish that all file or directory cycles have
+been eliminated.
+
+## Verification obligations
+
+Verify isolated base-definition loading, ordinary application loading, and eager
+loading. Check ordinary and preloaded-base initialization orders, canonical
+constant identity, representative subclass hierarchies, and catching a domain
+exception with `rescue Phronomy::Error`. Preserve the public API snapshot and
+RBS signatures. Compare dependency targets against the applied baseline and
+report remaining entry-point references separately.

data/docs/decisions/038-responsibility-based-source-layout.md

@@ -0,0 +1,131 @@
+# ADR-038: Responsibility-Based Source Layout
+
+## Status
+
+Accepted on the architecture refactoring branch; configuration/runtime lifecycle
+ownership amended by
+[039-runtime-configuration-lifecycle-ownership](039-runtime-configuration-lifecycle-ownership.md).
+Concrete-default ownership is subsequently amended by
+[040-configuration-default-composition](040-configuration-default-composition.md).
+Agent default selection and one-shot placement are subsequently refined by
+[044-agent-default-and-one-shot-composition](044-agent-default-and-one-shot-composition.md).
+The Workflow recovery prepend requirement is subsequently replaced by direct
+Runner ownership in
+[054-workflow-terminal-save-single-owner](054-workflow-terminal-save-single-owner.md).
+
+Amends the extraction scope of
+[037-common-definition-ownership](037-common-definition-ownership.md).
+Its common-ownership rule and public Error contract remain unchanged.
+
+## Context
+
+The application loading entry point and the direct `lib/phronomy/` directory
+were distinct sources of mixed ownership. After the base Error extraction,
+the entry point still defined twenty feature/shared exceptions and global
+configuration operations. Thirty-nine direct Ruby files still included
+Workflow implementation, execution contracts, recovery, configuration, and
+general values alongside namespace declarations.
+
+A directory's location must describe its responsibility. A public constant
+under `Phronomy` does not require its implementation file to remain directly
+under `lib/phronomy/`. Conversely, a shared consumer list does not make a
+feature contract a general common definition.
+
+## Decision
+
+1. Reserve `lib/phronomy.rb` for application loading and explicit initialization
+   wiring. Production implementation files under `lib/phronomy/` must not require that entry
+   point. Use Zeitwerk for canonical constant loading and precise requires for
+   dependencies and initialization side effects.
+   The existing `testing/persistence_contract.rb` is a separately documented
+   public entry point for external backend authors. It remains allowed to load
+   Phronomy and RSpec, and remains excluded from production automatic loading.
+   This single named exception does not exempt other files under `testing/`.
+2. Allow only these direct Ruby files under `lib/phronomy/`:
+
+   | File | Reason |
+   |---|---|
+   | `version.rb` | Bundler/gem metadata convention and Zeitwerk GemInflector's version-file convention |
+   | `llm_adapter.rb` | Explicit namespace and extension-SPI documentation |
+   | `tool.rb` | Explicit public Tool authoring namespace and documentation |
+   | `vector_store.rb` | Explicit namespace and backend-SPI documentation |
+   | `output_parser.rb` | Explicit parser namespace declaration |
+   | `testing.rb` | Explicit test-support namespace declaration |
+   | `filter.rb` | Existing Filter convenience loading entry, without feature implementation |
+   | `tracing.rb` | Existing Tracing convenience loading entry, without feature implementation |
+
+   Namespace files must not accumulate method bodies or concrete classes.
+   RubyGems does not mandate this entire allowlist. Keeping these small files
+   is an explicit Phronomy design/compatibility choice. New exceptions to the
+   allowlist require an ownership reason and an amendment to this decision.
+3. Extend `common/` with `CanonicalJSON`, `ConfigurationError`, and
+   `Values::Immutable`. Preserve their canonical names, JSON representation,
+   copy/freeze behavior, and exception hierarchy. The three equivalent private
+   Agent copy helpers delegate to `Values::Immutable.copy`; domain-specific
+   command copying and Workflow copying keep their different contracts.
+4. Move the remaining implementation and exception definitions to their owners:
+
+   | Directory | Responsibility |
+   |---|---|
+   | `engine/` | EventLoop/FSM communication, synchronous callback constraints, execution composition, cancellation/deadlines, runtime diagnostics, invocation and runnable execution contracts |
+   | `recovery/` | Shared recovery vocabulary and execution rehydration requirement; no concrete Agent/Workflow orchestration |
+   | `workflow/execution/` | Workflow DSL, context ownership, runner, and terminal persistence recovery |
+   | `agent/api/` | Agent namespace/event loading and lifecycle extension installation |
+   | `agent/composition/` | One-shot Agent/Persistence composition; method definition loaded by the application entry (ADR-044) |
+   | `agent/lifecycle_contract/` | Agent ownership, handoff, and application stream-delivery exceptions |
+   | `configuration/` | Global configuration values, defaults, accessors, replacement, and scoped overrides |
+   | `runtime_composition/` | Application Runtime/configuration lifecycle coordination and concrete default bindings (ADR-039/040/044) |
+   | `llm_contract/` | Token usage, context-budget failures, and LLM call-boundary failures |
+   | `llm_adapter/ruby_llm_patches.rb` | RubyLLM version-guarded compatibility patch |
+   | `persistence/api/` | Public Persistence facade and repository composition |
+   | `generation/` | GeneratorVerifier pipeline and its confidence failure |
+   | `tool/contract/`, `filter/contract/`, `output_parser/contract/` | Feature-owned shared exceptions |
+
+5. Preserve all existing Ruby constant names, class/module kinds, inheritance,
+   constructors, method visibility, public signatures, and persisted formats.
+   Do not add constant aliases or compatibility files at retired implementation
+   paths. Ordinary application loading remains `require "phronomy"`; arbitrary
+   internal file paths are not a new public partial-loading API.
+6. Use existing Zeitwerk `collapse` and `push_dir(namespace: Phronomy)` facilities.
+   The named nested roots are independent of their enclosing namespace. This
+   retains top-level `Phronomy::WorkflowContext` beside existing nested
+   `Phronomy::Workflow::Persistence` without collapsing the entire Workflow
+   namespace. Load `version.rb` first to establish the non-reloadable Phronomy
+   root namespace. Do not depend on facilities introduced after Zeitwerk 2.6.
+7. Preserve explicit lifecycle initialization. Workflow recovery must be
+   prepended during ordinary application loading. Agent event/recovery
+   extensions must be installed when Agent is loaded. Keep external patching
+   and global namespace reopening files outside automatic name inference.
+   Production eager loading must continue to exclude RSpec conformance support.
+
+## Dependency interpretation and limits
+
+`Event` is an Engine communication contract, not a general-purpose common
+value. The `InvalidAsync*` family belongs to synchronous FSM callback rules:
+Engine and Agent use the entry-action failure as well as Workflow. Moving that
+contract into Workflow implementation would introduce the wrong dependency.
+
+`ExecutionRehydrationRequiredError` belongs to recovery even though its name
+starts with Execution. It is not the timeout/cancellation outcome of fan-out
+composition. `ConfigurationError` is common; `Configuration` is not. Default
+configuration still constructs a concrete LLM adapter and tracer. This change
+groups that existing composition but does not make it implementation-neutral.
+
+Directory relocation does not establish that every remaining dependency is
+downward or that all cycles disappear. Preserve and report actual references.
+An analyzer must resolve namespace operations to their defining implementation
+instead of treating the shortest namespace reopening as the owner of every
+method. Do not mistake a loading entry point for the implementation it loads.
+
+## Verification obligations
+
+- Check the direct-root allowlist and forbid internal entry-point requires.
+- Verify normal and eager loading, independent common/exception loading,
+  preloaded common definitions, nested-namespace access orders, and preserved
+  lifecycle extension installation.
+- Exercise the supported Zeitwerk lower bound and the current locked version.
+- Preserve the API snapshot and RBS without regenerating away a difference.
+- Run existing execution, Workflow, Agent, persistence/recovery, integration,
+  configuration, and serialization tests; run the repository style/type gates.
+- Compare dependencies against the applied baseline with the same analyzer.
+  Mark candidate results as unapplied and identify the exact source tree.