@laitszkin/apollo-toolkit 2.14.1 → 2.14.3

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [v2.14.3] - 2026-04-07
+
+### Changed
+- Strengthen `systematic-debug` so runtime-pipeline investigations must anchor on one canonical run or artifact root, map failures to concrete stages, and separate toolchain/platform faults from application-logic faults before fixing.
+- Strengthen `scheduled-runtime-health-check` so bounded runs must record the canonical run folder as soon as it materializes and use structured artifacts from that same run when analyzing health.
+
+## [v2.14.2] - 2026-04-06
+
+### Changed
+- Rewire `merge-changes-from-local-branches` so its final local-branch submission stage is handed to `commit-and-push`, which now owns the shared changelog/readiness/archival flow after merges.
+- Rework `archive-specs` so documentation alignment is delegated to `align-project-documents` and `maintain-project-constraints` before completed plan sets are archived.
+- Clarify that `commit-and-push` and `version-release` depend directly on `archive-specs` for completed plan conversion and project-doc alignment, instead of duplicating downstream documentation-sync steps.
+
 ## [v2.14.1] - 2026-04-06
 
 ### Changed

package/archive-specs/SKILL.md

@@ -7,7 +7,7 @@ description: Convert completed project plan sets into maintainable project docum
 
 ## Dependencies
 
-- Required: none.
+- Required: `align-project-documents` to align repository docs with current code before archiving, and `maintain-project-constraints` to synchronize `AGENTS.md` after the doc update.
 - Conditional: none.
 - Optional: none.
 - Fallback: not applicable.
@@ -15,9 +15,9 @@ description: Convert completed project plan sets into maintainable project docum
 ## Standards
 
 - Evidence: Treat code, config, deployment files, and current spec files as evidence sources; never guess when a detail is missing.
-- Execution: Inventory all relevant specs first, reconcile them with the current repository, then generate or update standardized docs from the provided templates.
+- Execution: Inventory all relevant specs first, reconcile them with the current repository, use `align-project-documents` to update durable project docs, use `maintain-project-constraints` to refresh `AGENTS.md` when repository guidance changed, then archive only the truly consumed planning artifacts.
 - Quality: Prefer source-of-truth behavior over stale plan text, align existing docs to the same standard structure, and call out unknowns explicitly instead of inventing missing setup details.
-- Output: Produce a concise `README.md` plus a categorized project-doc set, then archive or remove superseded spec files after the conversion is complete.
+- Output: Produce synchronized durable docs (`README.md`, categorized project docs, and `AGENTS.md` when needed), then archive or remove superseded spec files after the conversion is complete.
 
 ## Goal
 
@@ -44,6 +44,7 @@ Convert completed planning artifacts into stable, standardized project documenta
 
 ### 3) Standardize existing project docs into categorized outputs
 
+- Hand the documentation rewrite/alignment work to `align-project-documents`; use the templates below only as the target shape and evidence checklist.
 - If the project already has `README.md`, handbooks, setup guides, architecture docs, or runbooks, rewrite or reorganize them so they follow this skill's standardized split-document structure instead of leaving mixed formats in place.
 - Use `references/templates/readme.md` for the concise project introduction.
 - Use `references/templates/docs-index.md` for the project documentation index and reference list.
@@ -85,6 +86,7 @@ Ensure the split project docs cover all of the following:
 - `docs/README.md` should act as the reference list for the categorized docs.
 - Each category doc should stay focused on one topic instead of acting like another monolithic handbook.
 - Remove template placeholders and stale planning language before finishing.
+- After the docs are aligned, run `maintain-project-constraints` whenever the documentation changes imply `AGENTS.md` needs to reflect updated workflows, commands, or repository capabilities.
 
 ### 7) Archive superseded spec files after successful conversion
 

