chore: release v3.3.1

[carlos-alm]

Summary

• Bump version to 3.3.1
• Add CHANGELOG entry for all commits since v3.3.0
• Update ROADMAP version header

Test plan

• npm install succeeds with updated lock file
• CHANGELOG renders correctly on GitHub
• ROADMAP checklist items match actual codebase state

[claude]

Claude finished @carlos-alm's task —— View job

---

PR Review: chore: release v3.3.1

Todo List

• Read all changed files to understand release scope
• Check git history to validate changelog accuracy
• Phase 1: Root Cause Analysis
• Phase 2: Configuration Change Detection
• Phase 3: Test Integrity
• Phase 4: Code Quality
• Phase 5: Backlog Compliance Assessment
• Provide final rating and recommendation

---

Root Cause Analysis

Problem Being Solved: Standard patch release consolidating bug fixes and performance improvements accumulated since v3.3.0
Why This Approach: Following semantic versioning - patch release for fixes only, no new features
Risk Assessment: Low risk - purely consolidating existing fixes

Phase 1: Root Cause Analysis ✅

This is a legitimate patch release following semantic versioning. The changelog documents 8 fixes and 1 performance improvement from individual PRs since v3.3.0. No symptoms being hidden - this is proper release hygiene.

Phase 2: Configuration Change Detection ✅

NO HIGH-RISK CONFIG CHANGES DETECTED:

• No biome/linting rules modified
• No test timeouts or coverage thresholds changed
• No build configuration or module resolution changes
• No TypeScript strict mode modifications
• No workaround or silencing patterns

Phase 3: Test Integrity ✅

NO TEST INTEGRITY ISSUES:

• No test files modified in this PR
• No assertions removed or weakened
• No test expectations lowered
• No eslint-disable additions
• This is a pure release housekeeping PR

Phase 4: Code Quality ✅

CLEAN RELEASE PREPARATION:

• Version bump: 3.3.0 → 3.3.1 ✓
• CHANGELOG properly formatted with detailed entries for all 9 PRs in the release range ✓
• ROADMAP version header updated to reflect current version ✓
• BACKLOG version header updated ✓
• package-lock.json properly cleaned up (removes dev-specific entries) ✓
• Standard release commit format ✓
• All changes are appropriate for a patch release

Phase 5: Backlog Compliance Assessment

Zero-dep: ✓ — No new runtime dependencies added
Foundation-aligned: ✓ — Pure release housekeeping, no architectural changes
Problem-fit: 3 — Release management doesn't directly solve the core AI navigation problem, but proper versioning enables reliable dependency management
Breaking: No — Patch release with no breaking changes
Tier: 1 (zero-dep ✓ + foundation-aligned ✓)

Critical Concerns

None. This is exemplary release process execution.

Final Recommendation

• Rating: ⭐⭐⭐⭐⭐ (5/5)
• Action: APPROVE
• Reasoning: Perfect patch release execution. Consolidates important fixes (incremental rebuild accuracy, native engine parity, query performance recovery) with proper semantic versioning, comprehensive changelog, and clean release artifacts. Zero risk of breaking changes.

Key improvements in this release:

