@laitszkin/apollo-toolkit 2.11.4 → 2.12.1

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [v2.12.1] - 2026-03-28
+
+### Changed
+- Update `commit-and-push` so it must keep root `CHANGELOG.md` `Unreleased` aligned with the actual pending change set, preserving unrelated bullets while removing stale conflicting entries.
+- Update `version-release` so releases publish directly from curated root `CHANGELOG.md` `Unreleased` content instead of reconstructing release notes from `git diff`.
+
+## [v2.12.0] - 2026-03-28
+
+### Added
+- Add `agents` mode to install scripts for copying skills into `~/.agents/skills` directory, supporting agent-skill-compatible software.
+
+### Changed
+- Strengthen `production-sim-debug` so simulation investigations must verify protocol-sensitive blame against official docs or upstream source, distinguish liquidation pipeline stages precisely, and explain quote-budget counts as attempts versus unique opportunities.
+
 ## [v2.11.4] - 2026-03-27
 
 ### Added

package/commit-and-push/README.md

@@ -8,10 +8,11 @@ A Codex skill for commit-and-push workflows without release/version operations.
 
 1. Inspecting git status and staged state.
 2. Running `archive-specs` during submission to convert completed spec sets and archive them, or when existing project docs need normalization.
-3. Running `align-project-documents` and `maintain-project-constraints` before commit.
-4. Running additional dependency skills for code-affecting diffs when their coverage is needed.
-5. Committing with a concise Conventional Commit message.
-6. Pushing to the current branch.
+3. Keeping root `CHANGELOG.md` `Unreleased` aligned with the actual pending change set, including removing stale conflicting bullets when needed.
+4. Running `align-project-documents` and `maintain-project-constraints` before commit.
+5. Running additional dependency skills for code-affecting diffs when their coverage is needed.
+6. Committing with a concise Conventional Commit message.
+7. Pushing to the current branch.
 
 ## Scope
 
@@ -23,4 +24,6 @@ Use this skill when the user asks to commit/push/submit changes and does **not**
 
 If the repository contains a completed spec set, convert it into the categorized `archive-specs` project-doc structure during submission and archive the consumed plan files. Treat `spec.md`, `tasks.md`, and `checklist.md` semantically: unchecked task or decision checkboxes do not automatically mean the work is unfinished when the docs clearly show they were not selected, replaced, deferred, or marked `N/A`.
 
+Treat root `CHANGELOG.md` `Unreleased` as the source of pending release notes: add or refresh only the bullets that match the current change, keep unrelated pending bullets, and remove older conflicting bullets when the new implementation supersedes them.
+
 For release workflows, use `version-release`.

package/commit-and-push/SKILL.md

@@ -15,8 +15,8 @@ description: "Guide the agent to submit local changes with commit and push only
 ## Standards
 
 - Evidence: Inspect git state and classify the change set before deciding which quality gates apply.
-- Execution: Run the required quality-gate skills when applicable, convert completed spec sets into categorized project docs during submission, normalize non-standard project docs when needed, preserve staging intent, honor any explicit user-specified target branch, then commit and push without release steps; run dependent git mutations sequentially and verify the remote branch actually contains the new local `HEAD` before reporting success.
-- Quality: Re-run relevant validation for runtime changes, keep project docs plus agent constraints synchronized before committing, and preserve unrelated local work safely when branch switching or post-push local sync is required; treat `archive-specs` outputs as the canonical project-doc structure when normalization is required.
+- Execution: Run the required quality-gate skills when applicable, convert completed spec sets into categorized project docs during submission, normalize non-standard project docs when needed, keep `CHANGELOG.md` `Unreleased` aligned with the actual pending change set, preserve staging intent, honor any explicit user-specified target branch, then commit and push without release steps; run dependent git mutations sequentially and verify the remote branch actually contains the new local `HEAD` before reporting success.
+- Quality: Re-run relevant validation for runtime changes, keep project docs plus agent constraints synchronized before committing, preserve unrelated local work safely when branch switching or post-push local sync is required, and remove stale or conflicting `Unreleased` bullets when the current change supersedes them; treat `archive-specs` outputs as the canonical project-doc structure when normalization is required.
 - Output: Produce a concise Conventional Commit, push it to the intended branch, and report any temporary stash/restore or local branch sync that was required.
 
 ## Overview