package/commit-and-push/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: commit-and-push
-description: "Guide the agent to submit local changes with commit and push only (no versioning). Use when users ask to commit, submit, or push changes without requesting tag/version/release operations. During submission, run `archive-specs` to convert completed spec sets into project documentation and archive the consumed plans, and also use it when existing project docs do not match the standardized project-doc structure."
+description: "Guide the agent to submit local changes with commit and push only (no versioning). Use when users ask to commit, submit, or push changes without requesting tag/version/release operations. Depend directly on `archive-specs` when completed plan sets should become durable docs or when project docs need alignment, and let that skill own the downstream documentation synchronization work."
 ---
 
 # Commit and Push
@@ -8,14 +8,14 @@ description: "Guide the agent to submit local changes with commit and push only
 ## Dependencies
 
 - 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.
+- Conditional: `archive-specs` when completed plan sets should be converted or repository docs need alignment; `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, stop and report the missing dependency.
 
 ## Standards
 
 - 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, and when the worktree is already clean inspect local `HEAD`, upstream state, and the most recent relevant commit before deciding the request is a no-op; when worktree-based delivery is involved, verify where the authoritative target branch lives before moving history, re-validate on that target branch after replay or merge, and remove the temporary worktree only after the target branch is safely updated; 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.
+- 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 readiness classification, invoke `archive-specs` directly whenever completed plan sets should be converted or project docs need alignment, preserve staging intent, honor any explicit user-specified target branch, and when the worktree is already clean inspect local `HEAD`, upstream state, and the most recent relevant commit before deciding the request is a no-op; when worktree-based delivery is involved, verify where the authoritative target branch lives before moving history, re-validate on that target branch after replay or merge, and remove the temporary worktree only after the target branch is safely updated; 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.
 
@@ -61,10 +61,11 @@ Load only when needed:
    - Re-run relevant tests when runtime logic changes.
 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.
+   - Let it decide whether completed plan sets should be converted, whether project docs need alignment through `archive-specs`, 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.
+   - When readiness indicates doc conversion or project-doc drift, run `archive-specs` before the final commit instead of duplicating documentation alignment work locally.
 6. Commit
    - Preserve user staging intent where possible.
    - Write a concise Conventional Commit message using `references/commit-messages.md`.

package/merge-changes-from-local-branches/SKILL.md

@@ -4,26 +4,28 @@ description: >-
   Read changes from all local git branches and merge them into the local main
   branch. When conflicts arise, auto-resolve them by keeping correct functionality
   (preferring the more recent change on the same line, or the change that preserves
-  working behavior). Commit the merged result to local main without pushing to
-  remote. Use when the user asks to consolidate local branch work, merge all
-  changes into main, or prepare local branches for integration.
+  working behavior). Hand the final merged local branch state to `commit-and-push`
+  so the commit workflow can handle changelog/readiness steps and any required
+  spec archival before the work is considered complete. Use when the user asks
+  to consolidate local branch work, merge all changes into main, or prepare local
+  branches for integration.
 ---
 
 # Merge Changes from Local Branches
 
 ## Dependencies
 
-- Required: none (uses native git commands).
+- Required: `commit-and-push` for the final local-branch submission flow after merge verification.
 - Conditional: none.
-- Optional: `commit-and-push` if commit message guidance is needed.
+- Optional: none.
 - Fallback: If git operations fail, stop and report the error.
 
 ## Standards
 
 - Evidence: Inspect the current branch state, local branches, ahead/behind status, and actual conflicting files before deciding what to merge.
-- Execution: Merge only the relevant local branches into `main` sequentially, resolve conflicts by reading both sides and editing the merged result to preserve shipped behavior, then verify the merged state.
+- Execution: Merge only the relevant local branches into `main` sequentially, resolve conflicts by reading both sides and editing the merged result to preserve shipped behavior, verify the merged state, then hand the final local branch state to `commit-and-push` so commit/changelog/spec-archival work happens through the shared submission workflow.
 - Quality: Never use blanket timestamp rules or default `-X ours/theirs` conflict resolution as the primary merge strategy, and do not declare success until the final `main` state has been checked and verified.
-- Output: Produce a clean main branch with all local changes integrated.
+- Output: Produce a clean local main branch with all local changes integrated and ready for the shared submit workflow.
 
 ## Goal
 
@@ -94,10 +96,14 @@ For each local branch (excluding main):
   ```
 - If verification fails, fix the merged state on `main` before proceeding.
 
