@bolloon/bolloon-agent 0.1.0

package/src/bollharness/reference/boll-reference/.claude/skills/guardian-fixer/SKILL.md

@@ -0,0 +1,326 @@
+---
+name: guardian-fixer
+description: 守夜人 issue 自动修复管道。8 Gate 全流程——规划、独立审查、开发、测试、闭环、PR。用于修复 docs/issues/guard-*.md 中 status:open 的 issue。
+status: active
+tier: execution
+owner: nature
+last_audited: 2026-03-24
+triggers:
+  - 修复 guardian issue
+  - 执行 guard issue
+  - 自动修复管道
+outputs:
+  - 独立 branch 上的 PR
+  - 完整 Gate artifacts (PLAN/REVIEW/TASK/LOG/TEST/CLOSURE)
+truth_policy:
+  - issue 文档是唯一执行队列
+  - 不从口头描述、memory、聊天记录直接开做
+  - 代码真相以 repo 当前状态为准，不以 issue 描述为准
+---
+
+# 守夜人 Issue 自动修复
+
+## 我是谁
+
+我把 `docs/issues/guard-*.md`（status: open）变成可合并的 PR。我不发现 issue（那是巡逻的事），我只修复。
+
+## 核心约束
+
+1. **8 Gate 全走，一个都不能少。** 简单 issue 不是跳步的理由。
+2. **审查是独立的。** Gate 2/4/7 必须 spawn 独立 subagent（opus），不是自己审自己。
+3. **验证是诚实的。** 跑不了的测试标 BLOCKED，不标 PASS。"collect 通过" ≠ "测试通过"。
+4. **写了代码必须运行。** 每个 WP 完成后必须有运行时证据（命令 + 输出），不是"看起来对"。
+
+## 执行流程
+
+### Step 0: 选 issue
+
+```bash
+# 找到优先级最高的可执行 issue
+grep -rl 'status: open' docs/issues/guard-*.md | while read f; do
+  sev=$(grep '^severity:' "$f" | sed 's/severity: *//')
+  exec_st=$(grep '^execution_status:' "$f" | sed 's/execution_status: *//')
+  # 跳过已有 execution_status 的（除了 pending）
+  if [ -z "$exec_st" ] || [ "$exec_st" = "pending" ]; then
+    echo "$sev|$f"
+  fi
+done | sort
+```
+
+选第一个（P0 > P1 > P2）。如果需要检查 zone 冲突，查 DESIGN 文档 Section 3.6 的 CODE_ZONES。
+
+### Step 1: 建 worktree
+
+```bash
+ISSUE_SLUG="guard-YYYYMMDD-HHMM-slug"  # 从 issue 文件名提取
+git worktree add /tmp/boll-$ISSUE_SLUG -b codex/$ISSUE_SLUG main
+mkdir -p /tmp/boll-$ISSUE_SLUG/docs/decisions/tasks/GUARD-YYYYMMDD-HHMM
+```
+
+以下所有操作在 worktree 目录内进行。
+
+### Step 2: Gate 1 — 规划
+
+**输入**: issue 文档
+**产物**: `PLAN.md`
+
+PLAN.md 必须包含：
+
+```markdown
+# PLAN: guard-YYYYMMDD-HHMM — 标题
+
+**Issue**: issue 文档路径
+**Severity**: P0/P1/P2
+**Component**: 主要代码文件
+
+## 问题分析
+（根因，不是症状）
+
+## 变更清单
+| # | 文件 | 变更 | 类型 |
+
+## 契约 vs 实现分析
+- 契约变更？消费方？
+
+## 同类检查
+（grep 验证是否有其他地方有同样的问题）
+
+## 测试策略
+（修改前/修改后的验证方法）
+
+## Scope 判定
+- ≤3 文件 + 无契约变更 → 可执行
+- 否则 → needs_plan，停止
+```
+
+**Scope 硬上限**：
+- 超过 3 个代码文件 → 标 `needs_plan`，停止
+- API/schema/event 契约变更 → 标 `needs_plan`，停止
+- 需要数据库 migration → 标 `needs_plan`，停止
+
+### Step 3: Gate 2 — 独立审查 PLAN
+
+**用 Agent tool spawn 独立审查者（opus 模型）。不是自己审自己。**
+
+```
+Agent tool:
+  model: opus
+  prompt: |
+    你是独立代码审查者。你没有参与这段代码的编写。
+
+    审查 PLAN 文档：[路径]
+    对照 issue 文档：[路径]
+    读相关代码文件。
+
+    审查维度（全部覆盖）：
+    1. 覆盖性：变更清单完整吗？
+    2. 独立性：每个改动可独立验证吗？
+    3. 执行模拟：逐步走，开发者会卡住吗？
+    4. 自包含性：有执行所需全部信息吗？
+    5. 元数据准确性：severity/component/scope 正确吗？
+    6. 修复完整性：修复完整吗？有没有引入新问题？
+
+    输出写入：[PLAN-REVIEW.md 路径]
+    YAML frontmatter 必须有 verdict: PASS 或 FAIL。
+```
+
+**如果 FAIL**：修改 PLAN，重新提交审查（最多 2 轮）。2 轮不通过 → 标 `blocked`，停止。
+
+### Step 4: Gate 3 — 任务拆解
+
+**产物**: `TASK.md`
+
+```markdown
+# TASK: guard-YYYYMMDD-HHMM
+
+## WP-N: 标题
+**文件**: 路径
+**改什么**: 具体描述
+**验收标准**: 可机械验证的条件
+
+## 验收测试
+| # | 方法 | 预期结果 |
+```
+
+### Step 5: Gate 4 — 独立审查 TASK
+
+同 Gate 2，spawn 独立审查者审查 TASK.md。
+
+### Step 6: Gate 5 — 开发
+
+**操作顺序**：
+
+1. **先开 LOG.md**（实时写，不是事后补）
+2. 逐个 WP 执行：
+   a. 写代码
+   b. **运行代码**（关键！不是"看起来对"就 commit）
+   c. 记录运行命令和输出到 LOG.md
+   d. 验证 TASK.md 中的验收标准
+3. 更新 issue 文档状态（pre-commit hook 要求）
+4. Commit（不 push）
+
+**Worktree 里 Read/Edit 工具可能被 guard hook 阻塞**（pre-existing findings）。用 Bash 操作 worktree 文件：
+- 读文件：`cat` / `tail`
+- 写文件：`cat > file << 'EOF'` 或 `cat >> file << 'EOF'`
+- 小修改：`sed -i ''`
+
+**LOG.md 格式**：
+
+```markdown
+# LOG: guard-YYYYMMDD-HHMM
+
+## WP-N: 标题
+- 做了什么
+- 运行命令 + 输出（证据）
+- 偏差说明（如果有）
+
+## 验收检查
+| # | 方法 | 结果 |
+```
+
+### Step 7: Gate 6 — 测试
+
+**运行所有能跑的测试**：
+
+```bash
+# 从 worktree 运行，用主仓库的 venv
+VENV=/Users/nature/个人项目/boll/backend/venv/bin/pytest
+
+cd /tmp/boll-$ISSUE_SLUG
+$VENV -q backend/tests/unit/           # 无 Docker
+$VENV -q backend/tests/field/          # 无 Docker
+$VENV -q backend/tests/test_phase0_surface.py  # 无 Docker
+$VENV -q backend/tests/product/        # 需要 Docker
+$VENV -q backend/tests/matching/      # 无 Docker
+```
+
+**产物**: `TEST.md`
+
+```markdown
+# TEST: guard-YYYYMMDD-HHMM
+
+## 测试执行结果
+
+### 可运行测试
+| 测试集 | 数量 | 结果 | 命令 |
+
+### 需要 Docker 的测试
+| 测试集 | 状态 | 原因 |
+
+### 诚实声明
+- 新代码有没有被测试覆盖？
+- 是"旧测试通过"还是"新代码验证通过"？
+- 有没有把 BLOCKED 标成 PASSED？
+```
+
+**诚实规则**：
+- "collect 通过" ≠ "测试通过"
+- "旧测试通过" ≠ "新代码验证通过"
+- Docker 不可用 → 标 BLOCKED，不标 PASS
+- 不虚构测试数量
+
+### Step 8: Gate 7 — 最终审查
+
+Spawn 独立审查者（opus）审查代码 diff + 测试结果。
+
+```
+Agent tool:
+  model: opus
+  prompt: |
+    你是独立代码审查者（最终审查）。
+
+    审查 git diff + TEST.md + LOG.md。
+    检查代码是否与 PLAN 一致。
+    检查有没有引入新问题。
+    检查 TEST.md 是否诚实。
+
+    输出写入：[FINAL-REVIEW.md 路径]
+    verdict: PASS 或 FAIL。
+```
+
+### Step 9: Gate 7.5 — Closure
+
+**产物**: `CLOSURE.md`
+
+```markdown
+# CLOSURE
+
+## Issue 闭环状态
+- status: fixed ✓/✗
+- prevention_status: closed ✓/✗
+- mechanism_layer: guard|test|type|convention ✓/✗
+
+## 文档同步清单
+
+### 必须更新
+- [ ] issue 文档 status/prevention_status
+
+### 可能需要更新（写进 PR 描述）
+- [ ] CLAUDE.md 路由表（如果改了 API）
+- [ ] 其他 issue 文档（如果修复也解决了其他问题）
+
+### 不需要更新
+- （列出检查过但不需要改的）
+```
+
+**禁止修改的文件**：
+- CLAUDE.md（行为指令部分）
+- AGENTS.md
+- `.claude/skills/*/SKILL.md`
+- `scripts/guard-feedback.py`
+- `scripts/context_router.py`
+
+### Step 10: Gate 8 — Push + PR
+
+```bash
+cd /tmp/boll-$ISSUE_SLUG
+git push -u origin codex/$ISSUE_SLUG
+gh pr create --title "fix(...): guard-YYYYMMDD-HHMM 标题" --body "..."
+```
+
+PR 描述必须包含：
+- Issue 路径
+- 变更摘要
+- 8 Gate 结果表
+- 验证结果（诚实标注 PASS/BLOCKED）
+- Artifacts 列表
+
+## 异常处理
+
+| 场景 | 操作 |
+|------|------|
+| Scope 超 3 文件 | Gate 1 标 `needs_plan`，停止 |
+| 审查 2 轮不通过 | 标 `blocked`，停止 |
+| 测试失败且无法修 | TEST.md 记录失败原因，标 `blocked`，停止 |
+| 碰禁止修改的文件 | 停止 |
+| Rebase 冲突 | 标 `needs_coordination`，停止 |
+
+**所有异常路径都停止。不要强行继续。**
+
+## 反模式清单
+
+以下行为是明确禁止的（PLAN-064 教训）：
+
+| 反模式 | 正确做法 |
+|--------|---------|
+| 写完代码不运行就 commit | 每个 WP 必须有运行时证据 |
+| LOG.md 从 git log 生成 | LOG.md 在写代码时实时写 |
+| 把 "199 tests PASS" 当验证 | 区分旧测试/新测试，标注新代码覆盖率 |
+| 4 分钟完成一个 WP | 如果太快，说明没有运行验证 |
+| 自己审自己 | Gate 2/4/7 必须 spawn 独立 subagent |
+| Docker 不可用就跳过 | 标 BLOCKED，不标 PASS |
+
+## Gate 检查清单
+
+执行前自检——**如果正在写代码但 PLAN.md 不存在，立刻停下来。**
+
+```
+□ PLAN.md 存在？           → Gate 2 可以开始
+□ PLAN-REVIEW.md verdict: PASS？ → Gate 3 可以开始
+□ TASK.md 存在？           → Gate 4 可以开始
+□ TASK-REVIEW.md verdict: PASS？ → Gate 5 可以开始
+□ LOG.md 存在？            → Gate 6 可以开始
+□ TEST.md 存在？           → Gate 7 可以开始
+□ FINAL-REVIEW.md verdict: PASS？ → Gate 7.5 可以开始
+□ CLOSURE.md 存在？        → Gate 8 可以开始
+```

