@laitszkin/apollo-toolkit 3.12.1 → 3.13.0

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

@@ -1,133 +0,0 @@
-# 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/CLAUDE.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

@@ -1,92 +0,0 @@
-# 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

@@ -1,78 +0,0 @@
-# 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

@@ -1,133 +0,0 @@
-# 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

@@ -1,69 +0,0 @@
-# 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/CLAUDE.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/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 LaiTszKin
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/iterative-code-quality/README.md

@@ -1,45 +0,0 @@
-# iterative-code-quality
-
-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
-
-- 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.
-- 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.
-- 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.
-- 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.
-- 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/CLAUDE.md` through `align-project-documents` and `maintain-project-constraints` after implementation.
-
-## Repository structure
-
-- `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, module coverage, job selection, naming, simplification, module boundaries, logging, testing, unlock work, and iteration gates.
-
-## Typical usage
-
-```text
-Use $iterative-code-quality to improve this repository's code quality end to end without changing business behavior or macro architecture.
-```
-
-## License
-
-MIT. See `LICENSE`.