woods 2.0.0.beta2 → 2.0.0.beta3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afd0e7789aeee449784af8f4a3b49eb2dfae7bb522381a78dba2e1932c41057c
-  data.tar.gz: a1c7c26400a59fae7cce074e086c0928e2267399dba6cedef7c6f5e49697ed46
+  metadata.gz: f1877858142850cdb2a9802c103198cf5be63439e610ebbc43cd10f97554f10d
+  data.tar.gz: 5bad5ce4acdb04312a53d31414ea0b93b3cb4d7c103209f3172bb84e509278c3
 SHA512:
-  metadata.gz: d3f87143d3a9283f9ad53d6d8fb08c61929e162513c1b5ca55452c24b52f2e804d1ad9e664d754b664b6e76b312f0fd3b1afbe957b7f00d8701f8238ac4976fa
-  data.tar.gz: bece3ff52a93f3298ee3792769c61ae75b4d8913a5ea5ce92c1564a5d3c612f8073b15357fe0e9b25d81e983dcdaea0c7030dda5375df958a3d57805b0fd5457
+  metadata.gz: d878e5d2d4f51dcb4fcf4e39af29e78edf23eae756d0db4f2fe3b4c6e77454295d7a6f455d4d1f3aa397d70fb51253be040ca3ec29e17e32bd5d854dd4b434e4
+  data.tar.gz: 37a249bb634be55999c9d6ae1f058cd72a80be48496fc04b93d9d4213fa1355f1c7ff8d2d21abeeabaa8f88846846110a82547572ce74bce90dbb75d18133a0a

data/CHANGELOG.md

