phronomy 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 81df7b877b08caffbfdafb9ab1f1c186739a04ef643a14e7b457be805c8b2b9d
-  data.tar.gz: c0fd0ffad64df476c21e0205926df15589c0e654fed9675a6e8aef3589636f1c
+  metadata.gz: fbca82a7a23706719deda2e827af5a9b342c9b388d700929ca9eca19a531a2c9
+  data.tar.gz: b9727e2010acefc14738dbd5b71b5ea06b10f5ebd994a858dfbf1133e15ed003
 SHA512:
-  metadata.gz: cb22a0d7f3edba46a46e9614f4cdad1641941164a641e17c1b3aa24ed07a3d7fb88b408304f1e9c5eaceac02ef8a1fa8503cfb0cffac3ae86b1dd9786756f5ac
-  data.tar.gz: 4be7f67215d0b3b8381508f9ccf062fbfc8f41bb7a8a76299e2642634e78421c8ad5fcc551170db4e739c3db7e1cb8fd69ffad6982f50cdba8375f2237aa5ce9
+  metadata.gz: c33ee2c26a4b6e3d0470f4d95e30b04e9bc228cc87bdd807db1569c707888817f2d904f085822f91e94441e5c21e95ab348f0d7bc56b1ef87c72770ed4976e1d
+  data.tar.gz: 706148e7047ab570ca7d69f735f5767c2a983cf35312a70732723595ea80ed3b5f3efaaddd59d393f5680ec91c36c6ca3e01a70dcb671faa940ae9211df59b5a

data/.mutant.yml

@@ -0,0 +1,21 @@
+---
+# Mutant configuration for Phronomy (opensource project)
+# See: https://github.com/mbj/mutant
+
+usage: opensource
+
+integration: rspec
+
+includes:
+  - lib
+
+requires:
+  - phronomy
+
+subjects:
+  - Phronomy::WorkflowContext
+  - Phronomy::WorkflowRunner
+  - Phronomy::Tool::Base
+  - Phronomy::Context::TokenBudget
+  - Phronomy::Context::TokenEstimator
+  - Phronomy::VectorStore::InMemory

data/CHANGELOG.md

