@laitszkin/apollo-toolkit 2.12.1 → 2.12.3

package/AGENTS.md

@@ -31,6 +31,7 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can read, filter, and inspect remote GitHub issues before planning follow-up work.
 - Users can resolve a GitHub issue end-to-end and push the fix directly to a requested branch without opening a PR.
 - Users can run evidence-first application security audits focused on confirmed vulnerabilities.
+- Users can run a shared submission-readiness pass that synchronizes changelog, project docs, `AGENTS.md`, and completed plan archives before commit, push, PR creation, or release.
 - Users can learn new or improved skills from recent Codex conversation history.
 - Users can audit and maintain the skill catalog itself, including dependency classification and shared-skill extraction decisions.
 - Users can summarize mistakes into separate multiple-choice and long-answer error books backed by structured reference files and rendered PDFs.

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [v2.12.3] - 2026-03-30
+
+### Changed
+- Strengthen `commit-and-push`, `submission-readiness-check`, and `version-release` so submit flows must actually update root `CHANGELOG.md` `Unreleased` before continuing when the pending code-affecting or user-visible change is missing there.
+- Strengthen `commit-and-push` and `version-release` so `review-change-set` remains conditional, but becomes a blocking requirement whenever the change set includes code changes.
+- Strengthen `version-release` prompts and workflow docs to require reading the current version and existing tag/release state first, and to treat the release as incomplete until the matching commit, tag, and GitHub release all exist.
+- Clarify across submit and release workflows that every conditional gate becomes blocking as soon as its triggering scenario is present, including spec archival and other readiness work.
+- Clarify that `discover-edge-cases` and `harden-app-security` are important risk-driven code review gates that also become blocking whenever the change or release surface says they apply.
+
+## [v2.12.2] - 2026-03-29
+
+### Changed
+- Update the npm installer and local install scripts to expand `~/` path overrides consistently for managed toolkit homes and target skill directories.
+- Refresh skill docs and agent prompts to replace user-specific absolute home paths with portable `~/`-based examples.
+- Strengthen `production-sim-debug` and `scheduled-runtime-health-check` so bounded runs must verify the actual stop mechanism and treat overruns as contract/tooling bugs to diagnose.
+
 ## [v2.12.1] - 2026-03-28
 
 ### Changed

package/README.md

@@ -43,6 +43,7 @@ A curated skill catalog for Codex, OpenClaw, and Trae with a managed installer t
 - scheduled-runtime-health-check
 - shadow-api-model-research
 - solana-development
+- submission-readiness-check
 - systematic-debug
 - text-to-short-video
 - version-release

package/commit-and-push/README.md

@@ -7,12 +7,13 @@ A Codex skill for commit-and-push workflows without release/version operations.
 `commit-and-push` helps agents safely submit local changes by:
 
 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. 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.
+2. Running `review-change-set` as a blocking gate whenever the change set includes code changes.
+3. Running `archive-specs` during submission to convert completed spec sets and archive them, or when existing project docs need normalization.
+4. Keeping root `CHANGELOG.md` `Unreleased` aligned with the actual pending change set, including removing stale conflicting bullets when needed.
+5. Running `align-project-documents` and `maintain-project-constraints` before commit.
+6. Running additional dependency skills for code-affecting diffs when their coverage is needed.
+7. Committing with a concise Conventional Commit message.
+8. Pushing to the current branch.
 
 ## Scope
 
@@ -26,4 +27,10 @@ If the repository contains a completed spec set, convert it into the categorized
 
 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.
 
+When the diff includes code changes, `review-change-set` is still a conditional dependency, but that condition is considered met and becomes blocking for the submit flow.
+
+Apply the same rule to every other conditional gate: if its scenario is met during classification, it becomes blocking before commit rather than a best-effort follow-up.
+
+That includes risk-driven review gates such as `discover-edge-cases` and `harden-app-security` whenever the change surface makes them applicable.
+
 For release workflows, use `version-release`.

package/commit-and-push/SKILL.md

@@ -7,16 +7,16 @@ description: "Guide the agent to submit local changes with commit and push only
 
 ## Dependencies
 
-- Required: `align-project-documents` and `maintain-project-constraints` before the final commit.
-- Conditional: `review-change-set`, `discover-edge-cases`, and `harden-app-security` for code-affecting changes; `archive-specs` during submission when completed spec sets should be converted into project docs and archived, or when existing project docs need normalization into the standard categorized structure.
+- Required: `submission-readiness-check` before the final commit.
+- Conditional: `review-change-set` is required for code-affecting changes; `discover-edge-cases` and `harden-app-security` are important review gates that remain conditional, but become required whenever the reviewed scope or risk profile warrants them.
 - Optional: none.
-- Fallback: If any required dependency is unavailable, or if `archive-specs` is required for spec conversion but unavailable, stop and report the missing dependency.
+- Fallback: If any required dependency is unavailable, stop and report the missing dependency.
 
 ## 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, 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.
+- Evidence: Inspect git state and classify the change set before deciding which quality gates apply, then compare the actual pending diff against root `CHANGELOG.md` `Unreleased` before committing.
+- Execution: Run the required quality-gate skills when applicable, and treat every conditional gate whose scenario is met as blocking before submission; hand the repository to `submission-readiness-check` for changelog/docs/plan finalization, 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, preserve unrelated local work safely when branch switching or post-push local sync is required, and do not bypass blocking readiness findings such as missing/stale `Unreleased` bullets or unsynchronized project docs.
 - 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
@@ -43,6 +43,7 @@ Load only when needed:
    - `repo-specs-ready-for-conversion`: the relevant `spec.md`, `tasks.md`, and `checklist.md` have been updated to reflect the actual outcome of the work, and any unchecked task/decision checkbox that is clearly not selected, replaced, deferred, or `N/A` (for example, E2E intentionally not created) does not by itself mean the spec set is unfinished.
    - `project-doc-structure-mismatch`: existing `README.md` and project docs do not match the categorized structure required by `archive-specs`.
    - Treat a spec set as still active when it documents remaining implementation gaps, follow-up integration work, undecided design work, or deferred tasks that still belong to the same in-flight change.
