@laitszkin/apollo-toolkit 3.1.1 → 3.1.3

package/CHANGELOG.md

@@ -7,6 +7,17 @@ All notable changes to this repository are documented in this file.
 ### Changed
 - None yet.
 
+## [v3.1.3] - 2026-04-23
+
+### Changed
+- Tighten `iterative-code-quality` so agents must keep iterating while any known in-scope actionable quality issue remains, must not produce a completion report until the latest scan is clear or remaining candidates are explicitly classified as blocked, unsafe, low-value, speculative, or approval-dependent, and should use tests or equivalent guardrails to support more aggressive refactors instead of deferring them for subjective confidence reasons.
+
+## [v3.1.2] - 2026-04-23
+
+### Changed
+- Tighten `commit-and-push` so emitted UI git directives such as `::git-stage`, `::git-commit`, and `::git-push` never count as evidence that staging, commit creation, or remote push actually happened.
+- Tighten `version-release` so release flows require real git mutations for staging, commit/tag creation, and push verification instead of treating UI git directives as proof that the release commit or tag exists.
+
 ## [v3.1.1] - 2026-04-22
 
 ### Changed

package/commit-and-push/SKILL.md

@@ -15,7 +15,7 @@ description: "Guide the agent to submit local changes with commit and push only
 ## Standards
 
 - Evidence: Inspect git state and classify the change set before deciding which quality gates apply, then compare the actual pending diff against root `CHANGELOG.md` `Unreleased` before committing, while also distinguishing the staged surface from additional unstaged work before deciding commit scope.
-- 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; when the user asks for multiple commits or a narrower staged subset, keep those commit boundaries explicit instead of broadening scope implicitly; 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; when the user asks for multiple commits or a narrower staged subset, keep those commit boundaries explicit instead of broadening scope implicitly; 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, and never treat UI directives such as `::git-stage`, `::git-commit`, or `::git-push` as substitutes for actual git commands or as evidence that submission already happened.
 - Quality: Re-run relevant validation for runtime changes, preserve unrelated local work safely when branch switching or post-push local sync is required, do not bypass blocking readiness findings such as missing/stale `Unreleased` bullets or unsynchronized project docs, and never collapse intentionally separated commit scopes just because related unstaged changes are present.
 - Output: Produce a concise Conventional Commit, push it to the intended branch, and report any temporary stash/restore, commit-scope separation, or local branch sync that was required.
 
@@ -71,6 +71,7 @@ Load only when needed:
    - Preserve user staging intent where possible.
    - If the user explicitly asks for separate commits, or the staged set is already a deliberate subset of the worktree, keep those scopes separated and do not auto-stage the remaining diff unless the user expands the requested scope.
    - If the user later broadens the requested scope, restate the new grouping, verify it against the actual staged/unstaged surfaces, and only then create the additional commit(s).
+   - Use actual `git add` / `git commit` operations; do not emit UI git directives as a stand-in for repository mutations.
    - Write a concise Conventional Commit message using `references/commit-messages.md`.
 7. Push
    - Push commit(s) to the intended branch.
@@ -79,6 +80,7 @@ Load only when needed:
    - If the push result is ambiguous, out of order, or the hashes do not match, rerun the missing git step sequentially and re-check before reporting success.
    - Confirm the local branch state matches the user's requested destination when post-push synchronization was requested.
    - When the user explicitly asks to merge work back from a temporary worktree and delete that worktree, do the final verification on the authoritative target branch first, then remove the temporary worktree and prune stale worktree records before reporting completion.
+   - Do not claim success based on emitted UI directives or optimistic status text alone; remote-hash verification is the required evidence.
 
 ## Notes
 
@@ -88,6 +90,7 @@ Load only when needed:
 - 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.
 - Never fabricate a commit/push result when the worktree is already clean; either identify the exact existing commit/upstream state that satisfies the user's request or say that no matching new submission exists.
+- Never treat `::git-stage`, `::git-commit`, `::git-push`, or similar UI helpers as proof that repository history was mutated; rely on actual git command results plus local/remote hash checks.
 - Never delete a temporary worktree before the target branch has been updated, tested, and verified to contain the intended final content.
 - Never auto-stage or auto-merge unrelated unstaged changes into a commit when the user or current index state already defines narrower commit boundaries.
 - If release/version/tag work is requested, use `version-release` instead.

package/iterative-code-quality/README.md

