worclaude 2.4.13 → 2.5.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to worclaude are documented in this file. Format loosely fol
 
 ## [Unreleased]
 
+## [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.0",
   "description": "The Workflow Layer for Claude Code — scaffold agents, commands, skills, hooks, and memory into any project",
   "type": "module",
   "bin": {

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