woods 2.0.0.beta1 → 2.0.0.beta3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34d92f37cbc6ef7c357b1566fe22c316716f0723bf7fb87a89194a8851fbe347
-  data.tar.gz: c9684e3f87be6cfe4ac1c199c96099478d8a22801a52fd6ac112b2ef4b70dab2
+  metadata.gz: f1877858142850cdb2a9802c103198cf5be63439e610ebbc43cd10f97554f10d
+  data.tar.gz: 5bad5ce4acdb04312a53d31414ea0b93b3cb4d7c103209f3172bb84e509278c3
 SHA512:
-  metadata.gz: f003ea2e4d4586b4da3e2970b27197993893d17c9e064af3a0fed513e54780799ee663fbbe2b2e1dcf5248ba9df7570ee94a43eaf3eacdab556ca46ebcf5d18a
-  data.tar.gz: 1da574149c4fe985d700d30e3d6dfe9f80a6ce8f9c7606080158b8efcf1a453d8df8846695dd373cccec3e4a4a51ac3f61fe749e1b60f9c94c51b00d539feb4d
+  metadata.gz: d878e5d2d4f51dcb4fcf4e39af29e78edf23eae756d0db4f2fe3b4c6e77454295d7a6f455d4d1f3aa397d70fb51253be040ca3ec29e17e32bd5d854dd4b434e4
+  data.tar.gz: 37a249bb634be55999c9d6ae1f058cd72a80be48496fc04b93d9d4213fa1355f1c7ff8d2d21abeeabaa8f88846846110a82547572ce74bce90dbb75d18133a0a

data/CHANGELOG.md