@@ -10,7 +10,8 @@ Improve an existing repository through repeated, evidence-backed code-quality pa
 - Splits mixed-responsibility code into narrower modules without changing macro architecture.
 - Repairs stale or missing logs and adds tests for important observability contracts.
 - Adds high-value unit, property-based, integration, or E2E tests based on risk.
-- Repeats the pass cycle until remaining issues are low-value, blocked, or require explicit product/architecture approval.
+- Uses those tests and other guardrails to justify more aggressive refactors, instead of leaving known issues in place for subjective confidence reasons.
+- Repeats the pass cycle while any known in-scope actionable quality issue remains, and forbids a completion report until the latest scan is clear or remaining items are explicitly deferred with a valid reason.
 - Synchronizes project docs and `AGENTS.md` through `align-project-documents` and `maintain-project-constraints` after implementation.
 
 ## Repository structure

package/iterative-code-quality/SKILL.md

@@ -22,15 +22,15 @@ description: >-
 ## Standards
 
 - Evidence: Read repository docs, project constraints, source, tests, logs, and entrypoints before editing; every rename, extraction, split, log update, or test must be backed by code context.
-- Execution: Work in bounded passes, prioritize behavior-neutral improvements with the highest maintainability and test value, validate after each pass, and repeat until the remaining quality gaps are low-value or unsafe to change.
-- Quality: Preserve business behavior and macro architecture unless tests expose an existing logic defect; avoid style-only churn, compatibility theater, broad rewrites, and unverified "cleanup".
-- Output: Deliver a concise pass-by-pass summary, changed behavior-neutral surfaces, test coverage added, validation results, unresolved risks, and documentation/`AGENTS.md` sync status.
+- Execution: Work in bounded passes, prioritize behavior-neutral improvements with the highest maintainability and test value, validate after each pass, and keep iterating while any known in-scope codebase quality issue remains unresolved; when tests or other reliable guardrails can prove equivalence, prefer taking the refactor instead of deferring it for subjective confidence reasons; do not produce the completion report while the scan still contains actionable gaps.
+- Quality: Preserve business behavior and macro architecture unless tests expose an existing logic defect; avoid style-only churn, compatibility theater, broad rewrites, and unverified "cleanup", but do not reject a worthwhile refactor purely because it feels risky when existing or newly added guardrails can verify it safely.
+- Output: Deliver a concise pass-by-pass summary, changed behavior-neutral surfaces, test coverage added, validation results, and documentation/`AGENTS.md` sync status only after every known in-scope quality issue is resolved or explicitly classified as blocked, unsafe, low-value, speculative, or requiring user approval.
 
 ## Goal
 
 Raise code quality across an existing repository without changing intended product behavior or the system's macro architecture.
 
-This skill is intentionally implementation-oriented, not report-only. It should identify high-value improvements, apply them, test them, and keep iterating until further changes would be speculative, low-value, or architecture-changing.
+This skill is intentionally implementation-oriented, not report-only. It should identify high-value improvements, apply them, test them, and keep iterating across the codebase until there are no unresolved known in-scope quality issues. If a post-pass scan finds remaining actionable gaps, continue the next pass instead of writing a completion report.
 
 ## Required Reference Loading
 
@@ -71,6 +71,7 @@ For each pass:
 - Prefer repository-native abstractions over new parallel frameworks.
 - Preserve public behavior, data contracts, side effects, error classes, and macro architecture.
 - Add or update tests in the same pass when the change touches non-trivial logic, observability contracts, or extracted helpers.
+- If strong guardrails exist or can be added cheaply, prefer the clearer or more maintainable refactor instead of leaving a known issue in place due to subjective caution alone.
 - Validate the touched scope before starting another pass.
 
 ### 3) Rename for clarity without churn
@@ -87,6 +88,7 @@ For each pass:
 - Extract helpers only when they reduce duplication, centralize one business rule, clarify caller intent, or make a behavior testable.
 - Keep helper placement aligned with current module ownership.
 - Do not create abstractions for one-off code unless they isolate a meaningful domain rule or external contract.
+- If tests or equivalent guardrails can prove behavior preservation, do not let moderate implementation uncertainty block an otherwise valuable simplification or extraction.
 - Preserve observable behavior unless a test proves the current behavior is a defect.
 
 ### 5) Split modules by responsibility
@@ -95,6 +97,7 @@ For each pass:
 - Define the new module's responsibility before moving code.
 - Keep interfaces narrow, explicit, and consistent with existing project style.
 - Avoid macro-architecture changes such as new layers, new service boundaries, new persistence strategies, or framework swaps unless the user explicitly expands scope.
