@laitszkin/apollo-toolkit 3.1.8 → 3.2.0

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

@@ -0,0 +1,133 @@
+# Performance Iteration Gates And Stopping Criteria
+
+## Pass discipline
+
+Each iteration must have:
+
+- a selected module or bounded module cluster,
+- a concrete performance target,
+- an explicit record of which performance job lenses were checked during the deep read,
+- a bounded file/symbol scope,
+- one or more selected execution directions,
+- baseline evidence or a reason measurement is unavailable,
+- a confidence assessment covering the agent's own ability to complete the optimization, the task's inherent difficulty, objective guardrail strength, benchmark quality, and rollback or repair paths,
+- expected behavior-preserving outcome,
+- validation plan,
+- rollback point if evidence contradicts the change.
+
+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 evidence and leverage: measurement, complexity, IO, caching, allocation, concurrency, and/or staged unlock work.
+
+Confidence is not a synonym for "easy". Assess whether the agent has enough understanding, skill, workload context, tests, benchmarks, validation commands, and recovery path to complete the optimization safely. A hard task can still be high-confidence when strong guardrails, characterization coverage, and clear rollback let the agent repair mistakes by making the guarded behavior green again.
+
+Avoid starting a broad second iteration before validating the first, but do not stop after a validated iteration if known actionable performance 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:
+
+1. Formatter or type check for touched files when available.
+2. Unit tests for touched helpers and modules.
+3. Benchmarks, profiler runs, query-count checks, or operation-count checks for the optimized path when available.
+4. Integration tests for affected chains.
+5. Broader suite or build once multiple passes interact.
+
+If validation fails:
+
+- determine whether the failure is pre-existing, stale test expectation, flaky benchmark, test isolation issue, or real product bug,
+- fix the true owner,
+- keep regression coverage for real defects,
+- do not mask failures by weakening assertions or widening benchmark budgets without evidence.
+
+If validation passes and the performance plus correctness guardrails meaningfully cover the changed behavior, do not keep a known bottleneck in place purely because of subjective confidence concerns. Reassess whether the agent has enough capability and objective support to proceed; if yes, continue, and if no, choose the smallest measurement, benchmark, or unlock step that would make the next optimization credible.
+
+The final stopping condition also requires the relevant guarded test surface to be green; a partially red repository is not a completed optimization outcome.
+
+## Re-scan after each iteration
+
+Inspect the full known performance backlog for:
+
+- modules that are still unvisited or only shallowly read,
+- modules that were read but not yet checked against every available performance job lens,
+- new repeated work after moved or extracted concepts,
+- remaining N+1 calls, serial round trips, or excessive query shapes,
+- caches that are stale, unbounded, or unnecessary,
+- hot loops that still allocate avoidable objects,
+- concurrency changes that need backpressure or max-in-flight proof,
+- logs, metrics, traces, or benchmarks that now describe stale names or paths,
+- documentation or `AGENTS.md` drift.
+
+Then choose the next execution directions with these priorities:
+
+1. strongest bottleneck evidence,
+2. largest user-visible or high-frequency impact,
+3. highest combined confidence from agent capability, workload understanding, correctness guardrails, benchmark quality, and recovery path,
+4. strongest leverage for later deeper optimization,
+5. 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 performance backlog.
+2. Refresh the module coverage ledger and identify unvisited in-scope modules.
+3. Ask whether any known in-scope actionable bottleneck still remains.
+4. If yes, decide whether it should be addressed in the very next iteration or whether measurement or unlock work is needed first.
+5. If the obstacle is a large, coupled, or central hot path, 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 bottleneck 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 optimization does not by itself mean the repository is done.
+
+## Continue when
+
+Repeat the cycle when:
+
+- any known in-scope actionable performance issue remains unresolved,
+- any in-scope module remains unvisited,
+- measured slow paths remain,
+- clear algorithmic waste remains,
+- avoidable IO, query, or external-service round trips remain,
+- unsafe or low-value caches need removal or replacement,
+- allocation churn or hot-loop repeated work remains in a material path,
+- concurrency, backpressure, or batching gaps remain,
+- benchmarks or profiling are missing for a high-risk optimization that is otherwise actionable.
+
+Do not produce a final completion report while any item in this section is true. Continue with the next bounded iteration instead.
+
+## Stop when
+
+Stop only when there are no unresolved known in-scope actionable performance issues. Any remaining candidates must be explicitly classified as one of:
+
+- low-value micro-optimization,
+- speculative without concrete evidence,
+- production-measurement-only with no safe local proxy,
+- public contract migrations,
+- macro-architecture changes,
+- product behavior changes needing user approval,
+- blocked by unavailable credentials, unstable external systems, or missing documentation,
+- untestable with the current repository tooling and too risky to change safely.
+
+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 performance deep-read iteration, it is still an actionable coverage gap even when the already-read modules look fast.
+
+## 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,
+- performance job lenses checked 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 optimization,
+- speedup, throughput, latency, CPU, memory, allocation, query-count, or complexity evidence,
+- behavior-preservation evidence,
+- docs and constraints sync status,
+- proof that the latest scan found no known actionable in-scope performance issues,
+- deferred items with reason and required approval, dependency, production data, or safety constraint.

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

