woods 2.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c00b317c5f1df618b940db9d8d2b596c27c1538b4d713d60c9263b1f0ab6acae
-  data.tar.gz: b0fceeb5a3220efdd9d3f0f5dd77d9bc12e1d780ddc689dfd2121f163d9ec75d
+  metadata.gz: 999a4f9f01b4f8c86e560f47c1051233a4cafff30d463ae8051a50b363fb623b
+  data.tar.gz: f9e0c50a283eadde42b4034426c7258325fbad18205fa6016c5fb2e7b59fa1d7
 SHA512:
-  metadata.gz: 0ec485c382f5a334d3607f2f18dd1489c02a6de17df0ba8922dd1d7271a36c8ffa1a71ec16346fe148460632e26f7ccbfc51c938ad96d1c8d03e68672d590993
-  data.tar.gz: 011e559a5cbd6478d579c0fc477c020048352b75872daaab75a52df527dd0b2c0e27645f0627321b03a87c9844aa52b7b5f9fab0e90b7e6ec071a244c8697ef1
+  metadata.gz: 845c357cd67e5923bb283d075e608020ff0a7d8ce1df16c379fd6c197084d5ecb398e047d74951006741b14667414eadfb2cbf85fb2be890076df02cb1e12cf4
+  data.tar.gz: 0103d3cabd3c4e6eeccf13063470590f8ba93cfd6b1a12acb9728e70adb0e7f7fb89cddcd9048c3db048c3e2633dddf11b74ac53348abf542e242b3a5ee09298

data/CHANGELOG.md

@@ -7,26 +7,113 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [2.0.1] - 2026-09-26
-
-### Documentation
-
-- Clarify supported Console redaction, SQL projection, adapter timeout and HTTP origin behavior, including maintenance-line differences.
+## [2.1.0] - 2026-09-28
 
 ### Fixed
 