+- When module boundaries are currently poor but can be protected by focused tests or other guardrails, choose the cleaner split instead of preserving a mixed-responsibility file out of caution alone.
 - Use `references/module-boundaries.md` for extraction rules and anti-patterns.
 
 ### 6) Repair logging and observability drift
@@ -118,9 +121,10 @@ For each pass:
 ### 8) Iterate until quality gates pass
 
 - After each pass, run the narrowest relevant tests first, then broaden validation when confidence increases.
-- Re-scan touched areas for new naming drift, duplicated helper candidates, module-boundary cracks, logging drift, and missing tests.
-- Repeat the full pass cycle when significant gaps remain and can be fixed safely without changing business behavior or macro architecture.
-- Stop only when remaining issues are low-value, speculative, blocked, or require explicit product/architecture approval.
+- Re-scan both touched areas and the known quality backlog for new naming drift, duplicated helper candidates, module-boundary cracks, logging drift, and missing tests.
+- Repeat the full pass cycle whenever any known in-scope actionable gap remains and can be fixed safely without changing business behavior or macro architecture.
+- Do not write the completion report, summarize the task as done, or hand back as complete while the latest scan still contains known actionable quality issues.
+- Stop only when every known in-scope issue has been resolved, or each remaining candidate is explicitly classified as low-value, speculative, blocked, unsafe, or requiring product/architecture approval.
 - Use `references/iteration-gates.md` for stopping criteria.
 
 ### 9) Synchronize docs and constraints
@@ -142,6 +146,8 @@ After code and tests are complete:
 
 ## Completion Report
 
+Only write this report after the latest scan confirms there are no known actionable in-scope quality issues remaining. If any such issue remains, continue iterating instead of reporting completion.
+
 Return:
 
 1. Passes completed and why they were ordered that way.

package/iterative-code-quality/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Iterative Code Quality"
   short_description: "Refactor names, functions, modules, logs, and tests in repeated behavior-safe passes"
-  default_prompt: "Use $iterative-code-quality to scan this repository, build an evidence-backed quality backlog, then iteratively clarify variable names, simplify or extract reusable functions, split code into single-responsibility modules, repair stale or missing logs, and add high-value unit/property/integration/E2E tests while preserving business behavior and macro architecture; after code and tests are complete, run $align-project-documents and $maintain-project-constraints to synchronize docs and AGENTS.md."
+  default_prompt: "Use $iterative-code-quality to scan this repository, build an evidence-backed quality backlog, then iteratively clarify variable names, simplify or extract reusable functions, split code into single-responsibility modules, repair stale or missing logs, and add high-value unit/property/integration/E2E tests while preserving business behavior and macro architecture; when tests or other reliable guardrails exist or can be added cheaply, use them to justify a more aggressive refactor instead of deferring worthwhile cleanup for subjective confidence reasons; if the latest scan still contains any known in-scope actionable quality issue, do not write a completion report and continue the next bounded iteration instead; after all known actionable issues are resolved or explicitly classified as blocked, unsafe, low-value, speculative, or requiring approval, run $align-project-documents and $maintain-project-constraints to synchronize docs and AGENTS.md."

package/iterative-code-quality/references/iteration-gates.md

@@ -10,7 +10,7 @@ Each pass must have:
 - validation plan,
 - rollback point if evidence contradicts the change.
 
-Avoid starting a broad second pass before validating the first.
+Avoid starting a broad second pass before validating the first, but do not stop after a validated pass if known actionable quality issues remain anywhere in the in-scope codebase.
 
 ## Validation cadence
 
@@ -28,9 +28,11 @@ If validation fails:
 - keep regression coverage for real defects,
 - do not mask failures by weakening assertions.
 
+If validation passes and the guardrails meaningfully cover the changed behavior, do not keep a known quality issue in place purely because of subjective confidence concerns.
+
 ## Re-scan after each pass
 
-Inspect touched areas for:
+Inspect touched areas and the full known quality backlog for:
 
 - new naming drift from moved or extracted concepts,
 - duplicated logic that remains after extraction,
@@ -43,15 +45,18 @@ Inspect touched areas for:
 
 Repeat the cycle when:
 
+- any known in-scope actionable quality issue remains unresolved,
 - high-impact unclear names remain,
 - duplicated or hard-coded workflows still have safe extraction paths,
 - a module still mixes distinct responsibilities and can be split locally,
 - logs are still misleading or missing at critical decisions,
 - high-value business logic remains untested and is testable.
 