@@ -0,0 +1,92 @@
+# Performance Job Selection Guide
+
+## Purpose
+
+Help the agent choose the next execution direction after each full-codebase performance 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.
+
+Before choosing, the agent should first scan the selected module through every available performance job lens. Job selection happens after that scan; it is not a substitute for that scan.
+
+## Available jobs
+
+- measurement / benchmarking
+- algorithmic complexity / repeated-work cleanup
+- IO batching / query shaping
+- caching / memoization
+- allocation / hot-loop cleanup
+- concurrency / pipeline tuning
+- staged unlock work
+
+## Choose `measurement / benchmarking` when
+
+- the slow path is suspected but not proven,
+- multiple candidate bottlenecks compete and prioritization would otherwise be guesswork,
+- an optimization could regress correctness or user-visible latency without a baseline,
+- production symptoms exist but local reproduction or profiling is missing.
+
+## Choose `algorithmic complexity / repeated-work cleanup` when
+
+- nested loops, repeated scans, repeated sorts, or repeated filters dominate the path,
+- the same derived value is recomputed for every item or request,
+- a more appropriate data structure would reduce asymptotic or constant-factor cost,
+- the complexity change can be proven without changing business behavior.
+
+## Choose `IO batching / query shaping` when
+
+- N+1 database, network, filesystem, or external API calls exist,
+- serial round trips can be safely batched or preloaded,
+- query predicates, projections, pagination, or indexes are mismatched to real access patterns,
+- external calls lack timeout, retry, or result-shape handling that affects throughput.
+
+## Choose `caching / memoization` when
+
+- the same expensive pure or owner-scoped computation repeats,
+- cache ownership, invalidation, size bounds, and failure behavior are clear,
+- stale data cannot violate business rules,
+- a simpler repeated-work or data-structure fix is insufficient.
+
+## Choose `allocation / hot-loop cleanup` when
+
+- tight loops allocate avoidable objects, strings, buffers, regexes, or closures,
+- repeated serialization, parsing, cloning, copying, or formatting appears in a hot path,
+- memory pressure or garbage collection is part of the observed slowdown,
+- changes can preserve readability or are justified by strong hot-path evidence.
+
+## Choose `concurrency / pipeline tuning` when
+
+- safe independent work is unnecessarily serial,
+- current parallelism is unbounded or overloads downstream resources,
+- queues, workers, streams, or async tasks lack backpressure,
+- batching or bounded concurrency would improve throughput without changing ordering guarantees.
+
+## Choose `staged unlock work` when
+
+- the file feels too central or too coupled for direct optimization,
+- no safe full hot-path rewrite exists yet, but a preparatory step does,
+- you can reduce risk through measurement hooks, seam extraction, characterization tests, type extraction, data-shape clarification, or side-effect isolation,
+- the best next move is to make a future optimization cheaper rather than solve the whole area now.
+
+## Tie-breakers
+
+If multiple jobs are plausible, prefer the one that:
+
+1. addresses the highest-evidence bottleneck,
+2. improves the most user-visible or high-frequency path,
+3. increases safety for the next iteration,
+4. removes the strongest blocker to a deeper future optimization,
+5. helps an unvisited module reach performance deep-read coverage,
+6. matches the agent's self-assessed ability to understand, execute, benchmark, and repair the change under current evidence,
+7. preserves behavior with the clearest available guardrails.
+
+## Hard rule
+
+If performance evidence is too weak, `measurement / benchmarking` should usually win before code changes.
+
+If a high-risk hot path lacks enough correctness guardrails, benchmark or characterization guardrail work should usually win before a deeper optimization.
+
+If the area is difficult but the agent can explain the workload, behavior, affected contracts, rollback path, and available tests or benchmarks clearly, do not downgrade confidence just because the optimization is non-trivial. Strong guardrails mean accidental breakage should be repaired by returning the test and benchmark surface to green, not avoided by leaving an actionable bottleneck in place.
+
+If any in-scope module remains unvisited, choose jobs that help the next highest-evidence or easiest useful unvisited module become deeply read, improved, or validated-clear before spending another round on already-familiar areas.

