@laitszkin/apollo-toolkit 3.1.3 → 3.1.5

package/CHANGELOG.md

@@ -7,6 +7,16 @@ All notable changes to this repository are documented in this file.
 ### Changed
 - None yet.
 
+## [v3.1.5] - 2026-04-23
+
+### Changed
+- Strengthen `iterative-code-quality` so large coupled or apparently core files trigger staged unlock work instead of passive stopping, and require a full-codebase stage-gate decision after every iteration to determine whether additional rounds are still needed.
+
+## [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

package/iterative-code-quality/README.md

@@ -1,17 +1,23 @@
 # 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.
 - 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.
+- Treats large coupled or apparently core files as staged unlock problems, not as automatic stop signals.
+- Runs a stage-gate full-codebase decision after every iteration to decide whether more rounds are still required.
 - 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 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.
+- 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 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.
+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
 
@@ -39,6 +41,7 @@ Load references only when they match the active pass:
 - `references/repository-scan.md`: scope mapping, generated-file exclusions, and quality backlog selection.
 - `references/naming-and-simplification.md`: variable renames, function simplification, reusable extraction, and behavior-preservation checks.
 - `references/module-boundaries.md`: single-responsibility split heuristics and safe module extraction rules.
+- `references/coupled-core-file-strategy.md`: staged unlock strategy for large, coupled, or apparently core files that should not become stop signals.
 - `references/logging-alignment.md`: stale log detection, missing log criteria, and behavior-neutral observability updates.
 - `references/testing-strategy.md`: risk-based unit, property, integration, and E2E coverage selection.
 - `references/iteration-gates.md`: multi-pass quality gates, stopping criteria, and validation cadence.
@@ -54,9 +57,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,15 +69,23 @@ 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.
+- When a file appears too coupled, too central, or too risky for a direct rewrite, treat that as a prompt to switch into staged unlock work rather than a reason to stop. Load `references/coupled-core-file-strategy.md` and choose the next smallest refactor that reduces future risk.
+
+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.
+- 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 pass.
+- Validate the touched scope before starting another iteration.
 
 ### 3) Rename for clarity without churn
 
@@ -96,10 +109,18 @@ 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.
 
+### 5.1) Handle large coupled or apparently core files through unlock work
+
+- Do not treat a large coupled file, a central orchestrator, or a historically fragile module as an automatic stop condition.
+- First ask: what is the next smallest refactor that lowers the risk of changing this area later without changing business behavior now?
+- Prefer unlock steps such as characterization tests, naming cleanup, type extraction, pure-function extraction, side-effect boundary isolation, read/write path separation, dependency seam introduction, and caller grouping.
+- Only stop when no such unlock step can be identified under current guardrails. If an unlock step exists, do it before reconsidering the larger refactor.
+- Use `references/coupled-core-file-strategy.md` whenever the current obstacle is "too coupled", "too central", or "too risky to touch directly".
+
 ### 6) Repair logging and observability drift
 
 - Compare log messages, event names, structured fields, metrics, and trace names against the current code ownership model.
@@ -118,11 +139,14 @@ 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 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.
+- 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.
+- Perform an explicit stage-gate decision after that full-codebase scan: decide whether all known in-scope issues are now resolved, whether remaining issues are only legitimately deferred categories, or whether another iteration is required right now.
+- 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.
@@ -138,7 +162,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.
@@ -146,11 +170,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. If any such issue remains, continue iterating instead of reporting completion.
+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, which execution directions were selected in each one, and the stage-gate decision after each full-codebase re-scan.
 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; 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."
+  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, and when a file feels too coupled or too central switch into staged unlock work instead of stopping; use tests or other reliable guardrails to justify aggressive cleanup without breaking intended behavior or the system's top-level runtime architecture, run a full-codebase stage-gate after each iteration to decide whether another round is required, 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/coupled-core-file-strategy.md