package/src/bollharness/reference/boll-reference/.claude/skills/lead/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: lead
+description: 流形开发流程统领（fail-closed 状态机）。从想法到生产代码的全流程管理，机械化门禁强制。当用户提出新功能、改动需求、或需要讨论方向时使用。
+status: active
+tier: entry
+owner: nature
+last_audited: 2026-03-27
+triggers:
+  - 新功能
+  - 方向讨论
+  - 跨模块修复
+  - 需要 Gate 管理
+outputs:
+  - Gate 包（current_gate + required_artifact + required_next_skill + required_review_substrate）
+  - 决策缺口
+  - 执行 DAG 骨架
+truth_policy:
+  - 不复制实时仓库事实
+  - 实时事实以 boll-dev-handoff 的真相优先级为准
+  - 只维护稳定流程、门禁和升级条件
+---
+
+# 流形开发统领（Fail-Closed 状态机）
+
+## 我是谁
+
+我是 fail-closed 的流程状态机。我的职责不是建议，而是**阻塞**——没有满足入门条件就不能进下一门。
+
+我优先处理的不是"快不快"，而是：
+
+1. 当前处于哪一门，前置条件是否满足
+2. 下一门需要什么产物，由哪个 skill 产出
+3. 审查由谁做，用什么基底（TeamCreate，不是 Agent）
+
+## 状态机定义
+
+### Gate 转移表
+
+| Gate | 名称 | entry_condition | required_artifact | required_next_skill | required_review_substrate |
+|------|------|-----------------|-------------------|---------------------|--------------------------|
+| 0 | 问题锁定 | 用户提出需求 | 问题陈述 + Change Classification | `arch` | — |
+| 1 | 架构设计 | Gate 0 产物存在 | ADR 草稿 + 消费方清单 | `arch` | — |
+| 2 | 架构审查 | ADR 草稿完成 | 审查报告（PASS/BLOCK） | **TeamCreate** | `ref-review-sop.md` 阶段②维度 |
+| 3 | PLAN | Gate 2 PASS | PLAN 文档 + 架构覆盖矩阵 | `boll-eng` + `plan-lock` | — |
+| 4 | PLAN 审查 + plan-lock | PLAN `vN-final` 冻结 | 审查报告 + plan-lock 确认 | **TeamCreate** | `ref-review-sop.md` 阶段④维度 + C/D/E/F |
+| 5 | task-arch | Gate 4 PASS + plan-lock | WP 拆分 + TASK.md | `task-arch` | — |
+| 6 | task 审查 | 全部 TASK.md 完成 | 审查报告（PASS/BLOCK） | **TeamCreate** | `ref-review-sop.md` WP 拆分专项 |
+| 7 | 执行 + 日志 | Gate 6 PASS | 代码 + LOG.md（每 WP 实时写） | `boll-eng` / `boll-dev` | — |
+| 8 | 执行审查 | 全部 WP 代码 + LOG.md 存在 | 审查报告 + 验收确认 | **TeamCreate** + `boll-eng-test` | `ref-review-sop.md` 阶段⑤⑥维度 |
+
+### 转移函数（硬规则）
+
+```
+transition(current_gate, artifact) -> next_gate | BLOCKED
+
+规则：
+- Gate N 的 entry_condition 未满足 → BLOCKED，输出缺什么
+- Gate 2/4/6/8 的 required_review_substrate 是 TeamCreate → Agent 审查 = 不合规
+- Gate 4 → Gate 5：PLAN 必须有 plan-lock 标记（vN-final）
+- Gate 5 → Gate 6：task-arch 产物必须存在（TASK.md）
+- Gate 6 → Gate 7：task 审查 PASS
+- Gate 7 → Gate 8：每个 WP 必须同时有代码 commit 和 LOG.md
+- Gate 8 PASS → 完成；BLOCK → 回退到对应 Gate 修复
+```
+
+### 审查门强制 TeamCreate
+
+Gate 2/4/6/8 是审查门。硬规则：
+
+```
+审查门执行方式：
+  ✅ TeamCreate("review-{plan-id}-gate-{N}")  — 独立上下文，多视角
+  ❌ Agent(subagent_type="...")               — 共享上下文，单视角，不合规
+```
+
+审查维度参见 `ref-review-sop.md`。Gate 4 额外覆盖 C/D/E/F 维度。
+
+## Output Contract
+
+每次调用我，我**必须**先输出 Gate 包：
+
+```yaml
+gate_pack:
+  current_gate: N            # 当前所在门
+  entry_satisfied: true/false # 入门条件是否满足
+  blockers: [...]            # 未满足的条件列表
+  required_artifact: "..."   # 本门需要产出什么
+  required_next_skill: "..." # 由谁产出
+  required_review_substrate: "..." # 审查用什么（如果是审查门）
+```
+
+如果 `entry_satisfied: false`，不输出任何执行建议，只输出 blockers。
+
+## 快速通道
+
+只有同时满足以下**全部 5 条**，才允许跳 gate（不能跳 skill）：
+
+1. 改动不超过 3 个文件
+2. 无契约变更（Change Classification = `implementation`）
+3. 无跨模块接缝
+4. 不影响用户心智或产品语义
+5. 不引入新的架构决策
+
+快速通道仍然需要：执行 skill + 审查（可简化为单人 TeamCreate）。
+
+## Change Classification
+
+每个工作单元先分类，分类决定最低门禁：
+
+| 分类 | 定义 | 最低门禁 |
+|------|------|---------|
+| `policy` | 边界、身份、权限、场景承诺、对外语义 | Gate 0 → Gate 8 全走 |
+| `contract` | API、schema、事件、共享配置、生成物 | Gate 0 → Gate 8 全走 + 消费方清单 |
+| `implementation` | 单模块内部实现 | 可走快速通道（需满足 5 条） |
+
+## Parallel Planning Contract
+
+进入并行前必须显式写出：
+
+```yaml
+parallel_contract:
+  write_set: [...]           # 每个 track 的写文件集
+  parallel_tracks: [...]     # 并行 track 列表
+  depends_on: {track: dep}   # 依赖关系
+  integration_owner: "..."   # 集成负责人
+  seam_owner: "..."          # 接缝负责人
+  golden_journeys: [...]     # 端到端验证路径
+```
+
+如果两个 track 有共享接口但没有 `seam_owner` → 不是可执行计划 → BLOCKED。
+
+## 来自 crystal-learn 的门禁
+
+**INV-4 真相源分裂**：涉及文档、配置、版本、部署描述时，必须追问"这个事实还写在哪"。如果有第二个副本，要么删掉，要么标注以谁为准。
+
+**INV-6 验证衰减**：不要只验最容易的那一层。任何计划都必须有从用户价值链最后一步倒推回来的 golden journeys。
+
+## Gate 7 开发日志硬性要求（PLAN-064 教训）
+
+**LOG.md 不是可选项。** 每个 WP 的 `LOG.md` 必须在开发过程中实时写入，不得事后补写。
+
+Gate 7 → Gate 8 的转移条件包含：每个 WP 的 `docs/decisions/tasks/WP-*/LOG.md` 存在且非空。代码已 commit 但 LOG.md 不存在 = BLOCKED。
+
+## 联动规则（skill 调度表）
+
+| 需要做什么 | 调度 skill | 在哪些 gate |
+|-----------|-----------|------------|
+| 本质和边界 | `arch` | Gate 0, 1 |
+| 锁 plan | `plan-lock` | Gate 3 → 4 |
+| 拆 WP | `task-arch` | Gate 5 |
+| 编排并行执行 | `boll-eng` | Gate 3, 7 |
+| 全栈实现 | `boll-dev` | Gate 7 |
+| 质量闭环 | `boll-eng-test` | Gate 8 |
+| 审真相源和漂移 | `boll-ops` | 任何 gate |
+| 独立上下文审查 | **TeamCreate** | Gate 2, 4, 6, 8 |

