chore: release v3.1.1 (#386)

* chore: release v3.1.1

Bump version to 3.1.1 across package.json, package-lock.json,
Cargo.toml. Add CHANGELOG entry with all commits since v3.1.0.
Update ROADMAP to reflect Phase 3 progress (3.2, 3.3, 3.4 started).

* fix: revert Cargo.toml bump and remove phantom linux-arm64-musl binary

Cargo.toml version is synced by sync-native-versions.js during the
publish workflow — manual bumps create a mismatch with optionalDeps.

Remove @optave/codegraph-linux-arm64-musl from optionalDependencies
since there is no aarch64-unknown-linux-musl target in the CI build
matrix. The package was never published, leaving an incomplete
package-lock entry that confused resolution.

* feat: add /release skill for automated release preparation

Codifies the release process: version bump, CHANGELOG, ROADMAP
updates, lock file verification, branch/PR creation. Documents
that Cargo.toml and optionalDeps are synced by the publish workflow.

* feat: expand /release skill with BACKLOG, README steps and release-note tone

- Add Step 5 (BACKLOG.md) — mark completed items, check Depends on
- Expand Step 6 (README.md) — check commands, MCP tools, features, roadmap
- Rewrite Step 3 (CHANGELOG) — emphasize release-note tone for users
- Renumber steps, update staging list

Author: carlos-alm

.claude/skills/release/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: release
+description: Prepare a codegraph release — bump versions, update CHANGELOG, ROADMAP, BACKLOG, README, create PR
+argument-hint: <version e.g. 3.1.1>
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Agent
+---
+
+# Release v$ARGUMENTS
+
+You are preparing a release for `@optave/codegraph` version **$ARGUMENTS**.
+
+---
+
+## Step 1: Gather context
+
+Run these in parallel:
+1. `git log --oneline v<previous-tag>..HEAD` — all commits since the last release tag
+2. Read `CHANGELOG.md` (first 80 lines) — understand the format
+3. Read `package.json` — current version
+4. `git describe --tags --match "v*" --abbrev=0` — find the previous stable release tag
+
+## Step 2: Bump version in package.json
+
+Edit `package.json` to set `"version": "$ARGUMENTS"`.
+
+**Do NOT bump:**
+- `crates/codegraph-core/Cargo.toml` — synced automatically by `scripts/sync-native-versions.js` during the publish workflow
+- `optionalDependencies` versions — also synced automatically by the same script
+
+Then run `npm install --package-lock-only` to update `package-lock.json`.
+
+## Step 3: Update CHANGELOG.md
+
+The CHANGELOG doubles as **release notes** — it's what users see on the GitHub release page. Write it for humans, not machines.
+
+Add a new section at the top (below the header) following the existing format:
+
+```
+## [X.Y.Z](https://github.com/optave/codegraph/compare/vPREVIOUS...vX.Y.Z) (YYYY-MM-DD)
+
+**One-line summary.** Expanded description of the release highlights — what's new, what's better, what's fixed. This paragraph should tell a user whether they should upgrade and why.
+
+### Features
+* **scope:** description ([#PR](url))
+
+### Bug Fixes
+* **scope:** description ([#PR](url))
+
+### Performance
+* **scope:** description ([#PR](url))
+
+### Refactors
+* description ([#PR](url))
+
+### Chores
+* **scope:** description ([#PR](url))
+```
+
+Rules:
+- **Write for users, not developers.** Describe what changed from the user's perspective, not the implementation details. "MCP server connects reliably on first attempt" beats "defer heavy imports in MCP server"
+- The bold summary paragraph at the top is the most important part — it's the TL;DR that appears in release notifications
+- Categorize every commit since the last tag (skip docs-only and benchmark-only commits unless they're notable)
+- Use the conventional commit scope as the bold prefix
+- Link every PR number
+- Include a Performance section if there are performance improvements
+- Read previous CHANGELOG entries to match the tone and detail level
+
+## Step 4: Update ROADMAP.md
+
+Read `docs/roadmap/ROADMAP.md` and update:
+1. **Version header** — update `Current version: X.Y.Z`
+2. **Phase status table** — if any phase moved from Planned to In Progress (or completed), update the status column
+3. **Task-level progress** — for any roadmap tasks that have been completed or partially completed by commits in this release:
+   - Add a progress note with version and PR links
+   - Add checklist items: `- ✅` for done, `- 🔲` for remaining
+   - Check actual code exists (glob/grep for new files/directories mentioned in PRs) before marking tasks complete
+
+## Step 5: Update BACKLOG.md
+
+Read `docs/roadmap/BACKLOG.md` and check if any backlog items were completed or partially completed by commits in this release.
+
+- Backlog items are organized into tiers (1, 1b–1g, 2, 3) with an ID, title, and description per row
+- Completed items are marked with strikethrough title (`~~Title~~`) and a `**DONE**` suffix with a description of what was shipped and PR links
+- If a feature in this release matches a backlog item:
+  - Strike through the title: `~~Title~~`
+  - Add `**DONE** — description of what shipped (PR links)` at the end of the row
+  - Check the "Depends on" column of other items — if they depended on the newly completed item, note that they are now unblocked
+- Update the `Last updated` date at the top of the file
+
+## Step 6: Update README.md
+
+Read `README.md` and check if any new user-facing features from this release need to be documented:
+
+1. **Commands table** — if a new CLI command was added, add it to the commands section
+2. **MCP tools table** — if new MCP tools were added, add them to the AI integration section
+3. **Feature descriptions** — if a major new capability was added (new analysis type, new output format, etc.), add it to the relevant section
+4. **Roadmap section** — if a phase status changed, update the roadmap summary at the bottom
+5. **Version references** — only update version-specific references (e.g., install commands). Historical milestone markers like "Complete (v3.0.0)" should stay as-is
+6. If nothing user-facing changed (pure refactors, bug fixes, internal improvements), no README update is needed
+
+## Step 7: Verify package-lock.json
+
+Run `grep` to confirm the new version appears in `package-lock.json` and that all `@optave/codegraph-*` optional dependency entries are complete (have version, resolved, integrity, cpu, os fields). Flag any incomplete entries — they indicate an unpublished platform binary.
+
+## Step 8: Create branch, commit, push, PR
+
+1. Create branch: `git checkout -b release/$ARGUMENTS`
+2. Stage only the files you changed: `CHANGELOG.md`, `package.json`, `package-lock.json`, `docs/roadmap/ROADMAP.md`, `docs/roadmap/BACKLOG.md` if changed, `README.md` if changed
+3. Commit: `chore: release v$ARGUMENTS`
+4. Push: `git push -u origin release/$ARGUMENTS`
+5. Create PR:
+
+```
+gh pr create --title "chore: release v$ARGUMENTS" --body "$(cat <<'EOF'
+## Summary
+- Bump version to $ARGUMENTS
+- Add CHANGELOG entry for all commits since previous release
+- Update ROADMAP progress
+
+## Test plan
+- [ ] `npm install` succeeds with updated lock file
+- [ ] CHANGELOG renders correctly on GitHub
+- [ ] ROADMAP checklist items match actual codebase state
+EOF
+)"
+```
+
+## Important reminders
+
+- **No co-author lines** in commit messages
+- **No Claude Code references** in commit messages or PR descriptions
+- The publish workflow (`publish.yml`) handles: Cargo.toml version sync, optionalDependencies version sync, npm publishing, git tagging, and the post-publish version bump PR
+- If you find issues (incomplete lock entries, phantom packages), fix them in a separate commit with a descriptive message

CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
 
+## [3.1.1](https://github.com/optave/codegraph/compare/v3.1.0...v3.1.1) (2026-03-08)
+
+**Reliability, architecture, and MCP cold-start fixes.** This patch breaks a circular dependency cycle, fixes MCP server first-connect reliability by deferring heavy imports, corrects flow matching to use core symbol kinds, and refactors all database access to use try/finally for reliable `db.close()`. Internal architecture improves with repository pattern for data access and command/query separation.
+
+### Features
+
+* **hooks:** add pre-commit hooks for cycles, dead exports, signature warnings ([#381](https://github.com/optave/codegraph/pull/381))
+* **benchmark:** add 1-file rebuild phase breakdown to build benchmarks ([#370](https://github.com/optave/codegraph/pull/370))
+
+### Bug Fixes
+
+* **cycles:** break circular dependency cycle and remove dead `queryName` export ([#378](https://github.com/optave/codegraph/pull/378))
+* **queries:** use `CORE_SYMBOL_KINDS` in flow matching ([#382](https://github.com/optave/codegraph/pull/382))
+* **mcp:** defer heavy imports in MCP server for first-connect reliability ([#380](https://github.com/optave/codegraph/pull/380))
+
+### Refactors
+
+* wrap all db usage in try/finally for reliable `db.close()` ([#384](https://github.com/optave/codegraph/pull/384), [#383](https://github.com/optave/codegraph/pull/383))
+* repository pattern for data access ([#371](https://github.com/optave/codegraph/pull/371))
+* command/query separation — extract CLI wrappers, shared output helper ([#373](https://github.com/optave/codegraph/pull/373))
+
+### Chores
+
+* **ci:** allow `merge` type in commitlint config ([#385](https://github.com/optave/codegraph/pull/385))
+* **deps-dev:** bump tree-sitter-go from 0.23.4 to 0.25.0 ([#356](https://github.com/optave/codegraph/pull/356))
+
 ## [3.1.0](https://github.com/optave/codegraph/compare/v3.0.4...v3.1.0) (2026-03-08)
 
 **Sequence diagrams, native engine performance leap, and unused export detection.** This release adds `codegraph sequence` for Mermaid sequence diagram generation from call graph edges, delivers major native engine build optimizations (deep-clone elimination, batched SQLite inserts, call edge building in Rust, FS caching, rayon-parallel import resolution), introduces `--unused` on the exports command to detect dead exports, and fixes an ~80x native no-op rebuild regression.

docs/roadmap/ROADMAP.md

@@ -1,6 +1,6 @@
 # Codegraph Roadmap
 
-> **Current version:** 3.0.0 | **Status:** Active development | **Updated:** March 2026
+> **Current version:** 3.1.1 | **Status:** Active development | **Updated:** March 2026
 
 Codegraph is a strong local-first code graph CLI. This roadmap describes planned improvements across ten phases -- closing gaps with commercial code intelligence platforms while preserving codegraph's core strengths: fully local, open source, zero cloud dependency by default.
 
@@ -16,7 +16,7 @@ Codegraph is a strong local-first code graph CLI. This roadmap describes planned
 | [**2**](#phase-2--foundation-hardening) | Foundation Hardening | Parser registry, complete MCP, test coverage, enhanced config, multi-repo MCP | **Complete** (v1.4.0) |
 | [**2.5**](#phase-25--analysis-expansion) | Analysis Expansion | Complexity metrics, community detection, flow tracing, co-change, manifesto, boundary rules, check, triage, audit, batch, hybrid search | **Complete** (v2.6.0) |
 | [**2.7**](#phase-27--deep-analysis--graph-enrichment) | Deep Analysis & Graph Enrichment | Dataflow analysis, intraprocedural CFG, AST node storage, expanded node/edge types, extractors refactoring, CLI consolidation, interactive viewer, exports command, normalizeSymbol | **Complete** (v3.0.0) |
-| [**3**](#phase-3--architectural-refactoring) | Architectural Refactoring | Unified AST analysis framework, command/query separation, repository pattern, queries.js decomposition, composable MCP, CLI commands, domain errors, curated API, unified graph model | Planned |
+| [**3**](#phase-3--architectural-refactoring) | Architectural Refactoring | Unified AST analysis framework, command/query separation, repository pattern, queries.js decomposition, composable MCP, CLI commands, domain errors, curated API, unified graph model | **In Progress** (v3.1.1) |
 | [**4**](#phase-4--typescript-migration) | TypeScript Migration | Project setup, core type definitions, leaf -> core -> orchestration module migration, test migration | Planned |
 | [**5**](#phase-5--intelligent-embeddings) | Intelligent Embeddings | LLM-generated descriptions, enhanced embeddings, build-time semantic metadata, module summaries | Planned |
 | [**6**](#phase-6--natural-language-queries) | Natural Language Queries | `ask` command, conversational sessions, LLM-narrated graph queries, onboarding tools | Planned |
@@ -552,7 +552,9 @@ Plus updated enums on existing tools (edge_kinds, symbol kinds).
 
 ---
 
-## Phase 3 -- Architectural Refactoring
+## Phase 3 -- Architectural Refactoring 🔄
+
+> **Status:** In Progress -- started in v3.1.1
 
 **Goal:** Restructure the codebase for modularity, testability, and long-term maintainability. These are internal improvements -- no new user-facing features, but they make every subsequent phase easier to build and maintain.
 
@@ -591,7 +593,16 @@ A single AST walk with pluggable visitors eliminates 3 redundant tree traversals
 
 **Affected files:** `src/complexity.js`, `src/cfg.js`, `src/dataflow.js`, `src/ast.js` -> split into `src/ast-analysis/`
 
-### 3.2 -- Command/Query Separation ★ Critical
+### 3.2 -- Command/Query Separation ★ Critical 🔄
+
+> **v3.1.1 progress:** CLI display wrappers for all query commands extracted to `queries-cli.js` (866 lines, 15 functions). Shared `result-formatter.js` (`outputResult()` for JSON/NDJSON) and `test-filter.js` created. `queries.js` reduced from 3,395 → 2,490 lines — all `*Data()` functions remain, CLI formatting fully separated ([#373](https://github.com/optave/codegraph/pull/373)).
+
+- ✅ `queries.js` CLI wrappers → `queries-cli.js` (15 functions)
+- ✅ Shared `result-formatter.js` (`outputResult` for JSON/NDJSON dispatch)
+- ✅ Shared `test-filter.js` (`isTestFile` predicate)
+- 🔲 Extract CLI wrappers from remaining modules (audit, batch, check, cochange, communities, complexity, cfg, dataflow, flow, manifesto, owners, structure, triage, branch-compare)
+- 🔲 Introduce `CommandRunner` shared lifecycle
+- 🔲 Per-command `src/commands/` directory structure
 
 Eliminate the `*Data()` / `*()` dual-function pattern replicated across 19 modules. Every analysis module (queries, audit, batch, check, cochange, communities, complexity, cfg, dataflow, ast, flow, manifesto, owners, structure, triage, branch-compare, viewer) currently implements both data extraction AND CLI formatting.
 
@@ -616,7 +627,17 @@ src/
 
 **Affected files:** All 19 modules with dual-function pattern, `src/cli.js`, `src/mcp.js`
 
-### 3.3 -- Repository Pattern for Data Access ★ Critical
+### 3.3 -- Repository Pattern for Data Access ★ Critical 🔄
+
+> **v3.1.1 progress:** `src/db/` directory created with `repository.js` (134 lines), `query-builder.js` (280 lines), and `migrations.js` (312 lines). All db usage across the codebase wrapped in try/finally for reliable `db.close()` ([#371](https://github.com/optave/codegraph/pull/371), [#384](https://github.com/optave/codegraph/pull/384), [#383](https://github.com/optave/codegraph/pull/383)).
+
+- ✅ `src/db/` directory structure created
+- ✅ `repository.js` — initial Repository class
+- ✅ `query-builder.js` — lightweight SQL builder (280 lines)
+- ✅ `migrations.js` — schema migrations extracted (312 lines)
+- ✅ All db usage wrapped in try/finally for reliable `db.close()`
+- 🔲 Migrate remaining raw SQL from 25+ modules into Repository
+- 🔲 `connection.js` — extract connection setup (open, WAL mode, pragma tuning)
 
 Consolidate all SQL into a single `Repository` class. Currently SQL is scattered across 25+ modules that each independently open the DB and write raw SQL inline across 13 tables.
 
@@ -633,7 +654,14 @@ Add a query builder for the common pattern "find nodes WHERE kind IN (...) AND f
 
 **Affected files:** `src/db.js` -> split into `src/db/`, SQL extracted from all modules
 
-### 3.4 -- Decompose queries.js (3,395 Lines)
+### 3.4 -- Decompose queries.js (3,395 Lines) 🔄
+
+> **v3.1.1 progress:** `queries.js` reduced from 3,395 → 2,490 lines by extracting all CLI formatting to `queries-cli.js` (3.2). Symbol kind constants extracted to `kinds.js` (49 lines) ([#378](https://github.com/optave/codegraph/pull/378)).
+
+- ✅ CLI formatting separated → `queries-cli.js` (via 3.2)
+- ✅ `kinds.js` — symbol kind constants extracted
+- 🔲 Split remaining `queries.js` data functions into `src/analysis/` modules
+- 🔲 Extract `shared/normalize.js`, `shared/generators.js`
 
 Split into pure analysis modules that return data and share no formatting concerns.