@modus-ai/modus 0.2.7 → 0.2.9

package/templates/skills/modus-cr/SKILL.md

@@ -0,0 +1,386 @@
+---
+name: modus-cr
+description: Use this skill when executing /modus:cr command to perform standalone code review backed by design documents (design.md / plan.md). Runs a two-phase review — (1) document-code consistency check (speckit.analyze style) and (2) code quality CR (modus-reviewer style) — then outputs a cr-report.md compatible with the harness HANDOFF format. Optionally creates TAPD Bug units for P1/P2 issues. Trigger on /modus:cr command or when user wants to review code changes against a design document.
+allowed-tools: Read, Write, Glob, Bash
+disable: false
+---
+
+# modus-cr（独立代码评审）
+
+**触发条件：** 用户运行 `/modus:cr --doc <文档路径>` 时使用此 Skill。
+
+## 职责
+
+独立代码评审入口，不依赖 harness 流程。接受技术方案文档（design.md / plan.md）和可选的 PRD，对当前代码变更进行两阶段评审：
+
+1. **一致性检查**（来源：speckit.analyze）：文档需求 vs 代码实现的覆盖率矩阵，识别「缺失实现」「超出范围」「任务完成率」
+2. **代码质量 CR**（来源：modus-reviewer 独立版本）：架构/事务/安全/性能/业务规则，P1/P2/P3 分级
+
+产出物 `cr-report.md` 与 harness 内部 cr-report.md 格式完全兼容，可复用 TAPD Bug 创建逻辑。
+
+---
+
+## 参数解析（优先执行）
+
+**首先**检测用户输入中的参数标志：
+
+```
+--help        → 输出帮助文档，结束执行
+--doc X       → DOC_PATHS=X（支持多路径，空格分隔）
+--diff X      → DIFF_TARGET=X（指定评审代码范围）
+--story X     → STORY_URL=X（从 TAPD 加载 PRD）
+--quick       → QUICK_MODE=true（跳过一致性检查）
+```
+
+**必要参数校验：**
+- 若无 `--doc` 且非 `--quick` 模式：提示「`--doc` 是必填参数。若无设计文档请使用 `--quick` 模式」
+- `--quick` 模式可以不提供 `--doc`，但需提供 `--diff` 或存在 git 变更
+
+---
+
+## 执行流程
+
+### Step 0：加载参考文档（contextFiles）
+
+> **来源：opsx:apply contextFiles** — 先读完所有上下文，再执行评审
+
+**按以下顺序依次读取（类 opsx:apply）：**
+
+1. `--doc` 指定的每个文档路径（design.md / plan.md / tasks.md / PRD）：
+   - 若路径不存在，输出警告并继续（不阻塞）
+   - 若路径是目录，自动在目录内查找：`design.md` > `plan.md`，以及同级 `tasks.md`
+2. 若有 `--story`，调用 TAPD MCP（`tapd_mcp_http`）读取 Story 描述作为 PRD 补充
+3. `modus/config.yaml`：读取 `constitution`（`hard_rules`、`tech_stack`、`key_patterns`）
+4. `modus/knowledge-catalog.md`：识别相关业务域，加载对应 `modus/knowledge/biz-{domain}/SKILL.md`（仅 hash 检查，不更新）
+
+**输出上下文加载摘要：**
+
+```
+📚 上下文加载完成
+   参考文档：{doc_path1}、{doc_path2}（{功能名称}）
+   TAPD PRD：{story_url 或「未指定」}
+   业务域：{domain1}, {domain2}
+   代码约束：{constitution.hard_rules 摘要（前 3 条）}
+```
+
+---
+
+### Step 1：获取代码变更范围
+
+**获取变更文件列表（按优先级）：**
+
+```
+情形 A：--diff 指定了文件/目录
+  → 读取指定路径的文件（若是目录则 Glob 扫描其中的源码文件）
+
+情形 B：默认模式（无 --diff）
+  → 执行：git diff HEAD --name-only
+  → 获取所有变更文件列表
+
+情形 C：无 git，且无 --diff
+  → Glob 扫描主要源码目录（src/、app/、lib/ 等），取最近修改文件
+  → 输出警告：⚠️ 未检测到 git 仓库，使用文件修改时间作为变更范围参考
+```
+
+**过滤规则（自动排除）：**
+- `*.lock`、`*.sum`、`node_modules/`、`.git/`、`dist/`、`target/`、`build/`
+- 测试数据文件（`*.json` in test fixtures，`*.sql` in resources）
+
+**输出变更范围摘要：**
+
+```
+📝 代码变更范围
+   变更文件：{N} 个（已过滤 {M} 个非源码文件）
+   主要变更：
+     {文件路径1}（{新增/修改/删除}）
+     {文件路径2}（{新增/修改/删除}）
+     ...（超过 10 个时折叠）
+```
+
+---
+
+### Step 2：一致性检查（speckit.analyze 风格，只读）
+
+> **来源：speckit.analyze** — 禁止修改任何文件；`--quick` 时跳过此步
+
+**Phase 2-1：需求覆盖率矩阵**
+
+从参考文档中提取需求点列表：
+- 从 `design.md` 第 3 节「影响范围」和第 4 节「API 契约草稿」提取具体需求
+- 从 `plan.md` 的「实现 Todos」提取任务项
+- 若有 `tasks.md`，提取所有 `T{ID}` 任务条目
+- 若有 TAPD PRD，提取「验收标准」或「功能描述」中的需求点
+
+对每个需求点，检查代码变更中是否有对应实现（基于文件名、类名、方法名关键词匹配）：
+
+| 需求点 | 状态 | 代码位置 |
+|--------|------|---------|
+| {需求描述} | ✅ 已覆盖 | `{文件路径}:{行号}` |
+| {需求描述} | ❌ 缺失实现 | — |
+| （代码变更中有实现但文档无对应需求） | ⚠️ 超出范围 | `{文件路径}` |
+
+**覆盖率计算：**
+```
+consistency_score = 已覆盖需求数 / 总需求数 × 100%
+```
+
+**Phase 2-2：tasks.md 完成率（若存在）**
+
+统计 tasks.md 中 `- [x]` vs `- [ ]` 的比例，输出任务完成情况。
+
+**Phase 2-3：一致性问题分级**
+
+| 问题类型 | 严重度 | 说明 |
+|----------|--------|------|
+| 核心功能缺失（P1/P2 需求未实现） | HIGH | 对应 CR P1 |
+| 接口契约变更未实现 | HIGH | 对应 CR P1 |
+| 次要需求缺失（P3 任务未完成） | MEDIUM | 对应 CR P2 |
+| 超出范围的代码变更 | MEDIUM | 注意：可能合理（如重构优化），仅提示 |
+| 文档需求模糊无法验证 | LOW | 仅记录 |
+
+**输出一致性检查报告（内联展示，不落盘）：**
+
+```
+📊 一致性检查结果
+   需求覆盖率：{N}/{total}（{score}%）
+   任务完成率：{M}/{tasks}（若存在 tasks.md）
+
+   ❌ 缺失实现（HIGH）：
+     - {需求点 1}（对应 design.md § {节号}）
+     - {需求点 2}
+
+   ⚠️  超出范围的变更（MEDIUM）：
+     - {文件路径}（建议确认是否属于本次需求范围）
+
+   ✅ 已覆盖：{N} 个需求点
+```
+
+---
+
+### Step 3：代码质量 CR（modus-reviewer 独立版本）
+
+> **来源：modus-reviewer** — 评审维度与 harness 内部保持一致；P1/P2/P3 分级规则相同
+
+对 Step 1 获取的每个变更文件，依次执行以下维度的代码审查：
+
+#### 维度 1：需求符合性（仅在有 --doc 时执行）
+
+将 Step 2 的一致性检查结果转化为 CR 问题：
+- 核心功能缺失 → P1 问题
+- 次要需求缺失 → P2 问题
+
+#### 维度 2：代码质量
+
+**命名规范：**
+- 类名、方法名、变量名是否语义清晰
+- 是否遵循业务 Skill 中的命名约定（`[guideline]` 标签）
+
+**架构规范：**
+- 文件放置位置是否正确（包结构/目录层次）
+- 是否存在跨层调用（如 Controller 直接调 Mapper）
+- 职责分离是否清晰（业务逻辑是否在正确的层）
+
+**事务与并发：**
+- `@Transactional` 是否在正确位置（Manager 层，避免同类内部调用失效）
+- 是否存在事务嵌套或传播问题
+- 分布式锁使用是否正确（加锁范围、锁粒度、释放时机）
+
+**防御性编程：**
+- 关键参数是否有非空校验（`@NotNull`、`Assert.notNull`）
+- 数据库结果是否处理了 null/empty 情况
+- 集合操作前是否判空（`CollectionUtils.isEmpty`）
+
+**异常处理：**
+- 是否使用项目统一异常类（从 constitution/business Skill 获取规范）
+- 是否存在异常吞咽（`catch (Exception e) {}`）
+- 关键操作是否有完整日志（入参/出参/异常信息）
+
+**金额处理：**
+- 金额字段类型是否符合 `constitution.hard_rules` 规范
+- 若 hard_rules 未明确，默认检查是否使用 BigDecimal，并在报告中标注「未找到金额规范配置，使用默认规则」
+
+#### 维度 3：安全（多租户隔离）
+
+- `tenantId` 是否来自 `UserContext`（而非 request 参数）
+- Facade/Controller 层是否有权限校验（`@UserAuthorization`）
+- 日志中是否有敏感信息泄露（银行卡号、身份证、手机号明文）
+- 是否存在 SQL 拼接风险（`${}` 而非 `#{}`）
+
+#### 维度 4：性能
+
+- 是否存在 N+1 查询（循环内数据库调用）
+- 批量操作是否缺少 batch 方法（逐条 insert 替代 batchInsert）
+- 大数据量查询是否缺少分页保护
+- 列表接口是否有最大条数限制
+
+#### 维度 5：业务规则（来自 Skill）
+
+从已加载业务域 Skill 的 `[pitfall]` 和 `[guideline]` 标签中，检查代码变更是否违反已知规则：
+- 每个相关 `[pitfall]` 检查代码中是否有对应的保护措施
+- 每个相关 `[guideline]` 检查代码是否遵循约定
+
+---
+
+### Step 4：生成 cr-report.md
+
+**确定产出路径：**
+
+```
+modus/cr/{YYYYMMDD}-{feature-name}/cr-report.md
+
+feature-name 来源（按优先级）：
+1. --doc 文档的目录名（如 modus/plans/batch-export/ → batch-export）
+2. --story URL 中的 story ID
+3. git branch 名称中的 feature 部分
+4. 默认：cr-{YYYYMMDD}
+```
+
+**cr-report.md 格式（与 harness 完全兼容）：**
+
+```markdown
+---
+schema_version: "1.2"
+agent: "cr-standalone"
+run_id: "{YYYYMMDD}-{feature-name}"
+source_docs:
+  - "{doc_path1}"
+  - "{doc_path2}"
+story_id: "{story-id 或空字符串}"
+domains: ["{domain1}", "{domain2}"]
+consistency_score: "{N}/{total}"
+gate_status: "{passed|failed}"
+artifact_status: "complete"
+issues:
+  - level: "P1"
+    code: "P1-01"
+    agent: "cr-standalone"
+    location: "{文件名}:{行号}"
+    summary: "{一句话问题摘要}"
+    suggestion: "{修复建议}"
+    category: "{consistency|quality|security|performance|business-rule}"
+  - level: "P2"
+    code: "P2-01"
+    agent: "cr-standalone"
+    location: "{文件名}:{行号}"
+    summary: "{一句话问题摘要}"
+    suggestion: "{修复建议}"
+    category: "{category}"
+skill_refs:
+  - "modus-biz-{domain}@{version}"
+---
+
+# 代码评审报告（独立模式）
+
+## 评审摘要
+- 评审时间: {YYYY-MM-DD HH:mm}
+- 参考文档：{doc_paths}
+- 代码变更：{N} 个文件
+- 需求覆盖率：{consistency_score}（{quick_mode 时：「--quick 模式，已跳过一致性检查」}）
+- P1 问题: {N} 个 | P2 问题: {N} 个 | P3 建议: {N} 个
+- **合入结论: {✅ 可合入 / ❌ 需修复后重审}**
+
+## 一致性检查（需求覆盖率矩阵）
+
+| 需求点 | 状态 | 代码位置 |
+|--------|------|---------|
+| {需求描述} | ✅ 已覆盖 | `{文件路径}:{行号}` |
+| {需求描述} | ❌ 缺失实现 | — |
+| {代码变更描述} | ⚠️ 超出范围 | `{文件路径}` |
+
+（--quick 模式时此节显示「已跳过（--quick 模式）」）
+
+## P1 问题（必须修复）
+
+### [P1-01] {问题标题}
+- **位置：** `{文件名}:{行号}`
+- **类别：** {consistency | quality | security | performance | business-rule}
+- **问题描述：** {详细说明问题是什么，为什么有问题}
+- **代码片段：**
+  ```{language}
+  // 有问题的代码
+  ```
+- **修复方案：**
+  ```{language}
+  // 正确的代码
+  ```
+
+## P2 问题（必须修复）
+...（与 P1 格式相同）
+
+## P3 建议（建议修复）
+...（格式同上，可精简描述）
+
+## 正向确认
+- ✅ {正确的做法，鼓励延续的好实践}
+
+## 下一步
+{如有 P1/P2 → "需修复以下问题后重新评审，建议运行 /modus:vibe 修复"}
+{如无 P1/P2 → "通过评审，可直接合入代码"}
+```
+
+**HANDOFF 块填写规则（与 harness cr-report.md 相同）：**
+- `gate_status`：无 P1/P2 → `passed`；有 P1/P2 → `failed`
+- `issues`：仅列 P1/P2（P3 不阻塞）；无 P1/P2 时写空列表 `issues: []`
+- 新增字段：`consistency_score`（一致性检查覆盖率）、`category`（问题来源类别）
+
+---
+
+### Step 5（可选）：创建 TAPD Bug 单
+
+> **前置条件：** `modus/config.yaml` 中 `tapdProjectId` 非空，且 TAPD MCP（`tapd_mcp_http`）可用。
+
+> **协调说明：** 如果 workspace 中已安装独立的 `tapd-bug-creator` Skill，**优先使用外部 Skill** 创建 Bug 单，本节逻辑作为降级兜底。
+
+满足前置条件时，对 P1/P2 问题自动创建 TAPD Bug 单：
+
+- Bug 标题：`[Modus CR] {问题标题}`
+- 关联 Story：若有 `--story`，填入对应 Story ID
+- 描述：包含代码位置（`location` 字段）、问题代码片段、修复方案（`suggestion` 字段）
+- 严重程度：P1 → 严重，P2 → 一般
+- 优先级：P1 → 高，P2 → 中
+
+创建完成后将 Bug ID 写入 cr-report.md 末尾的 `tapd_bugs` 列表：
+
+```markdown
+## TAPD Bug 单
+| CR 问题 | Bug ID | 链接 |
+|---------|--------|------|
+| P1-01 {标题} | {bugId} | {tapd_url} |
+```
+
+---
+
+## 产出物目录结构
+
+```
+modus/
+└── cr/
+    └── {YYYYMMDD}-{feature-name}/
+        └── cr-report.md    ← 评审报告（HANDOFF 格式）
+```
+
+---
+
+## 问题分级规则
+
+| 级别 | 定义 | 处理 |
+|------|------|------|
+| **P1（严重）** | 核心功能缺失、数据安全漏洞、会导致生产故障的 Bug、多租户数据泄露 | 必须修复，`gate_status: failed` |
+| **P2（高风险）** | 架构规范违反、事务/并发问题、安全隐患、性能高风险、次要需求缺失 | 必须修复，`gate_status: failed` |
+| **P3（建议）** | 代码质量改进、命名优化、日志完善、低风险性能建议 | 建议修复，不阻塞合入 |
+
+**性能问题分级映射（来自 modus-reviewer 规则）：**
+
+| 原始级别 | CR 级别 | 触发条件 |
+|----------|---------|---------|
+| 高风险 | P2（或 P1） | 影响 SLA 则升为 P1 |
+| 中风险 | P3 | 建议优化 |
+| 低风险 | P3 | 建议优化 |
+
+**安全问题分级映射：**
+
+| 原始级别 | CR 级别 |
+|----------|---------|
+| 严重 | P1 |
+| 高风险 | P2 |
+| 低风险 | P3 |