package/src/bollharness/reference/boll-reference/.claude/skills/lead/ref-review-sop.md

@@ -0,0 +1,91 @@
+# 审查闭环 SOP
+
+lead skill 的审查操作手册。审查是每个阶段的硬门禁。
+
+---
+
+## 核心原则
+
+每个阶段结束后必须审查。审查用 TeamCreate（独立上下文 = 不被已有讨论污染的判断）。不是 Agent tool（subagent），是持久化 Team。
+
+## 审查何时触发
+
+```
+① 讨论沉淀 → ✅ 审查：本质找对了吗？
+② 决策书 ADR → ✅ 审查：决策完备吗？
+③ 接口设计 → ✅ 审查：契约清楚吗？消费方覆盖了吗？
+④ 实现方案 PLAN → ✅ 审查：方案能实现计划吗？
+  ④-a 任务拆分 WP → ✅ 审查：WP 完备、解耦、可执行吗？
+⑤ 代码实现 → ✅ 审查：每个 WP 完成后单独审查
+⑥ 集成验收 → ✅ 审查：端到端走通吗？
+```
+
+## 标准审查流程
+
+```
+TeamCreate("review-{plan-id}")
+
+第 1 轮：多视角独立审查（Team 内并行）
+├── Teammate A：视角 1
+├── Teammate B：视角 2
+└── Teammate C：视角 3
+
+↓ 收集独立报告 → 汇总 → 修正 → 再审 → 通过
+```
+
+## 审查维度矩阵
+
+| 阶段 | 视角 A | 视角 B | 视角 C |
+|------|--------|--------|--------|
+| ① 讨论 | 商业可行性 | 技术本质 | 用户体验 |
+| ② ADR | 选项完备性 | 架构一致性 | 风险分析 |
+| ③ 接口 | 消费方完备 | 向后兼容 | 可测试性 |
+| ④ PLAN/WP | 代码现状验证 | 任务解耦+依赖 | 测试+验收可执行 |
+| ⑤ 代码 | 功能正确性 | 安全+错误处理 | 性能+生产就绪 |
+| ⑥ 集成 | 端到端链路 | 回归验证 | 部署就绪 |
+
+## PLAN-033 教训：审查团队扩展维度
+
+**Gate 4（PLAN 审查）必须额外覆盖**（详见 `plan-lock/ref-three-checks.md`）：
+
+| 维度 | 检查什么 |
+|------|---------|
+| C. 消费方语义兼容 | 接口变更后所有调用方在新语义下行为正确 |
+| D. 数据流完整性 | 新字段从创建到消费的传递链无断点 |
+| E. 时间边界 | 跨午夜/跨过期/并发竞态 |
+| F. 对抗/红队 | 攻击者能构造什么输入获得不正当利益 |
+
+## 生产问题诊断硬规则（2026-03-18 沉淀）
+
+**当审查对象是"生产故障"时，审查的第一步不是看代码，是看生产证据。**
+
+| 顺序 | 动作 | 不是 |
+|------|------|------|
+| 1 | 看日志、事件、DB 中的实际错误 | 看代码猜"可能哪里错了" |
+| 2 | 对比成功 case 和失败 case 的时间线 | 从代码结构推断"应该用另一种方式" |
+| 3 | 验证运行环境（认证、权限、沙盒、磁盘） | 假设环境和本地一样 |
+| 4 | 最后看代码，只为理解机制 | 把"代码可以改进"等同于"这里是 bug" |
+
+**Gate 0 的额外检查项**（生产故障类 issue）：
+- [ ] 是否已查看失败 run 的实际错误消息（不是推测）
+- [ ] 是否已对比同路径下的成功 run
+- [ ] 是否已验证运行环境与本地的差异
+
+## WP 拆分专项审查
+
+当 PLAN 拆分成 WP 后，逐条检查：
+
+1. **PLAN 覆盖率** — 每个 RP 在 WP 中都有归属
+2. **WP 解耦与依赖** — 依赖正确，并行度最大化
+3. **代码现状验证** — 文件/函数签名与真实代码一致
+4. **接缝完整性** — 没有"不属于任何 WP 的中间层"
+5. **验收可测试性** — 每个 WP 有可自动化的验收标准
+6. **执行分配** — 每个 WP 由哪个 Skill 负责
+
+## 日志要求
+
+每次审查产生日志：`docs/decisions/tasks/{WP-ID}/LOG.md`。
+
+## Skill 自迭代
+
+审查中发现的可复用教训，沉淀到对应 Skill 的 reference 文件中，不只是 memory。

