feat: auto-detect semver bump in /release skill (#496)

* docs: promote #83 (brief command) and #71 (type inference) to Tier 0 in backlog

These two items deliver the highest immediate impact on agent experience
and graph accuracy without requiring Rust porting or TypeScript migration.
They should be implemented before any Phase 4+ roadmap work.

- #83: hook-optimized `codegraph brief` enriches passively-injected context
- #71: basic type inference closes the biggest resolution gap for TS/Java

* docs: add Phase 4 (Native Analysis Acceleration) to roadmap

Add new Phase 4 covering the port of JS-only build phases to Rust:
- 4.1-4.3: AST nodes, CFG, dataflow visitor ports (~587ms savings)
- 4.4: Batch SQLite inserts (~143ms)
- 4.5: Role classification & structure (~42ms)
- 4.6: Complete complexity pre-computation
- 4.7: Fix incremental rebuild data loss on native engine
- 4.8: Incremental rebuild performance (target sub-100ms)

Bump old Phases 4-10 to 5-11 with all cross-references updated.
Benchmark evidence shows ~50% of native build time is spent in
JS visitors that run identically on both engines.

* docs: fix sub-section numbering to match parent phase headings

* fix: align version computation between publish.yml and bench-version.js

- Add COMMITS=0 guard in publish.yml to return clean version when HEAD
  is exactly at a tag (mirrors bench-version.js early return)
- Change bench-version.js to use PATCH+1-dev.COMMITS format instead of
  PATCH+COMMITS-dev.SHA (mirrors publish.yml's new scheme)
- Fix fallback in bench-version.js to use dev.1 matching publish.yml's
  no-tags COMMITS=1 default

Impact: 1 functions changed, 0 affected

* feat: auto-detect semver bump in /release skill when no version provided

The release skill now scans commit history using conventional commit
rules to determine major/minor/patch automatically. Explicit version
argument still works as before.

* fix: restore SHA-based uniqueness in bench-version fallback and add -dev.0 suffix

The no-tags fallback hardcoded dev.1, causing repeated benchmark runs
to silently overwrite each other. Restore short SHA for uniqueness.
Also add -dev.0 suffix when COMMITS=0 so dev builds at an exact tag
are never confused with stable releases.

Impact: 1 functions changed, 0 affected

* fix: add -dev.0 suffix for COMMITS=0 dev builds in publish.yml

When HEAD is exactly at a release tag, the dev build emitted a clean
semver string identical to the stable release. Add -dev.0 suffix to
prevent confusion between dev pre-releases and stable releases.

Author: carlos-alm

.claude/skills/release/SKILL.md

@@ -1,27 +1,55 @@
 ---
 name: release
 description: Prepare a codegraph release — bump versions, update CHANGELOG, ROADMAP, BACKLOG, README, create PR
-argument-hint: <version e.g. 3.1.1>
+argument-hint: "[version e.g. 3.1.1]  (optional — auto-detects from commits)"
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Agent
 ---
 
-# Release v$ARGUMENTS
+# Release
 
-You are preparing a release for `@optave/codegraph` version **$ARGUMENTS**.
+You are preparing a release for `@optave/codegraph`.
+
+**Version argument:** `$ARGUMENTS`
+- If a version was provided (e.g. `3.1.1`), use it as the target version.
+- If no version was provided (empty or blank `$ARGUMENTS`), you will auto-detect it in Step 1b.
 
 ---
 
-## Step 1: Gather context
+## Step 1a: Gather context
 
 Run these in parallel:
-1. `git log --oneline v<previous-tag>..HEAD` — all commits since the last release tag
+1. `git log --oneline v<previous-tag>..HEAD` — all commits since the last release tag (use `git describe --tags --match "v*" --abbrev=0` to find the previous 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 1b: Determine version (if not provided)
+
+If `$ARGUMENTS` is empty or blank, determine the semver bump from the commits gathered in Step 1a.
+
+Scan **every commit message** between the last tag and HEAD. Apply these rules in priority order:
+
+| Condition | Bump |
+|-----------|------|
+| Any commit has a `BREAKING CHANGE:` or `BREAKING-CHANGE:` footer, **or** uses the `!` suffix (e.g. `feat!:`, `fix!:`, `refactor!:`) | **major** |
+| Any commit uses `feat:` or `feat(scope):` | **minor** |
+| Everything else (`fix:`, `refactor:`, `perf:`, `chore:`, `docs:`, `test:`, `ci:`, etc.) | **patch** |
+
+Given the current version `MAJOR.MINOR.PATCH` from `package.json`, compute the new version:
+- **major** → `(MAJOR+1).0.0`
+- **minor** → `MAJOR.(MINOR+1).0`
+- **patch** → `MAJOR.MINOR.(PATCH+1)`
+
+Print the detected bump reason and the resolved version, e.g.:
+> Detected **minor** bump (found `feat:` commits). Version: 3.1.0 → **3.2.0**
+
+Use the resolved version as `VERSION` for all subsequent steps.
+
+If `$ARGUMENTS` was provided, use it directly as `VERSION`.
+
 ## Step 2: Bump version in package.json
 
-Edit `package.json` to set `"version": "$ARGUMENTS"`.
+Edit `package.json` to set `"version": "VERSION"`.
 
 **Do NOT bump:**
 - `crates/codegraph-core/Cargo.toml` — synced automatically by `scripts/sync-native-versions.js` during the publish workflow
@@ -104,16 +132,16 @@ Run `grep` to confirm the new version appears in `package-lock.json` and that al
 
 ## Step 8: Create branch, commit, push, PR
 
-1. Create branch: `git checkout -b release/$ARGUMENTS`
+1. Create branch: `git checkout -b release/VERSION`
 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`
+3. Commit: `chore: release vVERSION`
+4. Push: `git push -u origin release/VERSION`
 5. Create PR:
 
 ```
-gh pr create --title "chore: release v$ARGUMENTS" --body "$(cat <<'EOF'
+gh pr create --title "chore: release vVERSION" --body "$(cat <<'EOF'
 ## Summary
-- Bump version to $ARGUMENTS
+- Bump version to VERSION
 - Add CHANGELOG entry for all commits since previous release
 - Update ROADMAP progress
 

.github/workflows/publish.yml

@@ -81,7 +81,7 @@ jobs:
               IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT"
             fi
             if [ "$COMMITS" -eq 0 ]; then
-              VERSION="${MAJOR}.${MINOR}.${PATCH}"
+              VERSION="${MAJOR}.${MINOR}.${PATCH}-dev.0"
             else
               VERSION="${MAJOR}.${MINOR}.$((PATCH + 1))-dev.${COMMITS}"
             fi

scripts/bench-version.js

@@ -5,7 +5,7 @@
  *   1. `git describe --tags --match "v*" --abbrev=0` → find nearest release tag
  *   2. `git rev-list <tag>..HEAD --count` → count commits since that tag
  *
- * - If HEAD is exactly tagged (0 commits): returns "3.1.5"
+ * - If HEAD is exactly tagged (0 commits): returns "3.1.5-dev.0"
  * - Otherwise: returns "3.1.6-dev.12" (NEXT_PATCH-dev.COMMIT_COUNT)
  *   This keeps dev versions in the correct semver range between the
  *   current release and the next, avoiding inflated patch numbers.
@@ -36,8 +36,8 @@ export function getBenchmarkVersion(pkgVersion, cwd) {
 
 		const [, major, minor, patch] = m;
 
-		// Exact tag (0 commits since tag): return clean release version
-		if (commits === 0) return `${major}.${minor}.${patch}`;
+		// Exact tag (0 commits since tag): still mark as dev to avoid confusion with stable
+		if (commits === 0) return `${major}.${minor}.${patch}-dev.0`;
 
 		// Dev build: MAJOR.MINOR.(PATCH+1)-dev.COMMITS
 		const nextPatch = Number(patch) + 1;
@@ -46,11 +46,17 @@ export function getBenchmarkVersion(pkgVersion, cwd) {
 		/* git not available or no tags */
 	}
 
-	// Fallback: no git or no tags — match publish.yml's no-tags behavior (COMMITS=1)
+	// Fallback: no git or no tags — try to get a unique SHA so repeated runs
+	// don't collide in benchmark reports (which deduplicate by version)
 	const parts = pkgVersion.split('.');
 	if (parts.length === 3) {
 		const [major, minor, patch] = parts;
-		return `${major}.${minor}.${Number(patch) + 1}-dev.1`;
+		try {
+			const hash = execFileSync('git', ['rev-parse', '--short', 'HEAD'], { cwd, ...GIT_OPTS }).trim();
+			return `${major}.${minor}.${Number(patch) + 1}-dev.${hash}`;
+		} catch {
+			return `${major}.${minor}.${Number(patch) + 1}-dev`;
+		}
 	}
 	return `${pkgVersion}-dev`;
 }