@laitszkin/apollo-toolkit 3.1.4 → 3.1.5

package/CHANGELOG.md

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

package/iterative-code-quality/README.md

@@ -14,6 +14,8 @@ Improve an existing repository through repeated, evidence-backed full-iteration
 - 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.

package/iterative-code-quality/SKILL.md

@@ -41,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.
@@ -74,6 +75,7 @@ Direction-selection rules:
 - 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:
 
@@ -111,6 +113,14 @@ For each iteration:
 - 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.
@@ -133,6 +143,7 @@ For each iteration:
 
 - 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.
@@ -163,7 +174,7 @@ Only write this report after the latest scan confirms there are no known actiona
 
 Return:
 
-1. Iterations completed and which execution directions were selected in each one.
+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 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."
+  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

@@ -52,6 +52,18 @@ Then choose the next execution directions with these priorities:
 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:
@@ -87,6 +99,7 @@ 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,

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

@@ -41,6 +41,8 @@ The following do **not** count as macro-architecture changes by themselves:
 
 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/package.json

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