package/templates/skills/modus-harness/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: modus-harness
-description: Use this skill when executing /modus:harness command to run the full dual-loop multi-agent Harness from requirements analysis to deployment. Acts as the orchestrator coordinating SubAgents 00-07. Trigger on /modus:harness command or when user provides a TAPD Story URL and wants automated end-to-end delivery.
+description: Use this skill when executing /modus:harness command to run the full dual-loop multi-agent Harness from requirements analysis to deployment. Acts as the orchestrator coordinating SubAgents 00-07. Trigger on /modus:harness command or when user provides a TAPD Story URL and wants automated end-to-end delivery. Also handles --from-plan relay (skip SA01+SA02, read plan.md as dev input) and --show-progress (write events.jsonl).
 allowed-tools: Read, Write, Glob, Bash, Task
 disable: false
 ---
@@ -61,6 +61,67 @@ Orchestrator 每步只需读 HANDOFF 块（≤ 20 行），而非整份 MD 文
 
 ---
 
+## 参数解析（优先执行，Step 1 之前）
+
+**首先**检测用户输入中的参数标志，设置后续行为开关：
+
+```
+--help           → 输出帮助文档，结束执行
+--from-plan X    → FROM_PLAN_MODE=true，PLAN_NAME=X（进入 from-plan 接力路径，见下方）
+--show-progress  → SHOW_PROGRESS=true（每个关键节点写入 events.jsonl）
+--domain X       → FORCED_DOMAINS=X（逗号分隔，跳过域确认交互）
+--skip X         → SKIP_AGENTS=X（逗号分隔的 SubAgent ID）
+--loop1-only     → LOOP1_ONLY=true
+--resume         → RESUME=true
+--dry-run        → DRY_RUN=true
+--force          → FORCE=true（跳过人工确认，Codex 平台自动开启）
+--no-deploy      → NO_DEPLOY=true
+--max-loop2 N    → MAX_LOOP2=N（默认 3）
+--verbose        → VERBOSE=true
+--project X      → PROJECT=X
+```
+
+**FROM_PLAN 接力路径（--from-plan 时，替代 Step 2 的标准澄清流程）：**
+
+```
+Step P1：读取 plan.md
+  路径：modus/plans/{PLAN_NAME}/plan.md
+  读取 HANDOFF frontmatter 验证：
+    → design_mode = true 且 status ∈ {approved, continued}
+    → 若 status = pending_review：
+        提示「plan 尚未批准（status=pending_review），请先完成技术评审后再 --continue」
+        输出「如需强制继续，运行：/modus:harness --from-plan {name} --force」
+        若 FORCE=false：结束执行
+  提取关键内容：
+    → domains：传给知识注入（SA00）
+    → story_id：用于工作目录路径（若 plan.md 有 story_id）
+    → 「实现 Todos」章节 → 作为 SA03 的代码开发计划（替代 01-analysis + 02-design Sprint 拆分）
+    → 「技术方案评审 → 推荐方案」→ 作为 SA03 的架构决策参考
+    → 「已知风险」→ 传递给 SA07 代码评审作为审查重点
+    → continue_token：记录到工作目录 .harness-state.yaml
+
+Step P2：初始化工作目录
+  若 plan.md 含 story_id：工作目录 = modus/stories/{story_id}/harness/
+  若无 story_id：工作目录 = modus/plans/{PLAN_NAME}/harness/
+
+Step P3：输出接力摘要
+  🚀 从 plan --from-plan 接力启动
+     plan：modus/plans/{PLAN_NAME}/plan.md
+     continue_token：{token}
+     跳过：SA01（需求分析）+ SA02（设计方案）
+     直接执行：SA00（知识注入）→ SA03（代码开发）→ SA04/05/06（并行审计）→ SA07（评审）→ SA08（部署）
+
+Step P4：设置 SKIP_AGENTS = ["01", "02"]（强制跳过 SA01 + SA02）
+  并将 plan.md 的「实现 Todos」封装为 FROM_PLAN_CONTEXT，注入 SA03 执行时的任务描述
+
+写入进度事件（若 SHOW_PROGRESS=true）：
+  {"ts":"...","type":"plan_relay","plan_name":"{PLAN_NAME}","continue_token":"{token}","skipped_stages":["01-analysis","02-design"]}
+
+完成后进入标准 Step 1（项目宪法 + 前置检查），跳过 Step 2（澄清意图）。
+```
+
+---
+
 ## 执行流程
 
 ### Step 1：项目宪法 + 前置检查
