1.11.2

Install

Drop the attached .zip at your repo root without extracting it — the agent unpacks it as the first step. Then type this shortcut phrase as a chat message to your AI agent (Claude Code, Cursor, Codex, Junie, GitHub Copilot, Windsurf, Air, or Warp):

Install Wavefoundry

That is the only operator-typed command — the agent runs the rest of the install. Prerequisites: Python 3.11+, an MCP-aware agent host. Full walkthrough and host-specific notes in the README.

Upgrade

Already running Wavefoundry? Drop the attached .zip at your repo root without extracting it and type this shortcut phrase to your agent:

Upgrade Wavefoundry

The agent unpacks the zip, advances the framework, runs any required migrations and index rebuilds, and reloads the MCP server. Review the version notes below for anything that re-indexes or changes behavior on this upgrade.

---

Fixed

• Upgrading from an older version now removes the one-time install-wavefoundry.md bootstrap file from the project root. The cleanup added in 1.11.1 only ran during the extract step, which executes the previously-installed code when upgrading through the MCP server — so an upgrade from a version that predated the cleanup left the file behind, and it was cleared only on the following upgrade. The cleanup now also runs during the index-update step, which always executes the freshly installed code, so an upgrade from any prior version removes the file in the same run. The archive still ships the file at its root by design; only the extracted copy is removed.

1.11.1

Install

Drop the attached .zip at your repo root without extracting it — the agent unpacks it as the first step. Then type this shortcut phrase as a chat message to your AI agent (Claude Code, Cursor, Codex, Junie, GitHub Copilot, Windsurf, Air, or Warp):

Install Wavefoundry

That is the only operator-typed command — the agent runs the rest of the install. Prerequisites: Python 3.11+, an MCP-aware agent host. Full walkthrough and host-specific notes in the README.

Upgrade

Already running Wavefoundry? Drop the attached .zip at your repo root without extracting it and type this shortcut phrase to your agent:

Upgrade Wavefoundry

The agent unpacks the zip, advances the framework, runs any required migrations and index rebuilds, and reloads the MCP server. Review the version notes below for anything that re-indexes or changes behavior on this upgrade.

---

Fixed

• Upgrading from a version before 1.10.1 now provisions the collision-resistant lifecycle-ID scheme automatically. A repository upgraded from an older version through the MCP server could silently keep minting the previous, collision-prone ID scheme, because the code that installs the new scheme was not yet running when the upgrade was orchestrated — so a manual provisioning step was required. The upgrade's index phase, which always runs the freshly installed code, now provisions the new scheme idempotently and fail-safe, so a from-old-version upgrade self-heals without any manual step.
• Install and upgrade no longer leave the one-time install-wavefoundry.md bootstrap file in the project root. The distribution ships that single-use file at the archive root so the install agent can find it before the framework is unpacked, but nothing removed the extracted copy afterward, and every upgrade re-dropped it. Install and upgrade now delete it once it has been consumed; the archive-root packaging contract is unchanged.

Changed

• Closing a wave now reclaims search-index storage that has grown large. A heavy documentation session could balloon the on-disk docs index, because its full-text index accumulates stale versions that only a deep optimization reclaims — and that optimization previously ran only at install and upgrade. Wave close now runs a bloat-gated, lock-aware optimization that reclaims the leaked storage when the index has grown well beyond its expected size, and does nothing when the index is already compact. It never delays or blocks the close, and never triggers a heavy rebuild.

1.11.0

Install

Drop the attached .zip at your repo root without extracting it — the agent unpacks it as the first step. Then type this shortcut phrase as a chat message to your AI agent (Claude Code, Cursor, Codex, Junie, GitHub Copilot, Windsurf, Air, or Warp):

Install Wavefoundry

That is the only operator-typed command — the agent runs the rest of the install. Prerequisites: Python 3.11+, an MCP-aware agent host. Full walkthrough and host-specific notes in the README.

Upgrade

Already running Wavefoundry? Drop the attached .zip at your repo root without extracting it and type this shortcut phrase to your agent:

Upgrade Wavefoundry

