feat(core): safety trinity — SKIPPER_FAIL_OPEN, SKIPPER_CACHE_TTL, SKIPPER_SYNC_ALLOW_DELETE

- SKIPPER_FAIL_OPEN (default: true): on API failure with no valid cache,
  run all tests instead of crashing; set to false to rethrow as before.
- SKIPPER_CACHE_TTL (default: 300s): write .skipper-cache.json after every
  successful fetch and use it as a fallback within the TTL on API failure.
- SKIPPER_SYNC_ALLOW_DELETE (default: false): in sync mode, orphaned rows are
  now only logged by default; set to true to allow deletion (previous behaviour).

Closes #1

Author: EmanueleMinotto

CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.1.0] - 2026-03-28
+
+### Added
+- `SKIPPER_FAIL_OPEN` env var: when the API is unreachable and no valid cache exists, run all tests instead of crashing (default: `true`). Set to `false` to restore the previous behaviour of rethrowing the exception.
+- `SKIPPER_CACHE_TTL` env var: after every successful fetch, skipper writes a local `.skipper-cache.json` file. On subsequent API failures the cache is used as a fallback if its age is within this TTL (default: `300` seconds).
+- `SKIPPER_SYNC_ALLOW_DELETE` env var: in sync mode, orphaned rows are now only logged by default. Set to `true` to allow skipper to delete them from the spreadsheet (previous behaviour).
+
+## [1.0.0] - 2026-03-26
+
+### Added
+- Initial release with support for PHPUnit (10/11/12), Pest (v2/v3), Behat (3.x), Codeception (5.x), PHPSpec (7/8), and Kahlan (5.x/6.x).
+- Google Sheets-based test-gating via `disabledUntil` dates.
+- Sync mode (`SKIPPER_MODE=sync`) to reconcile the spreadsheet with the discovered test suite.
+- Reference sheets support for merging test entries from multiple sheets.
+- Parallel test execution support via cross-process resolver cache (`SKIPPER_CACHE_FILE`, `SKIPPER_DISCOVERED_DIR`).
+- Three credential formats: file path, base64 string, environment variable.
+
+[Unreleased]: https://github.com/get-skipper/skipper-php/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/get-skipper/skipper-php/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/get-skipper/skipper-php/releases/tag/v1.0.0

CONTRIBUTING.md

@@ -91,6 +91,36 @@ chore: update google/apiclient to ^2.16
 
 ---
 