@@ -0,0 +1,69 @@
+# Staged Strategy For Large Coupled Or Apparently Core Files
+
+## Purpose
+
+Teach the agent how to keep making progress when a file feels too central, too coupled, or too risky to refactor directly.
+
+The correct response is usually not "stop". The correct response is "find the next unlock step".
+
+## Core rule
+
+A large coupled file is a **decomposition signal**, not a **completion blocker**.
+
+If a safe, behavior-preserving unlock step exists under current guardrails, take that step now instead of deferring the whole area.
+
+## First questions to ask
+
+When a file feels untouchable, ask:
+
+- Which parts are pure logic and which parts are side effects?
+- Which names or local concepts are blocking understanding?
+- Which behavior can be locked down with characterization tests?
+- Which dependency seams can be introduced without changing behavior?
+- Which caller groups or workflow slices can be isolated first?
+- Which refactor would most reduce the cost of the next refactor?
+
+## Typical unlock sequence
+
+Pick one or more of these, in the order justified by current evidence:
+
+1. Add characterization or regression tests around current behavior.
+2. Rename confusing variables, flags, intermediate states, and helper names.
+3. Extract constants, schemas, types, and small pure transformations.
+4. Separate read path from write path, or decision logic from side effects.
+5. Isolate external calls, persistence, and logging behind clearer seams.
+6. Group callers by responsibility and split one slice at a time.
+7. Move one coherent responsibility into a new internal module.
+8. Re-scan and decide whether a deeper split is now safer.
+
+## What not to do
+
+Avoid these anti-patterns:
+
+- declaring the area blocked just because it is important,
+- attempting a full rewrite before guardrails exist,
+- preserving obvious local design debt only because the file is central,
+- escalating ordinary internal decomposition into a fake macro-architecture concern,
+- mixing unlock work with unrelated style churn.
+
+## Choosing the next step
+
+Prefer the next step that maximizes:
+
+1. confidence under existing tests or quickly addable tests,
+2. leverage for future deeper cleanup,
+3. reduction in coupling or cognitive load,
+4. low risk to current business behavior.
+
+If two steps are both safe, choose the one that makes the next iteration easier.
+
+## Completion rule for coupled files
+
+Do not ask "Can I solve the whole file now?"
+
+Ask:
+
+- "Can I make this file meaningfully easier to change in the next iteration?"
+- "Can I reduce coupling, clarify ownership, or improve guardrails right now?"
+
+If the answer is yes, continue iterating.

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, but do not stop after a validated pass if known actionable quality issues remain anywhere in the in-scope codebase.
+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
 
@@ -30,9 +33,11 @@ If validation fails:
 
 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
+The final stopping condition also requires the relevant guarded test surface to be green; a partially red repository is not a completed refactor outcome.
+
+## Re-scan after each iteration
 
-Inspect touched areas and the full known quality backlog for:
+Inspect the full known quality backlog for:
 
 - new naming drift from moved or extracted concepts,
 - duplicated logic that remains after extraction,
@@ -41,6 +46,24 @@ Inspect touched areas and the full known quality backlog 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.
+
+## Stage-gate after each iteration
+
+After every validated iteration, run a deliberate full-codebase decision pass:
+
+1. Re-scan the repository and refresh the known quality backlog.
+2. Ask whether any known in-scope actionable issue still remains.
+3. If yes, decide whether it should be addressed in the very next iteration or whether first-step unlock work is needed.
+4. If the obstacle is a large, coupled, or central file, do not stop there; switch to staged unlock work and continue.
+5. Only declare the repository iteration-complete when the re-scan shows no remaining actionable in-scope issue except items that are explicitly deferred under the allowed stop categories.
+
+This stage-gate is mandatory. A validated local change does not by itself mean the repository is done.
+
 ## Continue when
 
 Repeat the cycle when:
@@ -52,7 +75,9 @@ Repeat the cycle when:
 - 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.
+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
 
@@ -73,7 +98,10 @@ If a remaining candidate cannot be placed in one of these categories, it is stil
 The final report should make the stopping point auditable:
 
 - passes completed,
+- execution directions selected per iteration,
+- stage-gate verdict after each full-codebase re-scan,
 - 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,

package/iterative-code-quality/references/module-boundaries.md

@@ -21,6 +21,28 @@ 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.
+
+Large coupled or central files should therefore be treated as decomposition problems, not as automatic macro-architecture blockers. If the top-level system model remains intact, prefer staged internal cleanup over stopping.
+
 ## Safe split patterns
 
 - Move pure domain logic into a domain-owned helper module.

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

@@ -8,6 +8,8 @@ For every non-trivial pass, ask what could regress silently if the cleanup were
 
 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:

package/package.json

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