@laitszkin/apollo-toolkit 3.0.2 → 3.0.4

package/CHANGELOG.md

@@ -7,6 +7,16 @@ All notable changes to this repository are documented in this file.
 ### Changed
 - None yet.
 
+## [v3.0.4] - 2026-04-22
+
+### Changed
+- Strengthen `systematic-debug` so stress, chaos, and edge-case reruns must preserve a minimally executable path, classify globally disabling profiles as toolchain or harness invalidation before blaming product logic, and report whether the final scenario still exercises the target lifecycle stage.
+
+## [v3.0.3] - 2026-04-21
+
+### Changed
+- Strengthen `improve-observability` so ownership-model refactors must audit and repair stale log messages, event names, and structured fields, keeping canonical owners distinct from compatibility projections in telemetry.
+
 ## [v3.0.2] - 2026-04-20
 
 ### Changed

package/improve-observability/SKILL.md

@@ -14,10 +14,10 @@ description: Add focused observability to an existing system so opaque workflows
 
 ## Standards
 
-- Evidence: Read the real execution path and current telemetry before deciding where visibility actually disappears.
-- Execution: Add the smallest useful instrumentation around decision points, scope contracts, outcomes, failure reasons, and any cross-path lifecycle gaps between summary counters and detailed outcome records.
-- Quality: Keep changes behavior-neutral, use structured high-signal telemetry, avoid secrets, and lock the signals with tests.
-- Output: Report which stages are now observable, which fields or metrics to inspect, and which tests validate the instrumentation.
+- Evidence: Read the real execution path, current telemetry, and the true ownership model before deciding where visibility actually disappears or where existing logs no longer describe the live code path.
+- Execution: Add the smallest useful instrumentation around decision points, scope contracts, outcomes, failure reasons, and any cross-path lifecycle gaps between summary counters and detailed outcome records; when observability drift already exists, repair stale log names and structured fields so they match the current owner, scope, and lifecycle semantics.
+- Quality: Keep changes behavior-neutral, use structured high-signal telemetry, avoid secrets, and lock the signals with tests; treat stale terminology after refactors as an observability defect, not harmless wording.
+- Output: Report which stages are now observable, which fields or metrics to inspect, which stale signals were renamed or re-scoped, and which tests validate the instrumentation.
 
 ## Overview
 
@@ -42,6 +42,8 @@ Do not use this skill for generic bug fixing when the main request is behavior c
 - Read the relevant entrypoints, orchestration layers, and current telemetry before editing.
 - Identify the exact stages where information disappears: validation, branching, external calls, persistence, retries, settlement, cleanup, or error handling.
 - When the same business event can flow through multiple execution paths such as harness, replay, batch worker, or production runtime, compare those paths explicitly and find where their observability contract diverges.
+- Identify the canonical owner of the workflow under today's implementation, such as account, request, job, batch, position projection, or transaction step, before changing any log labels or field names.
+- Distinguish canonical owners from compatibility projections or legacy mirrors. If the code still stores or exposes a compatibility projection, keep it diagnosable but do not let logs present that projection as the primary truth.
 - Reuse the project's existing logger, tracing library, metric naming style, and error taxonomy.
 
 ### 2. Choose the smallest useful signals
