@laitszkin/apollo-toolkit 3.1.2 → 3.1.4

package/CHANGELOG.md

@@ -7,6 +7,16 @@ All notable changes to this repository are documented in this file.
 ### Changed
 - None yet.
 
+## [v3.1.4] - 2026-04-23
+
+### Changed
+- Refine `iterative-code-quality` so it now treats naming, abstraction, module boundaries, logging, and tests as selectable execution directions under continuous full-codebase rescans, guiding agents to choose the highest-confidence, highest-leverage gradual refactors that prepare the ground for deeper later cleanup while preserving behavior under green guardrails and a precise system-level definition of macro architecture.
+
+## [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

@@ -1,16 +1,21 @@
 # iterative-code-quality
 
-Improve an existing repository through repeated, evidence-backed code-quality passes while preserving intended business behavior and macro architecture.
+Improve an existing repository through repeated, evidence-backed full-iteration refactors while preserving intended business behavior and the system's top-level macro architecture.
 
 ## Core capabilities
 
 - Scans the full codebase and builds a prioritized quality backlog before editing.
+- Treats naming, abstraction, module boundaries, logging, and tests as selectable execution directions rather than a fixed sequence.
 - Clarifies ambiguous variable, parameter, field, helper, and test-data names.
 - Simplifies complex functions and extracts reusable helpers only when they centralize real behavior.
 - 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.
+- Re-scans the full repository after every iteration and picks the next highest-confidence, highest-leverage directions.
+- Uses small safe refactors to prepare the ground for larger later refactors, progressing gradually from outside to inside.
+- 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.
+- Targets as many inherited repository quality problems as can be solved safely, and expects the guarded test surface to remain green after the refactor.
 - Synchronizes project docs and `AGENTS.md` through `align-project-documents` and `maintain-project-constraints` after implementation.
 
 ## Repository structure

package/iterative-code-quality/SKILL.md

@@ -5,7 +5,7 @@ description: >-
   passes: clarify poor variable names, simplify or extract reusable functions,
   split oversized code into single-responsibility modules, repair stale or
   missing logs, and add high-value tests while preserving business behavior and
-  macro architecture. Use when users ask for comprehensive refactoring, code
+  system-level macro architecture. Use when users ask for comprehensive refactoring, code
   cleanup, maintainability hardening, naming cleanup, log alignment, or test
   coverage improvement across a repository.
 ---
@@ -22,15 +22,17 @@ 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: Continuously re-scan the full codebase, treat naming, abstraction, module boundaries, logging, and tests as selectable execution directions rather than a fixed sequence, choose the highest-confidence directions that can safely land now, and use those smaller refactors to prepare the ground for larger future refactors; validate after each iteration, then 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: Solve as many inherited code-quality problems as safely possible without changing intended behavior or the system's macro architecture; 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.
+Resolve as many inherited repository quality problems as possible without breaking intended behavior, and use tests plus other reliable guardrails to prove that the refactor leaves the project in a fully green state.
 
-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 keep scanning the full codebase, choose the best available refactor directions at each moment, apply as much safe cleanup as the repository can support, add or strengthen tests to guard the refactor, and use incremental cleanup to unlock deeper improvements over time. If a post-iteration scan finds remaining actionable gaps, continue the next iteration instead of writing a completion report.
+
+For this skill, `macro architecture` means the system's top-level runtime shape and overall operating logic: major subsystems, top-level execution model, deployment/runtime boundaries, persistence model, service boundaries, and the end-to-end way the whole system works. Ordinary module interactions, helper extraction, local responsibility moves, and internal call-boundary cleanup do not count as macro-architecture changes by themselves.
 
 ## Required Reference Loading
 
@@ -54,9 +56,11 @@ Load references only when they match the active pass:
 - Build an initial quality backlog with concrete file/function/test targets before changing code.
 - Use `references/repository-scan.md` for the scan checklist and backlog scoring.
 
-### 2) Execute bounded improvement passes
+### 2) Execute continuous full scans with selectable directions
+
+Do not force one fixed order such as "finish naming first, then abstraction, then modules". Instead, keep re-scanning the whole codebase and select the execution directions that are highest-confidence and highest-leverage right now.
 