-### 5) Commit the merged result
+### 5) Hand off the merged result for shared submission handling
 
-- The merge commits are the submission artifact; do not amend them unless the user explicitly asks for history rewriting.
-- If a follow-up fix is required after verification, create a normal commit on `main` that explains the correction.
+- Once merge verification passes, invoke `commit-and-push` for the authoritative local branch so the final submission flow owns:
+  - `CHANGELOG.md` readiness
+  - any required `archive-specs` run
+  - the final commit creation on the local target branch
+- Do not duplicate commit-message, changelog, or spec-archival logic inside this skill.
+- If a follow-up fix is required after verification, make that fix on `main` before handing off to `commit-and-push`.
 
 ### 6) Report completion
 
@@ -106,13 +112,13 @@ For each local branch (excluding main):
 - Confirm main is updated with all changes.
 - Note any conflicts that were resolved and the rationale.
 - Report the verification commands that were run.
-- Confirm no remote push was performed.
+- Confirm whether the workflow stopped at the local commit boundary or continued into a remote push because the user explicitly requested it.
 
 ## Working Rules
 
 - Never force-push; use only merge or rebase with merge.
 - Prefer preserving functionality over keeping either branch's exact changes.
-- Do not push to remote — this skill only merges to local main.
+- Do not push to remote from this skill directly; let `commit-and-push` own any later publish step only when the user explicitly requests it.
 - If a branch contains no meaningful changes (empty merge), skip it.
 - Keep the main branch history clean and readable.
 - If a branch's merge breaks tests, resolve the conflict differently before committing.

package/package.json

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

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

@@ -14,8 +14,8 @@ 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, 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.
+- Evidence: Anchor every conclusion to the requested command, execution window, startup/shutdown timestamps, one canonical run folder or artifact root, captured logs, and concrete runtime signals.
+- 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, record the canonical run folder once the process materializes it, 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.
 
@@ -45,10 +45,12 @@ This skill is an orchestration layer. It owns the background terminal session, o
 
 - Prefer one bounded observation window over open-ended monitoring.
 - Use one dedicated background terminal session per requested run so execution and logs stay correlated.
+- Record the canonical run directory, artifact root, or other generated output location as soon as it exists, and use that as the source of truth for later analysis.
 - Treat code update as optional and only perform it when the user explicitly requests it.
 - Treat startup, steady-state, and shutdown as part of the same investigation.
 - Do not call a module healthy unless there is at least one positive signal for it.
 - Separate scheduler failures, boot failures, runtime failures, and shutdown failures.
+- For complex pipelines, identify the last successful stage before attributing the failure to application logic.
 - If logs cannot support a health judgment, mark the module as `unknown` instead of guessing.
 
 ## Required workflow
@@ -62,6 +64,7 @@ This skill is an orchestration layer. It owns the background terminal session, o
    - 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.
+   - Decide in advance what the canonical evidence root will be if the command generates its own run directory, artifact bundle, database, or report file, so later diagnosis does not drift across multiple runs.
 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.
@@ -73,6 +76,7 @@ This skill is an orchestration layer. It owns the background terminal session, o
    - If the user requested a future start time and no reliable scheduler is available, fail closed and report the scheduling limitation instead of starting early.
 5. Run and capture readiness
    - Execute the requested command in the same background terminal.
+   - As soon as the command emits or creates its canonical run directory, artifact root, or equivalent output location, record that path and reuse it for every later check.
    - Wait for a concrete readiness signal when the command is expected to stay up, such as a health endpoint, listening-port log, worker boot line, or queue-consumer ready message.
    - If readiness never arrives, stop the run, preserve logs, and treat it as a failed startup window.
 6. Observe and stop when bounded