@@ -63,14 +63,20 @@ Load only when needed:
 6. Run pre-commit sync dependencies
    - Execute `align-project-documents` after spec conversion and code/doc scans are complete.
    - Execute `maintain-project-constraints` immediately before the commit.
-7. Keep docs synchronized when needed
+7. Keep changelog synchronized before commit
+   - Treat root `CHANGELOG.md` `Unreleased` as the canonical pending release-notes source.
+   - Add or update only the bullets that correspond to the actual current change set.
+   - Preserve unaffected `Unreleased` bullets from other pending work.
+   - If an older `Unreleased` bullet conflicts with, duplicates, or is superseded by the current implementation, rewrite or remove the stale entry instead of leaving both versions behind.
+   - Keep section grouping consistent with the repository changelog format.
+8. Keep docs synchronized when needed
    - Apply the output from `archive-specs` when repository specs were converted or existing project docs were normalized into categorized project docs.
    - Apply the output from `align-project-documents` when behavior or usage changed.
    - Apply the output from `maintain-project-constraints` when agent workflow/rules changed.
-8. Commit
+9. Commit
    - Preserve user staging intent where possible.
    - Write a concise Conventional Commit message using `references/commit-messages.md`.
-9. Push
+10. Push
    - Push commit(s) to the intended branch.
    - Do not overlap `git commit`, `git push`, branch switching, or post-push sync operations; wait for each mutation to finish before starting the next one.
    - After pushing, verify the remote branch tip matches the local `HEAD`, for example by comparing `git rev-parse HEAD` with the target branch hash from `git rev-parse @{u}` or `git ls-remote --heads <remote> <branch>`.

package/commit-and-push/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Commit and Push"
   short_description: "Submit local changes with commit and push only"
-  default_prompt: "Use $commit-and-push to inspect the current git state, classify the diff, run required dependency skills ($align-project-documents and $maintain-project-constraints, plus $review-change-set, $discover-edge-cases, and $harden-app-security for code-affecting changes when their coverage is needed), then during submission run $archive-specs to convert any completed spec set into categorized project docs, archive the consumed plans, and normalize existing project docs when needed. Treat spec.md, tasks.md, and checklist.md semantically: unchecked task or decision checkboxes alone do not block conversion when the docs show they were not selected, replaced, deferred, or marked N/A. Then create a concise Conventional Commit and push to the current branch without any versioning or release steps."
+  default_prompt: "Use $commit-and-push to inspect the current git state, classify the diff, run required dependency skills ($align-project-documents and $maintain-project-constraints, plus $review-change-set, $discover-edge-cases, and $harden-app-security for code-affecting changes when their coverage is needed), then during submission run $archive-specs to convert any completed spec set into categorized project docs, archive the consumed plans, and normalize existing project docs when needed. Treat spec.md, tasks.md, and checklist.md semantically: unchecked task or decision checkboxes alone do not block conversion when the docs show they were not selected, replaced, deferred, or marked N/A. Keep root CHANGELOG.md Unreleased aligned with the actual pending change set by adding or updating the relevant bullets, preserving unrelated pending bullets, and removing stale conflicting entries when the current change supersedes them. Then create a concise Conventional Commit and push to the current branch without any versioning or release steps."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "2.11.4",
+  "version": "2.12.1",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",

package/production-sim-debug/SKILL.md

@@ -8,7 +8,7 @@ description: Investigate production or local simulation runs for runtime-toolcha
 ## Dependencies
 
 - Required: `systematic-debug` for evidence-first root-cause analysis when a simulation shows failing or missing expected behavior.
