docs(runbooks): add runbook spec, template, index and 6 first-batch runbooks; light-enhance existing 10

- RUNBOOKS.md: repo-level spec (six-field model, naming, safety, maturity path) - runbooks/_template.md + README.md: standard template and 16-entry routing index - new: issue-to-merge, fix-ci, release, rollback, network-change, network-recovery - light-enhance 10 existing runbooks with Purpose/Scope/Safety headers - AGENTS.md: point step 3 at index/spec, add runbook execution rules - docs/agent-runbook-guide.md: archive of Manus AI guide
2026-08-17 15:59:46 +08:00
parent 047ac03346
commit b0c01b2551
21 changed files with 1140 additions and 2 deletions
@@ -0,0 +1,89 @@
+# Runbook: issue → mergeable change
+
+## Purpose
+
+Turn an approved Linear `vps` issue into a reviewed, mergeable change in this
+repo (docs, runbooks, hosts facts, or Ansible playbooks).
+
+## Scope
+
+- Applicable: repo content under `docs/`, `runbooks/`, `hosts/`, `inventory/`, `ansible/`.
+- Not applicable: mutating production state directly — that goes through `release.md` / `ansible-operations.md`.
+
+## Ownership
+
+- Owner: personal ops (Windy)
+- Last reviewed: 2026-08-17
+- Related systems: Linear MCP (`vps` project), git
+
+## Inputs
+
+| Input | Source | Required | Validation |
+|---|---|---:|---|
+| Issue identifier | Linear (`vps` project) | Yes | `linear_get_issue <id>` returns a description |
+| Current repo state | `git status` / `git log` | Yes | Clean or intended worktree |
+
+## Safety
+
+- Scope is locked to the issue: do not bundle unrelated changes.
+- Never commit secrets (see `AGENTS.md` §Safety).
+- Verify every change; do not merge a change whose verification was skipped.
+
+## Procedure
+
+### Step 1 — Read the issue
+
+**Action** — `linear_get_issue <id>`, read description and acceptance criteria.
+
+**Expected** — clear scope, action, and verification for the change.
+
+**Decision** — if the issue is ambiguous or lacks verification criteria, `STOP`
+and ask for clarification (add a `needs-info` label if applicable). Otherwise go to Step 2.
+
+### Step 2 — Inspect and change
+
+**Action** — read the relevant files, then make the minimal change the issue asks for.
+
+**Expected** — diff is scoped to the issue.
+
+**Decision** — if the change needs production mutation, `STOP` and route to
+`release.md`. Otherwise go to Step 3.
+
+### Step 3 — Verify
+
+**Action** — run the applicable verification (link check for docs; `ansible-playbook --check` / `--syntax-check` for playbooks).
+
+**Verification** — see `RUNBOOKS.md` §校验; the concrete checks must match the change type.
+
+**Decision** — verification passed → Step 4; failed → Troubleshooting A.
+
+### Step 4 — Commit and link
+
+**Action** — commit with a message containing the full issue ID (e.g. `W1N-123: …`); open a PR if the change is substantial; link the issue via `linear_save_comment`.
+
+**Verification** — `git log -1` shows the issue ID; the issue has the commit/PR pointer.
+
+**Rollback** — `git revert <sha>` or `git checkout <branch>` to drop the change; re-verify after.
+
+## Troubleshooting
+
+### Troubleshooting A — Verification failed
+
+- Evidence: command output, failing check.
+- Allowed: fix the change within scope; re-run verification.
+- Next: still failing → `STOP` and report in the issue.
+
+## Final Verification
+
+- Change matches the issue scope.
+- Verification passed and the issue is updated with evidence.
+
+## Failure Handling
+
+If unfinished: stop, collect the failed check output, record completed steps, and
+hand back to the issue — do not guess.
+
+## References
+
+- [`docs/agents/issue-tracker.md`](../docs/agents/issue-tracker.md)
+- [`RUNBOOKS.md`](../RUNBOOKS.md)