@@ -7,6 +7,265 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.0.beta3] - 2026-09-18
+
+### Added
+
+- Optional `changelog/<type>_<slug>.md` entry files let parallel branches record changes without editing the same Unreleased block. `release:prepare` validates, folds, and removes consumed entries; release validation refuses leftover entries at the tagged SHA (B-179).
+- Add optional `volatile_dependency_limit_per_target` to keep one hot dependency
+  from filling the volatility report (B-188). Apply the per-target edge cap before
+  the global top 20, preserve the default output, and expose the configured cap
+  and reported count alongside the full qualifying count when enabled.
+
+- Gate retrieval quality in CI with a versioned Canopy runtime corpus, captured
+  real MiniLM vectors, per-strategy quality floors, latency observations, and
+  exact output-token counts. Preserve known failed queries in the evidence (#227).
+- Bound `dependencies` and `dependents` traversal work independently of response
+  pagination, with configurable node/edge budgets and explicit partial-result
+  reasons. Filtered edges and reverse relationship checks consume the edge
+  budget; complete small results retain their existing shape (#311).
+
+- Document the published filesystem layout for non-Ruby consumers, with pinned
+  Bash/jq and Python reads, retention-race handling, and structural snapshot
+  publication guidance (#306).
+
+- `WOODS_WATCH_TRUST_FOREIGN_HOST=1` lets watch status, incremental/clean guards,
+  daemon startup checks, and MCP trust fresh foreign-container heartbeats without
+  checking an unrelated local pid. This is opt-in; foreign records expire after
+  15 minutes, and malformed or excessively future timestamps are rejected (#321).
+
+- `WOODS_WATCH_POLL_INTERVAL` configures positive, finite seconds between watch
+  polling scans, including fallback from native watching (default 1.0; #322).
+
+- Published manifests record `woods_version`, the last publisher's gem version,
+  for Rails extraction and static self-maps. MCP exposes it independently of the
+  reader version, and `woods:validate` gives nonfatal warnings for malformed
+  writer versions or different major versions. Older manifests remain valid
+  without this optional provenance field (#323).
+- Supply concise, capability-aware Index MCP instructions through initialization and modern discovery, with status-first retrieval guidance, bounded traversal and source verification. Preserve the SDK's omission for protocol `2024-11-05`; tool registration and authorization remain unchanged. (#402)
+- Added generation-bound source-input evidence with bounded `current` / `drifted` / `unknown` status, per-consumer incremental provenance, private keyed content identities, and a fresh-process `woods-extract` launcher. The opt-in session hook now checks source content through the shared no-environment status task. Old indexes and unproved boot/runtime consumption remain explicitly unknown.
+Add separately opt-in, bounded Claude orientation and post-edit candidate context from a retained published generation, with explicit uncertainty, repeat suppression, independent refresh controls, and an installed `woods-hook-context` helper.
+Explicit Claude and OpenCode edit adapters preserve every affected patch path,
+including both rename sides, through the shared durable refresh queue. Native
+OpenCode registration is optional and version-pinned; unsupported or escaping
+events produce diagnostics without claiming refresh.
+MCP `search` now reports whether its returned matches exhaust the requested domain, prove an additional match, or leave the remainder unknown after a scan budget or regex timeout. Bounded lookahead shares the existing scan budget, deep reads preserve typed identities, and detected artifact corruption remains an error. JSON and text formats distinguish returned counts from exact totals; agent guidance explains how to narrow partial searches. Mixed Rails/gem source directories remain searchable and loadable by lexical retrieval while rejecting unrelated type mismatches.
+`woods:validate` now checks semantic graph invariants against typed unit indexes and artifacts within one pinned published generation. It detects broken reverse membership, invalid sources, duplicate typed variants, file/type index drift, and missing indexed nodes while accepting cycles, unresolved targets, legacy string edges, and the Woods static source map. Validation remains read-only, preserves existing report/exit behavior, and reports actionable identities without repairing the graph.
+
+The validator, deep search, and lexical retrieval accept all four GraphQL unit types in the shared `graphql/` directory, preserving actual typed identities and existing directory-family search labels.
+`dependencies` and `dependents` accept optional `explain: true` to retain typed source ownership, original edge direction and relationship attributes, and bounded shortest witnesses. Explanations distinguish direct records from transitive reachability, preserve unknown labels and ambiguous target candidates, and retain ancestor context across pages. Existing compact responses remain unchanged; explanation work shares traversal budgets.
+Publish additive `reverse_via` target buckets with typed source identities, relationship labels and association attributes, preserving existing `reverse` arrays and legacy graph loading.
+- Mark whole-file caching, configuration, test mapping, Rails source, and gem source graph nodes and typed variants with `kind: "file_profile"`, preserving file membership and identifiers while letting consumers distinguish profiles from constant-owned units (#417).
+Add `woods-agent-config` for explicit Claude Code project/user setup, update, and removal. Preview saves one private edit plan; apply checks its original snapshots, preserves unrelated configuration, tracks owned entries and instruction sections, and supports recovery after interrupted writes. Host/Compose preflight checks the installed Index Server and published index.
+- Add opt-in compact source evidence and declared API outlines to retrieval and lookup, with complete published spans, explicit omissions, honest generation/source provenance, and typed SHA-guarded full-source follow-up. Existing full-source behavior remains the default.
+- Add explicit embedding-free lexical retrieval over published extraction units. Set `WOODS_RETRIEVAL_MODE=lexical` for Index MCP or `config.retrieval_mode = :lexical` for Ruby builders; field-aware ranked results preserve typed identity, generation consistency and budgeted matching evidence without provider or vector access. Semantic retrieval remains the default.
+- Add explicit package and application-relative source-path scopes to ranked retrieval and discovery, with eligibility before candidate limits, typed scope metadata, and native scoped vector searches without re-embedding.
+
+### Fixed
+
+- Reflect model callbacks from Rails' per-event chains instead of nonexistent
+  per-kind readers; include `before_commit` and keep `callback_count` equal to
+  the emitted callback list. Preserve framework callbacks with stable Proc/lambda
+  source-site labels and address-free default callback-object descriptions in
+  metadata and chunks, including Rails 6's `raw_filter`, so separate-process
+  extractions of unchanged models remain equivalent. Preserve custom object labels.
+
+- Explain the Zeitwerk 2.6.9 naming requirement in identifier-collision errors
+  and upgrade guidance before suggesting changes to valid namespace wrappers
+  on older-loader or classic-mode hosts (B-149).
+
+- Stabilize controller inline callback and condition labels across processes and
+  checkout paths, including action chunks; retain `unless` conditions in the
+  generated filter-chain header (B-167).
+
+- Publish metadata-only changes in local embedding snapshots without re-embedding
+  unchanged source; retain no-op dumps and source-hash checkpoints (B-119).
+
+- Search Boolean metadata fields as `true`/`false` consistently in SQLite and
+  InMemory, preserving numeric `1`/`0` and null semantics (B-199, #356).
+
+- Keep the default SQLite metadata database inside the effective `WOODS_OUTPUT`
+  directory for embedding tasks, isolating indexes while preserving explicit
+  database overrides (B-156). Existing databases are not moved; run `woods:embed`
+  for the selected index after upgrading.
+
+- Treat non-object JSON snapshots and files removed or made unreadable during
+  a read as absent across lookup, listing, diffs, and unit history (B-158).
+
+- Count corrupt and unreadable SHA-named JSON snapshots toward retention and
+  evict them before valid history, preserving the just-captured snapshot and
+  unrelated files (B-163).
+
+- Count the final retrieval context after formatting and type-rank metadata,
+  keeping `tokens_used` and its trace consistent with the configured counter
+  or estimate (B-197, #354).
+
+- Order tied hybrid retrieval candidates deterministically before graph seed
+  selection, truncation and reciprocal-rank fusion across supported Ruby versions
+  (B-192).
+
+- Bound OpenAI embedding requests to 36 valid inputs, preserving chunk order and
+  rejecting partial or dimension-inconsistent batches (B-157). Chunk-heavy runs
+  use more HTTP requests to stay within the API's input and total-token limits.
+
+- Match embedded NUL literally in SQLite metadata searches, including substrings after NUL; preserve ASCII case folding and literal wildcard characters (B-198, #355).
+
+- Prevent single-component cache keys from colliding with multi-component or
+  empty keys by uniformly length-prefixing components (B-155). Custom callers
+  using persistent single-component keys should clear that cache domain on upgrade.
+
+- Make middleware argument metadata, generated source and hashes stable across Rails processes by describing runtime identities structurally while preserving literal and nested configuration (#362).
+
+- Omit per-unit git enrichment for shallow checkouts or unverifiable repository
+  depth, with one warning and full-history recovery guidance, instead of
+  reporting truncated commit counts as complete churn data (B-189).
+
+- Validate direct/legacy Console scope arrays with the active SQL dialect and
+  MySQL session quote modes, refusing subqueries hidden by mismatched quote
+  stripping while retaining the supported tools' narrower scope grammar (B-154).
+
+- Read and clear legacy Redis session indexes before any new record without
+  `WRONGTYPE`; atomic SET/ZSET access tolerates concurrent index migration
+  and keeps reader-only upgrades compatible with older SET writers (B-162).
+
+- Allow full extraction when ActionMailer is absent and skip non-app mailers
+  instead of publishing empty units at fabricated paths; share that ownership
+  gate with incremental class discovery (B-153).
+
+- Repair corrupt pipeline cooldown state on an explicit all-reset, including
+  `pipeline_repair` in custom operator-configured servers; ordinary reads still
+  deny operations and scoped resets preserve corrupt state (B-159).
+
+- Normalize incremental change paths before deduplication and dispatch, including
+  trailing root slashes, repeated separators and dot segments (B-148).
+
+- Load lazy Rails routes before caching navigation helpers, preserving view-to-controller dependencies during fresh-process incremental extraction (#360).
+
+- Reflect model methods after schema loading so full and incremental runs agree
+  on Rails-generated constructors while preserving application overrides (B-202, #363).
+
+- Parse job `perform_params` and shared `initialize_params` from Ruby parameter
+  syntax, avoiding phantom names from keyword/default expressions while preserving
+  the existing metadata fields and named rest/block arguments (B-151).
+
+- Resolve ERB-backed Solid Queue recurring schedules using Rails configuration
+  loading, including relative requires, conditional entries, aliases and custom
+  environment sections (B-203, #364).
+
+- Preserve navigation edges for real named routes such as `file_path`,
+  `image_url`, `download_path`, and `root_path`; unresolved asset/filesystem
+  helper names still produce no edge (B-152).
+
+- Resolve and track app-owned nested model mixins through runtime source locations, refreshing includer source and callbacks on incremental edits (B-150, #361).
+
+- Explain the full-extraction recovery for runtime job removals and bundle
+  upgrades; missing gem-path warnings now include the bundle-update remedy
+  without changing incremental discovery rules (B-165, B-166).
+
+- Preserve all reverse dependencies on symbolic external targets such as `http_api` after incremental graph reloads and re-registration (B-193, #305).
+
+- Preserve changes to nested `extracted_at` metadata when deciding whether to
+  rewrite a unit; only Woods' top-level extraction stamp is ignored (B-147).
+- Read per-unit git enrichment in one streamed HEAD history walk instead of
+  repeated 500-path batches (B-195, #305). Merge commits compare with their first
+  parent while all HEAD ancestry is visited; counts can change from legacy
+  pathspec simplification. Optional enrichment now requires Git 2.31 or newer;
+  incomplete/failed history is omitted with a warning. Run full extraction
+  after upgrading to refresh retained metadata. Host speedup remains unmeasured.
+
+- Apply the same app-owned path exclusions to full and incremental git enrichment;
+  external, vendored, and node_modules units no longer gain empty git metadata (B-194).
+
+- Prune default excluded package directories before recursively discovering
+  `package.yml`, avoiding scans of indexes and snapshots under `tmp/` (B-196, #305).
+
+- Preserve namespaced and CamelCase graph-retrieval subjects, keep snake_case
+  lookup working, and exclude tracing instructions from fallback metadata searches (B-190).
+
+- Order equal PageRank scores by identifier before assigning retrieval importance
+  percentiles, making their ranking weights deterministic across Ruby versions
+  and graph insertion orders (B-191).
+
+- Reduce payload-seed metadata lookups by classifying each entry once. Preserve
+  per-file hardlink/copy fallback, atomic publication and generation retention
+  while reducing full and incremental seed overhead (#305).
+
+- Keep runtime trace evidence for same-name instance and singleton methods separate, including inherited singleton owners and caller kinds. Legacy untyped events enrich instance methods only; re-record old singleton traces.
+
+- Ruby trace enrichment now records the nearest observed calling Ruby method
+  instead of the callee receiver. Recording keeps separate fiber stacks, handles
+  recursive and unwound calls, and leaves outside-recording callers unknown
+  without binding or backtrace inspection (#309).
+
+- Scope per-file git metadata to HEAD history instead of every ref, excluding
+  unmerged branches and tool checkpoints from churn and authorship (#319). Run
+  a full `woods:extract` after upgrading to refresh previously published metadata.
+
+- Full extraction no longer creates empty type directories at the index root
+  before publishing its generation payload. Existing root directories and legacy
+  flat-index files are preserved (#320).
+
+- Watch startup reconciles environment-boot-covered restart inputs with one full
+  extraction instead of repeatedly exiting 75. Live changes and changes during
+  environment initialization still require restart; failed reconciliation and
+  deleted restart inputs survive retries and supervisor restarts. Built-in
+  watchers establish detection before startup extraction begins (#318).
+
+- Add `console_mcp_http_enabled` (default `true`) so stdio-only Console setups
+  can explicitly disable HTTP and its boot-time token warnings. Production
+  still refuses to boot without a token when HTTP Console is enabled (#304).
+
+- Solid Cache conditional writes on MySQL no longer claim ownership of a
+  pre-existing row when the adapter reports matched rows as affected rows.
+  Validate ownership using the per-attempt serialized payload, with live MySQL
+  contention/recovery coverage and documented crash/eviction limits (#228).
+- Keep Notion model/column/migration data and Unblocked full/partial documents tied to their exact extracted type. Refuse incomplete export reads before mutation, and preserve remote documents when same-name, same-file types cannot be represented safely by Unblocked's existing URI scheme.
+Preserve the selected extraction type when framework search and recent changes read colliding identifiers. Session controller lookup and root outgoing-edge selection now retain the controller type. Public untyped lookup, downstream references and the bare-name multi-step context pool retain their existing contracts.
+Obsidian export preserves same-name units of different types, their separate outgoing links, and original public identifiers. Collision-bearing vaults publish a version-2 typed manifest; ordinary version-1 manifests and note paths remain unchanged. Ambiguous bare targets are omitted with a diagnostic, and incomplete typed reads cannot trigger stale-note deletion.
+- Reject ambiguous cross-type dependencies in session context with an actionable `ambiguous_identity` MCP error instead of silently selecting a source or reusing another type's context key. Leave unresolved controllers in the timeline without a misleading source reference. Pin candidate discovery and all assembly reads to one generation; retain typed controller roots, metadata-only timelines, and successful response shapes. Refs #213; this does not migrate global identifiers.
+- Refresh Console credential indexes from a fresh encrypted-file and key snapshot, retain the last valid index when refresh fails, and update all live embedded servers without retaining abandoned servers. Each response scan uses one complete credential index.
+Keep credential scanner refresh snapshots limited to live weakly referenced
+scanners on older Ruby versions, avoiding unsafe receiver access after garbage
+collection while preserving updates to every live Console server.
+- Refuse incomplete native embedding input before changing stores or checkpoints, retaining legacy flat-index support while rejecting malformed JSON. A source-empty unit now retires superseded vectors and checkpoints its no-content state without calling the embedding provider (#442, #444).
+- Terminate the evaluation command's owned process group on timeout, including ordinary descendants whose parent has already exited.
+- Let only the hook that removes a recorded dead-owner marker replace its mkdir lock, so concurrent recovery does not leave all edits queued behind an abandoned empty directory.
+- Refuse Obsidian exports that would overwrite unmanaged notes, indexes, settings, or sidecars. Preflight all destinations, record generated asset digests separately from the public manifest, and suppress sweeps on conflicts or write failures. Legacy assets are adopted only when byte-identical; changed legacy sidecars require inspection and backup or a fresh export directory.
+- Coordinate `Woods.extract!` and `Woods.extract_changed!` with task/watch writers and raise on lock timeout or failed generation publication, so background jobs can retry unsuccessful extraction.
+- Accept Rails 6.0 positional middleware options on Ruby 3 while preserving explicit keyword precedence, required bearer tokens, and unknown-option refusal. Add an installed-gem CI contract for all advertised direct runtime dependency floors, with a constrained Rails 6.0.0 fixture and recorded transitive resolution.
+- Honor configured context-token defaults in Builder-created semantic/lexical retrieval, caches, and MCP while preserving explicit budgets and the legacy custom-collaborator fallback. Deprecate the inert similarity_threshold option with a warning instead of changing ranking behavior (#446).
+- Preserve the dispatched controller's runtime class name in session traces, with a Rails-inflector fallback, so acronym namespaces retain source context in `session_trace`.
+- Preserve each logical directory alias in polling and startup catch-up so an earlier irrelevant alias cannot hide an extraction input such as `app/models`. Detect cycles per traversal branch while retaining ignored-subtree pruning.
+
+### Changed
+
+- Clarify the existing search-regex timeout exclusion: Ruby 3.0/3.1 remain
+  supported without a per-match time bound. Run the Index MCP process on Ruby
+  3.2+ for the one-second per-match limit; no runtime mitigation was added
+  for older interpreters (B-161).
+
+- Reduce payload-clone allocation and traversal overhead while preserving
+  hardlinks, copy fallback and immutable generation ownership (#305).
+- Make extraction profiling additive: report git enrichment, reconciliation,
+  finalization, pointer publication and retention separately, with a distinct
+  whole-run wall-time line (#305).
+- Expand opt-in refresh hooks to the shared extraction input rules, including
+  services, controllers, jobs, views, locales, and supported tests/lib paths.
+  Restart inputs request fresh full extraction. Preserve queued edits across
+  failures and daemon deferral, bound the worker lifetime, and carry JSON batches
+  through Docker command prefixes without host-bundle or environment-forwarding
+  assumptions. Existing manual incremental and watch behavior is unchanged.
+Add a trusted, disabled-by-default release profile for the supported 1.6.2 security maintenance line. Publication requires a separately reviewed exact candidate SHA pin on main, all fixed maintenance CI rows, and the existing immutable artifact and protected publication safeguards. The v2 release path retains its existing requirements.
+
+### Documentation
+
+- Clarify that source literals and optional session traces can contain sensitive information, and correct the session FileStore configuration example.
+- Qualify the `~> 2.0` installation examples for stable releases and direct prerelease adopters to the exact published version in the README release table. Keep agent setup and plugin guidance aligned with installed-version capabilities; clarify that the refresh-hook deadline starts after complete event input is collected and queued.
+
+### Testing
+
+- Raise the default-suite CI line-coverage floor from 85% to 90%, calibrated against current local and CI measurements. Branch coverage remains measured without a gate; per-file floors and combined opt-in coverage remain separate work.
+
 ## [2.0.0.beta2] - 2026-09-10
 
 ### Added
@@ -438,7 +697,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   a previous version migrates automatically on the first record through a
   single atomic server-side script, so concurrent writers racing the legacy
   index cannot erase each other's members or fail mid-migration; eviction
-  order (oldest last request) is unchanged. Adds a live-Redis contract spec
+  order follows oldest last request for newly scored members. Migrated members
+  receive score zero and evict lexicographically until recorded again (B-160).
+  Adds a live-Redis contract spec
   (`spec/session_tracer/redis_store_live_spec.rb`, `WOODS_RUN_LIVE_BACKENDS=1`).
 
 ### Documentation

data/CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # Contributing to Woods
 
 <!-- release-state:contributing-intro -->
-Woods welcomes bug fixes, extractor coverage, storage and retrieval improvements, MCP compatibility work, documentation, and focused performance changes. This guide covers the shared contribution contract. Coding agents working from a source checkout should also read the repository's [AGENTS.md](https://github.com/lost-in-the/woods/blob/v2.0.0.beta2/AGENTS.md).
+Woods welcomes bug fixes, extractor coverage, storage and retrieval improvements, MCP compatibility work, documentation, and focused performance changes. This guide covers the shared contribution contract. Coding agents working from a source checkout should also read the repository's [AGENTS.md](https://github.com/lost-in-the/woods/blob/v2.0.0.beta3/AGENTS.md).
 <!-- release-state:end -->
 
 ## Choose the right channel
@@ -46,7 +46,7 @@ Create a branch from current `main`. Keep each pull request to one logical chang
 | `plugin/skills/` | Distributed Woods skills (setup/upgrade, MCP configuration, investigation, agent enablement, diagnosis) |
 
 <!-- release-state:contributing-architecture -->
-Read [CLAUDE.md](https://github.com/lost-in-the/woods/blob/v2.0.0.beta2/CLAUDE.md) for architecture and implementation gotchas before changing runtime behavior.
+Read [CLAUDE.md](https://github.com/lost-in-the/woods/blob/v2.0.0.beta3/CLAUDE.md) for architecture and implementation gotchas before changing runtime behavior.
 <!-- release-state:end -->
 
 ### Agent orientation and static self-map
@@ -96,7 +96,25 @@ bin/rubocop
 
 Before requesting review, run the full unit suite and style check unless the PR explains why one cannot run.
 
-Coverage from the default process excludes opt-in Rails, installed-artifact, and live-backend lanes. Report their results separately; a low percentage for subprocess-driven tasks does not establish that they are untested. CI enforces the aggregate line floor and measures branches, but does not enforce a branch floor. Add behavior-based regressions and real optional-gem fixtures for changed extraction paths before proposing higher thresholds.
+Coverage from the default process excludes opt-in Rails, installed-artifact, and live-backend lanes. Report their results separately; a low percentage for subprocess-driven tasks does not establish that they are untested. CI enforces a 90% aggregate line floor and measures branches, but does not enforce a branch floor. The line gate was calibrated against local and CI default-suite results on 2026-09-18; it does not establish per-file coverage or coverage across the opt-in lanes. Add behavior-based regressions and real optional-gem fixtures for changed extraction paths before proposing higher thresholds.
+
+### Pending examples in CI
+
+CI fails when a running example becomes unexpectedly pending, including `skip`,
+`xit`, and pending metadata. `spec/support/pending_policy.rb` records the exact
+file, full description, reason, and unavailable capability for each reviewed
+exception. Current exceptions cover the two optional tiktoken benchmarks, one
+optional Tokenizers example, two Ruby-before-3.2 regexp-timeout examples, one
+procfs example, and three filesystem-permission examples when running as root.
+The Linux CI unit jobs run the real procfs identity example as an unprivileged
+user, so the procfs and root exceptions normally apply only to other environments.
+Opt-in suites excluded by their documented environment gates are not pending
+examples. Focused runs do not need to include every reviewed exception.
+
+Adding a new skip requires review of both its exact entry and capability check;
+matching an existing reason alone is insufficient. Local runs retain normal
+RSpec pending behavior. Exercise the policy and matrix consistency checks with
+`CI=true bin/rspec spec/ci`.
 
 ### Rails version matrix
 
@@ -113,6 +131,44 @@ WOODS_RUN_BOOTED_APP=1 BUNDLE_GEMFILE=gemfiles/rails_7.2.gemfile \
   bin/rspec spec/integration/booted_extraction_spec.rb
 ```
 
+The unit suite evaluates every hand-maintained Rails gemfile and checks its
+Appraisal requirements, old-Rails compatibility pins, and CI matrix membership.
+This detects configuration drift; it does not replace the booted rows.
+
+### Exact runtime dependency floors
+
+The separate `minimum-dependencies` CI job runs on Ruby 3.0 with Bundler 2.5.23:
+
+```bash
+gem install bundler -v 2.5.23
+ruby script/test-minimum-dependencies
+```
+
+Run outside `bundle exec`. The harness builds and installs the candidate gem,
+resolves `gemfiles/minimum_runtime.gemfile` independently of the development
+bundle, and verifies every loaded Woods library comes from that installed gem.
+All five direct runtime dependencies are pinned to their advertised gemspec
+floors. Transitive dependencies are compatible solver selections, **not** a
+claim that every transitive version is minimal. CI retains the full resolved
+version/platform list, lockfile, candidate gem and SHA-256 under the
+`minimum-runtime-dependencies` artifact; local output defaults to
+`tmp/minimum-dependencies/`.
+
+The probe exercises lexical retrieval and typed lookup over a synthetic published
+index, MCP SDK dispatch, Prism parsing, and MessagePack snapshots. It also boots
+an actual Rails 6.0.0 API-style app, loads Woods tasks, and checks the real Rails
+middleware stack for disabled Console passthrough, authorized requests, missing
+and incorrect token refusal, and forbidden origins. Static serving is explicitly
+disabled: Rails 6.0.0's own Static middleware predates Ruby 3 keyword forwarding.
+This is a bounded Woods runtime-floor contract, not evidence that arbitrary
+Rails 6.0.0 applications boot on Ruby 3. The booted Rails matrix uses compatible
+patch releases and covers full extraction; enabled database-backed Console and
+optional storage/provider combinations remain in their separate lanes.
+
+The exact-floor job is required by release CI validation. Changing a runtime
+lower bound requires updating its explicit pin and retaining a successful
+installed-artifact run, rather than silently advancing a pin to make CI pass.
+
 When adding a Rails line, update `Appraisals`, the corresponding hand-maintained gemfile, and `.github/workflows/ci.yml`. For Rails below 7.1, copy an existing 6.x gemfile so its sqlite3 and concurrent-ruby compatibility pins are preserved.
 
 ### Live storage and SQL dialects
@@ -127,6 +183,36 @@ WOODS_RUN_LIVE_BACKENDS=1 BUNDLE_GEMFILE=gemfiles/live_backends.gemfile \
 
 The lane expects reachable PostgreSQL/pgvector, MySQL, and Qdrant services. Configure endpoints with `WOODS_PG_URL`, `WOODS_MYSQL_URL`, and `WOODS_QDRANT_URL`. The Console contracts exercise blocked-table enforcement and legitimate SQL on both database dialects. New adapter behavior that depends on a real server belongs in this lane.
 
+### Solid Cache session compatibility
+
+The live-backend job runs `spec/integration/solid_cache_compatibility_spec.rb`
+against SQLite, PostgreSQL, and MySQL. MySQL coverage asserts that the adapter
+has no insert `RETURNING`, checks actual insert ownership (including same-value
+conflicts), exercises concurrent ownership, expiry, conditional deletion, and
+session clear/epoch recovery. A separate case strips only insert-result metadata
+to exercise the older Rails read-back fallback against real MySQL rows.
+
+Solid Cache coordination depends on private APIs. Before declaring a newly
+resolved `solid_cache` version supported:
+
+1. Record the exact Ruby, Active Record, Solid Cache, and database versions.
+2. Run the complete compatibility file against disposable PostgreSQL and MySQL
+   databases, with `WOODS_RUN_LIVE_BACKENDS=1`,
+   `BUNDLE_GEMFILE=gemfiles/live_backends.gemfile`, `WOODS_PG_URL`, and
+   `WOODS_MYSQL_URL` set. The suite recreates `solid_cache_entries`; never point
+   it at an application cache database.
+3. Require every example to pass, including SQLite local-cache bypass, TTL,
+   sharding, missing-private-API errors, and the MySQL ownership cases. Attach
+   the versions and results to the PR; a passing double-based unit suite is
+   insufficient.
+
+The live gemfile resolves `solid_cache ~> 1.0`; this is a dependency selection
+range, not evidence that every version in it has been tested. The baseline
+validated for #228 is Ruby 4.0.6, Solid Cache 1.0.10, Active Record 8.1.3.1,
+SQLite 3.53.2, PostgreSQL 16.15, and MySQL 26.7.0.
+Accepted crash/eviction limits are documented in the
+[configuration reference](docs/CONFIGURATION_REFERENCE.md#solid-cache-session-retention-and-compatibility).
+
 ## Keep public surfaces synchronized
 
 A pull request is incomplete when behavior and user guidance disagree.
@@ -193,8 +279,29 @@ RubyGems treats any letter in a version as a prerelease, so a `~> 1.6` or `~> 2.
 ### During feature work
 
 - Do not edit `lib/woods/version.rb` by hand.
-- Put changelog entries under `## [Unreleased]` only, beneath one of its `###` headings. Duplicate headings are merged at release time, in the order they first appear.
 - Leave the `release-state` fences alone. `release:prepare` rewrites them.
+- Put changelog entries under `## [Unreleased]`, beneath one of its `###` headings, or in an optional `changelog/<type>_<slug>.md` file. Entry files avoid conflicts between parallel branches; inline entries remain supported. Duplicate headings merge at release time, in the order they first appear.
+
+Entry files contain nonempty UTF-8 Markdown without ATX (`#`) or setext
+(underlined) headings, usually a bullet
+and indented continuation lines. For example, `changelog/fixed_watch-restart.md`
+can contain `- Preserve pending work across watch restarts.` Supported types are
+`added`, `build`, `changed`, `dependencies`, `documentation`, `fixed`,
+`performance`, `security`, `testing`, and `upgrade-notes`. Slugs start with a
+lowercase letter or digit and use lowercase letters, digits, hyphens, or
+underscores. Use one unique file per change; do not copy its entry into
+Unreleased as well. Keep entry files directly inside a real `changelog/`
+directory; symlinks and directories masquerading as entries are refused.
+Other file extensions are left untouched.
+
+`release:prepare` appends entry files in filename order after inline Unreleased
+entries, folds them through the same heading merger, and deletes exactly the
+consumed files. It validates every entry and documentation rewrite before
+changing any files; an invalid entry or a later refusal preserves all entries.
+A prepared release has an empty Unreleased section and no entry files. During
+an ordinary beta cycle, entry files may accumulate even with an empty Unreleased section while
+VERSION stays at the previous beta; the tag validator always rejects entry
+files at the candidate release SHA, regardless of inline notes or the version.
 
 ### Preparing a release
 
@@ -207,9 +314,9 @@ One command per transition. It never commits, tags, pushes, or publishes.
 | Release candidate to the release | `bin/rake "release:prepare[2.0.0]"` |
 | After the release publishes, reopen development | `bin/rake "release:reopen[2.1.0.alpha]"` |
 
-`release:prepare` refuses a dirty working tree, a version that moves backwards, a version whose base is not the line `main` is developing, and an alpha target. It then bumps VERSION, folds `## [Unreleased]` into `## [<version>] - <date>` with one block per `###` heading, restates the fences, regenerates the surface inventory, and prints the tag and dispatch commands. Every rewrite is computed before any of it is written, so a refusal leaves the working tree untouched.
+`release:prepare` refuses a dirty working tree, a version that moves backwards, a version whose base is not the line `main` is developing, and an alpha target. It then bumps VERSION, folds `## [Unreleased]` and optional entry files into `## [<version>] - <date>` with one block per `###` heading, restates the fences, regenerates the surface inventory, and prints the tag and dispatch commands. Every rewrite is computed before any of it is written, so a refusal leaves the working tree untouched.
 
-A final release also absorbs every prerelease section of its own base version. Cutting `2.0.0` folds `## [2.0.0.beta1]` and `## [2.0.0.rc1]` into `## [2.0.0] - <date>` and removes their headings, prerelease entries first and anything written after them second, so the notes a user reads for 2.0.0 are the whole story rather than three fragments. An empty `## [Unreleased]` is therefore legitimate for a final release cut straight from a release candidate. A beta or a release candidate has nothing to absorb, so an empty Unreleased section refuses: there is nothing new to publish.
+A final release also absorbs every prerelease section of its own base version. Cutting `2.0.0` folds `## [2.0.0.beta1]` and `## [2.0.0.rc1]` into `## [2.0.0] - <date>` and removes their headings, prerelease entries first and anything written after them second, so the notes a user reads for 2.0.0 are the whole story rather than three fragments. An empty `## [Unreleased]` is therefore legitimate for a final release cut straight from a release candidate. A beta or a release candidate has nothing to absorb, so an empty Unreleased section without entry files refuses: there is nothing new to publish.
 
 Review the diff and run the release contracts:
 
@@ -227,8 +334,8 @@ A release is pinned by its tag, never by a branch:
 
 | Step | Command | What guards it |
 |---|---|---|
-| Tag the merge commit | `git tag v<version> <merge-sha> && git push origin v<version>` (lightweight or annotated both work) | `script/validate-release` requires the tag to sit on `main` history, match `Woods::VERSION`, match the dated `CHANGELOG.md` heading, and not be an alpha |
-| Trigger the release workflow | `gh api --method POST repos/lost-in-the/woods/dispatches -f event_type=release -F 'client_payload[tag]=v<version>' -F 'client_payload[ci_run_id]=<id>'` where `<id>` is the green CI run on the tagged SHA (requires Contents write) | `.github/workflows/release.yml` re-validates the named CI run through the API, verifies the artifact digest, and runs secret-free candidate package tests before publishing |
+| Tag the merge commit | `git tag v<version> <merge-sha> && git push origin v<version>` (lightweight or annotated both work) | `script/validate-release` requires the tag to sit on `main` history (or the explicitly approved maintenance history below), match `Woods::VERSION`, match the dated `CHANGELOG.md` heading, and not be an alpha |
+| Trigger the release workflow | `gh api --method POST repos/lost-in-the/woods/dispatches -f event_type=release -F 'client_payload[tag]=v<version>' -F 'client_payload[ci_run_id]=<id>'` where `<id>` is the green CI run the tag push itself started, the one whose branch column reads `v<version>`; main's run on the same commit is refused with `tested ref is main` (requires Contents write) | `.github/workflows/release.yml` re-validates the named CI run through the API, verifies the artifact digest, and runs secret-free candidate package tests before publishing |
 | Verify publication | `gem info woods --remote` shows the new version; for a prerelease, `gem info woods --remote --prerelease`. The README gem badge updates on its own | just before pushing, the workflow re-runs `script/verify-release-tag` so a tag that moved since validation aborts the publish |
 
 Nothing is published from a laptop: the workflow builds and pushes the gem from the validated CI artifact, so the bytes on RubyGems are the bytes CI tested. `rake release` and `rake release:rubygem_push`, which `bundler/gem_tasks` installs, are blocked for that reason.
@@ -284,9 +391,66 @@ short body that links `CHANGELOG.md` at the tag itself (not at `main`) and
 anchors straight to that version's dated heading, so the note a reader lands
 on always matches the bytes RubyGems published.
 
+### One-off 1.6.2 security maintenance release
+
+The [security policy](SECURITY.md#supported-versions) supports 1.6.x security
+fixes until 2027-02-20. While main develops v2, the sole maintenance exception
+is `v1.6.2` from the short-lived `release/1.6.2` branch, descending from the
+immutable v1.6.1 commit `73423a42644176b09961be373e13648c94690933`.
+This is a stable patch, separate from the next v2 prerelease; it does not declare
+v2 final or establish a general-purpose maintenance publishing path.
+
+`script/release_profile.rb` on trusted main owns this exact tag/branch/base and
+its required CI jobs. `MAINTENANCE_APPROVED_SHA` starts as `nil`: publication
+fails closed until a **separate reviewed main PR** pins the exact prepared
+maintenance commit. Neither a dispatch parameter nor candidate code can choose
+another profile, branch, base, SHA or weaker CI requirements. The SHA binds the
+whole reviewed candidate, including its CI definition and installed-package
+tests; review those files as release controls, not just their job names.
+
+The preparation order is:
+
+1. Merge the main-side maintenance policy/tooling PR. Before creating the remote
+   target, confirm its effective branch rules require pull requests and prevent
+   force pushes and deletion; configure those rules before creating the target. The GitHub
+   rules API can check `release/1.6.2` before the branch exists.
+2. Create that target from the immutable v1.6.1 commit. Review the narrow security
+   backport and its legacy preparation adapter against that line. Disable the
+   inherited automatic tag-push publisher before any maintenance tag exists.
+3. Use the legacy adapter's `release:reopen[1.6.2.alpha]` and
+   `release:prepare[1.6.2]` transitions in clean, separately reviewed commits.
+   The adapter owns the legacy documentation profile; do not copy v2 fences or
+   surface claims into v1, and never hand-edit VERSION.
+4. Review and merge the prepared candidate into `release/1.6.2`. Require passing
+   unit, booted Rails, installed-package, lint, coverage, security and build
+   jobs. Review the complete CI and package-test implementation at that SHA.
+   Then pin that **exact final commit** in `MAINTENANCE_APPROVED_SHA` through the
+   separate main PR. No pin means no maintenance release.
+5. Only after the pin merges, the maintainer may tag that exact commit and wait
+   for its tag-push CI run. Dispatch uses the ordinary tag/run-ID payload.
+   Every exact maintenance matrix row in the trusted profile must succeed;
+   missing, duplicated, skipped or failed rows refuse publication.
+
+The validators require the approved SHA to remain reachable from the freshly
+fetched maintenance branch and to descend from the fixed legacy base. They retain
+exact tag/VERSION/changelog checks, the unpublished-version check, one immutable
+CI artifact ID/digest, and protected `release` environment approval. Both Ruby
+package-test rows install that same artifact and run the pinned v1-specific
+`maintenance_packaged_gem_spec.rb` outside the repository load path. The oldest
+Ruby maintenance row explicitly activates MCP 0.23.0, the reviewed security
+floor; the latest row resolves the candidate's supported SDK range. Candidate
+code still executes only in secret-free, read-only jobs. After environment
+approval, maintenance history/publication checks run again before requesting
+RubyGems credentials; the remote tag is checked again immediately before push.
+
+A candidate fix or changed prepared SHA requires a new reviewed main pin and a
+fresh tag-push CI run. Updating main's tooling alone never authorizes different
+candidate bytes. Main's v2 release contract remains unchanged. Do not create or
+push tags, dispatch, publish, or claim 1.6.2 is available during preparation.
+
 ### Stable branches
 
-A stable branch is `N-M-stable`, cut from the release tag. Create one only when a released line needs a patch after a newer major has shipped on `main`; until then, `main` is the only branch. There is no stable branch today.
+A stable branch is `N-M-stable`, cut from the release tag. Create one only when a released line needs a patch after a newer major has shipped on `main`; until then, `main` is the development branch. The explicitly approved short-lived `release/1.6.2` security exception above does not establish an `N-M-stable` branch.
 
 ### What coding agents may do
 

data/README.md

@@ -15,15 +15,15 @@
 >
 > `main` is the development branch and can run ahead of the latest published gem. The gem badge above shows the latest published version; documentation for a published version lives on its tag.
 >
-> ### Version: 2.0.0.beta2 is published as a prerelease; `main` documents 2.0.0
+> ### Version: 2.0.0.beta3 is published as a prerelease; `main` documents 2.0.0
 >
 > | Line | Version | Documentation |
 > |---|---|---|
 > | Documented here | **2.0.0**, unreleased | this README and the [documentation index](docs/README.md) |
-> | Latest prerelease | **2.0.0.beta2** | [the v2.0.0.beta2 tag](https://github.com/lost-in-the/woods/tree/v2.0.0.beta2) |
+> | Latest prerelease | **2.0.0.beta3** | [the v2.0.0.beta3 tag](https://github.com/lost-in-the/woods/tree/v2.0.0.beta3) |
 > | Latest published gem | **1.6.1** | [the v1.6.1 tag](https://github.com/lost-in-the/woods/tree/v1.6.1) |
 >
-> RubyGems treats 2.0.0.beta2 as a prerelease, so `gem "woods", "~> 2.0"` does not resolve it. Install it explicitly with `gem "woods", "2.0.0.beta2"`. The released constraint stays `gem "woods", "~> 1.6"`.
+> RubyGems treats 2.0.0.beta3 as a prerelease, so `gem "woods", "~> 2.0"` does not resolve it. Install it explicitly with `gem "woods", "2.0.0.beta3"`. The released constraint stays `gem "woods", "~> 1.6"`.
 <!-- release-state:end -->
 
 Woods boots your Rails app, extracts the behavior Rails assembles at runtime, and serves it to AI tools through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). Agents can inspect resolved routes, schema, associations, callbacks, included concerns, dependencies, and execution flows instead of guessing from source files alone.
@@ -62,6 +62,10 @@ The default setup provides structural code intelligence. It does not require an
 
 ### 1. Install Woods
 
+First [choose a version that is published on RubyGems](docs/GETTING_STARTED.md#1-install-the-gem).
+The example below requires a stable 2.x release; beta and release-candidate
+installations need an exact published prerelease pin from that guide.
+
 ```ruby
 # Gemfile
 group :development do

data/SECURITY.md

@@ -60,11 +60,12 @@ Woods runs inside your Rails application and has access to:
 - **Application source code**: extracted and written to the output directory as JSON
 - **Database schema**: column names, types, indexes, and foreign keys (no row data)
 - **Git metadata**: commit history, contributors, file change frequency
-- **Runtime state** (Console MCP Server only), live database queries within a rolled-back transaction
+- **Optional session traces**: session/trace identifiers, request paths and controller/action timelines when session tracing is configured
+- **Live database rows** (Console MCP Server), queries within a rolled-back transaction
 
 ### Output Directory
 
-Extracted data is written to `tmp/woods/` by default. This directory contains your application's source code and schema in structured JSON format. Treat it with the same sensitivity as your source code, do not expose it to untrusted parties.
+Extracted data is written to `tmp/woods/` by default. This directory contains your application's source code and schema in structured JSON format. Source literals, comments and configuration metadata may contain sensitive values. Treat the index with the same sensitivity as your source code; do not expose it to untrusted parties. Optional session stores can be configured under this directory and add request metadata that may be more sensitive than the source itself. Apply the [session tracing access and retention guidance](docs/CONFIGURATION_REFERENCE.md#session-tracer-options) to those stores too.
 
 ### Console Server
 
@@ -80,13 +81,15 @@ If extraction output leaks, what can an attacker do with it?
 
 **What the output contains.** Application source code (inlined concerns, callback-resolved behavior), database schema (column names, types, indexes, foreign keys), route tables, migration history, gem versions, and git metadata (commit history, contributor emails, file change frequency).
 
-**What the output does not contain.** No row-level data from your database. Woods extracts schema only. No environment variables, no `Rails.application.credentials`, no API keys, no session state, no request logs, no customer data.
+**Structural extraction boundaries.** Structural extraction collects schema rather than dumping live database rows, and does not intentionally collect environment variables or the Rails encrypted credential store. This is not a guarantee that output is free of secrets or customer information: extracted source can contain hardcoded values, comments or examples, and Index tools can return that source. Console redaction and export-specific scrubbing do not sanitize the structural index.
+
+**Optional session data.** When configured, session tracing records session/trace identifiers, request paths and controller/action timelines. Request paths and identifiers can contain sensitive user information. The configured session store controls where these records live; configured Index session tools can return them. Session storage and access need their own retention and authorization controls. Console MCP is a separate live-data boundary described above.
 
 | Leak scenario | Attacker gains | Attacker does not gain |
 |---|---|---|
-| `tmp/woods/` directory exfiltrated | Source code + schema equivalent to a git clone + `rails db:schema:dump` | Database rows, secrets, tokens, customer data |
-| MCP Index Server token leaked (HTTP transport) | Read-only query access to the extracted index, no write or execution paths | Shell access, database row data, secrets |
+| `tmp/woods/` directory exfiltrated | Source code, schema and metadata, including sensitive values present in source; session records if their store is configured here | No additional live database or shell access merely from possessing these files |
+| MCP Index Server token leaked (HTTP transport) | Access to published source/metadata and configured session tools, including sensitive content they contain | The packaged default does not boot Rails or provide live database queries or shell execution; custom tool wiring has its own access boundary |
 | Notion sync database compromised | Model and column summaries synced to Notion | Anything not mirrored, source code stays local |
-| Console MCP Server exposed (dev/staging) | Read-only database access through a rolled-back transaction, bounded by TableGate + Redactor + SqlValidator | Write access (rolled back), full credentials (redacted), blocked tables |
+| Console MCP Server exposed (dev/staging) | Live database access constrained by TableGate, credential scanning, Redactor and SqlValidator; this remains admin-trust access | Supported packaged modes expose no write or eval tools; rollback and redaction have the limits described in the Console guide |
 
 **Mitigation.** Treat `tmp/woods/` as source-equivalent, keep it out of world-readable directories and public container images. Rotate `WOODS_MCP_HTTP_TOKEN` on compromise. Keep `console_mcp_enabled = false` in production regardless of environment, since the console layers are defense-in-depth and not primary controls.