@@ -7,8 +7,398 @@ 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
+
+- **`release:prepare` runs a live preflight before printing the tag and dispatch
+  commands.** The new `release:preflight` task (also runnable standalone) checks, via
+  `gh api`, that the live `release` environment still requires review and disallows admin
+  bypass; that `REQUIRED_CI_JOBS` in `script/validate-release-run` still matches
+  `ci.yml`'s job names; and that both `release.yml` download-artifact steps set
+  `merge-multiple: true`. Every check is advisory: a missing or failing `gh` skips with a
+  note rather than blocking prepare. CONTRIBUTING.md and the release-flow skill also gained
+  a "when a dispatch fails" guide (which failures a main merge alone fixes versus which need
+  the tag moved, and only before publication) and the documented final step for creating the
+  GitHub Release entry by hand, which the workflow deliberately never automates.
+- **A release_v2 spec greps `spec/` for hard-coded current-version literals** (`'= 2.0.0'`,
+  `"2.0.0\n"`, `gem_version: '2.0.0'`-shaped strings), built from `Woods::VERSION`'s base, so
+  the next version bump cannot leave one behind the way the beta1 cut did.
+- **`WOODS_PROFILE=1` logs a timing line per extraction phase.** The per-extractor
+  lines already reported extraction itself; everything after it (payload seed, previous
+  graph load, eager load, blast radius, re-extraction, type index, graph analysis, flows,
+  manifest and summary, publish) was unattributed, so a slow run could only be split by
+  guessing. One `[Woods] [profile] <phase> in N.NNs` line per phase, on the monotonic
+  clock. Off by default and free when off.
+- **`durable_payload_writes` restores the per-file `fsync` on payload files.** Boolean,
+  default `false`. Off is not the weaker setting: readers resolve only through
+  `generation.json`, and every publish now flushes the whole payload before writing that
+  pointer, so the contract holds either way. Turning the key on buys exactly one thing, an
+  individual payload file being durable before the pointer exists, and pays two forced
+  flushes per file (about 8.9ms each on btrfs) for it. It cannot disable the publish
+  flush, which has no opt-out.
+
+- **`incremental_blast_radius_depth` bounds how far an incremental run re-extracts.**
+  `extract_changed` walked the unbounded transitive dependent closure of every changed
+  file, so one edit to a widely referenced unit re-extracted most of the app. The new key
+  caps the walk at N reverse hops (`nil`, the default, keeps the unbounded closure). A
+  unit outside the cap keeps its content and still gets its `dependents` list refreshed by
+  the run's second pass, which the equivalence harness now covers under a cap of 1. The
+  default stays unbounded on purpose: an STI grandchild inherits its grandparent's
+  associations, validations and callback chain while sitting two hops away in the graph,
+  and nested `has_many :through` resolves the same way, so a host opts in for a tree it
+  knows has neither. On a 200-service chain in the dummy app, one leaf edit re-extracts
+  200 units unbounded and 2 under a depth of 1.
+
+### Changed
+
+- **Payload durability moved from every file to the generation pointer.** `AtomicFile.write`
+  fsynced the temp file and the containing directory for every file it wrote, so a full
+  extraction of a large application paid two forced flushes 8323 times: 71.3s of the write
+  phase for 8000 files on btrfs, against 1.0s for one filesystem flush. Payload writes (unit
+  files, type indexes, the dependency graph, the graph analysis, the manifest, the summary,
+  the flow documents) now skip both, and `publish_generation` calls the new
+  `AtomicFile.sync_directory_tree` on the payload directory immediately before writing
+  `generation.json`.
+
+  The guarantee that replaces the old one: **when `generation.json` is durable, every file
+  in the payload it names is durable.** What is given up is an individual payload file being
+  durable before the pointer exists, and nothing reads a payload file in that window, since
+  every reader resolves through the pointer and a crash there leaves an unreferenced partial
+  payload the next run prunes. `generation.json` itself, the watch daemon's status file, the
+  update check cache, the Obsidian and Unblocked exports, Notion sync state, temporal
+  snapshots, embedding checkpoints and MCP task records all keep the per-file fsync: their
+  readers do not go through the pointer. The gem mapper's self-map publishes through the
+  same pointer but keeps its per-file fsync for now; it is a small payload and adopts the
+  single flush in a follow-up.
+
+  `sync_directory_tree` tries `syncfs(2)` through Fiddle, then `sync -f <dir>`, then a bare
+  `sync`, then an `fsync` on every file in the tree, and returns which one ran. The last
+  resort is what keeps this honest: the chain never silently does nothing, it only gets
+  slower. Fiddle is required inside a rescue and stays out of the gemspec, since it is a
+  bundled gem from Ruby 3.5. `bench/atomic_write_bench.rb` measures all four modes.
+
+- **Seeding a payload creates each directory once rather than once per file.**
+  `PayloadStore#clone` ran `FileUtils.mkdir_p` before every file it replicated.
+  `Pathname#find` visits a directory before its children, so the directory branch had
+  already created every parent a file could need. 8001 files across four type directories
+  on btrfs: 0.906s before, 0.847s after.
+
+- **Cycle detection is capped, and says so.** `GraphAnalyzer#analyze` runs on every
+  extraction regardless of the change set, and enumerating every cycle was the largest
+  part of it: one cycle per DFS back-edge, uncapped in count and in length, each
+  canonicalized by joining a path that on a deep DFS is thousands of nodes long. Two new
+  config keys bound it, `graph_cycle_limit` (default 500) and `graph_cycle_max_length`
+  (default 50, in distinct nodes); either firing sets the new
+  `stats.cycle_limit_reached` in `graph_analysis.json`. Set either to `nil` to remove
+  its cap and restore exhaustive enumeration. Signatures are now keyed by a digest of
+  the rotated cycle rather than the joined path. On a synthetic 8201-node graph, cycle
+  detection went from 8.6s to 0.4s.
+- **Bridge detection reuses its work.** `bfs_shortest_path` carries parent pointers
+  instead of enqueueing a copy of the path so far for every node it reaches, and forward
+  adjacency resolves through a per-analyzer memo instead of being re-derived on each of
+  the 200 sampled traversals. Output is unchanged. On the same graph, bridges went from
+  2.2s to 0.6s and the whole report from 3.1s to 1.0s.
+- **Flow assembly caches loaded units and parsed sources.** One `FlowAssembler` serves a
+  whole precompute run, but nothing was cached across it: a unit's JSON was re-globbed
+  and re-parsed on every expansion, and its source re-parsed once per action of every
+  controller that reached it. Three per-instance LRU memos (unit data, whole-source AST,
+  and the method index derived from it) bound at 1000 entries each. On 435 controllers x
+  7 actions over 3000 services, precompute went from 20.5s to 3.8s.
+- **The manifest and `SUMMARY.md` read each type index once.** Both derive their totals
+  from the per-type `_index.json` files and run back to back at the end of every
+  incremental run, so every index was globbed, read and parsed twice. An unreadable index
+  still drops that type from both, now with one warning instead of two.
+- **The incremental flow refresh is scoped to the flow assembly radius.** Flows were
+  reassembled for every controller in the run's touched set, and the touched set is the
+  graph's whole reverse closure, so one leaf edit re-ran flow assembly for nearly every
+  controller in the app. A flow document reaches `FlowPrecomputer::DEFAULT_MAX_DEPTH`
+  units, so the run now walks the pre-change graph to that same depth and reassembles
+  only the controllers inside it. Controllers outside it carry their
+  `metadata[:flow_paths]` annotation forward out of the previous flow index rather than
+  losing it. A targeted `refresh`, a routes re-run, and a controller whose action set no
+  longer matches the index all still reassemble in full. On 50 controllers over a
+  50-service chain in the dummy app, one edit at the far end went from 50 controllers
+  reassembled to 3 plus 47 carried.
+- **`graph_sha` is digested from the bytes written.** `graph_analysis.json`'s digest of
+  `dependency_graph.json` came from reading the file back off disk, one whole-file read
+  per run of an artifact that on a large app is tens of megabytes, to digest bytes the
+  run had just serialized. The value is unchanged.
+
 ### Fixed
 