+## Changelog
+
+This project uses [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format in `CHANGELOG.md`.
+
+Every pull request that changes user-facing behaviour **must** include a `CHANGELOG.md` entry under `[Unreleased]`.
+
+### Categories
+
+| Category | When to use |
+|----------|-------------|
+| `Added` | New features or env vars |
+| `Changed` | Changes to existing behaviour |
+| `Deprecated` | Features that will be removed in a future release |
+| `Removed` | Features removed in this release |
+| `Fixed` | Bug fixes |
+| `Security` | Security-related fixes |
+
+### Example entry
+
+```markdown
+## [Unreleased]
+
+### Added
+- `SKIPPER_FAIL_OPEN` env var: run all tests instead of crashing when the API is unreachable and no cache exists (default: `true`).
+```
+
+Releases are cut by a maintainer: the `[Unreleased]` section is renamed to the new version with its release date, and a new empty `[Unreleased]` section is added at the top.
+
+---
+
 ## Pull requests
 
 1. Fork the repository and create a branch:

README.md

@@ -365,7 +365,10 @@ referenceSheets: ['SharedDisabled', 'QA']
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `SKIPPER_MODE` | `read-only` | Set to `sync` to enable spreadsheet reconciliation |
-| `SKIPPER_CACHE_FILE` | _(auto)_ | Path to the resolver cache file (set by the main process) |
+| `SKIPPER_FAIL_OPEN` | `true` | On API failure with no valid cache, run all tests instead of crashing. Set to `false` to rethrow the exception |
+| `SKIPPER_CACHE_TTL` | `300` | Seconds the on-disk fallback cache (`.skipper-cache.json`) remains valid after a successful fetch |
+| `SKIPPER_SYNC_ALLOW_DELETE` | `false` | In sync mode, delete orphaned rows from the spreadsheet. When `false`, orphaned rows are only logged |
+| `SKIPPER_CACHE_FILE` | _(auto)_ | Path to the resolver cache file (set by the main process for parallel workers) |
 | `SKIPPER_DISCOVERED_DIR` | _(auto)_ | Directory for collecting discovered test IDs across workers |
 | `SKIPPER_DEBUG` | _(unset)_ | Set to any non-empty value to enable verbose logging |
 

src/Core/Resolver/SkipperResolver.php

@@ -39,18 +39,80 @@ public function __construct(
     /**
      * Fetches the spreadsheet and populates the in-memory cache.
      * Must be called once before isTestEnabled().
+     *
+     * On API failure:
+     * - Uses the on-disk fallback cache if within SKIPPER_CACHE_TTL seconds (default: 300).
+     * - If no valid cache exists and SKIPPER_FAIL_OPEN is not "false", runs all tests
+     *   instead of crashing (fail-open is the default).
+     * - If SKIPPER_FAIL_OPEN=false, the exception is rethrown.
      */
     public function initialize(): void
     {
-        $result = $this->client->fetchAll();
-        $this->cache = [];
+        $cacheFile = '.skipper-cache.json';
+        $ttl = (int)(getenv('SKIPPER_CACHE_TTL') ?: 300);
+        $failOpen = getenv('SKIPPER_FAIL_OPEN') !== 'false';
+
+        try {
+            $result = $this->client->fetchAll();
+            $this->cache = [];
+
+            foreach ($result->entries as $entry) {
+                $key = TestIdHelper::normalize($entry->testId);
+                $this->cache[$key] = $entry->disabledUntil?->format(\DateTimeInterface::ATOM);
+            }
+
+            file_put_contents($cacheFile, json_encode(['ts' => time(), 'rows' => $this->cache], \JSON_THROW_ON_ERROR));
+            $this->initialized = true;
+        } catch (\Exception $e) {
+            $cached = $this->tryReadCache($cacheFile, $ttl);
+            if ($cached !== null) {
+                error_log('[skipper] API failed, using cache (' . $cached['ageSeconds'] . 's old): ' . $e->getMessage());
+                $this->cache = $cached['rows'];
+                $this->initialized = true;
+                return;
+            }
+            if ($failOpen) {
+                error_log('[skipper] API failed, no cache — running all tests (fail-open): ' . $e->getMessage());
+                $this->cache = [];
+                $this->initialized = true;
+                return;
+            }
+            throw $e;
+        }
+    }
+
+    /**
+     * Reads the on-disk fallback cache and returns rows + age if within TTL.
+     *
+     * @return array{rows: array<string, string|null>, ageSeconds: int}|null
+     */
+    private function tryReadCache(string $cacheFile, int $ttl): ?array
+    {
+        if (!file_exists($cacheFile)) {
+            return null;
+        }
+
+        $raw = file_get_contents($cacheFile);
+        if ($raw === false) {
+            return null;
+        }
+
+        try {
+            $data = json_decode($raw, true, 512, \JSON_THROW_ON_ERROR);
+        } catch (\JsonException) {
+            return null;
+        }
+
+        if (!isset($data['ts'], $data['rows']) || !is_int($data['ts']) || !is_array($data['rows'])) {
+            return null;
+        }
 
-        foreach ($result->entries as $entry) {
-            $key = TestIdHelper::normalize($entry->testId);
-            $this->cache[$key] = $entry->disabledUntil?->format(\DateTimeInterface::ATOM);
+        $ageSeconds = time() - $data['ts'];
+        if ($ageSeconds > $ttl) {
+            return null;
         }
 
-        $this->initialized = true;
+        return ['rows' => $data['rows'], 'ageSeconds' => $ageSeconds];
     }
 
     /**

src/Core/Writer/SheetsWriter.php

@@ -66,6 +66,13 @@ public function sync(array $discoveredIds): void
             fn ($nid) => !isset($normalizedDiscovered[$nid])
         );
 
+        $allowDeletes = getenv('SKIPPER_SYNC_ALLOW_DELETE') === 'true';
+
+        if (!$allowDeletes && !empty($toRemoveNormalized)) {
+            Logger::log('[skipper] ' . count($toRemoveNormalized) . ' orphaned row(s) found. Set SKIPPER_SYNC_ALLOW_DELETE=true to prune them.');
+            $toRemoveNormalized = [];
+        }
+
         if (empty($toAdd) && empty($toRemoveNormalized)) {
             Logger::log('[skipper] Spreadsheet is already up to date.');
             return;