@laitszkin/apollo-toolkit 3.0.1 → 3.0.3

package/CHANGELOG.md

@@ -7,6 +7,17 @@ All notable changes to this repository are documented in this file.
 ### Changed
 - None yet.
 
+## [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
+- Strengthen `scheduled-runtime-health-check` so bounded-run investigations must detect artifact-path drift, reconcile reports back to one canonical run root before comparison, and report bounded execute time separately from setup and shutdown overhead.
+- Strengthen `systematic-debug` so runtime reruns that inherit stale report paths are classified as artifact-routing problems before any performance conclusion, and speed analysis now separates execute time from provisioning/readiness/cleanup overhead.
+
 ## [v3.0.1] - 2026-04-19
 
 ### 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.1",
+  "version": "3.0.3",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",

package/scheduled-runtime-health-check/SKILL.md

@@ -14,7 +14,7 @@ description: Use a background terminal to run a user-specified command immediate
 
 ## Standards
 
-- Evidence: Anchor every conclusion to the requested command, execution window, startup/shutdown timestamps, one canonical run folder or artifact root, captured logs, and concrete runtime signals.
+- Evidence: Anchor every conclusion to the requested command, execution window, startup/shutdown timestamps, one canonical run folder or artifact root, captured logs, and concrete runtime signals; when structured artifacts land outside that canonical root because of inherited environment or wrapper drift, prove the mismatch and treat the artifact-path correction as part of the evidence trail.
 - Execution: Collect the run contract, verify the real stop mechanism before launch, choose the highest-fidelity execution mode that matches the user's intent, use a background terminal, optionally update the code only when the user asks, execute the requested command immediately or in the requested window, record the canonical run folder once the process materializes it, capture logs, stop cleanly when bounded, then delegate log review to `analyse-app-logs` only when findings are requested or needed.
 - Quality: Keep scheduling, execution, and shutdown deterministic; separate confirmed findings from hypotheses; and mark each assessed module healthy/degraded/failed/unknown with reasons.
 - Output: Return the run configuration, execution status, log locations, optional code-update result, optional module health by area, confirmed issues, potential issues, observability gaps, and scheduler status when applicable.
@@ -53,6 +53,7 @@ This skill is an orchestration layer. It owns the background terminal session, o
 - Separate scheduler failures, boot failures, runtime failures, and shutdown failures.
 - For complex pipelines, identify the last successful stage before attributing the failure to application logic.
 - When the user asks to compare a bounded run with a previous run, compare only runs with the same command or preset, duration, runtime mode, and complete structured artifacts. If the previous run lacks canonical reports, databases, or startup artifacts, mark the runs incomparable and explain the artifact completeness gap instead of inventing performance deltas.
+- When wrappers, copied environments, or report-path variables cause the current run's report or database to land under an older run directory, stop and reconcile the artifact root before analysis: record the intended run root, locate the actual emitted files, move or copy them back only when needed to restore one canonical evidence set, and report the path drift as an observability problem instead of silently mixing runs.
 - If logs cannot support a health judgment, mark the module as `unknown` instead of guessing.
 
 ## Required workflow
@@ -80,6 +81,7 @@ This skill is an orchestration layer. It owns the background terminal session, o
 5. Run and capture readiness
    - Execute the requested command in the same background terminal.
    - As soon as the command emits or creates its canonical run directory, artifact root, or equivalent output location, record that path and reuse it for every later check.
+   - If later structured outputs appear under a different directory than the recorded run root, pause the analysis and reconcile the mismatch before reading metrics or logs from either location.
    - Report the exact runtime mode used in the evidence record so later analysis does not accidentally treat synthetic-harness results as proof about production behavior.
    - Wait for a concrete readiness signal when the command is expected to stay up, such as a health endpoint, listening-port log, worker boot line, or queue-consumer ready message.
    - If readiness never arrives, stop the run, preserve logs, and treat it as a failed startup window.
@@ -99,6 +101,7 @@ This skill is an orchestration layer. It owns the background terminal session, o
    - Reuse its confirmed issues, hypotheses, and monitoring improvements instead of rewriting a separate incident workflow.
 8. Produce the final report
    - Always summarize the actual command executed, actual start/end timestamps, execution status, and log locations.
+   - Separate bounded execute time from setup, readiness, collection, and shutdown overhead so a 2-minute observation is not misreported as 2 minutes of end-to-end pipeline latency.
    - Include the code-update result only when an update step was requested.
    - When findings were requested, classify each relevant module as `healthy`, `degraded`, `failed`, or `unknown` with concrete evidence and separate observed issues from risks that still need validation.
 
@@ -125,7 +128,7 @@ Absence of errors alone is not enough for `healthy`.
 Use this structure in responses:
 
 1. Run summary
-   - Workspace, command, schedule if any, actual start/end timestamps, duration if bounded, readiness result, shutdown result if applicable, canonical run folder or artifact root, and log locations.
+   - Workspace, command, schedule if any, actual start/end timestamps, bounded execute duration, total wall-clock duration, readiness result, shutdown result if applicable, canonical run folder or artifact root, and log locations.
 2. Execution result
    - Whether the command completed, stayed up for the requested window, or failed early.
 3. Code update result

package/systematic-debug/SKILL.md

@@ -14,7 +14,7 @@ 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.
+- 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.
@@ -59,8 +59,9 @@ Also auto-invoke this skill when mismatch evidence appears during normal executi
 - If a hypothesized cause cannot be reproduced, document why and deprioritize it explicitly.
 - For long-running or generated-artifact workflows, record the exact command, timestamps, and artifact paths before inspecting outputs so later comparisons stay on the same evidence set.
 - Do not mix baseline data and rerun data casually; compare the same scenario or command across runs and call out when a conclusion comes from a rerun rather than the original failure.
+- 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.
+- 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 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.