@laitszkin/apollo-toolkit 3.12.0 → 3.13.0

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`.

package/iterative-code-quality/SKILL.md

@@ -1,112 +0,0 @@
----
-name: iterative-code-quality
-description: >-
-  Improve an existing codebase through repeated evidence-based repository-wide
-  scans, module-by-module deep-read coverage, and behavior-safe refactors until
-  no known in-scope actionable quality issue or unvisited in-scope module
-  remains: clarify poor names, simplify or extract reusable functions, split
-  mixed-responsibility code, repair stale or missing logs, and add high-value
-  tests where guardrails are missing, while preserving intended business
-  behavior and the system's macro architecture. Use when users ask for
-  comprehensive refactoring, code cleanup, maintainability hardening, naming
-  cleanup, log alignment, or test coverage improvement across a repository.
----
-
-# Iterative Code Quality
-
-## Dependencies
-
-- Required: `align-project-documents` and `maintain-project-constraints` after the repository is truly iteration-complete.
-- Conditional: `systematic-debug` when a newly added or existing test exposes a real business-logic defect that must be fixed at the true owner.
-- Optional: `discover-edge-cases` for high-risk boundary exploration before adding tests; `improve-observability` for non-trivial telemetry design.
-- Fallback: If required completion dependencies are unavailable, finish code and validation first, then report exactly which documentation or constraint-sync action could not run.
-
-## Standards
-
-- Evidence: Read repository docs, project constraints, source, tests, logs, 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 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, unless the remaining surface is explicitly classified with evidence as blocked, unsafe, user-owned active work, speculative, low-value, or approval-dependent.
-- 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.
-
-## Mission
-
-Leave the repository materially cleaner by continuously scanning the whole codebase, landing the highest-value safe refactors available at each moment, and repeating until there is no known in-scope actionable quality gap left to fix.
-
-For this skill, `macro architecture` means the system's top-level runtime shape and overall operating logic: major subsystems, top-level execution model, deployment/runtime boundaries, persistence model, service boundaries, and the end-to-end way the whole system works. Ordinary module interactions, helper extraction, local responsibility moves, internal call-boundary cleanup, and local module splits do not count as macro-architecture changes by themselves.
-
-## Three-Step Loop
-
-### 1) Scan the repository
-
-- Read root guidance first: `AGENTS.md/CLAUDE.md`, `README*`, package manifests, task runners, CI/test config, and major project docs.
-- Map runtime entrypoints, domain modules, external integrations, logging utilities, and current test surfaces.
-- Exclude generated, vendored, lock, build-output, fixture, or snapshot files unless evidence shows they are human-maintained source.
-- Build or refresh a concrete repository-wide backlog of known actionable quality issues.
-- Build or refresh a module inventory and coverage ledger; every in-scope module starts as unvisited until it has received a 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, 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.
-- If the user has clearly indicated that a touched area is their active in-progress change, treat that area as blocked for this skill, record the evidence, and continue with other in-scope modules instead of modifying or debugging it.
-- 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.
-- If a desired refactor is high-risk and weakly guarded, make guardrail-building part of this round instead of stopping.
-- If a file feels too coupled, too central, or too risky for a direct rewrite, do staged unlock work rather than declaring the area blocked.
-- Read all directly affected callers, tests, interfaces, and logs before editing.
-- Validate from narrow to broad after each bounded round, then perform a full-codebase stage-gate decision:
-  - if any known in-scope actionable issue still remains or any in-scope module has not received a deep-read iteration, return to Step 1;
-  - only continue to Step 3 when the latest scan is clear.
-
-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 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.
-- `references/logging-alignment.md` for stale or missing log repair.
-- `references/testing-strategy.md` for unit, property, integration, and E2E test strategy.
-- `references/coupled-core-file-strategy.md` for staged unlock work on large coupled or apparently core files.
-- `references/iteration-gates.md` for validation cadence, stage-gate rules, and stop criteria.
-
-### 3) Update project documents and constraints
-
-Only enter this step when the latest full-codebase scan confirms there is no remaining known actionable in-scope quality issue and every in-scope module has received a deep-read iteration, except items explicitly classified as blocked, unsafe, speculative, low-value, excluded, or approval-dependent.
-
-- Run `align-project-documents` when README, architecture notes, setup docs, debugging docs, or test guidance may have drifted.
-- Run `maintain-project-constraints` to verify `AGENTS.md/CLAUDE.md` still matches the repository's real architecture, business flow, commands, and conventions.
-- Update only the documentation and constraints that changed in reality because of the refactor.
-
-## Hard Guardrails
-
-- Do not change intended business logic while refactoring, except to fix a real defect exposed by tests and verified at the true owner.
-- Do not change the system's macro architecture unless the user explicitly expands scope.
-- Do not use one-off scripts to rewrite product code.
-- Do not stop early just because a file is large, central, or historically fragile; if a safe unlock step exists, that is the next job.
-- Do not stop before every in-scope module has been inventoried, deeply read, and either improved, validated as clear, or explicitly deferred/excluded with evidence.
-- Do not touch user-owned active edits; classify them as blocked with evidence and continue elsewhere.
-- Do not weaken tests to make a refactor pass; fix the real defect or update stale expectations to stable invariants.
-- Do not add style-only churn that does not improve naming, modularity, observability, reuse, or guardrail strength.
-- Do not add unreliable E2E coverage when a controlled integration or characterization test can prove the same risk more safely.
-
-## Completion Report
-
-Only report completion after Step 3 is done, the latest Step 1 scan is clear, and the module coverage ledger has no unvisited in-scope module.
-
-Return:
-
-1. Iterations completed and the jobs selected in each iteration.
-2. Stage-gate verdict after each full-codebase re-scan.
-3. Module coverage ledger summary: modules deep-read, improved, validated-clear, deferred, or excluded.
-4. Key files changed and the quality issue each change resolved.
-5. Business behavior preservation evidence.
-6. Tests or other guardrails added or updated, including property/integration/E2E `N/A` reasons where relevant.
-7. Validation commands and results.
-8. Documentation and `AGENTS.md/CLAUDE.md` synchronization status.
-9. Remaining blocked or approval-dependent items, if any.

package/iterative-code-quality/agents/openai.yaml

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

@@ -1,73 +0,0 @@
-# Staged Strategy For Large Coupled Or Apparently Core Files
-
-## Purpose
-
-Teach the agent how to keep making progress when a file feels too central, too coupled, or too risky to refactor directly.
-
-The correct response is usually not "stop". The correct response is "find the next unlock step".
-
-## Core rule
-
-A large coupled file is a **decomposition signal**, not a **completion blocker**.
-
-If a safe, behavior-preserving unlock step exists under current guardrails, take that step now instead of deferring the whole area.
-
-If guardrails are too weak for direct cleanup, strengthening them is itself the next unlock step.
-
-## First questions to ask
-
-When a file feels untouchable, ask:
-
-- Which parts are pure logic and which parts are side effects?
-- Which names or local concepts are blocking understanding?
-- Which behavior can be locked down with characterization tests?
-- Which dependency seams can be introduced without changing behavior?
-- Which caller groups or workflow slices can be isolated first?
-- Which refactor would most reduce the cost of the next refactor?
-
-## Typical unlock sequence
-
-Pick one or more of these, in the order justified by current evidence:
-
-1. Add characterization or regression tests around current behavior.
-2. Rename confusing variables, flags, intermediate states, and helper names.
-3. Extract constants, schemas, types, and small pure transformations.
-4. Separate read path from write path, or decision logic from side effects.
-5. Isolate external calls, persistence, and logging behind clearer seams.
-6. Group callers by responsibility and split one slice at a time.
-7. Move one coherent responsibility into a new internal module.
-8. Re-scan and decide whether a deeper split is now safer.
-
-## What not to do
-
-Avoid these anti-patterns:
-
-- declaring the area blocked just because it is important,
-- attempting a full rewrite before guardrails exist,
-- preserving obvious local design debt only because the file is central,
-- escalating ordinary internal decomposition into a fake macro-architecture concern,
-- mixing unlock work with unrelated style churn.
-
-## Choosing the next step
-
-Prefer the next step that maximizes:
-
-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 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
-
-Do not ask "Can I solve the whole file now?"
-
-Ask:
-
-- "Can I make this file meaningfully easier to change in the next iteration?"
-- "Can I reduce coupling, clarify ownership, or improve guardrails right now?"
-
-If the answer is yes, continue iterating.

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

@@ -1,127 +0,0 @@
-# Iteration Gates And Stopping Criteria
-
-## Pass discipline
-
-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,
-- 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.
-
-## 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. Integration tests for affected chains.
-4. Broader suite or build once multiple passes interact.
-
-If validation fails:
-
-- determine whether the failure is pre-existing, stale test expectation, test isolation issue, or real product bug,
-- fix the true owner,
-- 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. 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.
-
-## Re-scan after each iteration
-
-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,
-- logs that now use stale names,
-- tests that cover only the happy path,
-- documentation or `AGENTS.md/CLAUDE.md` drift.
-
-Then choose the next execution directions with these priorities:
-
-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.
-
-Use `references/job-selection.md` to convert those priorities into a concrete next-job choice.
-
-## Stage-gate after each iteration
-
-After every validated iteration, run a deliberate full-codebase decision pass:
-
-1. Re-scan the repository and refresh the known quality backlog.
-2. Refresh the module coverage ledger and identify unvisited in-scope modules.
-3. Ask whether any known in-scope actionable issue still remains.
-4. If yes, decide whether it should be addressed in the very next iteration or whether first-step unlock work is needed.
-5. If the obstacle is a large, coupled, or central file, do not stop there; switch to staged unlock work and continue.
-6. Only declare the repository iteration-complete when the re-scan shows no remaining actionable in-scope issue and no unvisited in-scope module except items that are explicitly deferred or excluded under the allowed stop categories.
-
-This stage-gate is mandatory. A validated local change does not by itself mean the repository is done.
-
-## Continue when
-
-Repeat the cycle when:
-
-- any known in-scope actionable quality issue remains unresolved,
-- any in-scope module remains unvisited,
-- high-impact unclear names remain,
-- duplicated or hard-coded workflows still have safe extraction paths,
-- a module still mixes distinct responsibilities and can be split locally,
-- logs are still misleading or missing at critical decisions,
-- high-value business logic remains untested and is testable.
-
-Do not produce a final completion report while any item in this section is true. Continue with the next bounded iteration instead.
-
-Prefer gradual outside-in progress: boundary cleanup, naming clarity, and guardrail strengthening should often come before deeper internal rewrites because they make the deeper work safer later.
-
-## Stop when
-
-Stop only when there are no unresolved known in-scope actionable issues. Any remaining candidates must be explicitly classified as one of:
-
-- low-value style preference,
-- speculative without concrete evidence,
-- 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 deep-read iteration, it is still an actionable coverage gap even when the already-read modules look clean.
-
-## Completion evidence
-
-The final report should make the stopping point auditable:
-
-- passes completed,
-- execution directions selected per iteration,
-- module or module cluster covered per iteration,
-- 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 refactor,
-- tests added by risk category,
-- behavior-preservation evidence,
-- docs and constraints sync status,
-- proof that the latest scan found no known actionable in-scope quality issues,
-- deferred items with reason and required approval, dependency, or safety constraint.