docs: rewrite CLAUDE.md for TRM5 production-grade project

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,443 @@
+# CLAUDE.md
+
+> [!URGENT]
+> **科研工程混合 + 生产级项目（非 MVP）**
+> 1. 本项目是科研工程混合体（当下工程为主，后续 Agent 进化科研为主），要求**生产级**的稳定性、并发性、防御性、可观测与测试。YAGNI 仍然适用，但**绝不以牺牲健壮性、并发、防御、可观测、测试为代价**换取"简单"。
+> 2. 你的所有思考过程和回复必须使用 **简体中文**。
+
+## 1. 项目元数据 (Metadata)
+- **核心目标**: 在层次化视频树上构建可自我进化的搜索 Agent + 可训练的递归检索器（RecursiveRetriever），通过 Harness Engineering（工具、技能、记忆、中间件）的持续改进实现长视频理解；服务于科研产出。详见 `research-wiki/ARCHITECTURE.md`、`README.md`。
+- **项目类型**: 科研工程混合体 + 生产级（非 MVP）
+- **目标会议**: EMNLP 2026
+- **后端架构**: Python 3.11（Clean Architecture 四层分层，详见 `research-wiki/ARCHITECTURE.md §2`）
+- **版本管理**: Git
+- **Conda 环境**: `Video-Tree-TRM` (Python 3.11)
+
+## 1.5 系统设计类比 (Design Analogy)
+
+本系统的自进化循环对标 PyTorch 训练循环：
+
+| PyTorch 概念 | 本项目对应 | 代码位置 |
+|-------------|-----------|----------|
+| `DataLoader` | 出题 question_gen | `app/question_gen/generator.py` |
+| `model.forward()` | 推理 inference | `app/harness/inference.py` + `core/agent/loop.py` |
+| `loss.backward()` | 诊断 diagnose | `core/evolution/diagnose.py` |
+| `optimizer.step()` | 进化 evolve | `core/evolution/evolve.py` |
+| `nn.Parameter` | Skills + Prompts（版本化） | `store/skills/`, `store/prompts/` |
+| `training loop` | 外层循环 runner | `app/harness/runner.py` |
+| `checkpoint` | Store 版本快照 | `app/harness/workspace.py` |
+| `grad clipping` | 进化 validation | `core/evolution/validate.py` |
+
+### 关键推论
+
+- **只有 inference 是 agent-controlled**（LLM 自主决定工具调用），其余三步均为 code-controlled workflow。
+- 四步之间通过**函数调用 + 明确返回类型**组合，无需调度框架。
+- Store 中版本化资源 = 可回滚的"模型权重"，Workspace = 一次"训练实验"。
+
+## 2. 常用命令 (Commands)
+
+### 2.1 Conda 环境管理
+
+> [!CRITICAL]
+> **所有 Python 相关命令（pytest / ruff / 脚本）必须在 `Video-Tree-TRM` 环境中执行**
+> - 使用 `conda run -n Video-Tree-TRM <command>` 确保命令在正确环境中运行
+> - 或在命令前显式添加 `source activate Video-Tree-TRM &&`
+> - 如果需要使用 LLM 可以依据 `.env` 环境变量文件使用
+
+```bash
+# 激活项目环境（交互式 shell）
+conda activate Video-Tree-TRM
+
+# 推荐：使用 conda run 执行命令（自动使用正确环境）
+conda run -n Video-Tree-TRM pip install xxx
+conda run -n Video-Tree-TRM pytest xxx
+conda run -n Video-Tree-TRM python xxx
+```
+
+### 2.2 Makefile 入口
+
+常用工程动作统一收口到 `Makefile`。
+
+```bash
+make test            # conda 环境内跑 pytest + 覆盖率
+make lint            # ruff check --fix + ruff format（app/ core/）
+```
+
+### 2.3 代码质量检查
+```bash
+# 代码格式化
+conda run -n Video-Tree-TRM ruff format app/ core/ adapters/
+
+# 代码检查并自动修复
+conda run -n Video-Tree-TRM ruff check app/ core/ adapters/ --fix
+```
+
+### 2.4 GPU 约定
+
+> [!CRITICAL]
+> - **本地 (RTX 4070 Ti SUPER)**：默认 `CUDA_VISIBLE_DEVICES=0`
+> - 所有涉及 GPU 的命令都要显式 `CUDA_VISIBLE_DEVICES=<idx>` 前缀，避免占用他人卡
+> - **严禁**省略 `CUDA_VISIBLE_DEVICES` 导致 PyTorch 自动选卡
+
+### 2.5 实验入口（sh 文件）
+
+每个 sh 文件是自包含的实验记录，写死全部参数，零参数即可复现（GPU 卡号除外）。
+
+```bash
+# 典型调用
+CUDA_VISIBLE_DEVICES=0 bash scripts/<experiment>.sh
+MODE=mock N_SAMPLES=10 bash scripts/<experiment>.sh   # smoke test
+```
+
+## 3. 标准作业程序 (Standard Operating Procedure)
+> **Agent 必须严格遵守以下生命周期执行任务（全量强制，不分级、不因任务"简单"而省略）：**
+
+### Phase 1: 规划与设计 (Planning)
+1. **需求探索**: 涉及创建新功能、新组件、修改行为时，**必须**先调用 `brainstorming` skill 进行需求探索与设计。无论用户的指令多么具体、改动多么简单，都不得跳过此步骤（除非用户显式说"跳过 brainstorming"）。
+2. **查阅规格 & 讨论**: 仔细阅读 `research-wiki/`（单一事实源）下对应的文档，了解项目最新情况。对于不理解的地方请与人类进行多轮讨论，确保理解人类的设计意图。
+3. **日志方案设计**: 功能会产生运行时数据时，**必须**调用 `structured-logging` skill 设计日志方案。
+4. **撰写计划**: 正式编码前，**必须**调用 `writing-plans` skill 撰写实现计划。
+5. **审核门控（差异化）**:
+   - **design：Claude 自审 → Codex 审 → 人类审**（保留人类门，批准后方可进入计划阶段）。
+   - **plan：Claude 自审 → Codex 审 → 直接执行**（无 plan 人类门）；plan 经 Claude 自审 + Codex 审通过后直接进入 Phase 2 执行。
+
+### Phase 2: 执行与验证 (Execution & Verification)
+1. **编码**: 审核通过后，开始编写代码。
+2. **验证**: 声称工作完成前，**必须**调用 `verification-before-completion` skill 进行验证。
+   - **环境检查**: 确保所有命令在 `Video-Tree-TRM` 环境中执行。
+   - *失败*: 回到编码阶段修复，直到通过。
+   - *成功*: 进入下一步。
+
+## 4. 核心规则 (Rules)
+
+### 4.1 核心原则 (Core Principles)
+
+> 以下原则按优先级排序，冲突时高优先级原则优先。
+
+#### P1: YAGNI（You Aren't Gonna Need It）
+- 不写当前用不到的代码。"未来可能需要"不是写代码的理由。
+- 但 YAGNI **不等于**砍健壮性：生产级所需的并发控制、防御校验、可观测埋点、错误隔离与测试**都是"当前需要"**，不在 YAGNI 削减之列。
+- 抽象只在真正易变 / 需替换 / 需造测试替身的接缝处引入（见 `research-wiki/ARCHITECTURE.md §3`），其余写直白的领域函数。
+
+#### P2: 高可读性（Readability）
+- 命名：用领域术语命名，不用技术实现命名。名字应让人无需读函数体就能猜出它干什么。
+- 注释：解释"为什么"，不解释"是什么"。需要注释来解释代码在做什么 = 代码不够清晰。
+
+#### P3: 单一职责（Single Responsibility）
+- 每个函数只做一件事，每个模块只负责一个领域。
+- 判断标准：能否用一句话描述职责？需要用"和"连接 = 应该拆分。
+
+#### P4: 显式优于隐式（Explicit over Implicit）
+- 所有公共函数的参数和返回值必须有完整类型注解。
+- 函数需要的东西通过参数传入（依赖注入），不从全局状态或环境变量中偷偷拿取。
+- **严禁**使用默认参数掩盖逻辑（必须显式传递关键参数）。
+
+#### P5: 防御性与安全性（Defensiveness & Safety）
+- 所有外部输入（用户输入、API 响应、LLM 返回、文件读取）校验后再使用。
+- **严禁** `except Exception: pass`。每个 except 处理特定异常类型。
+- **严禁**出错后使用默认值掩盖错误。正确做法是直接报错。
+- 敏感信息（API key、密码、token）不得出现在代码中，走 `.env` / 密钥管理。
+
+#### P6: 可测试性（Testability）
+- 纯函数优先：相同输入永远产生相同输出。
+- 外部依赖通过端口（Protocol）注入，便于测试时替换成假实现（见 `research-wiki/ARCHITECTURE.md §3` 接缝清单）。
+- 测试用例应尽可能使用真实样本，而非完全虚假的数据。
+
+### 4.2 代码开发规范 (Code Style)
+- **文档**: 所有模块、类、方法必须包含 **中文 Docstring** (功能、参数、返回值、关键实现细节)。
+- **运行时检查**: 关键维度、设备一致性、门控条件必须通过 assertion 或 if 验证。
+- **代码组织**:
+  - 使用阶段化注释 (`# Phase 1`, `# Phase 2`) 组织复杂逻辑。
+  - 接口返回值需包含完整诊断信息（输出、统计、溯源），使用条件标志控制。
+- **命名与依赖**:
+  - 类名 `PascalCase`，变量描述性命名，私有变量前缀 `_`。
+  - 导入顺序：标准库 → 第三方库 → 项目内部。
+- **日志与错误处理**:
+  - 使用 **loguru** 作为统一日志框架，禁用 `print()`。
+  - Agent 遥测走 `TelemetryRecorder` Protocol（见 §4.8），不要自己拼裸 SQL 或临时落盘。
+- **功能修改**:
+  - **必须** 不考虑向后兼容，直接修改原文件。代码简洁性优先。
+
+### 4.3 Git 工作流规范
+- **Feature Branch**: 所有开发工作在 feature 分支上进行，**严禁**直接在 main/master 上修改。
+- **增量提交**: 频繁提交，每个提交有明确的语义。
+- **提交前检查**: 提交前 `git diff` 审查变更，避免提交调试代码或临时文件。
+- **风险操作前备份**: 执行重构或大改动前，先提交当前状态作为回滚点。
+- **Commit 规范**: 提交代码时**必须**调用 `commit` skill。
+
+### 4.4 工作区与实现规范
+- **临时文件清理**: 任务完成后删除所有临时脚本、调试输出、中间文件。
+- **实现完整性**: 开始实现就必须完成到可运行状态，**严禁**留下 `TODO`、`NotImplementedError`、mock 占位。
+- **知识输出路径**: 所有 Skill 产出的知识统一写入 `research-wiki/`（单一事实源）。
+  - 设计文档 → `research-wiki/designs/`
+  - 实现计划 → `research-wiki/plans/`
+  - 调试发现 → `research-wiki/findings/`
+  - 架构决策 → `research-wiki/adrs/`
+  - 审查记录 → `research-wiki/reviews/`
+
+### 4.5 配置管理规范（双模式）
+
+本项目存在两类配置，**互不混用**：
+
+| 模式 | 用途 | 载体 | 优先级 |
+|------|------|------|--------|
+| **工程配置** | 系统运行所需、少变或敏感（API 密钥、Redis URL、LLM 超时等） | `pydantic-settings` + `.env`（敏感项不提交，模板见 `.env.example`） | `.env` 环境变量 |
+| **科研实验配置** | 会在实验中被反复扫动 / 对比的参数（gate 阈值、batch 大小、评估口径等） | per-experiment YAML + harness run 运行快照（保证可复现） | 实验 YAML |
+
+> **D7 配置归属判定规则（防串台，强制遵守）**：
+> 某参数**是否会在科研实验中被反复扫动 / 对比**？
+> - **是** → 科研配置（per-experiment YAML + harness run 快照）。
+> - **否**（系统运行所需、少变、或敏感）→ 工程配置（`pydantic-settings` + `.env`）。
+>
+> **CLI args 仅用于单次临时覆盖，不作为任何配置的常驻来源。**
+> **配置合并优先级**: CLI args > `.env` > YAML，三者统一归口到 dataclass。
+
+- **原则**: 上述两类载体之外，严禁在代码中散落硬编码默认值；缺失关键配置应直接报错而非兜底。
+- **Prompt 分类**: 推理 prompt（`system.md`、`*_extract.md`、`*_verify.md`）存放在 `store/prompts/` 下，参与版本化进化。诊断 prompt（`diagnose_*.md`）存放在项目根 `prompts/` 下，不参与版本化——它们是评估标尺，不应随进化改变。
+
+### 4.6 测试组织规范
+#### 测试哲学
+- **真实场景优先**: 测试用例应使用真实数据或真实数据的二次构造，而非完全虚假的样本。
+- **边缘场景处理**: 边缘场景不通过测试解决，而是通过代码中的 assertion/报错解决。测试只负责确保核心功能和核心场景能真实跑通。
+- **测试目标**: 验证系统在真实条件下的端到端正确性。生产级业务应**逐步提高覆盖率并以 integration 测试为重**。
+
+- **目录**: `tests/{unit,integration,e2e}/test_*.py`，最低覆盖率 80%
+- **运行**: `conda run -n Video-Tree-TRM pytest tests/ --cov=app --cov=core --cov-report=term-missing`
+
+#### Agent 测试输出规范（仅限 agent / LLM 类测试）
+
+> 下述规范**只适用于涉及 agent / LLM 执行的测试**；常规单元 / 集成测试无需产出该 MD。
+
+| 要素 | 规范 |
+|------|------|
+| **输出位置** | `tests/outputs/<test_module>/<test_name>_<timestamp>.md` |
+| **触发时机** | 所有涉及 Agent / LLM 执行的测试 |
+| **内容要求** | 任务描述、每步 Agent 输入/输出/推理过程、工具调用、最终结果 |
+| **格式要求** | 结构化 Markdown（标题、代码块、列表），人类可读 |
+| **分析方式** | Claude Code 读取 MD 文件，评估推理质量、任务完成度、代码正确性 |
+
+**pytest 集成**: 使用 fixture 或工具类自动保存，测试结束后输出文件路径。
+
+### 4.7 核心算法保真
+
+迁移时逐一比对参考代码，不可简化。完整清单见 `research-wiki/ARCHITECTURE.md §6`（建树 4 项 + 训练 9 项 = 13 项）。
+
+| # | 算法 | 核心逻辑 |
+|---|------|---------|
+| 1 | L2 轴心建树策略 | L2 先行→L3 向下→L1 向上，asyncio 链式并发 |
+| 2 | VLM 批量帧描述 + JSON fallback | `_L3_BATCH_SIZE=5` 批量调用，解析失败逐帧 fallback |
+| 3 | 断点续跑机制 | `progress.json` + L1 中间 JSON，按段恢复 |
+| 4 | RecursiveRetriever | Cross-Attention 选择器 + ACT halt + z 状态累积 |
+| 5 | CE-Gate e-process | 截断 Beta 混合、四出口门控 |
+| 6 | 信息阶梯 | 冷启动 2:1、gamma-EMA、反泄漏 |
+| 7 | 块顺序验证 | 基线缓存、INFRA 护栏、配对翻转 |
+| 8 | 诊断瀑布 | 错误归因级联、缺陷 vs 失误、D1-D5 |
+| 9 | 进化 patch 引擎 | 保护跨度、rank-and-clip、附录/动量 |
+| 10 | Mini-batch 构建 | FFD + round-robin + 正确率混合 |
+| 11 | Agent Loop | Thinking+JSON、json_repair、pluggy hook |
+| 12 | 树环境语义搜索 | 分块 embedding、祖先去重、锚定验证 |
+| 13 | 训练循环编排 | 三级嵌套、慢更新10步、断点续训 |
+
+> **任何 PR 涉及上述算法的修改，必须在 commit message 中标注对应序号并说明变更理由。**
+
+### 4.8 Agent 遥测
+
+每次 LLM/VLM 调用必须经过 `TelemetryRecorder` Protocol（`core/evolution/protocols.py`）记录。完整规范见 `research-wiki/ARCHITECTURE.md §4`。
+
+| 必录字段 | 类型 | 说明 |
+|----------|------|------|
+| `call_id` | str | UUID，本次调用唯一标识 |
+| `session_id` | str | epoch/step/question 关联 ID |
+| `model_name` | str | 使用的模型名 |
+| `prompt_tokens` / `completion_tokens` | int | token 用量 |
+| `latency_ms` | int | 延迟毫秒 |
+| `cache_hit` | bool | 是否命中 Redis 缓存 |
+| `error` | str? | 异常信息（正常为 null） |
+
+**存储实现**：`adapters/telemetry.py` → SQLite `telemetry.db`。`GovernedLLMClient`（`adapters/llm.py`）在每次调用后自动写入，**严禁**绕过此路径裸调 LLM API。
+
+### 4.9 LLM 韧性
+
+所有 LLM/VLM 调用必须经过 `GovernedLLMClient`（`adapters/llm.py`）治理，禁止裸调 OpenAI SDK。治理栈五层（详见 `research-wiki/ARCHITECTURE.md §5`）：
+
+| 层 | 机制 | 说明 |
+|---|------|------|
+| 1 | 硬超时 | `asyncio.wait_for(call, timeout=config.llm_timeout)` |
+| 2 | 指数退避重试 | `max_retries`、`base_delay`、`max_delay`（可配置） |
+| 3 | 熔断器 | 连续 N 失败 → 短路 M 秒 → 探针恢复 |
+| 4 | Redis 响应缓存 | content-addressed：`hash(model + messages)` → response |
+| 5 | ARQ 任务队列 | 长时间推理任务异步执行 |
+
+> 熔断参数（`LLM_CIRCUIT_BREAKER_THRESHOLD`、`LLM_CIRCUIT_BREAKER_COOLDOWN`）和超时（`LLM_TIMEOUT`）通过 `.env` 工程配置管理。
+
+## 5. 项目结构规范
+
+目录结构遵循 `research-wiki/ARCHITECTURE.md §2.3` Clean Architecture 四层分层：
+
+```text
+project_root/
+├── CLAUDE.md                # Agent 指令入口
+├── README.md                # 项目概览与快速开始
+├── Makefile                 # 工程命令收口（test / lint）
+├── main.py                  # CLI 入口（唯一允许的根目录 .py）
+├── .env / .env.example      # 工程配置（.env 不提交 Git）
+├── .claude/                 # Claude 配置（skills, hooks, tools）
+│
+├── core/                    # 可提取内核（不依赖 app/、adapters/）
+│   ├── agent/               # AgentLoop 引擎（loop, types, protocols）
+│   ├── evolution/           # 诊断+进化引擎（diagnose, evolve, gate）
+│   └── types.py             # 跨模块共享类型
+│
+├── app/                     # 应用层（组合 core + adapters，领域特化）
+│   ├── tree/                # 建树模块（TreeIndex, VideoTreeBuilder）
+│   ├── harness/             # 训练 harness（runner, inference, batching）
+│   ├── question_gen/        # 新题构建
+│   ├── search/              # 搜索 Agent 装配（prompt, skills）
+│   ├── retriever/           # 可训练检索器（RecursiveRetriever）
+│   └── ports.py             # 应用层端口
+│
+├── adapters/                # 外部实现层（LLM/VLM/embedding/cache/遥测）
+├── config/                  # 声明性配置（YAML，禁止 .py）
+├── store/                   # 版本化资源（skills/prompts/questions/videos）
+├── workspaces/              # 实验工作区
+├── prompts/                 # 诊断 prompt（不参与进化，是评估标尺）
+├── scripts/                 # 实验运行脚本（仅 .sh，禁止 .py）
+├── tools/                   # 独立工具脚本（不被其他模块 import）
+├── tests/                   # 测试代码
+│   ├── unit/
+│   ├── integration/
+│   └── e2e/
+├── data/                    # 数据（不提交 Git）
+├── logs/                    # 运行日志（不提交 Git）
+├── results/                 # 实验结果输出
+└── research-wiki/           # 研究知识库 = 单一事实源
+```
+
+### 硬性规则
+1. **依赖只能向内**：`adapters/` → `app/ports.py` / `core/protocols.py`；`app/` → `core/`；`core/` 绝不依赖 `app/` 或 `adapters/`。
+2. **可提取内核判据**：`core/agent/` 和 `core/evolution/` 搬到没有 adapters 的环境，用假实现替换 Protocol 即可原样运行。
+3. **根目录除 `main.py` 外不得出现 `.py` 文件。**
+4. **`prompts/`、`config/` 只放声明性文件**（.md / .yaml / .json），不放可执行代码。
+5. **`scripts/` 只放 `.sh` 脚本**，不放 `.py` 文件。
+6. **禁止创建以下目录名**：`helpers/`、`common/`、`shared/`、`misc/`、`lib/`。必须使用具体的领域名称。
+7. **`data/`、`logs/` 不提交 Git。**
+
+## 6. 上下文获取与迷途指南 (Context & Navigation)
+
+| 需求 | 文档路径 | 说明 |
+|------|----------|------|
+| 系统架构与边界 | `research-wiki/ARCHITECTURE.md` | 四层分层、依赖方向、接缝清单、核心算法、韧性规范 |
+| 项目目标与背景 | `README.md` | 核心业务逻辑与项目定性 |
+| 关键决策记忆 | `research-wiki/adrs/` | 架构决策记录（ADR） |
+| 领域知识压缩摘要 | `research-wiki/query_pack.md` | idea-creator 的核心上下文输入 |
+| 研究知识库索引 | `research-wiki/index.md` | 所有实体的分类索引 |
+| 代码结构检索 | `graphify-out/GRAPH_REPORT.md` + `conda run -n Video-Tree-TRM graphify query/path/explain/affected`（主对话可用 `/graphify`） | 读代码前先查图谱而非盲读；首次需手动 `/graphify .`，刷新用 `/graphify . --update` |
+
+## 7. 输出规范
+
+### 7.1 语言要求
+- 所有输出语言: **中文**
+
+### 7.2 文档撰写约束
+
+#### 优先使用的表达方式（按优先级排序）
+1. **表格** — 对比、配置、参数说明、实验结果等结构化信息
+2. **伪代码** — 描述算法和流程时，而非完整可执行代码
+3. **Mermaid 流程图** — 流程、架构、状态转换
+4. **简洁的连贯段落** — 论述逻辑关系时，2-3 句话的短段落
+
+#### 严格禁止
+- **禁止大段代码**: 文档中不得出现超过 15 行的代码块。需要展示实现思路时用伪代码；需要完整代码时引用文件路径。
+- **禁止碎片化列点**: 不得出现连续超过 5 个的短句列点。改用表格或合并为连贯段落。
+- **禁止冗长解释**: 能用一句话说清的不用三句话。能用表格呈现的不用段落罗列。
+
+#### 文档长度控制
+
+| 文档类型 | 长度上限 | 超出时的处理 |
+|---------|---------|------------|
+| 实验报告 | 300 行 | 拆分为摘要 + 附录，摘要不超过 100 行 |
+| 计划/方案（`research-wiki/plans/`） | 1000 行 | 聚焦关键决策，细节留给代码注释 |
+| 设计文档（`research-wiki/designs/`） | 400 行 | 用 Mermaid 图替代文字描述 |
+| 会议/进度记录 | 100 行 | 只记结论和 action items |
+
+## 8. Skill 使用规则
+
+> [!CRITICAL]
+> **Skill 调用是无条件义务，不是判断题。**
+>
+> 当任务匹配下方触发时机表中的任一条件时，你**必须**在行动前通过 Skill 工具调用对应 Skill。
+>
+> **以下任何理由都不构成跳过 Skill 的正当依据：**
+> - "用户已经给出了明确方案，brainstorming 不会产生额外价值"
+> - "这个改动很小/很简单，不需要走完整流程"
+> - "我判断调用后也会发现不适用"
+> - "用户的指令已经足够具体，不需要探索"
+>
+> **你没有权限做这个判断。** 即使你 100% 确信 Skill 不会改变结果，仍然必须调用。
+> 调用后 Skill 流程明确指示"不适用"时，才可以跳过后续步骤。
+>
+> **优先级（从高到低）：**
+> 1. 用户的显式指令（如用户说"跳过 brainstorming"则可跳过）
+> 2. Skill 的详细流程（优先于 CLAUDE.md 中的宏观规则）
+> 3. CLAUDE.md 宏观规则
+
+### 工程类 Skill（当前主力，按触发时机强制调用）
+
+| Skill | 触发时机 |
+|-------|---------|
+| `brainstorming` | 创建新功能、新组件、修改行为前 |
+| `writing-plans` | 有需求/规格后、编码前 |
+| `systematic-debugging` | 遇到 bug、测试失败、异常行为时 |
+| `test-driven-development` | 实现功能或修复 bug 时 |
+| `verification-before-completion` | 声称完成、提交、创建 PR 前 |
+| `commit` | 提交代码时 |
+| `finishing-a-development-branch` | 实现完成且测试通过，准备集成时 |
+| `subagent-driven-development` | 执行实现计划时：Claude 子代理实现 + 3×Codex 审（规格合规 / 功能质量 / 代码风格） |
+| `requesting-code-review` | 完成重要功能、合并前（Codex 审查） |
+| `receiving-code-review` | 收到代码审查反馈后 |
+| `structured-logging` | 功能会产生运行时数据时，brainstorming 之后 |
+| `research-wiki` | 管理知识库、初始化、查询、统计时 |
+| `harness-eval` | 功能完成后评估性能，或 subagent-driven-development Step 10 |
+
+### 科研类 Skill（现阶段先不用，不写门控规则）
+
+> 这些 skill 为一等公民资产，但项目当前处于工程为主的架构平台期，**现阶段先不用**；**何时启用由模型依据任务实际需要自行判断**，不设强制触发门控。
+
+| Skill | 用途 |
+|-------|------|
+| `research-lit` | 了解领域现状、找论文、文献综述 |
+| `idea-creator` | 生成 / 排序研究想法 |
+| `novelty-check` | 验证想法新颖性、查新 |
+
+## 9. Research Wiki
+
+> 项目唯一知识仓库（单一事实源），所有 Skill 产出的研究与开发知识统一存储于此。
+
+### 初始化
+使用 `/research-wiki init` 或 `python3 .claude/tools/research_wiki.py init research-wiki/`。
+
+### 实体类型
+
+| 实体 | 目录 | 来源 Skill |
+|------|------|-----------|
+| paper | `papers/` | research-lit |
+| idea | `ideas/` | idea-creator |
+| experiment | `experiments/` | run-experiment（未来） |
+| claim | `claims/` | novelty-check |
+| gap | `gaps/` | research-lit, idea-creator |
+| design | `designs/` | brainstorming |
+| finding | `findings/` | systematic-debugging, verification |
+| adr | `adrs/` | 架构决策记录（重大不可逆的技术决策） |
+| plan | `plans/` | writing-plans |
+| review | `reviews/` | code-review |
+| schema | `schemas/` | structured-logging |
+| metric | `metrics/` | structured-logging, harness-eval |
+
+### 关键文件
+
+| 文件 | 说明 |
+|------|------|
+| `query_pack.md` | 压缩摘要（≤8000 字符），idea-creator 的核心上下文 |
+| `index.md` | 自动生成的分类索引 |
+| `log.md` | 所有变更的审计日志 |
+| `graph/edges.json` | 实体间关系图（NetworkX JSON） |