@@ -158,11 +219,20 @@ last_updated: "{ISO 8601 时间戳}"
 
 将 Skill 内容（已加载的完整 SKILL.md）和 constitution.hard_rules 一起传递给 SubAgent 01 作为背景知识。
 
+**FROM_PLAN_MODE 特殊处理：**
+
+若 FROM_PLAN_MODE=true，在输出启动摘要时补充 plan 上下文说明：
+
 ```
-[Harness Orchestrator 启动]
-Story: {id} | 工作目录: modus/stories/{id}/harness/
-知识注入: order[verified→已更新] | payment[proven→已读取] | user[新建 draft]
-Constitution: {N} 条硬性规则已加载
+[Harness Orchestrator 启动 — plan 接力模式]
+plan：modus/plans/{PLAN_NAME}/plan.md（continue_token: {token}）
+工作目录: {工作目录}
+跳过: SA01（需求分析）→ SA02（设计方案）
+知识注入: {domains}[...] | Constitution: {N} 条硬性规则已加载
+
+📋 SA03 将读取 plan.md 中的「实现 Todos」作为代码开发输入：
+   {plan.md 中 Todos 章节前 3 条预览}
+   ...（共 N 条 Todo）
 ```
 
 ---
@@ -313,17 +383,27 @@ feat: {业务摘要}
 
 ## 调度 CoT（每次行动前循环执行）
 