@@ -80,6 +82,16 @@ When a system reports aggregate counts such as `success_count`, `processed_count
 - treat "aggregate says success but detail table is empty" as an observability bug, not as an acceptable reporting gap
 - if multiple runtime modes claim the same business event, keep the critical observability fields aligned across those modes unless the output contract intentionally differs
 
+### 3.3 Repair terminology drift after refactors
+
+When the codebase has moved from one ownership model or lifecycle model to another, audit existing observability for stale terminology.
+
+- rename log messages, event names, metrics, and structured fields that still describe retired concepts such as old owners, outdated scope units, or deprecated lifecycle phases
+- prefer names that describe the live source of truth, for example `account`, `account_opportunity`, `projection`, `admission_health`, or `projected_step`, instead of legacy names that survived only because a field was never revisited
+- preserve compatibility aliases only when operators or downstream dashboards still require them, and clearly label them as compatibility views rather than canonical truth
+- when a workflow still legitimately mixes canonical owners and derived projections, name both explicitly so operators can tell which field is authoritative
+- update or add tests that lock the renamed signals, especially around branch-specific reason codes, progress events, and structured field keys
+
 ### 3.1 Preserve cross-stage scope contracts
 
 When a workflow derives scope in one stage and consumes it later, make that contract observable end-to-end.
@@ -105,6 +117,7 @@ Add or update tests that prove the new observability survives refactors. Focus o
 - metrics increments for success, skip, and failure paths
 - regression coverage for the exact opaque scenario that motivated the work
 - edge paths such as early-return, dependency failure, and partial completion
+- renamed observability fields or progress-event names after ownership-model or lifecycle refactors
 
 Use existing test helpers for log capture and avoid brittle assertions on timestamps or fully formatted log strings.
 

package/package.json

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

package/systematic-debug/README.md

@@ -14,6 +14,7 @@ Use this skill when:
 - Multiple code paths may explain the same failure
 - You need evidence-backed fixes with reproducible tests
 - You want to reduce regressions from guess-based changes
+- You need to determine whether a stress or chaos profile exposed a product bug or merely disabled the local harness
 
 ## Invocation rule
 
@@ -42,6 +43,7 @@ This skill follows a fixed workflow:
 - **Comprehensive hypotheses**: do not stop at the first guess.
 - **Minimal change**: keep fixes targeted to confirmed failures.
 - **Clear traceability**: map fixes to specific failing-then-passing tests.
+- **Executable pressure**: keep stress and fault profiles adversarial without destroying every path to the lifecycle stage being measured.
 
 ## Typical deliverables
 

package/systematic-debug/SKILL.md

@@ -15,9 +15,9 @@ description: "Systematic debugging workflow for program issues: understand obser
 ## Standards
 
 - Evidence: Gather expected versus observed behavior from code and runtime facts before deciding on a cause, and when the issue involves a runtime pipeline or bounded run, anchor the investigation to one canonical artifact root or run directory instead of mixed terminal snippets from multiple runs; if generated reports or databases drift into an older run directory, capture that mismatch explicitly before treating any artifact as evidence.
-- Execution: Inspect the relevant paths, reproduce every plausible cause with tests or bounded reruns, choose a reproduction mode whose fidelity matches the user's claim, map each observed failure to a concrete pipeline stage, distinguish toolchain/platform faults from application-logic faults, classify failing tests as stale test contract vs test-harness interference vs real product bug, then apply the minimal fix at the true owner.
-- Quality: Keep scope focused on the bug, prefer existing test patterns, explicitly rule out hypotheses that could not be reproduced, and when failures disappear in isolated reruns treat shared-state or parallel-test interference as a first-class hypothesis instead of silently dismissing the original failure.
-- Output: Deliver the plausible-cause list, the canonical evidence source, reproduction tests or reruns, the final failure classification for each investigated symptom, validated fix summary, and passing-test confirmation.
+- Execution: Inspect the relevant paths, reproduce every plausible cause with tests or bounded reruns, choose a reproduction mode whose fidelity matches the user's claim, map each observed failure to a concrete pipeline stage, distinguish toolchain/platform faults from application-logic faults, classify failing tests as stale test contract vs test-harness interference vs real product bug, and when tuning a stress, chaos, or edge-case profile preserve a minimal executable path so the rerun still exercises the target lifecycle stage before applying the minimal fix at the true owner.
+- Quality: Keep scope focused on the bug, prefer existing test patterns, explicitly rule out hypotheses that could not be reproduced, treat shared-state or parallel-test interference as a first-class hypothesis when failures disappear in isolated reruns, and when a fault-injection profile wipes out all execution opportunities first classify that as toolchain, harness, or profile invalidation before blaming product logic.
+- Output: Deliver the plausible-cause list, the canonical evidence source, reproduction tests or reruns, the final failure classification for each investigated symptom, validated fix summary, passing-test confirmation, and when runtime profile tuning was involved state whether the final scenario still preserves meaningful executability.
 
 ## Core Principles
 
@@ -28,6 +28,8 @@ description: "Systematic debugging workflow for program issues: understand obser
 - When comparing runtime runs, first verify the baseline run is complete enough for the requested comparison: same command or scenario, same runtime mode, same bounded duration, and matching structured artifacts. If the baseline is incomplete, report that the only proven change is artifact/run completeness and avoid drawing strategy or performance conclusions from missing data.
 - When a repository has both scenario or harness runs and a production-like runtime, do not treat the lower-fidelity mode as proof about the higher-fidelity mode unless you explicitly state that limitation and the user agrees.
 - When the failing flow crosses multiple layers, identify the last confirmed successful stage before assigning blame.
+- When debugging a stress, chaos, or edge-case profile, keep the profile adversarial but not globally disabling: preserve at least one realistic path that can reach the target stage so the rerun measures product behavior under pressure instead of only proving the harness can self-sabotage.
+- If a profile adjustment restores some execution but the target stage is still unobserved, classify the remaining blocker precisely by stage instead of reporting a blanket recovery.
 - When tests fail, separate stale assertions and fixture drift from real implementation regressions before changing product code.
 - If failures only appear under parallel execution or shared shell-out paths, investigate test isolation, shared locks, temp directories, run-name collisions, and environment leakage before blaming the product.
 
@@ -47,7 +49,7 @@ Also auto-invoke this skill when mismatch evidence appears during normal executi
 
 1. **Understand and inspect**: Parse expected vs observed behavior, explore relevant code paths, record the canonical failing run or artifact root when runtime output is involved, and build a list of plausible root causes.
 2. **Map the failure boundary**: Break the flow into concrete stages such as setup, startup, readiness, steady-state execution, persistence, and shutdown, then identify the last stage that is confirmed to have succeeded.
-3. **Reproduce with tests or bounded reruns**: Write or extend tests that reproduce every plausible cause, and when the bug depends on runtime orchestration rerun the same bounded command or the same runtime mode instead of switching contexts mid-investigation. If the user is asking about real runtime or market behavior, prefer the production-like bounded run over a synthetic scenario replay unless safety or tooling constraints make that impossible. When a failing test passes in isolation, rerun it under the original suite shape to determine whether the real cause is stale expectations, fixture drift, or shared-state interference.
+3. **Reproduce with tests or bounded reruns**: Write or extend tests that reproduce every plausible cause, and when the bug depends on runtime orchestration rerun the same bounded command or the same runtime mode instead of switching contexts mid-investigation. If the user is asking about real runtime or market behavior, prefer the production-like bounded run over a synthetic scenario replay unless safety or tooling constraints make that impossible. When a failing test passes in isolation, rerun it under the original suite shape to determine whether the real cause is stale expectations, fixture drift, or shared-state interference. When stress or chaos configuration is part of the reproduction, keep the pressure profile strong enough to preserve the intended edge cases while still allowing at least partial traversal of the target lifecycle stage.
 4. **Diagnose and confirm**: Use reproduction evidence to confirm the true root cause, explicitly rule out non-causes, and classify whether each investigated failure belongs to the toolchain/platform layer, test contract drift, test-harness interference, orchestration, or application logic.
 5. **Fix and validate**: Implement focused fixes and iterate until all reproduction tests or bounded reruns pass.
 
@@ -62,6 +64,7 @@ Also auto-invoke this skill when mismatch evidence appears during normal executi
 - When rerun artifacts land in the wrong directory because a wrapper or inherited environment reused a previous report path, fix the evidence layout first and only then compare metrics; otherwise classify the result as an artifact-routing problem rather than a performance delta.
 - For post-run "why did most events not happen" questions, derive the answer from a funnel over structured artifacts first, then corroborate with logs: discovered or eligible candidates, admission blocks, stale or skipped decisions, queue/governor outcomes, execution attempts, confirmations, retries, and persisted event rows.
 - For speed questions, compute per-stage timings from available event timestamps and state which stages are measured versus unavailable; avoid treating wall-clock bounded duration as pipeline latency, and separately report bounded execute time versus provisioning/readiness/cleanup overhead when both are present.
+- When a runtime profile adds extreme faults, distinguish "edge cases are present" from "the harness globally disabled execution"; if every candidate dies before the claimed stage, reduce only the globally disabling parts, keep representative faults, and rerun the same bounded scenario to prove the profile still exercises the target path.
 - When test fixtures or assertions no longer match the implemented contract, update the tests instead of weakening the product behavior to satisfy stale expectations.
 - When tests shell out to shared local infrastructure, add deterministic isolation such as mutexes, unique temp roots, or serialized sections before accepting flakes as inevitable.
 

package/systematic-debug/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Systematic Debug"
   short_description: "Diagnose bugs with reproduction tests before fixing"
-  default_prompt: "Use $systematic-debug to understand expected vs observed behavior, inspect relevant code paths, write or extend tests for every plausible cause, confirm the true root cause from reproduction evidence, apply the smallest focused fix, and validate with passing tests."
+  default_prompt: "Use $systematic-debug to understand expected vs observed behavior, inspect relevant code paths, write or extend tests for every plausible cause, confirm the true root cause from reproduction evidence, and classify each symptom as toolchain/platform, harness interference, stale test contract, or real product bug before fixing. When the issue involves a bounded runtime, stress profile, or chaos harness, anchor on one canonical run root, map failures to concrete lifecycle stages, preserve a minimally executable path while tuning the profile, and rerun the same bounded scenario to prove the target stage still executes under pressure."