woods 2.0.0.beta3 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (120) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +500 -420
  3. data/CONTRIBUTING.md +29 -17
  4. data/README.md +78 -178
  5. data/docs/AGENT_GUIDE.md +52 -11
  6. data/docs/AGENT_SETUP.md +34 -17
  7. data/docs/AUTOMATIC_MAINTENANCE.md +222 -0
  8. data/docs/BACKEND_MATRIX.md +18 -7
  9. data/docs/CLIENT_HOOKS.md +1 -1
  10. data/docs/CONFIGURATION_REFERENCE.md +105 -29
  11. data/docs/CONSOLE_MCP_SETUP.md +54 -9
  12. data/docs/DOCKER_SETUP.md +16 -1
  13. data/docs/EVALUATION.md +10 -4
  14. data/docs/EXTRACTOR_REFERENCE.md +23 -3
  15. data/docs/FAQ.md +14 -3
  16. data/docs/GETTING_STARTED.md +18 -17
  17. data/docs/INCREMENTAL_EXTRACTION.md +37 -8
  18. data/docs/INDEX_LAYOUT.md +2 -2
  19. data/docs/MCP_SERVERS.md +79 -7
  20. data/docs/MCP_TOOL_COOKBOOK.md +5 -5
  21. data/docs/MCP_WORKTREE_SETUP.md +55 -83
  22. data/docs/PUBLISHED_INDEX.md +17 -0
  23. data/docs/README.md +2 -1
  24. data/docs/RETRIEVAL_GUIDE.md +81 -13
  25. data/docs/SOURCE_FRESHNESS.md +1 -1
  26. data/docs/TOKEN_BENCHMARK.md +16 -10
  27. data/docs/TROUBLESHOOTING.md +142 -47
  28. data/docs/UPGRADING_TO_2.md +12 -6
  29. data/docs/WATCH_DAEMON.md +189 -24
  30. data/docs/WHY_WOODS.md +9 -5
  31. data/exe/woods-console +13 -11
  32. data/exe/woods-mcp-start +14 -9
  33. data/exe/woods-watch +5 -0
  34. data/lib/generators/woods/pgvector_generator.rb +8 -2
  35. data/lib/generators/woods/watch_generator.rb +53 -0
  36. data/lib/puma/plugin/woods.rb +10 -0
  37. data/lib/tasks/woods.rake +14 -0
  38. data/lib/woods/agent_configuration/applier.rb +5 -3
  39. data/lib/woods/agent_configuration/cli.rb +2 -2
  40. data/lib/woods/agent_configuration/layout.rb +13 -0
  41. data/lib/woods/cache/cache_middleware.rb +6 -0
  42. data/lib/woods/console/credential_scanner.rb +4 -3
  43. data/lib/woods/console/dispatch_pipeline.rb +7 -0
  44. data/lib/woods/console/embedded_executor.rb +31 -9
  45. data/lib/woods/console/sql_noise_stripper.rb +9 -7
  46. data/lib/woods/console/sql_table_scanner.rb +47 -7
  47. data/lib/woods/console/sql_validator.rb +49 -9
  48. data/lib/woods/console/sqlite_read_guard.rb +46 -0
  49. data/lib/woods/console/stdio_transport.rb +27 -0
  50. data/lib/woods/coordination/pipeline_lock.rb +3 -2
  51. data/lib/woods/embedding/indexer.rb +24 -14
  52. data/lib/woods/extractor.rb +70 -19
  53. data/lib/woods/extractors/declared_parent.rb +55 -0
  54. data/lib/woods/extractors/graphql_extractor.rb +2 -11
  55. data/lib/woods/extractors/lib_extractor.rb +10 -8
  56. data/lib/woods/extractors/mailer_extractor.rb +6 -10
  57. data/lib/woods/extractors/model_extractor.rb +1 -15
  58. data/lib/woods/extractors/poro_extractor.rb +10 -8
  59. data/lib/woods/extractors/shared_utility_methods.rb +22 -5
  60. data/lib/woods/git_command.rb +6 -7
  61. data/lib/woods/git_provenance.rb +4 -6
  62. data/lib/woods/mcp/bearer_auth.rb +2 -1
  63. data/lib/woods/mcp/bootstrapper.rb +20 -5
  64. data/lib/woods/mcp/config_resolver.rb +2 -1
  65. data/lib/woods/mcp/index_reader.rb +11 -2
  66. data/lib/woods/mcp/initialization_guidance.rb +1 -1
  67. data/lib/woods/mcp/renderers/markdown_renderer.rb +14 -8
  68. data/lib/woods/mcp/renderers/plain_renderer.rb +11 -7
  69. data/lib/woods/mcp/server.rb +63 -37
  70. data/lib/woods/mcp/tool_contract.rb +1 -1
  71. data/lib/woods/mcp/tool_response_renderer.rb +16 -0
  72. data/lib/woods/mcp/traversal_evidence_text.rb +1 -1
  73. data/lib/woods/mcp/traversal_response.rb +22 -0
  74. data/lib/woods/path_dispatcher.rb +6 -5
  75. data/lib/woods/published_index/typed_unit_reader.rb +40 -3
  76. data/lib/woods/published_index.rb +2 -2
  77. data/lib/woods/rake_helpers.rb +2 -12
  78. data/lib/woods/retrieval/corpus_status.rb +46 -0
  79. data/lib/woods/retrieval/lexical_assembler.rb +14 -3
  80. data/lib/woods/retrieval/lexical_index.rb +2 -1
  81. data/lib/woods/retriever.rb +19 -7
  82. data/lib/woods/session_tracer/file_store.rb +6 -1
  83. data/lib/woods/source_inputs/consumer_errors.rb +4 -0
  84. data/lib/woods/storage/local_corpus_stats.rb +32 -0
  85. data/lib/woods/storage/metadata_store.rb +20 -0
  86. data/lib/woods/storage/pgvector.rb +6 -2
  87. data/lib/woods/storage/vector_store.rb +10 -0
  88. data/lib/woods/temporal/json_snapshot_store.rb +35 -7
  89. data/lib/woods/version.rb +1 -1
  90. data/lib/woods/watch/child_environment.rb +30 -0
  91. data/lib/woods/watch/cli.rb +91 -0
  92. data/lib/woods/watch/daemon.rb +73 -11
  93. data/lib/woods/watch/event_stream.rb +70 -0
  94. data/lib/woods/watch/guardian.rb +142 -0
  95. data/lib/woods/watch/installation/layout.rb +70 -0
  96. data/lib/woods/watch/installation/options.rb +128 -0
  97. data/lib/woods/watch/installation/planner.rb +128 -0
  98. data/lib/woods/watch/installation/probe.rb +101 -0
  99. data/lib/woods/watch/installation/receipt.rb +77 -0
  100. data/lib/woods/watch/installation/recovery.rb +64 -0
  101. data/lib/woods/watch/installation/templates.rb +58 -0
  102. data/lib/woods/watch/installation.rb +56 -0
  103. data/lib/woods/watch/lifecycle.rb +182 -0
  104. data/lib/woods/watch/managed_child.rb +113 -0
  105. data/lib/woods/watch/managed_cleanup.rb +48 -0
  106. data/lib/woods/watch/managed_process.rb +144 -0
  107. data/lib/woods/watch/puma_adapter.rb +87 -0
  108. data/lib/woods/watch/puma_child.rb +66 -0
  109. data/lib/woods/watch/supervision_records.rb +95 -0
  110. data/lib/woods/watch/supervision_status.rb +104 -0
  111. data/lib/woods/watch/supervisor.rb +161 -0
  112. data/lib/woods/watch/supervisor_reporting.rb +46 -0
  113. data/plugin/.claude-plugin/plugin.json +1 -1
  114. data/plugin/hooks/woods-input-rules.sh +4 -4
  115. data/plugin/skills/woods-agent-enable/SKILL.md +7 -1
  116. data/plugin/skills/woods-diagnose/SKILL.md +134 -34
  117. data/plugin/skills/woods-investigate/SKILL.md +54 -15
  118. data/plugin/skills/woods-mcp-config/SKILL.md +38 -11
  119. data/plugin/skills/woods-setup/SKILL.md +72 -15
  120. metadata +38 -5