-- Conditional: `scheduled-runtime-health-check` when the user wants a bounded production/local simulation run executed and observed; `read-github-issue` when the requested simulation work is driven by a remote issue; `open-github-issue` when confirmed toolchain gaps should be published.
+- Conditional: `scheduled-runtime-health-check` when the user wants a bounded production/local simulation run executed and observed; `read-github-issue` when the requested simulation work is driven by a remote issue; `marginfi-development` when liquidation, health, receivership, or instruction-order conclusions depend on official marginfi docs/source; `jupiter-development` when swap, quote, routing, or rate-limit conclusions depend on official Jupiter docs; `open-github-issue` when confirmed toolchain gaps should be published.
 - Optional: none.
 - Fallback: If the relevant simulation entrypoint, preset, logs, or run artifacts cannot be found, stop and report the missing evidence instead of inferring behavior from stale docs or memory.
 
@@ -63,6 +63,13 @@ Use this skill to debug simulation workflows where the repository exposes a prod
 
 ### 4) Separate product failures from toolchain realism failures
 
+- When the suspected blocker touches protocol rules, instruction legality, quote semantics, or liquidation invariants, verify the claim against the relevant official docs or upstream source before assigning blame.
+- For every major blocker, explicitly classify the result as one of:
+  - production bot problem
+  - simulation environment problem
+  - both
+- Treat "both" as a first-class result when a bot bug and a local-harness realism gap are stacked in the same flow.
+
 - Classify each blocker into one of these buckets:
   - preset design mismatch
   - runtime scheduling or budget behavior
@@ -75,6 +82,31 @@ Use this skill to debug simulation workflows where the repository exposes a prod
 - If a local stub inflates or distorts profitability, preserve the runtime behavior and calibrate the stub.
 - If a scenario intentionally stresses one dimension, make sure the harness is not accidentally stressing unrelated dimensions.
 
+### 4.1) Map the observed failure to the real pipeline stage
+
+- Do not treat every `liquidation_event` row as evidence that the run reached verification or execution.
+- Reconstruct the stage explicitly, such as:
+  - candidate discovery
+  - local estimate
+  - solver candidate quote
+  - verification or pre-submit re-quote
+  - simulation
+  - execution
+- When logs or event rows expose `stage`, `bucket`, `reason`, or similar structured fields, use them to explain exactly where the attempt stopped.
+- When the user is confused by counts, distinguish:
+  - unique positions
+  - candidate attempts
+  - quote attempts
+  - verification attempts
+  - executed liquidations
+
+### 4.2) Audit quote-budget behavior before calling the strategy broken
+
+- Check whether a high quote count reflects many unique positions or repeated coarse/refinement exploration on the same few positions.
+- Trace how the runtime reserves verification capacity versus non-verification capacity, and explain which bucket was exhausted.
+- If the strategy relies on local oracle estimates before quoting, verify whether the admission threshold is merely "positive estimate" or something stricter before assuming those candidates were all strong.
+- When quote pressure appears unreasonable, tie the explanation back to the actual solver-step count, coarse/refinement selection logic, and the number of cross-mint candidates in the run.
+
 ### 5) Trace the full decision tree for missed liquidations or remediations
 
 - Follow the candidate from discovery through:
@@ -117,12 +149,17 @@ Use this skill to debug simulation workflows where the repository exposes a prod
 - **Overloaded “unknown” failures**: logs contain structured reasons, but the first-pass analysis never decomposes them.
 - **Continuous-mode self-sabotage**: a stress regime intended to stale pull oracles instead makes the runtime’s own primary feeds unusable.
 - **Quote budget starvation**: local filtering improves behavior but still lets low-value cross-mint candidates consume scarce quote capacity before higher-value paths can finish.
