@laitszkin/apollo-toolkit 3.1.5 → 3.1.7

package/CHANGELOG.md

@@ -7,6 +7,16 @@ All notable changes to this repository are documented in this file.
 ### Changed
 - None yet.
 
+## [v3.1.7] - 2026-04-23
+
+### Changed
+- Enhance `iterative-code-quality` with module inventory and coverage-ledger guidance so agents start from the easiest useful modules, deeply read each in-scope module before completion, and return to scanning whenever unvisited modules remain.
+
+## [v3.1.6] - 2026-04-23
+
+### Changed
+- Rewrite `iterative-code-quality` around a strict three-step loop of full-codebase scan, per-round job selection/refactor, and final doc/constraint sync, while moving job-specific execution guidance into reference documents so the main skill no longer reads like a serial workflow.
+
 ## [v3.1.5] - 2026-04-23
 
 ### Changed

package/iterative-code-quality/README.md

@@ -1,30 +1,36 @@
 # iterative-code-quality
 
-Improve an existing repository through repeated, evidence-backed full-iteration refactors while preserving intended business behavior and the system's top-level macro architecture.
+Improve an existing repository through a strict three-step loop of full-codebase scan, job-based refactor, and final documentation/constraint sync 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.
+- Runs a repository-wide scan before every refactor round and refreshes a concrete quality backlog.
+- Uses a strict three-step loop: scan the codebase, choose this round's jobs and refactor, then update docs/constraints only when no actionable gap remains.
+- Keeps job execution guidance in focused reference documents instead of embedding every job as a workflow step in the main skill.
+- Builds a module inventory and coverage ledger so every in-scope module receives a deep-read iteration before completion.
+- Starts from the easiest useful modules first, while preserving the rule that unvisited modules cannot be skipped before completion.
 - 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.
+- Does not require pre-existing tests before every refactor; for high-risk under-guarded areas, it treats test addition as the next unlock direction.
 - 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.
+- Uses explicit next-job selection conditions from references so the agent can decide more concretely whether naming, simplification, modularization, logging, testing, or unlock work should happen next.
 - 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.
+- Forbids completion while any in-scope module remains unvisited, even if already-read modules look clean.
 - 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
 
-- `SKILL.md`: Main iterative workflow, dependencies, guardrails, and output contract.
+- `SKILL.md`: Main three-step loop, dependencies, guardrails, and output contract.
 - `agents/openai.yaml`: Agent interface metadata and default prompt.
-- `references/`: Focused guides for scanning, naming, simplification, module boundaries, logging, testing, and iteration gates.
+- `references/`: Focused guides for scanning, module coverage, job selection, naming, simplification, module boundaries, logging, testing, unlock work, and iteration gates.
 
 ## Typical usage
 

package/iterative-code-quality/SKILL.md

@@ -1,183 +1,108 @@
 ---
 name: iterative-code-quality
 description: >-
-  Improve an existing codebase through repeated evidence-based code-quality
-  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
-  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.
+  Improve an existing codebase through repeated evidence-based repository-wide
+  scans, module-by-module deep-read coverage, and behavior-safe refactors until
+  no known in-scope actionable quality issue or unvisited in-scope module
+  remains: clarify poor names, simplify or extract reusable functions, split
+  mixed-responsibility code, repair stale or missing logs, and add high-value
+  tests where guardrails are missing, while preserving intended business
+  behavior and the system's macro architecture. Use when users ask for
+  comprehensive refactoring, code cleanup, maintainability hardening, naming
+  cleanup, log alignment, or test coverage improvement across a repository.
 ---
 
 # Iterative Code Quality
 
 ## Dependencies
 
