ace-handbook 0.30.1 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40af330ac77e755b410a9980a9fa75b816909fb03dc94081433e51ae9d260f62
-  data.tar.gz: 9bd06eb119329dcce38947dad0023f9fe38493d7956877627e056a4189ab8f5a
+  metadata.gz: 837b9e5d5edbfab28596d94f6e53d3b0a4641451cf43da81899591736a3352ed
+  data.tar.gz: d99a5b04b59b095d60575aac6adc4a7e7bf8009071b0fe42ba7bdb6d342bee3c
 SHA512:
-  metadata.gz: e2f88476c18b665fc2ea415ce37231534aa737b099546feab4cf2e01ffb464b6194dd2d26a80cff81dd78d406a98ee7458ab39eeedb863b385778636bcb0bccf
-  data.tar.gz: 2020c665a6a35b2d68586107a64f2f0bd7d197f63e4e21ae68bda110cf570c36fb30c3558fca9a4c4c1e67c91b429e31c61348f7f52090f559f81831b38c3316
+  metadata.gz: 90654bdde3d8faec5d009c9991091db20aa2f7033615959f82aeec5d7fdaab8a3a38865468f4b5d16c5f3331bbc582ab1fd9ead74f97fba798589cef9ab9a1d1
+  data.tar.gz: fc9dad5f9987207a3ff1c00782df8a4a663d8cba5296d06c3125ce8e0ab17d83506ba06186f91ae1d34f0033c3ef3362cfb80f927d67153edf6b01a5ca9d55b2

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.31.0] - 2026-08-12
+
+### Added
+- Shipped generic baseline `wfi://release/*` workflows (`local`, `bump-version`, `update-changelog`, `publish`, `rubygems-publish`) under `handbook/workflow-instructions/release/` so plain installs resolve release skills without monorepo overlays; defaults stay non-publishing until a project publication contract exists.
+
+## [0.30.3] - 2026-08-12
+
+### Technical
+- Raised the `ace-support-core` dependency floor to `~> 0.31` after the principles-first bootstrap guidance release.
+## [0.30.2] - 2026-08-12
+
+### Technical
+- Aligned gemspec dependency floors with current ACE package minor release lines and safe external minor dependency bumps (no major version jumps).
+
 ## [0.30.1] - 2026-07-15
 
 ### Fixed

data/handbook/workflow-instructions/release/bump-version.wf.md

@@ -0,0 +1,93 @@
+---
+name: release-bump-version
+description: Bump project version surfaces following semver (local only)
+allowed-tools: Bash, Read, Edit
+argument-hint: "[target] [patch|minor|major]"
+doc-type: workflow
+purpose: generic version-bump baseline
+update:
+  frequency: on-change
+  last-updated: "2026-08-12"
+---
+
+# Bump Version Workflow
+
+## Goal
+
+Increment one or more project version surfaces according to Semantic Versioning and keep
+changelog metadata consistent. This workflow is **local preparation only** — it does not publish,
+tag remotely, or mutate external registries.
+
+## Prep vs publication
+
+- **In scope:** edit version files, align changelog headers/entries, refresh lockfiles when
+  required by the bump.
+- **Out of scope:** `gem push`, `npm publish`, deploy scripts, GitHub Release creation, or
+  any other externally mutating publication step.
+
+## Prerequisites
+
+- Target(s) identified (package/module/app) or detectable from the working tree
+- Readable current version and a known bump policy (explicit level or conventional commits)
+- Clean enough git state to attribute the bump (prefer committed feature work first)
+
+## Project Context Loading
+
+- `ace-bundle project` (or project equivalent)
+- `git status --short` and recent commits affecting the target
+
+## Process Steps
+
+### 1. Identify target and current version
+
+```bash
+# Discover version surfaces (adapt to the project)
+# Examples:
+#   package.json → "version"
+#   lib/**/version.rb → VERSION =
+#   Cargo.toml → [package].version
+#   pyproject.toml → project.version
+```
+
+Confirm the current version string before editing.
+
+### 2. Decide bump level
+
+Priority:
+
+1. Explicit argument: `patch`, `minor`, or `major`
+2. Otherwise infer from commits since the last release tag/changelog section
+3. If ambiguous, stop and ask — do not guess major bumps
+
+### 3. Apply the bump
+
+1. Write the new version to every authoritative version surface for the target.
+2. Update changelog to match (new section or Unreleased notes — follow project convention).
+3. Update dependency pins/lockfiles only when the version bump requires it.
+
+```bash
+# TODO: project-specific bump commands
+```
+
+### 4. Verify and commit
+
+- Run targeted tests/build for the bumped target when available.
+- Commit version + changelog (+ required lockfile) as a focused release-prep commit.
+- Do not publish.
+
+## Override
+
+Replace or overlay this file via project WFI sources (for example
+`.ace-handbook/workflow-instructions/release/bump-version.wf.md`). Lower source priority
+numbers win. Keep the URI `wfi://release/bump-version` stable for skills.
+
+## Success Criteria
+
+- [ ] New version written to all authoritative surfaces for the target
+- [ ] Changelog aligned with the bump
+- [ ] No external publish/deploy performed
+
+## Common Issues
+
+- Multiple version files disagree — reconcile before committing.
+- Pre-1.0 projects may treat minor bumps as breaking; follow project policy, not assumptions.