+- **Blame assigned too early**: the first visible error gets labeled as either bot or tooling before official docs, upstream source, and run artifacts confirm that attribution.
+- **Phase confusion**: event counts are interpreted as verification or execution attempts even though the run stopped much earlier in candidate quote or pre-submit simulation.
+- **Quote-count misread**: a large total quote count is mistaken for many distinct opportunities when the runtime actually spent repeated exploration quotes on a smaller set of positions.
 
 ## Output checklist
 
 - Name the exact scenario, preset, duration, and run directory.
 - State whether the root cause was product logic, toolchain realism, or both.
+- For protocol-sensitive issues, name the official docs or upstream source used to justify that attribution.
 - Cite the artifact types used: preset, logs, SQLite tables, and code paths.
+- Explain the failing stage in the liquidation pipeline and whether the key counts represent positions, attempts, quotes, or executed outcomes.
 - Summarize the narrow fix and the regression test or rerun evidence.
 - If the final scenario should be reused, state where the preset or docs were added.
 

package/scripts/install_skills.ps1

@@ -9,18 +9,20 @@ $ErrorActionPreference = "Stop"
 function Show-Usage {
   @"
 Usage:
-  ./scripts/install_skills.ps1 [codex|openclaw|trae|all]...
+  ./scripts/install_skills.ps1 [codex|openclaw|trae|agents|all]...
 
 Modes:
   codex     Copy skills into ~/.codex/skills
   openclaw  Copy skills into ~/.openclaw/workspace*/skills
   trae      Copy skills into ~/.trae/skills
+  agents    Copy skills into ~/.agents/skills (for agent-skill-compatible software)
   all       Install all supported targets
 
 Optional environment overrides:
   CODEX_SKILLS_DIR   Override codex skills destination path
   OPENCLAW_HOME      Override openclaw home path
   TRAE_SKILLS_DIR    Override trae skills destination path
+  AGENTS_SKILLS_DIR  Override agents skills destination path
   APOLLO_TOOLKIT_HOME Override local install path used when repo root is unavailable
   APOLLO_TOOLKIT_REPO_URL Override git repository URL used when repo root is unavailable
 "@
@@ -126,8 +128,9 @@ function Resolve-Modes {
     Write-Host "1) codex (~/.codex/skills)"
     Write-Host "2) openclaw (~/.openclaw/workspace*/skills)"
     Write-Host "3) trae (~/.trae/skills)"
-    Write-Host "4) all"
-    $inputValue = Read-Host "Enter choice(s) [1-4]"
+    Write-Host "4) agents (~/.agents/skills)"
+    Write-Host "5) all"
+    $inputValue = Read-Host "Enter choice(s) [1-5]"
 
     foreach ($rawChoice in ($inputValue -split ",")) {
       $choice = $rawChoice.Trim()
@@ -135,10 +138,12 @@ function Resolve-Modes {
         "1" { Add-ModeOnce -Selected $selected -Mode "codex" }
         "2" { Add-ModeOnce -Selected $selected -Mode "openclaw" }
         "3" { Add-ModeOnce -Selected $selected -Mode "trae" }
-        "4" {
+        "4" { Add-ModeOnce -Selected $selected -Mode "agents" }
+        "5" {
           Add-ModeOnce -Selected $selected -Mode "codex"
           Add-ModeOnce -Selected $selected -Mode "openclaw"
           Add-ModeOnce -Selected $selected -Mode "trae"
+          Add-ModeOnce -Selected $selected -Mode "agents"
         }
         default {
           throw "Invalid choice: $choice"
@@ -152,10 +157,12 @@ function Resolve-Modes {
         "codex" { Add-ModeOnce -Selected $selected -Mode "codex" }
         "openclaw" { Add-ModeOnce -Selected $selected -Mode "openclaw" }
         "trae" { Add-ModeOnce -Selected $selected -Mode "trae" }
+        "agents" { Add-ModeOnce -Selected $selected -Mode "agents" }
         "all" {
           Add-ModeOnce -Selected $selected -Mode "codex"
           Add-ModeOnce -Selected $selected -Mode "openclaw"
           Add-ModeOnce -Selected $selected -Mode "trae"
+          Add-ModeOnce -Selected $selected -Mode "agents"
         }
         default {
           Show-Usage
@@ -256,6 +263,22 @@ function Install-Trae {
   }
 }
 
+function Install-Agents {
+  param([string[]]$SkillPaths)
+
+  $target = if ($env:AGENTS_SKILLS_DIR) {
+    $env:AGENTS_SKILLS_DIR
+  }
+  else {
+    Join-Path $HOME ".agents/skills"
+  }
+
+  Write-Host "Installing to agents: $target"
+  foreach ($src in $SkillPaths) {
+    Copy-Skill -Source $src -TargetRoot $target
+  }
+}
+
 if ($Modes.Count -gt 0 -and ($Modes[0] -eq "-h" -or $Modes[0] -eq "--help")) {
   Show-Usage
   exit 0
@@ -269,6 +292,7 @@ foreach ($mode in $selectedModes) {
     "codex" { Install-Codex -SkillPaths $skillPaths }
     "openclaw" { Install-OpenClaw -SkillPaths $skillPaths }
     "trae" { Install-Trae -SkillPaths $skillPaths }
+    "agents" { Install-Agents -SkillPaths $skillPaths }
     default { throw "Unknown mode: $mode" }
   }
 }

package/scripts/install_skills.sh

@@ -4,18 +4,20 @@ set -euo pipefail
 usage() {
   cat <<"USAGE"
 Usage:
-  ./scripts/install_skills.sh [codex|openclaw|trae|all]...
+  ./scripts/install_skills.sh [codex|openclaw|trae|agents|all]...
 
 Modes:
   codex     Copy skills into ~/.codex/skills
   openclaw  Copy skills into ~/.openclaw/workspace*/skills
   trae      Copy skills into ~/.trae/skills
+  agents    Copy skills into ~/.agents/skills (for agent-skill-compatible software)
   all       Install all supported targets
 
 Optional environment overrides:
   CODEX_SKILLS_DIR   Override codex skills destination path
   OPENCLAW_HOME      Override openclaw home path
   TRAE_SKILLS_DIR    Override trae skills destination path
+  AGENTS_SKILLS_DIR  Override agents skills destination path
   APOLLO_TOOLKIT_HOME Override local install path used in curl/pipe mode
   APOLLO_TOOLKIT_REPO_URL Override git repository URL used in curl/pipe mode
 USAGE
@@ -135,6 +137,16 @@ install_trae() {
   done
 }
 
+install_agents() {
+  local agents_skills_dir
+  agents_skills_dir="${AGENTS_SKILLS_DIR:-$HOME/.agents/skills}"
+
+  echo "Installing to agents: $agents_skills_dir"
+  for src in "${SKILL_PATHS[@]}"; do
+    replace_with_copy "$src" "$agents_skills_dir"
+  done
+}
+
 add_mode_once() {
   local mode="$1"
   local existing
@@ -153,13 +165,14 @@ parse_mode() {
   local mode="$1"
 
   case "$mode" in
-    codex|openclaw|trae)
+    codex|openclaw|trae|agents)
       add_mode_once "$mode"
       ;;
     all)
       add_mode_once "codex"
       add_mode_once "openclaw"
       add_mode_once "trae"
+      add_mode_once "agents"
       ;;
     *)
       echo "Invalid mode: $mode" >&2
@@ -195,8 +208,9 @@ choose_modes_interactive() {
   echo "1) codex (~/.codex/skills)"
   echo "2) openclaw (~/.openclaw/workspace*/skills)"
   echo "3) trae (~/.trae/skills)"
-  echo "4) all"
-  choice="$(read_choice_from_user 'Enter choice(s) [1-4]: ')"
+  echo "4) agents (~/.agents/skills)"
+  echo "5) all"
+  choice="$(read_choice_from_user 'Enter choice(s) [1-5]: ')"
 
   IFS=',' read -r -a choices <<< "$choice"
   for raw_choice in "${choices[@]}"; do
@@ -205,7 +219,8 @@ choose_modes_interactive() {
       1) add_mode_once "codex" ;;
       2) add_mode_once "openclaw" ;;
       3) add_mode_once "trae" ;;
-      4) add_mode_once "codex"; add_mode_once "openclaw"; add_mode_once "trae" ;;
+      4) add_mode_once "agents" ;;
+      5) add_mode_once "codex"; add_mode_once "openclaw"; add_mode_once "trae"; add_mode_once "agents" ;;
       *)
         echo "Invalid choice: $raw_choice" >&2
         exit 1
@@ -249,6 +264,7 @@ main() {
       codex) install_codex ;;
       openclaw) install_openclaw ;;
       trae) install_trae ;;