@@ -7,7 +7,7 @@ description: Configure Woods MCP connections with the exact client JSON shapes a
7
7
 
8
8
  ## Managed configuration availability
9
9
 
10
- `woods-agent-config` (#407) is unreleased after `2.0.0.beta2`. First record the
10
+ `woods-agent-config` (#407) is available in Woods `2.0.0.beta3`. First record the
11
11
  installed version and test `bundle exec woods-agent-config --help` in the
12
12
  selected application bundle. When supported, use its saved setup/update/remove
13
13
  plan and explicit client/scope/root selection; apply the reviewed plan within
@@ -30,7 +30,7 @@ This skill describes the Woods 2.x line; the authoritative minimum version lives
30
30
 
31
31
  Default to Index-only. It reads generated code context and exposes 14 tools. Console MCP boots Rails and reads live data; ask before enabling it.
32
32
 
33
- Initialization guidance (#402) is unreleased after `2.0.0.beta2`; check the
33
+ Initialization guidance (#402) is available in Woods `2.0.0.beta3`; check the
34
34
  installed gem before expecting MCP `instructions`. Supporting servers provide
35
35
  a short workflow through initialization or modern discovery; protocol
36
36
  `2024-11-05` omits it. Missing instructions alone are not a connection failure.
@@ -55,11 +55,26 @@ when unavailable. See the
55
55
 
56
56
  Use this shape for any stdio-capable MCP client, adapted to the client's configuration location. `woods-mcp-start` validates and launches; it does not install or auto-restart.
57
57
 
58
- Writer-version provenance (#323) is unreleased; check the installed gem version's
59
- release notes before expecting `index.woods_version` in `woods_status`. It reports
58
+ MCP registration does not start automatic indexing. Existing readers observe
59
+ published generations without reconnecting; separately verify the watcher owner,
60
+ startup catch-up, and a real edit. Native launcher/Puma installation (#538) is
61
+ included in Woods `2.0.0`: check installed `woods-watch` and generator help
62
+ before offering it. Preserve the existing external service in Docker/Grove and
63
+ keep its source/index aligned across switches. See
64
+ [automatic maintenance](https://github.com/lost-in-the/woods/blob/main/docs/AUTOMATIC_MAINTENANCE.md).
65
+
66
+ Writer-version provenance (#323) is available in Woods `2.0.0.beta3`; check the installed
67
+ gem version's release notes before expecting `index.woods_version` in `woods_status`. It reports
60
68
  the last manifest publisher, independently of `server.version`. Treat missing/null
61
69
  as unknown and see [writer provenance](https://github.com/lost-in-the/woods/blob/main/docs/PUBLISHED_INDEX.md#manifest-writer-provenance).
62
70
 
71
+ Verify semantic retrieval separately from structural `ready`. A reachable
72
+ provider and bootstrap `hydrated` can coexist with empty stores. If the recorded
73
+ reader supports #549, inspect `retriever.corpus` for local record counts and
74
+ known-empty diagnostics; absent or unknown counts require checking embedding
75
+ artifacts. These fields do not certify embedding coverage. See the
76
+ [readiness distinction](https://github.com/lost-in-the/woods/blob/main/docs/RETRIEVAL_GUIDE.md#semantic-corpus-diagnostics).
77
+
63
78
  When Woods is installed only in Docker, prefer running the server through the application container:
64
79
 
65
80
  ```json
@@ -74,12 +89,18 @@ When Woods is installed only in Docker, prefer running the server through the ap
74
89
  }
75
90
  ```
76
91
 
77
- Use a host-side bundle only after verifying Ruby, the application bundle, and the index are available on the host. Always pass the path visible to the process that runs `woods-mcp`.
92
+ Use a host-side bundle only after verifying Ruby, the application bundle, and the index are available on the host. Always pass the path visible to the process that runs `woods-mcp`. Prefer an explicit index path on all versions. Woods `2.0.0` includes `WOODS_OUTPUT` as a fallback after the positional path and `WOODS_DIR`; check the installed version's configuration guide before relying on it. `woods-mcp-start` still refuses a missing path rather than selecting its working directory.
93
+
94
+ For linked worktrees, verify source/index alignment and the extraction's Git
95
+ branch and exact SHA. Preserve the complete shared Git layout and select the
96
+ worktree-specific directory when using the installed version's `WOODS_GIT_DIR`
97
+ override; the shared root selects the primary checkout's HEAD. Follow the
98
+ [worktree mount guide](https://github.com/lost-in-the/woods/blob/main/docs/TROUBLESHOOTING.md#git-directory-mounts-for-linked-worktrees).
78
99
 
79
100
  A read-only index mount is sufficient for structural tools. The `reload` tool for in-memory semantic retrieval also takes Woods' shared on-disk writer lock, so the MCP process needs write access to the index directory. Without it, reload returns a typed degraded error and keeps serving the previous aligned generation. Either grant that access or restart the MCP process after publishing a new embedded index.
80
101
 
81
102
  For host MCP reading a container daemon's shared index, foreign heartbeat trust
82
- (#321) is unreleased. Verify the installed gem version's release notes before
103
+ (#321) is available in Woods `2.0.0.beta3`. Verify the installed gem version's release notes before
83
104
  offering `WOODS_WATCH_TRUST_FOREIGN_HOST=1` in the MCP environment. It makes
84
105
  `woods_status.watch.alive` use the same bounded freshness policy as task readers;
85
106
  see [cross-host liveness](https://github.com/lost-in-the/woods/blob/main/docs/WATCH_DAEMON.md#cross-host-liveness).
@@ -97,8 +118,8 @@ end
97
118
 
98
119
  The token authenticates HTTP requests and is not sent by a stdio client.
99
120
  Before suggesting `console_mcp_http_enabled = false`, verify that the installed
100
- version supports it: the option is unreleased in Woods 2.0.0.beta2. Supported
101
- stdio-only hosts can set it to `false` and omit the HTTP token; existing
121
+ version supports it: the option is available in Woods `2.0.0.beta3`. Supported
122
+ stdio-only hosts can set it to `false` and omit the HTTP token; older
102
123
  versions require the token at production boot whenever Console is enabled.
103
124
  For HTTP, retain a strong token, allowed origins and TLS. Use installed-version
104
125
  tagged documentation; the [canonical Console guide](https://github.com/lost-in-the/woods/blob/main/docs/CONSOLE_MCP_SETUP.md)
@@ -116,6 +137,12 @@ Then add a direct Console process:
116
137
 
117
138
  For Docker/SSH, configure `~/.woods/console.yml` or `WOODS_CONSOLE_CONFIG`; the launcher owns process replacement. Direct Docker stdio uses `docker exec -i`, or `docker compose exec -T` to disable Compose's pseudo-TTY while retaining stdin.
118
139
 
140
+ Reserve stdout for MCP. Through Woods `2.0.0.beta4`, configure the Console
141
+ process's Rails logger to use stderr or a file, including logs during queries.
142
+ Runtime stdout isolation is included in Woods `2.0.0`; verify the installed
143
+ revision before relying on it. Use the rake entry point to capture Rails boot
144
+ output as well.
145
+
119
146
  Console registers nine default tools. `config.console_embedded_read_tools = true` explicitly adds `console_sql` and `console_query` for eleven total. Tier 2, Tier 3, and `console_eval` are inventory-only in supported packaged modes.
120
147
 
121
148
  ## Shape 3: Authenticated Console HTTP
@@ -142,14 +169,14 @@ Canonical guide: [MCP_SERVERS.md](https://github.com/lost-in-the/woods/blob/main
142
169
 
143
170
  ## Lexical retrieval capability check
144
171
 
145
- This is a development capability. Before proposing it, verify the installed gem
172
+ Lexical retrieval is available from `2.0.0.beta3`. Before proposing it, verify the installed gem
146
173
  exposes `Woods::Configuration#retrieval_mode` and its matching guide documents
147
174
  `WOODS_RETRIEVAL_MODE`. Keep the installed-version preflight; do not infer support
148
175
  from the plugin version or an unreleased checkout.
149
176
 
150
177
  When supported, put `WOODS_RETRIEVAL_MODE=lexical` in the environment of the
151
178
  process launching Index MCP (stdio or HTTP). A Rails initializer alone is not
152
- loaded by that process. Confirm `woods_status.retriever.mode` reports `lexical`.
179
+ loaded by that process. Restart the MCP server after changing its environment, then confirm `woods_status.retriever.mode` reports `lexical`. A beta3 no-provider error may omit this option; it does not mean embeddings are required for explicit lexical mode.
153
180
  See the [retrieval guide](https://github.com/lost-in-the/woods/blob/main/docs/RETRIEVAL_GUIDE.md#embedding-free-lexical-retrieval)
154
181
  for the supported contract, checked against the installed gem version.
155
182
 
@@ -165,7 +192,7 @@ query. Scoping can hide relevant cross-boundary relationships, so broaden the
165
192
  request deliberately when the task needs them. See the
166
193
  [scope contract](https://github.com/lost-in-the/woods/blob/main/docs/RETRIEVAL_GUIDE.md#explicit-package-and-source-path-scopes).
167
194
 
168
- ## Source-content freshness (unreleased #405)
195
+ ## Source-content freshness (Woods 2.0.0.beta3; #405)
169
196
 
170
197
  Check installed-version support before using `woods-extract` or the optional
171
198
  `woods_status.source_check` argument. With support, inspect
@@ -9,7 +9,7 @@ Install a structural Index Server first. Embeddings and Console MCP are separate
9
9
 
10
10
  ## Managed configuration availability
11
11
 
12
- `woods-agent-config` (#407) is unreleased after `2.0.0.beta2`. First record the
12
+ `woods-agent-config` (#407) is available in Woods `2.0.0.beta3`. First record the
13
13
  installed version and test `bundle exec woods-agent-config --help` in the
14
14
  selected application bundle. When supported, use its saved setup/update/remove
15
15
  plan and explicit client/scope/root selection; apply the reviewed plan within
@@ -38,7 +38,7 @@ This skill describes the Woods 2.x line; the authoritative minimum version lives
38
38
 
39
39
  Choose the published version using the canonical
40
40
  [installation guide](https://github.com/lost-in-the/woods/blob/main/docs/GETTING_STARTED.md#1-install-the-gem)
41
- and its linked README release table. When only prereleases are published for
41
+ and confirm the selected version on RubyGems. When only prereleases are published for
42
42
  2.x, add the exact published beta/RC constraint shown there to the development
43
43
  group; `~> 2.0` does not select prereleases. Use `gem "woods", "~> 2.0"` only after
44
44
  a stable 2.x release is published. Follow the selected version's tag docs and
@@ -74,8 +74,8 @@ bin/rails woods:stats
74
74
 
75
75
  If extraction fails, reproduce Rails boot and eager loading first. Do not inspect internal payload files when Woods tasks provide the check.
76
76
 
77
- Writer-version provenance (#323) is unreleased; check the installed gem version's
78
- release notes before expecting `woods_status.index.woods_version`. When present,
77
+ Writer-version provenance (#323) is available in Woods `2.0.0.beta3`; check the installed
78
+ gem version's release notes before expecting `woods_status.index.woods_version`. When present,
79
79
  it names the last manifest publisher; `server.version` names the MCP reader.
80
80
  Missing/null means unknown. A matching version after an incremental run never
81
81
  replaces a required full upgrade extraction. See [writer provenance](https://github.com/lost-in-the/woods/blob/main/docs/PUBLISHED_INDEX.md#manifest-writer-provenance).
@@ -108,11 +108,61 @@ When Woods is installed only in Docker, launch it through the application servic
108
108
  }
109
109
  ```
110
110
 
111
- Reconnect and call `woods_status`, then `search`, `lookup`, and `dependents` for a known class. The normal Index Server has 14 tools. `codebase_retrieve` requires configured embeddings in semantic mode; see the lexical capability check below for the opt-in provider-free mode.
111
+ For linked worktrees, verify source/index alignment and the extraction's Git
112
+ branch and exact SHA. Preserve the complete shared Git layout and select the
113
+ worktree-specific directory when using the installed version's `WOODS_GIT_DIR`
114
+ override; the shared root selects the primary checkout's HEAD. Follow the
115
+ [worktree mount guide](https://github.com/lost-in-the/woods/blob/main/docs/TROUBLESHOOTING.md#git-directory-mounts-for-linked-worktrees).
112
116
 
113
- Offer to add `bundle exec rake woods:watch` to the existing development process manager. When authorized, it catches up missed changes and automatically maintains the structural index; the Index Server refreshes on its next call, so ordinary edits need no manual extraction or MCP restart. Use the standalone watch command; do not prepend the `environment` task. Check the installed version's watch guide before relying on automatic startup reconciliation. State that live boot-captured changes require supervisor restart, Docker may need `WOODS_WATCH_POLL=1`, and semantic vectors still need `woods:embed_incremental`.
117
+ Reconnect and call `woods_status`, then `search`, `lookup`, and `dependents` for a known class. The normal Index Server has 14 tools. `codebase_retrieve` requires configured embeddings in semantic mode; see the lexical capability check below for the opt-in provider-free mode.
114
118
 
115
- Foreign-host heartbeat trust (`WOODS_WATCH_TRUST_FOREIGN_HOST=1`, #321) is unreleased.
119
+ Structural readiness alone does not verify semantic retrieval. If that mode is
120
+ requested, confirm an embedding run and a useful retrieval result. Readers with
121
+ #549 expose `retriever.corpus` counts; check the installed capability before
122
+ expecting them. Unknown counts are not zero, and positive counts do not certify
123
+ complete embedding coverage. See
124
+ [corpus diagnostics](https://github.com/lost-in-the/woods/blob/main/docs/RETRIEVAL_GUIDE.md#semantic-corpus-diagnostics).
125
+
126
+ Offer one automatic-maintenance owner within the setup scope. The managed launcher,
127
+ watcher generator, and Puma adapter (#538) are **included in Woods `2.0.0`**.
128
+ Record the loaded gem path and revision, then verify `bundle exec woods-watch
129
+ --help` and `bin/rails generate woods:watch --help` before using them. Follow the
130
+ [managed startup runbook](https://github.com/lost-in-the/woods/blob/main/docs/WATCH_DAEMON.md#managed-development-startup):
131
+ Puma for simple Rails startup, an explicit verified Foreman command/Procfile, or
132
+ the existing external Docker/Grove supervisor. Preview before applying within
133
+ existing authorization. Preserve `bin/dev`; never claim an unused Procfile is
134
+ active. Keep the portable receipt with generated files and respect edit conflicts.
135
+ Puma installation supports the normal default `config/puma.rb` route; an existing
136
+ environment-specific file or custom `-C` route needs a different explicit owner.
137
+ The #542 guard included in Woods `2.0.0` checks plugin files in the active gem, including Git/path
138
+ bundles. Older gems without the plugin skip watcher startup. Existing generated
139
+ Puma setups need an explicit `--operation update --mode puma` (preview first) to
140
+ upgrade the owned guard in place; repeating setup preserves it. The wrapper and
141
+ Foreman entry still require a supporting gem. Remove owned setup before a permanent
142
+ downgrade; do not hand-edit the receipt or its managed block.
143
+ Run setup in the normal application bundle environment. The #540 fix in Woods `2.0.0`
144
+ preserves `BUNDLE_PATH`, `BUNDLE_APP_CONFIG`, and group selection during preflight;
145
+ older Git builds may falsely report missing gems. Check the loaded revision
146
+ before changing persistent Bundler settings to work around that error.
147
+ The #544 fix in Woods `2.0.0` makes generator refusals exit nonzero. Earlier Git builds
148
+ can exit zero after printing a refusal; verify the diagnostic and applied setup
149
+ before treating their exit status as installation success.
150
+ For an interrupted install, use the generator's `--operation recover --pretend`
151
+ before applying recovery; preserve journals when concurrent edits block it. The
152
+ Rails generator command boots the app first: use the runbook's direct bundled
153
+ Ruby recovery helper when an initializer prevents boot.
154
+
155
+ On older gems, use the raw task only with a restart-capable external supervisor;
156
+ do not place it bare in Foreman, where exit 75 stops the whole stack. Use the
157
+ application's real Rails task entrypoint without a preceding `environment` task.
158
+ Managed mode rejects idle TTL and does not take over conflicting owners. Verify
159
+ startup catch-up, an edit, and a planned restart through the existing MCP reader;
160
+ for Grove, also verify worktree/source/index alignment. Docker may need polling.
161
+ Semantic vectors still need `woods:embed_incremental`; hooks and MCP registration
162
+ do not install watcher startup.
163
+
164
+ Foreign-host heartbeat trust (`WOODS_WATCH_TRUST_FOREIGN_HOST=1`, #321) is available in
165
+ Woods `2.0.0.beta3`.
116
166
  Check the installed gem version against its release notes before offering it;
117
167
  do not assume installing this plugin upgrades the gem. For a supporting version,
118
168
  follow [cross-host liveness](https://github.com/lost-in-the/woods/blob/main/docs/WATCH_DAEMON.md#cross-host-liveness)
@@ -120,14 +170,14 @@ and set the opt-in in each task/MCP reader of a shared container index. Explain
120
170
  the 15-minute crash-detection delay and preserve one supervisor per daemon.
121
171
 
122
172
  For slow bind mounts, check whether the installed version documents
123
- `WOODS_WATCH_POLL_INTERVAL` before suggesting it; this setting is unreleased
124
- in Woods 2.0.0.beta2. Where supported, a positive value such as `2.5` reduces
173
+ `WOODS_WATCH_POLL_INTERVAL` before suggesting it; this setting is available in Woods
174
+ `2.0.0.beta3`. Where supported, a positive value such as `2.5` reduces
125
175
  polling frequency at the cost of detection latency. Use the installed preflight version to select tagged documentation; the
126
176
  [canonical watch guide](https://github.com/lost-in-the/woods/blob/main/docs/WATCH_DAEMON.md)
127
177
  tracks current source and may describe unreleased behavior.
128
178
 
129
179
  The plugin ships opt-in refresh and session-start hooks. The expanded refresh
130
- contract (#408) is unreleased after Woods 2.0.0.beta2: first verify the installed
180
+ contract (#408) is available in Woods `2.0.0.beta3`: first verify the installed
131
181
  gem exposes `woods:hook_refresh` through the actual application command. Do not
132
182
  infer support from the plugin version. With support, edits to standard services,
133
183
  controllers, jobs, views, concerns, locales, supported tests/lib files, routes,
@@ -146,7 +196,7 @@ The refresh worker's deadline starts after the complete event input has been
146
196
  collected, validated, and queued; it does not bound input collection. It includes
147
197
  subsequent batches, but cancelling Docker exec does not prove its container
148
198
  process stopped. See the [hook deadline and retry contract](https://github.com/lost-in-the/woods/blob/main/docs/WATCH_DAEMON.md#hooks-for-agent-sessions).
149
- Source freshness (#405) is unreleased after beta2: verify the installed command
199
+ Source freshness (#405) is available in Woods `2.0.0.beta3`: verify the installed command
150
200
  exposes `woods:source_status` and `woods-extract` before using it. Supporting
151
201
  SessionStart hooks check source content and report missing/failed evidence as
152
202
  unknown; silence does not acknowledge queued refresh work. Follow the [hook guide](https://github.com/lost-in-the/woods/blob/main/docs/WATCH_DAEMON.md#hooks-for-agent-sessions)
@@ -154,17 +204,24 @@ for transport, retry and custom-root limits.
154
204
 
155
205
  ## Ask before expanding scope
156
206
 
207
+ For pgvector, match the provider output and migration dimensions within 1–2,000. Default `text-embedding-3-large` output (3,072) needs an explicit smaller provider width or another backend; never silently truncate vectors. Early adapter/generator refusal is included in Woods `2.0.0`, so check the installed revision. See the [dimension contract](https://github.com/lost-in-the/woods/blob/main/docs/CONFIGURATION_REFERENCE.md#pgvector-postgresql).
208
+
157
209
  Require explicit approval before adding Ollama/OpenAI, pgvector/Qdrant, secrets, Console MCP/live-data access, HTTP transport, or purge overrides. The `:local` preset avoids cloud keys but requires the `sqlite3` gem, an installed/running Ollama service, and a pulled model (`ollama pull nomic-embed-text` by default); `:shared_filesystem` avoids sqlite3 but still uses Ollama. Recommend `gem "tokenizers", "~> 0.5"` for exact counting on dense Ruby source, while stating that it is optional.
158
210
 
159
211
  ## Handoff
160
212
 
161
- Report the Woods version, branch, files changed, commands/results, index path, MCP calls verified, semantic retrieval status, Console status, and unresolved risks. Never infer availability from source schemas alone.
213
+ Report the Woods version/revision, branch, files changed, commands/results, index
214
+ path, MCP calls verified, semantic retrieval and Console status, and unresolved
215
+ risks. For automatic maintenance record the owner, actual startup command,
216
+ completed catch-up, observed edit/restart, and worktree verification. Report
217
+ refresh hooks, session checks, and context hints separately. Never infer
218
+ availability from source schemas or a live process alone.
162
219
 
163
220
  Canonical runbook: [AGENT_SETUP.md](https://github.com/lost-in-the/woods/blob/main/docs/AGENT_SETUP.md).
164
221
 
165
222
  ## Lexical retrieval capability check
166
223
 
167
- This is a development capability. Before proposing it, verify the installed gem
224
+ Lexical retrieval is available from `2.0.0.beta3`. Before proposing it, verify the installed gem
168
225
  exposes `Woods::Configuration#retrieval_mode` and its matching guide documents
169
226
  `WOODS_RETRIEVAL_MODE`. Keep the installed-version preflight; do not infer support
170
227
  from the plugin version or an unreleased checkout.
@@ -175,7 +232,7 @@ remains the default; setting up embeddings is a separate choice.
175
232
  See the [retrieval guide](https://github.com/lost-in-the/woods/blob/main/docs/RETRIEVAL_GUIDE.md#embedding-free-lexical-retrieval)
176
233
  for the supported contract, checked against the installed gem version.
177
234
 
178
- ## Explicit edit adapters (unreleased #409)
235
+ ## Explicit edit adapters (Woods 2.0.0.beta3; #409)
179
236
 
180
237
  Check the installed gem exposes `woods:hook_refresh` before enabling hooks.
181
238
  Claude's registered wrapper covers one documented edit path; OpenCode 1.18.27
@@ -190,7 +247,7 @@ user's setup request. Follow [client hooks](https://github.com/lost-in-the/woods
190
247
  ## Optional context hints
191
248
 
192
249
  Check installed `bundle exec woods-hook-context --help` before enabling
193
- `WOODS_HOOK_CONTEXT_ENABLED=1`; this capability is unreleased after beta2 and the
250
+ `WOODS_HOOK_CONTEXT_ENABLED=1`; this capability is available in Woods `2.0.0.beta3` and the
194
251
  plugin does not upgrade the gem. Context and refresh opt-ins are independent;
195
252
  `WOODS_HOOKS_DISABLED=1` disables both. Native Claude context is synchronous and
196
253
  bounded, with served-generation and pre-refresh/unknown labels. Verify candidate
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: woods
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.0.0.beta3
4
+ version: 2.0.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Leah Armstrong
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2026-09-18 00:00:00.000000000 Z
11
+ date: 2026-09-23 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: mcp
@@ -113,6 +113,7 @@ description: |
113
113
  email:
114
114
  - info@leah.wtf
115
115
  executables:
116
+ - woods-watch
116
117
  - woods-mcp
117
118
  - woods-mcp-start
118
119
  - woods-console-mcp
@@ -133,6 +134,7 @@ files:
133
134
  - assets/woods-wordmark-white-with-bg.png
134
135
  - docs/AGENT_GUIDE.md
135
136
  - docs/AGENT_SETUP.md
137
+ - docs/AUTOMATIC_MAINTENANCE.md
136
138
  - docs/BACKEND_MATRIX.md
137
139
  - docs/CLIENT_HOOKS.md
138
140
  - docs/CONFIGURATION_REFERENCE.md
@@ -171,11 +173,14 @@ files:
171
173
  - exe/woods-mcp
172
174
  - exe/woods-mcp-http
173
175
  - exe/woods-mcp-start
176
+ - exe/woods-watch
174
177
  - lib/generators/woods/install_generator.rb
175
178
  - lib/generators/woods/pgvector_generator.rb
176
179
  - lib/generators/woods/templates/add_pgvector_to_woods.rb.erb
177
180
  - lib/generators/woods/templates/create_woods_tables.rb.erb
178
181
  - lib/generators/woods/templates/woods.rb.tt
182
+ - lib/generators/woods/watch_generator.rb
183
+ - lib/puma/plugin/woods.rb
179
184
  - lib/tasks/woods.rake
180
185
  - lib/tasks/woods_checks.rake
181
186
  - lib/tasks/woods_evaluation.rake
@@ -234,6 +239,8 @@ files:
234
239
  - lib/woods/console/sql_noise_stripper.rb
235
240
  - lib/woods/console/sql_table_scanner.rb
236
241
  - lib/woods/console/sql_validator.rb
242
+ - lib/woods/console/sqlite_read_guard.rb
243
+ - lib/woods/console/stdio_transport.rb
237
244
  - lib/woods/console/table_gate.rb
238
245
  - lib/woods/console/tool_specs.rb
239
246
  - lib/woods/console/tools/tier1.rb
@@ -294,6 +301,7 @@ files:
294
301
  - lib/woods/extractors/configuration_extractor.rb
295
302
  - lib/woods/extractors/controller_extractor.rb
296
303
  - lib/woods/extractors/database_view_extractor.rb
304
+ - lib/woods/extractors/declared_parent.rb
297
305
  - lib/woods/extractors/decorator_extractor.rb
298
306
  - lib/woods/extractors/engine_extractor.rb
299
307
  - lib/woods/extractors/event_extractor.rb
@@ -386,6 +394,7 @@ files:
386
394
  - lib/woods/mcp/traversal_evidence_index.rb
387
395
  - lib/woods/mcp/traversal_evidence_page.rb
388
396
  - lib/woods/mcp/traversal_evidence_text.rb
397
+ - lib/woods/mcp/traversal_response.rb
389
398
  - lib/woods/mcp/version_aware_tool_dispatch.rb
390
399
  - lib/woods/model_name_cache.rb
391
400
  - lib/woods/notion/client.rb
@@ -427,6 +436,7 @@ files:
427
436
  - lib/woods/resilience/retryable_provider.rb
428
437
  - lib/woods/resolved_config.rb
429
438
  - lib/woods/retrieval/context_assembler.rb
439
+ - lib/woods/retrieval/corpus_status.rb
430
440
  - lib/woods/retrieval/lexical_assembler.rb
431
441
  - lib/woods/retrieval/lexical_index.rb
432
442
  - lib/woods/retrieval/query_classifier.rb
@@ -466,6 +476,7 @@ files:
466
476
  - lib/woods/source_inputs/verifier.rb
467
477
  - lib/woods/storage/graph_store.rb
468
478
  - lib/woods/storage/inapplicable_backend.rb
479
+ - lib/woods/storage/local_corpus_stats.rb
469
480
  - lib/woods/storage/metadata_store.rb
470
481
  - lib/woods/storage/pgvector.rb
471
482
  - lib/woods/storage/qdrant.rb
@@ -488,10 +499,32 @@ files:
488
499
  - lib/woods/util/uuid5.rb
489
500
  - lib/woods/version.rb
490
501
  - lib/woods/watch/boot_snapshot.rb
502
+ - lib/woods/watch/child_environment.rb
503
+ - lib/woods/watch/cli.rb
491
504
  - lib/woods/watch/daemon.rb
505
+ - lib/woods/watch/event_stream.rb
506
+ - lib/woods/watch/guardian.rb
507
+ - lib/woods/watch/installation.rb
508
+ - lib/woods/watch/installation/layout.rb
509
+ - lib/woods/watch/installation/options.rb
510
+ - lib/woods/watch/installation/planner.rb
511
+ - lib/woods/watch/installation/probe.rb
512
+ - lib/woods/watch/installation/receipt.rb
513
+ - lib/woods/watch/installation/recovery.rb
514
+ - lib/woods/watch/installation/templates.rb
515
+ - lib/woods/watch/lifecycle.rb
492
516
  - lib/woods/watch/listen_watcher.rb
517
+ - lib/woods/watch/managed_child.rb
518
+ - lib/woods/watch/managed_cleanup.rb
519
+ - lib/woods/watch/managed_process.rb
493
520
  - lib/woods/watch/polling_watcher.rb
521
+ - lib/woods/watch/puma_adapter.rb
522
+ - lib/woods/watch/puma_child.rb
494
523
  - lib/woods/watch/status.rb
524
+ - lib/woods/watch/supervision_records.rb
525
+ - lib/woods/watch/supervision_status.rb
526
+ - lib/woods/watch/supervisor.rb
527
+ - lib/woods/watch/supervisor_reporting.rb
495
528
  - lib/woods/watch/tree_scan.rb
496
529
  - lib/woods/watch/watcher.rb
497
530
  - plugin/.claude-plugin/plugin.json
@@ -514,10 +547,10 @@ licenses:
514
547
  - MIT
515
548
  metadata:
516
549
  homepage_uri: https://github.com/lost-in-the/woods
517
- source_code_uri: https://github.com/lost-in-the/woods/tree/v2.0.0.beta3
518
- changelog_uri: https://github.com/lost-in-the/woods/blob/v2.0.0.beta3/CHANGELOG.md
550
+ source_code_uri: https://github.com/lost-in-the/woods/tree/v2.0.0
551
+ changelog_uri: https://github.com/lost-in-the/woods/blob/v2.0.0/CHANGELOG.md
519
552
  bug_tracker_uri: https://github.com/lost-in-the/woods/issues
520
- documentation_uri: https://github.com/lost-in-the/woods/tree/v2.0.0.beta3/docs
553
+ documentation_uri: https://github.com/lost-in-the/woods/tree/v2.0.0/docs
521
554
  rubygems_mfa_required: 'true'
522
555
  post_install_message:
523
556
  rdoc_options: []