+- Correct the generated development README banner after reopening a patch release: the next version is unreleased, while the existing stable gem remains installable with its released constraint (#555).
+- Store app-owned event publisher/subscriber paths and ViewComponent sidecar paths relative to the application root, including event source annotations, so identical checkouts produce matching metadata and event source hashes while source reads and external paths retain their original locations.
+- Restrict Phlex, ViewComponent and ActionCable discovery and direct extraction to application-owned runtime descendants. Dependency-only definitions and source-less framework classes are excluded consistently, and incremental reconciliation removes their stale units. Source containment now distinguishes sibling directories and treats dependency exclusions relative to the application root (#594).
+- Resolve constant references to indexed library declarations on autoload-only paths when the exact registered constant and absolute source path match. Reference lookup still never executes autoloads or application methods; uncertain paths, namespaces, scopes, private access and typed collisions remain unresolved. Run a full extraction after upgrading to rebuild missing edges.
+- Prefer an executable application bin/rake for the direct Console launcher, including a relative application directory; preserve explicit commands, remote defaults, and bundle exec rake fallback.
+- Reject unsupported Console launcher configuration instead of silently ignoring it, count singular associations as zero or one through their guarded relation, and return a stable HTTP 503 after a Rails eager-load naming error until the application is fixed and restarted.
+- Return zero for missing polymorphic association targets in Console association counts, and give a clear validation error for scoped polymorphic counts.
+- Include metadata-only units in durable-store reconciliation, so deleting an empty-source unit removes its SQLite metadata under the existing mass-deletion safeguards.
+- Keep embedding requests, stored vector widths, and cache identities consistent when restoring provider configuration or changing models, endpoints, or requested dimensions; refuse malformed or mismatched vectors before publication.
+- Bound complete embedding inputs, including context prefixes, without silently truncating source. Known OpenAI models use a conservative UTF-8 byte-BPE bound; Ollama disables server truncation and reports strict refusals while local counts remain estimates. No tokenizer downloads occur during preparation. Oversized prefixes and unsplittable inputs fail with bounded unit diagnostics.
+- Track preparation policy and ordered prepared-input fingerprints in embedding checkpoints so dependency, path, namespace and chunk changes invalidate stale vectors even when source hashes match. Old checkpoints require a one-time re-embed; completed durable batches remain resumable, and a changed unit is checkpointed only after its replacement and obsolete-chunk cleanup succeed. Unknown custom-adapter cleanup remains adapter-owned.
+- Refuse incremental and targeted-refresh publication when a whole-app extractor raises before mutation or cannot initialize, even if sibling extractors succeed. The optional embedded `pipeline_extract` tool now reports failed full/incremental publication through its Tasks result instead of marking the task completed. Previous published generations remain active; retry the complete batch after fixing the cause. (#584)
+- Reject changelog fragments without a leading list item before preparing a release, naming the invalid file and leaving the checkout unchanged.
+- Index GraphQL schema classes, inherited resolver classes, and the runtime types of every application schema. Preserve distinct Ruby identities that share a GraphQL name, classify shared query roots consistently, and keep full, incremental, and targeted refresh results aligned when a schema changes a type's role. Failed schema introspection now reports the schema and preserves the prior published generation instead of publishing a partial inventory (#558, #562, #563).
 - Report invalidly encoded HTTP origin settings with bounded startup diagnostics; preserve existing origin defaults and access checks.
 - Use the same Console configuration error for malformed origins during automatic and manual middleware construction.
+- Align HTTP preflight and SDK dispatch with one origin policy, normalize default ports, and reject malformed configured origins once at boot with a bounded diagnostic naming the entry. Explicit browser-origin allowlists replace loopback defaults.
 - HTTP startup diagnostics consistently name `WOODS_MCP_HTTP_ALLOWED_ORIGINS` for malformed origins, including under a POSIX (`C`) locale.
+- Accept uniquely proven runtime job and serializer source moves while preserving complete-discovery and duplicate-source checks. Collision errors now name a fresh full extraction as recovery after an unproven move.
+- Refresh the complete job and serializer inventories after Ruby source changes so indirect runtime inputs, such as a job queue read from another constant, cannot leave incremental metadata stale. Non-Ruby batches retain graph-scoped selection. (#638)
+- Resolve incremental Git changes relative to the Rails application in nested repositories, normalize and contain explicit changed paths before filtering, and ignore blank CI range variables while retaining failures for invalid revisions. Document exact-baseline cache restore and full extraction on CI cold starts (#571).
+- Preserve nested runtime-discovered jobs and serializers by reconciling their complete file/runtime union; refresh BehavioralProfile through resolved Rails configuration. Fresh one-shot incremental tasks escalate schema and boot inputs to full extraction, while embedded incremental callers receive an actionable fresh-boot refusal. Disabling flow precomputation withdraws old flow documents and controller annotations atomically. These corrections are unreleased after 2.0.0. (#588)
+- Reject conflicting source ownership during incremental extraction and targeted refresh before publication, matching the full-extraction collision policy. Preserve the preceding generation on refusal, retain same-file re-derivation and independent cross-type identities, and allow confirmed file moves or authoritative wholesale source replacement. Repair previously overwritten indexes with a successful full extraction after fixing the producer or declarations (#561).
+- Preserve effective settings of injected built-in embedding providers through snapshot restoration and known wrappers; omit unsafe endpoint metadata and require explicit host configuration when a provider cannot be reconstructed safely.
+- Preserve the declared identity of behaviorful inline modules in unmanaged library directories, restoring typed lookup and source-reference edges. Inline namespace-only wrappers retain distinct nested identities; mixin modules and empty namespace preludes keep their existing handling. Run a full extraction after upgrading to replace affected path-derived identities. (#639)
+- Preserve application Bundler settings during agent preflight, accept Git checkout permission differences in watcher ownership, keep project-scoped agent receipts independent of user configuration directories, and document safe temporary plan paths on hosts with symlinked `/tmp`.
+- Prefer an executable application `bin/rake` in `woods-extract`, retaining `bundle exec rake` as the fallback. Recognize installed Bundler Git gems as external source while keeping local overrides and explicitly scoped roots in application freshness coverage.
+- Refuse incremental extraction and targeted refresh over legacy flat manifests or generations written by Woods 1.x before creating a payload. Full extraction remains the migration path, and generation indexes without writer provenance remain compatible with early v2 betas.
+- Aggregate compatible reopened library declarations under their existing constant identity while retaining every source contributor, physical source boundaries, per-file Git/package facts and dependency edges. Full, incremental and refresh extraction reconcile the complete library family; incompatible owners still refuse publication. Run a full extraction once after upgrading to rebuild versioned source-reference evidence.
+- Preserve nested class identities in one-line library namespaces, keeping namespace and class units distinct and restoring their source-reference edges. Read complete source when selecting module owners so heredoc text cannot become a declaration. Run a full extraction after upgrading to replace affected identifiers.
+- Decode library contributors as UTF-8 independently of the process locale, retaining publication refusal and per-file diagnostics for invalid source bytes.
+- Report local-preset vector reloads as degraded with an explicit MCP restart remedy. A running server no longer reports successful zero-vector refresh while retaining an older vector snapshot beside live SQLite metadata.
+- Accept the GraphQL family alias for exact MCP lookup while returning the concrete published type, and normalize uppercase hexadecimal snapshot SHA inputs before detail and diff lookup.
+- Preserve concrete search result types across scoped and unscoped family filters; support encoded slash-bearing unit resources; distinguish missing flow units and snapshots from valid empty answers; and report repeated malformed generation reads without exposing raw exceptions or falling back to unrelated payloads.
+- Honor the owning Rails `main` or `once` autoloader when naming declared source constants, preserving loader-specific inflections, namespaces, collapses, ignored paths and copied-root ambiguity. This prevents once-autoloaded library children from colliding under their shared wrapper identifier. Rebuild affected indexes with one full extraction after upgrading. (#579)
+- Publish a usable code index when freshness evidence alone exceeds its size limit, with bounded `unavailable` status, stable `source_manifest_too_large` reason, measured bytes and limit. Preserve verified source-reference reuse for incremental work, keep watcher catch-up bounded, and avoid recommending an identical full rebuild in status or hooks; corrupt evidence, failed writes and unstable source retain their safeguards.
+- Preserve source-consumption evidence for successfully extracted models when another model fails, so an optional framework model with a missing table does not prevent unrelated incremental extraction or refresh. The failed extractor remains explicitly unverified; failed models and changed retained source are not certified (#568).
+- Accept incremental source-ownership moves out of surviving files when completed discovery proves a unique replacement. Collect changed-file candidates before registration and pruning so file order cannot decide acceptance, while preserving collision and incomplete-loading safeguards (#574).
+- Read typed and bulk published units as UTF-8 regardless of the process locale, restoring typed lookup, scoped search, exports, and lexical MCP startup for indexes with non-ASCII identifiers or source (#570). Reject malformed UTF-8 without replacing source bytes.
+- Block Bundler source-control publication tasks, reject nested changelog entries before preparation, include published-index checks in surface inventory, validate release text as UTF-8 under any locale, and correct transition/recovery guidance. No release transition or publication occurs as part of these fixes.
+- Preserve every repeated method definition when chunking singleton class bodies, nested classes, and inlined overrides. Later definitions receive deterministic occurrence suffixes instead of overwriting earlier source.
+- Restore ordinary Ruby `Resolvers::Base` subclasses omitted by runtime GraphQL discovery. Verify loaded ancestry and preserve their historical `graphql_type` identities during full extraction, incremental updates, and refresh. Run a full extraction to recover helpers missing from an earlier 2.1 development index.
+- Preserve schedules with the same task name across Solid Queue, Sidekiq-Cron and Whenever. Only conflicting identifiers gain a deterministic format qualifier; unique identifiers stay unchanged. Full, incremental, refresh and file extraction use the same allocation. Ambiguous task keys within one format fail before publication instead of overwriting a schedule (#594).
+- Verify source inputs through stable directory symlinks under their logical application paths, so unrelated static-assets links no longer prevent first publication. Retain distinct aliases, exclude output aliases, bound cycle traversal and refuse changing links or scoped external files before reading their contents. Run a fresh full extraction after upgrading to establish the updated source-capture rules (#653).
+- Encode Unblocked branch citations, retain separate repository/ref ownership scopes, and provide resumable explicit URI migration with a no-write preview. Refuse foreign-collection URI overwrites and incomplete pagination; preserve unknown remote documents and report incomplete cleanup. The upgraded manifest is version 2; keep a backup and one writer per local manifest and remote scope.
+- Avoid reading every GraphQL and framework unit during unscoped identifier searches; use published summary types and resolve legacy types only when needed. Searches retain readable matches and report partial coverage when an individual candidate unit is unreadable or corrupt.
+- Use owned runtime ancestry for manager and Pundit classification, select actual migration declarations without executing historical files, and retain distinct class/instance method chunks with punctuation and operator names. Migration helper siblings no longer supply identity or DDL metadata; ambiguous declarations are reported and duplicate identities retain the publication collision guard.
+- Keep source-freshness evidence bounded and scoped to the checked checkout: enforce the 16 MiB reader limit for source evidence and launcher handoffs, distinguish installed gems from uncaptured application source, retain accessible scan results after entry errors, and avoid invented additions/deletions from missing or incomplete baselines. Status exposes root provenance and separate deep-check versus fresh-capture advice; copied-index task checks default to the invoking application directory.
+- Remove vanished SQLite metadata during full and incremental embedding with dump-backed vectors, including source-empty and typed records, while retaining incremental purge guards. Restore vector type filters from the same SQLite metadata store used by standalone retrieval (#572).
+- Extract default-attribute and parenthesized `state_machines` declarations, including multiline arguments, without changing named-machine identifiers. Keep each declaration's states, events and initial state within its own block; do not execute callbacks or infer dynamic attribute names.
+- Skip Unblocked inventory documents without a usable URI. Report incomplete synchronization with a migration or manual-cleanup remedy when legacy ownership remains unresolved, including stale legacy receipts; URI prefixes alone never authorize deleting another ref's documents.
+- Name bounded, escaped paths and verification reasons when source-reference publication refuses undecodable filenames, while keeping the preceding generation active.
+- Handle undecodable filenames without crashing source capture or polling: keep source evidence incomplete, bound escaped diagnostics, and retain the previous generation when reference verification fails. Preserve valid UTF-8 paths under the C locale.
+- Preserve Unicode roots, output directories and edit paths through Ruby-only refresh and SessionStart hooks under the C locale. Keep failed batches queued and sanitize malformed JSON/encoding diagnostics (#592).
+- Add explicit token-checked recovery for abandoned managed watcher claims protected by lifetime filesystem leases, preserving live owners and permanent coordination files during cleanup. Treat blank idle timeouts consistently, resolve boot-free check defaults beside the selected Rakefile, refuse implicit verified-launch output mismatches before publication, and report safe, actionable identity-key diagnostics.
+- Catch source edits made between extraction capture and publication when watch starts, including the interval after final verification and whole-second file timestamps. Compare candidate content with the published source identities to avoid repeating unchanged work, and reconcile older indexes without capture metadata once before using the new boundary (#585).
+- Keep deletion-only watcher startup reconciliation queued after extraction, lock, or publication failures, including when no source paths can safely be named (#640). Check publication errors before accepting empty-touch incremental runs, so failed withdrawal of disabled flow artifacts reports degraded status and retries the original event (#641).
+- Preserve the canonical identities of loaded Struct/Data classes assigned inside class or module wrappers under `app/models` and `lib`, instead of omitting them or colliding on the wrapper name. Verified assigned classes also participate as source-reference targets; constructor block bodies remain outside reference coverage. Run a full extraction after upgrading to repair earlier identities and rebuild the version 3 source-reference cache; older caches refuse incremental publication (#559).
+
+### Added
+
+- Discover all application-owned `ActionMailer::Base` descendants, including `ApplicationMailer`, direct framework subclasses and application subclasses of external mailer bases. Their defaults, layouts, callbacks and actions remain reflective: extraction does not deliver mail or invoke callback/default procs (#594).
+- Add internal constant-reference collection and conservative resolution foundations for PORO and library dependency coverage (#475). The integrated pass described below adds these verified references to the published graph.
+- Add conservative method-body constant references from models, controllers, services, POROs, library units and concerns to verified indexed targets (#475). Publish forward/reverse relationships and cached unresolved candidates atomically; incremental extraction and refresh update unchanged callers when targets appear or disappear. Supporting writers require a full extraction to establish a reference-cache baseline when upgrading older indexes. They refuse publication if captured source changes during boot/extraction or a scoped refresh leaves changed reference-bearing Ruby units unprocessed, retaining the preceding generation. Dynamic or ambiguous references remain outside the declared coverage.
+- Discover callable standalone modules under `app/models` as `poro` units with `ruby_kind: module` metadata, using verified runtime and source ownership. Namespace-only wrappers and uncertain owners remain excluded; runtime model mixins retain concern ownership. Run a full extraction after upgrading to populate these units and their source references (#552).
+- Add `release:retarget` for moving an untagged alpha to the next minor development line, preserving changelog entries and refusing dirty or previously tagged version lines.
+
+### Build
+
+- Add an exact-candidate 1.6.4 maintenance release profile and select the legacy package SDK floor through trusted release metadata, preserving published 1.6.3 and normal v2 controls.
+- Add a 2.0.1 maintenance release profile bound to its exact branch and 2.0.0 base, retaining normal v2 CI and package tests and revalidating every maintenance profile after release approval.
+
+### Documentation
+
+- Mark included capabilities as Woods 2.1 in the public guides, align the upgrade baseline with reference-cache format 3, and link the published Console security advisory. Plugin availability checks remain independent of release preparation.
+
+- Clarify v1-to-v2 configuration changes, snapshot preservation across cleaning, retained runtime freshness evidence, early middleware setup, structural readiness and custom-process MCP capabilities. These notes describe existing behavior; they do not add tools or restore unsafe eval.
+- Clarify supported Console redaction, SQL projection, adapter timeout and HTTP origin behavior, including maintenance-line differences.
+- Update plugin setup, MCP configuration, and diagnosis guidance for Woods 2.0.1 and the 1.6.4 maintenance patch, with version-specific Console compatibility links and separate checks for unreleased 2.1 capabilities.
+- Clarify search completeness, GraphQL lookup aliases, local MCP reload limits, explicit Unblocked legacy-ref migration, extraction launcher selection, and legacy index write guards in public guides and agent skills. Explain usable code indexes with oversized source evidence and the `inspect_source_limits` remedy without promising freshness or recommending repeated identical rebuilds.
+- Pin the reviewed 1.6.4 and 2.0.1 maintenance candidates after complete protected-branch CI; retain exact-artifact, fresh tag CI, and protected publication gates.
+
+### Performance
+
+- Scope incremental job and serializer reconciliation to relevant paths, affected units and newly nested runtime classes. Identical registered unit bytes no longer enter touched, Git-enrichment or dependents-update sets.
 
 ### Security
 
+The Console protections below include the fixes already published in Woods 2.0.1 and 1.6.4; see [GHSA-wxxx-6hqc-qm8g](https://github.com/lost-in-the/woods/security/advisories/GHSA-wxxx-6hqc-qm8g).
+
 - Refuse unsupported PostgreSQL escaped identifiers in raw Console SQL before query execution. Ordinary quoted identifiers, literal contents, and comments retain their existing behavior.
 - Share validated Console query projections between execution and typed EAV redaction context, including whitespace normalization.
+- Strengthen Console SQL result provenance and protected query-input checks across supported database families. Preserve EAV redaction for typed keys and keep independent table patterns compatible.
+- Apply and restore the supported MariaDB statement timeout through MySQL-family adapters.
 - Refuse SQL relation and CTE column alias lists while output redaction is configured, with an explicit redaction-identity error before execution. Direct unaliased projections remain supported.
-- Harden Console request validation, protected result handling, and HTTP authentication and origin enforcement.
+- Tighten Console SQL policy, adapter compatibility, and whole-row and multi-source redaction while retaining supported structured reads. See the repository security advisories for release details.
+- Strengthen per-mount Console transport guards and protected-value rendering. See the repository security advisories for release details.
 - Apply typed key/value redaction consistently to case-variant and schema-qualified source table names, retaining all matching model types when source schemas are ambiguous.
-- Isolate cached retrieval contexts between application instances sharing a cache backend.
+- Strengthen retrieval context isolation and reload behavior on shared cache stores. See the repository security advisories for release details.
+
+### Testing
+
+- Extend the POSIX-locale CI lane to extractor, embedding and plugin regressions, and isolate update-check specs from the caller's `WOODS_NO_UPDATE_CHECK` setting.
 
 ## [2.0.0] - 2026-09-23
 

data/CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # Contributing to Woods
 
 <!-- release-state:contributing-intro -->
-Woods welcomes bug fixes, extractor coverage, storage and retrieval improvements, MCP compatibility work, documentation, and focused performance changes. This guide covers the shared contribution contract. Coding agents working from a source checkout should also read the repository's [AGENTS.md](https://github.com/lost-in-the/woods/blob/v2.0.1/AGENTS.md).
+Woods welcomes bug fixes, extractor coverage, storage and retrieval improvements, MCP compatibility work, documentation, and focused performance changes. This guide covers the shared contribution contract. Coding agents working from a source checkout should also read the repository's [AGENTS.md](https://github.com/lost-in-the/woods/blob/v2.1.0/AGENTS.md).
 <!-- release-state:end -->
 
 ## Choose the right channel
@@ -13,6 +13,22 @@ Woods welcomes bug fixes, extractor coverage, storage and retrieval improvements
 
 Search existing issues and pull requests first. A minimal reproduction in a small Rails app is more useful than a large application dump; never attach secrets or production data.
 
+### Work tracking
+
+[GitHub issues](https://github.com/lost-in-the/woods/issues) own active work,
+acceptance criteria and resolution evidence. Projects organize those issues.
+Use `release-gate` for required work on the next combined candidate,
+`post-release` for deferred work, and `needs-decision` for maintainer choices.
+Recommended cleanup may share a release milestone without being a blocker.
+
+The old `docs/backlog.json` queue is retired. `.Codex/backlog-archive.json`
+preserves every B-ID, completed record, approved decision and issue migration
+link. `tracked-on-github` is a migration state, and `not-planned` records a
+declined proposal; neither claims a bug was fixed. The original v2 snapshot lives at
+`.Codex/release-v2/backlog-archive.json`; its statuses are historical. New work
+belongs in issues rather than another local JSON queue. Preserve evidence when
+closing an issue, and distinguish fixed defects from declined proposals.
+
 ## Development setup
 
 Prerequisites are Git, Ruby 3.0 or later, and a Bundler version compatible with that Ruby. The repository tests several Ruby versions and intentionally does not pin one local version; select a supported Ruby with your normal version manager, then confirm `ruby --version` and `bundle --version`. `bin/setup` installs the bundle but does not install or select Ruby.
@@ -46,7 +62,7 @@ Create a branch from current `main`. Keep each pull request to one logical chang
 | `plugin/skills/` | Distributed Woods skills (setup/upgrade, MCP configuration, investigation, agent enablement, diagnosis) |
 
 <!-- release-state:contributing-architecture -->
-Read [CLAUDE.md](https://github.com/lost-in-the/woods/blob/v2.0.1/CLAUDE.md) for architecture and implementation gotchas before changing runtime behavior.
+Read [CLAUDE.md](https://github.com/lost-in-the/woods/blob/v2.1.0/CLAUDE.md) for architecture and implementation gotchas before changing runtime behavior.
 <!-- release-state:end -->
 
 ### Agent orientation and static self-map
@@ -103,8 +119,7 @@ Coverage from the default process excludes opt-in Rails, installed-artifact, and
 CI fails when a running example becomes unexpectedly pending, including `skip`,
 `xit`, and pending metadata. `spec/support/pending_policy.rb` records the exact
 file, full description, reason, and unavailable capability for each reviewed
-exception. Current exceptions cover the two optional tiktoken benchmarks, one
-optional Tokenizers example, two Ruby-before-3.2 regexp-timeout examples, one
+exception. Current exceptions cover the two optional tiktoken benchmarks, two Ruby-before-3.2 regexp-timeout examples, one
 procfs example, and three filesystem-permission examples when running as root.
 The Linux CI unit jobs run the real procfs identity example as an unprivileged
 user, so the procfs and root exceptions normally apply only to other environments.
@@ -285,7 +300,7 @@ For Git-sourced candidates, record the locked Git revision, loaded gem path, and
 - Put changelog entries under `## [Unreleased]`, beneath one of its `###` headings, or in an optional `changelog/<type>_<slug>.md` file. Entry files avoid conflicts between parallel branches; inline entries remain supported. Duplicate headings merge at release time, in the order they first appear.
 
 Entry files contain nonempty UTF-8 Markdown without ATX (`#`) or setext
-(underlined) headings, usually a bullet
+(underlined) headings, starting with a `- ` list item
 and indented continuation lines. For example, `changelog/fixed_watch-restart.md`
 can contain `- Preserve pending work across watch restarts.` Supported types are
 `added`, `build`, `changed`, `dependencies`, `documentation`, `fixed`,
@@ -293,8 +308,9 @@ can contain `- Preserve pending work across watch restarts.` Supported types are
 lowercase letter or digit and use lowercase letters, digits, hyphens, or
 underscores. Use one unique file per change; do not copy its entry into
 Unreleased as well. Keep entry files directly inside a real `changelog/`
-directory; symlinks and directories masquerading as entries are refused.
-Other file extensions are left untouched.
+directory; all nested directories and symlinks are refused before preparation,
+including ones whose names do not end in `.md`. Regular files with other
+extensions are left untouched.
 
 `release:prepare` appends entry files in filename order after inline Unreleased
 entries, folds them through the same heading merger, and deletes exactly the
@@ -305,6 +321,10 @@ an ordinary beta cycle, entry files may accumulate even with an empty Unreleased
 VERSION stays at the previous beta; the tag validator always rejects entry
 files at the candidate release SHA, regardless of inline notes or the version.
 
+The Bundler tasks `release`, `release:rubygem_push`, and
+`release:source_control_push` are blocked, including their prerequisites.
+Use the preparation tasks below; tagging and publishing remain maintainer steps.
+
 ### Preparing a release
 
 One command per transition. It never commits, tags, pushes, or publishes.
@@ -320,6 +340,14 @@ One command per transition. It never commits, tags, pushes, or publishes.
 
 `release:reopen` accepts only a final release and a strictly later alpha. It does not reopen a beta/RC or move the same version line backwards to alpha. Continue prerelease development with Unreleased notes or changelog fragments, then use `release:prepare` for the next forward beta, RC, or final when authorized.
 
+When an unpublished alpha needs a minor release instead of a patch, use
+`bin/rake "release:retarget[2.1.0.alpha]"` from `2.0.1.alpha`. Retarget accepts
+only the next minor `X.Y.0.alpha`, refuses a dirty checkout or any local release
+tag for the current or target line, and leaves changelog entries untouched.
+Fetch release tags before using it. It updates VERSION and the generated fences
+without committing, tagging or publishing. Retarget main before tagging a
+separate maintenance release from its previous development line.
+
 A final release also absorbs every prerelease section of its own base version. Cutting `2.0.0` folds `## [2.0.0.beta1]` and `## [2.0.0.rc1]` into `## [2.0.0] - <date>` and removes their headings, prerelease entries first and anything written after them second, so the notes a user reads for 2.0.0 are the whole story rather than three fragments. An empty `## [Unreleased]` is therefore legitimate for a final release cut straight from a release candidate. A beta or a release candidate has nothing to absorb, so an empty Unreleased section without entry files refuses: there is nothing new to publish.
 
 Review the diff and run the release contracts:
@@ -397,9 +425,13 @@ on always matches the bytes RubyGems published.
 
 ### One-off 1.6.3 security maintenance release
 
+This section records the published 1.6.3 preparation flow. Its approved SHA,
+base and test profile remain fixed; new 1.6.x work uses the separate 1.6.4
+profile below rather than changing the published candidate.
+
 The [security policy](SECURITY.md#supported-versions) supports 1.6.x security
-fixes until 2027-02-20. While main develops v2, the sole maintenance exception
-is `v1.6.3` from the short-lived `release/1.6.3` branch, descending from the
+fixes until 2027-02-20. The legacy maintenance exception is `v1.6.3` from the
+short-lived `release/1.6.3` branch, descending from the
 immutable v1.6.2 commit `4b40e17fd68122a70ccf00d9d2ffb8af42171d3d`.
 This is a stable patch, separate from the next v2 prerelease; it does not declare
 v2 final or establish a general-purpose maintenance publishing path.
@@ -460,19 +492,102 @@ fresh tag-push CI run. Updating main's tooling alone never authorizes different
 candidate bytes. Main's v2 release contract remains unchanged. Do not create or
 push tags, dispatch, publish, or claim 1.6.3 is available during preparation.
 
-### 2.0.1 maintenance CI contract
-
-The 2.0.1 candidate uses trusted main's reviewed maintenance profile, not this
-candidate's copy of the release tooling. That profile intentionally omits
-`exact_ci_jobs` and `package_spec`: validation uses the normal v2 required-job
-list and `spec/integration/packaged_gem_spec.rb`, rather than the legacy matrix
-or package spec. The 1.6.4 profile is separate and has no C-locale artifact-reader
-CI lane. Candidate evidence must identify the actual jobs and artifacts tested;
-profile approval and publication remain maintainer steps.
+### One-off 1.6.4 security maintenance release
+
+The next legacy maintenance profile allows only `v1.6.4` from `release/1.6.4`,
+descending from the immutable published v1.6.3 commit
+`60d6b7c4a3ddc421073f1fb57a7249eccb77826e`. Its approved candidate is
+`11672856b09d30b9fb3ac40c17aa336e795b91e7`, pinned by `V1_PATCH_APPROVED_SHA`
+in trusted main's `script/release_profile.rb`. All 19 required jobs passed in
+[protected-branch CI run 36205164768](https://github.com/lost-in-the/woods/actions/runs/36205164768).
+The published 1.6.3 pin and the separate 2.0.1 profile remain independent.
+
+1. Before creating the remote `release/1.6.4` target, require pull requests and
+   prevent force pushes and deletion through its effective branch rules. Create
+   it from the fixed v1.6.3 commit and keep the backport limited to that line.
+2. Use the inherited legacy `release:reopen[1.6.4.alpha]` and
+   `release:prepare[1.6.4]` adapter in clean, separately reviewed commits. Keep
+   the old automatic publisher disabled. Do not hand-edit VERSION or transplant
+   v2 documentation fences. The candidate PR targets `release/1.6.4`.
+3. Review the candidate's own CI definition, branch trigger and package tests.
+   Adding a branch trigger on main does not update the legacy branch. Require
+   every exact legacy matrix row listed in trusted main's maintenance profile:
+   unit, booted Rails, installed package, lint, coverage, security and build,
+   plus the 1.6.4-only `Maintenance security backends` job with real PostgreSQL
+   and MySQL. The published 1.6.3 job list stays unchanged.
+   After upstream branch CI passes, pin its exact prepared SHA through a
+   separate reviewed main PR. Private qualification does not replace this CI.
+4. Only after that pin merges may the maintainer tag the candidate and dispatch
+   its successful **tag-push** CI run. Both package rows test the same immutable
+   artifact using `maintenance_packaged_gem_spec.rb`. The trusted profile emits
+   MCP `0.23.0` for the Ruby 3.0 row; the newer Ruby row resolves the supported
+   SDK range. v2 profiles emit no legacy SDK floor and use normal v2 tests.
+
+All branch/base, exact SHA, tag/VERSION/changelog, unpublished-version,
+immutable-artifact and protected-environment checks apply. Maintenance history
+and publication checks repeat after approval, before RubyGems credentials; the
+remote tag is verified immediately before push. A changed candidate requires a
+new reviewed pin and fresh CI. Keep private qualification and advisory details
+private until the fixed gems are available. The approved pin does not itself
+publish a release or change live branch rules; the remaining gates still apply.
+
+### One-off 2.0.1 security maintenance release
+
+The separate v2 maintenance profile allows only `v2.0.1` from `release/2.0.1`,
+descending from the immutable v2.0.0 commit
+`838252a79b89846937be6dbd21e283fa7cad897f`. Its approved candidate is
+`07442a730c3d8f305711d81b3242bcb136433bd3`, pinned by `V2_MAINTENANCE_APPROVED_SHA`
+in trusted main's `script/release_profile.rb`. All 24 required jobs passed in
+[protected-branch CI run 36205538304](https://github.com/lost-in-the/woods/actions/runs/36205538304).
+The pin does not publish a release; fresh tag CI and artifact checks still apply.
+The legacy 1.6.3 and 1.6.4 profiles, SHA pins, CI rows and SDK floors are independent.
+
+1. Merge the trusted tooling and complete the separately reviewed move of main
+   to the 2.1 development line before a 2.0.1 tag exists. Keep the minimal 2.0.1
+   patch separate from main's accumulated development changes.
+2. Before creating the remote `release/2.0.1` branch, require pull requests and
+   prevent force pushes and deletion through its effective branch rules. Create
+   it from the fixed v2.0.0 commit, then review the narrow backport and release
+   controls on that line.
+3. Use the supported `release:reopen[2.0.1.alpha]` and
+   `release:prepare[2.0.1]` tasks in clean, separately reviewed commits. Never
+   edit VERSION or generated fences by hand. The generic preparation report's
+   instruction to merge into main does **not** apply to this candidate: its PR
+   targets `release/2.0.1`.
+4. Require the normal v2 CI contract, including live backends, MCP transports
+   and minimum dependencies, and review the complete candidate CI and package
+   tests. The maintenance branch needs the reviewed v2 CI definition with its
+   branch trigger; adding that trigger on main alone does not update the branch.
+   After upstream branch CI passes, pin its exact final SHA through a separate
+   reviewed main PR. A private report is not a substitute for upstream CI.
+5. Only after that pin merges may the maintainer tag the exact candidate and
+   dispatch with its successful **tag-push** CI run ID. The release workflow
+   runs normal `spec/integration/packaged_gem_spec.rb` on the same immutable
+   artifact in both Ruby/Rails package rows. It does not select the v1 job set,
+   legacy package spec or MCP 0.23.0 exception.
+
+All maintenance profiles require fresh branch/base and tag checks, exact
+VERSION/changelog agreement, an unpublished version, an immutable CI artifact
+and protected environment approval. They repeat history/publication validation
+after approval, before requesting RubyGems credentials, and verify the remote
+tag immediately before push. A changed candidate needs a new reviewed main pin
+and fresh tag-push CI. Keep the advisory unpublished until fixed gems are
+available. Tags, dispatch, publication and live branch rules remain maintainer
+steps; this runbook does not execute them.
+
+### Maintenance CI compatibility
+
+The 1.6.4 profile intentionally has no C-locale artifact-reader CI lane; its
+legacy matrix and installed maintenance-package contracts define its validation.
+The trusted-main 2.0.1 profile omits `exact_ci_jobs` and `package_spec`, so it
+inherits the normal v2 required-job list and
+`spec/integration/packaged_gem_spec.rb`. An omitted override does not select
+legacy jobs or waive validation. Review candidate CI against trusted-main
+`script/release_profile.rb` and `script/validate-release-run`.
 
 ### Stable branches
 
-A stable branch is `N-M-stable`, cut from the release tag. Create one only when a released line needs a patch after a newer major has shipped on `main`; until then, `main` is the development branch. The explicitly approved short-lived `release/1.6.3` security exception above does not establish an `N-M-stable` branch.
+A stable branch is `N-M-stable`, cut from the release tag. Create one only when a released line needs a patch after a newer major has shipped on `main`; until then, `main` is the development branch. The explicitly approved short-lived maintenance exceptions above do not establish an `N-M-stable` branch.
 
 ### What coding agents may do
 

data/README.md

@@ -51,7 +51,7 @@ These steps are for **Woods 2.x**. Choose a published 2.x version from [RubyGems
 <!-- release-state:version-banner -->
 <!-- release-state:end -->
 
-Once a stable 2.x release is published, add `gem "woods", "~> 2.0"` to your Gemfile's `:development` group. For a prerelease, use its exact published version instead. Then run:
+Add `gem "woods", "~> 2.1"` to your Gemfile's `:development` group for the 2.1 line. For an older release or a prerelease, use its published version and matching tag documentation. Then run:
 
 ```bash
 bundle install

data/docs/AGENT_GUIDE.md

@@ -86,6 +86,10 @@ Bare names identify units, not methods across the application. For example,
 be a FactoryBot factory in `spec/factories/`. Find the owning class with
 `search` and `lookup`, then pass its identifier with `#order`.
 
+**Included in Woods 2.1 (#593):** an unknown indexed flow unit returns
+`not_found`; a known unit with no discovered operations remains a successful
+empty flow. Neither outcome establishes whether an unindexed caller exists.
+
 Flow assembly derives operations from source. A receiverless local call such
 as `order` inside `CheckoutService#call` may remain visible without expanding
 the local method body. Follow it in source or trace `CheckoutService#order`
@@ -150,6 +154,10 @@ do not establish absence of production callers. Check source before claiming abs
 The `graph_coverage` notice makes this scope explicit in supporting responses;
 that metadata is included in Woods `2.0.0`.
 
+A supporting post-2.0 writer recovers additional [constant source references](EXTRACTOR_REFERENCE.md#constant-source-references)
+(included in Woods 2.1). Upgrading the reader alone cannot add relationships
+to an old index. The coverage warning still applies.
+
 Start at depth 1 or 2. A deeper unfiltered traversal can obscure the direct evidence that matters. Common relationship values include associations (`belongs_to`, `has_many`, `has_one`), code references, renders, redirects, form actions, and navigation links.
 
 Both return at most 50 nodes by default and say so with a `Showing N of M (truncated)`
@@ -322,3 +330,14 @@ on the evidence. Verify direct and inferred downstream candidates using typed
 lookup and `dependents explain:true`; suggested tests do not prove coverage.
 Silence does not establish no impact. See [bounded context hints](WATCH_DAEMON.md#optional-bounded-context-hints)
 for opt-in, independent refresh controls, limits and repeat suppression.
+
+### Library units with several source files
+
+In supporting builds (included in Woods 2.1), `source_contributors` identifies
+all physical files behind an aggregate library unit. Treat `file_path` as the
+primary display path. Use each contributor's own SHA256 and coordinates when
+citing it; the composite source hash is not the hash of the primary file.
+Generated headers and spans crossing contributors have no physical location.
+Per-file Git facts are separate, and a missing aggregate churn count does not
+mean the library has no history. Package/path scope must include all contributors
+to return the aggregate. See [library extraction](EXTRACTOR_REFERENCE.md#libextractor).

data/docs/AGENT_SETUP.md

@@ -140,9 +140,10 @@ client format is Claude Code (tested with 2.1.267).
 Create a private plan, inspect its paths and diff, then apply that same plan:
 
 ```bash
+woods_plan_dir="$(ruby -rtmpdir -e 'puts File.realpath(Dir.mktmpdir("woods-agent-plan-"))')"
 bundle exec woods-agent-config setup --client claude --scope project \
-  --root "$PWD" --instructions CLAUDE.md,AGENTS.md --plan /tmp/woods-setup.json --diff
-bundle exec woods-agent-config apply /tmp/woods-setup.json \
+  --root "$PWD" --instructions CLAUDE.md,AGENTS.md --plan "$woods_plan_dir/setup.json" --diff
+bundle exec woods-agent-config apply "$woods_plan_dir/setup.json" \
   --client claude --scope project --root "$PWD"
 ```
 
@@ -153,6 +154,10 @@ keep them private and remove them when no longer needed. `show FILE` prints its
 summary; `show FILE --diff` checks the original snapshots and prints a unified
 diff. Applying a changed snapshot fails rather than replacing the new content.
 A repeated identical setup makes no configuration edits.
+The example creates a private temporary directory and resolves its real path:
+on macOS, `/tmp` commonly points through a symlink. Plan files and managed
+targets reject symlink components; use the real parent directory for both
+preview and apply, and never use a symlink as the plan file itself.
 
 | Selection | Managed files |
 |---|---|
@@ -165,6 +170,15 @@ With `CLAUDE_CONFIG_DIR`, user scope uses that directory's `.claude.json`,
 configures the Index Server. Client trust and project approval remain Claude
 Code settings; apply does not change them.
 
+Included in Woods 2.1: project ownership ignores the user's home and
+`CLAUDE_CONFIG_DIR`, including that unused field in older receipts and plans.
+The application root, client, scope, target paths, and original file snapshots
+must still match. User-scoped ownership remains tied to its user configuration
+paths. Record the loaded revision before relying on this compatibility fix.
+Older executables cannot consume newly written project identities. Keep a
+supporting Woods revision for updates/removal, or remove owned configuration
+with it before permanently downgrading.
+
 Preflight runs the selected installed bundle, validates its index, and checks
 its actual registered capabilities. It does not boot Rails or contact an
 embedding provider. The bundle must already resolve in frozen mode; prepare
@@ -175,6 +189,12 @@ to the selected root. For Compose, also select `--mode compose --service web
 access that project. Preflight verifies the index and installed gem inside that
 service. Both host and container subprocesses have time limits.
 
+Included in Woods 2.1: host preflight preserves intended `BUNDLE_PATH`,
+`BUNDLE_APP_CONFIG`, and `BUNDLE_WITHOUT` settings while clearing activation of
+the caller's bundle and selecting the application's Gemfile. Older builds can
+report missing gems that the application already has; check the loaded revision
+and environment before reinstalling dependencies or writing bundle settings.
+
 Use `update --plan FILE` with the same client/scope/root and the desired launch
 options to change the owned entry or instruction selection. Update explicitly
 records the current template and installed-gem evidence; background hooks never

data/docs/BACKEND_MATRIX.md

@@ -27,6 +27,13 @@ The shape determines the capability matrix:
 | Cross-machine query | After deploying/copying `output_dir` | Yes, when the filesystem is shared | External vectors are shared; metadata/config still require a shared or deployed `output_dir` |
 | `woods.json` schema-versioned config snapshot | Yes | Yes | Yes |
 
+**Included in Woods 2.1:** `:local` cannot atomically reload snapshot vectors
+alongside its SQLite metadata in a running MCP server. `reload` reports degraded
+and retains the previous aligned state; restart `woods-mcp` after `woods:embed`
+to load the latest vectors. Write access alone does not resolve this limitation.
+The in-memory stores used by `:shared_filesystem` support transactional reload
+under the writer lock. See [MCP reload requirements](MCP_SERVERS.md#index-server).
+
 `Builder#build_vector_store` accepts exactly `:in_memory`, `:pgvector`, `:qdrant`, anything else raises `ArgumentError: Unknown vector_store`. `build_metadata_store` accepts `:in_memory`, `:sqlite`. `build_graph_store` accepts `:in_memory` only. Presets are `:local`, `:shared_filesystem`, `:postgresql`, and `:production`.
 
 ---

data/docs/CLIENT_HOOKS.md

@@ -79,6 +79,12 @@ deadline, locks and active-daemon behavior described in
 inside the application container. The host needs Bash 3.2 or later, Unix tools,
 and either jq or Ruby; OpenCode supplies its own JavaScript runtime.
 
+The Unicode Ruby-fallback repair (#592, included in Woods 2.1) explicitly
+decodes hook JSON and paths as UTF-8, including under `LC_ALL=C`. It covers edit
+queues, legacy queue import and Claude SessionStart checks. With older plugin
+hooks, install jq or use a UTF-8 locale; a zero hook exit status alone does not
+confirm that an edit was queued or refreshed.
+
 The complete event is validated before queueing. Empty/NUL paths, traversal,
 foreign-project paths and symlink path components are rejected. Deleted paths
 need not exist; contained symlinks are deliberately unsupported too. Spaces,