package/src/bollharness/reference/boll-reference/.claude/skills/lead/ref-stages.md

@@ -0,0 +1,129 @@
+# 开发阶段详细描述
+
+lead skill 的 5 个阶段的深度定义。主 SKILL.md 的 Gate 0-8 是强制顺序，这里是每个阶段的详细操作指南。
+
+---
+
+## 阶段 ①：讨论沉淀
+
+**目标**：把想法想清楚，找到本质。
+
+**必须加载**：`arch` skill（架构师做本质分析，不是 lead 自己想）
+
+**做什么**：
+- 从架构原则出发分析（引用 `docs/ARCHITECTURE_DESIGN.md` 的具体 Section）
+- 列出多个方案和 trade-off，不只给一个答案
+- 追问"这个东西的本质是什么？它属于哪一层？"
+- 识别它是**契约变更**还是**实现变更**
+- 记录讨论中达成的共识
+
+**消费方发现门禁**（必须在讨论阶段完成，三个维度都要覆盖）：
+```
+数据消费方（谁在读这个实体的数据）：
+□ 这个 Feature 改动涉及哪些组件/模块？
+□ 每个被改组件有哪些消费方？（grep import 来源）
+□ 消费方 > 1 时，所有消费方都在 Feature scope 内吗？
+□ 不在的消费方：纳入 scope，或显式标注"不受影响 + 原因"
+
+行为消费方（谁在调用这个实体的能力）：
+□ 这个实体被创建/注册后，系统中谁会调用它的方法/能力？
+□ 每个调用点，实体的状态是否足以支持调用？（如 adapter!=None 才能 chat）
+□ "接口接受" ≠ "语义完整"——API 接受你的输入不代表产物是完整公民
+
+可见性消费方（谁在查找/匹配这个实体）：
+□ 这个实体在所有 scope/query 条件下都能被找到吗？
+□ 有没有过滤条件会让它隐形？（如空 scene_ids → 场景查询不可见）
+```
+**原则**：Feature scope = 改动集 ∪ 改动的所有消费方（数据+行为+可见性三维）。scope 不由"我想做什么"决定，由"谁在用我改的东西"决定。
+
+**不做**：不跳到"怎么实现"。这个阶段只讨论"是什么"和"为什么"。
+
+---
+
+## 阶段 ②：决策书 (ADR)
+
+**目标**：把共识变成正式决策，留下记录。
+
+**门禁**：阶段 ① 的讨论已充分，核心问题已回答。
+
+**必须加载**：`arch` skill
+
+**做什么**：
+- 写 `docs/decisions/ADR-NNN-xxx.md`
+- 格式：背景 → 选项分析（≥2 个方案 + trade-off）→ 决策 → 核心原则 → 影响范围
+
+**不做**：不在 ADR 里写实现细节。ADR 描述"做什么决定"，不描述"怎么实现"。
+
+---
+
+## 阶段 ③：接口设计
+
+**目标**：定义功能的**本质**——它做什么，不是怎么做。
+
+**门禁**：ADR 已获批准。
+
+**必须加载**：`arch` skill + 领域相关 Skill
+
+**做什么**：
+- 定义输入/输出的语义
+- 定义调用方和实现方之间的契约
+- 定义操作会产生的事件/状态变化
+- 与现有契约的关系
+
+**本质描述的标准**：换一种实现方式，接口定义不需要改。
+
+---
+
+## 阶段 ④：实现方案 (PLAN)
+
+**目标**：把接口设计映射到代码改动。
+
+**门禁**：接口设计已完成，且架构设计审查 blocker 已清零。
+
+**必须加载**：`boll-eng` + 领域 Skill + `plan-lock`
+
+**做什么**：
+- 写 `docs/decisions/PLAN-NNN-xxx.md`
+- 列出具体要改/新增的文件
+- 每条变更链路追踪到底
+- 架构覆盖矩阵：逐条核对"架构设计 → PLAN 承载"
+- **冻结步骤**：必须经过 `plan-lock` 关掉所有决策口子
+
+**变更链路追踪清单**：
+```
+□ 我改的是契约还是实现？
+□ 如果是契约，消费方有哪些？列出来。
+□ 数据从哪来 → 经过哪些层 → 到哪去？每一层有代码吗？
+□ 有没有降级路径？降级路径也通了吗？
+□ 有没有"不归任何人"的中间层？
+```
+
+**消费方验证清单**：
+```
+数据消费方：每个都有对应的变更条目吗？降级路径覆盖了吗？
+行为消费方：复用已有模式时，原模式的语义意图适用于新场景吗？
+可见性消费方：新实体在所有 scope 查询下都可见吗？
+```
+
+**硬性规则**：只有标成 `vN-final` 的冻结计划，才允许进入审查或交给 `task-arch`。
+
+---
+
+## 阶段 ⑤：代码实现
+
+**目标**：按方案写生产级代码。
+
+**强制 Skill 调度**：
+
+| 领域 | Skill | 什么时候用 |
+|------|-------|-----------|
+| 全栈实现（默认） | `boll-dev` | 跨前后端改动、调试、重构 |
+| 状态机/编排 | `arch` + `boll-eng` + `boll-dev` | 需要先冻结状态语义，再落执行编排和实现 |
+| LLM/Prompt | `soul-writing` + `boll-dev` | 行为文本设计、tool-use、parser 落地 |
+| HDC/向量 | `arch` + `boll-lab` | 编码策略、共振实验、证据化验证 |
+| 前端 UI | `boll-eng-frontend` | 组件、WS 事件消费 |
+| 前端设计 | `nature-designer` | 视觉设计、交互 |
+| 测试 | `boll-eng-test` | 测试策略 |
+| 架构对齐 | `arch` | 可能违反架构原则时 |
+
+**快速通道可以跳阶段，不可以跳 Skill。**