Add protocol incident response runbook

.github/workflows/ci.yml

@@ -79,6 +79,8 @@ jobs:
             scripts/test_architecture_threat_model.py \
             scripts/check_audit_package.py \
             scripts/test_audit_package.py \
+            scripts/check_incident_response.py \
+            scripts/test_incident_response.py \
             scripts/check_release_readiness.py \
             scripts/test_release_readiness.py \
             scripts/generate_release_manifest.py \
@@ -263,6 +265,14 @@ jobs:
           python3 scripts/test_audit_package.py 2>&1 | tee ci-logs/audit-package-tests.log
           python3 scripts/check_audit_package.py 2>&1 | tee ci-logs/audit-package-check.log
 
+      - name: Incident response
+        shell: bash
+        run: |
+          set -o pipefail
+          mkdir -p ci-logs
+          python3 scripts/test_incident_response.py 2>&1 | tee ci-logs/incident-response-tests.log
+          python3 scripts/check_incident_response.py 2>&1 | tee ci-logs/incident-response-check.log
+
       - name: Release readiness
         shell: bash
         run: |

CHANGELOG.md

@@ -108,6 +108,10 @@ the release policy in `docs/release-policy.md`.
   retained placeholder artifact, checker, and local/CI gate so future reviewed
   non-local evidence can be machine-validated before release manifest and
   checksum generation.
+- Added a protocol incident-response runbook and local/CI checker covering
+  stuck auctions, failed or stale randomness, bad Merkle roots, bad metadata or
+  dependency configuration, signer compromise, and release artifact/evidence
+  mistakes before release manifest and checksum generation.
 - Added a production dependency operations runbook covering dependency version
   proposal, review, source packaging, registry registration, unfrozen
   collection repinning, deprecation, rollback by corrective version, frozen

Makefile

@@ -22,9 +22,9 @@ RM_RF := rm -rf out cache broadcast
 endif
 PATH := $(FOUNDRY_BIN)$(PATH_SEPARATOR)$(REPO_ROOT)/$(VENV_BIN)$(PATH_SEPARATOR)$(PATH)
 
-.PHONY: check build test gas-snapshot gas-snapshot-check size deploy-rehearsal metadata-fixtures-check release-artifacts release-artifacts-check source-verification-inputs source-verification-inputs-check abi-compatibility abi-compatibility-check broadcast-manifest-inputs broadcast-manifest-inputs-check deployment-manifests deployment-manifest-check address-books address-books-check dependency-artifacts dependency-artifacts-check ceremony-evidence-check randomizer-operations-check release-signatures-check non-local-release-evidence-check public-beta-evidence-check architecture-threat-model-check audit-package-check release-readiness-check release-manifest release-manifest-check release-checksums release-checksums-check changelog-check fmt-check slither clean
+.PHONY: check build test gas-snapshot gas-snapshot-check size deploy-rehearsal metadata-fixtures-check release-artifacts release-artifacts-check source-verification-inputs source-verification-inputs-check abi-compatibility abi-compatibility-check broadcast-manifest-inputs broadcast-manifest-inputs-check deployment-manifests deployment-manifest-check address-books address-books-check dependency-artifacts dependency-artifacts-check ceremony-evidence-check randomizer-operations-check release-signatures-check non-local-release-evidence-check public-beta-evidence-check architecture-threat-model-check audit-package-check incident-response-check release-readiness-check release-manifest release-manifest-check release-checksums release-checksums-check changelog-check fmt-check slither clean
 
-check: build test gas-snapshot-check size metadata-fixtures-check release-artifacts-check source-verification-inputs-check abi-compatibility-check non-local-release-evidence-check public-beta-evidence-check architecture-threat-model-check audit-package-check release-readiness-check release-checksums-check changelog-check deploy-rehearsal
+check: build test gas-snapshot-check size metadata-fixtures-check release-artifacts-check source-verification-inputs-check abi-compatibility-check non-local-release-evidence-check public-beta-evidence-check architecture-threat-model-check audit-package-check incident-response-check release-readiness-check release-checksums-check changelog-check deploy-rehearsal
 
 build:
 	forge build
@@ -133,14 +133,18 @@ audit-package-check:
 	$(PYTHON) scripts/test_audit_package.py
 	$(PYTHON) scripts/check_audit_package.py
 
+incident-response-check:
+	$(PYTHON) scripts/test_incident_response.py
+	$(PYTHON) scripts/check_incident_response.py
+
 release-readiness-check:
 	$(PYTHON) scripts/test_release_readiness.py
 	$(PYTHON) scripts/check_release_readiness.py
 
-release-manifest: address-books source-verification-inputs dependency-artifacts ceremony-evidence-check randomizer-operations-check release-signatures-check non-local-release-evidence-check public-beta-evidence-check architecture-threat-model-check audit-package-check release-readiness-check
+release-manifest: address-books source-verification-inputs dependency-artifacts ceremony-evidence-check randomizer-operations-check release-signatures-check non-local-release-evidence-check public-beta-evidence-check architecture-threat-model-check audit-package-check incident-response-check release-readiness-check
 	$(PYTHON) scripts/generate_release_manifest.py
 