+   - Any conditional gate whose trigger is confirmed by this classification becomes mandatory before commit, including review, spec archival, docs synchronization, and changelog updates.
 3. Resolve branch target before mutating history
    - Treat an explicit user-specified destination such as `main`, `origin/main`, or another named branch as authoritative over the current branch.
    - If the current branch does not match the requested destination, inspect `git status --short` for unrelated local changes before switching branches.
@@ -50,33 +51,20 @@ Load only when needed:
    - If the fix was committed on the wrong branch, move it to the requested branch with safe history-preserving operations such as `cherry-pick`, `merge --ff-only`, or a clean replay; do not force-push unless the user explicitly asks for it.
    - If the user asks to sync the local target branch after pushing, fast-forward or pull that branch locally and then restore any preserved worktree changes.
 4. Run code-affecting dependency skills (when applicable)
-   - Run `review-change-set`, `discover-edge-cases`, and `harden-app-security` for the same code-affecting scope when their coverage is needed.
+   - Run `review-change-set` for every code-affecting change before continuing; treat unresolved review findings as blocking.
+   - Run `discover-edge-cases` and `harden-app-security` for the same code-affecting scope when the reviewed risk profile or repository context says their coverage is needed; treat them as blocking review gates, not optional polish, whenever that condition is met.
    - Consolidate and resolve all confirmed findings before continuing.
    - Re-run relevant tests when runtime logic changes.
-5. Standardize project docs when specs or doc normalization is needed
-   - During submission, 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.
-   - If the current change intentionally ships a partial phase while the same plan set still tracks remaining work, keep that plan set live and skip archival for that scope.
-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 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.
-9. Commit
+5. Run shared submission readiness
+   - Execute `$submission-readiness-check` after code/doc scans are complete and before the final commit.
+   - Let it decide whether completed plan sets should be converted, whether project docs or `AGENTS.md` need synchronization, and whether `CHANGELOG.md` is blocking submission.
+   - Do not continue to commit while `submission-readiness-check` reports unresolved readiness blockers.
+   - Treat root `CHANGELOG.md` `Unreleased` coverage as mandatory for code-affecting or user-visible changes: if the current work is not reflected there yet, update it before committing instead of merely noting the gap.
+   - Re-open the final `CHANGELOG.md` diff after readiness updates and confirm the `Unreleased` bullets describe the same scope as the commit you are about to create.
+6. Commit
    - Preserve user staging intent where possible.
    - Write a concise Conventional Commit message using `references/commit-messages.md`.
-10. Push
+7. 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>`.
@@ -86,6 +74,10 @@ Load only when needed:
 ## Notes
 
 - Never run version bump, tag creation, or changelog release steps in this skill.
+- Treat every scenario-matched gate as blocking before commit, not as an optional reminder to maybe do later.
+- Never skip `review-change-set` for code-affecting changes, and do not continue past review while confirmed findings remain unresolved.
+- Never downgrade `discover-edge-cases` or `harden-app-security` to optional follow-up when the change risk says they apply.
+- Never claim the repository is ready to commit while root `CHANGELOG.md` `Unreleased` is missing the current change or still describes superseded work.
 - If release/version/tag work is requested, use `version-release` instead.
 - If a new branch is required, follow `references/branch-naming.md`.
 - A pushed implementation can still leave an active spec set behind; commit completion and spec archival are separate decisions.

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. 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."
+  default_prompt: "Use $commit-and-push to inspect the current git state and classify the diff. Treat every conditional gate whose scenario is met as blocking before any commit: if the change set includes code changes, run $review-change-set; if the reviewed risk profile says edge-case or security review is needed, run $discover-edge-cases and $harden-app-security as blocking gates too; if completed specs should be converted or docs need normalization, ensure $archive-specs runs through $submission-readiness-check; if changelog synchronization is needed, complete it before continuing. Then run any additional required code-quality skills, hand the repository to $submission-readiness-check so it can synchronize completed plan archives, project docs, AGENTS.md, and CHANGELOG.md before any commit, confirm root CHANGELOG.md Unreleased reflects the actual pending change set, preserve user staging intent, create a concise Conventional Commit, and push to the intended branch without any versioning or release steps."

package/lib/installer.js

@@ -11,9 +11,25 @@ function resolveHomeDirectory(env = process.env) {
   return env.HOME || env.USERPROFILE || os.homedir();
 }
 
+function expandUserPath(inputPath, env = process.env) {
+  if (!inputPath) {
+    return inputPath;
+  }
+
+  if (inputPath === '~') {
+    return resolveHomeDirectory(env);
+  }
+
+  if (inputPath.startsWith('~/') || inputPath.startsWith('~\\')) {
+    return path.join(resolveHomeDirectory(env), inputPath.slice(2));
+  }
+
+  return inputPath;
+}
+
 function resolveToolkitHome(env = process.env) {
   if (env.APOLLO_TOOLKIT_HOME) {
-    return path.resolve(env.APOLLO_TOOLKIT_HOME);
+    return path.resolve(expandUserPath(env.APOLLO_TOOLKIT_HOME, env));
   }
 
   return path.join(resolveHomeDirectory(env), '.apollo-toolkit');
@@ -142,7 +158,9 @@ async function getTargetRoots(modes, env = process.env) {
       targets.push({
         mode,
         label: 'Codex',
-        root: env.CODEX_SKILLS_DIR || path.join(homeDir, '.codex', 'skills'),
+        root: env.CODEX_SKILLS_DIR
+          ? path.resolve(expandUserPath(env.CODEX_SKILLS_DIR, env))
+          : path.join(homeDir, '.codex', 'skills'),
       });
       continue;
     }
@@ -151,13 +169,17 @@ async function getTargetRoots(modes, env = process.env) {
       targets.push({
         mode,
         label: 'Trae',
-        root: env.TRAE_SKILLS_DIR || path.join(homeDir, '.trae', 'skills'),
+        root: env.TRAE_SKILLS_DIR
+          ? path.resolve(expandUserPath(env.TRAE_SKILLS_DIR, env))
+          : path.join(homeDir, '.trae', 'skills'),
       });
       continue;
     }
 
     if (mode === 'openclaw') {
-      const openclawHome = env.OPENCLAW_HOME || path.join(homeDir, '.openclaw');
+      const openclawHome = env.OPENCLAW_HOME
+        ? path.resolve(expandUserPath(env.OPENCLAW_HOME, env))
+        : path.join(homeDir, '.openclaw');
       const entries = await fsp.readdir(openclawHome, { withFileTypes: true }).catch(() => []);
       const workspaceNames = entries
         .filter((entry) => entry.isDirectory() && entry.name.startsWith('workspace'))
@@ -218,6 +240,7 @@ async function installLinks({ toolkitHome, modes, env = process.env, previousSki
 }
 
 module.exports = {
+  expandUserPath,
   VALID_MODES,
   getTargetRoots,
   installLinks,

package/novel-to-short-video/SKILL.md

@@ -120,9 +120,9 @@ If producing multiple short videos in one request, enforce the same 50-60 second
 - Generate images with:
 
 ```bash
