worclaude 2.4.12 → 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/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+sefaertunc@gmail.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

package/CONTRIBUTING.md

@@ -0,0 +1,132 @@
+# Contributing to Worclaude
+
+Thanks for your interest in contributing to Worclaude! Whether it's a bug report, feature idea, or pull request, your input helps make this tool better for everyone.
+
+## Branching Strategy
+
+```
+feature-branch ──PR──▶ develop ──PR──▶ main (release)
+                           │
+                           └── gh-pages (docs, auto-deployed)
+```
+
+| Branch     | Purpose             | Who can push             | Who can PR to it                     |
+| ---------- | ------------------- | ------------------------ | ------------------------------------ |
+| `develop`  | Active development  | Maintainer               | Contributors (from feature branches) |
+| `main`     | Production releases | Maintainer               | Maintainer only (from `develop`)     |
+| `gh-pages` | Documentation site  | Maintainer (auto-deploy) | Nobody                               |
+
+**Contributors only interact with `develop`.** Fork the repo, create a feature branch from `develop`, and open a PR back to `develop`. You cannot push or open PRs against `main` — they will be closed.
+
+## Development Setup
+
+```bash
+git clone https://github.com/sefaertunc/Worclaude.git
+cd Worclaude
+git checkout develop
+npm install
+npm test
+npm run lint
+```
+
+Run the CLI locally during development:
+
+```bash
+node src/index.js init
+node src/index.js status
+```
+
+## Using the Worclaude Workflow
+
+If you have [Claude Code](https://claude.com/claude-code), this project includes a 6-stage workflow pipeline to guide contributions:
+
+`/start` → `/review-plan` → implement → `/review-changes` → `/verify` → `/commit-push-pr`
+
+Run these as slash commands in Claude Code for a guided experience.
+
+## Pull Request Guidelines
+
+1. Fork the repo and create a branch from `develop`
+2. Make your changes in focused, logical commits
+3. Write or update tests for any new functionality
+4. Run the full test suite: `npm test`
+5. Run the linter: `npm run lint`
+6. Run the formatter: `npm run format`
+7. Open a PR **targeting `develop`** with a clear description of the change
+
+**Never open PRs against `main`** — they will be closed. Only the maintainer merges `develop` into `main` for releases.
+
+Keep PRs focused on a single concern. If you're fixing a bug and adding a feature, split them into separate PRs.
+
+### What CI Checks
+
+Every PR is validated by CI before merge:
+
+- **Tests** — full test suite across Node 18, 20, and 22
+- **ESLint** — code quality and style rules
+- **Prettier** — formatting consistency check
+- **Branch** — must be up-to-date with `develop`
+
+## Release Process (maintainer only)
+
+Releases are cut from `main` and published automatically by GitHub Actions with
+npm provenance (SLSA attestations).
+
+1. Open a PR from `develop` to `main` containing the version bump (handled by `/sync`).
+2. After merge, create a GitHub Release against `main` with tag `vX.Y.Z`.
+3. The `.github/workflows/release.yml` workflow runs `npm publish --provenance`.
+4. Verify the "Provenance" badge on `https://www.npmjs.com/package/worclaude`.
+
+Do not run `npm publish` from a local machine — manual publishes omit provenance
+and weaken the Snyk security score.
+
+## Reporting Bugs
+
+Open an issue on [GitHub Issues](https://github.com/sefaertunc/Worclaude/issues) with:
+
+- A clear, descriptive title
+- Steps to reproduce the problem
+- Expected behavior vs actual behavior
+- Your Node.js version and OS
+- Any relevant error output
+
+## Suggesting Features
+
+Open an issue on [GitHub Issues](https://github.com/sefaertunc/Worclaude/issues) with the **enhancement** label. Describe the use case and how you envision the feature working.
+
+## Code Style
+
+This project uses ESLint and Prettier for consistent formatting. Before submitting:
+
+```bash
+npm run format    # Auto-format with Prettier
+npm run lint      # Check for lint errors
+```
+
+All code must pass both checks. The CI pipeline enforces this automatically.
+
+## Testing
+
+We use [Vitest](https://vitest.dev/) for testing. All tests must pass before a PR can be merged:
+
+```bash
+npm test          # Run the full test suite
+```
+
+When adding new features, include tests that cover:
+
+- The expected happy path
+- Edge cases and error conditions
+- Integration with existing commands (init, upgrade, status)
+
+Test all three scenarios (fresh project, existing project, upgrade) if your change touches merge logic or file generation.
+
+## Template Format Requirements
+
+- **Skills** must be in directory format: `templates/skills/universal/skill-name.md` is the source, scaffolded as `.claude/skills/skill-name/SKILL.md` in user projects. Flat `.md` files in `.claude/skills/` are silently ignored by Claude Code.
+- **Agents** must have both `name` and `description` in YAML frontmatter. Without `description`, agents are invisible to Claude Code's `/agents` and routing system.
+- **Commands** are flat `.md` files in `templates/commands/` and scaffolded as `.claude/commands/command-name.md`. This is the legacy format and is supported.
+
+## Questions?
+
+Open a discussion on GitHub or mention it in your issue/PR. We're happy to help.

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/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 2.4.x   | :white_check_mark: |
+| < 2.4   | :x:                |
+
+## Reporting a Vulnerability
+
+Please report security issues privately via
+[GitHub Security Advisories](https://github.com/sefaertunc/Worclaude/security/advisories/new).
+This is the preferred channel — it lets us coordinate a fix before disclosure.
+
+As a fallback, you may email **sefaertunc@gmail.com**.
+
+Please do **not** open a public issue for security vulnerabilities.
+
+You can expect an initial response within 48 hours.
+If the vulnerability is accepted, a fix will be prioritized and released as a patch version.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worclaude",
-  "version": "2.4.12",
+  "version": "2.5.0",
   "description": "The Workflow Layer for Claude Code — scaffold agents, commands, skills, hooks, and memory into any project",
   "type": "module",
   "bin": {
@@ -12,6 +12,9 @@
     "templates/",
     "README.md",
     "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md",
+    "SECURITY.md",
     "LICENSE"
   ],
   "repository": {
@@ -22,6 +25,7 @@
   "bugs": {
     "url": "https://github.com/sefaertunc/Worclaude/issues"
   },
+  "funding": "https://github.com/sponsors/sefaertunc",
   "author": "Sefa Ertunç",
   "engines": {
     "node": ">=18.0.0"
@@ -37,6 +41,10 @@
     "docs:preview": "vitepress preview docs",
     "prepublishOnly": "npm test && npm run lint"
   },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "keywords": [
     "claude",
     "claude-code",

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