-- Required: `align-project-documents` and `maintain-project-constraints` after implementation changes are complete.
-- Conditional: `systematic-debug` when a new or existing test reveals a real business-logic defect that must be fixed.
-- Optional: `discover-edge-cases` for high-risk boundary exploration before choosing missing tests; `improve-observability` for complex telemetry design.
-- Fallback: If required completion dependencies are unavailable, finish code and tests, then report exactly which documentation or constraint sync step could not run.
+- Required: `align-project-documents` and `maintain-project-constraints` after the repository is truly iteration-complete.
+- Conditional: `systematic-debug` when a newly added or existing test exposes a real business-logic defect that must be fixed at the true owner.
+- Optional: `discover-edge-cases` for high-risk boundary exploration before adding tests; `improve-observability` for non-trivial telemetry design.
+- Fallback: If required completion dependencies are unavailable, finish code and validation first, then report exactly which documentation or constraint-sync action could not run.
 
 ## 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: 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.
+- Evidence: Read repository docs, project constraints, source, tests, logs, build scripts, entrypoints, and nearby abstractions before editing; every refactor and every new test must be justified by code context.
+- Execution: Run a continuous three-step loop of full-codebase scan → choose this round's jobs and refactor → if and only if the latest full-codebase scan is clear, update docs and constraints; otherwise return to scanning immediately. Maintain a module inventory and coverage ledger so every in-scope module receives a deep-read iteration before completion. Do not treat jobs as workflow steps. Do not produce a completion report while any known in-scope actionable issue or unvisited in-scope module remains.
+- Quality: Resolve as many inherited quality problems as safely possible without changing intended behavior or the system's macro architecture. Do not require pre-existing tests before every safe refactor; if an area is high-risk and weakly guarded, add the missing guardrails as part of the work instead of treating the area as untouchable.
+- Output: Return iteration-by-iteration decisions, selected jobs, module coverage status, changed files, behavior-preservation evidence, tests and guardrails added, validation results, and docs/constraint sync status only after the latest scan shows no remaining known actionable in-scope issue and no unvisited in-scope module.
 
-## Goal
+## Mission
 
-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.
+Leave the repository materially cleaner by continuously scanning the whole codebase, landing the highest-value safe refactors available at each moment, and repeating until there is no known in-scope actionable quality gap left to fix.
 
-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, internal call-boundary cleanup, and local module splits do not count as macro-architecture changes by themselves.
 
-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.
+## Three-Step Loop
 
-## Required Reference Loading
+### 1) Scan the repository
 
-Load references only when they match the active pass:
+- Read root guidance first: `AGENTS.md`, `README*`, package manifests, task runners, CI/test config, and major project docs.
+- Map runtime entrypoints, domain modules, external integrations, logging utilities, and current test surfaces.
+- Exclude generated, vendored, lock, build-output, fixture, or snapshot files unless evidence shows they are human-maintained source.
+- Build or refresh a concrete repository-wide backlog of known actionable quality issues.
+- Build or refresh a module inventory and coverage ledger; every in-scope module starts as unvisited until it has received a deep-read iteration with callers, callees, tests, logs, and relevant contracts inspected.
+- Re-scan the full codebase after every landed iteration, not only the files just changed.
+- Load `references/repository-scan.md` for the scan checklist and backlog shaping rules.
+- Load `references/module-coverage.md` for module inventory, deep-read coverage, easy-first ordering, and completion rules.
 