+      agents) install_agents ;;
       *)
         usage
         exit 1

package/version-release/README.md

@@ -6,12 +6,12 @@ A Codex skill for explicit release workflows: code/documentation alignment, vers
 
 `version-release` helps agents perform release work in a repeatable flow:
 
-1. Inspect the release scope from git history.
+1. Inspect the current repository state and the curated `CHANGELOG.md` `Unreleased` content.
 2. Run quality gates for code-affecting changes when their coverage is needed.
 3. Run `archive-specs` before finalizing the release to convert completed spec sets and archive them, or when existing project docs need normalization.
 4. Align project code and categorized project docs.
 5. Resolve version and tag details.
-6. Update version files and changelog.
+6. Update version files and cut the release directly from `CHANGELOG.md` `Unreleased`.
 7. Commit release metadata.
 8. Create and push the release tag.
 9. Publish the matching GitHub release and verify any release-triggered automation.
@@ -27,4 +27,6 @@ Use this skill only when the user explicitly asks for:
 
 If the repository contains a completed spec set, convert it into the categorized `archive-specs` project-doc structure before finalizing the release and archive the consumed plan files. Treat `spec.md`, `tasks.md`, and `checklist.md` semantically: unchecked task or decision checkboxes do not automatically mean the work is unfinished when the docs clearly show they were not selected, replaced, deferred, or marked `N/A`.
 