+- `TraceEnricher.record` rejects calls without a block before creating a
+  TracePoint, preventing an enabled hook from leaking into subsequent execution (#308).
+
+- **The Changed list only names the surface inventory when regenerating it actually moved
+  it.** `release:prepare` used to list `.Codex/release-v2/surface-inventory.json`
+  unconditionally, even on the ordinary run where nothing in the public surface changed.
+- **The release banner no longer links an upgrade guide that does not exist yet.** A major
+  version bump past `docs/UPGRADING_TO_2.md`'s own major derived a
+  `docs/UPGRADING_TO_<major>.md` link without checking the file exists.
+- **Changelog entries merged from a duplicate heading no longer carry a stray blank line.**
+  Two occurrences of the same `###` heading in one `## [Unreleased]` cycle folded into a
+  release section with a blank line between their bullets, splitting one list into two; they
+  now join tight.
 - **Release validation names the live-backends CI job as it is called.** The release
   validator required a CI job named `Live backends (pgvector + Qdrant + Solid Cache)`,
   but the job gained `+ Redis` in its name, so every release dispatch failed at
@@ -23,6 +413,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   snapshot fixture, so the first prerelease failed them (Bundler never resolves a prerelease
   from an unpinned requirement). They now use `Woods::VERSION`. The candidate host also
   installs `webrick` so `woods-mcp-http` finds a Rack handler on Rubies that no longer ship one.
+- **Inspector contract specs track the pinned `@modelcontextprotocol/inspector` version instead
+  of a literal.** Bumping the dev dependency to 2.6.0 fixed the SDK bug where Inspector sent a
+  legacy `logging/setLevel` call after negotiating the modern 2026-07-28 protocol, so the two
+  `pending` stdio/HTTP examples in `mcp_inspector_contract_spec.rb` asserted a stderr message
+  that no longer occurs. Those examples now assert a clean modern handshake, and every version
+  literal in that file reads from `package.json` instead. `sdk_dependency_spec.rb`'s deliberate
+  version-and-integrity trip wire is bumped to match the new pin.
 
 ## [2.0.0.beta1] - 2026-09-09
 
@@ -300,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