Hotfix for v3.9.28 — bridge payload shape (#482 round 3)
After v3.9.28 fixed the subscriber-loading order, handlers fired for
every bridge event but immediately short-circuited because
event.payload.experience was undefined. The bridge had been publishing a
flat payload { experienceId, domain, agent, task, ... } that didn't
match handleExperienceCaptured's destructure.
Fix: bridge now publishes the canonical nested
{ experience: TaskExperience-shaped, reward } shape that matches the
existing publisher in src/learning/experience-capture.ts:1043.
Also dropped the domain-specific fan-out events (test-execution.TestRunCompleted,
coverage-analysis.CoverageGapDetected, etc.) — their handlers expect
domain-event-specific fields (runId, passed, failed, gapId, riskScore)
that hooks don't capture, so publishing them with undefined fields
recorded degenerate experiences. Universal learning.ExperienceCaptured
is now the bridge's sole publication.
Integration test now uses requirements-validation domain (per Jordi's
suggestion) so the universal-event path is the sole thing being tested,
not masked by a fan-out side effect.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Hotfix for v3.9.27 — bridge subscriber wiring (#482)
The CapturedExperienceBridge shipped in v3.9.27 published events into a
kernel with no subscribers because lazyLoading: true left domain plugins
un-initialized when the bridge's first drain ran. Cursor advanced past
the rows; events were silently lost.
Fix: kernel.initialize() now eagerly loads all enabled domain plugins
before starting the bridge. CLI commands opt out via the new
enableExperienceBridge: false flag to keep their fast startup. Added
end-to-end integration test (real kernel + real plugin + real drain →
asserts kv_store has learning:experience:* key).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- AbortSignal threading bounds ReasoningBank.initialize() (#478)
prevents leaked init from runaway patterns.rvf writes
- CapturedExperienceBridge wires hook activity to domain plugins (#479)
via kernel-side drain of captured_experiences
- Removes dead v3-qe-bridge.sh, two stale planning docs, five orphan
workers in qe-workers.ts (subsumed by LearningConsolidationWorker)
Net: +430 / -2,090 lines
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Ten learning-pipeline fixes (#453, #454, #455, #456, #460, #461, #462,
#463, #464, #465) plus dup closures (#457-#459). Tightens the #465
sentinel sweep with the same task_json discriminator the LIMIT-1 close
uses, preserving the #451 ownership split (route sentinels owned by
post-route, pre-task sentinels by post-task). Updates the regression
suite to reflect the new sweep behavior.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(hooks): post-route Stop hook closes route sentinels 1:1 (#451)
The `route` hook fires on UserPromptSubmit and writes a sentinel row to
routing_outcomes with quality_score=-1, expecting `post-task` to close
it. But `post-task` only fires on PostToolUse ^(Task|Agent)$, which is
rare in direct-work sessions (Bash/Edit/Read without spawning sub-
agents). Sentinels accumulated indefinitely — Jordi reported 123+
unresolved rows per session. Stream D never converged.
Changes:
1. New `aqe hooks post-route` subcommand
(src/cli/commands/hooks-handlers/routing-hooks.ts)
Closes the most-recent unresolved route sentinel using a
`task_json NOT LIKE '%"taskId"%'` discriminator that isolates
route entries from pre-task entries. Quality formula collapses the
6-dim outcome formula for unknown duration:
0.325 + 0.25·success + 0.10·1.0
= 0.675 (success) / 0.425 (failure)
2. Inverse discriminator on updateRoutingOutcomeQuality
(src/cli/commands/hooks-handlers/hooks-dream-learning.ts)
Added `task_json LIKE '%"taskId"%'` to the WHERE clause so
post-task only ever closes pre-task sentinels. Without this,
post-task could grab a stale route sentinel by accident and
miscredit duration to a row that wasn't about a Task() call.
Symmetric counterpart to the post-route filter.
3. Stop-hook wiring in both init template paths
(src/init/phases/07-hooks.ts + src/init/init-wizard-hooks.ts)
Added `npx agentic-qe hooks post-route --success true --json`
to the Stop block. Timeout 5000ms, continueOnError: true, so a
failed post-route cannot block session teardown.
4. CLI help text (src/cli/commands/hooks.ts)
Added example for the new subcommand.
5. Regression test (tests/unit/cli/commands/post-route.test.ts)
4 tests using in-memory better-sqlite3:
- Closes most-recent route sentinel; leaves pre-task sentinels
and resolved rows untouched
- quality_score = 0.425 when --success false
- No-op when only pre-task sentinels exist (discriminator works)
- No-op on second invocation when only one sentinel was outstanding
Bug-introduce verification: stashed routing-hooks.ts, ran new test —
all 4 cases failed (Commander rejects unknown subcommand). Restored
fix, all 4 pass. Test distinguishes pre-fix and post-fix states.
Co-authored-by: Jordi Izquierdo <noreply@github.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* chore(release): bump version to v3.9.25
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(hooks): post-task runs Stream B/D/F when --task-id is missing (#449)
The shipped PostToolUse hook command for Task/Agent matchers is
`npx agentic-qe hooks post-task --task-id "$TOOL_RESULT_agent_id" --success --json`
Claude Code does not populate $TOOL_RESULT_agent_id, so the flag arrives
empty and options.taskId is falsy on every real hook invocation. The
`if (options.taskId)` gate inside post-task then short-circuited the
entire Stream B/D/F learning chain:
- reasoningBank.recordOutcome — never called
- persistTaskOutcome — never called (no captured_experiences,
experience_applications, qe_trajectories, dream_insights.applied)
- updateRoutingOutcomeQuality — never called (routing_outcomes
sentinels accumulated unfilled at success=0/quality_score=-1)
- updateHookRouterQValue — never called (rl_q_values stayed empty
forever)
Same regression was fixed in v3.9.21 (patch 030) and silently came
back in v3.9.23.
Fix:
- Remove the `if (options.taskId)` gate in post-task. Use
`hook-${Date.now()}` fallback for the patternId / experience id
when the caller didn't supply one. The bridge lookup in
persistTaskOutcome keys by `ORDER BY created_at DESC LIMIT 1`
(not by taskId), so Stream F's Bellman Q-update still finds the
bridge payload it needs.
- Remove the parallel `&& options.taskId` clause from the pre-task
routing_outcomes sentinel write at line 195 — same root cause.
- Add `DO NOT REINTRODUCE` comment blocks at both sites pointing
at #449 and patch 030.
Test: tests/unit/cli/commands/task-hooks-no-taskid.test.ts mocks
hooks-shared and asserts persistTaskOutcome / updateHookRouterQValue
fire when --task-id is absent. Bug-introduce verification:
re-introducing the gate makes the no-taskId test fail with the
expected "called 1 times, but got 0 times".
Co-authored-by: Jordi Izquierdo <noreply@github.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* chore(release): bump version to v3.9.24
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Closes#447. Three-layer fix for the upsert-returns-wrong-UUID bug that
silently broke Stream C of self-learning:
* sqlite-persistence.ts: SELECT actual id after ON CONFLICT(name,
qe_domain, pattern_type) — the upsert keeps the existing row's UUID
but we were returning the input one, leaving downstream callers with
a UUID that didn't exist in qe_patterns.
* rvf-pattern-store.ts: capture the SQLite return value and realign
pattern.id BEFORE the HNSW ingest so the index keys stay consistent
with the source-of-truth table.
* qe-hooks.ts QEAgentCompletion: change const → let on
effectivePatternId, capture storeResult.value.id from the auto-create
storePattern call, feed it into recordOutcome. Without this, every
auto-created pattern's outcome silently failed with "Pattern not
found", which is why qe_pattern_usage stayed at 0 forever.
Also (#448): excluded tests/unit/learning/qe-reasoning-bank.test.ts and
aqe-learning-engine.test.ts from test:unit:fast — both chronically hang
the vitest fork worker on heavy module graph load. Same pattern as
domain-handlers.test.ts already excluded from test:ci. Issue #448 tracks
the root-cause investigation.
Thanks to @Jordi-Izquierdo-DDS for the #447 diagnosis.
Co-Authored-By: Jordi Izquierdo <jordi-izquierdo-dds@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Fixes routing learning loop — bootstrap patterns now reach HNSW index
(#445). After this release, `patternCount` in routing hook output is
non-zero, existing installs auto-backfill `.agentic-qe/patterns.rvf` from
SQLite on next startup.
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Bumps version + fleetVersion across package.json, plugin.json, and the
two skills-manifest.json copies. Adds CHANGELOG entry and release notes.
Includes one fix discovered during the release-prep e2e: stale-lock
recovery in shared-rvf-adapter's openOrCreateRvf ladder. The native
@ruvector/rvf-node binding leaves a `<file>.lock` artifact when a
process exits without calling close() — a behaviour that frequently
happens in CLI flows and that the previous always-create code path
masked. With open-or-create, those stale locks now surfaced as
`LockHeld` errors. The ladder now detects that, removes the stale
lock file, and retries open exactly once. E2E confirms RVF native
recovers cleanly across init → CLI invocation boundaries.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Bundles fixes for issue #439 (Windows install) and Jordi RUFLO patches
P020 (RVF init) + P220 (hypergraph blindness).
Windows install (#439):
- Move hnswlib-node from dependencies to optionalDependencies so
installs no longer fail on Windows boxes without VS C++ Build Tools;
HnswAdapter already routes around a missing native binary at runtime.
- Replace HNSWIndex.ts top-level static `import hnswlib from
'hnswlib-node'` with a lazy require so package load survives the
optional dep being absent.
- README + preinstall.cjs: document toolchain requirement and disclose
that the JS fallback degrades to O(N) brute-force when @ruvector/gnn
is also unavailable (Windows default — no win32 prebuilds ship).
- ADR-090 amendment reconciling the move with ADR-081's optional-dep +
JS-fallback intent.
RVF init (Jordi P020):
- Root cause: shared-rvf-adapter and pattern-store factory always called
RvfDatabase.create(), which throws `0x0303 FsyncFailed` when the .rvf
file already exists from a prior init phase. Reproduced and confirmed
against both 0.1.7 and 0.1.8 native binaries — not a version
regression.
- Fix: race-tolerant open-or-create ladder (try open → fall back to
create → retry open on create-race) with dim() verification after
open. Mismatched-dim files are closed and the caller degrades rather
than corrupting silently.
Hypergraph (Jordi P220):
- Drop the original flushEdgesToHypergraph (wrote `call`/`extends`
edges that no production query reads — devil's-advocate review caught
it as dead infrastructure).
- Add HypergraphEngine.synthesizeTestCoverage that re-tags test files
type='test' and writes `covers` edges from each test file to
functions in the source files it imports. This is the shape
findUntestedFunctions / findImpactedTests actually filter on.
- E2E verified: untested correctly excludes covered functions;
impacted-tests returns the right test file.
Verification:
- `npm run build` clean
- 276/276 tests pass across HNSW, RVF, KG, coordinator, hypergraph
suites (5 new synthesizeTestCoverage tests; replaced 4 obsolete
flush tests)
- E2E on fresh project: aqe init clean, hooks stats shows
nativeAvailable: true, code index logs `Test coverage synthesized`,
hg untested + hg impacted return useful results
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The shipped `aqe init` template wired the UserPromptSubmit hook to
`npx agentic-qe hooks route --task "$PROMPT" --json`, but Claude Code
never exposed `$PROMPT` as an env var — only stdin event JSON. The
shell expanded `"$PROMPT"` to `""`, so every prompt routed as empty
and `routing_outcomes.task_json` was persisted as `{"description":""}`,
silently breaking the routing learning loop.
- routing-hooks.ts: demote --task to optional, read stdin (500ms
timeout) and extract prompt/user_prompt/command/tool_input.{prompt,
description}; explicit error when neither source has content
- 07-hooks.ts and init-wizard-hooks.ts: drop --task "\$PROMPT", let
the CLI read stdin directly. isAqeHookEntry still matches both
shapes, so existing projects upgrade on `aqe init --upgrade`
- tests/unit/cli/commands/hooks-routing.test.ts: 10 unit tests
covering all event shapes, fallback ordering, malformed JSON, and
empty-field skip
Verified end-to-end: piped a Claude Code-shaped event into a fresh
project's configured route command and confirmed task_json captures
the real prompt instead of "". Backward-compat manual --task usage
preserved.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
ADR-091 (qe-browser) promoted to Implemented, trust tier 3:
- new aqe eval run --skill <skill> CLI executes skill eval YAMLs as real CommandRunner evals
- aqe init --auto on Linux ARM64 now prints an exact VIBIUM_BROWSER_PATH hint
- docs/guides/qe-browser-getting-started.md for new users
- .github/workflows/test-qe-browser.yml gates PRs with vitest + smoke + eval jobs
- qe-browser eval YAML reworked to use httpbin.org (no fixture server needed)
- Vibium pin comment corrected: ^26.3.18 is a major-line pin, not major.minor
No breaking changes. CLI surface additions only.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Security + supply-chain hardening closes five P0 release blockers from
the v3.9.13 QE audit. Shipped tarball drops 52% (19.9 MB → 9.6 MB),
15 critical runtime npm vulnerabilities are eliminated, and a
command-injection path in `aqe learning repair` is closed.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Security (M-01):
- src/cli/commands/learning.ts: replace execSync shell-interpolation of
the user-controlled --file path with execFileSync + file-descriptor
redirect (dump) and stdin input (import). Closes the command-injection
vector where a crafted --file="x.db\"; rm -rf ~; \"" would escape
shell quoting.
Build / supply chain:
- Move @claude-flow/guidance from dependencies to optionalDependencies
alongside @claude-flow/browser. No stable successor exists on npm;
usage is already guarded by try/await-import/catch fallbacks so
demotion is safe. Documented in the follow-up research memo.
- Lazy-load @faker-js/faker via dynamic import in
test-data-generator.ts and mark it external in build-cli.mjs /
build-mcp.mjs. Faker is a devDep that previously got statically
bundled into shipped artefacts because of a top-level import. Tarball
drops 11.5 MB → 9.6 MB.
MCP API contracts:
- Add required:true to semantically load-bearing first parameters on
agent_metrics (agentId), coverage_analyze_sublinear (target),
accessibility_test (url), defect_predict (target), code_index
(target). Verified via live MCP tools/list handshake — required
arrays now match the intent documented in each tool's description.
CI hygiene:
- Rewrite the "Commit telemetry data" step in
qcsd-production-trigger.yml to push to a bot branch and open a PR
instead of `git push` direct to protected main. That push failed 8/10
runs on the last audit cycle because of branch protection. Artifact
upload (already present) continues to preserve the raw payload for 90
days regardless of whether the PR lands.
Verification:
- npm audit --omit=dev: 0 critical, 0 high (1 moderate in
@mapbox/node-pre-gyp — extraneous, pre-existing, unrelated).
- npm run typecheck: clean.
- CLI + MCP bundles rebuild successfully.
- 253/253 test-generation unit tests pass.
- Live MCP protocol smoke: new required flags visible on tools/list;
advisor_consult guard from v3.9.14 round 1 still fires.
Memory note: see feedback_cli_is_aqe.md — CLAUDE.md ruflo refs were
audited. Only 2 lines (204, 260-261) are stale AQE-product refs; the
other 11 swarm/memory/daemon ruflo commands are legitimate
orchestration-layer invocations and are intentionally retained.
Deferred to a dedicated docs PR so the user can review each.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Security (15 criticals → 0):
- Pin protobufjs to ^7.5.5 via overrides + resolutions to break the
@xenova/transformers → @claude-flow/{browser,guidance,embeddings}
→ onnxruntime-web → onnx-proto chain reaching the CVE-94 payload
(GHSA-xq3m-2v4x-88gg). npm audit --omit=dev now reports 0 vulns.
Tarball bloat (-42%):
- Add rmSync(dist/cli/chunks) to build-cli.mjs before the code-split
build so only fresh chunks ship. 799 → 240 chunks, dist/cli 44 → 11
MB, npm tarball 19.9 → 11.5 MB.
Retiring-model refs (ADR-093 tier-1 hardcodes):
- Replace 'claude-3-haiku-20240307' with 'claude-haiku-4-5' in
MODEL_TIERS[1] at constants.ts:608 and in five mirror implementations
across test-execution, contract-testing, chaos-resilience,
learning-optimization, and visual-accessibility services. Haiku 3
retirement will no longer 404 these tier-1 fallback paths. Backward-
compat refs retained intentionally in bedrock ARN table, cost
tracker, type unions, and RETIRING_MODELS schedule.
ESLint harness:
- package.json lint script invoked eslint on both `src` and `tests`
but .eslintrc.cjs explicitly ignores `tests`, causing ESLint to
abort. Narrow the script to `eslint src --ext .ts` so the harness
runs. (955 pre-existing rule violations remain as separate backlog.)
advisor_consult MCP contract (ADR-092 F-01):
- Mark `agent` and `task` parameters as required:true in the schema.
- Validate via trim() guard in the handler and return a structured
error when either is empty/whitespace instead of shelling out to
`aqe llm advise` with placeholder values. Verified via live MCP
stdio handshake: both empty-string and whitespace-only `agent`
produce the expected rejection without any child process spawn.
Verification:
- npm audit --omit=dev → 0 vulnerabilities (verified from node_modules,
not just lockfile).
- npm run typecheck → clean.
- npm run build → CLI + MCP bundles both build.
- 94/94 tests pass across the patterns touched (security-compliance
scanners + task-executor-errors).
- MCP protocol smoke test confirms advisor_consult guard fires.
Restores Dependency/Build from Grade C to Grade B and lifts the
composite quality score from 7.0 to ~7.3.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Ships ADR-093 Opus 4.7 migration: Sonnet 4.6 becomes the fleet-wide
default, xhigh effort level is on everywhere, Opus 4.7 is the opt-in
escalation target via MultiModelExecutor, and cyber-sensitive agents
stay pinned to Sonnet 4.6 pending Cyber Verification Program approval.
Also fixes two stale integration-test assertions that still expected
the retiring claude-haiku-3-5 ID; both now assert the current
claude-haiku-4-5 per the model registry.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Ships qe-browser fleet skill (Vibium engine, ADR-091) — a ~10MB Go binary
replacement for 300MB Playwright with typed assertions, batch execution,
visual-diff, prompt-injection scanning, and semantic intents. 11 skills
migrated to the new engine.
Total skills: 84 → 85. Tier 3 verified: 49 → 50. Manifest: 1.3.0 → 1.4.0.
fleetVersion bumped to 3.9.9 in skills-manifest.json.
See CHANGELOG.md and docs/releases/v3.9.9.md for details.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Release-process maturity release. No source code changes since v3.9.7
— every commit lands in CI infrastructure, fixtures, scripts, or docs.
The published package is functionally identical to v3.9.7 except for
a refreshed lockfile carrying two transitive security patches.
Closes 4 of the 5 #401 follow-up issues:
- #408 PR template CI enforcement (#416)
- #409 VERIFICATION.md + matrix embed (#417)
- #410 Weekly chaos workflow (#417)
- #411 Mirror init-corpus tarballs to GitHub Releases (#415)
Plus #414 (dependabot transitive bumps: hono 4.12.9→4.12.12,
@hono/node-server 1.19.11→1.19.13).
The remaining #401 follow-up is #407 (worker_threads phase 06
isolation), which stays deferred per its own definition — none of
its 4 trigger conditions have fired.
Verification (per docs/policies/release-verification.md):
- npm run build — clean (CLI + MCP bundles report v3.9.8)
- npm run typecheck — clean (zero errors)
- 711/711 unit tests pass on the critical CLI subset + the load-
bearing phase 06 watchdog test
- 15/15 performance gates pass
- Clean-room install: npm pack -> fresh project -> npm install ->
aqe --version returns 3.9.8 with exit 0
- aqe init --auto --json in fresh project: zero step errors, 84
skills installed, 60 agents installed, MCP configured, CLAUDE.md
generated, workers started
Full test:ci suite intentionally not run locally per CLAUDE.md
("DO NOT run local tests in Codespace if they OOM — CI tests in
the workflow are sufficient"). The release-gate corpus + post-
publish canary will exercise the full surface in CI.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Release notes + CHANGELOG + fleetVersion bump for v3.9.7. See
docs/releases/v3.9.7.md for the user-facing summary.
Highlights:
- Release-gate corpus with 4 pinned real public repo fixtures
(mitt, p-queue, RuView with sha256-pinned regression marker,
agentic-qe self-dogfood) running `aqe init --auto` end-to-end
before every publish
- `aqe init --json` with stable schemaVersion 1 contract and
stricter exit codes
- Phase 06 no longer hides non-critical failures behind
result.success:true (the v3.9.3 failure shape is now structurally
impossible to ship silently)
- Post-publish canary re-runs the corpus against the freshly
published package via real npm CDN edge
- Watchdog effectiveness unit test covering async-stall branches
- AQE_SKIP_CODE_INDEX promoted to permanent supported flag
Verification:
- npm run build — clean
- npm run typecheck — clean
- tests/unit/init/ + tests/unit/cli/ — 1084/1084 pass
- Full corpus gate against /tmp/agentic-qe-3.9.7.tgz — 4/4 pass
with 22 assertions each
- Isolated install probe (npm install + aqe --version) — OK
- aqe security --sast on all touched files — 0 findings
Refs: #401, #412
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Headline change: native HNSW search actually works again. The previous
NativeHnswBackend wrapped @ruvector/router 0.1.28's VectorDb, which a
fresh investigation found to have four serious bugs:
1. HNSW search returned essentially random results — recall@10 ≈ 0%
on the project's FNV fixture and 10% on textbook unit-Gaussian
random vectors. The graph walk could not find self-vectors when
querying with a stored vector.
2. The VectorDb constructor unconditionally wrote a vectors.db redb
file to the user's project root, polluting CWD with multi-MB
files outside .agentic-qe/, in a non-SQLite format that no AQE
migration or backup tooling knew about.
3. Process-wide singleton lock — only ONE VectorDb instance could
exist per process. Subsequent constructors threw "Database error:
Database already open. Cannot acquire lock."
4. NAPI dispose did not synchronously release the redb lock — root
cause of v3.9.5's futex deadlock.
NativeHnswBackend was rewritten to wrap hnswlib-node@^3.0.0 (the
canonical Yury Malkov C++ Hnswlib reference implementation, used by
Pinecone, Weaviate, Qdrant, LangChain, ChromaDB). All four bugs are
gone in one swap. Empirical verification: 100% recall@10 vs the old
10%, faster inserts, multiple instances coexist, no CWD pollution.
useNativeHNSW default is flipped back from false to true (reverting
the v3.9.5 hotfix). Users with large codebases get sublinear HNSW
search by default again.
aqe init now warns when it detects a stale `vectors.db` from the
previous version and suggests `rm vectors.db`. It does NOT auto-delete
(per the data protection rules).
No new dependency was added — hnswlib-node was already in package.json.
Bumps fleetVersion in skills-manifest.json from 3.9.2 (stale) to
3.9.6 to match.
Adds release notes at docs/releases/v3.9.6.md and updates the
release index.
Closes#399. Closes#396 (test-suite cleanup carried over from the
closed PR #403, also in this release).
See ADR-090 for the full decision record and CHANGELOG.md for the
user-facing summary.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
ROOT CAUSE FOUND for the ruview / ruview_live.py hang.
Investigation
-------------
v3.9.4's per-file log gave the user the exact stalling file:
examples/ruview_live.py from the public RuView project. I downloaded
the file (28 KB, 776 lines, 95 entities — normal-shaped Python),
reproduced the hang locally against v3.9.4, then dumped kernel
state of the hung process via /proc/<pid>/wchan and strace.
Findings:
Main thread: futex(0x3c6ded50, FUTEX_WAIT_PRIVATE, 1, NULL)
(NULL timeout = wait forever)
17 total threads:
- MainThread (blocked in futex)
- V8Worker × 4 (blocked in futex)
- DelayedTaskScheduler (epoll_wait — normal libuv)
- SignalInspector (blocked in futex)
- tokio-runtime-w × 6 (blocked in futex)
- libuv-worker × 4 (blocked in futex)
Native modules loaded:
- ruvector-router.linux-arm64-gnu.node
- ruvector-gnn.linux-arm64-gnu.node
- better_sqlite3.node
The deadlock is reproducible: every run against this file produces
the same futex_wait_queue state. After 7 successful VectorDb.insert()
calls (7 rows visible in the vectors table), the 8th never returns.
This is a futex deadlock inside the @ruvector/router native NAPI
module, triggered by VectorDb.insert() against certain vector content
shapes. The Rust tokio runtime threads inside the module hold a lock
the main thread is waiting for, and never release it. The setTimeout-
based watchdog v3.9.3 added cannot interrupt this — setTimeout
callbacks queue between event loop iterations and the event loop is
frozen inside a kernel futex syscall. That's a Node.js architectural
limitation, not a bug in our watchdog code.
The fix
-------
One-line change: useNativeHNSW feature flag default flipped from
true to false in src/integrations/ruvector/feature-flags.ts. All
HNSW operations now route through ProgressiveHnswBackend instead of
NativeHnswBackend. The native module is still loaded and still
available to anyone who explicitly opts in via
setRuVectorFeatureFlags({ useNativeHNSW: true }) — the default path
just no longer touches the deadlock-prone code.
Why this isn't a regression
---------------------------
ProgressiveHnswBackend was already updated in v3.9.3 commit 2bd601b0
to use brute-force exact cosine for the cosine metric. For AQE's
typical KG sizes (<10k vectors @ 384 dim), brute-force cosine is
*faster* than HNSW because it skips the per-query graph-walk
overhead:
1k vectors: brute-force ~0.4 ms vs native HNSW ~0.8 ms (BF wins)
10k vectors: brute-force ~4 ms vs native HNSW ~1.5 ms (HNSW wins)
100k vectors: brute-force ~40 ms vs native HNSW ~3 ms (HNSW wins)
For workloads AQE actually runs in production, brute-force is
faster. Native HNSW only matters above ~10k vectors, which is rare.
And critically, brute-force cannot deadlock — it's a deterministic
loop in pure JS.
Verification
------------
- examples/ruview_live.py: was deadlock, now 258 ms / 95 entries / exit 0
- 200-file synthetic fixture: 1761 ms / 2600 entries / exit 0
- 1-file empty fixture: 380 ms total init / exit 0
- HNSW + memory + init test suites: 152/152 + 452/452 = 604/604 pass
Test updates: native-hnsw-backend.test.ts had three tests asserting
the OLD `useNativeHNSW: true` default. Updated to assert the new
`false` default with a comment explaining v3.9.5's reasoning so
future contributors understand why the flag was flipped.
What's still v3.9.6 scope (#401)
---------------------------------
The architectural fix — running phase 06 inside a killable
worker_threads.Worker so any future native deadlock can be
terminated by the parent — remains tracked in #401. v3.9.5
disables the deadlock-prone path; v3.9.6 will make the watchdog
actually effective for any native code regardless of the underlying
library. Both layers are needed for long-term reliability. The
verification gap that allowed v3.9.3 to ship (no real-world
fixtures, no watchdog effectiveness test, no post-publish canary)
is also tracked in #401 with concrete release-gate changes that
will land alongside v3.9.6.
What we kept from v3.9.4
------------------------
- AQE_SKIP_CODE_INDEX env var + --skip-code-index flag (kept as
user-facing emergency overrides for any future native-layer issue)
- Per-file progress logging in phase 06 (diagnostic transparency)
- Governance / kiro / sync installer findPackageRoot walk-up fixes
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Same-day hotfix for two issues v3.9.3 did not catch:
1. Governance phase failing on chunked bundles (cf-devpod).
2. Phase 06 hang on codespaces (ruview) — watchdog unable to
interrupt synchronous native code blocking the event loop.
v3.9.4 ships:
- Fix C: findPackageRoot() walk-up for governance/kiro/sync
installers — repairs the chunk-split regression class of bugs.
- Fix A: AQE_SKIP_CODE_INDEX env var + --skip-code-index flag —
escape hatch for the phase 06 stall until the proper killable-
worker fix lands in v3.9.5.
- Fix B: Per-file progress logging — exposes the exact file the
indexer is processing when a stall happens, providing the
diagnostic evidence needed for a targeted fix.
The proper fix for the phase 06 stall (running the indexer in a
killable worker_thread or child_process.fork) is deferred to
v3.9.5 and tracked in a separate issue. v3.9.4 is a unblock-first
release, not an architectural change.
All v3.9.1 feature benefits (RVF pattern store, unified HNSW,
agent memory branching, KG semantic search) remain enabled.
Local verification: 440/440 init + kernel + optimizer unit tests
pass. Build + typecheck clean. Three real fixture runs confirm
the escape hatch works, per-file logging works, and governance
phase succeeds with asterisk.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Version bump and release docs for the 5-fix init reliability release.
v3.9.3 addresses the remaining root causes the v3.9.2 hotfix did not
cover:
Fix 1: HnswAdapter dispose() plumbing for test/shutdown paths.
Fix 2: Lazy TokenOptimizerService — no more bootstrap noise at
CLI startup. CLI commands that don't use the token optimizer
no longer open patterns.rvf or memory.db.
Fix 3: Phase 10 no longer spawns the MCP daemon — the spawn was
racing the parent for file locks and producing cosmetic
error spam. Claude Code starts MCP on demand via .mcp.json.
Fix 4: findMcpEntry() works with esbuild code-split chunks
(regression of v3.7.10 fix introduced in v3.9.0).
Fix 5: Phase 06 now has a 30 s per-file and 180 s whole-phase
watchdog with progress logs every 100 files. KG semantic
search and vector embeddings remain fully enabled.
All v3.9.1 feature flags (useRVFPatternStore, useUnifiedHnsw,
useAgentMemoryBranching) remain true — this release preserves the
v3.9.1 benefits and fixes the rollout bugs.
User-perspective verification (all passing):
Empty fresh project: 427 ms exit 0
200-file fixture: 672 ms with progress logs
15k-entity heavy fixture: 3120 ms exit 0
Pre-existing .agentic-qe + aqe --version: 1 line "3.9.3"
aqe mcp --help: exits 0 with usage text
Targeted test results:
token-optimizer-service: 17/17
HNSW (native/legacy/unification): 99/99
unified-memory: 53/53
pattern-store / rvf-pattern-store: 65/65
init/orchestrator + init/phases/database-phase: 32/32
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Two related fixes for the init flow broken in v3.9.1:
1. aqe init --auto hangs at "Code intelligence pre-scan"
After v3.9.1 flipped useRVFPatternStore to true by default,
AQELearningEngine.initialize() would open patterns.rvf twice in
the same process:
a) createPatternStore() -> _createRvfStore('.agentic-qe/patterns.rvf')
acquires an exclusive native file lock via @ruvector/rvf-node
b) getSharedRvfDualWriter() -> getSharedRvfAdapter() ->
createRvfStore('.agentic-qe/patterns.rvf') tries to acquire the
same exclusive lock -> deadlocks forever
Fix: createPatternStore() now routes through the getSharedRvfAdapter()
singleton. Only one file handle exists per process; subsequent callers
receive the cached instance. RvfPatternStore.dispose() gains a
skipCloseOnDispose option so it won't close a shared adapter.
2. CLI doesn't exit after init completes
Native NAPI handles from @ruvector/rvf-node and @ruvector/router
kept the event loop alive indefinitely. cleanupAndExit() previously
used async dynamic imports for cleanup modules, which loaded more
native bindings before the unref'd 3s force-exit timer could fire.
Fix: cleanupAndExit() is now synchronous — fire-and-forget disposes
followed by immediate process.exit(). Init completes and exits
cleanly in ~7s.
Verification:
- aqe init --auto on fresh project: EXIT=0, ~7s, all 12 phases pass
- Isolated npm pack+install: aqe --version returns 3.9.2
- 65 pattern-store + rvf-pattern-store tests pass
- 15/15 performance gates pass
- Build + typecheck: zero errors
Note: Full unit suite runtime regression (>22min, unrelated to this
fix) tracked separately in #396.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: implement ADR-062 (StrongDM all 3 tiers) and ADR-087 (RuVector 14/14 capabilities)
ADR-062 StrongDM Software Factory — all 6 actions across 3 tiers:
- Tier 1: Loop detection wired to MCP protocol-server (blocks on strike 3+),
token dashboard (pre-existing)
- Tier 2: Holdout testing (10% FNV-1a selection, filtered in test-execution),
gate ratcheting (monotonic 5-pass/2%/95% cap, persisted to MemoryBackend)
- Tier 3: Progressive context (TF-IDF prediction, reduces availableFiles on spawn),
meta-learning cycle (4 insight types, stored + published as domain events)
ADR-087 RuVector Advanced Capabilities — milestones 1-5:
- EWC++ recordOutcome + backgroundConsolidate wired to 3 domain coordinators
- R1: HDC fingerprinting (10K-bit hypervectors, wired to PatternStore.store())
- R3: Delta event sourcing (sparse encoding, wired to PatternStore.store())
- R13: Cognitive routing (predictive compression, wired to mailbox.send/receive)
- R14: Hyperbolic HNSW (Poincare ball, auto-indexed in PatternStore.store())
Also updates ADR statuses: 059, 060, 061 → Implemented (were already done),
062 → Implemented, 086 → In Progress, 087 → Implemented.
223 new tests across 11 test files, all passing. Zero regressions.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: implement RVF cluster (ADR-065/066/067/071) with native benchmarks
Implements the RVF persistence cluster for persistent HNSW vector storage,
agent memory branching, and HNSW unification foundation.
Key changes:
- RvfPatternStore: IPatternStore backed by @ruvector/rvf-node native HNSW
(1.2ms cold-start, 0.19ms search p50, verified with real native binary)
- AgentMemoryBranch: per-agent COW isolation via derive(), ingest-log merge,
wired into Kernel.initialize() + DefaultAgentCoordinator
- HnswLegacyBridge: adapts old IHNSWIndex to unified IHnswIndexProvider,
wired into PatternStore when useUnifiedHnsw flag enabled
- Factory routing: createPatternStore() returns RvfPatternStore when flag
enabled + native available + data directory exists
- Dream engine: accepts external RVF adapter (no duplicate file handles),
RVCOWBranchManager enhanced with recall validation check
- @ruvector/gnn bumped 0.1.19→0.1.25, 3 new feature flags added
- IPatternStore interface extracted for polymorphic pattern store usage
- 50 new tests (16 RvfPatternStore + 17 AgentMemoryBranch + 12 bridge + 5 benchmarks)
- 1188 tests pass, 0 regressions
ADR status: 066 Implemented, 067 Implemented, 065 Implemented,
069/071 In Progress (honest assessment after brutal-honesty review)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(init): resolve skills/agents paths from package root, not relative to bundle depth
esbuild code-splitting puts installer code into dist/cli/chunks/ (3 levels
deep) instead of dist/init/ (2 levels deep), so the old ../../ traversals
landed at dist/ instead of the package root — causing "Source directory not
found" errors for all global installs.
Replace brittle relative-path resolution in all 4 installers with a shared
findPackageRoot() that walks up to the nearest package.json with
name=agentic-qe. Prioritise assets/ paths (canonical npm source) over
.claude/ paths.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: complete RVF cluster Phases 2-3 (ADR-067/069/071/072) with devil's advocate fixes
Phase 2A (ADR-067): Agent memory branching enabled — useAgentMemoryBranching=true,
BRANCH_DISCARD witness action, recordIngest callback exposed to agents via config.
Phase 2B (ADR-069): Dream RVF COW — useRvfFork driven by isRVFPatternStoreEnabled(),
child adapter stored + temp files cleaned up on merge/discard, 13 tests.
Phase 2C (ADR-071): HNSW unification — useUnifiedHnsw=true, HNSWEmbeddingIndex routes
through HnswAdapter, UnifiedMemory vectorIndex uses UnifiedHnswIndex, HnswLegacyBridge
delegates to adapter string-ID APIs (no duplicate ID maps), addEmbeddingsBatch routed
correctly, saveIndex/loadIndex safe under unified mode.
Phase 3 (ADR-072): RVF primary migration scaffolding — RvfMigrationAdapter (5-stage
routing with write latency tracking), RvfConsistencyValidator (rolling divergence +
compaction), RvfStageGate (go/no-go with witness chain), rvfMigrationStage=1 default,
wired into shared-rvf-dual-writer at stage >= 2, 32 tests.
Cross-cutting fixes from devil's advocate review:
- Shared RVF adapter singleton eliminates dual file handles (kernel + dream engine)
- RvfPatternStore reports honest nativeAvailable=false + rvfInitError on failure
- ESM-safe dynamic import() replaces require() in dream-engine and branch-manager
- quality_assess defaults to src/ instead of cwd to prevent full-project scan hang
- discoverSourceFiles skips .agentic-qe/.claude/.cache dirs, adds maxFiles=5000 cap
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: complete RVF cluster plan — Phase 2C decommission, Phase 3 integration, fix 7 pre-existing test failures
Phase 2C (ADR-071) — HNSW decommission:
- Remove RuvectorFlatIndex fallback from unified-memory.ts; always use UnifiedHnswIndex
- Hardcode isUnifiedHnswActive()=true in HNSWEmbeddingIndex (hnswlib-node legacy path is dead code)
- Create HnswShadowValidator for brute-force vs HnswAdapter divergence validation
- Benchmark alias (rvf-pattern-store.bench.ts) for plan compliance
Phase 3 (ADR-072) — RVF Primary Migration integration:
- RvfMigrationCoordinator: wires adapter + validator + gate with real SQLite/RVF handles
- MCP tools: migration_status, migration_check, migration_promote (persistence category)
- Kernel boot wiring: coordinator initializes when rvfMigrationStage >= 2
- RvfMigrationAdapter.setStage(): propagate promotions to routing logic
- Promote default rvfMigrationStage from 1 (hybrid) to 2 (dual-write-sqlite-primary)
- Integration test: 13 tests covering full lifecycle (stage 1→2→3→4), write/read routing,
consistency checks, gate enforcement, fallback, metrics
Test fixes (7 pre-existing failures → 1 remaining):
- code-intelligence-metrics-wiring: spy console.info not console.log (logger routes to console.info)
- mcp-integration: disable ADR-062 loop detection (repeated identical calls are by design)
- dream-cycle-tool (2 tests): RvfPatternStore empty-query branch returns all patterns from SQLite
- coherence-integration (4 tests): RvfPatternStore vector search fallback computes brute-force
cosine over SQLite embeddings when RVF adapter unavailable; getStats() falls back to SQLite count;
auto-attach SQLitePatternStore in initialize() when not explicitly wired
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* chore(release): bump version to v3.9.1
- Version bump in package.json and skills-manifest.json
- Fix "Dynamic require of X is not supported" in ESM bundles by adding
createRequire banner to both CLI and MCP build scripts — every chunk
now has a working require() for Node.js builtins
- Add CHANGELOG.md entry and release notes for v3.9.1
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(ci): regenerate package-lock.json for npm ci compatibility
The lock file was out of sync with package.json — new transitive
dependencies added on main were missing. All 15 CI checks failed
at `npm ci` with "Missing from lock file" errors.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(ci): pin Node to 24.13.0 and restore working lock file
Node 24.14.1 ships npm 11.11.0 which enforces stricter lock file
validation than 11.6.x (what 24.13.0 ships). The existing lock file
passes under 11.6.x but fails under 11.11.0 with "Missing from lock
file" for transitive dependencies of private-registry packages.
Pin all 5 workflow files to node-version: '24.13.0' and restore the
lock file from commit f9b76968 (last CI-passing state) with only the
version bump to 3.9.1.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(ci): regenerate package-lock.json with npm 10 for stable npm ci
npm 11 (Node 24) produces internally inconsistent lock files that npm ci
rejects — each npm install resolves transitive deps differently. Generated
with npm 10 (Node 22 LTS) which produces stable lock files compatible with
both npm 10 and npm 11.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Integrate tree-sitter WASM as the default parser for 5 languages, replacing
regex-only parsing (~97-98%) with AST-based parsing (~100% accuracy).
- Add TreeSitterWASMParser implementing ILanguageParser for 5 languages
- Bundle only needed WASM grammars in assets/grammars/ (8.5MB vs 50MB)
- Add FallbackParser with 3-retry logic before permanent regex degradation
- Add per-call parser instances to prevent concurrency races across await
- Add cyclomatic complexity computation from AST branching nodes
- Add property extraction from class/struct AST nodes
- Add AQE_PARSER_REGEX_ONLY=1 env var for opt-out to regex
- Replace require() with ESM-compatible dynamic import() in registry
- Mark web-tree-sitter as external in CLI/MCP esbuild configs
- Amend ADR-076 with decision rationale and alternatives evaluated
Alternatives evaluated and rejected:
- @ast-grep/napi: npm package only ships JS/TS/CSS/HTML, others need native .so
- node-tree-sitter: requires native C compilation via node-gyp
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Dragan Spiridonov