+Do not rebuild release notes from `git diff`. Publish from the already curated root `CHANGELOG.md` `Unreleased` content by moving it into the target version entry and clearing `Unreleased` afterward.
+
 If the user only wants commit + push, use `commit-and-push`.

package/version-release/SKILL.md

@@ -14,9 +14,9 @@ description: "Guide the agent to prepare and publish a versioned release (versio
 
 ## Standards
 
-- Evidence: Inspect the active change set and the release range before touching version files, tags, or changelog entries.
-- Execution: Use this workflow only for explicit release intent, run the required quality gates when applicable, convert completed spec sets into categorized project docs before release finalization, normalize non-standard project docs when needed, then update versions, docs, commit, tag, push, and publish the GitHub release; run git mutations sequentially and verify both the branch tip and release tag exist remotely before publishing the GitHub release.
-- Quality: Never guess versions, align user-facing docs with actual code, convert completed planning docs into standardized categorized project docs before the release is published, and treat the `archive-specs` structure as the release-ready documentation format.
+- Evidence: Inspect the active change set, current version files, and root `CHANGELOG.md` `Unreleased` content before touching version files, tags, or release metadata.
+- Execution: Use this workflow only for explicit release intent, run the required quality gates when applicable, convert completed spec sets into categorized project docs before release finalization, normalize non-standard project docs when needed, then cut the release directly from `CHANGELOG.md` `Unreleased`, update versions and docs, commit, tag, push, and publish the GitHub release; run git mutations sequentially and verify both the branch tip and release tag exist remotely before publishing the GitHub release.
+- Quality: Never guess versions, align user-facing docs with actual code, convert completed planning docs into standardized categorized project docs before the release is published, treat the `archive-specs` structure as the release-ready documentation format, and do not reconstruct release notes from `git diff` when curated changelog content already exists.
 - Output: Produce a versioned release commit and tag, publish a matching GitHub release, and keep changelog plus relevant repository documentation synchronized.
 
 ## Overview