-1. 扫描 `modus/stories/{story-id}/harness/` 目录，列出已有 HANDOFF frontmatter
+1. 扫描工作目录，列出已有 HANDOFF frontmatter
 2. 只需读各文件的 HANDOFF frontmatter（≤ 20 行），对照串行顺序确定当前阶段
 3. 检查当前阶段的 Gate 条件是否满足（优先读 HANDOFF，必要时读全文）。**每个 Gate 仅在对应 SubAgent 完成后单独执行，互相独立，不同时触发**：
-   - Gate A0：**当 SubAgent 01 写入 `01-analysis.md` 后**，检查该文件 HANDOFF 块的 `gate_status` 字段，确保 = "passed"（需求分析质量门，独立于 Gate A0.5）
-   - Gate A0.5：**当 SubAgent 02 写入 `02-design-brief.md` 后**，检查 `gate_status ∈ {passed, warning}`；`failed` 时重入 SubAgent 02，最多 2 次
+   - Gate A0：**当 SubAgent 01 写入 `01-analysis.md` 后**，检查该文件 HANDOFF 块的 `gate_status` 字段，确保 = "passed"（需求分析质量门，独立于 Gate A0.5）。**FROM_PLAN_MODE 时跳过此 Gate**（SA01 已跳过）
+   - Gate A0.5：**当 SubAgent 02 写入 `02-design-brief.md` 后**，检查 `gate_status ∈ {passed, warning}`；`failed` 时重入 SubAgent 02，最多 2 次。**FROM_PLAN_MODE 时跳过此 Gate**（SA02 已跳过）
    - Gate A：执行 `constitution.build_command`（如 `mvn clean compile -q -DskipTests`），检查 exit code = 0；失败时重入 SubAgent 03，最多 3 次
    - Gate B：扫描 harness/ 目录，检查 `04-test-report.md`、`05-perf-report.md`、`06-security-report.md` 的 HANDOFF `artifact_status` 均为 `complete`；各报告 `gate_status ≠ "failed"`；06（安全审计）有严重/高危则强制拦截；超时（30 分钟）上报用户
    - Gate C：读 `cr-report.md` HANDOFF，检查 `issues` 数组为空或全为 P3；有 P1/P2 时从 `issues[].affected_sprint` 定位受影响 Sprint，触发 Loop 2 精准重入 SubAgent 03
 4. Gate 通过 → 调用下一个 SubAgent 的 Skill（传递 constitution + 相关 Skill 内容）
