woods 1.6.1 → 2.0.0.beta2

data/CHANGELOG.md

@@ -7,6 +7,2041 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+  release-context with nothing published. The prefix now matches, and a spec checks every
+  required contract job against the names in `ci.yml` so a rename cannot drift again.
+- **Release candidate jobs find the downloaded artifact.** `actions/download-artifact` with
+  `artifact-ids` extracts into `dist/<artifact-name>/`, so the digest check and the install
+  in `dist/` failed with a missing file on every dispatch since the switch to artifact ids.
+  Both downloads now set `merge-multiple: true`; the workflow spec requires it.
+- **Release candidate tests accept a prerelease version.** The clean-install smoke specs
+  pinned `2.0.0` as a literal in the dummy app's Gemfile, the loaded-version check, and a
+  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
+
+### Added
+
+- **`WOODS_GIT_DIR` names the canonical git directory outright.** It wins over
+  whatever repository Woods would otherwise find, at all three of Woods's git
+  call sites: per-unit enrichment, `manifest.json` provenance, and the
+  `woods:incremental` diff range. All three build their command line with the
+  new `Woods::GitCommand.argv`. This is the escape hatch for a container that
+  can mount the canonical git directory but not the host path a linked
+  worktree's `gitdir:` pointer names.
+- **Database-partition layer for multi-database apps (#280).** Model units record
+  `metadata[:database]` from `connection_db_config` (Rails 6.1+, `nil` on 6.0), so a model
+  that inherits `connects_to` from an abstract class reports the inherited database.
+  Association entries carry `from_db`, `to_db`, `through_db` (the has_many :through join
+  model's database, nil for a plain association), and `disable_joins`; `metadata[:foreign_keys]`
+  lists each foreign key's `from_table`, `to_table`, and `column` (the target table's owning
+  database is a graph-level lookup, not stored per model). The dependency graph gains additive
+  node keys (`database`, `table`, `foreign_key_tables`) and edge keys (`through`, `through_db`,
+  `disable_joins`); a graph with none of these serializes exactly as before.
+- **`cross_database_edges` report.** `GraphAnalyzer#analyze` lists association and
+  foreign-key edges that cross databases, with `kind` set to `join_through_across_databases`
+  when `disable_joins` is false and `from_db`, `through_db`, or `to_db` disagree (a nil
+  `through_db` falls back to comparing the two ends). A foreign key never resolves to an
+  owner living in its own source database, even when another database also claims the
+  table; only when every owner sits elsewhere, across more than one database, does the
+  entry come back with `to: nil` and an `ambiguous_owners` list instead of guessing.
+  Written to `graph_analysis.json`; exposed through `graph_analysis` in Task 10.
+- **A phase breakdown of one full extraction of the fixture app**, in
+  `docs/WATCH_DAEMON.md`. Graph analysis, PageRank included, is 3.2% of the run;
+  git enrichment is 11.6%; the one phase over 15% is `RailsSourceExtractor`,
+  which is 52.6% only because 119 of the fixture's 147 units are framework
+  sources.
+- **Positioning against Rubydex, rails-mcp-server, and ruby-lsp-rails.** `docs/WHY_WOODS.md`
+  gains a comparison table with versions checked on 2026-09-08, and frames Rubydex as
+  complementary on symbol references.
+- **Git commit facts land on graph nodes before analysis (#280).** Both extraction
+  paths copy `commit_count` and `change_frequency` from a unit's git metadata onto its
+  graph node: full extraction after git enrichment and before graph analysis
+  (`Extractor#annotate_graph_with_git_data`), incremental extraction as part of the
+  per-unit JSON patch (`Extractor#annotate_node_from_git`). A patch missing one of the
+  two keys leaves the node's existing value for that key alone rather than clearing it.
+
+  This gives `GraphAnalyzer` access to git facts without holding every unit in memory,
+  which an incremental run never does.
+- **`volatile_dependencies` report (#280).** Git churn and graph edges finally meet:
+  `GraphAnalyzer#analyze` lists edges whose dependency has at least
+  `config.volatile_dependency_ratio` (default `3.0`) times the dependent's commit count,
+  ranked by the dependency's PageRank. Young classes (fewer than 5 commits, or `new`)
+  are skipped, and the report is informational only. The top 20 are persisted in
+  `graph_analysis.json` (`stats.volatile_dependency_count` reports the full qualifying
+  total); the top 5 appear in `SUMMARY.md`. Each entry carries both ends' node types
+  (`from_type`/`to_type`). PageRank now runs inside `analyze`.
+- **`Woods::PublishedIndex` (#280).** A small read-only Ruby API over one published index
+  generation for RuboCop cops and gate scripts: look up units by identifier (optionally
+  scoped to a type, to avoid a same-identifier collision across type directories), iterate
+  edges with their attributes, build a table-to-database map, pin a retained `payloads/gen-N`
+  under the same retention lock protocol as `PayloadStore#prune`, and get a checksum keyed to
+  the pinned payload for `external_dependency_checksum`. Raises
+  `Woods::PublishedIndex::CorruptPointerError` for a `generation.json` that exists but will
+  not parse, rather than reporting zero published generations. `docs/PUBLISHED_INDEX.md`
+  includes a worked `Multidb/ForeignKeyAcrossDatabases` cop.
+- **Agent-level ablation harness (#280).** `woods:evaluate:ablation[task_set]` runs a task
+  set twice per task, with the index on and off, through any agent command that prints
+  `claude -p --output-format json` style output. Each trial runs in a disposable git
+  worktree checked out from a fixed baseline SHA, verifies Woods availability before
+  running, and enforces a per-trial timeout. Reports resolution rate, tokens, cost, turns,
+  and errors per condition with the delta, plus provenance (agent command, model, MCP
+  config, Woods generation, baseline SHA) per result. No Rails boot. This is a harness for
+  collecting paired runs, not causal evidence. `docs/EVALUATION.md` now documents
+  `woods:evaluate`, the baseline, and the ablation in one place.
+- **Plugin hooks for index freshness (#280).** The Claude Code plugin (2.3.0) ships two
+  opt-in hooks under `plugin/hooks/`: a `PostToolUse` hook that runs `woods:incremental`
+  in the background when an edit touches models, routes, migrations, schema, or a
+  `package.yml`, reading `cwd` from the hook payload so linked worktrees refresh their own
+  index; and a `SessionStart` hook that warns when the published generation predates the
+  last commit (scoped to commit timestamps, so it does not cover uncommitted edits or an
+  older checkout). Both do nothing until `WOODS_HOOKS_ENABLED=1` is set, honor
+  `WOODS_HOOKS_DISABLED=1`, and resolve the index directory the same no-boot way
+  `woods:watch_status` does (`WOODS_OUTPUT`, default `tmp/woods`). Lock contention batches
+  concurrent edits instead of dropping them: a busy hook appends its path to
+  `hook-pending.txt` and returns, and the lock holder drains it in a loop until empty
+  (mkdir-based lock on hosts without `flock`, reclaimed after `WOODS_HOOK_LOCK_STALE_SECONDS`,
+  default 1800, when a crashed run leaves it behind). Docs gain the Rails 8.1 `config/ci.rb` step
+  `step "Woods: refresh", "bin/rails woods:incremental"`.
+- **Packwerk package layer (#280).** A new `package` unit type reads every `package.yml`
+  `enforce_dependencies`, `layer`, `public_path`, `owner`, with a `package_dependency`
+  edge per declared dependency. Any `package.yml` change re-runs the extractor wholesale
+  during incremental extraction. Woods reports boundaries; `pks check` and
+  `packwerk check` keep enforcement. A pack-resident file-based unit (a service under
+  `packs/billing/app/services/`) is still not discovered by `PathDispatcher`, so it never
+  becomes a unit at all (follow-up B-175).
+- **Package membership on units (#280).** Every discovered app-owned unit under a package
+  root carries `metadata[:package]` and its graph node carries `package`, on full and
+  incremental runs alike; a `package.yml` change re-annotates the affected units in the
+  same incremental run.
+- **`undeclared_package_edges` report.** `GraphAnalyzer#analyze` lists every edge that
+  crosses a package boundary the source package never declared, read from the `package`
+  node attribute and each package unit's own `package_dependency` edges. `dependents`,
+  `lookup`, and `domain_clusters` already show the units; this shows the boundary an
+  agent is about to cross. Enforcement stays with `packwerk check` / `pks check`.
+- **`graph_analysis` exposes the cross-database and volatile-dependency reports.**
+  `analysis` accepts `cross_database_edges`, `volatile_dependencies`, and
+  `undeclared_package_edges`; `all` paginates them like every other section, and the
+  markdown and plain renderers print edge-shaped items on one line each.
+- **`woods:check:moved_messages` (#280).** Compares two retained payload generations through
+  `Woods::PublishedIndex` and lists every public method name that looks like it moved between
+  units while its `test_coverage` edge did not follow. Each row is a candidate move into a unit
+  without mapped tests, not a proven coverage loss. `WOODS_CHECK_STRICT=1` exits 1 for CI. No
+  Rails boot.
+
+- **MCP 2026-07-28 support** (B-111–B-114). The gemspec now requires `mcp >= 1.2, < 2.0`,
+  the release that added the 2026-07-28 protocol revision.
+  - **Stateless Streamable HTTP by default.** `woods-mcp-http` no longer mints
+    `Mcp-Session-Id`, so restarting it (gem upgrade, machine sleep, worktree rebuild) is
+    invisible to connected clients instead of invalidating every session, and several
+    instances can serve one volume-mounted index without sticky routing. Set
+    `WOODS_MCP_HTTP_STATELESS=0` for a client that still needs sessions, the GET SSE
+    stream, or DELETE teardown — a transitional escape hatch, since all three are gone
+    from the specification.
+  - **Tasks extension** (`io.modelcontextprotocol/tasks`). `pipeline_extract` and
+    `pipeline_embed` return a durable task handle to clients that declare the extension:
+    poll with `tasks/get`. Cancellation is not advertised: `tasks/cancel` returns
+    `Method not found` because Woods cannot safely stop work already holding the
+    pipeline lock or prevent it from publishing. Records live on disk under
+    `<index_dir>/tasks/`, so a run reports real success or failure, a client that drops
+    mid-run can reconnect — even to a restarted server — and collect the result, and a
+    task whose owning process died resolves to `failed` instead of leaving an agent
+    polling forever. Clients that do not declare the extension get the previous
+    fire-and-forget behaviour, unchanged.
+  - **Cache hints and deterministic tool ordering.** List and read results carry
+    `ttlMs` (default 10s, `WOODS_MCP_CACHE_TTL_MS`) and `cacheScope: "private"`, and tools
+    are advertised in sorted order so a host with optional integrations wired presents the
+    same tool block as one without.
+  - **`server/discover`** is answered, advertising supported versions, capabilities and
+    the Tasks extension.
+
+- **`embedding_provider = :fake`** — the deterministic bag-of-words provider is now a
+  first-class citizen (promoted from spec support), and `Builder` also accepts an injected
+  provider object responding to `#embed`/`#embed_batch`. `woods:embed` → `woods:retrieve`
+  now runs fully offline; `woods:retrieve` resolves all four backends through the
+  configuration instead of hardcoding Ollama + in-memory stores (#178).
+- **Notion sync manifest** — unchanged pages cost zero API calls on re-sync; changed pages
+  update by cached page id without a title query; `WOODS_NOTION_FORCE=1` bypasses for one
+  run (#207).
+- **`woods:validate`** warns for units whose `file_path` resolves neither as written nor
+  under `Rails.root` (#169).
+
+- **`rake woods:watch` — a resident extraction daemon** (#164, phase 2). Watches the app and
+  keeps the index current as files change, instead of as-fresh-as-the-last-explicit-run. One
+  cycle is watch → debounce → classify → reload if needed → extract → publish. Freshness was
+  pull-based because every sync from a cold process pays a full Rails boot; a process that
+  stays booted removes that tax without giving up runtime-true extraction. Development only —
+  it adds no network listener. See `docs/WATCH_DAEMON.md`.
+  - **Restart triggers, Spring-style.** A change to `Gemfile.lock`, `config/**`, or the schema
+    stops the daemon with a degraded status and exit `75` for a supervisor, because Rails'
+    reloader re-runs none of it.
+  - **Failure posture.** A failed reload (the mid-edit syntax error) publishes a degraded
+    status naming the reason and leaves the index intact at its last good generation. The
+    daemon never crash-loops, never publishes a partial write, and never advances the
+    generation over work that didn't land.
+  - **Storm handling.** Above a changed-file threshold (default 50) a branch switch falls back
+    to one full extraction rather than N incremental steps.
+  - **Two watcher backends.** The `listen` gem when the host has it; a dependency-free polling
+    scan otherwise — which is also the right choice inside a container, where native FS events
+    don't cross bind mounts reliably.
+- **Multi-instance operation across worktrees** (#164, phase 4). Worktrees stay disjoint by
+  construction (own `Rails.root`, own `tmp/woods`), so the work is within one worktree: the
+  daemon, a manual `woods:extract`, and a hook-triggered `woods:incremental` now share the
+  existing `PipelineLock`. The daemon yields to another writer and carries its paths into the
+  next cycle rather than losing them; manual runs wait up to 30 s and then proceed with a
+  warning rather than hanging a terminal; and `woods:incremental` skips entirely when a live
+  daemon is already watching the tree (`WOODS_IGNORE_WATCH=1` overrides). New
+  `rake woods:watch_status` exits 0 when a daemon is alive, so a worktree hook can revive one
+  without parsing anything. `Woods::Watch::Daemon`'s `idle_timeout` (off by default) stops a
+  daemon in a dormant slot so it stops holding a booted app's memory.
+- **An MCP freshness contract** (#164, phase 3). `woods_status` now reports the index
+  `generation` (number, when it moved, what moved it), whether the **working tree** is dirty
+  plus a fingerprint of it, and the watch daemon's state (`running` / `degraded` + reason /
+  `stopped` / `absent`). `git_sha_matches_head` only ever saw *committed* HEAD, so an agent
+  forty uncommitted edits deep was told the index matched while every answer described the
+  tree before those edits.
+- **`IndexReader` self-refreshes on a generation change**, making the MCP `reload` tool an
+  optimization rather than a correctness requirement. A long-lived server used to hold
+  whatever it read at boot, so an agent working alongside a running extraction silently got
+  answers describing the tree as of the last server start. The check costs one `File.stat` of
+  a ~100-byte file per read. `IndexReader#with_pinned_generation` extends it across a sequence
+  of reads. Indexes with no generation file behave exactly as before.
+- **`Woods::Generation`** — a monotonic marker for "which version of the index is on disk",
+  written atomically as the last step of a successful run by *every* extraction mode (full,
+  incremental, targeted refresh, daemon cycle). Never advanced by a run that failed or changed
+  nothing, so staleness stays honest.
+- **`Extractor#refresh(*keys)` and `rake "woods:refresh[routes]"`** (#164, phase 1). Re-runs
+  named extractors wholesale against an already-booted app, replacing every unit of the types
+  they own. The unit types with no per-file entry point — routes, middleware, engines,
+  scheduled jobs, state machines, factories, events, database views — were only reachable by
+  full extraction from a cold boot, which was an artifact of the boot cost rather than
+  anything inherent: in a booted process re-running one extractor takes seconds. A routes
+  refresh cascades to the extractors that embed the route table. Any extractor key is
+  accepted, so `refresh(:models)` is a legitimate way to re-derive models after a schema
+  change.
+- **`Woods::ReloadPolicy`** — the reload-trigger inventory (#164). Classifies a changed path
+  as `:ignore`, `:reextract` (Woods reads bytes; no Rails involvement), `:reload` (an
+  autoloaded constant changed) or `:restart` (boot-captured state changed — initializers,
+  `config/**`, `Gemfile.lock`, schema). Consumed by `Watch::Daemon` on every cycle, and
+  tested against the `railties >= 6.0` support matrix. `spec/reload_policy_spec.rb` derives
+  its samples from the `PathDispatcher` rules themselves, so the two cannot drift apart
+  silently.
+- **Differential test harness for incremental extraction**
+  (`spec/integration/incremental_equivalence_spec.rb`, tagged `:booted_app`). Applies
+  randomized create/modify/delete/rename sequences to a booted fixture app and asserts, at
+  every step, that the incrementally-maintained index matches a cold full extraction: same
+  units, same unit content, same graph, PageRank recomputed. Tune with `WOODS_DIFF_OPS` and
+  `WOODS_DIFF_SEEDS`; runs in CI on every Rails-matrix row.
+- `Woods::ChangeSet` — one normalization of "what changed" (absolutize, de-duplicate, split
+  present from vanished) shared by every entry point, so the git-diff caller and the watch
+  daemon can't drift apart.
+
+### Performance
+
+- **Controller and mailer chunk extraction parses each file once, not once per
+  action (P1).** `AstSourceExtraction#extract_action_source` re-read and re-parsed
+  the defining file for every action, so a 30-action controller cost 30 reads and
+  30 parses of one source file. The defining file is now read and parsed once per
+  extractor instance and every action is answered from that parse; per-action
+  chunk output is byte-identical.
+
+- **Event extraction reads each file once per run (P2).** `EventExtractor`
+  re-read every publisher/subscriber file for every event that referenced it
+  (once per event in pass 2, on top of the pass-1 scan), so a widely-shared file
+  was read once per event. Both passes now share one read per path per run.
+
+- **Rake task extraction reads and parses each `.rake` file once per run
+  (P9a).** `all_definitions` — the sibling-definition index built on the first
+  `sibling_definitions` call — re-read and re-parsed every `.rake` file the main
+  extraction path had just handled. Both paths now share a memoized read+parse.
+
+- **GraphQL model-reference scanning makes one pass per type file (P9c).** The
+  constant follow-up check ran one full-source scan per unique capitalized
+  constant; one combined scan now collects the constants followed by a model
+  call. Emitted dependencies are unchanged.
+
+- **Git metadata batching sends each pathspec once (P9d).** Multi-unit files
+  repeated their path in every 500-path git log batch; `batch_git_data` now
+  deduplicates before slicing. Output is keyed by relative path and unchanged.
+
+- **User search regexes are time-bounded (P5).** `search` compiled the query as
+  a raw Ruby regex with no time limit, so a pattern with catastrophic
+  backtracking could stall the dispatch thread indefinitely. On Ruby 3.2+ the
+  compiled pattern carries a 1s per-match limit; an overrun aborts the scan
+  into a partial response with a note instead of hanging. Invalid patterns
+  still fall back to an escaped literal match.
+
+- **`dependency_graph.json` parses once per generation (P6).** The Index
+  Server's `dependency_graph` and `raw_graph_data` each parsed the same file,
+  holding two copies of a large graph per generation; the typed graph now
+  builds from the single raw parse. Because `raw_graph_data` exposes that
+  shared parsed object, Woods recursively freezes it before publication so a
+  caller cannot mutate nested nodes or edges and corrupt later graph reads.
+
+- **JSON temporal snapshots are pruned by retention (P8).** `snapshots/`
+  wrote one file per SHA and never pruned, growing unboundedly on long-lived
+  repos. Capture now keeps the newest `WOODS_PAYLOAD_RETENTION` snapshots
+  (default 3, same variable and default as payload retention), and the bound
+  holds even when the just-captured snapshot's timestamp ties or precedes
+  older entries; `diff` and `unit_history` beyond the retention window
+  return empty.
+
+- **Redis session-tracer eviction uses a recency ZSET (P4).** `prune_sessions`
+  read every candidate session's history on every record once `max_sessions`
+  was reached (up to 1000 session reads per request). The `woods:sessions`
+  index is now a ZSET scored by each request's timestamp, so eviction touches
+  a bounded window and never reads session histories. A legacy SET index from
+  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
+  (`spec/session_tracer/redis_store_live_spec.rb`, `WOODS_RUN_LIVE_BACKENDS=1`).
+
+### Documentation
+
+- **The documentation set is restructured for a cold reader** (from the
+  2026-09-03 documentation review). The README opens with the pitch and
+  reaches setup before any migration content, links Why Woods, and points
+  1.x users at the upgrade guide instead of restating it;
+  `docs/ARCHITECTURE.md` is renamed `docs/INTERNALS.md` (ending the name
+  collision with generated self-analysis output); Troubleshooting's quick
+  reference sits under its intro; the FAQ, tool cookbook, and configuration
+  reference open with question/scenario/options indexes; reference-doc
+  headings use sentence case; the release-cutting runbook lives in
+  CONTRIBUTING.md; and implementation plans moved under `docs/design/`.
+  `woods:self_analyze` no longer emits `call-graph.md`, `dependency-map.md`,
+  and `dataflow.md` — byte-identical duplicates of sections
+  `architecture.md` already embeds (13k generated lines removed).
+
+- **The distributed plugin grows from three skills to five, with upgrade
+  coverage and reworked triggering** (plugin 2.2.0). `woods-investigate`
+  triggers on audits, code reviews, investigations, debugging, onboarding,
+  and change-impact assessment, distilling AGENT_GUIDE.md's tool-selection
+  workflow so index consumption — not just setup — has a skill.
+  `woods-agent-enable` wires Woods into a repository's own agent tooling:
+  project MCP configuration, index-first guidance in CLAUDE.md/AGENTS.md,
+  and an optional project skill seeded from real cluster/pagerank output.
+  `woods-setup` now covers the 1.x→2.0 upgrade path (clean re-index, no
+  in-place durable-index upgrade, full re-embed) and triggers on upgrades.
+  Every skill description states what the skill does as well as when to use
+  it, and skill prose no longer hardcodes a patch-precise version floor or a
+  pinned MCP protocol date: the marketplace entry is the authoritative
+  minimum, and skills operate against the preflight-recorded installed
+  version.
+
+- **`woods-mcp-start` is described as what it is: a preflight wrapper (MCP-10).**
+  It validates the index directory and published manifest, then `exec`s
+  `woods-mcp`; there is no supervision and no restart loop. The "self-healing
+  MCP wrapper" description in the header comment and the CLAUDE.md architecture
+  table is gone. (`docs/MCP_SERVERS.md` and `docs/DOCKER_SETUP.md` already
+  described it accurately.)
+- **Reload documentation drift (MCP-7).** `Bootstrapper.populate_vector_metadata`
+  named `populate_reloaded_vector_metadata`, a method the M7 transaction removed;
+  `Ranker#invalidate_pagerank_cache!` claimed a bootstrapper caller that does not
+  exist (the transaction installs a fresh Ranker instead, deliberately). Both
+  comments now describe the current design; `invalidate_pagerank_cache!` is
+  re-documented as an API for direct embedders that repoint a Ranker's graph
+  store without rebuilding it.
+- **The unreleased-2.0 story is legible from the repository root.** `README.md`
+  gains a version banner naming both the documented 2.0.0 line and the published
+  1.6.1 gem, a "What's new in 2.0" comparison table, and a compact upgrade
+  checklist; `docs/UPGRADING_TO_2.md` covers the Notion physical-column re-sync,
+  the new task exit codes, the incremental baseline guard, and `reload`'s
+  write-access requirement; every claim that expires at tag time is wrapped in a
+  `release-state` fence, listed in the new release note in `docs/README.md`.
+
+### Upgrade Notes
+
+This is a major release: the full-gem review (#210) corrected how several extractors
+derive unit identifiers, which changes the index format's observable contract.
+
+- **Unit identifiers have changed shape.** Namespaces are now derived correctly by a
+  position-aware nesting parser (#174), abstract-model and mixin-module artifacts no
+  longer leak into names, and GraphQL inner classes are no longer folded into
+  identifiers (#194). Concretely: a state machine that indexed as `Payment::aasm` is now
+  `Billing::Payment::aasm`; a service that indexed as bare `IssueInvoice` is now
+  `Billing::IssueInvoice`; concern units are no longer misnamed `ClassMethods`.
+  **Anything that cached the old identifiers will miss**: saved retrieval queries,
+  external notes, exported Notion pages and Unblocked documents, MCP clients holding
+  identifier lists.
+- **The remedy is one clean re-index**: `woods:clean` followed by `woods:extract`
+  (then `woods:embed` if you embed, and a re-export if you sync Notion/Obsidian/
+  Unblocked — the exporters reconcile renamed units as delete-plus-add).
+- **Durable vector stores are now reconciled against extraction output** (#211). The
+  first `woods:embed` / `woods:embed_incremental` after upgrading will **delete** vectors
+  for units the extraction no longer produces — including every unit the identifier
+  renames moved. Deleting more than 30% of the store (or purging into an empty load) is
+  refused with an explanation; `WOODS_ALLOW_PURGE=1` overrides after you've confirmed the
+  deletion is intentional. On a rename-heavy index, expect to need it once.
+- **An embedding-dimension mismatch now refuses to embed up front** (#214).
+  `woods:embed` compares the provider's dimension against what the store actually holds
+  (pgvector's column type, Qdrant's collection config) before embedding anything, raising
+  `Woods::MCP::DimensionMismatch` with both widths — instead of embedding everything and
+  failing per-row on insert. If you changed `embedding_model` at some point and it
+  "worked", this check may now surface the latent mismatch; the remedy is a full re-embed
+  into a store created at the new width.
+- **New environment variables**: `WOODS_ALLOW_PURGE` (override the vector purge guard,
+  above) and `WOODS_NOTION_FORCE` (bypass the Notion sync manifest for one run, forcing
+  a full re-push).
+
+### Changed
+
+- **Release flow: `main` carries an alpha development marker.** `Woods::VERSION` is
+  `X.Y.Z.alpha` between releases, so `main` never claims a released version and the
+  gemspec points its source, changelog, and documentation URIs at the branch rather
+  than at a tag that does not exist. A release is an explicit commit plus a tag:
+  `bin/rake "release:prepare[<version>]"` bumps VERSION, folds `## [Unreleased]` into
+  `## [<version>] - <date>` with one block per `###` heading, restates the documentation
+  fences (renamed from `v2-unreleased-note` to `release-state`, now driven by VERSION
+  rather than by hand), regenerates the surface inventory, and prints the tag and
+  dispatch commands. `bin/rake "release:reopen[<next>.alpha]"` reopens development after
+  a release. `spec/release_v2/version_state_spec.rb` enforces the state on every commit,
+  both release validators refuse an alpha tag, and the `release` task `bundler/gem_tasks`
+  installs is blocked: nothing is published from a laptop. Betas and release candidates
+  are supported states, and RubyGems treats them as prereleases, so a `~> 1.6` or
+  `~> 2.0` constraint never resolves one. See the release flow section of
+  `CONTRIBUTING.md`.
+
+- **Dead code removed.** The unwired formatting adapters (Claude, GPT, Generic),
+  console job/cache adapters, `StubBridge`, `HealthCheck`, `Instrumentation`,
+  `Notion::Mapper`, and a dozen spec-only methods are gone. `config.add_gem`
+  now warns like `config.extractors`: accepted, not implemented.
+- **Docs rewritten for readability**: shorter sentences, tables for
+  comparisons, no em-dashes, one owner per fact. The MCP 2026 handoff document
+  was folded into the strategy ADR.
+
+- **The packaged gem ships only user-facing files.** Internal release machinery
+  (`lib/tasks/release_v2.rake`, `lib/woods/release_v2/`) and non-user-facing
+  documentation subdirectories are excluded from the package; the repo keeps
+  them for CI. Historical build-phase design documents were removed from
+  `docs/` for the release and remain in git history.
+- **The Claude plugin releases with the gem.** `plugin.json` is 2.0.2.
+- **`config.extractors` warns when set.** The knob is accepted for forward
+  compatibility but extractor selection is not implemented; all extractors run.
+  Docs no longer teach it as a live setting. The unused `log_level` accessor
+  is removed.
+- **`woods-mcp-start` no longer pins the MCP protocol version.** It defaulted
+  `MCP_PROTOCOL_VERSION` to `2024-11-05` — the oldest revision there is — which silently
+  opted every user out of four protocol revisions. The SDK server is dual-era, answering
+  `initialize` for legacy clients while serving `server/discover` and per-request metadata
+  for modern ones, so the unpinned server is the *more* compatible one. The variable
+  remains as an escape hatch and now announces itself on stderr when set.
+  **No action required:** legacy clients keep working, and no re-extraction or re-embedding
+  is implied — no on-disk artifact format changed.
+
+- `woods:watch_status` no longer depends on `:environment`. It reads one small JSON file, and
+  the point is that a worktree hook can call it *before* deciding whether to do real work —
+  paying a full Rails boot to find out cost more than the sync it exists to avoid.
+- `WOODS_WATCH_POLL=1` forces the polling backend. `docs/WATCH_DAEMON.md` told container hosts
+  watching a bind mount to do this; nothing exposed it. `WOODS_WATCH_IDLE_TIMEOUT` and
+  `WOODS_WATCH_CATCH_UP` are exposed on the rake task for the same reason.
+- The debounce window now genuinely coalesces. The watcher callback merges into a pending set
+  and returns, so a save, the formatter's rewrite and the linter's touch become one cycle
+  rather than three — previously `settle` only delayed the first of the three.
+- `spec/reload_policy_spec.rb` derives its samples from the `PathDispatcher` rules rather than
+  a hand-written list, so a rule added for a new extractor is covered without editing the
+  spec. `spec/support/index_comparison.rb` compares PageRank *values* (to 6 dp) rather than
+  just keys — comparing keys alone said nothing about the modify-only operations most likely
+  to leave scores stale.
+- `GraphAnalyzer` output is now a pure function of graph content. `hubs` breaks ties on
+  identifier instead of graph-insertion order, and `bridges` samples from a sorted node list,
+  so two extractions of the same tree publish the same analysis.
+
+- New `Woods::Extractors::LineNeutralizer`: the quote-aware comment stripper (formerly private to
+  `SharedDependencyScanner`) plus string- and heredoc-blanking variants, shared by SourceNesting,
+  the rake and factory parsers, and CallbackAnalyzer.
+- New `Woods::Extractors::ReferencePatterns`: the namespace-capable service, mailer, and job-enqueue
+  regexes, shared by `SharedDependencyScanner`, `JobExtractor`, and `CallbackAnalyzer`.
+
+- **`FlowPrecomputer`'s `fail_closed:` switch is gone (EXTB-14).** Both callers
+  passed `true` and CLAUDE.md documents both paths as fail-closed, but the YARD
+  still promised the full path a "log-and-skip contract" and the
+  `Rails.logger.error` branch it described was dead code. Flow assembly now always
+  raises `Woods::ExtractionError` on a per-action failure.
+
+- **An unlisted integer tool parameter fails the server build with a named error
+  (MCP-8).** `ToolContract::INTEGER_BOUNDS.fetch` raised a bare
+  `KeyError: key not found: "count"` at `Server.build`, with no pointer to the
+  table that needs the entry. It now raises an `ArgumentError` naming the tool,
+  the property, and `INTEGER_BOUNDS`.
+
+- CI gains a `c-locale` job running the artifact-reader specs (`spec/mcp`,
+  `spec/feedback`, `spec/session_tracer`, `spec/evaluation`) under `LC_ALL=C`. The
+  runners default to a UTF-8 locale, so the whole encoding family could regress
+  with the suite green.
+- Three specs that simulate an unreadable/read-only path with `chmod` now skip as
+  root, where `chmod` is ineffective (`spec/operator/pipeline_guard_spec.rb` x2,
+  `spec/mcp/tasks/pipeline_tasks_spec.rb`).
+- `docs/backlog.json` gains B-140..B-163: the seven prior-audit deferred lows that
+  never received IDs (R2-2 — L3, L7, L12, L13, L14, L15, L21) plus seventeen
+  deferrals from this audit (CORE-3, CORE-5, EXTA-7, EXTA-9, EXTA-11, EXTA-13,
+  EXTA-15, CON-4, STO-7, STO-10, STO-14, INF-5, INF-6, INF-13, R2-4, R2-5, R2-6).
+
+- **STO-12**: Corrected the `Storage::Snapshotter` doc comment: `Snapshotter::Metadata.validate_store!` can use plain `respond_to?` only because `MetadataStore::Interface` defines neither `#each_entry` nor `#bulk_load` — adding either stub would silently convert the check into the B-108 bug. `spec/storage/snapshotter/vector_spec.rb`'s float-truncation tolerance block (which passed whether or not the load raised, stale since the M10 fix) now asserts the raise.
+
+### Fixed
+
+- **The release contract specs pass in every version state.** `spec/release_v2`
+  copied this checkout's `CHANGELOG.md`, `README.md`, `CONTRIBUTING.md`, and
+  `docs/UPGRADING_TO_2.md` into its temporary repository, so eleven examples
+  assumed the checked-in tree was an alpha with a non-empty Unreleased section.
+  A release commit produced by `release:prepare` therefore could not pass its
+  own specs, which defeats the flow. The transition specs now run against a
+  self-contained fixture (`spec/fixtures/release_repository`), each of them
+  keeps one example that reads this checkout and asserts only the invariants of
+  the state it finds, and `spec/release_v2/release_state_matrix_spec.rb`
+  generates the alpha, prerelease, and final states from the fixture in one run
+  and checks all three plus the running checkout against the same invariants.
+  The gemspec metadata example asserts the ref rule (`tree/main` for an alpha,
+  `tree/v<VERSION>` otherwise) instead of a fixed state.
+
+- **Components outside the eager-load paths are indexed.** `PhlexExtractor` and
+  `ViewComponentExtractor` discovered units from `component_base.descendants`
+  after `eager_load!`, so a component under an autoloaded but not eager-loaded
+  subtree of `app/views` was never a descendant and never indexed. Both now ask
+  the autoloader for every Ruby file under the component directories first, and
+  the directory list is configurable through `config.component_paths` (default
+  `app/components`, `app/views/components`, `app/views`; an empty array walks
+  nothing). Nested directories collapse into their ancestor, and one debug line
+  per run reports files whose directory is not on an autoload path. The
+  ViewComponent path is skipped entirely when `ViewComponent::Base` is
+  undefined.
+- **Git enrichment refuses to invent history it cannot read.** Over a
+  containerized linked worktree, `git rev-parse --git-dir` succeeds while no ref
+  resolves (the private git directory reaches the shared one through a relative
+  `commondir` pointer), `git log` exits 0 with no output, and every unit was
+  written with `commit_count: 0` and `change_frequency: "new"`,
+  indistinguishable from a file that was never committed. Enrichment now
+  requires `git rev-parse HEAD` to succeed: when it does not, the git keys are
+  omitted from every unit, provenance records `"unknown"`, and one warning names
+  git's own reason. `docs/TROUBLESHOOTING.md` and
+  `docs/CONFIGURATION_REFERENCE.md` state that `GIT_DIR` alone is not enough for
+  a linked worktree.
+- **`dependents` and `dependencies` are bounded and say when they truncate.**
+  Both tools now return at most 50 traversal nodes by default, accept `limit`
+  and `offset` like `graph_analysis`, and print the same
+  `Showing N of M (truncated)` line; their descriptions name `depth`, `types`
+  and `via` as the controls that shrink an answer rather than page it. Every
+  partial answer carries `nodes_total`, the last page of a walk included, so a
+  page is never mistaken for a complete result. Rows carry the unit's database,
+  but only in a graph that spans more than one, so a single-database index
+  renders exactly as before.
+- **`graph_analysis.json` states its own volatile-dependency cap.**
+  `stats.volatile_dependencies_limit` (20) now sits beside
+  `stats.volatile_dependency_count`, so a reader of the truncated
+  `volatile_dependencies` array can tell a page from the whole population.
+  `docs/INTERNALS.md` gains a table mapping every analysis section to its stat
+  key and naming which sections the artifact caps.
+- **`graph_sha` is now a function of graph content, not of registration order.**
+  `DependencyGraph#to_h` sorted neither the members of `reverse`, `file_map` and
+  `type_index` nor the keys of any section, and the extractor wrote PageRank in
+  node-registration order, so a no-op incremental run republished an identical
+  graph under a new digest and every consumer caching on `graph_sha` redid its
+  work. The incremental equivalence oracle now compares `graph_sha` as well.
+- Respect MySQL session quote modes throughout Console SQL checks, including
+  `ANSI_QUOTES` and `NO_BACKSLASH_ESCAPES`, without rejecting ordinary escaped literals.
+- Preserve absolute Ruby constants through both AST backends and static-map resolution.
+- Compare evaluation baselines against public names after typed storage transitions.
+
+- Preserve coexisting typed units through embedding, checkpoints, retrieval and
+  snapshots. SQLite migration 007 retains old snapshot rows; older JSON snapshots
+  remain readable. Remove metadata when the corresponding vanished vectors are pruned.
+- Keep precomputed flows for namespaced and underscore-named controllers separately
+  addressable, and resolve known lexical module dependencies in the static self-map.
+- Remove machine-specific session and host instructions from shared contributor context.
+- Keep release-inventory drift tests from temporarily modifying real source and guide files.
+
+
+- **Wrapper-nested classes no longer collide on one identifier.** A file under
+  a managed autoload path is now named for the constant its path spells
+  (Zeitwerk-governed naming): `app/services/domain/container/parser.rb`
+  declaring `module Domain; class Container; class Parser` indexes as
+  `Domain::Container::Parser` instead of the wrapper `Domain::Container`.
+  Previously every sibling under the same wrapper indexed as the wrapper and
+  same-type dedup silently dropped all but one. The source parser remains the
+  fallback for unmanaged or unconventional paths, and extraction now aborts
+  naming both file paths when one type+identifier is still derived from two
+  different files. **Re-extract after upgrading** — embeddings, exports, and
+  saved queries keyed by the old identifiers need regeneration.
+
+- **Console stdio setup now explains production token validation.** Stdio clients do
+  not send the HTTP bearer token, but Rails still requires a 32-character-or-longer
+  `console_mcp_token` at production boot whenever Console MCP is enabled. The upgrade,
+  direct, Docker, FAQ, and agent setup paths now state that boundary explicitly.
+
+- **Console SQL gate no longer has MySQL comment and dollar-quote blind spots.**
+  `SqlNoiseStripper` did not know `#` line comments or `/*! ... */` executable
+  comments (both live SQL on MySQL), and treated a `$` inside a PostgreSQL
+  identifier as a dollar-quote opener, so a blocked table could be hidden from
+  `TableGate`. The `TABLE name` statement form was never scanned at all. All
+  four are closed, with the `#` rule gated on the MySQL dialect.
+- **Redacted columns are refused as query inputs, not only masked on output.**
+  `console_aggregate(column:)`, scope keys (including `_matches`), `find(by:)`,
+  and `recent(order_by:)` accepted `console_redacted_columns`, which gave a
+  plaintext aggregate or a comparison oracle over a secret.
+- **The MySQL console timeout no longer leaks into the host's connection pool.**
+  `SET max_execution_time` is session-scoped and survives rollback; the prior
+  value is now read and restored in `ensure`.
+- **Console SQL validation stops rejecting columns named `do`, `start`,
+  `lock`, `release`, or `handler`.** Forbidden statement keywords now match only
+  at a statement-leader position. `EXPLAIN ANALYSE` (the PostgreSQL spelling) is
+  rejected like `ANALYZE`. `console_association_count` gates the rendered SQL, so
+  a blocked `through` table is refused.
+- **Long-running MCP tasks no longer expire the moment they complete.** Terminal
+  task ttl is measured from the terminal transition, not from creation. A task
+  minted under a different boot identity (a container) is left alone by a host
+  reader instead of being marked failed.
+- **Extractor accuracy batch.** `permitted_params` no longer leaks across method
+  bodies (and reads Rails 8 `params.expect`); GraphQL complexity is read from a
+  real match; per-file GraphQL classification agrees with the runtime pass;
+  `form_action` edges stop at `do`/`end`; `SourceNesting` pops on `end.freeze`;
+  `render :partial => 'x'` resolves the real partial; a rake task whose name
+  contains `do` no longer swallows its neighbours; inline-namespaced migrations
+  are extracted; mounted engines are unwrapped from `Mapper::Constraints` so
+  `mounted_path` is populated, and `Rails::Application` is no longer reported as
+  an engine.
+- **An empty vector dump no longer refuses to boot.** `woods:embed` over an empty
+  payload wrote `dimension = 0` and every later boot raised `DimensionMismatch`.
+- **Storage hardening.** Interface stubs are no longer probed with `respond_to?`
+  (B-108) in the retryable provider, builder, indexer, and ranker; Notion
+  read-only POSTs retry on a network failure; the watch daemon's stale-claim
+  reclaim checks the claim inode before removing it and falls back to an
+  exclusive create where `File.link` is unsupported; `InMemory#delete_by_filter`
+  honours array filters like `#search`.
+- **Task orphan detection compares pid namespaces, not only boot ids.** Docker
+  on Linux shares the host kernel boot id, so a host reader could judge a
+  container's task by an unrelated host pid. The producer identity now carries
+  `/proc/<pid>/ns/pid`, and a task from another namespace is left alone.
+- **Daemon claim reclaim runs under an `flock`.** A byte comparison before the
+  delete still left a read-then-unlink window where two starters could both
+  end up as claim owners; the whole reclaim-and-create loop is now one
+  critical section on a sidecar lock file, released by the kernel on death.
+- **Snapshot capture retries a locked SQLite database.** SQLite skips the busy
+  handler in its deadlock-avoidance case, so two concurrent captures could
+  fail at `BEGIN IMMEDIATE` despite `busy_timeout`. Three bounded attempts.
+- **`woods:clean` and `woods:validate` no longer raise `NameError` in a host
+  app.** `woods.rake` reached `Woods::Generation` through the extractor, which
+  those tasks never load. Caught by every woods-testbed variant.
+- **The daemon's stale-claim race guard compares bytes, not the inode.** Linux
+  reuses a freed inode for the next file in the directory, so the inode check
+  let a just-replaced live claim be deleted. Failed on CI, passed on macOS.
+- **Routes that differ only by constraint are all indexed.** The identifier is
+  `VERB /path`, qualified by request constraints when the route has any:
+  `GET /users [subdomain=api]`, `GET /users [format=json]`, `constraint=proc`
+  for a callable. Routes that still collide are numbered in route order
+  (`GET /users #2`) instead of being dropped. Unconstrained routes keep their
+  old identifier; a constrained one changes, so the clean re-index above
+  covers it.
+- **A rake task reopened in two `.rake` files is one unit**, the way Rake sees
+  it: its source carries every definition, `metadata.defined_in` lists the
+  files, and a per-file incremental run produces the same merged unit as a
+  full run. Previously the second file overwrote the first.
+- **`woods:validate` and `Resilience::IndexValidator` are one implementation.**
+  The task now runs the class, which gained the task's manifest-count,
+  unit-file, file-path, and dependency-graph checks (`app_root:` opts into
+  the file-path check).
+- **`EXPLAIN (FORMAT JSON) SELECT` is accepted.** The option list was read as
+  a call to a function named `EXPLAIN`. `EXPLAIN ANALYZE` in any form is
+  still refused.
+- **Class names are position-aware in every file-scanning extractor.** Jobs,
+  serializers, decorators, policies, Pundit policies, managers, and validators
+  took the first `class` token in the file, so `module Billing; class ChargeJob`
+  indexed as bare `ChargeJob` (and the class-based second pass then added a
+  duplicate `Billing::ChargeJob`), while the decorator scanner joined every
+  `module` token, including helpers nested inside the class. All of them now
+  go through `SourceNesting#qualified_first_class_name` (#174).
+- **Policy `evaluated_models` no longer invents models from parameter syntax.**
+  `def initialize(order, user = nil, strict: false)` produced `Nil`, `Strict`,
+  and `False` model edges; only bare positional parameters are read now.
+- **The release gate requires the booted-extraction matrix.**
+  `script/validate-release-run` did not list the `rails-matrix` CI job, so a
+  red Rails 6.0 to 8.1 row could not block a release.
+- **Spec order no longer leaks a nil `Woods.configuration`.** Four spec files
+  nil it out in `after` hooks; `spec_helper` now restores whatever each example
+  started with, which fixes two seed-dependent failures in `extractor_spec`.
+
+- **Every MCP entry point boots a payload-layout index.** The #226 layout moved
+  `manifest.json` into `payloads/gen-<N>/`, but `woods-mcp`, `woods-mcp-http`,
+  `woods-mcp-start`, the retriever's graph hydration, and the operator status
+  reporter still looked for root-level artifacts: a fresh 2.0 extract was refused
+  at boot with "Run `rake woods:extract` first", the retriever's graph store
+  hydrated empty (silent loss of PageRank and graph expansion), and status read
+  `:not_extracted`. All five now resolve through the generation pointer, with the
+  legacy flat layout still accepted.
+- **MCP `reload` no longer crashes the stdio server on pgvector/Qdrant.** The
+  reload metadata backfill guarded on `respond_to?(:each_entry)`, which the
+  vector-store interface answers true for while raising `NotImplementedError`
+  (the B-108 anti-pattern); on stdio that unwound the transport loop and killed
+  the process. The guard is now an ownership check.
+- **Wholesale replacement prunes by `(identifier, type)`.** The #225 typed-graph
+  work missed one call site: a factories (or any wholesale) re-run removing a
+  vanished unit deleted every type sharing the identifier, so a same-named
+  Scenic view's node and JSON file vanished from the index until a full run.
+  Colliding identifiers also now serialize dependents on every sharing unit and
+  carry each type's own git metadata instead of one type's history.
+- **Incremental runs abort instead of publishing a collapsed index.** When
+  payload creation failed over a payload-born index, the degrade path published
+  a near-empty flat root and redirected readers to it. Incremental and refresh
+  runs now raise without bumping the generation; full runs keep the flat
+  fallback (their write set is complete). Payload seeding also gained the
+  cross-device copy fallback, and payload pruning survives a restarted
+  generation counter.
+- **Woods artifacts are read encoding-safely everywhere.** Twelve remaining bare
+  `File.read` sites (extractor incremental path, rake validate/stats/flow, the
+  index validator) crashed with `Encoding::InvalidByteSequenceError` under
+  `LANG=C` (the documented daemon container environment) on any multibyte byte.
+  All now use `AtomicFile.read`.
+- **Extraction-family rake tasks honor `config.output_dir`.** They hardcoded
+  `tmp/woods` while the embed and export families used the configured
+  directory, so a host that set `output_dir` split its index in two silently.
+- **The watch daemon captures files changed during startup catch-up.** The
+  watcher started only after catch-up finished, so a save during a long
+  catch-up extraction was lost until the next edit. The watcher now starts
+  first. A dead container daemon's startup claim also no longer blocks a
+  host-side daemon forever (host identity is compared before trusting pid
+  liveness), and a lock-release failure after a successful cycle no longer
+  relabels the cycle as a lock failure.
+- **Retrieval ranking and budgeting defects.** RRF source merging demoted
+  strong cross-source hits into the supporting section; the framework partition
+  never fired for real graph-expansion candidates; empty metadata could shadow
+  real metadata; `:within_type_fallback` was reported for types the fallback
+  never returned; an empty supporting section stranded ~35% of the token budget;
+  keyword scores encoded arbitrary database row order as the dominant ranking
+  signal. All fixed; keyword scores now derive from matched-field counts.
+- **Console SQL validation stops rejecting English.** Body keyword scans ran
+  over string literals, so `WHERE body = 'please update the record'` was refused
+  as an UPDATE; scans now run over noise-stripped SQL while comment-hidden
+  injections stay caught. `MERGE` joined the forbidden set, recursive writable
+  CTEs get the specific error, and the stdio transport passes the table map so
+  qualified `table.column` references validate like they do over HTTP.
+- **Exporter clients treat ambiguous 503s honestly.** A 503 for a
+  non-idempotent create (Notion `create_page`, Unblocked `create_collection`)
+  can arrive from an intermediary after the origin committed, so those now
+  raise the ambiguous-outcome error instead of retrying into a duplicate; 429
+  and idempotent requests retry as before. Notion's `query_all` gained the
+  nil-cursor loop guard, and the two clients' retry budgets now agree.
+- **Session tracer fairness and hygiene.** The Redis store evicted arbitrary
+  sessions at the cap (now oldest-first, matching the file store), and
+  client-controlled header values are escaped before landing in the
+  session-context document served to agents.
+- **Storage edge paths.** Dump-capability detection uses ownership checks
+  (typed `InapplicableBackend` instead of a bare `NotImplementedError`), the
+  in-memory metadata search no longer matches on injected timestamps, dump
+  pruning can never delete the just-promoted dump after a backward clock step,
+  and the tasks store sweeps corrupt records older than the TTL.
+- **A generation's payload is published atomically (#226).** `generation.json` was
+  bumped atomically and last, but it named the output root — a directory of
+  independently-written files — so a reader refreshing mid-publish could load a
+  unit from generation N+1 beside a manifest from N. Extraction now publishes
+  into `payloads/gen-<N>/` and names that directory from `generation.json`, so
+  the single atomic write of that file commits the whole payload; a reader sees
+  one generation whole, including artifacts it had not read yet. Incremental
+  runs seed their directory from the published one with hardlinks, so an
+  unchanged artifact costs a directory entry rather than a copy. Three
+  generations are retained by default (`WOODS_PAYLOAD_RETENTION`).
+  **This changes the on-disk layout.** No re-index is required — the first run
+  after upgrading publishes a payload and reading is unaffected, since every
+  Woods reader resolves the pointer — but anything outside Woods that reads
+  `tmp/woods/manifest.json`, `tmp/woods/dependency_graph.json` or
+  `tmp/woods/<type>/*.json` directly must now read `generation.json`, take its
+  `payload` value, and resolve relative to the index directory. Files left at
+  the root by a pre-2.0 run are stale from the first payload publish onward;
+  `woods:clean` removes them.
+- **Units of different types no longer collapse onto one graph node (#225).** A Scenic
+  view `reports` and a factory `reports` are two units and the index has always written
+  them to two files, but `DependencyGraph` keyed nodes on the bare identifier, so
+  registering the second destroyed the first's reverse edges, `file_map` entry and
+  `type_index` entry. Both now coexist as typed nodes. Deleting one type's source file
+  removes that type's node and its JSON only; incremental re-extraction, git enrichment
+  and the `dependents` rewrite fan out over every type an identifier names; and the MCP
+  traversal tools follow both units' edges and report `types` when an identifier is
+  ambiguous instead of picking one silently. **No re-index is required** — the persisted
+  graph is unchanged for any index with no shared identifier, and identifiers that are
+  shared add a `variants` array that older graphs simply do not carry.
+- **Release-hardening batch (2026-08-07, #211–#218, #220):**
+  - *Embedding durability:* every pgvector/Qdrant embed run crashed at the very end and
+    discarded its work — `Indexer#persistable?` asked `respond_to?(:each_entry)`, which
+    the storage interface answers true for by definition; it now asks which module owns
+    the method (B-108, #220). Durable stores are reconciled against extraction output on
+    full and incremental runs, with the purge guard shared with the dump path (#211).
+    Checkpoint hits on durable backends are verified against the store, so switching
+    `vector_store` from `:local` to pgvector/Qdrant no longer strands unchanged units
+    (#211). Qdrant mutating point operations pass `wait=true`, so a delete is readable
+    as deleted (#220). Dimension mismatches are detected before embedding, not per-row
+    after (#214).
+  - *Extraction fidelity:* blockless factories (`factory :admin, parent: :user`) are
+    extracted; abstract models no longer enter the model-name scan (which inflated
+    `ApplicationRecord`'s PageRank); `private def` methods are no longer reported
+    public; `EventExtractor` no longer mints phantom events from non-Wisper `.on(:sym)`
+    calls; `ManagerExtractor` resolves multi-word models (`order_item` → `OrderItem`,
+    not `Order_item`) (#215).
+  - *Flow/graph determinism:* `find_node_by_suffix` is memoized (was a full-graph scan
+    per call) and resolves ambiguous short names deterministically; `case` predicates
+    are no longer misattributed as branch operations; `domain_clusters` output no longer
+    depends on registration order; vector dumps record the embedding model in the WVF1
+    header (#216).
+  - *Export hardening:* the Unblocked client redacts its bearer token in error paths and
+    describes its per-run (not "daily") budget honestly; `Retry-After` is capped at 120s
+    in both export clients; Unblocked citations use the ref recorded in the manifest
+    rather than hardcoded `blob/main`, with path segments percent-encoded; Notion aborts
+    fast on 401/403 instead of spending the whole cold sync failing per-unit (#217).
+  - *Retrieval/observability residuals:* ranking signals no longer go neutral on chunked
+    corpora (the ranker now strips chunk suffixes like every other consumer); metadata
+    keyword search is case-insensitive on both adapters with the contract pinned by
+    shared examples; `IndexReader`'s LRU is thread-safe under the HTTP transport;
+    `GapDetector` counts queries, not keyword occurrences; `RedisStore#sessions` returns
+    recent sessions rather than arbitrary ones (#218).
+  - *MCP:* the `pipeline_extract` tool loads the extractor lazily, so it works in a
+    standalone `woods-mcp` process instead of dying in the background with
+    `NameError: uninitialized constant Woods::Extractor` (B-110).
+- **The evaluation harness is runnable** (#212). `woods:evaluate` existed on no host (its
+  rake file was never loaded by the railtie), called accessors that had never existed, and
+  no adapter implemented `all_identifiers` for the baselines. It now loads, builds stores
+  through the MCP bootstrapper so evaluation reads the same persisted index that semantic
+  search serves, and ships an offline end-to-end smoke on the `:fake` provider. The
+  ground-truth taxonomy now *is*
+  `QueryClassifier::INTENTS`/`SCOPES`, so annotations compare against what the pipeline
+  actually classified (#218's open item, closed here).
+
+- **Full-gem review batch (2026-07-30): 30 defects fixed** (#183–#209 and pre-existing
+  #149, #150, #169, #170, #174–#178; see each issue for the full analysis). Highlights,
+  grouped by blast radius:
+  - *Host-app safety:* enabling the documented console-MCP mode no longer 401s the entire
+    host application (guards are path-scoped, enablement is decided at request time), and
+    the enable flags now work from `config/initializers/woods.rb` (#183).
+  - *Retrieval correctness:* type-filtered `codebase_retrieve` no longer returns empty on
+    every booted server (symbol-keyed vector metadata on boot and reload, #150); the
+    weighted ranking layer actually ranks (live keyword signal, normalized RRF, assembler
+    honors ranked order, PageRank memo invalidated on reload, #185); classifier-derived
+    target types no longer hard-filter vector search on common English words (#184);
+    framework units are no longer duplicated across context sections (#186).
+  - *Extraction fidelity:* concern inlining works for compact-style class declarations and
+    concern-defined callbacks now yield side effects, for models and (new) controllers
+    (#193, #175); a shared position-aware nesting parser fixes namespace derivation in five
+    source-parsing extractors (#174); polymorphic associations, ApplicationController
+    discovery, cache-call attribution, GraphQL inner classes, YAML anchors, Whenever
+    blocks, label-form rake tasks, and `RSpec.describe Klass, type:` test mapping all
+    parse correctly (#194, #199–#204, #176); full extraction sweeps orphaned unit files
+    so reused output dirs stop over-reporting (#177).
+  - *Pipeline integrity:* `rails_source`/`gem_source` route through the real write pipeline
+    as a Gemfile.lock-keyed whole-app extractor and `include_framework_sources` genuinely
+    gates it (#169); every index writer — `woods:clean`, the embed tasks, MCP
+    `pipeline_extract` — now takes the pipeline lock (#170); incremental extraction cannot
+    prune units on a failed extractor construction or a degraded eager-load boot (#198);
+    the write-skip optimization actually fires (#208).
+  - *Embedding durability:* a mis-pointed `woods:embed_incremental` can no longer wipe the
+    vector index (30% purge guard + empty-load refusal, #191); non-ASCII identifiers stop
+    re-embedding forever (WVF1 ids hydrate as UTF-8, #192); a single 429 no longer aborts
+    an embed run — providers are wrapped in the previously-unwired resilience layer with
+    Retry-After honored (#188); pgvector works via the documented setup path and dedupes
+    in-batch ids (#187, #181); PageRank keeps rank mass for duplicate/unresolvable edges
+    (#205); temporal snapshots stop leaking a unit set per same-SHA re-capture (#206).
+  - *Robustness:* the embed pipeline, Unblocked manifest, StatusReporter, and flow layer
+    survive `LANG=C` and torn files (`AtomicFile` everywhere, #189, #190); flow artifacts
+    are portable (relative paths, #190); a standing-down watch daemon no longer clobbers
+    the live daemon's status, and the lock heartbeat cannot resurrect a released lock
+    (#196, #197); Notion/Unblocked clients no longer retry non-idempotent POSTs on read
+    timeout (#150); Notion multi-model sync no longer corrupts the Columns database
+    (qualified `table.column` titles with legacy-page adoption, #149); metadata search
+    validates field names and escapes LIKE metacharacters (#209).
+
+- **`woods:embed_incremental` no longer discards the vectors it embeds** (B-059, #148). On the
+  `:local` and `:shared_filesystem` presets the vector store is in-memory and the dump under
+  `dumps/` is the *only* durable copy — but `Indexer#index_incremental` never called
+  `persist_snapshot`, while `process_units` advanced `checkpoint.json` regardless. Each
+  incremental run therefore embedded changed units into a store that died with the process,
+  wrote nothing to `dumps/`, and left a checkpoint claiming the work was done, so no later
+  incremental run would ever produce those vectors again: unrecoverable without a full
+  re-embed, and silent — stats reported `processed: 1`. An incremental run now hydrates the
+  store from `dumps/latest` before embedding and dumps afterwards, so the dump it writes is
+  cumulative. The invariant now enforced is that **`checkpoint.json` never advances over a
+  unit whose vector was not durably stored**: on the dump-backed path the checkpoint is
+  written only after the dump is on disk and the `latest` pointer is flipped (the interval
+  checkpoints are suppressed there — a dump is a whole-store snapshot, so there is no partial
+  durability for them to record), and a checkpoint hit is honoured only when the hydrated
+  artifact actually holds a vector for that unit. A checkpoint that ran ahead of its dump —
+  an older gem with this bug, an interrupted promote, a store swap — self-heals into a
+  re-embed and says so on stderr. A dump that cannot be read (corrupt file, dimension
+  mismatch after a model switch) warns and falls back to re-embedding everything, which is
+  the documented remedy for both. Durable backends (pgvector, Qdrant) are unaffected: their
+  `store_batch` *is* the durable write, so they keep the interval checkpoints and never
+  hydrate.
+
+- **Woods' own JSON artifacts are read as UTF-8, not as the process locale** (#164 review,
+  round 4). `AtomicFile.write` uses `binmode` so bytes land verbatim, but a plain `File.read`
+  tags the result with the default *external* encoding — US-ASCII in a container with no
+  locale set, which is a plain Docker image and exactly where the watch daemon is documented
+  to run. The daemon writes status reasons containing em dashes, so one ordinary lock
+  contention under `LANG=C` raised `Encoding::InvalidByteSequenceError` out of
+  `Watch::Status#read` (which rescued `JSON::ParserError` and `SystemCallError`, neither of
+  which that is), taking `woods:watch_status`, the hook sync's daemon-deference check and the
+  `woods_status` tool down with it until something rewrote the file with an ASCII-only reason.
+  New `AtomicFile.read` is the counterpart to `.write`; `Status`, `Generation`, the daemon's
+  pending/graph reads and `woods_status` all go through it, and `Status#read` now also rescues
+  `EncodingError`.
+- **A cycle that writes an index without publishing a generation now reports degraded**
+  (#164 review, round 4). `Extractor#publish_generation` rescues its own failures so a good
+  index is not discarded over an unwritable marker — right, but the marker *is* the freshness
+  contract, so readers kept serving the previous index while the daemon reported `running`,
+  and the next incremental could be a no-op that bumped nothing either. The daemon now
+  cross-checks that the number moved when units were written, carries the paths forward, and
+  logs at error rather than warn.
+- **`graph_analysis.json` no longer depends on registration order** (#164 review, round 4).
+  `orphans` and `dead_ends` were emitted in graph-registration order and `cycles` started its
+  DFS from the same, so a full and an incremental extraction of one tree published different
+  analysis — the opposite of what the docs claimed. The differential harness could not see it:
+  its oracle `deep_sort`ed both sides of that file before comparing. Sorting there and
+  asserting determinism here cannot both be load-bearing; the analyzer is now genuinely
+  order-independent and the oracle compares the file exactly. Guarded by a registration-order
+  rotation in `spec/graph_analyzer_spec.rb`.
+- **The harness oracle keys units by filename, not by their own contents** (#164 review,
+  round 4). `unit_snapshot` keyed on the identifier *inside* each document, so a stale file
+  whose identifier a newly-written file also carried collapsed onto one entry with
+  last-write-wins — a leftover unit read as no difference at all — and content written under
+  the wrong name compared equal while the directories plainly were not.
+- **A class removed from a file that still exists is now pruned** (#164 review, round 4).
+  Deletion keyed on the source file being gone, which cannot see this: two models in one `.rb`
+  with one deleted leaves no missing path, and class-based units register a *convention* path
+  derived from the constant name, so the second class was never attributed to the file it
+  actually lived in. Nothing in the run removed it, so it outlived every subsequent
+  incremental — a permanent divergence from a full extraction. Class-based reconciliation now
+  runs in both directions, with removal gated on the eager load having completed: on the
+  documented NameError fallback the discovery sets are known-partial, and deleting by the type
+  is a far worse failure than a stale unit. The booted harness cannot cover this — Zeitwerk
+  unloads only a file's expected constant, so the side-effect class survives the reload and
+  the in-process full extraction the oracle compares against emits it too.
+- **`RailsReloader#reload!` no longer carries an unreachable interlock wrapper** (#164 review,
+  round 4). The call was guarded by `interlock.respond_to?(:done)`, and
+  `ActiveSupport::Dependencies::Interlock` has never had a `#done` — so the guard was false on
+  every Rails version, the wrapper never ran, and the comment above it described locking that
+  was not happening. It is also not needed: `reload!` takes the unload lock itself via
+  `class_unload!` → `require_unload_lock!`. Found by writing the first test that drives the
+  real reloader instead of a double; it was stubbed in every spec and so ran on zero of the
+  seven matrix rows.
+- **New GraphQL files are indexed incrementally** (#164 review, round 3). `app/graphql` had no
+  `PathDispatcher` rule and GraphQL types are not class-discoverable, so a created type,
+  mutation or resolver routed nowhere and never entered the index, and a rename lost the unit
+  entirely — #164 gap 1 verbatim, in the one corner the gap-1 fix missed. The coverage guard
+  missed it too: `GRAPHQL_TYPES` is its own constant, so deriving the expectation from
+  `FILE_BASED` left a hole exactly the size of the bug. The guard now works by subtraction —
+  every unit type must be reachable per file, wholesale, or by class discovery, with
+  `rails_source` the one stated exception.
+- **`resolve_head_sha` no longer folds git's stderr into the SHA** (#164 review, round 3). The
+  same `capture2e` hazard as the working-tree probe one method over: a warning on an otherwise
+  successful `rev-parse` was concatenated into the value and then compared against the manifest
+  as if it were a SHA. The status spec's git stub had also gone dead when the working-tree
+  probe moved to `capture3`, so real git was running against `/tmp` in those examples.
+- **Startup catch-up now notices deletion-only downtime** (#164 review, round 2). The
+  reconciliation scanned mtimes of files that exist, so a file deleted while no daemon was
+  running left no trace: the daemon logged "index is current at startup" and the ghost units
+  survived until the next unrelated event. Catch-up now also checks the graph's registered
+  paths for files gone from disk and, if any, runs one cycle with an *empty* change set — the
+  extractor's bounded sweep reaches the ghosts, with the bounds that keep nominal paths
+  (Rails < 7.1 `SchemaMigration`) safe from authoritative deletion.
+- **The drain guard is an atomic test-and-set** (#164 review, round 2). The re-entrancy guard
+  was a check-then-act boolean — the exact race it guarded against: two `listen` callback
+  threads could both read `false` before either wrote `true` and run two overlapping drain
+  loops. It is now `Mutex#try_lock`; the refused caller's paths are already in the pending set,
+  so the winning loop picks them up and nothing is lost.
+- **`IndexReader` freshness bookkeeping is safe under a threaded transport** (#164 review,
+  round 2). The generation check-and-reload was unguarded check-then-act, and the pin was a
+  boolean — under `woods-mcp-http`, whose tool handlers run on the Rack server's request
+  threads, two concurrent reads could double-reload or drop each other's caches mid-sequence,
+  and the first of two overlapping `with_pinned_generation` blocks to finish unpinned the
+  reader for both. The check-and-reload now runs under a per-reader mutex and pins are
+  refcounted: invalidation resumes when the *last* pin releases.
+- **A cycle that can't land its work no longer loses it** (#164 review). Lock contention
+  already carried its paths into the next cycle; a *failed reload* did not. Saving a valid
+  `post.rb` while `user.rb` sat half-typed produced one app-wide reload failure covering both,
+  and when `user.rb` was fixed the event named only `user.rb` — so `post.rb`'s change never
+  reached the index at all. Failed reloads and raising extractions now carry forward too, and
+  the drain lives inside `Daemon#process`, so an embedded host gets the same retry behaviour
+  `#run` does.
+- **A quiet daemon is no longer declared dead** (#164 review). `Status#alive?` disbelieves a
+  record older than 15 minutes and only cycle boundaries wrote one, so a healthy daemon
+  watching a worktree nobody was typing in read as stopped — and every caller that stands down
+  for a live daemon started contending for its lock instead. A heartbeat now re-stamps the
+  last published record every 5 minutes, republishing `degraded` as `degraded` rather than
+  claiming recovery.
+- **The daemon reconciles changes that predate it** (#164 review). It only ever reacted to
+  events it personally witnessed, so the documented hook pattern — start a daemon, then sync —
+  stood the sync down over changes the fresh daemon had never seen. `Daemon#run` now
+  reconciles against the index's own watermark (`generation.json`'s mtime) before waiting for
+  its first event. `woods:incremental` also no longer stands down for a *degraded* daemon:
+  alive but not updating is not coverage.
+- **`woods:refresh` serializes with the other writers** (#164 review). It rewrites the whole
+  dependency graph and took no lock, so a refresh racing a daemon cycle silently discarded the
+  other's work and then bumped the generation over it — atomic writes don't help, because each
+  write is individually intact and the *set* is not. It now runs under `PipelineLock` like
+  `woods:extract` and `woods:incremental`, and records its own generation reason instead of
+  masquerading as an incremental run.
+- **The polling watcher no longer loses a same-second write** (#164 review). Snapshots
+  truncated mtime with `to_i`, so a second write inside the same second was invisible
+  permanently — there is no later event to catch it — and save-then-formatter at the default
+  1s interval is entirely ordinary. Snapshots now carry full-resolution mtime plus size.
+- **`IndexReader` no longer misses a same-size generation bump** (#164 review). The freshness
+  signature was `[mtime, size]`, and equal size is the daemon's steady state (reason
+  `"incremental"` every cycle). On a coarse-mtime filesystem — including the volume-mounted
+  Docker deployment the Index Server is documented for — two bumps in one tick were
+  indistinguishable and the reader served a stale index indefinitely. The inode is now part of
+  the signature, which `AtomicFile`'s rename-per-write guarantees moves.
+- **A clean working tree no longer reports dirty** (#164 review). `resolve_working_tree_status`
+  used `capture2e`, folding git's stderr into the porcelain output — so any warning on an
+  otherwise successful run (a stale `index.lock` notice, `core.fsmonitor` chatter) read as
+  uncommitted changes, and the fingerprint tracked the warning rather than the code.
+- **Index artifacts are written atomically.** `dependency_graph.json`, `manifest.json`,
+  `_index.json` and every per-unit file went through plain `File.write`. With a resident daemon
+  writing while resident MCP readers read, a reader could catch a truncated file mid-write;
+  all of them now route through `Woods::AtomicFile`.
+- **A class-based file moved between autoload directories is no longer dropped for a run**
+  (#164 review). Reconciliation ran before pruning, so a file moved with its constant unchanged
+  still looked "known" and was not re-extracted, then was pruned for its vanished path.
+  `extract_changed` now reconciles once more after pruning.
+- The `listen` backend degrades instead of dying: only its setup is wrapped in the
+  `WatcherError` rescue, so a failure raised once it is merely parked (including from the
+  extraction inside a callback) is no longer relabelled "failed to start", and inotify
+  exhaustion falls back to polling. Both watchers also honour a `stop` that races startup.
+- The storm threshold counts only paths the reload policy considers actionable — sixty edited
+  markdown files plus one model is a one-model change, not a storm.
+
+- **Token estimates now describe the file that is written.** `ExtractedUnit#estimated_tokens`
+  measured `metadata.to_json`, which with ActiveSupport loaded applies HTML-safe escaping (`>`
+  becomes `\u003e`), while the unit file is written with `JSON.generate`. Any unit whose
+  metadata contained a lambda scope was therefore indexed with a token count that described a
+  document that was never written — and differed depending on whether a full or an incremental
+  run last touched it. Both sides now measure `JSON.generate`.
+
+- **Incremental extraction is now equivalent to a full extraction** (#164, phase 0). Five
+  confirmed correctness gaps in `woods:incremental` are closed. They mattered most in an
+  incremental CI chain, where the previous graph is restored and `woods:incremental` runs per
+  merge: a missed unit propagated forward run over run instead of being erased by the next
+  full rebuild.
+  - **New files are indexed.** Changes routed only through `DependencyGraph#affected_by`,
+    which resolves a path via the graph's file map — populated only from already-registered
+    units — so a file that did not exist at the last extraction routed nowhere and was
+    silently ignored. A new `Woods::PathDispatcher` supplies the missing direction, path →
+    extractor, for file-based types; class-based types (models, controllers, mailers,
+    components, channels) are reconciled against each extractor's own runtime discovery set,
+    now exposed as `#discoverable_classes`.
+  - **Deleted files no longer leave ghosts.** Units whose source file has vanished are pruned
+    — unit JSON removed, graph node unregistered, reverse edges withdrawn, type index
+    regenerated. Deletions named in the change set are authoritative; a sweep over registered
+    paths catches callers whose change set omits them. A rename resolves to delete-plus-add.
+  - **Files defining several units reconcile as a whole.** `DependencyGraph`'s file map is now
+    multi-valued (`path => Set<identifier>`), so a task removed from a multi-task `.rake` file
+    is dropped rather than left behind. Graphs written before this load unchanged.
+  - **Whole-app unit types refresh.** `route`, `middleware`, `engine`, `scheduled_job`,
+    `state_machine`, `factory`, `event`, and `database_view` are re-run wholesale when their
+    trigger paths change, instead of being skipped while the run still rewrote the manifest
+    and zeroed `staleness_seconds`. A routes change also re-extracts the types that embed the
+    route table (controllers, mailers, components, view templates).
+  - **Derived data no longer drifts.** Incremental runs recompute `graph_analysis.json`, and
+    refresh each affected unit's `dependents` list and `metadata.git` — all previously
+    full-extraction-only. A run that extracts nothing now leaves the manifest timestamp alone
+    rather than reporting the index as freshly synced.
+
+- **Assignment-form multi-line conditionals no longer unbalance depth
+  tracking.** `block_opener?` counted `if`/`unless` only in line-leading
+  position while `case`/`begin`/`do` matched anywhere, so
+  `value = if cond … end` popped a frame that was never pushed and closed
+  the enclosing construct one `end` early. In a `.rake` file every task
+  after the conditional lost its namespace prefix (wrong identifiers, a
+  public contract); in `SourceNesting` a sibling class after the
+  conditional lost its qualification (absorbed by governed naming for
+  conventional paths); in the factory parser the enclosing factory
+  completed early and attributes after the conditional were dropped.
+  `if`/`unless` now also count directly after an assignment operator
+  (`value = if x`, `@memo ||= unless y`), still excluding trailing
+  modifiers and self-balancing one-liners, in all three copies of the
+  rule (`RakeTaskExtractor`, `SourceNesting` — which
+  `StateMachineExtractor` shares — and `FactoryExtractor`);
+  `SemanticChunker` already counted assignment position. Surfaced by the
+  v2 downstream validation after the comment/string neutralization fix
+  removed a compensating miscount.
+
+- **An alias can no longer name a protected output header (CON-1).**
+  `console_query` accepted `select: ["key", "value", "id AS value"]`; the
+  duplicate header made the positional redactor mask the aliased cell and
+  return the real EAV secret in cleartext (`id AS key` disarmed masking
+  entirely). A fourth select refusal now rejects any `AS` alias whose name
+  collides with a `console_redacted_columns` or `console_redacted_key_values`
+  column, case-insensitively. Defense-in-depth: the positional redactor now
+  treats a duplicated key or value header as ambiguous and masks every cell
+  under a value-named header unconditionally instead of letting a
+  last-index-wins lookup pick the shadow. The alias/aggregate refusals also
+  compare configured column names case-insensitively (CON-3/R1-6), matching
+  the predicate-side refusals. `console_sql` was already immune (its
+  reference scan sees the alias token) and is unchanged.
+- **`woods:incremental` refuses to run without a baseline index (CORE-2).**
+  Against an output directory with no published generation and no dependency
+  graph — a failed CI cache restore, a typo'd `WOODS_OUTPUT`, a first run on
+  a fresh runner — `extract_changed` computed an empty blast radius over the
+  empty graph, dispatched only the diffed paths, and silently published a
+  near-empty index as generation 1 that nothing self-heals until a full
+  extraction. `prepare_incremental_run` now raises a typed
+  `Woods::ExtractionError` naming `woods:extract` (the task exits non-zero);
+  the watch daemon keeps its existing missing-generation → full-extraction
+  posture, and an embedding caller that already holds a populated in-memory
+  graph still runs. `woods:refresh` gets the same guard.
+- **Per-path prune skips by (identifier, type), not bare identifier
+  (CORE-1).** Two dispatch rules can claim one path (`app/policies` is
+  claimed by the policies and pundit_policies rules) and mint the same
+  identifier for different unit types; when an edit made one of them stop
+  producing, the surviving identifier shielded the stale sibling-type node
+  from the prune — a permanent full/incremental divergence. The #225 typed
+  discipline now covers `prune_path_leftovers` too.
+
+- Trailing `#` comments no longer steer `SourceNesting`'s depth tracking. A comment ending in the
+  word "end" (`module Api # rename at the end`) made the wrapper look self-terminated and dropped
+  the namespace from the identifier; a comment containing `do`/`for` opened a phantom frame that
+  swallowed a real `end` and leaked a closed wrapper onto a later top-level class (EXTA-1).
+- `SourceNesting` keeps non-ASCII constant names whole (`class Café` was captured as `Caf`) and
+  skips declarations inside `=begin`/`=end` block comments (EXTA-14).
+- `RakeTaskExtractor` no longer counts block keywords found in comments, string literals, or
+  heredoc bodies. A `# do not touch production` inside a task inflated depth with no matching
+  `end`, so later namespaces inherited a stale prefix (`other:third` indexed as
+  `cleanup:other:third`) and a task swallowed the next one's lines; a heredoc line reading
+  `end of the road` truncated a task body and lost its dependency edges (EXTB-1).
+- `FactoryExtractor` no longer reads block keywords inside attribute strings. Two of them in one
+  factory (`title { "things to do" }`, `note { "walk for a while" }`) left the factory unclosed at
+  EOF and the unit was dropped from the index entirely (EXTB-2).
+- `SemanticChunker`'s line-depth heuristic no longer treats `=begin`/`=end` as a block opener. Each
+  block comment added a permanent +1 to the depth count, so the enclosing method never closed and
+  every later method was appended to its chunk (STO-3).
+- A blockless AASM/`state_machines` `event :noop` is emitted immediately instead of being replaced
+  unseen by the next event, and event depth is clamped at zero so an unbalanced `end` can no longer
+  disable parsing for every event that follows (EXTB-17).
+- Service, job/worker, and mailer dependency edges keep their namespace. Since G-1 a namespaced
+  unit's identifier is fully qualified, so `Billing::ChargeService.call` recorded an edge to
+  `ChargeService` — matching no node, invisible to `dependents`, PageRank, and the incremental
+  blast radius (EXTA-2).
+- One shared enqueue pattern is now used by the dependency scanner, `JobExtractor`, and
+  `CallbackAnalyzer`, so all three agree: Sidekiq `*Worker` classes and
+  `SyncJob.set(wait: …).perform_later` chains produce `:job` edges everywhere (EXTA-4).
+- `CallbackAnalyzer` detects `self.col ||=`, `self.col +=` and the other operator-assignment forms
+  as column writes — `self.token ||= SecureRandom.uuid` reported none — and no longer reads
+  `self.col =~ /re/` as a write (EXTA-6).
+- `CallbackAnalyzer` neutralizes comments and string bodies before its regex scans, so
+  `logger.info "self.status = pending"` and a commented-out assignment no longer report a column
+  write (EXTA-8).
+- `EventExtractor` recognizes Wisper's canonical paren form `broadcast(:event, …)`; the
+  whitespace-only regex registered no publisher, and with no subscriber naming the event the event
+  unit did not exist at all (EXTB-3).
+- Quoted namespaced rake dependencies keep their namespace: `task deploy: 'assets:precompile'`
+  recorded `precompile` and pointed the edge at a task that does not exist (EXTB-9).
+- Whenever commands in single quotes are recognized: `runner 'CleanupJob.perform_later'` yielded
+  command type `:unknown`, no job class, and no `:job` edge (EXTB-12).
+- Environment-nested schedule YAML unwraps the section for the current `Rails.env` (falling back to
+  the first) instead of whichever environment happens to be listed first (EXTB-19).
+- `retry_config[:retry_on]` keeps namespaced error classes: `retry_on Net::OpenTimeout, wait: …,
+  attempts: …` recorded `Net` and lost both `wait` and `attempts` (EXTA-10).
+- A class-discovered job whose source cannot be resolved records a nil `file_path` instead of a
+  fabricated `app/jobs/<name>.rb`. The fabricated path entered the graph's `file_map` and the next
+  incremental run's safety-net sweep deleted a unit every full extraction emits — the B-070/#171
+  GraphQL shape, reproduced for jobs (EXTA-3).
+- GraphQL per-field complexity is attributed to the field that declares it; the match crossed
+  declarations, so a field with no complexity absorbed the next field's and the real owner lost it
+  (EXTB-8).
+- Strong-params capture accepts the fluent chain style — `params.require(:post)` with `.permit(…)`
+  on the following line, and the fully fluent `params` / `.require` / `.permit` form — which the
+  multi-line (M2) fix did not reach (EXTA-5 / R1-2).
+- `permitted_params` now lists every top-level key, hash-form keys included, and excludes nested
+  leaves: `permit(:title, tags: [], meta: {seo: [:keyword]})` yields `title, tags, meta` where it
+  used to yield `title, keyword` (EXTA-12 / R1-3).
+
+- **`unless` no longer inverts every flow document (EXTB-4).** `Prism::UnlessNode`
+  shared `convert_prism_if` and landed its body in the *then* slot, so
+  `woods:flow`, the precomputed `flows/*.json`, and the MCP flow tools stated the
+  opposite of what the code does for every `unless` — including the modifier form.
+  The parser now swaps the then/else slots for `unless`, which makes the emitted
+  `if <predicate>` reading exact; the parser-gem branch already normalized it that
+  way.
+- **Call arguments are walkable AST children (EXTB-5).** Arguments were flattened
+  to source text, so anything nested in an argument list was invisible to every
+  tree walker: `private def hidden; …; end` lost the whole method (no
+  `ruby_method` unit, no `extract_method_source`, no dataflow), and `foo(Bar.baz)`
+  never produced a `Bar.baz` call site. Argument nodes now become children,
+  appended after the receiver; the `arguments` text field is unchanged.
+- **Call sites in a block call's receiver chain are recorded (EXTB-16).**
+  `User.where(active: true).each { … }` recorded `each` but not `where`, while the
+  same chain without a block recorded both. `CallSiteExtractor`'s `:block` branch
+  now recurses into the send's own children, matching the non-block path.
+- **A predicate-less `case` keeps its first `when` branch (EXTB-15).** The
+  predicate slot is now positional (a nil hole when absent), mirroring the L2 fix
+  for `:if`. `handle_case`'s `drop(1)` used to consume the first branch and render
+  its condition as the literal word "when".
+- **`MermaidRenderer#render_dependency_map` renders edges again (EXTB-6).**
+  `DependencyGraph#to_h` has emitted `[{target:, via:}]` hashes since the via
+  migration; the renderer iterated them as bare targets, so `nodes.key?(hash)` was
+  always false and every edge was silently dropped — the committed
+  `docs/self-analysis/dependency-map.md` shipped ~2,400 nodes and zero
+  dependencies. Edges are normalized through `DependencyGraph.normalize_edges`
+  (legacy bare strings still load) and now carry `|via|` labels. The
+  `docs/self-analysis/` artifacts are regenerated.
+- **`GraphAnalyzer#domain_clusters` is order-free (EXTB-7).** Unnamespaced units
+  were assigned to clusters one at a time, each assignment mutating the target
+  before the next unit was scored, so a unit whose only connection was *another*
+  unnamespaced unit joined a cluster only when that other unit was registered
+  first — full and incremental runs register in different orders, so the MCP
+  `domain_clusters` tool could answer differently for identical trees. Assignment
+  now scores every pending unit against one pre-round membership snapshot and
+  applies the round together, iterating to a fixed point within
+  `ORPHAN_ASSIGNMENT_ROUNDS`. Closes the residual hole in the #216/B-103
+  determinism claim.
+- **`pagerank` survives a graph carrying edges for a node-less source
+  (EXTB-10).** `from_h` accepts (and `registered_types` relies on) that shape, but
+  `pagerank_step` read `scores[src]` for every reverse source and raised
+  `NoMethodError: undefined method '*' for nil` out of the incremental PageRank
+  refresh. A phantom source now contributes 0.0.
+- **`DependencyGraph#to_h` no longer hands out the live edge arrays (EXTB-11).**
+  The documented "returns a dup so callers can't pollute the cached hash" was
+  shallow: `to_h[:edges][id]` was the very Array `@edges` holds, so appending to it
+  changed what `dependencies_of` answered. Edge arrays are copied element-wise,
+  and each snapshot is detached from the memo.
+- **`change_table` columns are extracted from migrations (EXTB-18).**
+  `change_table :orders do |t| t.string :notes end` produced no `columns_added`
+  entry and left `orders` out of `tables_affected` (so no `:table_name` model
+  edge). `change_table` joins `TABLE_OPERATIONS` and the three block scanners
+  accept both openers.
+- **STI models sharing a table no longer churn the Notion Columns database
+  (EXP-1).** Column pages are titled by *table*, so two models emitted the same
+  `users.id` title with a different `Table` relation and a different content hash,
+  each run PATCHing the page back — two API calls per shared column, forever, with
+  the relation pointing at whichever model synced last. Columns are now grouped by
+  physical table before syncing: one page per physical column per run, validations
+  unioned, and the `Table` relation lists every owning model's page in a
+  deterministic order. The #149 distinct-table behavior is unchanged.
+- **Notion rich_text is truncated in UTF-16 code units (EXP-2).** Notion's 2000
+  limit counts UTF-16 units, not Ruby characters, so text containing non-BMP
+  characters (emoji in a header comment is enough) shipped payloads up to twice
+  the limit and the unit failed with `Notion API error 400` on *every* run.
+  Truncation now walks whole characters accumulating 1 or 2 units, never splitting
+  a surrogate pair.
+- **Notion "Last Schema Change" is the migration's date, not the extraction's
+  (EXP-3).** `latest_changes` keyed on `extracted_at`, which a full extraction
+  re-stamps for every unit — so every table read "changed today" and every Data
+  Models page was rewritten to say so. The migration's own `migration_version`
+  stamp (`%Y%m%d%H%M%S`, already in the same metadata hash) is preferred;
+  `extracted_at` remains the fallback when it is absent or unparseable.
+- **Exporters pin the index generation (EXP-5).** `IndexReader` self-refreshes on
+  every public accessor when the published generation moves and assigns pinning
+  responsibility to direct callers; none of the three exporters pinned, so an
+  extraction publishing mid-export produced a mixed-generation export (silently:
+  Notion column pages created with no `Table` relation, Obsidian's
+  "byte-identical across runs" contract broken, sweep and purge sets computed
+  against a mixture). `Notion::Exporter#sync_all`, `Unblocked::Exporter#sync_all`
+  and `Obsidian::VaultExporter#export_all` now run inside
+  `reader.with_pinned_generation` when the injected reader supports it.
+- **The Obsidian stale-note sweep survives glob metacharacters in the vault path
+  (EXP-6).** The vault path was interpolated into the glob pattern, so `[`, `]`,
+  `{`, `}`, `*` or `?` in a folder name (`my [work] vault`) made `managed_notes`
+  match nothing — the sweep saw zero managed notes and deleted nothing, forever.
+  The glob now runs with `base:` so the path is never pattern syntax.
+- **NameMapper re-checks its hashed candidate and sanitizes Windows device names
+  (EXP-9).** The collision-hash suffix was inserted into the taken set without
+  being re-checked, so a hash prefix colliding with an existing literal basename
+  put two notes at one path (last writer wins, one id lost from the inverse map);
+  the digest slice now widens until the basename is free. `CON`, `PRN`, `AUX`,
+  `NUL`, `COM1-9` and `LPT1-9` (any case) are prefixed, so a class named `Aux` no
+  longer produces a note Windows cannot create.
+- **A columns-only Notion configuration syncs its columns (EXP-11).** `sync_all`
+  required *both* database ids before running the column sync, so a columns-only
+  configuration returned all-zero stats in silence — indistinguishable from
+  breakage, and contradicting the documented "the other sync is skipped
+  gracefully". The sync now runs with no parent pages (`ColumnMapper` already
+  tolerates that) and says on stderr why the `Table` relation is missing.
+- **`context_completeness` is no longer recall under a second name (EXP-10).**
+  The evaluator passed `expected_units` as both the relevant and the required set,
+  so `mean_context_completeness == mean_recall` always and a threshold keyed on it
+  silently gated on recall. `QuerySet::Query` gains an optional `required_units`
+  annotation (loaded, saved, and validated as a subset of `expected_units`);
+  queries without it keep the previous value.
+- **`flow_document.rb` and `evaluation/report_generator.rb` load standalone
+  (EXTB-13, EXP-8).** Both named `Time#iso8601` (and `FileUtils` in the report
+  generator) without requiring them; only a transitive `require "woods"` masked it.
+  Missing requires added, with a subprocess smoke spec.
+
+- **`reload` no longer degrades an index that has never run `woods:embed` (MCP-1).**
+  A retriever-wired server with no promoted dump used `required: true` against a
+  nil dump, so `reload` aborted the transaction, answered `degraded_index`, and
+  stamped `bootstrap.reload_failure` into `woods_status` — clearable only by a
+  successful reload, which was impossible until an embed ran. Boot hydrates that
+  shape with `load_or_empty`; reload now agrees and answers a zero-count success.
+  A dump that IS promoted but incomplete still fails closed.
+- **`reload` refreshes the reader on every zero-count no-op (MCP-2).**
+  `Bootstrapper.reload_stores!`'s early returns (no retriever, no swap target, no
+  artifact, durable stores, no promoted dump) skipped `reader.reload!`. On a flat
+  (pre-2.0) index the reader never self-refreshes, so `reload` is its only
+  freshness path — and precisely there the tool reported `reloaded: true` with the
+  retired manifest. Every early return now runs the reader's exclusive reload
+  first. Both packaged executables always wire a reloader, so the tool's
+  non-reloader fallback was never the path in a shipped process; the spec that
+  covered it now exercises the real wiring.
+- **A raising pipeline-lock acquire no longer wedges `pipeline_extract` /
+  `pipeline_embed` for the life of the process (MCP-3).** On an index directory
+  the server cannot write (a read-only Docker mount), `PipelineLock#acquire`
+  raises `SystemCallError` instead of returning false. The raise escaped between
+  `pipeline_start` and the background hand-off, leaking the in-process in-flight
+  flag — every later call answered `already_running` — and reached `ToolContract`
+  as a nested `SystemCallError`, which relabeled it `corrupt_artifact` ("An Index
+  artifact is unavailable or malformed"), the wrong diagnosis for a permissions
+  failure. The window is now owned by one guarded region that answers a typed
+  `lock_unwritable` error and releases both the on-disk lock and the in-process
+  slot unless the run was handed off.
+- **An orphaned task from a producer this host cannot judge now expires (MCP-4).**
+  A `working` record whose `producer_identity` names a foreign boot id or pid
+  namespace was left alone forever — correct for a cross-machine producer over a
+  shared filesystem, wrong for the far more common reading of a boot-id mismatch
+  on the same store: this machine rebooted mid-run, so the producer is dead by
+  construction and the client polled `working` with no TTL backstop. Foreign
+  producers are now believed on age alone, up to
+  `Tasks::Store::FOREIGN_PRODUCER_GRACE_SECONDS` (24h from `updated_at`), then
+  resolved to `failed`. Younger foreign records are untouched.
+- **Bounded staleness under sustained overlapping requests (MCP-5).**
+  `IndexReader` only attempted a refresh when a pin arrived at depth 0, so on a
+  threaded transport with continuous traffic — several agents against one
+  `woods-mcp-http`, the deployment stateless mode exists for — the depth never
+  reached zero and a retired generation was served indefinitely, silently. A pin
+  arriving after the generation moved while pins are held now registers as a
+  refresh waiter: it gates new pin entries (the same way an exclusive reload
+  does), waits for the held pins to drain, refreshes, and admits the queue.
+  Nested pins and the reads of an already-held pin are exempt, so the drain
+  always completes.
+- **Store failures inside the retrieval pipeline surface as the typed store
+  error (MCP-6).** M8 wrapped the three lookups the Retriever performs itself,
+  but the store reads carrying most query traffic happen inside the pipeline
+  components (the ranker's and assembler's `find_batch`, every executor store
+  call). Those raised raw, so the SDK reported "Internal error calling tool
+  codebase_retrieve" or `ToolContract` relabeled an IO-flavored cause as
+  `corrupt_artifact`. The pipeline components now read through facades that
+  translate any store failure into `Woods::Retriever::StoreError` naming the
+  failing store, which `codebase_retrieve` already maps to
+  `degraded_index (phase: 'query')`. `build_structural_context` no longer
+  swallows a store failure to `nil` — the last swallow-to-empty on the query
+  path.
+- **A payload directory without its `manifest.json` degrades instead of hanging
+  (CORE-4).** The reader's retention-pin loop retried on `ENOENT` by reloading
+  the generation; with the pointer unchanged, every iteration took the identical
+  path with no sleep and no cap, spinning the request thread at 100% CPU. A
+  second consecutive `ENOENT` for the same expected directory now proceeds
+  unpinned, matching the flat-index branch.
+- **`search` rejects an unknown `fields` value (MCP-9).** `fields: ["sourcecode"]`
+  used to return a clean empty result with nothing saying the selector was
+  meaningless. The schema now enumerates `identifier`, `metadata`, `source_code`
+  and `ToolContract` enforces it.
+- **A whitespace-only `OPENAI_API_KEY` is treated as absent on the `woods.json`
+  path (R1-5).** The resolver-default path already stripped before deciding; the
+  stored-config path did not, so `OPENAI_API_KEY=" "` wired an OpenAI provider
+  with a blank key and failed per request instead of raising the one-line
+  `MissingCredential` message.
+
+- **Console MCP `console_sql` is validated once, with the host adapter's dialect.**
+  The registered tool handler pre-validated with a dialect-blind `SqlValidator.new`
+  (the conservative MySQL+PostgreSQL union) before the executor ever ran, so on a
+  MySQL host a statement like `WHERE body = 'customer\'s request for update'` was
+  rejected as a row-lock clause and the PR-248 dialect-aware acceptance path was
+  dead on both real transports. The handler now only builds the request; the
+  executor still raises `SqlValidationError` for anything it refuses, so no gate is
+  lost. (CON-2)
+- **Console audit log redacts before it truncates.** `AuditLogger` cut a >16 KiB
+  field at `MAX_FIELD_CHARS` and *then* ran the credential scanner, so a secret
+  straddling that boundary was split, no longer matched the scanner's
+  word-boundary-anchored patterns, and its cleartext prefix landed in the JSONL.
+  Redaction now runs over the whole value first. `#entries` also reads UTF-8
+  explicitly (the truncation notice itself carries a multibyte ellipsis). (CON-5)
+- **Unexpected exceptions inside the Console dispatch pipeline render as sanitized
+  tool errors.** `DispatchPipeline#call` rescued five known error classes; anything
+  else (a renderer `NoMethodError`, an encoding oddity, a handler defect) escaped
+  into the `mcp` gem's handling of a raising tool block, which can echo
+  `Class: message` to the client. Such failures now answer with the executor's
+  sanitized shape — the tool name only, details logged server-side via
+  `console.dispatch.unexpected_error` — still routed through the credential scan.
+  (prior-audit L9)
+- **`exe/woods-console` leases a database connection per request.** The stdio
+  server passed `SafeContext.new(connection: ActiveRecord::Base.connection)`,
+  pinning one connection for the process lifetime, so every tool call failed after
+  a failover or a `wait_timeout` recycle until the client restarted. It now passes
+  `pool:`, matching the HTTP path. (prior-audit L10)
+- **Console executor error text is credential-scanned before the `Rails.logger`
+  write.** The client response for an unexpected execution error was already
+  sanitized to the class name, but the log line carried the adapter's own message —
+  and PG/Mysql2 errors embed the rejected SQL and constraint literals, so a secret
+  in a WHERE clause reached the server log unscanned. (prior-audit L11)
+- **The missing-Console-token boot warning names the transport it applies to.**
+  "Console MCP requests will be refused (401) until one is set" has no transport
+  qualifier, but the 401 belongs to the HTTP stack; the stdio transport neither
+  sends nor consumes a bearer token. The warning now says so, and that a stdio-only
+  setup still works. The production raise is unchanged. (prior-audit G-3)
+- **Four more Woods JSONL/JSON readers no longer depend on the process locale.**
+  `Feedback::Store#all_entries`, `SessionTracer::FileStore` (history append, read,
+  and the legacy-file merge), and `Evaluation::QuerySet.load`/`#save` used bare
+  reads, so under `LANG=C` the first non-ASCII entry raised
+  `Encoding::CompatibilityError` and — because the poison line stays on disk while
+  writes keep succeeding — permanently took down `retrieval_explain`,
+  `retrieval_suggest`, GapDetector, and the `session_trace` MCP tool. All read
+  UTF-8 explicitly now, per the `AtomicFile.read` contract. (INF-3, R1-1, EXP-7)
+- **`woods:embed`, `woods:embed_incremental` and `woods:notion_sync` exit 1 when
+  they report errors.** They printed `Errors: N` and exited 0, so a revoked API
+  key, a full vector store, or a Notion 401 on every page left CI green while the
+  embedding index or the Notion database went stale. They now fail like their
+  siblings `woods:unblocked_sync` and `woods:obsidian`. (INF-4 / EXP-4)
+- **A missing `git` binary is a decision, not a crash, in `woods:incremental`.**
+  `Errno::ENOENT` out of `Open3.capture3` killed the task with a backtrace before
+  the tail-M1 decision matrix ran, so a daemon-covered tree that should have stood
+  down failed its hook instead. The helper now returns the same `[nil, failure]`
+  shape with `git unavailable: …`. (INF-12)
+- **`woods/session_tracer/redis_store` loaded standalone raises the documented
+  error.** Without `lib/woods.rb` loaded first, the missing-redis-gem guard raised
+  `NameError: uninitialized constant …SessionTracerError` instead of the actionable
+  "add `gem \"redis\"`" message. (INF-8)
+- **`woods/feedback/store` requires `time`.** `Time#iso8601` only exists after
+  `require 'time'`; in the MCP server process unrelated requires masked it, so a
+  narrow entry point got a `NoMethodError` from `record_rating`. (INF-9)
+
+- **STO-1**: A genuine pre-rename `codebase_index` database no longer wedges `Db::Migrator#migrate!` permanently. The legacy gem recorded applied versions in `codebase_index_schema_migrations`, which nothing renamed, so `ensure_table!` created an empty ledger, 001-005 re-ran against a live legacy database and 006's `ALTER TABLE codebase_units RENAME TO woods_units` then failed against the table 001 had just created — and failed identically on every later run. `SchemaVersion#ensure_table!` now adopts the legacy ledger first (guarded, idempotent; when both tables exist the `woods_` one wins and the legacy table is left in place with a warning). The spec fixture that recorded legacy versions in a table the legacy gem never had is corrected.
+- **STO-2**: Durable-store reconciliation no longer deletes non-Woods Qdrant points. A collection shared with another writer had every foreign point read as "vanished" on each `woods:embed`, and silently deleted whenever the vanished fraction stayed under the 30% purge guard. `Qdrant#each_id` now skips points with no `woods_identifier` payload (they are unattributable to Woods), and `Indexer#vanished_durable_identifiers` additionally ignores ids shaped like a canonical UUID or a native integer point id — shapes Woods never mints as an identifier.
+- **STO-4**: `Snapshotter::Metadata` raises the typed `Woods::MCP::UnsupportedArtifact` for a truncated or malformed `metadata.msgpack` and for a header missing or mistyping `schema_version`/`record_count`, instead of a raw `EOFError`/`NoMethodError`. Mirrors the M3/M10 guards the Vector twin already carried.
+- **STO-5**: `woods/storage/qdrant`, `woods/resilience/circuit_breaker` and `woods/cache/cache_middleware` load in isolation again. The first two were missing the repo's `class Error < StandardError; end unless defined?` shim; the third included `Embedding::Provider::Interface` without requiring it. `spec/load_order_spec.rb` grew a require-in-isolation sweep over the storage/cache/embedding entry files.
+- **STO-6**: `Builder` no longer crashes with `NoMethodError` when an injected embedding provider implements only `#embed`/`#embed_batch` and a durable vector store is configured with an explicit `vector_store_options[:dimensions]`. `vector_dimensions` is now probed like `safe_max_input_tokens` (`respond_to?` plus `rescue NotImplementedError`), which makes the documented "built without an embedding provider" fallback reachable.
+- **STO-8**: `MetadataStore::InMemory` and `MetadataStore::SQLite` agree on non-string values. InMemory now normalises stored metadata through the same JSON round-trip SQLite performs (symbol keys *and* values become strings, all the way down) and builds field-scoped search haystacks the way `json_extract` does, instead of leaking Ruby `Hash#to_s` syntax such as `=>` into the haystack. The shared "hardened search" examples grew hash/array-valued field queries and value round-trips; the spec that pinned InMemory's divergent symbol round-trip under a parity title is flipped.
+- **STO-9**: `MetadataStore::SQLite#store` rejects a blank `type` (`''` or whitespace) as well as a missing one — it fabricated exactly the empty type column L22 was fixed to prevent.
+- **STO-11**: The Indexer's prune guards use the `implements_own?` ownership check rather than `respond_to?(:delete)`, which was always true because `VectorStore::Interface` defines `#delete` as a raising stub (B-108). `reconcilable?` now requires an own `#delete` too, so an adapter that can be enumerated but not deleted from completes the run instead of raising `NotImplementedError` mid-sweep.
+- **STO-13**: `Util::UUID5.name_bytes` hashes an `ASCII-8BIT`-tagged name by its bytes instead of raising `Encoding::UndefinedConversionError` on high bytes. BINARY is "already bytes", not an encoding to transcode from — the method's own contract.
+- **STO-15**: The OpenAI provider's in-adapter retry rescues `Net::ReadTimeout`, matching Ollama. `Net::ReadTimeout` descends from `Timeout::Error`, not `IOError`, so a read timeout escaped both the retry and the `RequestError` typing.
+- **INF-1**: The watch daemon's polling fallback rebuilds the watcher with `ignored: ignored_directories`. Dropping it re-armed the output-directory feedback loop for any `WOODS_OUTPUT` under the root but outside the default ignore set — a daemon that never idles and re-extracts forever, on precisely the path a large tree reaches when listen cannot start.
+- **INF-2**: Carried-forward work is retried on its own thread rather than inline on the heartbeat thread. A retried storm used to starve the `PipelineLock` touch and the status re-stamp for its whole duration: past `LOCK_STALE_TIMEOUT` (600 s) a waiting writer retires the live lock (the two-writer clobber the lock exists to prevent), and past `Status::STALE_AFTER` (900 s) `woods:incremental` stops standing down. `drain`'s `try_lock` still bounds it to one drain at a time.
+- **INF-7**: `PipelineLock#acquire` unlinks the lock file it just created if the write fails (a full or read-only disk). The 0-byte remnant was fresh, unparseable (`:unknown` ownership for everyone) and never released, blocking every writer for the whole stale window — the artifact `#touch` was already fixed never to create.
+- **INF-10**: The daemon's startup watermark treats a generation whose payload directory no longer resolves as no index at all, so the existing no-watermark → storm → full-extraction path recovers a gutted index. Previously the surviving marker read as "index is current at startup" while every reader resolved to a rootward fallback holding nothing.
+- **INF-11**: `Daemon#release_claim` verifies ownership before deleting the startup claim, mirroring `reclaim_if_stale`'s snapshot-compare and `PipelineLock#release`. A daemon whose claim had been replaced deleted its *successor's* live claim at shutdown, letting a third starter in while the successor ran.
+- **CORE-6**: `Generation#payload_dir` bounds the payload pointer with a `realpath` comparison against the index root, mirroring `IndexArtifact#validate_dump_dir!` (B-134). `expand_path` is textual, so a symlink planted inside `payloads/` and pointing outside the index passed the check and every payload reader followed it. Flat-index, missing-directory and textual-escape fallbacks are unchanged.
+- **Gem-owned classes keep their real source path instead of a synthesized
+  app path.** `resolve_source_location` accepted only app-owned locations and
+  otherwise returned the caller's convention fallback, so an engine model such
+  as `ActiveStorage::Blob` indexed at `app/models/active_storage/blob.rb`, a
+  file that does not exist, with no class body in its source and a
+  `woods:validate` warning telling the operator to re-run extraction for a
+  path no extraction could produce. When nothing in the app defines the class
+  and its definition site exists on disk, that site is used. It stays absolute
+  through path normalization, `woods:validate` reports it as gem-owned, and git
+  enrichment skips paths outside `Rails.root` (git rejects a whole `log`
+  invocation when any pathspec is outside the repository) as well as vendored
+  `vendor/` and `node_modules/` paths under it (a bundle vendored inside the
+  app root is gitignored, so asking git about it is wasted work). Applies to every
+  class-based extractor sharing the helper: models, controllers, mailers, jobs,
+  serializers.
+
+- **Incremental runs no longer duplicate a class-discovered job under its
+  enclosing class's identifier.** A job nested inside a non-job file (`class
+  Billing::Invoicing::Reconciler; class RefreshJob < ApplicationJob`) is found
+  on the full path by the `ApplicationJob` descendant walk, with the model
+  file as its `file_path`. Blast-radius re-extraction only knew the unit's
+  type, took the file-based entry point, and Zeitwerk-governed naming then
+  correctly named the *file* for its outer constant — registering a second
+  `job` unit under the PORO's identifier that no full extraction emits. The
+  duplicate flipped the graph node's type, added a false `variants` entry,
+  and made `woods:incremental` and `woods:extract` disagree about the same
+  tree until the next full run. `Extractor#re_extracted_units` now falls back
+  to the class-based entry point when the file does not reproduce the unit,
+  and only for a class the extractor's own discovery would return
+  (`JobExtractor#discoverable_classes`). The booted equivalence lane pins the
+  shape with a nested-job fixture in `spec/dummy`.
+
+- **Concerns join the Zeitwerk-governed naming contract.** `ConcernExtractor`
+  was the one extractor still naming from the outer-module chain alone, which
+  stops at the first non-module line. A concern under a mid-path `concerns/`
+  segment (a real namespace, not an autoload root) with a one-line `class
+  SomeError < StandardError; end` declared above it indexed as the wrapper
+  (`Outer::Mid::Inner`) instead of `Outer::Mid::Inner::Concerns::Leaf`. The
+  governed name is tried first; the module-chain scan remains the fallback.
+
+- **The missing-token console warning names the transport it applies to.**
+  It claimed every Console MCP request would be refused with 401, but only
+  the HTTP transport carries the bearer check; an stdio console server lists
+  and executes every Tier 1 tool without a token. The warning now says HTTP
+  requests will be refused, that stdio does not check the token, and that
+  production boot will raise.
+
+- **`woods:validate` no longer tells you to re-run extraction for gem-owned
+  paths.** Engine models and framework sources carry absolute paths outside
+  the application tree, so under a different install prefix they resolve
+  nowhere by design and re-extraction cannot change that. They now get their
+  own warning without the no-op remedy; app-tree paths keep the original one.
+
+- **Metadata searches with `fields: []` now return an empty result on every
+  backend (B-133).** The SQLite adapter previously emitted an incomplete
+  `WHERE` clause and exposed a raw `SQLite3::SQLException`; adapters now stop
+  before touching their backing store when no fields are searchable.
+
+- **Snapshot dump writers reject symlink escapes before writing (B-134).**
+  Vector dumps, metadata dumps, and promotion now share the same realpath-aware
+  `dumps_root` boundary check. A legitimate symlinked alias of the artifact
+  root remains supported, while a child symlink targeting another directory
+  cannot receive snapshot files.
+
+- **Corrupt JSON temporal snapshots are consistently treated as absent
+  (B-135).** Direct `find` now follows the existing list/history posture by
+  warning and returning `nil`; `diff` warns and returns an empty result when a
+  requested snapshot is truncated, rather than leaking `JSON::ParserError`.
+
+- **Payload retention preserves generations pinned by readers in other
+  processes.** `IndexReader#with_pinned_generation` previously coordinated
+  only threads sharing one reader object. A long MCP request could remain on
+  generation N while three quick extraction publishes advanced retention far
+  enough to delete `payloads/gen-N/`; an artifact first opened later in the
+  request then failed with `ENOENT`. Pinned readers now hold a shared advisory
+  lock on that generation's manifest, and retention skips any payload whose
+  manifest cannot immediately take the exclusive lock. The operating system
+  releases the lock on normal exit or a crash, and a later publish reclaims
+  the skipped payload.
+
+- **One-shot extraction tasks fail when their generation marker cannot be
+  published.** `woods:extract`, `woods:incremental`, `woods:refresh`, and the
+  `woods:extract_framework` compatibility task no longer print success and
+  exit 0 after writing a payload that readers cannot reach. They now raise a
+  typed `Woods::ExtractionError` while the previous generation stays active.
+  The resident watch daemon keeps its existing recoverable behavior: it
+  reports degraded and carries the paths into a later cycle.
+
+- **`woods:watch_status` resolves its conventional index beside the active
+  Rakefile, not the caller's current directory.** Cheap hook checks still do
+  not boot Rails, but `rake -f /app/Rakefile woods:watch_status` now reads
+  `/app/tmp/woods/watch_status.json` even when a worktree manager launches it
+  elsewhere. `WOODS_OUTPUT` continues to override the conventional path.
+
+- **`console_sql` rejects `INSERT`, `UPDATE`, and `DELETE` written as bare
+  keywords mid-statement.** The forbidden-body keyword scan anchored every
+  keyword to statement-leader positions only (start of the SQL, or after
+  `;`/a comment boundary), so a statement like `SELECT 1 UPDATE posts SET
+  status = 10` passed validation and failed as an adapter-level syntax error
+  instead of a typed refusal. Those three keywords are reserved words on every
+  supported backend and can never be bare identifiers, so the validator now
+  also rejects them as bare tokens anywhere in the noise-stripped statement
+  body. `MERGE` is deliberately excluded from that scan: SQLite permits an
+  unquoted `merge` column, so body-level MERGE scanning would reject ordinary
+  selects like `SELECT merge FROM posts`; MERGE statements remain covered by
+  the allowed-prefix rule and the WITH-attached-DML check. Literal content
+  never triggers (`SELECT 'update' AS word`, `WHERE title = 'UPDATE me'` stay
+  accepted), identifier-shaped column names stay accepted (`updated_at`,
+  `last_update`, `merge`), and row-lock clauses keep their dedicated earlier
+  check, so `SELECT 1 FOR UPDATE` still reports the lock-clause message.
+  Non-DML keywords that are plausible column names (`do`, `lock`, `release`)
+  keep the leader-anchored rule unchanged.
+
+- **`console_query` placeholder scopes resolve table-qualified columns
+  case-insensitively, exactly like the public path.** A `["posts.status = ?",
+  10]` scope passed the public schema but was refused at execution with
+  `Unknown table 'posts'. Cannot validate qualified column 'posts.status'.`
+  whenever the executor's ModelValidator had no model-to-table mapping to
+  resolve the qualifier, and a case variant (`["Posts.status = ?", 10]`) was
+  refused even with the mapping. The query scope path now resolves a
+  `table.column` reference whose table matches the queried model's own table
+  (case-insensitively, matching unquoted SQL identifier semantics) against
+  that model's own columns, so own-table qualification behaves exactly like
+  the bare-column form. Redaction stays strict: a redacted column referenced
+  through any case variant (`Users.Password_Digest = ?`, `Orders.Amount = ?`,
+  bare `AMOUNT`) refuses with the typed redaction message — the refusal now
+  runs before column resolution and matches column names case-insensitively —
+  and any other qualified table still resolves through the fail-closed
+  table-column check.
+
+- **The Index MCP `reload` tool no longer reports an empty success when the promoted dump's
+  store configuration diverges from the live server (M2).** The live retriever was in-memory
+  and the captured dump was complete and valid, but when the dump's embedded `woods.json`
+  named a store type the live target cannot refresh (a re-embed ran with pgvector or Qdrant
+  configured and promoted over the dump the server hydrated from), the reload-time resolver
+  adopted the dump's store types, every candidate builder returned nil, and the tool answered
+  `reloaded: true` with zero counts while nothing was swapped and no degraded condition was
+  recorded. That divergence is now a degraded reload: the `reload` tool responds with the
+  reload-phase `degraded_index` error naming both store types and the honest state (nothing
+  was swapped, the previous generation is still served), and the condition surfaces additively
+  through `woods_status` (`bootstrap.reload_failure`). A genuine empty dump still reloads
+  successfully with zero counts.
+
+- **Vector dump hydration fails closed on a truncated or mismatched `vectors.idx` (M3).** The
+  idx parser read each record's length, id, and offset with no end-of-file guard: a dump
+  truncated mid-record hydrated a garbage short id silently, an idx holding more records than
+  the float blob crashed hydration with a bare `NoMethodError`, and an idx holding fewer
+  silently hydrated fewer vectors than the dump header claims. Parsing now raises the same
+  typed `UnsupportedArtifact` the bin side raises for a truncated float payload when a record
+  would read past EOF, and the idx record count is cross-checked against the header's
+  `vector_count` after parsing, naming both counts and prompting a re-run of `woods:embed` on
+  mismatch.
+
+- **Best-effort Git provenance and file-history probes are now quiet and rooted
+  at the extracted application.** Expected failures in source copies without a
+  `.git` directory no longer emit `fatal: not a git repository` on stderr, and
+  extraction launched from another checkout can no longer attach that
+  checkout's branch or file history to the Rails application.
+
+- **Reloading the Index MCP server no longer opens an empty-store window, and a
+  failed reload no longer leaves a misaligned index (M7).** The `reload` tool
+  refreshed the live in-memory vector and metadata stores with `clear!` followed by
+  `bulk_load`, so a concurrent `codebase_retrieve` could search an empty or
+  half-loaded store (and the reader's caches were reloaded even when store
+  hydration failed, pairing one generation's JSON index with another's vectors).
+  The reload is now a transaction: candidate stores are built off-side against one
+  captured generation marker and one captured promoted-dump identity, reading
+  exclusively from those captured locations (config from the captured dump's
+  embedded snapshot, vector/metadata from the captured dump directory, the graph
+  from the captured payload), so a concurrent promotion can never mix vector and
+  metadata halves from two dumps. Any candidate failure leaves the previous fully
+  aligned generation untouched — the old retriever keeps answering and a distinct
+  reload-phase `degraded_index` condition (with `phase: 'reload'` naming the
+  generation still being served) is reported on the `reload` tool response and
+  additively through `woods_status` (`bootstrap.reload_failure`), without flipping
+  the boot degraded state. The commit acquires the same on-disk extraction
+  PipelineLock every writer uses before rechecking both identities, so a writer
+  cannot publish between the recheck and the one-assignment store-bundle swap; a
+  promoted dump missing any required vector or metadata component also fails
+  closed without replacing the healthy live bundle. Because the reload transaction
+  takes the shared on-disk writer lock, the MCP process needs write access to the
+  index directory when using `reload`. A
+  generation movement fails the attempt with `ReloadGenerationMoved` and a
+  promoted-dump movement (an embed promotes without bumping the generation file)
+  with `ReloadDumpMoved` — the next `reload` is the recovery path. A successful
+  reload clears the condition.
+
+- **Incremental extraction no longer misses a class-based unit whose file
+  moved with its constant unchanged (M1).** Moving `app/models/tag.rb` to
+  `app/services/tag.rb` without renaming `Tag` pruned the model for the
+  vanished old path, and the second reconciliation pass refused to re-add
+  it, so one generation served an index with the unit missing until the
+  next run. The pass now re-adds pruned class-based identifiers the active
+  Zeitwerk loader still governs a changed file for — the constant path
+  `cpath_expected_at` derives (its inflector, ignores, and root namespaces
+  decide), gated on the file declaring it; a loader non-claim is
+  authoritative, so an unmanaged path re-adds nothing. Another namespace's
+  same-named file and a file that only mentions the class in a comment or
+  string literal resurrect nothing; deletions (including deletions batched
+  with unrelated additions) stay pruned exactly as before.
+- **Incremental runs now refresh the flow artifact family, and both paths
+  fail closed (M3).** With `precompute_flows` enabled, a controller
+  re-extracted incrementally lost `metadata[:flow_paths]`,
+  `flow_index.json` kept describing pre-change routes, and `flows/`
+  documents for deleted or renamed controllers persisted across every
+  generation. Incremental runs now recompute the run's controller delta,
+  carry untouched controllers' entries forward, and sweep `flows/`
+  documents nothing references through a dedicated flow-artifact sweep
+  (separate from the unit sweep). Full and incremental extractions of the
+  same tree produce equivalent flow artifacts. A failure anywhere in the
+  family on either path — assembly, index write, annotation rewrite, or
+  sweep — now aborts before the generation publish, so a partial flow
+  index, stale prior flow artifacts alongside a new graph, or
+  half-rewritten annotations can never be published; the preceding
+  generation stays resolved and readable.
+- **`woods:validate` no longer fails every flow-enabled index (G-2).** The
+  validator treated `flows/` as a unit-type directory and demanded
+  `_index.json` from it, so any index published with flow precomputation
+  on reported "Missing _index.json in flows/". Type directories are now
+  bounded by a shared allowlist derived from `Extractor::EXTRACTORS`, and
+  the flow family is validated by its own rule: `flow_index.json` must
+  parse and every entry must point at a flow document that exists and
+  parses, with missing or malformed artifacts reported accurately.
+- **Multi-line `strong params` declarations are captured (M2).** The
+  `permit(...)`/`expect(...)` capture regexes could not cross newlines, so
+  the common multi-line style produced an empty `metadata[:permitted_params]`.
+- **A half-loaded model no longer aborts the models phase (L1).**
+  `ModelExtractor.discoverable_classes` called `abstract_class?` unguarded;
+  a descendant that raises on it (possible under the NameError fallback)
+  escaped the scan and failed the whole extraction. The call is guarded the
+  same way `ModelNameCache` already guarded its twin, keeping the class and
+  letting per-class extraction handle failures.
+- **`if nil` no longer misattributes conditional branches in flow analysis
+  (L2).** The AST normalized `if` children with a `compact` that dropped a
+  literal `nil` condition, so the else body landed in `then_ops`. `if`
+  children are positional now; missing slots stay nil.
+- **A hydration failure at boot no longer reports `:hydrated` over empty stores (M6).**
+  A corrupt or unreadable dump left the in-memory vector/metadata stores empty behind
+  only a stderr warning while `woods_status` reported a healthy `:hydrated` — a server
+  that answered everything with nothing. The boot status is now derived from store
+  health (`:degraded` plus a per-store `hydration_failures` report), and
+  `codebase_retrieve` answers with a typed `degraded_index` error naming the affected
+  stores instead of a clean empty result. Graph hydration reads through the
+  encoding-safe atomic-file path, so a non-ASCII index stays healthy under `LANG=C`.
+- **A metadata-store failure no longer produces misleading retrieval answers (M8).**
+  Store errors were swallowed at three call sites: `types:` queries reported `:absent`
+  for types that exist, the rank-within-type fallback short-circuited to empty, and
+  exclusion filtering silently no-op'd. All store accesses now raise the shared
+  `Woods::Retriever::StoreError`, which `codebase_retrieve` maps to the same typed
+  degraded metadata instead of raising through the tool boundary.
+- **A set-but-empty `OPENAI_API_KEY` behaves as absent (M9).** The truthiness check
+  wired the OpenAI provider with a blank key, skipped the Ollama fallback a missing key
+  gets, and then crashed boot with a raw backtrace. Blank keys now fall through to the
+  Ollama probe (pattern-only when nothing is usable), and both executables catch
+  `Woods::ConfigurationError` in their bootstrap rescue so an unusable embedding
+  configuration prints the one-line operator message.
+- **A non-`SystemCallError` guard failure no longer leaks the pipeline lock (L6).**
+  `pipeline_extract`/`pipeline_embed` released the on-disk lock only for
+  `SystemCallError`/`IOError` from the task-durability guard; any other raise blocked
+  every later writer until the stale window expired. The release is now `ensure`-based
+  for every pre-handoff exit path.
+- **"find who calls X" routes to graph tracing (L8).** The query classifier's
+  first-match ordering sent mixed locate/trace queries to keyword location handling;
+  the `:trace` intent pattern now runs before `:locate`.
+
+- **`woods_status` no longer reports a stale registry version alongside a newer
+  install.** When the installed gem is ahead of RubyGems (for example while
+  testing an unreleased release), `server.update.latest_version` now reports the
+  newest known version — the installed one — instead of the raw published
+  version, so the payload no longer pairs `current_version: 2.0.0` with
+  `latest_version: 1.6.0` and `update_available: false`. `update_available`
+  semantics and all key names are unchanged.
+- A wrong-dimension query vector now raises the typed `Woods::Error` before the
+  request leaves the process on both the pgvector and Qdrant search paths
+  (previously a server-side `PG::DataException` or Qdrant 400).
+- An OpenAI embedding request whose one retry also fails now raises the typed
+  `RequestError` (as Ollama already did) instead of leaking a raw
+  `Errno::ECONNRESET`. Persistent HTTP connections dropped on transport errors
+  are closed promptly instead of waiting for GC.
+
+- **A truncated vector dump now refuses to load instead of corrupting search (M10).**
+  `vectors.bin` with a valid header but a short float payload used to unpack with nil
+  padding: the nil-floated vectors loaded into the live store, crashed search with
+  `TypeError`, and re-published as zeros on the next dump. Loading now raises
+  `Woods::MCP::UnsupportedArtifact` pointing at the file; the remedy is a re-run of
+  `woods:embed`.
+- **Every atomic dump write now fsyncs its directory (M11).** The vector and metadata
+  snapshotters and the index artifact writer skipped the containing-directory fsync
+  `AtomicFile` performs, so a crash after the rename could leave a directory entry that
+  a reboot drops — a "complete" generation that vanishes. The class contract that the
+  dump directory is fully fsynced before the `latest` pointer flips now holds on every
+  write path.
+- **File permissions are explicit per artifact (O1).** `AtomicFile.write` takes a `mode:`
+  parameter defaulting to the restrictive 0600 Tempfile already used. The one artifact
+  with a cross-boundary consumer — the watch daemon's `watch_status.json`, read by
+  host-side hooks through a bind mount — is written 0644 by design.
+- **A second writer on the metadata SQLite database no longer raises
+  `SQLite3::BusyException` immediately (O2).** The connection now sets a busy timeout at
+  open and retries a contended write a bounded number of times, mirroring the temporal
+  snapshot store.
+- **Re-capturing an unchanged HEAD computes diff stats against real history (L20).**
+  Both temporal stores resolved "previous" to the snapshot being captured, so the
+  re-capture diffed against itself and zeroed every stat. Previous now excludes the SHA
+  being captured.
+- **Storing metadata without a type key raises instead of writing an empty type (L22).**
+  The SQLite metadata adapter coerced an absent key to `""` in the column that backs
+  `find_by_type`; it now raises `ArgumentError`.
+
+- **Select aliasing no longer defeats console redaction.** `console_query` accepted
+  `select: ["password_digest AS note"]`; the positional redactor masks by output
+  header name, so the aliased column returned plaintext. Three select shapes are
+  now refused: an alias over a `console_redacted_columns` column, an aggregate over
+  one (aliased or bare), and an alias over either column of a
+  `console_redacted_key_values` pair. Direct, unaliased selection of a redacted
+  column is unchanged and stays masked. Aggregates over either column of a
+  `console_redacted_key_values` pair are also refused: an aggregate such as
+  `MAX(amount)` over the rows a sensitive key selects reads the redacted EAV value
+  itself. Selecting an EAV value column without its paired key column is refused
+  as well — the positional rule needs both headers, so a lone value column
+  returned plaintext.
+- **`console_query`'s having no longer leaks protected values.** `having` accepted
+  aggregates over redacted or EAV-protected columns (`MAX(amount) > ?`) and bare
+  predicates on redacted columns or EAV value columns; repeated guesses revealed
+  the protected value from whether a row was returned. The same protected-column
+  refusal used for `select` aggregates now runs on the having template and hash
+  keys before any query executes. Structured scope predicates now apply the same
+  rule to redacted columns and EAV value columns while preserving EAV key-column
+  predicates.
+- **Tier 1 and raw-SQL redaction shapes now fail closed.** `console_sample`,
+  `console_find`, `console_pluck`, and `console_recent` refuse an EAV value column
+  unless its paired key column is selected too; `console_aggregate` refuses either
+  EAV pair column. Structured order/group inputs and legacy multi-bind scope arrays
+  now apply the protected-predicate guard. `console_sql` accepts a protected
+  identifier only as a direct, unaliased outer select column; aliases, aggregates,
+  predicates, CTE shapes, and unpaired EAV values are rejected before execution.
+- **A writable CTE past the first WITH entry no longer validates.** The writable-CTE
+  check anchored its match to the statement leader, so
+  `WITH a AS (SELECT 1), b AS (DELETE FROM users RETURNING *) SELECT * FROM b`
+  passed validation and PostgreSQL executed the DELETE. Every `AS (...)` body in
+  the statement is now inspected. A CTE list attached to top-level DML
+  (`WITH a AS (SELECT 1) DELETE FROM users RETURNING *`) is also rejected; DELETE
+  and UPDATE previously validated because the statement prefix is WITH and neither
+  keyword is a body keyword (only the INSERT variant tripped a check, incidentally
+  via INTO).
+- **Row-lock clauses are rejected.** `SELECT ... FOR UPDATE`, `FOR NO KEY UPDATE`,
+  `FOR SHARE`, `FOR KEY SHARE` (with `NOWAIT`/`SKIP LOCKED`), and MySQL
+  `LOCK IN SHARE MODE` validated as reads but took live row locks for the duration
+  of the rolled-back transaction. The check is adapter-aware: `console_sql`
+  validates with the active adapter's dialect (MySQL and PostgreSQL quote/comment
+  grammars differ; MySQL double-quoted strings/backtick identifiers and PostgreSQL
+  quoted identifiers/E-strings are tracked faithfully), while scanning
+  both normalizations when the adapter is unknown, and every view is checked under
+  both MySQL executable-comment (`/*!...*/`) semantics — `#` comments and
+  version-guarded comments can no longer split a lock clause apart.
+
+- **Index MCP reads no longer break under a C/US-ASCII host locale.** The
+  Index Server read manifest.json, per-type `_index.json` files, and
+  SUMMARY.md with bare `Pathname#read`, which tags the bytes with the host's
+  default external encoding. Under a C locale that tag is US-ASCII, so any
+  non-ASCII content in an index artifact (a branch like `feature/café`, a
+  unit identifier, summary prose) made `JSON.parse` raise
+  `Encoding::InvalidByteSequenceError`, surfacing search, lookup,
+  dependencies, dependents, framework, and recent_changes results as
+  misleading `corrupt_artifact` errors and degrading structure and
+  `woods_status`. All `IndexReader` artifact reads now go through one
+  UTF-8-forcing binary read (the mode unit loading already used), so an
+  index is read correctly regardless of host locale. No re-index needed.
+
+- **Console redaction-oracle refusals now fire on the real transports.**
+  `Server.build_embedded` handed the executor the transport-provided
+  SafeContext (connection/pool, statement timeout, rolled-back transaction)
+  while building a separate, render-only SafeContext for the configured
+  `console_redacted_columns`/`console_redacted_key_values`. The executor-side
+  refusals (redacted scope/filter keys, find locators, order keys, aggregates
+  and aliases over protected columns, unpaired EAV value selects, protected
+  raw-SQL usage) all read the executor's context, so on the
+  `exe/woods-console` and RackMiddleware wiring every one of them was dead: a
+  comparison, aggregate, sort, or unpaired-EAV read executed against the
+  database and returned plaintext before render-side redaction ever ran.
+  `build_embedded` now derives a single policy-complete SafeContext from the
+  transport context (`SafeContext#with_redaction_policy`), preserving its
+  pool, timeout, and rolled-back transaction while applying the configured
+  policy, and passes that one context to both the executor and the response
+  renderer. The policy comes from the kwargs when supplied and otherwise from
+  the lists the supplied context itself carries — a context that carries its
+  own redaction lists now renders through the same policy-complete context
+  instead of losing its renderer. When redaction is effectively configured
+  but the supplied context cannot derive a policy-complete context,
+  construction fails closed with a `ConfigurationError` rather than leaving
+  the renderer disabled. Render-side masking behavior is unchanged.
+
+- **TableGate catches blocked tables hidden in MySQL executable comments at
+  FROM, JOIN, and subquery lead position.** The noise stripper deliberately
+  preserves `/*! ... */` forms (MySQL executes their body), but the scanner's
+  FROM/JOIN lead grammars cannot start on a comment marker, so
+  `SELECT * FROM /*!authorizations*/`, `SELECT * FROM /*!99999*/
+  authorizations`, `users JOIN /*!authorizations*/ a ...`, and
+  `FROM (SELECT * FROM /*!authorizations*/) t` surfaced no identifier and the
+  blocked table executed. The scanner now scans two additional views of each
+  dialect's stripped text — every executable comment replaced by its body,
+  and the whole form dropped — mirroring SqlValidator's dual
+  executable-comment semantics for lock clauses. The preserved form is still
+  scanned, so the post-comma shape keeps working; on PostgreSQL the `/*!`
+  form is a syntax error, so extra detections there are over-detection by
+  design.
+
+- **A failed wholesale re-run can no longer publish a graph with phantom
+  units (M8).** `replace_type_wholesale`'s rescue swallowed every failure.
+  A unit's graph node is registered before its JSON is written, the removal
+  half deletes the JSON before dropping the graph node, and registration
+  itself mutates the graph before it can fail (a malformed dependency raises
+  after the node is already inserted) — so a raise in any of those windows
+  (a full disk, a serialization error, a malformed unit) left the in-memory
+  graph and the payload directory disagreeing, and the run went on to
+  publish a generation whose `dependency_graph.json` held nodes with no unit
+  file, so `dependencies`/`dependents` reported `found: true` while lookup
+  returned nothing. The rescue now re-raises (as `Woods::ExtractionError`)
+  once the replacement has begun to register, write, or remove anything —
+  the marker is placed before each mutation, so a failure inside one cannot
+  slip past it — and the run aborts before publication, leaving the
+  previous generation resolved. A failure that landed nothing is still
+  swallowed, as before.
+
+- **Incremental runs no longer ship the previous generation's SUMMARY.md
+  (M4).** `write_structural_summary` returned early because an incremental
+  run holds no units in memory, so the hardlinked summary of the last full
+  extraction was served unchanged — its `Units:`/`Chunks:` totals went stale
+  the first time a run added or removed a unit. The summary is now derived on
+  the incremental path from the same persisted per-type `_index.json` files
+  the manifest counts, so the two artifacts agree; the `Generated:` stamp
+  still names the moment the summary was written. The equivalence oracle now
+  also compares SUMMARY.md's totals against the manifest of the same index,
+  so this drift can no longer hide.
+
+- **`woods:incremental` no longer exits 0 over a git range it cannot resolve
+  (M1).** The diff helper discarded git's exit status, so an unresolvable
+  range — a GitLab zero-SHA, an unfetched GitHub base ref, garbage — read as
+  "no relevant files changed" and the task exited 0 while the sync never ran;
+  the degraded-daemon extract-anyway branch was unreachable. The helper now
+  carries the failure out and the task decides in order: a resolvable range
+  behaves as before; a failed range stands down with a printed reason (exit
+  0) only when a running watch daemon maintains the index, and otherwise
+  fails with an actionable error naming the range (exit 1, like the
+  lock-timeout abort). The diff is also rooted at the extracted application
+  (`git -C Rails.root`), consistent with the provenance rooting, so it can no
+  longer diff whatever checkout the process happened to start in.
+
+### Testing
+
+- The verifying-double sweep: 102 string-named `instance_double`s — which verify nothing
+  when the constant isn't loaded — now either reference the real constant (26) or are
+  honest plain doubles (76) (#219). `PhlexExtractor` went from 3 examples/~38% line
+  coverage to 39 examples/99% (#219). Every spec directory now passes standalone; nine
+  spec files only passed in the company of the full suite because earlier files loaded
+  their constants first (B-109). Two order-dependent flakes fixed: `wait_for_threads`
+  now fails loudly on a hung thread, and `tasks_spec` no longer leaks a mutated global
+  configuration (#215, #216).
+- **CI** (#220): workflows run on pushes to `main` as well as PRs (a bad merge previously
+  went green by absence of a run); the unit axis adds Ruby 3.4 and the booted matrix adds
+  Rails 8.1 rows; a new `live-backends` lane runs storage-adapter contract specs against
+  real PostgreSQL+pgvector and Qdrant service containers plus an offline embed→retrieve
+  round trip — every other storage spec drives doubles, which is how #181 shipped. The
+  lane found B-108 on its first run.
+
+- **The live-Redis session-tracer contract spec now runs in CI (M6).** The
+  `spec/session_tracer/redis_store_live_spec.rb` suite from the P4 eviction
+  rework was gated on `WOODS_RUN_LIVE_BACKENDS=1` but appeared in no CI
+  job's rspec run, so its six examples (including the two-client Lua
+  migration race) never executed anywhere. The `live-backends` job now
+  lists it; that job already provides the ephemeral `redis` client install,
+  the redis service, and `WOODS_REDIS_URL`.
+
+### Security
+
+- Preserve Console blocked-table boundaries for MySQL adjacent subtraction and
+  whitespace/comment-separated qualified table names. Validate every SQL safety
+  check with the active dialect and exercise PostgreSQL/MySQL Console requests in CI.
+- Require MessagePack 1.8.2 or newer for the patched runtime buffer implementation.
+- Require patched JSON 2.x (>=2.19.9, <3) so older supported Rails encoders
+  retain their `quirks_mode` compatibility. Activate installed Index executables
+  before optional libraries can select conflicting dependency versions.
+- Update Inspector transitive dependencies `fast-uri` and `qs` to patched versions
+  and audit the pinned Node dependency tree in CI.
+
 ## [1.6.1] - 2026-07-22
 
 ### Fixed