@@ -84,7 +88,8 @@ This skill is an orchestration layer. It owns the background terminal session, o
 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.
-   - Pass the service or module names, environment, timezone, run folder, relevant log files, and the exact start/end boundaries.
+   - Pass the service or module names, environment, timezone, canonical run folder, relevant log files, and the exact start/end boundaries.
+   - When the command produced reports, databases, or other structured artifacts, compare them against the same run's logs before making a health judgment.
    - Reuse its confirmed issues, hypotheses, and monitoring improvements instead of rewriting a separate incident workflow.
 8. Produce the final report
    - Always summarize the actual command executed, actual start/end timestamps, execution status, and log locations.
@@ -114,7 +119,7 @@ Absence of errors alone is not enough for `healthy`.
 Use this structure in responses:
 
 1. Run summary
-   - Workspace, command, schedule if any, actual start/end timestamps, duration if bounded, readiness result, shutdown result if applicable, and log locations.
+   - Workspace, command, schedule if any, actual start/end timestamps, duration if bounded, readiness result, shutdown result if applicable, canonical run folder or artifact root, and log locations.
 2. Execution result
    - Whether the command completed, stayed up for the requested window, or failed early.
 3. Code update result

package/systematic-debug/SKILL.md

@@ -14,16 +14,18 @@ description: "Systematic debugging workflow for program issues: understand obser
 
 ## Standards
 
-- Evidence: Gather expected versus observed behavior from code and runtime facts before deciding on a cause.
-- Execution: Inspect the relevant paths, reproduce every plausible cause with tests, diagnose the real cause, then apply the minimal fix.
+- Evidence: Gather expected versus observed behavior from code and runtime facts before deciding on a cause, and when the issue involves a runtime pipeline or bounded run, anchor the investigation to one canonical artifact root or run directory instead of mixed terminal snippets from multiple runs.
+- Execution: Inspect the relevant paths, reproduce every plausible cause with tests or bounded reruns, map each observed failure to a concrete pipeline stage, distinguish toolchain/platform faults from application-logic faults, then apply the minimal fix.
 - Quality: Keep scope focused on the bug, prefer existing test patterns, and explicitly rule out hypotheses that could not be reproduced.
-- Output: Deliver the plausible-cause list, reproduction tests, validated fix summary, and passing-test confirmation.
+- Output: Deliver the plausible-cause list, the canonical evidence source, reproduction tests or reruns, validated fix summary, and passing-test confirmation.
 
 ## Core Principles
 
 - Gather facts from user reports and code behavior before changing implementation.
 - Cover all plausible causes with reproducible tests instead of guessing a single cause.
 - Keep fixes minimal, focused, and validated by passing tests.
+- When logs or runtime artifacts exist, treat one run as canonical and compare every conclusion against that same run's generated artifacts, not against ad hoc console recollection.
+- When the failing flow crosses multiple layers, identify the last confirmed successful stage before assigning blame.
 
 ## Trigger Conditions
 
@@ -39,10 +41,11 @@ Also auto-invoke this skill when mismatch evidence appears during normal executi
 
 ## Required Workflow
 