-   - 调用 SubAgent 03 时，必须同时传入 `02-design-brief.md` 内容
+   - 调用 SubAgent 03 时：
+     - **标准模式**：必须同时传入 `02-design-brief.md` 内容
+     - **FROM_PLAN_MODE**：传入 plan.md 的「实现 Todos」+ 「推荐方案」作为等价输入，代替 02-design-brief.md
 5. Gate 失败 → 按规则处理（重入/上报）
 6. 输出本轮进度卡片
 7. 若 SubAgent 08 完成且 `08-deploy-status.md` HANDOFF `artifact_status = complete` → 触发 ARCHIVE 知识提取（SubAgent 00 模式 D），进入 Step 4
-8. 等待 SubAgent 写入产出物，重复步骤 1
+8. **进度事件写入（SHOW_PROGRESS=true 时，在步骤 4/5/7 后各执行一次）：**
+   向 `modus/sessions/events.jsonl` 追加事件（JSON Lines 格式，见 `modus/docs/protocol.md §七`）：
+   - SubAgent 开始执行前：写入 `stage_start` 事件
+   - SubAgent 完成后：写入 `stage_done` 事件
+   - Gate 检查完成后：写入 `gate` 事件
+   - Gate A 编译检查后：写入 `compile` 事件
+   - Loop 2 触发时：写入 `loop2_start` 事件
+   - 全流程完成时：写入 `harness_done` 事件
+9. 等待 SubAgent 写入产出物，重复步骤 1