@laitszkin/apollo-toolkit 3.1.2 → 3.1.3

package/CHANGELOG.md

@@ -7,6 +7,11 @@ 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

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.2",
+  "version": "3.1.3",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",