-Run focused passes in the order that fits the repository evidence. A typical order is:
+Treat these as multi-select execution directions, not mandatory sequential stages:
 
 1. Naming clarity for variables, parameters, fields, local helpers, and test data.
 2. Function simplification and reusable extraction for duplicated or hard-coded workflows.
@@ -64,14 +68,22 @@ Run focused passes in the order that fits the repository evidence. A typical ord
 4. Logging alignment for stale, misleading, missing, or low-context diagnostics.
 5. Risk-based test coverage for high-value business logic and boundary cases.
 
-For each pass:
+Direction-selection rules:
+
+- Prefer the directions with the strongest current evidence and best guardrails.
+- Prefer smaller, higher-confidence refactors that unlock or de-risk larger later refactors.
+- Prefer outside-in progress: stabilize boundaries, callers, naming, logs, and tests around a subsystem before attempting deeper internal rewrites.
+- Re-evaluate the whole backlog after every landed iteration; the next best direction may change because the previous cleanup improved the local safety or clarity.
+
+For each iteration:
 
 - Read all directly affected callers, tests, and public interfaces before editing.
-- Keep the pass small enough to validate and review; split broad cleanups into multiple passes.
+- Keep the scope small enough to validate and review, and select whichever directions are most justified for that scope instead of forcing every direction to appear in every iteration.
 - 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.
-- Validate the touched scope before starting another pass.
+- Add or update tests in the same iteration 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 iteration.
 
 ### 3) Rename for clarity without churn
 
@@ -87,6 +99,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
@@ -94,7 +107,8 @@ For each pass:
 - Split code only when one file/module owns multiple change reasons, domain boundaries, external integrations, or lifecycle stages.
 - 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.
+- Avoid macro-architecture changes such as new top-level layers, new service boundaries, new persistence strategies, deployment/runtime model changes, 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
@@ -115,12 +129,15 @@ For each pass:
 - If a new test exposes an existing business-logic bug, invoke `systematic-debug`, fix the true owner, and keep the regression test.
 - Use `references/testing-strategy.md` for coverage selection and required `N/A` reasoning.
 
-### 8) Iterate until quality gates pass
+### 8) Iterate gradually from outside to inside until the repository is clear of known actionable issues
 
-- 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.
+- After each iteration, run the narrowest relevant tests first, then broaden validation until the changed scope and final repository state are adequately guarded.
+- Re-scan the full codebase, not only the touched area, because the best next direction may have shifted after the last cleanup.
+- Re-rank the backlog after every iteration and choose the next highest-confidence, highest-leverage direction set.
+- Use small external or boundary-level cleanups to make later deeper refactors safer; treat that groundwork as progress toward a thorough long-horizon refactor, not as a distraction from it.
+- Repeat the full iteration 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
@@ -134,7 +151,7 @@ After code and tests are complete:
 ## Hard Guardrails
 
 - Do not change intended business logic while refactoring.
-- Do not change macro architecture, framework choice, storage model, deployment model, or service boundaries unless the user explicitly approves that expanded scope.
+- Do not change the system's macro architecture—its top-level runtime shape, deployment/runtime model, persistence model, major service boundaries, or overall operating logic—unless the user explicitly approves that expanded scope.
 - Do not use one-off scripts to rewrite product code.
 - Do not perform style-only churn that does not improve naming, reuse, modularity, observability, or test confidence.
 - Do not weaken tests to make refactors pass; update tests to stable invariants or fix the implementation defect.
@@ -142,9 +159,11 @@ 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 and the relevant test/guardrail suite is green. If any such issue remains, continue iterating instead of reporting completion.
+
 Return:
 