+Do not produce a final completion report while any item in this section is true. Continue with the next bounded pass instead.
+
 ## Stop when
 
-Stop when remaining candidates are:
+Stop only when there are no unresolved known in-scope actionable issues. Any remaining candidates must be explicitly classified as one of:
 
 - low-value style preference,
 - speculative without concrete evidence,
@@ -61,6 +66,8 @@ Stop when remaining candidates are:
 - blocked by unavailable credentials, unstable external systems, or missing documentation,
 - untestable with the current repository tooling and too risky to change safely.
 
+If a remaining candidate cannot be placed in one of these categories, it is still an actionable gap and the agent must continue iterating rather than complete the task.
+
 ## Completion evidence
 
 The final report should make the stopping point auditable:
@@ -70,4 +77,5 @@ The final report should make the stopping point auditable:
 - tests added by risk category,
 - behavior-preservation evidence,
 - docs and constraints sync status,
-- deferred items with reason and required approval or dependency.
+- proof that the latest scan found no known actionable in-scope quality issues,
+- deferred items with reason and required approval, dependency, or safety constraint.

package/iterative-code-quality/references/naming-and-simplification.md

@@ -69,3 +69,5 @@ Before and after simplification, verify:
 - public API and CLI behavior remain stable,
 - log fields remain compatible unless stale names were intentionally corrected,
 - existing tests still pass and new tests cover extracted rules.
+
+If these checks can be enforced by existing or newly added tests, do not treat subjective confidence alone as a reason to avoid the simplification.

package/iterative-code-quality/references/testing-strategy.md

@@ -6,6 +6,8 @@ Choose tests from the risk inventory, not from a generic coverage target.
 
 For every non-trivial pass, ask what could regress silently if the cleanup were wrong.
 
+Use the resulting guardrails aggressively: when tests or equivalent verification can prove behavior preservation, they should unlock bolder refactors rather than merely justify small cosmetic edits.
+
 ## Unit tests
 
 Use for:
@@ -76,3 +78,4 @@ Consider:
 - Preserve failing seeds or examples from property-based tests.
 - Do not weaken existing tests to fit the refactor.
 - If old tests asserted implementation details, rewrite them around stable behavior while preserving the business invariant.
+- Once stable guardrails exist, do not refuse a maintainability-improving refactor purely because confidence feels lower than ideal; let the guardrails decide.

package/package.json

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

package/version-release/SKILL.md

@@ -15,7 +15,7 @@ description: "Guide the agent to prepare and publish a versioned release (versio
 ## 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, 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; when the user explicitly wants the same prerelease version to point at newer fixes, retarget the existing prerelease tag and GitHub release instead of inventing an extra version bump; when editing an existing GitHub prerelease during that retarget flow, use a GitHub-accepted release target such as the intended branch name if the tool or API rejects a raw commit SHA for `target_commitish`; otherwise 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; when the user explicitly wants the same prerelease version to point at newer fixes, retarget the existing prerelease tag and GitHub release instead of inventing an extra version bump; when editing an existing GitHub prerelease during that retarget flow, use a GitHub-accepted release target such as the intended branch name if the tool or API rejects a raw commit SHA for `target_commitish`; otherwise 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, and never treat UI git directives such as `::git-stage`, `::git-commit`, or `::git-push` as evidence that the release commit or tag already exists.
 - 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.
 
@@ -92,6 +92,7 @@ Load only when needed:
    - For new-version flows, create the version tag locally after commit.
    - For prerelease retarget flows, move the existing tag locally only after the new fix commit exists, and verify the target commit hash before rewriting the tag.
    - Re-read the version files after editing and before tagging to confirm they all match the intended release version.
+   - Use actual git mutations for staging, commit creation, and tag creation; do not substitute UI git directives for these steps.
 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.
    - For prerelease retarget flows, push the rewritten tag explicitly (for example `--force-with-lease` for the single tag only), then verify the remote tag hash matches local `HEAD` before touching the GitHub release.
@@ -117,5 +118,6 @@ Load only when needed:
 - 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.
 - Never treat a PR creation step, release-page URL guess, or tag-only push as evidence that the GitHub release exists.
+- Never treat `::git-stage`, `::git-commit`, `::git-push`, or similar UI helpers as proof that the release commit, pushed tag, or remote branch update actually happened.
 - If tests are required by repository conventions, run them before commit.
 - If a new branch is required, follow `references/branch-naming.md`.