@laitszkin/apollo-toolkit 3.1.7 → 3.2.0

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
@@ -64,10 +66,13 @@ If multiple jobs are plausible, prefer the one that:
 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.
+5. matches the agent's self-assessed ability to understand, execute, and repair the change under current evidence,
+6. 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 the area is difficult but the agent can explain the behavior, affected contracts, rollback path, and available tests clearly, do not downgrade confidence just because the refactor is non-trivial. Strong guardrails mean accidental breakage should be repaired by returning the test suite to green, not avoided by leaving an actionable quality issue in place.
+
 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

@@ -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/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.
 
+Confidence decisions must include the agent's own ability to understand and complete the refactor, not only the apparent difficulty of the code. Strong tests, characterization coverage, narrow rollback points, and clear validation commands are objective support: if the refactor breaks behavior, the agent should use the failing guardrails to repair the true owner and return the suite to green instead of treating the task as impossible.
+
 Do not require pre-existing tests before every refactor. Instead:
 
 - if existing guardrails are already sufficient, proceed;
@@ -89,5 +91,5 @@ Consider:
 - Preserve failing seeds or examples from property-based tests.
 - Do not weaken existing tests to fit the refactor.
 - If old tests asserted implementation details, rewrite them around stable behavior while preserving the business invariant.
-- Once stable guardrails exist, do not refuse a maintainability-improving refactor purely because confidence feels lower than ideal; let the guardrails decide.
+- Once stable guardrails exist, do not refuse a maintainability-improving refactor purely because confidence feels lower than ideal; combine self-assessed ability with the objective safety net and 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.7",
+  "version": "3.2.0",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",