-1. **Understand and inspect**: Parse expected vs observed behavior, explore relevant code paths, and build a list of plausible root causes.
-2. **Reproduce with tests**: Write or extend tests that reproduce every plausible cause.
-3. **Diagnose and confirm**: Use reproduction evidence to confirm the true root cause and explicitly rule out non-causes.
-4. **Fix and validate**: Implement focused fixes and iterate until all reproduction tests pass.
+1. **Understand and inspect**: Parse expected vs observed behavior, explore relevant code paths, record the canonical failing run or artifact root when runtime output is involved, and build a list of plausible root causes.
+2. **Map the failure boundary**: Break the flow into concrete stages such as setup, startup, readiness, steady-state execution, persistence, and shutdown, then identify the last stage that is confirmed to have succeeded.
+3. **Reproduce with tests or bounded reruns**: Write or extend tests that reproduce every plausible cause, and when the bug depends on runtime orchestration rerun the same bounded command or scenario instead of switching contexts mid-investigation.
+4. **Diagnose and confirm**: Use reproduction evidence to confirm the true root cause, explicitly rule out non-causes, and classify whether the fault belongs to the toolchain/platform layer, the orchestration layer, or application logic.
+5. **Fix and validate**: Implement focused fixes and iterate until all reproduction tests or bounded reruns pass.
 
 ## Implementation Guidelines
 
@@ -50,10 +53,13 @@ Also auto-invoke this skill when mismatch evidence appears during normal executi
 - Prefer existing test patterns and fixtures over creating new frameworks.
 - Keep the scope to bug reproduction and resolution; avoid unrelated refactors.
 - If a hypothesized cause cannot be reproduced, document why and deprioritize it explicitly.
+- For long-running or generated-artifact workflows, record the exact command, timestamps, and artifact paths before inspecting outputs so later comparisons stay on the same evidence set.
+- Do not mix baseline data and rerun data casually; compare the same scenario or command across runs and call out when a conclusion comes from a rerun rather than the original failure.
 
 ## Deliverables
 
 - Plausible root-cause list tied to concrete code paths
-- Reproduction tests for each plausible cause
+- Canonical failing run or artifact root when runtime evidence exists
+- Reproduction tests or bounded reruns for each plausible cause
 - Fix summary mapped to failing-then-passing tests
 - Final confirmation that all related tests pass

package/version-release/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: version-release
-description: "Guide the agent to prepare and publish a versioned release (version bump, changelog, tag, GitHub release, and push). Use only when users explicitly request version/tag/release work. Before finalizing the release, run `archive-specs` to convert completed spec sets into project documentation and archive the consumed plans, and also use it when existing project docs do not match the standardized project-doc structure."
+description: "Guide the agent to prepare and publish a versioned release (version bump, changelog, tag, GitHub release, and push). Use only when users explicitly request version/tag/release work. Depend directly on `archive-specs` when completed plan sets should become durable docs or when project docs need alignment, and let that skill own the downstream documentation synchronization work."
 ---
 
 # Version Release
@@ -8,14 +8,14 @@ description: "Guide the agent to prepare and publish a versioned release (versio
 ## Dependencies
 
 - 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.
+- Conditional: `archive-specs` when completed plan sets should be converted or repository docs need alignment; `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, stop and report the missing dependency.
 
 ## Standards
 
 - 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, and if the worktree is already clean inspect the current version, local/remote tag state, and existing GitHub release state before deciding whether the request is already satisfied; then cut the release directly from `CHANGELOG.md` `Unreleased`, update versions and docs, commit, tag, push, and publish the GitHub release with actual release tooling rather than PR-surrogate directives; run git mutations sequentially and verify both the branch tip and release tag exist remotely before publishing the GitHub release.
+- 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, invoke `archive-specs` directly whenever completed plan sets should be converted or project docs need alignment, and if the worktree is already clean inspect the current version, local/remote tag state, and existing GitHub release state before deciding whether the request is already satisfied; then cut the release directly from `CHANGELOG.md` `Unreleased`, update versions and docs, commit, tag, push, and publish the GitHub release with actual release tooling rather than PR-surrogate directives; 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.
 
@@ -61,8 +61,9 @@ Load only when needed:
    - Resolve all confirmed findings before changing version files, tags, or release metadata.
 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.
+   - Let it decide whether completed plan sets should be converted, whether project docs need alignment through `archive-specs`, 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.
+   - When readiness indicates completed-spec conversion or project-doc drift, run `archive-specs` before version edits instead of reproducing documentation alignment inside the release workflow.
 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.