data/handbook/workflow-instructions/release/local.wf.md

@@ -0,0 +1,133 @@
+---
+name: release-local
+description: Prepare a local release (version, changelog, verification) without publishing
+allowed-tools: Bash, Read, Edit
+argument-hint: "[target...] [patch|minor|major]"
+doc-type: workflow
+purpose: generic local release-preparation baseline
+update:
+  frequency: on-change
+  last-updated: "2026-08-12"
+---
+
+# Local Release Preparation Workflow
+
+## Goal
+
+Prepare a release **locally**: decide what is being released, bump version surfaces, update
+changelogs, run verification, and create release commits. This baseline does **not** publish
+to any external registry, deploy target, or package host.
+
+## Prep vs publication
+
+| Mode | This workflow | External mutation |
+|------|---------------|-------------------|
+| **Local preparation (default)** | Version bumps, changelog edits, builds/tests, git commits | None |
+| **Publication** | Out of scope here | Registries, deploys, GitHub Releases, etc. |
+
+Do not run publish/deploy commands unless the project has replaced this baseline with an
+explicit publication contract (see Override below, and `wfi://release/publish` /
+`wfi://release/rubygems-publish` when customized).
+
+## Prerequisites
+
+- Working tree reflects the changes to release (committed or intentionally staged)
+- Project has an identifiable version surface (examples below)
+- You understand Semantic Versioning and the project's changelog convention
+
+## Project Context Loading
+
+- Load project conventions: `ace-bundle project` (or the project's equivalent context bundle)
+- Inspect git state: `git status --short`, recent commits for the release set
+
+## Process Steps
+
+### 1. Resolve release targets
+
+Treat workflow arguments as zero or more release targets plus an optional bump level
+(`patch`, `minor`, or `major`).
+
+- If targets are named, release only those.
+- If none are named, detect candidates from the working tree and recent commits
+  (`git status --short`, `git diff --name-only`, `git diff origin/main...HEAD --name-only`
+  when `origin/main` exists).
+- Prefer the project's existing package/module layout over inventing a new one.
+
+### 2. Locate version and changelog surfaces
+
+Discover (do not invent paths blindly):
+
+| Concern | Common examples |
+|---------|-----------------|
+| Version | `package.json`, `lib/**/version.rb`, `*.gemspec`, `Cargo.toml`, `pyproject.toml`, `VERSION` |
+| Changelog | root `CHANGELOG.md`, package `CHANGELOG.md`, Keep a Changelog sections |
+| Lockfiles | `Gemfile.lock`, `package-lock.json`, `Cargo.lock`, etc. |
+
+If the project has no clear version surface, stop and report what is missing rather than
+guessing.
+
+### 3. Choose bump level
+
+- Use an explicit `patch|minor|major` argument when provided.
+- Otherwise infer from conventional commits / user intent: fix→patch, feature→minor,
+  breaking→major.
+- Record the chosen level before editing files.
+
+### 4. Update version and changelog (local only)
+
+For each target:
+
+1. Bump the version surface to the new version.
+2. Add or extend changelog entries for this release (Keep a Changelog categories when used).
+3. Refresh lockfiles only when the project's dependency tooling requires it for the bump.
+4. Do **not** push tags, create GitHub Releases, or publish packages in this workflow.
+
+Placeholder checklist (fill with project-specific commands):
+
+```bash
+# TODO: project version bump command(s)
+# TODO: project changelog update approach
+# TODO: project lockfile refresh (if required)
+```
+
+### 5. Verify before commit
+
+Run the project's standard verification for the release set:
+
+```bash
+# TODO: replace with project test/lint/build gates
+# Examples: ace-test <package>, npm test, cargo test, pytest
+```
+
+Fix failures before committing release metadata.
+
+### 6. Commit release preparation
+
+Create one or more commits that contain only release preparation (version, changelog,
+required lockfile). Prefer the project's commit skill/tooling when available
+(for example `ace-git-commit`).
+
+Do not push or publish as part of this baseline.
+
+## Override
+
+Higher-priority project sources win over this gem baseline. To customize:
+
+1. Add project workflows under `.ace-handbook/workflow-instructions/release/` (or another
+   registered WFI directory source), **or** package `handbook/workflow-instructions/release/`.
+2. Keep URI names stable (`wfi://release/local`) so skills and assign steps keep working.
+3. WFI source priority: lower number wins; project overlays typically beat gem defaults.
+
+## Success Criteria
+
+- [ ] Version and changelog surfaces updated for every selected target
+- [ ] Verification gates for the release set passed
+- [ ] Release preparation committed locally
+- [ ] No registry publish, deploy, or remote release mutation performed
+
+## Common Issues
+
+- **Unresolved custom publish path:** this baseline stops at local prep; add a project
+  publication contract before publishing.
+- **Missing version surface:** stop and ask rather than inventing version files.
+- **Monorepo vs single package:** detect layout from the repo; do not assume `ace-*` gems.

data/handbook/workflow-instructions/release/publish.wf.md

@@ -0,0 +1,81 @@
+---
+name: release-publish
+description: Compatibility entrypoint for release preparation (non-publishing default)
+allowed-tools: Bash, Read, Edit
+argument-hint: "[target...] [patch|minor|major]"
+doc-type: workflow
+purpose: compatibility alias for local release prep until a publication contract exists
+update:
+  frequency: on-change
+  last-updated: "2026-08-12"
+---
+
+# Release Publish (Compatibility) Workflow
+
+## Goal
+
+Provide a stable `wfi://release/publish` entrypoint for skills and assign catalog steps.
+**Default behavior is non-publishing:** follow local release preparation until the project
+supplies an explicit publication contract.
+
+## Prep vs publication
+
+| State | Behavior |
+|-------|----------|
+| **Default (this baseline)** | Equivalent to local preparation — version/changelog/verify/commit only |
+| **Project publication contract present** | Project overlay replaces this file and may perform registry/deploy steps |
+
+Never invent registry credentials, deploy targets, or publish commands from this baseline.
+
+## Prerequisites
+
+Same as local release preparation: identifiable release targets, version/changelog surfaces,
+and verification tooling when available.
+
+## Project Context Loading
+
+- Load `wfi://release/local` via `ace-bundle wfi://release/local` and treat that workflow as
+  the executable contract for this compatibility entrypoint.
+- Also load project context (`ace-bundle project`) when the local workflow requires it.
+
+## Process Steps
+
+### 1. Prefer local preparation
+
+1. Run `ace-bundle wfi://release/local`.
+2. Read and execute that workflow end-to-end with the same arguments passed to this skill/step.
+3. Stop after local preparation succeeds.
+
+### 2. Publication gate (do not cross by default)
+
+Only continue into external publication when **all** of the following are true:
+
+- A project-local (or higher-priority) overlay for `wfi://release/publish` defines publish steps, **or**
+  the operator explicitly loaded a dedicated publication workflow (for example a customized
+  `wfi://release/rubygems-publish`).
+- Credentials/targets required by that contract are present.
+- The operator intent is clearly to publish (not merely prepare).
+
+If those are not met, report that publication is blocked pending a project publication contract.
+
+## Override
+
+To make `wfi://release/publish` actually publish:
+
+1. Add `.ace-handbook/workflow-instructions/release/publish.wf.md` (or another higher-priority
+   WFI source) with explicit registry/deploy steps, credentials checks, and verification gates.
+2. Keep the URI stable so assign catalog steps (`release`, `release-minor`) keep resolving.
+3. Optionally specialize sibling URIs (`rubygems-publish`, deploy workflows) instead of
+   overloading this compatibility entrypoint.
+
+## Success Criteria
+
+- [ ] Local release preparation completed via the local workflow contract
+- [ ] No external publish/deploy performed unless a project publication contract authorized it
+- [ ] If publication was requested without a contract, failure is explicit and actionable
+
+## Common Issues
+
+- Assign steps reference `wfi://release/publish` expecting prep — that is intentional for the
+  default baseline.
+- Silent publish is forbidden; missing contracts must fail clearly rather than no-op publish.

data/handbook/workflow-instructions/release/rubygems-publish.wf.md

@@ -0,0 +1,112 @@
+---
+name: release-rubygems-publish
+description: RubyGems publication guidance (blocked until project opts into a publish contract)
+allowed-tools: Bash, Read
+argument-hint: "[gem-name...] [--dry-run]"
+doc-type: workflow
+purpose: specialized RubyGems publication baseline with non-mutating default
+update:
+  frequency: on-change
+  last-updated: "2026-08-12"
+---
+
+# RubyGems Publish Workflow (Baseline)
+
+## Goal
+
+Describe a safe RubyGems publication path for projects that ship gems. **This baseline does
+not push gems by default.** It inventories readiness and stops until the project opts into an
+explicit publication contract (project overlay or confirmed operator publish intent with
+credentials and dry-run evidence).
+
+## Prep vs publication
+
+| Phase | Allowed in this baseline by default |
+|-------|-------------------------------------|
+| Inventory gemspecs, versions, dependency order | Yes |
+| Credential presence check (non-secret) | Yes |
+| `gem build` / dry-run planning | Yes when explicitly requested |
+| `gem push` / registry mutation | **No** until publication contract + explicit publish path |
+
+## Prerequisites
+
+- One or more `*.gemspec` files (or a documented gem build surface)
+- Versions already bumped via local release preparation when releasing new versions
+- For real pushes later: RubyGems credentials (`~/.gem/credentials` or `GEM_HOST_API_KEY`)
+
+## Project Context Loading
+
+- `ace-bundle project`
+- Prefer completing `wfi://release/local` (or project release prep) before any publish attempt
+
+## Process Steps
+
+### 1. Discover gem targets
+
+```bash
+# Example discovery — adapt to the repository layout
+ls ./*.gemspec 2>/dev/null
+ls ./*/*.gemspec 2>/dev/null
+```
+
+If arguments name specific gems, filter to those and fail clearly when a name is missing.
+
+### 2. Build a publish plan (no push)
+
+For each gem:
+
+1. Read the local version from the gemspec / version file.
+2. Note runtime dependencies that are also local gems (publish dependencies first).
+3. Produce an ordered plan (topological order for internal gem deps).
+
+```text
+Publish plan (dry):
+1. <gem-a> <version>  (deps: ...)
+2. <gem-b> <version>  (deps: gem-a)
+```
+
+### 3. Credential check (non-mutating)
+
+```bash
+[ -f ~/.gem/credentials ] && echo "credentials file present" || echo "credentials file missing"
+echo "${GEM_HOST_API_KEY:+GEM_HOST_API_KEY is set}"
+```
+
+Do not print secret values.
+
+### 4. Publication gate
+
+**Stop here by default.** Report:
+
+- The ordered publish plan
+- Whether credentials appear present
+- That registry mutation requires a project overlay or an explicit operator-approved publish
+  contract that replaces/extends this baseline
+
+Only if a higher-priority project workflow authorizes pushes **and** the operator requested a
+real publish (not merely prep/dry-run) may `gem build` + `gem push` proceed under that
+project contract's steps and verification gates.
+
+Suggested placeholders for a project overlay (not executed by this baseline):
+
+```bash
+# gem build <gemspec>
+# gem push <built-gem>   # only under project publication contract
+```
+
+## Override
+
+Ship project-specific publish behavior at
+`.ace-handbook/workflow-instructions/release/rubygems-publish.wf.md` (or another higher-priority
+WFI source). Keep URI `wfi://release/rubygems-publish` stable for the distributed skill.
+
+## Success Criteria
+
+- [ ] Ordered publish plan produced for requested gems
+- [ ] Credential presence reported without leaking secrets
+- [ ] No `gem push` / registry mutation from this baseline alone
+
+## Common Issues
+
+- ACE monorepo operators may use a specialized overlay; plain projects must not depend on it.
+- Missing credentials should block publish contracts, not local planning.

data/handbook/workflow-instructions/release/update-changelog.wf.md

@@ -0,0 +1,93 @@
+---
+name: release-update-changelog
+description: Update CHANGELOG entries for recent changes (local only)
+allowed-tools: Bash, Read, Edit
+argument-hint: "[change-description]"
+doc-type: workflow
+purpose: generic changelog-update baseline
+update:
+  frequency: on-change
+  last-updated: "2026-08-12"
+---
+
+# Update Changelog Workflow
+
+## Goal
+
+Capture recent work in the project's changelog using the repository's established format
+(prefer [Keep a Changelog](https://keepachangelog.com/) when the file already follows it).
+This is **documentation/prep only** — it does not bump versions for publication or publish
+artifacts.
+
+## Prep vs publication
+
+- **In scope:** audit commits/diffs, classify entries, edit changelog file(s), commit docs.
+- **Out of scope:** cutting a GitHub Release, publishing packages, or deploying.
+
+## Prerequisites
+
+- A changelog file exists or the project agrees to create one (usually `CHANGELOG.md`)
+- Enough git history to attribute changes since the last recorded entry
+
+## Project Context Loading
+
+- `ace-bundle project` (or project equivalent)
+- Inspect `CHANGELOG.md` (root and/or package-level) and recent `git log`
+
+## Process Steps
+
+### 1. Locate changelog target
+
+Prefer the changelog the project already uses. Common layouts:
+
+- Single root `CHANGELOG.md`
+- Per-package changelogs in a monorepo
+- `## [Unreleased]` section that later becomes a versioned section at release time
+
+### 2. Audit changes since the last entry
+
+```bash
+git log --pretty=format:"%h %s" --no-merges
+# Narrow with paths or --since once the last changelog boundary is known
+git diff --stat <last-boundary>..HEAD
+```
+
+### 3. Classify entries
+
+Use Keep a Changelog categories when applicable:
+
+| Category | Use when |
+|----------|----------|
+| Added | Net-new capability |
+| Changed | Behavior change to existing capability |
+| Fixed | Bug/crash correction |
+| Removed | Capability removed |
+| Deprecated | Still present but discouraged |
+| Security | Vulnerability fixes |
+| Technical | Non-functional chore/docs/test/refactor (if the project uses this bucket) |
+
+### 4. Write entries
+
+- Append under `## [Unreleased]` when that section exists; otherwise follow project layout.
+- Keep bullets user-facing and scoped; mention package/module names in monorepos.
+- Incorporate any explicit change-description argument from the skill invocation.
+
+### 5. Commit locally
+
+Commit changelog-only edits when that matches project practice. Do not publish.
+
+## Override
+
+Project overlays under registered WFI sources replace this baseline while keeping
+`wfi://release/update-changelog` stable. Lower priority numbers win.
+
+## Success Criteria
+
+- [ ] Changelog reflects audited changes for the intended scope
+- [ ] Categories match project convention
+- [ ] No publish/deploy side effects
+
+## Common Issues
+
+- Missing `[Unreleased]` section — add it after the header when using Keep a Changelog.
+- Duplicate bullets — dedupe against existing Unreleased items before committing.

data/lib/ace/handbook/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Handbook
-    VERSION = '0.30.1'
+    VERSION = "0.31.0"
   end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-handbook
 version: !ruby/object:Gem::Version
-  version: 0.30.1
+  version: 0.31.0
 platform: ruby
 authors:
 - Michal Czyz
-autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-07-15 00:00:00.000000000 Z
+date: 2026-08-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-config
@@ -16,42 +15,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.9'
+        version: '0.17'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.9'
+        version: '0.17'
 - !ruby/object:Gem::Dependency
   name: ace-support-core
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.29'
+        version: '0.31'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.29'
+        version: '0.31'
 - !ruby/object:Gem::Dependency
   name: ace-support-nav
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.25'
+        version: '0.28'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.25'
+        version: '0.28'
 - !ruby/object:Gem::Dependency
   name: ace-support-cli
   requirement: !ruby/object:Gem::Requirement
@@ -198,6 +197,11 @@ files:
 - handbook/workflow-instructions/handbook/review-workflows.wf.md
 - handbook/workflow-instructions/handbook/synthesize-research.wf.md
 - handbook/workflow-instructions/handbook/update-docs.wf.md
+- handbook/workflow-instructions/release/bump-version.wf.md
+- handbook/workflow-instructions/release/local.wf.md
+- handbook/workflow-instructions/release/publish.wf.md
+- handbook/workflow-instructions/release/rubygems-publish.wf.md
+- handbook/workflow-instructions/release/update-changelog.wf.md
 - lib/ace/handbook.rb
 - lib/ace/handbook/atoms/provider_registry.rb
 - lib/ace/handbook/cli.rb
@@ -216,7 +220,6 @@ metadata:
   homepage_uri: https://github.com/cs3b/ace
   source_code_uri: https://github.com/cs3b/ace/tree/main/ace-handbook/
   changelog_uri: https://github.com/cs3b/ace/blob/main/ace-handbook/CHANGELOG.md
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -231,8 +234,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Standardized workflows for creating and managing guides, workflow instructions,
   and agent definitions.