package/iterative-code-performance/references/measurement-and-benchmarking.md

@@ -0,0 +1,78 @@
+# Measurement And Benchmarking
+
+## Principle
+
+Optimize from evidence. A performance change should have at least one of:
+
+- production latency, throughput, CPU, memory, queue, or query evidence,
+- profiler output,
+- repeatable benchmark baseline,
+- test runtime profile,
+- log or trace timings,
+- clear algorithmic complexity proof tied to a plausible workload.
+
+If none exists, measurement is usually the next job.
+
+Measurement also informs confidence, but it is not the only input. The agent must assess its own ability to understand and complete the optimization, then combine that self-assessment with task difficulty, benchmark quality, correctness tests, rollback options, and repair paths. Strong tests and repeatable benchmarks should make difficult changes more actionable because failures can be diagnosed and driven back to green.
+
+## Baseline rules
+
+Before changing a hot path, record:
+
+- command, scenario, fixture, data size, seed, and environment,
+- current timing, throughput, allocation, query count, memory, or operation count,
+- variance or repeated-run notes when possible,
+- correctness oracle used with the benchmark,
+- reason if the path can only be measured in production.
+
+Do not compare a cold-cache baseline with a warm-cache after result unless that is the intended user-visible scenario.
+
+## Benchmark selection
+
+Use the cheapest reliable benchmark that proves the risk:
+
+- unit microbenchmarks for pure hot helpers,
+- integration benchmarks for query, serialization, or multi-module orchestration paths,
+- command or request benchmarks for user-visible entrypoints,
+- load tests only when concurrency, backpressure, or throughput is the actual risk,
+- profiler snapshots when the bottleneck location is unknown.
+
+Avoid expensive load tests when a deterministic benchmark or integration test proves the same performance issue.
+
+## Before/after comparisons
+
+A useful comparison names:
+
+- baseline command and result,
+- after command and result,
+- data shape and scale,
+- correctness validation,
+- variance or caveat,
+- whether the improvement is latency, throughput, CPU, memory, allocation, query count, or algorithmic complexity.
+
+If exact numbers are unstable, report operation counts, query counts, asymptotic complexity, or profiler rank change instead of pretending precision exists.
+
+## Guardrail design
+
+Performance guardrails should fail on meaningful regressions, not noise.
+
+Prefer:
+
+- deterministic operation or query counts,
+- bounded latency budgets with generous margins only when the environment is stable,
+- regression tests for duplicate work removal,
+- benchmark scripts documented for local use,
+- assertions on cache invalidation behavior,
+- profiler notes for manual verification when automated thresholds are unreliable.
+
+Do not add flaky timing thresholds to CI when the repository has no stable benchmark environment.
+
+## Production-only measurement
+
+When a bottleneck requires production data or credentials:
+
+- capture the best local proxy evidence available,
+- document the missing data source,
+- avoid speculative rewrites that cannot be validated,
+- add safe instrumentation or benchmark hooks if approved and useful,
+- classify the remaining item as production-measurement-only if no safe local action remains.

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

