docs: prepare release notes for v3.9.6

[carlos-alm]

Summary

• Add CHANGELOG entry for v3.9.6 covering all commits since v3.9.5: native engine parity & incremental-build perf (perf(native): scope incremental rebuild to truly-changed files (#1012) #1027, perf(native): batch-load file/symbol IDs in edges phase (#1013) #1028, fix(parity): log per-file reasons for native orchestrator drops (#1011) #1024, fix(parity): align WASM and native ast_nodes extraction #1016), bench worker fix (fix(bench): dispose WASM worker pool and keep progress off stdout #1009), CI parity gate (ci(bench): gate release benchmark on engine parity thresholds #1014), and 5 dep bumps
• Bump ROADMAP version header to 3.9.6 (no phase status changes — Phase 6 already Complete; v3.9.6 perf work is iterative parity hardening within the existing complete phase)
• Bump BACKLOG `Last updated` date (no new backlog items shipped)
• Restore `libc` fields on the three Linux entries in `package-lock.json` (`glibc` for `-gnu`, `musl` for `-musl`); npm v11+ silently strips them and without these npm may install glibc binaries on musl systems

After merging: create a GitHub Release with tag `v3.9.6` to trigger the publish workflow, which handles version bumping, native binary builds, and npm publishing.

Test plan

• CHANGELOG renders correctly on GitHub
• ROADMAP version header updated
• All three Linux `package-lock.json` entries have `libc` arrays

[claude]

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

---

PR Review Complete ✅

Todo List:

• Phase 1: Root Cause Analysis - Understand what problem this PR solves
• Phase 2: Configuration Change Detection - Check for high-risk changes
• Phase 3: Test Integrity - Look for red flags in test modifications
• Phase 4: Code Quality - Review implementation details
• Phase 5: Backlog Compliance - Rate against BACKLOG.md criteria
• Final Assessment - Provide rating and recommendation

---

Root Cause Analysis

Problem Being Solved: Standard v3.9.6 release preparation - updating CHANGELOG with comprehensive release notes, bumping version headers in roadmap docs, and fixing npm v11+ compatibility by restoring stripped libc fields in package-lock.json.

Why This Approach: Follows established release workflow. The libc field restoration addresses documented npm v11+ behavior where these fields are silently stripped, potentially causing glibc binaries to be installed on musl systems.

Risk Assessment: Minimal risk. Pure documentation/metadata updates with targeted package-lock.json fix for known npm compatibility issue.

Backlog Compliance

• Zero-dep: ✓ — No new runtime dependencies added
• Foundation-aligned: ✓ — Release documentation fully aligns with all principles
• Problem-fit: 3 — Release maintenance is necessary but doesn't directly address core AI navigation problems
• Breaking: No — Purely additive documentation updates
• Tier: 1 (zero-dep ✓ + foundation-aligned ✓)

Critical Concerns

None. This is exemplary release preparation work:

✅ Comprehensive CHANGELOG: Excellent structured release notes covering performance improvements, parity fixes, and CI enhancements from v3.9.5 to v3.9.6

✅ Accurate version bumps: ROADMAP.md version header updated from 3.9.5 → 3.9.6 with correct date

✅ Proper maintenance: BACKLOG.md "Last updated" field refreshed appropriately

✅ Critical npm fix: Restores libc arrays (glibc for -gnu, musl for -musl) that npm v11+ silently strips, preventing wrong libc binary selection on Linux

✅ No configuration drift: Zero changes to biome.json, tsconfig.json, test configs, or linting rules

✅ Clean scope: Single-concern PR focused entirely on release preparation

Final Recommendation

• Rating: ⭐⭐⭐⭐☆ (4/5)
• Action: APPROVE
• Reasoning: High-quality release preparation work that addresses both documentation requirements and a legitimate npm compatibility issue. The CHANGELOG is comprehensive and well-structured, version bumps are accurate, and the libc field restoration prevents a real deployment issue. This is exactly the kind of maintenance work that should ship with releases.

Minor note: The PR description could have mentioned the specific npm version where this behavior changed, but the fix itself is correct and necessary.

---

[greptile-apps]

Greptile Summary

This is a release-prep PR for v3.9.6: it adds the CHANGELOG entry covering native-engine parity and incremental-build performance improvements, bumps the ROADMAP version header and BACKLOG date, and restores the libc arrays on three Linux package-lock.json entries that npm v11+ silently strips.

• The libc fields are restored for the current 3.9.5 lockfile entries, but the publish workflow that runs after the v3.9.6 tag is created will likely re-run npm install, which under npm v11+ may strip libc from the newly-written 3.9.6 entries — causing the same musl/glibc confusion on the next install cycle. Worth validating the workflow pins npm <11 or re-injects these fields post-install.

Confidence Score: 4/5

Safe to merge; all findings are P2 and do not block this release-prep PR

This is a documentation and lockfile-fix PR with no code logic changes. The only concerns are P2: the libc fields may be re-stripped by npm v11+ in the publish workflow, and a question about whether an arm64-musl target needs the same treatment. Both are post-merge follow-up items rather than blockers.

package-lock.json — verify publish workflow won't strip libc fields again for 3.9.6 entries

Important Files Changed

Filename	Overview
CHANGELOG.md	Adds v3.9.6 changelog entry with bug fixes, performance, CI, and dep-bump chores; format and PR links look correct
docs/roadmap/BACKLOG.md	One-line date bump from 2026-04-23 to 2026-04-29; no other content changes
docs/roadmap/ROADMAP.md	Version header bumped from 3.9.5 to 3.9.6 and date updated to 2026-04-29; no phase-status changes
package-lock.json	Restores libc arrays (glibc/musl) on three Linux package entries stripped by npm v11+; versions still at 3.9.5 (intentional, publish workflow handles bump); worth confirming no arm64-musl target exists that also needs patching

Sequence Diagram

sequenceDiagram
    participant Author
    participant GitHub
    participant PublishWorkflow
    participant npm

    Author->>GitHub: Merge PR #1029 (docs + libc fix)
    Author->>GitHub: Create Release tag v3.9.6
    GitHub->>PublishWorkflow: Trigger publish workflow
    PublishWorkflow->>PublishWorkflow: Bump version to 3.9.6
    PublishWorkflow->>PublishWorkflow: Build native binaries (arm64-gnu, x64-gnu, x64-musl)
    PublishWorkflow->>npm: Publish packages
    Note over PublishWorkflow,npm: ⚠️ npm v11+ may strip libc fields from new 3.9.6 lockfile entries

Loading

Comments Outside Diff (2)

1. package-lock.json, line 1310-1357 (link)

   libc fields may be stripped again by the publish workflow

   The fix restores libc on the 3.9.5 entries. When the publish workflow runs after the v3.9.6 tag is created it will likely invoke npm install or similar, which under npm v11+ will silently strip these fields from the new 3.9.6 entries. Consider either pinning npm to <11 in the workflow, or adding an explicit post-install step to re-inject the libc arrays, so the same problem doesn't resurface immediately on the next release.

   

2. package-lock.json, line 1342-1357 (link)

   Possible missing arm64-musl entry

   The PR restores libc for linux-arm64-gnu, linux-x64-gnu, and linux-x64-musl. If an arm64-musl native binary is ever added as a build target it would need the same libc: ["musl"] treatment. Is arm64-musl deliberately absent (no build target exists), or should it be patched here too?

   

_{Reviews (1): Last reviewed commit: "build(deps): restore libc fields in pack..." | Re-trigger Greptile}