-1. Passes completed and why they were ordered that way.
+1. Iterations completed and which execution directions were selected in each one.
 2. Key files changed and the quality issue each change resolved.
 3. Business behavior preservation evidence.
 4. Tests added or updated, including property/integration/E2E `N/A` reasons where relevant.

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 keep scanning the full repository, treat naming, simplification, reusable extraction, module-boundary cleanup, logging alignment, and testing as selectable execution directions rather than a fixed sequence, and choose the highest-confidence, highest-leverage directions available at each moment; use small safe refactors to prepare the ground for larger later refactors, progress gradually from outside to inside, use tests or other reliable guardrails to justify aggressive cleanup without breaking intended behavior or the system's top-level runtime architecture, and do not write a completion report while any known in-scope actionable issue remains; only finish after the latest full-codebase scan is clear or remaining items are explicitly classified as blocked, unsafe, low-value, speculative, or approval-dependent, and the guarded test surface is green; then run $align-project-documents and $maintain-project-constraints to synchronize docs and AGENTS.md."

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

@@ -2,15 +2,18 @@
 
 ## Pass discipline
 
-Each pass must have:
+Each iteration must have:
 
 - a concrete quality target,
 - a bounded file/symbol scope,
+- one or more selected execution directions,
 - expected behavior-neutral outcome,
 - validation plan,
 - rollback point if evidence contradicts the change.
 
-Avoid starting a broad second pass before validating the first.
+An iteration is not "one work type", and it also does not need to include every direction every time. Within the selected scope, choose the subset of directions that has the best current confidence and leverage: naming, simplification, module boundaries, logging, and/or tests.
+
+Avoid starting a broad second iteration before validating the first, but do not stop after a validated iteration if known actionable quality issues remain anywhere in the in-scope codebase.
 
 ## Validation cadence
 
@@ -28,9 +31,13 @@ If validation fails:
 - keep regression coverage for real defects,
 - do not mask failures by weakening assertions.
 
-## Re-scan after each pass
+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.
+
+The final stopping condition also requires the relevant guarded test surface to be green; a partially red repository is not a completed refactor outcome.
 
-Inspect touched areas for:
+## Re-scan after each iteration
+
+Inspect the full known quality backlog for:
 
 - new naming drift from moved or extracted concepts,
 - duplicated logic that remains after extraction,
@@ -39,19 +46,30 @@ Inspect touched areas for:
 - tests that cover only the happy path,
 - documentation or `AGENTS.md` drift.
 
+Then choose the next execution directions with these priorities:
+
+1. highest confidence under current guardrails,
+2. strongest leverage for later deeper cleanup,
+3. lowest business-risk path toward broader system improvement.
+
 ## Continue when
 
 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 iteration instead.
+
+Prefer gradual outside-in progress: boundary cleanup, naming clarity, and guardrail strengthening should often come before deeper internal rewrites because they make the deeper work safer later.
+
 ## 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,13 +79,18 @@ 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:
 
 - passes completed,
+- execution directions selected per iteration,
 - validation commands and outcomes,
+- confirmation that the guarded test surface is green after the refactor,
 - 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/module-boundaries.md

@@ -21,6 +21,26 @@ Define:
 - which interfaces must remain stable,
 - which tests prove behavior did not change.
 
+## Macro architecture boundary
+
+For this skill, `macro architecture` means the whole system's runtime shape and operating model, such as:
+
+- major subsystems and their top-level responsibilities,
+- deployment/runtime boundaries,
+- persistence model and data ownership model,
+- inter-service or inter-process boundaries,
+- the overall execution logic by which the system operates end to end.
+
+The following do **not** count as macro-architecture changes by themselves:
+
+- moving logic between ordinary internal modules,
+- extracting helpers,
+- splitting a mixed-responsibility file into narrower local modules,
+- clarifying call boundaries inside one subsystem,
+- replacing duplicated local control flow with a shared internal abstraction.
+
+Treat those changes as ordinary refactoring work unless they also alter the top-level system model above.
+
 ## Safe split patterns
 
 - Move pure domain logic into a domain-owned helper module.

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,10 @@ 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.
+
+The intended end state is not merely "some tests passed for touched files". The refactor is complete only when the relevant guarded test surface for the repository remains green after the cleanup.
+
 ## Unit tests
 
 Use for:
@@ -76,3 +80,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.4",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",