From b8b3698d1d0da65a96b1882017f792799a700572 Mon Sep 17 00:00:00 2001
From: ArchieIndian <mitra.arkid@gmail.com>
Date: Sun, 29 Mar 2026 16:49:33 +0530
Subject: [PATCH] Clean up docs and refactor state helpers

---
 CHANGELOG.md                                  | 10 +++
 CONTRIBUTING.md                               | 12 +++-
 README.md                                     | 19 ++++++
 docs/OPERATIONS.md                            | 68 +++++++++++++++++++
 scripts/state_helpers.py                      | 68 +++++++++++++++++++
 .../cron-execution-prover/prove.py            | 38 +++--------
 .../deployment-preflight/check.py             | 38 ++++-------
 .../mcp-auth-lifecycle-manager/manage.py      | 46 ++++---------
 .../message-delivery-verifier/verify.py       | 38 +++--------
 .../session-reset-recovery/recover.py         | 34 +++-------
 .../upgrade-rollback-manager/manage.py        | 35 ++++------
 tests/test-runner.sh                          | 56 ++++++++-------
 12 files changed, 274 insertions(+), 188 deletions(-)
 create mode 100644 docs/OPERATIONS.md
 create mode 100644 scripts/state_helpers.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4035d16..77ecb90 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,15 @@
 # Changelog
 
+## [0.2.0] - 2026-03-29
+
+### Added
+- Runtime reliability skills: `runtime-verification-dashboard`, `deployment-preflight`, `session-reset-recovery`, `cron-execution-prover`, `message-delivery-verifier`, `subagent-capability-auditor`, `upgrade-rollback-manager`, and `mcp-auth-lifecycle-manager`
+- Operational playbooks in `docs/OPERATIONS.md`
+
+### Changed
+- README and contributor guidance now reflect the expanded operational skill set and validation workflow
+- New shared `scripts/state_helpers.py` reduces repeated state loading and saving code across recent Python helpers
+
 ## [0.1.0] - 2026-03-15
 
 ### Added
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 14c0d57..84b4d40 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -6,7 +6,7 @@ We'd love your skills! Here's how to contribute.
 
 1. **Propose your idea** — [Open a Skill Proposal issue](../../issues/new?template=skill-proposal.yml) to get feedback
 2. **Create the skill** — Use the `create-skill` superpower or copy the [template](skills/core/create-skill/TEMPLATE.md)
-3. **Validate locally** — Run `./scripts/validate-skills.sh` to catch issues
+3. **Validate locally** — Run `./scripts/validate-skills.sh` and `bash ./tests/test-runner.sh`
 4. **Submit a PR** — CI validates automatically on any PR that touches `skills/`
 
 ## Where to Put Your Skill
