@laitszkin/apollo-toolkit 3.0.4 → 3.1.0

package/AGENTS.md

@@ -53,6 +53,7 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can investigate gated or shadow LLM APIs by capturing real client request shapes, replaying verified traffic patterns, and attributing the likely underlying model through black-box fingerprinting.
 - Users can build and maintain Solana programs and Rust clients using official Solana development workflows.
 - Users can add focused observability to opaque workflows through targeted logs, metrics, traces, and tests.
+- Users can iteratively improve repository code quality through behavior-neutral naming, simplification, module-boundary, logging, and test-coverage passes.
 - Users can build against Jupiter's official Solana swap, token, price, lending, trigger, recurring, and portfolio APIs with an evidence-based development guide.
 - Users can render and embed math formulas with KaTeX using official documentation-backed guidance and reusable rendering scripts.
 - Users can debug software systematically by reproducing causes, validating fixes, and testing outcomes.

package/CHANGELOG.md

@@ -7,6 +7,11 @@ All notable changes to this repository are documented in this file.
 ### Changed
 - None yet.
 
+## [v3.1.0] - 2026-04-22
+
+### Added
+- Add `iterative-code-quality`, a new repository-wide improvement skill that performs repeated behavior-neutral passes for naming cleanup, function simplification, module-boundary refactors, logging alignment, and risk-based test coverage, then synchronizes project docs and `AGENTS.md`.
+
 ## [v3.0.4] - 2026-04-22
 
 ### Changed

package/README.md

@@ -24,6 +24,7 @@ A curated skill catalog for Codex, OpenClaw, Trae, and Claude Code with a manage
 - harden-app-security
 - implement-specs
 - improve-observability
+- iterative-code-quality
 - jupiter-development
 - katex
 - learn-skill-from-conversations

package/iterative-code-quality/LICENSE

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

@@ -0,0 +1,30 @@
+# iterative-code-quality
+
+Improve an existing repository through repeated, evidence-backed code-quality passes while preserving intended business behavior and macro architecture.
+
+## Core capabilities
+
+- Scans the full codebase and builds a prioritized quality backlog before editing.
+- 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.
+- Repeats the pass cycle until remaining issues are low-value, blocked, or require explicit product/architecture approval.
+- Synchronizes project docs and `AGENTS.md` through `align-project-documents` and `maintain-project-constraints` after implementation.
+
+## Repository structure
+
+- `SKILL.md`: Main iterative workflow, dependencies, guardrails, and output contract.
+- `agents/openai.yaml`: Agent interface metadata and default prompt.
+- `references/`: Focused guides for scanning, naming, simplification, module boundaries, logging, testing, 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

