@laitszkin/apollo-toolkit 3.1.7 → 3.1.8

package/CHANGELOG.md

@@ -7,6 +7,11 @@ All notable changes to this repository are documented in this file.
 ### Changed
 - None yet.
 
+## [v3.1.8] - 2026-04-23
+
+### Changed
+- Refine `iterative-code-quality` so module deep reads must scan each module through the available job lenses before choosing which refactors land, preventing scan phases from degrading into generic reading or low-value micro-fixes.
+
 ## [v3.1.7] - 2026-04-23
 
 ### Changed

package/iterative-code-quality/README.md

@@ -8,6 +8,7 @@ Improve an existing repository through a strict three-step loop of full-codebase
 - 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.
+- Defines deep-read as a job-oriented scan across naming, simplification, module boundaries, logging, testing, and staged unlock opportunities instead of generic reading.
 - 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.

package/iterative-code-quality/SKILL.md

@@ -24,7 +24,7 @@ description: >-
 ## Standards
 
 - 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.
+- 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 job-oriented 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.
 
@@ -42,14 +42,15 @@ For this skill, `macro architecture` means the system's top-level runtime shape
 - 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.
+- Build or refresh a module inventory and coverage ledger; every in-scope module starts as unvisited until it has received a job-oriented deep-read iteration with callers, callees, tests, logs, relevant contracts, and each available job lens 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.
+- Load `references/module-coverage.md` for module inventory, job-oriented deep-read coverage, easy-first ordering, and completion rules.
 
 ### 2) Choose this round's jobs and refactor
 
 - Choose jobs only after the latest full-codebase scan. Jobs are optional execution directions, not ordered workflow steps.
+- Treat module scanning and job choice as one linked activity: inspect the selected module through every available job lens before deciding which jobs actually land in this round.
 - 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.
@@ -63,7 +64,7 @@ For this skill, `macro architecture` means the system's top-level runtime shape
 
 Load references for this step only as needed:
 
-- `references/module-coverage.md` for choosing the next module and proving every in-scope module has been deeply read.
+- `references/module-coverage.md` for choosing the next module and proving every in-scope module has been deeply read through the available-job lenses.
 - `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.

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 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."
+  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, scan it through every available job lens, and only then decide which jobs actually land 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 job-oriented 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 through the available-job lenses, 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/iteration-gates.md

@@ -6,6 +6,7 @@ Each iteration must have:
 
 - a selected module or bounded module cluster,
 - a concrete quality target,
+- an explicit record of which job lenses were checked during the deep read,
 - a bounded file/symbol scope,
 - one or more selected execution directions,
 - expected behavior-neutral outcome,
@@ -43,6 +44,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,
+- modules that were read but not yet checked against every available job lens,
 - new naming drift from moved or extracted concepts,
 - duplicated logic that remains after extraction,
 - module boundaries that are still mixed,
@@ -110,6 +112,7 @@ The final report should make the stopping point auditable:
 - passes completed,
 - execution directions selected per iteration,
 - module or module cluster covered per iteration,
+- job lenses checked per iteration,
 - final module coverage ledger,
 - stage-gate verdict after each full-codebase re-scan,
 - validation commands and outcomes,

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

@@ -8,6 +8,8 @@ These are job-selection rules for Step 2 of the main skill loop. They are not wo
 
 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.
 
+Before choosing, the agent should first scan the selected module through every available job lens. Job selection happens after that scan; it is not a substitute for that scan.
+
 ## Available jobs
 
 - naming cleanup

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

@@ -6,6 +6,8 @@ Prevent the agent from repeatedly improving only familiar or easy files while un
 
 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.
 
+Deep-read here does not mean generic reading. It means scanning the module through each available job lens so the agent can identify whether naming cleanup, simplification, module-boundary cleanup, logging alignment, test addition, or staged unlock work is justified.
+
 ## Module inventory
 
 List every meaningful in-scope module before completion. A module may be:
@@ -33,7 +35,7 @@ Exclude generated, vendored, lock, build-output, snapshot, fixture-only, or expl
 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.
+- `deep-read`: callers, callees, tests, logs, contracts, core files, and all available job lenses 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.
@@ -68,7 +70,17 @@ A module iteration is not deep-read until the agent inspects:
 - configuration, persistence, and external-service contracts when relevant,
 - known TODOs, comments, or docs that describe current behavior.
 
+It also must inspect the module through each available job lens:
+
+- `naming cleanup`: are names hiding ownership, units, state, lifecycle, or intent?
+- `function simplification / extraction`: are there duplicated flows, hard-coded orchestration paths, or overly mixed functions?
+- `module-boundary cleanup`: are responsibilities mixed in ways that can be split safely?
+- `logging alignment`: are logs stale, misleading, or missing at important branch/outcome points?
+- `test addition`: are important behaviors, edges, or invariants weakly guarded?
+- `staged unlock work`: if the module is too coupled for direct cleanup, what is the next smaller unlock step?
+
 Do not mark a module `validated-clear` from a shallow file skim.
+Do not mark a module `validated-clear` until every available job lens has been checked and classified as one of: actionable now, unlock-first, deferred, excluded, or no meaningful issue found.
 
 ## Choosing the next module
 
@@ -77,9 +89,10 @@ 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.
+4. Scan that module through every available job lens before deciding what "this round" means.
+5. If the next unvisited module is high-risk and under-guarded, choose guardrail-building jobs first.
+6. If the next unvisited module is too coupled for direct cleanup, choose staged unlock work rather than skipping it.
+7. Return to the full-codebase scan after validation and update the ledger.
 
 Revisiting a familiar module is valid only when:
 
@@ -104,7 +117,7 @@ Keep clusters bounded. Do not use clustering to claim full-repository coverage w
 At the end of each iteration, answer:
 
 - Which module or module cluster was deeply read?
-- Which jobs were selected and why?
+- Which job lenses were checked, and 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`?

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

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-Build a factual map before changing code, then choose the highest-value quality improvements while tracking module-by-module deep-read coverage.
+Build a factual map before changing code, then choose the highest-value quality improvements while tracking module-by-module job-oriented deep-read coverage.
 
 ## Required scan
 
@@ -10,6 +10,7 @@ Build a factual map before changing code, then choose the highest-value quality
 - 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`.
+- For each module, scan through the available job lenses instead of treating scan as generic code reading.
 - 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.
 
@@ -31,6 +32,7 @@ For each candidate record:
 
 - file path and symbol name,
 - owning module or module cluster,
+- job lens that exposed the issue,
 - observed quality problem,
 - why it matters to maintainability or correctness confidence,
 - expected behavior-neutral change,

package/package.json

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