Contributing Warden runbooks

Source of truth: docs/contributing/runbooks.md (synced at build time — edit the original, not this copy). Runbooks are Apache-2.0 YAML content under warden/runbooks/. They must use actions registered by Warden and must preserve the approval boundary for risky work.

Before you start

1. Search the existing runbooks and issues for the same response flow.
2. Read warden/docs/runbook-authoring.md and the action registry in warden/docs/actions.md.
3. Do not put credentials, tokens, or fixed customer data in a runbook. Refer to a configured connection.

Author the runbook

Start from the nearest shipped runbook. Keep inputs explicit and keep evidence-producing read steps separate from response steps. Any action whose response contract is not read-only must remain behind an approval step. Reversible response must include its reversal or expiry path.

Every file needs this header:

# SPDX-License-Identifier: Apache-2.0

Use stable action names from the registry. A runbook must not depend on an action that is absent from the current tree.

Validate

From a Warden checkout:

python3 scripts/validate_content.py
python3 -m unittest scripts.test_validate_content -v

The pull-request workflow runs the same validator on the existing shared self-hosted X64 pool. It parses every runbook through Warden’s runtime schema, checks action references, and validates integration-pack content.

Pull request evidence

Describe the trigger, expected evidence, approval points, and rollback or expiry behavior. Include the exact validator command and result. Fixture-only integrations must say verified: fixture; do not claim live verification.