@@ -0,0 +1,153 @@
+---
+name: iterative-code-quality
+description: >-
+  Improve an existing codebase through repeated evidence-based code-quality
+  passes: clarify poor variable names, simplify or extract reusable functions,
+  split oversized code into single-responsibility modules, repair stale or
+  missing logs, and add high-value tests while preserving business behavior and
+  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 implementation changes are complete.
+- Conditional: `systematic-debug` when a new or existing test reveals a real business-logic defect that must be fixed.
+- Optional: `discover-edge-cases` for high-risk boundary exploration before choosing missing tests; `improve-observability` for complex telemetry design.
+- Fallback: If required completion dependencies are unavailable, finish code and tests, then report exactly which documentation or constraint sync step could not run.
+
+## Standards
+
+- Evidence: Read repository docs, project constraints, source, tests, logs, and entrypoints before editing; every rename, extraction, split, log update, or test must be backed by code context.
+- Execution: Work in bounded passes, prioritize behavior-neutral improvements with the highest maintainability and test value, validate after each pass, and repeat until the remaining quality gaps are low-value or unsafe to change.
+- Quality: Preserve business behavior and macro architecture unless tests expose an existing logic defect; avoid style-only churn, compatibility theater, broad rewrites, and unverified "cleanup".
+- Output: Deliver a concise pass-by-pass summary, changed behavior-neutral surfaces, test coverage added, validation results, unresolved risks, and documentation/`AGENTS.md` sync status.
+
+## Goal
+
+Raise code quality across an existing repository without changing intended product behavior or the system's macro architecture.
+
+This skill is intentionally implementation-oriented, not report-only. It should identify high-value improvements, apply them, test them, and keep iterating until further changes would be speculative, low-value, or architecture-changing.
+
+## Required Reference Loading
+
+Load references only when they match the active pass:
+
+- `references/repository-scan.md`: scope mapping, generated-file exclusions, and quality backlog selection.
+- `references/naming-and-simplification.md`: variable renames, function simplification, reusable extraction, and behavior-preservation checks.
+- `references/module-boundaries.md`: single-responsibility split heuristics and safe module extraction rules.
+- `references/logging-alignment.md`: stale log detection, missing log criteria, and behavior-neutral observability updates.
+- `references/testing-strategy.md`: risk-based unit, property, integration, and E2E coverage selection.
+- `references/iteration-gates.md`: multi-pass quality gates, stopping criteria, and validation cadence.
+
+## Workflow
+
+### 1) Establish the repository baseline
+
+- Read root guidance first: `AGENTS.md`, `README*`, major docs, package manifests, task runners, CI configs, and test setup.
+- Map runtime entrypoints, domain modules, external integrations, logging/telemetry utilities, and existing test suites.
+- Identify generated, vendored, lock, build-output, fixture, or snapshot files; exclude them from refactoring unless evidence shows they are human-maintained source.
+- Run or inspect the most relevant existing validation commands before editing when feasible, so pre-existing failures are distinguishable from new regressions.
+- Build an initial quality backlog with concrete file/function/test targets before changing code.
+- Use `references/repository-scan.md` for the scan checklist and backlog scoring.
+
+### 2) Execute bounded improvement passes
+
+Run focused passes in the order that fits the repository evidence. A typical order is:
+
+1. Naming clarity for variables, parameters, fields, local helpers, and test data.
+2. Function simplification and reusable extraction for duplicated or hard-coded workflows.
+3. Single-responsibility module splits for oversized or mixed-concern code.
+4. Logging alignment for stale, misleading, missing, or low-context diagnostics.
+5. Risk-based test coverage for high-value business logic and boundary cases.
+
+For each pass:
+
+- Read all directly affected callers, tests, and public interfaces before editing.
+- Keep the pass small enough to validate and review; split broad cleanups into multiple passes.
+- Prefer repository-native abstractions over new parallel frameworks.
+- Preserve public behavior, data contracts, side effects, error classes, and macro architecture.
+- Add or update tests in the same pass when the change touches non-trivial logic, observability contracts, or extracted helpers.
+- Validate the touched scope before starting another pass.
+
+### 3) Rename for clarity without churn
+
+- Rename only when the current name hides domain meaning, confuses ownership, conflicts with real units, or makes tests/logs misleading.
+- Prefer names that encode domain role, unit, lifecycle stage, or canonical owner.
+- Update all references, tests, fixtures, structured log fields, docs, and comments that describe the renamed concept.
+- Avoid renaming stable public API fields or persisted schema names unless the user explicitly requested a breaking migration.
+- Use `references/naming-and-simplification.md` before broad rename passes.
+
+### 4) Simplify and extract reusable functions
+
+- Simplify functions when branches, temporary state, repeated transformations, or hard-coded workflows obscure the invariant.
+- Extract helpers only when they reduce duplication, centralize one business rule, clarify caller intent, or make a behavior testable.
+- Keep helper placement aligned with current module ownership.
+- Do not create abstractions for one-off code unless they isolate a meaningful domain rule or external contract.
+- Preserve observable behavior unless a test proves the current behavior is a defect.
+
+### 5) Split modules by responsibility
+
+- Split code only when one file/module owns multiple change reasons, domain boundaries, external integrations, or lifecycle stages.
+- Define the new module's responsibility before moving code.
+- Keep interfaces narrow, explicit, and consistent with existing project style.
+- Avoid macro-architecture changes such as new layers, new service boundaries, new persistence strategies, or framework swaps unless the user explicitly expands scope.
+- Use `references/module-boundaries.md` for extraction rules and anti-patterns.
+
+### 6) Repair logging and observability drift
+
+- Compare log messages, event names, structured fields, metrics, and trace names against the current code ownership model.
+- Fix stale terminology after renames or refactors so logs describe the live workflow.
+- Add logs only at high-value decision points: branch selection, skipped work, external dependency outcome, persistence side effect, retry/rollback, and final outcome.
+- Use structured fields already accepted by the project; never log secrets, tokens, full sensitive payloads, or personal data.
+- Add tests or assertions for important log fields when the project has log-capture helpers.
+- Use `references/logging-alignment.md` for detailed criteria.
+
+### 7) Add high-value tests
+
+- Start from risk, not coverage percentage.
+- Prioritize tests for business rules, state transitions, error handling, extracted helpers, edge cases, observability contracts, and integration boundaries.
+- Use unit tests for local logic, property-based tests for invariants and generated input spaces, integration tests for cross-module chains, and E2E tests only when external services are stable or can be controlled reliably.
+- Mock or fake external services unless the real service contract is the subject under test.
+- If a new test exposes an existing business-logic bug, invoke `systematic-debug`, fix the true owner, and keep the regression test.
+- Use `references/testing-strategy.md` for coverage selection and required `N/A` reasoning.
+
+### 8) Iterate until quality gates pass
+
+- After each pass, run the narrowest relevant tests first, then broaden validation when confidence increases.
+- Re-scan touched areas for new naming drift, duplicated helper candidates, module-boundary cracks, logging drift, and missing tests.
+- Repeat the full pass cycle when significant gaps remain and can be fixed safely without changing business behavior or macro architecture.
+- Stop only when remaining issues are low-value, speculative, blocked, or require explicit product/architecture approval.
+- Use `references/iteration-gates.md` for stopping criteria.
+
+### 9) Synchronize docs and constraints
+
+After code and tests are complete:
+
+- Invoke `align-project-documents` when README, docs, architecture notes, debugging docs, setup instructions, or test guidance may have drifted.
+- Invoke `maintain-project-constraints` to verify `AGENTS.md` still reflects architecture, business flow, common commands, macro purpose, and coding conventions.
+- Update only documentation that is affected by real code, command, logging, or test changes.
+
+## Hard Guardrails
+
+- Do not change intended business logic while refactoring.
+- Do not change macro architecture, framework choice, storage model, deployment model, or service boundaries unless the user explicitly approves that expanded scope.
+- Do not use one-off scripts to rewrite product code.
+- Do not perform style-only churn that does not improve naming, reuse, modularity, observability, or test confidence.
+- Do not weaken tests to make refactors pass; update tests to stable invariants or fix the implementation defect.
+- Do not add E2E tests that depend on unreliable external services when a controlled integration test can prove the same business risk.
+
+## Completion Report
+
+Return:
+
+1. Passes completed and why they were ordered that way.
+2. Key files changed and the quality issue each change resolved.
+3. Business behavior preservation evidence.
+4. Tests added or updated, including property/integration/E2E `N/A` reasons where relevant.
+5. Validation commands and results.
+6. Documentation and `AGENTS.md` synchronization status.
+7. Remaining quality gaps, blockers, or deferred architecture/product decisions.

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

