worclaude 2.4.13 → 2.5.1

package/CHANGELOG.md

@@ -4,6 +4,53 @@ All notable changes to worclaude are documented in this file. Format loosely fol
 
 ## [Unreleased]
 
+## [2.5.1] — 2026-04-21
+
+Patch release fixing a user-visible bug found while dogfooding the v2.5.0 upgrade: reference-copy template files (the copies worclaude writes when your customized file and the shipped template both change) were being placed as `.workflow-ref.md` siblings next to the live file — including inside `.claude/commands/`, where Claude Code's command loader discovered them as phantom slash commands like `/sync.workflow-ref`, and inside `.claude/agents/`, where they could shadow live agents. Reference copies now live in a dedicated `.claude/workflow-ref/` tree that Claude Code does not scan. Installs upgrading from pre-v2.5.1 have their legacy reference files automatically relocated on the next `worclaude upgrade`.
+
+### Fixed
+
+- **Phantom slash commands from reference-copy siblings** (PR #101) — ref files are now written under `.claude/workflow-ref/<original-path>/` with the original filename preserved, instead of as `<name>.workflow-ref.md` siblings next to the live file. `.claude/commands/` and `.claude/agents/` are no longer polluted by `.workflow-ref` artifacts, so Claude Code's command and subagent loaders don't register them as live. `diff .claude/workflow-ref/commands/sync.md .claude/commands/sync.md` now reads cleanly.
+
+### Added
+
+- **`migrateWorkflowRefLocation()` in `src/core/migration.js`** (PR #101) — runs unconditionally at the start of every `worclaude upgrade`. Sweeps legacy `*.workflow-ref.md` siblings under `.claude/{commands,agents,skills}/` (plus root-level `CLAUDE.md.workflow-ref.md` and `AGENTS.md.workflow-ref`) into the new `.claude/workflow-ref/<original-path>/` tree. Idempotent (skips when target already exists, never overwrites). Scoped scan avoids re-stat'ing `.claude/sessions/` on every upgrade. Deliberately not version-gated — semver-gating this kind of cleanup migration creates a new bug class for users who downgrade then re-upgrade.
+- **Shared helpers in `src/core/file-categorizer.js`** (PR #101) — `WORKFLOW_REF_DIR` constant, `workflowRefRelPath(keyOrRelPath)` returning project-root-relative paths for `scaffoldFile`, `resolveRefPath(keyOrRelPath, projectRoot)` for absolute writes, and `isWorkflowRefFile(absPath, claudeDir)` predicate that unifies new-location-or-legacy-suffix detection so `status`, `doctor`, and `remover` stay in sync across the transition window.
+
+### Changed
+
+- **`worclaude upgrade` report output** (PR #101) — "Conflicts: N files (saved as .workflow-ref.md)" → "Conflicts: N files (saved under .claude/workflow-ref/)". New "Relocated: N legacy ref file(s) → .claude/workflow-ref/" line surfaces the one-time migration when it fires. Final hint reads "Review files under .claude/workflow-ref/ and merge what's useful."
+- **`worclaude init` and `worclaude status` output** (PR #101) — Scenario B conflict block, Next Steps, and Pending Review list all updated to reference the new location. Status continues to surface legacy `*.workflow-ref.md` siblings anywhere under `.claude/` so users upgrading from pre-v2.5.1 still see what they need to resolve before the next upgrade migrates them.
+- **`src/core/remover.js`** (PR #101) — the entire `.claude/workflow-ref/` subtree is classified as safe-to-delete on `worclaude delete`; the empty-subdir cleanup list extended to include `workflow-ref`.
+
+### Docs
+
+- **Upgrading guide** (PR #101) — 7 inline references updated plus a new "Upgrading from pre-v2.5.1 installs" subsection explaining what the automatic relocation does and how the skip-on-collision rule works.
+- **Existing-projects guide** (PR #101) — Tier 2 "Safe Alongside" section rewritten to describe the new `.claude/workflow-ref/` layout; post-merge report sample updated; the "Reviewing reference files" section now shows the clean `diff workflow-ref/commands/sync.md commands/sync.md` idiom.
+- **Commands reference, agents reference, SPEC.md, project-patterns skill** (PR #101) — all references to `.workflow-ref.md` sibling layout updated; `docs/spec/SPEC.md` edited on the feature branch as a shared-state override (PR #79 precedent: the SPEC update describes the very behavior the PR adds).
+
+### Tests
+
+- **Relocation migration coverage** (PR #101) — 8 new cases in `tests/core/migration.test.js` covering command/agent/skill subdir sweeps, root-level `CLAUDE.md.workflow-ref.md` / `AGENTS.md.workflow-ref` handling, target-collision skip behavior, idempotency on repeated runs, no-op on projects with files already at the new location, and clean-project no-ops. Regression assertions in `tests/commands/upgrade.test.js`, `tests/commands/init.test.js`, and `tests/core/merger.test.js` explicitly verify that `.workflow-ref.md` siblings are NEVER created inside `.claude/commands/` or `.claude/agents/`, so the phantom-command class of bug cannot silently return. 575/575 pass (567 prior + 8 new).
+
+## [2.5.0] — 2026-04-21
+
+First release under the new per-PR bump declaration workflow. Shifts release mechanism from "every `/sync` publishes" to "every PR declares a bump, `/sync` aggregates, and only user-visible work ships." PR authors now declare `Version bump: {major|minor|patch|none}` in their PR body; `/sync` picks the highest declared bump since the last tag using precedence `major > minor > patch > none`. All-`none` batches update shared-state files on develop but never cut a release — internal-only work (docs, CI, tests) accumulates without triggering noisy publishes.
+
+### Added
+
+- **Per-PR `Version bump:` declaration** (PR #99) — new step 6 in `/commit-push-pr` asks authors to declare `major`/`minor`/`patch`/`none` in the PR body; revert PRs match the bump of the PR being reverted; ambiguous cases ASK the user. The declaration is pasted into both `templates/commands/` (scaffolded into user projects) and `.claude/commands/` (Worclaude's own runtime), kept byte-identical by convention.
+- **`/sync` aggregation rewrite** (PR #99) — replaces the single-step version bump with bootstrap (no-tag → yes/custom/cancel prompt, broadened semver regex accepts pre-release/build metadata, push-failure recovery), aggregation (`gh pr list --limit 500`, `%as` date format to avoid GitHub-search incompatibility with `%ai`, release-PR filter via `headRefName=develop`+`baseRefName=main`, missing-declarations treated as `none`+warning carried through to release PR body and CHANGELOG), ship/wait confirmation (always prompts including for `major`), CHANGELOG append with section defaults mapped from bump type (major/minor → Added, patch → Fixed) and content-driven placement across `### Added`/`### Changed`/`### Fixed`/`### Tests`/`### Docs`.
+- **`tests/templates/version-bump-consistency.test.js`** (PR #99) — new 8-case Vitest asserts `Version bump:` appears literally in all 8 authoritative files (`CLAUDE.md`, both tree copies of `commit-push-pr.md`, `sync.md`, `git-conventions`, and `.github/pull_request_template.md`). Catches rename drift (e.g., `Version bump:` → `Release bump:` in one file without the others). Uses `import.meta.dirname`-derived `REPO_ROOT` matching the `v2-audit` test convention.
+- **`.github/pull_request_template.md`** — required `Version bump:` field with HTML-comment placeholder.
+
+### Changed
+
+- **CLAUDE.md Rule #13** reworded: "every merge to `main` gets at least a patch bump" → "every merge to `main` IS a release." Internal-only `none`-only batches now update shared-state files on develop but never reach `main`.
+- **`.claude/skills/git-conventions/SKILL.md`** — fixed two pre-existing statements that contradicted the new policy: line 117 "every merge to main gets at least a patch bump" replaced with release-carries-bump wording; line 124 table row for docs/CI/tests changed from `patch` to `none (no release)`. `templates/skills/universal/git-conventions.md` already said "no bump" so no contradiction-fix was needed there; both files now have the new `### Per-PR bump declarations` + `### Edge cases` subsections appended identically. Unrelated wording divergence between the two trees left alone.
+- **`README.md`** — short "Batched releases" bullet in the "Why Worclaude" section.
+- ⚠ **PR #98 (`fix(upstream): advance state on SKIP_ISSUE`)** — no `Version bump:` declaration (merged 2026-04-21 14:58 UTC, before PR #99 introduced the workflow). Treated as `none` with warning per bootstrap handling. Under-documentation made visible here rather than silently lost. The fix itself advances `.github/upstream-state.json` whenever Claude returns `SKIP_ISSUE` so no-new-item runs don't re-evaluate the same feed indefinitely.
+
 ## [2.4.12] — 2026-04-20
 
 Internal fix release — first post-v2.4.11 `upstream-check` run on `main` (workflow run 24693290867) failed with `error_max_turns / num_turns: 16` at the Claude cross-reference step. Not a parser issue: the v2.4.11 format-drift fix still works; Claude simply couldn't fit the workload into 15 turns. The prompt requires ~9 `Read` calls (feed inputs + `.claude/commands/upstream-check.md` + cross-reference against agents/commands/hooks templates, `src/data/agents.js`, `src/data/agent-registry.js`, `docs/spec/BACKLOG-v2.1.md`, `CLAUDE.md`) before the final response — each Read burns a turn, so 15 was tight by luck, not by design.

package/README.md

@@ -144,6 +144,7 @@ See the [full command reference](https://sefaertunc.github.io/Worclaude/referenc
 - **Hook profiles.** Dial strictness up or down via one environment variable. `minimal` for CI, `standard` for daily work, `strict` for type-heavy projects.
 - **Smart merge.** Detects existing Claude Code setups and merges additively — existing files never overwritten without confirmation. Three-tier strategy: additive for missing content, safe-alongside for conflicts, interactive for CLAUDE.md.
 - **Self-healing doctor.** Catches drift, stale hashes, deprecated models, broken learnings — before they bite.
+- **Batched releases.** Every PR declares `Version bump: {major|minor|patch|none}` in its body; `/sync` aggregates declarations across merged PRs and only cuts a release when at least one rises above `none`. Internal-only work (docs, CI, tests) accumulates on `develop` without triggering noisy publishes.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worclaude",
-  "version": "2.4.13",
+  "version": "2.5.1",
   "description": "The Workflow Layer for Claude Code — scaffold agents, commands, skills, hooks, and memory into any project",
   "type": "module",
   "bin": {

package/src/commands/doctor.js

@@ -11,7 +11,7 @@ import {
   TEMPLATE_SKILLS,
 } from '../data/agents.js';
 import { hasClaudeMdMemoryGuidance, readClaudeMd } from '../core/drift-checks.js';
-import { resolveKeyPath } from '../core/file-categorizer.js';
+import { resolveKeyPath, isWorkflowRefFile } from '../core/file-categorizer.js';
 import * as display from '../utils/display.js';
 
 // Check categories
@@ -202,7 +202,7 @@ async function checkClaudeMdMemoryGuidance(projectRoot) {
     result(
       WARN,
       'CLAUDE.md memory guidance',
-      'CLAUDE.md lacks memory-architecture guidance. Run worclaude upgrade to write a CLAUDE.md.workflow-ref.md sidecar with suggested additions.'
+      'CLAUDE.md lacks memory-architecture guidance. Run worclaude upgrade to write a sidecar under .claude/workflow-ref/CLAUDE.md with suggested additions.'
     ),
   ];
 }
@@ -828,10 +828,8 @@ async function checkPendingReviewFiles(projectRoot) {
     const claudeDir = path.join(projectRoot, '.claude');
     const allFiles = await listFilesRecursive(claudeDir);
     for (const fp of allFiles) {
-      const rel = path.relative(claudeDir, fp).split(path.sep).join('/');
-      if (rel.endsWith('.workflow-ref.md')) {
-        pending.push(rel);
-      }
+      if (!isWorkflowRefFile(fp, claudeDir)) continue;
+      pending.push(path.relative(claudeDir, fp).split(path.sep).join('/'));
     }
   } catch {
     // .claude dir might not exist

package/src/commands/init.js

@@ -528,7 +528,7 @@ function displayMergeReport(report, backupPath) {
     }
     if (report.added.skills.length > 0) {
       display.barLine(
-        `  ${display.green('✓')} ${report.added.skills.length} skills added${report.conflicts.skills.length > 0 ? ` (${report.conflicts.skills.length} conflicts saved as .workflow-ref.md)` : ''}`
+        `  ${display.green('✓')} ${report.added.skills.length} skills added${report.conflicts.skills.length > 0 ? ` (${report.conflicts.skills.length} conflicts saved under .claude/workflow-ref/)` : ''}`
       );
     }
     if (report.added.permissions > 0) {
@@ -549,10 +549,11 @@ function displayMergeReport(report, backupPath) {
     ...report.conflicts.commands,
   ];
   if (allConflicts.length > 0) {
-    display.barLine(`${display.yellow('~')} Conflicts (saved alongside for review):`);
+    display.barLine(
+      `${display.yellow('~')} Conflicts (template copy saved under .claude/workflow-ref/):`
+    );
     for (const file of allConflicts) {
-      const refName = file.replace('.md', '.workflow-ref.md');
-      display.barLine(`  ${display.yellow('⚠')} ${file} → ${refName}`);
+      display.barLine(`  ${display.yellow('⚠')} ${file}`);
     }
     display.newline();
   }
@@ -606,12 +607,14 @@ function displayMergeReport(report, backupPath) {
   display.divider('NEXT');
   display.newline();
   if (allConflicts.length > 0) {
-    console.log(`  ${display.white('1.')} Review .workflow-ref.md files and merge what's useful`);
+    console.log(
+      `  ${display.white('1.')} Review files under .claude/workflow-ref/ and merge what's useful`
+    );
   }
   if (report.claudeMdHandling === 'suggestions-generated') {
     console.log(`  ${display.white('2.')} Review CLAUDE.md.workflow-suggestions`);
     console.log(
-      `  ${display.white('3.')} Delete .workflow-ref.md and .workflow-suggestions files when done`
+      `  ${display.white('3.')} Delete .claude/workflow-ref/ and .workflow-suggestions when done`
     );
   }
   console.log(

package/src/commands/status.js

@@ -3,6 +3,7 @@ import { requireWorkflowMeta, getPackageVersion } from '../core/config.js';
 import { hashFile } from '../utils/hash.js';
 import { fileExists, readFile, listFilesRecursive } from '../utils/file.js';
 import { getLatestNpmVersion } from '../utils/npm.js';
+import { isWorkflowRefFile } from '../core/file-categorizer.js';
 import { TECH_STACKS } from '../data/agents.js';
 import * as display from '../utils/display.js';
 
@@ -99,16 +100,17 @@ export async function statusCommand() {
     display.newline();
   }
 
-  // Pending review files
+  // Pending review files — anything isWorkflowRefFile() recognizes. That
+  // covers the v2.5.1+ .claude/workflow-ref/ tree plus legacy .workflow-ref.md
+  // siblings, so users mid-migration still see what they need to resolve.
   const pendingReview = [];
   try {
     const claudeDir = path.join(projectRoot, '.claude');
     const allFiles = await listFilesRecursive(claudeDir);
     for (const fp of allFiles) {
+      if (!isWorkflowRefFile(fp, claudeDir)) continue;
       const rel = path.relative(claudeDir, fp).split(path.sep).join('/');
-      if (rel.endsWith('.workflow-ref.md')) {
-        pendingReview.push(`.claude/${rel}`);
-      }
+      pendingReview.push(`.claude/${rel}`);
     }
   } catch {
     // .claude dir might not exist

package/src/commands/upgrade.js

@@ -5,7 +5,7 @@ import inquirer from 'inquirer';
 import ora from 'ora';
 import { requireWorkflowMeta, writeWorkflowMeta, getPackageVersion } from '../core/config.js';
 import { createBackup } from '../core/backup.js';
-import { categorizeFiles, resolveKeyPath } from '../core/file-categorizer.js';
+import { categorizeFiles, resolveKeyPath, resolveRefPath } from '../core/file-categorizer.js';
 import { buildSettingsJson, mergeSettingsPermissionsAndHooks } from '../core/merger.js';
 import { readTemplate, substituteVariables, updateGitignore } from '../core/scaffolder.js';
 import { buildAgentsMdVariables } from '../core/variables.js';
@@ -19,7 +19,12 @@ import { writeFile, readFile, fileExists } from '../utils/file.js';
 import { hashFile } from '../utils/hash.js';
 import { getLatestNpmVersion } from '../utils/npm.js';
 import * as display from '../utils/display.js';
-import { semverLessThan, migrateSkillFormat, patchAgentDescriptions } from '../core/migration.js';
+import {
+  semverLessThan,
+  migrateSkillFormat,
+  patchAgentDescriptions,
+  migrateWorkflowRefLocation,
+} from '../core/migration.js';
 
 const CONFLICT_CHECK_TYPES = new Set(['hook', 'root-file']);
 
@@ -41,12 +46,6 @@ function selfUpdate(latestVersion) {
   }
 }
 
-function sidecarPathFor(dest) {
-  const ext = path.extname(dest);
-  const base = ext ? dest.slice(0, dest.length - ext.length) : dest;
-  return `${base}.workflow-ref${ext}`;
-}
-
 async function renderTemplate({ templatePath, type }, variables) {
   const templateContent = await readTemplate(templatePath);
   return type === 'root-file' ? substituteVariables(templateContent, variables) : templateContent;
@@ -57,8 +56,8 @@ async function writeTemplateToDest(entry, dest, variables) {
   await writeFile(dest, await renderTemplate(entry, variables));
 }
 
-async function writeSidecarFor(entry, dest, variables) {
-  const sidecarPath = sidecarPathFor(dest);
+async function writeSidecarFor(entry, projectRoot, variables) {
+  const sidecarPath = resolveRefPath(entry.key, projectRoot);
   await writeFile(sidecarPath, await renderTemplate(entry, variables));
   return sidecarPath;
 }
@@ -122,7 +121,7 @@ function renderRepairPreview(plan) {
   }
   if (plan.claudeMdNeedsSidecar) {
     sidecarLines.push(
-      '  ~ CLAUDE.md memory guidance missing (will write CLAUDE.md.workflow-ref.md)'
+      '  ~ CLAUDE.md memory guidance missing (will write .claude/workflow-ref/CLAUDE.md sidecar)'
     );
   }
   if (sidecarLines.length > 0) {
@@ -197,7 +196,7 @@ async function applyRepairPass(projectRoot, plan, variables) {
     if (await fileExists(dest)) {
       const matches = await diskContentMatchesTemplate(entry, dest, variables);
       if (!matches) {
-        const sidecarPath = await writeSidecarFor(entry, dest, variables);
+        const sidecarPath = await writeSidecarFor(entry, projectRoot, variables);
         result.migrationConflicts.push({ key: entry.key, dest, sidecarPath });
         continue;
       }
@@ -282,7 +281,7 @@ async function runRepairOnlyFlow({ projectRoot, meta, plan, variables, dryRun, y
     }
     if (result.migrationConflicts.length > 0) {
       display.barLine(
-        `Conflicts:   ${result.migrationConflicts.length} files ${display.dimColor('(saved as .workflow-ref)')}`
+        `Conflicts:   ${result.migrationConflicts.length} files ${display.dimColor('(saved under .claude/workflow-ref/)')}`
       );
     }
     if (result.createdDirs.length > 0) {
@@ -295,7 +294,7 @@ async function runRepairOnlyFlow({ projectRoot, meta, plan, variables, dryRun, y
 
     if (result.migrationConflicts.length > 0 || result.sidecars.length > 0) {
       display.newline();
-      display.barLine(`Review .workflow-ref files and merge what's useful.`);
+      display.barLine(`Review files under .claude/workflow-ref/ and merge what's useful.`);
     }
   } catch (err) {
     spinner.fail('Repair failed.');
@@ -440,17 +439,25 @@ export async function upgradeCommand(options = {}) {
       spinner.start('Applying updates...');
     }
 
+    // v2.5.1 migration: relocate legacy ref files out of Claude-Code-scanned
+    // dirs. Runs unconditionally since it's idempotent and the fix applies
+    // to any project with legacy refs, regardless of source version.
+    const refRelocationReport = await migrateWorkflowRefLocation(projectRoot);
+    if (refRelocationReport.moved > 0) {
+      spinner.text = `Relocated ${refRelocationReport.moved} legacy ref file(s)...`;
+    }
+
     // Auto-update files
     for (const { key, templatePath } of categories.autoUpdate) {
       const content = await readTemplate(templatePath);
       await writeFile(resolveKeyPath(key, projectRoot), content);
     }
 
-    // Conflict files: save as .workflow-ref.md
+    // Conflict files: save under .claude/workflow-ref/ so they never collide
+    // with Claude Code's command/agent discovery.
     for (const { key, templatePath } of categories.conflict) {
       const content = await readTemplate(templatePath);
-      const refKey = key.replace(/\.md$/, '.workflow-ref.md');
-      await writeFile(resolveKeyPath(refKey, projectRoot), content);
+      await writeFile(resolveRefPath(key, projectRoot), content);
     }
 
     // New files (non-migration types handled here; migration types were
@@ -510,7 +517,7 @@ export async function upgradeCommand(options = {}) {
     }
     if (repairResult.migrationConflicts.length > 0) {
       display.barLine(
-        `Migration conflicts: ${repairResult.migrationConflicts.length} ${display.dimColor('(saved as .workflow-ref)')}`
+        `Migration conflicts: ${repairResult.migrationConflicts.length} ${display.dimColor('(saved under .claude/workflow-ref/)')}`
       );
     }
     if (categories.autoUpdate.length > 0) {
@@ -518,7 +525,12 @@ export async function upgradeCommand(options = {}) {
     }
     if (categories.conflict.length > 0) {
       display.barLine(
-        `Conflicts:   ${categories.conflict.length} files ${display.dimColor('(saved as .workflow-ref.md)')}`
+        `Conflicts:   ${categories.conflict.length} files ${display.dimColor('(saved under .claude/workflow-ref/)')}`
+      );
+    }
+    if (refRelocationReport.moved > 0) {
+      display.barLine(
+        `Relocated:   ${refRelocationReport.moved} legacy ref file(s) ${display.dimColor('→ .claude/workflow-ref/')}`
       );
     }
     if (plan.templateNewFiles.length > 0) {
@@ -558,7 +570,7 @@ export async function upgradeCommand(options = {}) {
       repairResult.sidecars.length > 0
     ) {
       display.newline();
-      display.barLine(`Review .workflow-ref files and merge what's useful.`);
+      display.barLine(`Review files under .claude/workflow-ref/ and merge what's useful.`);
     }
   } catch (err) {
     spinner.fail('Upgrade failed.');

package/src/core/drift-checks.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import fs from 'fs-extra';
 import { fileExists, readFile, writeFile } from '../utils/file.js';
+import { resolveRefPath } from './file-categorizer.js';
 
 export const MEMORY_GUIDANCE_KEYWORDS = [
   'memory architecture',
@@ -47,7 +48,7 @@ export function buildMemoryGuidanceSidecar() {
 }
 
 export async function writeMemoryGuidanceSidecar(projectRoot) {
-  const dest = path.join(projectRoot, 'CLAUDE.md.workflow-ref.md');
+  const dest = resolveRefPath('root/CLAUDE.md', projectRoot);
   await writeFile(dest, buildMemoryGuidanceSidecar());
   return dest;
 }

package/src/core/file-categorizer.js

@@ -36,6 +36,7 @@ export function isAlwaysScaffolded(entry, meta) {
 }
 
 export const ROOT_KEY_PREFIX = 'root/';
+export const WORKFLOW_REF_DIR = 'workflow-ref';
 
 export function resolveKeyPath(key, projectRoot) {
   if (key.startsWith(ROOT_KEY_PREFIX)) {
@@ -45,6 +46,43 @@ export function resolveKeyPath(key, projectRoot) {
   return path.join(projectRoot, '.claude', ...key.split('/'));
 }
 
+/**
+ * Project-root-relative path for a ref file. Useful for scaffoldFile() which
+ * takes a destRelativePath. Returns e.g. ".claude/workflow-ref/commands/sync.md".
+ * Accepts a workflow key ("commands/sync.md", "root/CLAUDE.md") or a plain
+ * relative path. Root-level files (CLAUDE.md, AGENTS.md) land directly
+ * under workflow-ref/, not under workflow-ref/root/.
+ */
+export function workflowRefRelPath(keyOrRelPath) {
+  const rel = keyOrRelPath.startsWith(ROOT_KEY_PREFIX)
+    ? keyOrRelPath.slice(ROOT_KEY_PREFIX.length)
+    : keyOrRelPath;
+  return path.join('.claude', WORKFLOW_REF_DIR, ...rel.split('/'));
+}
+
+/**
+ * Resolve an absolute ref file destination for a given relative path.
+ * Wraps workflowRefRelPath with projectRoot.
+ */
+export function resolveRefPath(keyOrRelPath, projectRoot) {
+  return path.join(projectRoot, workflowRefRelPath(keyOrRelPath));
+}
+
+/**
+ * Predicate for "is this file a reference copy?". Matches both the v2.5.1+
+ * layout (anywhere under .claude/workflow-ref/) and the legacy sibling
+ * convention (.workflow-ref.md suffix). Used by status, doctor, and remover
+ * so they stay in sync across the two location schemes.
+ *
+ * @param {string} absPath — absolute path on disk
+ * @param {string} claudeDir — absolute path to the project's .claude/ directory
+ */
+export function isWorkflowRefFile(absPath, claudeDir) {
+  const refDirPrefix = path.join(claudeDir, WORKFLOW_REF_DIR) + path.sep;
+  if (absPath.startsWith(refDirPrefix)) return true;
+  return absPath.endsWith('.workflow-ref.md');
+}
+
 /**
  * Build a map of all workflow template files to their hash keys, template paths, and hashes.
  * Hash keys match the format stored in workflow-meta.json (relative to .claude/).

package/src/core/merger.js

@@ -10,6 +10,7 @@ import {
   scaffoldPluginJson,
   scaffoldMemoryDocs,
 } from './scaffolder.js';
+import { workflowRefRelPath } from './file-categorizer.js';
 import { promptHookConflict } from '../prompts/conflict-resolution.js';
 import {
   detectMissingSections,
@@ -124,10 +125,11 @@ async function mergeSkills(projectRoot, existingScan, variables, report, selecti
     const existsAsFlat = existingScan.existingSkills.includes(`${skill.name}.md`);
 
     if (existsAsDir || existsAsFlat) {
-      // Tier 2: conflict — save as .workflow-ref.md
+      // Tier 2: conflict — save under .claude/workflow-ref/ so the live
+      // SKILL.md stays authoritative and the ref cannot shadow it.
       await scaffoldFile(
         skill.templatePath,
-        path.join('.claude', 'skills', skill.name, 'SKILL.workflow-ref.md'),
+        workflowRefRelPath(`skills/${skill.name}/SKILL.md`),
         skill.vars,
         projectRoot
       );
@@ -147,7 +149,7 @@ async function mergeSkills(projectRoot, existingScan, variables, report, selecti
 
   if (routingExistsAsDir || routingExistsAsFlat) {
     await writeFile(
-      path.join(projectRoot, skillsDir, 'agent-routing', 'SKILL.workflow-ref.md'),
+      path.join(projectRoot, workflowRefRelPath('skills/agent-routing/SKILL.md')),
       routingContent
     );
     report.conflicts.skills.push('agent-routing');
@@ -166,7 +168,7 @@ async function mergeAgents(projectRoot, existingScan, selectedAgents, report) {
     if (existingScan.existingAgents.includes(filename)) {
       await scaffoldFile(
         `agents/universal/${agent}.md`,
-        path.join(destDir, `${agent}.workflow-ref.md`),
+        workflowRefRelPath(`agents/${filename}`),
         {},
         projectRoot
       );
@@ -191,7 +193,7 @@ async function mergeAgents(projectRoot, existingScan, selectedAgents, report) {
     if (existingScan.existingAgents.includes(filename)) {
       await scaffoldFile(
         `agents/optional/${category}/${agent}.md`,
-        path.join(destDir, `${agent}.workflow-ref.md`),
+        workflowRefRelPath(`agents/${filename}`),
         {},
         projectRoot
       );
@@ -216,7 +218,7 @@ async function mergeCommands(projectRoot, existingScan, report) {
     if (existingScan.existingCommands.includes(filename)) {
       await scaffoldFile(
         `commands/${cmd}.md`,
-        path.join(destDir, `${cmd}.workflow-ref.md`),
+        workflowRefRelPath(`commands/${filename}`),
         {},
         projectRoot
       );
@@ -431,7 +433,12 @@ async function mergeAgentsMd(projectRoot, existingScan, variables, report) {
     await scaffoldFile('core/agents-md.md', 'AGENTS.md', variables, projectRoot);
     report.agentsMdHandling = 'created';
   } else {
-    await scaffoldFile('core/agents-md.md', 'AGENTS.md.workflow-ref', variables, projectRoot);
+    await scaffoldFile(
+      'core/agents-md.md',
+      workflowRefRelPath('root/AGENTS.md'),
+      variables,
+      projectRoot
+    );
     report.agentsMdHandling = 'saved-alongside';
   }
 }

package/src/core/migration.js

@@ -1,7 +1,16 @@
 import path from 'node:path';
 import { AGENT_CATALOG } from '../data/agents.js';
-import { readFile, writeFile, dirExists, moveFile, listFiles } from '../utils/file.js';
+import {
+  fileExists,
+  readFile,
+  writeFile,
+  dirExists,
+  moveFile,
+  listFiles,
+  listFilesRecursive,
+} from '../utils/file.js';
 import { hashFile } from '../utils/hash.js';
+import { WORKFLOW_REF_DIR } from './file-categorizer.js';
 
 // --- Version comparison ---
 
@@ -142,3 +151,70 @@ export async function patchAgentDescriptions(projectRoot, meta, promptFn) {
 
   return report;
 }
+
+// --- Workflow-ref relocation (v2.5.1) ---
+
+const LEGACY_ROOT_REFS = ['CLAUDE.md.workflow-ref.md', 'AGENTS.md.workflow-ref'];
+
+// Legacy ref files could only live inside these subdirs. Scoping the scan
+// here instead of walking all of .claude/ matters because `sessions/` and
+// `learnings/` can accumulate hundreds of files that will never be refs.
+const LEGACY_REF_SUBDIRS = ['commands', 'agents', 'skills'];
+
+function legacyClaudeRefTarget(relKey) {
+  // relKey is relative to .claude/, e.g. "commands/sync.workflow-ref.md".
+  // Lookahead `(?=\.[^.]+$)` ensures ".workflow-ref" is stripped only when
+  // followed by a final extension — so "sync.workflow-ref.md" → "sync.md",
+  // but a hypothetical "sync.workflow-ref" (no final ext) wouldn't match.
+  const parts = relKey.split('/');
+  const name = parts.pop();
+  parts.push(name.replace(/\.workflow-ref(?=\.[^.]+$)/, ''));
+  return path.join(WORKFLOW_REF_DIR, ...parts);
+}
+
+export async function migrateWorkflowRefLocation(projectRoot) {
+  const report = { moved: 0, names: [], skipped: [] };
+  const claudeDir = path.join(projectRoot, '.claude');
+  const refDir = path.join(claudeDir, WORKFLOW_REF_DIR);
+
+  // 1. Scan only the subdirs where legacy `.workflow-ref.md` siblings could
+  //    live. Walking all of .claude/ would re-stat hundreds of session files
+  //    on every upgrade for no benefit.
+  for (const subdir of LEGACY_REF_SUBDIRS) {
+    const scanRoot = path.join(claudeDir, subdir);
+    if (!(await dirExists(scanRoot))) continue;
+
+    const allFiles = await listFilesRecursive(scanRoot);
+    for (const fp of allFiles) {
+      const rel = path.relative(claudeDir, fp).split(path.sep).join('/');
+      if (!rel.endsWith('.workflow-ref.md')) continue;
+
+      const target = path.join(claudeDir, legacyClaudeRefTarget(rel));
+      if (await fileExists(target)) {
+        report.skipped.push(rel);
+        continue;
+      }
+      await moveFile(fp, target);
+      report.moved++;
+      report.names.push(rel);
+    }
+  }
+
+  // 2. Legacy root-level refs (CLAUDE.md.workflow-ref.md, AGENTS.md.workflow-ref).
+  for (const legacyName of LEGACY_ROOT_REFS) {
+    const src = path.join(projectRoot, legacyName);
+    if (!(await fileExists(src))) continue;
+
+    const original = legacyName.replace(/\.workflow-ref(?:\.md)?$/, '');
+    const target = path.join(refDir, original);
+    if (await fileExists(target)) {
+      report.skipped.push(legacyName);
+      continue;
+    }
+    await moveFile(src, target);
+    report.moved++;
+    report.names.push(legacyName);
+  }
+
+  return report;
+}

package/src/core/remover.js

@@ -9,6 +9,7 @@ import {
   listFilesRecursive,
   removeDirectory,
 } from '../utils/file.js';
+import { WORKFLOW_REF_DIR } from './file-categorizer.js';
 
 /**
  * Classify .claude/ files into safe-to-delete, modified, missing, and user-owned.
@@ -55,8 +56,9 @@ export async function classifyClaudeFiles(projectRoot, meta) {
     const relKey = path.relative(claudeDir, fp).split(path.sep).join('/');
     if (allTrackedKeys.has(relKey)) continue;
 
-    // .workflow-ref.md files are upgrade artifacts — safe to delete
-    if (relKey.endsWith('.workflow-ref.md')) {
+    // Upgrade artifacts — safe to delete: anything under workflow-ref/ (new
+    // location) or the legacy `.workflow-ref.md` sibling suffix.
+    if (relKey.startsWith(`${WORKFLOW_REF_DIR}/`) || relKey.endsWith('.workflow-ref.md')) {
       safeToDelete.push(relKey);
     } else {
       userOwned.push(relKey);
@@ -115,7 +117,7 @@ export async function removeTrackedFiles(projectRoot, fileKeys) {
   }
 
   // Clean up empty subdirectories
-  for (const subdir of ['agents', 'commands', 'skills']) {
+  for (const subdir of ['agents', 'commands', 'skills', WORKFLOW_REF_DIR]) {
     const dirPath = path.join(claudeDir, subdir);
     if (await dirExists(dirPath)) {
       const remaining = await listFilesRecursive(dirPath);

package/templates/commands/commit-push-pr.md

@@ -45,12 +45,35 @@ files (see git-conventions.md for the canonical list).
 3. Write a clear, conventional commit message
 4. Push to the current branch
 5. Create a PR targeting develop: gh pr create --base develop
-6. Include in PR description: title, changes, testing done, reviewer notes
+6. Determine the version bump level for this PR. Read the Versioning Policy
+   in the project's git-conventions document to decide: `major`, `minor`,
+   `patch`, or `none`.
+   - `major` — breaking change to public API, CLI, or scaffold contract
+   - `minor` — new feature, command, agent, or flag
+   - `patch` — bug fix or user-visible behavior change with no new surface
+   - `none` — docs, CI, tests, internal refactor (nothing consumers notice)
+
+   For revert PRs: declare the same bump level as the PR being reverted.
+
+   If the change is ambiguous, ASK THE USER. Do not guess.
+
+   The PR description MUST include this line on its own, verbatim:
+
+   ```
+   Version bump: {major|minor|patch|none}
+   ```
+
+   `/sync` parses this string exactly — other phrasings will be ignored.
+7. Include in PR description: title, changes, testing done, reviewer notes
 
 ## On develop
 
 Only used for release merges after /sync has been run.
 
+Versioning happens in `/sync`, not here. The release PR body is pre-written
+by `/sync` with the aggregated bump summary and the list of feature PRs
+included in the release.
+
 1. Write a session summary to .claude/sessions/:
    - Filename: YYYY-MM-DD-HHMM-{short-branch-name}.md
    - Same format as the feature branch session summary above

package/templates/commands/sync.md

@@ -35,23 +35,190 @@ and tell the user to run /conflict-resolver first.
    docs/spec/SPEC.md to reflect the current state.
    If nothing changed spec-wise, leave it alone.
 
-## Version bump
+## Bootstrap: ensure a version tag exists
 
-6. Determine version bump using the Versioning Policy in
-   git-conventions.md. If bump needed: update version in package.json.
+6. Check for a version tag:
+
+   ```bash
+   LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+   ```
+
+   If no tag exists, prompt the user. Do NOT silently auto-tag:
+
+   ```
+   No version tag found. /sync needs a starting tag to compute release scope.
+
+   Proposed: tag current HEAD as v0.1.0
+
+   - yes      → create v0.1.0 tag at HEAD and continue
+   - custom   → specify your own starting version (e.g., v1.0.0 if this
+                project had releases before adopting this workflow)
+   - cancel   → stop; tag manually before re-running
+
+   Choose (yes / custom / cancel):
+   ```
+
+   On "yes": `git tag v0.1.0 && git push origin v0.1.0`, then set
+   `LAST_TAG="v0.1.0"`.
+
+   On "custom": prompt for the version string. Accept any string matching
+   `^v\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$` (semver with
+   optional pre-release and build metadata, e.g. `v1.0.0-rc.1`, `v2.0.0+build.5`).
+   Reject non-matching input with a clear message and re-prompt. Then tag
+   and push as above.
+
+   On "cancel": exit cleanly with "Tag the current state manually before
+   re-running /sync."
+
+   If `git push origin {tag}` fails (fork clone, expired credentials,
+   network): the local tag is already created and valid. Report:
+   "Local tag created but push failed — retry with `git push origin {tag}`
+   manually before opening a release PR." Then exit cleanly.
+
+   After bootstrap, proceed to step 7. Expect "Nothing publishable since
+   {tag}" if no PRs have been merged yet — that is correct behavior for
+   a first-release bootstrap, not an error.
+
+## Aggregate version bumps from merged PRs
+
+7. Collect `Version bump:` declarations from all PRs merged into develop
+   since the last version tag. Use `%as` for the date format (strict
+   YYYY-MM-DD; `%ai` breaks GitHub search due to space separator and
+   timezone offset). Pass `--limit 500` to avoid the `gh pr list` default
+   cap of 30, which would silently truncate on repos with infrequent
+   tagging:
+
+   ```bash
+   SINCE=$(git log -1 --format=%as "$LAST_TAG")
+   gh pr list --state merged --base develop \
+     --limit 500 \
+     --search "merged:>=$SINCE" \
+     --json number,title,body,headRefName,baseRefName
+   ```
+
+   Filter out release PRs — any PR with `headRefName: develop` AND
+   `baseRefName: main` is a release PR from a prior `/sync` run, not an
+   input. Skip those.
+
+   For each remaining PR, extract the `Version bump:` line from the body.
+   Valid values: `major`, `minor`, `patch`, `none`.
+
+   Missing declarations: treat as `none` and add to a warning list
+   (carried through to step 9's summary and step 10's CHANGELOG entry).
+   Do NOT guess a higher value. Do NOT stop.
+
+8. Compute the release bump using precedence: `major > minor > patch > none`.
+   - If the highest is `none`: update PROGRESS.md and SPEC.md if needed,
+     commit those, push, and stop. Do NOT bump the version. Do NOT open
+     a PR to main. Report:
+
+     ```
+     Nothing publishable since {last-tag}. Shared state updated.
+     ```
+
+   - If the highest is `patch`, `minor`, or `major`: proceed to step 9.
+
+9. Summarize the release group for the user and ask for confirmation.
+   Always prompt, including for `major` — that's exactly when the human
+   sanity-check is most valuable.
+
+   If the warnings list from step 7 is empty, omit the warnings section
+   entirely — do NOT render an empty block or a "no warnings" line.
+
+   Summary format (warnings section included only when warnings exist):
+
+   ```
+   Release group since {last-tag}:
+   - #{num} {title} — {bump}
+   - #{num} {title} — {bump}
+   - ...
+
+   ⚠ PRs without Version bump: declaration (treated as none):
+   - #{num} {title}
+   - ...
+
+   Proposed version: {old} → {new} ({highest-bump})
+
+   Ship now, or wait for more work to land? (ship/wait)
+   ```
+
+   If the user says "wait", stop without bumping. They will re-run `/sync`
+   later when more PRs have merged.
+
+10. On "ship":
+
+    a. Update the `version` field in `package.json` to the new version.
+
+    b. Append to `CHANGELOG.md` at the top of the entries list (after the
+       `# Changelog` header and the `## [Unreleased]` marker if present).
+       If `CHANGELOG.md` does not exist, create it with this header:
+
+       ```markdown
+       # Changelog
+
+       All notable changes to this project are documented in this file.
+       Format loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+       versions follow [semver](https://semver.org/).
+
+       ## [Unreleased]
+       ```
+
+       The new entry format:
+
+       ```markdown
+       ## [{new-version}] — {YYYY-MM-DD}
+
+       {one-paragraph prose summary of what this release does — synthesize
+       from the merged PR titles and bodies; no bullet list in the summary}
+
+       ### {Section}
+
+       - {bullet per PR mapped to its section, including PR number}
+       ```
+
+       Section mapping — the declared bump determines the MINIMUM section,
+       but each PR's content governs its actual placement. PRs may be filed
+       under any of `### Added` / `### Changed` / `### Fixed` / `### Tests` /
+       `### Docs` as content warrants. Do not force a mapping that fights
+       the content.
+
+       Defaults when content is ambiguous:
+       - `major`, `minor` → default `### Added` (or `### Changed` for
+         breaking changes)
+       - `patch` → default `### Fixed` (but `### Added` is fine for
+         patch-level additive surface like new optional flags)
+       - `none` with warning → `### Changed` with ⚠ prefix noting
+         "no Version bump declaration — under-documented"
+
+       If a release mixes levels, each PR goes under its own section.
+       Multiple sections per release entry are standard.
+
+       The warning list from step 9 MUST appear in the CHANGELOG entry as
+       ⚠-prefixed bullets under `### Changed` — not just in the transient
+       prompt. This is how under-documentation becomes permanent record.
 
 ## Verify
 
-7. Run /verify to confirm tests and lint pass.
-   If anything fails, fix it before proceeding.
+11. Run /verify to confirm tests and lint pass.
+    If anything fails, fix it before proceeding.
 
 ## Commit, push, and PR
 
-8. git add -A
-9. git commit -m "chore: sync progress, spec, and version to [new version]"
-   Use exactly this message format — no trailers or Co-Authored-By lines.
-10. git push origin develop
-11. gh pr create --base main with description of what was merged
+12. git add -A
+13. git commit -m "chore: sync progress, spec, and version to [new version]"
+    Use exactly this message format — no trailers or Co-Authored-By lines.
+14. git push origin develop
+15. Create the PR to main. Use the release group summary from step 9 as the
+    PR body verbatim (including any warnings block) — that becomes the
+    release notes:
+
+    ```bash
+    gh pr create --base main --title "release: v{new-version}" --body "{step-9-summary}"
+    ```
+
+    The maintainer then manually creates a GitHub Release against main
+    with tag vX.Y.Z — that triggers the release.yml workflow which
+    publishes to npm with provenance. /sync does not publish.
 
 ## Trigger Phrases
 - "sync progress"

package/templates/skills/universal/git-conventions.md

@@ -135,6 +135,55 @@ Follow [semver](https://semver.org/) when the project publishes releases:
 
 **Rule of thumb:** If the change affects what users see, install, or depend on, it needs a version bump. If it only affects the project's internal development workflow, it does not.
 
+### Per-PR bump declarations
+
+Every PR targeting `develop` declares its intended version bump in the PR
+description:
+
+```
+Version bump: {major|minor|patch|none}
+```
+
+- `major` — breaking change to public API, CLI, or scaffold contract
+- `minor` — new feature, command, agent, or flag
+- `patch` — bug fix or user-visible behavior change with no new surface
+- `none` — docs, CI, tests, internal refactor (nothing consumers notice)
+
+`/sync` aggregates declarations from all PRs merged since the last version
+tag and picks the highest: `major > minor > patch > none`. If all merged
+PRs are `none`, no release is cut — `/sync` updates shared-state files but
+does not bump the version or open a PR to `main`.
+
+This is how release batching works: internal-only work accumulates on
+develop without triggering publishes, and multiple user-facing PRs group
+into a single well-documented release.
+
+### Edge cases
+
+- **Release PRs (develop → main):** `/sync` excludes these from scanning.
+  They ARE the release, not an input to one. Known limitation: any
+  develop→main PR is excluded regardless of content. Safe in practice
+  because that direction is only used for releases.
+- **Revert PRs:** Declare the same bump level as the PR being reverted.
+  Reverting a `patch` is itself a `patch`. A `patch` + matching revert
+  in the same release group produces a net-zero user-visible change but
+  still bumps the version — something shipped internally and was
+  un-shipped, which is part of the release's history. Do not cancel
+  them out.
+- **Missing declarations:** Treated as `none` with a warning that
+  propagates to the release PR body and CHANGELOG entry. Do not manually
+  backfill old PR bodies — let them flow through as `none` so
+  under-documentation is visible rather than silent.
+- **No tags yet (first release):** `/sync` prompts to create a starting
+  tag (default `v0.1.0`, customizable, cancelable). The tool does NOT
+  silently invent a tag.
+- **Hotfix merged directly to main:** Bypasses `/sync` entirely. Requires
+  manual version management. Known limitation; out of scope.
+
+**Optional:** GitHub labels (`release:major`, `release:minor`, etc.) can
+replace body-text declarations for maintainers who prefer them. Deferred
+to a future phase; not scaffolded by default.
+
 ## Gotchas
 
 - Never force-push to main/master. Force-push to feature branches only when you