-python /Users/tszkinlai/.codex/skills/openai-text-to-image-storyboard/scripts/generate_storyboard_images.py \
+python ~/.codex/skills/openai-text-to-image-storyboard/scripts/generate_storyboard_images.py \
   --project-dir "<project_dir>" \
-  --env-file /Users/tszkinlai/.codex/skills/openai-text-to-image-storyboard/.env \
+  --env-file ~/.codex/skills/openai-text-to-image-storyboard/.env \
   --content-name "<content_name>" \
   --prompts-file "<project_dir>/pictures/<content_name>/prompts.json"
 ```
@@ -133,7 +133,7 @@ python /Users/tszkinlai/.codex/skills/openai-text-to-image-storyboard/scripts/ge
 - Generate audio + timeline + SRT:
 
 ```bash
-python /Users/tszkinlai/.codex/skills/docs-to-voice/scripts/docs_to_voice.py \
+python ~/.codex/skills/docs-to-voice/scripts/docs_to_voice.py \
   --project-dir "<project_dir>" \
   --project-name "<content_name>" \
   --text "<loop_narration_script>"

package/open-github-issue/SKILL.md

@@ -38,6 +38,7 @@ It is designed to be reusable by other skills that already know the issue title
 - Preserve upstream evidence content; only localize section headers and default fallback text.
 - Make the issue type explicit: `problem`, `feature`, `performance`, `security`, `docs`, or `observability`.
 - For `problem` issues, describe the expected behavior and current behavior with BDD-style `Given / When / Then`, then state the behavioral difference explicitly.
+- Prefer `python3` plus an absolute helper path when invoking bundled scripts; do not assume `python`, relative paths, or the caller's cwd are wired correctly.
 
 ## Workflow
 
@@ -95,10 +96,16 @@ It is designed to be reusable by other skills that already know the issue title
 
 Use the bundled script.
 
+First resolve:
+
+```bash
+SKILL_ROOT=~/.codex/skills/open-github-issue
+```
+
 Problem issue:
 
 ```bash
-python scripts/open_github_issue.py \
+python3 "$SKILL_ROOT/scripts/open_github_issue.py" \
   --issue-type problem \
   --title "[Log] <short symptom>" \
   --problem-description $'Expected Behavior (BDD)\nGiven ...\nWhen ...\nThen ...\n\nCurrent Behavior (BDD)\nGiven ...\nWhen ...\nThen ...\n\nBehavior Gap\n- Expected: ...\n- Actual: ...\n- Difference/Impact: ...\n\nEvidence\n- symptom: ...\n- impact: ...\n- key evidence: ...' \
@@ -110,7 +117,7 @@ python scripts/open_github_issue.py \
 Feature proposal issue:
 
 ```bash
-python scripts/open_github_issue.py \
+python3 "$SKILL_ROOT/scripts/open_github_issue.py" \
   --issue-type feature \
   --title "[Feature] <short proposal>" \
   --proposal "<what should be added or changed>" \
@@ -122,7 +129,7 @@ python scripts/open_github_issue.py \
 Performance issue:
 
 ```bash
-python scripts/open_github_issue.py \
+python3 "$SKILL_ROOT/scripts/open_github_issue.py" \
   --issue-type performance \
   --title "[Performance] Slow dashboard query under large tenants" \
   --problem-description "Dashboard loading time degrades sharply once tenant data exceeds current pagination assumptions." \
@@ -135,7 +142,7 @@ python scripts/open_github_issue.py \
 Security issue:
 
 ```bash
-python scripts/open_github_issue.py \
+python3 "$SKILL_ROOT/scripts/open_github_issue.py" \
   --issue-type security \
   --title "[Security] Missing authorization check on admin export" \
   --problem-description "The admin export endpoint can be reached without verifying the caller's admin role." \
@@ -150,7 +157,7 @@ python scripts/open_github_issue.py \
 Docs issue:
 
 ```bash
-python scripts/open_github_issue.py \
+python3 "$SKILL_ROOT/scripts/open_github_issue.py" \
   --issue-type docs \
   --title "[Docs] Deployment guide omits required Redis configuration" \
   --problem-description "The deployment guide does not mention the required Redis URL and worker startup order." \
@@ -162,7 +169,7 @@ python scripts/open_github_issue.py \
 Observability issue:
 
 ```bash
-python scripts/open_github_issue.py \
+python3 "$SKILL_ROOT/scripts/open_github_issue.py" \
   --issue-type observability \
   --title "[Observability] Missing request identifiers in payment retry logs" \
   --problem-description "Retry logs do not include stable request or trace identifiers, so multi-line failures cannot be correlated quickly." \
@@ -199,3 +206,4 @@ When another skill depends on `open-github-issue`:
 ## Resources
 
 - `scripts/open_github_issue.py`: Deterministic issue publishing helper with auth fallback and README language detection.
+- If the helper path is unavailable or still fails for environment reasons, fall back to direct `gh issue create` or GitHub REST API publishing instead of retrying the same broken relative-path invocation.

package/openai-text-to-image-storyboard/README.md

@@ -50,14 +50,14 @@ OPENAI_IMAGE_MODEL=gpt-image-1
 > Both `OPENAI_IMAGE_RATIO` and `OPENAI_IMAGE_ASPECT_RATIO` are supported; `OPENAI_IMAGE_RATIO` is preferred.  
 > If a ratio is provided, the script performs center-crop post-processing to match it.  
 > If provider ignores `aspect_ratio`, use `OPENAI_IMAGE_SIZE` (for example `1024x768`).  