@@ -9,6 +9,344 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **`VectorStore#size` — document count for all backends, contract coverage for RedisSearch and Pgvector** (#240):
+  `VectorStore::Base` gains `#size` as an abstract method; `InMemory`, `RedisSearch`,
+  and `Pgvector` all implement it. `RedisSearch#size` queries `FT.INFO num_docs`;
+  `Pgvector#size` delegates to `model_class.count`. The `a_vector_store` shared example
+  is applied to RedisSearch and Pgvector (nightly real-backend CI); unit specs add a
+  skip-guarded `it_behaves_like` reference and dedicated `#size` unit tests.
+  `empty_store` override hook added to the shared example for real-backend callers.
+
+- **`force_kill: false` default in `dispatch_parallel`, `fan_out`, and `EventLoop#stop`** (#235):
+  Thread#kill is now opt-in. The default `force_kill: false` leaves timed-out workers
+  running and raises `TimeoutError` immediately, avoiding the risk of interrupted
+  `ensure` blocks or corrupted database transactions. Pass `force_kill: true` to
+  restore the previous behaviour (with a `logger.warn` to make it visible).
+  `EventLoop#stop` gains the same keyword and returns `:timeout` instead of
+  `:force_killed` when `force_kill: false` and the thread is still alive.
+
+- **Public API compatibility snapshot spec** (#236):
+  `spec/phronomy/public_api_spec.rb` enumerates expected public methods for every
+  `Stable`-tagged constant. The spec runs as part of the default RSpec suite; any
+  accidental removal or rename of a listed method now fails CI immediately.
+
+- **Nightly real-backend CI split into three independent job groups** (#238):
+  The nightly workflow (`nightly.yml`) now has three separately skippable jobs:
+  `real-backend-redis` (Redis Stack), `real-backend-pgvector` (PostgreSQL + pgvector),
+  and `real-backend-otel` (OpenTelemetry in-process SDK exporter). Each job runs only
+  the relevant spec with `--tag real_backend:<backend>`. The existing `redis_search_spec`
+  and `pgvector_spec` gain the `real_backend:` metadata tag. A new `otel_spec.rb`
+  verifies span emission, attribute attachment, and error recording via
+  `InMemorySpanExporter`.
+
+- **`CancellationToken#raise_if_cancelled!` — convenience cancellation check** (#234):
+  New instance method that raises `Phronomy::CancellationError` when the token is
+  cancelled, or returns `nil` otherwise. Replaces the `if cancelled? then raise`
+  pattern inside tools, RAG loaders, and hooks.
+
+- **Tool cooperative cancellation via `cancellation_token:` keyword** (#234):
+  `Tool::Base#call` now injects `Thread.current[:phronomy_cancellation_token]` as
+  `cancellation_token:` into `execute` when the method declares that keyword. Existing
+  tools without the keyword continue to work unchanged. Tool authors can opt in:
+  `def execute(query:, cancellation_token: nil)`.
+
+- **`CancellationToken.timeout_after` — monotonic-clock deadline** (#225):
+  New `CancellationToken.timeout_after(seconds)` class method creates a token that
+  becomes cancelled after the specified number of seconds, measured with
+  `Process::CLOCK_MONOTONIC` (immune to NTP/DST drift). The existing `deadline:`
+  keyword for wall-clock deadlines remains supported for backward compatibility.
+
+- **`EventLoop#stop` — drain mode and cooperative shutdown** (#233):
+  `EventLoop#stop` now accepts a `drain: true` keyword (default: `false`). When
+  set, the loop waits up to `Phronomy.configuration.event_loop_stop_grace_seconds`
+  (default: 5 s, configurable) for in-flight FSM sessions to complete before
+  joining threads. New sessions submitted while shutdown is pending are rejected
+  immediately with `Phronomy::CancellationError`. A new
+  `event_loop_stop_grace_seconds` configuration attribute is available on
+  `Phronomy::Configuration`.
+
+- **`invoke_timeout` DSL and `Phronomy::TimeoutError`**: Agents can declare a per-invoke
+  timeout in seconds via `invoke_timeout N` in the class body. Exceeding the timeout raises
+  `Phronomy::TimeoutError` (a subclass of `Phronomy::Error`). The default remains unlimited.
+
+- **`dispatch_parallel` / `fan_out` — per-call `timeout:` option** (#133): Both methods now
+  accept `timeout: nil` (default, unlimited) or a positive `Numeric` in seconds. Timed-out
+  tasks are treated the same as errors and follow the existing `on_error:` policy (`:raise`
+  or `:skip`).
+
+- **MCP `HttpTransport` custom authentication headers** (#144): `McpTool.from_server` now
+  accepts `headers: {}`, forwarded all the way to `HttpTransport#initialize`. Arbitrary
+  headers (e.g. `Authorization: Bearer …`) are injected into every JSON-RPC request,
+  enabling use of MCP servers that require bearer tokens or API keys.
+
+- **`StdioTransport` — `env:`, `cwd:`, and `startup_timeout:` options** (#145):
+  Three new keyword arguments are now accepted when constructing a `StdioTransport` (and
+  therefore via `McpTool.from_server`): `env: {}` merges extra variables into the child
+  process environment; `cwd: nil` sets the working directory; `startup_timeout: 5` limits
+  how long to wait for the child process to become ready.
+
+- **Workflow DSL validates graph structure at build time** (#124): `Phronomy::Workflow.define`
+  now raises `ArgumentError` immediately for hard structural errors (no states declared,
+  transitions referencing undefined targets). Unreachable states emit a warning but do not
+  raise. Errors surface at load time rather than at the first `invoke`.
+
+- **Expanded error taxonomy** (#149): Five new subclasses of `Phronomy::Error` are now
+  available: `TransportError` (MCP or LLM network-layer failure; subclasses are
+  `RateLimitError` for HTTP 429 and `AuthenticationError` for HTTP 401/403),
+  `ContextLengthError` (prompt exceeds model context window), and
+  `CancellationError` (explicit invocation cancellation, distinct from the
+  deadline-exceeded `TimeoutError`). All five are defined as subclasses of
+  `Phronomy::Error` so application code can rescue them uniformly.
+
+- **`Agent::Base.static_knowledge_refresh!`** (#164): New class-level method that clears the
+  cached `static_knowledge` chunks so the next `invoke` re-fetches from all registered
+  sources. Essential for long-running processes (web servers, job workers) where knowledge
+  sources may be updated at runtime without a process restart.
+
+- **`Phronomy::Configuration#logger`** (#158): New optional configuration attribute. Any
+  object responding to `#warn` (e.g. `Rails.logger`) can be assigned. Framework diagnostic
+  messages — starting with the unreachable-state warning from `Workflow.define` — are routed
+  through this logger instead of writing directly to `$stderr` via `Kernel#warn`.
+
+- **`Phronomy.with_configuration` and `Phronomy.reset_runtime!`** (#206): Two new class
+  methods for runtime isolation. `with_configuration` yields the current `Configuration`
+  object and restores the original after the block — even on exception — enabling per-request
+  overrides and scoped test configuration. `reset_runtime!` stops any running `EventLoop`,
+  clears its singleton, and resets configuration to defaults; intended for test suites to
+  ensure clean state between examples. `spec_helper.rb` now calls `reset_runtime!` in an
+  `after(:each)` hook automatically.
+
+- **`CancellationToken` — cooperative cancellation for agent invocations** (#216):
+  New class `Phronomy::CancellationToken` enables cooperative cancellation without
+  `Thread#kill`. Tokens are passed via `config: { cancellation_token: token }`.
+  `cancel!` marks the token (thread-safe via Mutex); `cancelled?` returns `true`
+  once cancelled or once an optional `deadline: Time` has passed. Agents check the
+  token in `_invoke_impl` (fail-fast before any LLM call) and again immediately
+  before `chat.ask`. `CancellationError` is never retried by the retry policy.
+  `dispatch_parallel` and `fan_out` accept `cancellation_token:` and automatically
+  inject it into every worker task's config unless the task already supplies its own.
+
+### Changed
+
+- **`CancellationToken` checked at granular checkpoints** (#223):
+  The cancellation token (passed via `config: { cancellation_token: token }`) is
+  now checked at multiple additional points beyond the initial LLM call boundary:
+  before each `KnowledgeSource#fetch` in `build_context` (RAG phase); after each
+  streaming chunk in `_stream_impl`; before each tool-call batch in
+  `ParallelToolChat`; and after each `before_completion` hook. This ensures that
+  long-running retrieval, streaming, and tool-dispatch phases respect cancellation
+  with minimal latency.
+
+- **`Agent::Orchestrator` uses `CancellationToken` for internal stop flag** (#224):
+  The boolean stop flag in `Orchestrator` is replaced with an internal
+  `CancellationToken`. FSM session loops perform cooperative cancellation checks
+  via `cancelled?`; `Thread#kill` is retained only as a last resort after
+  cooperative shutdown.
+
+- **Error taxonomy classes are now raised at the retry boundary** (#204): The classes
+  `Phronomy::RateLimitError`, `Phronomy::AuthenticationError`, `Phronomy::ContextLengthError`,
+  and `Phronomy::TransportError` (introduced in #149) are now actually raised when the
+  corresponding `RubyLLM` exceptions occur. A new internal `ErrorTranslation` concern wraps
+  the retry exhaust path and maps `RubyLLM::*` exceptions to their Phronomy counterparts,
+  preserving the original exception as `#cause`. **Migration**: callers rescuing
+  `RubyLLM::RateLimitError` (or other `RubyLLM::*` errors) directly should migrate to
+  `rescue Phronomy::RateLimitError` / `Phronomy::TransportError` etc.
+
+- **`Orchestrator#bounded_map` uses cooperative cancellation before force-kill** (#203):
+  Workers now check a shared `cancelled` flag at each loop iteration and stop picking up new
+  tasks once the timeout deadline passes. A 0.5 s grace period is given to in-flight workers
+  before `Thread#kill` is used as a last resort. `EventLoop#stop` similarly logs a warning
+  via `Phronomy.configuration.logger` when force-kill is triggered.
+
+- **`Orchestrator#bounded_map` timeout deadline uses monotonic clock** (#209): Replaced
+  `Time.now` deadline arithmetic with `Process.clock_gettime(Process::CLOCK_MONOTONIC)` to
+  avoid sensitivity to NTP adjustments, DST transitions, and system-clock changes that could
+  inflate or deflate effective timeouts.
+
+- **`EventLoop` warns on events for unknown `target_id`**: When the event loop receives an
+  event whose `target_id` does not match any registered session, a warning is emitted instead
+  of silently discarding the event.
+
+- **`VectorStore#search` validates `k` is a positive integer**: All three backends
+  (`InMemory`, `RedisSearch`, `Pgvector`) now raise `ArgumentError` immediately when `k` is
+  not a positive integer, providing a clear error instead of a silent empty result or an
+  obscure database error.
+
+- **`max_parallel_tools` DSL**: Agents can cap the number of concurrent tool-call threads
+  with `max_parallel_tools N` in the class body. Useful for rate-limiting external API calls.
+  The default is **10** (inheriting from `Base`); set explicitly to raise or lower the cap.
+
+- **`max_parallel_tools` and `invoke_timeout` DSL argument validation** (#152): Both setters
+  now raise `ArgumentError` at class-definition time if the supplied value is invalid
+  (`max_parallel_tools` requires an `Integer >= 1`; `invoke_timeout` requires a positive
+  `Numeric`), surfacing configuration mistakes immediately.
+
+- **`on_error :suppress` — canonical alias for `:return_empty`** (#165): `:suppress` is the
+  new preferred name for the error-suppression behaviour in `Tool::Base`. `:return_empty`
+  continues to function but emits a deprecation warning and will be removed in a future major
+  release. Migrate by replacing `on_error :return_empty` with `on_error :suppress`.
+
+- **Tool nested object properties injected into JSON Schema** (#162): `Tool::Base#params_schema`
+  now recursively serialises nested `:object` param specs (including `enum` constraints and
+  further nesting) into the JSON Schema `properties` structure forwarded to the LLM,
+  enabling accurate structured argument generation for complex tool parameters.
+
+### Fixed
+
+- **`EventLoop#start` is now idempotent; stale `:__stop__` sentinel race fixed** (#203):
+  Calling `start` on an already-running `EventLoop` is now a no-op. Fixed a race condition
+  where `stop` setting `@running = false` before the worker thread was scheduled left the
+  `:__stop__` sentinel unconsumed in the queue; a subsequent `start` would then immediately
+  terminate the new thread upon popping the stale sentinel. The sentinel is now treated as a
+  pure unblock signal for `queue.pop` (`next` instead of `break`) — loop termination is
+  driven solely by `@running`.
+
+- **`trace_pii: false` now redacts both input and output**: Previously only the user input
+  was redacted when `trace_pii` was `false`; LLM responses and tool results were still
+  forwarded to the tracing backend unredacted. Both sides are now replaced with `[REDACTED]`.
+
+- **`StdioTransport` — `read_timeout` prevents indefinite blocking**: A configurable
+  `read_timeout` (default 30 s) is now enforced on MCP stdio reads. A silent child process
+  could previously block the calling thread forever.
+
+- **MCP schema `required` and `enum` constraints propagated to `param` DSL**:
+  `McpTool.from_server` now copies `required` and `enum` constraints from the MCP JSON Schema
+  into the generated `param` declarations so downstream validation sees them.
+
+- **`FSMSession` notifies parent when child `AgentFSM` fails**: An unhandled error in a child
+  `AgentFSM` now correctly notifies the parent `FSMSession`, preventing it from waiting
+  indefinitely for a completion event that will never arrive.
+
+- **`WorkflowContext.field` rejects plain `Array` or `Hash` defaults**: Passing a plain `Array`
+  or `Hash` as a field default now raises `ArgumentError` at class-definition time,
+  preventing accidental state sharing across workflow invocations. Other mutable objects
+  are not checked. Wrap collection defaults in a Proc: `default: -> { [] }`.
+
+- **Tool aliases inherited by `Agent` subclasses**: `tool_aliases` declared in a parent
+  `Agent::Base` subclass are now correctly merged into subclasses rather than being silently
+  dropped.
+
+- **`ReactAgent` output selection skips tool-role messages**: The final output selection
+  logic no longer misidentifies `tool`-role messages as the assistant response, fixing
+  spurious tool-call JSON appearing in `result[:output]`.
+
+- **Thread-local context cache cleaned up after each `invoke`** (#128): `Agent::Base#invoke`
+  previously leaked thread-local context cache entries after each call, causing stale cache
+  hits in long-lived threads. The cache is now cleared in an `ensure` block.
+
+- **Unknown tool parameters are rejected** (#130): `Tool::Base#call` now raises
+  `ArgumentError` when keyword arguments not declared via the `param` DSL are passed, instead
+  of forwarding them silently to `execute`.
+
+- **`EventLoop#stop` uses cooperative shutdown instead of `Thread#kill`** (#135):
+  `Thread#kill` bypasses `ensure` blocks and is unsafe. The event loop now sets a sentinel
+  flag and joins the worker thread, allowing it to flush pending events before termination.
+
+- **`Orchestrator` propagates parent `config` and `thread_id` to sub-agents** (#132):
+  Sub-agents spawned via `dispatch` or `dispatch_parallel` now inherit the caller's `config`
+  hash and `thread_id`, enabling correct memory isolation and distributed tracing in
+  multi-agent pipelines.
+
+- **`Agent::Base` caches `static_knowledge` fetch at the class level** (#127): The RAG
+  knowledge fetch was re-executed on every `invoke`. The result is now memoized at the class
+  level (`@static_knowledge_chunks ||= ...`), eliminating redundant vector-store queries.
+  The cache is **not** invalidated automatically when source content changes; call
+  `static_knowledge_refresh!` explicitly to force a reload.
+
+- **`WorkflowContext#initialize` raises on unknown field keys** (#121): Passing an
+  unrecognised key to `WorkflowContext.new` was silently ignored. The constructor now raises
+  `ArgumentError`, surfacing typos and API mismatches immediately.
+
+- **`WorkflowContext#merge` raises `ArgumentError` for unknown field keys** (#154): Passing
+  an unrecognised key to `WorkflowContext#merge` was silently ignored. The method now raises
+  `ArgumentError`, matching the guard added to `#initialize` in #121.
+
+- **`WorkflowContext#deep_dup_value` rescues `TypeError` for non-dupable objects** (#156):
+  Objects that raise `TypeError` from `#dup` (e.g. `Method`, frozen `Proc`, `Integer`,
+  `Symbol`) are now returned as-is instead of crashing.
+
+- **`Workflow.define` raises for undefined `from:` state in transitions** (#157): Transitions
+  that reference a `from:` state not declared in the DSL now raise `ArgumentError` at
+  build time, complementing the existing check for undefined `to:` targets.
+
+- **`Workflow.define` unreachable-state warning routes through configured logger** (#158):
+  The diagnostic warning for unreachable states now uses `Phronomy.configuration.logger`
+  when set, falling back to `Kernel#warn`. Previously the warning always went to `$stderr`.
+
+- **`require "set"` added to `workflow.rb`** (#159): Eliminates an implicit dependency on
+  `Set` being pre-loaded by another gem.
+
+- **`Tool::Base#validate_nested_object` rejects undeclared extra keys** (#166): Keys present
+  in the LLM-supplied hash but absent from the tool's nested `param` schema now produce a
+  validation error rather than being silently forwarded.
+
+- **`WorkflowContext#merge` deep-copies unchanged fields** (#123): Fields absent from the
+  `merge` argument were previously shared by reference with the original context, allowing
+  one branch to mutate another branch's state. All fields are now independently copied.
+
+- **Robust metadata parsing in `VectorStore::Pgvector#search`** (#139): Metadata stored as a
+  PostgreSQL JSON string is now parsed correctly regardless of whether the database driver
+  returns a `String` or an already-decoded `Hash`.
+
+- **`OutputParser::JsonParser` tries all fenced code blocks before falling back** (#146):
+  The parser now scans every fenced block in the LLM response (in order) and returns the
+  first one that parses as valid JSON, rather than only checking the first block. This
+  improves reliability with models that include prose before the JSON block.
+
+- **`on_error: :return_empty` emits a warning and returns a descriptive string** (#147):
+  Errors in tools that declare `on_error :return_empty` are now logged to `warn` before the
+  tool returns. The placeholder string includes the tool name and a brief reason, making
+  silent failures easier to diagnose.
+
+- **`context_version_cache` accessible after `invoke` completes**: The thread-local cache is
+  cleared in `invoke`'s `ensure` block, which caused `context_version_cache` to return `nil`
+  immediately after every call. The value is now persisted in `@last_context_version_cache`
+  so it remains readable post-invoke.
+
+- **`WorkflowContext` field type `:merge` comment corrected**: The inline comment incorrectly
+  described `:merge` as a deep-merge. It performs a shallow merge (`Hash#merge`). The comment
+  has been updated.
+
+- **`WorkflowContext` return value from entry actions now adopted in EventLoop mode** (#107):
+  `FSMSession` previously discarded the `WorkflowContext` returned by entry action callables,
+  causing `s.merge(...)` updates to be silently lost when `event_loop = true`. The context is
+  now correctly propagated, bringing EventLoop semantics in line with the synchronous
+  `WorkflowRunner`. Regression tests added in `spec/phronomy/fsm_session_spec.rb` (unit)
+  and `spec/integration/workflow_spec.rb` (integration, both sync and EventLoop paths).
+
+### Documentation
+
+- **`trace_pii = false` description corrected** (#153): The inline comment and README Note
+  now correctly state that both the input and the output are redacted.
+
+- **`invoke_timeout` is a wait timeout, not cancellation** (#163): YARD comment now
+  explicitly documents that the background agent thread and in-flight LLM/tool calls are
+  **not** interrupted when the timeout fires. Only the caller receives `TimeoutError`.
+
+- **`context_version_cache` thread-safety limitation documented** (#161): A NOTE in the YARD
+  comment explains that the per-instance cache is not thread-safe when the same agent
+  instance is shared across threads.
+
+- **`trace_pii` option documented in README**: The `trace_pii:` configuration key and its
+  behaviour (default `false`, redacts input and output in trace records) is now described in
+  the Configuration section of the README.
+
+- **CJK token under-count warning in `TokenEstimator`**: A note in both the source and README
+  explains that the byte-based heuristic under-counts CJK characters by roughly 3×. Users
+  processing Chinese, Japanese, or Korean content should apply a correction factor or use a
+  model-specific tokenizer.
+
+- **Stability labels, `reset_configuration!` caveat, CI, and gemspec** (#140 / #141 / #142 / #143 / #148 / #150):
+  README stability table revised for several APIs. `Phronomy.reset_configuration!` now carries
+  a warning that it is intended for test isolation only. Gemspec upper bounds added for
+  `ruby_llm` and `pg`. `ruby head` added to the CI test matrix. README API smoke tests added.
+
+---
+
+## [0.6.0] - 2026-05-21
+
 ### Removed
 
 - **`Phronomy::Guardrail::Builtin` module removed**: `PromptInjectionDetector`

data/CONTRIBUTING.md

@@ -0,0 +1,102 @@
+# Contributing to phronomy
+
+Thank you for your interest in contributing!
+
+---
+
+## Development Setup
+
+```bash
+git clone https://github.com/Raizo-TCS/phronomy.git
+cd phronomy
+bundle install
+```
+
+Run the test suite:
+
+```bash
+bundle exec rspec --format documentation
+bundle exec rspec --tag integration
+```
+
+Run the linter:
+
+```bash
+bundle exec standardrb
+```
+
+Check that no Japanese characters appear in source files:
+
+```bash
+ruby scripts/check_japanese.rb
+```
+
+---
+
+## Code Style
+
+- All source files under `lib/` and `spec/` must begin with `# frozen_string_literal: true`.
+- All comments, error messages (`raise`), and YARD documentation inside source files must be in **English**.
+- Follow [Ruby Standard Style](https://github.com/standardrb/standard) (`standardrb`).
+
+---
+
+## Public API Changes
+
+When adding, removing, or renaming a public method or class:
+
+1. Update the stability table in `README.md`.
+2. Add or update `@api private` YARD annotations for internal APIs.
+3. Regenerate the API compatibility snapshot:
+   ```bash
+   bundle exec ruby scripts/api_snapshot.rb --write
+   ```
+
+---
+
+## 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, caching strategy, or public API shape.
+
+---
+
+## Mutation Testing
+
+Phronomy uses [mutant](https://github.com/mbj/mutant) to verify that each test
+actually detects real code changes. Mutation tests are **not** part of the
+required CI gate (they are slow), but run nightly via `.github/workflows/nightly-mutation.yml`.
+
+### Run mutation tests locally
+
+```bash
+# All subjects defined in .mutant.yml
+bash scripts/run_mutation.sh
+
+# Single subject
+bash scripts/run_mutation.sh "Phronomy::WorkflowContext"
+```
+
+### Coverage targets
+
+| Subject | Baseline | Target |
+|---|---|---|
+| `Phronomy::WorkflowContext` | 84.85% | ≥ 80% |
+| `Phronomy::WorkflowRunner` | — | ≥ 80% |
+| `Phronomy::Tool::Base` | 55.74% | ≥ 80% |
+| `Phronomy::Context::TokenBudget` | — | ≥ 80% |
+| `Phronomy::VectorStore::InMemory` | — | ≥ 80% |
+
+When you add or modify tests for a covered subject, run mutation tests to confirm
+the score does not regress.
+
+---
+
+## Releasing
+
+See [RELEASE_CHECKLIST.md](RELEASE_CHECKLIST.md) for the full pre-release quality
+gate and step-by-step release instructions.
+
+**Never run `gem push` directly.** Releases are published via the GitHub Actions
+`release.yml` workflow.