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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +500 -420
- data/CONTRIBUTING.md +29 -17
- data/README.md +78 -178
- data/docs/AGENT_GUIDE.md +52 -11
- data/docs/AGENT_SETUP.md +34 -17
- data/docs/AUTOMATIC_MAINTENANCE.md +222 -0
- data/docs/BACKEND_MATRIX.md +18 -7
- data/docs/CLIENT_HOOKS.md +1 -1
- data/docs/CONFIGURATION_REFERENCE.md +105 -29
- data/docs/CONSOLE_MCP_SETUP.md +54 -9
- data/docs/DOCKER_SETUP.md +16 -1
- data/docs/EVALUATION.md +10 -4
- data/docs/EXTRACTOR_REFERENCE.md +23 -3
- data/docs/FAQ.md +14 -3
- data/docs/GETTING_STARTED.md +18 -17
- data/docs/INCREMENTAL_EXTRACTION.md +37 -8
- data/docs/INDEX_LAYOUT.md +2 -2
- data/docs/MCP_SERVERS.md +79 -7
- data/docs/MCP_TOOL_COOKBOOK.md +5 -5
- data/docs/MCP_WORKTREE_SETUP.md +55 -83
- data/docs/PUBLISHED_INDEX.md +17 -0
- data/docs/README.md +2 -1
- data/docs/RETRIEVAL_GUIDE.md +81 -13
- data/docs/SOURCE_FRESHNESS.md +1 -1
- data/docs/TOKEN_BENCHMARK.md +16 -10
- data/docs/TROUBLESHOOTING.md +142 -47
- data/docs/UPGRADING_TO_2.md +12 -6
- data/docs/WATCH_DAEMON.md +189 -24
- data/docs/WHY_WOODS.md +9 -5
- data/exe/woods-console +13 -11
- data/exe/woods-mcp-start +14 -9
- data/exe/woods-watch +5 -0
- data/lib/generators/woods/pgvector_generator.rb +8 -2
- data/lib/generators/woods/watch_generator.rb +53 -0
- data/lib/puma/plugin/woods.rb +10 -0
- data/lib/tasks/woods.rake +14 -0
- data/lib/woods/agent_configuration/applier.rb +5 -3
- data/lib/woods/agent_configuration/cli.rb +2 -2
- data/lib/woods/agent_configuration/layout.rb +13 -0
- data/lib/woods/cache/cache_middleware.rb +6 -0
- data/lib/woods/console/credential_scanner.rb +4 -3
- data/lib/woods/console/dispatch_pipeline.rb +7 -0
- data/lib/woods/console/embedded_executor.rb +31 -9
- data/lib/woods/console/sql_noise_stripper.rb +9 -7
- data/lib/woods/console/sql_table_scanner.rb +47 -7
- data/lib/woods/console/sql_validator.rb +49 -9
- data/lib/woods/console/sqlite_read_guard.rb +46 -0
- data/lib/woods/console/stdio_transport.rb +27 -0
- data/lib/woods/coordination/pipeline_lock.rb +3 -2
- data/lib/woods/embedding/indexer.rb +24 -14
- data/lib/woods/extractor.rb +70 -19
- data/lib/woods/extractors/declared_parent.rb +55 -0
- data/lib/woods/extractors/graphql_extractor.rb +2 -11
- data/lib/woods/extractors/lib_extractor.rb +10 -8
- data/lib/woods/extractors/mailer_extractor.rb +6 -10
- data/lib/woods/extractors/model_extractor.rb +1 -15
- data/lib/woods/extractors/poro_extractor.rb +10 -8
- data/lib/woods/extractors/shared_utility_methods.rb +22 -5
- data/lib/woods/git_command.rb +6 -7
- data/lib/woods/git_provenance.rb +4 -6
- data/lib/woods/mcp/bearer_auth.rb +2 -1
- data/lib/woods/mcp/bootstrapper.rb +20 -5
- data/lib/woods/mcp/config_resolver.rb +2 -1
- data/lib/woods/mcp/index_reader.rb +11 -2
- data/lib/woods/mcp/initialization_guidance.rb +1 -1
- data/lib/woods/mcp/renderers/markdown_renderer.rb +14 -8
- data/lib/woods/mcp/renderers/plain_renderer.rb +11 -7
- data/lib/woods/mcp/server.rb +63 -37
- data/lib/woods/mcp/tool_contract.rb +1 -1
- data/lib/woods/mcp/tool_response_renderer.rb +16 -0
- data/lib/woods/mcp/traversal_evidence_text.rb +1 -1
- data/lib/woods/mcp/traversal_response.rb +22 -0
- data/lib/woods/path_dispatcher.rb +6 -5
- data/lib/woods/published_index/typed_unit_reader.rb +40 -3
- data/lib/woods/published_index.rb +2 -2
- data/lib/woods/rake_helpers.rb +2 -12
- data/lib/woods/retrieval/corpus_status.rb +46 -0
- data/lib/woods/retrieval/lexical_assembler.rb +14 -3
- data/lib/woods/retrieval/lexical_index.rb +2 -1
- data/lib/woods/retriever.rb +19 -7
- data/lib/woods/session_tracer/file_store.rb +6 -1
- data/lib/woods/source_inputs/consumer_errors.rb +4 -0
- data/lib/woods/storage/local_corpus_stats.rb +32 -0
- data/lib/woods/storage/metadata_store.rb +20 -0
- data/lib/woods/storage/pgvector.rb +6 -2
- data/lib/woods/storage/vector_store.rb +10 -0
- data/lib/woods/temporal/json_snapshot_store.rb +35 -7
- data/lib/woods/version.rb +1 -1
- data/lib/woods/watch/child_environment.rb +30 -0
- data/lib/woods/watch/cli.rb +91 -0
- data/lib/woods/watch/daemon.rb +73 -11
- data/lib/woods/watch/event_stream.rb +70 -0
- data/lib/woods/watch/guardian.rb +142 -0
- data/lib/woods/watch/installation/layout.rb +70 -0
- data/lib/woods/watch/installation/options.rb +128 -0
- data/lib/woods/watch/installation/planner.rb +128 -0
- data/lib/woods/watch/installation/probe.rb +101 -0
- data/lib/woods/watch/installation/receipt.rb +77 -0
- data/lib/woods/watch/installation/recovery.rb +64 -0
- data/lib/woods/watch/installation/templates.rb +58 -0
- data/lib/woods/watch/installation.rb +56 -0
- data/lib/woods/watch/lifecycle.rb +182 -0
- data/lib/woods/watch/managed_child.rb +113 -0
- data/lib/woods/watch/managed_cleanup.rb +48 -0
- data/lib/woods/watch/managed_process.rb +144 -0
- data/lib/woods/watch/puma_adapter.rb +87 -0
- data/lib/woods/watch/puma_child.rb +66 -0
- data/lib/woods/watch/supervision_records.rb +95 -0
- data/lib/woods/watch/supervision_status.rb +104 -0
- data/lib/woods/watch/supervisor.rb +161 -0
- data/lib/woods/watch/supervisor_reporting.rb +46 -0
- data/plugin/.claude-plugin/plugin.json +1 -1
- data/plugin/hooks/woods-input-rules.sh +4 -4
- data/plugin/skills/woods-agent-enable/SKILL.md +7 -1
- data/plugin/skills/woods-diagnose/SKILL.md +134 -34
- data/plugin/skills/woods-investigate/SKILL.md +54 -15
- data/plugin/skills/woods-mcp-config/SKILL.md +38 -11
- data/plugin/skills/woods-setup/SKILL.md +72 -15
- 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
|
|
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
|
|
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
|
-
|
|
59
|
-
|
|
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
|
|
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
|
|
101
|
-
stdio-only hosts can set it to `false` and omit the HTTP token;
|
|
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
|
-
|
|
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.
|
|
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 (
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
124
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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 (
|
|
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
|
|
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
|
|
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-
|
|
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
|
|
518
|
-
changelog_uri: https://github.com/lost-in-the/woods/blob/v2.0.0
|
|
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
|
|
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: []
|