phronomy 0.5.4 → 0.7.0

data/README.md

@@ -1,32 +1,52 @@
 # Phronomy
 
+> **⚠️ Development Notice**
+> This project is primarily developed and maintained by **AI coding agents**.
+> As a result, `main` receives frequent, large, and unannounced changes.
+> External contributors should expect significant churn and potential conflicts at any time.
+> We apologise for the instability this may cause.
+
 **Phronomy** is a Ruby AI agent framework inspired by open-source AI agent frameworks.  
 It provides composable building blocks — Workflows, Agents, Tools, Guardrails, RAG, and Tracing — all powered by [RubyLLM](https://github.com/crmne/ruby_llm) for LLM abstraction.
 
 ## Features
 
-> **Stability labels**: `Stable` — production-ready, semver-protected API.
-> `Beta` — functional but the API may change in a minor release.
-> `Experimental` — subject to breaking changes without notice.
+> **Stability labels** (phronomy is pre-1.0, so `0.x` minor releases may include
+> breaking changes even to `Stable` APIs; patch releases (`0.x.y`) are non-breaking):
+> - `Stable` — API is considered complete and suitable for production use. Breaking changes
+>   within a minor release are avoided, and any breaking changes in a minor bump are noted
+>   in `CHANGELOG.md`.
+> - `Beta` — Functionality is complete and tested, but the API may change in a minor version release (0.x). Use with awareness that signatures or behaviour may evolve.
+> - `Experimental` — Functionality may be incomplete or subject to breaking changes at any time without notice. Not recommended for production use.
+>
+> **Note**: The `main` branch contains unreleased development work. Pin to a released gem
+> version (`gem "phronomy", "~> 0.x"`) for stability in production.
 
 | Feature | Stability |
 |---|---|
 | **Workflow** — Stateful, branching workflows with wait_state/send_event | Stable |
+| **Workflow EventLoop Mode** — Opt-in event-driven execution: `Phronomy.configure { \|c\| c.event_loop = true }` | Experimental |
+| **Agent EventLoop Mode** — `Agent#invoke` (non-blocking via EventLoop), `Agent#run_as_child` (child-FSM pattern for Workflow integration), parallel tool dispatch via `ParallelToolChat` | Experimental |
 | **Workflow Parallel Node** — Concurrent branches via application-level threads | Beta |
 | **Agent** — ReAct-style tool-calling agents with guardrails and conversation history | Stable |
 | **Before-Completion Hook** — Three-tier LLM parameter injection | Stable |
 | **Context Management** — Token budget calculation, estimation, and pruning | Stable |
-| **Knowledge/RAG** — Retrieval sources with pluggable loaders, splitters, and vector stores | Beta |
+| **Knowledge/RAG** — Retrieval sources with pluggable loaders, splitters, and vector stores; `static_knowledge_refresh!` for runtime cache invalidation | Beta |
+| **`VectorStore#size`** — Returns document count for all three backends (InMemory, RedisSearch, Pgvector) | Beta |
 | **Multi-agent** — Agent-as-Tool pattern and hub-and-spoke handoff routing | Beta |
 | **GeneratorVerifier** — Generator-Verifier loop with injectable prompt builders/parsers | Beta |
 | **Agent::Orchestrator** — Parallel subagent dispatch, fan-out, and `subagent` DSL | Beta |
-| **Agent::TeamCoordinator** — Agent teams pattern: LLM coordinator + stateful worker pool with task queue (worker-local message history per run) | Beta |
+| **Agent::TeamCoordinator** — Agent teams pattern: LLM coordinator + stateful workers with sequential task assignment (worker-local message history persisted across tasks) | Beta |
 | **Agent::SharedState** — Shared state pattern: peer agents collaborate via a shared KnowledgeStore; `member` DSL with per-agent instructions and `coordination` team protocol | Experimental |
-| **Guardrails** — Input/output validation; built-in PII and prompt-injection detectors | Beta |
+| **Guardrails** — Input/output validation with custom `InputGuardrail`/`OutputGuardrail` | Beta |
 | **Output Parser** — JSON and Struct-mapped parsers for structured LLM responses | Stable |
 | **Eval Framework** — Dataset-driven evaluation with multiple scorer types | Beta |
 | **Tracing** — Pluggable span-based observability | Stable |
 | **MCP Tool** — Model Context Protocol server integration | Beta |
+| **Error Taxonomy** — `RateLimitError`, `AuthenticationError`, `ContextLengthError`, `TransportError` (subclasses of `Phronomy::Error`) raised at the agent retry boundary | Beta |
+| **`Phronomy.with_configuration` / `Phronomy.reset_runtime!`** — Scoped configuration override and full runtime reset for test isolation | Beta |
+| **CancellationToken** — Cooperative cancellation via `cancel!`/`cancelled?`/`raise_if_cancelled!`; `timeout_after(seconds)` for monotonic-clock deadlines; optional `deadline:` (wall-clock) for backward compatibility; passed as `config: { cancellation_token: token }` to agents and `dispatch_parallel`; injected into `tool.execute` when the method declares a `cancellation_token:` keyword | Experimental |
+| **`dispatch_parallel` / `fan_out` `force_kill:` option** — `force_kill: false` (default) leaves timed-out workers running and raises `TimeoutError` immediately; `force_kill: true` restores the old `Thread#kill` behaviour with a `logger.warn` | Beta |
 
 ## Installation
 
@@ -42,17 +62,42 @@ Then run:
 bundle install
 ```
 
+### RubyLLM setup
+
+Phronomy uses [RubyLLM](https://github.com/crmne/ruby_llm) for LLM access.
+Configure your provider credentials before using agents or chains:
+
+```ruby
+RubyLLM.configure do |c|
+  c.openai_api_key = ENV["OPENAI_API_KEY"]
+  # c.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+end
+```
+
+See the [RubyLLM documentation](https://rubyllm.com) for all supported providers.
+
+### Optional dependencies
+
+Install additional gems only for the features you use:
+
+| Gem | Required for |
+|-----|-------------|
+| `pgvector` | `Phronomy::VectorStore::Pgvector` |
+| `redis` | `Phronomy::VectorStore::RedisSearch` |
+| `opentelemetry-api` | `Phronomy::Tracing::OpenTelemetryTracer` |
+
 ## Quick Start
 
 ### Agent — ReAct tool-calling agent
 
-```ruby
+```ruby runnable
 class WebSearch < Phronomy::Tool::Base
   description "Search the web"
   param :query, type: :string, desc: "Search query"
 
   def execute(query:)
-    # ... call a search API
+    # Replace with a real search API call (e.g., SerpAPI, Tavily)
+    "Mock search result for: #{query}"
   end
 end
 
@@ -69,7 +114,7 @@ puts result[:output]
 
 ### Workflow — Stateful workflow with wait_state/send_event
 
-```ruby
+```ruby runnable
 class ReviewContext
   include Phronomy::WorkflowContext
   field :draft,    type: :replace
@@ -77,17 +122,21 @@ class ReviewContext
   field :approved, type: :replace, default: false
 end
 
+# Placeholder callables representing your own implementation
+write_draft  = ->(state) { state.merge(draft:    "Draft content here") }
+review_draft = ->(state) { state.merge(feedback: "Feedback on: #{state.draft}") }
+
 app = Phronomy::Workflow.define(ReviewContext) do
   initial :write
-  state     :write,    action: ->(s) { s.merge(draft: Writer.call(s)) }
-  state     :review,   action: ->(s) { s.merge(feedback: Reviewer.call(s.draft)) }
+  state     :write,    action: write_draft
+  state     :review,   action: review_draft
   wait_state :awaiting_approval           # halts here for human decision
   state     :finalize, action: ->(s) { s.merge(approved: true) }
-  after :write,    to: :review
-  after :review,   to: :awaiting_approval
-  after :finalize, to: :__finish__
-  event :approve, from: :awaiting_approval, to: :finalize
-  event :reject,  from: :awaiting_approval, to: :write
+  transition from: :write,              to: :review
+  transition from: :review,             to: :awaiting_approval
+  transition from: :finalize,           to: :__finish__
+  transition from: :awaiting_approval,  on: :approve, to: :finalize
+  transition from: :awaiting_approval,  on: :reject,  to: :write
 end
 
 # First run — halts at :awaiting_approval
@@ -100,6 +149,19 @@ final = app.send_event(state: state, event: :approve)
 puts "Approved: #{final.approved}"  # => true
 ```
 
+In EventLoop mode (`c.event_loop = true`), `Agent#run_as_child` spawns a child agent
+asynchronously. When the child succeeds, `:child_completed` is dispatched; when it fails,
+`:child_failed` is dispatched. Always declare both transitions to avoid a stuck workflow:
+
+```ruby
+# EventLoop mode: workflow that runs an agent as a child FSM
+entry :run_agent, ->(ctx) {
+  MyAgent.new.run_as_child(ctx.query, ctx: ctx) { |r| ctx.answer = r[:output] }
+}
+transition from: :run_agent, on: :child_completed, to: :done
+transition from: :run_agent, on: :child_failed,    to: :handle_error
+```
+
 ### Multi-Agent — Agent-as-Tool pattern
 
 Wrap sub-agents as `Tool::Base` subclasses so the orchestrator LLM can call them on demand.
@@ -114,6 +176,11 @@ class ResearchTool < Phronomy::Tool::Base
   end
 end
 
+class WriterAgent < Phronomy::Agent::Base
+  model "gpt-4o"
+  instructions "You are a professional technical writer."
+end
+
 class WriteTool < Phronomy::Tool::Base
   description "Write a technical blog post given research notes and a writing brief."
   param :instructions, type: :string, desc: "Writing brief including research notes"
@@ -135,6 +202,9 @@ puts result[:output]
 
 ### Guardrails — Input/output validation
 
+Call `fail!(reason)` inside `check` to reject — it raises `Phronomy::GuardrailError`.
+When a guardrail rejects, `invoke` raises instead of returning an output.
+
 ```ruby
 class NoSensitiveDataGuardrail < Phronomy::Guardrail::InputGuardrail
   def check(input)
@@ -144,18 +214,19 @@ end
 
 agent = ResearchAgent.new
 agent.add_input_guardrail(NoSensitiveDataGuardrail.new)
-```
-
-### Built-in Guardrails — PII and prompt injection detection
-
-```ruby
-# Detect SSNs, credit cards, emails, and phone numbers
-agent.add_input_guardrail(Phronomy::Guardrail::Builtin::PIIPatternDetector.new)
 
-# Block common prompt-injection attempts
-agent.add_input_guardrail(Phronomy::Guardrail::Builtin::PromptInjectionDetector.new)
+begin
+  agent.invoke("Charge 4111-1111-1111-1111")
+rescue Phronomy::GuardrailError => e
+  puts e.message   # => "Credit card numbers are not allowed"
+end
 ```
 
+> **Limitations:** Phronomy ships no built-in guardrail implementations. There is no
+> built-in prompt injection detector, PII scanner, or content classifier. All guardrail
+> logic must be implemented by the application. Reference implementations for common
+> patterns are available in `phronomy-examples` (example 06).
+
 ### Knowledge/RAG — Context injection and vector retrieval
 
 ```ruby
@@ -169,6 +240,13 @@ policy = Phronomy::KnowledgeSource::StaticKnowledge.new(
 # RAG retrieval from a vector store
 store      = Phronomy::VectorStore::InMemory.new
 embeddings = Phronomy::Embeddings::RubyLLMEmbeddings.new(model: "text-embedding-3-small")
+
+# Add documents before querying
+text1 = "Refunds are processed within 5 business days."
+text2 = "Contact support@example.com for refund requests."
+store.add(id: "doc-1", embedding: embeddings.embed(text1), metadata: { content: text1, source: "policy.md" })
+store.add(id: "doc-2", embedding: embeddings.embed(text2), metadata: { content: text2, source: "policy.md" })
+
 rag = Phronomy::KnowledgeSource::RAGKnowledge.new(store: store, embeddings: embeddings, k: 5)
 
 # Inject at invocation time
@@ -176,6 +254,15 @@ result = MyAgent.new.invoke("What is the refund policy?",
   config: { knowledge_sources: [policy, rag] })
 ```
 
+`static_knowledge_refresh!` invalidates the class-level cache of *static* knowledge sources
+(not RAG stores). Call it when the underlying file or content has changed:
+
+```ruby
+# Static knowledge sources are cached at the class level after the first fetch.
+# Call refresh! when the underlying content changes (e.g. after reloading policy.md).
+MyAgent.static_knowledge_refresh!
+```
+
 Load and split documents with built-in loaders:
 
 ```ruby
@@ -219,7 +306,7 @@ Phronomy.configure do |c|
 end
 ```
 
-Hooks are called in order — global → class → instance — and deep-merged.
+Hooks are called in order — global → class → instance — and shallow-merged (`Hash#merge`; last hook wins on key conflicts).
 
 ### GeneratorVerifier — Generator-Verifier loop with custom prompt builders
 
@@ -271,10 +358,11 @@ end
 
 ### Agent::Orchestrator — Parallel subagent dispatch
 
-> **Note:** `dispatch_parallel` and `fan_out` use plain Ruby threads and are
-> intended for small-scale fan-out (a handful of subagents). For large-scale
-> parallel dispatch, manage concurrency (thread pools, rate limiting) at the
-> application level.
+> **Note:** `dispatch_parallel` and `fan_out` use plain Ruby threads. Use
+> `max_concurrency:` to cap the number of concurrent workers and `on_error:`
+> to control failure handling (`:raise` re-raises the first error after all
+> tasks complete; `:skip` fills failed slots with `nil`). For very large
+> fan-outs consider additional rate-limiting at the application level.
 
 ```ruby
 class ResearchOrchestrator < Phronomy::Agent::Orchestrator
@@ -297,16 +385,24 @@ class MyOrchestrator < Phronomy::Agent::Orchestrator
   instructions "Orchestrate."
 
   def run(query)
-    # Heterogeneous agents in parallel
+    # Heterogeneous agents in parallel (cap at 4 threads; skip failures; 30 s timeout)
     results = dispatch_parallel(
       {agent: SearchAgent,   input: "topic A"},
-      {agent: AnalysisAgent, input: query}
+      {agent: AnalysisAgent, input: query},
+      max_concurrency: 4,
+      on_error: :skip,
+      timeout: 30
     )
 
     # Fan-out — same agent, multiple inputs
-    translations = fan_out(agent: TranslationAgent, inputs: %w[Hello World])
+    translations = fan_out(
+      agent: TranslationAgent,
+      inputs: %w[Hello World],
+      max_concurrency: 2,
+      timeout: 20
+    )
 
-    results.map { |r| r[:output] }.join("\n")
+    results.compact.map { |r| r[:output] }.join("\n")
   end
 end
 ```
@@ -325,15 +421,18 @@ end
 app = Phronomy::Workflow.define(EnrichContext) do
   initial :enrich
   state :enrich, action: ->(s) do
-    results = {}
-    threads = [
-      Thread.new { results[:summary] = Summarizer.call(s) },
-      Thread.new { results[:tags]    = Tagger.call(s) }
-    ]
-    threads.each { |t| t.join(10) }  # 10-second timeout
-    s.merge(summary: results[:summary], tags: Array(results[:tags]))
+    # Use Thread#value to collect results safely — avoids concurrent Hash writes
+    threads = {
+      summary: Thread.new { Summarizer.call(s) },
+      tags:    Thread.new { Tagger.call(s) }
+    }
+    # For production use, wrap with Timeout.timeout to avoid unbounded waits:
+    #   require "timeout"
+    #   Timeout.timeout(30) { threads.each_value(&:join) }
+    threads.each_value(&:join)
+    s.merge(summary: threads[:summary].value, tags: Array(threads[:tags].value))
   end
-  after :enrich, to: :__finish__
+  transition from: :enrich, to: :__finish__
 end
 
 state = app.invoke({}, config: { thread_id: "t1" })
@@ -420,22 +519,38 @@ puts result2[:output]   # => "Your name is Alice."
 `result[:messages]` contains the complete message history after each invocation.
 Persist it however suits your application (in-memory hash, Redis, ActiveRecord, etc.).
 
+> **Note on `thread_id`**: `thread_id` is a correlation identifier used internally for
+> checkpoint/compaction context and EventLoop routing. It does **not** automatically persist or
+> restore conversation history — you must pass `messages:` explicitly on each turn as shown above.
+
 
 ## Configuration
 
 ```ruby
 Phronomy.configure do |c|
-  c.default_model       = "gpt-4o-mini"
-  c.recursion_limit     = 25
-  c.tracer              = Phronomy::Tracing::NullTracer.new
-  c.before_completion   = nil   # optional; global hook lambda
+  c.default_model                   = "gpt-4o-mini"
+  c.recursion_limit                 = 25
+  c.tracer                          = Phronomy::Tracing::NullTracer.new
+  c.before_completion               = nil   # optional; global hook lambda
+  c.trace_pii                       = false # default; set to true only when trace data contains no PII
+  c.logger                          = nil   # optional; any object responding to #warn (e.g. Rails.logger)
+  c.event_loop_stop_grace_seconds   = 5     # seconds to wait for sessions to drain on EventLoop#stop(drain: true)
 end
 ```
 
+`c.logger` receives framework diagnostic messages (e.g. unreachable-state warnings from
+`Workflow.define`). When `nil` (default), messages are written to `$stderr` via `Kernel#warn`.
+
+> **Note**: When `trace_pii = false`, both the _input_ and the _output_ (LLM
+> responses and tool results) are replaced with `[REDACTED]` in trace spans.
+> The default is `false` (PII protection enabled). Set to `true` only when
+> trace data does not contain sensitive information.
+
 ## Context Management
 
-Phronomy includes a context window management layer so agents automatically
-stay within the token limits of the underlying model.
+Phronomy includes a context window management layer. When model metadata is
+available (either from the built-in registry or via an explicit `context_window:` setting),
+agents automatically stay within the configured token limit.
 
 ### TokenBudget
 
@@ -467,12 +582,82 @@ class MyAgent < Phronomy::Agent::Base
   model "gpt-4o"
   max_output_tokens 4096   # override max_output_tokens from registry
   context_overhead  600    # extra reservation for system prompt + tools
+  invoke_timeout    30     # raise Phronomy::TimeoutError after 30 s (wait timeout, not cancellation)
+  max_parallel_tools 4     # cap concurrent tool-call threads (default: 10)
 end
 ```
 
 `Agent::Base#invoke` builds a `TokenBudget` automatically. When the model is not in the
 registry the budget is silently skipped.
 
+> **Note on CJK languages**: The default `TokenEstimator` uses a character-ratio heuristic
+> calibrated for ASCII/Latin text (4 chars/token). For Chinese, Japanese, and Korean text,
+> actual token counts are approximately **4× higher** than the estimate because CJK
+> characters are typically 1 token each. For accurate CJK token counting, supply a
+> tokenizer-backed callable:
+>
+> ```ruby
+> require "tiktoken_ruby"
+> enc = Tiktoken.encoding_for_model("gpt-4o")
+> Phronomy::Context::TokenEstimator.tokenizer = ->(text) { enc.encode(text).length }
+> ```
+
+
+### CancellationToken — Cooperative cancellation
+
+Pass a `CancellationToken` to any agent via `config: { cancellation_token: token }`.
+Cancellation is checked at multiple granular checkpoints: before the LLM call, before
+each RAG knowledge-source fetch, after each streaming chunk, before each parallel
+tool-call batch, and after each `before_completion` hook. `CancellationError` is
+raised immediately and is never retried. No threads are force-killed — `ensure`
+blocks always execute.
+
+> **Cooperative cancellation — not preemptive**
+>
+> Phronomy uses _cooperative boundary cancellation_. The token is polled at the
+> checkpoints listed above; it is **not** injected as a signal into a running
+> operation. This means the following are **not** interrupted mid-execution:
+>
+> - A single `KnowledgeSource#fetch` that is already blocking (e.g. HTTP call)
+> - A single `chat.ask` call that is not streaming
+> - A single `tool.execute` call that is already running
+> - Any external I/O (database query, vector search, HTTP request) inside those calls
+>
+> For deep in-flight safety, complement `CancellationToken` with per-source or
+> per-tool timeouts (e.g. `Net::HTTP#read_timeout`, `Timeout.timeout`, connection
+> pool limits). Ruby's GVL prevents fully preemptive cancellation without
+> `Thread#kill`, which Phronomy avoids by default due to resource safety concerns.
+
+```ruby
+token = Phronomy::CancellationToken.new
+
+# Cancel from another thread after 5 s
+Thread.new { sleep 5; token.cancel! }
+
+begin
+  result = MyAgent.new.invoke("...", config: { cancellation_token: token })
+rescue Phronomy::CancellationError
+  puts "cancelled"
+end
+
+# Hard deadline via monotonic clock (recommended — immune to NTP/DST changes)
+token = Phronomy::CancellationToken.timeout_after(30)
+result = MyAgent.new.invoke("...", config: { cancellation_token: token })
+
+# Hard deadline via wall-clock (legacy — still supported)
+token = Phronomy::CancellationToken.new(deadline: Time.now + 30)
+result = MyAgent.new.invoke("...", config: { cancellation_token: token })
+
+# Propagate to all parallel workers via dispatch_parallel / fan_out
+token = Phronomy::CancellationToken.new
+Thread.new { sleep 10; token.cancel! }
+
+orchestrator.dispatch_parallel(
+  {agent: SearchAgent,   input: "topic A"},
+  {agent: AnalysisAgent, input: "topic B"},
+  cancellation_token: token
+)
+```
 
 ## Examples
 
@@ -543,6 +728,35 @@ bin/console
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/Raizo-TCS/phronomy.
 
+## Security & Privacy
+
+**API credentials** — Phronomy does not store or transmit your LLM API keys. All
+credentials are handled by RubyLLM and passed directly to the provider.
+
+**Tracing and PII** — When tracing is enabled (`Phronomy::Tracing::OpenTelemetryTracer`
+or a custom tracer), agent inputs and LLM outputs are replaced with `[REDACTED]` in
+span attributes by default (`trace_pii: false`). To include full content in traces
+(e.g., for debugging in a non-production environment), set `trace_pii: true` in your
+Phronomy configuration. Evaluate whether your tracing backend (OTLP collector, Jaeger,
+Honeycomb, etc.) meets your data-retention and privacy requirements.
+
+**Prompt injection** — Phronomy provides no built-in prompt injection detection.
+Applications that process untrusted user input should implement their own input
+guardrails (see the Guardrails section above).
+
+**Tool and MCP security** — Tools can perform real-world side effects (database
+writes, API calls, file deletion). Treat tool execution as a privileged operation:
+use the interrupt/approval mechanism for high-risk tools (e.g., payment processing,
+file deletion) rather than allowing fully autonomous execution. MCP servers are
+external trust boundaries: connect only to servers you control. A compromised MCP
+server can inject instructions that manipulate agent behavior (tool-level prompt
+injection). Avoid passing secrets as direct tool parameters — if `trace_pii: true`
+is set, tool arguments are captured in trace spans.
+
+**Vulnerability reports** — Please report security vulnerabilities privately via
+GitHub's [Security Advisories](https://github.com/Raizo-TCS/phronomy/security/advisories)
+rather than opening a public issue.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/RELEASE_CHECKLIST.md

@@ -0,0 +1,86 @@
+# Release Checklist
+
+Use this checklist before every release of the `phronomy` gem.
+Copy it into the GitHub Release draft and check off each item.
+
+---
+
+## Pre-release
+
+- [ ] `CHANGELOG.md` updated (Added / Changed / Fixed / Removed / Deprecated / Security)
+- [ ] Version bumped in `lib/phronomy/version.rb`
+- [ ] Stability table in `README.md` reflects any API additions, removals, or promotions
+- [ ] `@api private` annotations are consistent with the README stability table (Issue #205)
+- [ ] Public API compatibility snapshot regenerated if any Stable API changed:
+  ```bash
+  bundle exec ruby scripts/api_snapshot.rb --write
+  ```
+  (Issue #210)
+- [ ] Migration notes or deprecation warnings added for any breaking changes
+
+---
+
+## Quality Gates (all must pass before tagging)
+
+- [ ] `bundle exec rspec --format documentation` — 0 failures
+- [ ] `bundle exec rspec --tag integration` — 0 failures, all expected pending
+- [ ] `ruby scripts/check_japanese.rb` — exit 0 (no Japanese in source)
+- [ ] `bundle exec standardrb` — 0 offenses
+- [ ] `COVERAGE=1 bundle exec rspec` — coverage above configured threshold (Issue #207)
+- [ ] CI green on all Ruby matrix versions (3.2 / 3.3 / 3.4 / head)
+
+---
+
+## Security Review
+
+- [ ] `SECURITY.md` is up to date (supported versions table, contact info)
+- [ ] No new `trace_pii`-sensitive data paths introduced without redaction
+- [ ] No new `requires_approval` tools missing the approval gate
+- [ ] No secrets, credentials, or PII in tool descriptions, schema strings, or spec fixtures
+- [ ] Dependency audit passes: `bundle exec bundler-audit check --update`
+
+---
+
+## Release Steps
+
+> **Do not use `gem push` directly.** The GitHub Actions release workflow handles
+> gem publication. Follow the steps below exactly.
+
+1. Commit the version bump:
+   ```bash
+   git commit -m "bump version to X.Y.Z"
+   git push origin main
+   ```
+2. Create and push the tag:
+   ```bash
+   git tag vX.Y.Z
+   git push origin vX.Y.Z
+   ```
+3. Trigger the release workflow:
+   ```bash
+   gh workflow run release.yml --field tag=vX.Y.Z
+   ```
+4. Monitor the workflow run:
+   ```bash
+   gh run list --workflow release.yml --limit 3
+   ```
+5. Verify the gem appears on RubyGems: `gem search phronomy`
+
+---
+
+## Post-release
+
+- [ ] `phronomy-examples` `Gemfile` updated to the new version
+  ```bash
+  cd ../phronomy-examples && bundle update phronomy
+  ```
+- [ ] `phronomy-examples` tests pass after the update
+- [ ] GitHub Release description includes the relevant CHANGELOG excerpt
+
+---
+
+## Reference Issues
+
+- #205 — `@api private` annotation policy
+- #207 — SimpleCov coverage gate
+- #210 — Public API compatibility snapshot

data/SECURITY.md

@@ -0,0 +1,80 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| Latest release (main branch) | ✅ |
+| Older versions | ❌ — please upgrade |
+
+Only the latest released version of `phronomy` receives security patches. If you
+are running an older version, please upgrade before filing a report.
+
+---
+
+## Reporting a Vulnerability
+
+**Please do NOT open a public GitHub Issue for security vulnerabilities.**
+
+Use [GitHub's private vulnerability reporting](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing/privately-reporting-a-security-vulnerability)
+instead:
+
+1. Navigate to the [Security tab](https://github.com/Raizo-TCS/phronomy/security)
+   of this repository.
+2. Click **"Report a vulnerability"**.
+3. Fill in the advisory form with as much detail as possible.
+
+This creates a private draft advisory visible only to maintainers, keeping the
+details confidential until a fix is prepared and released.
+
+---
+
+## Response Timeline
+
+| Milestone | Target |
+|-----------|--------|
+| Acknowledgement of report | Within **7 days** |
+| Triage and initial assessment | Within **14 days** |
+| Patch release (critical / high severity) | Within **30 days** |
+| Patch release (medium / low severity) | Best effort; typically within **60 days** |
+
+If you do not receive an acknowledgement within 7 days, please follow up by
+opening a **public** Issue with the subject "Security report follow-up (no
+response)" — do **not** include vulnerability details in the public Issue.
+
+---
+
+## Scope
+
+**In scope:**
+
+- Vulnerabilities in the `phronomy` gem source code (`lib/`, `spec/`).
+- Dependency vulnerabilities that affect gem consumers when `phronomy` is used as intended.
+- Information disclosure via tracing/logging APIs (e.g. `trace_pii: false` bypass).
+- Approval gate bypasses (tool execution without the registered approval handler).
+
+**Out of scope:**
+
+- Security of consumer applications built on top of `phronomy`.
+- Vulnerabilities in the LLM provider (OpenAI, Anthropic, etc.) or in `ruby_llm`.
+- Attacks that require an attacker to already have write access to the host system.
+- Prompt injection via LLM output — the gem forwards LLM output faithfully; prompt
+  injection resistance is the responsibility of the LLM provider and the application.
+
+---
+
+## Disclosure Policy
+
+- Maintainers will coordinate with you on the release date and credit you in the
+  `CHANGELOG.md` entry and GitHub release notes.
+- If you wish to remain anonymous, let us know in the advisory.
+- We follow a **coordinated disclosure** model: the advisory will be made public
+  after a patch is released (or after 90 days, whichever comes first).
+
+---
+
+## Credit
+
+Security reporters are credited in the `CHANGELOG.md` entry for the patch release,
+in the GitHub Security Advisory, and in the release notes — unless they request
+anonymity.

data/benchmark/baseline.json

@@ -0,0 +1,9 @@
+{
+  "workflow_context_merge": 124364.81010472385,
+  "workflow_define": 2179.945274115319,
+  "tool_params_schema_definition": 19534379.159046534,
+  "dispatch_parallel_10": 1483.2255243486482,
+  "cancellation_token_cancelled": 4335060.97443425,
+  "cancellation_token_raise_if_cancelled_noop": 3566903.189098373,
+  "trim_context_remove_2000": 1761.5700678986254
+}