From 1b448fef2325d171c96ae64c9f01bbcf958ee94b Mon Sep 17 00:00:00 2001
From: timmy <timmy@stackchain.ai>
Date: Sun, 23 Aug 2026 01:10:16 +0000
Subject: [PATCH] docs: add disk capacity incident runbook (Closes #1287)

---
 docs/ops-fundamentals.md       | 17 +++++++++++++++++
 tests/test_ops_fundamentals.py | 16 ++++++++++++++++
 2 files changed, 33 insertions(+)
 create mode 100644 tests/test_ops_fundamentals.py

diff --git a/docs/ops-fundamentals.md b/docs/ops-fundamentals.md
index a499a79..444be8a 100644
--- a/docs/ops-fundamentals.md
+++ b/docs/ops-fundamentals.md
@@ -23,3 +23,20 @@
 - API contracts + versioning
 - independent deployability
 - observability: metrics, traces, structured logs
+
+# Disk capacity incident
+
+Root filesystem usage at or above 85% is an operations incident.
+
+1. Capture the initial state with `df -h / /var/lib/gitea`.
+2. Inspect directory sizes and active processes before cleanup. Reclaim only
+   disposable caches and abandoned temporary environments. Responders must not
+   delete Gitea data, repositories, databases, secrets, or active release
+   artifacts.
+3. Re-run `df -h / /var/lib/gitea`; usage must be below 85%.
+4. Confirm the release path with `systemctl is-active gitea act_runner`, then run
+   the repository test suite.
+
+Record the before and after usage in the incident ticket. If safe cleanup cannot
+restore capacity below 85%, keep the incident open and escalate storage
+expansion rather than removing durable data.
diff --git a/tests/test_ops_fundamentals.py b/tests/test_ops_fundamentals.py
new file mode 100644
index 0000000..ee2088b
--- /dev/null
+++ b/tests/test_ops_fundamentals.py
@@ -0,0 +1,16 @@
+from pathlib import Path
+
+
+RUNBOOK = Path(__file__).parents[1] / "docs" / "ops-fundamentals.md"
+
+
+def test_disk_capacity_runbook_requires_safe_remediation_and_release_verification():
+    text = " ".join(RUNBOOK.read_text().split())
+
+    assert "Disk capacity incident" in text
+    assert "85%" in text
+    assert "df -h / /var/lib/gitea" in text
+    assert "disposable caches and abandoned temporary environments" in text
+    assert "must not delete Gitea data" in text
+    assert "systemctl is-active gitea act_runner" in text
+    assert "repository test suite" in text