@@ -0,0 +1,133 @@
+# Module Coverage And Performance Deep-Read Iterations
+
+## Purpose
+
+Prevent the agent from repeatedly optimizing only familiar hot paths 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 performance deep-read iteration.
+
+Deep-read here does not mean generic reading. It means scanning the module through each available performance job lens so the agent can identify whether measurement, algorithmic complexity, repeated-work removal, IO batching, caching, allocation cleanup, concurrency work, or staged unlock work is justified.
+
+## 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 persistence/query, external-integration, queue, cache, or reporting subsystem,
+- 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,
+- expected workload shape and frequency,
+- tests, benchmarks, and performance guardrails,
+- logs, metrics, traces, or profiling surfaces,
+- persistence, network, filesystem, or external API contracts,
+- 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, benchmarks, contracts, workload shape, core files, and all available performance job lenses were inspected with enough context to judge performance.
+- `optimized`: at least one behavior-safe performance improvement landed for this module.
+- `validated-clear`: deep read found no actionable in-scope performance issue worth changing now.
+- `deferred`: an issue exists but is blocked, unsafe, speculative, approval-dependent, production-measurement-only, 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 and evidence-first ordering
+
+Start with the easiest useful modules when that reduces risk:
+
+- small surface area,
+- clear ownership,
+- local tests, cheap benchmarks, or profiling hooks,
+- limited side effects,
+- low public API or persistence risk,
+- likely to clarify workload shape, tests, benchmarks, caching seams, batching seams, or data structures used by harder modules.
+
+Prefer measured high-impact bottlenecks when they exist, even if they are not the easiest module.
+
+Do not confuse easy-first with low-value micro-optimization. The chosen module should either resolve real performance issues or create context/guardrails that make later hot paths safer.
+
+## 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,
+- workload size, frequency, and data-shape assumptions,
+- tests, fixtures, mocks, benchmark commands, and validation commands,
+- logs, metrics, tracing, profiler hooks, and error messages,
+- configuration, persistence, query, cache, concurrency, and external-service contracts when relevant,
+- known TODOs, comments, or docs that describe performance behavior.
+
+It also must inspect the module through each available performance job lens:
+
+- `measurement / benchmarking`: is there enough baseline evidence, or is measurement the next unlock?
+- `algorithmic complexity / repeated work`: are there avoidable scans, sorts, conversions, or duplicated computations?
+- `IO batching / queries`: are there N+1 calls, excessive round trips, poor query shapes, or serial external work?
+- `caching / memoization`: would caching help, and are ownership plus invalidation safe?
+- `allocation / hot loops`: are tight loops creating avoidable objects, strings, parsing, or serialization?
+- `concurrency / pipelines`: is work too serial, too parallel, unbounded, or missing backpressure?
+- `staged unlock work`: if the module is too coupled for direct optimization, 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 performance job lens has been checked and classified as one of: actionable now, measure-first, unlock-first, deferred, excluded, or no meaningful issue found.
+
+## 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 highest-evidence hot module, or the easiest useful `unvisited` module that can be deeply read and improved or validated now.
+4. Scan that module through every available performance job lens before deciding what "this round" means.
+5. If the next module is high-risk and under-guarded, choose benchmark or characterization guardrails first.
+6. If the next module is too coupled for direct optimization, 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:
+
+- it blocks safe deep reading of an unvisited module,
+- a previous optimization created follow-up risk that must be stabilized,
+- validation exposed a real defect, stale benchmark, or stale contract,
+- cross-module optimization requires touching it together with the next module.
+
+## Module cluster iterations
+
+One iteration may cover a small cluster of modules when they share one hot path or invariant, such as:
+
+- a command and its parser,
+- a route and its service,
+- a domain module and its query adapter,
+- an integration wrapper and its retry or batching helper,
+- a worker and its queue processor.
+
+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 performance job lenses were checked, and which jobs were selected and why?
+- What bottleneck was fixed, or why is the module validated-clear?
+- Which guardrails prove behavior was preserved?
+- What baseline and after evidence exists?
+- Which modules remain `unvisited`?
+- Which module is the next highest-evidence or 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-performance/references/repository-scan.md