@@ -46,7 +46,15 @@ Run the validation script before submitting:
 ./scripts/validate-skills.sh
 ```
 
-It checks: frontmatter format, naming conventions, file structure, line count, stateful skill coherence (`STATE_SCHEMA.yaml` present when `stateful: true`), and cron expression format.
+It checks: frontmatter format, naming conventions, file structure, line count, stateful skill coherence (`STATE_SCHEMA.yaml` present when `stateful: true`), cron expression format, and README inventory metrics.
+
+Run the repository smoke tests too:
+
+```bash
+bash ./tests/test-runner.sh
+```
+
+If you are adding or updating a stateful helper script, prefer reusing the shared helpers in `scripts/state_helpers.py` instead of open-coding the same YAML/JSON state loader again.
 
 ## Pull Requests
 
diff --git a/README.md b/README.md
index 41a7a55..e723f26 100644
--- a/README.md
+++ b/README.md
@@ -61,6 +61,22 @@ openclaw gateway restart
 
 Install `PyYAML` before using the stateful Python helpers: `python3 -m pip install PyYAML`.
 
+For operator workflows and rollout order, see [docs/OPERATIONS.md](docs/OPERATIONS.md).
+
+---
+
+## Start Here
+
+If you are adopting the repo for real unattended usage, start in this order:
+
+1. Run `deployment-preflight` before the first install or after Docker/compose changes.
+2. Install the repo and run `runtime-verification-dashboard` once the runtime is live.
+3. Wrap scheduled work with `cron-execution-prover` and `message-delivery-verifier`.
+4. Add `session-reset-recovery` and `upgrade-rollback-manager` before relying on overnight or upgrade-heavy automation.
+5. If you use MCP servers, pair `mcp-health-checker` with `mcp-auth-lifecycle-manager`.
+
+This gives you deployment safety, runtime visibility, proof of execution, proof of delivery, reset survival, rollback coverage, and MCP auth coverage without enabling every skill at once.
+
 ---
 
 ## Skills included
@@ -259,6 +275,9 @@ Skills marked with a script ship a small executable alongside their `SKILL.md`:
 **Self-hosted or Docker deployment**
 > Run `deployment-preflight` before the first rollout or after compose changes to catch missing mounts, missing bootstrap files, and public gateway exposure. Follow it with `runtime-verification-dashboard` once the runtime is live.
 
+**Operators building a reliability stack**
+> Use the playbooks in [docs/OPERATIONS.md](docs/OPERATIONS.md) to layer deployment safety, cron proofing, delivery verification, reset recovery, upgrade rollback, and MCP auth checks in a sane order.
+
 **Open-source maintainer**
 > `community-skill-radar` scans Reddit for pain points automatically. `skill-vetting` catches malicious community contributions before they're installed. `installed-skill-auditor` detects post-install tampering.
 
diff --git a/docs/OPERATIONS.md b/docs/OPERATIONS.md
new file mode 100644
index 0000000..7ebd538
--- /dev/null
+++ b/docs/OPERATIONS.md
@@ -0,0 +1,68 @@
+# Operational Playbooks
+
+This repo has enough always-on skills now that the useful question is no longer "which skills exist?" but "which ones should I turn on together?"
+
+Use these playbooks as a rollout order.
+
+## 1. First deployment
+
+Use this when bringing up OpenClaw on a laptop, server, or Docker host for the first time.
+
+1. Run `deployment-preflight` before install or after any compose change.
+2. Install `openclaw-superpowers`.
+3. Run `runtime-verification-dashboard` once the runtime is live.
+4. Fix any missing mounts, missing bootstrap files, missing cron registrations, or state path issues before enabling unattended workflows.
+
+Why this order:
+- `deployment-preflight` catches layout and exposure mistakes before the runtime starts.
+- `runtime-verification-dashboard` catches post-install drift inside the live runtime.
+
+## 2. Scheduled workflow with proof
+
+Use this when a cron workflow writes files, posts a report, or notifies a human.
+
+1. Wrap the workflow in `cron-execution-prover`.
+2. Track the last-mile notification in `message-delivery-verifier`.
+3. Review stale executions and stale deliveries before trusting the automation.
+
+Why this order:
+- `cron-execution-prover` proves the job started and finished.
+- `message-delivery-verifier` proves the output was actually sent and acknowledged.
+
+## 3. Overnight continuity
+
+Use this when long-running work regularly crosses the session reset window.
+
+1. Enable `session-reset-recovery`.
+2. Pair it with `task-handoff` for tasks that may span multiple sessions or agents.
+3. Review `resume_brief` output after restart before resuming work.
+
+Why this order:
+- `session-reset-recovery` preserves the active checkpoint.
+- `task-handoff` keeps the next operator or session from restarting blind.
+
+## 4. Safer upgrades
+
+Use this before changing OpenClaw versions, config structure, or deployment layout.
+
+1. Run `upgrade-rollback-manager --snapshot`.
+2. Apply the upgrade.
+3. Re-run `deployment-preflight`.
+4. Re-run `runtime-verification-dashboard`.
+5. If something regresses, generate rollback instructions with `upgrade-rollback-manager --rollback-plan <label>`.
+
+Why this order:
+- Snapshot first.
+- Then verify both the deployment surface and the live runtime after the change.
+
+## 5. MCP-dependent automation
+
+Use this when OpenClaw depends on GitHub, Linear, filesystem, browser, or other MCP servers.
+
+1. Use `mcp-health-checker` to verify transport reachability.
+2. Use `mcp-auth-lifecycle-manager` to verify token expiry, env vars, and refresh readiness.
+3. Avoid unattended dependency on MCP servers that still require interactive re-authentication.
+
+Why this order:
+- Reachability and auth are different failure modes.
+- A healthy server can still be unusable if the auth path is broken.
diff --git a/scripts/state_helpers.py b/scripts/state_helpers.py
new file mode 100644
index 0000000..117f459
--- /dev/null
+++ b/scripts/state_helpers.py
@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import copy
+import json
+import os
+from datetime import datetime
+from pathlib import Path
+
+try:
+    import yaml
+
+    HAS_YAML = True
+except ImportError:
+    HAS_YAML = False
+
+
+def openclaw_dir() -> Path:
+    return Path(os.environ.get("OPENCLAW_HOME", Path.home() / ".openclaw"))
+
+
+def skill_state_file(skill_name: str, filename: str = "state.yaml") -> Path:
+    return openclaw_dir() / "skill-state" / skill_name / filename
+
+
+def now_iso(timespec: str = "seconds") -> str:
+    return datetime.now().isoformat(timespec=timespec)
+
+
+def _default_value(default_factory):
+    if callable(default_factory):
+        return default_factory()
+    return copy.deepcopy(default_factory)
+
+
+def load_state(path: Path, default_factory) -> dict:
+    default_value = _default_value(default_factory)
+    if not path.exists():
+        return default_value
+    try:
+        text = path.read_text()
+        if HAS_YAML:
+            return yaml.safe_load(text) or _default_value(default_factory)
+        return json.loads(text)
+    except Exception:
+        return _default_value(default_factory)
+
+
+def save_state(path: Path, state: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if HAS_YAML:
+        with open(path, "w") as handle:
+            yaml.dump(state, handle, default_flow_style=False, allow_unicode=True, sort_keys=False)
+    else:
+        path.write_text(json.dumps(state, indent=2))
+
+
+def load_structured(path: Path, default_factory=dict):
+    if not path.exists():
+        return _default_value(default_factory)
+    try:
+        text = path.read_text()
+        if path.suffix == ".json":
+            return json.loads(text)
+        if HAS_YAML:
+            return yaml.safe_load(text) or _default_value(default_factory)
+    except Exception:
+        pass
+    return _default_value(default_factory)
diff --git a/skills/openclaw-native/cron-execution-prover/prove.py b/skills/openclaw-native/cron-execution-prover/prove.py
index 40df24b..eb54574 100755
--- a/skills/openclaw-native/cron-execution-prover/prove.py
+++ b/skills/openclaw-native/cron-execution-prover/prove.py
@@ -10,18 +10,19 @@
 
 import argparse
 import json
-import os
+import sys
 from datetime import datetime
 from pathlib import Path
 
-try:
-    import yaml
-    HAS_YAML = True
-except ImportError:
-    HAS_YAML = False
+REPO_ROOT = Path(__file__).resolve().parents[3]
+SCRIPTS_DIR = REPO_ROOT / "scripts"
+if str(SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIR))
 
-OPENCLAW_DIR = Path(os.environ.get("OPENCLAW_HOME", Path.home() / ".openclaw"))
-STATE_FILE = OPENCLAW_DIR / "skill-state" / "cron-execution-prover" / "state.yaml"
+from state_helpers import load_state as load_state_file
+from state_helpers import now_iso, save_state as save_state_file, skill_state_file
+
+STATE_FILE = skill_state_file("cron-execution-prover")
 MAX_RUNS = 100
 MAX_HISTORY = 12
 STALE_AFTER_MINUTES = 60
@@ -37,28 +38,11 @@ def default_state() -> dict:
 
 
 def load_state() -> dict:
-    if not STATE_FILE.exists():
-        return default_state()
-    try:
-        text = STATE_FILE.read_text()
-        if HAS_YAML:
-            return yaml.safe_load(text) or default_state()
-        return json.loads(text)
-    except Exception:
-        return default_state()
+    return load_state_file(STATE_FILE, default_state)
 
 
 def save_state(state: dict) -> None:
-    STATE_FILE.parent.mkdir(parents=True, exist_ok=True)
-    if HAS_YAML:
-        with open(STATE_FILE, "w") as handle:
-            yaml.dump(state, handle, default_flow_style=False, allow_unicode=True, sort_keys=False)
-    else:
-        STATE_FILE.write_text(json.dumps(state, indent=2))
-
-
-def now_iso() -> str:
-    return datetime.now().isoformat(timespec="seconds")
+    save_state_file(STATE_FILE, state)
 
 
 def find_run(state: dict, skill: str, run_id: str) -> dict | None:
diff --git a/skills/openclaw-native/deployment-preflight/check.py b/skills/openclaw-native/deployment-preflight/check.py
index d45c7da..9e90fad 100755
--- a/skills/openclaw-native/deployment-preflight/check.py
+++ b/skills/openclaw-native/deployment-preflight/check.py
@@ -23,17 +23,18 @@
 import shutil
 import subprocess
 import sys
-from datetime import datetime
 from pathlib import Path
 
-try:
-    import yaml
-    HAS_YAML = True
-except ImportError:
-    HAS_YAML = False
+REPO_ROOT = Path(__file__).resolve().parents[3]
+SCRIPTS_DIR = REPO_ROOT / "scripts"
+if str(SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIR))
 
-OPENCLAW_DIR = Path(os.environ.get("OPENCLAW_HOME", Path.home() / ".openclaw"))
-STATE_FILE = OPENCLAW_DIR / "skill-state" / "deployment-preflight" / "state.yaml"
+from state_helpers import HAS_YAML, load_state as load_state_file
+from state_helpers import now_iso, openclaw_dir, save_state as save_state_file, skill_state_file
+
+OPENCLAW_DIR = openclaw_dir()
+STATE_FILE = skill_state_file("deployment-preflight")
 WORKSPACE_DIR = Path(os.environ.get("OPENCLAW_WORKSPACE", OPENCLAW_DIR / "workspace"))
 SUPERPOWERS_PATH = OPENCLAW_DIR / "extensions" / "superpowers"
 MAX_HISTORY = 12
@@ -61,24 +62,11 @@ def default_state() -> dict:
 
 
 def load_state() -> dict:
-    if not STATE_FILE.exists():
-        return default_state()
-    try:
-        text = STATE_FILE.read_text()
-        if HAS_YAML:
-            return yaml.safe_load(text) or default_state()
-        return json.loads(text)
-    except Exception:
-        return default_state()
+    return load_state_file(STATE_FILE, default_state)
 
 
 def save_state(state: dict) -> None:
-    STATE_FILE.parent.mkdir(parents=True, exist_ok=True)
-    if HAS_YAML:
-        with open(STATE_FILE, "w") as handle:
-            yaml.dump(state, handle, default_flow_style=False, allow_unicode=True, sort_keys=False)
-    else:
-        STATE_FILE.write_text(json.dumps(state, indent=2))
+    save_state_file(STATE_FILE, state)
 
 
 def finding(severity: str, check: str, detail: str, suggestion: str, file_path: Path | str = "") -> dict:
@@ -88,7 +76,7 @@ def finding(severity: str, check: str, detail: str, suggestion: str, file_path:
         "detail": detail,
         "suggestion": suggestion,
         "file_path": str(file_path),
-        "detected_at": datetime.now().isoformat(),
+        "detected_at": now_iso(),
         "resolved": False,
     }
 
@@ -401,7 +389,7 @@ def run_check(root: Path) -> dict:
 
     state = load_state()
     history = state.get("check_history") or []
-    now = datetime.now().isoformat()
+    now = now_iso()
     history.insert(
         0,
         {
diff --git a/skills/openclaw-native/mcp-auth-lifecycle-manager/manage.py b/skills/openclaw-native/mcp-auth-lifecycle-manager/manage.py
index 60a08fe..db8b171 100755
--- a/skills/openclaw-native/mcp-auth-lifecycle-manager/manage.py
+++ b/skills/openclaw-native/mcp-auth-lifecycle-manager/manage.py
@@ -11,17 +11,21 @@
 import json
 import os
 import re
+import sys
 from datetime import datetime, timedelta
 from pathlib import Path
 
-try:
-    import yaml
-    HAS_YAML = True
-except ImportError:
-    HAS_YAML = False
+REPO_ROOT = Path(__file__).resolve().parents[3]
+SCRIPTS_DIR = REPO_ROOT / "scripts"
+if str(SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIR))
 
-OPENCLAW_DIR = Path(os.environ.get("OPENCLAW_HOME", Path.home() / ".openclaw"))
-STATE_FILE = OPENCLAW_DIR / "skill-state" / "mcp-auth-lifecycle-manager" / "state.yaml"
+from state_helpers import load_state as load_state_file
+from state_helpers import load_structured as load_structured_file, now_iso, openclaw_dir
+from state_helpers import save_state as save_state_file, skill_state_file
+
+OPENCLAW_DIR = openclaw_dir()
+STATE_FILE = skill_state_file("mcp-auth-lifecycle-manager")
 MAX_HISTORY = 20
 
 MCP_CONFIG_PATHS = [
@@ -57,37 +61,15 @@ def default_state() -> dict:
 
 
 def load_structured(path: Path) -> dict:
-    text = path.read_text()
-    if path.suffix == ".json":
-        return json.loads(text)
-    if HAS_YAML:
-        return yaml.safe_load(text) or {}
-    return {}
+    return load_structured_file(path, dict)
 
 
 def load_state() -> dict:
-    if not STATE_FILE.exists():
-        return default_state()
-    try:
-        text = STATE_FILE.read_text()
-        if HAS_YAML:
-            return yaml.safe_load(text) or default_state()
-        return json.loads(text)
-    except Exception:
-        return default_state()
+    return load_state_file(STATE_FILE, default_state)
 
 
 def save_state(state: dict) -> None:
-    STATE_FILE.parent.mkdir(parents=True, exist_ok=True)
-    if HAS_YAML:
-        with open(STATE_FILE, "w") as handle:
-            yaml.dump(state, handle, default_flow_style=False, allow_unicode=True, sort_keys=False)
-    else:
-        STATE_FILE.write_text(json.dumps(state, indent=2))
-
-
-def now_iso() -> str:
-    return datetime.now().isoformat(timespec="seconds")
+    save_state_file(STATE_FILE, state)
 
 
 def find_config(paths: list[Path]) -> tuple[Path | None, dict]:
diff --git a/skills/openclaw-native/message-delivery-verifier/verify.py b/skills/openclaw-native/message-delivery-verifier/verify.py
index cdd838a..13242db 100755
--- a/skills/openclaw-native/message-delivery-verifier/verify.py
+++ b/skills/openclaw-native/message-delivery-verifier/verify.py
@@ -9,18 +9,19 @@
 
 import argparse
 import json
-import os
+import sys
 from datetime import datetime
 from pathlib import Path
 
-try:
-    import yaml
-    HAS_YAML = True
-except ImportError:
-    HAS_YAML = False
+REPO_ROOT = Path(__file__).resolve().parents[3]
+SCRIPTS_DIR = REPO_ROOT / "scripts"
+if str(SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIR))
 
-OPENCLAW_DIR = Path(os.environ.get("OPENCLAW_HOME", Path.home() / ".openclaw"))
-STATE_FILE = OPENCLAW_DIR / "skill-state" / "message-delivery-verifier" / "state.yaml"
+from state_helpers import load_state as load_state_file
+from state_helpers import now_iso, save_state as save_state_file, skill_state_file
+
+STATE_FILE = skill_state_file("message-delivery-verifier")
 MAX_DELIVERIES = 200
 MAX_HISTORY = 12
 STALE_AFTER_MINUTES = 60
@@ -36,28 +37,11 @@ def default_state() -> dict:
 
 
 def load_state() -> dict:
-    if not STATE_FILE.exists():
-        return default_state()
-    try:
-        text = STATE_FILE.read_text()
-        if HAS_YAML:
-            return yaml.safe_load(text) or default_state()
-        return json.loads(text)
-    except Exception:
-        return default_state()
+    return load_state_file(STATE_FILE, default_state)
 
 
 def save_state(state: dict) -> None:
-    STATE_FILE.parent.mkdir(parents=True, exist_ok=True)
-    if HAS_YAML:
-        with open(STATE_FILE, "w") as handle:
-            yaml.dump(state, handle, default_flow_style=False, allow_unicode=True, sort_keys=False)
-    else:
-        STATE_FILE.write_text(json.dumps(state, indent=2))
-
-
-def now_iso() -> str:
-    return datetime.now().isoformat(timespec="seconds")
+    save_state_file(STATE_FILE, state)
 
 
 def find_delivery(state: dict, delivery_id: str) -> dict | None:
diff --git a/skills/openclaw-native/session-reset-recovery/recover.py b/skills/openclaw-native/session-reset-recovery/recover.py
index 732ec01..d008844 100755
--- a/skills/openclaw-native/session-reset-recovery/recover.py
+++ b/skills/openclaw-native/session-reset-recovery/recover.py
@@ -8,18 +8,19 @@
 
 import argparse
 import json
-import os
+import sys
 from datetime import datetime
 from pathlib import Path
 
-try:
-    import yaml
-    HAS_YAML = True
-except ImportError:
-    HAS_YAML = False
+REPO_ROOT = Path(__file__).resolve().parents[3]
+SCRIPTS_DIR = REPO_ROOT / "scripts"
+if str(SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIR))
 
-OPENCLAW_DIR = Path(os.environ.get("OPENCLAW_HOME", Path.home() / ".openclaw"))
-STATE_FILE = OPENCLAW_DIR / "skill-state" / "session-reset-recovery" / "state.yaml"
+from state_helpers import load_state as load_state_file
+from state_helpers import save_state as save_state_file, skill_state_file
+
+STATE_FILE = skill_state_file("session-reset-recovery")
 MAX_HISTORY = 12
 
 
@@ -34,24 +35,11 @@ def default_state() -> dict:
 
 
 def load_state() -> dict:
-    if not STATE_FILE.exists():
-        return default_state()
-    try:
-        text = STATE_FILE.read_text()
-        if HAS_YAML:
-            return yaml.safe_load(text) or default_state()
-        return json.loads(text)
-    except Exception:
-        return default_state()
+    return load_state_file(STATE_FILE, default_state)
 
 
 def save_state(state: dict) -> None:
-    STATE_FILE.parent.mkdir(parents=True, exist_ok=True)
-    if HAS_YAML:
-        with open(STATE_FILE, "w") as handle:
-            yaml.dump(state, handle, default_flow_style=False, allow_unicode=True, sort_keys=False)
-    else:
-        STATE_FILE.write_text(json.dumps(state, indent=2))
+    save_state_file(STATE_FILE, state)
 
 
 def build_resume_brief(checkpoint: dict) -> str:
diff --git a/skills/openclaw-native/upgrade-rollback-manager/manage.py b/skills/openclaw-native/upgrade-rollback-manager/manage.py
index d04372e..2e7bd77 100755
--- a/skills/openclaw-native/upgrade-rollback-manager/manage.py
+++ b/skills/openclaw-native/upgrade-rollback-manager/manage.py
@@ -10,20 +10,22 @@
 
 import argparse
 import json
-import os
 import shutil
 import subprocess
+import sys
 from datetime import datetime
 from pathlib import Path
 
-try:
-    import yaml
-    HAS_YAML = True
-except ImportError:
-    HAS_YAML = False
+REPO_ROOT = Path(__file__).resolve().parents[3]
+SCRIPTS_DIR = REPO_ROOT / "scripts"
+if str(SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIR))
 
-OPENCLAW_DIR = Path(os.environ.get("OPENCLAW_HOME", Path.home() / ".openclaw"))
-STATE_FILE = OPENCLAW_DIR / "skill-state" / "upgrade-rollback-manager" / "state.yaml"
+from state_helpers import load_state as load_state_file
+from state_helpers import openclaw_dir, save_state as save_state_file, skill_state_file
+
+OPENCLAW_DIR = openclaw_dir()
+STATE_FILE = skill_state_file("upgrade-rollback-manager")
 SNAPSHOT_ROOT = OPENCLAW_DIR / "rollback-snapshots"
 MAX_HISTORY = 12
 PRESERVED_PATHS = [
@@ -44,24 +46,11 @@ def default_state() -> dict:
 
 
 def load_state() -> dict:
-    if not STATE_FILE.exists():
-        return default_state()
-    try:
-        text = STATE_FILE.read_text()
-        if HAS_YAML:
-            return yaml.safe_load(text) or default_state()
-        return json.loads(text)
-    except Exception:
-        return default_state()
+    return load_state_file(STATE_FILE, default_state)
 
 
 def save_state(state: dict) -> None:
-    STATE_FILE.parent.mkdir(parents=True, exist_ok=True)
-    if HAS_YAML:
-        with open(STATE_FILE, "w") as handle:
-            yaml.dump(state, handle, default_flow_style=False, allow_unicode=True, sort_keys=False)
-    else:
-        STATE_FILE.write_text(json.dumps(state, indent=2))
+    save_state_file(STATE_FILE, state)
 
 
 def detect_openclaw_version() -> str:
diff --git a/tests/test-runner.sh b/tests/test-runner.sh
index 89baef4..c38a256 100755
--- a/tests/test-runner.sh
+++ b/tests/test-runner.sh
@@ -4,41 +4,39 @@ set -euo pipefail
 REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 SKILLS_DIR="$REPO_DIR/skills"
 PASS=0; FAIL=0
-for skill_dir in "$SKILLS_DIR"/**/*; do
-  if [ -d "$skill_dir" ]; then
-    skill_name="$(basename "$skill_dir")"
-    label="$skill_name"
+while IFS= read -r skill_dir; do
+  skill_name="$(basename "$skill_dir")"
+  label="$skill_name"
 
-    # Check SKILL.md exists
-    if [ ! -f "$skill_dir/SKILL.md" ]; then
-      echo "FAIL: $skill_name missing SKILL.md"; FAIL=$((FAIL+1))
-      continue
-    fi
-
-    # Check stateful coherence: stateful: true requires STATE_SCHEMA.yaml
-    fm_stateful="$(sed -n '2,/^---$/p' "$skill_dir/SKILL.md" | grep '^stateful:' | sed 's/^stateful: *//' | tr -d '[:space:]' || true)"
-    if [ "$fm_stateful" = "true" ] && [ ! -f "$skill_dir/STATE_SCHEMA.yaml" ]; then
-      echo "FAIL: $skill_name stateful: true but STATE_SCHEMA.yaml missing"; FAIL=$((FAIL+1))
-      continue
-    fi
+  # Check SKILL.md exists
+  if [ ! -f "$skill_dir/SKILL.md" ]; then
+    echo "FAIL: $skill_name missing SKILL.md"; FAIL=$((FAIL+1))
+    continue
+  fi
 
-    # Check cron format if present
-    fm_cron="$(sed -n '2,/^---$/p' "$skill_dir/SKILL.md" | grep '^cron:' | sed 's/^cron: *//' | tr -d '"'"'" || true)"
-    if [ -n "$fm_cron" ]; then
-      if ! echo "$fm_cron" | grep -qE '^[0-9*/,\-]+ [0-9*/,\-]+ [0-9*/,\-]+ [0-9*/,\-]+ [0-9*/,\-]+$'; then
-        echo "FAIL: $skill_name invalid cron expression '$fm_cron'"; FAIL=$((FAIL+1))
-        continue
-      fi
-    fi
+  # Check stateful coherence: stateful: true requires STATE_SCHEMA.yaml
+  fm_stateful="$(sed -n '2,/^---$/p' "$skill_dir/SKILL.md" | grep '^stateful:' | sed 's/^stateful: *//' | tr -d '[:space:]' || true)"
+  if [ "$fm_stateful" = "true" ] && [ ! -f "$skill_dir/STATE_SCHEMA.yaml" ]; then
+    echo "FAIL: $skill_name stateful: true but STATE_SCHEMA.yaml missing"; FAIL=$((FAIL+1))
+    continue
+  fi
 
-    # Append [stateful] tag to label when applicable
-    if [ "$fm_stateful" = "true" ]; then
-      label="$skill_name [stateful]"
+  # Check cron format if present
+  fm_cron="$(sed -n '2,/^---$/p' "$skill_dir/SKILL.md" | grep '^cron:' | sed 's/^cron: *//' | tr -d '"'"'" || true)"
+  if [ -n "$fm_cron" ]; then
+    if ! echo "$fm_cron" | grep -qE '^[0-9*/,\-]+ [0-9*/,\-]+ [0-9*/,\-]+ [0-9*/,\-]+ [0-9*/,\-]+$'; then
+      echo "FAIL: $skill_name invalid cron expression '$fm_cron'"; FAIL=$((FAIL+1))
+      continue
     fi
+  fi
 
-    echo "PASS: $label"; PASS=$((PASS+1))
+  # Append [stateful] tag to label when applicable
+  if [ "$fm_stateful" = "true" ]; then
+    label="$skill_name [stateful]"
   fi
-done
+
+  echo "PASS: $label"; PASS=$((PASS+1))
+done < <(find "$SKILLS_DIR" -mindepth 2 -maxdepth 2 -type d | sort)
 "$REPO_DIR/scripts/check-readme-metrics.sh"
 echo "Results: $PASS passed, $FAIL failed"
 [ $FAIL -eq 0 ]