# Runbook

> 操作手册：安装、日常命令、常见错误处理、配置管理。

## 安装

```bash
# <安装方式占位：通过包管理器 / 二进制 / 源码>
# 例如：
#   <package-manager> install <project-name>
#   curl -L <release-url> | tar xz

# 验证
<project-cli> --version
```

## 项目初始化

```bash
cd <your-project>
koala-core init
```

`koala-core init` 会：

1. 创建 `koala.toml` 配置（默认 profile=balanced）
2. 创建 `wiki/` 骨架目录（runbook / testing / tech-debt / health 模板）
3. 创建 `.koala/architecture.toml`（架构边界规则模板）
4. 创建 `.koala/invariants/default.toml`（首批 invariant 规则）
5. 写入 `.gitignore`：`.koala/cache/`

## 日常命令

### `koala-core check`

跑全套 CI gate（本地复现 CI 行为）：

```bash
koala-core check                  # 全部
koala-core check --invariant-only # 仅跑 invariant suite
koala-core check --drift-only     # 仅跑 drift detector
koala-core check --pr <branch>    # 模拟 CI 跑指定分支
```

### `koala-core drift`

```bash
koala-core drift                  # 检测当前 wiki ↔ code 一致性
koala-core drift --explain        # 输出违反原因 + 修复建议
koala-core drift --fix-trivial    # 自动修复格式问题（不改语义）
```

### `koala-core adr`

```bash
koala-core adr new <title>         # 创建新 ADR（自动分配编号）
koala-core adr list [--status accepted|superseded|deprecated]
koala-core adr supersede 0042 0099 # 标记 ADR-0042 被 0099 替代
koala-core adr validate            # 校验所有 ADR 链接 + 状态
```

### `koala-core health`

```bash
koala-core health                 # 看当前指标快照
koala-core health update          # 重算指标并写 health.md（CI 用）
koala-core health trend           # 趋势图（最近 30 天）
```

### `koala-core wiki`

```bash
koala-core wiki gen               # 重生成所有 Tier 1 文件（_index, health, etc）
koala-core wiki tags              # 重建 _tags/ 索引
```

## 常见错误处理

### `drift detected: features/<name>.md claims X implemented but no related code`

**原因**：`wiki/features/<name>.md` 里有 `[x] ...` 但代码层 grep 不到对应关键字。

**处理**：

1. 如果功能确实没做：把 `[x]` 改回 `[ ]`，或把整段 acceptance criteria 删掉
2. 如果功能已改名：更新 wiki 文件描述使用新词
3. 如果被误判（关键词在不可见路径）：在 `koala.toml` 加 grep 例外路径

### `artifact verification mismatch on .review/...`

**原因**：CI 抽样重跑的 reviewer 命令输出与 artifact 记录不一致。

**处理**：看 CI log 的 diff，判断是否真的篡改。误判（含时间戳等不稳定字段）→ 在 `.koala/artifact-normalize.toml` 加 regex 替换规则。

### `cannot supersede ADR-NNNN: already superseded by ADR-MMMM`

**原因**：试图重复标记 supersede。

**处理**：跟随 supersede 链。如要再次推翻，写新 ADR 并 `koala-core adr supersede <last> <new>`。

## 配置管理

项目根的 `koala.toml` 是主配置。详见 [templates/koala.toml](../koala.toml)（init 时复制到项目根）。

`.koala/architecture.toml` 与 `.koala/invariants/*.toml` 由 `koala-core init` 写入默认值，按项目需求微调。

## CI 集成

GitHub Actions 模板：[templates/.github/workflows/koala.yml](../.github/workflows/koala.yml)。

`koala-core init` 不会自动写入 `.github/`——按需手动复制。

## 故障排除

```bash
koala-core doctor                 # 输出环境信息（toolchain / config / git status）
<project-cli> --verbose <command> # 详细日志
```

提交 issue 时附 `koala-core doctor` 输出。

## 升级

```bash
# <按你的安装方式升级 koala-core>
koala-core migrate                # 升级配置文件格式（major version 时需要）
```

升级 major version 务必先读 `wiki/decisions/` 下当版的 superseded ADR，了解断层变化。

---

> 此文件由 koala-core init 创建。Tier 2（LLM 起草 + 人审）。