-release-manifest-check: address-books-check source-verification-inputs-check dependency-artifacts-check ceremony-evidence-check randomizer-operations-check release-signatures-check non-local-release-evidence-check public-beta-evidence-check architecture-threat-model-check audit-package-check release-readiness-check
+release-manifest-check: address-books-check source-verification-inputs-check dependency-artifacts-check ceremony-evidence-check randomizer-operations-check release-signatures-check non-local-release-evidence-check public-beta-evidence-check architecture-threat-model-check audit-package-check incident-response-check release-readiness-check
 	$(PYTHON) scripts/test_release_manifest.py
 	$(PYTHON) scripts/generate_release_manifest.py --check
 

SECURITY.md

@@ -5,6 +5,10 @@ protocol draft with known P0 blockers tracked in [ops/ROADMAP.md](ops/ROADMAP.md
 Do not use these contracts for production drops, custody of valuable assets, or
 public security claims until the launch gates are complete.
 
+Operational incidents that do not contain public exploit details should follow
+the no-secret procedure in [docs/incident-response.md](docs/incident-response.md)
+after private vulnerability triage starts.
+
 ## Reporting Vulnerabilities
 
 Please do not open public GitHub issues for exploitable vulnerabilities.
@@ -89,5 +93,7 @@ The current roadmap calls out these high-risk areas:
 - Randomizer request and callback validation.
 - Static-analysis high/medium findings.
 - Deployment rehearsal, verification, and release artifacts.
+- Incident response, emergency pause, signer revocation, retry/recovery,
+  withdrawal availability, and evidence retention.
 
 Security reports should reference the relevant roadmap issue ID when possible.

docs/audit-package.md

@@ -45,6 +45,7 @@ Explicitly out of scope for this package:
 | Current maturity and evidence | [`docs/status.md`](status.md) |
 | Known unresolved blockers | [`docs/known-blockers.md`](known-blockers.md) |
 | Release-readiness dashboard | [`docs/release-readiness.md`](release-readiness.md) |
+| Incident response runbook | [`docs/incident-response.md`](incident-response.md) |
 | Public-beta evidence status | [`docs/public-beta-evidence.md`](public-beta-evidence.md) |
 | Gated execution roadmap | [`ops/ROADMAP.md`](../ops/ROADMAP.md) |
 | Autonomous execution state | [`ops/AUTONOMOUS_RUN.md`](../ops/AUTONOMOUS_RUN.md) |
@@ -77,6 +78,7 @@ Protocol-specific docs that are useful during review:
 - [`docs/randomizer-operations.md`](randomizer-operations.md)
 - [`docs/deployment.md`](deployment.md)
 - [`docs/release-policy.md`](release-policy.md)
+- [`docs/incident-response.md`](incident-response.md)
 - [`docs/release-signatures.md`](release-signatures.md)
 - [`docs/public-beta-evidence.md`](public-beta-evidence.md)
 - [`docs/release-readiness.md`](release-readiness.md)
@@ -140,11 +142,13 @@ Local deployment and release evidence:
   defines the retained status format.
 
 The release manifest includes this audit package as a governance document. The
-release manifest also includes the architecture map and threat model as
-governance documents, and it summarizes the public-beta evidence status. The
+release manifest also includes the architecture map, threat model, and incident
+response runbook as governance documents, and it summarizes the public-beta
+evidence status. The
 checksum bundle covers the release manifest, so changes to the audit package,
-architecture map, threat model, or public-beta evidence status must refresh
-release evidence before a release-oriented PR can pass.
+architecture map, threat model, incident-response runbook, or public-beta
+evidence status must refresh release evidence before a release-oriented PR can
+pass.
 
 ## Known Blockers And Accepted Risks
 
@@ -193,6 +197,8 @@ python scripts/test_audit_package.py
 python scripts/check_audit_package.py
 python scripts/test_architecture_threat_model.py
 python scripts/check_architecture_threat_model.py
+python scripts/test_incident_response.py
+python scripts/check_incident_response.py
 python scripts/test_release_readiness.py
 python scripts/check_release_readiness.py
 python scripts/test_public_beta_evidence.py

docs/dependency-operations.md

@@ -29,6 +29,10 @@ This runbook applies when an operator or maintainer:
 It does not authorize mutation of frozen collection output. Frozen collections
 must remain tied to their pinned dependency key, version, content hash, registry
 address, freeze manifest, and event history.
+If a dependency release, repin, deprecation, source-retention artifact, or
+metadata output is wrong, follow
+[`docs/incident-response.md`](incident-response.md) before changing public
+readiness status.
 
 ## Source Of Truth
 
@@ -254,8 +258,8 @@ Allowed operations for frozen collections:
   if a security incident requires a new path
 
 If a frozen collection depends on a version later found to be unsafe, the
-incident response must document the risk, the immutable proof, and any new
-deployment or collection path. It must not imply that the frozen output was
+incident response runbook must document the risk, the immutable proof, and any
+new deployment or collection path. It must not imply that the frozen output was
 mutated.
 
 ## Deprecation