@@ -26,7 +26,7 @@ Run a standardized release workflow for versioned delivery:
 - resolve release scope
 - align project code and standardized categorized project documentation
 - bump version files
-- update changelog and relevant docs
+- cut the release from `CHANGELOG.md` `Unreleased` and update relevant docs
 - commit, tag, push, and publish the GitHub release
 
 ## References
@@ -57,44 +57,44 @@ Load only when needed:
    - For code-affecting changes, run `review-change-set`, `discover-edge-cases`, and `harden-app-security` for the same release scope when their coverage is needed.
    - Consolidate all confirmed findings before continuing.
    - Resolve all confirmed findings before changing version files, tags, or release metadata.
-4. Identify release range
-   - Find latest version tag with `git describe --tags --abbrev=0` (fallback to `git tag --list`).
-   - If no tags exist, use initial commit from `git rev-list --max-parents=0 HEAD`.
-   - Review `git log --oneline <range>` and `git diff --stat <range>`.
-5. Standardize project docs when specs or doc normalization is needed
+4. Standardize project docs when specs or doc normalization is needed
    - Before finalizing the release, execute `archive-specs` when `repo-specs-ready-for-conversion` is true or when `project-doc-structure-mismatch` is true.
    - Let `archive-specs` convert the relevant specs into categorized project docs such as `docs/README.md`, `docs/getting-started.md`, `docs/configuration.md`, `docs/architecture.md`, `docs/features.md`, and `docs/developer-guide.md`.
    - Let the skill normalize any existing project docs to the same structure and archive superseded source spec files.
    - Do not treat unchecked task or decision checkboxes alone as blocking unfinished work; read the surrounding notes and requirement status semantically.
    - If the docs still show unresolved implementation scope that is neither completed, intentionally deferred, nor explicitly `N/A`, do not convert them yet; report that the spec files remain active and should not be deleted.
-6. Align code and project docs
-   - Compare release range changes with user-facing docs and operational docs to ensure they match actual code behavior.
+5. Align code and project docs
+   - Compare the pending release intent plus current repository behavior with user-facing docs and operational docs to ensure they match actual code behavior.
    - Required alignment targets include project docs such as `README.md`, usage/setup docs, API docs, deployment/runbook docs, and release notes sources when present.
    - After `archive-specs` runs, treat the categorized outputs as the canonical project-doc structure.
    - If existing project docs are present but still use a mixed or non-standard layout, normalize them into the same categorized structure before version bumping or tagging.
    - If mismatches are found, update the relevant project docs before version bumping/tagging.
-7. Decide version and tag format
+6. Decide version and tag format
    - Read existing version files (for example `project.toml`, `package.json`, or repo-specific version files).
    - Infer existing tag format (`vX.Y.Z` or `X.Y.Z`) from repository tags.
    - If the user provides the target version, use it directly.
    - If it is missing, ask the user for the target version or semver bump type.
    - Provide recommendations only when explicitly requested.
-8. Update version files
+7. Update version files
    - Update every detected version file consistently.
    - Preserve file formatting; change only version values.
-9. Update release docs
-   - Update `CHANGELOG.md` with a new version entry using the selected release range.
+8. Update release docs
+   - Treat root `CHANGELOG.md` `Unreleased` as the canonical pending release content.
+   - If `Unreleased` is empty, stop and report that there are no curated release notes to publish yet.
+   - Create the new version entry by moving the current `Unreleased` sections under the selected version heading and release date.
+   - Reset `Unreleased` to an empty placeholder after the version entry is created.
+   - Remove duplicate section headers or bullets only when the move would otherwise create repeated content.
    - Update `README.md` only when behavior or usage changed.
    - Update `AGENTS.md` only when agent workflow/rules changed.
