# Runtime Runbook Optimization Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** 将 `docs/runtime/runtime-runbook.md` 重构为面向运维的可执行手册，覆盖门禁、启动、验证、故障与回滚全流程。

**Architecture:** 保持单文档模式，在不改变脚本和运行时代码的前提下重排章节与命令。先做命令基线校对，再做文档结构重构，最后执行可达性验证并提交。所有命令以仓库现有脚本和 compose 路径为准。

**Tech Stack:** Markdown, Bash, Docker Compose, tmux, uv。

---

### Task 1: 命令与脚本基线核对

**Files:**
- Modify: `docs/runtime/runtime-runbook.md`
- Verify: `infra/scripts/app-up.sh`

**Step 1: 写失败校验（当前 runbook 存在 TODO 与历史表述）**

```bash
grep -n "TODO\|dev-app-up" docs/runtime/runtime-runbook.md
```

**Step 2: 运行并确认失败**

Run: `grep -n "TODO\|dev-app-up" docs/runtime/runtime-runbook.md`  
Expected: 命中至少 1 条（表示需重构）。

**Step 3: 写最小实现（命令映射清单）**

```markdown
- 启动脚本统一为 infra/scripts/app-up.sh
- bootstrap 命令统一为 docker compose --env-file .env -f infra/docker/docker-compose.yml ...
- 迁移/初始化强调 init-job --build
```

**Step 4: 运行验证**

Run: `bash -n infra/scripts/app-up.sh`  
Expected: exit 0。

### Task 2: 文档结构重构为运维分层

**Files:**
- Modify: `docs/runtime/runtime-runbook.md`

**Step 1: 写失败校验（缺失目标章节）**

```bash
grep -n "Bootstrap Gate\|Operational Verification\|Incident Playbook\|Rollback" docs/runtime/runtime-runbook.md
```

**Step 2: 运行并确认失败**

Run: `grep -n "Bootstrap Gate\|Operational Verification\|Incident Playbook\|Rollback" docs/runtime/runtime-runbook.md`  
Expected: 命中不完整或为空。

**Step 3: 写最小实现（章节重排）**

```markdown
1. Scope & Preconditions
2. Bootstrap Gate (Mandatory)
3. Service Start/Stop
4. Operational Verification (L1/L2/L3)
5. Incident Playbook
6. Rollback Procedure
```

**Step 4: 运行验证**

Run: `grep -n "Bootstrap Gate\|Operational Verification\|Incident Playbook\|Rollback Procedure" docs/runtime/runtime-runbook.md`  
Expected: 4 个目标章节都能命中。

### Task 3: 补齐运维验证与故障处理细则

**Files:**
- Modify: `docs/runtime/runtime-runbook.md`

**Step 1: 写失败校验（缺少通过判定）**

```bash
grep -n "通过标准\|判定" docs/runtime/runtime-runbook.md
```

**Step 2: 运行并确认失败**

Run: `grep -n "通过标准\|判定" docs/runtime/runtime-runbook.md`  
Expected: 命中不足。

**Step 3: 写最小实现（每段加判定）**

```markdown
- L1 必跑：health/compose/smoke + 通过标准
- L2 可选：auth/profile + 通过标准
- L3 可选：agent_chat tests + 通过标准
- 故障条目：症状/定位/修复
```

**Step 4: 运行验证**

Run: `grep -n "L1 必跑\|L2 可选\|L3 可选\|通过标准" docs/runtime/runtime-runbook.md`  
Expected: 关键段落均命中。

### Task 4: 收尾校验与提交

**Files:**
- Modify: `docs/runtime/runtime-runbook.md`

**Step 1: 运行文档语义检查（关键命令可达）**

```bash
bash -n infra/scripts/app-up.sh
PYTHONPATH=backend/src uv run python -c "import core.runtime.cli"
```

**Step 2: 运行并确认通过**

Run: `bash -n infra/scripts/app-up.sh`  
Expected: exit 0。

Run: `PYTHONPATH=backend/src uv run python -c "import core.runtime.cli"`  
Expected: 无报错并 exit 0。

**Step 3: 提交**

```bash
git add docs/runtime/runtime-runbook.md \
  docs/plans/2026-02-25-runtime-runbook-optimization-design.md \
  docs/plans/2026-02-25-runtime-runbook-optimization-implementation-plan.md
git commit -m "docs(runtime): optimize runbook for ops workflow"
```