@@ -0,0 +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 to scan this repository, build an evidence-backed quality backlog, then iteratively clarify variable names, simplify or extract reusable functions, split code into single-responsibility modules, repair stale or missing logs, and add high-value unit/property/integration/E2E tests while preserving business behavior and macro architecture; after code and tests are complete, run $align-project-documents and $maintain-project-constraints to synchronize docs and AGENTS.md."

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

@@ -0,0 +1,73 @@
+# Iteration Gates And Stopping Criteria
+
+## Pass discipline
+
+Each pass must have:
+
+- a concrete quality target,
+- a bounded file/symbol scope,
+- expected behavior-neutral outcome,
+- validation plan,
+- rollback point if evidence contradicts the change.
+
+Avoid starting a broad second pass before validating the first.
+
+## 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.
+
+## Re-scan after each pass
+
+Inspect touched areas for:
+
+- 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` drift.
+
+## Continue when
+
+Repeat the cycle when:
+
+- 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.
+
+## Stop when
+
+Stop when remaining candidates are:
+
+- 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.
+
+## Completion evidence
+
+The final report should make the stopping point auditable:
+
+- passes completed,
+- validation commands and outcomes,
+- tests added by risk category,
+- behavior-preservation evidence,
+- docs and constraints sync status,
+- deferred items with reason and required approval or dependency.

package/iterative-code-quality/references/logging-alignment.md

@@ -0,0 +1,67 @@
+# Logging Alignment And Missing Observability
+
+## Purpose
+
+Keep logs and diagnostics synchronized with the real code path while preserving behavior.
+
+## Stale log signals
+
+Update logs when they:
+
+- mention retired owners, lifecycle stages, resource names, or field names,
+- describe a branch that no longer matches the condition,
+- use generic text like `failed` without the operation or reason,
+- report aggregate success without identifiers that let operators reconcile details,
+- keep compatibility-era names after code has moved to a new canonical model,
+- conflict with structured field names or metrics in the same path.
+
+## Missing log criteria
+
+Add logs only where they answer a concrete debugging question.
+
+High-value locations:
+
+- workflow start and final outcome for long-running jobs,
+- branch selection or skipped work with reason code,
+- validation rejection with safe context,
+- external dependency outcome including status class, retry count, request id, and latency when available,
+- persistence side effect or emitted command,
+- rollback, compensation, idempotency, duplicate, or replay decisions.
+
+Low-value locations:
+
+- every line of a tight loop,
+- logs that only restate the function name,
+- dumping raw payloads,
+- duplicating an exception already logged with equal context,
+- noisy success logs in hot paths without operational value.
+
+## Structured field rules
+
+- Reuse the project's existing logger, field naming, metric naming, and trace conventions.
+- Prefer stable identifiers, counts, reason codes, status classes, and lifecycle stages.
+- Keep field names aligned with canonical owners, not stale compatibility projections.
+- Do not log secrets, tokens, private keys, passwords, raw personal data, or full sensitive payloads.
+- Avoid high-cardinality values unless they are necessary identifiers already used by the project.
+
+## Behavior-neutral updates
+
+Logging changes must not:
+
+- alter retry, error, persistence, or branch behavior,
+- swallow exceptions,
+- add blocking network calls,
+- create expensive serialization in hot paths,
+- change public output unless logs are the product output.
+
+## Tests
+
+Add or update tests when:
+
+- the project already captures logs in tests,
+- branch-specific reason codes matter,
+- stale field names were renamed,
+- extracted helpers need observability contracts,
+- aggregate and detail telemetry must stay reconcilable.
+
+Assert stable fields and event names, not timestamps or full formatted strings.

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

@@ -0,0 +1,61 @@
+# Module Boundary And Single Responsibility Refactoring
+
+## When to split a module
+
+Split only when the module has multiple independent reasons to change, such as:
+
+- domain rules mixed with IO, formatting, CLI parsing, or external service calls,
+- unrelated workflows sharing one file because of history, not ownership,
+- test setup forced to instantiate unrelated dependencies,
+- large files where local changes frequently touch distant concepts,
+- circular or awkward imports caused by unclear ownership,
+- logging, validation, persistence, and presentation all living in one function or class.
+
+## Before splitting
+
+Define:
+
+- the current module's actual responsibilities,
+- the target responsibility of each new module,
+- which module owns the canonical business rule,
+- which interfaces must remain stable,
+- which tests prove behavior did not change.
+
+## Safe split patterns
+
+- Move pure domain logic into a domain-owned helper module.
+- Move external adapter code into an integration or infrastructure-adjacent module if the repository already uses that boundary.
+- Move formatting/reporting away from computation.
+- Move test helpers into existing test utility locations rather than production modules.
+- Keep orchestration modules thin: validate inputs, call owners, handle outcomes.
+
+## Interface design
+
+Use narrow interfaces:
+
+- pass only data the callee needs,
+- return explicit result objects or existing domain types,
+- avoid leaking framework/request/database objects into pure domain modules,
+- preserve existing error taxonomy,
+- keep naming aligned with current project vocabulary.
+
+## Anti-patterns
+
+Avoid:
+
+- creating a generic `utils` dumping ground,
+- moving code only to reduce file length,
+- adding new layers that duplicate existing architecture,
+- introducing dependency injection frameworks or service locators without explicit approval,
+- splitting tightly coupled state machines before defining the state owner,
+- changing public boundaries during a cleanup pass.
+
+## Validation checklist
+
+After a split:
+
+- imports remain acyclic or no worse than before,
+- public entrypoints still call the same behavior,
+- tests cover moved logic and orchestration glue,
+- logs still carry the same correlation identifiers,
+- docs or `AGENTS.md` are updated only if the visible architecture or command surface changed.

package/iterative-code-quality/references/naming-and-simplification.md

@@ -0,0 +1,71 @@
+# Naming And Function Simplification
+
+## Naming improvements
+
+Rename only when the current name creates real ambiguity.
+
+Good rename reasons:
+
+- hides domain role, unit, quantity, ownership, or lifecycle stage,
+- uses stale terminology after a refactor,
+- collides with another concept in the same scope,
+- makes boolean, enum, or state-transition meaning unclear,
+- forces readers to inspect implementation before understanding intent.
+
+Avoid renaming when:
+
+- the name is already clear in local context,
+- the change is pure personal preference,
+- the name is part of a stable external API, database schema, event contract, or migration-sensitive field,
+- the rename would create broad churn without reducing ambiguity.
+
+## Naming patterns
+
+- Prefer domain nouns over implementation nouns: `selectedAccount` over `item`.
+- Include units for quantities: `timeoutMs`, `amountCents`, `windowDays`.
+- Use booleans that read as predicates: `isEligible`, `hasPendingRetry`, `shouldPersist`.
+- Name collections by contents: `pendingInvoices`, not `list`.
+- Name state transitions by lifecycle: `markSettlementComplete`, not `updateStatus`.
+- Keep test data names meaningful: `expiredSubscription`, `duplicateEvent`, `unauthorizedActor`.
+
+## Function simplification signals
+
+Simplify functions that contain:
+
+- repeated guard clauses or duplicated validation,
+- mixed parsing, validation, orchestration, persistence, and formatting,
+- nested branches that hide the main path,
+- temporary variables whose names encode implementation steps rather than domain state,
+- hard-coded workflow steps repeated in multiple callers,
+- comments explaining what code structure should make obvious.
+
+## Safe simplification moves
+
+- Extract pure transformations and validations into small helpers.
+- Replace repeated literal mappings with a named table or function.
+- Flatten nested conditionals with explicit guard clauses when it clarifies failure paths.
+- Centralize one business rule behind one function when multiple callers duplicate it.
+- Split orchestration from local computation when tests need a deterministic unit.
+- Delete dead compatibility paths only when reachability evidence and tests support deletion.
+
+## Extraction rules
+
+Create a reusable helper only when at least one condition is true:
+
+- two or more call sites duplicate the same rule,
+- the extracted logic has a clear domain name and stable contract,
+- the helper makes a high-value invariant testable,
+- the helper isolates an external dependency contract or side-effect boundary,
+- the current function has multiple reasons to change.
+
+Keep extracted helpers close to the owner module unless the repository already has a shared utility location for that domain.
+
+## Behavior preservation checklist
+
+Before and after simplification, verify:
+
+- inputs, outputs, exceptions, side effects, and ordering are unchanged,
+- persisted data and emitted events keep the same contract,
+- public API and CLI behavior remain stable,
+- log fields remain compatible unless stale names were intentionally corrected,
+- existing tests still pass and new tests cover extracted rules.

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

@@ -0,0 +1,59 @@
+# Repository Scan And Backlog Selection
+
+## Purpose
+
+Build a factual map before changing code, then choose the highest-value quality improvements.
+
+## Required scan
+
+- Read `AGENTS.md`, `README*`, project docs, manifests, task runners, CI configs, and test setup.
+- List entrypoints: CLI commands, servers, workers, jobs, frontend routes, scripts, libraries, or public packages.
+- Identify core domain modules, external integrations, persistence boundaries, logging utilities, and test helpers.
+- Inspect current git state before editing so unrelated user changes are not overwritten.
+- Identify generated, vendored, lock, snapshot, build-output, and fixture files; exclude them from refactoring unless they are human-maintained source.
+
+## Code quality backlog signals
+
+Prioritize files or functions with:
+
+- high fan-in or many call sites,
+- critical business rules or money/security/data-integrity decisions,
+- duplicated condition trees, conversions, validation, or external-call choreography,
+- unclear naming around ownership, units, state, or lifecycle,
+- large functions that mix parsing, validation, orchestration, side effects, and formatting,
+- log messages that describe old concepts or omit branch/failure context,
+- low or missing tests around meaningful invariants and edge cases.
+
+## Evidence to capture
+
+For each candidate record:
+
+- file path and symbol name,
+- observed quality problem,
+- why it matters to maintainability or correctness confidence,
+- expected behavior-neutral change,
+- tests or validations needed to prove safety,
+- reason to defer if the candidate requires product or architecture approval.
+
+## Exclusion rules
+
+Do not refactor:
+
+- third-party, generated, or compiled artifacts,
+- snapshots where churn would hide signal,
+- code the user marked as actively edited elsewhere,
+- public schema/API names that require migration planning,
+- areas that cannot be validated and are not causing a clear quality risk.
+
+## Backlog scoring
+
+Prefer a small set of high-confidence improvements over an exhaustive sweep.
+
+Score each candidate by:
+
+1. **Impact**: criticality, call frequency, future change risk.
+2. **Confidence**: evidence that the change is behavior-neutral.
+3. **Validation**: ability to test or otherwise prove equivalence.
+4. **Blast radius**: number of modules, public contracts, and migrations affected.
+
+Start with high-impact, high-confidence, low-blast-radius items. Escalate broad changes only when smaller passes cannot resolve the root problem.

package/iterative-code-quality/references/testing-strategy.md

@@ -0,0 +1,78 @@
+# Risk-Based Testing Strategy
+
+## Principle
+
+Choose tests from the risk inventory, not from a generic coverage target.
+
+For every non-trivial pass, ask what could regress silently if the cleanup were wrong.
+
+## Unit tests
+
+Use for:
+
+- extracted helpers,
+- renamed or simplified business rules,
+- validation and rejection logic,
+- branch-specific errors and side effects,
+- formatting or parsing boundaries.
+
+Good oracles:
+
+- exact return values,
+- exact domain state transitions,
+- exact error class or reason code,
+- emitted side effect or explicit lack of side effect.
+
+## Property-based tests
+
+Use when logic has invariants or broad input space:
+
+- serialization or parsing round trips,
+- sorting, grouping, deduplication, aggregation,
+- authorization or eligibility predicates,
+- idempotency, retry, replay, and state-machine transitions,
+- generated mocked external-service states.
+
+Record `N/A` only with a concrete reason, such as "no generated input space; pass only renamed local variables."
+
+## Integration tests
+
+Use when the risk spans modules:
+
+- orchestration calling extracted domain helpers,
+- persistence plus domain transition,
+- API/CLI handler plus service layer,
+- logging contract across a real execution path,
+- adapter behavior with mocked external services.
+
+For external services, prefer mocks, fakes, local emulators, or recorded stable fixtures unless the real contract is explicitly under test.
+
+## E2E tests
+
+Use only when:
+
+- the project already has reliable E2E infrastructure,
+- the path is user-critical,
+- required external services are stable, controlled, or safely mocked,
+- the same confidence cannot be gained from faster integration tests.
+
+If E2E is unreliable or too costly, add stronger integration coverage and state the reason.
+
+## Edge and adversarial coverage
+
+Consider:
+
+- null, empty, malformed, duplicate, oversized, and boundary inputs,
+- unauthorized actors and invalid transitions,
+- stale, duplicate, out-of-order, or replayed events,
+- dependency timeout, 429/500, partial response, and inconsistent response,
+- partial write, rollback, compensation, and idempotency behavior,
+- concurrency or shared-state contamination when the code is stateful.
+
+## Test hygiene
+
+- Keep tests deterministic and close to the behavior owner.
+- Prefer table-driven cases for many similar business permutations.
+- 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.

package/package.json

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