The agent unpacks the zip, advances the framework, runs any required migrations and index rebuilds, and reloads the MCP server. Review the version notes below for anything that re-indexes or changes behavior on this upgrade.

---

Added

• The code graph extracts SQL far more accurately, including Oracle and T-SQL dialects. SQL graph extraction now recovers data-manipulation edges inside procedural loop bodies (so a routine's writes are no longer lost when they sit inside a WHILE/LOOP), distinguishes foreign-key / LIKE / CREATE TABLE AS references from ordinary column-type mentions in CREATE TABLE, handles CREATE TYPE, MERGE, and SELECT … INTO (including temp-table sigils so a #tmp/SELECT INTO #x target is not minted as a permanent table), and recognizes Oracle/T-SQL forms — pseudo-types, built-in scalar types, DUAL, FOR UPDATE SKIP LOCKED/NOWAIT, and bracket-qualified names. Schema DDL and stored-routine bodies now produce correct nodes and edges instead of phantom or missing relations. An upgrade materializes the new extraction automatically.

Fixed

• The local dashboard's stop and restart work on a dead instance. When a dashboard process exited without being reaped it lingered as a zombie that the stop/restart tools mistook for a live process and failed to clear, returning a stop failure with nothing actually stopped. The server now reaps the dashboard children it spawns — including opportunistically during ordinary editing — and classifies a recorded process with a zombie-safe check, so stop and restart reliably clear a dead dashboard and start fresh. Windows process handling is unchanged.
• The running dashboard no longer silently stops reflecting repository changes. Three compounding gaps could leave the page stale while the server kept serving: the single watcher thread could wedge on a slow filesystem call with no timeout, its directory-level watch missed edits to files nested inside a watched folder (the common wave-document editing pattern), and the browser had no recovery when the event stream was "connected" but no longer delivering updates. The watcher's snapshot collection is now bounded per cycle and surfaces a staleness signal on the dashboard API and event stream, change detection catches nested-file edits promptly, the client falls back to an active poll when updates stop arriving, and watcher activity is always written to dashboard.log so a future stall is diagnosable even under the MCP launch path.

Changed

• Reload the MCP server after an upgrade that changes the graph builder, or the graph is silently downgraded. An already-running MCP server keeps the previous graph extractor in memory for its whole lifetime. An upgrade re-extracts the graph at the new version, but the first graph query on a server that was not reloaded re-extracts the graph back down to the old version using its stale in-memory extractor — reverting the upgrade's graph work. The upgrade instructions now state plainly that reloading the server (wave_mcp_reload) or restarting the host after a graph-builder change is mandatory before issuing graph queries, and the upgrade's own code comments were corrected to describe how the graph phase actually works (it re-extracts during the upgrade; the first-query rebuild is only a safety net).

1.10.1

Install

Drop the attached .zip at your repo root without extracting it — the agent unpacks it as the first step. Then type this shortcut phrase as a chat message to your AI agent (Claude Code, Cursor, Codex, Junie, GitHub Copilot, Windsurf, Air, or Warp):

Install Wavefoundry

That is the only operator-typed command — the agent runs the rest of the install. Prerequisites: Python 3.11+, an MCP-aware agent host. Full walkthrough and host-specific notes in the README.

Upgrade

Already running Wavefoundry? Drop the attached .zip at your repo root without extracting it and type this shortcut phrase to your agent:

Upgrade Wavefoundry

The agent unpacks the zip, advances the framework, runs any required migrations and index rebuilds, and reloads the MCP server. Review the version notes below for anything that re-indexes or changes behavior on this upgrade.

---

Changed

• First setup now builds the code index by default and verifies SOCKS proxy support. wf setup validates the httpx[socks] dependency through socksio, builds docs and code indexes synchronously unless an explicit background-layer flag is used, and preserves the setup-selected CPU provider for accelerator prewarm/index subprocesses. Wave 1p9gr / 1p9gq.
• FTS indexes use no-position storage with compatible query shaping. Index rebuild and rewrite paths create FTS indexes without positional data, while docs/code query construction avoids phrase-shaped identifier searches that no-position FTS cannot satisfy. Wave 1p9jn / 1p9j1.
• Server-side full docs-lint scans have a configurable timeout. Lifecycle tools now use the full-scan timeout setting and return a clear validation failure on timeout instead of surfacing a raw subprocess timeout. Wave 1p9j0 / 1p9iu.

Fixed

• Setup fails closed when python3 is missing or too old. Setup now requires python3 --version to resolve to Python 3.11 or newer and gives repair guidance instead of implying a tool-venv MCP fallback can bypass the committed launch contract. Wave 1p9hi / 1p9hh.
• Native Windows lifecycle paths no longer corrupt stdout or fail common process checks. In-process server helpers keep diagnostics off the MCP JSON-RPC stdout channel, dashboard/process liveness uses Windows-safe checks, install-log reads tolerate non-UTF-8 logs, venv recreation detects failed removal, spaced dashboard roots parse correctly, line endings and cosmetic paths normalize, and server startup detects a missing venv before handshake. Wave 1p9hn / 1p9io, 1p9hi, 1p9hj, 1p9hk, 1p9hl, 1p9hm, 1p9i7.
• Setup/index child processes are bounded and keep the operator informed. Phase-1 setup children and model warmup paths now have per-step deadlines, no-progress watchdogs, clean timeout exits, corruption-quarantine bypass for model-warm timeouts, bounded post-EOF indexer waits, and unconditional indexer heartbeat prints during long embed/finalize phases. Wave 1p9j0 / 1p9it.
• Rendered hooks decode host stdin as UTF-8 across host surfaces. Generated Claude, Cursor, Windsurf, and GitHub/Copilot hooks reconfigure stdin consistently so non-ASCII file paths no longer mis-decode under cp1252-style host encodings. Wave 1p9j0 / 1p9iv.
• Windows metadata writes and development test paths are more robust. Atomic metadata replacement retries Windows sharing violations, rendered surfaces and secret-scan path filters keep forward-slash/line-ending behavior consistent, and the framework test runner uses a cross-platform run lock plus UTF-8 subprocess capture. Wave 1p9j0 / 1p9iw, 1p9ix, 1p9iy.
• Change and wave lookups report ambiguous lifecycle IDs instead of silently choosing one match. Lookup tools/resources now return candidate lists for ambiguous change or wave prefixes, keep change and wave namespaces separate, exclude wave.md from change lookup, and preserve token-anchored matching. Wave 1p9jn / 1p9ip.
• Apple Silicon CoreML provider-probe temp-dir failures fall back safely to CPU. Provider selection retries a bounded private temp-dir repair inside the probe window, records setup-cache/fresh-probe/operator-request provenance consistently, and reports recovery guidance without masking persistent CoreML failure. Wave 1p9j0 / 1p9lj.

1.10.0

Install

Drop the attached .zip at your repo root without extracting it — the agent unpacks it as the first step. Then type this shortcut phrase as a chat message to your AI agent (Claude Code, Cursor, Codex, Junie, GitHub Copilot, Windsurf, Air, or Warp):

Install Wavefoundry

That is the only operator-typed command — the agent runs the rest of the install. Prerequisites: Python 3.11+, an MCP-aware agent host. Full walkthrough and host-specific notes in the README.

Upgrade

Already running Wavefoundry? Drop the attached .zip at your repo root without extracting it and type this shortcut phrase to your agent:

Upgrade Wavefoundry

The agent unpacks the zip, advances the framework, runs any required migrations and index rebuilds, and reloads the MCP server. Review the version notes below for anything that re-indexes or changes behavior on this upgrade.

---

Added

• wave_index_optimize — reclaim on-disk index bloat without re-embedding. The semantic index tables accumulate on-disk bloat from incremental, edit-driven refreshes (superseded data fragments, stale full-text-search artifacts, old index versions). This new tool runs a tiered ladder — compact in place; if in-place compaction fails because of a LanceDB list-column corruption, rewrite the table fresh (which recomputes offsets and sidesteps the bug) and rebuild its vector and full-text indexes; fall back to a full rebuild only if a table is entirely unreadable — reclaiming the space with no embedding cost in the common case. It also runs automatically at the end of install and upgrade. A new MCP tool requires a one-time reconnect after upgrade to appear.
• Index size is visible in wave_index_health. The health response now includes a size object — the total on-disk index size plus a per-component breakdown (the docs and code tables and the graph) — so index growth and bloat are diagnosable without shelling out to du.
• wave_index_build_status reports an authoritative build-lock state. The response now carries a lock object whose held is determined by testing the real operating-system lock (not the presence of the lock file, which persists by design as a last-owner record), plus the last build's owner and whether it finished cleanly or was interrupted. Read lock.held to tell whether a build is actually running — do not read the lock file.

Changed

• Index refreshes are coalesced to the end of a turn instead of firing on every edit. Previously each file edit spawned a background reindex; a session of many edits churned the index — and re-grew its on-disk size — continuously. The post-edit hook now marks the index dirty and a single coalesced refresh runs when the turn ends (on hosts with a turn-end hook; other hosts use a longer debounce). The in-session staleness monitor is now a quiet-period safety net — it refreshes only once editing has settled and a recent build has not just run — so the two triggers no longer compete. A new indexing.monitor.quiet_period_seconds setting (default 5 minutes) tunes the safety net. Trade-off: semantic search reflects edits made earlier in the same turn only after the turn ends.
• Embedding precision is provider-aware: half-precision on a GPU, 8-bit on CPU. The indexer selects embedding precision from the active hardware — FP16 on a GPU/accelerator, INT8 on CPU — for faster indexing with no quality regression, and the reranker follows the same single machine classification so the two never disagree. Small incremental edit batches are routed to the CPU path to skip GPU padding waste, while full rebuilds always use the accelerator.
• Switching machines no longer forces a needless full re-embed. The index records the embedding precision class (full-precision vs. quantized), so moving a repository between a GPU and a CPU machine re-embeds only when the class actually changes, not on every provider switch.
• Dependency sync installs pinned version bumps, not just missing packages. Setup and upgrade now compare installed versions against the pinned specifications and install a newer pin even when the package is already present — so a bumped dependency (such as the LanceDB upgrade in this release) actually lands on upgrade instead of being skipped as "already installed."
• Index builds self-heal corruption-driven bloat. When in-place compaction fails because of the LanceDB list-column corruption, the build and the incremental refresh now automatically reclaim the table by rewriting it fresh — so a corrupted table recovers on the next build instead of growing unbounded.
• Shipped agent guidance no longer references the removed framework index. Seed prompts and rendered command docs that still described the retired separate "framework" index layer (removed when the framework's own seeds and docs were folded into each project's single index) now state the current single-index reality, so an upgrading repository's agent no longer follows stale guidance.
• Seed prompts state the journal/persona/manifest structure contracts verbatim. The seeds that guide an install agent to author agent journals, personas, and the prompt-surface manifest now list the exact required section headings (with case), the per-section bullet rule, the accepted salience markers, the persona Role:/Category: frontmatter, and the required manifest keys — so an agent produces a compliant artifact on the first pass instead of discovering the structure through repeated validation failures.
• Factor-review reconciliation is self-seeding and no longer noisy on a fresh install. A fresh install now seeds the factor-review lane set from the repository profile's applicable factors as a prunable default; and when the lane set is left empty while the profile still marks several factors applicable, the audit emits one consolidated, actionable advisory (naming the factors and the remediation) instead of a separate warning per factor on every audit. The review gate still keys off the configured lane set, not the profile.
• The post-edit docs-lint is incremental. Docs-lint was the last post-edit reaction that still scanned the whole docs/ tree on every edit (the index refresh and secret scan were already incremental). The post-edit hook now self-detects the git working-tree changed set and runs only the per-file checks on changed docs; a changed config file falls back to the full lint. The authoritative full corpus lint is unchanged and still runs at prepare, close, install, and upgrade — so a large repo gets fast per-edit feedback without weakening the gate.
• docs-lint has a configurable file-size guard. A markdown document larger than docs_lint.max_file_bytes (default 5 MB, matching the secret-scan and index file caps) now has its content validators skipped with a single loud, non-blocking warning naming the file, its size, and the remedy — so a pathological multi-megabyte generated document can't stall the regex passes or balloon lint memory, while a legitimately large document never fails the gate.
• docs-lint reads each file once per run and can report per-phase timings. The full lint previously re-read the same doc several times (once per validator that touches it); a transparent content cache keyed on file identity removes the redundant reads. A new --timings flag reports per-phase wall-clock (secrets/corpus/metadata/links) to help diagnose full-scan cost on large repositories.

Fixed

• Index tables no longer accumulate unbounded on-disk bloat. A full rebuild's finalize now compacts and reclaims the stale index artifacts a rebuild leaves behind (old vector/full-text index versions and data fragments), and incremental refreshes clean reliably — so the on-disk index no longer grows far past its working set over repeated builds.
• The index-build lock correctly detects a crashed or recycled owner. The lock's liveness check no longer trusts a bare process-exists signal (which a zombie or a recycled PID could pass), and background index builds launched by the long-running MCP server are now reaped instead of lingering as zombies — so a stale lock is reliably reclaimed on the next build and status surfaces stop reporting a dead build as running.
• The index-build lock recovery guidance no longer tells you to delete the lock file. The lock file persists by design as a last-owner record; the early-exit message now points at wave_index_build_status to check whether a build is actually running, and the "wait for the running build" case stays actionable.
• Embedding-model downloads succeed behind a corporate TLS proxy outside of wf setup. The corporate-CA trust bundle was previously applied only during setup's model prewarm; a model download triggered later — by wave_index_build, a background index refresh, or the first code_search / code_ask — ran without it and failed certificate verification behind a proxy. The trust bundle (with a reactive fallback ladder) is now applied at every model-download entry point, so first-use downloads succeed behind a proxy too.
• LanceDB auto-install no longer fails behind a corporate TLS proxy. When the indexer auto-installs LanceDB via pip on first use, it now applies the same TLS-conflict mitigation setup already used (removing the exclusive certificate-file variable and enabling native trust), so the auto-install succeeds behind a proxy instead of failing certificate verification.
• The post-edit docs-lint gate no longer hangs or fails early on a large repository. The docs-lint hook ran the linter unbounded (and was capped too low in an earlier build), so on a large docs tree it could stall the editing agent or reject an edit. It now runs under a generous, configurable timeout (docs_lint.hook_timeout_seconds in docs/workflow-config.json, default 120 s) and treats a timeout as advisory — the edit proceeds and `...

1.9.8

Install

Drop the attached .zip at your repo root without extracting it — the agent unpacks it as the first step. Then type this shortcut phrase as a chat message to your AI agent (Claude Code, Cursor, Codex, Junie, GitHub Copilot, Windsurf, Air, or Warp):

Install Wavefoundry

That is the only operator-typed command — the agent runs the rest of the install. Prerequisites: Python 3.11+, an MCP-aware agent host. Full walkthrough and host-specific notes in the README.

Upgrade

Already running Wavefoundry? Drop the attached .zip at your repo root without extracting it and type this shortcut phrase to your agent:

Upgrade Wavefoundry

The agent unpacks the zip, advances the framework, runs any required migrations and index rebuilds, and reloads the MCP server. Review the version notes below for anything that re-indexes or changes behavior on this upgrade.

---

Fixed

• Upgrades no longer abort when a pack-search location is sandboxed. The upgrade scans common pack-drop folders (including ~/Downloads) for a newer release zip; on macOS a privacy-sandboxed folder made that scan raise a permission error and stop the whole upgrade. A location it can't read is now logged, skipped, and listed under skipped_scan_locations in the upgrade summary — so you can grant access and re-run if a newer pack lives there, while the upgrade proceeds with the best pack it could reach.
• Shipped seeds no longer point at a wavefoundry-internal decision record. The stage-gate guidance added in 1.9.7 referenced an internal architecture-decision file that target repositories don't have, so an upgrading project's agent could cite a missing document. The references are removed (the rationale stays inline); the stage-gate reconciliation behavior is unchanged.

1.9.7

Install

Drop the attached .zip at your repo root without extracting it — the agent unpacks it as the first step. Then type this shortcut phrase as a chat message to your AI agent (Claude Code, Cursor, Codex, Junie, GitHub Copilot, Windsurf, Air, or Warp):

Install Wavefoundry

That is the only operator-typed command — the agent runs the rest of the install. Prerequisites: Python 3.11+, an MCP-aware agent host. Full walkthrough and host-specific notes in the README.

Upgrade

Already running Wavefoundry? Drop the attached .zip at your repo root without extracting it and type this shortcut phrase to your agent:

Upgrade Wavefoundry

The agent unpacks the zip, advances the framework, runs any required migrations and index rebuilds, and reloads the MCP server. Review the version notes below for anything that re-indexes or changes behavior on this upgrade.

---

Fixed

• The MCP server no longer hangs on the first model-loading call. Loading onnxruntime (for the GPU/provider probe behind wave_gpu_doctor, and for embedding/reranking on the first code_search / code_ask / docs_search) can make its native execution provider write diagnostics directly to the process's stdout file descriptor — which is the MCP JSON-RPC channel — corrupting the protocol on the first cold call after a host restart. The server now hands the protocol a private copy of stdout and points the real stdout file descriptor at the null device at startup, so no native library write can corrupt the channel; the GPU probe keeps an additional fd-level guard.
• uv dependency install no longer fails behind a corporate TLS proxy. When SSL_CERT_FILE pointed at a single corporate-root certificate (set so the embedding-model download trusts the proxy), uv treated that file as its exclusive trust anchor and rejected PyPI. Setup now runs uv with the certificate-file variables removed from its environment and native TLS enabled (OS trust store), and assembles a merged superset trust bundle for the certifi/requests consumers — so both dependency install and the model download succeed. The previous per-store model-download trust ladder is unchanged.
• The runtime .gitignore block is written programmatically and self-heals. The Wavefoundry runtime ignore entries (semantic index, logs, lock/state files, pack-drop archives) are now written by the surface renderer on every install / wf render-surfaces / upgrade, instead of relying on an agent following prose. A repository that wasn't a git repo at install time — or whose ignore step was skipped — now gets the block automatically on its next upgrade, with operator-authored entries preserved.
• Wave-close summaries no longer show stray dashes. A Markdown table separator row in a change doc's Decision Log no longer leaks a -------- entry into the generated close summary's key-decisions list.

Changed

• Secret-scan finding IDs: the legacy exc-### migration was removed. The one-release shim that auto-converted legacy exc-### finding IDs to the lifecycle <prefix>-sec form has been removed. The secrets gate keys on a finding's status, not its ID shape, so an existing ledger with old IDs still reads and gates correctly; new findings continue to mint <prefix>-sec IDs.
• The stage-gate sections stay a fixed contract on upgrade. Upgrade reconciliation now keeps the two named stage-gate sections in AGENTS.md (repository-code gate and product-code guard) as separate named sections rather than letting them be consolidated, because they're referenced by name across host entry docs and lifecycle prompts.

1.9.6

Install

Drop the attached .zip at your repo root without extracting it — the agent unpacks it as the first step. Then type this shortcut phrase as a chat message to your AI agent (Claude Code, Cursor, Codex, Junie, GitHub Copilot, Windsurf, Air, or Warp):

Install Wavefoundry

That is the only operator-typed command — the agent runs the rest of the install. Prerequisites: Python 3.11+, an MCP-aware agent host. Full walkthrough and host-specific notes in the README.

Upgrade

Already running Wavefoundry? Drop the attached .zip at your repo root without extracting it and type this shortcut phrase to your agent:

Upgrade Wavefoundry

The agent unpacks the zip, advances the framework, runs any required migrations and index rebuilds, and reloads the MCP server. Review the version notes below for anything that re-indexes or changes behavior on this upgrade.

---

Fixed

• No console windows flash on Windows. Framework subprocesses that don't need a console — the upgrade/index/graph pipeline spawns, the dashboard server, and the rendered hook bodies — now launch via pythonw.exe on Windows when their output is redirected. A console-subsystem python.exe could still flash a window despite CREATE_NO_WINDOW, especially for long-running detached or rapidly-spawned processes. POSIX and the MCP server launch are unchanged.
• The dashboard starts cleanly on Windows. The dashboard server now launches windowless, and the start path no longer false-reports url_not_ready or spawns duplicates that climb ports: it reconciles an already-serving dashboard before spawning and accepts a serving dashboard by URL reachability instead of requiring an exact recorded-PID match. The Windows lifetime lock was also moved off the byte the metadata occupies, so the dashboard can publish its URL while holding the lock (Windows mandatory byte-range locking had blocked that write).
• The dashboard renders horizontal rules. A --- (or ***/___) separator line now renders as a horizontal rule in the dashboard's document view instead of as literal dashes.

1.9.5

Install

Drop the attached .zip at your repo root without extracting it — the agent unpacks it as the first step. Then type this shortcut phrase as a chat message to your AI agent (Claude Code, Cursor, Codex, Junie, GitHub Copilot, Windsurf, Air, or Warp):

Install Wavefoundry

That is the only operator-typed command — the agent runs the rest of the install. Prerequisites: Python 3.11+, an MCP-aware agent host. Full walkthrough and host-specific notes in the README.

Upgrade

Already running Wavefoundry? Drop the attached .zip at your repo root without extracting it and type this shortcut phrase to your agent:

Upgrade Wavefoundry

The agent unpacks the zip, advances the framework, runs any required migrations and index rebuilds, and reloads the MCP server. Review the version notes below for anything that re-indexes or changes behavior on this upgrade.

---

Added

• wf gpu-doctor. The GPU/provider diagnostics previously reachable only through the wave_gpu_doctor MCP tool now have a wf gpu-doctor CLI subcommand, for CLI or no-MCP use. It reuses the same provider detection (no duplicated logic).

Changed

• wave_upgrade returns its structured summary on the primary call. The summary block (versions, files pruned, docs-gate result, index state, and the retired-surface reconciliation findings) is now emitted on the primary wave_upgrade() response, not only on the later cleanup phase — so agents read the computed fields, including the reconciliation list, directly from the main upgrade call.
• Retired-surface reconciliation runs on every upgrade. The reconciliation scan (stale .wavefoundry/bin/* references that should now be wf forms) now runs on any upgrade — including patch bumps and same-version build-successors — rather than only on major/minor bumps, since a patch can change or retire a surface during testing. The scan stays report-only and exclusion-aware.
• Secret-scan finding IDs now use the lifecycle format. docs/scan-findings.json findings use lifecycle-backed <prefix>-sec IDs (for example 1p8l0-sec) instead of the legacy exc-### sequence — new findings immediately, and existing findings are migrated once (idempotent and lossless) with a legacy_id recorded for traceability. New and migrated IDs are collision-safe against other lifecycle IDs and findings; the secrets-gate behavior and the file/rule/hash finding re-binding are unchanged, and legacy exc-### IDs are still tolerated.
• Reconciliation scan output is cleaner. Host permission/allow-rule files (e.g. .claude/settings.local.json) are now reported in a separate host_permission_flags channel in the wave_upgrade summary — operator-flagged, kept out of the auto-editable reconciliation list — and the scan no longer false-flags CHANGELOG.md (at any path) or the generated prompt-surface manifest.
• The secret scan always writes its ledger. A clean scan now writes docs/scan-findings.json as an empty [], so the file's presence confirms the scan ran; it changes only when findings change (no repeat-scan churn).

Fixed

• No more flashing console windows on native Windows. Every framework-spawned subprocess — including the indexing, graph, and secret-scanning multiprocessing pools (which the earlier per-spawn fix did not cover) — now runs window-free on Windows: the pools launch via the console-free pythonw.exe, falling back to serial execution when it is unavailable. No spawn inherits a blocking stdin, which previously could hang the upgrade.
• Native-Windows upgrade no longer crashes on encoding or paths. The upgrade uses the platform temp directory instead of a POSIX /tmp fallback (absent on Windows), forces UTF-8 on stdout at every CLI entry point so a non-ASCII glyph no longer raises a UnicodeEncodeError in a cp1252 console, and gives spawned indexer/graph/secrets children their own UTF-8 stdio — fixing the silent index-build failure and the garbled output.
• wave_install_audit validates artifacts correctly. The install-log parser no longer misreads an artifact's description text as a file path, so the install-state check verifies real on-disk artifacts again.
• MCP handler_not_ready during upgrade/reload. The server now lazily builds its handler from the known repository root, so a started server no longer reports handler_not_ready in the startup or post-reload window.

1.9.4

Install

Drop the attached .zip at your repo root without extracting it — the agent unpacks it as the first step. Then type this shortcut phrase as a chat message to your AI agent (Claude Code, Cursor, Codex, Junie, GitHub Copilot, Windsurf, Air, or Warp):

Install Wavefoundry

That is the only operator-typed command — the agent runs the rest of the install. Prerequisites: Python 3.11+, an MCP-aware agent host. Full walkthrough and host-specific notes in the README.

Upgrade

Already running Wavefoundry? Drop the attached .zip at your repo root without extracting it and type this shortcut phrase to your agent:

Upgrade Wavefoundry

The agent unpacks the zip, advances the framework, runs any required migrations and index rebuilds, and reloads the MCP server. Review the version notes below for anything that re-indexes or changes behavior on this upgrade.

---

Added

• New wf subcommands for agent-run framework scripts. wf codebase-map, wf render-surfaces, and wf secrets-scan join the cross-OS wf dispatcher so operators and agents stop guessing raw python3 .wavefoundry/framework/scripts/*.py invocations. Framework upgrade cleanup stays a manual python3 .wavefoundry/framework/scripts/prune_framework.py step — it needs the pre-upgrade MANIFEST that only the operator running the upgrade holds.
• Upgrade-time retired-surface reconciliation. A minor-or-major wf upgrade now scans the repository for stale references to retired framework surfaces (such as the per-command .wavefoundry/bin/* wrappers replaced by the cross-OS wf dispatcher) and reports an actionable file:line → suggested wf form list in place of generic recommend-only prose. The scan is report-only and exclusion-aware (it skips the framework pack, the generated index, historical records, and tests) and matches both forward-slash and backslash path references. Reconciliation guidance also names host permission/allow-rule files (for example .claude/settings.local.json) as a surface to flag for the operator rather than self-edit, and clarifies the gate-before-reload window during upgrade.
• Structured wave_upgrade summary. wave_upgrade now returns a parsed summary block (from/to version, files pruned, docs-gate result, index-update state, failed phase, and the reconciliation findings) plus a top-level next_step and next_tools, so agents read computed fields instead of scraping the raw output. The existing output and exit_code are unchanged and parsing is fail-safe.

Changed

• Committed MCP configs standardize on python3. Every generated host MCP config launches the server with command: "python3" and the repo-relative server.py, byte-identical across macOS, Linux, and native Windows. wf setup verifies python3 resolves to Python 3.11+ and, when it does not, fails closed with platform-aware guidance (install via Scoop/Microsoft Store on Windows, or your package manager / a symlink on macOS/Linux) plus the no-PATH per-machine fallback config. Setup does not modify your Python installation or PATH.

Fixed

• MCP helper subprocesses no longer contend with the host's JSON-RPC stdio. Server-side helper processes (docs-lint, gardener, sync-surfaces, upgrade phases, sensors) now run with stdin detached and intentional stdout/stderr handling — fixing wave_validate/docs-lint-over-MCP timeouts seen on some hosts — and suppress their console window on native Windows.
• Setup fails loudly instead of silently shipping a dead MCP config. When wf setup finds python3 does not resolve to Python 3.11+ on PATH, it reports the exact problem and exits non-zero with platform-aware guidance (make python3 resolve — Scoop/Microsoft Store on Windows, your package manager or a symlink on macOS/Linux — or use the per-machine absolute-venv-path fallback) rather than reporting success for a command: "python3" config the host cannot launch. Setup does not modify your Python installation or PATH.