• Fixes critical incremental rebuild edge gaps (fix: close edge gap in watcher single-file rebuild (#533) #542)
• Resolves native/WASM engine parity issues (fix(native): align edge builder kind filters with JS parity #541)
• Recovers query performance lost in 3.1.4→3.3.0 (perf: reduce query latency regression from 3.1.4 to 3.3.0 #528)
• Plugs memory leaks in native engine (fix: free leaked WASM trees in native engine typeMap backfill #534)

This is exactly how patch releases should be executed.

---

[greptile-apps]

Greptile Summary

This PR bumps @optave/codegraph to v3.3.1, adds a CHANGELOG entry covering incremental rebuild accuracy fixes, native engine parity improvements, a WASM memory leak fix, and a query performance restoration. It also adds a libc field verification step to the release SKILL.md and updates the ROADMAP/BACKLOG version headers.

Key changes:

• package.json / package-lock.json: root package version bumped to 3.3.1
• CHANGELOG.md: new 3.3.1 section with 7 bug fixes, 1 performance improvement, 1 test addition, and 1 chore entry — all correctly linked to PRs
• .claude/skills/release/SKILL.md: documents the libc field footgun introduced by npm v11+ that silently strips libc when regenerating the lock file, with an explicit verification command and remediation instructions
• docs/roadmap/ROADMAP.md + BACKLOG.md: version header and date stamp updated

Issue to address before merging:

• The six @optave/codegraph-{platform} optional dependency entries in package.json and the corresponding resolved entries in package-lock.json are still pinned at 3.3.0. This release includes native Rust engine bug fixes (edge kind filter alignment, WASM tree memory leak), so users on systems that load the native addon will receive the older 3.3.0 binary and miss those fixes. The "version" lifecycle script (sync-native-versions.js) should have updated these; it either did not run or did not take effect. This should be verified and corrected before publishing.

Confidence Score: 2/5

• Not safe to publish as-is — users on native-binary-capable platforms will receive 3.3.0 native binaries despite the release advertising native engine fixes.
• All documentation and version string changes are correct, but the optional platform binary dependencies remain at 3.3.0 while the package is at 3.3.1. This is a functional mismatch: the CHANGELOG lists native engine bug fixes that will not be delivered to users who load the native addon. The release's own SKILL.md explicitly requires verifying that the new version appears in the lock file for these entries.
• package.json lines 85-90 and the corresponding package-lock.json @optave/codegraph-* entries need to be updated to reference 3.3.1 binaries.

Important Files Changed

Filename	Overview
package.json	Version bumped to 3.3.1 but optional platform binary dependencies remain pinned at 3.3.0 — users with native addon support will miss the native engine fixes included in this release.
package-lock.json	Root version bumped to 3.3.1, but all @optave/codegraph-* optional package entries still resolve to 3.3.0 with 3.3.0 integrity hashes — consistent with the package.json issue. libc fields on all three Linux entries are present and correct (glibc/musl).
CHANGELOG.md	Well-structured 3.3.1 entry with a clear summary blurb, all PRs linked, and changes correctly categorised across Bug Fixes, Performance, Tests, and Chores.
.claude/skills/release/SKILL.md	Adds a critical verification step for libc fields on Linux package-lock entries — valuable institutional knowledge captured from a real npm v11+ footgun.
docs/roadmap/ROADMAP.md	Version header updated from 3.3.0 to 3.3.1 — straightforward, no issues.
docs/roadmap/BACKLOG.md	"Last updated" date bumped to 2026-03-20 — no issues.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[npm install @optave/codegraph@3.3.1] --> B{Native binary available?}
    B -->|Yes - native addon loads| C["Installs @optave/codegraph-{platform}@3.3.0 ⚠️"]
    B -->|No - WASM fallback| D[Uses WASM engine - gets 3.3.1 JS fixes]
    C --> E["Missing: edge kind filter fix (#541)"]
    C --> F["Missing: WASM tree memory leak fix (#534)"]
    D --> G[All 3.3.1 bug fixes applied]
    E --> H[Native/WASM engine parity broken]
    F --> I[Memory leak persists on native engine]

Loading

Comments Outside Diff (1)

1. package.json, line 85-90 (link)

   Platform binary optional dependencies not bumped to 3.3.1

   All six @optave/codegraph-* optional dependencies are still pinned at 3.3.0 while the main package has been bumped to 3.3.1. This is significant because the 3.3.1 CHANGELOG explicitly includes native engine bug fixes:

   • **native:** align edge builder kind filters with JS engine parity (fix(native): align edge builder kind filters with JS parity #541)
   • **native:** free leaked WASM trees in native engine typeMap backfill (fix: free leaked WASM trees in native engine typeMap backfill #534)

   Users who install @optave/codegraph@3.3.1 on a Linux/macOS/Windows system that picks up the native binary will receive the 3.3.0 native binary, missing both of these fixes. They would only get the 3.3.1 fixes if the native addon is unavailable and the WASM fallback is used.

   The package.json "version" lifecycle script (node scripts/sync-native-versions.js) exists specifically to keep these in sync — it appears it either didn't run or didn't update the optional dependency entries. The release SKILL.md also calls this out explicitly as a required verification step: "Run grep to confirm the new version appears in package-lock.json and that all @optave/codegraph-* optional dependency entries are complete."

   If the 3.3.1 platform binaries have already been published to the registry, these entries should be updated:

   If the native binaries haven't been published yet at 3.3.1, this release should be held until they are (or the native fixes excluded from the CHANGELOG and deferred to a later patch).

_{Last reviewed commit: "fix(skills): remove ..."}

[carlos-alm]

Addressed the libc field concern:

• Root cause: npm v11.5.2 (shipped with Node 22) silently strips the libc field when regenerating package-lock.json. This is a known npm regression — the field was introduced in lockfileVersion 3 but npm v11 drops it during --package-lock-only runs.
• Fix: Manually restored all three libc entries in commit f00b63a ("glibc" for -gnu packages, "musl" for -musl).
• Prevention: Added explicit libc field verification to the /release skill (Step 7) in commit 519c5f1, so future releases will catch this automatically.

@greptileai