@@ -0,0 +1,69 @@
+# Repository Performance Scan And Backlog Selection
+
+## Purpose
+
+Build a factual performance map before changing code, then choose the highest-value optimizations while tracking module-by-module performance deep-read coverage.
+
+## Required scan
+
+- Read `AGENTS.md`, `README*`, project docs, manifests, task runners, CI configs, benchmark setup, profiler setup, and test setup.
+- List entrypoints: CLI commands, servers, workers, jobs, frontend routes, scripts, libraries, public packages, and scheduled tasks.
+- Identify core domain modules, persistence/query boundaries, external integrations, serialization/parsing paths, logging utilities, queues, caches, and test helpers.
+- Create a module inventory and coverage ledger using `references/module-coverage.md`.
+- For each module, scan through the available performance 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, fixture, compiled, and minified files; exclude them unless they are human-maintained source.
+
+## Performance backlog signals
+
+Prioritize files or functions with:
+
+- measured slow requests, commands, jobs, tests, startup, builds, or user-visible interactions,
+- high fan-in, high loop counts, high request frequency, or repeated invocation in long-running workers,
+- avoidable nested loops, repeated scans, repeated sorting, repeated parsing, or repeated conversions,
+- N+1 database, network, filesystem, or external API calls,
+- unbounded concurrency, serial work that can be safely batched, or pipelines without backpressure,
+- repeated serialization/deserialization or large intermediate objects,
+- allocation churn, excessive cloning/copying, or memory-pressure paths,
+- caches with missing invalidation, excessive retention, or low hit value,
+- logs, metrics, traces, or benchmarks that hide where time is spent.
+
+## Evidence to capture
+
+For each candidate record:
+
+- file path and symbol name,
+- owning module or module cluster,
+- job lens that exposed the issue,
+- performance evidence: benchmark, trace, profiler output, log timing, production symptom, or complexity analysis,
+- expected speed, throughput, allocation, IO, or complexity improvement,
+- correctness risks and behavior invariants,
+- tests, benchmarks, or validations needed to prove safety,
+- reason to defer if the candidate requires product, architecture, operational, or production-data approval.
+
+## Exclusion rules
+
+Do not optimize:
+
+- third-party, generated, compiled, or minified artifacts,
+- snapshots where churn would hide signal,
+- code the user marked as actively edited elsewhere,
+- public schema/API names or data contracts that require migration planning,
+- cold paths where the optimization makes code harder to maintain without evidence of value,
+- areas that cannot be validated and are not causing a clear performance risk.
+
+## Backlog scoring
+
+Prefer a small set of high-confidence improvements over an exhaustive sweep.
+
+Score each candidate by:
+
+1. **Impact**: latency, throughput, CPU, memory, IO, user criticality, and call frequency.
+2. **Evidence**: measurement quality or clear complexity proof.
+3. **Correctness confidence**: ability to preserve business behavior.
+4. **Validation**: ability to benchmark, test, or otherwise prove equivalence.
+5. **Blast radius**: number of modules, public contracts, persistence paths, and operational assumptions affected.
+
+Start with high-impact, high-evidence, low-blast-radius items. Escalate broad changes only when smaller passes cannot resolve the root performance 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/README.md