-- `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.
+### 2) Choose this round's jobs and refactor
 
-## Workflow
+- Choose jobs only after the latest full-codebase scan. Jobs are optional execution directions, not ordered workflow steps.
+- Select the smallest set of jobs that can safely improve the currently selected module or module cluster under current guardrails.
+- Prefer easy-first module ordering: start from low-risk, high-confidence modules when doing so builds context, tests, naming clarity, or seams that make harder modules safer later.
+- Do not keep revisiting familiar modules while other in-scope modules remain unvisited unless the familiar module blocks the next unvisited module's safe deep read.
+- Prefer smaller, high-confidence refactors that reduce risk and prepare the ground for deeper later cleanup.
+- If a desired refactor is high-risk and weakly guarded, make guardrail-building part of this round instead of stopping.
+- If a file feels too coupled, too central, or too risky for a direct rewrite, do staged unlock work rather than declaring the area blocked.
+- Read all directly affected callers, tests, interfaces, and logs before editing.
+- Validate from narrow to broad after each bounded round, then perform a full-codebase stage-gate decision:
+  - if any known in-scope actionable issue still remains or any in-scope module has not received a deep-read iteration, return to Step 1;
+  - only continue to Step 3 when the latest scan is clear.
 
-### 1) Establish the repository baseline
+Load references for this step only as needed:
 
-- Read root guidance first: `AGENTS.md`, `README*`, major docs, package manifests, task runners, CI configs, and test setup.
-- Map runtime entrypoints, domain modules, external integrations, logging/telemetry utilities, and existing test suites.
-- Identify generated, vendored, lock, build-output, fixture, or snapshot files; exclude them from refactoring unless evidence shows they are human-maintained source.
-- Run or inspect the most relevant existing validation commands before editing when feasible, so pre-existing failures are distinguishable from new regressions.
-- 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.
+- `references/module-coverage.md` for choosing the next module and proving every in-scope module has been deeply read.
+- `references/job-selection.md` for next-job choice conditions and tie-breakers.
+- `references/naming-and-simplification.md` for naming cleanup and function simplification/extraction.
+- `references/module-boundaries.md` for single-responsibility module cleanup.
+- `references/logging-alignment.md` for stale or missing log repair.
+- `references/testing-strategy.md` for unit, property, integration, and E2E test strategy.
+- `references/coupled-core-file-strategy.md` for staged unlock work on large coupled or apparently core files.
+- `references/iteration-gates.md` for validation cadence, stage-gate rules, and stop criteria.
 
-### 2) Execute continuous full scans with selectable directions
+### 3) Update project documents and constraints
 
-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.
+Only enter this step when the latest full-codebase scan confirms there is no remaining known actionable in-scope quality issue and every in-scope module has received a deep-read iteration, except items explicitly classified as blocked, unsafe, speculative, low-value, excluded, or approval-dependent.
 
-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.
-3. Single-responsibility module splits for oversized or mixed-concern code.
-4. Logging alignment for stale, misleading, missing, or low-context diagnostics.
-5. Risk-based test coverage for high-value business logic and boundary cases.
-
-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 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 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
-
-- Rename only when the current name hides domain meaning, confuses ownership, conflicts with real units, or makes tests/logs misleading.
-- Prefer names that encode domain role, unit, lifecycle stage, or canonical owner.
-- Update all references, tests, fixtures, structured log fields, docs, and comments that describe the renamed concept.
-- Avoid renaming stable public API fields or persisted schema names unless the user explicitly requested a breaking migration.
-- Use `references/naming-and-simplification.md` before broad rename passes.
-
-### 4) Simplify and extract reusable functions
-
-- Simplify functions when branches, temporary state, repeated transformations, or hard-coded workflows obscure the invariant.
-- 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
-
-- 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 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.
-- Fix stale terminology after renames or refactors so logs describe the live workflow.
-- Add logs only at high-value decision points: branch selection, skipped work, external dependency outcome, persistence side effect, retry/rollback, and final outcome.
-- Use structured fields already accepted by the project; never log secrets, tokens, full sensitive payloads, or personal data.
-- Add tests or assertions for important log fields when the project has log-capture helpers.
-- Use `references/logging-alignment.md` for detailed criteria.
-
-### 7) Add high-value tests
-
-- Start from risk, not coverage percentage.
-- Prioritize tests for business rules, state transitions, error handling, extracted helpers, edge cases, observability contracts, and integration boundaries.
-- Use unit tests for local logic, property-based tests for invariants and generated input spaces, integration tests for cross-module chains, and E2E tests only when external services are stable or can be controlled reliably.
-- Mock or fake external services unless the real service contract is the subject under test.
-- 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 gradually from outside to inside until the repository is clear of known actionable issues
-
-- 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.
-
-### 9) Synchronize docs and constraints
-
-After code and tests are complete:
-
-- Invoke `align-project-documents` when README, docs, architecture notes, debugging docs, setup instructions, or test guidance may have drifted.
-- Invoke `maintain-project-constraints` to verify `AGENTS.md` still reflects architecture, business flow, common commands, macro purpose, and coding conventions.
-- Update only documentation that is affected by real code, command, logging, or test changes.
+- Run `align-project-documents` when README, architecture notes, setup docs, debugging docs, or test guidance may have drifted.
+- Run `maintain-project-constraints` to verify `AGENTS.md` still matches the repository's real architecture, business flow, commands, and conventions.
+- Update only the documentation and constraints that changed in reality because of the refactor.
 
 ## Hard Guardrails
 
-- Do not change intended business logic while refactoring.
-- 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 change intended business logic while refactoring, except to fix a real defect exposed by tests and verified at the true owner.
+- Do not change the system's macro architecture unless the user explicitly expands 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.
-- Do not add E2E tests that depend on unreliable external services when a controlled integration test can prove the same business risk.
+- Do not stop early just because a file is large, central, or historically fragile; if a safe unlock step exists, that is the next job.
+- Do not stop before every in-scope module has been inventoried, deeply read, and either improved, validated as clear, or explicitly deferred/excluded with evidence.
+- Do not weaken tests to make a refactor pass; fix the real defect or update stale expectations to stable invariants.
+- Do not add style-only churn that does not improve naming, modularity, observability, reuse, or guardrail strength.
+- Do not add unreliable E2E coverage when a controlled integration or characterization test can prove the same risk more safely.
 
 ## 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.
+Only report completion after Step 3 is done, the latest Step 1 scan is clear, and the module coverage ledger has no unvisited in-scope module.
 
 Return:
 
-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.
-5. Validation commands and results.
-6. Documentation and `AGENTS.md` synchronization status.
-7. Remaining quality gaps, blockers, or deferred architecture/product decisions.
+1. Iterations completed and the jobs selected in each iteration.
+2. Stage-gate verdict after each full-codebase re-scan.
+3. Module coverage ledger summary: modules deep-read, improved, validated-clear, deferred, or excluded.
+4. Key files changed and the quality issue each change resolved.
+5. Business behavior preservation evidence.
+6. Tests or other guardrails added or updated, including property/integration/E2E `N/A` reasons where relevant.
+7. Validation commands and results.
+8. Documentation and `AGENTS.md` synchronization status.
+9. Remaining blocked or approval-dependent items, if any.

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, 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."
+  default_prompt: "Use $iterative-code-quality as a strict three-step loop. Step 1: scan the full repository, refresh the actionable quality backlog, and maintain a module inventory plus coverage ledger. Step 2: choose this round's module or bounded module cluster, then choose jobs from the reference documents and land the highest-value safe refactors now; start from the easiest useful unvisited modules, jobs are selectable directions rather than workflow steps, and if a high-risk area is weakly guarded add the missing tests or other guardrails instead of stopping. If a file is too coupled or too central for direct cleanup, switch to staged unlock work and keep progressing. After validation, run a full-codebase stage-gate; if any known in-scope actionable issue remains or any in-scope module has not received a deep-read iteration, go back to Step 1 immediately. Step 3: only when the latest full-codebase scan is clear and every in-scope module is deeply read, run $align-project-documents and $maintain-project-constraints to synchronize docs and AGENTS.md. Preserve intended business behavior and the system's macro architecture, keep the guarded test surface green, and do not write a completion report while actionable gaps or unvisited modules still exist."

package/iterative-code-quality/references/coupled-core-file-strategy.md

@@ -12,6 +12,8 @@ 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.
 
+If guardrails are too weak for direct cleanup, strengthening them is itself the next unlock step.
+
 ## First questions to ask
 
 When a file feels untouchable, ask:
@@ -57,6 +59,8 @@ Prefer the next step that maximizes:
 
 If two steps are both safe, choose the one that makes the next iteration easier.
 
+If the file is high-risk and under-tested, prefer adding the smallest useful characterization tests before attempting deeper structural edits.
+
 ## Completion rule for coupled files
 
 Do not ask "Can I solve the whole file now?"

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

@@ -4,6 +4,7 @@
 
 Each iteration must have:
 
+- a selected module or bounded module cluster,
 - a concrete quality target,
 - a bounded file/symbol scope,
 - one or more selected execution directions,
@@ -15,6 +16,8 @@ An iteration is not "one work type", and it also does not need to include every
 
 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.
 
+Do not stop after a validated iteration if any in-scope module remains unvisited in the module coverage ledger.
+
 ## Validation cadence
 
 Run validation from narrow to broad:
@@ -39,6 +42,7 @@ The final stopping condition also requires the relevant guarded test surface to
 
 Inspect the full known quality backlog for:
 
+- modules that are still unvisited or only shallowly read,
 - new naming drift from moved or extracted concepts,
 - duplicated logic that remains after extraction,
 - module boundaries that are still mixed,
@@ -52,15 +56,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.
 
+Use `references/job-selection.md` to convert those priorities into a concrete next-job choice.
+
 ## 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.
+2. Refresh the module coverage ledger and identify unvisited in-scope modules.
+3. Ask whether any known in-scope actionable issue still remains.
+4. If yes, decide whether it should be addressed in the very next iteration or whether first-step unlock work is needed.
+5. If the obstacle is a large, coupled, or central file, do not stop there; switch to staged unlock work and continue.
+6. Only declare the repository iteration-complete when the re-scan shows no remaining actionable in-scope issue and no unvisited in-scope module except items that are explicitly deferred or excluded under the allowed stop categories.
 
 This stage-gate is mandatory. A validated local change does not by itself mean the repository is done.
 
@@ -69,6 +76,7 @@ This stage-gate is mandatory. A validated local change does not by itself mean t
 Repeat the cycle when:
 
 - any known in-scope actionable quality issue remains unresolved,
+- any in-scope module remains unvisited,
 - 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,
@@ -93,12 +101,16 @@ Stop only when there are no unresolved known in-scope actionable issues. Any rem
 
 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.
 
+If an in-scope module has not received a deep-read iteration, it is still an actionable coverage gap even when the already-read modules look clean.
+
 ## Completion evidence
 
 The final report should make the stopping point auditable:
 
 - passes completed,
 - execution directions selected per iteration,
+- module or module cluster covered per iteration,
+- final module coverage ledger,
 - stage-gate verdict after each full-codebase re-scan,
 - validation commands and outcomes,
 - confirmation that the guarded test surface is green after the refactor,

package/iterative-code-quality/references/job-selection.md

@@ -0,0 +1,73 @@
+# Job Selection Guide
+
+## Purpose
+
+Help the agent choose the next execution direction after each full-codebase re-scan.
+
+These are job-selection rules for Step 2 of the main skill loop. They are not workflow steps.
+
+The goal is not to force one permanent order. The goal is to choose the next job that most safely improves the selected module or module cluster and unlocks later work.
+
+## Available jobs
+
+- naming cleanup
+- function simplification / extraction
+- module-boundary cleanup
+- logging alignment
+- test addition
+- staged unlock work
+
+## Choose `naming cleanup` when
+
+- confusing names are the main thing blocking understanding,
+- flags, units, lifecycle states, or ownership terms are misleading,
+- better naming would clearly reduce the risk of a later deeper refactor.
+
+## Choose `function simplification / extraction` when
+
+- duplicated logic exists across multiple call sites,
+- one function mixes too many concerns,
+- control flow is currently the main complexity bottleneck,
+- extracting a helper would make the next test or split easier.
+
+## Choose `module-boundary cleanup` when
+
+- one file or module clearly has multiple reasons to change,
+- local responsibilities are already visible enough to separate,
+- a safe split would reduce repeated touching of unrelated concerns.
+
+## Choose `logging alignment` when
+
+- stale or missing diagnostics are the main blocker to safe validation,
+- later refactors would be safer if branch decisions and outcomes were easier to observe,
+- observability drift is currently hiding the real ownership model.
+
+## Choose `test addition` when
+
+- the target area is high-risk and weakly guarded,
+- desired cleanup is blocked mainly by missing behavior locks,
+- coupling spans multiple modules and needs characterization before change,
+- regression risk is too high to justify deeper refactors without stronger coverage.
+
+## Choose `staged unlock work` when
+
+- the file feels too central or too coupled for direct cleanup,
+- no safe full refactor exists yet, but a preparatory step does,
+- you can reduce risk through naming, seam extraction, type extraction, side-effect isolation, or caller grouping,
+- the best next move is to make a future refactor cheaper rather than solve the whole area now.
+
+## Tie-breakers
+
+If multiple jobs are plausible, prefer the one that:
+
+1. increases safety for the next iteration,
+2. reduces cognitive load fastest,
+3. removes the strongest blocker to a deeper future refactor,
+4. helps an unvisited module reach deep-read coverage,
+5. preserves behavior with the clearest available guardrails.
+
+## Hard rule
+
+If a high-risk area lacks enough guardrails, `test addition` or another guardrail-building job should usually win before a deeper structural refactor.
+
+If any in-scope module remains unvisited, choose jobs that help the next easiest useful unvisited module become deeply read, improved, or validated-clear before spending another round on already-familiar areas.

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

@@ -0,0 +1,113 @@
+# Module Coverage And Deep-Read Iterations
+
+## Purpose
+
+Prevent the agent from repeatedly improving only familiar or easy files while untouched modules remain unexamined.
+
+Use this reference in Step 1 to build the module inventory and in Step 2 to choose which module or module cluster receives the next deep-read iteration.
+
+## Module inventory
+
+List every meaningful in-scope module before completion. A module may be:
+
+- a package, app, service, route group, command group, worker, or library,
+- a domain folder with a clear responsibility,
+- a runtime entrypoint plus its owned helpers,
+- a testable subsystem with stable callers and contracts.
+
+Record each module with:
+
+- module name and path roots,
+- primary responsibility,
+- entrypoints and public interfaces,
+- key callers and callees,
+- tests and guardrails,
+- logging or telemetry surfaces,
+- risk level and estimated ease,
+- current coverage status.
+
+Exclude generated, vendored, lock, build-output, snapshot, fixture-only, or explicitly out-of-scope areas only with evidence.
+
+## Coverage ledger statuses
+
+Use simple statuses so stopping conditions are auditable:
+
+- `unvisited`: inventoried but not deeply read yet.
+- `deep-read`: callers, callees, tests, logs, contracts, and core files were inspected with enough context to judge quality.
+- `refactored`: at least one behavior-neutral improvement landed for this module.
+- `validated-clear`: deep read found no actionable in-scope quality issue worth changing now.
+- `deferred`: an issue exists but is blocked, unsafe, speculative, approval-dependent, or requires macro-architecture/product scope.
+- `excluded`: not human-maintained source or outside the user's requested scope.
+
+Completion is not allowed while any in-scope module remains `unvisited`.
+
+## Easy-first module ordering
+
+Start with the easiest useful modules when that reduces risk:
+
+- small surface area,
+- clear ownership,
+- local tests or cheap guardrails,
+- limited side effects,
+- low public API or persistence risk,
+- likely to clarify names, tests, boundaries, or seams used by harder modules.
+
+Do not confuse easy-first with low-value churn. The chosen module should either resolve real quality issues or create context/guardrails that make later modules safer.
+
+If multiple modules are equally easy, prefer the one that unlocks harder modules by improving shared naming, helpers, tests, logging, or dependency seams.
+
+## Deep-read requirements
+
+A module iteration is not deep-read until the agent inspects:
+
+- module entrypoints and public interfaces,
+- internal core files and responsibility boundaries,
+- key callers and downstream callees,
+- tests, fixtures, mocks, and validation commands,
+- logs, metrics, tracing, and error messages,
+- configuration, persistence, and external-service contracts when relevant,
+- known TODOs, comments, or docs that describe current behavior.
+
+Do not mark a module `validated-clear` from a shallow file skim.
+
+## Choosing the next module
+
+After every iteration:
+
+1. Re-scan the module ledger.
+2. Prefer an `unvisited` module unless a just-touched module must be stabilized before moving on.
+3. Choose the easiest useful `unvisited` module that can be deeply read and improved or validated now.
+4. If the next unvisited module is high-risk and under-guarded, choose guardrail-building jobs first.
+5. If the next unvisited module is too coupled for direct cleanup, choose staged unlock work rather than skipping it.
+6. Return to the full-codebase scan after validation and update the ledger.
+
+Revisiting a familiar module is valid only when:
+
+- it blocks safe deep reading of an unvisited module,
+- a previous refactor created follow-up drift that must be stabilized,
+- validation exposed a real defect or stale contract,
+- cross-module cleanup requires touching it together with the next module.
+
+## Module cluster iterations
+
+One iteration may cover a small cluster of modules when they share one boundary or invariant, such as:
+
+- a command and its parser,
+- a route and its service,
+- a domain module and its test helpers,
+- an integration wrapper and its local fake.
+
+Keep clusters bounded. Do not use clustering to claim full-repository coverage without deep context.
+
+## Stage-gate questions
+
+At the end of each iteration, answer:
+
+- Which module or module cluster was deeply read?
+- Which jobs were selected and why?
+- What quality issue was fixed, or why is the module validated-clear?
+- Which guardrails prove behavior was preserved?
+- Which modules remain `unvisited`?
+- Which module is the next easiest useful target?
+
+If any in-scope module remains `unvisited`, the correct action is to return to Step 1, not to finish.

package/iterative-code-quality/references/repository-scan.md

@@ -2,13 +2,14 @@
 
 ## Purpose
 
-Build a factual map before changing code, then choose the highest-value quality improvements.
+Build a factual map before changing code, then choose the highest-value quality improvements while tracking module-by-module deep-read coverage.
 
 ## Required scan
 
 - Read `AGENTS.md`, `README*`, project docs, manifests, task runners, CI configs, and test setup.
 - List entrypoints: CLI commands, servers, workers, jobs, frontend routes, scripts, libraries, or public packages.
 - Identify core domain modules, external integrations, persistence boundaries, logging utilities, and test helpers.
+- Create a module inventory and coverage ledger using `references/module-coverage.md`.
 - Inspect current git state before editing so unrelated user changes are not overwritten.
 - Identify generated, vendored, lock, snapshot, build-output, and fixture files; exclude them from refactoring unless they are human-maintained source.
 
@@ -29,6 +30,7 @@ Prioritize files or functions with:
 For each candidate record:
 
 - file path and symbol name,
+- owning module or module cluster,
 - observed quality problem,
 - why it matters to maintainability or correctness confidence,
 - expected behavior-neutral change,
@@ -57,3 +59,5 @@ Score each candidate by:
 4. **Blast radius**: number of modules, public contracts, and migrations affected.
 
 Start with high-impact, high-confidence, low-blast-radius items. Escalate broad changes only when smaller passes cannot resolve the root problem.
+
+Do not finish from backlog scoring alone. Completion also requires the module coverage ledger to show that every in-scope module has been deeply read and either improved, validated-clear, deferred, or excluded with evidence.

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

@@ -8,6 +8,11 @@ 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.
 
+Do not require pre-existing tests before every refactor. Instead:
+
+- if existing guardrails are already sufficient, proceed;
+- if the area is high-risk and guardrails are weak, add the smallest high-value tests first and treat that as progress toward the refactor.
+
 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
@@ -27,6 +32,8 @@ Good oracles:
 - exact error class or reason code,
 - emitted side effect or explicit lack of side effect.
 
+For high-risk legacy code with weak coverage, characterization-style unit tests are often the first unlock step even before the larger cleanup happens.
+
 ## Property-based tests
 
 Use when logic has invariants or broad input space:
@@ -51,6 +58,8 @@ Use when the risk spans modules:
 
 For external services, prefer mocks, fakes, local emulators, or recorded stable fixtures unless the real contract is explicitly under test.
 
+When risk comes from multi-module coupling rather than one local function, integration coverage is often the best guardrail to add before refactoring.
+
 ## E2E tests
 
 Use only when:
@@ -81,3 +90,4 @@ Consider:
 - 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.
+- If stable guardrails do not yet exist for a high-risk area, create them as the next execution direction instead of treating the refactor as blocked forever.

package/package.json

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