-10. Commit and tag
-   - Create a release-oriented commit message (for example `chore(release): bump version and update changelog`) when applicable.
+9. Commit and tag
+   - Create a release-oriented commit message (for example `chore(release): publish 2.12.1`) when applicable.
    - Create the version tag locally after commit.
-11. Push
+10. Push
    - Push commit(s) and the release tag to the current branch before publishing the GitHub release when the hosting platform requires the tag to exist remotely.
    - Do not overlap `git commit`, `git tag`, `git push`, or release-publish steps; wait for each mutation to finish before starting the next one.
    - After pushing, verify the remote branch tip matches local `HEAD`, and verify the release tag exists remotely via `git ls-remote --tags <remote> <tag>`.
    - If any git step finishes ambiguously or the remote hashes do not match local state, rerun the missing step sequentially and re-check before publishing the GitHub release.
-12. Publish the GitHub release
+11. Publish the GitHub release
    - Create a non-draft GitHub release that matches the pushed version tag.
    - Use the release notes from the new `CHANGELOG.md` entry unless the repository has a stronger established release-note source.
    - If the repository has publish automation triggered by `release.published`, ensure the GitHub release is actually published rather than left as a draft.

package/version-release/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Version Release"
   short_description: "Prepare a versioned release with bump, changelog, tag, GitHub release, and push"
-  default_prompt: "Use $version-release only for explicit release/version/tag requests: inspect the release scope, and for code-affecting changes run $review-change-set, $discover-edge-cases, and $harden-app-security when their coverage is needed. Before finalizing the release, run $archive-specs to convert any completed spec set into categorized project docs, archive the consumed plans, and normalize existing project docs when needed. Treat spec.md, tasks.md, and checklist.md semantically: unchecked task or decision checkboxes alone do not block conversion when the docs show they were not selected, replaced, deferred, or marked N/A. Then align user-facing docs with real behavior, update version files and CHANGELOG, create the release commit and tag, push commits and tags, then publish the matching GitHub release and confirm any triggered publish workflow."
+  default_prompt: "Use $version-release only for explicit release/version/tag requests: inspect the current repository state and root CHANGELOG.md Unreleased content, and for code-affecting changes run $review-change-set, $discover-edge-cases, and $harden-app-security when their coverage is needed. Before finalizing the release, run $archive-specs to convert any completed spec set into categorized project docs, archive the consumed plans, and normalize existing project docs when needed. Treat spec.md, tasks.md, and checklist.md semantically: unchecked task or decision checkboxes alone do not block conversion when the docs show they were not selected, replaced, deferred, or marked N/A. Then align user-facing docs with real behavior, update version files, cut the release directly from CHANGELOG.md Unreleased, create the release commit and tag, push commits and tags, then publish the matching GitHub release and confirm any triggered publish workflow."

package/version-release/references/changelog-writing.md

@@ -2,6 +2,10 @@
 
 Follow the existing changelog format. If none is defined, use Keep a Changelog style.
 
+- Treat `## [Unreleased]` as the canonical source for pending release notes.
+- During normal commit/push work, update only the `Unreleased` bullets that correspond to the current actual change set.
+- Preserve unrelated pending bullets from other unfinished work, and remove stale or conflicting bullets when the current implementation supersedes them.
+- During a version release, do not rebuild notes from `git diff`; move the curated `Unreleased` sections into the new version heading and then clear `Unreleased`.
 - Add a new version heading with the release date (YYYY-MM-DD).
 - Group entries under clear sections: Added, Changed, Fixed, Removed, Deprecated, Security.
 - Write user-facing bullets; avoid commit hashes or internal-only details.