@@ -16,6 +16,7 @@ Improve an existing repository through a strict three-step loop of full-codebase
 - 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.
+- Requires confidence decisions to combine the agent's self-assessed ability, task complexity, guardrail strength, rollback or repair paths, and whether a strong test suite can safely drive broken refactors back to green.
 - 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.

package/iterative-code-quality/SKILL.md

@@ -52,6 +52,7 @@ For this skill, `macro architecture` means the system's top-level runtime shape
 - 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.
+- Before choosing or deferring a refactor, explicitly assess refactor confidence as a combination of the agent's own ability to understand and complete the task, the objective safety net from tests and other guardrails, the clarity of rollback or repair paths, and the task's inherent difficulty. Do not treat difficulty alone as low confidence; when strong tests guard the behavior, use them to support bolder changes because failures can be driven back to green.
 - 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.

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, 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."
+  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 assess refactor confidence from your own ability to understand and complete the change, task complexity, guardrail strength, rollback or repair paths, and whether tests can drive accidental breakage back to green. If a high-risk area is weakly guarded add the missing tests or other guardrails instead of stopping; if strong tests guard the behavior, use them to justify bolder safe refactors rather than avoiding the work. 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/coupled-core-file-strategy.md

@@ -52,14 +52,14 @@ Avoid these anti-patterns:
 
 Prefer the next step that maximizes:
 
-1. confidence under existing tests or quickly addable tests,
+1. combined confidence from the agent's own ability, code understanding, 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.
 
-If the file is high-risk and under-tested, prefer adding the smallest useful characterization tests before attempting deeper structural edits.
+If the file is high-risk and under-tested, prefer adding the smallest useful characterization tests before attempting deeper structural edits. If the file is high-risk but well-guarded, do not stop only because the change is difficult; use the guardrails to validate the agent's work and repair any accidental breakage.
 
 ## Completion rule for coupled files
 

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

@@ -9,12 +9,15 @@ Each iteration must have:
 - an explicit record of which job lenses were checked during the deep read,
 - a bounded file/symbol scope,
 - one or more selected execution directions,
+- a confidence assessment covering the agent's own ability to complete the refactor, the task's inherent difficulty, objective guardrail strength, and rollback or repair paths,
 - expected behavior-neutral outcome,
 - validation plan,
 - rollback point if evidence contradicts the change.
 
 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.
 
+Confidence is not a synonym for "easy". Assess whether the agent has enough understanding, skill, local context, tests, validation commands, and recovery path to complete the refactor safely. A hard task can still be high-confidence when strong tests, characterization coverage, and clear rollback let the agent repair mistakes by making the guarded behavior green again.
+
 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.
@@ -35,7 +38,7 @@ If validation fails:
 - keep regression coverage for real defects,
 - do not mask failures by weakening assertions.
 
-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.
+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. Reassess whether the agent has enough capability and objective support to proceed; if yes, continue, and if no, choose the smallest guardrail or unlock step that would make the next refactor credible.
 
 The final stopping condition also requires the relevant guarded test surface to be green; a partially red repository is not a completed refactor outcome.
 
@@ -54,7 +57,7 @@ Inspect the full known quality backlog for:
 
 Then choose the next execution directions with these priorities:
 
-1. highest confidence under current guardrails,
+1. highest combined confidence from agent capability, code understanding, guardrails, and recovery path,
 2. strongest leverage for later deeper cleanup,
 3. lowest business-risk path toward broader system improvement.
 

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

@@ -66,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/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.8",
+  "version": "3.2.0",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",