-> By default, the script reads `/Users/tszkinlai/.codex/skills/openai-text-to-image-storyboard/.env`.
+> By default, the script reads `~/.codex/skills/openai-text-to-image-storyboard/.env`.
 
 3. Run with JSON prompt file
 
 ```bash
 python scripts/generate_storyboard_images.py \
   --project-dir /path/to/project \
-  --env-file /Users/tszkinlai/.codex/skills/openai-text-to-image-storyboard/.env \
+  --env-file ~/.codex/skills/openai-text-to-image-storyboard/.env \
   --content-name "1_chapter_title" \
   --prompts-file /path/to/prompts.json
 ```

package/openai-text-to-image-storyboard/SKILL.md

@@ -44,7 +44,7 @@ Always save outputs in `pictures/<content_name>/` (example: `pictures/1_chapter_
 
 Create `.env` in this skill folder (default path used by script):
 
-- `/Users/tszkinlai/.codex/skills/openai-text-to-image-storyboard/.env`
+- `~/.codex/skills/openai-text-to-image-storyboard/.env`
 
 You can still override via `--env-file` when needed.
 All CLI parameters take priority over environment variables.
@@ -59,16 +59,16 @@ All CLI parameters take priority over environment variables.
 - `OPENAI_IMAGE_STYLE` (optional)
 
 A template is provided at:
-- `/Users/tszkinlai/.codex/skills/openai-text-to-image-storyboard/.env.example`
+- `~/.codex/skills/openai-text-to-image-storyboard/.env.example`
 
 ## Command
 
 Use JSON prompt file:
 
 ```bash
-python /Users/tszkinlai/.codex/skills/openai-text-to-image-storyboard/scripts/generate_storyboard_images.py \
+python ~/.codex/skills/openai-text-to-image-storyboard/scripts/generate_storyboard_images.py \
   --project-dir /path/to/project \
-  --env-file /Users/tszkinlai/.codex/skills/openai-text-to-image-storyboard/.env \
+  --env-file ~/.codex/skills/openai-text-to-image-storyboard/.env \
   --content-name "1_chapter_title" \
   --prompts-file /path/to/prompts.json
 ```

package/openai-text-to-image-storyboard/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "OpenAI Text to Image Storyboard"
   short_description: "Generate image sets from agent-decided prompts"
-  default_prompt: "Use $openai-text-to-image-storyboard to decide scene prompts from text and generate images into pictures/{content_name}/ as soon as content is available. Always provide prompts through a JSON prompts file and run image generation directly when required inputs are present. Load API settings from /Users/tszkinlai/.codex/skills/openai-text-to-image-storyboard/.env by default."
+  default_prompt: "Use $openai-text-to-image-storyboard to decide scene prompts from text and generate images into pictures/{content_name}/ as soon as content is available. Always provide prompts through a JSON prompts file and run image generation directly when required inputs are present. Load API settings from ~/.codex/skills/openai-text-to-image-storyboard/.env by default."

package/package.json

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

package/production-sim-debug/SKILL.md

@@ -15,7 +15,7 @@ description: Investigate production or local simulation runs for runtime-toolcha
 ## Standards
 
 - Evidence: Base conclusions on the actual preset, runtime command, logs, SQLite event store, local stub responses, and the code paths that generated them.
-- Execution: Reproduce with the exact scenario first, separate product logic failures from simulation-toolchain failures, make the smallest realistic toolchain fix, and rerun the same bounded scenario to validate.
+- Execution: Reproduce with the exact scenario first, verify the bounded-run contract against the actual script/env implementation before launch, separate product logic failures from simulation-toolchain failures, make the smallest realistic toolchain fix, and rerun the same bounded scenario to validate.
 - Quality: Prefer harness or stub fixes that improve realism over one-off scenario hacks, avoid duplicating existing workflow skills, and record reusable presets when a scenario becomes part of the regular test suite.
 - Output: Return the scenario contract, observed outcomes, root-cause chain, fixes applied, validation evidence, and any remaining realism gaps.
 
@@ -41,6 +41,8 @@ Use this skill to debug simulation workflows where the repository exposes a prod
 
 - Use the same production/local simulation script the repository already treats as canonical.
 - Prefer a bounded run window with a stable run name and output directory.
+- Before launch, read the script or wrapper that enforces the run duration and confirm the real control surface, such as the exact env var name, CLI flag, shutdown helper, and artifact path conventions.
+- Do not assume a generic `RUNTIME_SECS`-style variable is wired correctly; verify the actual variable names and stop path from code or scripts first.
 - Save and inspect the exact artifacts produced by that run:
   - main runtime log
   - actor or stub logs
@@ -48,6 +50,7 @@ Use this skill to debug simulation workflows where the repository exposes a prod
   - SQLite or other persistence outputs
   - scenario manifest or preset-resolved settings
 - Do not trust older run directories when the user asks about a new execution.
+- If the run exceeds the agreed bounded window, stop it promptly, preserve the partial artifacts, and treat the overrun itself as a toolchain bug or contract mismatch to diagnose.
 
 ### 3) Audit the artifact chain before diagnosing product logic
 
@@ -143,6 +146,7 @@ Use this skill to debug simulation workflows where the repository exposes a prod
 
 ## Common failure patterns
 
+- **Bounded-run contract drift**: the analyst assumes the wrong duration env var, CLI flag, or shutdown path, so the run exceeds the promised window and the captured evidence no longer matches the requested contract.
 - **Wrong artifact source**: the analyst inspects an older SQLite file or the wrong event database and concludes that runtime behavior is missing.
 - **Preset says one thing, harness does another**: scenario names sound right, but the actual matrix or oracle mode does not match the user’s intent.
 - **Stub realism drift**: local quote, swap, or oracle stubs distort pricing, accounts, or program IDs enough to create false failures or false profits.

package/scheduled-runtime-health-check/SKILL.md

@@ -15,7 +15,7 @@ description: Use a background terminal to run a user-specified command immediate
 ## Standards
 
 - Evidence: Anchor every conclusion to the requested command, execution window, startup/shutdown timestamps, captured logs, and concrete runtime signals.
-- Execution: Collect the run contract, use a background terminal, optionally update the code only when the user asks, execute the requested command immediately or in the requested window, capture logs, stop cleanly when bounded, then delegate log review to `analyse-app-logs` only when findings are requested or needed.
+- Execution: Collect the run contract, verify the real stop mechanism before launch, use a background terminal, optionally update the code only when the user asks, execute the requested command immediately or in the requested window, capture logs, stop cleanly when bounded, then delegate log review to `analyse-app-logs` only when findings are requested or needed.
 - Quality: Keep scheduling, execution, and shutdown deterministic; separate confirmed findings from hypotheses; and mark each assessed module healthy/degraded/failed/unknown with reasons.
 - Output: Return the run configuration, execution status, log locations, optional code-update result, optional module health by area, confirmed issues, potential issues, observability gaps, and scheduler status when applicable.
 
@@ -61,6 +61,7 @@ This skill is an orchestration layer. It owns the background terminal session, o
    - Use a dedicated background terminal session for the whole workflow.
    - Create a dedicated run folder and record timezone, cwd, requested command, terminal session identifier, and any requested start/end boundaries.
    - Capture stdout and stderr from the beginning of the session so the full run stays auditable.
+   - Identify and record the exact bounded-stop mechanism before launch: signal path, wrapper script, env var names, CLI flags, PID capture, and any project-specific shutdown helper.
 3. Optionally update to the latest safe code state
    - Only do this step when the user explicitly asked to update the project before execution.
    - Prefer the repository's normal safe update path, such as `git pull --ff-only`, or the project's documented sync command if one exists.
@@ -76,8 +77,10 @@ This skill is an orchestration layer. It owns the background terminal session, o
    - If readiness never arrives, stop the run, preserve logs, and treat it as a failed startup window.
 6. Observe and stop when bounded
    - If a bounded window or explicit stop time was requested, keep the process running only for that agreed window and then stop it cleanly.
+   - Do not rely only on the child command to self-terminate on time; track the wall-clock deadline yourself and enforce the stop sequence when the deadline is reached.
    - Track crashes, restarts, retry storms, timeout bursts, stuck jobs, resource pressure, and repeated warnings during the run.
    - Use the project's normal shutdown path first; if graceful stop fails, escalate deterministically and record the exact stop sequence and timestamps.
+   - If the process overruns the agreed window, stop it immediately, mark the run as an overrun, and report whether the cause was a bad wrapper contract, a missing stop hook, or a failed shutdown.
 7. Explain findings from logs when requested
    - If the user asked for findings after completion, wait for the run to finish before analyzing the captured logs.
    - Invoke `analyse-app-logs` on only the captured runtime window.
@@ -130,6 +133,7 @@ Use this structure in responses:
 ## Guardrails
 
 - Do not let the project continue running past the agreed window unless the user explicitly asks.
+- Do not assume the documented bound is real until the wrapper or script implementation confirms it.
 - Do not perform a code-update step unless the user explicitly asked for it.
 - Do not claim steady-state health from startup-only evidence.
 - Keep the run folder and scheduler metadata so the investigation can be reproduced.

package/scripts/install_skills.ps1

@@ -29,7 +29,27 @@ Optional environment overrides:
 }
 
 $ToolkitRepoUrl = if ($env:APOLLO_TOOLKIT_REPO_URL) { $env:APOLLO_TOOLKIT_REPO_URL } else { "https://github.com/LaiTszKin/apollo-toolkit.git" }
-$ToolkitHome = if ($env:APOLLO_TOOLKIT_HOME) { $env:APOLLO_TOOLKIT_HOME } else { Join-Path $HOME ".apollo-toolkit" }
+
+function Expand-UserPath {
+  param([string]$Path)
+
+  if ([string]::IsNullOrWhiteSpace($Path)) {
+    return $Path
+  }
+
+  if ($Path -eq "~") {
+    return $HOME
+  }
+
+  if ($Path.StartsWith("~/") -or $Path.StartsWith('~\')) {
+    $trimmed = $Path.Substring(2)
+    return Join-Path $HOME $trimmed
+  }
+
+  return $Path
+}
+
+$ToolkitHome = if ($env:APOLLO_TOOLKIT_HOME) { Expand-UserPath $env:APOLLO_TOOLKIT_HOME } else { Join-Path $HOME ".apollo-toolkit" }
 
 function Show-Banner {
   @"
@@ -207,7 +227,7 @@ function Install-Codex {
   param([string[]]$SkillPaths)
 
   $target = if ($env:CODEX_SKILLS_DIR) {
-    $env:CODEX_SKILLS_DIR
+    Expand-UserPath $env:CODEX_SKILLS_DIR
   }
   else {
     Join-Path $HOME ".codex/skills"
@@ -223,7 +243,7 @@ function Install-OpenClaw {
   param([string[]]$SkillPaths)
 
   $openclawHome = if ($env:OPENCLAW_HOME) {
-    $env:OPENCLAW_HOME
+    Expand-UserPath $env:OPENCLAW_HOME
   }
   else {
     Join-Path $HOME ".openclaw"
@@ -251,7 +271,7 @@ function Install-Trae {
   param([string[]]$SkillPaths)
 
   $target = if ($env:TRAE_SKILLS_DIR) {
-    $env:TRAE_SKILLS_DIR
+    Expand-UserPath $env:TRAE_SKILLS_DIR
   }
   else {
     Join-Path $HOME ".trae/skills"
@@ -267,7 +287,7 @@ function Install-Agents {
   param([string[]]$SkillPaths)
 
   $target = if ($env:AGENTS_SKILLS_DIR) {
-    $env:AGENTS_SKILLS_DIR
+    Expand-UserPath $env:AGENTS_SKILLS_DIR
   }
   else {
     Join-Path $HOME ".agents/skills"

package/scripts/install_skills.sh

@@ -25,7 +25,24 @@ USAGE
 
 SCRIPT_SOURCE="${BASH_SOURCE[0]-}"
 TOOLKIT_REPO_URL="${APOLLO_TOOLKIT_REPO_URL:-https://github.com/LaiTszKin/apollo-toolkit.git}"
-TOOLKIT_HOME="${APOLLO_TOOLKIT_HOME:-$HOME/.apollo-toolkit}"
+
+expand_user_path() {
+  local raw_path="${1-}"
+
+  case "$raw_path" in
+    "~")
+      printf '%s\n' "$HOME"
+      ;;
+    "~/"*)
+      printf '%s\n' "$HOME/${raw_path#~/}"
+      ;;
+    *)
+      printf '%s\n' "$raw_path"
+      ;;
+  esac
+}
+
+TOOLKIT_HOME="$(expand_user_path "${APOLLO_TOOLKIT_HOME:-$HOME/.apollo-toolkit}")"
 
 show_banner() {
   cat <<'BANNER'
@@ -94,7 +111,7 @@ replace_with_copy() {
 
 install_codex() {
   local codex_skills_dir
-  codex_skills_dir="${CODEX_SKILLS_DIR:-$HOME/.codex/skills}"
+  codex_skills_dir="$(expand_user_path "${CODEX_SKILLS_DIR:-$HOME/.codex/skills}")"
 
   echo "Installing to codex: $codex_skills_dir"
   for src in "${SKILL_PATHS[@]}"; do
@@ -106,7 +123,7 @@ install_openclaw() {
   local openclaw_home workspace skills_dir
   local -a workspaces
 
-  openclaw_home="${OPENCLAW_HOME:-$HOME/.openclaw}"
+  openclaw_home="$(expand_user_path "${OPENCLAW_HOME:-$HOME/.openclaw}")"
 
   workspaces=()
   while IFS= read -r workspace; do
@@ -129,7 +146,7 @@ install_openclaw() {
 
 install_trae() {
   local trae_skills_dir
-  trae_skills_dir="${TRAE_SKILLS_DIR:-$HOME/.trae/skills}"
+  trae_skills_dir="$(expand_user_path "${TRAE_SKILLS_DIR:-$HOME/.trae/skills}")"
 
   echo "Installing to trae: $trae_skills_dir"
   for src in "${SKILL_PATHS[@]}"; do
@@ -139,7 +156,7 @@ install_trae() {
 
 install_agents() {
   local agents_skills_dir
-  agents_skills_dir="${AGENTS_SKILLS_DIR:-$HOME/.agents/skills}"
+  agents_skills_dir="$(expand_user_path "${AGENTS_SKILLS_DIR:-$HOME/.agents/skills}")"
 
   echo "Installing to agents: $agents_skills_dir"
   for src in "${SKILL_PATHS[@]}"; do

package/submission-readiness-check/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: submission-readiness-check
+description: Prepare a repository for safe submission by synchronizing `CHANGELOG.md`, project docs, `AGENTS.md`, and completed planning artifacts before commit, push, PR creation, or release. Use when a workflow is about to submit changes and must avoid missing finalization steps such as stale `Unreleased` notes, unarchived completed spec sets, or unsynchronized agent constraints.
+---
+
+# Submission Readiness Check
+
+## Dependencies
+
+- Required: `align-project-documents` and `maintain-project-constraints` before any git submission step.
+- Conditional: `archive-specs` when completed `spec.md` / `tasks.md` / `checklist.md` sets should be converted into categorized project docs and archived, or when existing project docs need normalization into the standard structure.
+- Optional: none.
+- Fallback: If a required dependency is unavailable, or if spec conversion is required but `archive-specs` is unavailable, stop and report the missing dependency instead of submitting partially synchronized changes.
+
+## Standards
+
+- Evidence: Inspect the actual git diff, staged set, planning artifacts, `CHANGELOG.md`, and current project docs before declaring the repository ready to submit.
+- Execution: Decide whether the target flow is commit/push, PR, or release; normalize completed spec sets when appropriate; synchronize project docs plus `AGENTS.md`; then enforce changelog readiness before any commit, tag, push, PR creation, or release publishing step.
+- Quality: Treat missing or stale changelog entries as blocking issues for submit workflows, preserve unrelated pending `Unreleased` bullets, do not archive active plan sets that still track unfinished scope, and do not hand back a ready verdict until every conditional gate whose scenario is met has actually been completed.
+- Output: Return a ready-to-submit verdict with the synchronized files and any blocking items that must be fixed before the owning submit workflow continues.
+
+## Overview
+
+Use this skill as the shared finalization pass before repository submission workflows. It exists to prevent repeated omissions such as forgetting `CHANGELOG.md`, shipping stale project docs, or leaving completed plan sets unarchived.
+
+## Workflow
+
+### 1) Inventory the real submission surface
+
+- Read `git status -sb`, `git diff --stat`, and `git diff --cached --stat`.
+- Check whether the repository has root `CHANGELOG.md`, top-level `AGENTS.md`, and categorized project docs already in use.
+- Inventory planning artifacts across the repository, not only staged files, so completed plan sets are not missed.
+- Classify the intended downstream flow:
+  - `commit-push`
+  - `pull-request`
+  - `release`
+
+### 2) Decide whether planning artifacts should be converted
+
+- Treat live `spec.md`, `tasks.md`, and `checklist.md` sets semantically instead of mechanically.
+- Run `$archive-specs` when the relevant plan set reflects the delivered outcome, or when project docs still need normalization into the standard categorized structure.
+- Keep a plan set live when it still documents unfinished implementation, unresolved design work, or same-scope follow-up that is intentionally not shipping yet.
+- If the archive scenario is met, treat `$archive-specs` as blocking before returning a ready-to-submit verdict.
+
+### 3) Synchronize project docs and constraints
+
+- Run `$align-project-documents` after spec conversion or doc inspection is complete.
+- Run `$maintain-project-constraints` immediately before the owning submission workflow mutates git history.
+- Apply the resulting doc and `AGENTS.md` updates when behavior, operator workflow, or standing project rules changed.
+
+### 4) Enforce changelog readiness
+
+- Treat root `CHANGELOG.md` as the canonical user-facing submission summary when it exists.
+- For `commit-push` and `pull-request` flows:
+  - Keep `Unreleased` aligned with the actual pending change set.
+  - Add or update only the bullets that correspond to the current work.
+  - Preserve unrelated pending bullets from other unshipped work.
+  - Remove or rewrite stale bullets when the current implementation supersedes them.
+  - If `Unreleased` is missing the current code-affecting or user-visible change, edit `CHANGELOG.md` now instead of returning a warning for another workflow to maybe fix later.
+- For `release` flows:
+  - Require a non-empty `Unreleased` section before the release continues.
+  - Ensure the release workflow will cut notes directly from curated changelog content instead of reconstructing them from `git diff`.
+  - Confirm the `Unreleased` bullets are release-ready before handing control back: they must describe the exact release scope that will be versioned and tagged next.
+- If code-affecting or user-visible changes are about to ship and `CHANGELOG.md` does not reflect them, stop and fix the changelog before continuing.
+
+### 5) Hand back a submission verdict
+
+- Confirm which files were synchronized:
+  - project docs
+  - `AGENTS.md`
+  - `CHANGELOG.md`
+  - archived plan sets
+- If anything remains unsynchronized, report it as a blocking item rather than letting the submit workflow continue optimistically.
+
+## Notes
+
+- Do not create commits, tags, pushes, PRs, or releases inside this skill.
+- Treat scenario-matched conditional gates such as spec archival, docs synchronization, and changelog updates as blocking readiness work, not optional follow-up.
+- Use this skill as a shared preflight for submit workflows rather than duplicating the same finalization checklist in multiple skills.

package/submission-readiness-check/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Submission Readiness"
+  short_description: "Sync changelog and docs before submit"
+  default_prompt: "Use $submission-readiness-check to prepare repository docs, changelog, and plan archives before commit, push, or release."

package/text-to-short-video/README.md

@@ -32,8 +32,8 @@ No mandatory dependencies.
 1. Copy env template:
 
 ```bash
-cp /Users/tszkinlai/.codex/skills/text-to-short-video/.env.example \
-   /Users/tszkinlai/.codex/skills/text-to-short-video/.env
+cp ~/.codex/skills/text-to-short-video/.env.example \
+   ~/.codex/skills/text-to-short-video/.env
 ```
 
 2. Required values:
@@ -56,10 +56,10 @@ cp /Users/tszkinlai/.codex/skills/text-to-short-video/.env.example \
 If API-generated video ratio/size does not match the target, run:
 
 ```bash
-python /Users/tszkinlai/.codex/skills/text-to-short-video/scripts/enforce_video_aspect_ratio.py \
+python ~/.codex/skills/text-to-short-video/scripts/enforce_video_aspect_ratio.py \
   --input-video "<downloaded_video_path>" \
   --output-video "<final_output_video_path>" \
-  --env-file /Users/tszkinlai/.codex/skills/text-to-short-video/.env \
+  --env-file ~/.codex/skills/text-to-short-video/.env \
   --force
 ```
 

package/text-to-short-video/SKILL.md

@@ -82,11 +82,11 @@ Consistency rules:
 
 Use this template:
 
-- `/Users/tszkinlai/.codex/skills/text-to-short-video/.env.example`
+- `~/.codex/skills/text-to-short-video/.env.example`
 
 Copy to:
 
-- `/Users/tszkinlai/.codex/skills/text-to-short-video/.env`
+- `~/.codex/skills/text-to-short-video/.env`
 
 Required keys:
 
@@ -173,10 +173,10 @@ If provider returns multiple outputs, keep the best one that matches requested s
 When output ratio or resolution differs from target, run:
 
 ```bash
-python /Users/tszkinlai/.codex/skills/text-to-short-video/scripts/enforce_video_aspect_ratio.py \
+python ~/.codex/skills/text-to-short-video/scripts/enforce_video_aspect_ratio.py \
   --input-video "<downloaded_video_path>" \
   --output-video "<final_output_video_path>" \
-  --env-file /Users/tszkinlai/.codex/skills/text-to-short-video/.env \
+  --env-file ~/.codex/skills/text-to-short-video/.env \
   --force
 ```
 

package/text-to-short-video/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Text to Short Video"
   short_description: "Turn text into 30-60s short videos via API"
-  default_prompt: "Use $text-to-short-video to convert my text into one 30-60 second short video using an API-only workflow. Before building the final prompt, load <project_dir>/pictures/<content_name>/roles.json as the role source and keep role consistency: do not modify existing role id/name/appearance/outfit, only update role descriptions for clip-specific actions. Then call an OpenAI-compatible /videos/generations endpoint with settings from /Users/tszkinlai/.codex/skills/text-to-short-video/.env, poll until completion, download the MP4, and run post-process crop/resize only when output aspect ratio or size mismatches."
+  default_prompt: "Use $text-to-short-video to convert my text into one 30-60 second short video using an API-only workflow. Before building the final prompt, load <project_dir>/pictures/<content_name>/roles.json as the role source and keep role consistency: do not modify existing role id/name/appearance/outfit, only update role descriptions for clip-specific actions. Then call an OpenAI-compatible /videos/generations endpoint with settings from ~/.codex/skills/text-to-short-video/.env, poll until completion, download the MP4, and run post-process crop/resize only when output aspect ratio or size mismatches."

package/version-release/README.md

@@ -7,14 +7,15 @@ 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 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 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.
+2. Run `review-change-set` as a blocking gate whenever the release includes code changes.
+3. Run additional quality gates for code-affecting changes when their coverage is needed.
+4. Run `archive-specs` before finalizing the release to convert completed spec sets and archive them, or when existing project docs need normalization.
+5. Align project code and categorized project docs.
+6. Resolve version and tag details by reading the current version and existing tag/release state first.
+7. Update version files and cut the release directly from `CHANGELOG.md` `Unreleased`.
+8. Commit release metadata.
+9. Create and push the release tag.
+10. Publish the matching GitHub release and verify any release-triggered automation.
 
 ## Scope
 
@@ -29,4 +30,12 @@ If the repository contains a completed spec set, convert it into the categorized
 
 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.
 
+When the release includes code changes, `review-change-set` is still a conditional dependency, but that condition is considered met and becomes blocking before any version bump, tag, or release publication.
+
+Apply the same rule to every other conditional gate: if its scenario is met during release classification, it becomes blocking before version bumping, tagging, or release publication.
+
+That includes risk-driven review gates such as `discover-edge-cases` and `harden-app-security` whenever the release surface makes them applicable.
+
+Do not report release completion after only bumping versions or pushing a commit: the matching tag and GitHub release are part of done criteria unless the user explicitly says to skip publication.
+
 If the user only wants commit + push, use `commit-and-push`.

package/version-release/SKILL.md

@@ -7,16 +7,16 @@ description: "Guide the agent to prepare and publish a versioned release (versio
 
 ## Dependencies
 
-- Required: none.
-- Conditional: `review-change-set`, `discover-edge-cases`, and `harden-app-security` for code-affecting releases before metadata edits and the final commit; `archive-specs` before release finalization when completed spec sets should be converted into project docs and archived, or when existing project docs need normalization into the standard categorized structure.
+- Required: `submission-readiness-check` before version metadata edits, tagging, or release publication.
+- Conditional: `review-change-set` is required for code-affecting releases before metadata edits and the final commit; `discover-edge-cases` and `harden-app-security` are important review gates that remain conditional, but become required whenever the reviewed scope or risk profile warrants them.
 - Optional: none.
-- Fallback: If a required release dependency is unavailable for a code-affecting scope, or if `archive-specs` is required for spec conversion but unavailable, stop and report the missing dependency.
+- Fallback: If a required release dependency is unavailable, stop and report the missing dependency.
 
 ## Standards
 
-- 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.
+- Evidence: Inspect the active change set, current version files, existing tag format, existing remote tags/releases, 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, and treat every conditional gate whose scenario is met as blocking before versioning or publication; hand the repository to `submission-readiness-check` before versioning work, 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, do not bypass readiness blockers from `submission-readiness-check`, do not reconstruct release notes from `git diff` when curated changelog content already exists, and do not report release success until the commit, tag, and GitHub release all exist for the same version.
 - Output: Produce a versioned release commit and tag, publish a matching GitHub release, and keep changelog plus relevant repository documentation synchronized.
 
 ## Overview
@@ -54,31 +54,27 @@ Load only when needed:
    - `repo-specs-present`: the repository contains live project planning artifacts such as `spec.md`, `tasks.md`, `checklist.md`, or plan directories; exclude reference examples, templates, and archived samples.
    - `repo-specs-ready-for-conversion`: the relevant `spec.md`, `tasks.md`, and `checklist.md` reflect the actual delivered outcome, and any unchecked task/decision checkbox that is clearly not selected, replaced, deferred, or `N/A` (for example, E2E intentionally not created) does not by itself mean the spec set is unfinished.
    - `project-doc-structure-mismatch`: existing `README.md` and project docs do not match the categorized structure required by `archive-specs`.
-   - 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.
+   - For code-affecting changes, run `review-change-set` for the same release scope before continuing; treat unresolved review findings as blocking.
+   - Run `discover-edge-cases` and `harden-app-security` for the same release scope when the reviewed risk profile or repository context says their coverage is needed; treat them as blocking review gates, not optional polish, whenever that condition is met.
+   - Any conditional gate whose trigger is confirmed by this classification becomes mandatory before version bumping, tagging, or release publication, including review, spec archival, docs synchronization, and changelog readiness.
    - Consolidate all confirmed findings before continuing.
    - Resolve all confirmed findings before changing version files, tags, or release metadata.
-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.
-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.
-6. Decide version and tag format
+4. Run shared submission readiness
+   - Execute `$submission-readiness-check` before version file edits, tags, or release publication.
+   - Let it decide whether completed plan sets should be archived, whether project docs or `AGENTS.md` need synchronization, and whether `CHANGELOG.md` `Unreleased` is ready to be cut into a versioned release entry.
+   - Do not continue while `submission-readiness-check` reports unresolved blockers.
+5. 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.
+   - Inspect existing local and remote tags plus any existing GitHub Release for the target version before creating new release metadata, so duplicate or conflicting releases are caught early.
    - 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.
-7. Update version files
+   - Do not continue until you can state the current version, the intended next version, and the exact tag name that will be created.
+6. Update version files
    - Update every detected version file consistently.
    - Preserve file formatting; change only version values.
-8. Update release docs
+7. 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.
@@ -86,23 +82,29 @@ Load only when needed:
    - 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.
-9. Commit and tag
+8. 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.
-10. Push
+   - Re-read the version files after editing and before tagging to confirm they all match the intended release version.
+9. 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.
-11. Publish the GitHub release
+10. 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.
    - Prefer `gh release create <tag>` or the repository's existing release tool when available.
    - Confirm the GitHub release URL and any triggered publish workflow status in the final report.
+   - Never stop after the release commit or tag alone; creating the matching GitHub release is part of done criteria unless the user explicitly says to skip release publication.
 
 ## Notes
 
 - Never guess versions; always read from files and user intent.
+- Treat every scenario-matched gate as blocking before versioning or release publication, not as an optional reminder to maybe do later.
+- Never skip `review-change-set` for code-affecting releases, and do not continue to versioning work while confirmed review findings remain unresolved.
+- Never downgrade `discover-edge-cases` or `harden-app-security` to optional follow-up when the release risk says they apply.
+- Never claim a release is complete without checking the actual release version, creating the matching tag, and publishing the matching GitHub release.
 - If tests are required by repository conventions, run them before commit.
 - If a new branch is required, follow `references/branch-naming.md`.

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 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."
+  default_prompt: "Use $version-release only for explicit release/version/tag requests: inspect the current repository state, read the current version plus existing tag/release state, and inspect root CHANGELOG.md Unreleased content. Treat every conditional gate whose scenario is met as blocking before any version bump, tag, or release step: if the release includes code changes, run $review-change-set; if the reviewed risk profile says edge-case or security review is needed, run $discover-edge-cases and $harden-app-security as blocking gates too; if completed specs should be converted or docs need normalization, ensure $archive-specs runs through $submission-readiness-check; if changelog synchronization is needed, complete it before continuing. Then run any additional required code-quality skills, hand the repository to $submission-readiness-check so completed plan archives, project docs, AGENTS.md, and changelog readiness are settled before any version bump or tag, confirm CHANGELOG.md Unreleased is release-ready, update version files, cut the release directly from CHANGELOG.md Unreleased, create the release commit and matching tag, push commits and tags, and publish the matching GitHub release before reporting success."